SQS queues and consumers

This guide covers the SQS surface end to end: queue lifecycle, send/receive/delete, visibility timeouts, the in-flight cap, receipt handles, long polling, batch operations, message attributes, FIFO queues, and DLQ/redrive. Every SQS queue is a native KubeMQ Queue channel sqs.{name} (see Channel mapping). The SQS surface ships 18 actions (see Capabilities).

Queue lifecycle

• CreateQueue — idempotent on an existing name with the same attributes; a FIFO queue uses the .fifo name suffix. Re-creating the same name with different attributes returns QueueNameExists.
• GetQueueUrl — returns the path-style URL {scheme}://{host}/{AccountId}/{name}.
• ListQueues — pagination plus QueueNamePrefix; results are not authorization-filtered.
• DeleteQueue — removes the registry record, best-effort broker purge, drops node-local in-flight.
• PurgeQueue — an AckAllQueueMessages; a 60 s cooldown applies (a second purge within the window returns PurgeQueueInProgress).
• GetQueueAttributes / SetQueueAttributes — see below.
• TagQueue / UntagQueue / ListQueueTags — ≤ 50 tags.
• ListDeadLetterSourceQueues — reverse-resolves queues whose RedrivePolicy names this queue.

Queue attributes

Writable (SetQueueAttributes is a partial-update overlay; it is not retroactive to messages already in the queue):

An unknown attribute name, or a KMS/SSE attribute (KmsMasterKeyId, Policy, …), on a Set returns InvalidAttributeName.

Read-only on Get: QueueArn, ApproximateNumberOfMessages (broker stats, 2 s TTL), ApproximateNumberOfMessagesNotVisible (node-local in-flight), ApproximateNumberOfMessagesDelayed (always "0"), CreatedTimestamp, LastModifiedTimestamp; FIFO adds FifoQueue / ContentBasedDeduplication / DeduplicationScope.

Send / receive / delete

The round-trip is three actions:

1. SendMessage — returns MessageId, MD5OfBody, and (if attributes are present) MD5OfMessageAttributes.
2. ReceiveMessage — returns the message body plus a receipt handle.
3. DeleteMessage(receiptHandle) — acks the message off the queue (AckRange). It is idempotent: an unknown receipt handle returns success.

Visibility timeout

A received message is hidden for a visibility window before it becomes receivable again. Precedence: per-request VisibilityTimeout (0–43200) > the queue default > 30 s. ChangeMessageVisibility(timeout>0) moves the deadline; ChangeMessageVisibility(0) NAcks the message so it becomes visible again at the tail. A 250 ms sweeper NAcks expired in-flight entries back to the tail, and ApproximateReceiveCount increments on re-receive.

Receipt handles are node-local

A receipt handle is an opaque base64url(json) token carrying {version, node, txnId, queue, seq, receivedMs, salt}. Decoding validates version==1 and the node match.

In-flight cap

Received-but-not-deleted messages count against a per-queue / per-node cap, MaxInflightPerQueue (default 20,000). Exceeding it returns OverLimit.

Long polling

• WaitTimeSeconds is 0–20; MaxNumberOfMessages is 1–10.
• A parked long-poll slot pool (MaxConcurrentPolls, default 1024); when it is exhausted a request degrades to a short poll (it does not error).
• Wire waits are chunked into ≤ 2 s sub-Gets for shutdown responsiveness.

Batch operations

SendMessageBatch / DeleteMessageBatch / ChangeMessageVisibilityBatch take ≤ 10 entries. SendMessageBatch returns per-entry Successful[] / Failed[]:

• a single oversize entry → that entry is Failed with InvalidParameterValue (SenderFault), the rest Successful;
• an aggregate body+attributes over 262,144 bytes → the whole batch is rejected with BatchRequestTooLong.

Message attributes

• Up to 10 message attributes; the name is ≤ 256 chars with no AWS. / Amazon. prefix; the DataType is String / Number / Binary (plus custom subtypes like String.x). They round-trip losslessly through the tag codec sqs_attr_{Name} = {DataType}|{value} (Binary is base64).
• Message system attributes: only AWSTraceHeader (DataType String) is accepted; anything else returns InvalidParameterValue. It is stored as sqs_trace_header.

See Channel mapping for the full mapping and the MD5 algorithms.

FIFO queues

A .fifo suffix makes a queue FIFO (FifoQueue is immutable post-create):

• MessageGroupId is required on a FIFO send (1–128 printable ASCII characters) — omitting it returns InvalidParameterValue;
• per-message DelaySeconds is rejected → InvalidParameterValue;
• ReceiveRequestAttemptId is accepted and ignored;
• each group maps to its own channel sqs.{name}.fifo.g.{enc(group)};
• deduplication uses an explicit MessageDeduplicationId, or the SHA-256 of the body when ContentBasedDeduplication is on; a duplicate within the 5-minute LRU window returns the original MessageId / SequenceNumber without re-publishing;
• per-group ordering allows at most one un-acked downstream Get per group; ReceiveMessage drains groups round-robin, ≤ 10 total.

Full FIFO reliability detail is in Reliability.

DLQ / redrive

Set a queue RedrivePolicy of {deadLetterTargetArn, maxReceiveCount}. The connector stamps each message with MaxReceiveCount / MaxReceiveQueue=sqs.{dlq} at send; the message broker moves the message to the DLQ when the receive count exceeds maxReceiveCount, surfacing DeadLetterQueueSourceArn on the redriven message. ListDeadLetterSourceQueues reverse-resolves. See Reliability.

At-least-once and graceful shutdown

Unacked deliveries are NAcked back to the queue tail by the 250 ms sweeper or on graceful shutdown (≤ 10 s); the registry survives restart (a shared StorePath). Exactly-once is not provided — design consumers to be idempotent.

Error quick reference

Related