From c1c369f50ca068f0d4a40e4d6d32480aa83b0f0a Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 22:05:14 +0100 Subject: [PATCH 1/2] H-A-196: a process pulls a durable consumer once A second pull loop on a durable the same process already pulls takes every other event from the first, and nothing said so: the tool runner's two loops on the indexer bundle's durable left the catalog seat's revision verb stale twice today. The SDK now refuses it at bind time, naming the durable and both binders: PullOnce claims a durable (by stream, name and the time the bus made it), and HearEvents and Conn.Consume claim through it, releasing on stop, drain or the bus ending the loop. Builds: design 47 H H-A-196 --- go/process/event_hub_integration_test.go | 50 ++++++++++++++ go/process/module.go | 14 +++- go/process/pullonce.go | 83 ++++++++++++++++++++++++ go/process/queue.go | 5 ++ go/process/queue_integration_test.go | 11 +++- 5 files changed, 160 insertions(+), 3 deletions(-) create mode 100644 go/process/pullonce.go diff --git a/go/process/event_hub_integration_test.go b/go/process/event_hub_integration_test.go index 88ba2e46..cbe4c614 100644 --- a/go/process/event_hub_integration_test.go +++ b/go/process/event_hub_integration_test.go @@ -289,4 +289,54 @@ func TestTheHubBindsALateConsumerAndSaysItIsLive(t *testing.T) { t.Run("AModuleHearsASeatEventKeptOnItsOwnStream", subAModuleHearsASeatEventKeptOnItsOwnStream) t.Run("AModuleHearsAnotherModulesStreamKeptLastPerSubject", subAModuleHearsAnotherModulesStreamKeptLastPerSubject) t.Run("AModuleHearsAStreamKeptByAgeFromItsFirstMessage", subAModuleHearsAStreamKeptByAgeFromItsFirstMessage) + t.Run("AProcessPullsADurableOnce", subAProcessPullsADurableOnce) +} + +// A second pull loop on a durable this process already pulls is refused at bind time, naming the durable and both +// binders, and the durable is pulled again once the first loop stopped (design 47 H, H-A-196). +func subAProcessPullsADurableOnce(t *testing.T) { + nc, err := nats.Connect(testbus.URL(t)) + if err != nil { + t.Fatal(err) + } + defer nc.Close() + js, err := jetstream.New(nc) + if err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: process.EventsStream, Subjects: []string{"mesh.mod.*.event.>"}}); err != nil { + t.Fatal(err) + } + cred := process.Account{Node: "n1", Module: "twice"} + if _, err := js.CreateOrUpdateConsumer(ctx, process.EventsStream, jetstream.ConsumerConfig{Durable: cred.EventConsumerName(), AckPolicy: jetstream.AckExplicitPolicy}); err != nil { + t.Fatal(err) + } + cons, err := cred.EventConsumer(ctx, js, process.EventsStream) + if err != nil { + t.Fatal(err) + } + first, err := process.HearEvents(cons, func(m jetstream.Msg) { _ = m.Ack() }, t.Logf) + if err != nil { + t.Fatal(err) + } + _, err = process.PullOnce(cons, "the follower") + if err == nil { + t.Fatal("a second pull loop on the durable the process pulls was taken") + } + for _, want := range []string{cred.EventConsumerName(), process.EventsStream, "subAProcessPullsADurableOnce", "the follower"} { + if !strings.Contains(err.Error(), want) { + t.Fatalf("the refusal %q does not name %q", err, want) + } + } + if _, err := process.HearEvents(cons, func(jetstream.Msg) {}, t.Logf); err == nil { + t.Fatal("a second HearEvents on the durable the process pulls was taken") + } + first.Stop() + again, err := process.HearEvents(cons, func(m jetstream.Msg) { _ = m.Ack() }, t.Logf) + if err != nil { + t.Fatalf("the durable is not pulled again after its loop stopped: %v", err) + } + again.Stop() } diff --git a/go/process/module.go b/go/process/module.go index ccd8e9bd..642c2dc3 100644 --- a/go/process/module.go +++ b/go/process/module.go @@ -104,9 +104,19 @@ func (a Account) namedEventConsumerName(suffix string) string { } // HearEvents pulls from cons, handing each message to handle, and says every error the bus reports while -// hearing through logf ("hearing the bus: ..."). The caller stops the returned context. +// hearing through logf ("hearing the bus: ..."). The caller stops the returned context. A durable this process pulls +// already is refused (PullOnce, design 47 H, H-A-196). func HearEvents(cons jetstream.Consumer, handle func(jetstream.Msg), logf func(string, ...any)) (jetstream.ConsumeContext, error) { - return cons.Consume(handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { + release, err := PullOnce(cons, "") + if err != nil { + return nil, err + } + cc, err := cons.Consume(handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { logf("hearing the bus: %v", err) })) + if err != nil { + release() + return nil, err + } + return claimed(cc, release), nil } diff --git a/go/process/pullonce.go b/go/process/pullonce.go new file mode 100644 index 00000000..e359fc5a --- /dev/null +++ b/go/process/pullonce.go @@ -0,0 +1,83 @@ +package process + +import ( + "fmt" + "runtime" + "strings" + "sync" + "time" + + "github.com/nats-io/nats.go/jetstream" +) + +// A process pulls a durable consumer once (design 47 H, H-A-196): a second pull loop on a durable the same process +// already pulls takes every other event from the first, so each event reaches one loop only and nothing says so. The SDK +// refuses it, loud at bind time, the error naming the durable and both binders. A durable is told by its stream, its name +// and the time the bus made it, so the same names on two buses (two embedded buses in one test process) are two durables. + +var pulled = struct { + sync.Mutex + by map[string]string +}{by: map[string]string{}} + +// PullOnce claims the pull of cons, a durable consumer, for binder (a short label; empty is the calling function's +// name): it answers the release, called once the pull loop ends, or an error when this process already pulls that +// durable, naming it and both binders. A consumer that is not durable is no claim, and its release does nothing. +func PullOnce(cons jetstream.Consumer, binder string) (release func(), err error) { + if binder == "" { + binder = callerOutside() + } + info := cons.CachedInfo() + if info == nil || info.Config.Durable == "" { + return func() {}, nil + } + key := info.Stream + "/" + info.Name + "@" + info.Created.UTC().Format(time.RFC3339Nano) + pulled.Lock() + defer pulled.Unlock() + if first, ok := pulled.by[key]; ok { + return nil, fmt.Errorf("the durable consumer %s on %s is pulled in this process already, by %s: a second pull loop, by %s, "+ + "would take every other event from it, so it is refused (design 47 H, H-A-196)", info.Name, info.Stream, first, binder) + } + pulled.by[key] = binder + var once sync.Once + return func() { + once.Do(func() { + pulled.Lock() + delete(pulled.by, key) + pulled.Unlock() + }) + }, nil +} + +// ownPackage is this package's path as a function's name begins with it. +const ownPackage = "git.novox.be/novox/mesh-sdk/go/process." + +// callerOutside is the name of the first function on the stack outside this package: the part that asked the pull. +func callerOutside() string { + pcs := make([]uintptr, 16) + frames := runtime.CallersFrames(pcs[:runtime.Callers(3, pcs)]) + for { + f, more := frames.Next() + if !strings.HasPrefix(f.Function, ownPackage) { + return f.Function + } + if !more { + return f.Function + } + } +} + +// pulledOnce is a pull loop's context that releases its claim (PullOnce) when it is stopped or drained, or when the bus +// ends the loop. +type pulledOnce struct { + jetstream.ConsumeContext + release func() +} + +func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() } +func (p pulledOnce) Drain() { p.ConsumeContext.Drain(); p.release() } + +func claimed(cc jetstream.ConsumeContext, release func()) jetstream.ConsumeContext { + go func() { <-cc.Closed(); release() }() + return pulledOnce{ConsumeContext: cc, release: release} +} diff --git a/go/process/queue.go b/go/process/queue.go index 01e88cfa..13b6ee4b 100644 --- a/go/process/queue.go +++ b/go/process/queue.go @@ -71,6 +71,11 @@ func (c *Conn) Consume(ctx context.Context, stream string, handle func(*Message) if err != nil { return fmt.Errorf("binding %s's queue consumer %s on %s: %w", c.account.Module, name, stream, err) } + release, err := PullOnce(cons, "") + if err != nil { + return err + } + defer release() return runQueue(ctx, fetchOne(cons), handle) } diff --git a/go/process/queue_integration_test.go b/go/process/queue_integration_test.go index ce3736db..93382f89 100644 --- a/go/process/queue_integration_test.go +++ b/go/process/queue_integration_test.go @@ -4,6 +4,7 @@ package process import ( "context" + "strings" "testing" "time" @@ -90,15 +91,23 @@ func TestConsumeAckRemovesTheMessageFromTheStream(t *testing.T) { defer conn.Close() ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) - got := make(chan *Message, 1) + got, second := make(chan *Message, 1), make(chan error, 1) go func() { _ = conn.Consume(ctx, "MAIL_SENDS", func(m *Message) { + // A second pull loop on the durable this process pulls is refused at bind time (design 47 H, H-A-196). + short, stop := context.WithTimeout(context.Background(), time.Second) + second <- conn.Consume(short, "MAIL_SENDS", func(*Message) {}) + stop() got <- m cancel() }) }() msg := recv(t, got, 8*time.Second, "the message") <-ctx.Done() + if err := <-second; err == nil || !strings.Contains(err.Error(), "pulled in this process already") || + !strings.Contains(err.Error(), account.QueueConsumerName()) { + t.Fatalf("a second Consume of the queue the process pulls was not refused naming its durable: %v", err) + } if err := msg.Ack(); err != nil { t.Fatalf("Ack: %v", err) } -- 2.54.0 From becaf8096a616a53f008d0b21dcee41c60616ed2 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 22:18:43 +0100 Subject: [PATCH 2/2] H-A-196: one SDK function claims, pulls and wraps a durable's loop The tool runner would otherwise copy the claim's wrapper (review round 1, P7): ConsumeOnce claims the durable, pulls it and answers the loop, and HearEvents uses it; Conn.Consume claims through the same guard. A drain keeps its claim until the loop ended, and the loop's Closed is closed only once the claim is released, so a bind during a drain is refused and one after it is never. Builds: design 47 H H-A-196, H-A-197 --- go/process/event_hub_integration_test.go | 36 +++++++++++++++++++- go/process/module.go | 13 ++------ go/process/pullonce.go | 42 ++++++++++++++++-------- go/process/queue.go | 2 +- 4 files changed, 67 insertions(+), 26 deletions(-) diff --git a/go/process/event_hub_integration_test.go b/go/process/event_hub_integration_test.go index cbe4c614..82d31ffe 100644 --- a/go/process/event_hub_integration_test.go +++ b/go/process/event_hub_integration_test.go @@ -321,7 +321,7 @@ func subAProcessPullsADurableOnce(t *testing.T) { if err != nil { t.Fatal(err) } - _, err = process.PullOnce(cons, "the follower") + _, err = process.ConsumeOnce(cons, "the follower", func(jetstream.Msg) {}) if err == nil { t.Fatal("a second pull loop on the durable the process pulls was taken") } @@ -338,5 +338,39 @@ func subAProcessPullsADurableOnce(t *testing.T) { if err != nil { t.Fatalf("the durable is not pulled again after its loop stopped: %v", err) } + // A drain keeps the claim until the loop ended: a bind during it is refused, one after it (Closed) is taken. + held := make(chan struct{}) + slow, err := cred.EventConsumer(ctx, js, process.EventsStream) + if err != nil { + t.Fatal(err) + } again.Stop() + handed := make(chan struct{}, 2) + draining, err := process.ConsumeOnce(slow, "the drained loop", func(m jetstream.Msg) { handed <- struct{}{}; <-held; _ = m.Ack() }) + if err != nil { + t.Fatal(err) + } + if _, err := js.Publish(ctx, "mesh.mod.alpha.event.happened", []byte(`{}`)); err != nil { + t.Fatal(err) + } + if _, err := js.Publish(ctx, "mesh.mod.alpha.event.happened", []byte(`{}`)); err != nil { + t.Fatal(err) + } + select { + case <-handed: + case <-ctx.Done(): + t.Fatal("the drained loop was handed no message") + } + draining.Drain() + if _, err := process.ConsumeOnce(slow, "a bind during the drain", func(jetstream.Msg) {}); err == nil || + !strings.Contains(err.Error(), "the drained loop") { + t.Fatalf("a bind while the drain runs was not refused naming the draining loop: %v", err) + } + close(held) + <-draining.Closed() + after, err := process.ConsumeOnce(slow, "a bind after the drain", func(m jetstream.Msg) { _ = m.Ack() }) + if err != nil { + t.Fatalf("a bind after the drain ended was refused: %v", err) + } + after.Stop() } diff --git a/go/process/module.go b/go/process/module.go index 642c2dc3..57a337c8 100644 --- a/go/process/module.go +++ b/go/process/module.go @@ -105,18 +105,9 @@ func (a Account) namedEventConsumerName(suffix string) string { // HearEvents pulls from cons, handing each message to handle, and says every error the bus reports while // hearing through logf ("hearing the bus: ..."). The caller stops the returned context. A durable this process pulls -// already is refused (PullOnce, design 47 H, H-A-196). +// already is refused (ConsumeOnce, design 47 H, H-A-196). func HearEvents(cons jetstream.Consumer, handle func(jetstream.Msg), logf func(string, ...any)) (jetstream.ConsumeContext, error) { - release, err := PullOnce(cons, "") - if err != nil { - return nil, err - } - cc, err := cons.Consume(handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { + return ConsumeOnce(cons, callerOutside(), handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { logf("hearing the bus: %v", err) })) - if err != nil { - release() - return nil, err - } - return claimed(cc, release), nil } diff --git a/go/process/pullonce.go b/go/process/pullonce.go index e359fc5a..086a585a 100644 --- a/go/process/pullonce.go +++ b/go/process/pullonce.go @@ -20,13 +20,32 @@ var pulled = struct { by map[string]string }{by: map[string]string{}} -// PullOnce claims the pull of cons, a durable consumer, for binder (a short label; empty is the calling function's -// name): it answers the release, called once the pull loop ends, or an error when this process already pulls that -// durable, naming it and both binders. A consumer that is not durable is no claim, and its release does nothing. -func PullOnce(cons jetstream.Consumer, binder string) (release func(), err error) { +// ConsumeOnce is the one way a part of a module pulls a durable consumer: it claims cons for binder (a short label; empty +// is the calling function's name) and pulls it with handle and opts, as cons.Consume does. A durable this process pulls +// already is refused, the error naming it and both binders. The claim is released when the loop is stopped, when a drain +// has ended, or when the bus ends the loop: the context's Closed is closed only once the claim is released, so a part that +// binds again on it is never refused. A consumer that is not durable is no claim. +func ConsumeOnce(cons jetstream.Consumer, binder string, handle jetstream.MessageHandler, opts ...jetstream.PullConsumeOpt) (jetstream.ConsumeContext, error) { if binder == "" { binder = callerOutside() } + release, err := pullOnce(cons, binder) + if err != nil { + return nil, err + } + cc, err := cons.Consume(handle, opts...) + if err != nil { + release() + return nil, err + } + closed := make(chan struct{}) + go func() { <-cc.Closed(); release(); close(closed) }() + return pulledOnce{ConsumeContext: cc, release: release, closed: closed}, nil +} + +// pullOnce claims the pull of cons, a durable consumer, for binder: it answers the release, or an error when this process +// already pulls that durable, naming it and both binders. +func pullOnce(cons jetstream.Consumer, binder string) (release func(), err error) { info := cons.CachedInfo() if info == nil || info.Config.Durable == "" { return func() {}, nil @@ -67,17 +86,14 @@ func callerOutside() string { } } -// pulledOnce is a pull loop's context that releases its claim (PullOnce) when it is stopped or drained, or when the bus -// ends the loop. +// pulledOnce is a pull loop whose claim is released as it is stopped, before Stop returns (so a re-serve that stops its old +// loop binds the new one at once), and once a drain or the bus ended the loop, never at the drain's start, so a bind +// during a drain cannot run two loops; its Closed is closed after the release. type pulledOnce struct { jetstream.ConsumeContext release func() + closed chan struct{} } -func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() } -func (p pulledOnce) Drain() { p.ConsumeContext.Drain(); p.release() } - -func claimed(cc jetstream.ConsumeContext, release func()) jetstream.ConsumeContext { - go func() { <-cc.Closed(); release() }() - return pulledOnce{ConsumeContext: cc, release: release} -} +func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() } +func (p pulledOnce) Closed() <-chan struct{} { return p.closed } diff --git a/go/process/queue.go b/go/process/queue.go index 13b6ee4b..0dbe144d 100644 --- a/go/process/queue.go +++ b/go/process/queue.go @@ -71,7 +71,7 @@ func (c *Conn) Consume(ctx context.Context, stream string, handle func(*Message) if err != nil { return fmt.Errorf("binding %s's queue consumer %s on %s: %w", c.account.Module, name, stream, err) } - release, err := PullOnce(cons, "") + release, err := pullOnce(cons, callerOutside()) if err != nil { return err } -- 2.54.0