Event Hubs

Lightweight, dependency-free fake of Azure Event Hubs that speaks the documented Event Hubs REST API over plain HTTP, so application code and AI agents can publish and consume events across partitions and consumer groups with zero cost and zero side effects.

Wire-transport note. The real @azure/event-hubs 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 publish surface plus a small JSON control plane that mirrors the SDK's logical operations 1:1 (createBatch / sendBatch / send to partition / send by partition key / getEventHubProperties / getPartitionIds / getPartitionProperties / receiveBatch with earliest/latest/offset/sequenceNumber/enqueuedTime positions), plus the Atom-based management API for hubs and consumer groups. Agents and application code can therefore exercise every Event Hubs concept without a broker. See the Supported vs unsupported table below.

Quick Start

Start the server:

import { EventhubsServer } from "./services/eventhubs/src/server.js";

const server = new EventhubsServer(4595);
await server.start();
// ... use it ...
await server.stop();

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

Management (Atom/XML)

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

// Create an event hub with 4 partitions
await fetch(`${base}/telemetry`, {
  method: "PUT",
  headers: ATOM,
  body: `<entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml">
    <EventHubDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
      <PartitionCount>4</PartitionCount><MessageRetentionInDays>7</MessageRetentionInDays>
    </EventHubDescription></content></entry>`,
});

// Create a consumer group
await fetch(`${base}/telemetry/consumergroups/workers`, {
  method: "PUT",
  headers: ATOM,
  body: `<entry xmlns="http://www.w3.org/2005/Atom"><content type="application/xml">
    <ConsumerGroupDescription xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect"/>
  </content></entry>`,
});

Publish events (REST send)

// Send a single event (BrokerProperties carries PartitionKey + system metadata,
// custom headers map to application properties)
await fetch(`${base}/telemetry/messages`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    BrokerProperties: JSON.stringify({ PartitionKey: "device-7", MessageId: "m1" }),
    priority: '"high"',
  },
  body: JSON.stringify({ temp: 21.5 }),
});

// Send to a specific partition
await fetch(`${base}/telemetry/partitions/2/messages`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ temp: 22.0 }),
});

// Send a batch (lands together in one partition, like the real broker)
await fetch(`${base}/telemetry/messages`, {
  method: "POST",
  headers: { "Content-Type": "application/vnd.microsoft.servicebus.json" },
  body: JSON.stringify([
    { Body: { temp: 1 }, UserProperties: { unit: "C" } },
    { Body: { temp: 2 } },
  ]),
});

Consume events (receiveBatch)

// Read metadata
const meta = await (await fetch(`${base}/telemetry/properties`)).json();
// { name, createdOn, partitionIds: ["0","1","2","3"] }

const part = await (await fetch(`${base}/telemetry/partitions/0/properties`)).json();
// { partitionId, beginningSequenceNumber, lastEnqueuedSequenceNumber, lastEnqueuedOffset, isEmpty }

// Read events from a partition (earliest by default)
const r = await (await fetch(`${base}/telemetry/partitions/0/events?maxMessageCount=10`)).json();
for (const ev of r.events) console.log(ev.sequenceNumber, ev.body);

// Read from a position: earliest | latest | fromSequenceNumber | fromOffset | fromEnqueuedTime
await fetch(`${base}/telemetry/partitions/0/events?fromSequenceNumber=5&inclusive=true`);
await fetch(`${base}/telemetry/partitions/0/events?position=latest`);

// Read via a named consumer group
await fetch(`${base}/telemetry/consumergroups/workers/partitions/0/events`);

Using the real @azure/event-hubs client

The SDK's EventHubProducerClient / EventHubConsumerClient data plane speaks AMQP 1.0 and is therefore not wire-compatible with this HTTP fake. Use the REST publish/consume endpoints above (or raw HTTP) to drive the fake. The logical operations map 1:1:

The management surface is identical in shape to @azure/arm-eventhub / ServiceBusAdministrationClient-style Atom entities.

Implemented operations

Internal (parlel)

Management — Event Hubs

Management — Consumer groups

Every hub is created with the default $Default consumer group.

Metadata (JSON — mirrors the SDK)

Runtime — Publish

Runtime — Consume

Consume query parameters:

• maxMessageCount — cap on events returned (default 100).
• position=earliest|latest — start from the beginning or only future events.
• fromSequenceNumber=N — start after sequence N (add inclusive=true to include N).
• fromOffset=N — start after offset N (add inclusive=true to include N).
• fromEnqueuedTime=<ms-or-ISO> — start from the first event enqueued at/after the time.

Event semantics

• Partitions — each hub has N ordered partitions; events get a per-partition monotonic sequenceNumber (starting at 0) and offset.
• Partition routing — explicit partitionId (path/query), partitionKey (deterministic hash → stable partition affinity), or automatic least-loaded spread. partitionId and partitionKey are mutually exclusive on a send.
• Batches — a whole batch lands in a single partition (mirrors real Event Hubs).
• Watermarks — getPartitionProperties reports beginningSequenceNumber, lastEnqueuedSequenceNumber, lastEnqueuedOffset, lastEnqueuedOnUtc, isEmpty.
• EventData — messageId, correlationId, contentType (from BrokerProperties) and custom application properties (from headers) round-trip through consume; systemProperties carry x-opt-sequence-number, x-opt-offset, x-opt-enqueued-time, x-opt-partition-key.

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 Event Hub 'x' 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 with a BrokerProperties response header (PartitionId, SequenceNumber, Offset, EnqueuedTimeUtc).
• Metadata / consume → 200 with a JSON body.

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.

EVENTHUBS_NAMESPACE=parlel
EVENTHUBS_ENDPOINT=http://parlel-bridge:4595
EVENTHUBS_CONNECTION_STRING=Endpoint=sb://127.0.0.1:4595/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=parlellocaldevkey;UseDevelopmentEmulator=true
EVENTHUB_NAME=parlelhub