stuntman / providers / kinesis

Kinesis

An Amazon Kinesis Data Streams endpoint the AWS SDKs talk to: shards by partition key, iterators, resharding, fan-out consumers and throttling on cue.

Stands in for

  • Amazon Kinesis Data Streams (Kinesis_20131202, JSON 1.1 and CBOR)
  • Enhanced fan-out (SubscribeToShard)
  • Pub/Sub import topics from Kinesis

Everything Kinesis gives you

  1. 01

    Streams and shards

    Provisioned or on-demand streams; shards split the 128-bit hash key space and the MD5 of the partition key picks one.

  2. 02

    Every iterator type

    TRIM_HORIZON, LATEST, AT and AFTER_SEQUENCE_NUMBER, AT_TIMESTAMP; GetRecords pages with MillisBehindLatest.

  3. 03

    Resharding with lineage

    SplitShard, MergeShards and UpdateShardCount close parents; readers reach their end and get the ChildShards.

  4. 04

    Enhanced fan-out

    Register consumers and read with SubscribeToShard: an event stream that pushes records as they arrive.

  5. 05

    Retention on the clock

    Records expire after the retention period and iterators after 5 minutes, both on the environment clock.

  6. 06

    Java's CBOR too

    AWS JSON 1.1 and the CBOR the Java SDK sends by default: byte-string data, millisecond timestamps.

  7. 07

    Put as another producer

    Put a record from the screen or a tool; the app's consumers read it like any other.

  8. 08

    Feeds Pub/Sub

    A Pub/Sub import topic naming the stream's ARN reads it from TRIM_HORIZON, partition key as ordering key.

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 stream: its hash key space, and every record with who put it

A stream: its hash key space, and every record with who put it: the Kinesis screen in Stuntman
1Streams

Provisioned and on-demand streams with their open shards and record counts.

1 of 5
2Endpoint

AWS_ENDPOINT_URL_KINESIS points the SDKs here; any key works.

2 of 5
3Hash key space

One bar split by open shard: the MD5 of the partition key lands in one of them.

3 of 5
4Closed shard

Records of a parent closed by a split stay readable until the retention ends.

4 of 5
5Who put it

The app's records apart from yours and the agent's.

5 of 5
  1. Streams

    Provisioned and on-demand streams with their open shards and record counts.

  2. Endpoint

    AWS_ENDPOINT_URL_KINESIS points the SDKs here; any key works.

  3. Hash key space

    One bar split by open shard: the MD5 of the partition key lands in one of them.

  4. Closed shard

    Records of a parent closed by a split stay readable until the retention ends.

  5. Who put it

    The app's records apart from yours and the agent's.

Put a record, provoke, and the shards after a split

Put a record, provoke, and the shards after a split: the Kinesis screen in Stuntman
1Put a record

Data, partition key or an explicit hash key, as another producer would.

1 of 5
2Throughput exceeded

The next puts answer ProvisionedThroughputExceededException; the SDKs retry.

2 of 5
3Reshard now

Splits the widest open shard; consumers must follow the children.

3 of 5
4Parent shard

Children of a split name their parent; the parent's sequence range is closed.

4 of 5
5Fan-out consumer

Registered consumers read with SubscribeToShard.

5 of 5
  1. Put a record

    Data, partition key or an explicit hash key, as another producer would.

  2. Throughput exceeded

    The next puts answer ProvisionedThroughputExceededException; the SDKs retry.

  3. Reshard now

    Splits the widest open shard; consumers must follow the children.

  4. Parent shard

    Children of a split name their parent; the parent's sequence range is closed.

  5. Fan-out consumer

    Registered consumers read with SubscribeToShard.

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.

  • Throughput on puts

    PutRecord and PutRecords answer ProvisionedThroughputExceededException

    set_kinesis {provoke: throughput_puts, times: 2}
  • Throughput on gets

    GetRecords answers ProvisionedThroughputExceededException

    set_kinesis {provoke: throughput_gets}
  • Stream not found

    Calls naming the stream answer ResourceNotFoundException

    set_kinesis {provoke: not_found, stream}
  • Expired iterator

    GetRecords answers ExpiredIteratorException

    set_kinesis {provoke: expired_iterator}
  • KMS throttling

    Puts and gets answer KMSThrottlingException

    set_kinesis {provoke: kms_throttling}
  • Slow puts

    Each put waits delay_ms (3 s by default)

    set_kinesis {provoke: slow_puts}
  • Partial PutRecords

    Every second record fails; FailedRecordCount > 0

    set_kinesis {provoke: partial_failures}
  • Resharding

    The widest open shard is split now

    set_kinesis {provoke: reshard, stream}
  • Iterator ages out

    An iterator older than 5 minutes expires for real

    advance_clock {by: 6m}
  • Records past retention

    Records older than the retention are gone

    advance_clock {by: 25h}

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 tracking producer retries when Kinesis throttles it twice.

set_kinesis{"provoke": "throughput_puts", "times": 2, "stream": "shipments"}
→ ok the next 2 puts on shipments answer ProvisionedThroughputExceededException
wait_for_kinesis_record{"stream": "shipments", "contains": "SHP-1043"}
→ ok put by the app on the 3rd try · shardId-000000000001 · partition key SHP-1043

MCP tools

  • list_kinesis_streamsStreams, shards with hash ranges and parents, consumers
  • list_kinesis_recordsThe newest records with shard, sequence and producer
  • kinesis_putPut a record as another producer would
  • create_kinesis_streamA provisioned or on-demand stream
  • wait_for_kinesis_recordWait for the app to put a matching record
  • set_kinesisThrottling, not found, expired iterator, KMS, slow, partial, reshard
  • advance_clockAge iterators and records past their retention

The same over HTTP

  • GET/api/kinesis/streams
  • GET/api/kinesis/streams/{stream}/records
  • POST/api/kinesis/streams/{stream}/records
  • PUT/api/kinesis/streams/{name}
  • GET/api/kinesis/streams/{stream}/wait
  • PUT/api/kinesis/config