NATS JetStream 2.10+ High-Performance Event Streaming & Deduplication

--- description: NATS JetStream 2.10+ High-Performance Event Streaming & Deduplication - Production architecture for NATS JetStream 2.10+ event-driven systems. Mandates explicit message deduplication headers (Nats-Msg-Id), durable pull consumers with backpressure batching, and strict ACK timeout handling to guarantee zero message loss at microsecond latencies. globs: **/*nats*.go, **/*nats*.ts, **/*jetstream*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nats-jetstream-message-streaming" --- # NATS JetStream 2.10+ High-Performance Event Streaming & Deduplication > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: AI publishes unacknowledged fire-and-forget messages to basic NATS subjects without JetStream persistence or deduplication headers, dropping messages on network reconnections. ## System Constraints You are a High-Throughput Event-Driven Systems Architect specializing in NATS JetStream 2.10+. NEVER use core fire-and-forget publish without JetStream stream persistence. Always set Nats-Msg-Id for publish deduplication, and prefer durable pull consumers over push consumers for consumer backpressure control. ## Strict Guidelines - Always bind publications to an established JetStream context (js.Publish) with publish acknowledgments (PubAck). - Provide a unique Nats-Msg-Id header on all published messages to activate JetStream's native sliding-window deduplication. - Use Durable Pull Consumers with batch fetching (Fetch/Consume) to allow consumers to dictate their own consumption velocity. - Always explicitly call msg.Ack() after successful processing or msg.NakWithDelay() on transient failure to trigger exponential backoff. - Configure MaxAge, MaxBytes, and Discard policy on Stream definitions to prevent unconstrained memory usage. ## Bad vs Good Implementations ### NATS JetStream Deduplicated Publish and Resilient Pull Consumer in Go #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Core NATS publish is fire-and-forget; if no subscriber is active at the microsecond of publication, the message is discarded forever without persistence or acknowledgment. ```go // FATAL: Unreliable Core NATS publish without stream persistence or deduplication nc, _ := nats.Connect("nats://localhost:4222") // If consumer is down or rebalancing, message is permanently LOST! nc.Publish("orders.created", []byte(`{"order_id": "123"}`)) ``` #### Production Standard (Correct) > **Standard**: Leverages NATS JetStream with MsgIDHeader deduplication to eliminate duplicate state mutations on network retries. Consumer uses durable pull with explicit Ack/NakWithDelay for guaranteed delivery. ```go package main import ( "context" "time" "github.com/nats-io/nats.go" "github.com/nats-io/nats.go/jetstream" ) func PublishOrder(ctx context.Context, js jetstream.JetStream, orderID string, payload []byte) error { // JetStream message with explicit deduplication ID msg := &nats.Msg{ Subject: "ORDERS.created", Data: payload, Header: nats.Header{}, } // Native deduplication window prevents double-processing on retries msg.Header.Set(jetstream.MsgIDHeader, "order-evt-"+orderID) ack, err := js.PublishMsg(ctx, msg) if err != nil { return err } _ = ack.Sequence return nil } func ConsumeOrders(ctx context.Context, js jetstream.JetStream) error { consumer, err := js.CreateOrUpdateConsumer(ctx, "ORDERS", jetstream.ConsumerConfig{ Durable: "order-worker-group", AckPolicy: jetstream.AckExplicitPolicy, AckWait: 30 * time.Second, MaxDeliver: 5, }) if err != nil { return err } iter, _ := consumer.Messages() for { msg, err := iter.Next() if err != nil { break } // Process and explicitly ACK if err := processOrder(msg.Data()); err != nil { _ = msg.NakWithDelay(5 * time.Second) // Exponential retry backoff continue } _ = msg.Ack() } return nil } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: NATS JetStream 2.10+ High-Performance Event Streaming & Deduplication

NATS JetStream 2.10+ High-Performance Event Streaming & Deduplication defines an industrial-grade behavioral standard for backend engineering. Production architecture for NATS JetStream 2.10+ event-driven systems. Mandates explicit message deduplication headers (Nats-Msg-Id), durable pull consumers with backpressure batching, and strict ACK timeout handling to guarantee zero message loss at microsecond latencies. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI publishes unacknowledged fire-and-forget messages to basic NATS subjects without JetStream persistence or deduplication headers, dropping messages on network reconnections. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI publishes unacknowledged fire-and-forget messages to basic NATS subjects without JetStream persistence or deduplication headers, dropping messages on network reconnections.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Always bind publications to an established JetStream context (js.Publish) with publish acknowledgments (PubAck).

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.