Files
mesh-sdk/go/views/held_writer.go
T
jschoubben 78807e5ef3 Design 47 H1: a held writer always starts; a retired entry may name its scope
Start returned at the first early write, early clear or retired clear that
failed, before the writer started, so one refused kind stopped the writer
whole. A refused kind is now skipped (refuse said it once) and any other
failure is said in the journal and left to the next start; the writer always
starts. A RetiredKind may name its Scope, so an entry clears only keys of it.

Builds: design 47 H H-A-242 (3), H-A-249, G §580
2026-11-21 11:47:20 +01:00

211 lines
7.3 KiB
Go

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)
}