shadowbox 0.3.0__py3-none-any.whl

shadowbox/__init__.py

@@ -0,0 +1,3 @@
+"""ShadowBox: deterministic engine plus metrics, reports, and API (headless)."""
+
+__all__ = ["cards", "dsl", "engine", "errors", "metrics", "model", "report"]

shadowbox/api.py

@@ -0,0 +1,136 @@
+"""FastAPI surface over the headless core (M4a local server, M4b Worker later).
+
+Runs synchronously and returns the completed simulation (201) with a
+`status` field the Worker async path will reuse for queued/running states.
+Local-only: no authentication; bind to localhost unless you know why not.
+"""
+
+from dataclasses import asdict as _asdict
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ValidationError
+
+from shadowbox import engine as engine_mod
+from shadowbox.errors import ShadowBoxError
+from shadowbox.metrics import summarize
+from shadowbox.model import Scenario, SystemModel
+from shadowbox.report import build_report
+from shadowbox.store import Store
+
+MAX_EVENT_LIMIT = 1000
+
+app = FastAPI(title="ShadowBox", version="0.1.0")
+store = Store(Path("shadowbox.db"))
+
+
+class ScenarioIn(BaseModel):
+    scenario: dict[str, Any]
+    seed: int = 42
+
+
+def _as_422(code: str, message: str) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"code": code, "detail": message})
+
+
+@app.post("/api/v1/models", status_code=201)
+def create_model(body: dict[str, Any]) -> dict[str, str]:
+    try:
+        SystemModel.model_validate(body)
+    except ValidationError as exc:
+        return _as_422("E_SCHEMA", str(exc))  # type: ignore[return-value]
+    return {"id": store.save_model(body)}
+
+
+@app.get("/api/v1/models/{model_id}")
+def get_model(model_id: str) -> dict[str, Any]:
+    body = store.get_model(model_id)
+    if body is None:
+        raise HTTPException(status_code=404, detail="model not found")
+    return {"id": model_id, "model": body}
+
+
+@app.post("/api/v1/simulations", status_code=201)
+def create_simulation(model_id: str, payload: ScenarioIn) -> dict[str, Any]:
+    body = store.get_model(model_id)
+    if body is None:
+        raise HTTPException(status_code=404, detail="model not found")
+    try:
+        system = SystemModel.model_validate(body)
+        scenario = Scenario.model_validate(payload.scenario.get("scenario", payload.scenario))
+        result = engine_mod.simulate(system, scenario, payload.seed)
+        metrics = summarize(system, result, scenario.duration_s)
+        report = build_report(
+            system.model_dump(mode="json", by_alias=True),
+            scenario.model_dump(mode="json"),
+            payload.seed,
+            metrics,
+            result.events_processed,
+        )
+        sample = [_asdict(s) for s in result.sample]
+        report["sample"] = sample
+    except ShadowBoxError as exc:
+        return _as_422(exc.code, str(exc))  # type: ignore[return-value]
+    sim_id = store.save_simulation(model_id, payload.scenario, payload.seed, report)
+    return {"id": sim_id, "status": "completed", "metrics_hash": report["metrics_hash"]}
+
+
+@app.get("/api/v1/simulations/{sim_id}")
+def get_simulation(sim_id: str) -> dict[str, Any]:
+    found = store.get_simulation(sim_id)
+    if found is None:
+        raise HTTPException(status_code=404, detail="simulation not found")
+    report = found["report"]
+    assert isinstance(report, dict)
+    return {
+        "id": sim_id,
+        "status": found["status"],
+        "metrics_hash": report.get("metrics_hash"),
+        "metrics": report.get("metrics"),
+    }
+
+
+@app.get("/api/v1/simulations/{sim_id}/events")
+def get_events(sim_id: str, limit: int = 100, cursor: int = 0) -> dict[str, Any]:
+    found = store.get_simulation(sim_id)
+    if found is None:
+        raise HTTPException(status_code=404, detail="simulation not found")
+    if limit < 1 or limit > MAX_EVENT_LIMIT:
+        raise HTTPException(status_code=422, detail=f"limit must be 1..{MAX_EVENT_LIMIT}")
+    if cursor < 0:
+        raise HTTPException(status_code=422, detail="cursor must be >= 0")
+    report = found["report"]
+    assert isinstance(report, dict)
+    sample = report.get("sample", [])
+    assert isinstance(sample, list)
+    page = sample[cursor : cursor + limit]
+    nxt = cursor + len(page)
+    return {
+        "events": page,
+        "next_cursor": nxt if nxt < len(sample) else None,
+        "total_sampled": len(sample),
+    }
+
+
+@app.get("/api/v1/simulations/{sim_id}/metrics")
+def get_metrics(sim_id: str) -> dict[str, Any]:
+    found = store.get_simulation(sim_id)
+    if found is None:
+        raise HTTPException(status_code=404, detail="simulation not found")
+    report = found["report"]
+    assert isinstance(report, dict)
+    metrics = report.get("metrics")
+    assert isinstance(metrics, dict)
+    return metrics
+
+
+@app.get("/api/v1/simulations/{sim_id}/report")
+def get_report(sim_id: str) -> dict[str, Any]:
+    found = store.get_simulation(sim_id)
+    if found is None:
+        raise HTTPException(status_code=404, detail="simulation not found")
+    report = found["report"]
+    assert isinstance(report, dict)
+    return report

shadowbox/cards.py

@@ -0,0 +1,59 @@
+"""Bundled example and chaos cards, readable from an installed wheel (M6).
+
+Canonical files live under `src/shadowbox/data/`; `init` copies them to the
+user's directory so the tool works without a repo clone.
+"""
+
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from shadowbox.errors import ExistsError
+
+_DATA = resources.files("shadowbox.data")
+CARDS_DIR = _DATA / "cards"
+EXAMPLE_DIR = _DATA / "example"
+
+EXAMPLE_FILES = ("model.yaml", "docker-compose.yaml", "scenarios/db-failure.yaml")
+
+
+def list_cards() -> list[str]:
+    """Sorted chaos-card names shipped in the package."""
+    return sorted(p.name for p in CARDS_DIR.iterdir() if p.name.endswith(".yaml"))
+
+
+def read_card(name: str) -> str:
+    """Card YAML text; name with or without `.yaml` suffix."""
+    filename = name if name.endswith(".yaml") else f"{name}.yaml"
+    return (CARDS_DIR / filename).read_text(encoding="utf-8")
+
+
+def _copy_tree(source: Traversable, target: Path, written: list[str], force: bool) -> None:
+    for entry in sorted(source.iterdir(), key=lambda p: p.name):
+        dest = target / entry.name
+        if entry.is_dir():
+            dest.mkdir(parents=True, exist_ok=True)
+            _copy_tree(entry, dest, written, force)
+        elif entry.is_file():
+            if dest.exists() and not force:
+                raise ExistsError(f"{dest} exists (use --force to overwrite)")
+            dest.write_text(entry.read_text(encoding="utf-8"), encoding="utf-8")
+            written.append(str(dest))
+
+
+def write_tree(out: Path, force: bool = False, include_cards: bool = True) -> list[str]:
+    """Copy example (plus cards unless excluded) into `out`; returns written paths."""
+    written: list[str] = []
+    for filename in EXAMPLE_FILES:
+        dest = out / filename
+        if dest.exists() and not force:
+            raise ExistsError(f"{dest} exists (use --force to overwrite)")
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        text = (_DATA / "example" / filename).read_text(encoding="utf-8")
+        dest.write_text(text, encoding="utf-8")
+        written.append(str(dest))
+    if include_cards:
+        cards_out = out / "cards"
+        cards_out.mkdir(parents=True, exist_ok=True)
+        _copy_tree(CARDS_DIR, cards_out, written, force)
+    return written

shadowbox/cli.py

@@ -0,0 +1,222 @@
+"""Typer CLI: validate (M0) and simulate (M1); compare/report land in M3."""
+
+import json
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as pkg_version
+from pathlib import Path
+
+import typer
+import uvicorn
+import yaml
+from rich.console import Console
+
+from shadowbox import engine as engine_mod
+from shadowbox.cards import list_cards, write_tree
+from shadowbox.compare import (
+    DEFAULT_THRESHOLDS,
+    compare_reports,
+    parse_thresholds,
+    seed_warning,
+)
+from shadowbox.dsl import load_model, load_scenario
+from shadowbox.errors import SchemaError, ShadowBoxError
+from shadowbox.importers.compose import import_compose
+from shadowbox.metrics import summarize
+from shadowbox.report import build_report
+from shadowbox.store import Store
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+@app.command()
+def validate(
+    model: Path = typer.Argument(..., help="Path to model.yaml"),
+    scenario: Path = typer.Option(None, "--scenario", help="Path to scenario YAML"),
+) -> None:
+    """Validate a model and optionally a scenario (exit 0 ok, 3 invalid)."""
+    try:
+        system = load_model(model)
+        if scenario is not None:
+            load_scenario(scenario, system)
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    faults = f", {len(system.connections)} connections" if system.connections else ""
+    console.print(f"[green]valid[/green]: {len(system.components)} components{faults}")
+
+
+@app.command()
+def version() -> None:
+    """Print the package version (also keeps `validate` as a named subcommand)."""
+    try:
+        number = pkg_version("shadowbox")
+    except PackageNotFoundError:
+        number = "0.0.0+local"
+    console.print(f"shadowbox {number}")
+
+
+@app.command(name="import")
+def import_model(
+    from_path: Path = typer.Option(..., "--from", help="Path to docker-compose.yaml"),
+    out: Path = typer.Option(Path("model.yaml"), "--out", help="Imported model output path"),
+) -> None:
+    """Import a compose file into a validated model (all fields estimated)."""
+    try:
+        model, warnings = import_compose(from_path)
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    out.write_text(
+        yaml.safe_dump(model.model_dump(mode="json", by_alias=True), sort_keys=False),
+        encoding="utf-8",
+    )
+    for warning in warnings:
+        console.print(f"[yellow]warn[/yellow]: {warning}")
+    console.print(f"[green]imported[/green]: {len(model.components)} components -> {out}")
+
+
+@app.command()
+def simulate(
+    model: Path = typer.Argument(..., help="Path to model.yaml"),
+    scenario: Path = typer.Option(..., "--scenario", help="Path to scenario YAML"),
+    seed: int = typer.Option(42, "--seed", help="Deterministic RNG seed"),
+    out: Path = typer.Option(Path("report.json"), "--out", help="Report output path"),
+    format: str = typer.Option("json", "--format", help="json or text"),
+) -> None:
+    """Run a deterministic simulation and write the report envelope."""
+    try:
+        system = load_model(model)
+        ordered = load_scenario(scenario, system)
+        result = engine_mod.simulate(system, ordered, seed)
+        metrics = summarize(system, result, ordered.duration_s)
+        report = build_report(
+            system.model_dump(mode="json", by_alias=True),
+            ordered.model_dump(mode="json"),
+            seed,
+            metrics,
+            result.events_processed,
+        )
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    if format == "text":
+        out.write_text(_as_text(report), encoding="utf-8")
+    else:
+        out.write_text(json.dumps(report, indent=2, sort_keys=True), encoding="utf-8")
+    latency = metrics["latency_ms"]
+    assert isinstance(latency, dict)
+    error_rate = metrics["error_rate"]
+    assert isinstance(error_rate, float)
+    p99 = latency["p99"]
+    assert isinstance(p99, (int, float))
+    metrics_hash = report["metrics_hash"]
+    assert isinstance(metrics_hash, str)
+    console.print(
+        f"[green]done[/green]: {result.succeeded}/{result.total} ok, "
+        f"error_rate={error_rate:.3f}, p99={p99:.0f}ms, "
+        f"hash={metrics_hash[:12]} -> {out}"
+    )
+
+
+def _as_text(report: dict[str, object]) -> str:
+    metrics = report["metrics"]
+    assert isinstance(metrics, dict)
+    latency = metrics["latency_ms"]
+    assert isinstance(latency, dict)
+    lines = [
+        f"engine: {report['engine']}",
+        f"seed: {report['seed']}",
+        f"metrics_hash: {report['metrics_hash']}",
+        f"throughput_rps: {metrics['throughput_rps']}",
+        f"error_rate: {metrics['error_rate']}",
+        f"latency_ms p50/p95/p99: {latency['p50']}/{latency['p95']}/{latency['p99']}",
+        f"timeouts: {metrics['timeouts']}, cascade_depth: {metrics['cascade_depth']}",
+        f"confidence: {report['confidence']} ({report['calibration_source']})",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _read_report(path: Path) -> dict[str, object]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise SchemaError(f"cannot read report {path}: {exc}") from exc
+    if not isinstance(data, dict) or "metrics" not in data:
+        raise SchemaError(f"{path}: not a shadowbox report")
+    return data
+
+
+@app.command()
+def report(
+    report_path: Path = typer.Argument(..., help="Path to report.json"),
+    format: str = typer.Option("json", "--format", help="json or text"),
+) -> None:
+    """Render an existing report file (exit 0 ok, 3 invalid)."""
+    try:
+        found = _read_report(report_path)
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    if format == "text":
+        console.print(_as_text(found), end="")
+    else:
+        console.print_json(json.dumps(found, indent=2, sort_keys=True))
+
+
+@app.command()
+def compare(
+    a: Path = typer.Option(..., "--a", help="Baseline report.json"),
+    b: Path = typer.Option(..., "--b", help="Candidate report.json"),
+    threshold: str = typer.Option(DEFAULT_THRESHOLDS, "--threshold", help="p99:+10%,..."),
+) -> None:
+    """Compare two reports (exit 0 pass/improvement, 2 regression, 3 invalid)."""
+    try:
+        base = _read_report(a)
+        candidate = _read_report(b)
+        result = compare_reports(base, candidate, parse_thresholds(threshold))
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    warning = seed_warning(base, candidate)
+    if warning is not None:
+        console.print(f"[yellow]warn[/yellow]: {warning}")
+    for metric in sorted(result.deltas):
+        console.print(f"{metric}: {result.deltas[metric]:+.2f}")
+    if result.breaches:
+        console.print(f"[red]regression[/red]: breached {', '.join(sorted(result.breaches))}")
+        raise typer.Exit(code=2)
+    console.print(f"[green]{result.verdict}[/green]")
+
+
+@app.command()
+def serve(
+    host: str = typer.Option("127.0.0.1", "--host", help="Bind host"),
+    port: int = typer.Option(8000, "--port", help="Bind port"),
+    db: Path = typer.Option(Path("shadowbox.db"), "--db", help="SQLite file"),
+) -> None:
+    """Run the local API server (blocks; Ctrl-C to stop)."""
+    from shadowbox import api as api_mod
+
+    api_mod.store = Store(db)
+    uvicorn.run(api_mod.app, host=host, port=port)
+
+
+@app.command(name="init")
+def init_project(
+    out: Path = typer.Option(Path("."), "--out", help="Target directory"),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing files"),
+    cards: bool = typer.Option(True, "--cards/--no-cards", help="Include chaos cards"),
+) -> None:
+    """Scaffold example model plus chaos cards (works without a repo clone)."""
+    try:
+        written = write_tree(out, force, include_cards=cards)
+    except ShadowBoxError as exc:
+        console.print(f"[red]{exc.code}[/red]: {exc}")
+        raise typer.Exit(code=3) from exc
+    console.print(f"[green]initialized[/green]: {len(written)} files -> {out}")
+    console.print(f"cards available: {', '.join(n.replace('.yaml', '') for n in list_cards())}")
+
+
+if __name__ == "__main__":
+    app()

shadowbox/compare.py

@@ -0,0 +1,103 @@
+"""Scenario comparison: numeric deltas plus a threshold verdict (M3)."""
+
+import re
+from dataclasses import dataclass
+
+from shadowbox.errors import SchemaError
+
+_THRESHOLD_RE = re.compile(r"^(p50|p90|p95|p99|error_rate|throughput):([+-])(\d+(?:\.\d+)?)(%|pp)$")
+DEFAULT_THRESHOLDS = "p99:+10%,error_rate:+1pp,throughput:-10%"
+
+
+@dataclass(frozen=True)
+class Threshold:
+    metric: str
+    limit: float  # positive magnitude; unit implied by metric
+    percent: bool
+
+
+@dataclass
+class Comparison:
+    deltas: dict[str, float]
+    breaches: list[str]
+    verdict: str  # pass | regression | improvement
+
+
+def parse_thresholds(raw: str) -> list[Threshold]:
+    """Parse `p99:+10%,error_rate:+1pp,throughput:-10%` (pp only for error_rate)."""
+    parsed: list[Threshold] = []
+    for chunk in raw.split(","):
+        match = _THRESHOLD_RE.match(chunk.strip())
+        if match is None:
+            raise SchemaError(f"invalid threshold {chunk!r}; expected metric:±value%|pp")
+        metric, _, value, unit = match.groups()
+        if metric == "error_rate" and unit != "pp":
+            raise SchemaError("error_rate threshold must use pp units")
+        if metric != "error_rate" and unit != "%":
+            raise SchemaError(f"{metric} threshold must use % units")
+        parsed.append(Threshold(metric, float(value), unit == "%"))
+    if not parsed:
+        raise SchemaError("at least one threshold required")
+    return parsed
+
+
+def _latency(report: dict[str, object], key: str) -> float:
+    metrics = report["metrics"]
+    assert isinstance(metrics, dict)
+    latency = metrics["latency_ms"]
+    assert isinstance(latency, dict)
+    value = latency[key]
+    assert isinstance(value, (int, float))
+    return float(value)
+
+
+def _metric(report: dict[str, object], metric: str) -> float:
+    metrics = report["metrics"]
+    assert isinstance(metrics, dict)
+    if metric == "error_rate":
+        value = metrics["error_rate"]
+    elif metric == "throughput":
+        value = metrics["throughput_rps"]
+    else:
+        return _latency(report, metric)
+    assert isinstance(value, (int, float))
+    return float(value)
+
+
+def _pct_change(base: float, candidate: float) -> float:
+    if base == 0:
+        return 0.0 if candidate == 0 else float("inf")
+    return (candidate - base) / abs(base) * 100.0
+
+
+def compare_reports(
+    base: dict[str, object], candidate: dict[str, object], thresholds: list[Threshold]
+) -> Comparison:
+    """Diff candidate vs base; latency/error up is bad, throughput down is bad."""
+    deltas: dict[str, float] = {}
+    for threshold in thresholds:
+        a = _metric(base, threshold.metric)
+        b = _metric(candidate, threshold.metric)
+        deltas[threshold.metric] = (b - a) * 100.0 if not threshold.percent else _pct_change(a, b)
+    breaches = [
+        t.metric
+        for t in thresholds
+        if (deltas[t.metric] > t.limit if t.metric != "throughput" else deltas[t.metric] < -t.limit)
+    ]
+    if breaches:
+        verdict = "regression"
+    elif any(
+        (deltas[t.metric] < 0 if t.metric != "throughput" else deltas[t.metric] > 0)
+        for t in thresholds
+    ):
+        verdict = "improvement"
+    else:
+        verdict = "pass"
+    return Comparison(deltas, breaches, verdict)
+
+
+def seed_warning(base: dict[str, object], candidate: dict[str, object]) -> str | None:
+    """Warn when reports are not comparable (different seeds); confidence drops."""
+    if base.get("seed") != candidate.get("seed"):
+        return "seeds differ; treat verdict with low confidence (E_SEED_MISMATCH)"
+    return None

shadowbox/data/__init__.py

@@ -0,0 +1 @@
+"""Bundled data: example model plus chaos cards (ships inside the wheel)."""

shadowbox/data/cards/cache-poison.yaml

@@ -0,0 +1,7 @@
+# Card: cache poisoned (unavailable) 10s. Every request visits cache: expect ~1000 failed (10s x 100rps).
+scenario:
+  name: cache-poison
+  duration_s: 60
+  workload: { rate_rps: 100, arrival: deterministic }
+  faults:
+    - { target: cache, type: unavailable, start_s: 20, duration_s: 10 }

shadowbox/data/cards/db-down.yaml

@@ -0,0 +1,7 @@
+# Card: database down 10s in a 60s run. Expect ~1000 failed requests (10s x 100rps).
+scenario:
+  name: db-down
+  duration_s: 60
+  workload: { rate_rps: 100, arrival: deterministic }
+  faults:
+    - { target: database, type: unavailable, start_s: 20, duration_s: 10 }

shadowbox/data/cards/latency-500ms.yaml

@@ -0,0 +1,8 @@
+# Card: database +500ms for the whole run (505ms > 500ms db timeout).
+# Expect near-total timeouts; boundary requests past the window edge may still succeed.
+scenario:
+  name: latency-500ms
+  duration_s: 60
+  workload: { rate_rps: 100, arrival: deterministic }
+  faults:
+    - { target: database, type: latency, extra_ms: 500, start_s: 0, duration_s: 60 }

shadowbox/data/cards/queue-overflow.yaml

@@ -0,0 +1,6 @@
+# Card: queue overflow under 3000rps for 10s. Expect queue-full drops on api, error_rate > 0.
+scenario:
+  name: queue-overflow
+  duration_s: 10
+  workload: { rate_rps: 3000, arrival: deterministic }
+  faults: []

shadowbox/data/cards/slow-dependency.yaml

@@ -0,0 +1,8 @@
+# Card: slow cache dependency (+100ms, under the 200ms cache timeout).
+# Expect +~100ms latency delta vs baseline, no errors.
+scenario:
+  name: slow-dependency
+  duration_s: 60
+  workload: { rate_rps: 100, arrival: deterministic }
+  faults:
+    - { target: cache, type: latency, extra_ms: 100, start_s: 0, duration_s: 60 }

shadowbox/data/cards/traffic-10x.yaml

@@ -0,0 +1,6 @@
+# Card: Black Friday 10x (100 -> 1000rps). Checkout capacity holds: expect flat latency, no drops.
+scenario:
+  name: traffic-10x
+  duration_s: 60
+  workload: { rate_rps: 1000, arrival: deterministic }
+  faults: []

shadowbox/data/cards/zone-loss.yaml

@@ -0,0 +1,8 @@
+# Card: availability-zone loss takes cache+database down 20s. Expect near-total failure in window.
+scenario:
+  name: zone-loss
+  duration_s: 60
+  workload: { rate_rps: 100, arrival: deterministic }
+  faults:
+    - { target: cache, type: unavailable, start_s: 20, duration_s: 20 }
+    - { target: database, type: unavailable, start_s: 20, duration_s: 20 }

shadowbox/data/example/docker-compose.yaml

@@ -0,0 +1,13 @@
+# Checkout stack mirrored from examples/checkout/model.yaml (M2 import fixture).
+services:
+  api:
+    image: checkout/api:1.4
+    depends_on:
+      - cache
+      - database
+  cache:
+    image: redis:7
+    links:
+      - database
+  database:
+    image: postgres:16

shadowbox/data/example/model.yaml

@@ -0,0 +1,33 @@
+# Canonical M0 fixture: ecommerce checkout (api + cache + db).
+components:
+  - id: api
+    type: service
+    capacity: 50
+    latency_ms: { base: 20, jitter_ms: 5 }
+    timeout_ms: 1000
+    queue_size: 200
+    queue_policy: drop
+
+  - id: cache
+    type: cache
+    capacity: 100
+    latency_ms: { base: 2, jitter_ms: 1 }
+    timeout_ms: 200
+    queue_size: 500
+    queue_policy: drop
+
+  - id: database
+    type: database
+    capacity: 20
+    latency_ms: { base: 5, jitter_ms: 1 }
+    timeout_ms: 500
+    queue_size: 100
+    queue_policy: fifo
+
+connections:
+  - from: api
+    to: cache
+  - from: api
+    to: database
+  - from: cache
+    to: database

shadowbox/data/example/scenarios/db-failure.yaml

@@ -0,0 +1,12 @@
+# Chaos card: database down for 10s inside a 60s run at 100 rps.
+scenario:
+  name: database-failure
+  duration_s: 60
+  workload:
+    rate_rps: 100
+    arrival: deterministic
+  faults:
+    - target: database
+      type: unavailable
+      start_s: 20
+      duration_s: 10