stuntman / providers / pub/sub

Pub/Sub

A Google Cloud Pub/Sub emulator with schemas, snapshots, five subscription kinds, filters, transforms and exactly-once delivery.

Stands in for

  • Google Cloud Pub/Sub (google.pubsub.v1 gRPC)
  • Pub/Sub emulator
  • BigQuery, Cloud Storage and Bigtable subscriptions

Everything Pub/Sub gives you

  1. 01

    Publisher, Subscriber, Schema APIs

    Topics, subscriptions, Pull, StreamingPull, acks, snapshots, Seek and schema revisions over gRPC, with paging.

  2. 02

    Five subscription kinds

    Pull, push (wrapped or unwrapped, with an OIDC token), BigQuery, Cloud Storage and Bigtable; their rows and files are kept.

  3. 03

    Schemas that validate

    Avro and Protocol Buffers in JSON or binary; a publish no revision accepts gets INVALID_ARGUMENT.

  4. 04

    Filters and ordering

    Attribute filters with hasPrefix, NOT, AND, OR; ordering keys wait while one of their messages is out.

  5. 05

    Retries and dead letters

    Nack or a passed deadline redelivers with the retry backoff; past max attempts the message moves to the dead-letter topic.

  6. 06

    Exactly-once delivery

    Expired ack ids fail with EXACTLY_ONCE_ACKID_FAILURE; StreamingPull confirms acks, as ack_with_response reads.

  7. 07

    JavaScript and AI transforms

    UDFs run in QuickJS with Pub/Sub's signature; AI inference transforms are answered by the AI models simulator.

  8. 08

    Import topics

    Cloud Storage, MSK, Confluent and Kinesis sources read Stuntman storage, Kafka and Kinesis; any source takes pubsub_ingest.

  9. 09

    Snapshots and Seek

    Seek to a snapshot or a time replays what is retained, with retain-acked and topic retention honoured.

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 topic, and each subscription's view of its messages

A topic, and each subscription's view of its messages: the Pub/Sub screen in Stuntman
1Schema

Every publish is validated; subscribers get the googclient_schema* attributes.

1 of 5
2Ingestion

An import topic reading a Kafka topic as Amazon MSK, with its state.

2 of 5
3Transform

A JavaScript UDF runs on every message before the schema check.

3 of 5
4Ordering key

Messages with the same key are delivered in order, one out at a time.

4 of 5
5State per subscription

Pending, outstanding, acked, expired or dead after 5 attempts, per subscription.

5 of 5
  1. Schema

    Every publish is validated; subscribers get the googclient_schema* attributes.

  2. Ingestion

    An import topic reading a Kafka topic as Amazon MSK, with its state.

  3. Transform

    A JavaScript UDF runs on every message before the schema check.

  4. Ordering key

    Messages with the same key are delivered in order, one out at a time.

  5. State per subscription

    Pending, outstanding, acked, expired or dead after 5 attempts, per subscription.

Provoke on publish, and the subscriptions

Provoke on publish, and the subscriptions: the Pub/Sub screen in Stuntman
1Unavailable

Publish answers UNAVAILABLE; the client libraries retry it.

1 of 5
2Ack transient

Exactly-once acks fail with TRANSIENT_FAILURE_UNORDERED_ACK_ID until times runs out.

2 of 5
3Dead-letter topic

After 5 delivery attempts the message moves to shipments-dlq.

3 of 5
4Filter

Messages whose attributes do not match never reach this subscription.

4 of 5
5BigQuery, Storage, Bigtable

Subscriptions that write rows and files Stuntman keeps for you to read.

5 of 5
  1. Unavailable

    Publish answers UNAVAILABLE; the client libraries retry it.

  2. Ack transient

    Exactly-once acks fail with TRANSIENT_FAILURE_UNORDERED_ACK_ID until times runs out.

  3. Dead-letter topic

    After 5 delivery attempts the message moves to shipments-dlq.

  4. Filter

    Messages whose attributes do not match never reach this subscription.

  5. BigQuery, Storage, Bigtable

    Subscriptions that write rows and files Stuntman keeps for you to read.

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.

  • Unavailable

    Publish answers UNAVAILABLE; clients retry

    set_pubsub {provoke: unavailable, times: 2}
  • Deadline exceeded

    Publish answers DEADLINE_EXCEEDED

    set_pubsub {provoke: deadline_exceeded}
  • Resource exhausted

    Publish answers RESOURCE_EXHAUSTED

    set_pubsub {provoke: resource_exhausted}
  • Topic not found

    Publish answers NOT_FOUND, for one topic or all

    set_pubsub {provoke: not_found, topic}
  • Slow publish

    Each publish waits delay_ms (3 s by default)

    set_pubsub {provoke: slow_publish}
  • Duplicate delivery

    A message comes again after its first ack

    set_pubsub {provoke: duplicate}
  • Transient ack failure

    Exactly-once acks and modacks fail and are retried

    set_pubsub {provoke: ack_transient}
  • Push endpoint fails

    Non-2xx answers retry with backoff, then dead-letter

    create_pubsub_subscription {push_endpoint}
  • Row that does not fit

    BigQuery row refused, retried, then dead-lettered

    set_pubsub_bigquery_table
  • AI transform fails

    429 or 5xx from the model fails the publish

    force_ai_failure
  • Subscription expires

    An idle subscription past its ttl is deleted

    create_pubsub_subscription {expiration_ttl} + 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

Make sure our shipment publisher survives two UNAVAILABLE errors in a row.

set_pubsub{"provoke": "unavailable", "times": 2, "topic": "shipments"}
→ ok the next 2 publishes to shipments answer UNAVAILABLE
wait_for_pubsub_message{"topic": "shipments", "contains": "SHP-1043"}
→ ok published by the app on the 3rd try; billing pending, audit pending

MCP tools

  • list_pubsub_topicsTopics, subscriptions, counts per state, snapshots, schemas
  • list_pubsub_messagesMessages with their state in each subscription
  • pubsub_publishPublish as another service would
  • create_pubsub_subscriptionPull, push, BigQuery, Cloud Storage or Bigtable
  • set_pubsub_schemaCreate a schema or a revision; attach it to a topic
  • set_pubsub_topicIngestion source and JavaScript UDF of a topic
  • pubsub_ingestFeed records into an import topic
  • wait_for_pubsub_messageWait for the app to publish a matching message
  • list_pubsub_bigquery_rowsRows BigQuery subscriptions wrote
  • set_pubsubDefault project and a provocation on Publish

The same over HTTP

  • GET/api/pubsub/topics
  • GET/api/pubsub/messages
  • POST/api/pubsub/topics/{topic}/publish
  • PUT/api/pubsub/subscriptions/{subscription}
  • GET/api/pubsub/topics/{topic}/wait
  • PUT/api/pubsub/config