Compare commits

...
10 Commits
Author SHA1 Message Date
mesh-tools 8167d825ed Merge pull request 'mesh-grants: the marks subtest calls on the caller's granted token and waits for its refusals; the test's nats_streams stand-in skips a consumer gone' (#270) from fix/47-H1-grants-marks-test into main 2026-11-20 15:19:12 +00:00
jschoubben ac95e5628c mesh-grants: the test's stand-in nats_streams skips a consumer gone between its listing and its read
Under load (8 copies side by side) TestTheGrantsPartWhole panicked at
integration_test.go:151 at abb7cfcf too: st.Consumer's error was dropped
and a consumer deleted after ConsumerNames listed it gave a nil one.

Builds: design 47 H §746 (the pipeline's integration step)
2026-11-20 16:11:14 +01:00
jschoubben bed9b61d5a mesh-grants: the marks subtest calls on the caller's granted token and waits for its refusals
The subtest "a runtime denied the marks is delivered no call on a marked
subject" published the caller-named call on mesh.mod.shell.call.execute.asker~a,
a token the composer never grants (buscompose.CallerToken gives a~asker
for the user a.asker), so the server refused it every time; the test
passed only because it read the refusals with a non-blocking select
right after Flush, before the client's error callback had run. Under
load the callback won the race and the pipeline's integration step
failed (main.12, 15:50). The call now uses CallerToken, and a probe on
another caller's token is published last: the server refuses in order,
so waiting for the probe's refusal waits on every refusal asserted.

Builds: design 47 H §746 (the pipeline's integration step), G A-203 (AM-D4)
2026-11-20 16:09:35 +01:00
mesh-tools 67ef449230 Merge pull request 'mesh-grants: bring a held kept stream to its definition's source filter (H-A-145)' (#269) from fix/47-H1-kept-stream-source-filter into main 2026-11-20 14:47:59 +00:00
mesh-tools 8a52b6f801 Merge pull request 'forge bridge: adopt only an added branch; its integration tests wait on what they assert' (#268) from fix/47-H1-forge-bridge-integration into main 2026-11-20 14:46:50 +00:00
jschoubben 380d4781e6 mesh-grants: bring a held kept stream to its definition's source filter
The kept stream of the runner's pipeline-ended was made at G's
definition, sourced by a three-part subject; H1 moved the event to
<branch>.<source>, so the stream took nothing in since 08:13 and the
assigner, which hears a kept event from its kept stream, heard no end.
createKept left every held kept stream as it was. It now brings a held
one's source filter from the events stream to the definition's in place
(a stream update, its messages and other settings kept, never made
again) and says the held and the composed filter in the journal and the
pass; the same holds for pipeline-started and wait-held.

Builds: design 47 H H-A-145 (hq design/47-H1-answers-59 0787704b), §746
2026-11-20 15:42:24 +01:00
jschoubben 7534bf5c07 forge bridge: adopt only an added branch; its integration tests wait on what they assert
Pipeline main.8 failed TestBridgeSaysOneHeadMovedPerMove and TestBridgePerformsWhatIsOwedOnce on
shanks; both fail the same way at 403fb306, before the catalog client change, under load.

- The bridge read every head again, start true, whenever the registrations' first view said its
  values after the start had begun, so a head moved just after the start was said as a start.
  Only a registration adding a watched branch is adopted now (Watched.Set says so), decided under
  one lock with the start's read.
- The head-moved test moved the head before the restart's read was answered, and read the state
  heads before the bridge wrote it; it now waits for the stand-in's answer and watches heads.
- The owed test stopped the bridge while an outcome's publish was on its way (heard again after
  the start), and an act said while the bridge stops can be handed to the stopped bridge's pull,
  which the bus hands again only after the consumer's acknowledgement wait (30 s) past the
  test's 20 s bound. It now hears the bridge's acknowledgements before the stop and waits the
  consumer's acknowledgement wait for the act said meanwhile.

Builds: design 47 H §739; design 47 G §532; design 47 H-A-48
2026-11-20 15:41:10 +01:00
mesh-tools 08fe40f233 Merge pull request 'assigner: a machine's composition across the watched branches (H-A-143, H-A-144)' (#267) from fix/47-H1-compose-across-branches into main 2026-11-20 14:38:28 +00:00
jschoubben 27e96a2a1b assigner: say an unlisted module on every path; no registration, no branches (H-A-144)
Review round 1: an unlisted module was lost where the composer blamed a module.
It is now said in the failed or could-not-run words where one is set, else as a
warning. Once registrations are held, a module none names has no watched
branches and is unlisted, never composed from the branches the client follows;
before the first registrations the gate's source's branches stand in, in its
order. A module is judged unlisted by its own watched branches.

Builds: design 47 H H-A-143, H-A-144, G §532
2026-11-20 15:35:59 +01:00
jschoubben f98d5ec748 assigner: compose a machine across every watched branch (H-A-143)
The composition step judged a machine at the step's one branch revision, so an
app registered on another watched branch was missing and the machine failed
"nothing provides", ending every mover there "could not run". Each module's
entry now comes from the newest revision of the first of its watched branches,
in its registration's order, that lists it; the candidate's revision replaces
its branch's newest for the modules it moves. A module assigned to the machine
that no watched branch lists is said in the machine's reason.

Builds: design 47 H H-A-143, G §532
2026-11-20 15:28:29 +01:00
22 changed files with 655 additions and 53 deletions
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"strings"
"sync"
@@ -53,6 +54,13 @@ type compositionRun struct {
call func(key string, body any) (json.RawMessage, error)
// trunk is the trunk's catalog half as the assigner holds it.
trunk func() (mcc.Half, bool)
// newest is the newest catalog half the assigner's views hold of each watched branch (halves.views), and watched a module's
// watched branches in its registration's order (halves.watchedOf): a machine's composition takes each module's manifest across
// them (design 47 H-A-143, G §532). Nil: the step's revision alone.
newest func() map[string]mcc.Half
watched func(module string) []string
// assigned is the modules the assignments place on a machine (world.assignments), for the modules no watched branch lists.
assigned func(node string) []string
// running is the last `running` heard of a module on a node (world.runningOf), never the node-engine's bucket.
running func(node, module string) (ne.Running, bool)
// away says the watchman holds machine away (machine-away, not back since): the one presence the assigner keeps (world.awayNow),
@@ -123,7 +131,7 @@ func (r *compositionRun) read(ctx context.Context, module string, keys []string,
runs := r.runs.await(ctx, keys)
setPhase(ctx, meshwants.StepProgressEventPhaseReport)
for _, key := range keys {
ends = append(ends, judgeRun(module, runs[key]))
ends = append(ends, judgeRun(module, runs[key], r.unlistedOn(runs[key].Machine)))
}
out := outcomeOf(ends)
out.Shared = r.runs.sharedOf(keys, runs)
@@ -209,6 +217,9 @@ func (p *runPrep) get(ctx context.Context) error {
p.err = errors.New("the step's catalog revision is not read: " + err.Error())
return
}
if p.r.newest != nil && p.r.watched != nil {
half = acrossBranches(p.step, half, p.r.newest(), p.r.watched)
}
if p.seats, p.err = p.r.seats(ctx, half.Revision.Definitions); p.err != nil {
return
}
@@ -289,7 +300,27 @@ const notTried = "not tried: the search reached its bound"
// could not run where the module was not tried (A-470b); a machine that does not compose and blames no module fails every step on
// it, on the node's own account; a verdict with no `blamed` (a composer before §721) is judged as before, with the warning "the
// composer names no culprits"; otherwise the machine passes, with a warning for each other module blamed there.
func judgeRun(module string, run meshwants.CompositionRun) machineEnd {
//
// unlisted are the modules the machine is assigned that none of their watched branches lists: each is said on every path, in the
// machine's failed or could-not-run words where one is set, else as a warning, never dropped in silence (H-A-143, H-A-144).
func judgeRun(module string, run meshwants.CompositionRun, unlisted []string) machineEnd {
end := judgeVerdict(module, run)
for _, u := range unlisted {
said := run.Machine + " is assigned " + u + ", which no watched branch lists (H-A-143)"
switch {
case end.failed != "":
end.failed += "; " + said
case end.couldNot != "":
end.couldNot += "; " + said
default:
end.warnings = append(end.warnings, said)
}
}
return end
}
// judgeVerdict is judgeRun before the unlisted modules are said.
func judgeVerdict(module string, run meshwants.CompositionRun) machineEnd {
node := run.Machine
if run.Ended == nil {
return machineEnd{couldNot: node + ": the step stopped before its composition run " + runKeyOf(run.Candidate, node) + " ended"}
@@ -503,6 +534,74 @@ func caseOf(half mcc.Half) (map[string]composer.Manifest, map[string]string, err
return manifests, none, nil
}
// acrossBranches is the catalog half a machine's composition reads (design 47 H-A-143, H-A-144, G §532): each module's entry from
// the newest revision of the first of its watched branches, in its registration's order, that lists it, none for a module with no
// watched branches; the candidate's revision replaces its
// branch's newest for the modules it moves (its movers and the step's module), and the whole of it where it is that branch's newest
// or the branch's is not held. The half keeps the candidate's revision, its definitions with it.
func acrossBranches(step meshwants.StepRun, candidate mcc.Half, newest map[string]mcc.Half, watched func(module string) []string) mcc.Half {
halves := make(map[string]mcc.Half, len(newest)+1)
for b, h := range newest {
halves[b] = h
}
if own, held := newest[step.Branch]; !held || candidate.Revision.Revision >= own.Revision.Revision {
halves[step.Branch] = candidate
} else {
mix := mcc.Half{Revision: own.Revision, Entries: maps.Clone(own.Entries)}
moved := []string{step.Module}
for _, m := range candidate.Revision.Movers {
moved = append(moved, m.Module)
}
for _, m := range moved {
if e, ok := candidate.Entries[m]; ok {
mix.Entries[m] = e
} else {
delete(mix.Entries, m)
}
}
halves[step.Branch] = mix
}
out := mcc.Half{Revision: candidate.Revision, Entries: map[string]meshcatalog.CatalogEntry{}}
for _, h := range halves {
for name := range h.Entries {
if _, done := out.Entries[name]; done {
continue
}
for _, b := range watched(name) { // none: no watched branch lists it, it is unlisted (H-A-144)
if e, ok := halves[b].Entries[name]; ok {
out.Entries[name] = e
break
}
}
}
}
return out
}
// unlistedOn is the modules the assignments place on node that the newest revision of none of their watched branches lists, a
// module with no watched branches among them (H-A-143, H-A-144), by name.
func (r *compositionRun) unlistedOn(node string) []string {
if r.assigned == nil || r.newest == nil || r.watched == nil {
return nil
}
newest := r.newest()
var out []string
for _, m := range r.assigned(node) {
listed := false
for _, b := range r.watched(m) {
if _, ok := newest[b].Entries[m]; ok {
listed = true
break
}
}
if !listed {
out = append(out, m)
}
}
slices.Sort(out)
return slices.Compact(out)
}
// nodeEngineEntry is the entry of the module that claims the seat node-engine, or false.
func nodeEngineEntry(entries map[string]meshcatalog.CatalogEntry) (meshcatalog.CatalogEntry, bool) {
for _, name := range slices.Sorted(mapsKeys(entries)) {
@@ -616,3 +715,24 @@ func runAskPublisher(js jetstream.JetStream) func(ctx context.Context, a buildst
return err
}
}
// newestOf is the newest catalog half the views hold of each watched branch, or nil while the catalog half is not followed.
func (iv *catalogViews) newestOf() func() map[string]mcc.Half {
if iv == nil {
return nil
}
return func() map[string]mcc.Half {
if iv.h == nil {
return map[string]mcc.Half{}
}
return iv.h.views()
}
}
// watchedOf is a module's watched branches in its registration's order (halves.watchedOf); none while the half is not followed.
func (iv *catalogViews) watchedOf(module string) []string {
if iv == nil || iv.h == nil {
return nil
}
return iv.h.watchedOf(module)
}
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"errors"
"maps"
"slices"
"strings"
"sync"
@@ -259,6 +260,30 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
}
}
// Another watched branch's app is in every machine's case, and a module assigned there that no watched branch lists is said in
// the machine's reason (H-A-143, §532).
across := newRunStand(t, "src2:e1", "src2:e1", "d1")
across.r.newest = func() map[string]mcc.Half {
return map[string]mcc.Half{"master": {Revision: meshcatalog.CatalogRevision{Branch: "master", Revision: 2},
Entries: map[string]meshcatalog.CatalogEntry{"f1-circuits": {Module: "f1-circuits", Fp: "f1", Manifest: map[string]any{"module": "f1-circuits"}}}}}
}
across.r.watched = func(module string) []string {
if module == "checker" || module == "lidarr" { // no registration names them; lidarr is on main's revision all the same (H-A-144)
return nil
}
return []string{"main", "master"}
}
across.r.assigned = func(node string) []string { return []string{"m", "f1-circuits", "checker", "lidarr"} }
if out := across.r.run(context.Background(), "ask-step", step); out.Outcome != meshwants.StepEndedOutcomeFailed ||
!strings.Contains(out.Said, "g14 is assigned checker, which no watched branch lists (H-A-143)") ||
!strings.Contains(out.Said, "g14 is assigned lidarr, which no watched branch lists (H-A-143)") {
t.Errorf("the step across the watched branches came to %+v", out)
}
if c := across.requests["ace"].Cases[0]; string(c.Manifests["f1-circuits"].Raw) != `{"module":"f1-circuits"}` || len(c.Manifests) != 4 ||
c.Manifests["lidarr"].Raw != nil {
t.Errorf("the case across the watched branches holds %v", slices.Sorted(maps.Keys(c.Manifests)))
}
// At the inputs state's cap the ask is refused, naming the store (§354).
full := newRunStand(t, "src2:e1", "src2:e1", "d1")
full.r.keeper.used = func() (int64, error) { return inputsCap, nil }
@@ -438,21 +463,33 @@ func TestAMachineIsJudgedByTheModulesItBlames(t *testing.T) {
run meshwants.CompositionRun
failed, couldNo string
warnings []string
unlisted []string
}{
{"blamed module fails", "a", runOf(blamesA), "ace holds a: /etc/x is a's and c's", "", nil},
{"another module passes with a warning", "b", runOf(blamesA), "", "", []string{"ace holds a: /etc/x is a's and c's"}},
{"blames no module fails both", "b", runOf(`{"composes":false,"reason":"the node's own composition","blamed":[]}`), "ace does not compose and blames no module: the node's own composition", "", nil},
{"an old composer", "b", runOf(`{"composes":false,"reason":"x"}`), "ace does not compose: x", "", []string{"ace: the composer names no culprits"}},
{"composes", "b", runOf(`{"composes":true,"blamed":[]}`), "", "", nil},
{"blamed module fails", "a", runOf(blamesA), "ace holds a: /etc/x is a's and c's", "", nil, nil},
{"another module passes with a warning", "b", runOf(blamesA), "", "", []string{"ace holds a: /etc/x is a's and c's"}, nil},
{"blames no module fails both", "b", runOf(`{"composes":false,"reason":"the node's own composition","blamed":[]}`), "ace does not compose and blames no module: the node's own composition", "", nil, nil},
{"an old composer", "b", runOf(`{"composes":false,"reason":"x"}`), "ace does not compose: x", "", []string{"ace: the composer names no culprits"}, nil},
{"composes", "b", runOf(`{"composes":true,"blamed":[]}`), "", "", nil, nil},
{"own module not tried", "a", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"not tried: the search reached its bound"}]}`), "",
"ace holds a untried: the composer's search for culprits reached its bound of blame_tries (A-470b)", nil},
"ace holds a untried: the composer's search for culprits reached its bound of blame_tries (A-470b)", nil, nil},
{"another not tried", "b", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"not tried: the search reached its bound"}]}`), "", "",
[]string{"ace holds a: not tried: the search reached its bound"}},
{"not judged", "a", runOf(`{"composes":false,"not_judged":"no seat list","blamed":[]}`), "", "ace was not judged: no seat list", nil},
{"could not run", "a", meshwants.CompositionRun{Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: "ace: gone"}, "", "ace: gone", nil},
[]string{"ace holds a: not tried: the search reached its bound"}, nil},
{"not judged", "a", runOf(`{"composes":false,"not_judged":"no seat list","blamed":[]}`), "", "ace was not judged: no seat list", nil, nil},
{"could not run", "a", meshwants.CompositionRun{Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: "ace: gone"}, "", "ace: gone", nil, nil},
// H-A-143: a module assigned there that no watched branch lists is said in the reason, or as a warning where it composes.
{"an unlisted module in the reason", "b", runOf(`{"composes":false,"reason":"nothing provides \"photos\"","blamed":[]}`),
"ace does not compose and blames no module: nothing provides \"photos\"; ace is assigned photos, which no watched branch lists (H-A-143)", "", nil, []string{"photos"}},
{"does not compose, blames a module, an unlisted module", "a", runOf(`{"composes":false,"reason":"nothing provides \"photos\"","blamed":[{"module":"a","problem":"nothing provides \"photos\""}]}`),
"ace holds a: nothing provides \"photos\"; ace is assigned photos, which no watched branch lists (H-A-143)", "", nil, []string{"photos"}},
{"another module blamed, an unlisted module", "b", runOf(`{"composes":false,"blamed":[{"module":"a","problem":"x"}]}`), "", "",
[]string{"ace holds a: x", "ace is assigned photos, which no watched branch lists (H-A-143)"}, []string{"photos"}},
{"could not run, an unlisted module", "a", meshwants.CompositionRun{Machine: "ace", Ended: &at, Outcome: meshwants.CompositionRunOutcomeCouldNotRun, Said: "ace: gone"},
"", "ace: gone; ace is assigned photos, which no watched branch lists (H-A-143)", nil, []string{"photos"}},
{"an unlisted module where it composes", "b", runOf(`{"composes":true,"blamed":[]}`), "", "",
[]string{"ace is assigned photos, which no watched branch lists (H-A-143)"}, []string{"photos"}},
} {
t.Run(tc.name, func(t *testing.T) {
e := judgeRun(tc.module, tc.run)
e := judgeRun(tc.module, tc.run, tc.unlisted)
if e.failed != tc.failed || e.couldNot != tc.couldNo || !slices.Equal(e.warnings, tc.warnings) {
t.Errorf("judged %+v, want failed %q, could not run %q, warnings %q", e, tc.failed, tc.couldNo, tc.warnings)
}
@@ -572,3 +609,67 @@ func TestARerunMovesEveryReaderThatDidNotPass(t *testing.T) {
}
}
}
// Design 47 H-A-143, G §532: a machine's composition takes each module's entry from the newest revision of the first of its
// watched branches, in its registration's order, that lists it; the candidate's revision replaces its branch's newest for the
// modules it moves, and whole where it is that branch's newest; the half keeps the candidate's revision.
func TestACompositionTakesEachModuleAcrossTheWatchedBranches(t *testing.T) {
entry := func(module, fp string) meshcatalog.CatalogEntry {
return meshcatalog.CatalogEntry{Module: module, Fp: fp, Manifest: map[string]any{"module": module}}
}
half := func(branch string, revision int64, movers []string, entries ...meshcatalog.CatalogEntry) mcc.Half {
h := mcc.Half{Revision: meshcatalog.CatalogRevision{Branch: branch, Revision: revision, Definitions: []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: branch}}},
Entries: map[string]meshcatalog.CatalogEntry{}}
for _, m := range movers {
h.Revision.Movers = append(h.Revision.Movers, meshcatalog.TakeInEntry{Module: m})
}
for _, e := range entries {
h.Entries[e.Module] = e
}
return h
}
newest := map[string]mcc.Half{
"main": half("main", 4, nil, entry("engine", "e1"), entry("a", "a1"), entry("both", "main")),
"master": half("master", 9, nil, entry("f1-circuits", "f1")),
"nox-mesh": half("nox-mesh", 3, nil, entry("link2pay", "l1"), entry("photos", "p1"), entry("both", "nox")),
}
registrations := map[string][]string{"both": {"nox-mesh", "main"}, "f1-circuits": {"master"}, "link2pay": {"nox-mesh"}, "photos": {"nox-mesh"}}
registrations["engine"], registrations["a"] = []string{"main"}, []string{"main"}
watched := func(module string) []string { return registrations[module] } // a module no registration names has none (H-A-144)
for _, tc := range []struct {
name string
step meshwants.StepRun
candidate mcc.Half
newest map[string]mcc.Half
want map[string]string // module -> fingerprint
}{
{"the newest of main, the others' apps beside it", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, []string{"a"}, entry("engine", "e1"), entry("a", "a2"), entry("both", "main")), newest,
map[string]string{"engine": "e1", "a": "a2", "both": "nox", "f1-circuits": "f1", "link2pay": "l1", "photos": "p1"}},
{"an older candidate moves only its movers", meshwants.StepRun{Branch: "nox-mesh", Module: "link2pay", Revision: 2},
half("nox-mesh", 2, []string{"photos"}, entry("link2pay", "l0"), entry("both", "nox0")), newest,
map[string]string{"engine": "e1", "a": "a1", "both": "nox", "f1-circuits": "f1", "link2pay": "l0"}},
{"a branch not yet held is the candidate's", meshwants.StepRun{Branch: "master", Module: "f1-circuits", Revision: 1},
half("master", 1, nil, entry("f1-circuits", "f0")), map[string]mcc.Half{"main": newest["main"]},
map[string]string{"engine": "e1", "a": "a1", "both": "main", "f1-circuits": "f0"}},
{"no view held yet: the candidate alone", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, nil, entry("a", "a2")), nil, map[string]string{"a": "a2"}},
{"a module no registration names is not composed", meshwants.StepRun{Branch: "main", Module: "a", Revision: 5},
half("main", 5, nil, entry("a", "a2"), entry("checker", "c1")), nil, map[string]string{"a": "a2"}},
} {
t.Run(tc.name, func(t *testing.T) {
got := acrossBranches(tc.step, tc.candidate, tc.newest, watched)
fps := map[string]string{}
for name, e := range got.Entries {
fps[name] = e.Fp
}
if !maps.Equal(fps, tc.want) {
t.Errorf("composed from %v, want %v", fps, tc.want)
}
if got.Revision.Revision != tc.candidate.Revision.Revision || len(got.Revision.Definitions) != 1 || got.Revision.Definitions[0].Digest != tc.step.Branch {
t.Errorf("the half keeps revision %d with definitions %v, want the candidate's %d with its own", got.Revision.Revision, got.Revision.Definitions,
tc.candidate.Revision.Revision)
}
})
}
}
@@ -818,7 +818,7 @@ func (r *compositionRuns) leave(pipeline string, stop func(ids []string)) ([]str
// passedOn is whether the step of module passed on the machine of an ended run (§722): neither failed nor could not run there.
func passedOn(module string, run meshwants.CompositionRun) bool {
e := judgeRun(module, run)
e := judgeRun(module, run, nil) // the unlisted modules change only the words, never whether it passed
return e.failed == "" && e.couldNot == ""
}
@@ -416,7 +416,7 @@ func TestACompositionRunsBoundTimesOwedProgress(t *testing.T) {
len(*drops) != 1 || !strings.HasPrefix((*drops)[0], "run-1: ") {
t.Fatalf("past the bound: %+v, drops %v", run, *drops)
}
if got := judgeRun("a", run); got.couldNot != run.Said {
if got := judgeRun("a", run, nil); got.couldNot != run.Said {
t.Errorf("a reader of the run past its bound: %+v", got)
}
late := buildstep.StepEnded{Ask: "run-1", Asker: runAsker, Outcome: buildstep.OutcomePassed, Output: "{}"}
@@ -6,6 +6,7 @@ import (
"encoding/hex"
"encoding/json"
"slices"
"strings"
"sync"
"time"
@@ -13,6 +14,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/views"
)
@@ -191,3 +193,25 @@ func (h *halves) views() map[string]mcc.Half {
}
return out
}
// watchedOf is module's watched branches in its registration's order (the branch `register` named first, then each branch in the
// order `watch` added it). Once registrations are held, a module none names has none: it is unlisted (H-A-144). Only before the
// first registrations are held do the gate's source's branches stand in (the branches followed then), in the order the source
// gives them, by their names escaped as its keys are (design 47 G §532, H-A-143, H-A-144).
func (h *halves) watchedOf(module string) []string {
h.mu.Lock()
b := h.branches
h.mu.Unlock()
if b == nil {
return nil
}
if b.Registrations != nil && len(b.Registrations.All()) > 0 {
if reg, ok := b.Registrations.Registration(module); ok {
return slices.Clone(reg.Branches)
}
return nil
}
out := b.Followed()
slices.SortStableFunc(out, func(x, y string) int { return strings.Compare(keys.EscapeName(x), keys.EscapeName(y)) })
return out
}
@@ -3,6 +3,8 @@ package main
import (
"context"
"encoding/json"
"errors"
"slices"
"testing"
"time"
@@ -48,3 +50,45 @@ func TestAMeshThatNamesNoBranchSettlesTheAssignersFirstPass(t *testing.T) {
}
}
}
// Design 47 H-A-143, H-A-144, G §532: a module's watched branches are its registration's, in its order; once registrations are held a
// module none names has none; before the first registrations the gate's source's branches stand in, in the source's order.
func TestAModulesWatchedBranchesAreItsRegistrations(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
for _, tc := range []struct {
name string
regs []seat.Registration
module string
want []string
}{
{"its registration's order", []seat.Registration{{Module: "link2pay", Branches: []string{"nox-mesh", "main"}}}, "link2pay", []string{"nox-mesh", "main"}},
{"no registration names it", []seat.Registration{{Module: "link2pay", Branches: []string{"nox-mesh", "main"}}}, "checker", nil},
{"before the first registrations, the source's", []seat.Registration{}, "checker", []string{"main", "master"}},
} {
t.Run(tc.name, func(t *testing.T) {
call := func(key string, _ any) (json.RawMessage, error) {
switch key {
case mcc.RegistrationsVerb:
return json.Marshal(seat.RegistrationsAnswer{Registrations: tc.regs})
case mcc.SourceVerb:
return json.Marshal(map[string][]string{"branches": {"master", "main"}})
}
return nil, errors.New("not answered here")
}
reader := &views.ProcessReader{Module: "mesh-delivery-assigner", Call: call, Logf: t.Logf}
h := &halves{w: newWorld(), call: call, reader: reader, wake: func() {}, logf: t.Logf, ctx: ctx}
if err := h.follow(); err != nil {
t.Fatal(err)
}
for _, f := range reader.Followers()[:2] { // the registrations and the gate's source
if err := f.Start(ctx); err != nil {
t.Fatal(err)
}
}
if got := h.watchedOf(tc.module); !slices.Equal(got, tc.want) {
t.Errorf("the watched branches of %s are %v, want %v", tc.module, got, tc.want)
}
})
}
}
@@ -665,7 +665,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
// The composition step (design 47 G §22, §354): the seat mesh-wants' accepted kind step, run by one run ask per machine.
if bus != nil && js != nil && inputs != nil && p.publishWants != nil && runs != nil {
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFile}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept,
trunk: trunkOf(iv, w.trunkName), running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
steps := &compositionSteps{node: thisNode, say: p.publishWants, run: run.run, resume: run.resume,
validate: run.validate, resumeValidate: run.resumeValidate, ended: runs.stepEnded, now: time.Now, logf: logger.Printf}
move := steps.move(ctx) // the readers a rerun carried (§727, A-470d)
@@ -553,3 +553,12 @@ func (w *world) placedBranches() map[string]map[string]string {
}
return out
}
// assignedOn is the modules the assignments place on node.
func (w *world) assignedOn(node string) []string {
var out []string
for _, m := range w.assignments()[node].Modules {
out = append(out, m.Module)
}
return out
}
@@ -162,6 +162,8 @@ type bed struct {
answer func(verb string, answer string)
// calls are the verbs the stand-in was called with, in order, as `<seat>.<verb> <input>`.
calls func() []string
// called is signalled after each call the stand-in answered, its answer chosen.
called <-chan struct{}
// restart stops the bridge, runs between, and starts it again on the same bus.
restart func(between func())
}
@@ -237,6 +239,7 @@ func startBed(t *testing.T, head string) *bed {
answers["git."+verb] = string(gitfixture.Given(t, verb+" answers", "verb:"+verb+".answer"))
}
var called []string
signal := make(chan struct{}, 1)
for _, subject := range []string{"mesh.seat.*.call.*.*", "mesh.seat.*.tool.*"} {
sub, err := ctl.Subscribe(subject, func(m *nats.Msg) {
parts := strings.Split(m.Subject, ".")
@@ -249,6 +252,10 @@ func startBed(t *testing.T, head string) *bed {
answer = answers[verb+" "+in.Repository]
}
mu.Unlock()
select {
case signal <- struct{}{}:
default:
}
if answer == "" {
answer = `{"error":"the stand-in holds no answer"}`
}
@@ -279,7 +286,7 @@ func startBed(t *testing.T, head string) *bed {
start()
t.Cleanup(func() { stop() })
set := func(verb, answer string) { mu.Lock(); answers[verb] = answer; mu.Unlock() }
return &bed{srv: srv, ctl: ctl, js: js, ctx: ctx, done: done, answer: set,
return &bed{srv: srv, ctl: ctl, js: js, ctx: ctx, done: done, answer: set, called: signal,
calls: func() []string { mu.Lock(); defer mu.Unlock(); return append([]string(nil), called...) },
restart: func(between func()) {
stop()
@@ -289,6 +296,30 @@ func startBed(t *testing.T, head string) *bed {
}}
}
// callsOf is how many calls of the stand-in start with prefix.
func callsOf(b *bed, prefix string) int {
n := 0
for _, c := range b.calls() {
if strings.HasPrefix(c, prefix) {
n++
}
}
return n
}
// calledTimes waits until the stand-in answered n calls starting with prefix: a call's answer is chosen when it is counted.
func calledTimes(t *testing.T, b *bed, prefix string, n int) {
t.Helper()
bound := time.After(20 * time.Second)
for callsOf(b, prefix) < n {
select {
case <-b.called:
case <-bound:
t.Fatalf("%d calls %s within 20 s, want %d", callsOf(b, prefix), prefix, n)
}
}
}
// headAt sets the stand-in seat git so main of the catalog is at head, protected or not.
func headAt(b *bed, head string, protected bool) {
p := "true"
@@ -363,7 +394,10 @@ func TestBridgeSaysOneHeadMovedPerMove(t *testing.T) {
b.restart(func() { headAt(b, h4, true) })
said("a restart after a move", forgemsg.HeadMoved{Head: h4, Before: h3, Start: true})
held(t, b, h4)
branchReads := callsOf(b, "git.branch ")
b.restart(func() {}) // at the head held: nothing
// The head moves only once the start has read the head held, so that read is not the move's (§739: start true).
calledTimes(t, b, "git.branch ", branchReads+1)
headAt(b, h5, true)
move(t, b, "main")
said("the next move, the first message after the restart at the head held", forgemsg.HeadMoved{Head: h5, Before: h4})
@@ -372,13 +406,11 @@ func TestBridgeSaysOneHeadMovedPerMove(t *testing.T) {
t.Errorf("the bridge asked %s; it asks the seat git nothing but branch", c)
}
}
heads, err := b.js.KeyValue(b.ctx, headsBucket(forgeBridgeModule()))
if err != nil {
t.Fatal(err)
}
if e, err := heads.Get(b.ctx, "branch.novox.mesh-catalog.main"); err != nil || string(e.Value()) != h5 {
t.Errorf("the state heads holds %v (%v), want %s", e, err, h5)
// One read per start and per move of main: the first view's registrations, said after a start, adopt no branch (§532).
if n := callsOf(b, "git.branch "); n != 3+4 {
t.Errorf("the bridge read the head %d times, want 7: once at each of 3 starts and once per move of main (4)", n)
}
held(t, b, h5) // kept after the message is written, so watched for, not read at once
}
func heard(t *testing.T, b *bed) <-chan *nats.Msg {
@@ -395,10 +427,16 @@ func heard(t *testing.T, b *bed) <-chan *nats.Msg {
return ch
}
// next is the next message heard on subject within a bound; the others are passed by.
// next is the next message heard on subject within 20 s; the others are passed by.
func next(t *testing.T, ch <-chan *nats.Msg, subject string) []byte {
t.Helper()
bound := time.After(20 * time.Second)
return nextWithin(t, ch, subject, 20*time.Second)
}
// nextWithin is next within bound.
func nextWithin(t *testing.T, ch <-chan *nats.Msg, subject string, within time.Duration) []byte {
t.Helper()
bound := time.After(within)
for {
select {
case m := <-ch:
@@ -406,7 +444,7 @@ func next(t *testing.T, ch <-chan *nats.Msg, subject string) []byte {
return m.Data
}
case <-bound:
t.Fatalf("nothing on %s within 20 s", subject)
t.Fatalf("nothing on %s within %s", subject, within)
return nil
}
}
@@ -455,6 +493,30 @@ func TestBridgePerformsWhatIsOwedOnce(t *testing.T) {
}
return n
}
// The bridge's acknowledgements on its durable of the stream owed, heard as the bus hears them.
acks := make(chan *nats.Msg, 16)
ackSub, err := b.ctl.ChanSubscribe("$JS.ACK."+seat.StreamOwed+".n1_mesh-delivery-forge-bridge.>", acks)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = ackSub.Unsubscribe() })
if err := b.ctl.Flush(); err != nil {
t.Fatal(err)
}
acked := func(n int) {
t.Helper()
bound := time.After(20 * time.Second)
for n > 0 {
select {
case m := <-acks:
if string(m.Data) == "+ACK" {
n--
}
case <-bound:
t.Fatalf("the bridge did not acknowledge what it heard on %s within 20 s", seat.StreamOwed)
}
}
}
gateOwed := gitfixture.Seat(t, seat.Seat, "events", "owed is said, a status", "event:owed")[0]
subject := seat.SubjectOwed("novox~mesh-sdk", "178")
for range 2 {
@@ -479,12 +541,26 @@ func TestBridgePerformsWhatIsOwedOnce(t *testing.T) {
_ = json.Unmarshal(gateOwed, &other)
other["id"] = "status.novox/mesh-sdk#178.aaaaaaaaaaaa.mesh/other"
otherOwed, _ := json.Marshal(other)
// The three acts heard are acknowledged before the stop: one stopped while its outcome is on its way is heard again
// after the start, by design, which is not what this part of the test is about.
acked(3)
// An act said while the bridge stops may be handed to the stopped bridge's pull before the bus has seen it go: the bus
// hands it again after its consumer's acknowledgement wait, its redelivery the only clock (H-A-48).
owedConsumer, err := b.js.Consumer(b.ctx, seat.StreamOwed, "n1_mesh-delivery-forge-bridge")
if err != nil {
t.Fatal(err)
}
ackWait := owedConsumer.CachedInfo().Config.AckWait
b.restart(func() {
if _, err := b.js.Publish(b.ctx, subject, otherOwed); err != nil {
t.Fatal(err)
}
})
if e := ended(); e.Of != seat.Seat || e.Outcome != forgemsg.OwedPerformed {
afterRestart, err := forgemsg.DecodeOwedEnded(nextWithin(t, ch, forgeSubject(forgemsg.OwedEndedEvent), ackWait+20*time.Second))
if err != nil {
t.Fatal(err)
}
if e := afterRestart; e.Of != seat.Seat || e.Outcome != forgemsg.OwedPerformed {
t.Errorf("the gate's status after the restart: %+v, want performed", e)
}
if n := count("git.status"); n != 2 {
@@ -115,24 +115,31 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
var regs *meshcatalogclient.Registrations
turn := &sync.Mutex{}
mv := &mover{call: call, pub: js, heads: heads, watched: watched, turn: turn, logger: logger}
recompute := func() {
// begun says the start's read of the heads covers the watched branches from now on; it and what is watched are set
// under setting, so a branch added before begun is read by the start and one added after it is adopted.
var setting sync.Mutex
begun := false
recompute := func() (added bool) {
if regs != nil {
watched.Set(registeredOf(regs.All()), unescaped(src.Branches()))
added = watched.Set(registeredOf(regs.All()), unescaped(src.Branches()))
}
return added
}
started := make(chan struct{}) // closed once the watched branches are read
regs, _, err = meshcatalogclient.WireRegistrationsProcess(reader, keptCall, func(mcseat.Registration, bool) {
recompute()
select {
case <-started: // a branch registered while the bridge runs is adopted: its head read (§532)
setting.Lock()
adopt := recompute() && begun
setting.Unlock()
// Only a registration adding a watched branch while the bridge runs is adopted, its head read (§532); the first
// view's registrations, said after the start, add none, so the start reads their heads once, with start true (§739).
if adopt {
go mv.readHeads(ctx)
default:
}
})
if err != nil {
return err
}
src.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { recompute() }
src.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { setting.Lock(); recompute(); setting.Unlock() }
if _, err := reader.Adopt(src.Follower, sourcebranches.Seat, sourcebranches.EventSourceMoved, src.Hear); err != nil {
return err
}
@@ -167,7 +174,10 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
return nil
}
}
setting.Lock()
recompute()
begun = true
setting.Unlock()
close(started)
// What the gate says it owes, on its seat's stream owed through this module's durable there (made from its consumes).
// A stream not there yet is said, and the bridge goes on: its other work does not wait on the gate.
@@ -27,6 +27,23 @@ func TestAMoveOfAWatchedBranchIsOneHeadMoved(t *testing.T) {
if !watchedOf("main").Watches("novox/other", "main") || watchedOf("main").Watches("novox/other", "beta") {
t.Errorf("before the first registration the gate's source's branches are watched, of every repository")
}
// §532: only a registration adding a watched branch is adopted; the same registrations read again (a first view's
// values said after the start) add none.
regs := []Registered{{Origin: "novox/mesh-sdk", Branches: []string{"main", "beta"}}}
for _, c := range []struct {
name string
regs []Registered
want bool
}{
{"the same registrations again", regs, false},
{"a branch fewer", []Registered{{Origin: "novox/mesh-sdk", Branches: []string{"main"}}}, false},
{"a branch registered", regs, true},
{"a repository registered", append(regs, Registered{Origin: "novox/other", Branches: []string{"main"}}), true},
} {
if got := w.Set(c.regs, []string{"main"}); got != c.want {
t.Errorf("%s: added %v, want %v", c.name, got, c.want)
}
}
const head, before = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "cccccccccccccccccccccccccccccccccccccccc"
moved := Moved{Owner: "novox", Repo: "mesh-sdk", Branch: "feat/47-H"}
@@ -21,8 +21,10 @@ type Registered struct {
Branches []string
}
// Set takes what the bridge read: the registrations (none before the first) and the gate's source's branches by name.
func (w *Watched) Set(regs []Registered, source []string) {
// Set takes what the bridge read: the registrations (none before the first) and the gate's source's branches by name. It
// says whether a branch is watched now that was not (§532: a registration adding a watched branch is adopted); the same
// registrations read again add none.
func (w *Watched) Set(regs []Registered, source []string) (added bool) {
by := map[string][]string{}
for _, r := range regs {
for _, b := range r.Branches {
@@ -33,8 +35,33 @@ func (w *Watched) Set(regs []Registered, source []string) {
}
w.mu.Lock()
defer w.mu.Unlock()
before := w.pairsLocked()
w.byRepo, w.registered = by, len(regs) > 0
w.source = slices.Clone(source)
for p := range w.pairsLocked() {
if !before[p] {
added = true
}
}
return added
}
// pairsLocked is every watched branch as `<repository> <branch>`, the repository empty before the first registration
// (the gate's source's branch, of every repository). The caller holds mu.
func (w *Watched) pairsLocked() map[string]bool {
out := map[string]bool{}
if !w.registered {
for _, b := range w.source {
out[" "+b] = true
}
return out
}
for repo, branches := range w.byRepo {
for _, b := range branches {
out[repo+" "+b] = true
}
}
return out
}
// Watches says whether a move of branch in repository is one the bridge writes.
@@ -647,19 +647,32 @@ func aRuntimeDeniedTheMarksHearsNoMarkedCall(t *testing.T) {
t.Fatal(err)
}
asker, askerRefused := bus.dial("a.asker")
// The caller-named subject is process.Call's first: mesh.mod.<module>.call.<tool>.<caller's token>.
for _, subject := range []string{"mesh.mod.shell.tool.execute", "mesh.mod.shell.call.execute.asker~a", "mesh.mod.shell.tool.read"} {
// The caller-named subject is process.Call's first: mesh.mod.<module>.call.<tool>.<caller's token>, the token the
// composer grants (buscompose.CallerToken: `a~asker` for the user a.asker).
for _, subject := range []string{"mesh.mod.shell.tool.execute", "mesh.mod.shell.call.execute." + buscompose.CallerToken("a.asker"), "mesh.mod.shell.tool.read"} {
if err := asker.Publish(subject, []byte(`{}`)); err != nil {
t.Fatal(err)
}
}
// The server says a refused publish asynchronously, in the order of the publishes: a probe the asker may not publish
// (another caller's token) is refused after every refusal of the calls above, so waiting for it waits on what is asserted.
const probe = "mesh.mod.shell.call.execute.a~someone"
if err := asker.Publish(probe, []byte(`{}`)); err != nil {
t.Fatal(err)
}
if err := asker.Flush(); err != nil {
t.Fatal(err)
}
select {
case e := <-askerRefused:
t.Fatalf("the asker may not call: %s", e)
default:
for probed := false; !probed; {
select {
case e := <-askerRefused:
if !strings.Contains(e, `"`+probe+`"`) {
t.Fatalf("the asker may not call: %s", e)
}
probed = true
case <-time.After(5 * time.Second):
t.Fatal("the probe's refusal never came, so the calls' refusals are not known")
}
}
select {
case m := <-heard:
@@ -110,6 +110,34 @@ func (c creating) RaiseMaxBytes(stream string, to int64) (int64, bool, error) {
return from, true, nil
}
// SourceFilter brings the filter subject of a held stream's source from `source` to `filter` and changes nothing else
// (design 47 H H-A-145): it reads the stream's configuration and updates with the rest as it was, so its messages stay. A
// stream with no source from `source`, or one already at `filter`, is left as it is.
func (c creating) SourceFilter(stream, source, filter string) (string, bool, error) {
ctx, cancel := context.WithTimeout(c.ctx, requestWithin)
defer cancel()
s, err := c.js.Stream(ctx, stream)
if err != nil {
return "", false, err
}
cfg := s.CachedInfo().Config
i := slices.IndexFunc(cfg.Sources, func(src *jetstream.StreamSource) bool { return src != nil && src.Name == source })
if i < 0 || cfg.Sources[i].FilterSubject == filter {
if i < 0 {
return "", false, nil
}
return cfg.Sources[i].FilterSubject, false, nil
}
from := cfg.Sources[i].FilterSubject
src := *cfg.Sources[i]
src.FilterSubject = filter
cfg.Sources[i] = &src
if _, err := c.js.UpdateStream(ctx, cfg); err != nil {
return from, false, err
}
return from, true, nil
}
// AddFilters adds filter subjects to a held consumer and changes nothing else.
func (c creating) AddFilters(stream, name string, add []string) error {
ctx, cancel := context.WithTimeout(c.ctx, requestWithin)
@@ -147,7 +147,10 @@ func TestTheGrantsPartWhole(t *testing.T) {
consumers := []any{}
names := st.ConsumerNames(ctx)
for name := range names.Name() {
c, _ := st.Consumer(ctx, name)
c, err := st.Consumer(ctx, name)
if err != nil {
continue // deleted between the listing and its read: the bus module's tool lists what it can read
}
cfg := c.CachedInfo().Config
consumers = append(consumers, map[string]any{"name": name, "filters": cfg.FilterSubjects, "max_deliver": cfg.MaxDeliver})
}
@@ -611,6 +614,35 @@ func TestTheGrantsPartWhole(t *testing.T) {
if again, _ := stream.Info(ctx); !slices.Equal(again.Config.Subjects, []string{"a.>", "b.>"}) {
t.Errorf("subjects after adding a held one: %v", again.Config.Subjects)
}
// A kept stream's source filter is brought to its definition's in place: the stream is not made again, its settings
// stay, and an equal filter or a source of another stream changes nothing (design 47 H H-A-145, §746).
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: "KEPTSRC", Subjects: []string{"ev.>"}}); err != nil {
t.Fatal(err)
}
kept, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: "KEPT", MaxAge: time.Hour,
Sources: []*jetstream.StreamSource{{Name: "KEPTSRC", FilterSubject: "ev.ended.*.*.*"}}})
if err != nil {
t.Fatal(err)
}
keptBefore, _ := kept.Info(ctx)
for _, row := range []struct {
source, filter, from, holds string
changed bool
}{
{"KEPTSRC", "ev.ended.*.*", "ev.ended.*.*.*", "ev.ended.*.*", true},
{"KEPTSRC", "ev.ended.*.*", "ev.ended.*.*", "ev.ended.*.*", false},
{"OTHER", "ev.other", "", "ev.ended.*.*", false},
} {
from, changed, err := c.SourceFilter("KEPT", row.source, row.filter)
if err != nil {
t.Fatal(err)
}
now, _ := kept.Info(ctx)
if from != row.from || changed != row.changed || len(now.Config.Sources) != 1 || now.Config.Sources[0].FilterSubject != row.holds ||
now.Config.MaxAge != keptBefore.Config.MaxAge || !now.Created.Equal(keptBefore.Created) {
t.Errorf("source %s to %s: from %q changed %v, config %+v created %v", row.source, row.filter, from, changed, now.Config, now.Created)
}
}
// The named asks' purge takes one subject's messages and no other's, and a named worker's delete is said done also
// where the bus holds none (design 47 G §544).
for _, subj := range []string{"b.one", "b.two"} {
+7 -4
View File
@@ -202,6 +202,9 @@ func (b *fakeBus) AddSubjects(stream string, add []string) error {
return errors.New("stream not found")
}
// SourceFilter is the bus's update of a held stream's source filter: the fake holds no sources, so nothing changes.
func (b *fakeBus) SourceFilter(string, string, string) (string, bool, error) { return "", false, nil }
// RaiseMaxBytes is the bus's raise of a held stream's size cap: only to a larger cap, an unbounded stream and every other
// setting kept.
func (b *fakeBus) RaiseMaxBytes(stream string, to int64) (int64, bool, error) {
@@ -684,10 +687,10 @@ func TestGrants(t *testing.T) {
if n := strings.Count(string(src), "CreateStream"); (path == createOnly && n != 1) || (path != createOnly && n != 0) {
t.Errorf("%s holds CreateStream %d times: only create.go creates, once", path, n)
}
// The two updates of a stream: adding subjects to a held one (the operator, 2026-11-05) and raising its size cap
// (2026-11-09), both in create.go.
if n := strings.Count(string(src), "UpdateStream("); (path == createOnly && n != 2) || (path != createOnly && n != 0) {
t.Errorf("%s holds UpdateStream %d times: only create.go updates a stream, twice, to add subjects and to raise a size cap", path, n)
// The three updates of a stream: adding subjects to a held one (the operator, 2026-11-05), raising its size cap
// (2026-11-09) and bringing a kept stream's source filter to its definition's (design 47 H H-A-145), all in create.go.
if n := strings.Count(string(src), "UpdateStream("); (path == createOnly && n != 3) || (path != createOnly && n != 0) {
t.Errorf("%s holds UpdateStream %d times: only create.go updates a stream, three times, to add subjects, to raise a size cap and to bring a kept stream's source filter", path, n)
}
// The one object bucket: the part's own, of the user list sealed to the bus node, in sealed.go (ADR 0547 clause 7).
if path == sealedOnly {
@@ -1765,7 +1765,8 @@ const WatchmanModule = "mesh-delivery-watchman"
// 2026-10-26 08:54): its create, and its information to read back what it holds. Each by its own name: a name that
// is not one plain subject token is left out, since a wildcard there would be every stream. Its update is granted for the one
// acts the part does on a held stream: adding the subjects a manifest's new events need (grants.Creator.AddSubjects) and
// raising its size cap to the manifest's when larger (grants.Creator.RaiseMaxBytes; the operator, 2026-11-09); it never
// raising its size cap to the manifest's when larger (grants.Creator.RaiseMaxBytes; the operator, 2026-11-09), and bringing
// a kept stream's source filter to its definition's (grants.Creator.SourceFilter; design 47 H H-A-145); it never
// removes a subject, lowers a limit or recreates the stream, and never deletes or purges one.
func CreateStreamGrants(streams []string) []string {
var out []string
@@ -21,6 +21,9 @@ func (c *askCreator) AddSubjects(string, []string) error { return nil }
func (c *askCreator) RaiseMaxBytes(string, int64) (int64, bool, error) {
return 0, false, nil
}
func (c *askCreator) SourceFilter(string, string, string) (string, bool, error) {
return "", false, nil
}
// A seat whose queues came with G (mesh-builds) gets its work-queue ask stream from the seat list, as the controller made one for
// every seat before G; a seat that accepts nothing gets none, and a stream the bus holds is never made again (lead-47, 2026-11-15).
@@ -69,6 +69,10 @@ type Creator interface {
// changes nothing else (the operator, 2026-11-09 09:07: "raise only"). It answers the cap it held and whether it
// raised; a cap that is larger or equal, or an unbounded stream, is left as it is. It never lowers any limit.
RaiseMaxBytes(stream string, to int64) (from int64, raised bool, err error)
// SourceFilter brings the filter subject of a held stream's source from the stream `source` to `filter`, keeping its
// messages and every other setting, the stream not made again (design 47 H H-A-145). It answers the filter it held and
// whether it changed; a stream with no source from `source` is left as it is.
SourceFilter(stream, source, filter string) (from string, changed bool, err error)
}
// Raise is one held stream's size cap raised to the manifest's, said in the event and the journal.
@@ -1,8 +1,11 @@
package grants
import (
"strings"
"testing"
"github.com/nats-io/nats.go/jetstream"
"mesh-grants/internal/buscompose"
)
@@ -39,3 +42,70 @@ func TestTheGrantsAccountMayCreateEachKeptEventStream(t *testing.T) {
})
}
}
// sourcing is a Creator holding kept streams by their source filter and message count: SourceFilter updates a held one in
// place, so its messages stay; CreateDeclared makes one the bus lacks.
type sourcing struct {
Creator
filters map[string]string // by stream, its source filter from EVENTS
messages map[string]int
made []string
}
func (s *sourcing) SourceFilter(stream, source, filter string) (string, bool, error) {
from, ok := s.filters[stream]
if !ok || source != buscompose.EventsStream || from == filter {
return from, false, nil
}
s.filters[stream] = filter
return from, true, nil
}
func (s *sourcing) CreateDeclared(cfg jetstream.StreamConfig) error {
s.made = append(s.made, cfg.Name)
s.filters[cfg.Name], s.messages[cfg.Name] = cfg.Sources[0].FilterSubject, 0
return nil
}
// H-A-145 (design 47 H §746): a held kept stream whose source filter the definition changed is brought to the definition's
// filter in place, its messages kept and the change said with both filters; one at the definition's filter is untouched; one
// the bus lacks is made.
func TestAKeptStreamFollowsItsDefinitionsSourceFilter(t *testing.T) {
const ended = "mesh.seat.mesh-pipeline-runner.event.pipeline-ended.*.*"
for _, row := range []struct {
name string
held string // the held stream's source filter; "" for a stream the bus lacks
made bool
moved string
filter string
messages, keptMsgs int
}{
{name: "held at the definition's filter: untouched", held: ended, filter: ended, messages: 604, keptMsgs: 604},
{name: "held at an earlier filter: brought to the definition's, messages kept", held: ended + ".*", filter: ended, messages: 604, keptMsgs: 604,
moved: "SEAT_mesh-pipeline-runner_pipeline-ended: source filter " + ended + ".* brought to " + ended + ", its messages kept"},
{name: "not held: made", made: true, filter: ended},
} {
t.Run(row.name, func(t *testing.T) {
k := buscompose.KeptEvent{Seat: "mesh-pipeline-runner", Event: "pipeline-ended", Stream: "SEAT_mesh-pipeline-runner_pipeline-ended", Filter: ended, MaxAgeDays: 90, MaxMiB: 192}
c := &sourcing{filters: map[string]string{}, messages: map[string]int{}}
held := map[string]Limits{}
if row.held != "" {
c.filters[k.Stream], c.messages[k.Stream] = row.held, row.messages
held[k.Stream] = Limits{}
}
made, moved, notMade := createKept(c, &creations{}, []buscompose.KeptEvent{k}, held, false)
if len(notMade) != 0 {
t.Fatalf("not made: %v", notMade)
}
if (len(made) == 1) != row.made || len(c.made) != len(made) {
t.Errorf("made %v (bus %v), want made %v", made, c.made, row.made)
}
if got := strings.Join(moved, "; "); got != row.moved {
t.Errorf("moved %q, want %q", got, row.moved)
}
if c.filters[k.Stream] != row.filter || c.messages[k.Stream] != row.keptMsgs {
t.Errorf("the stream holds filter %q and %d messages, want %q and %d", c.filters[k.Stream], c.messages[k.Stream], row.filter, row.keptMsgs)
}
})
}
}
+15 -5
View File
@@ -65,14 +65,24 @@ func keptOutOfHearing(kept []buscompose.KeptEvent, watches []buscompose.Seat, co
}
// createKept makes each kept event's stream the bus lacks, from the shared events stream's messages of its subject, and
// says what it made. A stream the bus holds is left as it is; one made at this seat list and gone since is made again only on
// a hand assert (the same rule as a manifest's streams: made once per definition). held is what the bus held at this pass.
func createKept(c Creator, done *creations, kept []buscompose.KeptEvent, held map[string]Limits, force bool) (made, notMade []string) {
// says what it made. A stream the bus holds keeps its messages and is not made again; its source filter is brought to the
// definition's in place when the definition changed the event's subject (design 47 H H-A-145, §746: the runner's
// pipeline-ended moved from three parts to two and its kept stream took nothing in), said in moved with the held and the
// composed filter. One made at this seat list and gone since is made again only on a hand assert (the same rule as a
// manifest's streams: made once per definition). held is what the bus held at this pass.
func createKept(c Creator, done *creations, kept []buscompose.KeptEvent, held map[string]Limits, force bool) (made, moved, notMade []string) {
for _, k := range kept {
cfg := k.StreamConfig()
if _, ok := held[k.Stream]; ok {
from, changed, err := c.SourceFilter(k.Stream, buscompose.EventsStream, k.Filter)
switch {
case err != nil:
notMade = append(notMade, k.Stream+": its source filter is not brought to "+k.Filter+": "+err.Error()+" (tried again at the next pass)")
case changed:
moved = append(moved, k.Stream+": source filter "+from+" brought to "+k.Filter+", its messages kept")
}
continue
}
cfg := k.StreamConfig()
digest := fmt.Sprintf("%v", cfg.Sources[0].FilterSubject) + fmt.Sprint(k.Last, k.MaxAgeDays, k.MaxMiB)
if !force && done.madeAt(k.Stream) == digest {
notMade = append(notMade, k.Stream+": made at this definition and gone since; grants_assert makes it again")
@@ -87,7 +97,7 @@ func createKept(c Creator, done *creations, kept []buscompose.KeptEvent, held ma
notMade = append(notMade, k.Stream+": "+err.Error()+" (tried again at the next event)")
}
}
return made, notMade
return made, moved, notMade
}
// eventSubjectsOf is, by seat, each event's subject pattern (`running.<node>.<module>`) of the events whose subject carries
+11 -1
View File
@@ -565,11 +565,21 @@ func (p *Part) Compose() Result {
}
forced := ask.Assert
if p.Create != nil && heldErr == nil {
made, notMade := createKept(p.Create, &p.made, in.Kept, held, forced != "")
made, moved, notMade := createKept(p.Create, &p.made, in.Kept, held, forced != "")
if len(made) > 0 {
res.Asserted = append(res.Asserted, "the seats' kept events: created "+strings.Join(made, ", "))
p.say(&res, EventAsserted, map[string]any{"module": Module, "created": made})
}
for _, m := range moved {
// Said in the journal with both filters (H-A-145).
res.Asserted = append(res.Asserted, "the seats' kept events: "+m)
if p.Logf != nil {
p.Logf("kept stream %s", m)
}
}
if len(moved) > 0 {
p.say(&res, EventAsserted, map[string]any{"module": Module, "source-filters": moved})
}
for _, why := range notMade {
res.NotAsserted = append(res.NotAsserted, "kept event "+why)
}