stuntman / providers / event hubs

Event Hubs

An Azure Event Hubs namespace the official SDKs talk to over AMQP: partitions, consumer groups, owner levels, checkpoints and throttling on cue, with a Kafka endpoint too.

Stands in for

  • Azure Event Hubs (AMQP 1.0, emulator mode)
  • The Event Hubs Kafka endpoint ($ConnectionString)
  • Pub/Sub import topics from Event Hubs

Everything Event Hubs gives you

  1. 01

    Partitions like the service

    A partition key goes where the service sends it (lookup3 hash); no key, round-robin; a batch lands in one partition.

  2. 02

    Read from anywhere

    Receivers start at the beginning, @latest, after an offset or sequence number, or at an enqueued time.

  3. 03

    Consumer groups

    $Default plus the groups you create; at most 5 receivers per partition and group, as in Azure.

  4. 04

    Owner levels

    A receiver with a higher epoch takes the partition; the older one is disconnected with link stolen.

  5. 05

    Checkpoints you can see

    BlobCheckpointStore blobs in a Stuntman Storage account show next to each partition's reader.

  6. 06

    Management answers

    get_eventhub_properties and get_partition_properties: begin and last sequence number, last offset, empty.

  7. 07

    Retention on the clock

    Events older than the hub's retention go when you move the environment clock; begin sequence moves on.

  8. 08

    Kafka endpoint

    Kafka clients log in with $ConnectionString and read and write the same partitions as AMQP clients.

  9. 09

    Feeds Pub/Sub

    A Pub/Sub import topic naming the hub reads it: partition key as ordering key, properties as attributes.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

A hub: its partitions and every event with who sent it

A hub: its partitions and every event with who sent it: the Event Hubs screen in Stuntman
1Hubs

The namespace's event hubs with partitions, consumer groups and events kept.

1 of 5
2Two doors

AMQP on the Service Bus port, and Kafka through Streams' port.

2 of 5
3Partitions

Begin and last sequence number of each partition; click one to see only its events.

3 of 5
4Partition key

Sequence number, byte offset and the key that picked the partition.

4 of 5
5Who sent it

The app over AMQP or Kafka apart from you and the agent.

5 of 5
  1. Hubs

    The namespace's event hubs with partitions, consumer groups and events kept.

  2. Two doors

    AMQP on the Service Bus port, and Kafka through Streams' port.

  3. Partitions

    Begin and last sequence number of each partition; click one to see only its events.

  4. Partition key

    Sequence number, byte offset and the key that picked the partition.

  5. Who sent it

    The app over AMQP or Kafka apart from you and the agent.

Send, provoke, and the readers of each partition

Send, provoke, and the readers of each partition: the Event Hubs screen in Stuntman
1Send events

Body, properties, a partition key or a partition, as another producer would.

1 of 5
2Server busy

The next sends answer com.microsoft:server-busy; the SDKs send again.

2 of 5
3Steal owner

Readers lose their partition as if a higher epoch came.

3 of 5
4Owner level

Each receiver reading now, its epoch and the last sequence number sent.

4 of 5
5Checkpoint behind

The app's BlobCheckpointStore checkpoint, amber when it trails the reader.

5 of 5
  1. Send events

    Body, properties, a partition key or a partition, as another producer would.

  2. Server busy

    The next sends answer com.microsoft:server-busy; the SDKs send again.

  3. Steal owner

    Readers lose their partition as if a higher epoch came.

  4. Owner level

    Each receiver reading now, its epoch and the last sequence number sent.

  5. Checkpoint behind

    The app's BlobCheckpointStore checkpoint, amber when it trails the reader.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • Server busy

    The next N sends and management requests answer com.microsoft:server-busy

    set_eventhubs server_busy
  • Quota exceeded

    The next N sends are rejected with QuotaExceeded

    set_eventhubs quota_exceeded
  • Slow sends

    Each send waits before it is accepted

    set_eventhubs slow_sends
  • Entity not found

    A hub answers not found to links and management

    set_eventhubs not_found
  • Partition owner stolen

    Readers of a hub are disconnected with amqp:link:stolen

    set_eventhubs steal_owner
  • Higher epoch

    A second receiver with a higher owner level takes the partition

    a receiver with owner_level
  • Connection drop

    Every connection of the namespace closes; the SDKs reconnect

    set_eventhubs drop_connections
  • Wrong key

    With any_key off, tokens not signed by a policy key get 401

    set_eventhubs any_key false
  • Events expire

    Events older than the hub's retention go

    advance_clock

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Check that our order consumer survives a throttled Event Hubs and resumes from its checkpoint.

create_eventhub{"namespace": "acme-hubs-stg", "hub": "orders", "partitions": 4}
set_eventhubs{"namespace": "acme-hubs-stg", "server_busy": 2}
wait_for_eventhub_event{"namespace": "acme-hubs-stg", "hub": "orders", "where": {"kind": "OrderPaid"}}
→ ok partition 0 · sequence 412 · sent by the app after 2 retries
set_eventhubs{"namespace": "acme-hubs-stg", "steal_owner": "orders"}

MCP tools

  • list_eventhubsNamespaces, hubs, partitions, readers and checkpoints
  • create_eventhubA hub with partitions, consumer groups and retention
  • list_eventhub_eventsEvents with sequence number, offset and partition key
  • eventhub_sendSend as another producer
  • set_eventhubsServer busy, quota, slow sends, not found, steal owner, drop
  • wait_for_eventhub_eventWait for the app's event
  • advance_clockMove time: retention

The same over HTTP

  • GET/api/eventhubs
  • POST/api/eventhubs/{namespace}/hubs
  • GET/api/eventhubs/{namespace}/{hub}/events
  • POST/api/eventhubs/{namespace}/{hub}/events
  • PUT/api/eventhubs/{namespace}/settings
  • GET/api/eventhubs/{namespace}/{hub}/wait