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
This commit is contained in:
2026-11-20 22:18:43 +01:00
parent c1c369f50c
commit becaf8096a
4 changed files with 67 additions and 26 deletions
+35 -1
View File
@@ -321,7 +321,7 @@ func subAProcessPullsADurableOnce(t *testing.T) {
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
_, err = process.PullOnce(cons, "the follower") _, err = process.ConsumeOnce(cons, "the follower", func(jetstream.Msg) {})
if err == nil { if err == nil {
t.Fatal("a second pull loop on the durable the process pulls was taken") 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 { if err != nil {
t.Fatalf("the durable is not pulled again after its loop stopped: %v", err) 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() 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()
} }
+2 -11
View File
@@ -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 // 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 // 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) { func HearEvents(cons jetstream.Consumer, handle func(jetstream.Msg), logf func(string, ...any)) (jetstream.ConsumeContext, error) {
release, err := PullOnce(cons, "") return ConsumeOnce(cons, callerOutside(), handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) {
if err != nil {
return nil, err
}
cc, err := cons.Consume(handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) {
logf("hearing the bus: %v", err) logf("hearing the bus: %v", err)
})) }))
if err != nil {
release()
return nil, err
}
return claimed(cc, release), nil
} }
+29 -13
View File
@@ -20,13 +20,32 @@ var pulled = struct {
by map[string]string by map[string]string
}{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 // ConsumeOnce is the one way a part of a module pulls a durable consumer: it claims cons for binder (a short label; empty
// name): it answers the release, called once the pull loop ends, or an error when this process already pulls that // is the calling function's name) and pulls it with handle and opts, as cons.Consume does. A durable this process pulls
// durable, naming it and both binders. A consumer that is not durable is no claim, and its release does nothing. // already is refused, the error naming it and both binders. The claim is released when the loop is stopped, when a drain
func PullOnce(cons jetstream.Consumer, binder string) (release func(), err error) { // 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 == "" { if binder == "" {
binder = callerOutside() 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() info := cons.CachedInfo()
if info == nil || info.Config.Durable == "" { if info == nil || info.Config.Durable == "" {
return func() {}, nil 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 // pulledOnce is a pull loop whose claim is released as it is stopped, before Stop returns (so a re-serve that stops its old
// ends the loop. // 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 { type pulledOnce struct {
jetstream.ConsumeContext jetstream.ConsumeContext
release func() release func()
closed chan struct{}
} }
func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() } func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() }
func (p pulledOnce) Drain() { p.ConsumeContext.Drain(); p.release() } func (p pulledOnce) Closed() <-chan struct{} { return p.closed }
func claimed(cc jetstream.ConsumeContext, release func()) jetstream.ConsumeContext {
go func() { <-cc.Closed(); release() }()
return pulledOnce{ConsumeContext: cc, release: release}
}
+1 -1
View File
@@ -71,7 +71,7 @@ func (c *Conn) Consume(ctx context.Context, stream string, handle func(*Message)
if err != nil { if err != nil {
return fmt.Errorf("binding %s's queue consumer %s on %s: %w", c.account.Module, name, stream, err) 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 { if err != nil {
return err return err
} }