JetStream

JetStream extends NATS with durable, replayable message storage rather than replacing NATS’s lightweight publish-and-subscribe model. A publisher sends a message to a subject; a stream captures messages whose subjects match its configuration, and one or more consumers receive them later according to delivery rules.¹

Streams are the primary storage abstraction. They can retain messages by limits such as age, bytes, or count, or by a work-queue policy in which acknowledged messages are removed. A stream may replicate data across servers, while its consumers maintain delivery and acknowledgment state. This separation lets multiple applications read the same event history independently, with different starting positions or filtering subjects.²

JetStream is commonly deployed inside a NATS server cluster. Its control and data protocols remain subject-based, so clients can use ordinary NATS connections and language libraries rather than a separate broker protocol.¹

Consumers define how a stream’s messages are delivered to an application. A durable consumer preserves its position and configuration across client disconnects, whereas an ephemeral consumer is intended for shorter-lived processing and may be removed when inactive.³

JetStream supports pull and push delivery. Pull consumers let workers request batches or individual messages, which gives applications explicit control over concurrency and back pressure; push consumers deliver messages to a configured subject. Acknowledgments tell the server that processing succeeded, and an acknowledgment wait period can cause an unacknowledged message to be redelivered.³

Subjects can be filtered at the stream and consumer levels. Consumers can begin at the newest message, at a sequence or time, or at the point recorded in their durable state. These choices support event replay, catch-up processing, competing workers, and fan-out to several independent services.²

JetStream’s reliability comes from acknowledged delivery, replicated stream state, and explicit retention rather than from an assumption that every network operation succeeds. A client may acknowledge a message after its work is complete; if the server does not receive that acknowledgment, the message can be delivered again, so handlers should be idempotent or otherwise account for duplicates.³

Message identifiers can be used for publish deduplication within a configured window, and JetStream provides acknowledgment mechanisms designed to reduce ambiguity when a client receives a publish response or confirms processing.⁴ Replicas improve availability, but they do not remove the need to choose suitable storage, quorum, retention, and recovery policies. File storage is used for persistent streams; memory storage is available where volatility is acceptable.²

Operational design therefore involves monitoring consumer lag, redeliveries, pending acknowledgments, storage limits, and replica health—not merely checking whether a connection is open.

JetStream also provides higher-level services built on its stream primitives. The JetStream key-value API stores revisions of named keys and can expose history, watches, and compare-and-set-style operations; its object-store API divides larger objects into chunks and stores them through JetStream rather than pretending that the message layer is a conventional file system.⁵

A less obvious distinction is between retention and replay. A stream may retain an event for audit or reconstruction, while a consumer’s acknowledgment state determines which messages a particular application still needs. Work-queue retention instead treats successful acknowledgment as grounds for removal, making it suitable for task distribution but unsuitable as a shared event history.²

JetStream’s server-side APIs are themselves exposed through NATS subjects, and its clients can manage streams and consumers programmatically. This makes infrastructure-as-code and automated provisioning practical, but permissions must cover both ordinary application subjects and administrative API subjects.¹

Stream

A named JetStream resource that stores messages matching configured NATS subjects.

Consumer

A stateful view of a stream that controls message delivery, acknowledgment, filtering, and replay position.

Durable consumer

A consumer whose state is retained so processing can resume after a client disconnects.

Pull consumer

A consumer from which clients explicitly request messages, often to regulate worker concurrency and back pressure.

Work-queue retention

A retention policy that removes messages after successful acknowledgment, supporting task distribution.