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.

In Practice: Navigating Nuance in a Distributed Team

Understanding technical jargon is one thing; communicating effectively within a professional environment – particularly when collaborating with colleagues from diverse backgrounds – is entirely another. When working with systems like NATS JetStream, the vocabulary isn’t just about defining what something does; it’s about conveying its impact, potential issues, and desired outcomes in a way that resonates across different levels of technical understanding. Let’s consider some common scenarios where mastering nuanced English phrasing can make or break your interactions.

For instance, imagine you’re reviewing a pull request for a new consumer application. A developer might submit the PR description simply stating: “Added consumer to process messages from stream X.” While technically accurate, it lacks crucial context. A more effective approach would be something like, “This consumer now processes all messages published to stream_name related to order fulfillment. We’ve implemented a retry policy for transient errors – specifically, if a message fails to acknowledge after three attempts, it will be re-queued and processed by another instance of the consumer. Please ensure that this aligns with our current retention policies regarding data loss.” Notice how adding details about why the change was made, the error handling strategy, and referencing existing policies elevates the description from a simple notification to a clear explanation for review. Similarly, in Slack discussions, avoiding overly terse messages like “Consumer needs ack” is vital. Instead, try something like: “The consumer isn’t reliably acknowledging messages on stream_name. Let’s investigate potential issues with message processing or acknowledge settings.”

Another frequent challenge arises when discussing retention policies – a critical element of JetStream’s durability. Explaining the concept simply to someone unfamiliar with data persistence can be tricky. Phrases like “messages are kept until they’re explicitly acknowledged” or “we need to configure retention for this stream” are far more accessible than purely technical descriptions. It’s also important to consider the potential implications of different policies. Saying, “Let’s set a 24-hour retention policy on this stream,” is clear, but adding, “This will ensure we retain all order data for analysis purposes, even if some messages are temporarily unavailable due to network issues” provides valuable context and justifies the decision.

nats-jetstream consumer create --name my_consumer --stream my_stream --options { "retries": 3, "ack_timeout": "10s"}

This simple CLI command demonstrates how even technical details – like retry settings or acknowledgement timeouts – require careful phrasing when communicating them. Remember, the goal isn’t just to state what you’re doing with JetStream, but to clearly articulate its purpose and impact within the broader system architecture. Focusing on clear and precise English will significantly improve collaboration and reduce potential misunderstandings in a distributed team environment.