Skip to content

How JetStream settles and redelivers

This page is about the AtLeastOnce path of the JetStream backend. For what settlement means in the core, see Settle a delivery.

Attempts

Delivery.Attempt is the server's NumDelivered for the message, so it is a count the server keeps with the message and not a process's memory of it. It reads as 1 when the server's metadata cannot be read or reports zero.

What each answer sends

The core calls the backend's settlement once, after the handler returns. The backend sends:

Handler's answer Attempts left Sent to the server
Ack any Ack
Nack, or silence at least one Nak
Nack or NackAfter with a delay, or a Backoff delay at least one NakWithDelay(delay)
Nack, or silence none (the attempt equals MaxDeliver) Nak, and Exhausted counts one

On the last attempt a delay is not sent: the message is Naked plain, because the server will not offer it again whatever the delay. A message waiting out its delay holds one of the consumer's MaxAckPending slots. See Limits.

MaxDeliver

MaxDeliver is the consumer's MaxDeliver, and the server enforces it: after that many deliveries it stops offering the message. The adapter counts the last attempt's failure as Exhausted, in the places where it settles it: a decline on the last attempt, a message handed back at retirement on its last attempt, and a lease that reaches its bound on its last attempt.

MaxDeliver is fixed for a durable identity. See Subscribe durably.

The lease

AckWait is how long the server waits for a settlement before it offers the message again. Zero leaves the server's default, 30 seconds.

  • ExtendLease, the core's default, keeps the message while the handler works. The adapter calls InProgress every AckWait divided by three, until the handler settles or MaxProcessingTime passes. Because a message that has been prefetched is already on the AckWait clock and nothing could heartbeat it, the pull batch is one message under ExtendLease.
  • When MaxProcessingTime passes, the heartbeats stop and LeaseExpired counts one, and Exhausted too if that was the last attempt. AckWait then runs out and the server hands the message on while the handler may still be running. The handler's later settlement is dropped without being sent, and returns no error.
  • Redeliver sends no heartbeat. The server hands the message on when AckWait passes. The pull batch is the subscription's Bound. AckWait is then a correctness setting: shorter than your slowest handler, and duplicate work is routine.

Retirement

Retiring a source (the bus stopping, a session closing) stops the pull and drains it. A message the adapter took but never handed over, and a delivery in a handler's hand when the source retired, is Naked back so that the next holder of the name is owed it at once. A message whose attempt equals MaxDeliver is counted Exhausted here. A settlement arriving after the source has retired returns messaging.ErrSettlementRefused.

The adapter never deletes the consumer: it is a durable identity other processes may be using.

Whether Nak at retirement redelivers at once depends on the server staying up. A message returned this way is offered again at once by a live server, but a server restart forgets that and offers it again only when AckWait expires from its original delivery. See Limits.

When a source ends

If the pull iterator stops with the source not retired, the consumer has gone: the adapter logs messaging-nats: the consumer is gone at warn, records the cause as messaging-nats: the pull consumer ended, and closes the source's deliveries so the core sees it.

Source: settle, lease, returnDrained, giveBack and pull in jetsource.go; consumerConfig in jetsession.go.