sqs-queue

aws.sqs.queue

Managed message queue; the catalog's only queue node. Config knobs: fifo (false), visibilityTimeoutSec (30), retentionDays (4), dlqEnabled (true). Use it for async work handoff — see long-running-tasks.md for the job pattern, scaling-writes.md for write buffering, multi-step-processes.md for workflow chains.

SQS semantics

• Delivery is at-least-once: duplicates WILL occur (redelivery after consumer crash, visibility expiry, network retry). Consumers must be idempotent — dedupe on a message/business ID, or make the operation naturally safe to repeat.
• visibilityTimeoutSec: after a receive, the message is hidden for this long; if not deleted in time it reappears and another consumer gets it. Set it above worst-case processing time (a 2-6x margin is sane). For jobs that occasionally run long, have the worker heartbeat with ChangeMessageVisibility to extend the timeout rather than setting a huge static value.
• dlqEnabled: true attaches a dead-letter queue: after maxReceiveCount failed receives (poison message), SQS moves it to the DLQ for inspection/replay instead of retrying forever. Keep it on; alarm on DLQ depth.
• retentionDays: how long an undelivered/unprocessed message survives before SQS deletes it (default 4, max 14). This is a safety buffer for consumer outages, not a replayable log — once a consumer deletes a message, it is gone.
• fifo: true: strict ordering within a messageGroupId, plus 5-minute content/ID-based deduplication on the producer side. Throughput is capped (~300 msgs/sec per API action, ~3,000/sec with batching) — orders of magnitude below standard SQS. Default to fifo: false unless ordering is a real requirement.
• Scaling consumers: queue depth (ApproximateNumberOfMessagesVisible) is the natural autoscaling signal. Producers and consumers scale independently — that decoupling is the point.

Edges

• Edge kind: iam from producer/consumer compute → queue (IAM role grants send/receive).
• For fan-out (multiple independent consumer groups), put an aws.sns.topic in front with one queue subscribed per consumer type.