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" // EntryNotFoundKind is a part's finding of an entry by fingerprint the seat mesh-catalog's `entry` answered it does not hold // (design 47 G §614, A-15, A-103): scope the part, id the fingerprint. EntryNotFoundKind = "entry-not-found" ) // 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")) if s.WaitsFor == HolderWait { summary = seatWaitsSummary(part, s) // a seat's view with no holder yet (design 47 G §717) } 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()} } // WriteEntryNotFound writes the part's finding that the catalog holds no entry for fingerprint, asked since `since` // (design 47 G A-103); ClearEntryNotFound clears it, when nothing the part holds names the fingerprint or a later ask answers. func WriteEntryNotFound(w WireWriter, fingerprint string, since, at time.Time) error { module, _ := w.ModuleNode() return viewFinding{kind: EntryNotFoundKind, id: fingerprint, summary: fmt.Sprintf("%s holds a build of fingerprint %s that the catalog holds no entry for (asked since %s): what it needs of the entry stands still", module, fingerprint, since.UTC().Format(time.RFC3339)), headline: fmt.Sprintf("%s cannot find the catalog entry of a build", module), at: at.UTC()}.put(w) } // ClearEntryNotFound clears the finding WriteEntryNotFound wrote for fingerprint. func ClearEntryNotFound(w WireWriter, fingerprint string) error { return viewFinding{kind: EntryNotFoundKind, id: fingerprint}.drop(w) }