From 9e8427bc8e2970441acf69e6dc6f95c9c7b4bb66 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 19 Sep 2026 01:51:07 +1000 Subject: [PATCH] feat(nats): provision the ARCHIE_REACTIONS fan-out stream archie.reaction.* had no matching stream. bootstrap.go:501-502 bound only ARCHIE_TASKS to archie.task.> under WorkQueuePolicy, so any publish to a reaction subject made js.PublishMsg fail and the publisher saw a publish error -- the reason a previously landed reaction producer would have answered HTTP 500 on every webhook delivery. ARCHIE_TASKS must stay WorkQueuePolicy: under it a second consumer on an overlapping filter subject silently receives nothing, which is the trap recorded in CLAUDE.md. Reactions need the opposite property, so they get a second stream: - workintake.SubjectReactionWildcard ("archie.reaction.>") - nats.DefaultReactionStreamName ("ARCHIE_REACTIONS") - nats.FanOutRetention(), a pointer helper so composition can select LimitsPolicy without importing the NATS SDK, since nil Retention already means WorkQueuePolicy and the zero value (LimitsPolicy) is a valid explicit choice - a second nats.Connect in connectNATS carrying that stream, closed on failure and registered for shutdown cleanup Red-then-green: TestConnectNATSCreatesReactionStream failed with "publish to archie.reaction.* = nats: no response from stream, want it to land in ARCHIE_REACTIONS" before the stream existed. Step 1 of docs/prds/pr-review-remediation.md (bead archie-core-8li9.1). --- internal/app/archied/bootstrap.go | 26 +++- internal/app/archied/reaction_stream_test.go | 117 ++++++++++++++++++ internal/domain/workintake/subjects.go | 8 ++ .../infrastructure/eventbus/nats/config.go | 30 +++-- 4 files changed, 173 insertions(+), 8 deletions(-) create mode 100644 internal/app/archied/reaction_stream_test.go diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 78f95a167..1a867b05a 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -507,11 +507,35 @@ func (b *boot) connectNATS(ctx context.Context) error { //nolint:nestif // embed log.Error("nats connect failed", "err", err) return err } + + // Reactions are producer-only fan-out events: every interested consumer + // must see each one, so they get their own stream under LimitsPolicy + // rather than the work-queue policy ARCHIE_TASKS uses (which lets a + // second consumer on an overlapping filter silently receive nothing). + reactionClient, err := nats.Connect(ctx, nats.Config{ + URL: url, + Token: natsToken, + StreamName: nats.DefaultReactionStreamName, + Subjects: []string{workintake.SubjectReactionWildcard}, + FilterSubject: workintake.SubjectReactionWildcard, + Retention: nats.FanOutRetention(), + }, log) + if err != nil { + log.Error("nats reaction stream connect failed", "err", err) + natsClient.Close() + return err + } + b.natsClient = natsClient b.natsURL = url b.natsToken = natsToken b.addCleanup(func() { natsClient.Close() }) - log.Info("nats connected", "url", url) + // The reaction client is kept only so its connection stays open for the + // daemon's lifetime and is closed at shutdown; the stream it provisions + // is the deliverable. A future producer (bead archie-core-8li9.3) will + // need its own publisher surface, wired when that step lands. + b.addCleanup(func() { reactionClient.Close() }) + log.Info("nats connected", "url", url, "task_stream", nats.DefaultStreamName, "reaction_stream", nats.DefaultReactionStreamName) return nil } diff --git a/internal/app/archied/reaction_stream_test.go b/internal/app/archied/reaction_stream_test.go new file mode 100644 index 000000000..85c141898 --- /dev/null +++ b/internal/app/archied/reaction_stream_test.go @@ -0,0 +1,117 @@ +package archied + +import ( + "log/slog" + "path/filepath" + "slices" + "testing" + "time" + + natsio "github.com/nats-io/nats.go" + "github.com/nats-io/nats.go/jetstream" + + "github.com/samcharles93/archie-core/internal/config" +) + +// TestConnectNATSCreatesReactionStream pins the ARCHIE_REACTIONS stream the +// daemon must provision alongside ARCHIE_TASKS. A publish to archie.reaction.* +// must land in a fan-out (LimitsPolicy) stream: two consumers on overlapping +// filter subjects both receive it. Under the WorkQueuePolicy ARCHIE_TASKS +// keeps, the second consumer would silently receive nothing (the trap +// documented in CLAUDE.md). +// +// Before this stream existed the publish below failed with "no matching +// stream" because connectNATS bound only archie.task.>. +func TestConnectNATSCreatesReactionStream(t *testing.T) { + b := &boot{ + cfg: config.Config{ + DBPath: filepath.Join(t.TempDir(), "archie.db"), + NATS: config.NATSConfig{Mode: config.NATSModeEmbedded}, + }, + log: slog.New(slog.DiscardHandler), + } + if err := b.connectNATS(t.Context()); err != nil { + t.Fatalf("connectNATS = %v", err) + } + t.Cleanup(b.cleanup) + + conn, err := natsio.Connect(b.natsURL, natsio.Token(b.natsToken)) + if err != nil { + t.Fatalf("raw nats connect = %v", err) + } + t.Cleanup(conn.Close) + + js, err := jetstream.New(conn) + if err != nil { + t.Fatalf("jetstream.New = %v", err) + } + + // Criterion 1: a publish to archie.reaction.* lands in ARCHIE_REACTIONS. + // Before the stream existed this returned "no matching stream". + if _, err := js.PublishMsg(t.Context(), &natsio.Msg{ + Subject: "archie.reaction.test", + Data: []byte("x"), + }); err != nil { + t.Fatalf("publish to archie.reaction.* = %v, want it to land in ARCHIE_REACTIONS", err) + } + + stream, err := js.Stream(t.Context(), "ARCHIE_REACTIONS") + if err != nil { + t.Fatalf("js.Stream(ARCHIE_REACTIONS) = %v", err) + } + info, err := stream.Info(t.Context()) + if err != nil { + t.Fatalf("stream.Info = %v", err) + } + if info.Config.Retention != jetstream.LimitsPolicy { + t.Fatalf("ARCHIE_REACTIONS retention = %v, want %v (fan-out)", info.Config.Retention, jetstream.LimitsPolicy) + } + if !slices.Contains(info.Config.Subjects, "archie.reaction.>") { + t.Fatalf("ARCHIE_REACTIONS subjects = %v, want to contain archie.reaction.>", info.Config.Subjects) + } + + // Criterion 2: two consumers on the same overlapping filter subject both + // receive the one published message. A work-queue stream would deliver it + // to only one of them. + got := make(chan string, 2) + fetch := func() { + consumer, err := stream.CreateOrUpdateConsumer(t.Context(), jetstream.ConsumerConfig{ + FilterSubject: "archie.reaction.>", + AckPolicy: jetstream.AckExplicitPolicy, + }) + if err != nil { + t.Errorf("create reaction consumer: %v", err) + return + } + batch, err := consumer.Fetch(1, jetstream.FetchMaxWait(5*time.Second)) + if err != nil { + t.Errorf("reaction consumer fetch: %v", err) + return + } + for msg := range batch.Messages() { + if msg == nil { + continue + } + got <- string(msg.Data()) + _ = msg.Ack() + } + } + go fetch() + go fetch() + + var received []string + deadline := time.After(10 * time.Second) + for len(received) < 2 { + select { + case data := <-got: + received = append(received, data) + case <-deadline: + t.Fatalf("fan-out: received %v, want both consumers to receive x", received) + } + } + for _, data := range received { + if data != "x" { + t.Errorf("reaction consumer received %q, want x", data) + } + } +} diff --git a/internal/domain/workintake/subjects.go b/internal/domain/workintake/subjects.go index 8d99f3e30..318e3e8ab 100644 --- a/internal/domain/workintake/subjects.go +++ b/internal/domain/workintake/subjects.go @@ -18,6 +18,14 @@ const ( SubjectTaskWildcard = "archie.task.>" ) +// SubjectReactionWildcard matches every reaction subject under archie.reaction. +// Reactions are producer-only fan-out events +// (docs/prds/event-sources-and-reactions.md) delivered on a separate +// LimitsPolicy stream, so every registered consumer sees every matching event +// -- unlike the work-queue ARCHIE_TASKS stream, where one consumer claims each +// message. +const SubjectReactionWildcard = "archie.reaction.>" + // ErrUnknownKind reports a kind with no subject. Routing it to the default // queue instead would silently misdeliver work. var ErrUnknownKind = errors.New("workintake: unknown task kind") diff --git a/internal/infrastructure/eventbus/nats/config.go b/internal/infrastructure/eventbus/nats/config.go index 1d735007a..7e78397d2 100644 --- a/internal/infrastructure/eventbus/nats/config.go +++ b/internal/infrastructure/eventbus/nats/config.go @@ -10,13 +10,17 @@ import ( // Defaults for Config. Previously these were unexported package constants, // which made stream naming and timeouts untunable per deployment. const ( - DefaultStreamName = "ARCHIE_TASKS" - DefaultConsumerName = "archie-daemon" - DefaultDedupWindow = 2 * time.Minute - DefaultPollTimeout = 2 * time.Second - DefaultAckWait = 5 * time.Minute - DefaultMaxDeliver = 3 - DefaultInactiveTTL = 24 * time.Hour + DefaultStreamName = "ARCHIE_TASKS" + // DefaultReactionStreamName is the fan-out stream carrying reaction + // subjects. It coexists with DefaultStreamName (ARCHIE_TASKS), which + // stays work-queue for task distribution. + DefaultReactionStreamName = "ARCHIE_REACTIONS" + DefaultConsumerName = "archie-daemon" + DefaultDedupWindow = 2 * time.Minute + DefaultPollTimeout = 2 * time.Second + DefaultAckWait = 5 * time.Minute + DefaultMaxDeliver = 3 + DefaultInactiveTTL = 24 * time.Hour ) // Config describes how to reach NATS and how the stream and consumer should @@ -127,3 +131,15 @@ func (c Config) withDefaults() Config { } return c } + +// FanOutRetention returns a pointer to jetstream.LimitsPolicy for use as +// Config.Retention. It exists so composition can select fan-out retention +// without importing the NATS SDK: the retention policy type stays behind this +// package's boundary, like every other JetStream type. LimitsPolicy is the one +// policy that cannot be expressed by leaving Retention unset (withDefaults +// treats nil as WorkQueuePolicy), so the choice must be visible at the call +// site. +func FanOutRetention() *jetstream.RetentionPolicy { + policy := jetstream.LimitsPolicy + return &policy +}