Compare commits

...
16 Commits
Author SHA1 Message Date
mesh-tools 49b7db386a Merge pull request 'Design 47 H1: a held findings writer seeds only the kinds it owns; retired kinds clear once (H-A-242)' (#207) from fix/47-H1-sdk-held-writer-owned into main 2026-11-21 10:50:20 +00:00
jschoubben 78807e5ef3 Design 47 H1: a held writer always starts; a retired entry may name its scope
Start returned at the first early write, early clear or retired clear that
failed, before the writer started, so one refused kind stopped the writer
whole. A refused kind is now skipped (refuse said it once) and any other
failure is said in the journal and left to the next start; the writer always
starts. A RetiredKind may name its Scope, so an entry clears only keys of it.

Builds: design 47 H H-A-242 (3), H-A-249, G §580
2026-11-21 11:47:20 +01:00
jschoubben d06835bf93 Design 47 H1: a retired kind may name the ids its writer once wrote
Where another writer of the same state owns a retired kind now, clearing every
key of it would clear that writer's findings. A RetiredKind entry names its
kind and, optionally, the exact ids and id prefixes this writer wrote under
it; Start clears only those keys, every key of the kind when none are named.

Builds: design 47 H H-A-247 (3), H-A-249, G §580
2026-11-21 11:42:45 +01:00
jschoubben 220d511f95 Design 47 H1: a held writer clears its retired kinds once at start and reads only its own keys
A kind no code raises any more stood in the state with its condition open and
nobody to clear it. A writer's Retired kinds are cleared once at Start, said
as finding-cleared so the keeper clears their conditions, and never seeded;
Start reads (Get) only its own and its retired keys, checking ownership first.

Builds: design 47 H H-A-242, H-A-247 (3), G §580
2026-11-21 11:39:08 +01:00
jschoubben af2abcf121 Design 47 H1: a held writer seeds only the kinds it owns; an unowned kind is said once
The tool runner's held writer seeded every key of the module's shared state
`findings`, the daemon's kinds included, and then refused them once a minute,
so no finding of the indexer was stated. Start now seeds only keys of the
writer's own kinds (G §580: another bundle states its own), and a kind the
writer does not own is refused with "finding kind X not declared", said in
the journal once per kind and left out of a statement, never retried.

Builds: design 47 H H-A-240, H-A-242 (1) (3), G §580
2026-11-21 11:28:04 +01:00
mesh-tools bc138366af Merge pull request 'Design 47 H1: the views reader's test waits for the acknowledged floor, not the pending count (H-A-196, H-A-197)' (#205) from fix/47-H1-sdk-views-one-durable into main 2026-11-21 00:27:19 +00:00
jschoubben 4a5eb26f4e views: read the durable's ack floor up to a mark, not its pending count, after the handlers spoke
The views test read NumAckPending as soon as the picture and the adopted handler had said the last event, but the
reader acknowledges after both, and the bus takes acks on its own; on the loaded build node (pipeline main.54) one
ack was still pending. The reader binds the module's durable once (the hub's one pull); the guard of H-A-196 is not
involved. The test now publishes a mark the hub hands after every event before it, acknowledged with the bus's
answer, and reads that the ack floor reached the mark; an event the owner says after it may still wait.

Builds: design 47 H §774, H-A-196, H-A-197
2026-11-21 01:20:35 +01:00
mesh-tools 173a8c120d Merge pull request 'Design 47 H1: a process pulls a durable consumer once; ConsumeOnce claims, pulls and releases (H-A-196)' (#204) from fix/47-H1-durable-pulled-once into main 2026-11-20 23:53:09 +00:00
jschoubben becaf8096a 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
2026-11-20 22:18:43 +01:00
jschoubben c1c369f50c 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
2026-11-20 22:05:14 +01:00
mesh-tools c15460faf5 Merge pull request 'Design 47 H1: a view reader hears an event on its bare subject; an unhandled event is the module's finding (H-A-166, H-A-169)' (#203) from fix/47-H1-sdk-bare-subject into main 2026-11-20 16:55:39 +00:00
jschoubben a5225dfac3 views: wire the unhandled-event count once, and prove it on the bus
The hub's hook, the path the live fault took, had no test that failed
without it, and each Start appended it again, so a second Start counted
every event twice. Start now wires it once per hub and keeps the time of
the first start; the shared-durable integration test holds the reader's
finding of the one event nobody takes, counted once across two starts.

Builds: design 47 H H-A-169
2026-11-20 17:52:48 +01:00
jschoubben e568e6dc63 views: count the events no handler takes as the module's finding
An event a module consumes that no handler takes was said in the journal
alone, so a part that never acted on it (the runner's placing at 17:34) was
seen only by reading the log. The event hub now tells a hook of each such
subject; the process reader, where it holds a findings writer, counts them
in one finding event-unhandled per module (the count since the start and
the last subject) and clears it at its start, since a new build may handle
the event. Without a findings writer the journal line stands alone.

Builds: design 47 H H-A-166, H-A-169
2026-11-20 17:45:27 +01:00
mesh-tools 723c747cea Merge pull request 'Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7)' (#202) from proof/47-H1-two-modules into main 2026-11-20 16:44:50 +00:00
jschoubben 7aae152760 views: hear a seat's event on its bare subject as on its further parts
A seat's contract says an event on its bare subject (the seat mesh-catalog's
registration-changed), while both view readers adopted it on `<subject>.>`
alone, so the event hub acknowledged it unhandled and the part never acted.
The process reader now registers one handler on both forms of the hub (the
two patterns do not overlap, so a message reaches it once), and the stdio
reader subscribes both forms with the one handler.

Builds: design 47 H H-A-166
2026-11-20 17:43:14 +01:00
jschoubben 3667ec96a0 Design 47 H1: proof 2, a two-module change along a dependency edge delivered by its pipeline (H §5 step 7) 2026-11-20 17:06:03 +01:00
16 changed files with 691 additions and 49 deletions
+15
View File
@@ -26,6 +26,8 @@ type EventHub struct {
routes []hubRoute
cons jetstream.ConsumeContext
bound []func(created time.Time)
// unhandled are told each subject no handler took (OnUnhandled).
unhandled []func(subject string)
// kept are the module's durables on the kept seat events' streams it handles (StartKept).
kept []jetstream.ConsumeContext
}
@@ -72,6 +74,15 @@ func (h *EventHub) OnBound(f func(created time.Time)) {
h.mu.Unlock()
}
// OnUnhandled registers f, told the subject of each message no handler takes, after the hub said it in the log and
// acknowledged it: the module's process reader counts them in its finding `event-unhandled` (design 47 H, H-A-166,
// H-A-169).
func (h *EventHub) OnUnhandled(f func(subject string)) {
h.mu.Lock()
h.unhandled = append(h.unhandled, f)
h.mu.Unlock()
}
// Patterns are the registered subject patterns, in order.
func (h *EventHub) Patterns() []string {
h.mu.RLock()
@@ -235,10 +246,14 @@ func (h *EventHub) hear(m jetstream.Msg) {
break
}
}
told := h.unhandled
h.mu.RUnlock()
if take == nil {
h.logf("events: %s is taken by no handler of this module, acknowledged", m.Subject())
_ = m.Ack()
for _, f := range told {
f(m.Subject())
}
return
}
take(m)
+84
View File
@@ -289,4 +289,88 @@ func TestTheHubBindsALateConsumerAndSaysItIsLive(t *testing.T) {
t.Run("AModuleHearsASeatEventKeptOnItsOwnStream", subAModuleHearsASeatEventKeptOnItsOwnStream)
t.Run("AModuleHearsAnotherModulesStreamKeptLastPerSubject", subAModuleHearsAnotherModulesStreamKeptLastPerSubject)
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.ConsumeOnce(cons, "the follower", func(jetstream.Msg) {})
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)
}
// 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()
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()
}
+9
View File
@@ -37,6 +37,15 @@ func TestTheHubMatchesSubjectsAndRefusesOverlappingPatterns(t *testing.T) {
if err := h.Handle("mesh.mod.q.event.>", nop); err != nil {
t.Fatal(err)
}
// H-A-169: a message no handler takes is acknowledged and told to each OnUnhandled hook, with its subject; one taken is not.
var told []string
h.OnUnhandled(func(subject string) { told = append(told, subject) })
taken, lost := &bindMsg{subject: "mesh.mod.q.event.x"}, &bindMsg{subject: "mesh.seat.s.event.nobody"}
h.hear(taken)
h.hear(lost)
if !lost.acked || len(told) != 1 || told[0] != "mesh.seat.s.event.nobody" {
t.Errorf("the unhandled message: acked %v, told %v", lost.acked, told)
}
// W1.12: a seat's event kept in a stream of its own is heard on one bus name and one durable, the maker's and the
// hearer's alike; an event kept last per subject is delivered from the last of each subject. The name is the
// contract's Stream<E> as it stands (seatdef.KeptStream), never made again here: a dotted or unprefixed name is
+3 -2
View File
@@ -104,9 +104,10 @@ func (a Account) namedEventConsumerName(suffix string) string {
}
// 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 (ConsumeOnce, design 47 H, H-A-196).
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) {
return ConsumeOnce(cons, callerOutside(), handle, jetstream.ConsumeErrHandler(func(_ jetstream.ConsumeContext, err error) {
logf("hearing the bus: %v", err)
}))
}
+99
View File
@@ -0,0 +1,99 @@
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{}}
// ConsumeOnce is the one way a part of a module pulls a durable consumer: it claims cons for binder (a short label; empty
// is the calling function's name) and pulls it with handle and opts, as cons.Consume does. A durable this process pulls
// already is refused, the error naming it and both binders. The claim is released when the loop is stopped, when a drain
// 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 == "" {
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()
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 whose claim is released as it is stopped, before Stop returns (so a re-serve that stops its old
// 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 {
jetstream.ConsumeContext
release func()
closed chan struct{}
}
func (p pulledOnce) Stop() { p.ConsumeContext.Stop(); p.release() }
func (p pulledOnce) Closed() <-chan struct{} { return p.closed }
+5
View File
@@ -71,6 +71,11 @@ func (c *Conn) Consume(ctx context.Context, stream string, handle func(*Message)
if err != nil {
return fmt.Errorf("binding %s's queue consumer %s on %s: %w", c.account.Module, name, stream, err)
}
release, err := pullOnce(cons, callerOutside())
if err != nil {
return err
}
defer release()
return runQueue(ctx, fetchOne(cons), handle)
}
+10 -1
View File
@@ -4,6 +4,7 @@ package process
import (
"context"
"strings"
"testing"
"time"
@@ -90,15 +91,23 @@ func TestConsumeAckRemovesTheMessageFromTheStream(t *testing.T) {
defer conn.Close()
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() {
_ = 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
cancel()
})
}()
msg := recv(t, got, 8*time.Second, "the message")
<-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 {
t.Fatalf("Ack: %v", err)
}
+1
View File
@@ -9,6 +9,7 @@
// No transport here: the bus, the subjects and the memberships are the runtime's (ADR 0039, 0175).
// What a bundle asks of the bus — emitting an event — it asks of the runtime over the same channel,
// and the runtime does it as the module (ADR 0193). stdout is the protocol; log to stderr.
// Design 47 H1, proof 2: this comment is the mesh-sdk half of a two-module change its pipeline delivers.
package stdio
import (
+11
View File
@@ -23,6 +23,9 @@ const (
// EntryNotFoundKind is a part's finding of an entry by fingerprint the seat mesh-catalog's `entry` answered it does not hold
// (design 47 G §614, A-15, A-103): scope the part, id the fingerprint.
EntryNotFoundKind = "entry-not-found"
// EventUnhandledKind is a process's finding of the events its durable consumer delivered that no handler of the module
// took, one per module, counted since the process started (design 47 H, H-A-166, H-A-169).
EventUnhandledKind = "event-unhandled"
)
// viewFinding is what a views part says is wrong with a state it owns or follows, in plain fields: kind and id name it, summary
@@ -120,3 +123,11 @@ func WriteEntryNotFound(w WireWriter, fingerprint string, since, at time.Time) e
func ClearEntryNotFound(w WireWriter, fingerprint string) error {
return viewFinding{kind: EntryNotFoundKind, id: fingerprint}.drop(w)
}
// unhandledFinding is the module's one finding of the events no handler took since its process started (H-A-169): its id the
// module, its summary the count and the last subject.
func unhandledFinding(module string, count int, last string, since, at time.Time) viewFinding {
summary := fmt.Sprintf("%s took %d events by no handler since its process started at %s, the last on %s: what the module consumes it does not act on",
module, count, since.UTC().Format(time.RFC3339), last)
return viewFinding{kind: EventUnhandledKind, id: module, summary: summary, headline: fmt.Sprintf("%s hears events it does not handle", module), at: at.UTC()}
}
+34 -9
View File
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"sort"
"strings"
"sync"
)
@@ -139,16 +140,30 @@ func (h *HeldWriter[F, C, S, A]) Held() []F {
return out
}
// Start seeds what the writer holds from the keys of its state `findings` (design 47 G A-40), what was written before it
// standing over them, writes what was written and clears what was cleared before it, and starts the writer. A part makes the
// writer before its module serves, so nothing is read from the state until now.
// Start seeds what the writer holds from the keys of its state `findings` of the kinds it owns (design 47 G A-40, §580, H
// H-A-242: another bundle's keys are its own to state, and are not read), what was written before it standing over them;
// writes what was written and clears what was cleared before it; clears once the keys of its retired kinds, never seeding
// them (H-A-247 (3)); and starts the writer. A part makes the writer before its module serves, so nothing is read from the
// state until now.
func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
keys, err := h.state.Keys()
if err != nil {
return err
}
var retired [][4]string
h.mu.Lock()
for _, k := range keys {
if h.Writer.retiredKey(k) {
// a kind no code raises any more: cleared once, never seeded (H-A-247 (3))
scope, rest, _ := strings.Cut(k, ".")
if i := strings.LastIndex(rest, "."); i > 0 {
retired = append(retired, [4]string{scope, rest[:i], rest[i+1:], "the kind is retired: no code raises it any more"})
}
continue
}
if !h.Writer.ownsKey(k) {
continue // another bundle's kind: it states its own (design 47 G §580, H H-A-242 (1)), and is not read
}
e, err := h.state.Get(k)
if err != nil {
h.mu.Unlock()
@@ -171,15 +186,25 @@ func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
pending, cleared := h.pending, h.cleared
h.started, h.pending, h.cleared = true, nil, nil
h.mu.Unlock()
// None of these stops the writer (H-A-242 (3)): a kind it does not own was said once by refuse, and any other failure is
// said here and left to the next start.
for _, f := range pending {
if err := h.Writer.Write(ctx, f); err != nil {
return err
}
h.unstarted(h.Writer.Write(ctx, f), "an early write")
}
for _, c := range cleared {
if err := h.Writer.Clear(ctx, c[0], c[1], c[2], c[3]); err != nil {
return err
}
h.unstarted(h.Writer.Clear(ctx, c[0], c[1], c[2], c[3]), "an early clear of "+FindingKey(c[0], c[1], c[2]))
}
for _, c := range retired {
h.unstarted(h.Writer.clear(ctx, c[0], c[1], c[2], c[3]), "the retired key "+FindingKey(c[0], c[1], c[2]))
}
return h.Writer.Start(ctx)
}
// unstarted says in the journal an act of Start that failed, but for a kind the writer does not own, which refuse said once.
func (h *HeldWriter[F, C, S, A]) unstarted(err error, what string) {
var refused *unownedKind
if err == nil || errors.As(err, &refused) {
return
}
h.Writer.cfg.Logf("the finding writer's start: %s failed, left to the next start: %v", what, err)
}
+77 -6
View File
@@ -73,6 +73,12 @@ type ProcessReader struct {
asked bool
begun map[string]context.CancelFunc
status *process.AwaitedBucket
// unheard counts the events no handler of the module took since Start, the last of them on lastUnheard (H-A-169).
unheard int
lastUnheard string
startedAt time.Time
// hooked is the hub the count of unhandled events is wired on, so a second Start counts no event twice.
hooked *process.EventHub
}
// adoptedHear is one adopted follower's handler of its seat event, by its picture's bucket.
@@ -175,8 +181,7 @@ func (r *ProcessReader) Adopt(f *Follower, seat, event string, hear func(context
hub, handle := r.hub, r.handle
r.mu.Unlock()
if subject != "" && hub != nil {
// one subscription per event, with every further part (design 47 G §532)
if err := hub.Handle(subject+".>", handle); err != nil {
if err := handleEvent(hub, subject, handle); err != nil {
r.logf("views: %s's event %s is not heard (%v): the view %s is its first view's alone, asked again by hand", r.Module, subject, err, p.bucket)
}
}
@@ -202,8 +207,7 @@ func (r *ProcessReader) AdoptEvent(seat, event string, hear func(context.Context
hub, handle := r.hub, r.handle
r.mu.Unlock()
if fresh && hub != nil {
// one subscription per event, with every further part (design 47 G §532)
if err := hub.Handle(subject+".>", handle); err != nil {
if err := handleEvent(hub, subject, handle); err != nil {
r.logf("views: %s's event %s is not heard (%v)", r.Module, subject, err)
}
}
@@ -397,6 +401,50 @@ func (r *ProcessReader) Hear(ctx context.Context) func(jetstream.Msg) {
}
r.logf("views: %s is no views event of an owner followed, acknowledged", m.Subject())
_ = m.Ack()
r.unhandled(m.Subject())
}
}
// now is the reader's clock.
func (r *ProcessReader) now() time.Time {
if r.Now != nil {
return r.Now()
}
return time.Now()
}
// unhandled counts an event no handler of the module took, said in the log already, in the module's finding
// `event-unhandled` (design 47 H, H-A-166, H-A-169); with no findings writer the log line stands alone.
func (r *ProcessReader) unhandled(subject string) {
if r.Findings == nil {
return
}
r.mu.Lock()
r.unheard++
r.lastUnheard = subject
count, since := r.unheard, r.startedAt
r.mu.Unlock()
w := r.Findings()
if w == nil {
return
}
if err := unhandledFinding(r.Module, count, subject, since, r.now()).put(w); err != nil {
r.logf("views: the finding %s of %s is not written: %v", EventUnhandledKind, r.Module, err)
}
}
// clearUnhandled clears the module's finding `event-unhandled` at the process's start: a new build may handle the event
// (H-A-169).
func (r *ProcessReader) clearUnhandled() {
if r.Findings == nil {
return
}
w := r.Findings()
if w == nil {
return
}
if err := (viewFinding{kind: EventUnhandledKind, id: r.Module}).drop(w); err != nil {
r.logf("views: the finding %s of %s is not cleared at its start: %v", EventUnhandledKind, r.Module, err)
}
}
@@ -849,7 +897,21 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
})
hear := r.Hear(ctx)
err := hub.Handle(pattern, hear)
if r.Findings != nil {
// H-A-169: the events no handler of the module takes are its finding, cleared at each start
r.clearUnhandled()
r.mu.Lock()
wire := r.hooked != hub
r.hooked = hub
r.mu.Unlock()
if wire {
hub.OnUnhandled(r.unhandled)
}
}
r.mu.Lock()
if r.startedAt.IsZero() {
r.startedAt = r.now() // the process's start; a second Start counts on from it
}
r.status = status
if !own {
// an event adopted after the start is handled on the module's hub (Adopt); the reader's own hub takes every one
@@ -861,9 +923,8 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
subjects := slices.Sorted(maps.Keys(r.adopted))
r.mu.Unlock()
for _, subject := range subjects {
// one subscription per event, with every further part (design 47 G §532)
if err == nil {
err = hub.Handle(subject+".>", hear)
err = handleEvent(hub, subject, hear)
}
}
}
@@ -891,6 +952,16 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
r.Ask(ctx, said)
}
// handleEvent registers handle on the hub for a seat's event on its bare subject and on every further part after it
// (`<subject>.>`): one handler, both forms, as the seat's contract says the event on either (design 47 H, H-A-166; one
// subscription per event, design 47 G §532). The two patterns do not overlap, so a message reaches the handler once.
func handleEvent(hub *process.EventHub, subject string, handle func(jetstream.Msg)) error {
if err := hub.Handle(subject, handle); err != nil {
return err
}
return hub.Handle(subject+".>", handle)
}
// adoptedHears are the handlers of every follower adopted on the event whose subject is subject or has further parts
// after it (`<event>.<module>.<branch>.<commit or group>`, design 47 G §521, §532), or nil.
func adoptedHears(adopted map[string][]adoptedHear, subject string) []adoptedHear {
+90 -8
View File
@@ -7,6 +7,8 @@ import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"testing"
"time"
@@ -152,11 +154,14 @@ func subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
hub := process.NewEventHub(t.Logf)
got := map[string]chan string{"a": make(chan string, 8), "b": make(chan string, 8)}
for name, pattern := range map[string]string{"a": "mesh.mod.p.event.a", "b": "mesh.mod.q.event.b.*"} {
if err := hub.Handle(pattern, func(m jetstream.Msg) { _ = m.Ack(); got[name] <- m.Subject() }); err != nil {
// The handlers' acknowledgement waits for the bus's answer, so a message a handler handed on is acknowledged
// on the bus, and every one the hub handed before it too (acks of one consumer are taken in order).
if err := hub.Handle(pattern, func(m jetstream.Msg) { _ = m.DoubleAck(ctx); got[name] <- m.Subject() }); err != nil {
t.Fatal(err)
}
}
r := &views.ProcessReader{Module: "reader", Hub: hub, Logf: t.Logf,
found := &seenFindings{put: make(chan map[string]any, 8)}
r := &views.ProcessReader{Module: "reader", Hub: hub, Logf: t.Logf, Findings: func() views.WireWriter { return found },
Call: func(tool string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
m, err := nc.Request("mesh.mod.o.call.o_read_modules.n0", raw, 5*time.Second)
@@ -168,6 +173,20 @@ func subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
if _, err := r.Follow("o", "modules", "o.o_read_modules"); err != nil {
t.Fatal(err)
}
// H-A-166: a seat's event said on its bare subject (as the seat mesh-catalog says registration-changed) and one with
// further parts both reach the one adopted handler, each once.
if info, err := js.Stream(ctx, process.EventsStream); err != nil {
t.Fatal(err)
} else if cfg := info.CachedInfo().Config; !slices.Contains(cfg.Subjects, "mesh.seat.*.event.>") {
cfg.Subjects = append(cfg.Subjects, "mesh.seat.*.event.>")
if _, err := js.UpdateStream(ctx, cfg); err != nil {
t.Fatal(err)
}
}
seatHeard := make(chan string, 8)
if err := r.AdoptEvent("s", "registration-changed", func(_ context.Context, d []byte) error { seatHeard <- string(d); return nil }); err != nil {
t.Fatal(err)
}
r.Start(ctx, js, cred, nil)
if err := hub.Start(ctx, js, cred); err != nil {
t.Fatal(err)
@@ -181,8 +200,9 @@ func subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
if err != nil {
t.Fatal(err)
}
for _, s := range []string{"mesh.mod.p.event.a", "mesh.mod.q.event.b.c", "mesh.mod.z.event.nobody", "mesh.mod.p.event.a"} {
if _, err := js.Publish(ctx, s, []byte("{}")); err != nil {
for _, s := range []string{"mesh.mod.p.event.a", "mesh.mod.q.event.b.c", "mesh.mod.z.event.nobody", "mesh.mod.p.event.a",
"mesh.seat.s.event.registration-changed", "mesh.seat.s.event.registration-changed.m"} {
if _, err := js.Publish(ctx, s, []byte(`"`+s+`"`)); err != nil {
t.Fatal(err)
}
}
@@ -199,15 +219,70 @@ func subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
t.Fatalf("handler %s got %s, wanted %s", want.who, s, want.subject)
}
}
if len(got["a"])+len(got["b"]) != 0 {
t.Fatal("a handler heard a message that was another's")
for _, want := range []string{`"mesh.seat.s.event.registration-changed"`, `"mesh.seat.s.event.registration-changed.m"`} {
select {
case d := <-seatHeard:
if d != want {
t.Fatalf("the adopted seat event heard %s, wanted %s", d, want)
}
case <-time.After(10 * time.Second):
t.Fatalf("the adopted seat event never heard %s", want)
}
}
if len(got["a"])+len(got["b"])+len(seatHeard) != 0 {
t.Fatal("a handler heard a message that was another's, or one twice")
}
// The reader acknowledges an event after it took it into its picture and the adopted handler returned, so the
// picture and the handler say nothing of its ack: one more event, handed after them in order and acknowledged with
// the bus's answer, is the mark that every ack before it has landed (the build node, main.54, read one pending). An
// event said after the mark (the owner's own mark of its burst) may still wait for its ack, so the floor is read.
mark, err := js.Publish(ctx, "mesh.mod.p.event.a", []byte(`"the mark"`))
if err != nil {
t.Fatal(err)
}
select {
case <-got["a"]:
case <-time.After(10 * time.Second):
t.Fatal("the mark after the handled events was not heard")
}
cons, err := js.Consumer(ctx, process.EventsStream, cred.EventConsumerName())
if err != nil {
t.Fatal(err)
}
if info, err := cons.Info(ctx); err != nil || info.NumAckPending != 0 {
t.Fatalf("a message was left unacknowledged: %+v %v", info, err)
if info, err := cons.Info(ctx); err != nil || info.AckFloor.Stream < mark.Sequence {
t.Fatalf("a message up to the mark %d was left unacknowledged: %+v %v", mark.Sequence, info, err)
}
// H-A-169: the one event no handler takes is the module's finding event-unhandled, counted once, naming its subject,
// though the reader started twice.
r.Start(ctx, js, cred, nil)
select {
case f := <-found.put:
summary, _ := f["summary"].(string)
if f["kind"] != views.EventUnhandledKind || f["id"] != "reader" || !strings.Contains(summary, "took 1 events") ||
!strings.Contains(summary, "mesh.mod.z.event.nobody") {
t.Fatalf("the unhandled event's finding: %v", f)
}
case <-time.After(10 * time.Second):
t.Fatal("the unhandled event wrote no finding")
}
if _, err := js.Publish(ctx, "mesh.mod.z.event.nobody", []byte("{}")); err != nil {
t.Fatal(err)
}
if _, err := js.Publish(ctx, "mesh.mod.p.event.a", []byte("{}")); err != nil {
t.Fatal(err)
}
select {
case <-got["a"]: // the hub hands messages in order: every hook of the event before has run
case <-time.After(10 * time.Second):
t.Fatal("the handled event after the unhandled one was not heard")
}
select {
case f := <-found.put:
if summary, _ := f["summary"].(string); !strings.Contains(summary, "took 2 events") || len(found.put) != 0 {
t.Fatalf("after a second start one event is counted once: %v, and %d more", f, len(found.put))
}
default:
t.Fatal("the unhandled event after the second start wrote no finding")
}
// A hub started before the bus holds its durable says so, and binds at a later start: a module is not lost for the
// order in which the bus makes its consumer.
@@ -244,3 +319,10 @@ func TestAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
t.Run("TheViewsReaderAndTwoHandlersShareTheModulesOneDurable", subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable)
t.Run("WriterSaysItsEventsAndHearsAsksOnTheBus", subWriterSaysItsEventsAndHearsAsksOnTheBus)
}
// seenFindings is a findings writer that hands each finding written to the test.
type seenFindings struct{ put chan map[string]any }
func (f *seenFindings) WriteWire(_ context.Context, w map[string]any) error { f.put <- w; return nil }
func (f *seenFindings) Clear(context.Context, string, string, string, string) error { return nil }
func (f *seenFindings) ModuleNode() (string, string) { return "reader", "n1" }
+20 -10
View File
@@ -74,6 +74,10 @@ type adoption struct {
// further part, `<seat>.<event>.>` (design 47 G §532, §521).
func (a adoption) local() string { return a.seat + "." + a.event + ".>" }
// bare is the adopted follower's event on its bare subject, `<seat>.<event>`, heard by the same handler as local: the seat's
// contract says the event on either form (design 47 H, H-A-166).
func (a adoption) bare() string { return a.seat + "." + a.event }
func (r *Reader) logf(format string, args ...any) {
if r.Logf != nil {
r.Logf(format, args...)
@@ -316,17 +320,23 @@ func (r *Reader) begin(name string) {
r.asking[pattern] = true
ctx, f := r.ctx, r.followers[name]
handle := r.handler(ctx, pattern)
forms := []string{pattern}
if a, ok := r.adopted[name]; ok {
forms = []string{a.bare(), pattern} // one handler, both forms (H-A-166)
}
go func() {
for wait := 2 * time.Second; ; wait = min(wait*2, time.Minute) {
err := subscribe.get()(pattern, handle)
if err == nil {
break
}
r.logf("not hearing %s yet for %s's %s (%v); asking again in %s", pattern, f.Owner, f.State, err, wait)
select {
case <-ctx.Done():
return
case <-time.After(wait):
for _, form := range forms {
for wait := 2 * time.Second; ; wait = min(wait*2, time.Minute) {
err := subscribe.get()(form, handle)
if err == nil {
break
}
r.logf("not hearing %s yet for %s's %s (%v); asking again in %s", form, f.Owner, f.State, err, wait)
select {
case <-ctx.Done():
return
case <-time.After(wait):
}
}
}
r.mu.Lock()
+28 -8
View File
@@ -888,13 +888,17 @@ func subViews(t *testing.T) {
}
ready(next)
hmu.Lock()
h, n := handlers["s.revision-said.>"], len(handlers)
h, bare, n := handlers["s.revision-said.>"], handlers["s.revision-said"], len(handlers)
hmu.Unlock()
if h == nil || n != 1 {
t.Fatalf("subscriptions %v: want the event's one", handlers)
if h == nil || bare == nil || n != 2 {
t.Fatalf("subscriptions %v: want the event's bare subject and its further parts (H-A-166)", handlers)
}
// H-A-166: the event on its bare subject, as a seat's contract says it, reaches the same handler
if _ = bare(stdio.Envelope{Key: "s.revision-said", Body: []byte(`{"revision":7}`)}); len(*heard["main"]) != 1 || len(*heard["next"]) != 1 {
t.Errorf("the bare event reached %v and %v", *heard["main"], *heard["next"])
}
event := stdio.Envelope{Key: "s.revision-said.next", Body: []byte(`{"revision":8}`)}
if _ = h(event); len(*heard["main"]) != 1 || len(*heard["next"]) != 1 {
if _ = h(event); len(*heard["main"]) != 2 || len(*heard["next"]) != 2 {
t.Errorf("the event reached %v and %v", *heard["main"], *heard["next"])
}
next.WaitFor(ctx, "9")
@@ -911,7 +915,7 @@ func subViews(t *testing.T) {
if st := r.Statuses(); len(st) != 1 || st[0].State != main.State || r.Follows("s."+next.State) {
t.Errorf("first views after the drop: %+v", st)
}
if _ = h(event); len(*heard["next"]) != 1 || len(*heard["main"]) != 2 {
if _ = h(event); len(*heard["next"]) != 2 || len(*heard["main"]) != 3 {
t.Errorf("after the drop the event reached %v and %v", *heard["main"], *heard["next"])
}
if err := r.Drop("s." + next.State); err == nil {
@@ -932,7 +936,8 @@ func subViews(t *testing.T) {
t.Fatal(err)
}
ready(pn)
if !slices.Contains(pr.Hub.Patterns(), "mesh.seat.s.event.revision-other.>") {
if ps := pr.Hub.Patterns(); !slices.Contains(ps, "mesh.seat.s.event.revision-other.>") || !slices.Contains(ps, "mesh.seat.s.event.revision-other") ||
!slices.Contains(ps, "mesh.seat.s.event.revision-said") {
t.Errorf("the hub handles %v", pr.Hub.Patterns())
}
msg := func() *seatMsg {
@@ -950,8 +955,23 @@ func subViews(t *testing.T) {
t.Fatal(err)
}
m := msg()
if pr.Hear(ctx)(m); len(pfs.m) != 0 || len(pr.Followers()) != 1 || len(*heard["pnext"]) != 1 || !m.acked {
t.Errorf("after the drop: findings %v, followers %d, heard %v, acked %v", pfs.m, len(pr.Followers()), *heard["pnext"], m.acked)
if pr.Hear(ctx)(m); len(pr.Followers()) != 1 || len(*heard["pnext"]) != 1 || !m.acked {
t.Errorf("after the drop: followers %d, heard %v, acked %v", len(pr.Followers()), *heard["pnext"], m.acked)
}
// H-A-166, H-A-169: the event no handler takes, the dropped view's here, is the module's one finding event-unhandled,
// counted since the start, and the next start clears it.
if fd := pfs.next(t); fd.Kind != EventUnhandledKind || fd.ID != "reader" || !strings.Contains(fd.Summary, "took 1 events") ||
!strings.Contains(fd.Summary, m.subject) || len(pfs.m) != 1 {
t.Errorf("after the drop: findings %v, the unhandled event's %+v", pfs.m, fd)
}
pr.Hear(ctx)(&seatMsg{subject: "mesh.seat.s.event.nobody"})
if fd := pfs.next(t); !strings.Contains(fd.Summary, "took 2 events") || !strings.Contains(fd.Summary, "mesh.seat.s.event.nobody") || len(pfs.m) != 1 {
t.Errorf("the second unhandled event: findings %v, %+v", pfs.m, fd)
}
again := &ProcessReader{Module: "reader", Findings: func() WireWriter { return pfs }, Now: now, Hub: process.NewEventHub(t.Logf)}
again.Start(ctx, nil, process.Account{}, nil)
if len(pfs.m) != 0 {
t.Errorf("the start left the finding %v", pfs.m)
}
})
// Design 47 G §717: a view found by its seat starts without a holder, waits naming the seat, follows the holder the
+79 -3
View File
@@ -168,6 +168,11 @@ type WriterConfig[F, C, S, A any] struct {
// naming it, its statement carries them as `kinds` and deletes only keys of them. None given, it owns every kind.
// The kinds of a views reader (ViewKinds) are the reader's own and are always the writer's besides.
Kinds []string
// Retired are kinds no code of the part raises any more, last written by this writer (design 47 H H-A-247 (3),
// H-A-249): a held writer's Start clears their keys, saying finding-cleared so the keeper clears their conditions, and
// never seeds them; a Write of one is refused as of any kind not owned. An entry naming ids clears only the keys of
// those ids, where another writer owns the kind now.
Retired []RetiredKind
// JS is the bus connection's JetStream; Conn, when given, lets the writer hear the connection made again.
JS jetstream.JetStream
Conn *nats.Conn
@@ -212,6 +217,9 @@ type Writer[F, C, S, A any] struct {
wake chan struct{}
run context.Context
end context.CancelFunc
// said are the kinds a refusal was said of in the journal, once each (design 47 H H-A-242 (3)).
saidMu sync.Mutex
said map[string]bool
}
// NewWriter is the writer for cfg.
@@ -433,6 +441,33 @@ func (w *Writer[F, C, S, A]) loop(ctx context.Context) {
}
}
// unownedKind is the refusal of a finding kind the writer does not own (design 47 G §580, H H-A-240, H-A-242).
type unownedKind struct {
kind string
kinds []string
}
func (e *unownedKind) Error() string {
return fmt.Sprintf("finding kind %q not declared: it is not one this writer owns (%v)", e.kind, e.kinds)
}
// refuse is the refusal of kind, said in the journal the first time only (design 47 H H-A-242 (3)): a kind no writer list
// declares is a fault of the part's code, said once, never once a minute.
func (w *Writer[F, C, S, A]) refuse(kind string) error {
err := &unownedKind{kind: kind, kinds: w.cfg.Kinds}
w.saidMu.Lock()
first := !w.said[kind]
if w.said == nil {
w.said = map[string]bool{}
}
w.said[kind] = true
w.saidMu.Unlock()
if first {
w.cfg.Logf("%v: the part's code raises a kind its writer does not declare; said once", err)
}
return err
}
// owns says whether the writer's statement covers kind: every kind when none were given (design 47 G §580), else its
// own and the views reader's.
func (w *Writer[F, C, S, A]) owns(kind string) bool {
@@ -450,6 +485,38 @@ func (w *Writer[F, C, S, A]) statedKinds() []string {
}
// ownsKey says whether key is one of a kind the writer owns: its last part is the kind (`<scope>.<id>.<kind>`).
// RetiredKind is a kind a writer once wrote and no code raises any more (H-A-247 (3)). Where another writer of the same state
// owns the kind now, IDs and Prefixes name the ids this writer wrote under it, as they stand in a key (H-A-249): only a key
// whose id is one of IDs or starts with one of Prefixes is cleared. Neither given, every key of the kind is.
type RetiredKind struct {
Kind string
// Scope, when given, is the only scope whose keys the entry clears.
Scope string
IDs []string
Prefixes []string
}
// covers says whether the key of scope, id and kind is one the entry retires (H-A-249).
func (r RetiredKind) covers(scope, id, kind string) bool {
if kind != r.Kind || (r.Scope != "" && scope != r.Scope) {
return false
}
if len(r.IDs) == 0 && len(r.Prefixes) == 0 {
return true
}
return slices.Contains(r.IDs, id) || slices.ContainsFunc(r.Prefixes, func(p string) bool { return strings.HasPrefix(id, p) })
}
// retiredKey says whether key is one the writer's retired list clears (H-A-247 (3), H-A-249).
func (w *Writer[F, C, S, A]) retiredKey(key string) bool {
scope, rest, _ := strings.Cut(key, ".")
i := strings.LastIndex(rest, ".")
if i < 0 {
return false
}
return slices.ContainsFunc(w.cfg.Retired, func(r RetiredKind) bool { return r.covers(scope, rest[:i], rest[i+1:]) })
}
func (w *Writer[F, C, S, A]) ownsKey(key string) bool {
if len(w.cfg.Kinds) == 0 {
return true
@@ -523,7 +590,7 @@ func (w *Writer[F, C, S, A]) complete(finding F) (wire, wire, error) {
return f, nil, err
}
if !w.owns(str(f, "kind")) {
return f, nil, fmt.Errorf("the finding kind %q is not one this writer owns (%v)", str(f, "kind"), w.cfg.Kinds)
return f, nil, w.refuse(str(f, "kind"))
}
old, err := w.read(keyOf(f))
if err != nil {
@@ -588,10 +655,15 @@ func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
// Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said
// all the same, so a keeper holding the finding clears it (design 47 G §485).
func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
if !w.owns(kind) {
return fmt.Errorf("the finding kind %q is not one this writer owns (%v)", kind, w.cfg.Kinds)
return w.refuse(kind)
}
return w.clear(ctx, scope, id, kind, why)
}
// clear is Clear of a kind the writer may clear: its own, or a retired one at a held writer's start (H-A-247 (3)).
func (w *Writer[F, C, S, A]) clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
w.mu.Lock()
if err := w.cfg.State.Delete(key); err != nil {
w.mu.Unlock()
@@ -633,6 +705,10 @@ func (w *Writer[F, C, S, A]) stated(ctx context.Context, asked string) ([]byte,
findings, pending := []wire{}, []wire{}
for _, finding := range obs.Findings {
f, _, err := w.complete(finding)
var refused *unownedKind
if errors.As(err, &refused) {
continue // said once in the journal by refuse, never a reason to state again (design 47 H H-A-242 (3))
}
if err != nil {
return nil, err
}
+126 -2
View File
@@ -17,6 +17,26 @@ import (
"git.novox.be/novox/mesh-sdk/go/views"
)
// readState is a fakeState that names the keys read (H-A-247 (3): a held writer reads only its own keys).
type readState struct {
*fakeState
rmu sync.Mutex
got []string
}
func (s *readState) Get(key string) (*stdio.StateEntry, error) {
s.rmu.Lock()
s.got = append(s.got, key)
s.rmu.Unlock()
return s.fakeState.Get(key)
}
func (s *readState) read() []string {
s.rmu.Lock()
defer s.rmu.Unlock()
return slices.Clone(s.got)
}
// fakeState is an observer's state `findings` in memory.
type fakeState struct {
mu sync.Mutex
@@ -461,6 +481,14 @@ func subWriterKindsAndReaderFindings(t *testing.T) {
if _, ok := r.state.m["module.m=2eo=2es.view-waits"]; ok {
t.Errorf("the reader's finding was not cleared")
}
// H-A-242 (3): an observed finding of a kind the writer does not own is left out of the statement, never a reason to state
// again once a minute
r.observe = func(context.Context) (testObserved, error) {
return testObserved{Findings: []testFinding{finding("a", "observed"), other}}, nil
}
if err := r.w.State(ctx, ""); err != nil {
t.Errorf("a statement with a finding of a kind not owned: %v", err)
}
}
// A views reader's four findings are laid out by mesh-sdk through the body's setters (design 47 G §687): the finding's
@@ -637,8 +665,104 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
if held := h.Held(); len(held) != 2 {
t.Fatalf("after Start Held answers the seeded and the early: %v", held)
}
if _, ok := state.m["module.early.k"]; !ok {
t.Fatalf("the early finding was written at Start: %v", state.m)
if e, _ := state.Get("module.early.k"); e == nil {
t.Fatal("the early finding was not written at Start")
}
// Design 47 G §580, H H-A-240, H-A-242: a writer made with its kinds seeds only keys of those kinds; another bundle's key
// (kind b) is not held, so its statement is said and the key stays; a write of kind b is refused each time and said once.
owned := &fakeState{m: map[string][]byte{}}
owned.m["module.seeded.k"] = raw
other := finding("other", "another bundle's")
other.Kind = "b"
rawOther, _ := json.Marshal(other)
owned.m["module.other.b"] = rawOther
// H-A-247 (3): a retired kind's key is cleared once at Start, said as cleared, never seeded; no other bundle's key is read
gone := finding("gone", "no code raises it")
gone.Kind = "r"
rawGone, _ := json.Marshal(gone)
owned.m["module.gone.r"] = rawGone
// H-A-249: a retired entry with ids clears only those keys of its kind; the same kind's key of another writer stays
for _, id := range []string{"mine", "mine2.x", "theirs"} {
f := finding(id, "kind s")
f.Kind = "s"
rawS, _ := json.Marshal(f)
owned.m["module."+id+".s"] = rawS
}
other2 := finding("mine", "kind s in another scope")
other2.Kind, other2.Scope = "s", "machine"
rawM, _ := json.Marshal(other2)
owned.m["machine.mine.s"] = rawM
read := &readState{fakeState: owned}
var logs []string
var sent []said
ocfg := testConfig{Module: "m", State: read, Node: "n1", Asked: asked, Kinds: []string{"k"},
Retired: []views.RetiredKind{{Kind: "r"}, {Kind: "s", Scope: "module", IDs: []string{"mine"}, Prefixes: []string{"mine2."}}},
Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() },
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
mu.Lock()
sent = append(sent, said{subject, data})
mu.Unlock()
return nil
},
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }}
oh, err := views.NewHeldWriter(ocfg)
if err != nil {
t.Fatal(err)
}
// H-A-242 (3): a clear before Start of a kind the writer does not own is refused once and never stops the writer
if err := oh.Clear(ctx, "module", "early", "z", "not owned"); err != nil {
t.Fatal(err)
}
if err := oh.Start(ctx); err != nil {
t.Fatalf("a held writer given a clear of a kind it does not own did not start: %v", err)
}
defer oh.Close()
if held := oh.Held(); len(held) != 1 || held[0].Kind != "k" {
t.Fatalf("a writer of kinds [k] seeded %v", held)
}
if e, _ := owned.Get("module.gone.r"); e != nil {
t.Fatal("the retired kind's key stays after Start")
}
for key, stays := range map[string]bool{"module.mine.s": false, "module.mine2.x.s": false, "module.theirs.s": true, "machine.mine.s": true} {
if e, _ := owned.Get(key); (e != nil) != stays {
t.Errorf("after Start the key %s stands: %v, want %v", key, e != nil, stays)
}
}
mu.Lock()
clearedGone := slices.ContainsFunc(sent, func(e said) bool {
return e.subject == subjects.Cleared && strings.Contains(string(e.data), `"kind":"r"`) && strings.Contains(string(e.data), `"id":"gone"`)
})
mu.Unlock()
if !clearedGone {
t.Fatalf("the retired key's clear is not said: %v", sent)
}
if got := read.read(); slices.Contains(got, "module.other.b") || slices.Contains(got, "module.gone.r") {
t.Fatalf("Start read keys not its own: %v", got)
}
if err := oh.Write(ctx, gone); err == nil {
t.Fatal("a write of a retired kind was taken")
}
if err := oh.State(ctx, ""); err != nil {
t.Fatalf("the statement of a writer over another bundle's key: %v", err)
}
if e, _ := owned.Get("module.other.b"); e == nil {
t.Fatal("the statement deleted another bundle's key")
}
for range 2 {
if err := oh.Write(ctx, other); err == nil || !strings.Contains(err.Error(), `finding kind "b" not declared`) {
t.Fatalf("a write of kind b: %v", err)
}
}
mu.Lock()
defer mu.Unlock()
refusals := 0
for _, l := range logs {
if strings.Contains(l, `finding kind "b" not declared`) {
refusals++
}
}
if refusals != 1 {
t.Fatalf("the refusal of kind b is said %d times, not once: %v", refusals, logs)
}
}