simloom 0.1.0__py3-none-any.whl

simloom/__init__.py

@@ -0,0 +1,68 @@
+"""simloom — deterministic simulation testing for asyncio.
+
+Run unmodified asyncio programs inside a fully simulated universe: a seeded
+choice tape owns every scheduling decision, the clock is virtual, and every
+failure replays exactly from its recording.
+
+Phase A surface: the deterministic loop, the choice tape, run/replay, escape
+detection, and the versioned event log. The simulated world (hosts, network,
+faults) and the explorer arrive in later phases — see docs/plan.md.
+"""
+
+from ._buggify import draw, reached, sometimes
+from ._errors import (
+    EscapedSimulationError,
+    SimDeadlockError,
+    SimloomError,
+    TapeMisalignmentError,
+    UnhandledExceptionError,
+)
+from ._eventlog import EVENT_LOG_FORMAT_VERSION, EventLog
+from ._explore import Exploration, Failure, explore
+from ._loop import SimLoop
+from ._net import SimNetwork, SimServer, SimTransport
+from ._run import RunResult, replay, run
+from ._sched import PCT, RandomWalk
+from ._shrink import ShrinkResult, shrink
+from ._tape import TAPE_FORMAT_VERSION, Draw, MisalignmentPolicy, Tape
+from ._testing import Settings, SimloomTestFailure, test
+from ._version import __version__
+from ._world import Host, SimDisk, World
+
+__all__ = [
+    "EVENT_LOG_FORMAT_VERSION",
+    "PCT",
+    "TAPE_FORMAT_VERSION",
+    "Draw",
+    "EscapedSimulationError",
+    "EventLog",
+    "Exploration",
+    "Failure",
+    "Host",
+    "MisalignmentPolicy",
+    "RandomWalk",
+    "RunResult",
+    "Settings",
+    "ShrinkResult",
+    "SimDeadlockError",
+    "SimDisk",
+    "SimLoop",
+    "SimNetwork",
+    "SimServer",
+    "SimTransport",
+    "SimloomError",
+    "SimloomTestFailure",
+    "Tape",
+    "TapeMisalignmentError",
+    "UnhandledExceptionError",
+    "World",
+    "__version__",
+    "draw",
+    "explore",
+    "reached",
+    "replay",
+    "run",
+    "shrink",
+    "sometimes",
+    "test",
+]

simloom/_buggify.py

@@ -0,0 +1,62 @@
+"""Buggify: tape-drawn randomness for the code under test.
+
+FoundationDB's trick, adapted: user code annotates rare-but-legal behaviors
+(`if simloom.sometimes("drop_cache"): ...`) and the simulation explores them;
+in production the same call is a constant False, so the annotations cost
+nothing and never fire outside a test.
+
+Coverage counters (``reached``, and every ``sometimes`` that fires) land in
+``RunResult.coverage`` so a corpus runner can assert that fault-handling
+branches were actually exercised somewhere — the "sometimes assertion" that
+catches dead recovery code.
+"""
+
+from __future__ import annotations
+
+import asyncio.events
+
+from ._loop import SimLoop
+
+
+def _sim_loop() -> SimLoop | None:
+    loop = asyncio.events._get_running_loop()
+    return loop if isinstance(loop, SimLoop) else None
+
+
+def sometimes(label: str, percent: int = 25) -> bool:
+    """True with roughly ``percent`` probability inside a simulation;
+    always False outside one (safe to leave in production code)."""
+    if not 0 <= percent <= 100:
+        raise ValueError("percent must be in [0, 100]")
+    loop = _sim_loop()
+    if loop is None:
+        return False
+    fired = loop.tape.draw(f"buggify.{label}", 100) < percent
+    if fired:
+        loop.record_coverage(label)
+    return fired
+
+
+def draw(label: str, bound: int) -> int:
+    """A labeled integer draw in ``[0, bound)`` from the run's choice tape.
+
+    For randomness the *program under test* needs (election timeouts, victim
+    picks in chaos scripts) — it replays and shrinks with everything else.
+    Unlike :func:`sometimes` this has no meaningful production value, so it
+    raises outside a simulation.
+    """
+    loop = _sim_loop()
+    if loop is None:
+        raise RuntimeError("simloom.draw() requires a running simulation")
+    return loop.tape.draw(label, bound)
+
+
+def reached(label: str) -> None:
+    """Record that this point was reached (no-op outside a simulation).
+
+    Counts appear in ``RunResult.coverage``; a corpus runner can assert a
+    label was reached somewhere across many seeds.
+    """
+    loop = _sim_loop()
+    if loop is not None:
+        loop.record_coverage(label)

simloom/_context.py

@@ -0,0 +1,11 @@
+"""Context variables shared across simloom modules (no internal imports,
+so anything may import this without cycles)."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import Any
+
+#: The simulated host whose code is currently executing, if any. Set by
+#: Host.spawn's wrapper coroutine; inherited by child tasks via contextvars.
+current_host: ContextVar[Any] = ContextVar("simloom_current_host", default=None)

simloom/_errors.py

@@ -0,0 +1,54 @@
+"""Exception types raised by simloom."""
+
+from __future__ import annotations
+
+
+class SimloomError(Exception):
+    """Base class for every error simloom raises on its own behalf."""
+
+
+class EscapedSimulationError(SimloomError):
+    """The program under test reached for the real world from inside the sim.
+
+    Determinism only holds while every effect flows through the simulated
+    loop. Real sockets, file-descriptor callbacks, signal handlers, real DNS,
+    subprocesses — any of these would reintroduce nondeterminism silently, so
+    simloom turns them into this error at the exact call site instead.
+    """
+
+    def __init__(self, api: str, hint: str) -> None:
+        self.api = api
+        self.hint = hint
+        super().__init__(
+            f"{api} escapes the simulation: {hint} (see docs/determinism.md for the full boundary)"
+        )
+
+
+class SimDeadlockError(SimloomError):
+    """The simulated universe went quiescent with work still pending.
+
+    No callback is runnable and no timer is scheduled, but the run has not
+    finished: every remaining task is waiting on something that can no longer
+    happen. This is the classic distributed-systems deadlock, caught at the
+    moment it forms instead of as a test timeout.
+    """
+
+
+class TapeMisalignmentError(SimloomError):
+    """A replayed tape could not satisfy the draw the program asked for.
+
+    Replay re-executes the program and feeds it recorded decisions; if the
+    program requests a draw whose label or bound differs from what was
+    recorded — or runs past the end of the tape — the execution has diverged
+    from the recording (changed code, unpinned hash randomization, or an
+    escape simloom failed to catch).
+    """
+
+
+class UnhandledExceptionError(SimloomError):
+    """An exception reached the loop's exception handler and nothing else.
+
+    asyncio's default behavior is to log fire-and-forget task failures and
+    keep going; a testing harness must not let them pass silently. Configure
+    with ``on_unhandled`` if a test legitimately expects orphaned failures.
+    """

simloom/_eventlog.py

@@ -0,0 +1,95 @@
+"""The event log: a versioned, public record of everything a run did.
+
+One JSONL document per run: a header object carrying metadata, then one
+object per event in execution order. The format is a public contract —
+failure artifacts ship it, tooling consumes it, and the planned time-travel
+debugger replays from it — so schema changes bump the version. The schema is
+documented in docs/event-log.md.
+
+The digest covers the *events only*, not the header: two runs are the same
+universe iff their event sequences are byte-identical, regardless of which
+machine or interpreter produced them.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator, Mapping
+from pathlib import Path
+from typing import Any
+
+EVENT_LOG_FORMAT = "simloom-events"
+EVENT_LOG_FORMAT_VERSION = 1
+
+
+def _canonical(obj: Mapping[str, Any]) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+class EventLog:
+    """An append-only sequence of events with canonical serialization."""
+
+    __slots__ = ("_events", "metadata")
+
+    def __init__(self) -> None:
+        self._events: list[dict[str, Any]] = []
+        #: Run metadata for the header line; never part of the digest.
+        self.metadata: dict[str, Any] = {}
+
+    def emit(self, kind: str, t: float, **fields: Any) -> None:
+        """Append one event at virtual time ``t``.
+
+        Field values must be JSON-serializable and deterministic — no memory
+        addresses, no wall-clock times, no process-global counters.
+        """
+        event: dict[str, Any] = {"seq": len(self._events), "kind": kind, "t": t}
+        for key, value in fields.items():
+            if key in event:
+                raise ValueError(f"reserved event field: {key}")
+            event[key] = value
+        self._events.append(event)
+
+    # --- reading ---
+
+    @property
+    def events(self) -> tuple[Mapping[str, Any], ...]:
+        return tuple(self._events)
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def __iter__(self) -> Iterator[Mapping[str, Any]]:
+        return iter(self._events)
+
+    def __repr__(self) -> str:
+        return f"<EventLog {len(self._events)} events digest={self.digest()[:12]}>"
+
+    # --- serialization ---
+
+    def header(self) -> dict[str, Any]:
+        return {
+            "format": EVENT_LOG_FORMAT,
+            "version": EVENT_LOG_FORMAT_VERSION,
+            **self.metadata,
+        }
+
+    def event_lines(self) -> Iterator[str]:
+        for event in self._events:
+            yield _canonical(event)
+
+    def to_jsonl(self) -> str:
+        lines = [_canonical(self.header())]
+        lines.extend(self.event_lines())
+        return "\n".join(lines) + "\n"
+
+    def write_to(self, path: str | Path) -> None:
+        Path(path).write_text(self.to_jsonl(), encoding="utf-8")
+
+    def digest(self) -> str:
+        """sha256 over the canonical event lines (header excluded)."""
+        h = hashlib.sha256()
+        for line in self.event_lines():
+            h.update(line.encode("utf-8"))
+            h.update(b"\n")
+        return h.hexdigest()

simloom/_explore.py

@@ -0,0 +1,145 @@
+"""The explorer: run many fresh universes and collect what broke.
+
+Random exploration is embarrassingly parallel: with ``processes > 1`` seeds
+fan out over a process pool (``main`` must then be importable — a module-
+level callable). Workers report which seeds failed; the parent re-runs the
+first failing seed locally so the returned artifact is exactly reproducible
+in the caller's process.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine
+from concurrent.futures import ProcessPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._run import RunResult, run
+from ._sched import SchedulerFactory
+
+
+@dataclass(frozen=True, slots=True)
+class Failure:
+    seed: int
+    error: str  # exception type name
+    message: str
+
+
+@dataclass(slots=True)
+class Exploration:
+    """What ``explore`` found across a corpus of seeds."""
+
+    runs: int
+    failures: list[Failure]
+    #: Full artifact for the lowest failing seed (replayable, shrinkable).
+    first_failure: RunResult | None
+    #: Union of buggify/reached counters across all runs — the data for
+    #: corpus-level sometimes-assertions ("was this branch ever hit?").
+    coverage: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def failed(self) -> bool:
+        return bool(self.failures)
+
+    def summary(self) -> str:
+        if not self.failures:
+            return f"{self.runs} universes explored, none failed"
+        first = self.failures[0]
+        return (
+            f"{self.runs} universes explored, {len(self.failures)} failed; "
+            f"first: seed {first.seed} raised {first.error}: {first.message}"
+        )
+
+
+def explore(
+    main: Callable[..., Coroutine[Any, Any, Any]],
+    *,
+    runs: int,
+    start_seed: int = 0,
+    stop_on_failure: bool = True,
+    processes: int = 1,
+    scheduler: str | SchedulerFactory | None = None,
+    **run_kwargs: Any,
+) -> Exploration:
+    """Run ``main`` under ``runs`` fresh seeds and report the failures."""
+    if runs < 1:
+        raise ValueError("runs must be >= 1")
+    seeds = range(start_seed, start_seed + runs)
+    if processes > 1:
+        return _explore_pool(main, seeds, stop_on_failure, processes, scheduler, run_kwargs)
+
+    failures: list[Failure] = []
+    first: RunResult | None = None
+    coverage: dict[str, int] = {}
+    executed = 0
+    for seed in seeds:
+        result = run(main, seed=seed, raise_on_error=False, scheduler=scheduler, **run_kwargs)
+        executed += 1
+        for label, count in result.coverage.items():
+            coverage[label] = coverage.get(label, 0) + count
+        if result.outcome == "error":
+            assert result.error is not None
+            failures.append(Failure(seed, type(result.error).__name__, str(result.error)[:200]))
+            if first is None:
+                first = result
+            if stop_on_failure:
+                break
+    return Exploration(executed, failures, first, coverage)
+
+
+# --- process-pool fan-out ---
+
+
+def _probe(
+    main: Callable[..., Coroutine[Any, Any, Any]],
+    seed: int,
+    scheduler: str | None,
+    run_kwargs: dict[str, Any],
+) -> tuple[int, str | None, str, dict[str, int]]:
+    result = run(main, seed=seed, raise_on_error=False, scheduler=scheduler, **run_kwargs)
+    error = type(result.error).__name__ if result.error is not None else None
+    message = str(result.error)[:200] if result.error is not None else ""
+    return seed, error, message, result.coverage
+
+
+def _explore_pool(
+    main: Callable[..., Coroutine[Any, Any, Any]],
+    seeds: range,
+    stop_on_failure: bool,
+    processes: int,
+    scheduler: str | SchedulerFactory | None,
+    run_kwargs: dict[str, Any],
+) -> Exploration:
+    if scheduler is not None and not isinstance(scheduler, str):
+        raise TypeError("processes > 1 requires a string scheduler spec (picklable)")
+    failures: list[Failure] = []
+    coverage: dict[str, int] = {}
+    executed = 0
+    with ProcessPoolExecutor(max_workers=processes) as pool:
+        for seed, error, message, run_coverage in pool.map(
+            _probe,
+            (main for _ in seeds),
+            seeds,
+            (scheduler for _ in seeds),
+            (run_kwargs for _ in seeds),
+            chunksize=8,
+        ):
+            executed += 1
+            for label, count in run_coverage.items():
+                coverage[label] = coverage.get(label, 0) + count
+            if error is not None:
+                failures.append(Failure(seed, error, message))
+                if stop_on_failure:
+                    break
+    failures.sort(key=lambda f: f.seed)
+    first: RunResult | None = None
+    if failures:
+        # Re-run locally: the artifact must reproduce in the caller's process.
+        first = run(
+            main,
+            seed=failures[0].seed,
+            raise_on_error=False,
+            scheduler=scheduler,
+            **run_kwargs,
+        )
+    return Exploration(executed, failures, first, coverage)