English for NATS JetStream

JetStream adds durable, replayable persistence on top of NATS’s lightweight pub-sub core, and the vocabulary shift — from plain “subjects” to “streams” and “consumers” — trips people up in design discussions if the terms aren’t used precisely. This guide covers the core terms.

Key Vocabulary

Stream — a durable, ordered log of messages captured from one or more subjects, the JetStream equivalent of a Kafka topic partition set, configured with its own retention and storage policy. “We created a stream called ORDERS that captures everything published to orders.>, with a seven-day retention policy.”

Consumer — a stateful view into a stream that tracks delivery progress for one or more subscribers, either pull-based (client requests messages) or push-based (server delivers messages). “We’re using a pull consumer for the batch processor so it controls its own pace, rather than a push consumer that could overwhelm it during a backlog.”

Acknowledgment (ack) policy — the setting controlling whether and how a consumer must confirm message processing (none, all, or explicit) before JetStream considers a message delivered. “With explicit ack, a crashed worker’s unacknowledged messages get redelivered automatically instead of silently disappearing.”

Retention policy — the stream-level configuration determining how long messages persist: limits (time/size/count based), interest (retained while consumers exist), or workqueue (removed once acknowledged by any consumer). “We switched the notifications stream to workqueue retention since each message only needs to be processed once, and we don’t need it lingering after that.”

Redelivery — the automatic re-sending of a message to a consumer that failed to acknowledge it within the configured AckWait window, a core reliability mechanism distinct from at-most-once delivery. “The duplicate order emails were caused by a slow handler exceeding AckWait and triggering redelivery — we extended the window instead of the handler racing to ack in time.”

Common Phrases

• “Is this a pull consumer or a push consumer, and does that match how the client is built to consume it?”
• “What’s the retention policy on this stream — limits, interest, or workqueue?”
• “Is this consumer using explicit ack, or could a crash silently drop messages?”
• “What’s the AckWait set to, and is that long enough for this handler’s typical processing time?”
• “Are we seeing redelivery because of a genuine failure, or because the ack window is too tight?”

Example Sentences

Proposing a stream design in an architecture review: “I’d configure the payments stream with limits-based retention at thirty days and explicit ack on the consumer, so we have a replay window if the downstream service needs reprocessing.”

Debugging a duplicate-processing incident: “Redelivery kicked in because the consumer’s AckWait was five seconds but the handler was taking eight under load — we’ve both extended the window and made the handler idempotent as a safety net.”

Explaining a consumer choice to a teammate: “We’re using a pull consumer here specifically because the worker needs to control its own batch size — a push consumer would just fire messages at whatever rate the stream produces them.”

Professional Tips

• Say stream and consumer precisely rather than “topic” and “subscriber” — those Kafka-flavored terms don’t map cleanly and cause confusion in a NATS-specific discussion.
• State the retention policy explicitly when proposing a new stream — it’s a design decision with real storage and correctness implications, not a default to leave unstated.
• Always mention the ack policy when describing a consumer’s reliability guarantees — “it processes messages” says nothing about what happens on a crash mid-processing.
• When reporting a duplicate-message bug, check and report the AckWait value alongside redelivery counts — a tight window disguised as “flaky processing” is a very common root cause.

Practice Exercise

1. Write a sentence describing a stream’s retention policy for a specific use case.
2. Explain the difference between a pull consumer and a push consumer.
3. Describe a redelivery scenario and how you’d prevent it from causing duplicate side effects.