The reader's four findings (unanswered, view-waits, unsaid, too-large) are laid out by mesh-sdk (design 47 G §687) on the wire form and written through views.WireWriter, which the generic Writer is; the emitter writes view-too-large itself and its TooLarge hook goes; Adopt wires every adopted follower's four callbacks to its reader. Builds: design 47 G §686, §687, §689, A-22, A-26 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
102 lines
4.7 KiB
Go
102 lines
4.7 KiB
Go
package views
|
|
|
|
import (
|
|
"cmp"
|
|
"context"
|
|
"fmt"
|
|
"strings"
|
|
"time"
|
|
|
|
"git.novox.be/novox/mesh-sdk/go/keys"
|
|
)
|
|
|
|
// The findings a views part writes in its own state `findings`, which the condition keeper raises and clears
|
|
// (novox/hq ADR 0564 §2): an owner's value too large for an event (TooLargeKind), an owner's change not said past its
|
|
// bound (UnsaidKind), and a reader's first view unanswered past its bound (UnansweredKind).
|
|
const (
|
|
TooLargeKind = "view-too-large"
|
|
UnsaidKind = "view-unsaid"
|
|
UnansweredKind = "first-view-unanswered"
|
|
// ViewWaitsKind is a part's finding of a view it has waited for past WaitsBound (design 47 *A part with no view says it
|
|
// waits*).
|
|
ViewWaitsKind = "view-waits"
|
|
)
|
|
|
|
// viewFinding is what a views part says is wrong with a state it owns or follows, in plain fields: kind and id name it, summary
|
|
// and headline say it. It is laid out in the wire form of the contract's finding by mesh-sdk (body, design 47 G §687, A-22) and
|
|
// written through the part's generic writer; there is no other form of it.
|
|
type viewFinding struct {
|
|
kind string
|
|
id string
|
|
summary string
|
|
headline string
|
|
at time.Time
|
|
}
|
|
|
|
// WireWriter is what a views part's findings use of the part's finding writer, whatever the contract's body types: the
|
|
// generic Writer[F, C, S, A] is one (design 47 G §639, §687, A-22).
|
|
type WireWriter interface {
|
|
WriteWire(ctx context.Context, finding map[string]any) error
|
|
Clear(ctx context.Context, scope, id, kind, why string) error
|
|
ModuleNode() (module, node string)
|
|
}
|
|
|
|
// FindingScope is the scope of a views reader's findings: they are findings of the part's module (design 47 G §687).
|
|
const FindingScope = "module"
|
|
|
|
// body lays the finding out on its wire form (design 47 G §687): `kind` the finding's, `scope` module, `id` the finding's id
|
|
// escaped as a key's name is, `severity` warning but urgent for view-too-large, `source` views, `subject` the part's module on
|
|
// its node, `summary` and `headline` the finding's texts.
|
|
func (f viewFinding) body(module, node string) map[string]any {
|
|
sev := "warning"
|
|
if f.kind == TooLargeKind {
|
|
sev = "urgent"
|
|
}
|
|
subject := map[string]any{"scope": FindingScope, "id": module}
|
|
if node != "" {
|
|
subject["machine"] = node
|
|
}
|
|
b := map[string]any{"kind": f.kind, "scope": FindingScope, "id": keys.EscapeName(f.id), "severity": sev, "source": "views",
|
|
"subject": subject, "summary": f.summary}
|
|
if f.headline != "" {
|
|
b["headline"] = f.headline
|
|
}
|
|
if !f.at.IsZero() {
|
|
b["at"] = f.at
|
|
}
|
|
return b
|
|
}
|
|
|
|
// put writes the finding through w; drop clears it.
|
|
func (f viewFinding) put(w WireWriter) error {
|
|
module, node := w.ModuleNode()
|
|
return w.WriteWire(context.Background(), f.body(module, node))
|
|
}
|
|
|
|
func (f viewFinding) drop(w WireWriter) error {
|
|
return w.Clear(context.Background(), FindingScope, keys.EscapeName(f.id), f.kind, "the part no longer observes it")
|
|
}
|
|
|
|
func unsaidFinding(owner, state, key string, revision uint64, since time.Time, cause string, at time.Time) viewFinding {
|
|
summary := fmt.Sprintf("%s has not said the change of %s.%s at %d on its views family since %s (%s): its readers stand still before it",
|
|
owner, state, key, revision, since.UTC().Format(time.RFC3339), strings.TrimSpace(cause))
|
|
return viewFinding{kind: UnsaidKind, id: owner + "." + state, summary: summary, headline: fmt.Sprintf("%s cannot say a change of its %s", owner, state), at: at.UTC()}
|
|
}
|
|
|
|
func tooLargeFinding(owner, state, key string, size int, at time.Time) viewFinding {
|
|
summary := fmt.Sprintf("%s's %s.%s holds %d bytes, more than one views event carries (%d): every reader asks its first view again at each change of it", owner, state, key, size, MaxValueBytes)
|
|
return viewFinding{kind: TooLargeKind, id: owner + "." + state + "." + key, summary: summary, headline: fmt.Sprintf("A value of %s is too large for its views event", owner), at: at.UTC()}
|
|
}
|
|
|
|
func unansweredFinding(reader string, s Status, at time.Time) viewFinding {
|
|
summary := fmt.Sprintf("%s has no first view of %s's %s: %s has not answered since %s (%s)", reader, s.Owner, s.State, s.Tool,
|
|
s.Asked.Format(time.RFC3339), strings.TrimSpace(s.Error))
|
|
return viewFinding{kind: UnansweredKind, id: reader + "." + s.Owner + "." + s.State, summary: summary, headline: fmt.Sprintf("%s waits for %s", reader, s.Owner), at: at.UTC()}
|
|
}
|
|
|
|
func viewWaitsFinding(part string, s Status, at time.Time) viewFinding {
|
|
summary := fmt.Sprintf("%s waits for the view %s.%s at revision %s since %s and acts on nothing new until it holds it; it holds %s",
|
|
part, s.Owner, s.State, s.WaitsFor, s.WaitingSince.UTC().Format(time.RFC3339), cmp.Or(s.View, "none"))
|
|
return viewFinding{kind: ViewWaitsKind, id: part + "." + s.Owner + "." + s.State, summary: summary, headline: fmt.Sprintf("%s waits for a view of %s", part, s.Owner), at: at.UTC()}
|
|
}
|