H-A-197: the tool runner claims each durable it pulls through the SDK's guard

A tool runner built before H-A-132/133 ran two pull loops on the indexer
bundle's one durable, each event reached one loop only, and nothing said so;
the SDK's guard (H-A-196) could not see it, since the runner bound through the
bus client directly. hearing.bind now claims each durable with
process.PullOnce, naming the runner's hearing and the part that asked it, and
releases the claim as the loop is stopped or drained, or as the bus ends it,
so a re-serve (which stops its old loop first) binds again without a refusal.
The heartbeat test's second consume pulled the same durable: it gets its own.

Builds: design 47 H H-A-197, H-A-196
This commit is contained in:
2026-11-20 22:12:45 +01:00
parent d76d9e0b1a
commit c952386737
3 changed files with 78 additions and 3 deletions
+3 -1
View File
@@ -77,6 +77,8 @@ func TestAConsumerSaysItIsBoundWhileIdleAndOnceWhenTheBusEndedIt(t *testing.T) {
} }
})) }))
mesh.Consumer(t, "anchor", "quiet", []string{"mesh.mod.alpha.event.>"}, time.Second) mesh.Consumer(t, "anchor", "quiet", []string{"mesh.mod.alpha.event.>"}, time.Second)
// The unasked consume below pulls a durable of its own: a second loop on quiet's is refused (H-A-196, H-A-197).
mesh.Consumer(t, "anchor", "unasked", []string{"mesh.mod.alpha.event.>"}, time.Second)
c, err := bus.Connect(bus.Credential{URL: mt.URL(t), Module: "node-tools", Node: "anchor"}) c, err := bus.Connect(bus.Credential{URL: mt.URL(t), Module: "node-tools", Node: "anchor"})
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
@@ -97,7 +99,7 @@ func TestAConsumerSaysItIsBoundWhileIdleAndOnceWhenTheBusEndedIt(t *testing.T) {
t.Cleanup(stop) t.Cleanup(stop)
// A consume nobody asked a heartbeat of says nothing and asks the bus nothing, however many intervals pass. // A consume nobody asked a heartbeat of says nothing and asks the bus nothing, however many intervals pass.
var unaskedBeats atomic.Int32 var unaskedBeats atomic.Int32
unasked, err := c.ConsumeAsBeatingWhen("quiet", func(bus.Envelope) error { return nil }, unasked, err := c.ConsumeAsBeatingWhen("unasked", func(bus.Envelope) error { return nil },
func(bus.Beat) { unaskedBeats.Add(1) }, func() bool { return false }) func(bus.Beat) { unaskedBeats.Add(1) }, func() bool { return false })
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
+47 -2
View File
@@ -3,6 +3,8 @@ package bus
import ( import (
"context" "context"
"errors" "errors"
"fmt"
"runtime"
"sort" "sort"
"strings" "strings"
"sync" "sync"
@@ -10,6 +12,8 @@ import (
"time" "time"
"github.com/nats-io/nats.go/jetstream" "github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/process"
) )
// A module's own stream, as the runtime publishes to it and hears it (novox/hq ADR 0363 §8, issue 725). // A module's own stream, as the runtime publishes to it and hears it (novox/hq ADR 0363 §8, issue 725).
@@ -84,6 +88,9 @@ type hearing struct {
js jetstream.JetStream js jetstream.JetStream
module string module string
deliver func(Envelope) error deliver func(Envelope) error
// by is the part that asked this hearing (the first caller outside this package), named in the claim of each durable
// it pulls (design 47 H, H-A-196, H-A-197).
by string
// serial hands the module one event at a time across its consumers (novox/hq issue 387). // serial hands the module one event at a time across its consumers (novox/hq issue 387).
serial sync.Mutex serial sync.Mutex
@@ -107,7 +114,7 @@ type hearing struct {
} }
func newHearing(c *Conn, js jetstream.JetStream, module string, deliver func(Envelope) error) *hearing { func newHearing(c *Conn, js jetstream.JetStream, module string, deliver func(Envelope) error) *hearing {
return &hearing{c: c, js: js, module: module, deliver: deliver, return &hearing{c: c, js: js, module: module, deliver: deliver, by: callerOutside(),
bound: map[HeardIssued]jetstream.ConsumeContext{}, made: map[HeardIssued]time.Time{}, said: map[HeardIssued]bool{}, why: map[HeardIssued]error{}, bound: map[HeardIssued]jetstream.ConsumeContext{}, made: map[HeardIssued]time.Time{}, said: map[HeardIssued]bool{}, why: map[HeardIssued]error{},
kick: make(chan struct{}, 1), done: make(chan struct{})} kick: make(chan struct{}, 1), done: make(chan struct{})}
} }
@@ -129,11 +136,48 @@ func (h *hearing) bind(stream, durable string, onErr func(error)) (jetstream.Con
if onErr != nil { if onErr != nil {
opts = append(opts, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { onErr(err) })) opts = append(opts, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) { onErr(err) }))
} }
// Claimed through the SDK's one guard before it is pulled (design 47 H, H-A-196, H-A-197): a second pull loop on a
// durable this process pulls already would take every other event from the first, so it is refused here, loud.
release, err := process.PullOnce(consumer, fmt.Sprintf("the tool runner's hearing of %s, asked by %s", h.module, h.by))
if err != nil {
return nil, time.Time{}, "claiming", err
}
reading, err := consumer.Consume(h.handle, opts...) reading, err := consumer.Consume(h.handle, opts...)
if err != nil { if err != nil {
release()
return nil, time.Time{}, "reading", err return nil, time.Time{}, "reading", err
} }
return reading, created, "", nil go func() { <-reading.Closed(); release() }()
return pulled{ConsumeContext: reading, release: release}, created, "", nil
}
// pulled is a pull loop whose claim (process.PullOnce) is released as it is stopped or drained, before the call returns,
// so a re-serve that stops its old loop binds the new one without a refusal; a loop the bus ended is released by release.
type pulled struct {
jetstream.ConsumeContext
release func()
}
func (p pulled) Stop() { p.ConsumeContext.Stop(); p.release() }
func (p pulled) Drain() { p.ConsumeContext.Drain(); p.release() }
// released releases the claim of a loop the bus ended, before it is bound again.
func released(reading jetstream.ConsumeContext) {
if p, ok := reading.(pulled); ok {
p.release()
}
}
// callerOutside is the first function on the stack outside this package: the part that asked the hearing.
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, "github.com/novox/mesh-tools/node-tools/internal/bus.") || !more {
return f.Function
}
}
} }
// handle hands one delivered event to the module: acknowledged when it took it, offered again after NakDelay // handle hands one delivered event to the module: acknowledged when it took it, offered again after NakDelay
@@ -315,6 +359,7 @@ func (h *hearing) reconcile() {
for heard, reading := range h.bound { for heard, reading := range h.bound {
select { select {
case <-reading.Closed(): case <-reading.Closed():
released(reading)
delete(h.bound, heard) delete(h.bound, heard)
delete(h.made, heard) delete(h.made, heard)
h.whyMu.Lock() h.whyMu.Lock()
+28
View File
@@ -258,6 +258,34 @@ func TestAConsumerNamedBeforeItExistsIsBoundOnceItDoes(t *testing.T) {
} }
return nil return nil
}) })
// A second pull loop on the durable the runner pulls is refused, naming it and both binders (design 47 H, H-A-196,
// H-A-197); a re-serve that stops its loop first binds again without a refusal, its module stream's durable too.
if _, err := conn.ConsumeAs("reader", func(bus.Envelope) error { return nil }); err == nil ||
!strings.Contains(err.Error(), "pulled in this process already") || !strings.Contains(err.Error(), "anchor_reader") ||
strings.Count(err.Error(), "the tool runner's hearing of reader") != 2 {
t.Fatalf("a second pull loop on the durable the runner pulls was not refused naming it and both binders: %v", err)
}
stop()
again, err := conn.ConsumeAs("reader", func(env bus.Envelope) error {
mu.Lock()
heard[env.Key]++
mu.Unlock()
return nil
})
if err != nil {
t.Fatalf("the re-serve was refused after its old loop stopped: %v", err)
}
t.Cleanup(again)
mesh.Emit(t, "mesh.stream.mail.event.mail.home.message.added", map[string]any{})
mt.Until(t, func() error {
mu.Lock()
defer mu.Unlock()
if heard["mail.mail.home.message.added"] != 2 {
return fmt.Errorf("after the re-serve heard %v", heard)
}
return nil
})
} }
// novox/hq ADR 0363 §6 (issue 725): a consumer the controller deletes and makes again under the same name, its // novox/hq ADR 0363 §6 (issue 725): a consumer the controller deletes and makes again under the same name, its