README
¶
chaotic examples
Runnable, tested scenarios. Each directory has a main.go (go run .), a
main_test.go (go test ./...), and a README.md. Per-symbol godoc examples
live next to each package (see the Example* functions on
pkg.go.dev).
| Scenario | Demonstrates | Adapter |
|---|---|---|
| retry-http | a retry loop recovers from a transient injected failure | adapter/http |
| circuit-breaker | a breaker opens after repeated injected failures | adapter/http |
| db-conn-pool | the pool evicts a poisoned conn (ConnDrop → ErrBadConn) |
adapter/sql |
| grpc-stream-reconnect | a stream client reconnects after an injected Unavailable |
adapter/grpc |
| pgx-pool | pool-level chaos on a pgx pool (integration-gated) | adapter/pgx |
| redis-cache-fallback | a read-through cache falls back to the DB when Redis fails | adapter/redis |
| kafka-write-retry | a producer retries through a transient Kafka write outage (needs Docker) | adapter/kafka |
| nats-request-retry | a request/reply caller retries through a transient NATS outage | adapter/nats |
| mongo-read-fallback | a read retries through a transient MongoDB step-down (needs Docker) | adapter/mongo |
| rabbitmq-publish-retry | a publisher retries through a transient RabbitMQ outage (needs Docker) | adapter/rabbitmq |
| aws-dynamodb-retry | the AWS SDK's own retryer recovers from an injected outage | adapter/aws |
| net-conn-drop | a read loop retries through a transient connection drop | adapter/net |
| slow-body-read | a Truncate fault cuts a response body mid-JSON; the reader surfaces a clean parse error |
adapter/io |
| response-mutate | a client degrades gracefully when chaos corrupts a successful 200 body | fault.ResponseMutate |
| chaos-point | an explicit chaos.Point guards a post-commit hook |
chaos |
| clock-skew | a token expires once fault.Clock skews engine.Now past its TTL |
fault.Clock |
| terms-dsl | a one-line terms string activates chaos with no rule-building code | source/terms |
| observability-during-chaos | an engine.Observer records a chaos fire for logs/metrics/traces |
engine |
| fanout-partial-failure | a fan-out degrades to a partial result when one branch is faulted | adapter/http |
| prod-safety-rails | failure budget + caps + guard + kill switch bound the blast radius | engine |
Examples that wrap a third-party adapter (adapter/grpc, pgx, redis,
kafka, nats, mongo, rabbitmq, aws) are each their own Go module, so
running them pulls in only that integration's dependencies.
Most examples run with no external services — in-process fakes (miniredis, an
embedded nats-server, net.Pipe) or an httptest server stand in. Four need a
live backend and skip when it is unavailable:
kafka-write-retry,mongo-read-fallback,rabbitmq-publish-retrystart a real broker via testcontainers-go, so Docker must be running.pgx-poolneeds a reachable Postgres.
Directories
¶
| Path | Synopsis |
|---|---|
|
Command chaos-point demonstrates an explicit injection point guarding a post-commit hook.
|
Command chaos-point demonstrates an explicit injection point guarding a post-commit hook. |
|
Command circuit-breaker shows a circuit breaker opening after chaos injects repeated failures, after which calls short-circuit instead of calling the failing dependency.
|
Command circuit-breaker shows a circuit breaker opening after chaos injects repeated failures, after which calls short-circuit instead of calling the failing dependency. |
|
Command clock-skew demonstrates fault.Clock.
|
Command clock-skew demonstrates fault.Clock. |
|
Command db-conn-pool shows database/sql discarding a poisoned connection and transparently retrying on a fresh one when chaos injects a connection drop.
|
Command db-conn-pool shows database/sql discarding a poisoned connection and transparently retrying on a fresh one when chaos injects a connection drop. |
|
Command fanout-partial-failure shows graceful degradation: a fan-out queries three backends concurrently, chaos faults exactly one branch (path /b), and the aggregator returns the partial result instead of failing the whole request.
|
Command fanout-partial-failure shows graceful degradation: a fan-out queries three backends concurrently, chaos faults exactly one branch (path /b), and the aggregator returns the partial result instead of failing the whole request. |
|
Command observability-during-chaos shows an engine.Observer capturing a chaos fire: when a rule injects a fault on an HTTP call, the observer records the RuleFired event — exactly where a real app forwards it to logs, metrics, or traces (see observer/slog, observer/prometheus, observer/otel).
|
Command observability-during-chaos shows an engine.Observer capturing a chaos fire: when a rule injects a fault on an HTTP call, the observer records the RuleFired event — exactly where a real app forwards it to logs, metrics, or traces (see observer/slog, observer/prometheus, observer/otel). |
|
Command prod-safety-rails shows the production bounds that keep chaos from becoming the outage: a failure budget, a max-concurrent cap, a production guard, and a kill switch.
|
Command prod-safety-rails shows the production bounds that keep chaos from becoming the outage: a failure budget, a max-concurrent cap, a production guard, and a kill switch. |
|
Command response-mutate demonstrates fault.ResponseMutate via adapter/http.MutateResponse: chaos corrupts the body of an otherwise successful 200 response, and the client's decode path degrades gracefully (returns "unknown") instead of crashing.
|
Command response-mutate demonstrates fault.ResponseMutate via adapter/http.MutateResponse: chaos corrupts the body of an otherwise successful 200 response, and the client's decode path degrades gracefully (returns "unknown") instead of crashing. |
|
Command retry-http demonstrates a retry loop recovering from a transient fault injected into an http.Client's transport.
|
Command retry-http demonstrates a retry loop recovering from a transient fault injected into an http.Client's transport. |
Click to show internal directories.
Click to hide internal directories.