SQS

SQS is a custom Python reimplementation, not a thin wrapper. All 23 SQS operations are implemented in LocalEmu's own code: standard and FIFO queues, real visibility-timeout tracking, real long polling, dead-letter queues with redrive, message move tasks, CloudWatch metric emission, queue policies, server-side encryption metadata, tags, and persistence. Receiving a message blocks the request thread until a message arrives or the wait timer expires, just like real AWS.

Operation-level coverage: see the SQS coverage matrix.

Quick start

$ awsemu sqs create-queue --queue-name jobs
{
  "QueueUrl": "http://sqs.us-east-1.localhost:4566/000000000000/jobs"
}

$ awsemu sqs send-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs \
    --message-body '{"task":"resize","file":"img.png"}'

$ awsemu sqs receive-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs \
    --max-number-of-messages 1 \
    --wait-time-seconds 5
{
  "Messages": [{
    "MessageId":     "a1b2c3...",
    "ReceiptHandle": "AQEB...",
    "Body":          "{\"task\":\"resize\",\"file\":\"img.png\"}",
    "Attributes": {
      "ApproximateReceiveCount":          "1",
      "ApproximateFirstReceiveTimestamp": "1747700000000",
      "SentTimestamp":                    "1747699999500",
      "SenderId":                         "AKIAIOSFODNN7EXAMPLE"
    }
  }]
}

$ awsemu sqs delete-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs \
    --receipt-handle "AQEB..."

The queue URL returned by create-queue is the standard-format URL (sqs.us-east-1.localhost:4566/<account>/<queue>). Override the URL shape with SQS_ENDPOINT_STRATEGY if you need the domain, path, or dynamic format.

Architecture

SQS lives at services/sqs/. The provider class SqsProvider (provider.py:652) owns four background threads:

• •
  QueueUpdateWorker at provider.py:395-461: scans every in-flight message across all queues. When visibility_deadline elapses without a DeleteMessage or ChangeMessageVisibility, the message goes back on the queue. This worker also enforces MessageRetentionPeriod when SQS_ENABLE_MESSAGE_RETENTION_PERIOD=true.
• •
  Delayed-message scheduler at models.py:330: messages with DelaySeconds > 0 sit in a per-queue delayed set until their delay expires, then graduate to the visible queue.
• •
  CloudWatch metrics emitter at provider.py:224-361: every 60 seconds (configurable via SQS_CLOUDWATCH_METRICS_REPORT_INTERVAL), publishes seven metrics per queue to CloudWatch.
• •
  Message-move task executor at provider.py:1430-1502: drives StartMessageMoveTask when redriving from a DLQ back to the source.

Queue storage differs by type:

• •
  Standard queues use an InterruptiblePriorityQueue at models.py:801-814 with priority equal to the enqueue timestamp. Approximate FIFO ordering, no strict guarantee, matching real AWS standard semantics.
• •
  FIFO queues at models.py:1011-1032 hold one ordered queue per MessageGroupId. Strict ordering within a group; groups can be consumed in parallel by independent receivers.

When PERSISTENCE=1 is set, the SqsStore (queues + in-flight messages + delayed messages + dedup state) is serialised and restored across restarts via the standard StateVisitor hook (provider.py:684-685).

Configuration

Features supported

FIFO queues

FIFO queues add ordering guarantees and exactly-once delivery within a deduplication window:

• •
  Strict ordering within a MessageGroupId. Messages tagged with the same group ID are delivered in the order they were sent. Different group IDs are independent and can be processed in parallel.
• •
  Deduplication by explicit MessageDeduplicationId or by SHA-256 of the body when ContentBasedDeduplication=true. Re-sending the same dedup ID within 5 minutes is silently accepted by SQS but the duplicate is dropped.
• •
  Deduplication scope via DeduplicationScope: queue (default, one dedup window per queue) or messageGroup (one dedup window per MessageGroupId).
• •
  High-throughput FIFO: the FifoThroughputLimit=perMessageGroupId attribute is accepted and stored but the AWS per-group throughput cap is not enforced in LocalEmu.

$ awsemu sqs create-queue --queue-name orders.fifo \
    --attributes FifoQueue=true,ContentBasedDeduplication=true

# Three messages, same MessageGroupId => strict order preserved on receive
$ for i in 1 2 3; do
    awsemu sqs send-message \
        --queue-url http://sqs.us-east-1.localhost:4566/000000000000/orders.fifo \
        --message-group-id customer-42 \
        --message-body "{\"order\": $i}"
  done

$ for i in 1 2 3; do
    awsemu sqs receive-message \
        --queue-url http://sqs.us-east-1.localhost:4566/000000000000/orders.fifo \
        --query 'Messages[0].Body' --output text
  done
{"order": 1}
{"order": 2}
{"order": 3}

Dead-letter queues and redrive

A redrive policy is attached as a queue attribute. Once a message is received and not deleted before its visibility timeout expires more times than maxReceiveCount, the next would-be redelivery sends it to the dead-letter queue instead. The DLQ receives the original message body plus a DeadLetterQueueSourceArn system attribute pointing at the source queue.

# 1. Create the DLQ first; capture its ARN for the redrive policy
$ awsemu sqs create-queue --queue-name jobs-dlq
$ DLQ_ARN=$(awsemu sqs get-queue-attributes \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs-dlq \
    --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

# 2. Source queue with a redrive policy: 3 failed receives => DLQ
$ awsemu sqs create-queue --queue-name jobs \
    --attributes RedrivePolicy="{\"deadLetterTargetArn\":\"$DLQ_ARN\",\"maxReceiveCount\":\"3\"}"

$ Q=http://sqs.us-east-1.localhost:4566/000000000000/jobs
$ awsemu sqs send-message --queue-url $Q --message-body '{"work":"poisoned"}'

# Receive 3 times without deleting -- visibility timeout expires between each
# receive, so the next ReceiveMessage redelivers
$ for i in 1 2 3; do
    awsemu sqs receive-message --queue-url $Q --visibility-timeout 1 > /dev/null
    sleep 1.5
  done

# The 4th receive on the source queue returns nothing -- the message moved to the DLQ
$ awsemu sqs receive-message --queue-url $Q --query 'Messages' --output text
None

$ awsemu sqs receive-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/jobs-dlq \
    --query 'Messages[0].Attributes.DeadLetterQueueSourceArn' --output text
arn:aws:sqs:us-east-1:000000000000:jobs

StartMessageMoveTask walks every message currently in a DLQ and re-sends each one to the source queue named in its DeadLetterQueueSourceArn. Use it to replay messages after fixing the consumer.

CloudWatch metrics

The metrics worker publishes seven metrics per queue every 60 seconds (configurable). Disable with SQS_DISABLE_CLOUDWATCH_METRICS=true. All metrics use the AWS/SQS namespace with a QueueName dimension.

Integration points

SQS is a sink for five other LocalEmu services. All five paths are exercised end-to-end:

# Wire S3 ObjectCreated events to an SQS queue
$ awsemu sqs create-queue --queue-name uploads-events
$ QUEUE_ARN=$(awsemu sqs get-queue-attributes \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/uploads-events \
    --attribute-names QueueArn --query 'Attributes.QueueArn' --output text)

$ awsemu s3 mb s3://uploads
$ awsemu s3api put-bucket-notification-configuration --bucket uploads \
    --notification-configuration '{
      "QueueConfigurations": [{
        "QueueArn": "'"$QUEUE_ARN"'",
        "Events":   ["s3:ObjectCreated:*"]
      }]
    }'

$ echo "hello" | awsemu s3 cp - s3://uploads/hello.txt

$ awsemu sqs receive-message \
    --queue-url http://sqs.us-east-1.localhost:4566/000000000000/uploads-events \
    --query 'Messages[0].Body' --output text | python3 -m json.tool
{
  "Records": [{
    "eventSource": "aws:s3",
    "eventName":   "ObjectCreated:Put",
    "s3": {
      "bucket": {"name": "uploads"},
      "object": {"key": "hello.txt", "size": 6}
    }
  }]
}

Limits and defaults

LocalEmu's default MaximumMessageSize is 1 MiB, four times the 256 KiB AWS default. A queue created with no explicit MaximumMessageSize accepts messages up to 1 MiB. To match real AWS, pass --attributes MaximumMessageSize=262144 when calling CreateQueue. The other AWS-spec limits not listed above (max retention 14 days, max delay 15 min, max visibility 12 h, max in-flight 120 000 standard / 20 000 FIFO, max 10 message attributes per message) are not enforced by LocalEmu; the values are stored and reported as set but no upper bound is checked.

Known limitations

• •
  Default MaximumMessageSize is 1 MiB, not 256 KiB. See the previous section.
• •
  Queue policies are stored but not enforced. AddPermission / RemovePermission update the Policy attribute and the policy is returned by GetQueueAttributes, but cross-account requests are not actually denied based on the policy.
• •
  SqsManagedSseEnabled is metadata. Bodies are stored in cleartext at rest. SSE-SQS and SSE-KMS attributes are accepted, returned correctly, but no encryption is applied to the stored payload.
• •
  High-throughput FIFO not enforced. The FifoThroughputLimit attribute is accepted but the per-group rate cap is not applied.
• •
  DLQ chains are not supported. A DLQ cannot itself have a RedrivePolicy pointing at another DLQ. Real AWS supports up to 10 chained DLQs; LocalEmu rejects the second level.
• •
  Message move tasks do not survive a LocalEmu restart. An in-progress StartMessageMoveTask stops when the gateway stops; remaining DLQ messages stay in the DLQ until the task is restarted. Tracking: services/sqs/provider.py:473.
• •
  ListQueues pagination is partial. MaxResults is honoured but NextToken is not threaded through correctly. Tracking: services/sqs/provider.py:656-659.
• •
  Per-message KMS keys are not implemented. The queue-level KMS attribute is stored; per-message overrides have no effect.
• •
  AWS::SQS::QueueInlinePolicy CloudFormation resource is a stub. Use AWS::SQS::QueuePolicy instead.