Azure Queue Storage

Lightweight, dependency-free fake of Azure Queue Storage that speaks the real Azure Queue REST API (XML wire protocol + x-ms-* headers), so application code using @azure/storage-queue can run against it with zero cost and zero side effects.

Quick Start

Start the server:

import { AzurequeueServer } from "./services/azurequeue/src/server.js";

const server = new AzurequeueServer(4593);
await server.start();
// ... use it ...
await server.stop();

Connect with the real Azure SDK client. The fake uses path-style addressing (like Azurite), so the queue endpoint always includes the account name:

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

const account = "devstoreaccount1";
const key =
  "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==";

const credential = new StorageSharedKeyCredential(account, key);
const svc = new QueueServiceClient(
  `http://127.0.0.1:4593/${account}`,
  credential,
);

const queue = svc.getQueueClient("my-queue");
await queue.create();

// Send a message.
const sent = await queue.sendMessage("hello parlel");

// Receive (dequeue) it — becomes invisible for the visibility timeout.
const recv = await queue.receiveMessages();
const msg = recv.receivedMessageItems[0];
// msg.messageText -> "hello parlel"

// Delete it once processed.
await queue.deleteMessage(msg.messageId, msg.popReceipt);

You can also connect via a connection string:

const conn =
  "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;" +
  "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;" +
  "QueueEndpoint=http://127.0.0.1:4593/devstoreaccount1;";

const svc = QueueServiceClient.fromConnectionString(conn);

URL Shape

http://127.0.0.1:4593/<account>/<queue>?<comp>...                 # queue-level
http://127.0.0.1:4593/<account>/<queue>/messages?...              # messages-level
http://127.0.0.1:4593/<account>/<queue>/messages/<messageid>?...  # message-id-level
http://127.0.0.1:4593/<account>/?comp=...                         # service-level

Implemented Operations

Every wire operation the @azure/storage-queue client invokes is implemented.

Service-level (QueueServiceClient)

Queue-level (QueueClient)

Messages-level (QueueClient)

Message-id-level (QueueClient)

Internal (parlel) endpoints

Message Semantics

• FIFO ordering — visible messages are returned oldest-first.
• Visibility timeout — receiveMessages hides a message for the timeout (default 30s); it reappears (with an incremented DequeueCount and a fresh pop receipt) when the timeout elapses.
• Pop receipts — every dequeue/update issues a new pop receipt. updateMessage/deleteMessage reject stale receipts with PopReceiptMismatch (400).
• TTL — messages expire after messagettl seconds (default 7 days). messagettl=-1 means never expire. Expired messages are pruned lazily on access.
• Peek — does not change visibility or pop receipts and omits PopReceipt/TimeNextVisible/MessageText-mutating effects.

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 Azure-style XML with an x-ms-error-code response header. Validation errors include additional fields (QueryParameterName, QueryParameterValue, MinimumAllowed, MaximumAllowed, Reason) matching the real Azure Queue Storage error envelope:

<?xml version="1.0" encoding="utf-8"?>
<Error>
  <Code>OutOfRangeQueryParameterValue</Code>
  <Message>One of the query parameters specified in the request URI is outside the permissible range.</Message>
  <QueryParameterName>numofmessages</QueryParameterName>
  <QueryParameterValue>0</QueryParameterValue>
  <MinimumAllowed>1</MinimumAllowed>
  <MaximumAllowed>32</MaximumAllowed>
</Error>

Environment Variables

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.

AZURE_STORAGE_ACCOUNT=devstoreaccount1
AZURE_STORAGE_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;QueueEndpoint=http://127.0.0.1:4593/devstoreaccount1;