Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

SQS — Simple Queue Service

Quick start, standard and FIFO coverage with visibility timeouts and redrive, why an SDK resolves the endpoint from the queue URL, and the permissions API that is missing.

Standard and FIFO queues with long polling, visibility timeouts and dead-letter redrive. Queue URLs are minted on whichever origin you called.

Status: ✅ Supported

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

Q=$(aws sqs create-queue --queue-name orders --query QueueUrl --output text)
aws sqs send-message --queue-url "$Q" --message-body '{"id":1}'
aws sqs receive-message --queue-url "$Q" --wait-time-seconds 5

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

What works

AreaBehaviour
QueuesIdempotent CreateQueue, FIFO queues via the .fifo suffix, inline tags, all standard attributes
SendingSendMessage and SendMessageBatch with DelaySeconds, message attributes and MD5OfMessageAttributes
BatchesAll three batch operations take 1-10 entries with distinct Ids; a batch breaking either limit is rejected whole
ReceivingMaxNumberOfMessages, per-call and queue-default long polling, per-call VisibilityTimeout, FIFO ReceiveRequestAttemptId
FIFO orderingA batch drains a message group in sequence order and fills from other groups; a group with in-flight messages returns nothing more until they are deleted or become visible
VisibilityChangeMessageVisibility and its batch form on in-flight messages
Dead-letter queuesRedrivePolicy, ListDeadLetterSourceQueues, and StartMessageMoveTask to redrive back to the source
MetricsAWS/SQS CloudWatch metrics, including depth gauges sampled every minute whether or not the queue has traffic

Queue URLs and endpoint resolution

AWS SDKs resolve the SQS endpoint from the QueueUrl, not from the endpoint you configured. The JS v3 client’s queueUrlMiddleware replaces the resolved endpoint with the queue URL’s origin whenever the two differ, and .NET and Java v1 use the queue URL as the request URI outright.

Important

AWS_ENDPOINT_URL does not protect against this. The middleware checks the client’s endpoint config field, and the environment variable never reaches it. Only an endpoint passed explicitly to the client suppresses the override:

new SQSClient({ endpoint: process.env.AWS_ENDPOINT_URL });
new SQSClient({ useQueueUrlAsEndpoint: false });

So a queue URL is only usable by a caller that can dial its origin. Overcast mints them per request, on the origin the caller reached it on: a host CLI hitting localhost:4566 gets localhost:4566 URLs, and a Lambda container calling in on Overcast’s container address gets that address. OVERCAST_HOSTNAME is the fallback for callers with no usable origin, not an override.

Queue URLs minted elsewhere are always accepted — only the queue name is read out of the URL. For a URL that crosses the boundary out of band, such as a CDK deploy baking queue.queueUrl into a function’s environment, see Lambda: reaching Overcast from function code.

Differences from AWS

AreaOn AWSOvercast
AddPermission / RemovePermissionManage a queue’s access policyNot implemented — 501 Not Implemented
redrivePermissionRestricts which queues may redrive from a DLQAccepted, validated and round-tripped, but not enforced
Message attribute typesBinary and Number values are validatedStored as given; the DataType is not checked
In-flight message quota~120,000 per standard queue and 20,000 per FIFO queue; a short poll past the cap gets OverLimitNot enforced — quotas are outside Overcast’s scope, so ReceiveMessage never returns OverLimit
Queue URL hostA fixed regional endpointThe origin of the request that minted it

Operations

19 of 21 listed operations are implemented. Per-operation status, notes and AWS API links: SQS operations.