From 6852228000f08544227d6e4298827b82a24eb16f Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 23:18:34 +0100 Subject: [PATCH] Derive a seat's work queue and its worker from the seat definition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An accepted kind names its work queue's settings (max-age, duplicates-window, ack-wait, in-progress, max-msgs, max-ack-pending, max-deliveries); buscompose.SeatQueue derives the seat's work-queue stream and its one shared worker from them, once, for the grants part to take. Builds: design 47 H2 §777; H-A-350 DMC-1, H-A-362, H-A-340 (1) --- go/buscompose/derived.go | 4 ++ go/buscompose/names_test.go | 19 ++++++++ go/buscompose/seatqueue.go | 97 +++++++++++++++++++++++++++++++++++++ go/buscompose/streams.go | 2 + go/seatdef/seatdef.go | 35 +++++++++++++ go/seatdef/seatdef_test.go | 4 ++ 6 files changed, 161 insertions(+) create mode 100644 go/buscompose/seatqueue.go diff --git a/go/buscompose/derived.go b/go/buscompose/derived.go index 1885a933..b61d3336 100644 --- a/go/buscompose/derived.go +++ b/go/buscompose/derived.go @@ -38,6 +38,10 @@ type Consumer struct { // and a merge that came back rebuilt what it had just built, five times over on 2026-09-30. // With one outstanding, the server holds the rest, and the heartbeat is keeping the message. MaxAckPending int + // InProgressSeconds is how often a holder working a delivery says it is still in progress, so its ack wait does + // not pass while it works (design 47 H2 §777; H-A-340 (1)): the holder's to keep, never sent to the server. Zero + // says nothing. + InProgressSeconds int // FromNow makes a consumer that does not exist yet start at the stream's end rather than its // beginning (novox/hq issue 248). For a consumer that reacts to announcements — a merge, a build's // outcome — on a stream that keeps a week of them: the server's default, everything the stream diff --git a/go/buscompose/names_test.go b/go/buscompose/names_test.go index ba22fde5..75510257 100644 --- a/go/buscompose/names_test.go +++ b/go/buscompose/names_test.go @@ -49,4 +49,23 @@ func TestTheBusNamesAgree(t *testing.T) { t.Errorf("the shared events stream keeps %d s, a seat's definition says %d days", st.MaxAge, seatdef.SharedEventsMaxAgeDays) } } + // Design 47 H2 §777, H-A-362: a seat's work queue and its one worker are derived from its accepted kind's settings; + // absent settings take the defaults, two kinds naming one setting differently are refused, no accept is no queue. + st, w, ok, err := SeatQueue("mesh-builds", []seatdef.Message{{Name: "step", MaxAge: "24h", DuplicatesWindow: "2m", + AckWait: "60s", InProgress: "20s", MaxMsgs: 10000, MaxAckPending: 64, MaxDeliveries: 3}}) + if err != nil || !ok || st.Name != "SEAT_MESH_BUILDS" || st.Retention != RetentionWorkQueue || st.MaxAge != 86400 || + st.MaxMsgs != 10000 || st.DuplicatesSeconds != 120 || st.Subjects[0] != "mesh.seat.mesh-builds.accept.>" || + w.Name != "SEAT_MESH_BUILDS_worker" || w.Stream != st.Name || w.AckWaitSeconds != 60 || w.MaxDeliver != 3 || + w.MaxAckPending != 64 || w.InProgressSeconds != 20 { + t.Errorf("derived %+v and %+v, %v", st, w, err) + } + if st, w, _, _ := SeatQueue("mesh-wants", []seatdef.Message{{Name: "step"}}); st.MaxAge != 7*86400 || w.AckWaitSeconds != 60 || w.MaxDeliver != 5 { + t.Errorf("the defaults: %+v, %+v", st, w) + } + if _, _, _, err := SeatQueue("s", []seatdef.Message{{Name: "a", AckWait: "60s"}, {Name: "b", AckWait: "2m"}}); err == nil { + t.Error("two ack waits for one worker were derived") + } + if _, _, ok, _ := SeatQueue("s", nil); ok { + t.Error("a seat that accepts nothing has a queue") + } } diff --git a/go/buscompose/seatqueue.go b/go/buscompose/seatqueue.go new file mode 100644 index 00000000..be4fdcc7 --- /dev/null +++ b/go/buscompose/seatqueue.go @@ -0,0 +1,97 @@ +package buscompose + +import ( + "fmt" + "strings" + "time" + + "git.novox.be/novox/mesh-sdk/go/seatdef" +) + +// The work queue's settings where a seat's accepted kinds name none: a week of asks, a delivery given up after five +// handings, a minute before an unacknowledged one is handed again. +const ( + SeatQueueDefaultMaxAge = 7 * 24 * time.Hour + SeatQueueDefaultAckWait = time.Minute + SeatQueueDefaultDelivers = 5 +) + +// SeatQueueStreamName is the stream holding a seat's inbound work, named after the seat, never its holder. +func SeatQueueStreamName(seat string) string { return "SEAT_" + seatUpper(seat) } + +// SeatQueueWorkerName is the one worker a seat's holders share on its work queue. +func SeatQueueWorkerName(seat string) string { return "SEAT_" + seatUpper(seat) + "_worker" } + +func seatUpper(seat string) string { + return strings.ToUpper(strings.NewReplacer("-", "_", ".", "_").Replace(seat)) +} + +// SeatQueue derives a seat's work-queue stream and its one shared worker from its accepted kinds' work-queue settings +// (design 47 H2 §777; H-A-350 DMC-1, H-A-362), the one derivation every part takes: max-age, max-msgs and +// duplicates-window bound the stream; ack-wait, max-deliveries, max-ack-pending and in-progress the worker. A setting +// named by two accepted kinds with two values is refused: one stream and one worker carry one value. A seat that +// accepts nothing has no queue (ok false). +func SeatQueue(seat string, accepts []seatdef.Message) (stream Stream, worker Consumer, ok bool, err error) { + if len(accepts) == 0 { + return Stream{}, Consumer{}, false, nil + } + durations := map[string]string{} + counts := map[string]int{} + for _, a := range accepts { + if ps := a.QueueProblems("accepts " + a.Name); len(ps) > 0 { + return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %w", seat, ps) + } + for name, v := range map[string]string{"max-age": a.MaxAge, "duplicates-window": a.DuplicatesWindow, + "ack-wait": a.AckWait, "in-progress": a.InProgress} { + if v == "" { + continue + } + if was, seen := durations[name]; seen && was != v { + return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %s is %s and %s in two accepted kinds", seat, name, was, v) + } + durations[name] = v + } + for name, v := range map[string]int{"max-msgs": a.MaxMsgs, "max-ack-pending": a.MaxAckPending, "max-deliveries": a.MaxDeliveries} { + if v == 0 { + continue + } + if was, seen := counts[name]; seen && was != v { + return Stream{}, Consumer{}, false, fmt.Errorf("the seat %s's work queue: %s is %d and %d in two accepted kinds", seat, name, was, v) + } + counts[name] = v + } + } + seconds := func(name string, def time.Duration) int { + if v, set := durations[name]; set { + d, _ := time.ParseDuration(v) // QueueProblems read it + return int(d / time.Second) + } + return int(def / time.Second) + } + delivers := SeatQueueDefaultDelivers + if v, set := counts["max-deliveries"]; set { + delivers = v + } + subject := "mesh.seat." + seat + ".accept.>" + stream = Stream{ + Name: SeatQueueStreamName(seat), + Subjects: []string{subject}, + Retention: RetentionWorkQueue, + MaxAge: seconds("max-age", SeatQueueDefaultMaxAge), + MaxMsgs: counts["max-msgs"], + DuplicatesSeconds: seconds("duplicates-window", 0), + Why: fmt.Sprintf("work submitted to the %s seat; one holder consumes it, and it queues while nobody does", seat), + } + worker = Consumer{ + Name: SeatQueueWorkerName(seat), + Stream: stream.Name, + Filters: []string{subject}, + AckWaitSeconds: seconds("ack-wait", SeatQueueDefaultAckWait), + MaxDeliver: delivers, + MaxAckPending: counts["max-ack-pending"], + InProgressSeconds: seconds("in-progress", 0), + Why: fmt.Sprintf("every holder of %s pulls its asks from this one worker and acknowledges after the work is "+ + "done, so a crash mid-work redelivers rather than loses", seat), + } + return stream, worker, true, nil +} diff --git a/go/buscompose/streams.go b/go/buscompose/streams.go index 637793d6..627ec0a2 100644 --- a/go/buscompose/streams.go +++ b/go/buscompose/streams.go @@ -32,6 +32,8 @@ type Stream struct { // another's events out of a shared stream. Verified: with a cap of 3, ten messages on one // subject and one on another leave four in the stream, not three. MaxMsgsPerSubject int + // MaxMsgs caps the stream's messages, zero for unbounded: a seat's work queue's max-msgs (design 47 H2 §777). + MaxMsgs int // Why is carried into the assertion so an operator reading the server's own state finds the // reason there, rather than only in a repository they may not have. Why string diff --git a/go/seatdef/seatdef.go b/go/seatdef/seatdef.go index 0752d7dd..1ca8cb08 100644 --- a/go/seatdef/seatdef.go +++ b/go/seatdef/seatdef.go @@ -268,6 +268,40 @@ type Message struct { // `accept.`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it // `.`, so the same kind name may ride more than one stream (design 47 G §415). Stream string `json:"stream,omitempty"` + // The work queue's settings an accepted kind names (design 47 H2 §777; H-A-350 DMC-1, H-A-362), from which mesh-sdk's + // buscompose derives the seat's work-queue stream and its one shared worker: durations as Go writes them ("24h", + // "2m", "60s", "20s"), counts as integers. Each absent is buscompose's default. + MaxAge string `json:"max-age,omitempty"` + DuplicatesWindow string `json:"duplicates-window,omitempty"` + AckWait string `json:"ack-wait,omitempty"` + InProgress string `json:"in-progress,omitempty"` + MaxMsgs int `json:"max-msgs,omitempty"` + MaxAckPending int `json:"max-ack-pending,omitempty"` + MaxDeliveries int `json:"max-deliveries,omitempty"` +} + +// QueueProblems is what is wrong with an accepted kind's work-queue settings: a duration that is not one above zero, or +// a count below zero. +func (m Message) QueueProblems(where string) Problems { + var ps Problems + for _, d := range []struct{ name, value string }{{"max-age", m.MaxAge}, {"duplicates-window", m.DuplicatesWindow}, + {"ack-wait", m.AckWait}, {"in-progress", m.InProgress}} { + if d.value == "" { + continue + } + if v, err := time.ParseDuration(d.value); err != nil || v <= 0 { + ps = append(ps, Problem{where + "." + d.name, fmt.Sprintf("%q is not a duration above zero, as \"24h\" or \"60s\"", d.value)}) + } + } + for _, n := range []struct { + name string + value int + }{{"max-msgs", m.MaxMsgs}, {"max-ack-pending", m.MaxAckPending}, {"max-deliveries", m.MaxDeliveries}} { + if n.value < 0 { + ps = append(ps, Problem{where + "." + n.name, fmt.Sprintf("%d is below zero", n.value)}) + } + } + return ps } // What an event's keep says where it says less (design 47 G §396, §331). @@ -888,6 +922,7 @@ func checkMessages(field string, ms []Message, whole bool) Problems { ps = append(ps, Problem{where + ".keep", "an event of one subject kept last per subject is one message: give it a subject with parts"}) } } + ps = append(ps, m.QueueProblems(where)...) if m.Subject != "" && field != "events" { ps = append(ps, Problem{where + ".subject", "only an event carries a subject of its own"}) } else if why := checkSubject(m); why != "" { diff --git a/go/seatdef/seatdef_test.go b/go/seatdef/seatdef_test.go index 24ac54f8..383b7d17 100644 --- a/go/seatdef/seatdef_test.go +++ b/go/seatdef/seatdef_test.go @@ -154,6 +154,10 @@ func TestADefinitionIsReadStrictlyNamingWhatIsWrong(t *testing.T) { `"accepts":[{"name":"step","body":{},"stream":"check"},{"name":"step","body":{},"stream":"check"}],"events":`, 1), `"step" twice`}, {"a stream that is none", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"stream":"mail"}],"events":`, 1), `accepts[0].stream: "mail" is not check or delivery`}, + // Design 47 H2 §777, H-A-362: an accepted kind names its work queue's settings, durations as Go writes them. + {"a work queue's settings", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-age":"24h","duplicates-window":"2m","ack-wait":"60s","in-progress":"20s","max-msgs":10000,"max-ack-pending":64,"max-deliveries":5}],"events":`, 1), ""}, + {"a max age that is no duration", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-age":"a day"}],"events":`, 1), "accepts[0].max-age"}, + {"a negative max-msgs", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"max-msgs":-1}],"events":`, 1), "accepts[0].max-msgs"}, {"an event on a stream", strings.Replace(whole, `"name":"created"`, `"name":"created","stream":"check"`, 1), "only an accepted kind rides a stream"}, {"over 256 KiB", listGrain[:len(listGrain)-1] + `,"description":"` + strings.Repeat("x", MaxSize) + `"}`, ErrTooLarge.Error()},