SQS 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 Tarmac's design decisions make much more sense once you know them.

There Is No "Peek"

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

1. starts the visibility timeout — the message is hidden from all consumers until the timer lapses,
2. increments the message's receive count, which feeds the DLQ redrive threshold, and
3. issues a receipt handle — a temporary claim ticket required to delete the message.

This is why Tarmac receives into a local cache: pay the receive cost once, then do all your reading, searching, and filtering locally. It's also why Tarmac defaults to a 10-second visibility timeout — long enough to cache the message, short enough that your consumers get it back almost immediately.

Receipt Handles Are Perishable

DeleteMessage doesn't take a message ID — it takes a receipt handle from a specific receive. Handles stop working when the visibility window lapses and someone else receives the message (each new receive invalidates prior handles). There is no API to delete a message you don't currently hold.

Practical consequences in Tarmac:

• Deletes and redrives require a live receipt from the current session; cached messages from yesterday can be resent (that's just a new send) but not deleted until you re-fetch them.
• For destructive sessions, fetch with a visibility timeout that covers the whole session, and publish before it expires. Staged actions whose handles went stale are skipped with a reason, never silently forced.

At-Least-Once Delivery

Standard queues guarantee a message is delivered at least once — occasionally that means twice, even without anyone misbehaving. Consumers must be idempotent, and any tool that sends messages can create duplicates in edge cases. Tarmac participates honestly in this model:

• Re-received messages collapse onto one cached row (keyed by message ID), so the cache doesn't inflate.
• Redrive is send-then-delete; if the delete fails after the send, the message briefly exists in both queues and the action reports "delete failed after send." An idempotent consumer shrugs this off — the same guarantee it already lives with.
• A resend is a new message: new ID, fresh receive count, new timestamps. Your consumer sees a first delivery, not a retry.

Approximate Everything

Queue depth (ApproximateNumberOfMessages) and in-flight counts are eventually consistent — distributed counters that can lag reality by up to a minute. The depth shown in Tarmac's queue rail is a fetch-time 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 (Tarmac's fetch retries empty receives three times for the same reason).

Ordering, FIFO, and Deduplication

Standard queues make no ordering promises — the fetch order in Tarmac is arrival order of the receives, not send order (sort by sent date instead). FIFO queues add strict ordering per message group and a 5-minute deduplication window. Tarmac preserves MessageGroupId and MessageDeduplicationId on resend/redrive so groups stay intact — with the corollary that a resend inside the dedup window can be silently dropped as a duplicate. See Staged Actions.

Size Limits and Retention

Message bodies cap at 256 KB — larger payloads travel as S3 pointers (S3 Payloads). Messages also expire: the retention period (visible in Topology) silently deletes messages that outstay it, DLQs included. A DLQ with 14-day retention is a two-week window to act on failures — after that, the evidence deletes itself. Your local cache, however, keeps its copies: sometimes Tarmac's cache is the only surviving record of an expired message.

The Cost Model

Every SQS API call is billed per request, and receives are the bulk of any inspection tool's traffic. Tarmac's economics: a fetch of N messages costs about N/10 receive calls (10 per batch, the SQS max); live tail costs one receive every 3 seconds (~1,200/hour) while running; search, facets, and re-reading cached messages cost zero. For context, SQS pricing is per million requests — inspection traffic is cheap, just not free. Fetch once, filter locally.