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 callsInProgresseveryAckWaitdivided by three, until the handler settles orMaxProcessingTimepasses. Because a message that has been prefetched is already on theAckWaitclock and nothing could heartbeat it, the pull batch is one message underExtendLease.- When
MaxProcessingTimepasses, the heartbeats stop andLeaseExpiredcounts one, andExhaustedtoo if that was the last attempt.AckWaitthen 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. Redeliversends no heartbeat. The server hands the message on whenAckWaitpasses. The pull batch is the subscription'sBound.AckWaitis 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.