G A-13: the finding writer forms its four subjects itself, views.FindingSubjects(module, node)

Builds: design 47 G A-13, §461, §439, §383
Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-11 21:42:30 +01:00
parent 8a2f6bf6d3
commit 68670789d1
3 changed files with 46 additions and 31 deletions
+22 -15
View File
@@ -111,12 +111,19 @@ type FindingState interface {
Keys() ([]string, error)
}
// WriterSubjects are the subjects of the four events, as the seat's generated contract makes them for the observer's
// module and node.
// WriterSubjects are the subjects of the four events of an observer's module and node.
type WriterSubjects struct {
Written, Cleared, Stated, Asked string
}
// FindingSubjects are the subjects of the four events of the module's findings 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.
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"), Asked: of("findings-asked")}
}
// 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.
@@ -130,10 +137,8 @@ type WriterConfig[F, C, S, A any] struct {
// JS is the bus connection's JetStream; Conn, when given, lets the writer hear the connection made again.
JS jetstream.JetStream
Conn *nats.Conn
// Subjects are the four events' subjects.
Subjects WriterSubjects
// Node is the machine the module runs on, which a views reader's findings name in their subject (design 47 G §687);
// none given, MESH_NODE.
// 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.
@@ -156,7 +161,8 @@ type WriterConfig[F, C, S, A any] struct {
// 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]
mu sync.Mutex // the one lock of the acts
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()
@@ -176,8 +182,6 @@ func NewWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*Writer[F, C, S, A
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.Subjects.Written == "" || cfg.Subjects.Cleared == "" || cfg.Subjects.Stated == "" || cfg.Subjects.Asked == "":
return nil, errors.New("a finding writer needs the subjects of finding-written, finding-cleared, findings-stated and findings-asked")
case cfg.JS == nil && (cfg.Publish == nil || cfg.Listen == nil):
return nil, errors.New("a finding writer needs the bus connection's JetStream")
}
@@ -196,6 +200,9 @@ func NewWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*Writer[F, C, S, A
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() }
}
@@ -220,7 +227,7 @@ func NewWriter[F, C, S, A any](cfg WriterConfig[F, C, S, A]) (*Writer[F, C, S, A
if cfg.Listen == nil {
cfg.Listen = jetStreamListen(cfg.JS)
}
return &Writer[F, C, S, A]{cfg: cfg, wake: make(chan struct{}, 1)}, nil
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 {
@@ -298,7 +305,7 @@ func (w *Writer[F, C, S, A]) Close() {
}
func (w *Writer[F, C, S, A]) listen() error {
stop, err := w.cfg.Listen(w.run, w.cfg.Subjects.Asked, w.heard)
stop, err := w.cfg.Listen(w.run, w.subj.Asked, w.heard)
if err != nil {
return err
}
@@ -318,7 +325,7 @@ func (w *Writer[F, C, S, A]) Reconnected() {
return
}
if err := w.listen(); err != nil {
w.cfg.Logf("the finding writer could not make its consumer of %s again: %v", w.cfg.Subjects.Asked, err)
w.cfg.Logf("the finding writer could not make its consumer of %s again: %v", w.subj.Asked, err)
}
w.asks, w.want = append(w.asks, ""), true
w.signal()
@@ -528,7 +535,7 @@ func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
return nil
}
raw, _ := json.Marshal(f)
w.say(ctx, w.cfg.Subjects.Written, "finding-written", keyOf(f), raw)
w.say(ctx, w.subj.Written, "finding-written", keyOf(f), raw)
return nil
}
@@ -549,7 +556,7 @@ func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why str
return err
}
raw, _ := json.Marshal(&cleared)
w.say(ctx, w.cfg.Subjects.Cleared, "finding-cleared", key, raw)
w.say(ctx, w.subj.Cleared, "finding-cleared", key, raw)
return nil
}
@@ -617,7 +624,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
return nil
}
}
w.say(ctx, w.cfg.Subjects.Stated, "findings-stated", w.cfg.Module, raw)
w.say(ctx, w.subj.Stated, "findings-stated", w.cfg.Module, raw)
return nil
}
+10 -10
View File
@@ -30,12 +30,13 @@ func TestWriterSaysItsEventsAndHearsAsksOnTheBus(t *testing.T) {
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
for name, subj := range map[string]string{"EVENTS": "obs.event.>", "ASKS": "obs.ask"} {
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: name, Subjects: []string{subj}}); err != nil {
subj := views.FindingSubjects("m", "n1")
for name, subjects := range map[string][]string{"EVENTS": {subj.Written, subj.Cleared, subj.Stated}, "ASKS": {subj.Asked}} {
if _, err := js.CreateStream(ctx, jetstream.StreamConfig{Name: name, Subjects: subjects}); err != nil {
t.Fatal(err)
}
}
if _, err := js.Publish(ctx, "obs.ask", []byte(`{"ask":"old","at":"2026-11-11T12:00:00Z","by":"keeper"}`)); err != nil {
if _, err := js.Publish(ctx, subj.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})
@@ -44,7 +45,6 @@ func TestWriterSaysItsEventsAndHearsAsksOnTheBus(t *testing.T) {
}
state := &fakeState{m: map[string][]byte{}}
w, err := views.NewWriter(testConfig{Module: "m", State: state, JS: js, Conn: nc, Node: "n1",
Subjects: views.WriterSubjects{Written: "obs.event.written", Cleared: "obs.event.cleared", Stated: "obs.event.stated", Asked: "obs.ask"},
Observe: func(context.Context) (testObserved, error) {
return testObserved{Findings: []testFinding{finding("a", "now")}}, nil
}, Logf: t.Logf})
@@ -65,27 +65,27 @@ func TestWriterSaysItsEventsAndHearsAsksOnTheBus(t *testing.T) {
t.Fatalf("said %s, want %s", m.Subject(), want)
}
var st testStated
if want == "obs.event.stated" {
if want == subj.Stated {
if err := json.Unmarshal(m.Data(), &st); err != nil {
t.Fatal(err)
}
}
return st
}
if st := next("obs.event.stated"); st.Asked != "" || len(st.Findings) != 1 {
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("obs.event.written")
next(subj.Written)
for _, ask := range []string{"new", "again"} {
w.Reconnected()
next("obs.event.stated") // the statement after the connection was made again
if _, err := js.Publish(ctx, "obs.ask", []byte(`{"ask":"`+ask+`","at":"2026-11-11T12:00:00Z","by":"keeper"}`)); err != nil {
next(subj.Stated) // the statement after the connection was made again
if _, err := js.Publish(ctx, subj.Asked, []byte(`{"ask":"`+ask+`","at":"2026-11-11T12:00:00Z","by":"keeper"}`)); err != nil {
t.Fatal(err)
}
if st := next("obs.event.stated"); st.Asked != ask {
if st := next(subj.Stated); st.Asked != ask {
t.Fatalf("answered %q, want %q", st.Asked, ask)
}
}
+14 -6
View File
@@ -75,9 +75,17 @@ type rig struct {
ch chan struct{}
}
var subjects = 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", Asked: "mesh.seat.s.event.findings-asked",
// 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")
func TestFindingSubjectsAreTheEventsStreamForm(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", Asked: "mesh.stream.m.event.findings-asked.n1",
}
if subjects != want {
t.Fatalf("the subjects: %+v, want %+v", subjects, want)
}
}
func newRig(t *testing.T) *rig { return newRigKinds(t) }
@@ -86,7 +94,7 @@ 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, Subjects: subjects, Kinds: kinds, Node: "n1",
Module: "m", State: r.state, Kinds: kinds, Node: "n1",
Observe: func(ctx context.Context) (testObserved, error) { return r.observe(ctx) },
Logf: func(f string, a ...any) {
r.mu.Lock()
@@ -438,8 +446,8 @@ func TestWriterRefusesABodyWithoutAContractField(t *testing.T) {
At time.Time `json:"at"`
Subject testSubject
}
_, err := views.NewWriter(views.WriterConfig[noSince, testCleared, testStated, testAsked]{Module: "m", State: &fakeState{m: map[string][]byte{}},
Subjects: subjects, Observe: func(context.Context) (views.Observed[noSince], error) { return views.Observed[noSince]{}, nil },
_, err := views.NewWriter(views.WriterConfig[noSince, testCleared, testStated, testAsked]{Module: "m", State: &fakeState{m: map[string][]byte{}}, Node: "n1",
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"`) {