isolab 0.1.0__py3-none-any.whl

isolab/__init__.py

@@ -0,0 +1,2 @@
+"""isolab - a deterministic lab for PostgreSQL transaction-isolation anomalies."""
+__version__ = "0.1.0"

isolab/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

isolab/cli.py

@@ -0,0 +1,147 @@
+"""Command line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import scenarios
+from .engine import normalize, run_cells
+from .model import LEVELS
+from .report import render_json, render_markdown, render_table, render_trace, use_color
+
+DEFAULT_DSN = "postgresql://postgres:postgres@localhost:5433/isolab"
+
+
+def _levels(arg):
+    if not arg:
+        return list(LEVELS)
+    wanted = arg.upper().replace("-", " ").replace("_", " ")
+    short = {"RC": "READ COMMITTED", "RR": "REPEATABLE READ", "SER": "SERIALIZABLE", "SI": "REPEATABLE READ"}
+    wanted = short.get(wanted, wanted)
+    if wanted not in LEVELS:
+        raise SystemExit(f"unknown isolation level {arg!r}; choose from {', '.join(LEVELS)} (or rc/rr/ser)")
+    return [wanted]
+
+
+def _pick(keys):
+    try:
+        return [scenarios.get(k) for k in keys] if keys else list(scenarios.ALL)
+    except KeyError as exc:
+        raise SystemExit(str(exc.args[0]))
+
+
+def cmd_list(args):
+    for s in scenarios.ALL:
+        print(f"{s.key}  -  {s.title}\n    {s.summary}")
+        for v in s.variants:
+            print(f"    - {v.key:<22} {'fix' if v.is_fix else 'bug'}  {v.title}")
+        print()
+
+
+def cmd_explain(args):
+    s = _pick([args.scenario])[0]
+    print(f"{s.title}\n{'=' * len(s.title)}\n{s.summary}\nReference: {s.book_ref}\n")
+    for v in s.variants:
+        print(f"[{v.key}] {v.title}\n  {v.description}")
+        print("  schedule: " + "  ->  ".join(f"{t}.{n}" for t, n in v.schedule))
+        print("  documented: " + ", ".join(f"{k.lower()}={e}" for k, e in v.expected.items()) + "\n")
+
+
+def _execute(args, quiet=False):
+    dsn = args.dsn
+    chosen = _pick(getattr(args, "scenario", None))
+    done = [0]
+
+    def progress(cell):
+        done[0] += 1
+        if not quiet and sys.stderr.isatty():
+            print(f"\r  ran {done[0]} cells...", end="", file=sys.stderr, flush=True)
+
+    try:
+        cells, info = run_cells(dsn, chosen, _levels(getattr(args, "level", None)),
+                                variant_keys=[args.variant] if getattr(args, "variant", None) else None,
+                                repeat=args.repeat, retry=not args.no_retry, progress=progress)
+    except Exception as exc:  # connection problems are the common case
+        raise SystemExit(f"could not run against {dsn!r}: {exc}\n"
+                         f"Start Postgres with `make up` or pass --dsn / set ISOLAB_DSN.")
+    if sys.stderr.isatty() and not quiet:
+        print("\r" + " " * 30 + "\r", end="", file=sys.stderr)
+    if not cells:
+        raise SystemExit("nothing matched those filters")
+    return cells, info
+
+
+def cmd_run(args):
+    cells, info = _execute(args)
+    color = use_color() and not args.output
+    if args.format == "markdown":
+        text = render_markdown(cells, info, args.repeat, not args.no_retry)
+    elif args.format == "json":
+        text = render_json(cells, info)
+    else:
+        text = f"PostgreSQL {info['version']}   (repeat={args.repeat}, retry={'off' if args.no_retry else 'on'})\n\n" \
+               + render_table(cells, color)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+        print(f"wrote {args.output}")
+    else:
+        print(text)
+    if args.trace and args.format == "table":
+        print()
+        for c in cells:
+            if c.skipped:
+                continue
+            outcome = c.dominant
+            print(render_trace(c.sample[outcome],
+                               f"--- {c.scenario.key} / {c.variant.key} @ {c.level} ---", color))
+            print()
+
+
+def cmd_verify(args):
+    args.no_retry = args.no_retry
+    cells, info = _execute(args, quiet=True)
+    bad = [c for c in cells if not c.skipped and not c.matches]
+    skipped = [c for c in cells if c.skipped]
+    print(f"PostgreSQL {info['version']}: {len(cells) - len(skipped)} cells checked, "
+          f"{len(skipped)} skipped, {len(bad)} mismatched")
+    for c in bad:
+        got = ", ".join(f"{k}×{n}" for k, n in c.outcomes.items())
+        print(f"  MISMATCH {c.scenario.key}/{c.variant.key} @ {c.level}: "
+              f"expected {c.expected}, got {got}")
+    return 1 if bad else 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="isolab", description="Deterministic PostgreSQL isolation-anomaly lab.")
+    p.add_argument("--dsn", default=os.environ.get("ISOLAB_DSN", DEFAULT_DSN),
+                   help="libpq connection string (default: $ISOLAB_DSN or %(default)s)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list", help="list scenarios and variants").set_defaults(fn=cmd_list)
+    e = sub.add_parser("explain", help="show a scenario's story, schedules and documented results")
+    e.add_argument("scenario")
+    e.set_defaults(fn=cmd_explain)
+
+    def common(sp):
+        sp.add_argument("scenario", nargs="*", help="scenario keys (default: all)")
+        sp.add_argument("--variant", help="only this variant (e.g. naive, for_update)")
+        sp.add_argument("--level", help="only this isolation level (rc | rr | ser or full name)")
+        sp.add_argument("--repeat", type=int, default=1, help="run every cell N times to prove determinism")
+        sp.add_argument("--no-retry", action="store_true",
+                        help="do not retry aborted transactions (report them as ABORTED)")
+
+    r = sub.add_parser("run", help="run scenarios and print the anomaly matrix")
+    common(r)
+    r.add_argument("--format", choices=["table", "markdown", "json"], default="table")
+    r.add_argument("--output", "-o", help="write the report to a file")
+    r.add_argument("--trace", action="store_true", help="print the step-by-step timeline of each cell")
+    r.set_defaults(fn=cmd_run)
+
+    v = sub.add_parser("verify", help="exit 1 if any result differs from the documented expectation")
+    common(v)
+    v.set_defaults(fn=cmd_verify)
+
+    args = p.parse_args(argv)
+    return args.fn(args) or 0

isolab/engine.py

@@ -0,0 +1,417 @@
+"""Execution engine: a deterministic scheduler over real PostgreSQL connections.
+
+Every transaction in a variant gets its own connection and worker thread.  The
+scheduler releases *one step at a time* in the order given by the variant's
+schedule.  If a step blocks on a lock (detected through pg_stat_activity, not a
+sleep), the scheduler moves on to the next step; the blocked step completes
+later, when the lock holder commits.  After every step the scheduler waits for
+the system to "settle" (every worker idle or lock-blocked) so the interleaving
+is identical on every run.
+"""
+from __future__ import annotations
+
+import queue
+import threading
+import time
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+import psycopg
+from psycopg import errors as pgerr
+
+from .model import ABORTED, AppConflict, LEVELS, Scenario, Variant
+
+SCHEMA = "isolab"
+CONN_OPTIONS = f"-c search_path={SCHEMA},public"
+
+
+class EngineError(RuntimeError):
+    """The harness itself failed (timeout, stuck worker, ...)."""
+
+
+# --------------------------------------------------------------------------- errors
+
+def classify(exc: BaseException) -> tuple[str, bool]:
+    """Map an exception to (kind, retryable)."""
+    table = (
+        (pgerr.SerializationFailure, "serialization_failure"),
+        (pgerr.DeadlockDetected, "deadlock"),
+        (pgerr.UniqueViolation, "unique_violation"),
+        (pgerr.ExclusionViolation, "exclusion_violation"),
+        (pgerr.CheckViolation, "check_violation"),
+        (AppConflict, "app_conflict"),
+    )
+    for cls, kind in table:
+        if isinstance(exc, cls):
+            return kind, True
+    return "error", False
+
+
+# --------------------------------------------------------------------------- session
+
+def _inline(sql: str, params: tuple) -> str:
+    out = " ".join(sql.split())
+    for p in params:
+        out = out.replace("%s", f"'{p}'" if isinstance(p, str) else str(p), 1)
+    return out
+
+
+class Session:
+    """What scenario steps talk to: a connection plus a per-transaction ctx dict."""
+
+    def __init__(self, conn, log: Optional[Callable[[str], None]] = None, ctx: Optional[dict] = None):
+        self.conn = conn
+        self.ctx = ctx if ctx is not None else {}
+        self._log = log or (lambda line: None)
+
+    def raw(self, sql: str) -> None:
+        self._log(sql)
+        self.conn.execute(sql)
+
+    def _go(self, sql: str, params: tuple):
+        try:
+            return self.conn.execute(sql, params or None)
+        except Exception as exc:
+            self._log(f"{_inline(sql, params)}  ->  ERROR")
+            raise exc
+
+    def rows(self, sql: str, *params) -> list:
+        data = self._go(sql, params).fetchall()
+        self._log(f"{_inline(sql, params)}  ->  {data}")
+        return data
+
+    def scalar(self, sql: str, *params):
+        return self.rows(sql, *params)[0][0]
+
+    def run(self, sql: str, *params) -> int:
+        n = self._go(sql, params).rowcount
+        self._log(f"{_inline(sql, params)}  ->  {n} row(s)")
+        return n
+
+
+# --------------------------------------------------------------------------- trace
+
+@dataclass
+class Event:
+    seq: int
+    txn: str
+    step: str
+    status: str            # ok | blocked | error | skipped
+    lines: list
+    note: str = ""
+    ts: float = 0.0        # ordering key; COMMIT events use the moment COMMIT was *sent*
+
+
+class Trace:
+    def __init__(self):
+        self.events: list[Event] = []
+        self._lock = threading.Lock()
+
+    def add(self, txn, step, status, lines=(), note="", ts=None):
+        with self._lock:
+            self.events.append(Event(len(self.events) + 1, txn, step, status, list(lines), note,
+                                     time.monotonic() if ts is None else ts))
+
+    def ordered(self) -> list:
+        """Events in causal order.  A COMMIT releases locks on the server *before* its
+        client sees the reply, so a transaction it unblocks can finish first; stamping
+        commits at send time keeps the timeline readable."""
+        return sorted(self.events, key=lambda e: (e.ts, e.seq))
+
+
+@dataclass
+class TxnResult:
+    label: str
+    ctx: dict = field(default_factory=dict)
+    committed: bool = False
+    first_error: Optional[str] = None        # kind of the first failure, if any
+    first_detail: str = ""
+    first_retryable: bool = False
+    attempts: int = 1
+
+
+def connect(dsn: str):
+    return psycopg.connect(dsn, autocommit=True, options=CONN_OPTIONS)
+
+
+def _waiting_on_lock(obs, pid: int) -> bool:
+    row = obs.execute("SELECT wait_event_type FROM pg_stat_activity WHERE pid = %s", (pid,)).fetchone()
+    return bool(row) and row[0] == "Lock"
+
+
+# --------------------------------------------------------------------------- worker
+
+class Worker(threading.Thread):
+    def __init__(self, label: str, steps: list, dsn: str, level: str, trace: Trace):
+        super().__init__(daemon=True, name=f"txn-{label}")
+        if level not in LEVELS:
+            raise ValueError(level)
+        self.label, self.level, self.trace = label, level, trace
+        self.steps = {s.name: s for s in steps}
+        self.conn = connect(dsn)
+        self.pid = self.conn.info.backend_pid
+        self.result = TxnResult(label)
+        self.q: queue.Queue = queue.Queue()
+        self._pending = 0
+        self._lock = threading.Lock()
+        self._begun = False
+        self._failed = False
+
+    def submit(self, step_name: str) -> threading.Event:
+        done = threading.Event()
+        with self._lock:
+            self._pending += 1
+        self.q.put((step_name, done))
+        return done
+
+    def idle(self) -> bool:
+        with self._lock:
+            return self._pending == 0
+
+    def run(self):
+        while True:
+            item = self.q.get()
+            if item is None:
+                return
+            name, done = item
+            try:
+                self._exec(name)
+            finally:
+                with self._lock:
+                    self._pending -= 1
+                done.set()
+
+    def _exec(self, name: str):
+        if self._failed:
+            self.trace.add(self.label, name, "skipped", note="transaction already aborted")
+            return
+        lines: list = []
+        started = time.monotonic()
+        stamp = started if name == "commit" else None
+        s = Session(self.conn, lines.append, self.result.ctx)
+        try:
+            if not self._begun:
+                s.raw(f"BEGIN ISOLATION LEVEL {self.level}")
+                self._begun = True
+            if name == "commit":
+                s.raw("COMMIT")
+                self.result.committed = True
+            else:
+                self.steps[name].fn(s)
+            self.trace.add(self.label, name, "ok", lines, ts=stamp)
+        except Exception as exc:  # noqa: BLE001 - we classify everything
+            kind, retryable = classify(exc)
+            self._failed = True
+            r = self.result
+            r.first_error, r.first_retryable = kind, retryable
+            r.first_detail = (str(exc).strip().splitlines() or [repr(exc)])[0]
+            try:
+                self.conn.execute("ROLLBACK")
+            except Exception:  # noqa: BLE001
+                pass
+            self.trace.add(self.label, name, "error", lines, f"{kind}: {r.first_detail}", ts=stamp)
+
+
+# --------------------------------------------------------------------------- scheduling
+
+def _run_schedule(workers: dict, schedule: list, obs, trace: Trace, timeout: float) -> None:
+    def blocked(w: Worker) -> bool:
+        return _waiting_on_lock(obs, w.pid)
+
+    def settle():
+        deadline = time.monotonic() + timeout
+        while True:
+            if all(w.idle() or blocked(w) for w in workers.values()):
+                return
+            if time.monotonic() > deadline:
+                raise EngineError("workers never settled (stuck outside a lock wait?)")
+            time.sleep(0.002)
+
+    for label, name in schedule:
+        w = workers[label]
+        done = w.submit(name)
+        deadline = time.monotonic() + timeout
+        while not done.wait(0.004):
+            if blocked(w):
+                trace.add(label, name, "blocked", note=f"txn {label} is waiting on a lock; schedule continues")
+                break
+            if time.monotonic() > deadline:
+                raise EngineError(f"step {label}.{name} timed out")
+        settle()
+
+
+def _drain(workers: dict, timeout: float) -> None:
+    for w in workers.values():
+        w.q.put(None)
+    deadline = time.monotonic() + timeout
+    for w in workers.values():
+        w.join(max(0.1, deadline - time.monotonic()))
+        if w.is_alive():
+            raise EngineError(f"txn {w.label} never finished (deadlock the server did not detect?)")
+
+
+def _retry(dsn: str, variant: Variant, results: dict, level: str, trace: Trace, max_attempts: int) -> None:
+    """Re-run aborted transactions the way a well-behaved application would:
+    from the top, in a fresh transaction, one after another."""
+    for label, res in results.items():
+        if res.committed or not res.first_retryable:
+            continue
+        for attempt in range(2, max_attempts + 1):
+            conn = connect(dsn)
+            res.attempts, res.ctx = attempt, {}
+            lines: list = []
+            s = Session(conn, lines.append, res.ctx)
+            try:
+                s.raw(f"BEGIN ISOLATION LEVEL {level}")
+                for st in variant.txns[label]:
+                    st.fn(s)
+                s.raw("COMMIT")
+                res.committed = True
+                trace.add(f"{label}-retry", f"attempt {attempt}", "ok", lines)
+                break
+            except Exception as exc:  # noqa: BLE001
+                kind, retryable = classify(exc)
+                try:
+                    conn.execute("ROLLBACK")
+                except Exception:  # noqa: BLE001
+                    pass
+                trace.add(f"{label}-retry", f"attempt {attempt}", "error", lines, kind)
+                if not retryable:
+                    break
+            finally:
+                conn.close()
+
+
+# --------------------------------------------------------------------------- cells
+
+@dataclass
+class CellResult:
+    outcome: str                      # SAFE | ABORTED | RETRIED | ANOMALY | ERROR
+    violations: list
+    txns: dict
+    trace: Trace
+    duration: float
+    error: str = ""
+
+
+def normalize(outcome: str) -> str:
+    """RETRIED (aborted, then retried successfully) counts as ABORTED for expectations."""
+    return ABORTED if outcome == "RETRIED" else outcome
+
+
+def _outcome(violations: list, results: dict) -> str:
+    if violations:
+        return "ANOMALY"
+    failed = [r for r in results.values() if r.first_error]
+    if any(not r.first_retryable for r in failed):
+        return "ERROR"
+    if not failed:
+        return "SAFE"
+    return "RETRIED" if all(r.committed for r in failed) else "ABORTED"
+
+
+def reset_schema(obs, scenario: Scenario, variant: Variant) -> None:
+    obs.execute(f"DROP SCHEMA IF EXISTS {SCHEMA} CASCADE")
+    obs.execute(f"CREATE SCHEMA {SCHEMA}")
+    for stmt in [*scenario.setup, *variant.setup]:
+        obs.execute(stmt)
+
+
+def run_cell(dsn: str, scenario: Scenario, variant: Variant, level: str, *,
+             retry: bool = True, timeout: float = 10.0, max_attempts: int = 3) -> CellResult:
+    t0 = time.monotonic()
+    trace = Trace()
+    obs = connect(dsn)
+    workers: dict = {}
+    try:
+        reset_schema(obs, scenario, variant)
+        workers = {lbl: Worker(lbl, steps, dsn, level, trace) for lbl, steps in variant.txns.items()}
+        for w in workers.values():
+            w.start()
+        _run_schedule(workers, variant.schedule, obs, trace, timeout)
+        _drain(workers, timeout)
+        results = {lbl: w.result for lbl, w in workers.items()}
+        if retry:
+            _retry(dsn, variant, results, level, trace, max_attempts)
+        violations = scenario.invariant(Session(obs), results)
+        return CellResult(_outcome(violations, results), violations, results, trace,
+                          time.monotonic() - t0)
+    except EngineError as exc:
+        return CellResult("ERROR", [], {l: w.result for l, w in workers.items()}, trace,
+                          time.monotonic() - t0, error=str(exc))
+    finally:
+        for w in workers.values():
+            try:
+                w.conn.cancel()
+            except Exception:  # noqa: BLE001
+                pass
+            w.join(1)
+            try:
+                w.conn.close()
+            except Exception:  # noqa: BLE001
+                pass
+        obs.close()
+
+
+@dataclass
+class Cell:
+    scenario: Scenario
+    variant: Variant
+    level: str
+    outcomes: Counter = field(default_factory=Counter)
+    sample: dict = field(default_factory=dict)      # outcome -> first CellResult with that outcome
+    skipped: str = ""
+
+    @property
+    def dominant(self) -> str:
+        return self.outcomes.most_common(1)[0][0] if self.outcomes else "SKIPPED"
+
+    @property
+    def deterministic(self) -> bool:
+        return len(self.outcomes) <= 1
+
+    @property
+    def expected(self) -> str:
+        return self.variant.expected[self.level]
+
+    @property
+    def matches(self) -> bool:
+        return (not self.skipped and self.deterministic
+                and normalize(self.dominant) == self.expected)
+
+
+def preflight(dsn: str) -> dict:
+    with psycopg.connect(dsn, autocommit=True) as c:
+        version = c.execute("SHOW server_version").fetchone()[0]
+        extensions = set()
+        try:
+            c.execute("CREATE EXTENSION IF NOT EXISTS btree_gist")
+            extensions.add("btree_gist")
+        except Exception:  # noqa: BLE001
+            pass
+    return {"version": version, "extensions": extensions}
+
+
+def run_cells(dsn: str, scenarios: list, levels: list, *, variant_keys: Optional[list] = None,
+              repeat: int = 1, retry: bool = True, progress: Optional[Callable] = None) -> tuple[list, dict]:
+    info = preflight(dsn)
+    cells: list = []
+    for sc in scenarios:
+        for v in sc.variants:
+            if variant_keys and v.key not in variant_keys:
+                continue
+            for lvl in levels:
+                cell = Cell(sc, v, lvl)
+                missing = [e for e in v.requires if e not in info["extensions"]]
+                if missing:
+                    cell.skipped = f"needs extension {', '.join(missing)}"
+                else:
+                    for _ in range(repeat):
+                        res = run_cell(dsn, sc, v, lvl, retry=retry)
+                        cell.outcomes[res.outcome] += 1
+                        cell.sample.setdefault(res.outcome, res)
+                cells.append(cell)
+                if progress:
+                    progress(cell)
+    return cells, info

isolab/model.py

@@ -0,0 +1,89 @@
+"""Data model: scenarios, variants and steps.
+
+A *Scenario* is a business rule that can be broken by concurrency
+("a doctor must always be on call").  Each scenario has one or more
+*Variants*: the naive implementation plus the fixes that work (or
+deliberately don't).  A variant is a set of transactions, each a list of
+named *Steps*, and a *schedule* that fixes the exact interleaving.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+LEVELS = ("READ COMMITTED", "REPEATABLE READ", "SERIALIZABLE")
+
+# Vocabulary used for documented expectations.
+ANOMALY = "ANOMALY"    # the invariant was violated
+ABORTED = "ABORTED"    # the database/app rejected a transaction; invariant holds
+SAFE = "SAFE"          # nothing was rejected and the invariant holds
+EXPECTATIONS = (ANOMALY, ABORTED, SAFE)
+
+
+class AppConflict(Exception):
+    """Raised by application-level optimistic checks (e.g. a version column
+    mismatch).  Treated like a retryable serialization failure."""
+
+
+@dataclass(frozen=True)
+class Step:
+    name: str
+    fn: Callable  # fn(session) -> None; see engine.Session
+
+
+@dataclass
+class Variant:
+    key: str
+    title: str
+    description: str
+    txns: dict           # label -> list[Step]
+    schedule: list       # [(label, step_name | "commit"), ...]
+    expected: dict       # level -> ANOMALY | ABORTED | SAFE
+    setup: list = field(default_factory=list)   # extra DDL/DML after the scenario setup
+    is_fix: bool = True
+    requires: tuple = ()                        # PostgreSQL extensions needed
+
+    def validate(self, scenario_key: str) -> None:
+        where = f"{scenario_key}/{self.key}"
+        if set(self.expected) != set(LEVELS):
+            raise ValueError(f"{where}: expected must cover exactly {LEVELS}")
+        for lvl, exp in self.expected.items():
+            if exp not in EXPECTATIONS:
+                raise ValueError(f"{where}: bad expectation {exp!r} for {lvl}")
+        per_txn: dict = {label: [] for label in self.txns}
+        for label, step in self.schedule:
+            if label not in self.txns:
+                raise ValueError(f"{where}: schedule references unknown txn {label!r}")
+            names = {s.name for s in self.txns[label]}
+            if step != "commit" and step not in names:
+                raise ValueError(f"{where}: txn {label} has no step {step!r}")
+            per_txn[label].append(step)
+        for label, steps in self.txns.items():
+            declared = [s.name for s in steps] + ["commit"]
+            if per_txn[label] != declared:
+                raise ValueError(
+                    f"{where}: schedule for txn {label} is {per_txn[label]} "
+                    f"but its steps are {declared} (each step once, in order, then commit)"
+                )
+
+
+@dataclass
+class Scenario:
+    key: str
+    title: str
+    summary: str
+    book_ref: str
+    setup: list          # SQL run once per cell, in a fresh schema
+    invariant: Callable  # invariant(db: Session, txns: dict[str, TxnResult]) -> list[str]
+    variants: list
+
+    def __post_init__(self):
+        for v in self.variants:
+            v.validate(self.key)
+
+    def variant(self, key: str) -> Variant:
+        for v in self.variants:
+            if v.key == key:
+                return v
+        raise KeyError(f"{self.key} has no variant {key!r} "
+                       f"(choose from {[v.key for v in self.variants]})")