Service Bus

Lightweight, dependency-free fake of Azure Service Bus that speaks the documented Service Bus REST API over plain HTTP, so application code can drive queues, topics, subscriptions, rules and brokered messages with zero cost and zero side effects.

Wire-transport note. The real @azure/service-bus SDK uses AMQP 1.0 for its data plane — a binary framing protocol that is intentionally out of scope for a tiny in-process fake. This fake instead implements Azure's documented HTTP/REST surface, which mirrors the same logical operations 1:1 (send / peek-lock receive / complete / abandon / renew-lock / dead-letter / defer / schedule, plus the full Atom-based management API). Agents and application code can therefore exercise every Service Bus concept without a broker. See the Supported vs unsupported table below.

Quick Start

Start the server:

import { ServicebusServer } from "./services/servicebus/src/server.js";

const server = new ServicebusServer(4592);
await server.start();
// ... use it ...
await server.stop();

Drive it over the Service Bus REST API with any HTTP client. The examples below use fetch.

Management (Atom/XML)

const base = "http://127.0.0.1:4592";
const ATOM = { "Content-Type": "application/atom+xml;type=entry;charset=utf-8" };

// Create a queue
await fetch(`${base}/orders`, {
  method: "PUT",
  headers: ATOM,
  body: `<entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml">
    <QueueDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
      <MaxDeliveryCount>10</MaxDeliveryCount><LockDuration>PT30S</LockDuration>
    </QueueDescription></content></entry>`,
});

// Create a topic + subscription
await fetch(`${base}/events`, { method: "PUT", headers: ATOM, body: `<entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml"><TopicDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect"/></content></entry>` });
await fetch(`${base}/events/subscriptions/worker`, { method: "PUT", headers: ATOM, body: `<entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml"><SubscriptionDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect"/></content></entry>` });

Send + receive (brokered messages)

// Send a message (BrokerProperties carries system metadata, custom headers map
// to application properties)
await fetch(`${base}/orders/messages`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    BrokerProperties: JSON.stringify({ MessageId: "m1", Label: "new-order", CorrelationId: "c1" }),
    priority: '"high"',
  },
  body: JSON.stringify({ id: 42 }),
});

// Peek-lock receive
const recv = await fetch(`${base}/orders/messages/head?timeout=30`, { method: "POST" });
const props = JSON.parse(recv.headers.get("brokerproperties"));
const body = await recv.text();

// Complete (delete) the locked message
await fetch(`${base}/orders/messages/${props.SequenceNumber}/${props.LockToken}`, { method: "DELETE" });

Using the real @azure/service-bus client

The SDK's ServiceBusAdministrationClient (management plane) issues exactly the Atom/XML HTTP requests this fake implements. Point it at the local endpoint:

import { ServiceBusAdministrationClient } from "@azure/service-bus";

const admin = new ServiceBusAdministrationClient(
  "Endpoint=sb://127.0.0.1:4592/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=parlellocaldevkey;UseDevelopmentEmulator=true"
);
await admin.createQueue("orders");
await admin.createTopic("events");
await admin.createSubscription("events", "worker");

The data-plane ServiceBusClient (sendMessages / receiveMessages) speaks AMQP and is therefore not wire-compatible with this HTTP fake — use the REST runtime endpoints above (or raw HTTP) to send/receive against the fake.

Implemented operations

Internal (parlel)

Management — Queues

Management — Topics

Management — Subscriptions

Management — Rules

Every subscription is created with the default $Default TrueFilter rule.

Runtime — Messaging

{entity} is one of:

• {queue} — a queue
• {queue}/$DeadLetterQueue — the queue's dead-letter sub-queue
• {topic}/subscriptions/{sub} — a subscription
• {topic}/subscriptions/{sub}/$DeadLetterQueue — the subscription's dead-letter sub-queue

Message semantics

• Scheduled messages — set BrokerProperties.ScheduledEnqueueTimeUtc; messages in the future are held until their time arrives.
• Topic fan-out — a message published to a topic is copied to every subscription whose rules match.
• Filtering — TrueFilter, FalseFilter, CorrelationFilter (CorrelationId / Label), and a useful subset of SqlFilter (prop = 'value', numeric comparisons > < >= <= != <>, and AND / OR).
• Dead-lettering — automatic when deliveryCount exceeds the entity's MaxDeliveryCount on abandon, or explicit via the deadletter disposition.
• Lock expiry — peek-locks last 30s; expired locks are reclaimed and the message returns to the queue.

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 / shapes

Errors are returned as Azure-style XML:

<Error><Code>404</Code><Detail>MessagingEntityNotFound: The messaging entity could not be found.</Detail></Error>

Successful responses use Azure's conventions:

• Create → 201 with the entity's Atom <entry>.
• Get → 200 with the Atom <entry>.
• Delete → 200 (empty).
• Send → 201.
• Peek-lock receive → 201 with the message body + a BrokerProperties response header containing LockToken, SequenceNumber, DeliveryCount, etc.
• Receive-and-delete → 200 with the message body.
• Empty receive → 204 (no message available).

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.

SERVICEBUS_NAMESPACE=parlel
SERVICEBUS_ENDPOINT=http://parlel-bridge:4592
SERVICEBUS_CONNECTION_STRING=Endpoint=sb://127.0.0.1:4592/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=parlellocaldevkey;UseDevelopmentEmulator=true