Derive a seat's work queue and its worker from the seat definition

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)
This commit is contained in:
2026-11-21 23:18:34 +01:00
parent 1f2b1cd46b
commit 6852228000
6 changed files with 161 additions and 0 deletions
+4
View File
@@ -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
+19
View File
@@ -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")
}
}
+97
View File
@@ -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
}
+2
View File
@@ -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
+35
View File
@@ -268,6 +268,40 @@ type Message struct {
// `accept.<stream>`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it
// `<stream>.<kind>`, 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 != "" {
+4
View File
@@ -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()},