Merge pull request 'The tool runner binds a module's consumer once and hands each event to the follower and the bundles (design 47 H, H-A-132, H-A-133)' (#79) from fix/47-H1-one-consumer-loop into main

This commit was merged in pull request #79.
This commit is contained in:
2026-11-20 10:35:33 +00:00
5 changed files with 213 additions and 1 deletions
+4 -1
View File
@@ -89,7 +89,10 @@ func serve(ctx context.Context) error {
// The indexer's and the assigner's states the console indexes the mesh by, and the gate reads its marks from, come to it as // The indexer's and the assigner's states the console indexes the mesh by, and the gate reads its marks from, come to it as
// first views, asked of the owners' own tools and followed on their views families, never read from their state (novox/hq // first views, asked of the owners' own tools and followed on their views families, never read from their state (novox/hq
// ADR 0615 §1; design 46 7-approval-mark §5). // ADR 0615 §1; design 46 7-approval-mark §5).
source, stopViews := firstview.Start(context.Background(), conn, log.Printf) // In a module's own runtime the follower hears on the module's one consumer, bound by the runtime for its bundle (design 47
// H §752, H-A-132).
source, stopViews, hearing := startViews(context.Background(), firstview.DepsOf(conn, log.Printf), served, cred.Module, log.Printf)
opts = append(opts, hearing...)
defer stopViews() defer stopViews()
approvals := approvalsState{conn: conn, module: cred.Module} approvals := approvalsState{conn: conn, module: cred.Module}
gate := approval.New(approval.Deps{Node: conn.Node(), Runner: cred.Module, Catalog: source.ApprovalCatalog(definitionsOf(seatList)), Wait: source.WaitCatalog, gate := approval.New(approval.Deps{Node: conn.Node(), Runner: cred.Module, Catalog: source.ApprovalCatalog(definitionsOf(seatList)), Wait: source.WaitCatalog,
+68
View File
@@ -0,0 +1,68 @@
package main
import (
"context"
"sync"
"github.com/novox/mesh-tools/node-tools/internal/bus"
"github.com/novox/mesh-tools/node-tools/internal/firstview"
"github.com/novox/mesh-tools/node-tools/internal/runtime"
)
// ownHearer is the branch follower's hearing in a module's own runtime: the runtime binds the module's consumer once, for
// its bundle, and hands each event to it after the bundle took it (runtime.WithHearer), so no second pull loop reads the
// same durable and each event reaches both (design 47 H §752, H-A-113, H-A-132).
type ownHearer struct {
mu sync.Mutex
deliver func(bus.Envelope) error
}
// consume is the follower's Consume: it binds nothing, and holds deliver until the stop is called.
func (h *ownHearer) consume(deliver func(bus.Envelope) error) (func(), error) {
h.mu.Lock()
h.deliver = deliver
h.mu.Unlock()
return func() {
h.mu.Lock()
h.deliver = nil
h.mu.Unlock()
}, nil
}
// hear hands one event of the module's consumer to the follower, while it hears.
func (h *ownHearer) hear(env bus.Envelope) error {
h.mu.Lock()
deliver := h.deliver
h.mu.Unlock()
if deliver == nil {
return nil
}
return deliver(env)
}
// followerOnOwnConsumer is the first views' reach in a runtime that serves its own account's module: the follower hears on
// the consumer the runtime binds for the module's bundle, through the hearer answered, which the runtime is given
// (runtime.WithHearer). A runtime that serves another module's account (the machine's runtime) keeps the follower's own
// binding, and answers no hearer.
func followerOnOwnConsumer(d firstview.Deps, served []runtime.Served, own string) (firstview.Deps, *ownHearer) {
for _, s := range served {
if s.Module == own {
h := &ownHearer{}
d.Consume = h.consume
return d, h
}
}
return d, nil
}
// startViews is serve's first views: it starts the follower over d and answers the options runtime.Run is given, so that on a
// module's own account the follower binds nothing and hears on the module's one consumer (runtime.WithHearer), and on the
// machine's account the follower binds its own (design 47 H §752, H-A-132, H-A-133).
func startViews(ctx context.Context, d firstview.Deps, served []runtime.Served, own string, logf func(string, ...any)) (*firstview.Views, func(), []runtime.Option) {
followed, hearer := followerOnOwnConsumer(d, served, own)
source, stop := firstview.StartWith(ctx, followed, logf)
if hearer == nil {
return source, stop, nil
}
return source, stop, []runtime.Option{runtime.WithHearer(own, hearer.hear)}
}
@@ -0,0 +1,76 @@
package main
import (
"context"
"encoding/json"
"errors"
"testing"
"github.com/novox/mesh-tools/node-tools/internal/bus"
"github.com/novox/mesh-tools/node-tools/internal/firstview"
"github.com/novox/mesh-tools/node-tools/internal/runtime"
)
// In a module's own runtime the branch follower binds no consumer of its own and hears each event the runtime hands it from the
// module's one consumer; a runtime that is not the module's own keeps the follower's own binding (design 47 H §752, H-A-132).
func TestTheFollowerHearsOnTheOwnModulesOneConsumer(t *testing.T) {
for _, row := range []struct {
name string
served []runtime.Served
own string
binds bool
}{
{"a module's own runtime", []runtime.Served{{Module: "mesh-delivery-indexer"}}, "mesh-delivery-indexer", false},
{"the machine's runtime", []runtime.Served{{Module: "mesh-delivery-indexer"}}, runtime.NodeRuntimeModule, true},
} {
t.Run(row.name, func(t *testing.T) {
bound := 0
d := firstview.Deps{Consume: func(func(bus.Envelope) error) (func(), error) { bound++; return func() {}, nil }}
got, hearer := followerOnOwnConsumer(d, row.served, row.own)
var heard []string
stop, err := got.Consume(func(env bus.Envelope) error { heard = append(heard, env.Key); return nil })
if err != nil {
t.Fatal(err)
}
if (bound == 1) != row.binds || (hearer == nil) != row.binds {
t.Fatalf("bound its own consumer %d time(s), hearer given to the runtime %v; want its own binding %v", bound, hearer != nil, row.binds)
}
if row.binds {
return
}
env := bus.Envelope{Key: "mesh-catalog.catalog-revision.main", Body: json.RawMessage(`{}`)}
if err := hearer.hear(env); err != nil || len(heard) != 1 || heard[0] != env.Key {
t.Fatalf("the event handed by the runtime: err %v, the follower heard %q", err, heard)
}
stop()
if err := hearer.hear(env); err != nil || len(heard) != 1 {
t.Fatalf("after the follower stopped: err %v, heard %q", err, heard)
}
})
}
}
// serve's first views: on a module's own account the follower binds nothing and the runtime is given the hearer; on the
// machine's account the follower binds its own consumer and the runtime is given nothing (design 47 H §752, H-A-132).
func TestServesFollowerBindsOnlyOnTheMachinesAccount(t *testing.T) {
served := []runtime.Served{{Module: "mesh-delivery-indexer"}}
for _, row := range []struct {
own string
binds bool
}{{"mesh-delivery-indexer", false}, {runtime.NodeRuntimeModule, true}} {
t.Run(row.own, func(t *testing.T) {
bound := 0
d := firstview.Deps{Module: row.own,
Ask: func(string, any) (json.RawMessage, error) { return nil, errors.New("no owner here") },
Consume: func(func(bus.Envelope) error) (func(), error) { bound++; return func() {}, nil }}
ctx, cancel := context.WithCancel(context.Background())
_, stop, opts := startViews(ctx, d, served, row.own, t.Logf)
cancel()
stop()
if (bound == 1) != row.binds || (len(opts) == 1) == row.binds {
t.Fatalf("the follower bound %d consumer(s), the runtime is given %d option(s); want the follower's own binding %v",
bound, len(opts), row.binds)
}
})
}
}
@@ -193,3 +193,44 @@ func TestAHeartbeatHandlerSetAgainWhileWordsAreHandedOnIsNotARace(t *testing.T)
t.Error("a bundle gave a handler and no heartbeat is asked") t.Error("a bundle gave a handler and no heartbeat is asked")
} }
} }
// In a module's own runtime the module's consumer is bound once: one event on it reaches the bundle and then the runtime's
// hearer (the branch follower), and an event the bundle did not take is offered again before the hearer hears it (design 47
// H §752, H-A-132).
func TestOneEventOnAModulesConsumerReachesTheBundleAndTheHearer(t *testing.T) {
var order []string
all := &consumers{logf: t.Logf, of: map[string]*moduleEvents{}}
WithHearer("mod", func(env bus.Envelope) error { order = append(order, "hearer "+env.Key); return nil })(all)
m := &moduleEvents{}
all.of["mod"] = m
bundle := &deliverSlot{}
refuse := false
bundle.set(func(raw json.RawMessage) error {
if refuse {
return errorf("not now")
}
var env bus.Envelope
if err := json.Unmarshal(raw, &env); err != nil {
return err
}
order = append(order, "bundle "+env.Key)
return nil
})
m.delivers = []*deliverSlot{bundle}
if err := all.handOut("mod", m, bus.Envelope{Key: "mesh-catalog.catalog-revision.main", Body: json.RawMessage(`{}`)}); err != nil {
t.Fatal(err)
}
if got := strings.Join(order, ", "); got != "bundle mesh-catalog.catalog-revision.main, hearer mesh-catalog.catalog-revision.main" {
t.Fatalf("the event reached %q, want the bundle and then the hearer", got)
}
order, refuse = nil, true
if err := all.handOut("mod", m, bus.Envelope{Key: "a.b", Body: json.RawMessage(`{}`)}); err == nil || len(order) != 0 {
t.Fatalf("an event the bundle did not take: err %v, reached %q; want it offered again, heard by none", err, order)
}
// Another module's events are handed to its bundles alone.
other := &moduleEvents{delivers: []*deliverSlot{{f: func(json.RawMessage) error { order = append(order, "other"); return nil }}}}
all.of["other"] = other
if err := all.handOut("other", other, bus.Envelope{Key: "a.b", Body: json.RawMessage(`{}`)}); err != nil || strings.Join(order, ",") != "other" {
t.Fatalf("another module's event: err %v, reached %q", err, order)
}
}
+24
View File
@@ -256,6 +256,19 @@ func WithLedgerWriters(writer func(module string) (*bus.Conn, error)) Option {
return func(c *consumers) { c.ledgers.writer = writer } return func(c *consumers) { c.ledgers.writer = writer }
} }
// WithHearer hands every event of module's consumer also to hear, in process, after the module's bundles took it: the
// consumer is bound once, for the bundles, and no second pull loop reads the same durable, so in a module's own runtime the
// branch follower and the bundle each hear every event (design 47 H §752, H-A-113, H-A-132). An error of hear offers the
// event again, as a bundle's does.
func WithHearer(module string, hear func(bus.Envelope) error) Option {
return func(c *consumers) {
if c.hearers == nil {
c.hearers = map[string][]func(bus.Envelope) error{}
}
c.hearers[module] = append(c.hearers[module], hear)
}
}
// Run launches, binds and serves, and serves each module's bundle again when it appears, changes or // Run launches, binds and serves, and serves each module's bundle again when it appears, changes or
// goes, with no restart. It answers a stop function. // goes, with no restart. It answers a stop function.
func Run(conn *bus.Conn, served []Served, envs map[string]map[string]string, logf func(string, ...any), opts ...Option) (func(), error) { func Run(conn *bus.Conn, served []Served, envs map[string]map[string]string, logf func(string, ...any), opts ...Option) (func(), error) {
@@ -869,6 +882,8 @@ type consumers struct {
reread func() error reread func() error
rereadMu sync.Mutex rereadMu sync.Mutex
rereading *rereadFlight rereading *rereadFlight
// hearers hear every event of a module's consumer in process, after the module's bundles took it (WithHearer).
hearers map[string][]func(bus.Envelope) error
// askPlain and askChunked are how a bundle's ask is sent (the bus connection's AskAs and AskAsChunked); a test gives its own. // askPlain and askChunked are how a bundle's ask is sent (the bus connection's AskAs and AskAsChunked); a test gives its own.
askPlain, askChunked func(module, key string, body any, within time.Duration) (bus.Answered, error) askPlain, askChunked func(module, key string, body any, within time.Duration) (bus.Answered, error)
} }
@@ -1111,6 +1126,7 @@ func (c *consumers) handOut(module string, m *moduleEvents, env bus.Envelope) er
return errModuleReloading return errModuleReloading
} }
targets := append([]*deliverSlot(nil), m.delivers...) targets := append([]*deliverSlot(nil), m.delivers...)
hearers := append([]func(bus.Envelope) error(nil), c.hearers[module]...)
c.mu.Unlock() c.mu.Unlock()
for _, d := range targets { for _, d := range targets {
if err := d.get()(raw); err != nil { if err := d.get()(raw); err != nil {
@@ -1119,6 +1135,14 @@ func (c *consumers) handOut(module string, m *moduleEvents, env bus.Envelope) er
return err return err
} }
} }
// And the runtime's own hearers of the module's events, on this same consumer (WithHearer).
for _, hear := range hearers {
if err := hear(env); err != nil {
c.logf("[mesh-tools] the tool runner did not take %s%s of %s's consumer: %v; offered again in %s", env.Key,
eventRef(env), module, err, bus.NakDelay)
return err
}
}
return nil return nil
} }