Compare commits

..
Author SHA1 Message Date
mesh-tools 49b7db386a Merge pull request 'Design 47 H1: a held findings writer seeds only the kinds it owns; retired kinds clear once (H-A-242)' (#207) from fix/47-H1-sdk-held-writer-owned into main 2026-11-21 10:50:20 +00:00
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
jschoubben d06835bf93 Design 47 H1: a retired kind may name the ids its writer once wrote
Where another writer of the same state owns a retired kind now, clearing every
key of it would clear that writer's findings. A RetiredKind entry names its
kind and, optionally, the exact ids and id prefixes this writer wrote under
it; Start clears only those keys, every key of the kind when none are named.

Builds: design 47 H H-A-247 (3), H-A-249, G §580
2026-11-21 11:42:45 +01:00
jschoubben 220d511f95 Design 47 H1: a held writer clears its retired kinds once at start and reads only its own keys
A kind no code raises any more stood in the state with its condition open and
nobody to clear it. A writer's Retired kinds are cleared once at Start, said
as finding-cleared so the keeper clears their conditions, and never seeded;
Start reads (Get) only its own and its retired keys, checking ownership first.

Builds: design 47 H H-A-242, H-A-247 (3), G §580
2026-11-21 11:39:08 +01:00
jschoubben af2abcf121 Design 47 H1: a held writer seeds only the kinds it owns; an unowned kind is said once
The tool runner's held writer seeded every key of the module's shared state
`findings`, the daemon's kinds included, and then refused them once a minute,
so no finding of the indexer was stated. Start now seeds only keys of the
writer's own kinds (G §580: another bundle states its own), and a kind the
writer does not own is refused with "finding kind X not declared", said in
the journal once per kind and left out of a statement, never retried.

Builds: design 47 H H-A-240, H-A-242 (1) (3), G §580
2026-11-21 11:28:04 +01:00
3 changed files with 239 additions and 14 deletions
+34 -9
View File
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"sort"
"strings"
"sync"
)
@@ -139,16 +140,30 @@ func (h *HeldWriter[F, C, S, A]) Held() []F {
return out
}
// Start seeds what the writer holds from the keys of its state `findings` (design 47 G A-40), what was written before it
// standing over them, writes what was written and clears what was cleared before it, and starts the writer. A part makes the
// writer before its module serves, so nothing is read from the state until now.
// 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()
@@ -171,15 +186,25 @@ func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
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 {
if err := h.Writer.Write(ctx, f); err != nil {
return err
}
h.unstarted(h.Writer.Write(ctx, f), "an early write")
}
for _, c := range cleared {
if err := h.Writer.Clear(ctx, c[0], c[1], c[2], c[3]); err != nil {
return err
}
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)
}
+79 -3
View File
@@ -168,6 +168,11 @@ type WriterConfig[F, C, S, A any] struct {
// naming it, its statement carries them as `kinds` and deletes only keys of them. None given, it owns every kind.
// The kinds of a views reader (ViewKinds) are the reader's own and are always the writer's besides.
Kinds []string
// Retired are kinds no code of the part raises any more, last written by this writer (design 47 H H-A-247 (3),
// H-A-249): a held writer's Start clears their keys, saying finding-cleared so the keeper clears their conditions, and
// never seeds them; a Write of one is refused as of any kind not owned. An entry naming ids clears only the keys of
// those ids, where another writer owns the kind now.
Retired []RetiredKind
// JS is the bus connection's JetStream; Conn, when given, lets the writer hear the connection made again.
JS jetstream.JetStream
Conn *nats.Conn
@@ -212,6 +217,9 @@ type Writer[F, C, S, A any] struct {
wake chan struct{}
run context.Context
end context.CancelFunc
// said are the kinds a refusal was said of in the journal, once each (design 47 H H-A-242 (3)).
saidMu sync.Mutex
said map[string]bool
}
// NewWriter is the writer for cfg.
@@ -433,6 +441,33 @@ func (w *Writer[F, C, S, A]) loop(ctx context.Context) {
}
}
// unownedKind is the refusal of a finding kind the writer does not own (design 47 G §580, H H-A-240, H-A-242).
type unownedKind struct {
kind string
kinds []string
}
func (e *unownedKind) Error() string {
return fmt.Sprintf("finding kind %q not declared: it is not one this writer owns (%v)", e.kind, e.kinds)
}
// refuse is the refusal of kind, said in the journal the first time only (design 47 H H-A-242 (3)): a kind no writer list
// declares is a fault of the part's code, said once, never once a minute.
func (w *Writer[F, C, S, A]) refuse(kind string) error {
err := &unownedKind{kind: kind, kinds: w.cfg.Kinds}
w.saidMu.Lock()
first := !w.said[kind]
if w.said == nil {
w.said = map[string]bool{}
}
w.said[kind] = true
w.saidMu.Unlock()
if first {
w.cfg.Logf("%v: the part's code raises a kind its writer does not declare; said once", err)
}
return err
}
// owns says whether the writer's statement covers kind: every kind when none were given (design 47 G §580), else its
// own and the views reader's.
func (w *Writer[F, C, S, A]) owns(kind string) bool {
@@ -450,6 +485,38 @@ func (w *Writer[F, C, S, A]) statedKinds() []string {
}
// ownsKey says whether key is one of a kind the writer owns: its last part is the kind (`<scope>.<id>.<kind>`).
// RetiredKind is a kind a writer once wrote and no code raises any more (H-A-247 (3)). Where another writer of the same state
// owns the kind now, IDs and Prefixes name the ids this writer wrote under it, as they stand in a key (H-A-249): only a key
// whose id is one of IDs or starts with one of Prefixes is cleared. Neither given, every key of the kind is.
type RetiredKind struct {
Kind string
// Scope, when given, is the only scope whose keys the entry clears.
Scope string
IDs []string
Prefixes []string
}
// covers says whether the key of scope, id and kind is one the entry retires (H-A-249).
func (r RetiredKind) covers(scope, id, kind string) bool {
if kind != r.Kind || (r.Scope != "" && scope != r.Scope) {
return false
}
if len(r.IDs) == 0 && len(r.Prefixes) == 0 {
return true
}
return slices.Contains(r.IDs, id) || slices.ContainsFunc(r.Prefixes, func(p string) bool { return strings.HasPrefix(id, p) })
}
// retiredKey says whether key is one the writer's retired list clears (H-A-247 (3), H-A-249).
func (w *Writer[F, C, S, A]) retiredKey(key string) bool {
scope, rest, _ := strings.Cut(key, ".")
i := strings.LastIndex(rest, ".")
if i < 0 {
return false
}
return slices.ContainsFunc(w.cfg.Retired, func(r RetiredKind) bool { return r.covers(scope, rest[:i], rest[i+1:]) })
}
func (w *Writer[F, C, S, A]) ownsKey(key string) bool {
if len(w.cfg.Kinds) == 0 {
return true
@@ -523,7 +590,7 @@ func (w *Writer[F, C, S, A]) complete(finding F) (wire, wire, error) {
return f, nil, err
}
if !w.owns(str(f, "kind")) {
return f, nil, fmt.Errorf("the finding kind %q is not one this writer owns (%v)", str(f, "kind"), w.cfg.Kinds)
return f, nil, w.refuse(str(f, "kind"))
}
old, err := w.read(keyOf(f))
if err != nil {
@@ -588,10 +655,15 @@ func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
// Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said
// all the same, so a keeper holding the finding clears it (design 47 G §485).
func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
if !w.owns(kind) {
return fmt.Errorf("the finding kind %q is not one this writer owns (%v)", kind, w.cfg.Kinds)
return w.refuse(kind)
}
return w.clear(ctx, scope, id, kind, why)
}
// clear is Clear of a kind the writer may clear: its own, or a retired one at a held writer's start (H-A-247 (3)).
func (w *Writer[F, C, S, A]) clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
w.mu.Lock()
if err := w.cfg.State.Delete(key); err != nil {
w.mu.Unlock()
@@ -633,6 +705,10 @@ func (w *Writer[F, C, S, A]) stated(ctx context.Context, asked string) ([]byte,
findings, pending := []wire{}, []wire{}
for _, finding := range obs.Findings {
f, _, err := w.complete(finding)
var refused *unownedKind
if errors.As(err, &refused) {
continue // said once in the journal by refuse, never a reason to state again (design 47 H H-A-242 (3))
}
if err != nil {
return nil, err
}
+126 -2
View File
@@ -17,6 +17,26 @@ import (
"git.novox.be/novox/mesh-sdk/go/views"
)
// readState is a fakeState that names the keys read (H-A-247 (3): a held writer reads only its own keys).
type readState struct {
*fakeState
rmu sync.Mutex
got []string
}
func (s *readState) Get(key string) (*stdio.StateEntry, error) {
s.rmu.Lock()
s.got = append(s.got, key)
s.rmu.Unlock()
return s.fakeState.Get(key)
}
func (s *readState) read() []string {
s.rmu.Lock()
defer s.rmu.Unlock()
return slices.Clone(s.got)
}
// fakeState is an observer's state `findings` in memory.
type fakeState struct {
mu sync.Mutex
@@ -461,6 +481,14 @@ func subWriterKindsAndReaderFindings(t *testing.T) {
if _, ok := r.state.m["module.m=2eo=2es.view-waits"]; ok {
t.Errorf("the reader's finding was not cleared")
}
// H-A-242 (3): an observed finding of a kind the writer does not own is left out of the statement, never a reason to state
// again once a minute
r.observe = func(context.Context) (testObserved, error) {
return testObserved{Findings: []testFinding{finding("a", "observed"), other}}, nil
}
if err := r.w.State(ctx, ""); err != nil {
t.Errorf("a statement with a finding of a kind not owned: %v", err)
}
}
// A views reader's four findings are laid out by mesh-sdk through the body's setters (design 47 G §687): the finding's
@@ -637,8 +665,104 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
if held := h.Held(); len(held) != 2 {
t.Fatalf("after Start Held answers the seeded and the early: %v", held)
}
if _, ok := state.m["module.early.k"]; !ok {
t.Fatalf("the early finding was written at Start: %v", state.m)
if e, _ := state.Get("module.early.k"); e == nil {
t.Fatal("the early finding was not written at Start")
}
// Design 47 G §580, H H-A-240, H-A-242: a writer made with its kinds seeds only keys of those kinds; another bundle's key
// (kind b) is not held, so its statement is said and the key stays; a write of kind b is refused each time and said once.
owned := &fakeState{m: map[string][]byte{}}
owned.m["module.seeded.k"] = raw
other := finding("other", "another bundle's")
other.Kind = "b"
rawOther, _ := json.Marshal(other)
owned.m["module.other.b"] = rawOther
// H-A-247 (3): a retired kind's key is cleared once at Start, said as cleared, never seeded; no other bundle's key is read
gone := finding("gone", "no code raises it")
gone.Kind = "r"
rawGone, _ := json.Marshal(gone)
owned.m["module.gone.r"] = rawGone
// H-A-249: a retired entry with ids clears only those keys of its kind; the same kind's key of another writer stays
for _, id := range []string{"mine", "mine2.x", "theirs"} {
f := finding(id, "kind s")
f.Kind = "s"
rawS, _ := json.Marshal(f)
owned.m["module."+id+".s"] = rawS
}
other2 := finding("mine", "kind s in another scope")
other2.Kind, other2.Scope = "s", "machine"
rawM, _ := json.Marshal(other2)
owned.m["machine.mine.s"] = rawM
read := &readState{fakeState: owned}
var logs []string
var sent []said
ocfg := testConfig{Module: "m", State: read, Node: "n1", Asked: asked, Kinds: []string{"k"},
Retired: []views.RetiredKind{{Kind: "r"}, {Kind: "s", Scope: "module", IDs: []string{"mine"}, Prefixes: []string{"mine2."}}},
Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() },
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
mu.Lock()
sent = append(sent, said{subject, data})
mu.Unlock()
return nil
},
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }}
oh, err := views.NewHeldWriter(ocfg)
if err != nil {
t.Fatal(err)
}
// H-A-242 (3): a clear before Start of a kind the writer does not own is refused once and never stops the writer
if err := oh.Clear(ctx, "module", "early", "z", "not owned"); err != nil {
t.Fatal(err)
}
if err := oh.Start(ctx); err != nil {
t.Fatalf("a held writer given a clear of a kind it does not own did not start: %v", err)
}
defer oh.Close()
if held := oh.Held(); len(held) != 1 || held[0].Kind != "k" {
t.Fatalf("a writer of kinds [k] seeded %v", held)
}
if e, _ := owned.Get("module.gone.r"); e != nil {
t.Fatal("the retired kind's key stays after Start")
}
for key, stays := range map[string]bool{"module.mine.s": false, "module.mine2.x.s": false, "module.theirs.s": true, "machine.mine.s": true} {
if e, _ := owned.Get(key); (e != nil) != stays {
t.Errorf("after Start the key %s stands: %v, want %v", key, e != nil, stays)
}
}
mu.Lock()
clearedGone := slices.ContainsFunc(sent, func(e said) bool {
return e.subject == subjects.Cleared && strings.Contains(string(e.data), `"kind":"r"`) && strings.Contains(string(e.data), `"id":"gone"`)
})
mu.Unlock()
if !clearedGone {
t.Fatalf("the retired key's clear is not said: %v", sent)
}
if got := read.read(); slices.Contains(got, "module.other.b") || slices.Contains(got, "module.gone.r") {
t.Fatalf("Start read keys not its own: %v", got)
}
if err := oh.Write(ctx, gone); err == nil {
t.Fatal("a write of a retired kind was taken")
}
if err := oh.State(ctx, ""); err != nil {
t.Fatalf("the statement of a writer over another bundle's key: %v", err)
}
if e, _ := owned.Get("module.other.b"); e == nil {
t.Fatal("the statement deleted another bundle's key")
}
for range 2 {
if err := oh.Write(ctx, other); err == nil || !strings.Contains(err.Error(), `finding kind "b" not declared`) {
t.Fatalf("a write of kind b: %v", err)
}
}
mu.Lock()
defer mu.Unlock()
refusals := 0
for _, l := range logs {
if strings.Contains(l, `finding kind "b" not declared`) {
refusals++
}
}
if refusals != 1 {
t.Fatalf("the refusal of kind b is said %d times, not once: %v", refusals, logs)
}
}