package views import ( "context" "encoding/json" "errors" "sort" "strings" "sync" ) // HeldWriter is the finding writer of a part whose findings are raised as they happen, not judged afresh (design 47 G A-29, // §686): it holds the findings it has written, seeded from the keys of its state `findings` before it starts, under a lock of // its own (never the part's: the writer calls Observe under its own lock while the part writes under its), and its Observe // answers them, so a statement says exactly what the part holds. Write and Clear update the held set and then the writer's. // It is a Writer[F, C, S, A] with that Observe, so no part writes the adapter. type HeldWriter[F, C, S, A any] struct { *Writer[F, C, S, A] mu sync.Mutex held map[string]F state FindingState started bool pending map[string]F // written before Start, written through the writer at Start cleared map[string][4]string // cleared before Start, cleared through the writer at Start // pends are the keys the part cannot judge yet since its start (design 47 G §384): a kept call it has not yet made // again, named in every statement until the part judges it. pends map[string]PendingKey } // NewHeldWriter makes the writer for cfg, whose Observe is none (a given Observe is refused): the findings that stand in // cfg.State are read at once, each key's value as the writer kept it (a value that is no finding of F is left to the next // statement, which deletes its key when it is of a kind the writer owns). func NewHeldWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*HeldWriter[F, C, S, A], error) { if cfg.Observe != nil { return nil, errors.New("a held finding writer observes what it holds: it takes no Observe") } if cfg.State == nil { return nil, errors.New("a finding writer needs the state `findings`") } h := &HeldWriter[F, C, S, A]{held: map[string]F{}, pends: map[string]PendingKey{}} h.state, h.pending, h.cleared = cfg.State, map[string]F{}, map[string][4]string{} cfg.Observe = func(context.Context) (Observed[F], error) { h.mu.Lock() defer h.mu.Unlock() var o Observed[F] for _, f := range h.held { o.Findings = append(o.Findings, f) } for _, p := range h.pends { o.Pending = append(o.Pending, p) } sort.Slice(o.Pending, func(i, j int) bool { return o.Pending[i].Key < o.Pending[j].Key }) return o, nil } w, err := NewWriter(cfg) if err != nil { return nil, err } h.Writer = w return h, nil } // Write holds the finding and writes it through the writer. func (h *HeldWriter[F, C, S, A]) Write(ctx context.Context, finding F) error { m, err := wireOf(&finding) if err != nil { return err } if err := CheckFinding(m); err != nil { return err } if !h.Writer.owns(str(m, "kind")) { return h.Writer.Write(ctx, finding) // refused by the writer, naming the kind, and held no more than it is } h.mu.Lock() h.held[keyOf(m)] = finding if !h.started { h.pending[keyOf(m)] = finding delete(h.cleared, keyOf(m)) h.mu.Unlock() return nil } h.mu.Unlock() return h.Writer.Write(ctx, finding) } // Clear stops holding the finding of scope, id and kind and clears it through the writer. func (h *HeldWriter[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error { h.mu.Lock() k := FindingKey(scope, id, kind) delete(h.held, k) if !h.started { delete(h.pending, k) h.cleared[k] = [4]string{scope, id, kind, why} h.mu.Unlock() return nil } h.mu.Unlock() return h.Writer.Clear(ctx, scope, id, kind, why) } // WriteWire is Write of a finding in its wire form, held as Write holds it (design 47 G A-37): a views reader writing through // the held writer has its findings in the held set, so in the statement. func (h *HeldWriter[F, C, S, A]) WriteWire(ctx context.Context, finding map[string]any) error { var f F if err := fillFrom(&f, finding); err != nil { return err } return h.Write(ctx, f) } // Pend names a key the part cannot judge yet since its start, with its since and its bound, in every statement until Judged // (design 47 G §384; design 46 7-approval-mark §16: an acted ask whose hand-act is not yet asked again). A key pended again // keeps its first since. func (h *HeldWriter[F, C, S, A]) Pend(p PendingKey) { h.mu.Lock() defer h.mu.Unlock() if was, ok := h.pends[p.Key]; ok { p.Since = was.Since } h.pends[p.Key] = p } // Judged ends a key's pending: the part judged it, raising or clearing its finding as it found. func (h *HeldWriter[F, C, S, A]) Judged(key string) { h.mu.Lock() defer h.mu.Unlock() delete(h.pends, key) } // Held answers the findings the writer holds, a copy taken under its lock (design 47 G A-38), so a part reads its open findings // from the writer. func (h *HeldWriter[F, C, S, A]) Held() []F { h.mu.Lock() defer h.mu.Unlock() out := make([]F, 0, len(h.held)) for _, f := range h.held { out = append(out, f) } return out } // Start seeds what the writer holds from the keys of its state `findings` of the kinds it owns (design 47 G A-40, §580, H // H-A-242: another bundle's keys are its own to state, and are not read), what was written before it standing over them; // writes what was written and clears what was cleared before it; clears once the keys of its retired kinds, never seeding // them (H-A-247 (3)); and starts the writer. A part makes the writer before its module serves, so nothing is read from the // state until now. func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error { keys, err := h.state.Keys() if err != nil { return err } var retired [][4]string h.mu.Lock() for _, k := range keys { if h.Writer.retiredKey(k) { // a kind no code raises any more: cleared once, never seeded (H-A-247 (3)) scope, rest, _ := strings.Cut(k, ".") if i := strings.LastIndex(rest, "."); i > 0 { retired = append(retired, [4]string{scope, rest[:i], rest[i+1:], "the kind is retired: no code raises it any more"}) } continue } if !h.Writer.ownsKey(k) { continue // another bundle's kind: it states its own (design 47 G §580, H H-A-242 (1)), and is not read } e, err := h.state.Get(k) if err != nil { h.mu.Unlock() return err } if _, ok := h.held[k]; ok { continue } if _, ok := h.cleared[k]; ok { continue } var f F if e == nil || json.Unmarshal(e.Value, &f) != nil { continue } if m, err := wireOf(&f); err == nil && keyOf(m) == k { h.held[k] = f } } pending, cleared := h.pending, h.cleared h.started, h.pending, h.cleared = true, nil, nil h.mu.Unlock() // None of these stops the writer (H-A-242 (3)): a kind it does not own was said once by refuse, and any other failure is // said here and left to the next start. for _, f := range pending { h.unstarted(h.Writer.Write(ctx, f), "an early write") } for _, c := range cleared { h.unstarted(h.Writer.Clear(ctx, c[0], c[1], c[2], c[3]), "an early clear of "+FindingKey(c[0], c[1], c[2])) } for _, c := range retired { h.unstarted(h.Writer.clear(ctx, c[0], c[1], c[2], c[3]), "the retired key "+FindingKey(c[0], c[1], c[2])) } return h.Writer.Start(ctx) } // unstarted says in the journal an act of Start that failed, but for a kind the writer does not own, which refuse said once. func (h *HeldWriter[F, C, S, A]) unstarted(err error, what string) { var refused *unownedKind if err == nil || errors.As(err, &refused) { return } h.Writer.cfg.Logf("the finding writer's start: %s failed, left to the next start: %v", what, err) }