shadowbox 0.3.0__py3-none-any.whl

shadowbox/dsl.py

@@ -0,0 +1,94 @@
+"""Safe YAML loading + structural validation for M0 (no engine)."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from shadowbox.errors import (
+    CycleError,
+    RefError,
+    SchemaError,
+    TooLargeError,
+    UnsafeYamlError,
+)
+from shadowbox.model import MAX_COMPONENTS, Scenario, SystemModel
+
+_UNSAFE_TAGS = ("!!python/", "!python/")
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SchemaError(f"cannot read {path}: {exc}") from exc
+
+
+def _safe_load_yaml(path: Path) -> Any:
+    raw = _read_text(path)
+    for tag in _UNSAFE_TAGS:
+        if tag in raw:
+            raise UnsafeYamlError(f"{path}: unsafe YAML tag {tag!r} rejected")
+    try:
+        return yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise SchemaError(f"{path}: invalid YAML: {exc}") from exc
+
+
+def _check_cycles(model: SystemModel) -> None:
+    adjacency: dict[str, list[str]] = {c.id: [] for c in model.components}
+    for conn in model.connections:
+        adjacency[conn.from_].append(conn.to)
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def visit(node: str, stack: list[str]) -> None:
+        if node in visiting:
+            raise CycleError(f"cycle detected: {' -> '.join([*stack, node])}")
+        if node in visited:
+            return
+        visiting.add(node)
+        for nxt in sorted(adjacency[node]):
+            visit(nxt, [*stack, node])
+        visiting.remove(node)
+        visited.add(node)
+
+    for node in sorted(adjacency):
+        visit(node, [])
+
+
+def load_model(path: Path) -> SystemModel:
+    data = _safe_load_yaml(path)
+    if not isinstance(data, dict):
+        raise SchemaError(f"{path}: top-level mapping required")
+    try:
+        model = SystemModel.model_validate(data)
+    except ValidationError as exc:
+        raise SchemaError(f"{path}: {exc}") from exc
+    if len(model.components) > MAX_COMPONENTS:
+        raise TooLargeError(f"{path}: {len(model.components)} components > {MAX_COMPONENTS}")
+    known = {c.id for c in model.components}
+    for conn in model.connections:
+        if conn.from_ not in known or conn.to not in known:
+            raise RefError(f"{path}: unknown connection endpoint {conn.from_!r} -> {conn.to!r}")
+    _check_cycles(model)
+    return model
+
+
+def load_scenario(path: Path, model: SystemModel) -> Scenario:
+    data = _safe_load_yaml(path)
+    if not isinstance(data, dict):
+        raise SchemaError(f"{path}: top-level mapping required")
+    payload = data.get("scenario", data)
+    try:
+        scenario = Scenario.model_validate(payload)
+    except ValidationError as exc:
+        raise SchemaError(f"{path}: {exc}") from exc
+    known = {c.id for c in model.components}
+    for fault in scenario.faults:
+        if fault.target not in known:
+            raise RefError(f"{path}: unknown fault target {fault.target!r}")
+        if fault.start_s + fault.duration_s > scenario.duration_s:
+            raise SchemaError(f"{path}: fault exceeds scenario duration")
+    return scenario

shadowbox/engine.py

@@ -0,0 +1,220 @@
+"""Deterministic discrete-event engine (M1).
+
+Virtual time, 1ms resolution, single isolated RNG. No wall-clock reads.
+Only event *counts* are kept; full event logs are deferred to M5.
+"""
+
+from __future__ import annotations
+
+import heapq
+import random
+from dataclasses import dataclass, field
+
+from shadowbox.errors import TooLargeError
+from shadowbox.model import Component, Fault, Scenario, SystemModel
+
+MS_PER_S = 1000
+MAX_REQUESTS = 200_000
+MAX_SAMPLE = 500  # stored request summaries; full event log deferred to M5
+
+
+@dataclass
+class ComponentStats:
+    busy_time_ms: int = 0
+    max_queue_depth: int = 0
+    timeouts: int = 0
+
+
+@dataclass
+class _Runtime:
+    busy_until: list[int] = field(default_factory=list)  # min-heap of slot releases
+    waiter_starts: list[int] = field(default_factory=list)  # min-heap of queued starts
+    stats: ComponentStats = field(default_factory=ComponentStats)
+
+
+@dataclass
+class RequestSample:
+    correlation_id: str
+    ok: bool
+    latency_ms: int
+    failed_at: str | None
+    timed_out: bool
+    arrival_ms: int
+    finish_ms: int
+
+
+@dataclass
+class SimulationResult:
+    total: int
+    succeeded: int
+    failed: int
+    timeouts: int
+    latencies_ms: list[int]  # end-to-end, successes only
+    cascade_depth: int  # max failing-hop index over failed requests
+    events_processed: int
+    component_stats: dict[str, ComponentStats]
+    sample: list[RequestSample] = field(default_factory=list)  # first MAX_SAMPLE
+
+
+def build_path(model: SystemModel) -> list[Component]:
+    """Depth-first traversal from entry points, each component visited once."""
+    by_id = {c.id: c for c in model.components}
+    incoming = {c.id: 0 for c in model.components}
+    adjacency: dict[str, list[str]] = {c.id: [] for c in model.components}
+    for conn in model.connections:
+        adjacency[conn.from_].append(conn.to)
+        incoming[conn.to] += 1
+    for neighbours in adjacency.values():
+        neighbours.sort()
+    path: list[Component] = []
+    seen: set[str] = set()
+
+    def visit(node: str) -> None:
+        if node in seen:
+            return
+        seen.add(node)
+        path.append(by_id[node])
+        for nxt in adjacency[node]:
+            visit(nxt)
+
+    for entry in sorted(n for n, deg in incoming.items() if deg == 0):
+        visit(entry)
+    return path
+
+
+def _window_ms(fault: Fault) -> tuple[int, int]:
+    start = fault.start_s * MS_PER_S
+    return (start, start + fault.duration_s * MS_PER_S)
+
+
+def _effective_capacity(comp: Component, faults: list[Fault]) -> int:
+    capacity = comp.capacity
+    for fault in faults:
+        if fault.type == "resource-saturation":
+            return 1
+        if fault.type == "capacity-reduction":
+            capacity = min(capacity, max(1, int(comp.capacity * fault.factor)))
+    return capacity
+
+
+def _process(
+    comp: Component,
+    arrival_ms: int,
+    runtime: _Runtime,
+    faults: list[Fault],
+    rng: random.Random,
+) -> tuple[bool, int, bool, int]:
+    """Run one component visit. Returns (ok, end_ms, timed_out, events)."""
+    events = 4  # sent, received, processing-started, processing-completed
+    for fault in faults:
+        events += 1  # failure-injected observed
+        if fault.type == "unavailable":
+            return (False, arrival_ms, False, events)
+        if fault.type in ("error-rate", "packet-loss") and rng.random() < fault.probability:
+            return (False, arrival_ms, False, events)
+    extra_ms = sum(f.extra_ms for f in faults if f.type == "latency")
+    jitter = rng.randint(0, comp.latency_ms.jitter_ms) if comp.latency_ms.jitter_ms else 0
+    service_ms = comp.latency_ms.base + jitter + extra_ms
+    capacity = _effective_capacity(comp, faults)
+    while runtime.busy_until and runtime.busy_until[0] <= arrival_ms:
+        heapq.heappop(runtime.busy_until)
+    if len(runtime.busy_until) < capacity:
+        start_ms = arrival_ms
+    else:
+        while runtime.waiter_starts and runtime.waiter_starts[0] <= arrival_ms:
+            heapq.heappop(runtime.waiter_starts)
+        if len(runtime.waiter_starts) >= comp.queue_size:
+            return (False, arrival_ms, False, events)  # queue-full drop
+        start_ms = heapq.heappop(runtime.busy_until)  # consume the earliest slot
+        heapq.heappush(runtime.waiter_starts, start_ms)
+        depth_now = len(runtime.waiter_starts)
+        runtime.stats.max_queue_depth = max(runtime.stats.max_queue_depth, depth_now)
+    wait_ms = start_ms - arrival_ms
+    if wait_ms >= comp.timeout_ms:
+        runtime.stats.timeouts += 1
+        return (False, arrival_ms + comp.timeout_ms, True, events)  # gave up waiting
+    if service_ms > comp.timeout_ms - wait_ms:
+        busy_until = start_ms + (comp.timeout_ms - wait_ms)
+        runtime.stats.busy_time_ms += busy_until - start_ms
+        runtime.stats.timeouts += 1
+        heapq.heappush(runtime.busy_until, busy_until)
+        return (False, busy_until, True, events)
+    busy_until = start_ms + service_ms
+    runtime.stats.busy_time_ms += service_ms
+    heapq.heappush(runtime.busy_until, busy_until)
+    return (True, busy_until, False, events)
+
+
+@dataclass
+class _RequestOutcome:
+    ok: bool
+    latency_ms: int
+    failed_at: str | None
+    timed_out: bool
+    finish_ms: int
+
+
+def simulate(model: SystemModel, scenario: Scenario, seed: int) -> SimulationResult:
+    """Run the scenario deterministically; same inputs always give same outputs."""
+    total = scenario.workload.rate_rps * scenario.duration_s
+    if total > MAX_REQUESTS:
+        raise TooLargeError(f"{total} requests exceed cap of {MAX_REQUESTS}")
+    path = build_path(model)
+    windows: dict[str, list[tuple[int, int, Fault]]] = {}
+    for fault in scenario.faults:
+        start, end = _window_ms(fault)
+        windows.setdefault(fault.target, []).append((start, end, fault))
+    runtimes = {c.id: _Runtime() for c in model.components}
+    rng = random.Random(seed)
+    interval_ms = MS_PER_S / scenario.workload.rate_rps
+    latencies: list[int] = []
+    sample: list[RequestSample] = []
+    succeeded = 0
+    failed = 0
+    timeouts = 0
+    cascade_depth = 0
+    events = 0
+    for i in range(total):
+        arrival_ms = int(i * interval_ms)
+        cursor_ms = arrival_ms
+        events += 2  # request-created, request-completed
+        outcome = _RequestOutcome(True, 0, None, False, arrival_ms)
+        for depth, comp in enumerate(path):
+            active = windows.get(comp.id, [])
+            faults = [f for (start, end, f) in active if start <= cursor_ms < end]
+            ok, end_ms, timed_out, delta = _process(comp, cursor_ms, runtimes[comp.id], faults, rng)
+            events += delta
+            if not ok:
+                failed += 1
+                cascade_depth = max(cascade_depth, depth)
+                timeouts += 1 if timed_out else 0
+                outcome = _RequestOutcome(False, 0, comp.id, timed_out, end_ms)
+                break
+            cursor_ms = end_ms
+        else:
+            succeeded += 1
+            latencies.append(cursor_ms - arrival_ms)
+            outcome = _RequestOutcome(True, cursor_ms - arrival_ms, None, False, cursor_ms)
+        if len(sample) < MAX_SAMPLE:
+            sample.append(
+                RequestSample(
+                    correlation_id=f"req-{i:06d}",
+                    ok=outcome.ok,
+                    latency_ms=outcome.latency_ms,
+                    failed_at=outcome.failed_at,
+                    timed_out=outcome.timed_out,
+                    arrival_ms=arrival_ms,
+                    finish_ms=outcome.finish_ms,
+                )
+            )
+    return SimulationResult(
+        total=total,
+        succeeded=succeeded,
+        failed=failed,
+        timeouts=timeouts,
+        latencies_ms=latencies,
+        cascade_depth=cascade_depth,
+        events_processed=events,
+        component_stats={cid: rt.stats for cid, rt in runtimes.items()},
+        sample=sample,
+    )

shadowbox/errors.py

@@ -0,0 +1,38 @@
+"""Stable error codes for model/scenario validation (M0 contract)."""
+
+
+class ShadowBoxError(Exception):
+    """Base error with a stable machine-readable code."""
+
+    code: str = "E_UNKNOWN"
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class RefError(ShadowBoxError):
+    code = "E_REF"
+
+
+class CycleError(ShadowBoxError):
+    code = "E_CYCLE"
+
+
+class SchemaError(ShadowBoxError):
+    code = "E_SCHEMA"
+
+
+class TooLargeError(ShadowBoxError):
+    code = "E_TOO_LARGE"
+
+
+class UnsafeYamlError(ShadowBoxError):
+    code = "E_UNSAFE_YAML"
+
+
+class SeedMismatchWarning(ShadowBoxError):
+    code = "E_SEED_MISMATCH"
+
+
+class ExistsError(ShadowBoxError):
+    code = "E_EXISTS"

shadowbox/importers/__init__.py

@@ -0,0 +1,3 @@
+"""Model importers: external formats convert to ShadowBox models (M2)."""
+
+__all__ = ["compose"]

shadowbox/importers/compose.py

@@ -0,0 +1,109 @@
+"""Import a docker-compose file into a ShadowBox model (M2).
+
+Every performance field is an estimated default, never a measurement:
+the caller must calibrate before trusting any simulation output.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from shadowbox.errors import SchemaError, UnsafeYamlError
+from shadowbox.model import SystemModel
+
+_DB_HINTS = ("postgres", "mysql", "mariadb", "mongo", "sqlite", "cockroach", "cassandra")
+_CACHE_HINTS = ("redis", "memcached", "valkey", "cache")
+
+_DEFAULTS: dict[str, dict[str, Any]] = {
+    "service": {
+        "capacity": 20,
+        "latency_ms": {"base": 20, "jitter_ms": 5},
+        "timeout_ms": 1000,
+        "queue_size": 100,
+        "queue_policy": "drop",
+    },
+    "database": {
+        "capacity": 10,
+        "latency_ms": {"base": 5, "jitter_ms": 1},
+        "timeout_ms": 500,
+        "queue_size": 50,
+        "queue_policy": "fifo",
+    },
+    "cache": {
+        "capacity": 50,
+        "latency_ms": {"base": 2, "jitter_ms": 1},
+        "timeout_ms": 200,
+        "queue_size": 200,
+        "queue_policy": "drop",
+    },
+}
+
+
+def _infer_type(service: str, image: str) -> str:
+    lowered = image.lower()
+    if any(hint in lowered for hint in _DB_HINTS):
+        return "database"
+    if any(hint in lowered for hint in _CACHE_HINTS):
+        return "cache"
+    return "service"
+
+
+def _depends_on(spec: Any) -> list[str]:
+    if spec is None:
+        return []
+    if isinstance(spec, list):
+        return [str(item) for item in spec]
+    if isinstance(spec, dict):
+        return sorted(str(key) for key in spec)
+    return []
+
+
+def _links(spec: Any) -> list[str]:
+    if not isinstance(spec, list):
+        return []
+    return [str(item).split(":")[0] for item in spec]
+
+
+def import_compose(path: Path) -> tuple[SystemModel, list[str]]:
+    """Parse compose file; returns (model, warnings). All metrics are estimates."""
+    try:
+        raw_text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SchemaError(f"cannot read {path}: {exc}") from exc
+    if "!!python/" in raw_text or "!python/" in raw_text:
+        raise UnsafeYamlError(f"{path}: unsafe YAML tag rejected")
+    try:
+        data = yaml.safe_load(raw_text)
+    except yaml.YAMLError as exc:
+        raise SchemaError(f"{path}: invalid YAML: {exc}") from exc
+    if not isinstance(data, dict) or not isinstance(data.get("services"), dict):
+        raise SchemaError(f"{path}: top-level `services` mapping required")
+    services: dict[str, Any] = data["services"]
+    if not services:
+        raise SchemaError(f"{path}: no services defined")
+    components: list[dict[str, Any]] = []
+    connections: list[dict[str, Any]] = []
+    warnings: list[str] = []
+    for name in sorted(services):
+        spec = services[name] if isinstance(services[name], dict) else {}
+        image = str(spec.get("image", ""))
+        kind = _infer_type(name, image)
+        fields = dict(_DEFAULTS[kind])
+        components.append({"id": name, "type": kind, **fields})
+        shown_image = image if image else "(none)"
+        warnings.append(f"{name!r}: {kind} inferred from {shown_image}; fields estimated")
+        for dep in sorted(set(_depends_on(spec.get("depends_on")) + _links(spec.get("links")))):
+            connections.append({"from": name, "to": dep})
+    known_names = set(services)
+    kept: list[dict[str, Any]] = []
+    for conn in connections:
+        if conn["to"] not in known_names:
+            warnings.append(f"dropped {conn['from']} -> {conn['to']} (outside compose)")
+            continue
+        kept.append(conn)
+    try:
+        model = SystemModel.model_validate({"components": components, "connections": kept})
+    except Exception as exc:
+        raise SchemaError(f"{path}: cannot build model: {exc}") from exc
+    return (model, warnings)

shadowbox/metrics.py

@@ -0,0 +1,49 @@
+"""Metric aggregation over a finished simulation (exact percentiles)."""
+
+import math
+
+from shadowbox.engine import MS_PER_S, SimulationResult
+from shadowbox.model import SystemModel
+
+
+def percentile(sorted_values: list[int], pct: float) -> float:
+    """Nearest-rank percentile; empty input yields 0.0 (no successful requests)."""
+    if not sorted_values:
+        return 0.0
+    rank = max(1, math.ceil((pct / 100.0) * len(sorted_values)))
+    return float(sorted_values[rank - 1])
+
+
+def summarize(
+    model: SystemModel,
+    result: SimulationResult,
+    duration_s: int,
+) -> dict[str, object]:
+    """Aggregate counts, exact latency percentiles, and per-component stats."""
+    ordered = sorted(result.latencies_ms)
+    by_id = {c.id: c for c in model.components}
+    components = {}
+    for cid in sorted(result.component_stats):
+        stats = result.component_stats[cid]
+        capacity = by_id[cid].capacity
+        components[cid] = {
+            "utilization": stats.busy_time_ms / (capacity * duration_s * MS_PER_S),
+            "queue_depth": stats.max_queue_depth,
+            "timeouts": stats.timeouts,
+        }
+    total = result.total
+    return {
+        "throughput_rps": result.succeeded / duration_s if duration_s else 0.0,
+        "error_rate": result.failed / total if total else 0.0,
+        "latency_ms": {
+            "p50": percentile(ordered, 50),
+            "p90": percentile(ordered, 90),
+            "p95": percentile(ordered, 95),
+            "p99": percentile(ordered, 99),
+        },
+        "timeouts": result.timeouts,
+        "retries": 0,  # auto-retry disabled in MVP; scenario max_retries lands in M3
+        "cascade_depth": result.cascade_depth,
+        "requests": {"total": total, "succeeded": result.succeeded, "failed": result.failed},
+        "components": components,
+    }

shadowbox/model.py

@@ -0,0 +1,74 @@
+"""Pydantic domain model for M0 (structure only, no simulation)."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+QueuePolicy = Literal["drop", "fifo"]
+ConnectionKind = Literal["sync"]
+
+MAX_COMPONENTS = 200
+MAX_EVENTS = 500_000
+
+
+class LatencyMs(BaseModel):
+    base: int = Field(ge=0)
+    jitter_ms: int = Field(default=0, ge=0)
+
+
+class Component(BaseModel):
+    id: str = Field(min_length=1)
+    type: Literal["service", "database", "cache"]
+    capacity: int = Field(gt=0)
+    latency_ms: LatencyMs
+    timeout_ms: int = Field(gt=0)
+    queue_size: int = Field(gt=0)
+    queue_policy: QueuePolicy
+
+
+class Connection(BaseModel):
+    from_: str = Field(alias="from")
+    to: str
+    kind: ConnectionKind = "sync"
+
+
+class SystemModel(BaseModel):
+    components: list[Component] = Field(min_length=1)
+    connections: list[Connection] = Field(default_factory=list)
+
+    @field_validator("components")
+    @classmethod
+    def unique_ids(cls, items: list[Component]) -> list[Component]:
+        seen = {c.id for c in items}
+        if len(seen) != len(items):
+            raise ValueError("duplicate component id")
+        return items
+
+
+class Fault(BaseModel):
+    target: str = Field(min_length=1)
+    type: Literal[
+        "unavailable",
+        "latency",
+        "error-rate",
+        "capacity-reduction",
+        "packet-loss",
+        "resource-saturation",
+    ]
+    start_s: int = Field(ge=0)
+    duration_s: int = Field(ge=0)
+    extra_ms: int = Field(default=0, ge=0)
+    probability: float = Field(default=0.0, ge=0.0, le=1.0)
+    factor: float = Field(default=1.0, gt=0.0, le=1.0)
+
+
+class Workload(BaseModel):
+    rate_rps: int = Field(gt=0)
+    arrival: Literal["deterministic"] = "deterministic"
+
+
+class Scenario(BaseModel):
+    name: str = Field(min_length=1)
+    duration_s: int = Field(gt=0)
+    workload: Workload
+    faults: list[Fault] = Field(default_factory=list)

shadowbox/report.py

@@ -0,0 +1,48 @@
+"""Report envelope: metrics plus honesty metadata and a reproducibility hash."""
+
+import hashlib
+import json
+from typing import Any
+
+ENGINE_VERSION = "shadowbox-m1/0.1.0"
+
+ASSUMPTIONS = [
+    "sync calls only",
+    "depth-first traversal, each component visited once per request",
+    "deterministic uniform arrivals",
+    "no auto-retry (max_retries unsupported in M1)",
+    "no GC pause or infrastructure noise model",
+]
+
+LIMITATIONS = [
+    "uncalibrated latencies: outputs are what-if illustrations, not predictions",
+    "queueing is per-component FIFO with fixed capacity; no backpressure protocol",
+]
+
+
+def canonical_hash(payload: dict[str, Any]) -> str:
+    """SHA-256 over canonical JSON (sorted keys, compact separators)."""
+    raw = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def build_report(
+    model: dict[str, Any],
+    scenario: dict[str, Any],
+    seed: int,
+    metrics: dict[str, Any],
+    events_processed: int,
+) -> dict[str, Any]:
+    """Envelope the metrics; the hash covers model+scenario+seed+metrics only."""
+    payload = {"model": model, "scenario": scenario, "seed": seed, "metrics": metrics}
+    return {
+        "engine": ENGINE_VERSION,
+        "seed": seed,
+        "metrics": metrics,
+        "metrics_hash": canonical_hash(payload),
+        "assumptions": ASSUMPTIONS,
+        "limitations": LIMITATIONS,
+        "confidence": "low",
+        "calibration_source": "none",
+        "events_processed": events_processed,
+    }