AWS SQS Visibility and Delivery Essentials

You can use Tarmac productively without reading this page. But every "why did that happen?" moment with SQS traces back to a handful of core semantics, and these are the ones that come up.

There is no peek

SQS has no read-without-consequences API. The only way to see a message body is ReceiveMessage, and every receive does three things:

1. It starts the visibility timeout. The message is hidden from other consumers until the timer lapses.
2. It increments the message's receive count, which feeds the DLQ redrive threshold.
3. It issues a receipt handle, the temporary claim ticket you need in order to delete the message.

So pay the receive cost once and do your reading, searching, and filtering locally. Tarmac defaults to a 15-minute visibility timeout for that reason. Your consumers cannot see those messages while the timer runs, so size the window to your review.

Receipt handles are perishable

DeleteMessage does not take a message ID. It takes a receipt handle from a specific receive. Each receive issues a new handle, and after another receive you have to use the latest one, because an old handle can report success without deleting the message.

What that means in Tarmac:

• Deletes and staged sends that delete the original need a live receipt from the current session. A cached message from yesterday can be sent as a new message, but you cannot delete it until you fetch it again.
• For destructive sessions, fetch while the receipt has time to spare. Tarmac extends visibility before a destructive publish. If a handle is stale, the action fails with a reason rather than being forced through.

At-least-once delivery

Standard queues guarantee a message is delivered at least once. Occasionally that means twice, with nobody misbehaving. Consumers have to be idempotent, and any tool that sends messages can create duplicates in edge cases.

• Receiving a message again updates the copy in your cache instead of adding a second one, so the cache does not inflate.
• A staged send that deletes the original sends first and deletes second. If the delete fails after the send, the original stays and the action reports it. An idempotent consumer shrugs this off. It's the same guarantee it already lives with.
• A sent copy is a new message, with a new ID, a fresh receive count, and new timestamps. Your consumer sees a first delivery, not a retry.

Approximate everything

Queue depth (ApproximateNumberOfMessages) and in-flight counts are eventually consistent. These are distributed counters that can lag reality by up to a minute. The depth in Tarmac's queue list is the latest loaded snapshot of that approximate number. Don't expect it to decrement in lockstep with your deletes, and don't treat "0 visible" as proof of emptiness.

Ordering, FIFO, and deduplication

Standard queues make no ordering promises. The fetch order in Tarmac is the order the receives came back, not send order, so sort by sent date instead. FIFO queues add strict ordering per message group and a 5-minute deduplication window. Tarmac preserves MessageGroupId on staged sends, and retries of the same staged send count as the same operation. See Staged Actions.

Size limits and retention

Message bodies cap at 1 MiB. Larger payloads can use S3 pointers, covered in S3 Payloads. Messages also expire. The retention period, shown in Tarmac's Queue Settings, deletes messages that outstay it, DLQs included. A DLQ with 14-day retention is a two-week window to act on failures, and after that the evidence deletes itself. Your local cache keeps its copies, so sometimes it is the only surviving record of an expired message.

What costs money

Every SQS API action counts as a request, with payloads metered in 64 KB chunks. Search, filtering, and re-reading cached messages cost nothing against SQS. Fetch and Live Tail are SQS requests. On a Standard queue Live Tail receives about once every 3 seconds. On a FIFO queue it samples once per session so it cannot walk a group head into a DLQ, and on a Standard queue it stops before its own sampling could push a message past the queue's maxReceiveCount. SQS bills per million requests, so inspection traffic is cheap but not free. Fetch once, then filter locally.