NATS

This skill covers NATS across versions 2.10 through 2.12, including:

• Core NATS (fire-and-forget pub/sub, subject-based addressing, queue groups, request/reply)
• JetStream (persistent streams, consumers, deduplication, exactly-once, retention policies)
• KV Store (bucket CRUD, watch, history, compare-and-swap, per-key TTL)
• Object Store (large file chunking, metadata, links)
• Clustering (route-based full mesh, RAFT consensus for JetStream, multi-route connections)
• Super-clusters (gateways for cross-cluster connectivity, interest propagation)
• Leaf nodes (hub-and-spoke, edge/IoT, hybrid cloud)
• Security (accounts, NKey, JWT decentralized auth, auth callout, mTLS)
• Monitoring (HTTP endpoints, nats-top, Prometheus exporter, system account events)
• Stream mirrors and sources (geographic distribution, aggregation, mirror promotion)

How to Approach Tasks

1. Classify the request:

   • Troubleshooting -- Load references/diagnostics.md for consumer lag, stream issues, cluster health, connectivity, and CLI tools
   • Architecture / design -- Load references/architecture.md for Core NATS, JetStream, clustering, security, KV/Object Store
   • Best practices -- Load references/best-practices.md for subject design, stream configuration, consumer tuning, security, monitoring

2. Identify version -- Key version gates:

   • Multi-filter consumers, S2 compression, subject transforms, auth callout (2.10)
   • Per-message TTL, consumer pausing, priority groups, distributed tracing (2.11)
   • Atomic batch publish, distributed counters, delayed scheduling, mirror promotion, strict mode default (2.12)

3. Load context -- Read the relevant reference file before answering.

4. Recommend -- Provide actionable guidance with nats CLI commands, server config, and SDK examples.

Core Architecture

Core NATS (Fire-and-Forget)

Sub-millisecond latency. No persistence. If no subscriber exists, message is dropped. Optimized for speed and simplicity.

Subject-Based Addressing

Subjects use . as token separator. Wildcards (subscribers only): * (single token), > (multi-token tail).

orders.us.created       -- specific subject
orders.*.created        -- matches orders.us.created, orders.eu.created
orders.>                -- matches orders.us, orders.us.east.created

Queue Groups

Built-in load balancing. Multiple subscribers on same queue group receive messages round-robin:

nats sub --queue workers "orders.>"    # subscriber 1
nats sub --queue workers "orders.>"    # subscriber 2 (load-balanced)

JetStream

Built-in persistence engine. Streams capture messages from subjects. Consumers track position independently.

Retention policies: LimitsPolicy (default, retain to limits), WorkQueuePolicy (consume-once), InterestPolicy (retain while consumers exist).

Consumer types: Pull (recommended) or Push. Durable (named, persistent state) or Ephemeral.

KV Store and Object Store

KV: Built on JetStream streams. Consistent key-value with watch, history, CAS. Object Store: Large binary chunking with metadata and SHA-256 checksums.

Anti-Patterns

Anti-Pattern	Why It Fails	Instead
Using Core NATS for critical business events	No persistence; messages dropped if no subscriber	Use JetStream with explicit ack
Unbounded streams without limits	Disk fills up; no backpressure	Set MaxAge, MaxBytes, MaxMsgs
Push consumers for work queue patterns	Less control over flow; harder to scale	Use pull consumers
Publishing to wildcards	Not supported; server rejects	Publish to specific subjects
Large deduplication windows	Memory overhead per tracked ID	Keep Duplicates window as short as practical (default 2min)
Even-sized clusters	Split-brain risk	Use odd node counts (3 or 5)

Reference Files

• references/architecture.md -- Core NATS, JetStream streams/consumers, KV Store, Object Store, clustering (routes, gateways, leaf nodes), security (accounts, NKey, JWT, auth callout), monitoring
• references/best-practices.md -- Subject namespace design, stream configuration, consumer tuning, deduplication, security hardening, monitoring setup, version-specific features
• references/diagnostics.md -- Stream lag, consumer issues, cluster health, RAFT troubleshooting, connectivity, slow consumers, CLI reference, health checks

Cross-References

• The overview skill -- cross-broker comparisons and event-driven architecture design