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
This commit is contained in:
2026-11-21 11:47:20 +01:00
parent d06835bf93
commit 78807e5ef3
3 changed files with 33 additions and 18 deletions
+14 -9
View File
@@ -186,20 +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 {
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]), "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)
}
+8 -6
View File
@@ -489,14 +489,16 @@ func (w *Writer[F, C, S, A]) statedKinds() []string {
// 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
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.
func (r RetiredKind) covers(id, kind string) bool {
if kind != r.Kind {
// 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 {
@@ -507,12 +509,12 @@ func (r RetiredKind) covers(id, kind string) bool {
// 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 {
_, rest, _ := strings.Cut(key, ".")
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(rest[:i], rest[i+1:]) })
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 {
+11 -3
View File
@@ -688,11 +688,15 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
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", IDs: []string{"mine"}, Prefixes: []string{"mine2."}}},
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()
@@ -705,9 +709,13 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if err := oh.Start(ctx); err != nil {
// 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)
@@ -715,7 +723,7 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
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} {
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)
}