detangle 0.1.0__py3-none-any.whl

detangle/__init__.py

@@ -0,0 +1,118 @@
+"""detangle -- deterministic simulation testing for Python asyncio.
+
+Run your async code under thousands of different (but perfectly
+reproducible) schedules, network conditions and fault patterns; get the
+race conditions, deadlocks and cancellation bugs back as minimal, replayable
+counterexamples.
+
+Quick start::
+
+    import asyncio, detangle
+
+    @detangle.test
+    async def test_counter():
+        counter = {"value": 0}
+
+        async def incr():
+            current = counter["value"]
+            await asyncio.sleep(0)          # e.g. a database round-trip
+            counter["value"] = current + 1
+
+        await asyncio.gather(incr(), incr())
+        assert counter["value"] == 2        # fails: lost update found & shrunk
+
+See https://github.com/louistarwars/Detangle for the documentation.
+"""
+
+from __future__ import annotations
+
+from . import lin, net, strategies
+from ._api import (
+    choice,
+    flip,
+    in_simulation,
+    inject_cancellation,
+    invariant,
+    maybe_timeout,
+    network,
+    note,
+    now,
+    randint,
+    shuffle,
+    spawn,
+    uniform,
+)
+from ._choices import Decision, decode_token, encode_token
+from ._config import NetConfig, SimConfig
+from ._loop import SimLoop, current_loop
+from ._runner import Failure, RunResult, execute
+from ._version import __version__
+from .errors import (
+    BugFound,
+    DeadlockError,
+    DetangleError,
+    InjectedTimeout,
+    InvariantViolation,
+    NotLinearizable,
+    RealIOError,
+    SimulationError,
+    StepLimitExceeded,
+    TimeLimitExceeded,
+)
+from .explore import BugReport, ExploreStats, explore, replay, run, test
+from .lin import History
+from .strategies import DFS, FIFO, PCT, Portfolio, RandomWalk, Replay, Strategy
+
+__all__ = [
+    "DFS",
+    "FIFO",
+    "PCT",
+    "BugFound",
+    "BugReport",
+    "DeadlockError",
+    "Decision",
+    "DetangleError",
+    "ExploreStats",
+    "Failure",
+    "History",
+    "InjectedTimeout",
+    "InvariantViolation",
+    "NetConfig",
+    "NotLinearizable",
+    "Portfolio",
+    "RandomWalk",
+    "RealIOError",
+    "Replay",
+    "RunResult",
+    "SimConfig",
+    "SimLoop",
+    "SimulationError",
+    "StepLimitExceeded",
+    "Strategy",
+    "TimeLimitExceeded",
+    "__version__",
+    "choice",
+    "current_loop",
+    "decode_token",
+    "encode_token",
+    "execute",
+    "explore",
+    "flip",
+    "in_simulation",
+    "inject_cancellation",
+    "invariant",
+    "lin",
+    "maybe_timeout",
+    "net",
+    "network",
+    "note",
+    "now",
+    "randint",
+    "replay",
+    "run",
+    "shuffle",
+    "spawn",
+    "strategies",
+    "test",
+    "uniform",
+]

detangle/__main__.py

@@ -0,0 +1,157 @@
+"""Command-line interface.
+
+Usage::
+
+    detangle explore tests/test_bank.py:test_transfer --runs 2000
+    detangle replay dt1-eJxj... tests/test_bank.py:test_transfer --html report.html
+    detangle decode dt1-eJxj...
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._choices import decode_token
+from ._version import __version__
+
+
+def _load(target: str) -> Any:
+    if ":" not in target:
+        raise SystemExit(
+            f"error: target must look like 'module:function' or 'path.py:function', got {target!r}"
+        )
+    module_part, _, attr = target.rpartition(":")
+    if module_part.endswith(".py") or os.sep in module_part or "/" in module_part:
+        path = Path(module_part).resolve()
+        if not path.exists():
+            raise SystemExit(f"error: no such file: {module_part}")
+        sys.path.insert(0, str(path.parent))
+        name = path.stem
+        spec = importlib.util.spec_from_file_location(name, path)
+        if spec is None or spec.loader is None:
+            raise SystemExit(f"error: cannot import {module_part}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[name] = module
+        spec.loader.exec_module(module)
+    else:
+        sys.path.insert(0, os.getcwd())
+        module = importlib.import_module(module_part)
+    obj: Any = module
+    for part in attr.split("."):
+        obj = getattr(obj, part)
+    return getattr(obj, "_detangle_inner", obj)
+
+
+def _cmd_explore(args: argparse.Namespace) -> int:
+    from .errors import BugFound
+    from .explore import explore
+
+    fn = _load(args.target)
+    try:
+        stats = explore(
+            fn,
+            runs=args.runs,
+            strategy=args.strategy,
+            seed=args.seed,
+            max_duration=args.max_duration,
+            report_dir=args.report_dir,
+            database=False if args.no_db else None,
+        )
+    except BugFound as exc:
+        print(exc.report.render(trace_limit=args.trace_limit))
+        return 1
+    print(stats.summary())
+    return 0
+
+
+def _cmd_replay(args: argparse.Namespace) -> int:
+    from .explore import BugReport, _count_non_seed, _name_of, replay
+
+    fn = _load(args.target)
+    result = replay(fn, args.token, raise_on_failure=False)
+    if result.failure is None:
+        print(
+            f"detangle: replaying {args.token}: no failure ({result.steps} steps, "
+            f"virtual time {result.virtual_time:.6f}s)"
+        )
+        if result.trace is not None and args.trace:
+            print(result.trace.render(limit=args.trace_limit))
+        return 0
+    report = BugReport(
+        name=_name_of(fn),
+        failure=result.failure,
+        token=args.token,
+        values=decode_token(args.token),
+        runs=1,
+        strategy="replay",
+        seed=None,
+        trace=result.trace,
+        deviations=_count_non_seed(result),
+        secondary=result.secondary,
+        source="replay",
+    )
+    if args.html:
+        from ._html import render_html
+
+        Path(args.html).write_text(render_html(report), encoding="utf-8")
+        report.html_report = args.html
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, default=str))
+    else:
+        print(report.render(trace_limit=args.trace_limit))
+    return 1
+
+
+def _cmd_decode(args: argparse.Namespace) -> int:
+    values = decode_token(args.token)
+    nonzero = [(i, v) for i, v in enumerate(values) if v]
+    print(f"{len(values)} decisions, {len(nonzero)} non-default:")
+    for i, v in nonzero:
+        print(f"  decision #{i}: {v}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="detangle", description="Deterministic simulation testing for Python asyncio."
+    )
+    parser.add_argument("--version", action="version", version=f"detangle {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("explore", help="explore the schedules of an async function")
+    p.add_argument("target", help="module:function or path.py:function")
+    p.add_argument("--runs", type=int, default=None)
+    p.add_argument("--strategy", default=None)
+    p.add_argument("--seed", type=lambda s: int(s, 0), default=None)
+    p.add_argument("--max-duration", type=float, default=None)
+    p.add_argument("--report-dir", default=None)
+    p.add_argument("--no-db", action="store_true")
+    p.add_argument("--trace-limit", type=int, default=80)
+    p.set_defaults(func=_cmd_explore)
+
+    p = sub.add_parser("replay", help="replay a token printed by a failing run")
+    p.add_argument("token")
+    p.add_argument("target", help="module:function or path.py:function")
+    p.add_argument("--html", default=None, help="write an interactive HTML report")
+    p.add_argument("--json", action="store_true", help="print the report as JSON")
+    p.add_argument("--trace", action="store_true", help="print the trace even if the run passes")
+    p.add_argument("--trace-limit", type=int, default=0, help="max trace lines (0 = all)")
+    p.set_defaults(func=_cmd_replay)
+
+    p = sub.add_parser("decode", help="show the decisions inside a token")
+    p.add_argument("token")
+    p.set_defaults(func=_cmd_decode)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

detangle/_api.py

@@ -0,0 +1,144 @@
+"""Helpers meant to be called from code running *inside* a simulation."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Coroutine, MutableSequence, Sequence
+from typing import Any, TypeVar
+
+from ._choices import DATA
+from ._context import current_host
+from ._frames import caller_location
+from ._loop import SimLoop, current_loop
+from .errors import InjectedTimeout
+
+__all__ = [
+    "choice",
+    "flip",
+    "in_simulation",
+    "inject_cancellation",
+    "invariant",
+    "maybe_timeout",
+    "network",
+    "note",
+    "now",
+    "randint",
+    "shuffle",
+    "spawn",
+    "uniform",
+]
+
+_T = TypeVar("_T")
+
+
+def in_simulation() -> bool:
+    """True when called from code running inside a detangle simulation."""
+    return isinstance(asyncio.events._get_running_loop(), SimLoop)
+
+
+def now() -> float:
+    """Current virtual time, in seconds (same as ``loop.time()``)."""
+    return current_loop().time()
+
+
+def choice(options: Sequence[_T]) -> _T:
+    """Pick one of *options*.  Explored by the strategy; shrinks to the first one."""
+    if not options:
+        raise IndexError("cannot choose from an empty sequence")
+    return options[current_loop().choose(len(options), DATA)]
+
+
+def randint(a: int, b: int) -> int:
+    """An integer in ``[a, b]``.  Explored by the strategy; shrinks towards *a*."""
+    if b < a:
+        raise ValueError(f"empty range for randint({a}, {b})")
+    return a + current_loop().choose(b - a + 1, DATA)
+
+
+def uniform(a: float, b: float, steps: int = 64) -> float:
+    """A float in ``[a, b]`` (one of *steps* evenly spaced values; shrinks towards *a*)."""
+    if steps < 2:
+        return a
+    k = current_loop().choose(steps, DATA)
+    return a + (b - a) * k / (steps - 1)
+
+
+def flip(p: float = 0.5) -> bool:
+    """True with probability *p*.  Shrinks towards False."""
+    return current_loop().flip(p, DATA)
+
+
+def shuffle(items: MutableSequence[Any]) -> None:
+    """Shuffle *items* in place.  The default (all zeros) is the identity."""
+    loop = current_loop()
+    for i in range(len(items) - 1, 0, -1):
+        j = i - loop.choose(i + 1, DATA)
+        items[i], items[j] = items[j], items[i]
+
+
+def invariant(check: Callable[[], object], name: str | None = None) -> Callable[[], object]:
+    """Check ``check()`` after *every* step of the simulation.
+
+    The check fails if it raises ``AssertionError`` (or any exception) or
+    returns ``False``.  Returns *check* so it can be used as a decorator.
+    """
+    current_loop().add_invariant(check, name)
+    return check
+
+
+def note(message: str) -> None:
+    """Add a line to the trace shown when a bug is found (no-op otherwise)."""
+    loop = current_loop()
+    if loop.tracer is not None:
+        loop.tracer.on_note(asyncio.current_task(), message, caller_location(1))
+
+
+def inject_cancellation(task: asyncio.Task[Any], points: int = 8) -> None:
+    """Allow the strategy to cancel *task* at one of its next *points* awaits.
+
+    Models timeouts and client disconnects hitting at the worst moment.
+    """
+    current_loop().mark_interruptible(task, points)
+
+
+async def maybe_timeout(aw: Awaitable[_T], points: int = 8) -> _T:
+    """Await *aw*, but let the strategy "time it out" at any of its awaits.
+
+    Equivalent to ``asyncio.wait_for(aw, timeout=<adversarial>)``: returns the
+    result, or cancels the operation at one of its first *points* suspension
+    points and raises :class:`TimeoutError`.  Use it to find code that is not
+    cancellation-safe (leaked locks, connections, half-applied updates...).
+    """
+    loop = current_loop()
+    task = asyncio.ensure_future(aw)
+    loop.mark_interruptible(task, points)
+    try:
+        return await task
+    except asyncio.CancelledError:
+        if task in loop.injected and task.cancelled():
+            current = asyncio.current_task()
+            if current is None or not getattr(current, "cancelling", lambda: 0)():
+                raise InjectedTimeout(
+                    f"detangle: injected timeout (cancelled at {loop.injected[task]})"
+                ) from None
+        raise
+
+
+def spawn(
+    coro: Coroutine[Any, Any, _T], *, host: str | None = None, name: str | None = None
+) -> asyncio.Task[_T]:
+    """Create a task, optionally running on simulated *host* (see :mod:`detangle.net`)."""
+    loop = current_loop()
+    if host is None:
+        return loop.create_task(coro, name=name)
+    loop.net.ensure_host(host)
+    token = current_host.set(host)
+    try:
+        return loop.create_task(coro, name=name)
+    finally:
+        current_host.reset(token)
+
+
+def network() -> Any:
+    """The simulated network (:class:`detangle.net.SimNetwork`) of this run."""
+    return current_loop().net

detangle/_choices.py

@@ -0,0 +1,121 @@
+"""Decisions, choice sequences and replay tokens.
+
+Every source of nondeterminism in a simulation -- which ready task runs next,
+how late a timer fires, how long a network packet takes, whether a fault is
+injected -- is funnelled through a single primitive: *pick an integer in
+``range(n)``*.  The value ``0`` always means "what asyncio would do by
+default" (run the oldest ready callback, fire the timer on time, deliver the
+packet with minimum latency, inject no fault).
+
+A run is therefore fully described by the list of integers it picked.  That
+list can be replayed, mutated, shrunk and serialised into a short *token*
+which reproduces the run bit-for-bit.
+"""
+
+from __future__ import annotations
+
+import base64
+import zlib
+from collections.abc import Iterable, Sequence
+from typing import NamedTuple
+
+__all__ = ["Decision", "decode_token", "encode_token"]
+
+TOKEN_PREFIX = "dt1-"
+
+#: Decision kinds.
+SCHED = "sched"  # which ready lane runs next
+TIMER = "timer"  # timer jitter bucket
+NET = "net"  # network latency bucket / fragmentation
+FAULT = "fault"  # injected failures (drops, duplicates, cancellations)
+DATA = "data"  # user-level nondeterministic values (detangle.choice & co)
+SEED = "seed"  # seed for the global ``random`` module
+
+
+class Decision(NamedTuple):
+    """One nondeterministic choice made during a run."""
+
+    kind: str
+    n: int
+    value: int
+
+
+def _write_varint(out: bytearray, value: int) -> None:
+    if value < 0:
+        raise ValueError("choice values must be non-negative")
+    while True:
+        byte = value & 0x7F
+        value >>= 7
+        if value:
+            out.append(byte | 0x80)
+        else:
+            out.append(byte)
+            return
+
+
+def _read_varints(data: bytes) -> list[int]:
+    values: list[int] = []
+    shift = 0
+    current = 0
+    for byte in data:
+        current |= (byte & 0x7F) << shift
+        if byte & 0x80:
+            shift += 7
+            if shift > 70:
+                raise ValueError("corrupt detangle token (varint too long)")
+        else:
+            values.append(current)
+            current = 0
+            shift = 0
+    if shift:
+        raise ValueError("corrupt detangle token (truncated varint)")
+    return values
+
+
+def strip_trailing_zeros(values: Sequence[int]) -> list[int]:
+    """Trailing zeros are implicit: replaying past the end picks 0."""
+    end = len(values)
+    while end and values[end - 1] == 0:
+        end -= 1
+    return list(values[:end])
+
+
+def encode_token(values: Iterable[int]) -> str:
+    """Serialise a choice sequence into a compact, URL/shell-safe token."""
+    raw = bytearray()
+    for v in strip_trailing_zeros(list(values)):
+        _write_varint(raw, v)
+    compressed = zlib.compress(bytes(raw), 9)
+    payload = b"z" + compressed if len(compressed) < len(raw) else b"r" + bytes(raw)
+    text = base64.urlsafe_b64encode(payload).rstrip(b"=").decode("ascii")
+    return TOKEN_PREFIX + text
+
+
+def decode_token(token: str) -> list[int]:
+    """Inverse of :func:`encode_token`."""
+    token = token.strip()
+    if not token.startswith(TOKEN_PREFIX):
+        raise ValueError(f"not a detangle token (expected prefix {TOKEN_PREFIX!r}): {token!r}")
+    text = token[len(TOKEN_PREFIX) :]
+    padded = text + "=" * (-len(text) % 4)
+    try:
+        payload = base64.urlsafe_b64decode(padded.encode("ascii"))
+    except ValueError as exc:  # binascii.Error is a ValueError
+        raise ValueError(f"corrupt detangle token: {exc}") from None
+    if not payload:
+        raise ValueError("corrupt detangle token (empty payload)")
+    tag, body = payload[:1], payload[1:]
+    if tag == b"z":
+        try:
+            body = zlib.decompress(body)
+        except zlib.error as exc:
+            raise ValueError(f"corrupt detangle token: {exc}") from None
+    elif tag != b"r":
+        raise ValueError("corrupt detangle token (unknown encoding)")
+    return _read_varints(body)
+
+
+def complexity(values: Sequence[int]) -> tuple[int, int, int]:
+    """Ordering used by the shrinker: fewer deviations, then smaller, then shorter."""
+    nonzero = sum(1 for v in values if v)
+    return (nonzero, sum(min(v, 1 << 20) for v in values), len(strip_trailing_zeros(values)))

detangle/_config.py

@@ -0,0 +1,111 @@
+"""Simulation configuration."""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["NetConfig", "SimConfig"]
+
+
+@dataclass(frozen=True)
+class NetConfig:
+    """Behaviour of the simulated network.
+
+    All durations are in virtual seconds.  Latencies are drawn from
+    ``latency_steps`` evenly spaced values between ``latency[0]`` and
+    ``latency[1]``; the minimum is the default (choice 0).
+    """
+
+    latency: tuple[float, float] = (0.0005, 0.005)
+    latency_steps: int = 4
+    #: Probability that a datagram / mailbox message is lost.
+    drop: float = 0.0
+    #: Probability that a datagram / mailbox message is delivered twice.
+    duplicate: float = 0.0
+    #: Probability that a TCP write is split into several reads on the peer.
+    fragment: float = 0.0
+    #: Maximum number of pieces a fragmented write is split into.
+    max_fragments: int = 3
+    #: Time before a connection attempt to an unreachable host fails.
+    connect_timeout: float = 10.0
+    #: Time a TCP connection survives a partition before being reset.
+    tcp_timeout: float = 30.0
+    #: Retransmission interval while a link is partitioned.
+    retransmit_interval: float = 0.2
+    #: Deep-copy mailbox messages (simulates serialisation, catches aliasing).
+    copy_messages: bool = True
+
+    def __post_init__(self) -> None:
+        lo, hi = self.latency
+        if lo < 0 or hi < lo:
+            raise ValueError(f"invalid latency range {self.latency!r}")
+        for name in ("drop", "duplicate", "fragment"):
+            value = getattr(self, name)
+            if not 0.0 <= value <= 1.0:
+                raise ValueError(f"{name} must be a probability, got {value!r}")
+        if self.latency_steps < 1 or self.max_fragments < 1:
+            raise ValueError("latency_steps and max_fragments must be >= 1")
+
+
+@dataclass(frozen=True)
+class SimConfig:
+    """Knobs controlling what a simulation explores and what counts as a bug."""
+
+    #: Explore reorderings of ready tasks.  ``False`` keeps asyncio's strict
+    #: FIFO order and only explores time/network/fault nondeterminism.
+    reorder: bool = True
+    #: Maximum extra delay (virtual seconds) a timer may fire late.
+    timer_jitter: float = 0.0
+    #: Number of distinct jitter values explored between 0 and ``timer_jitter``.
+    jitter_steps: int = 4
+    #: Virtual time consumed by every step (models CPU time; 0 = infinitely fast).
+    step_cost: float = 0.0
+    #: Abort the run (as a failure) after this many steps.
+    max_steps: int = 200_000
+    #: Abort the run (as a failure) when virtual time exceeds this value.
+    max_time: float | None = None
+    #: Exceptions in background tasks that nobody retrieved are failures.
+    fail_on_unobserved: bool = True
+    #: Exceptions escaping plain callbacks (``loop.call_soon`` & co) are failures.
+    fail_on_callback_error: bool = True
+    #: Tasks still pending when the main coroutine returns are failures.
+    check_leaks: bool = False
+    #: Seed the global :mod:`random` module from the schedule (restored after).
+    seed_random: bool = True
+    #: Patch ``time.time``/``time.monotonic``/``time.perf_counter`` to virtual time.
+    patch_time: bool = False
+    #: Network simulation parameters.
+    net: NetConfig = field(default_factory=NetConfig)
+
+    def __post_init__(self) -> None:
+        if self.timer_jitter < 0 or self.step_cost < 0:
+            raise ValueError("timer_jitter and step_cost must be >= 0")
+        if self.jitter_steps < 2 and self.timer_jitter > 0:
+            raise ValueError("jitter_steps must be >= 2 when timer_jitter > 0")
+        if self.max_steps < 1:
+            raise ValueError("max_steps must be >= 1")
+
+    def replace(self, **changes: Any) -> SimConfig:
+        return dataclasses.replace(self, **changes)
+
+
+_SIM_FIELDS = {f.name for f in dataclasses.fields(SimConfig)}
+_NET_FIELDS = {f.name for f in dataclasses.fields(NetConfig)}
+
+
+def build_config(config: SimConfig | None, options: dict[str, Any]) -> SimConfig:
+    """Merge keyword options (``timer_jitter=...``, ``net=...``) into a config."""
+    base = config or SimConfig()
+    sim_changes: dict[str, Any] = {}
+    for key, value in options.items():
+        if key not in _SIM_FIELDS:
+            raise TypeError(f"unknown simulation option {key!r}")
+        if key == "net" and isinstance(value, dict):
+            bad = set(value) - _NET_FIELDS
+            if bad:
+                raise TypeError(f"unknown network option(s): {', '.join(sorted(bad))}")
+            value = dataclasses.replace(base.net, **value)
+        sim_changes[key] = value
+    return base.replace(**sim_changes) if sim_changes else base

detangle/_context.py

@@ -0,0 +1,14 @@
+"""Context variables shared by the loop and the network simulation."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+#: Simulated host the current task runs on (``None`` = the default host).
+current_host: ContextVar[str | None] = ContextVar("detangle_current_host", default=None)
+
+DEFAULT_HOST = "localhost"
+
+
+def host_name() -> str:
+    return current_host.get() or DEFAULT_HOST