Skip to content

Settlement, visibility and redrive

The reasoning is in How a message is settled. This is the lookup.

Receive

Each receive is ReceiveMessage with:

Parameter Value
MaxNumberOfMessages the free space in the bound, at most 10
WaitTimeSeconds 1
VisibilityTimeout the lease, below, in whole seconds
system attributes ApproximateReceiveCount
message attributes All

One receive is given 11 seconds in all. A source does not call again while its bound is full; it checks every 10 milliseconds. After a failed receive it waits 200 milliseconds.

Delivery.Attempt is ApproximateReceiveCount, or 1 if it is absent or below 1.

The lease

AckWait Lease
above zero AckWait rounded up to whole seconds
zero the queue's VisibilityTimeout; the subscription is refused if that is not a positive integer

Settling

Event Under AtLeastOnce Under AtMostOnce
Ack DeleteMessage none: deleted before hand-off
Nack or silence, with attempts left ChangeMessageVisibility to the delay rounded up to whole seconds, cut to what is left of twelve hours. Zero delay is zero seconds none
Nack or silence on the last attempt (Attempt >= MaxDeliver) counted Exhausted, then ChangeMessageVisibility to 0 none
a message that could not be read ChangeMessageVisibility to 0, counted Unreadable DeleteMessage, counted Unreadable
given back at retirement ChangeMessageVisibility to 0; in batches of ten (ChangeMessageVisibilityBatch) for what the source held nothing: already deleted
a settlement after retirement refused: messaging.ErrSettlementRefused refused

A settlement that fails because the receipt is no longer current (its visibility lapsed and the service handed the message on) is not an error. It is logged at INFO, as the message is now somebody else's.

Under AtMostOnce a message whose delete fails is not handed over and is not counted Accepted.

The twelve-hour cap

Fact Value
SQS's cap on a message's visibility 12 hours from the receive
MaxRedeliveryDelay declared 12 hours
a decline's hidden time ceil(delay to whole seconds), at most 12h - time since the receive, at least 0
a heartbeat's extension min(AckWait, 12h - time since the receive); none left ends the lease
FIFO with MaxHeadroom time since the receive is treated as zero, so the whole 12 hours is available per call. If SQS refuses a call as past the cap, the adapter retries at the figures above
MaxProcessingTime over 12 hours refused at Subscribe, unless FIFO with MaxHeadroom

The lease heartbeat

For AtLeastOnce with SlowHandler: ExtendLease and a MaxProcessingTime above zero, a heartbeat runs from the receive, every AckWait / 3:

  1. extends the message's visibility;
  2. stops when the handler settles, when MaxProcessingTime is reached, or when nothing is left of the cap. The last two end the lease and add to LeaseExpired; if that attempt was the last, to Exhausted too;
  3. stops, without counting, if an extension fails for another reason. It logs extending a lease failed; the message is somebody else's now.

What it counts

SourceStats, summed into ConsumerStats by the core:

Field Counted when
Accepted a message enters the source's queue after being read. Not an unreadable message, and not an at-most-once message whose delete failed
Pending held and not yet taken by the core
Exhausted an attempt was the last (Attempt >= MaxDeliver) and was declined, given back or had its lease expire
LeaseExpired a lease reached MaxProcessingTime or the cap while the handler held the message
DelayShortened a decline was hidden for less than it asked, because of the cap
Unreadable a message could not be read, once per receive
Refused, Evicted always zero

The message moves to the dead-letter queue when SQS next would receive it, after maxReceiveCount receives, not when Exhausted is counted.