diff --git a/modules/mesh-delivery-watchman/internal/watch/waits_test.go b/modules/mesh-delivery-watchman/internal/watch/waits_test.go index 7338d431..c9483df0 100644 --- a/modules/mesh-delivery-watchman/internal/watch/waits_test.go +++ b/modules/mesh-delivery-watchman/internal/watch/waits_test.go @@ -49,4 +49,24 @@ func TestAnActingPartsWaitIsLateByItsBoundFromItsClock(t *testing.T) { t.Fatalf("a late wait: %v", o.findings) } }) + // The grants part's wait is held as a seat's event too (design 47 G §269, G-20 A-12): its body names no node, and its release + // is said `wait-ended` with how `released`, which clears the finding. + t.Run("the seat mesh-grants' granting wait is late by its bound and ended by its release", func(t *testing.T) { + w, o, c := setup() + body := func(how string) []byte { + b, _ := json.Marshal(map[string]any{"step": "grant", "part": "mesh-grants", "version": "fp", "module": "web", "bound": "10m0s", + "since": c.t, "clock-from": c.t, "how": how}) + return b + } + gid := "mesh-grants-grant-mesh-grants--web" + w.WaitHeld("mesh-grants", body("")) + expire(w, c, signalKey(actingRow, gid), 10*time.Minute) + if _, ok := o.findings[FindingKey(ScopeDelivery, gid, KindActingPartLate)]; !ok { + t.Fatalf("past its bound: %v", o.findings) + } + w.WaitEnded("mesh-grants", body("released")) + if len(o.findings) != 0 { + t.Fatalf("the release left %v", o.findings) + } + }) } diff --git a/modules/mesh-delivery-watchman/manifest_test.go b/modules/mesh-delivery-watchman/manifest_test.go index 04571e4d..539a1637 100644 --- a/modules/mesh-delivery-watchman/manifest_test.go +++ b/modules/mesh-delivery-watchman/manifest_test.go @@ -127,7 +127,7 @@ func TestManifestStateAndReads(t *testing.T) { // 1135/AC6 t.Errorf("invokes = %v, want %v", m.Invokes, want) } // DLV-M5 its first views, 1585/T20 the indexer's take-in events, and DLV-W1 (ADR 0595 §4): the accepted verdicts and the bus module's created and refused, durably. - if want := []string{"mesh-delivery-assigner.views.wants", "mesh-delivery-indexer.take-in.pending", "mesh-delivery-indexer.take-in.taken", "mesh-delivery-indexer.views.modules", "mesh-catalog.manifest-accepted", "mesh-delivery.source-moved", "mesh-delivery.filling", "mesh-delivery.full", "mesh-delivery.room", "mesh-delivery.record-opened", "mesh-delivery.record-ended", "mesh-catalog.filling", "mesh-catalog.full", "mesh-catalog.room", "mesh-wants.filling", "mesh-wants.full", "mesh-wants.room", "mesh-grants.filling", "mesh-grants.full", "mesh-grants.room", "mesh-pipeline-runner.pipeline-started", "mesh-pipeline-runner.step-started", "mesh-pipeline-runner.step-ended", "mesh-pipeline-runner.wait-held", "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked"}; !reflect.DeepEqual(m.Consumes, want) { + if want := []string{"mesh-delivery-assigner.views.wants", "mesh-delivery-indexer.take-in.pending", "mesh-delivery-indexer.take-in.taken", "mesh-delivery-indexer.views.modules", "mesh-catalog.manifest-accepted", "mesh-delivery.source-moved", "mesh-delivery.filling", "mesh-delivery.full", "mesh-delivery.room", "mesh-delivery.record-opened", "mesh-delivery.record-ended", "mesh-catalog.filling", "mesh-catalog.full", "mesh-catalog.room", "mesh-wants.filling", "mesh-wants.full", "mesh-wants.room", "mesh-grants.filling", "mesh-grants.full", "mesh-grants.room", "mesh-pipeline-runner.pipeline-started", "mesh-pipeline-runner.step-started", "mesh-pipeline-runner.step-ended", "mesh-pipeline-runner.wait-held", "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", "mesh-grants.wait-held", "mesh-grants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked"}; !reflect.DeepEqual(m.Consumes, want) { t.Errorf("consumes = %v, want %v", m.Consumes, want) } // 1952/WM1: the watchman holds the seat mesh-watchdogs at mesh scope, its first seat (novox/hq ADR 0564 §1, §4). diff --git a/modules/mesh-delivery-watchman/module.json b/modules/mesh-delivery-watchman/module.json index 7f484f43..44b51e29 100644 --- a/modules/mesh-delivery-watchman/module.json +++ b/modules/mesh-delivery-watchman/module.json @@ -61,6 +61,8 @@ "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", + "mesh-grants.wait-held", + "mesh-grants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked" diff --git a/modules/mesh-grants/cmd/mesh-grants/bus.go b/modules/mesh-grants/cmd/mesh-grants/bus.go index 7f839eaa..d7c3e598 100644 --- a/modules/mesh-grants/cmd/mesh-grants/bus.go +++ b/modules/mesh-grants/cmd/mesh-grants/bus.go @@ -222,3 +222,5 @@ func (s ownStore) Delete(state, key string) error { return s.c.State(state).Dele type emitting struct{ c *process.Conn } func (e emitting) Emit(event string, body any) error { return e.c.Emit(event, body) } + +func (e emitting) EmitSeat(seat, event string, body any) error { return e.c.EmitSeat(seat, event, body) } diff --git a/modules/mesh-grants/cmd/mesh-grants/main.go b/modules/mesh-grants/cmd/mesh-grants/main.go index 97161aab..596087ce 100644 --- a/modules/mesh-grants/cmd/mesh-grants/main.go +++ b/modules/mesh-grants/cmd/mesh-grants/main.go @@ -139,6 +139,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro Objects: sealedObjects{ctx: ctx, js: js}, Purging: ownPurging{ctx: ctx, js: js, module: account.Module}, Logf: logger.Printf, Bus: grants.BusAddress{URL: account.URL, Fingerprint: account.Fingerprint}} f.Watch = fv + f.Part.ReadingRunning(nodeengine.StreamRunning) f.HearKept = func() error { return hearRunning(ctx, account, js, f, logger.Printf) } // The first view of the bindings (design 25 bindings-first-view): the seat mesh-broker's list, asked at each start and by // hand, with the seat's events held until its answer is applied or its bound passes. @@ -275,6 +276,14 @@ func hearRunning(ctx context.Context, account process.Account, js jetstream.JetS if hearingRunning.cc != nil { return nil } + // At each start the stream is read whole first, every subject's last message, through an ordered consumer made for that + // one read; the durable follows from its acknowledged position after it (design 47 G §556). Until it ends the part acts + // on none of running and grants_first_views says the stream waiting. + if err := readRunningWhole(ctx, js, f.Part, logf); err != nil { + return err + } + f.Part.RunningRead() + f.Wake() cc, err := account.HearSeatEvents(ctx, js, nodeengine.StreamRunning, func(m jetstream.Msg) { changed, err := f.Part.HearRunning(m.Subject(), m.Data()) if err != nil { @@ -314,3 +323,39 @@ func (g *seatGate) Definitions() map[string]seatdef.Definition { } return nil } + +// readRunningWhole reads every subject's last message of the node-engine's stream running through an ordered consumer, and +// keeps each in the part's state running (design 47 G §556). +func readRunningWhole(ctx context.Context, js jetstream.JetStream, p *grants.Part, logf func(string, ...any)) error { + stream, err := js.Stream(ctx, nodeengine.StreamRunning) + if err != nil { + return fmt.Errorf("the stream %s cannot be read whole: %w", nodeengine.StreamRunning, err) + } + cons, err := stream.OrderedConsumer(ctx, jetstream.OrderedConsumerConfig{DeliverPolicy: jetstream.DeliverLastPerSubjectPolicy}) + if err != nil { + return fmt.Errorf("the ordered consumer for the whole read of %s cannot be made: %w", nodeengine.StreamRunning, err) + } + read := 0 + for { + batch, err := cons.FetchNoWait(256) + if err != nil { + return fmt.Errorf("the whole read of %s failed: %w", nodeengine.StreamRunning, err) + } + n := 0 + for m := range batch.Messages() { + n++ + if _, err := p.HearRunning(m.Subject(), m.Data()); err != nil { + logf("running: %v, dropped", err) + } + } + if err := batch.Error(); err != nil { + return fmt.Errorf("the whole read of %s failed: %w", nodeengine.StreamRunning, err) + } + if n == 0 { + break + } + read += n + } + logf("running: the whole read ended, %d subjects kept; the durable follows from its place", read) + return nil +} diff --git a/modules/mesh-grants/cmd/mesh-grants/tools.go b/modules/mesh-grants/cmd/mesh-grants/tools.go index 4500e291..54971dea 100644 --- a/modules/mesh-grants/cmd/mesh-grants/tools.go +++ b/modules/mesh-grants/cmd/mesh-grants/tools.go @@ -144,6 +144,11 @@ type runtimeBus struct{} func (runtimeBus) Call(key string, body any) (json.RawMessage, error) { return stdio.Ask(key, body) } func (runtimeBus) Emit(event string, body any) error { return stdio.Emit(event, body) } +// EmitSeat is never asked of the tools: only the process holds the grant to publish a seat's event (design 47 G A-10). +func (runtimeBus) EmitSeat(seat, event string, _ any) error { + return fmt.Errorf("the tools do not say the seat %s's %s: the part's process does", seat, event) +} + func schema(properties map[string]string, required ...string) map[string]any { props := map[string]any{} for name, description := range properties { @@ -248,6 +253,16 @@ func toolsOf(p *grants.Part) []stdio.Tool { Run: func(a map[string]any) (any, error) { return p.AskFirstViewAgain(stdio.CallerOf(a), grants.Answer(a, "state"), grants.Answer(a, "why"), recordHandAct) }}, + {Name: grants.ToolWaits, Description: "The grants part's granting waits (design 47 G §276): each entry held because its grant is not " + + "composed yet by this version of the part, with its step, the acting part, its version, since when, its bound (10 minutes) and " + + "clock-from (the start of this version's first pass), and which have passed their bound. Read-only.", + Run: func(map[string]any) (any, error) { return p.WaitsOf() }}, + {Name: grants.ToolRelease, Description: "Release one held granting wait by a person's act with why, recorded as a hand act " + + "(the seat mesh-hand-acts) before it is released (design 47 G §276). grants_waits lists them.", + Input: schema(map[string]string{"module": "the held entry's module", "why": "why, kept in the hand act"}, "module", "why"), + Run: func(a map[string]any) (any, error) { + return p.ReleaseWait(stdio.CallerOf(a), grants.Answer(a, "module"), grants.Answer(a, "why"), recordHandAct) + }}, {Name: grants.ToolRunning, Description: "What each node-engine said it runs (novox/hq design 47, ADR 0660 §2): the last event " + "running of each node and module, as the grants part keeps it in its state running (module, node, the build's " + "fingerprint, the digest of that build's manifest, when it was seen running healthy). A seat's holder is read from " + diff --git a/modules/mesh-grants/go.mod b/modules/mesh-grants/go.mod index b36b96d8..da5b09e7 100644 --- a/modules/mesh-grants/go.mod +++ b/modules/mesh-grants/go.mod @@ -13,6 +13,7 @@ require ( git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshhealers v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/clients/meshvaultclient v0.0.0-00010101000000-000000000000 + git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshnodeenroller v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshvault v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient v0.0.0-00010101000000-000000000000 diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index cf70a3e7..ce59281c 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -62,6 +62,8 @@ type fakeBus struct { refuseTo map[string]bool calls []string events []string + // seatEvents are the seat events said, as seat.event. + seatEvents []string writes []string // Each membership's subject: the last membership said there, every notice, and whether it is refused. stream map[string][]byte @@ -389,6 +391,13 @@ func (b *fakeBus) Emit(event string, _ any) error { return nil } +func (b *fakeBus) EmitSeat(seat, event string, _ any) error { + b.mu.Lock() + defer b.mu.Unlock() + b.seatEvents = append(b.seatEvents, seat+"."+event) + return nil +} + func (b *fakeBus) count(key string) int { b.mu.Lock() defer b.mu.Unlock() @@ -1343,6 +1352,14 @@ func TestGrants(t *testing.T) { {"the holder's running build still claims it", map[string]catalogue.Manifest{"a.mesh-catalog": claimer("mesh-catalog")}, nil, []string{"mesh-catalog"}, ""}, {"a second claimant", nil, []string{"other"}, nil, "seat mesh-catalog --to /"}, } + // A holder whose node-engine said `stopped` claims nothing there (design 47 G §404, §459). + rows = append(rows, struct { + name string + running map[string]catalogue.Manifest + extra []string + want []string + said string + }{"the holder said stopped by its node-engine", map[string]catalogue.Manifest{"a.mesh-catalog": claimer("mesh-catalog")}, nil, []string{"mesh-delivery-indexer"}, "composed as held by mesh-delivery-indexer"}) // What the want names is no running build: the seat's holder is read from the digest the node-engine said it runs. wantedOnly := rows[1] wantedOnly.name = "a build only wanted, not said running by its node-engine, is not read" @@ -1359,13 +1376,20 @@ func TestGrants(t *testing.T) { Holds: []meshmoduleassigner.Holding{{Claim: "mesh-catalog", Scope: "mesh", Module: "mesh-catalog"}}}, "b": {Node: "b", Modules: []meshmoduleassigner.PlacedModule{{Module: "mesh-delivery-indexer"}}}}} if !strings.Contains(row.name, "only wanted") { - in.Ran = row.running + in.Ran, in.Heard, in.RanByFingerprint = row.running, map[string]catalogue.Heard{}, map[string]catalogue.Manifest{} + for key, m := range row.running { + in.Heard[key] = catalogue.Heard{Fingerprint: "fp-" + key} + in.RanByFingerprint["fp-"+key] = m + } } maps.Copy(in.Running, row.running) for _, c := range row.extra { in.Manifests[c] = claimer(c) in.Assigned["b"] = append(in.Assigned["b"], c) } + if strings.Contains(row.name, "stopped") { + in.Heard["a.mesh-catalog"] = catalogue.Heard{Stopped: true} + } before := maps.Clone(in.Placed) for node, p := range before { p.Holds = slices.Clone(p.Holds) @@ -2084,8 +2108,9 @@ func TestGrants(t *testing.T) { kb.loaded = shadowOf(t, kb) kp := partOn(kb) kp.Create, kp.Consumers = kb, kb + keepDays, keepMiB := 7, 64 kp.SeatList = keptGate{seatdef.Definition{Seat: "mesh-conditions", Events: []seatdef.Message{ - {Name: "condition-raised", Keep: seatdef.KeepStream, MaxAgeDays: 7, MaxMiB: 64}}}} + {Name: "condition-raised", Keep: &seatdef.Keep{Object: true, MaxAgeDays: &keepDays, MaxMiB: &keepMiB}}}}} kp.Compose() if !slices.Contains(kb.creates, "SEAT_mesh-conditions_condition-raised") || !slices.Contains(kb.consumerCreates, "SEAT_mesh-conditions_condition-raised.b_mod-y") || strings.Contains(fmt.Sprint(kb.consumers["EVENTS"]), "condition-raised") || @@ -2550,11 +2575,42 @@ func TestGrants(t *testing.T) { if p.Compose(); len(said) != 1 { t.Errorf("the same missing grant was said again: %+v", said) } + // The entry left without a grant is a granting wait (design 47 G §276, A-7): kept in the part's own state, with its + // bound of 10 minutes counted from the start of this version's first pass; a release is a hand act. + waits, err := p.WaitsOf() + if err != nil { + t.Fatal(err) + } + if w := waits.(grants.WaitsSaid).Waits; len(w) != 1 || w[0].Module != "mod-y" || w[0].Bound != "10m0s" || w[0].Step != "grant" || w[0].ClockFrom.IsZero() { + t.Fatalf("granting waits = %+v, want mod-y's, bound 10m0s, step grant", w) + } + if _, err := p.ReleaseWait("op", "mod-y", " ", nil); err == nil { + t.Error("a release with no why was taken") + } + var acts []string + if _, err := p.ReleaseWait("op", "mod-y", "why", func(what, why string) error { acts = append(acts, what); return nil }); err != nil || len(acts) != 1 { + t.Errorf("release: %v, hand acts %v", err, acts) + } + if w := func() []grants.HeldWait { x, _ := p.WaitsOf(); return x.(grants.WaitsSaid).Waits }(); len(w) != 1 || !w[0].Released { + t.Errorf("after the release: %+v", w) + } + // A-12: the held wait is said at its start, a release is said ended at the pass its ask makes, and said once. + p.Compose() + p.Compose() + if got := strings.Join(b.seatEvents, ","); got != "mesh-grants.wait-held,mesh-grants.wait-ended" { + t.Errorf("seat events = %q, want wait-held then one wait-ended (released)", got) + } + if x, _ := p.WaitsOf(); len(x.(grants.WaitsSaid).Late) != 0 { + t.Errorf("a released wait is late: %+v", x) + } b.put(grants.ReadModules, "mod-y", meshcatalog.ModulesByModuleValue{V: keys.Version, Fp2: fp, Manifest: meshcatalogclient.ManifestDigest([]byte(yManifest)), Repository: "novox/y", Commit: "c"}) if res := p.Compose(); len(res.Grants.Missing) != 0 || len(said) != 2 || said[1].State != occ.StateCleared { t.Errorf("once mod-y has a grant: missing %v, said %+v", res.Grants.Missing, said) } + if x, _ := p.WaitsOf(); len(x.(grants.WaitsSaid).Waits) != 0 { + t.Errorf("the wait of mod-y outlived its grant: %+v", x) + } }) // Issue 1966 (the registry delivery's second bootstrap loop): an assigner that serves no first views answers no @@ -4772,8 +4828,18 @@ func channelTakes(t *testing.T, say func(oc.Condition) error) func(oc.Condition) // Design 47, ADR 0660 §2: what the part hears of the node-engines' running is kept, a key a node and module, only when it // differs; a body that does not match its subject, or names no manifest, is refused; grants_running reads it back. func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { + at := time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC) + older := at.Add(-time.Hour) body := func(node, module, fp, digest string) []byte { - raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: time.Now(), Fingerprint: fp, Manifest: digest, Module: module, Node: node}) + raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: at, Fingerprint: fp, Manifest: digest, Module: module, Node: node}) + return raw + } + bodyAt := func(node, module, fp, digest string, when time.Time) []byte { + raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: when, Fingerprint: fp, Manifest: digest, Module: module, Node: node}) + return raw + } + stopped := func(node, module string) []byte { + raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: at.Add(time.Minute), Module: module, Node: node, Stopped: true}) return raw } bus := newFakeBus() @@ -4788,8 +4854,11 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { {"a first running is kept", subject, body("ace", "mod-c", "fp1", "sha256:a"), true, ""}, {"the same build said again keeps nothing", subject, body("ace", "mod-c", "fp1", "sha256:a"), false, ""}, {"a new build is kept", subject, body("ace", "mod-c", "fp2", "sha256:b"), true, ""}, + {"an event older by at than the one held changes nothing", subject, bodyAt("ace", "mod-c", "fp1", "sha256:a", older), false, ""}, {"a body of another node than its subject is refused", subject, body("g14", "mod-c", "fp2", "sha256:b"), false, "does not carry"}, {"a body with no manifest is refused", subject, body("ace", "mod-c", "fp2", ""), false, "no node, module or manifest"}, + {"a stopped body carries no fingerprint or manifest and is kept", subject, stopped("ace", "mod-c"), true, ""}, + {"the same stopped said again keeps nothing", subject, stopped("ace", "mod-c"), false, ""}, {"a body that is no running is refused", subject, []byte("x"), false, "not a running body"}, } { t.Run(row.name, func(t *testing.T) { @@ -4804,7 +4873,77 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { t.Fatal(err) } said := got.(grants.RunningSaid).Running - if len(said) != 1 || said[0].Manifest != "sha256:b" { - t.Errorf("grants_running = %+v, want the last build of ace.mod-c", said) + if len(said) != 1 || !said[0].Stopped { + t.Errorf("grants_running = %+v, want the last word of ace.mod-c: stopped", said) + } +} + +// A module naming a seat's view, `seat:.views.`, is granted the view of the module holding the seat on record, so a +// new holder is granted with no change of its manifest (design 47 G §616). +func TestASeatNamedViewIsResolvedToItsHolder(t *testing.T) { + consumer := func(consumes ...string) catalogue.Manifest { + return catalogue.Manifest{Module: "mod-t", Version: "1", RunsAs: "mod-t", Consumes: consumes, + OwnSecrets: catalogue.OwnSecrets{"broker": {Path: "/var/lib/mod-t/broker"}}} + } + holder := func(node string) grants.Inputs { + return grants.Inputs{Nodes: []string{"a"}, Assigned: map[string][]string{"a": {"mod-t"}}, + Placed: map[string]meshmoduleassigner.Assignments{"a": {Node: "a", + Holds: []meshmoduleassigner.Holding{{Claim: "mesh-module-assigner", Scope: "mesh", Module: node}}}}} + } + for _, row := range []struct { + name string + holder string + consumes []string + want []string + }{ + {"resolved to the holder on record", "mesh-delivery-assigner", []string{"seat:mesh-module-assigner.views.assignments", "mesh-vault.node-logins"}, + []string{"mesh-delivery-assigner.views.assignments", "mesh-vault.node-logins"}}, + {"a new holder is granted with no change of the manifest", "assigner-two", []string{"seat:mesh-module-assigner.views.seat-holders"}, + []string{"assigner-two.views.seat-holders"}}, + {"no holder on record stays as written", "", []string{"seat:mesh-module-assigner.views.assignments"}, + []string{"seat:mesh-module-assigner.views.assignments"}}, + } { + t.Run(row.name, func(t *testing.T) { + in := holder(row.holder) + if row.holder == "" { + in.Placed = nil + } + in.Manifests = map[string]catalogue.Manifest{"mod-t": consumer(row.consumes...)} + recs, _ := grants.ListRecords(in) + var got []string + for _, d := range recs.Assigned["a"] { + got = d.Consumes + } + if !slices.Equal(got, row.want) { + t.Errorf("consumes = %v, want %v", got, row.want) + } + }) + } +} + +// At its start the part reads the stream running whole before it follows it: until that read ends it acts on none of it and +// grants_first_views names the stream waiting (design 47 G §556). +func TestThePartNamesTheStreamItReadsWholeWaiting(t *testing.T) { + p := partOn(newFakeBus()) + p.ReadingRunning("SEAT_node-engine_running") + streamsAfterPass := func() []grants.StreamRead { + p.Compose() + got, err := p.FirstViewsOf() + if err != nil { + t.Fatal(err) + } + m, ok := got.(map[string]any) + if !ok { + t.Fatalf("grants_first_views answered %T", got) + } + reads, _ := m["streams"].([]grants.StreamRead) + return reads + } + if got := streamsAfterPass(); len(got) != 1 || got[0].State != "waiting" || got[0].Stream != "SEAT_node-engine_running" { + t.Fatalf("before its whole read ended the streams are %+v, want the stream waiting", got) + } + p.RunningRead() + if got := streamsAfterPass(); len(got) != 1 || got[0].State != "read" { + t.Fatalf("after its whole read ended the streams are %+v, want it read", got) } } diff --git a/modules/mesh-grants/internal/buscompose/modstreams.go b/modules/mesh-grants/internal/buscompose/modstreams.go index 64e0cec1..af945c1b 100644 --- a/modules/mesh-grants/internal/buscompose/modstreams.go +++ b/modules/mesh-grants/internal/buscompose/modstreams.go @@ -260,6 +260,14 @@ func heardGrants(p Principal, hears []Heard) []string { "$JS.API.CONSUMER.INFO."+h.Stream+"."+durable, "$JS.API.CONSUMER.MSG.NEXT."+h.Stream+"."+durable, "$JS.ACK."+h.Stream+"."+durable+".>") + if h.LastPerSubject { + // A stream kept last per subject is read whole at each start through an ordered consumer, made for that one read + // and with no durable name: its creation, its next message, its info and the deletion of its own (design 47 G §556, A-4). + out = append(out, + "$JS.API.CONSUMER.CREATE."+h.Stream, "$JS.API.CONSUMER.CREATE."+h.Stream+".>", + "$JS.API.CONSUMER.MSG.NEXT."+h.Stream+".*", "$JS.API.CONSUMER.INFO."+h.Stream+".*", + "$JS.API.CONSUMER.DELETE."+h.Stream+".*") + } } return out } diff --git a/modules/mesh-grants/internal/buscompose/orderedread_test.go b/modules/mesh-grants/internal/buscompose/orderedread_test.go new file mode 100644 index 00000000..fc61c48f --- /dev/null +++ b/modules/mesh-grants/internal/buscompose/orderedread_test.go @@ -0,0 +1,23 @@ +package buscompose + +import ( + "slices" + "testing" +) + +// A reader of a stream kept last per subject is granted what an ordered consumer of that stream uses, and a reader of +// another stream only its own durable (design 47 G §556, A-4). +func TestAReaderOfAStreamKeptLastPerSubjectIsGrantedItsOrderedConsumer(t *testing.T) { + p := Principal{Module: "m", Node: "a"} + ordered := []string{"$JS.API.CONSUMER.CREATE.S", "$JS.API.CONSUMER.MSG.NEXT.S.*", "$JS.API.CONSUMER.INFO.S.*", "$JS.API.CONSUMER.DELETE.S.*"} + last := heardGrants(p, []Heard{{Stream: "S", Filters: []string{"f"}, LastPerSubject: true}}) + for _, w := range ordered { + if !slices.Contains(last, w) { + t.Errorf("a last-per-subject reader is not granted %s: %v", w, last) + } + } + plain := heardGrants(p, []Heard{{Stream: "S", Filters: []string{"f"}}}) + if slices.Contains(plain, ordered[0]) { + t.Errorf("a reader of another stream is granted an ordered consumer: %v", plain) + } +} diff --git a/modules/mesh-grants/internal/grants/defined_test.go b/modules/mesh-grants/internal/grants/defined_test.go new file mode 100644 index 00000000..aafa7126 --- /dev/null +++ b/modules/mesh-grants/internal/grants/defined_test.go @@ -0,0 +1,27 @@ +package grants + +import ( + "slices" + "testing" + + "git.novox.be/novox/mesh-sdk/go/catalogue" +) + +// Design 47 G §386, §474, §644: a `*` emitter before one of mesh-sdk's finding events reaches each declaring module's own +// stream, with no seat list read; one before an event no definition names stays the shared stream's. +func TestAStarEmitterBeforeAFindingEventReachesEachDeclaringStream(t *testing.T) { + shelf := map[string]catalogue.Manifest{ + "a": {Module: "a", Streams: []catalogue.StreamDeclaration{{Name: "a-findings", Events: []string{"finding-written"}}}}, + "b": {Module: "b", Streams: []catalogue.StreamDeclaration{{Name: "b-usage", Events: []string{"usage"}}}}, + } + none := func(string, string) []any { return nil } + defined := func(e string) bool { return definedEventsOf(nil)[e] } + keeper := catalogue.Manifest{Module: "keeper", Consumes: []string{"*.finding-written", "*.usage"}} + hears, touches, onEvents := hearsOf(keeper, shelf, "ace", none, keeper.Consumes, defined) + if !touches || len(hears) != 1 || hears[0].Emitter != "a" || !slices.Equal(onEvents, []string{"*.finding-written", "*.usage"}) { + t.Fatalf("heard %+v (touches %v, on EVENTS %v)", hears, touches, onEvents) + } + if hears, _, _ := hearsOf(keeper, shelf, "ace", none, keeper.Consumes, nil); len(hears) != 0 { + t.Fatalf("with no event defined, heard %+v", hears) + } +} diff --git a/modules/mesh-grants/internal/grants/firstviews.go b/modules/mesh-grants/internal/grants/firstviews.go index 77bd2818..611cad1d 100644 --- a/modules/mesh-grants/internal/grants/firstviews.go +++ b/modules/mesh-grants/internal/grants/firstviews.go @@ -397,12 +397,14 @@ type FirstViewsState struct { // Bindings is the first view of the bindings, asked of the seat mesh-broker's list, beside the others (design 25 // bindings-first-view §6); absent where the part's process holds none. Bindings *BindingsStatus `json:"bindings,omitempty"` + // Streams are the whole reads of streams kept last per subject at the part's start, `waiting` until each ends (design 47 G §556). + Streams []StreamRead `json:"streams,omitempty"` } // sayFirstViews keeps the first views' statuses in the part's own state (for grants_first_views) when they change, and // raises or clears FirstViewEmpty for each answered at revision 0. Each pass calls it; nil Views is none. func (p *Part) sayFirstViews(res *Result) { - if p.Views == nil && p.Bindings == nil { + if p.Views == nil && p.Bindings == nil && len(p.StreamReads()) == 0 { return } state := FirstViewsState{V: 1, Views: []views.Status{}} @@ -418,6 +420,7 @@ func (p *Part) sayFirstViews(res *Result) { b.Asked, b.Answered = b.Asked.Truncate(time.Second), b.Answered.Truncate(time.Second) state.Bindings = &b } + state.Streams = p.StreamReads() data, _ := json.Marshal(state) p.changed(res, StateUserList, KeyFirstViews, data) if p.Views == nil { @@ -458,7 +461,7 @@ func (p *Part) FirstViewsOf() (any, error) { if err := json.Unmarshal(raw, &st); err != nil { return nil, fmt.Errorf("its own %s %s does not read: %w", StateUserList, KeyFirstViews, err) } - return map[string]any{"views": st.Views, "bindings": st.Bindings, "revision": rev, "first-views": FirstViews, + return map[string]any{"views": st.Views, "bindings": st.Bindings, "streams": st.Streams, "revision": rev, "first-views": FirstViews, "bindings-first-view": map[string]string{"seat": BrokerSeat, "verb": BrokerListVerb}}, nil } diff --git a/modules/mesh-grants/internal/grants/grants.go b/modules/mesh-grants/internal/grants/grants.go index 96eee602..3ec1411e 100644 --- a/modules/mesh-grants/internal/grants/grants.go +++ b/modules/mesh-grants/internal/grants/grants.go @@ -424,6 +424,7 @@ func (p *Part) writeGrants(res *Result, in Inputs, recs buscompose.Records, comp done := &GrantsWritten{Wanted: len(want), Missing: MissingGrants(in, want, drop, skip)} res.Grants = done p.sayMissing(done.Missing) + p.settleWaits(res, in, done.Missing) byUser := map[string]User{} for _, u := range composed { byUser[u.User] = u diff --git a/modules/mesh-grants/internal/grants/inputs.go b/modules/mesh-grants/internal/grants/inputs.go index 4904bb14..9dce0414 100644 --- a/modules/mesh-grants/internal/grants/inputs.go +++ b/modules/mesh-grants/internal/grants/inputs.go @@ -158,6 +158,10 @@ type Inputs struct { // Ran is the manifest of the digest each node-engine says it runs, by `.` (running.go): what a seat's // holder is read from. A node that said nothing has none, and its module is read from the trunk's manifest. Ran map[string]catalogue.Manifest + // Heard is what each node-engine's `running` said of each `.`: a fingerprint, or stopped (design 47 G §404, + // §459); a key absent was not heard since the part's consumer began. RanByFingerprint is the manifest of each fingerprint heard. + Heard map[string]catalogue.Heard + RanByFingerprint map[string]catalogue.Manifest // Had is the manifest of the build each machine runs now (its have's fingerprint, the builder's build of it), by // `.`; the want's Running may already be a newer build. A membership is composed from both and the trunk's. Had map[string]catalogue.Manifest @@ -186,6 +190,9 @@ type Inputs struct { // EventSubjects are, by seat, the subjects of its events that carry parts, by the event's local name, as the definitions // give them: where a node-scoped seat's event names its machine (buscompose.Seat.EventSubjects). EventSubjects map[string]map[string]string + // Defined are the events a seat definition of the seat list defines, by local name, and mesh-sdk's finding events: the + // events a `*` emitter before them reaches each declaring module's own stream for (design 47 G §386, §474, §644). + Defined map[string]bool // SeatListUnread says the seat list has not been read (the gate says so, seatlist.Reader.MayAct with no seat): only the // bootstrapped seats compose, so the pass keeps what the bus loaded (keeploaded.go). SeatListUnread bool @@ -349,9 +356,11 @@ func ReadInputs(r Reader, cache *Manifests) Inputs { NoFingerprint: map[string]string{}, Running: map[string]catalogue.Manifest{}, Had: map[string]catalogue.Manifest{}, HadFailed: map[string]string{}, Values: map[string]any{}, Gaps: append([]Gap(nil), standingGaps...)} in.SeatListUnread = gate != nil && !gate.MayAct() + in.Defined = definedEventsOf(nil) if d, ok := gate.(SeatDefinitions); ok && !in.SeatListUnread { in.Kept = buscompose.KeptEventsOf(d.Definitions()) in.EventSubjects = eventSubjectsOf(d.Definitions()) + in.Defined = definedEventsOf(d.Definitions()) } nodes := map[string]bool{} // **The seat's assignments alone places modules** (novox/hq ADR 0549 §5, ADR 0567 §9; issue 774): the controller's diff --git a/modules/mesh-grants/internal/grants/kept.go b/modules/mesh-grants/internal/grants/kept.go index 4f320bc5..9c0a03ad 100644 --- a/modules/mesh-grants/internal/grants/kept.go +++ b/modules/mesh-grants/internal/grants/kept.go @@ -4,8 +4,10 @@ import ( "errors" "fmt" "slices" + "strings" "git.novox.be/novox/mesh-sdk/go/seatdef" + "git.novox.be/novox/mesh-sdk/go/views" "mesh-grants/internal/buscompose" ) @@ -103,6 +105,23 @@ func eventSubjectsOf(defs map[string]seatdef.Definition) map[string]map[string]s return out } +// definedEventsOf is the events a `*` emitter before them may reach (catalogue.Hearing's defined, design 47 G §386, §474, +// §644): each event, by its local name, of a seat definition of the seat list, and mesh-sdk's four finding events, which +// views.FindingSubjects names and which are defined with or without the list read. +func definedEventsOf(defs map[string]seatdef.Definition) map[string]bool { + out := map[string]bool{} + for _, d := range defs { + for _, e := range d.Events { + out[e.Local()] = true + } + } + s := views.FindingSubjects("module", "node") + for _, subject := range []string{s.Written, s.Cleared, s.Stated, s.Asked} { + out[strings.TrimSuffix(strings.TrimPrefix(subject, "mesh.stream.module.event."), ".node")] = true + } + return out +} + // withEventSubjects gives each seat a declaration holds or watches the subjects of its events (machineEvent). func withEventSubjects(subjects map[string]map[string]string, d *buscompose.Declared) { if len(subjects) == 0 { diff --git a/modules/mesh-grants/internal/grants/part.go b/modules/mesh-grants/internal/grants/part.go index 85f9b9fa..f2c9bf77 100644 --- a/modules/mesh-grants/internal/grants/part.go +++ b/modules/mesh-grants/internal/grants/part.go @@ -62,6 +62,8 @@ type Store interface { // Emitter says one of the part's events. type Emitter interface { Emit(event string, body any) error + // EmitSeat says an event of a seat the module holds, on mesh.seat..event. (design 47 G A-10). + EmitSeat(seat, event string, body any) error } // UserListState is the value of `user-list`: the list the grants part composed (users and grants, no hashes), @@ -220,6 +222,10 @@ type Part struct { Bindings *BindingsView // bindMu orders the writes of the kept bindings: an event's and a first view's answer (bindings.go). bindMu sync.Mutex + // runningRead is the whole read of the stream running at the start (running.go), guarded by mu. + runningRead *StreamRead + // firstPass is when this version's first pass began (waits.go), guarded by mu. + firstPass time.Time } // keepBrokers keeps the modules whose manifest claims the seat mesh-broker: the only emitters whose created, recreated diff --git a/modules/mesh-grants/internal/grants/records.go b/modules/mesh-grants/internal/grants/records.go index c20ef223..15e0fc29 100644 --- a/modules/mesh-grants/internal/grants/records.go +++ b/modules/mesh-grants/internal/grants/records.go @@ -87,6 +87,7 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) { continue } declare := func(m catalogue.Manifest) buscompose.Declared { + m.Consumes = resolveSeatViews(m.Consumes, holders) d := declaredFor(m, seats, declarers) if len(in.Placed) > 0 { d.Holds = heldWherePlaced(d.Holds, holders, node, m.Module) @@ -94,7 +95,7 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) { for _, sr := range catalogue.ReadsGranted(m, here, node) { d.KeyedReads = append(d.KeyedReads, buscompose.KeyedRead{Read: sr.Read, Key: sr.Key}) } - d.Hears, d.HearsAStream, d.Consumes = hearsOf(m, declared, node, values, d.Consumes) + d.Hears, d.HearsAStream, d.Consumes = hearsOf(m, declared, node, values, d.Consumes, func(event string) bool { return in.Defined[event] }) var keptHeard bool d.Watches, d.Consumes, d.Hears, keptHeard = keptOutOfHearing(in.Kept, d.Watches, d.Consumes, d.Hears) d.HearsAStream = d.HearsAStream || keptHeard @@ -178,6 +179,39 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio return d } +// seatViewConsume is a `consumes` entry naming a seat's view as `seat:.views.` (design 47 G §616). +const seatViewConsume = "seat:" + +// resolveSeatViews resolves each `seat:.views.` of a module's consumes to `.views.`, the module +// holding the seat on record, as it resolves a seat's events: a new holder is granted with no change of the manifest (design +// 47 G §616). An entry whose seat has no holder on record stays as written, and grants nothing. Pure. +func resolveSeatViews(consumes []string, holders []catalogue.Held) []string { + var out []string + for i, c := range consumes { + rest, isSeat := strings.CutPrefix(c, seatViewConsume) + seatName, view, named := strings.Cut(rest, ".views.") + if !isSeat || !named || view == "" { + if out != nil { + out = append(out, c) + } + continue + } + if out == nil { + out = slices.Clone(consumes[:i]) + } + holder := slices.IndexFunc(holders, func(h catalogue.Held) bool { return sameSeat(h.Claim, seatName) }) + if holder < 0 { + out = append(out, c) + continue + } + out = append(out, holders[holder].Module+".views."+view) + } + if out == nil { + return consumes + } + return out +} + // consumedOf splits what a manifest consumes as the composer grants it: a seat's event on the seat's own subject (its // watches), every other by its emitter's (novox/hq ADR 0118). A placed module and the node-engine's own manifest are split // alike. @@ -423,10 +457,10 @@ func processesOf(m catalogue.Manifest) []buscompose.ProcessPrincipal { } func hearsOf(m catalogue.Manifest, declared map[string]catalogue.Manifest, node string, values func(provider, setting string) []any, - consumes []string) ([]buscompose.Heard, bool, []string) { + consumes []string, defined func(event string) bool) ([]buscompose.Heard, bool, []string) { reading := m reading.Consumes = consumes - parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values) + parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values, defined) var out []buscompose.Heard for _, p := range parts { h := buscompose.Heard{Stream: p.Stream.BusName(), Emitter: p.Emitter, Restricted: p.Stream.Grant != nil} @@ -456,20 +490,14 @@ func holdersAfterPass(in Inputs) ([]catalogue.Held, []Gap) { var assignments []catalogue.Assignment for _, node := range slices.Sorted(maps.Keys(in.Assigned)) { for _, module := range in.Assigned[node] { - m, ok := in.Ran[node+"."+module] - if !ok { - m, ok = in.Manifests[module] - } - if !ok { - m, ok = in.Held[module] - } - if !ok { - m = catalogue.Manifest{Module: module} - } - assignments = append(assignments, catalogue.Assignment{Node: node, Manifest: m, Unread: !ok}) + assignments = append(assignments, catalogue.Assignment{Node: node, Module: module}) } } - passes, said := catalogue.SeatsToPassOn(held, assignments) + heard := func(node, module string) (catalogue.Heard, bool) { + h, ok := in.Heard[node+"."+module] + return h, ok + } + passes, said := catalogue.SeatsToPassOn(held, assignments, heard, ranEntries{in}) var gaps []Gap for _, p := range passes { held = slices.DeleteFunc(held, func(h catalogue.Held) bool { return h.Kind == p.From.Kind && sameSeat(h.Claim, p.Seat.Name) }) @@ -485,6 +513,23 @@ func holdersAfterPass(in Inputs) ([]catalogue.Held, []Gap) { return held, gaps } +// ranEntries is the reader of entries SeatsToPassOn takes (design 47 G §459): the manifest of a fingerprint a node-engine +// said it runs, and a module's manifest where none was heard: the trunk's, else the running build of a held module. +type ranEntries struct{ in Inputs } + +func (r ranEntries) ByFingerprint(fingerprint string) (catalogue.Manifest, bool) { + m, ok := r.in.RanByFingerprint[fingerprint] + return m, ok +} + +func (r ranEntries) OnBranch(module, _ string) (catalogue.Manifest, bool) { + if m, ok := r.in.Manifests[module]; ok { + return m, true + } + m, ok := r.in.Held[module] + return m, ok +} + // heldWherePlaced is a module's holds on a node as the catalogue's assignments says them (ADR 0549 §1, §3). The assignments' // holds are the holders on record, as catalogue.World's Holdings are, after the passes of holdersAfterPass: a seat held // once for the mesh that some node's assignments holds is held only where assignments names it (this node's naming this diff --git a/modules/mesh-grants/internal/grants/running.go b/modules/mesh-grants/internal/grants/running.go index 8cda4a51..5d21e384 100644 --- a/modules/mesh-grants/internal/grants/running.go +++ b/modules/mesh-grants/internal/grants/running.go @@ -6,6 +6,7 @@ import ( "fmt" "sort" "strings" + "time" "git.novox.be/novox/mesh-contracts/go/seats/nodeengine" "git.novox.be/novox/mesh-sdk/go/catalogue" @@ -30,7 +31,8 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error if err := json.Unmarshal(data, &r); err != nil { return false, fmt.Errorf("%s is not a running body: %w", subject, err) } - if r.Node == "" || r.Module == "" || r.Manifest == "" { + // A `running` with stopped carries no fingerprint and no manifest (design 47 G §404, §365): the have no longer holds the module. + if r.Node == "" || r.Module == "" || (r.Manifest == "" && !r.Stopped) { return false, fmt.Errorf("%s names no node, module or manifest digest", subject) } if !strings.HasSuffix(subject, "."+RunningKey(r.Node, r.Module)) { @@ -43,7 +45,11 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error } if found { var w nodeengine.RunningEvent - if json.Unmarshal(was, &w) == nil && w.Manifest == r.Manifest && w.Fingerprint == r.Fingerprint { + // An event older by `at` than what the part holds changes nothing: a node's module's newer one stands (design 47 G §556). + if json.Unmarshal(was, &w) == nil && r.At.Before(w.At) { + return false, nil + } + if json.Unmarshal(was, &w) == nil && w.Manifest == r.Manifest && w.Fingerprint == r.Fingerprint && w.Stopped == r.Stopped { return false, nil } } @@ -53,10 +59,57 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error return true, nil } +// StreamRead is the part's whole read of a stream kept last per subject at its start (design 47 G §556): through an ordered +// consumer made for that one read, every subject's last message, before its durable consumer is followed. Until it ends the +// part acts on none of the stream's events, and `grants_first_views` names the stream `waiting`. +type StreamRead struct { + Stream string `json:"stream"` + // State is `waiting` until the read ends, then `read`. + State string `json:"state"` + Since time.Time `json:"since"` +} + +// ReadingRunning begins the whole read of the node-engine's stream running at the part's start; the part acts on none of +// `running` until RunningRead ends it. +func (p *Part) ReadingRunning(stream string) { + p.mu.Lock() + defer p.mu.Unlock() + p.runningRead = &StreamRead{Stream: stream, State: "waiting", Since: p.now()} +} + +// RunningRead ends the whole read: the part acts on `running` from the next pass. +func (p *Part) RunningRead() { + p.mu.Lock() + defer p.mu.Unlock() + if p.runningRead != nil { + p.runningRead.State = "read" + } +} + +// StreamReads are the whole reads the part makes at its start, with their state, for `grants_first_views`. +func (p *Part) StreamReads() []StreamRead { + p.mu.Lock() + defer p.mu.Unlock() + if p.runningRead == nil { + return nil + } + r := *p.runningRead + r.Since = r.Since.Truncate(time.Second) + return []StreamRead{r} +} + // readRan reads each key of StateRunning and the manifest its digest names (the indexer's, by digest), into in.Ran. A key // whose manifest cannot be read is a gap, and that node's module is read as it was before (the trunk's). func (p *Part) readRan(in *Inputs) { + if reads := p.StreamReads(); len(reads) > 0 && reads[0].State == "waiting" { + // The whole read of `running` has not ended: the part acts on none of it, and keeps the list it has (design 47 G §556). + in.Gaps = append(in.Gaps, Gap{Input: StateRunning, Failed: true, + Why: "the stream " + reads[0].Stream + " is waiting: its whole read at the part's start has not ended"}) + return + } in.Ran = map[string]catalogue.Manifest{} + in.Heard = map[string]catalogue.Heard{} + in.RanByFingerprint = map[string]catalogue.Manifest{} keys, err := p.Store.Keys(StateRunning) if err != nil { in.Gaps = append(in.Gaps, Gap{Input: StateRunning, Why: "its own state cannot be read, so no seat is read from what a node runs: " + err.Error()}) @@ -69,7 +122,15 @@ func (p *Part) readRan(in *Inputs) { continue } var r nodeengine.RunningEvent - if json.Unmarshal(raw, &r) != nil || r.Manifest == "" { + if json.Unmarshal(raw, &r) != nil { + continue + } + if r.Stopped { + // A stopped module is heard as stopped and claims nothing on that node (design 47 G §404, §459). + in.Heard[key] = catalogue.Heard{Stopped: true} + continue + } + if r.Manifest == "" { continue } m, err := p.cache.get(p.Read, r.Manifest) @@ -78,6 +139,8 @@ func (p *Part) readRan(in *Inputs) { continue } in.Ran[key] = m + in.Heard[key] = catalogue.Heard{Fingerprint: r.Fingerprint} + in.RanByFingerprint[r.Fingerprint] = m } } diff --git a/modules/mesh-grants/internal/grants/tools.go b/modules/mesh-grants/internal/grants/tools.go index 07ef30c7..a1589f9f 100644 --- a/modules/mesh-grants/internal/grants/tools.go +++ b/modules/mesh-grants/internal/grants/tools.go @@ -30,6 +30,9 @@ const ( ToolFirstViewAgain = "grants_first_view_again" // ToolRunning reads the state running (running.go). ToolRunning = "grants_running" + // ToolWaits and ToolRelease read and release the granting waits (waits.go). + ToolWaits = "grants_waits" + ToolRelease = "grants_release" // ToolSeatList and ToolSeatListAgain read and read again the seat list the part composes from (mesh-sdk seatlist.Tools). ToolSeatList = "grants_seat_list" ToolSeatListAgain = "grants_seat_list_again" @@ -37,7 +40,7 @@ const ( // Tools is every tool, in the manifest's order. var Tools = []string{ToolGrants, ToolMembership, ToolUserList, ToolComposeNow, ToolAssert, ToolAccounts, ToolConsumerMatch, - ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolSeatList, ToolSeatListAgain} + ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolWaits, ToolRelease, ToolSeatList, ToolSeatListAgain} // WritesGrants is what grants says of the part's own grants: written once the list the bus loaded carries a build's // accounts, and the one key the assigner reads (ADR 0571 clause 9, which changes ADR 0547 clause 5). diff --git a/modules/mesh-grants/internal/grants/waits.go b/modules/mesh-grants/internal/grants/waits.go new file mode 100644 index 00000000..7b6417f2 --- /dev/null +++ b/modules/mesh-grants/internal/grants/waits.go @@ -0,0 +1,191 @@ +package grants + +import ( + "encoding/json" + "errors" + "fmt" + "sort" + "strings" + "time" + + "git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants" +) + +// **The granting wait** (design 47 G §276, §266, §269; G-20 A-7). The grants part holds the entries of a revision whose +// accounts its new version has not yet composed: each module the pass leaves without a grant (MissingGrants) is one held +// entry, kept in the part's own state on the bus under KeyWaits. The bound's clock, `clock-from`, is the start of this +// version's first pass, which the part knows itself, so it hears no `build.ended`; the bound is GrantingBound, a constant of +// the part. A held entry ends when its grant is there (`ran`) or when a person releases it (`released`). + +// KeyWaits is the key of the part's own state user-list where it keeps the granting waits. +const KeyWaits = "waits" + +// GrantingBound is §266's bound of the granting step. +const GrantingBound = 10 * time.Minute + +// HeldWait is one granting wait as the part keeps it. +type HeldWait struct { + meshgrants.Wait + // Released says a person released the entry (grants_release): it is held no more. + Released bool `json:"released,omitempty"` + // Ended says wait-ended was said for the release: a released entry is said ended once. + Ended bool `json:"ended,omitempty"` +} + +// WaitsState is the value of KeyWaits, by the held module. +type WaitsState struct { + V int `json:"v"` + Waits map[string]HeldWait `json:"waits"` +} + +func (p *Part) readWaits() (WaitsState, error) { + st := WaitsState{V: 1, Waits: map[string]HeldWait{}} + raw, _, found, err := p.Store.Get(StateUserList, KeyWaits) + if err != nil { + return st, fmt.Errorf("its own %s %s cannot be read: %w", StateUserList, KeyWaits, err) + } + if found { + if err := json.Unmarshal(raw, &st); err != nil { + return st, fmt.Errorf("its own %s %s does not read: %w", StateUserList, KeyWaits, err) + } + if st.Waits == nil { + st.Waits = map[string]HeldWait{} + } + } + return st, nil +} + +// settleWaits keeps the granting waits of this pass: a module left without a grant is a held entry, begun at this pass; one +// that has its grant is ended as `ran`. A released entry stays released while it is still left without one. +func (p *Part) settleWaits(res *Result, in Inputs, missing []string) { + if p.Store == nil { + return + } + now := p.now() + p.mu.Lock() + if p.firstPass.IsZero() { + p.firstPass = now + } + clock := p.firstPass + p.mu.Unlock() + st, err := p.readWaits() + if err != nil { + res.Errors = append(res.Errors, err.Error()) + return + } + held := map[string]bool{} + for _, m := range missing { + module, _, _ := strings.Cut(m, ": ") + held[module] = true + } + changed := false + say := func(event string, w meshgrants.Wait) bool { + if p.Emit == nil { + return true + } + if err := p.Emit.EmitSeat(meshgrants.Seat, event, w); err != nil { + res.Errors = append(res.Errors, fmt.Sprintf("the seat event %s of %s could not be said: %v", event, w.Module, err)) + return false + } + return true + } + for _, module := range sortedKeys(held) { + if _, ok := st.Waits[module]; ok { + continue + } + w := HeldWait{Wait: meshgrants.Wait{Bound: GrantingBound.String(), ClockFrom: clock, Fp: in.Fingerprints[module], + Module: module, Part: "mesh-grants", Since: now, Step: meshgrants.WaitStepGrant, Version: in.Fingerprints["mesh-grants"]}} + if !say(meshgrants.EventWaitHeld, w.Wait) { + continue + } + st.Waits[module] = w + changed = true + } + for _, module := range sortedKeys(st.Waits) { + w := st.Waits[module] + switch { + case w.Released && !w.Ended: + // A-12: the released entry goes on, the wait is said ended `released`, and nothing is raised late for it. + ended := w.Wait + ended.How = meshgrants.WaitHowReleased + if say(meshgrants.EventWaitEnded, ended) { + w.Ended = true + st.Waits[module] = w + changed = true + } + case !held[module]: + if !w.Released { + ended := w.Wait + ended.How = meshgrants.WaitHowRan + if !say(meshgrants.EventWaitEnded, ended) { + continue + } + } + delete(st.Waits, module) + changed = true + } + } + if !changed { + return + } + data, _ := json.Marshal(st) + p.changed(res, StateUserList, KeyWaits, data) +} + +// WaitsSaid is what the tool grants_waits answers: each held granting wait, and which have passed their bound. +type WaitsSaid struct { + Waits []HeldWait `json:"waits"` + // Late is the held entries whose bound, counted from clock-from, has passed. + Late []string `json:"late,omitempty"` +} + +// WaitsOf reads the granting waits (grants_waits). +func (p *Part) WaitsOf() (any, error) { + st, err := p.readWaits() + if err != nil { + return nil, err + } + out := WaitsSaid{Waits: []HeldWait{}} + for _, module := range sortedKeys(st.Waits) { + w := st.Waits[module] + out.Waits = append(out.Waits, w) + if !w.Released && !w.ClockFrom.Add(GrantingBound).After(p.now()) { + out.Late = append(out.Late, module) + } + } + sort.Strings(out.Late) + return out, nil +} + +// ReleaseWait releases one held entry by a person's act with why, recorded as a hand act through record (the seat +// mesh-hand-acts) before anything is changed (grants_release). +func (p *Part) ReleaseWait(caller, module, why string, record func(what, why string) error) (any, error) { + if strings.TrimSpace(why) == "" { + return nil, errors.New("grants_release needs why: it is recorded as a hand act") + } + st, err := p.readWaits() + if err != nil { + return nil, err + } + w, ok := st.Waits[module] + if !ok { + return nil, fmt.Errorf("the grants part holds no granting wait for %q: grants_waits lists them", module) + } + if record != nil { + if err := record("grants_release "+module, why); err != nil { + return nil, fmt.Errorf("the hand act could not be recorded, so nothing was released: %w", err) + } + } + w.Released, w.By, w.How = true, caller+": "+why, meshgrants.WaitHowReleased + st.Waits[module] = w + data, _ := json.Marshal(st) + if _, err := p.Store.Put(StateUserList, KeyWaits, data); err != nil { + return nil, fmt.Errorf("the release could not be kept: %w", err) + } + // The part's process says wait-ended at the pass this ask makes (only it holds the grant to publish a seat's event). + ask, _ := json.Marshal(Ask{By: caller, At: p.now()}) + if _, err := p.Store.Put(StateUserList, KeyAsked, ask); err != nil { + return nil, fmt.Errorf("the release was kept, but the ask to compose could not be written: %w", err) + } + return map[string]any{"released": module, "by": w.By}, nil +} diff --git a/modules/mesh-grants/module.json b/modules/mesh-grants/module.json index 6443652e..6d9865eb 100644 --- a/modules/mesh-grants/module.json +++ b/modules/mesh-grants/module.json @@ -63,6 +63,8 @@ "grants_first_views", "grants_first_view_again", "grants_running", + "grants_waits", + "grants_release", "grants_seat_list", "grants_seat_list_again" ],