SQS

Lightweight, dependency-free fake of AWS SQS that speaks the real modern SQS JSON wire protocol (AWS JSON 1.0, query-compatible), so application code using @aws-sdk/client-sqs can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { SqsServer } from "./services/sqs/src/server.js";

const server = new SqsServer(4568);
await server.start();
// ... use it ...
await server.stop();

Connect with the real AWS SDK client:

import {
  SQSClient,
  CreateQueueCommand,
  SendMessageCommand,
  ReceiveMessageCommand,
  DeleteMessageCommand,
} from "@aws-sdk/client-sqs";

const sqs = new SQSClient({
  region: "us-east-1",
  endpoint: "http://127.0.0.1:4568",
  credentials: { accessKeyId: "parlel", secretAccessKey: "parlel" },
});

const { QueueUrl } = await sqs.send(new CreateQueueCommand({ QueueName: "jobs" }));

await sqs.send(new SendMessageCommand({ QueueUrl, MessageBody: "hello world" }));

const { Messages } = await sqs.send(
  new ReceiveMessageCommand({ QueueUrl, MaxNumberOfMessages: 1 }),
);
console.log(Messages[0].Body); // "hello world"

await sqs.send(
  new DeleteMessageCommand({ QueueUrl, ReceiptHandle: Messages[0].ReceiptHandle }),
);

Queue URLs

Created queues return a URL of the form http://127.0.0.1:4568/{accountId}/{queueName} (default account id 000000000000). The SDK's useQueueUrlAsEndpoint behavior uses the URL's origin as the request endpoint, so the host/port in the URL must match the running fake — which it does automatically. Bare queue names are also accepted wherever a QueueUrl is expected (the last path segment is used as the queue name).

Wire protocol

• Requests are POST / with header X-Amz-Target: AmazonSQS.<Operation> and Content-Type: application/x-amz-json-1.0. The body is the JSON-serialized input.
• Success responses are 200 with Content-Type: application/x-amz-json-1.0 and a JSON body containing the output shape.
• Errors are non-2xx with a JSON body { "__type": "<Code>", "message": "<msg>" } plus the query-compatible header x-amzn-query-error: <Code>;<Sender|Receiver>.

Authentication

SigV4 signatures are accepted but not verified (any credentials work). This matches LocalStack-style local development.

MD5 checksums

The real @aws-sdk/client-sqs validates MD5OfMessageBody, MD5OfBody, and MD5OfMessageAttributes locally after each call. This fake computes each of those exactly the way AWS does (including the canonical length-prefixed message-attribute digest), so the SDK's built-in validation passes.

Implemented Operations

All 23 operations exposed by @aws-sdk/client-sqs are implemented and tested.

Queue lifecycle

• CreateQueue — standard & FIFO queues, attribute defaults, idempotent re-create, tags.
• DeleteQueue
• GetQueueUrl
• ListQueues — prefix filter and MaxResults/NextToken pagination.

Queue attributes

• GetQueueAttributes — including computed QueueArn, ApproximateNumberOfMessages, ApproximateNumberOfMessagesNotVisible, ApproximateNumberOfMessagesDelayed, CreatedTimestamp, LastModifiedTimestamp.
• SetQueueAttributes
• PurgeQueue

Messaging

• SendMessage — delay, message attributes, system attributes, FIFO group/dedup.
• SendMessageBatch — up to 10 entries, partial success/failure.
• ReceiveMessage — MaxNumberOfMessages, VisibilityTimeout, system & message attribute selection, FIFO ordering, receive-count tracking.
• DeleteMessage
• DeleteMessageBatch
• ChangeMessageVisibility
• ChangeMessageVisibilityBatch

Tags

• TagQueue
• UntagQueue
• ListQueueTags

Permissions

• AddPermission
• RemovePermission

Dead-letter queues & message move tasks

• ListDeadLetterSourceQueues
• StartMessageMoveTask
• CancelMessageMoveTask
• ListMessageMoveTasks

Behavioral notes

• Visibility timeout: received messages are hidden for VisibilityTimeout seconds (default 30, or the queue's configured value). They become visible again automatically when the timeout elapses, or immediately when set to 0 via receive or ChangeMessageVisibility. Deleting a message before the timeout removes it permanently.
• FIFO queues (.fifo suffix, FifoQueue=true): require MessageGroupId; require either MessageDeduplicationId or ContentBasedDeduplication=true. Deduplication is enforced within a 5-minute window. Messages carry a monotonically increasing SequenceNumber and are received in FIFO order.
• Delay: per-message DelaySeconds or the queue's DelaySeconds attribute keeps a message invisible until the delay elapses.
• Message move tasks: StartMessageMoveTask drains the source (DLQ) into the destination queue (explicit DestinationArn, or the original source queue inferred from a matching RedrivePolicy). Completes synchronously in this fake.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes

Errors are returned as { "__type": "<Code>", "message": "..." } with the x-amzn-query-error: <Code>;<Fault> header. The SDK surfaces them as typed exceptions (the modeled name may differ from the wire code, e.g. the wire code AWS.SimpleQueueService.NonExistentQueue surfaces as QueueDoesNotExist).

Resetting state

State is in-memory and ephemeral. Reset it programmatically or over HTTP:

server.reset();                                   // in-process
await fetch("http://127.0.0.1:4568/_parlel/reset", { method: "POST" }); // over HTTP

Health check

GET http://127.0.0.1:4568/_parlel/health
→ { "status": "ok", "service": "sqs", "queues": <n> }

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

AWS_ACCESS_KEY_ID=parlel
AWS_SECRET_ACCESS_KEY=parlel
AWS_REGION=us-east-1
AWS_ENDPOINT_URL_SQS=http://parlel-bridge:4568
AWS_ENDPOINT_URL=http://parlel-bridge:4568