From c952386737cfdb7acf597ca8efa626463cacf322 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 22:12:45 +0100 Subject: [PATCH] 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 --- node-tools/internal/bus/consume_test.go | 4 +- node-tools/internal/bus/streams.go | 49 ++++++++++++++++++++++++- node-tools/internal/bus/streams_test.go | 28 ++++++++++++++ 3 files changed, 78 insertions(+), 3 deletions(-) diff --git a/node-tools/internal/bus/consume_test.go b/node-tools/internal/bus/consume_test.go index e5cc2e5..944a106 100644 --- a/node-tools/internal/bus/consume_test.go +++ b/node-tools/internal/bus/consume_test.go @@ -77,6 +77,8 @@ func TestAConsumerSaysItIsBoundWhileIdleAndOnceWhenTheBusEndedIt(t *testing.T) { } })) 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"}) if err != nil { t.Fatal(err) @@ -97,7 +99,7 @@ func TestAConsumerSaysItIsBoundWhileIdleAndOnceWhenTheBusEndedIt(t *testing.T) { t.Cleanup(stop) // A consume nobody asked a heartbeat of says nothing and asks the bus nothing, however many intervals pass. 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 }) if err != nil { t.Fatal(err) diff --git a/node-tools/internal/bus/streams.go b/node-tools/internal/bus/streams.go index 4f7b09e..e6c1b72 100644 --- a/node-tools/internal/bus/streams.go +++ b/node-tools/internal/bus/streams.go @@ -3,6 +3,8 @@ package bus import ( "context" "errors" + "fmt" + "runtime" "sort" "strings" "sync" @@ -10,6 +12,8 @@ import ( "time" "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). @@ -84,6 +88,9 @@ type hearing struct { js jetstream.JetStream module string 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 sync.Mutex @@ -107,7 +114,7 @@ type hearing struct { } 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{}, 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 { 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...) if err != nil { + release() 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 @@ -315,6 +359,7 @@ func (h *hearing) reconcile() { for heard, reading := range h.bound { select { case <-reading.Closed(): + released(reading) delete(h.bound, heard) delete(h.made, heard) h.whyMu.Lock() diff --git a/node-tools/internal/bus/streams_test.go b/node-tools/internal/bus/streams_test.go index 94a6d7c..6b6901b 100644 --- a/node-tools/internal/bus/streams_test.go +++ b/node-tools/internal/bus/streams_test.go @@ -258,6 +258,34 @@ func TestAConsumerNamedBeforeItExistsIsBoundOnceItDoes(t *testing.T) { } 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