stuntman / providers / storage

Storage

Azure Blob and Amazon S3 that keep every object, link and event, and fail exactly when you ask.

Stands in for

  • Azure Blob Storage
  • Amazon S3
  • Cloudflare R2
  • Event Grid
  • S3 event notifications

Everything Storage gives you

  1. 01

    Objects with their history

    Accounts, containers, block and multipart uploads. Each object shows versions, metadata and who wrote it: the app, you, the seed or an agent.

  2. 02

    Wait for the upload

    wait_for_object returns the first new object under a prefix, so a test acts in the app and then waits for the file instead of sleeping.

  3. 03

    Rules per operation

    When put, get, delete, list or link matches account, container and path glob: answer 503, 403, timeout or truncate. First N, every time or a share.

  4. 04

    Try a rule first

    test_rule replays the last requests and shows what each attempt would get, before anything is saved.

  5. 05

    Links you can break

    Every SAS or presigned URL is listed with what it allows, validity and uses. Make its next use expired, badly signed, IP-denied or gone.

  6. 06

    Events like the cloud

    BlobCreated and BlobDeleted in Event Grid or S3 format, to a webhook or a queue, with the Event Grid validation handshake first.

  7. 07

    Break event delivery

    Hold, duplicate, reorder, drop or strip a field from the next event, then resend it to check the app's handler is idempotent.

  8. 08

    Keys and reachability

    rotate_key makes apps that sign with the old key get 403. set_account_reachability makes the whole account time out, 503 or 401.

  9. 09

    Back to the seed

    reset_to_seed puts every account back to its seed folder and says what changed since it was loaded.

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.

Objects, the next read and the history

Objects, the next read and the history: the Storage screen in Stuntman
1Written by the app

Uploaded by acme-api over the real Blob API: size, type, reads and who wrote it.

1 of 5
2A read armed to fail

set_next_read makes the next read answer 403, 404, 503, slow, truncated or with a bad MD5.

2 of 5
3Added by you

put_object can store a truncated file on purpose; it is never shown as sent by the app.

3 of 5
4Next read, per object

Normal by default; pick a failure once, then it goes back to normal by itself.

4 of 5
5Versions

Every version is kept, with ETag and Content-MD5, so you can compare what the app overwrote.

5 of 5
  1. Written by the app

    Uploaded by acme-api over the real Blob API: size, type, reads and who wrote it.

  2. A read armed to fail

    set_next_read makes the next read answer 403, 404, 503, slow, truncated or with a bad MD5.

  3. Added by you

    put_object can store a truncated file on purpose; it is never shown as sent by the app.

  4. Next read, per object

    Normal by default; pick a failure once, then it goes back to normal by itself.

  5. Versions

    Every version is kept, with ETag and Content-MD5, so you can compare what the app overwrote.

A rule, tried before it is saved

A rule, tried before it is saved: the Storage screen in Stuntman
1Rules in order

The first rule that matches answers. Each shows its hits today and switches off with one click.

1 of 5
2Path glob

Operation, account, container and a glob: * is one level, ** any depth.

2 of 5
3The answer

503, 403, 404, 409, 412, 413, timeout, reset, empty, slow, truncate or bad_md5.

3 of 5
4How often

The first N attempts, every time, or a random share of the requests.

4 of 5
5What the app will see

Each attempt against the last 50 real requests: 503, 503, then 201.

5 of 5
  1. Rules in order

    The first rule that matches answers. Each shows its hits today and switches off with one click.

  2. Path glob

    Operation, account, container and a glob: * is one level, ** any depth.

  3. The answer

    503, 403, 404, 409, 412, 413, timeout, reset, empty, slow, truncate or bad_md5.

  4. How often

    The first N attempts, every time, or a random share of the requests.

  5. What the app will see

    Each attempt against the last 50 real requests: 503, 503, then 201.

Every SAS and presigned link

Every SAS and presigned link: the Storage screen in Stuntman
1By state

Valid, expired or revoked; filter by who issued the link and by kind (Azure SAS or S3 presigned).

1 of 5
2Refused uses

A late use of an expired link still shows up, with the answer the app's user got.

2 of 5
3Revoked

revoke_link: the next use answers 403 AuthenticationFailed, like Azure after a key rotation.

3 of 5
4Next use

set_next_use: expired, bad_signature, ip_denied, permission, not_yet_valid or gone.

4 of 5
5Uses

Each download with method, status and address, so you see who used the link and when.

5 of 5
  1. By state

    Valid, expired or revoked; filter by who issued the link and by kind (Azure SAS or S3 presigned).

  2. Refused uses

    A late use of an expired link still shows up, with the answer the app's user got.

  3. Revoked

    revoke_link: the next use answers 403 AuthenticationFailed, like Azure after a key rotation.

  4. Next use

    set_next_use: expired, bad_signature, ip_denied, permission, not_yet_valid or gone.

  5. Uses

    Each download with method, status and address, so you see who used the link and when.

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.

  • Uploads fail twice

    503 on the first 2 PUTs to contracts/**, then 201

    create_rule with how_often {"first": 2}
  • Reads fail at random

    A share of GETs answer 503 or time out

    create_rule with how_often {"random": 25}
  • One bad read

    The next read is 403, 404, 503, slow, truncated or bad MD5

    set_next_read
  • Link expired early

    The next use of a link answers as expired or badly signed

    set_next_use
  • Link revoked

    403 AuthenticationFailed; the app is not told

    revoke_link
  • Old key

    Apps signing with the previous key get 403

    rotate_key
  • Account down

    The whole account times out, answers 503 or 401

    set_account_reachability
  • Event duplicated

    The next BlobCreated arrives twice

    set_next_delivery duplicate
  • Events out of order

    Reorder, hold for 30 s or drop the next event

    set_next_delivery reorder | hold:30s | drop
  • Event missing a field

    The payload lacks a field the handler expects

    set_next_delivery missing_field

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

Make the contract upload fail twice with 503 and check that the app retries and the object ends up in storage.

create_rule{"service": "azure-blob", "name": "Contract uploads fail twice", "when": {"op": "put", "container": "documents", "path": "contracts/**"}, "then": {"respond": "503"}, "how_often": {"first": 2}}
→ ok rule saved, first in order
wait_for_object{"account": "acme-docs-stg", "container": "documents", "prefix": "contracts/", "timeout": "60s"}
→ ok contracts/2026/11/nda-acme.pdf · 248 KB · by acme-api · 3rd attempt 201
wait_for_storage_delivery{"type": "created", "path": "documents/contracts/2026/11/nda-acme.pdf"}

MCP tools

  • list_objectsObjects under a prefix, newest first, with who wrote them
  • get_objectProperties, versions and history of one object
  • wait_for_objectWait for the first new object under a prefix
  • set_next_readArm the next read: 403, 404, 503, slow, truncate, bad_md5
  • create_ruleFail matching requests: first N, every time or a share
  • test_ruleSee what a rule would do to recent traffic
  • list_linksSAS and presigned links with uses and refusals
  • set_next_useMake a link's next use expired, badly signed or gone
  • set_next_deliveryHold, duplicate, reorder or drop the next event
  • wait_for_storage_deliveryWait for an event delivery and the app's answer

The same over HTTP

  • GET/api/storage/{account}/{container}/objects
  • GET/api/storage/{account}/{container}/wait
  • PUT/api/storage/{account}/{container}/next-read/{*path}
  • POST/api/services/{name}/rules
  • PUT/api/storage/links/{id}/next-use
  • GET/api/storage/events/wait