Skip to content

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:

  • MaxDeliver must equal the queue's maxReceiveCount. 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 at Subscribe and refuses a queue that disagrees, or that has no redrive policy under AtLeastOnce, which would retry a message with no dead-letter destination until it is fourteen days old.
  • Exhausted is 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.