From a559b0e7c981dc656c80508ed44c0bf011713448 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 23:23:04 +0100 Subject: [PATCH] D1b: the two seats' work queues carry their settings, derived once in mesh-sdk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mesh-builds' and mesh-wants' accepted kind step names max-age 24h, max-msgs 10,000, ack-wait 60s, in-progress 20s, max-ack-pending 1,000, max-deliveries 5 and a duplicates window of 2m; the grants part makes each seat's ask stream through mesh-sdk's buscompose.SeatQueue and says a seat whose settings it refuses, and its own copy of the derivation goes. Builds: design 47 H2 §777; H-A-350 DMC-1, H-A-362 --- .../seats/mesh-builds/seat.json | 9 +- .../seats/mesh-wants/seat.json | 9 +- .../internal/buscompose/derived.go | 84 ++++--------------- .../mesh-grants/internal/buscompose/kept.go | 38 +++++---- .../internal/grants/askstreams_test.go | 15 +++- modules/mesh-grants/internal/grants/inputs.go | 6 +- 6 files changed, 73 insertions(+), 88 deletions(-) diff --git a/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json b/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json index 311c58e46..3ed175a97 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-builds/seat.json @@ -159,7 +159,14 @@ "name": "step", "body": { "$ref": "#/defs/StepRun" - } + }, + "max-age": "24h", + "max-msgs": 10000, + "ack-wait": "60s", + "in-progress": "20s", + "max-ack-pending": 1000, + "max-deliveries": 5, + "duplicates-window": "2m" } ], "events": [ diff --git a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json index 69c859799..e13f7058b 100644 --- a/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json +++ b/modules/mesh-delivery-contracts/seats/mesh-wants/seat.json @@ -314,7 +314,14 @@ "name": "step", "body": { "$ref": "#/defs/StepRun" - } + }, + "max-age": "24h", + "max-msgs": 10000, + "ack-wait": "60s", + "in-progress": "20s", + "max-ack-pending": 1000, + "max-deliveries": 5, + "duplicates-window": "2m" } ], "events": [ diff --git a/modules/mesh-grants/internal/buscompose/derived.go b/modules/mesh-grants/internal/buscompose/derived.go index d0772c425..10fd80821 100644 --- a/modules/mesh-grants/internal/buscompose/derived.go +++ b/modules/mesh-grants/internal/buscompose/derived.go @@ -5,6 +5,9 @@ import ( "slices" "sort" "strings" + + sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose" + "git.novox.be/novox/mesh-sdk/go/seatdef" ) // Streams and consumers derived from what modules declare. @@ -76,39 +79,11 @@ type Consumer struct { // is the whole reason a caller addresses a seat instead of a module. func seatStreamName(seat string) string { return "SEAT_" + upperSnake(seat) } -// SeatStreams is one work queue per declared seat, created when the declaring module is -// registered rather than when it is assigned. -// -// **The stream exists before anyone holds the seat, and that is the point.** Work queues until a -// holder appears, so installing the telegram module a week after something started sending to it -// flushes the backlog instead of having lost it. A stream created at assignment would make "the -// holder is not here yet" mean "your messages are gone". -func SeatStreams(seats []DeclaredSeat) []Stream { - sorted := append([]DeclaredSeat(nil), seats...) - sort.Slice(sorted, func(i, j int) bool { return sorted[i].Name < sorted[j].Name }) - - var out []Stream - for _, s := range sorted { - if len(s.Accepts) == 0 { - // A seat that only emits and serves needs no stream: its events ride EVENTS and its - // tools are core request/reply, which is never persisted. - continue - } - retain := s.RetainSeconds - if retain == 0 { - retain = 7 * 24 * 60 * 60 - } - out = append(out, Stream{ - Name: seatStreamName(s.Name), - Subjects: []string{"mesh.seat." + s.Name + ".accept.>"}, - Retention: RetentionWorkQueue, - MaxAge: retain, - Why: fmt.Sprintf("work submitted to the %s seat; one holder consumes it, and it "+ - "queues while nobody does", s.Name), - }) - } - return out -} +// A seat's work queue and its one shared worker are derived once, by mesh-sdk's buscompose.SeatQueue, from its accepted +// kinds' work-queue settings (design 47 H2 §777; H-A-350 DMC-1, H-A-362): the grants part keeps no copy of that +// derivation. **The stream exists before anyone holds the seat, and that is the point.** Work queues until a holder +// appears, so installing the telegram module a week after something started sending to it flushes the backlog instead +// of having lost it. // A DeclaredSeat is a seat as the catalogue knows it. Mirrored here rather than imported so this // package stays free of the catalogue's own types — the same reason the host mirrors the @@ -327,38 +302,6 @@ func AccountConsumers(users []Principal) []ModuleConsumer { return out } -// HolderConsumerFor is the worker a seat's holders share on that seat's work queue. -// -// **One worker for every holder, and each holder pulls one ask when it is idle** (novox/hq ADR -// 0190). The seat is *authority* — who may be the telegram sender — and the worker is *delivery*, -// kept separate so that relaxing one changes nothing about the other: a node-scoped seat has a -// holder per machine, and all of them take from this one consumer, so the work is shared without -// any holder knowing about the others. Pulled rather than pushed because a push consumer hands the -// next ask to whichever subscriber the server picks, busy or not, and a pulled one is asked for by -// a holder that has just become free. Which is also what ends the race issue 186 describes — asks -// delivered behind the one being worked, expiring unacknowledged and dropped after the fifth -// redelivery: nothing is delivered that nobody asked for. A long build keeps its own ask alive -// (stillWorking); the ack wait is for a holder that died. -func HolderConsumerFor(node, module string, seat DeclaredSeat) (Consumer, bool) { - if len(seat.Accepts) == 0 || seat.PulledByKind { - // A seat pulled by kind has a worker per kind, which its holders' seat traffic derives (SeatTrafficObjects): one - // worker filtered on every accept would overlap them on the work queue. - return Consumer{}, false - } - return Consumer{ - Name: "SEAT_" + upperSnake(seat.Name) + "_worker", - Stream: seatStreamName(seat.Name), - Filters: []string{"mesh.seat." + seat.Name + ".accept.>"}, - AckWaitSeconds: 60, - MaxDeliver: 5, - // As many in flight as there are holders working, which pulling bounds by itself: a holder - // fetches one and fetches again only after it acknowledged. The server's default stands. - Why: fmt.Sprintf("%s on %s holds %s; every holder pulls one ask at a time from this worker "+ - "and acknowledges after the work is done, so a crash mid-work redelivers rather than "+ - "loses and an idle holder is the one that takes the next ask", module, node, seat.Name), - }, true -} - // NodeConsumer is the durable consumer a node reads its own declaration through. // // **Derived from a node existing, and created by the controller, because a host cannot create it.** @@ -391,7 +334,16 @@ func NodeConsumer(node string) Consumer { // "subjects overlap with an existing stream"), so this is not a subtle divergence — it is a // registration that fails. Catching it here names both streams, before a half-applied mesh does. func AllOverlaps(seats []DeclaredSeat) []string { - all := append(MeshStreams(), SeatStreams(seats)...) + all := MeshStreams() + for _, s := range seats { + accepts := make([]seatdef.Message, 0, len(s.Accepts)) + for _, a := range s.Accepts { + accepts = append(accepts, seatdef.Message{Name: a}) + } + if st, _, ok, err := sdkbc.SeatQueue(s.Name, accepts); err == nil && ok { + all = append(all, Stream{Name: st.Name, Subjects: st.Subjects}) + } + } seen := map[string]string{} var clashes []string for _, s := range all { diff --git a/modules/mesh-grants/internal/buscompose/kept.go b/modules/mesh-grants/internal/buscompose/kept.go index 3734f6f97..83e22eb59 100644 --- a/modules/mesh-grants/internal/buscompose/kept.go +++ b/modules/mesh-grants/internal/buscompose/kept.go @@ -1,6 +1,7 @@ package buscompose import ( + "maps" "slices" "sort" "strings" @@ -8,6 +9,7 @@ import ( "github.com/nats-io/nats.go/jetstream" + sdkbc "git.novox.be/novox/mesh-sdk/go/buscompose" "git.novox.be/novox/mesh-sdk/go/seatdef" ) @@ -125,27 +127,31 @@ func SplitKept(kept []KeptEvent, consumes []string) (rest []string, hears []Hear return rest, hears } -// AskStreamsOf is the work-queue stream of each seat of the seat list that accepts work (SeatStreams' rule, design 47 G §544): -// `SEAT_` on `mesh.seat..accept.>`, kept seven days, so an ask is held until one holder takes it, and a JetStream -// publish of an ask is answered by the bus. Before G the controller made these; a seat whose queues came with G (mesh-builds, -// mesh-wants) had none, so every ask to it timed out unanswered (lead-47, 2026-11-15). Sorted by stream. -func AskStreamsOf(defs map[string]seatdef.Definition) []jetstream.StreamConfig { - var seats []DeclaredSeat - for _, d := range defs { +// AskStreamsOf is the work-queue stream of each seat of the seat list that accepts work, as mesh-sdk's buscompose.SeatQueue +// derives it from the seat's accepted kinds' settings (design 47 H2 §777; H-A-362): `SEAT_` on +// `mesh.seat..accept.>`, its max-age, max-msgs and duplicates window, so an ask is held until one holder takes it, and +// a JetStream publish of an ask is answered by the bus. Before G the controller made these; a seat whose queues came with G +// (mesh-builds, mesh-wants) had none, so every ask to it timed out unanswered (lead-47, 2026-11-15). A seat whose +// settings SeatQueue refuses is named in refused and gets no stream. Sorted by stream. +func AskStreamsOf(defs map[string]seatdef.Definition) (out []jetstream.StreamConfig, refused []string) { + for _, name := range slices.Sorted(maps.Keys(defs)) { + d := defs[name] if len(d.Accepts) == 0 || !safeSubject.MatchString(d.Seat) { continue } - var accepts []string - for _, a := range d.Accepts { - accepts = append(accepts, a.Name) + st, _, ok, err := sdkbc.SeatQueue(d.Seat, d.Accepts) + if err != nil { + refused = append(refused, err.Error()) + continue + } + if !ok { + continue } - seats = append(seats, DeclaredSeat{Name: d.Seat, Accepts: accepts}) - } - var out []jetstream.StreamConfig - for _, st := range SeatStreams(seats) { out = append(out, jetstream.StreamConfig{Name: st.Name, Description: st.Why, Subjects: st.Subjects, Retention: jetstream.WorkQueuePolicy, Storage: jetstream.FileStorage, Replicas: 1, - MaxAge: time.Duration(st.MaxAge) * time.Second}) + MaxAge: time.Duration(st.MaxAge) * time.Second, MaxMsgs: int64(st.MaxMsgs), + Duplicates: time.Duration(st.DuplicatesSeconds) * time.Second}) } - return out + slices.SortFunc(out, func(a, b jetstream.StreamConfig) int { return strings.Compare(a.Name, b.Name) }) + return out, refused } diff --git a/modules/mesh-grants/internal/grants/askstreams_test.go b/modules/mesh-grants/internal/grants/askstreams_test.go index bb070dda6..477ab1fa2 100644 --- a/modules/mesh-grants/internal/grants/askstreams_test.go +++ b/modules/mesh-grants/internal/grants/askstreams_test.go @@ -2,7 +2,9 @@ package grants import ( "slices" + "strings" "testing" + "time" "github.com/nats-io/nats.go/jetstream" @@ -27,17 +29,24 @@ func (c *askCreator) SourceFilter(string, string, string) (string, bool, error) // 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). +// The stream carries the settings the seat's accepted kinds name, derived by mesh-sdk's SeatQueue, and a seat whose settings it +// refuses is said (design 47 H2 §777; H-A-362). func TestEachSeatThatAcceptsWorkHasItsAskStream(t *testing.T) { defs := map[string]seatdef.Definition{ - "mesh-builds": {Seat: "mesh-builds", Accepts: []seatdef.Message{{Name: "step"}}}, + "mesh-builds": {Seat: "mesh-builds", Accepts: []seatdef.Message{{Name: "step", MaxAge: "24h", MaxMsgs: 10000, DuplicatesWindow: "2m"}}}, "mesh-wants": {Seat: "mesh-wants", Accepts: []seatdef.Message{{Name: "step"}}}, "git": {Seat: "git"}, + "two-ways": {Seat: "two-ways", Accepts: []seatdef.Message{{Name: "a", MaxAge: "1h"}, {Name: "b", MaxAge: "2h"}}}, } - asks := buscompose.AskStreamsOf(defs) + asks, refused := buscompose.AskStreamsOf(defs) if len(asks) != 2 || asks[0].Name != "SEAT_MESH_BUILDS" || asks[0].Retention != jetstream.WorkQueuePolicy || - !slices.Equal(asks[0].Subjects, []string{"mesh.seat.mesh-builds.accept.>"}) || asks[0].MaxAge == 0 { + !slices.Equal(asks[0].Subjects, []string{"mesh.seat.mesh-builds.accept.>"}) || asks[0].MaxAge != 24*time.Hour || + asks[0].MaxMsgs != 10000 || asks[0].Duplicates != 2*time.Minute || asks[1].MaxAge != 7*24*time.Hour { t.Fatalf("ask streams = %+v", asks) } + if len(refused) != 1 || !strings.Contains(refused[0], "two-ways") { + t.Errorf("refused = %v, want the seat whose two kinds name two max-ages", refused) + } c := &askCreator{} made, notMade := createAskStreams(c, &creations{}, asks, map[string]Limits{"SEAT_MESH_WANTS": {}}, false) if !slices.Equal(made, []string{"SEAT_MESH_BUILDS"}) || len(notMade) != 0 || diff --git a/modules/mesh-grants/internal/grants/inputs.go b/modules/mesh-grants/internal/grants/inputs.go index 0f1ecdd04..86591945f 100644 --- a/modules/mesh-grants/internal/grants/inputs.go +++ b/modules/mesh-grants/internal/grants/inputs.go @@ -385,7 +385,11 @@ func ReadInputs(r Reader, cache *Manifests) Inputs { // consumer only gains filters, so one made with such an event's subject on EVENTS would keep it). if d, ok := gate.(SeatDefinitions); ok { in.Kept = buscompose.KeptEventsOf(d.Definitions()) - in.AskStreams = buscompose.AskStreamsOf(d.Definitions()) + var refused []string + in.AskStreams, refused = buscompose.AskStreamsOf(d.Definitions()) + for _, why := range refused { + in.Gaps = append(in.Gaps, Gap{Input: "seat work queues", Why: why}) + } in.Chunked = buscompose.ChunkVerbsOf(d.Definitions()) in.EventSubjects = eventSubjectsOf(d.Definitions()) in.Defined = definedEventsOf(d.Definitions())