Skip to content

NATS JetStream Service

Purpose: Durable event streaming for audit trail and async processing Audience: Backend Engineers, DevOps Source of Truth: TRUTH_MAP.md

Last Updated: February 1, 2026

Purpose

NATS JetStream provides: - Durable event persistence - Async message processing - Audit trail streaming - Cross-service communication

Key Feature: Guarantees exactly-once delivery with persistent storage.

Configuration

Variable Required Default Description
NATS_URL Yes - Connection URL
NATS_USER No - Auth username
NATS_PASSWORD No - Auth password

Connection URL Format

nats://[user:password@]host:port

Connection

Environment Connection
Local (Docker) nats://localhost:4222
Railway (Production) nats://nats.railway.internal:4222
Production Use NATS_URL from Doppler/Railway secrets

Health Check

# HTTP monitoring endpoint
curl -s http://localhost:8222/healthz

# JetStream info
nats stream info FULCRUM_EVENTS --server "$NATS_URL"

# Consumer status
nats consumer info FULCRUM_EVENTS audit-consumer --server "$NATS_URL"

Streams

Stream Subjects Retention Purpose
FULCRUM_EVENTS fulcrum.> Limits (100GB) All events
FULCRUM_AUDIT fulcrum.audit.> Limits (1 year) Audit trail

Subject Hierarchy

fulcrum.{tenant_id}.{event_type}.{subtype}

Examples:
- fulcrum.abc123.envelope.created
- fulcrum.abc123.policy.evaluated
- fulcrum.abc123.budget.exceeded
- fulcrum.abc123.audit.login

Consumers

Consumer Stream Deliver Purpose
audit-consumer FULCRUM_EVENTS All Audit log persistence
metrics-consumer FULCRUM_EVENTS New Real-time metrics
dashboard-consumer FULCRUM_EVENTS New WebSocket updates

Event Schema

{
  "id": "evt_abc123",
  "tenant_id": "tenant_xyz",
  "type": "envelope.completed",
  "timestamp": "2026-01-15T12:00:00Z",
  "data": {
    "envelope_id": "env_123",
    "status": "COMPLETED",
    "cost": 0.05
  },
  "metadata": {
    "source": "policy-engine",
    "version": "1.0"
  }
}

Failure Modes

Failure Impact Detection Recovery
Connection lost Events queue locally Health check Reconnect, replay
Stream full New events rejected Storage metrics Increase limits or purge
Consumer lag Delayed processing Lag metrics Scale consumers
Message loss Audit gap Sequence check Investigate, replay

Monitoring

# Stream stats
nats stream report --server "$NATS_URL"

# Consumer lag
nats consumer report --server "$NATS_URL"

# Account info
nats account info --server "$NATS_URL"

Security

  • Network: NATS should NOT be exposed publicly
  • Auth: Use credentials in production
  • TLS: Enable for encrypted connections
  • Permissions: Limit publish/subscribe per tenant

Back to Runbooks | Documentation