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).
This commit is contained in:
sam committed 2026-09-19 01:51:07 +10:00
1 parent 3da93b8076
commit 9e8427bc8e
4 files changed
+173 -8

No files matched your search

+25 -1
View File
@@ -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
}
@@ -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)
}
}
}
+8
View File
@@ -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")
@@ -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
}