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
This commit is contained in:
2026-11-20 22:05:14 +01:00
parent c15460faf5
commit c1c369f50c
5 changed files with 160 additions and 3 deletions
+50
View File
@@ -289,4 +289,54 @@ func TestTheHubBindsALateConsumerAndSaysItIsLive(t *testing.T) {
t.Run("AModuleHearsASeatEventKeptOnItsOwnStream", subAModuleHearsASeatEventKeptOnItsOwnStream) t.Run("AModuleHearsASeatEventKeptOnItsOwnStream", subAModuleHearsASeatEventKeptOnItsOwnStream)
t.Run("AModuleHearsAnotherModulesStreamKeptLastPerSubject", subAModuleHearsAnotherModulesStreamKeptLastPerSubject) t.Run("AModuleHearsAnotherModulesStreamKeptLastPerSubject", subAModuleHearsAnotherModulesStreamKeptLastPerSubject)
t.Run("AModuleHearsAStreamKeptByAgeFromItsFirstMessage", subAModuleHearsAStreamKeptByAgeFromItsFirstMessage) 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()
} }
+12 -2
View File
@@ -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 // 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) { 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) logf("hearing the bus: %v", err)
})) }))
if err != nil {
release()
return nil, err
}
return claimed(cc, release), nil
} }
+83
View File
@@ -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}
}
+5
View File
@@ -71,6 +71,11 @@ 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, "")
if err != nil {
return err
}
defer release()
return runQueue(ctx, fetchOne(cons), handle) return runQueue(ctx, fetchOne(cons), handle)
} }
+10 -1
View File
@@ -4,6 +4,7 @@ package process
import ( import (
"context" "context"
"strings"
"testing" "testing"
"time" "time"
@@ -90,15 +91,23 @@ func TestConsumeAckRemovesTheMessageFromTheStream(t *testing.T) {
defer conn.Close() defer conn.Close()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) 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() { go func() {
_ = conn.Consume(ctx, "MAIL_SENDS", func(m *Message) { _ = 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 got <- m
cancel() cancel()
}) })
}() }()
msg := recv(t, got, 8*time.Second, "the message") msg := recv(t, got, 8*time.Second, "the message")
<-ctx.Done() <-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 { if err := msg.Ack(); err != nil {
t.Fatalf("Ack: %v", err) t.Fatalf("Ack: %v", err)
} }