Don't Panic — NATS Fundamentals

NATS is a messaging system that connects applications through subjects. A publisher sends a message to a subject; subscribers that express interest receive it without either side knowing the other's network address. It is a small binary that routes messages, from one server on a laptop to clusters spanning regions.

Before systems like this, services that wanted to talk to each other had to know each other's addresses, and a change in one meant a change in the other. NATS exists so that the address is a name — a subject — and the broker finds the listener.

Three ideas hold the practice up. Subjects are the addressing system, dot-separated names with * and > wildcards, and they are an API and a security boundary that is hard to change once applications depend on it. Core NATS is publish-subscribe for currently connected subscribers, at most once, with no storage — a message to a subject with no listener is not a failure, it is by design. JetStream adds persistent streams and consumers on top, decoupling publisher and subscriber in time as well as space, with at-least-once delivery and replay.

The one thing that surprises people: a missed Core NATS message is not a bug. Core NATS does not store, retry, or replay; it delivers to whoever is listening now. A team that uses Core NATS for order placement and then reports lost orders when a consumer restarts has not found a defect — it has chosen the wrong layer for a workload that needs time. The fix is a JetStream stream, not a bigger cluster.

The thing that catches every team: a JetStream acknowledgement is at-least-once, not exactly-once. Any unacknowledged message is redelivered, and a crash between the business work and the ack means the same message is processed twice. JetStream buys time-decoupling at the price of idempotency, and the application owns the idempotency — deduplication keys, idempotent operations — no matter how the stream is configured.

And the hard part is not the broker. The nats-server is a single binary that runs anywhere. The hard part is choosing a subject namespace that can survive the next year of features, because that namespace is the API.

Read the Intro for the two layers and the boundary between them. The Cheatsheet holds the subject wildcards and the consumer start positions side by side. The Timeline shows how a 2011 Cloud Foundry control plane grew JetStream, leaf nodes, and an agentic-AI workload — and why the subject model stayed the same while the persistence layer changed underneath it.