Skip to content

SQS

Protocol: Query (XML) and JSON 1.0 (both supported) Endpoint: POST http://localhost:4566/

Supported Actions

Action Description
CreateQueue Create a standard or FIFO queue
DeleteQueue Delete a queue
ListQueues List all queues
GetQueueUrl Look up a queue URL by name
GetQueueAttributes Get queue configuration attributes
SendMessage Send a message to a queue
ReceiveMessage Poll for messages
DeleteMessage Acknowledge and delete a message
DeleteMessageBatch Delete multiple messages at once
SendMessageBatch Send up to 10 messages in one call
ChangeMessageVisibility Extend or reset a message's visibility timeout
ChangeMessageVisibilityBatch Change visibility for multiple messages
SetQueueAttributes Update queue configuration
TagQueue Add tags to a queue
UntagQueue Remove tags from a queue
ListQueueTags List tags on a queue
PurgeQueue Delete all messages in a queue
ListDeadLetterSourceQueues Find queues that use this queue as DLQ
StartMessageMoveTask Start a DLQ redrive task
ListMessageMoveTasks List DLQ redrive tasks
CancelMessageMoveTask -
AddPermission -
RemovePermission -

Local Inspection Endpoint

For test assertions and debugging, Floci exposes a LocalStack-compatible endpoint that lets you peek at queue contents without consuming messages:

Method Path Description
GET /_aws/sqs/messages?QueueUrl=<url> List all messages in the queue (non-destructive)
DELETE /_aws/sqs/messages?QueueUrl=<url> Purge all messages from the queue

GET returns every message currently in the queue — including in-flight messages — without changing visibility timeouts or advancing receive counts. It does not remove messages.

DELETE is equivalent to PurgeQueue and removes all messages.

Response shape

{
  "messages": [
    {
      "MessageId": "abc123",
      "MD5OfBody": "...",
      "Body": "{\"event\":\"order.placed\"}",
      "ReceiptHandle": null,
      "Attributes": {
        "SentTimestamp": "1714000000000",
        "ApproximateReceiveCount": "0"
      },
      "MessageAttributes": {}
    }
  ]
}

ReceiptHandle is null for messages that have not yet been received. FIFO messages include MessageGroupId, MessageDeduplicationId, and SequenceNumber in Attributes when set.

Example

QUEUE_URL="http://localhost:4566/000000000000/orders"

# Peek at messages without consuming them
curl "http://localhost:4566/_aws/sqs/messages?QueueUrl=$QUEUE_URL"

# Purge the queue
curl -X DELETE "http://localhost:4566/_aws/sqs/messages?QueueUrl=$QUEUE_URL"

Long Polling

ReceiveMessage waits up to WaitTimeSeconds (0 to 20) for a message to arrive and returns as soon as one is available. Values outside that range are rejected with InvalidParameterValue. When the request omits WaitTimeSeconds, the queue's ReceiveMessageWaitTimeSeconds attribute applies (default 0, short polling), matching AWS.

# Enable long polling for every consumer of the queue
aws sqs set-queue-attributes \
  --queue-url $QUEUE_URL \
  --attributes ReceiveMessageWaitTimeSeconds=20 \
  --endpoint-url $AWS_ENDPOINT_URL

Queue Attributes

GetQueueAttributes with --attribute-names All returns the set AWS returns for a standard queue: QueueArn, CreatedTimestamp, LastModifiedTimestamp, ApproximateNumberOfMessages, ApproximateNumberOfMessagesNotVisible, ApproximateNumberOfMessagesDelayed, VisibilityTimeout, MaximumMessageSize, MessageRetentionPeriod, DelaySeconds, ReceiveMessageWaitTimeSeconds and SqsManagedSseEnabled. Policy, RedrivePolicy and KmsMasterKeyId appear only once set, and FIFO queues also report FifoQueue and ContentBasedDeduplication.

MaximumMessageSize defaults to 1048576 bytes, the AWS default and maximum since August 2025, when AWS raised both from 262144. CreateQueue and SetQueueAttributes reject values outside 1024 to 1048576 with InvalidAttributeValue; raising FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE above the AWS maximum raises that accepted ceiling with it. Lowering the variable below 1048576 only changes the default a new queue receives: the accepted ceiling stays at the AWS maximum, so a queue can still be set to 1048576 explicitly.

SqsManagedSseEnabled is true for a queue with no KmsMasterKeyId, matching AWS, and false once a KMS key is set. It is derived on read rather than stored, so clearing KmsMasterKeyId returns the queue to true, unless you set SqsManagedSseEnabled yourself, in which case your value stands. AWS does not document the cleared-key case crisply, so that behaviour is Floci's choice rather than a copied one.

Configuration

Variable Default Description
FLOCI_SERVICES_SQS_ENABLED true Enable or disable the service
FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT 30 Default message visibility timeout (seconds)
FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE 1048576 Maximum message size in bytes (1 MiB)
FLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGE false When true, PurgeQueue also clears the FIFO deduplication cache for the queue and any SNS FIFO topics subscribed to it

Examples

export AWS_ENDPOINT_URL=http://localhost:4566

# Create a standard queue
aws sqs create-queue --queue-name orders --endpoint-url $AWS_ENDPOINT_URL

# Create a FIFO queue
aws sqs create-queue \
  --queue-name orders.fifo \
  --attributes FifoQueue=true \
  --endpoint-url $AWS_ENDPOINT_URL

# Send a message
QUEUE_URL="$AWS_ENDPOINT_URL/000000000000/orders"
aws sqs send-message \
  --queue-url $QUEUE_URL \
  --message-body '{"event":"order.placed","id":"abc123"}' \
  --endpoint-url $AWS_ENDPOINT_URL

# Receive messages
aws sqs receive-message \
  --queue-url $QUEUE_URL \
  --max-number-of-messages 10 \
  --endpoint-url $AWS_ENDPOINT_URL

# Delete a message (replace RECEIPT_HANDLE with the value from ReceiveMessage)
aws sqs delete-message \
  --queue-url $QUEUE_URL \
  --receipt-handle "RECEIPT_HANDLE" \
  --endpoint-url $AWS_ENDPOINT_URL

# Set up a dead-letter queue
DLQ_ARN=$(aws sqs get-queue-attributes \
  --queue-url $AWS_ENDPOINT_URL/000000000000/orders-dlq \
  --attribute-names QueueArn \
  --query Attributes.QueueArn \
  --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

aws sqs set-queue-attributes \
  --queue-url $QUEUE_URL \
  --attributes "{\"RedrivePolicy\":\"{\\\"deadLetterTargetArn\\\":\\\"$DLQ_ARN\\\",\\\"maxReceiveCount\\\":3}\"}" \
  --endpoint-url $AWS_ENDPOINT_URL

Queue URL Format

http://localhost:4566/000000000000/<queue-name>