How a message is settled¶
SQS has no acknowledgement. A received message is hidden for its visibility timeout, and it is gone only if someone deletes it. Everything the adapter does about settlement is a choice of what to do with that hidden message. The table of calls is in Settlement, visibility and redrive; this page is the reasoning.
The attempt is the receive¶
Delivery.Attempt is the message's ApproximateReceiveCount, which SQS increments on every receive.
It is 1 when the attribute is absent or below 1. So an attempt is spent when a message is received,
whether or not a handler ever sees it, and that is why two things line up:
MaxDelivermust equal the queue'smaxReceiveCount. The redrive policy is where the budget is enforced: SQS moves the message to the dead-letter queue on the receive after the last one. The adapter checks the two atSubscribeand refuses a queue that disagrees, or that has no redrive policy underAtLeastOnce, which would retry a message with no dead-letter destination until it is fourteen days old.Exhaustedis counted by the adapter, not by SQS. When a declined message is on its last attempt (Attempt >= MaxDeliver), the adapter counts it exhausted and releases it at once. The next receive is the one SQS refuses, and it dead-letters the message instead.
Ack, Nack and silence¶
| The handler | Under AtLeastOnce the adapter |
Under AtMostOnce |
|---|---|---|
| acks | deletes the message | nothing: it was deleted before hand-off |
| nacks, or is silent | hides it for the decline's delay, or releases it at once with no delay | nothing: it is gone |
A nack on the last attempt is released at once whatever its delay, so SQS dead-letters it on the next receive.
Under AtMostOnce the message is deleted before the handler runs. One attempt; a handler that
crashes has lost it. A message whose delete fails is not handed over at all, because it would come
back as a second attempt.
Delays¶
A Backoff or NackAfter delay is ChangeMessageVisibility on the message, rounded up to whole
seconds. A delay is a floor, so it rounds up. SQS will not hide a message past twelve hours from the
receive that took it, so a longer delay is cut to what is left, the message comes back sooner than
asked, and DelayShortened counts it. It is rare: a message that near the cap has been failing for
most of a day. See spec 0013.
A slow handler¶
Under ExtendLease, the default, with AtLeastOnce, the adapter heartbeats. Every third of AckWait
from the receive it extends the message's visibility by one AckWait, until the handler settles or
MaxProcessingTime is reached. A heartbeat that misses one tick is not the one that loses the lease,
which is why it is a third.
Each extension is cut so the message's total hidden time stays under twelve hours from the receive,
because the service refuses rather than clamps. At MaxProcessingTime, or when nothing is left, the
heartbeat stops, the visibility lapses and the message becomes somebody else's. LeaseExpired
counts that, because a duplicate is now possible. A heartbeat that fails for another reason is logged
and also ends the lease, without counting.
After the lease has ended, the original handler's late Ack or Nack is recorded and not sent.
Under Redeliver there is no heartbeat: the message returns at AckWait.
The lease length¶
Every receive asks SQS for a visibility of AckWait, rounded up to whole seconds, which is also the
lease. If AckWait is zero the adapter reads the queue's own VisibilityTimeout instead and uses
that, and refuses the subscription if it is not a positive number. A heartbeat cadence derived from
zero would be a busy loop.
Retirement¶
Retire stops receiving, then gives back every message the adapter received and nobody finished: the
buffered ones and the ones a handler still holds. They are released at once, in batches of ten, so the
next holder of the queue is owed them now and not when their visibility lapses. A settlement that
arrives after retirement is refused with messaging.ErrSettlementRefused. Session.Close retires all
its sources at once, and Publish after it returns sqs.ErrClosed.
The receive in flight at retirement is never cancelled: SQS completes it whether or not the client is listening, and on a FIFO queue a message received and never released would block its whole group for the visibility timeout. So the adapter checks for retirement between receives and gives back what the last one returned. Each receive is a one-second long poll, so retirement waits up to about a second.
When a receive fails¶
A throttle, a timeout or a server error is logged and retried after 200 milliseconds. A deleted queue
(QueueDoesNotExist), a malformed queue address (InvalidAddress) or AccessDenied cannot succeed
on a retry, so the source ends and records the cause. What the bus does next is the core's: it sees a source whose deliveries channel closed with a cause.