Revert the revert of G's mesh-sdk merge (#191): G's sdk stands again over reader release 3

Main reverted G's half merge (#189, reverted by 8afc3eb in #191) and then took the reader release's S1-S5, which
copied G's code. G's form holds where they differ (process_bus.go, seats.go, state.go and their tests); the
release's kept names stay so main's callers keep building: SeatViewPrefix beside SeatReadPrefix, and QueueInvoke's
empty strings on not-ok (with its test TestQueueInvoke). The tree differs from G's head f30dee54 only by those and
the release's two tests (objects cap option, seat states and stream kinds).

Builds: design 47 G (the milestone's sdk part, as at f30dee54)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-13 12:49:56 +01:00
parent 93e0a7b50d
commit 5fa64be894
211 changed files with 32027 additions and 2484 deletions
+66
View File
@@ -0,0 +1,66 @@
package views_test
import (
"time"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Plain structs shaped as the types the seat generator emits for the seat `mesh-conditions` (design 47 G A-3): the writer
// is generic over them and works on their wire form, so the test brings the same shape, field for field.
type testSubject struct {
Also []string `json:"also,omitempty"`
ID string `json:"id"`
Machine string `json:"machine,omitempty"`
Scope string `json:"scope"`
}
type testFinding struct {
At time.Time `json:"at"`
Explanation string `json:"explanation,omitempty"`
Headline string `json:"headline,omitempty"`
ID string `json:"id"`
Kind string `json:"kind"`
Observer string `json:"observer"`
Owner string `json:"owner,omitempty"`
Run string `json:"run,omitempty"`
Scope string `json:"scope"`
Severity string `json:"severity"`
Since time.Time `json:"since"`
Source string `json:"source"`
Subject testSubject `json:"subject"`
Summary string `json:"summary"`
WaitingOn string `json:"waiting-on,omitempty"`
}
type testCleared struct {
At time.Time `json:"at"`
ID string `json:"id"`
Kind string `json:"kind"`
Scope string `json:"scope"`
Why string `json:"why"`
}
type testPending struct {
Bound string `json:"bound"`
Key string `json:"key"`
Since time.Time `json:"since"`
}
type testStated struct {
Asked string `json:"asked,omitempty"`
At time.Time `json:"at"`
Findings []testFinding `json:"findings"`
Kinds []string `json:"kinds,omitempty"`
Pending []testPending `json:"pending"`
}
type testAsked struct {
Ask string `json:"ask"`
Module string `json:"module,omitempty"`
}
type testWriter = views.Writer[testFinding, testCleared, testStated, testAsked]
type testConfig = views.WriterConfig[testFinding, testCleared, testStated, testAsked]
type testObserved = views.Observed[testFinding]
+10 -10
View File
@@ -24,12 +24,10 @@ type Emitter struct {
Publish func(ctx context.Context, msg *nats.Msg, id string) error
// Marks is the owner's state MarksState; nil says nothing is marked, and every start says from the bucket's end.
Marks jetstream.KeyValue
// TooLarge is told of a value too large for an event (said as a gap): the owner's finding naming the key. Nil
// only logs it.
TooLarge func(state, key string, size int)
// Findings writes and clears the owner's finding of a change not said past UnsaidAfter (UnsaidKind, its own state
// `findings`); nil says it in the log only.
Findings FindingWriter
// Findings is the owner's writer of its findings (its own state `findings`): the emitter writes and clears through it the
// finding of a change not said past UnsaidAfter (UnsaidKind) and writes that of a value too large for an event (TooLargeKind),
// laid out by mesh-sdk (design 47 G §687); nil says them in the log only.
Findings WireWriter
// UnsaidAfter is how long a change may stay not said before it is the owner's finding; zero is Bound.
UnsaidAfter time.Duration
// Wait pauses before a change not said is said again (its attempt so far); it answers false when ctx ended. Nil is
@@ -179,7 +177,7 @@ func (e Emitter) raiseUnsaid(state string, u jetstream.KeyValueEntry, first time
if e.Findings == nil {
return false
}
if err := e.Findings.Put(UnsaidFinding(e.Owner, state, u.Key(), u.Revision(), first, cause.Error(), e.now())); err != nil {
if err := unsaidFinding(e.Owner, state, u.Key(), u.Revision(), first, cause.Error(), e.now()).put(e.Findings); err != nil {
e.logf("views: the finding of %s's change not said could not be written: %v", state, err)
return false
}
@@ -188,7 +186,7 @@ func (e Emitter) raiseUnsaid(state string, u jetstream.KeyValueEntry, first time
// clearUnsaid clears the finding once the change is said; it answers whether it is cleared.
func (e Emitter) clearUnsaid(state string) bool {
if err := e.Findings.Delete(UnsaidFinding(e.Owner, state, "", 0, time.Time{}, "", e.now())); err != nil {
if err := unsaidFinding(e.Owner, state, "", 0, time.Time{}, "", e.now()).drop(e.Findings); err != nil {
e.logf("views: the finding of %s's change not said could not be cleared: %v", state, err)
return false
}
@@ -226,8 +224,10 @@ func (e Emitter) Event(state string, made time.Time, u jetstream.KeyValueEntry)
if n := len(u.Value()); n > MaxValueBytes {
ev.Gap = true
e.logf("views: %s.%s at %d holds %d bytes, more than an event carries: said as a gap, so a reader asks its first view", state, u.Key(), u.Revision(), n)
if e.TooLarge != nil {
e.TooLarge(state, u.Key(), n)
if e.Findings != nil {
if err := tooLargeFinding(e.Owner, state, u.Key(), n, e.now()).put(e.Findings); err != nil {
e.logf("views: the finding of %s.%s too large could not be written: %v", state, u.Key(), err)
}
}
return ev
}
+11
View File
@@ -0,0 +1,11 @@
package views
// PutViewFinding and DropViewFinding write and clear one of a views reader's findings through w, laid out as mesh-sdk lays
// the reader's own (design 47 G §687), for the tests of package views_test.
func PutViewFinding(w WireWriter, kind, id, summary, headline string) error {
return viewFinding{kind: kind, id: id, summary: summary, headline: headline}.put(w)
}
func DropViewFinding(w WireWriter, kind, id string) error {
return viewFinding{kind: kind, id: id}.drop(w)
}
+89 -42
View File
@@ -1,9 +1,13 @@
package views
import (
"cmp"
"context"
"fmt"
"strings"
"time"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// The findings a views part writes in its own state `findings`, which the condition keeper raises and clears
@@ -13,63 +17,106 @@ const (
TooLargeKind = "view-too-large"
UnsaidKind = "view-unsaid"
UnansweredKind = "first-view-unanswered"
// ViewWaitsKind is a part's finding of a view it has waited for past WaitsBound (design 47 *A part with no view says it
// waits*).
ViewWaitsKind = "view-waits"
// 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"
)
// Finding is what a views part says is wrong with a state it owns or follows, in plain fields: Kind and ID name it (a module-scoped
// finding of the observer), Summary, Headline and Explanation say it. It carries no layout: the writer a part gives
// (FindingWriter) encodes it as the condition keeper reads it, which is the seat mesh-conditions' contract, not this
// package's (novox/hq ADR 0634 §4, ADR 0635 §4).
type Finding struct {
Observer string
Kind string
ID string
Summary string
Headline string
Explanation string
At time.Time
// 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
// and headline say it. It is laid out in the wire form of the contract's finding by mesh-sdk (body, design 47 G §687, A-22) and
// written through the part's generic writer; there is no other form of it.
type viewFinding struct {
kind string
id string
summary string
headline string
at time.Time
}
// FindingWriter writes and clears a part's findings in its own state `findings`, where the condition keeper raises and
// clears conditions from them (novox/hq ADR 0564 §2): the part gives the one that encodes a Finding as that state's layout.
type FindingWriter interface {
Put(f Finding) error
Delete(f Finding) error
// WireWriter is what a views part's findings use of the part's finding writer, whatever the contract's body types: the
// generic Writer[F, C, S, A] is one (design 47 G §639, §687, A-22).
type WireWriter interface {
WriteWire(ctx context.Context, finding map[string]any) error
Clear(ctx context.Context, scope, id, kind, why string) error
ModuleNode() (module, node string)
}
// UnsaidFinding is the owner's finding of a change of state it has not said on its views family since since: every
// reader of the state stands still at the change before it until it is said, which clears this.
func UnsaidFinding(owner, state, key string, revision uint64, since time.Time, cause string, at time.Time) Finding {
id := owner + "." + state
// FindingScope is the scope of a views reader's findings: they are findings of the part's module (design 47 G §687).
const FindingScope = "module"
// body lays the finding out on its wire form (design 47 G §687): `kind` the finding's, `scope` module, `id` the finding's id
// escaped as a key's name is, `severity` warning but urgent for view-too-large, `source` views, `subject` the part's module on
// its node, `summary` and `headline` the finding's texts.
func (f viewFinding) body(module, node string) map[string]any {
sev := "warning"
if f.kind == TooLargeKind {
sev = "urgent"
}
subject := map[string]any{"scope": FindingScope, "id": module}
if node != "" {
subject["machine"] = node
}
b := map[string]any{"kind": f.kind, "scope": FindingScope, "id": keys.EscapeName(f.id), "severity": sev, "source": "views",
"subject": subject, "summary": f.summary}
if f.headline != "" {
b["headline"] = f.headline
}
if !f.at.IsZero() {
b["at"] = f.at
}
return b
}
// put writes the finding through w; drop clears it.
func (f viewFinding) put(w WireWriter) error {
module, node := w.ModuleNode()
return w.WriteWire(context.Background(), f.body(module, node))
}
func (f viewFinding) drop(w WireWriter) error {
return w.Clear(context.Background(), FindingScope, keys.EscapeName(f.id), f.kind, "the part no longer observes it")
}
func unsaidFinding(owner, state, key string, revision uint64, since time.Time, cause string, at time.Time) viewFinding {
summary := fmt.Sprintf("%s has not said the change of %s.%s at %d on its views family since %s (%s): its readers stand still before it",
owner, state, key, revision, since.UTC().Format(time.RFC3339), strings.TrimSpace(cause))
return finding(owner, UnsaidKind, id, summary,
fmt.Sprintf("%s cannot say a change of its %s", owner, state),
"The owner says each change of its state as an event on its own stream, and says a change again until the bus takes it; "+
"its readers hear nothing newer meanwhile. Look at the owner's stream on the bus: is it full, or is the bus away?", at)
return viewFinding{kind: UnsaidKind, id: owner + "." + state, summary: summary, headline: fmt.Sprintf("%s cannot say a change of its %s", owner, state), at: at.UTC()}
}
// TooLargeFinding is the owner's finding of state's key too large to say whole on its views family.
func TooLargeFinding(owner, state, key string, size int, at time.Time) Finding {
id := owner + "." + state + "." + key
func tooLargeFinding(owner, state, key string, size int, at time.Time) viewFinding {
summary := fmt.Sprintf("%s's %s.%s holds %d bytes, more than one views event carries (%d): every reader asks its first view again at each change of it", owner, state, key, size, MaxValueBytes)
return finding(owner, TooLargeKind, id, summary,
fmt.Sprintf("A value of %s is too large for its views event", owner),
"Each change of this key is said as a gap, so every reader of the state asks the owner's first view once more. "+
"It works, but costs a first view per change; the value should be made smaller or split.", at)
return viewFinding{kind: TooLargeKind, id: owner + "." + state + "." + key, summary: summary, headline: fmt.Sprintf("A value of %s is too large for its views event", owner), at: at.UTC()}
}
// UnansweredFinding is a reader's finding of its first view of s unanswered past its bound (ADR 0615 §6): it names the
// owner and the tool. A first view answered at revision 0 with nothing in it is said too, with the operator's step.
func UnansweredFinding(reader string, s Status, at time.Time) Finding {
id := reader + "." + s.Owner + "." + s.State
func unansweredFinding(reader string, s Status, at time.Time) viewFinding {
summary := fmt.Sprintf("%s has no first view of %s's %s: %s has not answered since %s (%s)", reader, s.Owner, s.State, s.Tool,
s.Asked.Format(time.RFC3339), strings.TrimSpace(s.Error))
return finding(reader, UnansweredKind, id, summary,
fmt.Sprintf("%s waits for %s", reader, s.Owner),
fmt.Sprintf("%s reads %s's %s only through %s, and keeps asking it; it never reads the state itself. The answer clears this. "+
"Look at %s's runtime of its own: is it running and connected?", reader, s.Owner, s.State, s.Tool, s.Owner), at)
return viewFinding{kind: UnansweredKind, id: reader + "." + s.Owner + "." + s.State, summary: summary, headline: fmt.Sprintf("%s waits for %s", reader, s.Owner), at: at.UTC()}
}
func finding(observer, kind, id, summary, headline, explanation string, at time.Time) Finding {
return Finding{Observer: observer, Kind: kind, ID: id, Summary: summary, Headline: headline, Explanation: explanation, At: at.UTC()}
func viewWaitsFinding(part string, s Status, at time.Time) viewFinding {
summary := fmt.Sprintf("%s waits for the view %s.%s at revision %s since %s and acts on nothing new until it holds it; it holds %s",
part, s.Owner, s.State, s.WaitsFor, s.WaitingSince.UTC().Format(time.RFC3339), cmp.Or(s.View, "none"))
if s.WaitsFor == HolderWait {
summary = seatWaitsSummary(part, s) // a seat's view with no holder yet (design 47 G §717)
}
return viewFinding{kind: ViewWaitsKind, id: part + "." + s.Owner + "." + s.State, summary: summary, headline: fmt.Sprintf("%s waits for a view of %s", part, s.Owner), at: at.UTC()}
}
// WriteEntryNotFound writes the part's finding that the catalog holds no entry for fingerprint, asked since `since`
// (design 47 G A-103); ClearEntryNotFound clears it, when nothing the part holds names the fingerprint or a later ask answers.
func WriteEntryNotFound(w WireWriter, fingerprint string, since, at time.Time) error {
module, _ := w.ModuleNode()
return viewFinding{kind: EntryNotFoundKind, id: fingerprint,
summary: fmt.Sprintf("%s holds a build of fingerprint %s that the catalog holds no entry for (asked since %s): what it needs of the entry stands still",
module, fingerprint, since.UTC().Format(time.RFC3339)),
headline: fmt.Sprintf("%s cannot find the catalog entry of a build", module), at: at.UTC()}.put(w)
}
// ClearEntryNotFound clears the finding WriteEntryNotFound wrote for fingerprint.
func ClearEntryNotFound(w WireWriter, fingerprint string) error {
return viewFinding{kind: EntryNotFoundKind, id: fingerprint}.drop(w)
}
+87 -1
View File
@@ -7,6 +7,7 @@ import (
"fmt"
"maps"
"slices"
"strings"
"sync"
"time"
@@ -30,6 +31,10 @@ type Follower struct {
// nothing.
Raise func(Status)
Clear func(Status)
// RaiseWaits and ClearWaits are the part's view-waits finding: written past WaitsBound of a WaitFor, cleared when it
// Holds the view. Nil says nothing.
RaiseWaits func(Status)
ClearWaits func(Status)
// Changed is told of each key the picture changes (deleted: the key is gone), after the change is held, with when the
// owner's bus wrote it: the event's time, or for a key a first view brought the time its answer says (Answer.Written;
// zero when the owner does not say it, and for a key the first view no longer holds).
@@ -87,6 +92,80 @@ type Status struct {
// Why is the last reason it asked (start, a gap and which, a hand act) or why the last ask failed.
Why string `json:"why,omitempty"`
Error string `json:"error,omitempty"`
// View is the revision of the revision view the part holds from this first view, as its seat's client names it
// (design 47 *A part with no view says it waits*); WaitsFor the one it waits for and acts on nothing new until it
// holds, since WaitingSince; WaitsRaised says its view-waits finding is written (past WaitsBound).
View string `json:"view,omitempty"`
WaitsFor string `json:"waits-for,omitempty"`
WaitingSince time.Time `json:"waiting-since,omitzero"`
WaitsRaised bool `json:"waits-raised,omitempty"`
}
// WaitsBound is how long a part waits for a view before it writes its finding view-waits (design 47): the bound the seat
// list's readers keep, so an owner down for a restart raises nothing.
const WaitsBound = 5 * time.Minute
// waitBound waits d within ctx: true when d passed, false when ctx ended first. A variable so a test ends it at once.
var waitBound = swappable(func(ctx context.Context, d time.Duration) bool {
b, cancel := context.WithTimeout(ctx, d)
defer cancel()
<-b.Done()
return ctx.Err() == nil
})
// NoneYet is what a seat's revision verb answers for a branch with no revision yet (design 47 G §479, §495): that view
// is ready and empty, and nothing waits for it.
const NoneYet = "none yet"
// WaitFor says the part waits for view, a revision of the revision view its seat's client names, and acts on nothing
// new until it holds it (Holds): the status says what and since when, and if it still waits for it past WaitsBound,
// RaiseWaits is told (the part writes view-waits, ViewWaitsFinding). Waiting for the view it waits for already changes
// nothing, not even since when.
func (f *Follower) WaitFor(ctx context.Context, view string) {
f.mu.Lock()
f.init()
if f.st.WaitsFor == view || view == "" || view == NoneYet {
f.mu.Unlock()
return
}
f.st.WaitsFor, f.st.WaitingSince, f.st.WaitsRaised = view, f.now(), false
s := f.st
f.mu.Unlock()
f.logf("views: %s waits for %s's view %s, from %s", f.Tool, f.Owner, view, s.WaitingSince.Format(time.RFC3339))
f.say(s)
go func() {
if !waitBound.get()(ctx, WaitsBound) {
return
}
f.mu.Lock()
raise := f.st.WaitsFor == view && !f.st.WaitsRaised
if raise {
f.st.WaitsRaised = true
}
s := f.st
f.mu.Unlock()
if raise {
f.logf("views: %s has waited for %s's view %s since %s", f.Tool, f.Owner, view, s.WaitingSince.Format(time.RFC3339))
if f.RaiseWaits != nil {
f.RaiseWaits(s)
}
f.say(s)
}
}()
}
// Holds says the part holds view now: it waits no more, and a raised view-waits is cleared (ClearWaits).
func (f *Follower) Holds(view string) {
f.mu.Lock()
f.init()
raised := f.st.WaitsRaised
f.st.View, f.st.WaitsFor, f.st.WaitingSince, f.st.WaitsRaised = view, "", time.Time{}, false
s := f.st
f.mu.Unlock()
if raised && f.ClearWaits != nil {
f.ClearWaits(s)
}
f.say(s)
}
func (f *Follower) now() time.Time {
@@ -475,7 +554,7 @@ func Hear(ctx context.Context, followers map[string]*Follower, logf func(string,
// HearEvent is Hear for one event given as its data, for a reader that takes the owner's events by another path than
// a consumer of its own (the tool runner's): routed to the follower of its state, an event of a state it does not
// follow passed over, and a gap asked once more on its own goroutine as a gap, never as a hand ask (Gap). Data that is
// follow passed over (a per-branch state's event goes by the first token of its key, §521), and a gap asked once more on its own goroutine as a gap, never as a hand ask (Gap). Data that is
// not a views event is answered as an error, and nothing is asked.
func HearEvent(ctx context.Context, followers map[string]*Follower, data []byte, logf func(string, ...any)) error {
ev, err := DecodeEvent(data)
@@ -483,6 +562,13 @@ func HearEvent(ctx context.Context, followers map[string]*Follower, data []byte,
return err
}
f := followers[ev.State]
if f == nil && ev.Key != "" {
// A per-branch state's event names the state as its owner declares it and the key `<branch>.<revision>`: it goes to
// the view `<state>.<branch>` of the key's first token, the branch escaped as a key's name is (design 47 G §521).
if branch, _, ok := strings.Cut(ev.Key, "."); ok && branch != "" {
f = followers[ev.State+"."+branch]
}
}
if f == nil {
logf("views: %s's %s is a state this reader does not follow: event at revision %d passed over", ev.Owner, ev.State, ev.Revision)
return nil
+308
View File
@@ -0,0 +1,308 @@
package views
// A view found by its seat (design 47 G §717): a part follows a state of the module holding a seat, the holder read from
// the seat-holders view through the holder function the part is given (A-295, A-298), so no code names the holder and a
// moved holder is followed as it moves. Nothing is asked on a timer: the holder is read again at each change of a view the
// reader follows, the seat-holders view among them.
import (
"context"
"encoding/json"
"errors"
"fmt"
"maps"
"sync"
"time"
)
// HolderWait is what a seat's view waits for while it follows no holder (design 47 G §717): its status's WaitsFor, and
// past WaitsBound the reader's view-waits finding names the seat and the state.
const HolderWait = "a holder of the seat"
// seatFollow is one seat's view: the picture the part reads (its follower names the seat, never asks) and the holder's
// view it hands on.
type seatFollow struct {
seat, state string
holders func(seat string) []string
pic *Picture
kick chan struct{}
running bool
mu sync.Mutex
holder string // the holder followed now, "" for none
inner *Picture // its view
cancel context.CancelFunc // ends the wait for its first view
handed *Picture // the view whose state the picture holds
}
// FollowSeat follows state of the module holding seat (design 47 G §717): it returns at once a picture that reads as empty,
// its follower not ready, and never fails for want of a holder. At each change of a view the reader follows (the
// seat-holders view the holder function answers from among them) it reads the seat's first holder: on a first holder it
// follows as Follow does after Start, the first view asked of `<holder>.<state>`, then its views family; on another holder
// it drops the old one's view and follows the new one, the picture handing on the new holder's state whole once its first
// view arrives; with no holder it keeps the picture it has and follows nothing. While no holder's first view is held the
// follower's status names the seat, waiting for HolderWait since the start or since its holder left, and past WaitsBound
// the reader writes view-waits naming the seat and the state, cleared when a holder's first view arrives. The picture's
// bus name is `<seat>_<state>` (KeyValue opens it). A seat's state followed already is its picture.
func (r *ProcessReader) FollowSeat(seat, state string, holders func(seat string) []string) (*Picture, error) {
if seat == "" || state == "" || holders == nil {
return nil, errors.New("views: a seat's view names its seat and state, and the holder function that answers its holder")
}
bucket := seat + "_" + state
r.mu.Lock()
if sw := r.seats[bucket]; sw != nil {
r.mu.Unlock()
return sw.pic, nil
}
sw := &seatFollow{seat: seat, state: state, holders: holders, kick: make(chan struct{}, 1)}
p := &Picture{bucket: bucket, ctx: context.Background()}
sf := &Follower{Owner: seat, Tool: "seat:" + seat + "." + state, State: state, Logf: r.Logf, Now: r.Now, Changed: p.changed}
sf.RaiseWaits = func(s Status) {
if r.holdsSeat(sw) {
r.waits(s, true)
}
}
sf.ClearWaits = func(s Status) { r.waits(s, false) }
p.f, sw.pic = sf, p
if r.seats == nil {
r.seats = map[string]*seatFollow{}
}
r.seats[bucket] = sw
asked := r.asked
r.mu.Unlock()
if asked {
r.runSeat(sw)
}
return p, nil
}
// holdsSeat says whether sw is still a seat's view of the reader.
func (r *ProcessReader) holdsSeat(sw *seatFollow) bool {
r.mu.Lock()
defer r.mu.Unlock()
return r.seats[sw.pic.bucket] == sw
}
// runSeat starts sw's reading of its holder once the reader asks (Ask): its wait from the start, then a read at once and at
// each change told (seatsChanged).
func (r *ProcessReader) runSeat(sw *seatFollow) {
r.mu.Lock()
if sw.running || !r.asked {
r.mu.Unlock()
return
}
sw.running = true
ctx, said := r.ctx, r.said
r.mu.Unlock()
sw.pic.f.Said = func(s Status) {
if said != nil && sw.waiting() {
said(s)
}
}
sw.pic.f.WaitFor(ctx, HolderWait)
go func() {
for {
r.reread(ctx, sw)
select {
case <-ctx.Done():
return
case <-sw.kick:
}
}
}()
}
// seatsChanged tells every seat's view to read its holder again, without blocking (a view's change is told outside its
// follower's lock, but may be told often: one read stands for many).
func (r *ProcessReader) seatsChanged() {
r.mu.Lock()
defer r.mu.Unlock()
for _, sw := range r.seats {
select {
case sw.kick <- struct{}{}:
default:
}
}
}
// waiting says whether no holder's first view is held: the seat's own status is said only then.
func (sw *seatFollow) waiting() bool {
sw.mu.Lock()
defer sw.mu.Unlock()
return sw.handed == nil
}
// reread reads the seat's first holder and follows it when it is another than the one followed.
func (r *ProcessReader) reread(ctx context.Context, sw *seatFollow) {
holder := ""
if hs := sw.holders(sw.seat); len(hs) > 0 {
holder = hs[0]
}
sw.mu.Lock()
old, cancel := sw.holder, sw.cancel
if holder == old {
sw.mu.Unlock()
return
}
sw.holder, sw.inner, sw.cancel, sw.handed = "", nil, nil, nil
sw.mu.Unlock()
if old != "" {
cancel()
if err := r.Drop(old, sw.state); err != nil {
r.logf("views: %s's view of %s's %s is not dropped: %v", r.Module, old, sw.state, err)
}
r.logf("views: %s no longer follows %s's %s: the seat %s holder is now %q", r.Module, old, sw.state, sw.seat, holder)
}
if holder == "" {
// the picture is kept; the wait is since the holder left
sw.pic.f.WaitFor(ctx, HolderWait)
return
}
inner, fresh, err := r.follow(holder, sw.state, holder+"."+sw.state)
if err != nil || !fresh {
r.logf("views: %s does not follow %s's %s for the seat %s: %v", r.Module, holder, sw.state, sw.seat, cmpErr(err, "followed already apart from the seat"))
return
}
own := inner.f.Changed
inner.f.Changed = func(key string, value json.RawMessage, deleted bool, at time.Time) {
own(key, value, deleted, at)
r.apply(sw, inner, key, value, deleted, at)
}
ictx, icancel := context.WithCancel(ctx)
sw.mu.Lock()
sw.holder, sw.inner, sw.cancel = holder, inner, icancel
sw.mu.Unlock()
r.logf("views: %s follows %s's %s, the holder of the seat %s", r.Module, holder, sw.state, sw.seat)
r.begin(inner.bucket)
go func() {
select {
case <-ictx.Done():
case <-inner.f.Ready():
r.hand(sw, inner)
}
}()
}
func cmpErr(err error, words string) error {
if err != nil {
return err
}
return errors.New(words)
}
// apply takes one change of the holder's view into the seat's picture, once its state was handed on whole.
func (r *ProcessReader) apply(sw *seatFollow, inner *Picture, key string, value json.RawMessage, deleted bool, at time.Time) {
sw.mu.Lock()
if sw.inner != inner {
sw.mu.Unlock()
return
}
if sw.handed != inner {
sw.mu.Unlock()
r.hand(sw, inner) // its first view: the state whole, this change in it
return
}
defer sw.mu.Unlock()
sf := sw.pic.f
sf.mu.Lock()
if deleted {
delete(sf.values, key)
} else {
sf.values[key] = value
}
changed := sf.Changed
sf.mu.Unlock()
if changed != nil {
changed(key, value, deleted, at)
}
}
// hand takes the holder's state whole into the seat's picture at its first view: each key it changes is told, each key the
// old holder had that the new lacks is told deleted, the picture is ready, and the wait for a holder is cleared.
func (r *ProcessReader) hand(sw *seatFollow, inner *Picture) {
sw.mu.Lock()
if sw.inner != inner || sw.handed == inner {
sw.mu.Unlock()
return
}
select {
case <-inner.f.Ready():
default:
sw.mu.Unlock()
return
}
sw.handed = inner
holder := sw.holder
values := inner.f.Values()
sf := sw.pic.f
sf.mu.Lock()
sf.init()
old := sf.values
sf.values = maps.Clone(values)
select {
case <-sf.ready:
default:
close(sf.ready)
}
changed := sf.Changed
sf.mu.Unlock()
if changed != nil {
for k, v := range values {
if ov, ok := old[k]; !ok || string(ov) != string(v) {
changed(k, v, false, time.Time{})
}
}
for k := range old {
if _, ok := values[k]; !ok {
changed(k, nil, true, time.Time{})
}
}
}
sw.mu.Unlock()
sf.Holds(holder)
r.logf("views: %s holds %s's %s, the holder of the seat %s", r.Module, holder, sw.state, sw.seat)
r.mu.Lock()
status := r.status
r.mu.Unlock()
if key := StatusKey(sw.seat, sw.state); status != nil && key != StatusKey(holder, sw.state) {
if kv := status.KV(); kv != nil {
if err := kv.Delete(context.Background(), key); err != nil {
r.logf("views: the waiting status %s is not removed from %s: %v", key, StatusState, err)
}
}
}
}
// HolderBucket is the bus name `<holder>_<state>` of the holder whose state FollowSeat follows now for seat, "" while it
// follows none (design 47 G A-303): the name a part uses where another part names the holder's real bucket (a key the
// watchman writes, a name kept in an entry), read at each use, so a moved holder is named as it moves.
func (r *ProcessReader) HolderBucket(seat, state string) string {
r.mu.Lock()
sw := r.seats[seat+"_"+state]
r.mu.Unlock()
if sw == nil {
return ""
}
sw.mu.Lock()
defer sw.mu.Unlock()
if sw.holder == "" {
return ""
}
return sw.holder + "_" + state
}
// seatPicture is the picture of a seat's view by its bus name, nil when none.
func (r *ProcessReader) seatPicture(bucket string) *Picture {
r.mu.Lock()
defer r.mu.Unlock()
if sw := r.seats[bucket]; sw != nil {
return sw.pic
}
return nil
}
// seatWaitsSummary is the view-waits words of a seat's view that follows no holder yet.
func seatWaitsSummary(part string, s Status) string {
return fmt.Sprintf("%s waits for a module holding the seat %s, to follow its view %s, since %s",
part, s.Owner, s.State, s.WaitingSince.UTC().Format(time.RFC3339))
}
+185
View File
@@ -0,0 +1,185 @@
package views
import (
"context"
"encoding/json"
"errors"
"sort"
"sync"
)
// HeldWriter is the finding writer of a part whose findings are raised as they happen, not judged afresh (design 47 G A-29,
// §686): it holds the findings it has written, seeded from the keys of its state `findings` before it starts, under a lock of
// its own (never the part's: the writer calls Observe under its own lock while the part writes under its), and its Observe
// answers them, so a statement says exactly what the part holds. Write and Clear update the held set and then the writer's.
// It is a Writer[F, C, S, A] with that Observe, so no part writes the adapter.
type HeldWriter[F, C, S, A any] struct {
*Writer[F, C, S, A]
mu sync.Mutex
held map[string]F
state FindingState
started bool
pending map[string]F // written before Start, written through the writer at Start
cleared map[string][4]string // cleared before Start, cleared through the writer at Start
// pends are the keys the part cannot judge yet since its start (design 47 G §384): a kept call it has not yet made
// again, named in every statement until the part judges it.
pends map[string]PendingKey
}
// NewHeldWriter makes the writer for cfg, whose Observe is none (a given Observe is refused): the findings that stand in
// cfg.State are read at once, each key's value as the writer kept it (a value that is no finding of F is left to the next
// statement, which deletes its key when it is of a kind the writer owns).
func NewHeldWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*HeldWriter[F, C, S, A], error) {
if cfg.Observe != nil {
return nil, errors.New("a held finding writer observes what it holds: it takes no Observe")
}
if cfg.State == nil {
return nil, errors.New("a finding writer needs the state `findings`")
}
h := &HeldWriter[F, C, S, A]{held: map[string]F{}, pends: map[string]PendingKey{}}
h.state, h.pending, h.cleared = cfg.State, map[string]F{}, map[string][4]string{}
cfg.Observe = func(context.Context) (Observed[F], error) {
h.mu.Lock()
defer h.mu.Unlock()
var o Observed[F]
for _, f := range h.held {
o.Findings = append(o.Findings, f)
}
for _, p := range h.pends {
o.Pending = append(o.Pending, p)
}
sort.Slice(o.Pending, func(i, j int) bool { return o.Pending[i].Key < o.Pending[j].Key })
return o, nil
}
w, err := NewWriter(cfg)
if err != nil {
return nil, err
}
h.Writer = w
return h, nil
}
// Write holds the finding and writes it through the writer.
func (h *HeldWriter[F, C, S, A]) Write(ctx context.Context, finding F) error {
m, err := wireOf(&finding)
if err != nil {
return err
}
if err := CheckFinding(m); err != nil {
return err
}
if !h.Writer.owns(str(m, "kind")) {
return h.Writer.Write(ctx, finding) // refused by the writer, naming the kind, and held no more than it is
}
h.mu.Lock()
h.held[keyOf(m)] = finding
if !h.started {
h.pending[keyOf(m)] = finding
delete(h.cleared, keyOf(m))
h.mu.Unlock()
return nil
}
h.mu.Unlock()
return h.Writer.Write(ctx, finding)
}
// Clear stops holding the finding of scope, id and kind and clears it through the writer.
func (h *HeldWriter[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
h.mu.Lock()
k := FindingKey(scope, id, kind)
delete(h.held, k)
if !h.started {
delete(h.pending, k)
h.cleared[k] = [4]string{scope, id, kind, why}
h.mu.Unlock()
return nil
}
h.mu.Unlock()
return h.Writer.Clear(ctx, scope, id, kind, why)
}
// WriteWire is Write of a finding in its wire form, held as Write holds it (design 47 G A-37): a views reader writing through
// the held writer has its findings in the held set, so in the statement.
func (h *HeldWriter[F, C, S, A]) WriteWire(ctx context.Context, finding map[string]any) error {
var f F
if err := fillFrom(&f, finding); err != nil {
return err
}
return h.Write(ctx, f)
}
// Pend names a key the part cannot judge yet since its start, with its since and its bound, in every statement until Judged
// (design 47 G §384; design 46 7-approval-mark §16: an acted ask whose hand-act is not yet asked again). A key pended again
// keeps its first since.
func (h *HeldWriter[F, C, S, A]) Pend(p PendingKey) {
h.mu.Lock()
defer h.mu.Unlock()
if was, ok := h.pends[p.Key]; ok {
p.Since = was.Since
}
h.pends[p.Key] = p
}
// Judged ends a key's pending: the part judged it, raising or clearing its finding as it found.
func (h *HeldWriter[F, C, S, A]) Judged(key string) {
h.mu.Lock()
defer h.mu.Unlock()
delete(h.pends, key)
}
// Held answers the findings the writer holds, a copy taken under its lock (design 47 G A-38), so a part reads its open findings
// from the writer.
func (h *HeldWriter[F, C, S, A]) Held() []F {
h.mu.Lock()
defer h.mu.Unlock()
out := make([]F, 0, len(h.held))
for _, f := range h.held {
out = append(out, 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.
func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
keys, err := h.state.Keys()
if err != nil {
return err
}
h.mu.Lock()
for _, k := range keys {
e, err := h.state.Get(k)
if err != nil {
h.mu.Unlock()
return err
}
if _, ok := h.held[k]; ok {
continue
}
if _, ok := h.cleared[k]; ok {
continue
}
var f F
if e == nil || json.Unmarshal(e.Value, &f) != nil {
continue
}
if m, err := wireOf(&f); err == nil && keyOf(m) == k {
h.held[k] = f
}
}
pending, cleared := h.pending, h.cleared
h.started, h.pending, h.cleared = true, nil, nil
h.mu.Unlock()
for _, f := range pending {
if err := h.Writer.Write(ctx, f); err != nil {
return err
}
}
for _, c := range cleared {
if err := h.Writer.Clear(ctx, c[0], c[1], c[2], c[3]); err != nil {
return err
}
}
return h.Writer.Start(ctx)
}
+44
View File
@@ -0,0 +1,44 @@
package views
import (
"context"
"encoding/json"
"os"
"git.novox.be/novox/mesh-sdk/go/process"
)
// OwnBuildKey is where a process keeps its own build in its state `first-views`, and the field both answers of a part's
// first views carry beside their list (design 47 G §674, §424, §519): the fingerprint the node-engine composed into
// the part's environment, or OwnBuildUnknown when it carries none.
const OwnBuildKey = "own-build"
// OwnBuildUnknown is what a part's first views say of its own build when its environment carries no fingerprint.
const OwnBuildUnknown = "unknown"
func ownBuildWord(b process.Build) string {
if b.Fingerprint == "" {
return OwnBuildUnknown
}
return b.Fingerprint
}
// ownBuild is the build this reader's bundle was composed with, read from its environment at each answer.
func (r *Reader) ownBuild() process.Build {
getenv := r.Getenv
if getenv == nil {
getenv = os.Getenv
}
return process.ReadOwnBuild(getenv)
}
// KeepOwnBuild writes a process's own build at OwnBuildKey of kv (its state `first-views`) at its start, for its tools
// bundle's status tool to read (design 47 G §674).
func KeepOwnBuild(ctx context.Context, kv interface {
Put(ctx context.Context, key string, value []byte) (uint64, error)
}, b process.Build, logf func(string, ...any)) {
data, _ := json.Marshal(ownBuildWord(b))
if _, err := kv.Put(ctx, OwnBuildKey, data); err != nil && logf != nil {
logf("views: the own build is not kept in %s: %v", StatusState, err)
}
}
+369 -37
View File
@@ -14,6 +14,7 @@ import (
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"strings"
"sync"
@@ -35,7 +36,7 @@ type ProcessReader struct {
Call func(key string, body any) (json.RawMessage, error)
// Findings is the reader's own state `findings`, where the condition keeper raises and clears the condition of a
// first view unanswered past its bound (ADR 0615 §6); nil says it in the log only.
Findings func() FindingWriter
Findings func() WireWriter
Logf func(string, ...any)
// Now, Bound and Wait are for tests: zero are the clock, Bound and five seconds.
Now func() time.Time
@@ -55,6 +56,29 @@ type ProcessReader struct {
mu sync.Mutex
pics map[string]*Picture // by bucket name <owner>_<state>
order []string
// adopted are the handlers of the adopted followers' seat events (Adopt), by the event's subject.
// Several followers adopt one event (two branches' views of the catalog half), each hearing it (design 47 G §532).
adopted map[string][]adoptedHear
// seats are the views found by their seat (FollowSeat), by their picture's bus name <seat>_<state> (design 47 G §717).
seats map[string]*seatFollow
// After Start and Ask (design 47 G §532): the hub the reader's events come through when it is the module's (Hub) and
// its handler, the time the bus made the consumer, the asks' life and Said, and of each first view begun, the cancel
// of its asks, by bucket; status is the state `first-views` each status is kept in.
hub *process.EventHub
handle func(jetstream.Msg)
created time.Time
ctx context.Context
said func(Status)
asked bool
begun map[string]context.CancelFunc
status *process.AwaitedBucket
}
// adoptedHear is one adopted follower's handler of its seat event, by its picture's bucket.
type adoptedHear struct {
bucket string
hear func(context.Context, []byte) error
}
func (r *ProcessReader) logf(format string, args ...any) {
@@ -66,19 +90,28 @@ func (r *ProcessReader) logf(format string, args ...any) {
// Follow adds the owner's state to follow, as the owner declares it (design 25 § 12.2): tool is its ordinary read tool
// of state as the reader's `invokes` names it (`<owner>.<tool>`, from the owner's manifest's tools). The owner's changes
// are ordinary events (`<owner>.views.<state>`), which the reader's manifest `consumes` one entry per followed state.
// views names no owner: the caller gives it. Call it before Start.
// views names no owner: the caller gives it. Called after Start, the view takes its first view at once and then follows
// (design 47 G §532).
func (r *ProcessReader) Follow(owner, state, tool string) (*Picture, error) {
p, fresh, err := r.follow(owner, state, tool)
if err == nil && fresh {
r.begin(p.bucket)
}
return p, err
}
func (r *ProcessReader) follow(owner, state, tool string) (*Picture, bool, error) {
r.mu.Lock()
defer r.mu.Unlock()
if owner == "" || state == "" || !strings.HasPrefix(tool, owner+".") {
return nil, fmt.Errorf("%s follows %s's %s by its read tool <owner>.<tool>, not %q", r.Module, owner, state, tool)
return nil, false, fmt.Errorf("%s follows %s's %s by its read tool <owner>.<tool>, not %q", r.Module, owner, state, tool)
}
if r.pics == nil {
r.pics = map[string]*Picture{}
}
bucket := owner + "_" + state
if p := r.pics[bucket]; p != nil {
return p, nil
return p, false, nil
}
p := &Picture{bucket: bucket, ctx: context.Background()}
call := r.Call
@@ -94,13 +127,173 @@ func (r *ProcessReader) Follow(owner, state, tool string) (*Picture, error) {
return call(key, m)
}, tool)
p.f = &Follower{Owner: owner, Tool: tool, State: state, Ask: ask, Logf: r.Logf, Now: r.Now, Bound: r.Bound, Wait: r.Wait,
Raise: func(s Status) { r.finding(s, true) }, Clear: func(s Status) { r.finding(s, false) },
Changed: p.changed}
Raise: func(s Status) {
if r.holds(p) {
r.finding(s, true)
}
}, Clear: func(s Status) { r.finding(s, false) },
Changed: func(key string, value json.RawMessage, deleted bool, at time.Time) {
p.changed(key, value, deleted, at)
r.seatsChanged() // a seat's view reads its holder again (§717)
}}
r.pics[bucket] = p
r.order = append(r.order, bucket)
return p, true, nil
}
// holds says whether p is still a picture of the reader: a dropped view writes no finding after its drop cleared them.
func (r *ProcessReader) holds(p *Picture) bool {
r.mu.Lock()
defer r.mu.Unlock()
return r.pics[p.bucket] == p
}
// FollowBranch is Follow for a state kept per branch: the view of one branch is named `<owner>.<state>.<branch>` (the
// branch escaped as a key's name is, BranchState) and its picture `<owner>_<state>.<branch>`, so a process follows
// several branches of one state, each its own view (design 47 G §479). Called after Start, it begins at once (§532).
func (r *ProcessReader) FollowBranch(owner, state, branch, tool string) (*Picture, error) {
return r.Follow(owner, BranchState(state, branch), tool)
}
// Adopt takes a follower a seat's client made (its Ask a seat's verb, such as the catalog half's view) as one of the
// process's first views, so the client's callers write no glue: the reader sets its conditions (the unanswered first
// view and view-waits, in the reader's findings), its log and clock, and its picture (`<owner>_<state>`) hands each
// change on before the follower's own Changed, set before. Start keeps its status, hears its hand asks, and asks it with
// the others; its events are the seat's event (seatdef's EventSubject of seat and event, on the module's durable
// consumer, as its `consumes` names it), handed to hear, the client's handler, and acknowledged; a state followed already
// is refused. Adopted after Start, as a part adopts a watched branch added while it runs, the view takes its first view
// at once and then follows (design 47 G §532).
func (r *ProcessReader) Adopt(f *Follower, seat, event string, hear func(context.Context, []byte) error) (*Picture, error) {
if f == nil || f.Owner == "" || f.State == "" || seat == "" || event == "" || hear == nil {
return nil, errors.New("views: an adopted follower names its owner and state, and its seat's event and handler")
}
p, subject, err := r.adopt(f, seat, event, hear)
if err != nil {
return nil, err
}
r.mu.Lock()
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 {
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)
}
}
r.begin(p.bucket)
return p, nil
}
// AdoptEvent hears a seat's event on the one subscription the followers adopted on that event share, with no picture and no
// first view (design 47 G A-185, A-199): hear is handed each message of the event beside every adopted follower's handler,
// and the message is acknowledged, unless hear fails: then it is left unacknowledged and the bus asks again (A-222). The subscription is made at once when no follower made it, so a part that follows no
// view of the seat still hears the event; adopted before Start, it is made at Start.
func (r *ProcessReader) AdoptEvent(seat, event string, hear func(context.Context, []byte) error) error {
if seat == "" || event == "" || hear == nil {
return errors.New("views: an adopted event names its seat, its event and its handler")
}
subject := "mesh.seat." + seat + ".event." + event
r.mu.Lock()
if r.adopted == nil {
r.adopted = map[string][]adoptedHear{}
}
fresh := len(r.adopted[subject]) == 0
r.adopted[subject] = append(r.adopted[subject], adoptedHear{hear: hear})
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 {
r.logf("views: %s's event %s is not heard (%v)", r.Module, subject, err)
}
}
return nil
}
// adopt is Adopt's part under the lock; subject is the event's subject when no follower adopted it before.
func (r *ProcessReader) adopt(f *Follower, seat, event string, hear func(context.Context, []byte) error) (*Picture, string, error) {
r.mu.Lock()
defer r.mu.Unlock()
if r.pics == nil {
r.pics = map[string]*Picture{}
}
bucket := f.Owner + "_" + f.State
if r.pics[bucket] != nil {
return nil, "", fmt.Errorf("views: %s's %s is followed already", f.Owner, f.State)
}
p := &Picture{bucket: bucket, ctx: context.Background(), f: f}
if f.Logf == nil {
f.Logf = r.Logf
}
if f.Now == nil {
f.Now = r.Now
}
if f.Bound == 0 {
f.Bound = r.Bound
}
if f.Wait == 0 {
f.Wait = r.Wait
}
f.Raise, f.Clear = func(s Status) {
if r.holds(p) {
r.finding(s, true)
}
}, func(s Status) { r.finding(s, false) }
f.RaiseWaits, f.ClearWaits = func(s Status) {
if r.holds(p) {
r.waits(s, true)
}
}, func(s Status) { r.waits(s, false) }
own := f.Changed
f.Changed = func(key string, value json.RawMessage, deleted bool, at time.Time) {
p.changed(key, value, deleted, at)
if own != nil {
own(key, value, deleted, at)
}
r.seatsChanged() // a seat's view reads its holder again (§717)
}
r.pics[bucket] = p
r.order = append(r.order, bucket)
if r.adopted == nil {
r.adopted = map[string][]adoptedHear{}
}
subject := "mesh.seat." + seat + ".event." + event
fresh := len(r.adopted[subject]) == 0
r.adopted[subject] = append(r.adopted[subject], adoptedHear{bucket: bucket, hear: hear})
if !fresh {
subject = ""
}
return p, subject, nil
}
// waits writes (raised) or clears the reader's view-waits finding of s (design 47 *A part with no view says it waits*).
func (r *ProcessReader) waits(s Status, raised bool) {
if raised {
r.logf("%s has waited for %s's view %s since %s", r.Module, s.Owner, s.WaitsFor, s.WaitingSince.Format(time.RFC3339))
}
if r.Findings == nil {
return
}
kv := r.Findings()
if kv == nil {
return
}
at := time.Now()
if r.Now != nil {
at = r.Now()
}
f := viewWaitsFinding(r.Module, s, at)
var err error
if raised {
err = f.put(kv)
} else {
err = f.drop(kv)
}
if err != nil {
r.logf("views: the view-waits finding of %s is not written: %v", s.Tool, err)
}
}
// Picture is the picture of the bucket the process used to bind, by its bus name (`<owner>_<state>`); nil when not
// followed.
func (r *ProcessReader) Picture(bucket string) *Picture {
@@ -113,6 +306,9 @@ func (r *ProcessReader) Picture(bucket string) *Picture {
// as buildrun.FollowPlacement takes it); any other bucket is refused, for the reader reads its owners' states by their
// first views alone.
func (r *ProcessReader) KeyValue(_ context.Context, bucket string) (jetstream.KeyValue, error) {
if p := r.seatPicture(bucket); p != nil {
return p, nil
}
if p := r.Picture(bucket); p != nil {
return p, nil
}
@@ -145,12 +341,12 @@ func (r *ProcessReader) finding(s Status, raised bool) {
if r.Now != nil {
at = r.Now()
}
f := UnansweredFinding(r.Module, s, at)
f := unansweredFinding(r.Module, s, at)
var err error
if raised {
err = kv.Put(f)
err = f.put(kv)
} else {
err = kv.Delete(f)
err = f.drop(kv)
}
if err != nil {
r.logf("views: the finding of the first view %s is not written: %v", s.Tool, err)
@@ -159,26 +355,42 @@ func (r *ProcessReader) finding(s Status, raised bool) {
// Hear is the handler of the module's durable consumer on the shared events stream (cred.EventConsumer on
// process.EventsStream): an owner's views event (`mesh.mod.<owner>.event.views.<state>`) goes to the follower of that
// owner's state, any other message to Other.
// owner's state, any other message to Other. The followers are read at each message, so a view followed or adopted
// after Start hears its events and a dropped one no longer does (design 47 G §532).
func (r *ProcessReader) Hear(ctx context.Context) func(jetstream.Msg) {
fs := map[string]map[string]*Follower{}
for _, f := range r.Followers() {
if fs[f.Owner] == nil {
fs[f.Owner] = map[string]*Follower{}
}
fs[f.Owner][f.State] = f
}
views := map[string]func(jetstream.Msg){}
for owner, m := range fs {
views[owner] = Hear(ctx, m, r.logf)
}
return func(m jetstream.Msg) {
if owner, ok := OwnerOfEvent(m.Subject()); ok {
if h := views[owner]; h != nil {
h(m)
return
r.mu.Lock()
hears := adoptedHears(r.adopted, m.Subject())
var owned map[string]*Follower
if owner, ok := OwnerOfEvent(m.Subject()); ok && hears == nil {
for _, b := range r.order {
if f := r.pics[b].f; f.Owner == owner {
if owned == nil {
owned = map[string]*Follower{}
}
owned[f.State] = f
}
}
}
r.mu.Unlock()
if hears != nil {
failed := false
for _, h := range hears {
if err := h.hear(ctx, m.Data()); err != nil {
r.logf("views: %s is not taken: %v", m.Subject(), err)
// an event adopted with no picture is asked again by the bus (design 47 G A-222)
failed = failed || h.bucket == ""
}
}
if !failed {
_ = m.Ack()
}
return
}
if owned != nil {
Hear(ctx, owned, r.logf)(m)
return
}
if r.Other != nil {
r.Other(m)
return
@@ -201,18 +413,100 @@ func (r *ProcessReader) Owners() []string {
}
// Ask asks every first view until answered, each on a goroutine of its own, so the process starts at once and waits for
// an owner that is down, saying so (ADR 0615 §6). Said, when set, keeps each status (KeepStatus).
// an owner that is down, saying so (ADR 0615 §6). Said, when set, keeps each status (KeepStatus). A view followed or
// adopted after it is asked at once (design 47 G §532).
func (r *ProcessReader) Ask(ctx context.Context, said func(Status)) {
for _, f := range r.Followers() {
if said != nil {
f.Said = said
}
go func() {
if err := f.Start(ctx); err != nil {
r.logf("the first view %s was not answered: %v", f.Tool, err)
}
}()
r.mu.Lock()
r.ctx, r.said, r.asked = ctx, said, true
buckets := slices.Clone(r.order)
seats := slices.Collect(maps.Values(r.seats))
r.mu.Unlock()
for _, b := range buckets {
r.begin(b)
}
for _, sw := range seats {
r.runSeat(sw)
}
}
// begin asks bucket's first view once Ask ran, on a goroutine of its own, until answered or the view is dropped.
func (r *ProcessReader) begin(bucket string) {
r.mu.Lock()
p := r.pics[bucket]
if !r.asked || p == nil || r.begun[bucket] != nil {
r.mu.Unlock()
return
}
if r.begun == nil {
r.begun = map[string]context.CancelFunc{}
}
ctx, cancel := context.WithCancel(r.ctx)
r.begun[bucket] = cancel
f, said, created := p.f, r.said, r.created
r.mu.Unlock()
if said != nil {
f.Said = func(s Status) {
if r.holds(p) {
said(s)
}
}
}
if !created.IsZero() {
f.ConsumerMade(ctx, created)
}
go func() {
if err := f.Start(ctx); err != nil && ctx.Err() == nil {
r.logf("the first view %s was not answered: %v", f.Tool, err)
}
}()
}
// Drop ends the view of owner's state, as a part drops a watched branch removed while it runs (design 47 G §532, §614):
// it asks it no more and hears none of its events, its status leaves the state `first-views` and so its row leaves
// `<module>_first_views`, and every finding it raised (its unanswered first view, its view-waits) is cleared through
// the reader's findings, the drop and each cleared finding said in the log. A state not followed is an error.
func (r *ProcessReader) Drop(owner, state string) error {
bucket := owner + "_" + state
r.mu.Lock()
p := r.pics[bucket]
if p == nil {
r.mu.Unlock()
return fmt.Errorf("%s does not follow %s's %s", r.Module, owner, state)
}
cancel := r.begun[bucket]
delete(r.pics, bucket)
delete(r.begun, bucket)
r.order = slices.DeleteFunc(r.order, func(b string) bool { return b == bucket })
for subject, hs := range r.adopted {
if hs = slices.DeleteFunc(hs, func(h adoptedHear) bool { return h.bucket == bucket }); len(hs) == 0 {
delete(r.adopted, subject)
} else {
r.adopted[subject] = hs
}
}
status := r.status
r.mu.Unlock()
if cancel != nil {
cancel()
}
r.logf("views: %s drops its view %s.%s", r.Module, owner, state)
if status != nil {
if kv := status.KV(); kv != nil {
if err := kv.Delete(context.Background(), StatusKey(owner, state)); err != nil {
r.logf("views: the status of the dropped view %s.%s is not removed from %s: %v", owner, state, StatusState, err)
}
}
}
s := p.f.Status()
if s.Raised {
r.finding(s, false)
r.logf("views: %s clears its finding %s of the dropped view %s.%s", r.Module, UnansweredKind, owner, state)
}
if s.WaitsRaised {
r.waits(s, false)
r.logf("views: %s clears its finding %s of the dropped view %s.%s", r.Module, ViewWaitsKind, owner, state)
}
return nil
}
// Ready is closed once every followed state had its first view.
@@ -546,11 +840,33 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
hub, pattern, own = process.NewEventHub(r.logf), ">", true
}
hub.OnBound(func(created time.Time) {
r.mu.Lock()
r.created = created
r.mu.Unlock()
for _, f := range r.Followers() {
f.ConsumerMade(ctx, created)
}
})
err := hub.Handle(pattern, r.Hear(ctx))
hear := r.Hear(ctx)
err := hub.Handle(pattern, hear)
r.mu.Lock()
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
r.hub, r.handle = hub, hear
}
r.mu.Unlock()
if !own {
r.mu.Lock()
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)
}
}
}
if err == nil && own {
err = hub.Start(ctx, js, cred)
}
@@ -561,7 +877,8 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
var said func(Status)
if status != nil {
status.Ready(func(kv jetstream.KeyValue) {
if err := HearAgain(ctx, kv, r.Followers(), r.logf); err != nil {
KeepOwnBuild(ctx, kv, process.OwnBuild(), r.logf)
if err := hearAgain(ctx, kv, r.Followers, r.logf); err != nil {
r.logf("views: the hand asks of %s's first views are not heard (%v) until it starts again", r.Module, err)
}
})
@@ -573,3 +890,18 @@ func (r *ProcessReader) Start(ctx context.Context, js jetstream.JetStream, cred
}
r.Ask(ctx, said)
}
// 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 {
if h := adopted[subject]; h != nil {
return h
}
for i := strings.LastIndex(subject, "."); i > 0; i = strings.LastIndex(subject, ".") {
subject = subject[:i]
if h := adopted[subject]; h != nil {
return h
}
}
return nil
}
+25 -3
View File
@@ -5,6 +5,7 @@ package views_test
import (
"context"
"encoding/json"
"errors"
"fmt"
"testing"
"time"
@@ -21,7 +22,7 @@ import (
// An owner's change is an ordinary event on the shared events stream (novox/hq ADR 0635 §5): a reader that follows the
// owner's state by its read tool hears it on the module's durable consumer of that stream, with no stream of the owner's,
// and a message that is no views event goes to Other.
func TestAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
func subAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
nc, err := nats.Connect(testbus.URL(t))
if err != nil {
t.Fatal(err)
@@ -51,7 +52,11 @@ func TestAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
if _, err := r.Follow("o", "modules", "o.o_read_modules"); err != nil {
t.Fatal(err)
}
r.Start(ctx, js, cred, nil)
statusKV, err := js.CreateKeyValue(ctx, jetstream.KeyValueConfig{Bucket: "reader_first-views", Storage: jetstream.MemoryStorage})
if err != nil {
t.Fatal(err)
}
r.Start(ctx, js, cred, process.AwaitBucket(ctx, js, nil, "reader_first-views", "", t.Logf))
<-r.Ready()
pic, err := r.KeyValue(ctx, "o_modules")
if err != nil {
@@ -115,12 +120,22 @@ func TestAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
if s := f.Status(); s.Asks != 1 {
t.Errorf("the reader asked its first view %d times across the bursts (%s): a revision written over was taken as a gap", s.Asks, s.Why)
}
// G §532, §614: a dropped view's status leaves the state first-views, and so its row of <module>_first_views.
if _, err := statusKV.Get(ctx, views.StatusKey("o", "modules")); err != nil {
t.Fatalf("the status was not kept: %v", err)
}
if err := r.Drop("o", "modules"); err != nil {
t.Fatal(err)
}
if _, err := statusKV.Get(ctx, views.StatusKey("o", "modules")); !errors.Is(err, jetstream.ErrKeyNotFound) {
t.Errorf("the dropped view's status is still kept: %v", err)
}
}
// A module has one durable consumer on the shared events stream, so the loops that hear events in one module must share
// one pull (process.EventHub): two handlers and the views reader on the hub each get their own messages and no other's,
// and a message nobody takes is acknowledged.
func TestTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
func subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
nc, err := nats.Connect(testbus.URL(t))
if err != nil {
t.Fatal(err)
@@ -222,3 +237,10 @@ func TestTheViewsReaderAndTwoHandlersShareTheModulesOneDurable(t *testing.T) {
t.Fatal("the hub started late heard nothing")
}
}
// TestAReaderHearsAnOwnersChangesAsOrdinaryEvents runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
func TestAReaderHearsAnOwnersChangesAsOrdinaryEvents(t *testing.T) {
t.Run("AReaderHearsAnOwnersChangesAsOrdinaryEvents", subAReaderHearsAnOwnersChangesAsOrdinaryEvents)
t.Run("TheViewsReaderAndTwoHandlersShareTheModulesOneDurable", subTheViewsReaderAndTwoHandlersShareTheModulesOneDurable)
t.Run("WriterSaysItsEventsAndHearsAsksOnTheBus", subWriterSaysItsEventsAndHearsAsksOnTheBus)
}
+367 -62
View File
@@ -3,13 +3,17 @@ package views
import (
"context"
"encoding/json"
"errors"
"fmt"
"maps"
"slices"
"sort"
"strings"
"sync"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
)
// Reader is a module's pictures of the owners' states it used to read (novox/hq ADR 0615 §1): it
@@ -22,25 +26,54 @@ type Reader struct {
Module string
// Findings writes and clears this module's finding of an unanswered first view (its own state `findings`); nil
// says it in the log only.
Findings FindingWriter
Findings WireWriter
Logf func(string, ...any)
rows map[string]func() any // the lists Rows added to the first views (guarded by mu)
// Changed is told of each key a followed state changes, after the picture holds it (state is `<owner>.<state>`).
Changed func(state, key string, value json.RawMessage, deleted bool)
// Acts records a re-read by hand before it is asked (nil records nothing
// and the re-read is refused).
Acts HandActs
// Now, Bound and Wait are for tests: zero are the clock, Bound and five seconds.
Now func() time.Time
Bound time.Duration
Wait time.Duration
// Now, Bound, Wait and Getenv are for tests: zero are the clock, Bound, five seconds and os.Getenv.
Getenv func(string) string
Now func() time.Time
Bound time.Duration
Wait time.Duration
mu sync.Mutex
followers map[string]*Follower // by "<owner>.<state>"
order []string
byOwner map[string]map[string]*Follower // owner -> state -> follower
watchers map[string][]func(key string, value []byte, gone bool)
// adopted are the followers a seat's client made (Adopt), by "<owner>.<state>": their events are a seat's, heard by
// the client's own handler, not an owner's views family.
adopted map[string]adoption
// events is, of each per-branch view (FollowBranch), by "<owner>.<state>.<branch>", the state as its owner's events name it (§521).
events map[string]string
// After Start (design 47 G §532): the reader's life, the event patterns whose subscription is taken (heard) or being
// asked (asking), and of each first view begun, the cancel of its asks, by "<owner>.<state>".
ctx context.Context
started bool
heard map[string]bool
asking map[string]bool
begun map[string]context.CancelFunc
}
// subscribe is how the reader asks the runtime for an event pattern; a variable so a test hears without a runtime.
var subscribe = swappable(stdio.Subscribe)
// adoption is how an adopted follower's events are heard: the seat's event, by its local name, and the client's handler.
type adoption struct {
seat, event string
hear func(context.Context, []byte) error
}
// local is an adopted follower's event as the stdio runtime subscribes it: one subscription per event with every
// further part, `<seat>.<event>.>` (design 47 G §532, §521).
func (a adoption) local() string { return a.seat + "." + a.event + ".>" }
func (r *Reader) logf(format string, args ...any) {
if r.Logf != nil {
r.Logf(format, args...)
@@ -48,8 +81,16 @@ func (r *Reader) logf(format string, args ...any) {
}
// Follow adds a state of an owner to follow, asked through the owner's read tool (`<module>.<tool>`, as the reader's
// `invokes` names it), with `values` so the answer is the first view. Call it before Start.
// `invokes` names it), with `values` so the answer is the first view. Called after Start, the view takes its first view
// at once and then follows (design 47 G §532).
func (r *Reader) Follow(owner, state, tool string) *Follower {
f := r.follow(owner, state, tool, "")
r.begin(owner + "." + f.State)
return f
}
// follow is Follow without beginning it: event, when given, is the state as the owner's events name it (FollowBranch).
func (r *Reader) follow(owner, state, tool, event string) *Follower {
r.mu.Lock()
defer r.mu.Unlock()
if r.followers == nil {
@@ -68,9 +109,96 @@ func (r *Reader) Follow(owner, state, tool string) *Follower {
}
return DecodeAnswer(raw)
}
f.Raise = func(s Status) { r.raise(s) }
r.wireLocked(name, f, nil)
if event != "" {
if r.events == nil {
r.events = map[string]string{}
}
r.events[name] = event
}
return f
}
// BranchState is the name of a per-branch state's view: `<state>.<branch>`, the branch escaped as a key's name is (design
// 47 G §479), so a reader names the view `<owner>.<state>.<branch>`. A state that is not per branch keeps its name.
func BranchState(state, branch string) string { return state + "." + keys.EscapeName(branch) }
// FollowBranch is Follow for a state kept per branch: the view of one branch is named `<owner>.<state>.<branch>`
// (BranchState), so a reader follows several branches of one state, each its own view and its own row of
// `<module>_first_views` (design 47 G §479). Called after Start, the view takes its first view at once and then follows
// (§532).
func (r *Reader) FollowBranch(owner, state, branch, tool string) *Follower {
f := r.follow(owner, BranchState(state, branch), tool, state)
r.begin(owner + "." + f.State)
return f
}
// Adopt takes a follower a seat's client made (its Ask a seat's verb, such as the catalog half's view) as one of the
// reader's first views, so the client's callers write no glue: the reader sets its conditions (the unanswered first view
// and view-waits, in the reader's findings), its log and clock, and hands each change to Watch, Changed and the
// follower's own Changed, set before; Keys, Get, Values, Watch, Statuses and the two tools name it `<owner>.<state>`.
// Its events are the seat's event (`<seat>.<event>`, as the reader's `consumes` names it), which Start subscribes and
// hands to hear, the client's handler; a state followed already is refused. Adopted after Start, as a part adopts a
// watched branch added while it runs, the view takes its first view at once and then follows (design 47 G §532).
func (r *Reader) Adopt(f *Follower, seat, event string, hear func(context.Context, []byte) error) error {
if f == nil || f.Owner == "" || f.State == "" || seat == "" || event == "" || hear == nil {
return errors.New("views: an adopted follower names its owner and state, and its seat's event and handler")
}
if err := r.adopt(f, seat, event, hear); err != nil {
return err
}
r.begin(f.Owner + "." + f.State)
return nil
}
func (r *Reader) adopt(f *Follower, seat, event string, hear func(context.Context, []byte) error) error {
r.mu.Lock()
defer r.mu.Unlock()
if r.followers == nil {
r.followers, r.byOwner = map[string]*Follower{}, map[string]map[string]*Follower{}
}
name := f.Owner + "." + f.State
if r.followers[name] != nil {
return fmt.Errorf("views: %s is followed already", name)
}
if f.Logf == nil {
f.Logf = r.Logf
}
if f.Now == nil {
f.Now = r.Now
}
if f.Bound == 0 {
f.Bound = r.Bound
}
if f.Wait == 0 {
f.Wait = r.Wait
}
r.wireLocked(name, f, f.Changed)
if r.adopted == nil {
r.adopted = map[string]adoption{}
}
r.adopted[name] = adoption{seat: seat, event: event, hear: hear}
return nil
}
// wireLocked makes f one of the reader's first views under name: its conditions are the reader's, and each change goes
// to the watchers, Changed and own (the follower's own Changed, or nil). The caller holds mu.
func (r *Reader) wireLocked(name string, f *Follower, own func(string, json.RawMessage, bool, time.Time)) {
// A view dropped writes no finding after its drop cleared them (Drop).
held := func() bool { r.mu.Lock(); defer r.mu.Unlock(); return r.followers[name] == f }
f.Raise = func(s Status) {
if held() {
r.raise(s)
}
}
f.Clear = func(s Status) { r.clear(s) }
f.Changed = func(key string, value json.RawMessage, deleted bool, _ time.Time) {
f.RaiseWaits = func(s Status) {
if held() {
r.waits(s, true)
}
}
f.ClearWaits = func(s Status) { r.waits(s, false) }
f.Changed = func(key string, value json.RawMessage, deleted bool, at time.Time) {
r.mu.Lock()
ws := append([]func(string, []byte, bool){}, r.watchers[name]...)
r.mu.Unlock()
@@ -80,14 +208,36 @@ func (r *Reader) Follow(owner, state, tool string) *Follower {
if r.Changed != nil {
r.Changed(name, key, value, deleted)
}
if own != nil {
own(key, value, deleted, at)
}
}
r.followers[name] = f
r.order = append(r.order, name)
if r.byOwner[owner] == nil {
r.byOwner[owner] = map[string]*Follower{}
if r.byOwner[f.Owner] == nil {
r.byOwner[f.Owner] = map[string]*Follower{}
}
r.byOwner[f.Owner][f.State] = f
}
// waits writes (raised) or clears the reader's view-waits finding of s (design 47 *A part with no view says it waits*).
func (r *Reader) waits(s Status, raised bool) {
if raised {
r.logf("%s has waited for %s's view %s since %s", r.Module, s.Owner, s.WaitsFor, s.WaitingSince.Format(time.RFC3339))
}
if r.Findings == nil {
return
}
f := viewWaitsFinding(r.Module, s, r.nowTime())
var err error
if raised {
err = f.put(r.Findings)
} else {
err = f.drop(r.Findings)
}
if err != nil {
r.logf("the view-waits finding of %s is not written: %v", s.Tool, err)
}
r.byOwner[owner][state] = f
return f
}
func (r *Reader) nowTime() time.Time {
@@ -102,7 +252,7 @@ func (r *Reader) raise(s Status) {
if r.Findings == nil {
return
}
if err := r.Findings.Put(UnansweredFinding(r.Module, s, r.nowTime())); err != nil {
if err := unansweredFinding(r.Module, s, r.nowTime()).put(r.Findings); err != nil {
r.logf("the finding of the unanswered first view %s could not be written: %v", s.Tool, err)
}
}
@@ -111,51 +261,209 @@ func (r *Reader) clear(s Status) {
if r.Findings == nil {
return
}
if err := r.Findings.Delete(UnansweredFinding(r.Module, s, r.nowTime())); err != nil {
if err := unansweredFinding(r.Module, s, r.nowTime()).drop(r.Findings); err != nil {
r.logf("the finding of the first view %s could not be cleared: %v", s.Tool, err)
}
}
// Start subscribes each owner's views family (the module's `consumes`: `<owner>.views.<state>`) and asks every first
// view until it is answered, each on a goroutine of its own, so a module starts at once and a reader whose owner is down
// waits, saying so (ADR 0615 §6). It returns when the subscriptions are taken.
// waits, saying so (ADR 0615 §6). It returns when the subscriptions are asked. A view followed or adopted after it is
// begun the same way, and Drop ends one (design 47 G §532).
func (r *Reader) Start(ctx context.Context) {
r.mu.Lock()
r.ctx, r.started = ctx, true
names := append([]string(nil), r.order...)
r.mu.Unlock()
for _, name := range names {
f := r.followers[name]
go func() {
for wait := 2 * time.Second; ; wait = min(wait*2, time.Minute) {
err := stdio.Subscribe(f.Owner+"."+EventName(f.State), r.hear(ctx, f))
if err == nil {
break
}
r.logf("not hearing %s's %s events yet (%v); asking again in %s", f.Owner, f.State, err, wait)
select {
case <-ctx.Done():
return
case <-time.After(wait):
}
}
if err := f.Start(ctx); err != nil {
r.logf("the first view %s was not answered: %v", f.Tool, err)
}
}()
r.begin(name)
}
}
// patternLocked is the event pattern a followed state's events come on: one subscription per pattern, the followers of
// a per-branch state sharing the owner's one event, which HearEvent routes to the branch's view by the key's first token
// (§521). The caller holds mu.
func (r *Reader) patternLocked(name string) string {
if a, ok := r.adopted[name]; ok {
return a.local()
}
f := r.followers[name]
if state, ok := r.events[name]; ok {
return f.Owner + "." + EventName(state)
}
return f.Owner + "." + EventName(f.State)
}
// begin starts the first view of name once the reader started: at once when its event pattern is heard, else once its
// subscription is taken, which it asks when none is asked yet, so no event said after the first view is missed.
func (r *Reader) begin(name string) {
r.mu.Lock()
defer r.mu.Unlock()
if !r.started || r.followers[name] == nil {
return
}
pattern := r.patternLocked(name)
if r.heard[pattern] {
r.askLocked(name)
return
}
if r.asking[pattern] {
return
}
if r.asking == nil {
r.asking, r.heard = map[string]bool{}, map[string]bool{}
}
r.asking[pattern] = true
ctx, f := r.ctx, r.followers[name]
handle := r.handler(ctx, pattern)
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):
}
}
r.mu.Lock()
defer r.mu.Unlock()
r.heard[pattern] = true
for _, n := range r.order {
if r.patternLocked(n) == pattern {
r.askLocked(n)
}
}
}()
}
// askLocked asks name's first view on a goroutine of its own, once, until answered or the view is dropped. The caller
// holds mu.
func (r *Reader) askLocked(name string) {
if r.begun[name] != nil {
return
}
if r.begun == nil {
r.begun = map[string]context.CancelFunc{}
}
ctx, cancel := context.WithCancel(r.ctx)
r.begun[name] = cancel
f := r.followers[name]
go func() {
if err := f.Start(ctx); err != nil && ctx.Err() == nil {
r.logf("the first view %s was not answered: %v", f.Tool, err)
}
}()
}
// handler is the handler of one event pattern: the followers on it are read at each event, so a view adopted after the
// subscription hears it and a dropped one no longer does. An event the adopted followers on it hear goes to each
// client's handler; otherwise HearEvent routes it to its state's view.
func (r *Reader) handler(ctx context.Context, pattern string) func(stdio.Envelope) error {
return func(e stdio.Envelope) error {
r.mu.Lock()
var fs []*Follower
for _, n := range r.order {
if r.patternLocked(n) == pattern {
fs = append(fs, r.followers[n])
}
}
adopted := maps.Clone(r.adopted)
r.mu.Unlock()
if h := r.hearAdoptedBy(ctx, fs, adopted); h != nil {
return h(e)
}
return r.hear(ctx, fs)(e)
}
}
// Drop ends the view of state (`<owner>.<state>`), as a part drops a watched branch removed while it runs (design 47 G
// §532, §614): it asks it no more and hears none of its events, its row leaves `<module>_first_views`, and every finding
// it raised (its unanswered first view, its view-waits) is cleared through the reader's findings, the drop and each
// cleared finding said in the log. A state not followed is an error.
func (r *Reader) Drop(state string) error {
r.mu.Lock()
f := r.followers[state]
if f == nil {
r.mu.Unlock()
return fmt.Errorf("%s is not a state this module follows", state)
}
cancel := r.begun[state]
delete(r.followers, state)
delete(r.begun, state)
delete(r.adopted, state)
delete(r.events, state)
delete(r.watchers, state)
r.order = slices.DeleteFunc(r.order, func(n string) bool { return n == state })
if byState := r.byOwner[f.Owner]; byState[f.State] == f {
delete(byState, f.State)
}
r.mu.Unlock()
if cancel != nil {
cancel()
}
r.logf("views: %s drops its view %s", r.Module, state)
s := f.Status()
if s.Raised {
r.clear(s)
r.logf("views: %s clears its finding %s of the dropped view %s", r.Module, UnansweredKind, state)
}
if s.WaitsRaised {
r.waits(s, false)
r.logf("views: %s clears its finding %s of the dropped view %s", r.Module, ViewWaitsKind, state)
}
return nil
}
// hear is the handler of one followed state's events: HearEvent routes it, and a gap asks that first view once more as a
// gap, said in the log.
func (r *Reader) hear(ctx context.Context, f *Follower) func(stdio.Envelope) error {
func (r *Reader) hear(ctx context.Context, fs []*Follower) func(stdio.Envelope) error {
byState := map[string]*Follower{}
for _, f := range fs {
byState[f.State] = f
}
return func(e stdio.Envelope) error {
if err := HearEvent(ctx, map[string]*Follower{f.State: f}, e.Body, r.logf); err != nil {
if err := HearEvent(ctx, byState, e.Body, r.logf); err != nil {
r.logf("views: %s is not a views event, dropped: %v", e.Key, err)
}
return nil
}
}
// hearAdoptedBy is the handler of an event every adopted follower of fs hears, never the first alone (two branches' views
// of the catalog half share one event, design 47 G §532); nil when none of fs is adopted.
func (r *Reader) hearAdoptedBy(ctx context.Context, fs []*Follower, adopted map[string]adoption) func(stdio.Envelope) error {
var heard []func(stdio.Envelope) error
for _, f := range fs {
if a, ok := adopted[f.Owner+"."+f.State]; ok {
heard = append(heard, r.hearAdopted(ctx, a))
}
}
if len(heard) == 0 {
return nil
}
return func(e stdio.Envelope) error {
for _, h := range heard {
_ = h(e)
}
return nil
}
}
// hearAdopted is the handler of an adopted follower's seat event: the client's handler takes it, and what it cannot read is
// said in the log.
func (r *Reader) hearAdopted(ctx context.Context, a adoption) func(stdio.Envelope) error {
return func(e stdio.Envelope) error {
if err := a.hear(ctx, e.Body); err != nil {
r.logf("views: %s is not taken: %v", e.Key, err)
}
return nil
}
}
// Ready is closed once every followed state had its first view.
func (r *Reader) Ready() <-chan struct{} {
r.mu.Lock()
@@ -269,13 +577,36 @@ func (r *Reader) Statuses() []Status {
return out
}
// Rows adds a list the part's `<prefix>_first_views` says beside the views' statuses, under name (design 47 G A-103: the
// entries by fingerprint the catalog half's follower keeps). rows is called at each reading.
func (r *Reader) Rows(name string, rows func() any) {
r.mu.Lock()
defer r.mu.Unlock()
if r.rows == nil {
r.rows = map[string]func() any{}
}
r.rows[name] = rows
}
// firstViews is what `<prefix>_first_views` answers: the views' statuses and each list added by Rows.
func (r *Reader) firstViews() map[string]any {
out := map[string]any{"views": r.Statuses(), OwnBuildKey: ownBuildWord(r.ownBuild())}
r.mu.Lock()
rows := maps.Clone(r.rows)
r.mu.Unlock()
for name, f := range rows {
out[name] = f()
}
return out
}
// Tools are the reader's two tools (design 25 § 12.2): `<prefix>_first_views` says where each first view stands and
// `<prefix>_first_view_again` asks one again by hand (a hand act, counted in the status).
func (r *Reader) Tools(prefix string) []stdio.Tool {
return []stdio.Tool{
{Name: prefix + "_first_views",
Description: "Where each first view this module keeps stands (novox/hq ADR 0615): the owner and its tool, the revision the picture holds, when it was asked and answered, how many asks (by hand among them) and whether its condition is raised. (r)",
Run: func(map[string]any) (any, error) { return map[string]any{"views": r.Statuses()}, nil }},
Run: func(map[string]any) (any, error) { return r.firstViews(), nil }},
{Name: prefix + "_first_view_again",
Description: "Ask a first view again by hand, for the state named (<owner>.<state>), or every one with none: a hand act, for a picture the operator doubts. Answers where it stands after. (a)",
Input: map[string]any{"type": "object", "properties": map[string]any{
@@ -310,29 +641,3 @@ func (r *Reader) Tools(prefix string) []stdio.Tool {
}},
}
}
// OwnFindings writes a reader's findings into its own state `findings` through its runtime, where the condition keeper
// raises and clears conditions from them: the Findings of a Reader whose module keeps the state `findings`. Encode is
// the module's: it turns a Finding into the state's key and value as the seat mesh-conditions' contract lays them out.
type OwnFindings struct {
Encode func(Finding) (key string, value []byte, err error)
}
// Put writes one finding.
func (o OwnFindings) Put(f Finding) error {
key, value, err := o.Encode(f)
if err != nil {
return err
}
_, err = stdio.State("findings").Put(key, json.RawMessage(value))
return err
}
// Delete clears one finding.
func (o OwnFindings) Delete(f Finding) error {
key, _, err := o.Encode(f)
if err != nil {
return err
}
return stdio.State("findings").Delete(key)
}
+26 -4
View File
@@ -51,6 +51,12 @@ func KeepStatus(ctx context.Context, kv jetstream.KeyValue, logf func(string, ..
// HearAgain takes each hand ask written at an AgainKey of kv, those standing at the start included, asks that
// follower's first view again with the ask's words and who asked, and deletes the ask. It returns once the watch is set.
func HearAgain(ctx context.Context, kv jetstream.KeyValue, followers []*Follower, logf func(string, ...any)) error {
return hearAgain(ctx, kv, func() []*Follower { return followers }, logf)
}
// hearAgain is HearAgain over the followers as they are at each ask, so a view adopted after the start is asked again by
// hand too (design 47 G §532).
func hearAgain(ctx context.Context, kv jetstream.KeyValue, current func() []*Follower, logf func(string, ...any)) error {
w, err := kv.Watch(ctx, "again.>")
if err != nil {
return err
@@ -74,6 +80,7 @@ func HearAgain(ctx context.Context, kv jetstream.KeyValue, followers []*Follower
_ = kv.Delete(ctx, e.Key())
continue
}
followers := current()
i := slices.IndexFunc(followers, func(f *Follower) bool { return f.Owner == a.Owner && f.State == a.State })
if i < 0 {
logf("views: the hand ask %s names no first view this part holds", e.Key())
@@ -90,18 +97,26 @@ func HearAgain(ctx context.Context, kv jetstream.KeyValue, followers []*Follower
return nil
}
// keptStatus is what the tools use of the state `first-views` (a stdio.KeptState is one).
type keptStatus interface {
Keys() ([]string, error)
Get(key string) (*stdio.StateEntry, error)
Put(key string, value any) (uint64, error)
}
// StatusTools are a reader's read tool of its first views (read) and its re-read tool (again), in its tools bundle,
// over its StatusState: read lists what the process last said of each; again writes a hand ask the process takes,
// naming the caller the runtime proved, and is recorded in the status's by-hand count and why. again is a hand act:
// acts records it before the ask is written, and one that is not taken is said and nothing is asked (nil acts
// record nothing, so again refuses).
func StatusTools(reader, read, again string, st stdio.KeptState, acts HandActs, now func() time.Time) []stdio.Tool {
func StatusTools(reader, read, again string, st keptStatus, acts HandActs, now func() time.Time) []stdio.Tool {
return []stdio.Tool{
{Name: read,
Description: fmt.Sprintf("%s's first views of the owners' states it follows (novox/hq ADR 0615): per owner and state, "+
"the tool it asks, the revision its picture holds now (events taken in included), the highest revision it heard and why "+
"it is behind it, if it is, when it asked and was answered, how many asks (by hand among them) and whether its "+
"condition (unanswered past two minutes) is raised.", reader),
"condition (unanswered past two minutes) is raised; and the revision of the revision view it holds, the one it waits "+
"for and acts on nothing new until it holds, since when, and whether its view-waits finding (past five minutes) is written.", reader),
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) {
keys, err := st.Keys()
@@ -110,7 +125,7 @@ func StatusTools(reader, read, again string, st stdio.KeptState, acts HandActs,
}
out := []Status{}
for _, k := range keys {
if strings.HasPrefix(k, "again.") {
if strings.HasPrefix(k, "again.") || k == OwnBuildKey {
continue
}
e, err := st.Get(k)
@@ -122,7 +137,14 @@ func StatusTools(reader, read, again string, st stdio.KeptState, acts HandActs,
out = append(out, s)
}
}
return map[string]any{"first-views": out}, nil
own := OwnBuildUnknown
if e, err := st.Get(OwnBuildKey); err == nil && e != nil {
var w string
if json.Unmarshal(e.Value, &w) == nil && strings.TrimSpace(w) != "" {
own = w
}
}
return map[string]any{"first-views": out, OwnBuildKey: own}, nil
}},
{Name: again,
Description: fmt.Sprintf("Ask %s's first view of an owner's state again now, by hand (a hand act, its caller and why kept in "+
+91
View File
@@ -0,0 +1,91 @@
package views
import (
"context"
"encoding/json"
"fmt"
"strings"
"sync/atomic"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// NewStdioWriter makes the finding writer of a stdio module (design 47 G A-16, §461, §485, §503): it fills `Publish` from
// the module's own event publish (stdio.Emit, answered once the bus acknowledged it) and `Listen` from its subscription
// (stdio.SubscribeNew of the seat event the config's Asked subject names, only the asks published after it is made), so no module writes that adapter. A `Publish` or `Listen`
// the config already holds is kept. The runtime publishes and subscribes by the event's name on the subject the module's
// membership names for it, so each of the writer's four subjects (FindingSubjects) is told by its event.
func NewStdioWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*Writer[F, C, S, A], error) {
return newStdioWriter(cfg, stdio.Emit, stdio.SubscribeNew)
}
func newStdioWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A],
emit func(string, any, ...stdio.EmitOptions) error,
subscribe func(string, func(stdio.Envelope) error) error) (*Writer[F, C, S, A], error) {
return NewWriter(withStdioPlumbing(cfg, emit, subscribe))
}
// NewStdioHeldWriter is NewHeldWriter for a stdio module: it fills `Publish` and `Listen` as NewStdioWriter does (design 47
// G A-37, after A-16).
func NewStdioHeldWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*HeldWriter[F, C, S, A], error) {
return NewHeldWriter(withStdioPlumbing(cfg, stdio.Emit, stdio.SubscribeNew))
}
func withStdioPlumbing[F, C, S, A any](cfg WriterConfig[F, C, S, A],
emit func(string, any, ...stdio.EmitOptions) error,
subscribe func(string, func(stdio.Envelope) error) error) WriterConfig[F, C, S, A] {
if cfg.Publish == nil {
cfg.Publish = func(_ context.Context, subject string, data []byte, id string) error {
event, err := eventOfSubject(subject)
if err != nil {
return err
}
return emit(event, json.RawMessage(data), stdio.EmitOptions{MessageID: id, Ack: true})
}
}
if cfg.Listen == nil {
cfg.Listen = func(_ context.Context, subject string, handle func([]byte)) (func(), error) {
event, err := seatEventOfSubject(subject)
if err != nil {
return nil, err
}
var stopped atomic.Bool
// the runtime keeps a subscription until the process ends: a stopped listener hands on nothing
if err := subscribe(event, func(env stdio.Envelope) error {
if !stopped.Load() {
handle(env.Body)
}
return nil
}); err != nil {
return nil, fmt.Errorf("subscribing to %s: %w", event, err)
}
return func() { stopped.Store(true) }, nil
}
}
return cfg
}
// eventOfSubject is the event of a subject of the writer: the old stream's `mesh.stream.<module>.event.<event>.<node>` or the
// binding's `mesh.bus.<module>.finding-events.<event>.<node>` (design 47 G A-274).
func eventOfSubject(subject string) (string, error) {
p := strings.Split(subject, ".")
for i, s := range p {
if s == "event" && i+2 == len(p)-1 && i > 0 {
return p[i+1], nil
}
}
if len(p) == 6 && p[0] == "mesh" && p[1] == "bus" && p[3] == FindingEventsLocal {
return p[4], nil
}
return "", fmt.Errorf("the subject %q is not of the form mesh.stream.<module>.event.<event>.<node> or mesh.bus.<module>.finding-events.<event>.<node>", subject)
}
// seatEventOfSubject is `<seat>.<event>` of a seat event's subject `mesh.seat.<seat>.event.<event>`, the name a runtime
// subscribes a seat's event by.
func seatEventOfSubject(subject string) (string, error) {
p := strings.Split(subject, ".")
if len(p) == 5 && p[0] == "mesh" && p[1] == "seat" && p[3] == "event" {
return p[2] + "." + p[4], nil
}
return "", fmt.Errorf("the subject %q is not of the form mesh.seat.<seat>.event.<event>", subject)
}
+145
View File
@@ -0,0 +1,145 @@
package views
import (
"context"
"encoding/json"
"strings"
"testing"
stdio "git.novox.be/novox/mesh-sdk/go"
)
type swFinding struct {
Kind string `json:"kind"`
Scope string `json:"scope"`
ID string `json:"id"`
Observer string `json:"observer"`
At string `json:"at"`
Since string `json:"since"`
Subject struct {
Scope string `json:"scope"`
} `json:"subject"`
}
type swCleared struct {
Kind string `json:"kind"`
Scope string `json:"scope"`
ID string `json:"id"`
At string `json:"at"`
Why string `json:"why"`
}
type swStated struct {
At string `json:"at"`
Findings []swFinding `json:"findings"`
Pending []PendingKey `json:"pending"`
}
type swAsked struct {
Ask string `json:"ask"`
}
// A stdio module's writer says each of its events through the module's own publish, acknowledged, under the writer's
// message id, and hears the asks through the module's subscription (design 47 G A-16).
func subStdioWriterPublishesAndListensThroughTheModulesOwnPlumbing(t *testing.T) {
type said struct {
event string
body string
o stdio.EmitOptions
}
var out []said
var subscribed []string
var deliver func(stdio.Envelope) error
w, err := newStdioWriter(WriterConfig[swFinding, swCleared, swStated, swAsked]{
Module: "m", Node: "n1", State: nil, Asked: "mesh.seat.s.event.findings-asked",
Observe: func(context.Context) (Observed[swFinding], error) { return Observed[swFinding]{}, nil },
}, func(event string, body any, o ...stdio.EmitOptions) error {
raw, _ := json.Marshal(body)
out = append(out, said{event, string(raw), o[0]})
return nil
}, func(pattern string, h func(stdio.Envelope) error) error {
subscribed = append(subscribed, pattern)
deliver = h
return nil
})
if err == nil || !strings.Contains(err.Error(), "state") {
t.Fatalf("the writer still needs its state: %v", err)
}
w, err = newStdioWriter(WriterConfig[swFinding, swCleared, swStated, swAsked]{
Module: "m", Node: "n1", State: noState{}, Asked: "mesh.seat.s.event.findings-asked",
Observe: func(context.Context) (Observed[swFinding], error) { return Observed[swFinding]{}, nil },
}, func(event string, body any, o ...stdio.EmitOptions) error {
raw, _ := json.Marshal(body)
out = append(out, said{event, string(raw), o[0]})
return nil
}, func(pattern string, h func(stdio.Envelope) error) error {
subscribed = append(subscribed, pattern)
deliver = h
return nil
})
if err != nil {
t.Fatal(err)
}
if err := w.cfg.Publish(context.Background(), w.subj.Written, []byte(`{"a":1}`), "id-1"); err != nil {
t.Fatal(err)
}
if len(out) != 1 || out[0].event != "finding-written" || out[0].body != `{"a":1}` || out[0].o.MessageID != "id-1" || !out[0].o.Ack {
t.Fatalf("the publish: %+v", out)
}
var heard []string
stop, err := w.cfg.Listen(context.Background(), w.cfg.Asked, func(b []byte) { heard = append(heard, string(b)) })
if err != nil || len(subscribed) != 1 || subscribed[0] != "s.findings-asked" {
t.Fatalf("the listen: %v %v", subscribed, err)
}
_ = deliver(stdio.Envelope{Body: json.RawMessage(`{"ask":"x"}`)})
stop()
_ = deliver(stdio.Envelope{Body: json.RawMessage(`{"ask":"y"}`)})
if len(heard) != 1 || heard[0] != `{"ask":"x"}` {
t.Fatalf("heard %v: a stopped listener hands on nothing", heard)
}
if err := w.cfg.Publish(context.Background(), "obs.event", nil, ""); err == nil {
t.Fatal("a subject of no event form is refused")
}
// the held form fills the same plumbing and states what it holds (design 47 G A-37)
out = nil
h, err := NewHeldWriter(withStdioPlumbing(WriterConfig[swFinding, swCleared, swStated, swAsked]{
Module: "m", Node: "n1", State: noState{}, Asked: "mesh.seat.s.event.findings-asked",
}, func(event string, body any, o ...stdio.EmitOptions) error {
raw, _ := json.Marshal(body)
out = append(out, said{event, string(raw), o[0]})
return nil
}, func(string, func(stdio.Envelope) error) error { return nil }))
if err != nil {
t.Fatal(err)
}
if err := h.Write(context.Background(), swFinding{Kind: "k", Scope: "module", ID: "x", Observer: "m", Subject: struct {
Scope string `json:"scope"`
}{"module"}}); err != nil {
t.Fatal(err)
}
if err := h.State(context.Background(), "a"); err != nil {
t.Fatal(err)
}
if len(out) == 0 || out[len(out)-1].event != "findings-stated" || !strings.Contains(out[len(out)-1].body, `"id":"x"`) {
t.Fatalf("a stdio held writer states its findings: %+v", out)
}
}
type noState struct{}
func (noState) Get(string) (*stdio.StateEntry, error) { return nil, nil }
func (noState) Put(string, any) (uint64, error) { return 0, nil }
func (noState) Delete(string) error { return nil }
func (noState) Keys() ([]string, error) { return nil, nil }
// Design 47 G A-274: the event of a writer's subject is read in both forms, the old stream's and the binding's.
func TestEventOfSubjectReadsBothForms(t *testing.T) {
for subject, want := range map[string]string{
"mesh.stream.m.event.finding-written.n1": "finding-written",
"mesh.bus.m.finding-events.findings-stated.n1": "findings-stated",
} {
if got, err := eventOfSubject(subject); err != nil || got != want {
t.Errorf("%s: %q, %v, want %q", subject, got, err, want)
}
}
if _, err := eventOfSubject("mesh.bus.m.other.finding-written.n1"); err == nil {
t.Error("another binding's subject was read as a finding event")
}
}
+17 -3
View File
@@ -11,6 +11,7 @@ import (
"fmt"
"slices"
"strings"
"sync/atomic"
"time"
)
@@ -46,7 +47,7 @@ const PageBytes = 768 * 1024
var PageBudget = 10 * time.Second
// clock is the page budget's time, replaced by a test.
var clock = time.Now
var clock = swappable(time.Now)
// Bound is how long a reader waits for its first view before it raises the condition naming the owner and the verb
// (ADR 0615 §6): longer than an owner's start, so a normal start, readers and owners coming up together, tells nobody.
@@ -265,12 +266,12 @@ func FirstView(owner, state string, values, marks Source, after string, now time
}
slices.Sort(keys)
size := 0
started := clock()
started := clock.get()()
for _, k := range keys {
if after != "" && k <= after {
continue
}
if size > 0 && clock().Sub(started) >= PageBudget {
if size > 0 && clock.get()().Sub(started) >= PageBudget {
a.Next = lastKey(a.Values)
break
}
@@ -326,3 +327,16 @@ func decode(data []byte, into any) error {
}
return nil
}
// swapped is a function a test replaces while a goroutine of an earlier test may still call it: held atomically, so the
// replacing and the calling never race.
type swapped[T any] struct{ p atomic.Pointer[T] }
func swappable[T any](v T) *swapped[T] {
s := &swapped[T]{}
s.p.Store(&v)
return s
}
func (s *swapped[T]) get() T { return *s.p.Load() }
func (s *swapped[T]) set(v T) { s.p.Store(&v) }
+718 -21
View File
@@ -5,6 +5,9 @@ import (
"encoding/json"
"errors"
"fmt"
"maps"
"reflect"
"runtime"
"slices"
"strings"
"sync"
@@ -16,6 +19,8 @@ import (
"github.com/nats-io/nats.go/jetstream"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
)
// mapSource is a state held in memory, as a Source.
@@ -52,7 +57,7 @@ func markOf(state string, rev uint64, made time.Time) Entry {
// The owners' and the readers' side of a first view (ADR 0615 §4-§6, ADR 0621 §2-§3, ADR 0622): one table of cases,
// since mesh-delivery is over its test budget.
func TestViews(t *testing.T) {
func subViews(t *testing.T) {
made := time.Date(2026, 11, 4, 12, 0, 0, 0, time.UTC)
now := func() time.Time { return made.Add(time.Hour) }
written := made.Add(-time.Minute)
@@ -98,8 +103,8 @@ func TestViews(t *testing.T) {
})
t.Run("a first view from a slow source stops at the page budget, with one value at least, and pages on to every key", func(t *testing.T) {
at := time.Unix(0, 0)
clock = func() time.Time { return at }
defer func() { clock = time.Now }()
clock.set(func() time.Time { return at })
defer clock.set(time.Now)
slow := mapSource{}
for i := range 5 {
slow[fmt.Sprintf("k%d", i)] = Entry{Value: json.RawMessage(`{"n":1}`), Revision: uint64(i + 1)}
@@ -299,6 +304,82 @@ func TestViews(t *testing.T) {
t.Errorf("said %v after %d asks", *said, f.Status().Asks)
}
})
// W1.4 (design 47 *A part with no view says it waits*): the status says the view held, the one waited for and since
// when; past the bound the part's view-waits is raised once, and holding the view clears it.
t.Run("a part that waits for a view says so, raises view-waits past its bound, and holding it clears that", func(t *testing.T) {
ended := make(chan bool)
kept := waitBound.get()
waitBound.set(func(context.Context, time.Duration) bool { return <-ended })
defer waitBound.set(kept)
var raised, cleared, said []Status
var mu sync.Mutex
raisedCh := make(chan struct{}, 4) // told after the part's raise, so the test reads it only once it is made
f := &Follower{Owner: "o", Tool: "o.revision", State: BranchState("catalog", "trunk"), Now: now,
RaiseWaits: func(s Status) { mu.Lock(); raised = append(raised, s); mu.Unlock(); raisedCh <- struct{}{} },
ClearWaits: func(s Status) { mu.Lock(); cleared = append(cleared, s); mu.Unlock() },
Said: func(s Status) { mu.Lock(); said = append(said, s); mu.Unlock() }}
f.Holds("trunk.11")
f.WaitFor(context.Background(), "trunk.12")
f.WaitFor(context.Background(), "trunk.12") // the same view again: nothing new, no second bound
if s := f.Status(); s.View != "trunk.11" || s.WaitsFor != "trunk.12" || !s.WaitingSince.Equal(now()) || s.WaitsRaised {
t.Fatalf("status = %+v", s)
}
ended <- true
select {
case <-raisedCh:
case <-time.After(10 * time.Second):
t.Fatal("the bound ended and view-waits was not raised")
}
mu.Lock()
if len(raised) != 1 || raised[0].WaitsFor != "trunk.12" {
t.Errorf("raised = %+v", raised)
}
mu.Unlock()
fd := viewWaitsFinding("mesh-delivery-builder", f.Status(), now())
if fd.kind != ViewWaitsKind || fd.id != "mesh-delivery-builder.o.catalog.trunk" || !strings.Contains(fd.summary, "waits for the view o.catalog.trunk at revision trunk.12") ||
!strings.Contains(fd.summary, "it holds trunk.11") {
t.Errorf("finding = %+v", fd)
}
none := &Follower{Owner: "o", Tool: "o.revision", State: BranchState("catalog", "new"), Now: now,
Ask: func(context.Context, string) (Answer, error) {
return Answer{V: 1, Owner: "o", State: "catalog.new", At: now()}, nil
}}
if err := none.Start(context.Background()); err != nil {
t.Fatal(err)
}
select {
case <-none.Ready():
default:
t.Errorf("a view of a branch with no revision is not ready")
}
if len(none.Values()) != 0 {
t.Errorf("not empty")
}
none.WaitFor(context.Background(), NoneYet) // a branch with no revision yet: ready, empty, nothing awaited (§495)
if s := none.Status(); s.WaitsFor != "" || !s.WaitingSince.IsZero() {
t.Errorf("a view of none yet is awaited: %+v", s)
}
f.Holds("trunk.12")
if s := f.Status(); s.View != "trunk.12" || s.WaitsFor != "" || s.WaitsRaised {
t.Errorf("after holding: %+v", s)
}
mu.Lock()
if len(cleared) != 1 || len(said) == 0 || said[len(said)-1].View != "trunk.12" {
t.Errorf("cleared %d, last said %+v", len(cleared), said)
}
mu.Unlock()
f.WaitFor(context.Background(), "trunk.13")
f.Holds("trunk.13")
ended <- true // the bound of a view now held raises nothing
for i := 0; i < 100; i++ {
runtime.Gosched()
}
mu.Lock()
if len(raised) != 1 {
t.Errorf("a view held before its bound raised: %+v", raised)
}
mu.Unlock()
})
t.Run("an event heard while an ask runs is taken again after its answer", func(t *testing.T) {
var f *Follower
f, _ = follower(func(ctx context.Context, after string) (Answer, error) {
@@ -479,6 +560,19 @@ func TestViews(t *testing.T) {
if err != nil || len(again.(map[string]any)["views"].([]Status)) != 1 || f.Status().ByHand != 1 || acted != 1 {
t.Errorf("asked again by hand: %v, %v", again, err)
}
// a list added by Rows is said beside the statuses (design 47 G A-103), and the entry-not-found finding is written and cleared
r.Rows("entries", func() any { return []string{"fp1"} })
seen, _ := r.Tools("reader")[0].Run(nil)
if got := seen.(map[string]any)["entries"]; !reflect.DeepEqual(got, []string{"fp1"}) {
t.Errorf("first views entries = %v", got)
}
nf := &findingsMap{}
if err := WriteEntryNotFound(nf, "fp1", now(), now()); err != nil || nf.m[EntryNotFoundKind+"/fp1"].Summary == "" {
t.Errorf("entry-not-found not written: %+v, %v", nf.m, err)
}
if err := ClearEntryNotFound(nf, "fp1"); err != nil || len(nf.m) != 0 {
t.Errorf("entry-not-found not cleared: %+v, %v", nf.m, err)
}
})
t.Run("a process's reader follows the read tool its caller names, reads the state as a read-only bucket, each key's written time handed on, and opens no other", func(t *testing.T) {
r := &ProcessReader{Module: "reader", Bound: time.Nanosecond, Wait: time.Millisecond, Now: now,
@@ -537,6 +631,486 @@ func TestViews(t *testing.T) {
}
_ = w.Stop()
})
// A seat's client makes the follower (its Ask a seat's verb) and both readers adopt it, so its callers write no glue:
// the reader's findings (unanswered, view-waits), Keys, Get, Watch, statuses and tools, and the seat's event handed to
// the client's handler.
// Design 47 G §479: a per-branch state's view is named <owner>.<state>.<branch>, several branches in one reader.
t.Run("a per-branch state is followed once per branch, each view its own row named with its escaped branch", func(t *testing.T) {
if got := BranchState("catalog-revisions", "feat/x y"); got != "catalog-revisions.feat/x=20y" {
t.Errorf("BranchState = %q", got)
}
r := &Reader{Module: "reader", Now: now}
a, b := r.FollowBranch("s", "catalog-revisions", "main", "s.read"), r.FollowBranch("s", "catalog-revisions", "feat/x", "s.read")
r.Follow("s", "plain", "s.read")
if a.State != "catalog-revisions.main" || b.State != "catalog-revisions.feat/x" {
t.Errorf("states %q %q", a.State, b.State)
}
for _, n := range []string{"s.catalog-revisions.main", "s.catalog-revisions.feat/x", "s.plain"} {
if !r.Follows(n) {
t.Errorf("%s is not followed", n)
}
}
if r.Follows("s.catalog-revisions") {
t.Errorf("the unnamed per-branch state is followed")
}
if st := r.Statuses(); len(st) != 3 || st[0].State != "catalog-revisions.main" || st[1].State != "catalog-revisions.feat/x" || st[2].State != "plain" {
t.Errorf("rows = %+v", st)
}
pr := &ProcessReader{Module: "reader"}
p1, err1 := pr.FollowBranch("s", "catalog-revisions", "main", "s.read")
p2, err2 := pr.FollowBranch("s", "catalog-revisions", "feat/x", "s.read")
if err1 != nil || err2 != nil || p1 == p2 || p1.Bucket() != "s_catalog-revisions.main" || pr.Picture("s_catalog-revisions.feat/x") != p2 {
t.Errorf("pictures %v %v %v", p1, p2, err1)
}
})
// Design 47 G §521: the owner's event names the state, the key names the branch; one event reaches the branch's own view.
t.Run("an event of a per-branch state goes to the view of its key's first token, one subscription for the branches", func(t *testing.T) {
made := now()
ask := func(context.Context, string) (Answer, error) {
return FirstView("s", "catalog-revisions", mapSource{}, mapSource{"catalog-revisions": markOf("catalog-revisions", 1, made)}, "", now())
}
r := &Reader{Module: "reader", Now: now}
a, b := r.FollowBranch("s", "catalog-revisions", "main", "s.read"), r.FollowBranch("s", "catalog-revisions", "feat/x", "s.read")
for _, f := range []*Follower{a, b} {
f.Ask = ask
if err := f.Start(context.Background()); err != nil {
t.Fatal(err)
}
}
followers := map[string]*Follower{a.State: a, b.State: b}
say := func(key string, rev uint64) {
data, _ := Event{Owner: "s", State: "catalog-revisions", Key: key, Revision: rev, Created: made, Value: json.RawMessage(`{}`)}.Encode()
if err := HearEvent(context.Background(), followers, data, t.Logf); err != nil {
t.Fatal(err)
}
}
say("main.r1", 2)
say("feat/x.r7", 2)
ka, kb := a.Values(), b.Values()
if _, ok := ka["main.r1"]; !ok || len(ka) != 1 {
t.Errorf("main's view holds %v", ka)
}
if _, ok := kb["feat/x.r7"]; !ok || len(kb) != 1 {
t.Errorf("feat/x's view holds %v", kb)
}
if r.events["s."+a.State] != "catalog-revisions" || r.events["s."+b.State] != "catalog-revisions" {
t.Errorf("events = %v", r.events)
}
})
t.Run("a follower a seat's client made is adopted: the reader's findings, reads and tools hold it, and its seat event goes to the client", func(t *testing.T) {
ended := make(chan bool, 1)
kept := waitBound.get()
waitBound.set(func(context.Context, time.Duration) bool { return <-ended })
defer waitBound.set(kept)
fs := &signalFindings{put: make(chan seenFinding, 4)}
r := &Reader{Module: "reader", Findings: fs, Now: now}
var own []string
f := &Follower{Owner: "s", Tool: "seat:s.revision", State: "revisions", Ask: answer,
Changed: func(k string, _ json.RawMessage, _ bool, _ time.Time) { own = append(own, k) }}
var heard []string
hear := func(_ context.Context, data []byte) error { heard = append(heard, string(data)); return nil }
if err := r.Adopt(f, "s", "revision-said", hear); err != nil {
t.Fatal(err)
}
if err := r.Adopt(f, "s", "revision-said", hear); err == nil {
t.Errorf("a state followed already is adopted twice")
}
if err := r.Adopt(&Follower{Owner: "s", State: "x"}, "s", "", hear); err == nil {
t.Errorf("a follower with no seat event is adopted")
}
if err := f.Start(context.Background()); err != nil {
t.Fatal(err)
}
keys, err := r.Keys("s.revisions")
if v, ok, _ := r.Get("s.revisions", "b"); err != nil || len(keys) != 2 || !ok || string(v) != `{"n":2}` || len(own) != 2 {
t.Errorf("keys %v (%v), b %s, own Changed %v", keys, err, v, own)
}
if st := r.Statuses(); len(st) != 1 || st[0].Tool != "seat:s.revision" {
t.Errorf("statuses = %+v", st)
}
_ = r.hearAdopted(context.Background(), r.adopted["s.revisions"])(stdio.Envelope{Key: "s.revision-said", Body: []byte(`{"revision":3}`)})
if r.adopted["s.revisions"].local() != "s.revision-said.>" || len(heard) != 1 {
t.Errorf("the seat event %v reached the client %v", r.adopted, heard)
}
// A later revision, said with a further part (`<seat>.<event>.<part>`), reaches the follower by the runtime's own matching.
if pat := r.adopted["s.revisions"].local(); !stdio.TopicMatches(pat, "s.revision-said.catalog-revision-9") || !stdio.TopicMatches(pat, "s.revision-said.a.b") {
t.Errorf("the pattern %q does not hear a later catalog revision", pat)
}
f.WaitFor(context.Background(), "3")
ended <- true
if fd := fs.next(t); fd.Kind != ViewWaitsKind || fd.ID != "reader.s.revisions" {
t.Errorf("view-waits is not the reader's finding: %+v", fd)
}
f.Holds("3")
if len(fs.m) != 0 {
t.Errorf("holding the view left %+v", fs.m)
}
// The process form: the picture reads the adopted follower, and the seat's event on the durable goes to the client.
pfs := &signalFindings{put: make(chan seenFinding, 4)}
pr := &ProcessReader{Module: "reader", Findings: func() WireWriter { return pfs }, Now: now}
pf := &Follower{Owner: "s", Tool: "seat:s.revision", State: "revisions", Ask: answer}
p, err := pr.Adopt(pf, "s", "revision-said", hear)
if err != nil || p.Bucket() != "s_revisions" || len(pr.Followers()) != 1 {
t.Fatalf("adopted %v, %v", p, err)
}
if err := pf.Start(context.Background()); err != nil {
t.Fatal(err)
}
if e, err := p.Get(context.Background(), "a"); err != nil || string(e.Value()) != `{"n":1}` {
t.Errorf("a = %v, %v", e, err)
}
m := &seatMsg{subject: "mesh.seat.s.event.revision-said", data: []byte(`{"revision":4}`)}
pr.Hear(context.Background())(m)
if len(heard) != 2 || heard[1] != `{"revision":4}` || !m.acked {
t.Errorf("the seat event on the durable: heard %v, acked %v", heard, m.acked)
}
// G §521, §532: an event's further parts reach the handler too
pr.Hear(context.Background())(&seatMsg{subject: "mesh.seat.s.event.revision-said.runner.main.abc", data: []byte(`{"revision":5}`)})
if len(heard) != 3 {
t.Errorf("an event with further parts: heard %v", heard)
}
// G §532: one subscription per event, `<event>.>`, and every follower adopted on the event hears it, two
// branches' views on one reader each
two := &Reader{Module: "reader", Now: now}
var one, other []string
for branch, got := range map[string]*[]string{"main": &one, "next": &other} {
f := &Follower{Owner: "s", State: BranchState("revisions", branch), Ask: answer}
if err := two.Adopt(f, "s", "revision-said", func(_ context.Context, d []byte) error { *got = append(*got, string(d)); return nil }); err != nil {
t.Fatal(err)
}
}
var fol []*Follower
for _, n := range two.order {
fol = append(fol, two.followers[n])
}
if err := two.hearAdoptedBy(context.Background(), fol, two.adopted)(stdio.Envelope{Key: "s.revision-said.main", Body: []byte(`{"revision":6}`)}); err != nil || len(one) != 1 || len(other) != 1 {
t.Errorf("two adopted views on one reader heard %v and %v (%v)", one, other, err)
}
var a, b []string
prr := &ProcessReader{Module: "reader", Now: now}
for i, got := range []*[]string{&a, &b} {
f := &Follower{Owner: "s", State: BranchState("revisions", []string{"main", "next"}[i]), Ask: answer}
if _, err := prr.Adopt(f, "s", "revision-said", func(_ context.Context, d []byte) error { *got = append(*got, string(d)); return nil }); err != nil {
t.Fatal(err)
}
}
prr.Hear(context.Background())(&seatMsg{subject: "mesh.seat.s.event.revision-said.main", data: []byte(`{"revision":7}`)})
if len(a) != 1 || len(b) != 1 {
t.Errorf("two adopted views on one process reader heard %v and %v", a, b)
}
// A-185, A-199: an event adopted with no picture is heard once on the same subscription, beside the views; a reader
// following no view hears it too.
var hooked []string
hook := func(_ context.Context, d []byte) error { hooked = append(hooked, string(d)); return nil }
if err := prr.AdoptEvent("s", "revision-said", hook); err != nil || prr.AdoptEvent("s", "", hook) == nil {
t.Fatalf("AdoptEvent: %v, and one naming no event was taken", err)
}
prr.Hear(context.Background())(&seatMsg{subject: "mesh.seat.s.event.revision-said.main", data: []byte(`{"revision":8}`)})
if len(a) != 2 || len(b) != 2 || len(hooked) != 1 || len(prr.Followers()) != 2 {
t.Errorf("beside two views the adopted event heard %v (views %v, %v)", hooked, a, b)
}
alone := &ProcessReader{Module: "reader", Now: now}
if err := alone.AdoptEvent("s", "revision-said", hook); err != nil {
t.Fatal(err)
}
am := &seatMsg{subject: "mesh.seat.s.event.revision-said.next", data: []byte(`{"revision":9}`)}
alone.Hear(context.Background())(am)
if len(hooked) != 2 || !am.acked {
t.Errorf("a reader following no view heard %v, acked %v", hooked, am.acked)
}
// A-222: an adopted event whose handler fails is left unacknowledged, so the bus asks again.
failing := &ProcessReader{Module: "reader", Now: now}
var tries int
if err := failing.AdoptEvent("s", "revision-said", func(context.Context, []byte) error {
tries++
if tries == 1 {
return errors.New("not placed yet")
}
return nil
}); err != nil {
t.Fatal(err)
}
fm := &seatMsg{subject: "mesh.seat.s.event.revision-said.next", data: []byte(`{"revision":10}`)}
failing.Hear(context.Background())(fm)
if fm.acked {
t.Error("a failed adopted event was acknowledged")
}
fm2 := &seatMsg{subject: fm.subject, data: fm.data}
failing.Hear(context.Background())(fm2)
if !fm2.acked || tries != 2 {
t.Errorf("the event asked again: acked %v after %d tries", fm2.acked, tries)
}
pf.WaitFor(context.Background(), "4")
ended <- true
if fd := pfs.next(t); fd.Kind != ViewWaitsKind || fd.ID != "reader.s.revisions" {
t.Errorf("view-waits is not the process reader's finding: %+v", fd)
}
})
// G §532, §614: a view adopted after the start takes its first view and follows on the event's one subscription; a
// dropped one hears nothing more, leaves `<module>_first_views`, and the findings it raised are cleared.
t.Run("a view adopted after the start takes its first view and follows, and a dropped one leaves with its findings cleared", func(t *testing.T) {
ended := make(chan bool, 2)
keptBound, keptSubscribe := waitBound.get(), subscribe.get()
waitBound.set(func(context.Context, time.Duration) bool { return <-ended })
var hmu sync.Mutex
handlers := map[string]func(stdio.Envelope) error{}
subscribe.set(func(p string, h func(stdio.Envelope) error) error {
hmu.Lock()
defer hmu.Unlock()
handlers[p] = h
return nil
})
defer func() { waitBound.set(keptBound); subscribe.set(keptSubscribe) }()
ready := func(f *Follower) {
t.Helper()
select {
case <-f.Ready():
case <-time.After(time.Second):
t.Fatalf("%s has no first view", f.State)
}
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
heard := map[string]*[]string{}
hearer := func(branch string) func(context.Context, []byte) error {
got := &[]string{}
heard[branch] = got
return func(_ context.Context, d []byte) error { *got = append(*got, string(d)); return nil }
}
fs := &signalFindings{put: make(chan seenFinding, 4)}
r := &Reader{Module: "reader", Findings: fs, Now: now}
main := &Follower{Owner: "s", Tool: "seat:s.revision", State: BranchState("revisions", "main"), Ask: answer}
if err := r.Adopt(main, "s", "revision-said", hearer("main")); err != nil {
t.Fatal(err)
}
r.Start(ctx)
ready(main)
next := &Follower{Owner: "s", Tool: "seat:s.revision", State: BranchState("revisions", "next"), Ask: answer}
if err := r.Adopt(next, "s", "revision-said", hearer("next")); err != nil {
t.Fatal(err)
}
ready(next)
hmu.Lock()
h, n := handlers["s.revision-said.>"], len(handlers)
hmu.Unlock()
if h == nil || n != 1 {
t.Fatalf("subscriptions %v: want the event's one", handlers)
}
event := stdio.Envelope{Key: "s.revision-said.next", Body: []byte(`{"revision":8}`)}
if _ = h(event); len(*heard["main"]) != 1 || len(*heard["next"]) != 1 {
t.Errorf("the event reached %v and %v", *heard["main"], *heard["next"])
}
next.WaitFor(ctx, "9")
ended <- true
if fd := fs.next(t); fd.Kind != ViewWaitsKind {
t.Fatalf("finding %+v", fd)
}
if err := r.Drop("s." + next.State); err != nil {
t.Fatal(err)
}
if len(fs.m) != 0 {
t.Errorf("the dropped view left its findings %v", fs.m)
}
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 {
t.Errorf("after the drop the event reached %v and %v", *heard["main"], *heard["next"])
}
if err := r.Drop("s." + next.State); err == nil {
t.Errorf("a view dropped twice")
}
// The process form: a view adopted after the start on another event is handled on the module's hub.
pfs := &signalFindings{put: make(chan seenFinding, 4)}
pr := &ProcessReader{Module: "reader", Findings: func() WireWriter { return pfs }, Now: now, Hub: process.NewEventHub(t.Logf)}
pm := &Follower{Owner: "s", Tool: "seat:s.revision", State: BranchState("revisions", "main"), Ask: answer}
if _, err := pr.Adopt(pm, "s", "revision-said", hearer("pmain")); err != nil {
t.Fatal(err)
}
pr.Start(ctx, nil, process.Account{}, nil)
ready(pm)
pn := &Follower{Owner: "s", Tool: "seat:s.revision", State: BranchState("revisions", "next"), Ask: answer}
if _, err := pr.Adopt(pn, "s", "revision-other", hearer("pnext")); err != nil {
t.Fatal(err)
}
ready(pn)
if !slices.Contains(pr.Hub.Patterns(), "mesh.seat.s.event.revision-other.>") {
t.Errorf("the hub handles %v", pr.Hub.Patterns())
}
msg := func() *seatMsg {
return &seatMsg{subject: "mesh.seat.s.event.revision-other.next", data: []byte(`{"revision":8}`)}
}
if pr.Hear(ctx)(msg()); len(*heard["pnext"]) != 1 {
t.Errorf("the process's adopted view heard %v", *heard["pnext"])
}
pn.WaitFor(ctx, "9")
ended <- true
if fd := pfs.next(t); fd.Kind != ViewWaitsKind {
t.Fatalf("finding %+v", fd)
}
if err := pr.Drop("s", pn.State); err != nil {
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)
}
})
// Design 47 G §717: a view found by its seat starts without a holder, waits naming the seat, follows the holder the
// seat-holders view names at its change, and a moved holder is followed as it moves; nothing is asked between changes.
t.Run("a seat's view starts with no holder, follows the one the seat-holders view names, and moves with it, asking nothing between changes", func(t *testing.T) {
ended := make(chan bool, 2)
keptBound := waitBound.get()
waitBound.set(func(ctx context.Context, _ time.Duration) bool {
select {
case v := <-ended:
return v
case <-ctx.Done():
return false
}
})
defer waitBound.set(keptBound)
var mu sync.Mutex
asked := map[string]int{}
states := map[string]map[string]json.RawMessage{
"assigner.seat-holders": {},
"h1.asks": {"hold.a": json.RawMessage(`{"n":1}`), "hold.b": json.RawMessage(`{"n":2}`)},
"h2.asks": {"hold.a": json.RawMessage(`{"n":3}`)},
}
fs := &signalFindings{put: make(chan seenFinding, 4)}
r := &ProcessReader{Module: "teller", Findings: func() WireWriter { return fs }, Now: now, Wait: time.Millisecond,
Call: func(tool string, _ any) (json.RawMessage, error) {
mu.Lock()
defer mu.Unlock()
asked[tool]++
vs, ok := states[tool]
if !ok {
return nil, fmt.Errorf("no tool %s", tool)
}
owner, state, _ := strings.Cut(tool, ".")
raw, _ := json.Marshal(Answer{V: Version, Owner: owner, State: state, Revision: 1, Created: made, Values: vs})
return raw, nil
}}
sh, err := r.Follow("assigner", "seat-holders", "assigner.seat-holders")
if err != nil {
t.Fatal(err)
}
holders := func(seat string) []string {
raw, ok := sh.Follower().Get(seat)
var held struct {
Holders []struct{ Module string } `json:"holders"`
}
if !ok || json.Unmarshal(raw, &held) != nil {
return nil
}
var out []string
for _, h := range held.Holders {
out = append(out, h.Module)
}
return out
}
p, err := r.FollowSeat("mesh-wants", "asks", holders)
if err != nil || p.Bucket() != "mesh-wants_asks" {
t.Fatalf("FollowSeat = %v, %v", p, err)
}
if again, _ := r.FollowSeat("mesh-wants", "asks", holders); again != p {
t.Errorf("a seat's view followed twice is two pictures")
}
if _, err := p.Get(context.Background(), "hold.a"); err == nil {
t.Errorf("a seat's view with no holder reads as held")
}
if b := r.HolderBucket("mesh-wants", "asks"); b != "" {
t.Errorf("with no holder the holder's bucket is %q", b)
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
r.Ask(ctx, nil)
<-sh.Follower().Ready()
// no holder: past the bound the reader writes view-waits naming the seat and the state
ended <- true
if fd := fs.next(t); fd.Kind != ViewWaitsKind || fd.ID != "teller.mesh-wants.asks" || !strings.Contains(fd.Summary, "seat mesh-wants") {
t.Fatalf("view-waits of a seat with no holder: %+v", fd)
}
if s := p.Follower().Status(); s.Owner != "mesh-wants" || s.WaitsFor != HolderWait {
t.Errorf("the waiting status names %q waiting for %q", s.Owner, s.WaitsFor)
}
ready := func(want string) {
t.Helper()
deadline := time.After(2 * time.Second)
for {
if e, err := p.Get(ctx, "hold.a"); err == nil && string(e.Value()) == want {
return
}
select {
case <-deadline:
t.Fatalf("the seat's picture never held hold.a %s", want)
case <-time.After(time.Millisecond):
}
}
}
w, _ := p.Watch(ctx, "hold.*")
// the seat-holders view names h1: its first view is asked of h1.asks, and its family heard
sh.Follower().Apply(Event{V: Version, Owner: "assigner", State: "seat-holders", Key: "mesh-wants", Revision: 2, Created: made,
Value: json.RawMessage(`{"holders":[{"module":"h1"}]}`)})
ready(`{"n":1}`)
if b := r.HolderBucket("mesh-wants", "asks"); b != "h1_asks" { // A-303: the holder's real bucket, at run time
t.Errorf("the holder's bucket is %q, want h1_asks", b)
}
if len(fs.m) != 0 {
t.Errorf("the holder's first view left the findings %v", fs.m)
}
if f := r.Picture("h1_asks"); f == nil {
t.Fatalf("h1's asks is not followed")
} else {
f.Follower().Apply(Event{V: Version, Owner: "h1", State: "asks", Key: "hold.c", Revision: 2, Created: made, Value: json.RawMessage(`{"n":4}`)})
}
if e, err := p.Get(ctx, "hold.c"); err != nil || string(e.Value()) != `{"n":4}` {
t.Errorf("the holder's event did not reach the seat's picture: %v, %v", e, err)
}
// another holder: h1's view is dropped, h2's taken whole (hold.b and hold.c leave)
sh.Follower().Apply(Event{V: Version, Owner: "assigner", State: "seat-holders", Key: "mesh-wants", Revision: 3, Created: made,
Value: json.RawMessage(`{"holders":[{"module":"h2"}]}`)})
ready(`{"n":3}`)
if b := r.HolderBucket("mesh-wants", "asks"); b != "h2_asks" {
t.Errorf("after the move the holder's bucket is %q, want h2_asks", b)
}
if keys, _ := p.Keys(ctx); strings.Join(keys, ",") != "hold.a" || r.Picture("h1_asks") != nil {
t.Errorf("after the move the picture holds %v, h1 followed %v", keys, r.Picture("h1_asks") != nil)
}
var seen []string
for !slices.Contains(seen, "hold.b:KeyValueDeleteOp") || !slices.Contains(seen, "hold.c:KeyValueDeleteOp") {
select {
case e := <-w.Updates():
if e != nil {
seen = append(seen, e.Key()+":"+e.Operation().String())
}
case <-time.After(2 * time.Second):
t.Fatalf("the watch saw %v", seen)
}
}
// no holder left: the picture is kept, h2 no longer followed
sh.Follower().Apply(Event{V: Version, Owner: "assigner", State: "seat-holders", Key: "mesh-wants", Revision: 4, Created: made, Deleted: true})
deadline := time.After(2 * time.Second)
for r.Picture("h2_asks") != nil {
select {
case <-deadline:
t.Fatalf("h2 is still followed with no holder")
case <-time.After(time.Millisecond):
}
}
if e, err := p.Get(ctx, "hold.a"); err != nil || string(e.Value()) != `{"n":3}` {
t.Errorf("with no holder the picture is not kept: %v, %v", e, err)
}
mu.Lock()
defer mu.Unlock()
if asked["h1.asks"] != 1 || asked["h2.asks"] != 1 || asked["assigner.seat-holders"] != 1 {
t.Errorf("asked %v: one first view per holder and none between changes", asked)
}
})
t.Run("a reader's again tool records its hand act before it writes the ask, and asks nothing when the act is not taken", func(t *testing.T) {
var recorded []HandAct
take := errors.New("no responders")
@@ -544,12 +1118,12 @@ func TestViews(t *testing.T) {
recorded = append(recorded, q)
return take
})
again := StatusTools("reader", "reader_first_views", "reader_first_view_again", stdio.State(StatusState), acts, now)[1]
again := StatusTools("reader", "reader_first_views", "reader_first_view_again", refusingStatus{}, acts, now)[1]
args := map[string]any{"owner": "o", "state": "modules", "why": "doubted"}
if _, err := again.Run(args); err == nil || !strings.Contains(err.Error(), "nothing was asked again") || len(recorded) != 1 {
t.Errorf("a hand act the seat did not take: %v, recorded %v", err, recorded)
}
take = nil // taken: the ask is written next (here refused, for no runtime serves this test)
take = nil // taken: the ask is written next (here refused)
if _, err := again.Run(args); err == nil || !strings.Contains(err.Error(), "hand ask is not written") || len(recorded) != 2 ||
recorded[1].Why != "doubted" || recorded[1].Verb != "reader_first_view_again" || !strings.Contains(recorded[1].What, "o's modules") {
t.Errorf("a hand act taken: %v, recorded %+v", err, recorded)
@@ -624,16 +1198,16 @@ func TestViews(t *testing.T) {
t.Errorf("%d failures: %d findings written, %d cleared, %d left, said %v", c.fails, fs.puts, fs.deletes, len(fs.m), said)
}
if c.puts > 0 {
f := UnsaidFinding("o", "s", "a", 1, made, "bus away", clock)
if f.Kind != UnsaidKind || f.ID != "o.s" || f.Observer != "o" || !strings.Contains(f.Summary, "o has not said the change of s.a at 1") {
f := unsaidFinding("o", "s", "a", 1, made, "bus away", clock)
if f.kind != UnsaidKind || f.id != "o.s" || !strings.Contains(f.summary, "o has not said the change of s.a at 1") {
t.Errorf("the finding is %+v", f)
}
}
}
// A finding a run before a restart raised is cleared by the first change said after it.
left0 := UnsaidFinding("o", "s", "a", 1, made, "bus away", made)
key := left0.Kind + "/" + left0.ID
fs := &findingsMap{m: map[string]Finding{key: left0}}
left0 := unsaidFinding("o", "s", "a", 1, made, "bus away", made)
key := left0.kind + "/" + left0.id
fs := &findingsMap{m: map[string]seenFinding{key: {Kind: left0.kind, ID: left0.id}}}
said, fails = nil, 0
em.Findings = fs
updates = make(chan jetstream.KeyValueEntry, 1)
@@ -643,6 +1217,12 @@ func TestViews(t *testing.T) {
if _, left := fs.m[key]; left || len(said) != 1 {
t.Errorf("after a restart the leftover finding stands (%v), said %v", left, said)
}
// A value too large for an event is said as a gap, and the emitter writes the owner's view-too-large itself (design 47 G §687).
tl := &findingsMap{}
te := Emitter{Owner: "o", Findings: tl, Now: func() time.Time { return made }}
if ev := te.Event("s", made, kvEntry{key: "big", rev: 3, at: made, size: MaxValueBytes + 1}); !ev.Gap || tl.m[TooLargeKind+"/o.s.big"].Kind != TooLargeKind {
t.Errorf("a value too large: gap %v, findings %v", ev.Gap, tl.m)
}
})
t.Run("each change names the revision said before it, and the mark is said as an event once written", func(t *testing.T) {
var said []Event
@@ -687,21 +1267,35 @@ func TestViews(t *testing.T) {
})
}
// findingsMap is a module's own findings state in memory, keyed `<kind>/<id>`.
// seenFinding is a finding a fake writer was handed, as its wire form names it.
type seenFinding struct{ Kind, ID, Summary string }
// findingsMap is a module's own findings writer in memory, keyed `<kind>/<id>` (the id as the finding names it).
type findingsMap struct {
m map[string]Finding
m map[string]seenFinding
puts, deletes int
}
func (f *findingsMap) Put(v Finding) error {
func (f *findingsMap) ModuleNode() (string, string) { return "m", "n1" }
func (f *findingsMap) WriteWire(_ context.Context, w map[string]any) error {
id, _ := keys.UnescapeName(w["id"].(string))
v := seenFinding{Kind: w["kind"].(string), ID: id, Summary: w["summary"].(string)}
if f.m == nil {
f.m = map[string]Finding{}
f.m = map[string]seenFinding{}
}
f.m[v.Kind+"/"+v.ID] = v
f.puts++
return nil
}
func (f *findingsMap) Clear(_ context.Context, _, id, kind, _ string) error {
plain, _ := keys.UnescapeName(id)
delete(f.m, kind+"/"+plain)
f.deletes++
return nil
}
// marksKV is an owner's marks state that takes puts and nothing else.
type marksKV struct {
jetstream.KeyValue
@@ -713,7 +1307,52 @@ func (m *marksKV) Put(context.Context, string, []byte) (uint64, error) {
return uint64(m.puts), nil
}
func (f *findingsMap) Delete(v Finding) error { delete(f.m, v.Kind+"/"+v.ID); f.deletes++; return nil }
// signalFindings is a findingsMap that hands each finding written to put, once written.
type signalFindings struct {
findingsMap
put chan seenFinding
}
func (f *signalFindings) WriteWire(ctx context.Context, w map[string]any) error {
_ = f.findingsMap.WriteWire(ctx, w)
id, _ := keys.UnescapeName(w["id"].(string))
f.put <- seenFinding{Kind: w["kind"].(string), ID: id, Summary: w["summary"].(string)}
return nil
}
// next is the next finding written; none within a second fails the test (a bound, never waited out when it comes).
func (f *signalFindings) next(t *testing.T) seenFinding {
t.Helper()
select {
case v := <-f.put:
return v
case <-time.After(time.Second):
t.Fatal("no finding was written")
return seenFinding{}
}
}
// seatMsg is one message of a seat's event on a module's durable consumer.
type seatMsg struct {
jetstream.Msg
subject string
data []byte
acked bool
}
func (m *seatMsg) Subject() string { return m.subject }
func (m *seatMsg) Data() []byte { return m.data }
func (m *seatMsg) Ack() error { m.acked = true; return nil }
// refusingStatus is a state `first-views` whose write the runtime refuses at once (no runtime serves this test, and the
// real binding waits 30 s for one).
type refusingStatus struct{}
func (refusingStatus) Keys() ([]string, error) { return nil, nil }
func (refusingStatus) Get(string) (*stdio.StateEntry, error) { return nil, nil }
func (refusingStatus) Put(string, any) (uint64, error) {
return 0, errors.New("no runtime serves this test")
}
// actsFunc records a hand act through a test's function.
type actsFunc func(HandAct) error
@@ -722,14 +1361,20 @@ func (f actsFunc) RecordHandAct(a HandAct) error { return f(a) }
// kvEntry is one change of a bucket as a watch hands it.
type kvEntry struct {
key string
rev uint64
at time.Time
key string
rev uint64
at time.Time
size int // the value's length when over the one event's: zero is a small value
}
func (k kvEntry) Bucket() string { return "b" }
func (k kvEntry) Key() string { return k.key }
func (k kvEntry) Value() []byte { return []byte(`{"n":1}`) }
func (k kvEntry) Bucket() string { return "b" }
func (k kvEntry) Key() string { return k.key }
func (k kvEntry) Value() []byte {
if k.size > 0 {
return make([]byte, k.size)
}
return []byte(`{"n":1}`)
}
func (k kvEntry) Revision() uint64 { return k.rev }
func (k kvEntry) Created() time.Time { return k.at }
func (k kvEntry) Delta() uint64 { return 0 }
@@ -777,3 +1422,55 @@ func (s *pagedSource) Page(after string, _ int, _ time.Duration) ([]KeyedEntry,
}
return out, "", nil
}
// TestViews runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
func TestViews(t *testing.T) {
t.Run("Views", subViews)
t.Run("StdioWriterPublishesAndListensThroughTheModulesOwnPlumbing", subStdioWriterPublishesAndListensThroughTheModulesOwnPlumbing)
}
type putRecorder struct{ puts map[string][]byte }
func (p *putRecorder) Put(_ context.Context, key string, value []byte) (uint64, error) {
p.puts[key] = value
return 1, nil
}
// statusWith is a state `first-views` holding the given values.
type statusWith map[string][]byte
func (s statusWith) Keys() ([]string, error) { return slices.Collect(maps.Keys(s)), nil }
func (s statusWith) Get(k string) (*stdio.StateEntry, error) {
if v, ok := s[k]; ok {
return &stdio.StateEntry{Value: v}, nil
}
return nil, nil
}
func (statusWith) Put(string, any) (uint64, error) { return 0, errors.New("read only") }
// design 47 G §674: both answers of a part's first views say its own build beside their list.
func TestFirstViewsSayTheOwnBuild(t *testing.T) {
for name, c := range map[string]struct{ env, want string }{"a fingerprint": {"abc123", "abc123"}, "none": {"", "unknown"}} {
getenv := func(string) string { return c.env }
// the bundle reader's answer
r := &Reader{Module: "m", Getenv: getenv}
got, _ := r.Tools("m")[0].Run(nil)
if v := got.(map[string]any)[OwnBuildKey]; v != c.want {
t.Errorf("%s: the bundle reader's first views say %v, want %s", name, v, c.want)
}
// the process writes it at its start, and its status tool reads it
rec := &putRecorder{puts: map[string][]byte{}}
KeepOwnBuild(context.Background(), rec, process.ReadOwnBuild(getenv), nil)
st := statusWith{OwnBuildKey: rec.puts[OwnBuildKey]}
read, err := StatusTools("m", "m_first_views", "m_first_view_again", st, nil, time.Now)[0].Run(nil)
m := read.(map[string]any)
if err != nil || m[OwnBuildKey] != c.want || len(m["first-views"].([]Status)) != 0 {
t.Errorf("%s: the status tool says %v, %v, want %s", name, m, err, c.want)
}
}
// a process that kept nothing yet says unknown
read, _ := StatusTools("m", "r", "a", statusWith{}, nil, time.Now)[0].Run(nil)
if read.(map[string]any)[OwnBuildKey] != "unknown" {
t.Errorf("nothing kept: %v", read)
}
}
+702
View File
@@ -0,0 +1,702 @@
package views
import (
"context"
"encoding/json"
"errors"
"fmt"
"maps"
"os"
"regexp"
"slices"
"strings"
"sync"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/membership"
)
// The finding writer (design 47 G §461, §485, §503): the one writer every observer uses to keep its findings in its own
// state `findings` and to say them as events (§383, §384). It names no seat and no module: the observer hands in the
// subjects of `finding-written`, `finding-cleared`, `findings-stated` and `findings-asked`, which the generated
// contract of the seat that defines them makes from its module name and node (§461, §439).
// The time constants of the writer (design 47 G §383, §485).
const (
// PublishRetryFor is how long an event the bus did not acknowledge is sent again before it is logged as an error.
PublishRetryFor = time.Minute
// ObserveRetryEvery is how often a failing observe is called again until a set is said.
ObserveRetryEvery = time.Minute
)
// A body is handled in its wire form (design 47 G A-3): the writer is generic over the contract's body types, which stay plain
// structs, and marshals a body, reads and sets `kind`, `scope`, `id`, `subject`, `at`, `since` and `observer` by their
// contract names. wire is that form.
type wire = map[string]any
// wireOf is v in its wire form.
func wireOf(v any) (wire, error) {
raw, err := json.Marshal(v)
if err != nil {
return nil, err
}
var m wire
if err := json.Unmarshal(raw, &m); err != nil {
return nil, fmt.Errorf("a body is not an object: %w", err)
}
return m, nil
}
func str(m wire, field string) string { s, _ := m[field].(string); return s }
// FindingKey is the key of the finding of scope, id and kind: `<scope>.<id>.<kind>` (novox/hq ADR 0564 §2).
func FindingKey(scope, id, kind string) string { return scope + "." + id + "." + kind }
func keyOf(m wire) string { return FindingKey(str(m, "scope"), str(m, "id"), str(m, "kind")) }
// requireFields refuses a contract body whose wire form lacks a field the writer reads or sets (design 47 G A-3).
func requireFields[T any](what string, fields ...string) error {
var zero T
m, err := wireOf(&zero)
if err != nil {
return fmt.Errorf("the %s body of the contract cannot be read: %w", what, err)
}
for _, f := range fields {
if _, ok := m[f]; !ok {
return fmt.Errorf("the %s body of the contract has no field %q on its wire form", what, f)
}
}
return nil
}
// ViewKinds are the finding kinds a views reader writes through the part's writer (design 47 G §639).
var ViewKinds = []string{ViewWaitsKind, UnansweredKind, UnsaidKind, TooLargeKind, EntryNotFoundKind}
var (
sessionForm = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$`)
seatForm = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
authorForm = regexp.MustCompile(`^forge:[A-Za-z0-9._-]+$`)
)
// formOfWho refuses a finding's `owner` or `waiting-on` of none of the three forms (design 47 G §678): a session
// (who@node), a seat's name, or a commit's author (forge:<account>); empty is none.
func formOfWho(field, v string) error {
if v == "" || sessionForm.MatchString(v) || seatForm.MatchString(v) || authorForm.MatchString(v) {
return nil
}
return fmt.Errorf("the finding's %s %q is none of a session (who@node), a seat's name or a commit's author (forge:<account>)", field, v)
}
// PendingKey is a key the observer cannot judge yet since its start: its `since` and its bound (a duration such as 5m).
type PendingKey struct {
Key string `json:"key"`
Since time.Time `json:"since"`
Bound string `json:"bound"`
}
// Observed is what an observer's own truth says now: the findings it observes and the keys it cannot judge yet.
type Observed[F any] struct {
Findings []F
Pending []PendingKey
}
// FindingState is the observer's own state `findings` (stdio.State and process.State both are one).
type FindingState interface {
Get(key string) (*stdio.StateEntry, error)
Put(key string, value any) (uint64, error)
Delete(key string) error
Keys() ([]string, error)
}
// WriterSubjects are the subjects of the three events an observer's module says on its own stream.
type WriterSubjects struct {
Written, Cleared, Stated string
}
// FindingSubjects are the subjects of the module's three own events on node, in §383's form
// `mesh.stream.<module>.event.<event>.<node>` (design 47 G A-13, §461, §439, §383). The writer forms them itself; a module
// passes none. The fourth, the subject of the ask it hears, is the seat's and is given (WriterConfig.Asked, A-17).
func FindingSubjects(module, node string) WriterSubjects {
of := func(event string) string { return "mesh.stream." + module + ".event." + event + "." + node }
return WriterSubjects{Written: of("finding-written"), Cleared: of("finding-cleared"), Stated: of("findings-stated")}
}
// FindingEventsLocal is the local name of the `events` template a part requires for its finding stream (design 47 G §529, A-30).
const FindingEventsLocal = "finding-events"
// FindingBindings is the part's bus bindings as the writer reads them (process.Binding is one): Asks says whether the part
// requires the entry of that local name, Names gives its names on the bus.
type FindingBindings interface {
Asks(local string) bool
Names(local string) (membership.BusBinding, error)
}
// subject is where the writer says event: under the binding `finding-events` when the process was handed one, whose subject
// is `mesh.bus.<module>.finding-events` and each message `<subject>.<event>.<node>`; with none, on the old stream
// (FindingSubjects). A binding not answered yet is an error, so the event is sent again until it is (design 47 G A-274, §529).
func (w *Writer[F, C, S, A]) subject(event string) (string, error) {
if w.cfg.Bindings != nil && w.cfg.Bindings.Asks(FindingEventsLocal) {
b, err := w.cfg.Bindings.Names(FindingEventsLocal)
if err != nil {
return "", err
}
if b.Subject == "" {
return "", fmt.Errorf("the bus entry %q of %s names no subject", FindingEventsLocal, w.cfg.Module)
}
return b.Subject + "." + event + "." + w.cfg.Node, nil
}
switch event {
case "finding-written":
return w.subj.Written, nil
case "finding-cleared":
return w.subj.Cleared, nil
}
return w.subj.Stated, nil
}
// WriterConfig makes a Writer.
type WriterConfig[F, C, S, A any] struct {
// Module is the observer's module name: it fills the observer of a finding and tells an ask for another module.
Module string
// State is the observer's own state `findings`.
State FindingState
// Kinds are the finding kinds this writer owns (design 47 G §580): it refuses a Write or a Clear of another kind,
// 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
// JS is the bus connection's JetStream; Conn, when given, lets the writer hear the connection made again.
JS jetstream.JetStream
Conn *nats.Conn
// Bindings are the part's bus bindings: when it asks the entry `finding-events` (an `events` template its manifest
// requires) the writer says its events under that binding's subjects, else on the old stream (design 47 G A-274); a
// module passes no subjects. nil is the old stream.
Bindings FindingBindings
// Asked is the subject the writer hears `findings-asked` on: the seat's event, which the module fills from the generated
// contract of the seat that defines it (design 47 G A-17); mesh-sdk names no seat.
Asked string
// Node is the machine the module runs on: it forms the subjects of the four events (FindingSubjects) and a views
// reader's findings name it in their subject (design 47 G §687, A-13); none given, MESH_NODE.
Node string
// Observe answers the findings the observer observes now and its pending keys, or an error. It is called under the
// writer's one lock, so it must not call Write or Clear.
Observe func(ctx context.Context) (Observed[F], error)
// Send puts a set larger than one bus message in the observer's sent store and answers what to publish instead
// (stateobjects.Sender.Send); nil sends the body as it is.
Send func(label string, body []byte) ([]byte, error)
// Logf is the observer's journal.
Logf func(string, ...any)
// Now is the clock, Wait pauses for d and answers false when ctx ended; nil are the real ones.
Now func() time.Time
Wait func(ctx context.Context, d time.Duration) bool
// Publish sends one message and answers when the bus acknowledged it, and Listen makes a consumer that delivers only
// the asks published after it is made; nil are JS's.
Publish func(ctx context.Context, subject string, data []byte, id string) error
Listen func(ctx context.Context, subject string, handle func(data []byte)) (stop func(), err error)
}
// Writer keeps an observer's findings and says them (design 47 G §461, §485). Its acts, Write, Clear and a statement,
// run one at a time in the order they are asked.
type Writer[F, C, S, A any] struct {
cfg WriterConfig[F, C, S, A]
subj WriterSubjects // the four subjects, formed by FindingSubjects
mu sync.Mutex // the one lock of the acts
seq uint64
ctl sync.Mutex // guards the consumer, the asks and the loop's context
stop func()
asks []string
want bool
wake chan struct{}
run context.Context
end context.CancelFunc
}
// NewWriter is the writer for cfg.
func NewWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*Writer[F, C, S, A], error) {
switch {
case cfg.Module == "":
return nil, errors.New("a finding writer needs its module's name")
case cfg.State == nil:
return nil, errors.New("a finding writer needs the state `findings`")
case cfg.Observe == nil:
return nil, errors.New("a finding writer needs the observe function")
case cfg.Asked == "":
return nil, errors.New("a finding writer needs the subject of findings-asked, from the generated contract of its seat")
case cfg.JS == nil && (cfg.Publish == nil || cfg.Listen == nil):
return nil, errors.New("a finding writer needs the bus connection's JetStream")
}
if err := requireFields[F]("finding", "kind", "scope", "id", "subject", "at", "since", "observer"); err != nil {
return nil, err
}
if err := requireFields[C]("finding-cleared", "kind", "scope", "id", "at", "why"); err != nil {
return nil, err
}
if err := requireFields[S]("findings-stated", "at", "findings", "pending"); err != nil {
return nil, err
}
if err := requireFields[A]("findings-asked", "ask"); err != nil {
return nil, err
}
if cfg.Node == "" {
cfg.Node = os.Getenv("MESH_NODE")
}
if cfg.Node == "" {
return nil, errors.New("a finding writer needs its node, which forms the subjects of its events")
}
if cfg.Now == nil {
cfg.Now = func() time.Time { return time.Now().UTC() }
}
if cfg.Wait == nil {
cfg.Wait = func(ctx context.Context, d time.Duration) bool {
t := time.NewTimer(d)
defer t.Stop()
select {
case <-ctx.Done():
return false
case <-t.C:
return true
}
}
}
if cfg.Logf == nil {
cfg.Logf = func(string, ...any) {}
}
if cfg.Publish == nil {
cfg.Publish = jetStreamPublish(cfg.JS)
}
if cfg.Listen == nil {
cfg.Listen = jetStreamListen(cfg.JS)
}
return &Writer[F, C, S, A]{cfg: cfg, subj: FindingSubjects(cfg.Module, cfg.Node), wake: make(chan struct{}, 1)}, nil
}
func jetStreamPublish(js jetstream.JetStream) func(context.Context, string, []byte, string) error {
return func(ctx context.Context, subject string, data []byte, id string) error {
pub, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
_, err := js.PublishMsg(pub, &nats.Msg{Subject: subject, Data: data}, jetstream.WithMsgID(id))
return err
}
}
// jetStreamListen makes an ephemeral consumer of its own on the stream that holds subject, from the next message on.
func jetStreamListen(js jetstream.JetStream) func(context.Context, string, func([]byte)) (func(), error) {
return func(ctx context.Context, subject string, handle func([]byte)) (func(), error) {
stream, err := js.StreamNameBySubject(ctx, subject)
if err != nil {
return nil, fmt.Errorf("the stream of %s: %w", subject, err)
}
cons, err := js.CreateConsumer(ctx, stream, jetstream.ConsumerConfig{
FilterSubject: subject, DeliverPolicy: jetstream.DeliverNewPolicy, AckPolicy: jetstream.AckNonePolicy,
InactiveThreshold: 10 * time.Minute,
})
if err != nil {
return nil, fmt.Errorf("a consumer of %s: %w", subject, err)
}
cc, err := cons.Consume(func(m jetstream.Msg) { handle(m.Data()) })
if err != nil {
return nil, fmt.Errorf("consuming %s: %w", subject, err)
}
return cc.Stop, nil
}
}
// Start makes the consumer of `findings-asked` and then states the findings now, and again on each ask and each time the
// connection is made again (design 47 G §384, §485). It returns once the consumer exists; the statements run in the
// writer's own goroutine until ctx ends or Close.
func (w *Writer[F, C, S, A]) Start(ctx context.Context) error {
w.ctl.Lock()
defer w.ctl.Unlock()
if w.run != nil {
return errors.New("the finding writer is started")
}
w.run, w.end = context.WithCancel(ctx)
if err := w.listen(); err != nil {
w.end()
w.run = nil
return err
}
w.asks, w.want = append(w.asks, ""), true
if w.cfg.Conn != nil {
prev := w.cfg.Conn.Opts.ReconnectedCB
w.cfg.Conn.SetReconnectHandler(func(nc *nats.Conn) {
if prev != nil {
prev(nc)
}
w.Reconnected()
})
}
go w.loop(w.run)
w.signal()
return nil
}
// Close ends the writer's consumer and its statements.
func (w *Writer[F, C, S, A]) Close() {
w.ctl.Lock()
defer w.ctl.Unlock()
if w.stop != nil {
w.stop()
w.stop = nil
}
if w.end != nil {
w.end()
}
}
func (w *Writer[F, C, S, A]) listen() error {
stop, err := w.cfg.Listen(w.run, w.cfg.Asked, w.heard)
if err != nil {
return err
}
if w.stop != nil {
w.stop()
}
w.stop = stop
return nil
}
// Reconnected is told that the bus connection was made again: the writer makes its consumer again, from the newest ask,
// and states its findings again (design 47 G §485).
func (w *Writer[F, C, S, A]) Reconnected() {
w.ctl.Lock()
defer w.ctl.Unlock()
if w.run == nil || w.run.Err() != nil {
return
}
if err := w.listen(); err != nil {
w.cfg.Logf("the finding writer could not make its consumer of %s again: %v", w.cfg.Asked, err)
}
w.asks, w.want = append(w.asks, ""), true
w.signal()
}
func (w *Writer[F, C, S, A]) signal() {
select {
case w.wake <- struct{}{}:
default:
}
}
// heard is an ask: answered when it names no module or this one.
func (w *Writer[F, C, S, A]) heard(data []byte) {
var body A
if err := json.Unmarshal(data, &body); err != nil {
w.cfg.Logf("an ask for findings could not be read: %v", err)
return
}
a, err := wireOf(&body)
if err != nil {
w.cfg.Logf("an ask for findings could not be read: %v", err)
return
}
if str(a, "module") != "" && str(a, "module") != w.cfg.Module {
return
}
w.ctl.Lock()
w.asks, w.want = append(w.asks, str(a, "ask")), true
w.ctl.Unlock()
w.signal()
}
func (w *Writer[F, C, S, A]) loop(ctx context.Context) {
for {
select {
case <-ctx.Done():
return
case <-w.wake:
}
w.ctl.Lock()
asks, want := w.asks, w.want
w.asks, w.want = nil, false
w.ctl.Unlock()
if !want {
continue
}
asked := ""
if len(asks) > 0 {
asked = asks[len(asks)-1]
}
for {
err := w.State(ctx, asked)
if err == nil {
break
}
w.cfg.Logf("the findings could not be stated, no set said, trying again in %s: %v", ObserveRetryEvery, err)
if !w.cfg.Wait(ctx, ObserveRetryEvery) {
return
}
}
}
}
// 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 {
return len(w.cfg.Kinds) == 0 || slices.Contains(w.cfg.Kinds, kind) || slices.Contains(ViewKinds, kind)
}
// statedKinds are the kinds a statement names: none when the writer owns every kind.
func (w *Writer[F, C, S, A]) statedKinds() []string {
if len(w.cfg.Kinds) == 0 {
return nil
}
k := append(slices.Clone(w.cfg.Kinds), ViewKinds...)
slices.Sort(k)
return slices.Compact(k)
}
// ownsKey says whether key is one of a kind the writer owns: its last part is the kind (`<scope>.<id>.<kind>`).
func (w *Writer[F, C, S, A]) ownsKey(key string) bool {
if len(w.cfg.Kinds) == 0 {
return true
}
i := strings.LastIndex(key, ".")
return i >= 0 && w.owns(key[i+1:])
}
func (w *Writer[F, C, S, A]) now() time.Time { return w.cfg.Now().UTC() }
// unsaid is a finding as compared to say whether what it says changed: not the time it was last seen, nor what saw it.
func unsaid(f wire) string {
m := maps.Clone(f)
delete(m, "at")
delete(m, "run")
raw, _ := json.Marshal(m)
return string(raw)
}
func (w *Writer[F, C, S, A]) read(key string) (wire, error) {
e, err := w.cfg.State.Get(key)
if err != nil {
return nil, err
}
if e == nil {
return nil, nil
}
var old wire
if err := json.Unmarshal(e.Value, &old); err != nil {
return nil, fmt.Errorf("the finding %s in the state findings: %w", key, err)
}
return old, nil
}
// CheckFinding refuses a finding the keeper could not make a condition of, naming the field of the first rule it breaks:
// the key's three parts (`scope`, `id` and `kind`, each given, the kind with no dot, since the kind is the key's last
// part), and the forms of `owner` and `waiting-on` (design 47 G §678, §689). It judges the finding's wire form (design 47
// G A-3): any value that marshals as a finding, the contract's generated type among them. The writer refuses such a
// finding before it writes it, and the keeper judges the findings others write with it.
func CheckFinding(finding any) error {
m, ok := finding.(wire)
if !ok {
var err error
if m, err = wireOf(finding); err != nil {
return fmt.Errorf("the finding could not be read: %w", err)
}
}
switch {
case strings.TrimSpace(str(m, "scope")) == "":
return errors.New("the finding's scope is not given")
case strings.TrimSpace(str(m, "id")) == "":
return errors.New("the finding's id is not given")
case strings.TrimSpace(str(m, "kind")) == "":
return errors.New("the finding's kind is not given")
case strings.Contains(str(m, "kind"), "."):
return fmt.Errorf("the finding's kind %q holds a dot, and the kind is the last part of its key", str(m, "kind"))
}
if err := formOfWho("owner", str(m, "owner")); err != nil {
return err
}
return formOfWho("waiting-on", str(m, "waiting-on"))
}
// complete fills what the observer leaves to the writer and keeps the key's `since` where the key exists (design 47 G §384).
func (w *Writer[F, C, S, A]) complete(finding F) (wire, wire, error) {
f, err := wireOf(&finding)
if err != nil {
return nil, nil, fmt.Errorf("the finding could not be read: %w", err)
}
if err := CheckFinding(f); err != nil {
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)
}
old, err := w.read(keyOf(f))
if err != nil {
return f, nil, err
}
if str(f, "observer") == "" {
f["observer"] = w.cfg.Module
}
at, _ := time.Parse(time.RFC3339Nano, str(f, "at"))
if at.IsZero() {
at = w.now()
}
f["at"] = at.UTC()
since, _ := time.Parse(time.RFC3339Nano, str(f, "since"))
if old != nil {
if os, _ := time.Parse(time.RFC3339Nano, str(old, "since")); !os.IsZero() {
since = os
}
}
if since.IsZero() {
since = at
}
f["since"] = since.UTC()
return f, old, nil
}
// WriteWire is Write of a finding given in its wire form (a views reader's findings, design 47 G §687).
func (w *Writer[F, C, S, A]) WriteWire(ctx context.Context, finding map[string]any) error {
var f F
if err := fillFrom(&f, finding); err != nil {
return err
}
return w.Write(ctx, f)
}
// ModuleNode is the module and the node the writer's findings are about.
func (w *Writer[F, C, S, A]) ModuleNode() (string, string) { return w.cfg.Module, w.cfg.Node }
// Write keeps the finding in its key and says `finding-written` only when what the finding says changed (design 47 G
// §383, §461). The key's `since` stays where the key exists.
func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
w.mu.Lock()
defer w.mu.Unlock()
f, old, err := w.complete(finding)
if err != nil {
return err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
if old != nil && unsaid(old) == unsaid(f) {
return nil
}
raw, _ := json.Marshal(f)
w.say(ctx, "finding-written", keyOf(f), raw)
return nil
}
// 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 {
w.mu.Lock()
defer w.mu.Unlock()
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)
}
if err := w.cfg.State.Delete(key); err != nil {
return fmt.Errorf("clearing the finding %s: %w", key, err)
}
var cleared C
if err := fillFrom(&cleared, wire{"kind": kind, "scope": scope, "id": id, "at": w.now(), "why": why}); err != nil {
return err
}
raw, _ := json.Marshal(&cleared)
w.say(ctx, "finding-cleared", key, raw)
return nil
}
// State judges every finding anew with observe, writes each stated finding's key, deletes each key neither stated nor
// pending, and says `findings-stated` (design 47 G §384, §461); asked is the ask it answers, none at a start. An error of
// observe says no set.
func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
w.mu.Lock()
defer w.mu.Unlock()
obs, err := w.cfg.Observe(ctx)
if err != nil {
return fmt.Errorf("observe: %w", err)
}
keep := map[string]bool{}
findings, pending := []wire{}, []wire{}
for _, finding := range obs.Findings {
f, _, err := w.complete(finding)
if err != nil {
return err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
keep[keyOf(f)] = true
findings = append(findings, f)
}
for _, p := range obs.Pending {
keep[p.Key] = true
pending = append(pending, wire{"key": p.Key, "since": p.Since, "bound": p.Bound})
}
keys, err := w.cfg.State.Keys()
if err != nil {
return fmt.Errorf("the keys of the state findings: %w", err)
}
slices.Sort(keys)
for _, k := range keys {
// a views reader's open findings are stated beside observe's (design 47 G §639)
if i := strings.LastIndex(k, "."); !keep[k] && i >= 0 && slices.Contains(ViewKinds, k[i+1:]) {
if old, err := w.read(k); err == nil && old != nil {
keep[k] = true
findings = append(findings, old)
}
}
if !keep[k] && w.ownsKey(k) {
if err := w.cfg.State.Delete(k); err != nil {
return fmt.Errorf("deleting the finding %s: %w", k, err)
}
}
}
stated := wire{"at": w.now(), "findings": findings, "pending": pending}
if asked != "" {
stated["asked"] = asked
}
if k := w.statedKinds(); k != nil {
stated["kinds"] = k
}
var body S
if err := fillFrom(&body, stated); err != nil {
return err
}
raw, _ := json.Marshal(&body)
if w.cfg.Send != nil {
if raw, err = w.cfg.Send("findings-stated."+w.cfg.Module, raw); err != nil {
w.cfg.Logf("the findings-stated of %s could not be sent, the next statement covers it: %v", w.cfg.Module, err)
return nil
}
}
w.say(ctx, "findings-stated", w.cfg.Module, raw)
return nil
}
// say publishes one event awaiting the bus's acknowledgement, sent again for PublishRetryFor when unacknowledged, then
// written in the journal as an error naming what it said (design 47 G §383); the next statement covers it.
func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data []byte) {
w.seq++
id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), w.seq)
start := w.now()
for delay := time.Second; ; delay = min(delay*2, 10*time.Second) {
subject, err := w.subject(event)
if err == nil {
err = w.cfg.Publish(ctx, subject, data, id)
}
if err == nil {
return
}
if w.now().Sub(start) >= PublishRetryFor || ctx.Err() != nil || !w.cfg.Wait(ctx, delay) {
w.cfg.Logf("error: %s for %s was not acknowledged by the bus, the next statement covers it: %v", event, what, err)
return
}
}
}
// fillFrom sets the contract body v from its wire form.
func fillFrom(v any, m wire) error {
raw, err := json.Marshal(m)
if err != nil {
return err
}
return json.Unmarshal(raw, v)
}
+92
View File
@@ -0,0 +1,92 @@
//go:build integration
package views_test
import (
"context"
"encoding/json"
"testing"
"time"
"github.com/nats-io/nats.go"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/testbus"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Against a real bus: the writer's events are acknowledged by their stream, a start states what the observer observes, an
// ask published before the writer's consumer existed is never answered, one published after is, and after the connection
// is made again (Reconnected) the consumer is made again from the newest ask (design 47 G §383, §390, §485).
func subWriterSaysItsEventsAndHearsAsksOnTheBus(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.WithCancel(context.Background())
defer cancel()
subj := views.FindingSubjects("m", "n1")
for name, subjects := range map[string][]string{"EVENTS": {subj.Written, subj.Cleared, subj.Stated}, "ASKS": {asked}} {
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: name, Subjects: subjects}); err != nil {
t.Fatal(err)
}
}
if _, err := js.Publish(ctx, asked, []byte(`{"ask":"old","at":"2026-11-11T12:00:00Z","by":"keeper"}`)); err != nil {
t.Fatal(err)
}
listen, err := js.CreateConsumer(ctx, "EVENTS", jetstream.ConsumerConfig{AckPolicy: jetstream.AckNonePolicy})
if err != nil {
t.Fatal(err)
}
state := &fakeState{m: map[string][]byte{}}
w, err := views.NewWriter(testConfig{Module: "m", State: state, JS: js, Conn: nc, Node: "n1", Asked: asked,
Observe: func(context.Context) (testObserved, error) {
return testObserved{Findings: []testFinding{finding("a", "now")}}, nil
}, Logf: t.Logf})
if err != nil {
t.Fatal(err)
}
if err := w.Start(ctx); err != nil {
t.Fatal(err)
}
defer w.Close()
next := func(want string) testStated {
t.Helper()
m, err := listen.Next(jetstream.FetchMaxWait(10 * time.Second))
if err != nil {
t.Fatal(err)
}
if m.Subject() != want {
t.Fatalf("said %s, want %s", m.Subject(), want)
}
var st testStated
if want == subj.Stated {
if err := json.Unmarshal(m.Data(), &st); err != nil {
t.Fatal(err)
}
}
return st
}
if st := next(subj.Stated); st.Asked != "" || len(st.Findings) != 1 {
t.Fatalf("start statement: %+v", st)
}
if err := w.Write(ctx, finding("b", "x")); err != nil {
t.Fatal(err)
}
next(subj.Written)
for _, ask := range []string{"new", "again"} {
w.Reconnected()
next(subj.Stated) // the statement after the connection was made again
if _, err := js.Publish(ctx, asked, []byte(`{"ask":"`+ask+`","at":"2026-11-11T12:00:00Z","by":"keeper"}`)); err != nil {
t.Fatal(err)
}
if st := next(subj.Stated); st.Asked != ask {
t.Fatalf("answered %q, want %q", st.Asked, ask)
}
}
}
+658
View File
@@ -0,0 +1,658 @@
package views_test
import (
"context"
"encoding/json"
"errors"
"fmt"
"runtime"
"slices"
"strings"
"sync"
"testing"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/membership"
"git.novox.be/novox/mesh-sdk/go/views"
)
// fakeState is an observer's state `findings` in memory.
type fakeState struct {
mu sync.Mutex
m map[string][]byte
}
func (s *fakeState) Get(key string) (*stdio.StateEntry, error) {
s.mu.Lock()
defer s.mu.Unlock()
if v, ok := s.m[key]; ok {
return &stdio.StateEntry{Key: key, Value: v}, nil
}
return nil, nil
}
func (s *fakeState) Put(key string, value any) (uint64, error) {
raw, _ := json.Marshal(value)
s.mu.Lock()
defer s.mu.Unlock()
s.m[key] = raw
return 1, nil
}
func (s *fakeState) Delete(key string) error {
s.mu.Lock()
defer s.mu.Unlock()
delete(s.m, key)
return nil
}
func (s *fakeState) Keys() ([]string, error) {
s.mu.Lock()
defer s.mu.Unlock()
var k []string
for key := range s.m {
k = append(k, key)
}
return k, nil
}
type said struct {
subject string
data []byte
}
type rig struct {
t *testing.T
state *fakeState
now time.Time
mu sync.Mutex
sent []said
fail int // publishes refused before one is taken
waits []time.Duration
logs []string
observe func(context.Context) (testObserved, error)
handle func([]byte)
listens int
stopped int
w *testWriter
ch chan struct{}
}
// subjects are the four subjects the writer forms itself in §383's form (design 47 G A-13); the literal is the form.
var subjects = views.FindingSubjects("m", "n1")
// asked is the subject the module gives the writer for findings-asked, as its seat's generated contract has it (design 47 G A-17).
const asked = "mesh.seat.s.event.findings-asked"
func subFindingSubjectsAreTheEventsStreamForm(t *testing.T) {
want := views.WriterSubjects{
Written: "mesh.stream.m.event.finding-written.n1", Cleared: "mesh.stream.m.event.finding-cleared.n1",
Stated: "mesh.stream.m.event.findings-stated.n1",
}
if subjects != want {
t.Fatalf("the subjects: %+v, want %+v", subjects, want)
}
}
// fakeBindings is a process's binding of the entries it asks.
type fakeBindings struct {
asks bool
names membership.BusBinding
err error
}
func (f fakeBindings) Asks(local string) bool { return f.asks && local == views.FindingEventsLocal }
func (f fakeBindings) Names(string) (membership.BusBinding, error) {
return f.names, f.err
}
// Design 47 G A-274: a part handed the binding `finding-events` says its three events under that binding's subject, a part
// with none on the old stream; a binding not answered yet is sent again until it is.
func subWriterSaysUnderItsFindingEventsBindingOrOnTheOldStream(t *testing.T) {
say := func(b views.FindingBindings) (*rig, []said) {
r := newRig(t)
w, err := views.NewWriter(testConfig{Module: "m", State: r.state, Node: "n1", Asked: asked, Bindings: b,
Observe: func(context.Context) (testObserved, error) { return testObserved{}, nil },
Wait: func(ctx context.Context, d time.Duration) bool {
r.mu.Lock()
r.now = r.now.Add(d)
r.mu.Unlock()
return ctx.Err() == nil
},
Now: func() time.Time { r.mu.Lock(); defer r.mu.Unlock(); return r.now },
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
r.mu.Lock()
defer r.mu.Unlock()
r.sent = append(r.sent, said{subject, data})
return nil
},
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }})
if err != nil {
t.Fatal(err)
}
if err := w.Write(context.Background(), finding("a", "one")); err != nil {
t.Fatal(err)
}
if err := w.Clear(context.Background(), "module", "a", "k", "gone"); err != nil {
t.Fatal(err)
}
if err := w.State(context.Background(), ""); err != nil {
t.Fatal(err)
}
return r, r.events()
}
subjectsOf := func(ev []said) []string {
var out []string
for _, e := range ev {
out = append(out, e.subject)
}
return out
}
bound := membership.BusBinding{Local: views.FindingEventsLocal, Subject: "mesh.bus.m.finding-events"}
_, ev := say(fakeBindings{asks: true, names: bound})
if got := subjectsOf(ev); !slices.Equal(got, []string{"mesh.bus.m.finding-events.finding-written.n1",
"mesh.bus.m.finding-events.finding-cleared.n1", "mesh.bus.m.finding-events.findings-stated.n1"}) {
t.Errorf("under the binding: %v", got)
}
for _, b := range []views.FindingBindings{nil, fakeBindings{asks: false}} {
if _, ev := say(b); !slices.Equal(subjectsOf(ev), []string{subjects.Written, subjects.Cleared, subjects.Stated}) {
t.Errorf("with no binding: %v", subjectsOf(ev))
}
}
if _, ev := say(fakeBindings{asks: true, err: errors.New("not bound yet")}); len(ev) != 0 {
t.Errorf("an unbound entry said %v", subjectsOf(ev))
}
}
func newRig(t *testing.T) *rig { return newRigKinds(t) }
func newRigKinds(t *testing.T, kinds ...string) *rig {
r := &rig{t: t, state: &fakeState{m: map[string][]byte{}}, now: time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC), ch: make(chan struct{}, 100)}
r.observe = func(context.Context) (testObserved, error) { return testObserved{}, nil }
w, err := views.NewWriter(testConfig{
Module: "m", State: r.state, Kinds: kinds, Node: "n1", Asked: asked,
Observe: func(ctx context.Context) (testObserved, error) { return r.observe(ctx) },
Logf: func(f string, a ...any) {
r.mu.Lock()
r.logs = append(r.logs, fmt.Sprintf(f, a...))
r.mu.Unlock()
},
Now: func() time.Time { r.mu.Lock(); defer r.mu.Unlock(); return r.now },
Wait: func(ctx context.Context, d time.Duration) bool {
r.mu.Lock()
defer r.mu.Unlock()
r.waits = append(r.waits, d)
r.now = r.now.Add(d)
return ctx.Err() == nil
},
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
r.mu.Lock()
defer r.mu.Unlock()
if r.fail > 0 {
r.fail--
return errors.New("no ack")
}
r.sent = append(r.sent, said{subject, data})
r.ch <- struct{}{}
return nil
},
Listen: func(_ context.Context, subject string, handle func([]byte)) (func(), error) {
r.mu.Lock()
defer r.mu.Unlock()
if subject != asked {
t.Errorf("listening on %s", subject)
}
r.listens++
r.handle = handle
return func() { r.mu.Lock(); r.stopped++; r.mu.Unlock() }, nil
},
})
if err != nil {
t.Fatal(err)
}
r.w = w
return r
}
func (r *rig) events() []said {
r.mu.Lock()
defer r.mu.Unlock()
return slices.Clone(r.sent)
}
func finding(id, summary string) testFinding {
return testFinding{Kind: "k", Scope: "module", ID: id, Severity: "warning", Summary: summary, Source: "probe",
Subject: testSubject{Scope: "module", ID: id}}
}
// A finding written says its event with the layout whole after the key, keeps the key's since, and says again only when
// what it says changed; a finding cleared says its event, also of a key that does not exist (design 47 G §383, §485).
func subWriterWritesAndClearsFindingsAsEvents(t *testing.T) {
r := newRig(t)
ctx := context.Background()
first := r.now
if err := r.w.Write(ctx, finding("a", "one")); err != nil {
t.Fatal(err)
}
r.now = r.now.Add(time.Hour)
f := finding("a", "one")
f.Run = "other run"
if err := r.w.Write(ctx, f); err != nil { // nothing said changed
t.Fatal(err)
}
if err := r.w.Write(ctx, finding("a", "two")); err != nil {
t.Fatal(err)
}
ev := r.events()
if len(ev) != 2 || ev[0].subject != subjects.Written || ev[1].subject != subjects.Written {
t.Fatalf("events: %+v", ev)
}
var got testFinding
if err := json.Unmarshal(ev[1].data, &got); err != nil {
t.Fatal(err)
}
if got.Summary != "two" || !got.Since.Equal(first) || got.Observer != "m" || views.FindingKey(got.Scope, got.ID, got.Kind) != "module.a.k" || !got.At.Equal(r.now) {
t.Fatalf("body: %+v", got)
}
if e, _ := r.state.Get("module.a.k"); e == nil {
t.Fatal("the key was not written")
}
if err := r.w.Clear(ctx, "module", "a", "k", "gone"); err != nil {
t.Fatal(err)
}
if err := r.w.Clear(ctx, "module", "never", "k", "held by the keeper"); err != nil {
t.Fatal(err)
}
ev = r.events()
var cl testCleared
if len(ev) != 4 || ev[3].subject != subjects.Cleared || json.Unmarshal(ev[3].data, &cl) != nil || cl.ID != "never" || cl.Why != "held by the keeper" {
t.Fatalf("clear events: %+v", ev)
}
if e, _ := r.state.Get("module.a.k"); e != nil {
t.Fatal("the key was not deleted")
}
}
// An event the bus does not acknowledge is sent again for one minute, then written in the journal as an error naming the
// finding (design 47 G §383).
func subWriterSendsAgainForAMinuteThenLogs(t *testing.T) {
r := newRig(t)
r.fail = 2
if err := r.w.Write(context.Background(), finding("a", "one")); err != nil || len(r.events()) != 1 {
t.Fatalf("resent: %v %+v", err, r.events())
}
r.fail = 1000
start := r.now
if err := r.w.Write(context.Background(), finding("b", "one")); err != nil {
t.Fatal(err)
}
if r.now.Sub(start) < views.PublishRetryFor || r.now.Sub(start) > views.PublishRetryFor+10*time.Second {
t.Fatalf("resent for %s", r.now.Sub(start))
}
if len(r.logs) != 1 || !strings.Contains(r.logs[0], "module.b.k") || !strings.Contains(r.logs[0], "error") {
t.Fatalf("journal: %v", r.logs)
}
}
// A start states the findings observed now, writes their keys, deletes the keys neither stated nor pending, and pends the
// rest; an ask naming another module is not answered, one naming none or this one is, with its id; an observe that fails
// says no set and is called again once a minute until a set is said; a connection made again makes the consumer again and
// states again (design 47 G §384, §461, §485).
func subWriterStatesAtStartAndOnAsksAndRecovers(t *testing.T) {
r := newRig(t)
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
r.state.Put("module.old.k", finding("old", "x"))
r.state.Put("module.wait.k", finding("wait", "x"))
first := r.now
r.state.Put("module.a.k", func() testFinding { f := finding("a", "before"); f.Since = first.Add(-time.Hour); return f }())
calls := 0
r.observe = func(context.Context) (testObserved, error) {
calls++
if calls <= 2 {
return testObserved{}, errors.New("not yet")
}
return testObserved{Findings: []testFinding{finding("a", "now")},
Pending: []views.PendingKey{{Key: "module.wait.k", Since: first, Bound: "5m"}}}, nil
}
if err := r.w.Start(ctx); err != nil {
t.Fatal(err)
}
defer r.w.Close()
stated := waitEvent(t, r, 1)
if calls != 3 || len(r.waits) != 2 || r.waits[0] != views.ObserveRetryEvery {
t.Fatalf("observe called %d times, waits %v", calls, r.waits)
}
var st testStated
if err := json.Unmarshal(stated.data, &st); err != nil {
t.Fatal(err)
}
if stated.subject != subjects.Stated || st.Asked != "" || len(st.Findings) != 1 || st.Findings[0].Summary != "now" ||
!st.Findings[0].Since.Equal(first.Add(-time.Hour)) || len(st.Pending) != 1 || st.Pending[0].Key != "module.wait.k" {
t.Fatalf("statement: %s", stated.data)
}
keys, _ := r.state.Keys()
slices.Sort(keys)
if !slices.Equal(keys, []string{"module.a.k", "module.wait.k"}) {
t.Fatalf("keys: %v", keys)
}
r.handle([]byte(`{"ask":"a1","at":"2026-11-11T12:00:00Z","by":"keeper","module":"other"}`))
r.handle([]byte(`{"ask":"a2","at":"2026-11-11T12:00:00Z","by":"keeper","module":"m"}`))
st = FindingsStatedOf(t, waitEvent(t, r, 2))
if st.Asked != "a2" || len(r.events()) != 2 {
t.Fatalf("ask answered: %+v %d", st, len(r.events()))
}
r.w.Reconnected()
waitEvent(t, r, 3)
if r.listens != 2 || r.stopped != 1 {
t.Fatalf("consumers made %d, stopped %d", r.listens, r.stopped)
}
}
func FindingsStatedOf(t *testing.T, e said) testStated {
var st testStated
if err := json.Unmarshal(e.data, &st); err != nil {
t.Fatal(err)
}
return st
}
// waitEvent is the n-th event said, woken by each event said (nothing sleeps for time).
func waitEvent(t *testing.T, r *rig, n int) said {
t.Helper()
for len(r.events()) < n {
select {
case <-r.ch:
case <-time.After(10 * time.Second):
t.Fatalf("event %d never said", n)
}
}
return r.events()[n-1]
}
// A write asked during a statement waits for it, so the statement never deletes the key the write made (design 47 G §485).
func subWriterRunsOneActAtATime(t *testing.T) {
r := newRig(t)
inside, release := make(chan struct{}), make(chan struct{})
r.observe = func(context.Context) (testObserved, error) {
close(inside)
<-release
return testObserved{}, nil
}
done := make(chan error, 1)
go func() { done <- r.w.State(context.Background(), "") }()
<-inside
wrote, started := make(chan error, 1), make(chan struct{})
go func() { close(started); wrote <- r.w.Write(context.Background(), finding("a", "one")) }()
<-started
for range 1000 {
runtime.Gosched()
}
close(release)
if err := <-done; err != nil {
t.Fatal(err)
}
if err := <-wrote; err != nil {
t.Fatal(err)
}
if e, _ := r.state.Get("module.a.k"); e == nil {
t.Fatal("the statement deleted the key the write made")
}
}
// A writer owns its kinds (design 47 G §580), states them, deletes no key of another kind, and covers a views reader's
// findings written through it beside observe's (§639); an owner or waiting-on of no form is refused, naming the field (§678).
func subWriterKindsAndReaderFindings(t *testing.T) {
ctx := context.Background()
r := newRigKinds(t, "k")
other := finding("x", "another bundle's")
other.Kind = "other"
otherKey := views.FindingKey(other.Scope, other.ID, other.Kind)
r.state.m[otherKey] = []byte(`{}`)
if err := r.w.Write(ctx, other); err == nil || !strings.Contains(err.Error(), `"other"`) {
t.Errorf("a write of another kind: %v", err)
}
if err := r.w.Clear(ctx, "module", "x", "other", "why"); err == nil || !strings.Contains(err.Error(), `"other"`) {
t.Errorf("a clear of another kind: %v", err)
}
for field, f := range map[string]testFinding{"owner": {Owner: "Not A Form"}, "waiting-on": {WaitingOn: "x y"}} {
b := finding("o", "s")
b.Owner, b.WaitingOn = f.Owner, f.WaitingOn
if err := r.w.Write(ctx, b); err == nil || !strings.Contains(err.Error(), field) {
t.Errorf("%s of no form: %v", field, err)
}
}
for _, v := range []string{"me@node-1", "mesh-catalog", "forge:jochen"} {
b := finding("ok", "s")
b.Owner = v
if err := r.w.Write(ctx, b); err != nil {
t.Errorf("owner %q: %v", v, err)
}
}
// a views reader writes through the part's writer, and the statement keeps its open findings
if err := views.PutViewFinding(r.w, views.ViewWaitsKind, "m.o.s", "waits", ""); err != nil {
t.Fatal(err)
}
r.observe = func(context.Context) (testObserved, error) {
return testObserved{Findings: []testFinding{finding("a", "observed")}}, nil
}
if err := r.w.State(ctx, ""); err != nil {
t.Fatal(err)
}
if _, ok := r.state.m["module.m=2eo=2es.view-waits"]; !ok {
t.Errorf("the statement deleted the reader's finding: %v", r.state.m)
}
if _, ok := r.state.m[otherKey]; !ok {
t.Errorf("the statement deleted another bundle's key")
}
if _, ok := r.state.m["module.ok.k"]; ok {
t.Errorf("a key of its own kind neither stated nor pending stays")
}
var stated testStated
for _, e := range r.events() {
if e.subject == subjects.Stated {
_ = json.Unmarshal(e.data, &stated)
}
}
if !slices.Contains(stated.Kinds, "k") || !slices.Contains(stated.Kinds, views.ViewWaitsKind) || len(stated.Findings) != 2 {
t.Errorf("the statement: kinds %v, %d findings", stated.Kinds, len(stated.Findings))
}
if err := views.DropViewFinding(r.w, views.ViewWaitsKind, "m.o.s"); err != nil {
t.Fatal(err)
}
if _, ok := r.state.m["module.m=2eo=2es.view-waits"]; ok {
t.Errorf("the reader's finding was not cleared")
}
}
// A views reader's four findings are laid out by mesh-sdk through the body's setters (design 47 G §687): the finding's
// kind, the scope module, the id escaped as a key's name is, a warning but urgent for view-too-large, the source views, the
// subject the module on its node; and CheckFinding refuses a finding breaking a rule before it is written, naming the field
// (§689).
func subReaderFindingsAreLaidOutAndCheckFindingRefuses(t *testing.T) {
r := newRig(t)
for _, kind := range views.ViewKinds {
if err := views.PutViewFinding(r.w, kind, "o.s.main", "sum "+kind, "head"); err != nil {
t.Fatal(err)
}
e, _ := r.state.Get("module.o=2es=2emain." + kind)
var got testFinding
if e == nil || json.Unmarshal(e.Value, &got) != nil {
t.Fatalf("%s not kept: %v", kind, r.state.m)
}
sev := "warning"
if kind == views.TooLargeKind {
sev = "urgent"
}
if got.Kind != kind || got.Scope != "module" || got.ID != "o=2es=2emain" || got.Severity != sev || got.Source != "views" ||
got.Subject.Scope != "module" || got.Subject.ID != "m" || got.Subject.Machine != "n1" || got.Summary != "sum "+kind || got.Headline != "head" || got.Observer != "m" {
t.Errorf("%s laid out as %+v", kind, got)
}
}
for name, c := range map[string]struct {
f testFinding
want string
}{
"scope": {testFinding{ID: "a", Kind: "k"}, "scope"},
"id": {testFinding{Scope: "module", Kind: "k"}, "id"},
"kind": {testFinding{Scope: "module", ID: "a"}, "kind"},
"dotted": {testFinding{Scope: "module", ID: "a", Kind: "k.x"}, "kind"},
"owner": {testFinding{Scope: "module", ID: "a", Kind: "k", Owner: "Not A Form"}, "owner"},
"waiting-on": {testFinding{Scope: "module", ID: "a", Kind: "k", WaitingOn: "x y"}, "waiting-on"},
} {
if err := views.CheckFinding(c.f); err == nil || !strings.Contains(err.Error(), c.want) {
t.Errorf("%s: %v", name, err)
}
if err := r.w.Write(context.Background(), c.f); err == nil {
t.Errorf("%s: written", name)
}
}
if err := views.CheckFinding(finding("a", "s")); err != nil {
t.Error(err)
}
}
// A finding body whose wire form lacks a field the contract names is refused when the writer is made, naming the field
// (design 47 G A-3).
func subWriterRefusesABodyWithoutAContractField(t *testing.T) {
type noSince struct {
Kind, Scope, ID, Observer string
At time.Time `json:"at"`
Subject testSubject
}
_, err := views.NewWriter(views.WriterConfig[noSince, testCleared, testStated, testAsked]{Module: "m", State: &fakeState{m: map[string][]byte{}}, Node: "n1", Asked: asked,
Observe: func(context.Context) (views.Observed[noSince], error) { return views.Observed[noSince]{}, nil },
Publish: func(context.Context, string, []byte, string) error { return nil },
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }})
if err == nil || !strings.Contains(err.Error(), `"kind"`) {
t.Fatalf("a body of other wire names: %v", err)
}
// the subject of findings-asked is the seat's and the module's to give; none given is refused (design 47 G A-17)
_, err = views.NewWriter(testConfig{Module: "m", State: &fakeState{m: map[string][]byte{}}, Node: "n1",
Observe: func(context.Context) (testObserved, error) { return testObserved{}, nil },
Publish: func(context.Context, string, []byte, string) error { return nil },
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }})
if err == nil || !strings.Contains(err.Error(), "findings-asked") {
t.Fatalf("a writer with no subject for findings-asked: %v", err)
}
}
// A part whose findings are raised as they happen holds them in a writer that observes from its own state (design 47 G A-29):
// the findings standing in the state are seeded before it starts, a statement says what is held, Write and Clear keep the held
// set, and an Observe of the part's own is refused.
func subHeldWriterStatesWhatItHoldsFromItsOwnState(t *testing.T) {
state := &fakeState{m: map[string][]byte{}}
raw, _ := json.Marshal(finding("seeded", "stood"))
state.m["module.seeded.k"] = raw
state.m["module.junk.k"] = []byte(`"not a finding"`)
var sent []said
cfg := testConfig{Module: "m", State: state, Node: "n1", Asked: asked,
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
sent = append(sent, said{subject, data})
return nil
},
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }}
cfg.Observe = func(context.Context) (testObserved, error) { return testObserved{}, nil }
if _, err := views.NewHeldWriter(cfg); err == nil {
t.Fatal("a held writer took an Observe of its own")
}
cfg.Observe = nil
h, err := views.NewHeldWriter(cfg)
if err != nil {
t.Fatal(err)
}
ctx := context.Background()
if err := h.Write(ctx, finding("raised", "now")); err != nil {
t.Fatal(err)
}
if err := h.Write(ctx, testFinding{Kind: "k", ID: "no-scope"}); err == nil {
t.Fatal("a finding that breaks a rule was held")
}
// a views reader writes its findings in the wire form: they are held as well (design 47 G A-37)
var wire map[string]any
rawWire, _ := json.Marshal(finding("wired", "from a reader"))
_ = json.Unmarshal(rawWire, &wire)
if err := h.WriteWire(ctx, wire); err != nil {
t.Fatal(err)
}
if err := h.Clear(ctx, "module", "seeded", "k", "no longer"); err != nil {
t.Fatal(err)
}
// a key the part cannot judge yet is named in the statement's pending until judged (design 47 G §384), keeping its since
since := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC)
h.Pend(views.PendingKey{Key: "machine.n1.a2.call-unanswered", Since: since, Bound: "5m"})
h.Pend(views.PendingKey{Key: "machine.n1.a2.call-unanswered", Since: since.Add(time.Hour), Bound: "5m"})
h.Pend(views.PendingKey{Key: "machine.n1.a3.call-unanswered", Since: since, Bound: "5m"})
h.Judged("machine.n1.a3.call-unanswered")
sent = nil
if err := h.State(ctx, "a1"); err != nil {
t.Fatal(err)
}
var stated testStated
if len(sent) != 1 || sent[0].subject != subjects.Stated || json.Unmarshal(sent[0].data, &stated) != nil ||
len(stated.Findings) != 2 || stated.Asked != "a1" {
t.Fatalf("the statement says %+v after %d events", stated, len(sent))
}
if p := stated.Pending; len(p) != 1 || p[0].Key != "machine.n1.a2.call-unanswered" || !p[0].Since.Equal(since) || p[0].Bound != "5m" {
t.Fatalf("the statement's pending is %+v", p)
}
if held := h.Held(); len(held) != 2 {
t.Fatalf("Held answers %v", held)
} else if held[0].ID = "mutated"; len(h.Held()) != 2 {
t.Fatal("Held is not a copy")
}
ids := []string{stated.Findings[0].ID, stated.Findings[1].ID}
slices.Sort(ids)
if ids[0] != "raised" || ids[1] != "wired" {
t.Fatalf("the statement says %v", ids)
}
}
// A held writer reads its state at Start, not when made: what was written before Start is held and written at Start, over
// what stood in the state (design 47 G A-40).
func subHeldWriterSeedsAtStart(t *testing.T) {
state := &fakeState{m: map[string][]byte{}}
raw, _ := json.Marshal(finding("seeded", "stood"))
state.m["module.seeded.k"] = raw
var mu sync.Mutex
cfg := testConfig{Module: "m", State: state, Node: "n1", Asked: asked,
Publish: func(context.Context, string, []byte, string) error { mu.Lock(); mu.Unlock(); return nil },
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }}
h, err := views.NewHeldWriter(cfg)
if err != nil {
t.Fatal(err)
}
ctx := context.Background()
if err := h.Write(ctx, finding("early", "before")); err != nil {
t.Fatal(err)
}
if held := h.Held(); len(held) != 1 || held[0].ID != "early" {
t.Fatalf("before Start Held answers what was written so far: %v", held)
}
if len(state.m) != 1 {
t.Fatalf("a write before Start touched the state: %v", state.m)
}
if err := h.Start(ctx); err != nil {
t.Fatal(err)
}
defer h.Close()
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)
}
}
// TestFindingSubjectsAreTheEventsStreamForm runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
func TestFindingSubjectsAreTheEventsStreamForm(t *testing.T) {
t.Run("FindingSubjectsAreTheEventsStreamForm", subFindingSubjectsAreTheEventsStreamForm)
t.Run("WriterSaysUnderItsFindingEventsBindingOrOnTheOldStream", subWriterSaysUnderItsFindingEventsBindingOrOnTheOldStream)
t.Run("WriterWritesAndClearsFindingsAsEvents", subWriterWritesAndClearsFindingsAsEvents)
t.Run("WriterSendsAgainForAMinuteThenLogs", subWriterSendsAgainForAMinuteThenLogs)
t.Run("WriterStatesAtStartAndOnAsksAndRecovers", subWriterStatesAtStartAndOnAsksAndRecovers)
t.Run("WriterRunsOneActAtATime", subWriterRunsOneActAtATime)
t.Run("WriterKindsAndReaderFindings", subWriterKindsAndReaderFindings)
t.Run("ReaderFindingsAreLaidOutAndCheckFindingRefuses", subReaderFindingsAreLaidOutAndCheckFindingRefuses)
t.Run("WriterRefusesABodyWithoutAContractField", subWriterRefusesABodyWithoutAContractField)
t.Run("HeldWriterStatesWhatItHoldsFromItsOwnState", subHeldWriterStatesWhatItHoldsFromItsOwnState)
t.Run("HeldWriterSeedsAtStart", subHeldWriterSeedsAtStart)
}