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
- 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.
- 02
Every iterator type
TRIM_HORIZON, LATEST, AT and AFTER_SEQUENCE_NUMBER, AT_TIMESTAMP; GetRecords pages with MillisBehindLatest.
- 03
Resharding with lineage
SplitShard, MergeShards and UpdateShardCount close parents; readers reach their end and get the ChildShards.
- 04
Enhanced fan-out
Register consumers and read with SubscribeToShard: an event stream that pushes records as they arrive.
- 05
Retention on the clock
Records expire after the retention period and iterators after 5 minutes, both on the environment clock.
- 06
Java's CBOR too
AWS JSON 1.1 and the CBOR the Java SDK sends by default: byte-string data, millisecond timestamps.
- 07
Put as another producer
Put a record from the screen or a tool; the app's consumers read it like any other.
- 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

Provisioned and on-demand streams with their open shards and record counts.
AWS_ENDPOINT_URL_KINESIS points the SDKs here; any key works.
One bar split by open shard: the MD5 of the partition key lands in one of them.
Records of a parent closed by a split stay readable until the retention ends.
The app's records apart from yours and the agent's.
- Streams
Provisioned and on-demand streams with their open shards and record counts.
- Endpoint
AWS_ENDPOINT_URL_KINESIS points the SDKs here; any key works.
- Hash key space
One bar split by open shard: the MD5 of the partition key lands in one of them.
- Closed shard
Records of a parent closed by a split stay readable until the retention ends.
- Who put it
The app's records apart from yours and the agent's.
Put a record, provoke, and the shards after a split

Data, partition key or an explicit hash key, as another producer would.
The next puts answer ProvisionedThroughputExceededException; the SDKs retry.
Splits the widest open shard; consumers must follow the children.
Children of a split name their parent; the parent's sequence range is closed.
Registered consumers read with SubscribeToShard.
- Put a record
Data, partition key or an explicit hash key, as another producer would.
- Throughput exceeded
The next puts answer ProvisionedThroughputExceededException; the SDKs retry.
- Reshard now
Splits the widest open shard; consumers must follow the children.
- Parent shard
Children of a split name their parent; the parent's sequence range is closed.
- 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 putsPutRecord and PutRecords answer ProvisionedThroughputExceededException
set_kinesis {provoke: throughput_puts, times: 2}Throughput on getsGetRecords answers ProvisionedThroughputExceededException
set_kinesis {provoke: throughput_gets}Stream not foundCalls naming the stream answer ResourceNotFoundException
set_kinesis {provoke: not_found, stream}Expired iteratorGetRecords answers ExpiredIteratorException
set_kinesis {provoke: expired_iterator}KMS throttlingPuts and gets answer KMSThrottlingException
set_kinesis {provoke: kms_throttling}Slow putsEach put waits delay_ms (3 s by default)
set_kinesis {provoke: slow_puts}Partial PutRecordsEvery second record fails; FailedRecordCount > 0
set_kinesis {provoke: partial_failures}ReshardingThe widest open shard is split now
set_kinesis {provoke: reshard, stream}Iterator ages outAn iterator older than 5 minutes expires for real
advance_clock {by: 6m}Records past retentionRecords older than the retention are gone
advance_clock {by: 25h}
Why not the real sandbox
Throttling when you want it
Real streams throttle only under load; here the next N calls fail, so the retry and backoff paths get tested.
Resharding in a test
Split a shard mid-test and see whether the consumer finishes the parent and follows the children.
No shard-hour bill
Streams, shards and fan-out consumers cost nothing and vanish with the environment.
See every record
Shard, sequence number, partition key, data and who put it, without writing a consumer.
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.
Check that our tracking producer retries when Kinesis throttles it twice.
MCP tools
list_kinesis_streamsStreams, shards with hash ranges and parents, consumerslist_kinesis_recordsThe newest records with shard, sequence and producerkinesis_putPut a record as another producer wouldcreate_kinesis_streamA provisioned or on-demand streamwait_for_kinesis_recordWait for the app to put a matching recordset_kinesisThrottling, not found, expired iterator, KMS, slow, partial, reshardadvance_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
- One port (4567) serves every environment; the default one answers.
- Per-shard throughput limits are not enforced, only provoked.