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:
@@ -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
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
|
||||
@@ -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 != "" {
|
||||
|
||||
@@ -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()},
|
||||
|
||||
Reference in New Issue
Block a user