From 68670789d1471d852b7917b504c1ed157044b55c Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:42:30 +0100 Subject: [PATCH] G A-13: the finding writer forms its four subjects itself, views.FindingSubjects(module, node) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G A-13, §461, §439, §383 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/views/writer.go | 37 +++++++++++++++++------------ go/views/writer_integration_test.go | 20 ++++++++-------- go/views/writer_test.go | 20 +++++++++++----- 3 files changed, 46 insertions(+), 31 deletions(-) diff --git a/go/views/writer.go b/go/views/writer.go index 0acd499c..5e40157e 100644 --- a/go/views/writer.go +++ b/go/views/writer.go @@ -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..event..` (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 } diff --git a/go/views/writer_integration_test.go b/go/views/writer_integration_test.go index e89ce052..f697dffc 100644 --- a/go/views/writer_integration_test.go +++ b/go/views/writer_integration_test.go @@ -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) } } diff --git a/go/views/writer_test.go b/go/views/writer_test.go index 36ce4d50..5889e15a 100644 --- a/go/views/writer_test.go +++ b/go/views/writer_test.go @@ -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"`) {