stuntman / providers / streams

Streams

A Kafka broker and a Confluent Schema Registry that decode every Avro message and break on cue.

Stands in for

  • Apache Kafka
  • Confluent Schema Registry
  • Avro

Everything Streams gives you

  1. 01

    The real Kafka protocol

    Produce, Fetch, ListOffsets, Metadata, CreateTopics and consumer groups with JoinGroup, SyncGroup, Heartbeat and offset commits.

  2. 02

    Avro, decoded

    Values in Confluent framing are decoded with their registry schema, so you read JSON, not bytes. JSON and text values too.

  3. 03

    A Schema Registry

    Confluent-compatible subjects and versions; register Avro, JSON or Protobuf schemas. The same schema keeps its id.

  4. 04

    Produce as the partner

    produce sends a key, value, headers and partition; with a subject the value is Avro-encoded with that schema.

  5. 05

    Consumer groups and lag

    Members, assigned partitions and the lag of each partition: committed offset against the high watermark.

  6. 06

    Force a rebalance

    rebalance makes members get REBALANCE_IN_PROGRESS on their next heartbeat, so they must join again.

  7. 07

    SASL logins

    PLAIN and SCRAM-SHA-256/512. With sasl_required and no users listed, any user works and any password except wrong.

  8. 08

    Broker-level failures

    Leader not available, SASL refused, slow fetch, duplicated records and a Schema Registry that answers 503.

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.

Topics and decoded messages

Topics and decoded messages: the Streams screen in Stuntman
1Topics

Each topic with its partitions and message count; made when a client asks, unless auto_create is off.

1 of 4
2How to connect

Kafka on localhost:9092 and the Schema Registry on :8081.

2 of 4
3Partition and offset

Where each record landed, to check keys go to the partition the app expects.

3 of 4
4Avro, readable

The value decoded with schema 3 from the registry, not raw bytes.

4 of 4
  1. Topics

    Each topic with its partitions and message count; made when a client asks, unless auto_create is off.

  2. How to connect

    Kafka on localhost:9092 and the Schema Registry on :8081.

  3. Partition and offset

    Where each record landed, to check keys go to the partition the app expects.

  4. Avro, readable

    The value decoded with schema 3 from the registry, not raw bytes.

Produce and provoke

Produce and provoke: the Streams screen in Stuntman
1Key

The record key, which picks the partition as a real producer would.

1 of 5
2Registry subject

With a subject, the value is Avro-encoded with that schema in Confluent framing.

2 of 5
3Produce

Sends the record as the partner would; the app's consumer reads it on its next fetch.

3 of 5
4Leader not available

Producers and consumers get LEADER_NOT_AVAILABLE until you set Normal.

4 of 5
5Registry down

The Schema Registry answers 503: does the app retry or drop the record?

5 of 5
  1. Key

    The record key, which picks the partition as a real producer would.

  2. Registry subject

    With a subject, the value is Avro-encoded with that schema in Confluent framing.

  3. Produce

    Sends the record as the partner would; the app's consumer reads it on its next fetch.

  4. Leader not available

    Producers and consumers get LEADER_NOT_AVAILABLE until you set Normal.

  5. Registry down

    The Schema Registry answers 503: does the app retry or drop the record?

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.

  • Leader not available

    Clients get LEADER_NOT_AVAILABLE

    set_streams provoke leader_not_available
  • SASL refused

    Logins are refused

    set_streams provoke sasl_refused
  • Slow fetch

    Each fetch takes 3 s

    set_streams provoke slow_fetch
  • Duplicated records

    Each record is kept twice: is the consumer idempotent?

    set_streams provoke duplicate
  • Registry down

    The Schema Registry answers 503

    set_streams provoke registry_down
  • Rebalance

    Members get REBALANCE_IN_PROGRESS and must rejoin

    rebalance
  • Unknown schema id

    A record the consumer cannot decode

    produce with bad_schema=true
  • No such topic

    Topics are not created on demand

    set_streams auto_create false

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

Send a shipment event twice and check the app's consumer does not create a duplicate.

register_schema{"subject": "shipments-value", "schema": "{\"type\": \"record\", \"name\": \"Shipment\", \"fields\": [{\"name\": \"id\", \"type\": \"string\"}]}"}
set_streams{"provoke": "duplicate"}
produce{"topic": "shipments", "key": "SH-1042", "value": {"id": "SH-1042"}, "subject": "shipments-value"}
list_consumer_groups{}
→ ok shipments-worker · lag 0 on 3 partitions · 2 records read

MCP tools

  • list_topicsTopics with partitions, messages, high watermarks
  • create_topicCreate a topic with N partitions
  • list_stream_messagesNewest messages, values decoded
  • produceProduce a record, Avro-encoded with a subject
  • list_consumer_groupsGroups, members, assignments and lag
  • rebalanceForce a consumer-group rebalance
  • set_streamsBroker settings, SASL and provocations
  • list_schemasRegistry subjects, versions and ids
  • register_schemaRegister a schema under a subject

The same over HTTP

  • GET/api/streams/topics
  • GET/api/streams/topics/{topic}/messages
  • POST/api/streams/topics/{topic}/produce
  • GET/api/streams/groups
  • PUT/api/streams/config
  • POST/api/streams/schemas