gapwatch 0.1.0__tar.gz

gapwatch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      GAPWATCH_TEST_DSN: postgresql://postgres:postgres@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: pytest -q

gapwatch-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

gapwatch-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.json
+!package.json

gapwatch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for helping. Bug reports, new sources and better fault types are all welcome.
+
+## Setup
+
+```bash
+git clone https://github.com/Dakokodaripon/gapwatch
+cd gapwatch
+pip install -e ".[dev]"
+```
+
+The checker tests run without a database. The Postgres tests need a database you can create tables in:
+
+```bash
+export GAPWATCH_TEST_DSN="postgresql://postgres:postgres@localhost:5432/postgres"
+pytest -q
+```
+
+Before opening a pull request:
+
+```bash
+ruff check .
+ruff format .
+pytest -q
+```
+
+## Adding a source
+
+A source writes numbered changes and listens for them the way a real app would. Look at `src/gapwatch/listen_notify.py`: it returns what was sent, what was received, and when the listener was disconnected. `checker.py` does the rest. Please open an issue first so we can agree on the shape before you build it.
+
+## Reporting results
+
+If you run gapwatch against a service and get surprising numbers, open an issue with the command you ran, the JSON report and the versions involved. Please leave out connection strings and anything secret. I'll review it as soon as I can.

gapwatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Akokodaripon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gapwatch-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: gapwatch
+Version: 0.1.0
+Summary: Crash-test how database changes reach your app: find the changes it silently misses.
+Project-URL: Repository, https://github.com/Dakokodaripon/gapwatch
+Project-URL: Issues, https://github.com/Dakokodaripon/gapwatch/issues
+Author: David Akokodaripon
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cdc,fault-injection,listen-notify,postgres,realtime,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: psycopg[binary]>=3.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gapwatch
+
+**Crash-test how database changes reach your app.**
+
+Live dashboards, chat, order tracking and notifications all depend on database changes reaching the app. When a connection drops or a server restarts, some of those changes can disappear without any error. Nobody notices until a user says "my screen didn't update."
+
+gapwatch measures it. It writes numbered changes to your database, listens the way your app does, cuts the connection on purpose, and tells you exactly what never arrived.
+
+```
+$ gapwatch run --dsn postgresql://localhost/postgres
+
+gapwatch 0.1.0 · source: postgres LISTEN/NOTIFY
+
+Wrote 5,000 changes and cut the listener's connection 3 time(s) (run took 12.1s)
+
+  Delivered     3,492 (69.84%)
+  Missing       1,508
+  Duplicated    0
+  Out of order  0
+
+  Disconnect #1:  2.64s →  3.65s (1.01s offline), 502 changes missed
+  Disconnect #2:  4.53s →  5.53s (1.01s offline), 503 changes missed
+  Disconnect #3:  7.28s →  8.28s (1.01s offline), 503 changes missed
+
+  Missing changes: 1317–1818, 2259–2761, 3634–4136
+
+Result: your app would have silently missed these changes.
+```
+
+That's a real run against Postgres 16, with a listener that waits one second before reconnecting, like many apps do.
+
+**Reconnecting faster doesn't fix it.** With `--reconnect-delay 0`, the listener was back within about 10 milliseconds each time, and it still lost 3 changes per disconnect (9 of 5,000). Without any faults, all 5,000 arrived. The changes are lost in the gap itself, however short it is.
+
+## Quick start
+
+```bash
+pip install gapwatch    # or, until the first release: pip install git+https://github.com/Dakokodaripon/gapwatch
+gapwatch run --dsn "postgresql://user:password@host:5432/dbname"
+gapwatch cleanup --dsn "..."
+```
+
+You can also set `GAPWATCH_DSN` instead of passing `--dsn`.
+
+**Use a test or staging database.** gapwatch creates a table called `gapwatch_events` and a trigger. `gapwatch cleanup` removes both.
+
+## Running against Supabase
+
+gapwatch works with a Supabase database, since it's Postgres underneath. This tests Postgres LISTEN/NOTIFY on your Supabase database. Support for Supabase Realtime itself is on the roadmap.
+
+1. In your Supabase project, open **Connect** and copy the **Direct connection** string (or the **Session pooler** one if your network has no IPv6).
+2. Run:
+
+```bash
+gapwatch run --dsn "postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT_REF.supabase.co:5432/postgres"
+gapwatch cleanup --dsn "..."
+```
+
+Don't use the **Transaction pooler** (port 6543). It doesn't support LISTEN, so the listener can't subscribe.
+
+Use a test or development project, not production.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `--count` | 5000 | How many changes to write |
+| `--rate` | 500 | Changes per second (0 means as fast as possible) |
+| `--faults` | 3 | How many times to cut the listener's connection |
+| `--reconnect-delay` | 1.0 | Seconds the listener waits before reconnecting |
+| `--drain` | 2.0 | Seconds to wait for late changes before counting |
+| `--seed` | none | Makes the timing of faults repeatable |
+| `--json PATH` | none | Also write the report as JSON |
+| `--fail-on-loss` | off | Exit with code 1 if anything was lost, for use in CI |
+
+## How it works
+
+1. A trigger sends a notification for every row gapwatch inserts, each carrying a sequence number.
+2. A listener subscribes the way a typical app does. If its connection drops, it waits, reconnects and subscribes again.
+3. While changes are being written, gapwatch ends the listener's connection with `pg_terminate_backend`, the same thing that happens when a server restarts or a connection is killed.
+4. The checker compares what was sent with what arrived, and works out which disconnect each missing change belongs to.
+
+In systems engineering terms, it's fault-injection testing for realtime data delivery: it measures loss, duplication and ordering under degraded connectivity.
+
+## Is this a Postgres bug?
+
+No. Postgres documents that notifications are only delivered to sessions that are listening at the time. gapwatch makes that behaviour visible and measurable, so you can decide whether your app needs a way to catch up, such as re-reading recent rows after reconnecting.
+
+## Roadmap
+
+Version 0.1 tests Postgres `LISTEN/NOTIFY`. Next:
+
+- Supabase Realtime
+- Debezium and Kafka
+- Logical replication consumers
+- Network faults (latency, packet loss) as well as connection kills
+- A catch-up mode, to measure whether a recovery strategy actually closes the gap
+
+Ideas and results from your own setup are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

gapwatch-0.1.0/README.md

@@ -0,0 +1,102 @@
+# gapwatch
+
+**Crash-test how database changes reach your app.**
+
+Live dashboards, chat, order tracking and notifications all depend on database changes reaching the app. When a connection drops or a server restarts, some of those changes can disappear without any error. Nobody notices until a user says "my screen didn't update."
+
+gapwatch measures it. It writes numbered changes to your database, listens the way your app does, cuts the connection on purpose, and tells you exactly what never arrived.
+
+```
+$ gapwatch run --dsn postgresql://localhost/postgres
+
+gapwatch 0.1.0 · source: postgres LISTEN/NOTIFY
+
+Wrote 5,000 changes and cut the listener's connection 3 time(s) (run took 12.1s)
+
+  Delivered     3,492 (69.84%)
+  Missing       1,508
+  Duplicated    0
+  Out of order  0
+
+  Disconnect #1:  2.64s →  3.65s (1.01s offline), 502 changes missed
+  Disconnect #2:  4.53s →  5.53s (1.01s offline), 503 changes missed
+  Disconnect #3:  7.28s →  8.28s (1.01s offline), 503 changes missed
+
+  Missing changes: 1317–1818, 2259–2761, 3634–4136
+
+Result: your app would have silently missed these changes.
+```
+
+That's a real run against Postgres 16, with a listener that waits one second before reconnecting, like many apps do.
+
+**Reconnecting faster doesn't fix it.** With `--reconnect-delay 0`, the listener was back within about 10 milliseconds each time, and it still lost 3 changes per disconnect (9 of 5,000). Without any faults, all 5,000 arrived. The changes are lost in the gap itself, however short it is.
+
+## Quick start
+
+```bash
+pip install gapwatch    # or, until the first release: pip install git+https://github.com/Dakokodaripon/gapwatch
+gapwatch run --dsn "postgresql://user:password@host:5432/dbname"
+gapwatch cleanup --dsn "..."
+```
+
+You can also set `GAPWATCH_DSN` instead of passing `--dsn`.
+
+**Use a test or staging database.** gapwatch creates a table called `gapwatch_events` and a trigger. `gapwatch cleanup` removes both.
+
+## Running against Supabase
+
+gapwatch works with a Supabase database, since it's Postgres underneath. This tests Postgres LISTEN/NOTIFY on your Supabase database. Support for Supabase Realtime itself is on the roadmap.
+
+1. In your Supabase project, open **Connect** and copy the **Direct connection** string (or the **Session pooler** one if your network has no IPv6).
+2. Run:
+
+```bash
+gapwatch run --dsn "postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT_REF.supabase.co:5432/postgres"
+gapwatch cleanup --dsn "..."
+```
+
+Don't use the **Transaction pooler** (port 6543). It doesn't support LISTEN, so the listener can't subscribe.
+
+Use a test or development project, not production.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `--count` | 5000 | How many changes to write |
+| `--rate` | 500 | Changes per second (0 means as fast as possible) |
+| `--faults` | 3 | How many times to cut the listener's connection |
+| `--reconnect-delay` | 1.0 | Seconds the listener waits before reconnecting |
+| `--drain` | 2.0 | Seconds to wait for late changes before counting |
+| `--seed` | none | Makes the timing of faults repeatable |
+| `--json PATH` | none | Also write the report as JSON |
+| `--fail-on-loss` | off | Exit with code 1 if anything was lost, for use in CI |
+
+## How it works
+
+1. A trigger sends a notification for every row gapwatch inserts, each carrying a sequence number.
+2. A listener subscribes the way a typical app does. If its connection drops, it waits, reconnects and subscribes again.
+3. While changes are being written, gapwatch ends the listener's connection with `pg_terminate_backend`, the same thing that happens when a server restarts or a connection is killed.
+4. The checker compares what was sent with what arrived, and works out which disconnect each missing change belongs to.
+
+In systems engineering terms, it's fault-injection testing for realtime data delivery: it measures loss, duplication and ordering under degraded connectivity.
+
+## Is this a Postgres bug?
+
+No. Postgres documents that notifications are only delivered to sessions that are listening at the time. gapwatch makes that behaviour visible and measurable, so you can decide whether your app needs a way to catch up, such as re-reading recent rows after reconnecting.
+
+## Roadmap
+
+Version 0.1 tests Postgres `LISTEN/NOTIFY`. Next:
+
+- Supabase Realtime
+- Debezium and Kafka
+- Logical replication consumers
+- Network faults (latency, packet loss) as well as connection kills
+- A catch-up mode, to measure whether a recovery strategy actually closes the gap
+
+Ideas and results from your own setup are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

gapwatch-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gapwatch"
+version = "0.1.0"
+description = "Crash-test how database changes reach your app: find the changes it silently misses."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "David Akokodaripon" }]
+keywords = ["postgres", "realtime", "cdc", "listen-notify", "fault-injection", "testing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = ["psycopg[binary]>=3.2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+gapwatch = "gapwatch.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Dakokodaripon/gapwatch"
+Issues = "https://github.com/Dakokodaripon/gapwatch/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gapwatch"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["gapwatch"]

gapwatch-0.1.0/src/gapwatch/__init__.py

@@ -0,0 +1,3 @@
+"""gapwatch: crash-test how database changes reach your app."""
+
+__version__ = "0.1.0"

gapwatch-0.1.0/src/gapwatch/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from gapwatch.cli import main
+
+sys.exit(main())

gapwatch-0.1.0/src/gapwatch/checker.py

@@ -0,0 +1,133 @@
+"""Compare what was written with what was received.
+
+Everything in this module is pure: no database, no clock, no threads.
+That keeps the part that decides "was anything lost?" easy to test.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Window:
+    """A period when the listener was disconnected, in seconds since the run started."""
+
+    start: float
+    end: float
+
+    def contains(self, t: float) -> bool:
+        return self.start <= t <= self.end
+
+
+@dataclass
+class Report:
+    sent: int
+    received: int
+    missing: list[int]
+    duplicates: dict[int, int]
+    out_of_order: int
+    missing_ranges: list[tuple[int, int]]
+    missing_by_window: list[int] = field(default_factory=list)
+    missing_outside_windows: int = 0
+
+    @property
+    def delivered(self) -> int:
+        return self.sent - len(self.missing)
+
+    @property
+    def delivery_rate(self) -> float:
+        return 1.0 if self.sent == 0 else self.delivered / self.sent
+
+    @property
+    def ok(self) -> bool:
+        return not self.missing and not self.duplicates and self.out_of_order == 0
+
+    def to_dict(self) -> dict:
+        return {
+            "sent": self.sent,
+            "received": self.received,
+            "delivered": self.delivered,
+            "delivery_rate": round(self.delivery_rate, 6),
+            "missing": len(self.missing),
+            "missing_ranges": [list(r) for r in self.missing_ranges],
+            "duplicates": sum(c - 1 for c in self.duplicates.values()),
+            "out_of_order": self.out_of_order,
+            "missing_by_window": self.missing_by_window,
+            "missing_outside_windows": self.missing_outside_windows,
+            "ok": self.ok,
+        }
+
+
+def _ranges(sorted_values: list[int]) -> list[tuple[int, int]]:
+    """Collapse sorted integers into inclusive (first, last) runs."""
+    ranges: list[tuple[int, int]] = []
+    for value in sorted_values:
+        if ranges and value == ranges[-1][1] + 1:
+            ranges[-1] = (ranges[-1][0], value)
+        else:
+            ranges.append((value, value))
+    return ranges
+
+
+def check(
+    sent: list[int],
+    received: list[int],
+    sent_at: dict[int, float] | None = None,
+    windows: list[Window] | None = None,
+) -> Report:
+    """Compare sent sequence numbers with the order they were received in.
+
+    - missing: sent but never received
+    - duplicates: received more than once (value -> times received)
+    - out_of_order: first deliveries that arrived after a higher number had
+      already been seen
+    - missing_by_window: if send times and disconnect windows are given, how
+      many missing changes were sent during each window
+    """
+    sent_set = set(sent)
+    counts: dict[int, int] = {}
+    out_of_order = 0
+    highest = None
+
+    for seq in received:
+        if seq not in sent_set:
+            # Not ours (or from an older run); ignore rather than miscount.
+            continue
+        counts[seq] = counts.get(seq, 0) + 1
+        if counts[seq] > 1:
+            continue
+        if highest is not None and seq < highest:
+            out_of_order += 1
+        highest = seq if highest is None else max(highest, seq)
+
+    missing = sorted(sent_set - counts.keys())
+    duplicates = {seq: n for seq, n in counts.items() if n > 1}
+
+    report = Report(
+        sent=len(sent_set),
+        received=len(received),
+        missing=missing,
+        duplicates=duplicates,
+        out_of_order=out_of_order,
+        missing_ranges=_ranges(missing),
+    )
+
+    if windows:
+        by_window = [0] * len(windows)
+        outside = 0
+        for seq in missing:
+            t = (sent_at or {}).get(seq)
+            hit = (
+                None
+                if t is None
+                else next((i for i, w in enumerate(windows) if w.contains(t)), None)
+            )
+            if hit is None:
+                outside += 1
+            else:
+                by_window[hit] += 1
+        report.missing_by_window = by_window
+        report.missing_outside_windows = outside
+
+    return report

gapwatch-0.1.0/src/gapwatch/cli.py

@@ -0,0 +1,148 @@
+"""Command line interface: `gapwatch run` and `gapwatch cleanup`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from gapwatch import __version__
+from gapwatch.checker import Report, check
+from gapwatch.listen_notify import RunConfig, RunResult, cleanup, run
+
+
+def _format(report: Report, result: RunResult, config: RunConfig) -> str:
+    lines = [
+        f"gapwatch {__version__} · source: postgres LISTEN/NOTIFY",
+        "",
+        f"Wrote {report.sent:,} changes and cut the listener's connection "
+        f"{len(result.windows)} time(s) (run took {result.duration:.1f}s)",
+        "",
+        f"  Delivered     {report.delivered:,} ({report.delivery_rate:.2%})",
+        f"  Missing       {len(report.missing):,}",
+        f"  Duplicated    {sum(c - 1 for c in report.duplicates.values()):,}",
+        f"  Out of order  {report.out_of_order:,}",
+    ]
+    if result.windows:
+        lines.append("")
+        for i, (window, lost) in enumerate(
+            zip(result.windows, report.missing_by_window, strict=True), start=1
+        ):
+            lines.append(
+                f"  Disconnect #{i}: {window.start:5.2f}s → {window.end:5.2f}s "
+                f"({window.end - window.start:.2f}s offline), {lost:,} changes missed"
+            )
+        if report.missing_outside_windows:
+            lines.append(f"  Missed outside any disconnect: {report.missing_outside_windows:,}")
+    if report.missing_ranges:
+        shown = ", ".join(f"{a}" if a == b else f"{a}–{b}" for a, b in report.missing_ranges[:5])
+        more = len(report.missing_ranges) - 5
+        lines.append("")
+        suffix = f" (+{more} more ranges)" if more > 0 else ""
+        lines.append(f"  Missing changes: {shown}{suffix}")
+    lines.append("")
+    lines.append(
+        "Result: no changes lost."
+        if report.ok
+        else "Result: your app would have silently missed these changes."
+    )
+    return "\n".join(lines)
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    config = RunConfig(
+        dsn=args.dsn,
+        count=args.count,
+        rate=args.rate,
+        faults=args.faults,
+        reconnect_delay=args.reconnect_delay,
+        drain=args.drain,
+        seed=args.seed,
+    )
+    result = run(config)
+    report = check(result.sent, result.received, result.sent_at, result.windows)
+    print(_format(report, result, config))
+
+    if args.json:
+        data = report.to_dict()
+        data.update(
+            run_id=result.run_id,
+            source="listen_notify",
+            duration_s=round(result.duration, 3),
+            disconnects=[
+                {"start_s": round(w.start, 3), "end_s": round(w.end, 3)} for w in result.windows
+            ],
+            config={
+                "count": config.count,
+                "rate": config.rate,
+                "faults": config.faults,
+                "reconnect_delay": config.reconnect_delay,
+            },
+        )
+        with open(args.json, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    return 1 if args.fail_on_loss and not report.ok else 0
+
+
+def _cmd_cleanup(args: argparse.Namespace) -> int:
+    cleanup(args.dsn)
+    print("Removed gapwatch_events and gapwatch_notify().")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gapwatch",
+        description="Crash-test how database changes reach your app.",
+    )
+    parser.add_argument("--version", action="version", version=f"gapwatch {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    dsn_help = "Postgres connection string (or set GAPWATCH_DSN)"
+    default_dsn = os.environ.get("GAPWATCH_DSN")
+
+    p_run = sub.add_parser("run", help="write changes, cut connections, report what was lost")
+    p_run.add_argument("--dsn", default=default_dsn, required=default_dsn is None, help=dsn_help)
+    p_run.add_argument("--count", type=int, default=5000, help="changes to write (default 5000)")
+    p_run.add_argument("--rate", type=float, default=500, help="changes per second (default 500)")
+    p_run.add_argument(
+        "--faults", type=int, default=3, help="times to cut the connection (default 3)"
+    )
+    p_run.add_argument(
+        "--reconnect-delay",
+        type=float,
+        default=1.0,
+        help="seconds the listener waits before reconnecting (default 1.0)",
+    )
+    p_run.add_argument(
+        "--drain", type=float, default=2.0, help="seconds to wait for late changes (default 2)"
+    )
+    p_run.add_argument("--seed", type=int, default=None, help="seed for fault timing")
+    p_run.add_argument("--json", metavar="PATH", help="also write the report as JSON")
+    p_run.add_argument(
+        "--fail-on-loss", action="store_true", help="exit with code 1 if anything was lost"
+    )
+    p_run.set_defaults(func=_cmd_run)
+
+    p_clean = sub.add_parser("cleanup", help="remove the table and trigger gapwatch created")
+    p_clean.add_argument("--dsn", default=default_dsn, required=default_dsn is None, help=dsn_help)
+    p_clean.set_defaults(func=_cmd_cleanup)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # keep the CLI output readable
+        print(f"gapwatch: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gapwatch-0.1.0/src/gapwatch/listen_notify.py

@@ -0,0 +1,217 @@
+"""Postgres LISTEN/NOTIFY source.
+
+A trigger sends a notification for every row the writer inserts. A listener
+receives them the way a typical app does: it reconnects after a failure and
+subscribes again. Meanwhile the fault injector cuts the listener's connection
+with pg_terminate_backend, so the run shows what a real app would miss.
+"""
+
+from __future__ import annotations
+
+import random
+import threading
+import time
+import uuid
+from dataclasses import dataclass, field
+
+import psycopg
+
+from gapwatch.checker import Window
+
+CHANNEL = "gapwatch"
+
+SETUP_SQL = f"""
+create table if not exists gapwatch_events (
+    run_id text not null,
+    seq bigint not null,
+    created_at timestamptz not null default now(),
+    primary key (run_id, seq)
+);
+
+create or replace function gapwatch_notify() returns trigger
+language plpgsql as $$
+begin
+    perform pg_notify('{CHANNEL}', new.run_id || ':' || new.seq);
+    return new;
+end;
+$$;
+
+drop trigger if exists gapwatch_notify on gapwatch_events;
+create trigger gapwatch_notify
+    after insert on gapwatch_events
+    for each row execute function gapwatch_notify();
+"""
+
+CLEANUP_SQL = """
+drop table if exists gapwatch_events;
+drop function if exists gapwatch_notify();
+"""
+
+
+@dataclass
+class RunConfig:
+    dsn: str
+    count: int = 5000
+    rate: float = 500.0
+    faults: int = 3
+    reconnect_delay: float = 1.0
+    drain: float = 2.0
+    seed: int | None = None
+
+
+@dataclass
+class RunResult:
+    run_id: str
+    sent: list[int] = field(default_factory=list)
+    sent_at: dict[int, float] = field(default_factory=dict)
+    received: list[int] = field(default_factory=list)
+    windows: list[Window] = field(default_factory=list)
+    duration: float = 0.0
+
+
+def setup(dsn: str) -> None:
+    with psycopg.connect(dsn, autocommit=True) as conn:
+        conn.execute(SETUP_SQL)
+
+
+def cleanup(dsn: str) -> None:
+    with psycopg.connect(dsn, autocommit=True) as conn:
+        conn.execute(CLEANUP_SQL)
+
+
+class _Run:
+    def __init__(self, config: RunConfig):
+        self.config = config
+        self.result = RunResult(run_id=uuid.uuid4().hex[:12])
+        self.app_name = f"gapwatch-listener-{self.result.run_id}"
+        self.start = 0.0
+        self.listening = threading.Event()
+        self.writer_done = threading.Event()
+        self.stop = threading.Event()
+        self.kill_times: list[float] = []
+        self.resubscribe_times: list[float] = []
+        self.errors: list[BaseException] = []
+
+    def now(self) -> float:
+        return time.monotonic() - self.start
+
+    # The listener behaves like a typical app: subscribe, and if the
+    # connection drops, wait a moment, reconnect and subscribe again.
+    def listener(self) -> None:
+        prefix = self.result.run_id + ":"
+        try:
+            while not self.stop.is_set():
+                try:
+                    with psycopg.connect(
+                        self.config.dsn,
+                        autocommit=True,
+                        application_name=self.app_name,
+                    ) as conn:
+                        conn.execute(f"listen {CHANNEL}")
+                        if self.listening.is_set():
+                            self.resubscribe_times.append(self.now())
+                        self.listening.set()
+                        while not self.stop.is_set():
+                            for note in conn.notifies(timeout=0.2):
+                                if note.payload.startswith(prefix):
+                                    self.result.received.append(int(note.payload[len(prefix) :]))
+                except psycopg.OperationalError:
+                    if not self.stop.is_set():
+                        time.sleep(self.config.reconnect_delay)
+        except BaseException as exc:  # surface unexpected errors to the caller
+            self.errors.append(exc)
+            self.listening.set()
+
+    def writer(self) -> None:
+        interval = 1.0 / self.config.rate if self.config.rate > 0 else 0.0
+        try:
+            with psycopg.connect(self.config.dsn, autocommit=True) as conn:
+                next_at = time.monotonic()
+                for seq in range(1, self.config.count + 1):
+                    conn.execute(
+                        "insert into gapwatch_events (run_id, seq) values (%s, %s)",
+                        (self.result.run_id, seq),
+                    )
+                    self.result.sent.append(seq)
+                    self.result.sent_at[seq] = self.now()
+                    next_at += interval
+                    delay = next_at - time.monotonic()
+                    if delay > 0:
+                        time.sleep(delay)
+        except BaseException as exc:
+            self.errors.append(exc)
+        finally:
+            self.writer_done.set()
+
+    def fault_times(self) -> list[float]:
+        """Spread the faults across the write period, with a little jitter."""
+        n = self.config.faults
+        if n <= 0:
+            return []
+        total = self.config.count / self.config.rate if self.config.rate > 0 else 1.0
+        rng = random.Random(self.config.seed)
+        slot = total / (n + 1)
+        return [slot * (i + 1) + rng.uniform(-0.2, 0.2) * slot for i in range(n)]
+
+    def injector(self) -> None:
+        try:
+            with psycopg.connect(self.config.dsn, autocommit=True) as conn:
+                for at in self.fault_times():
+                    delay = at - self.now()
+                    if delay > 0 and self.writer_done.wait(delay):
+                        return
+                    # Take the time before the cut, so changes committed while
+                    # the terminate call is in flight count as part of it.
+                    cut_at = self.now()
+                    cur = conn.execute(
+                        "select count(*) from ("
+                        " select pg_terminate_backend(pid) from pg_stat_activity"
+                        " where application_name = %s and pid <> pg_backend_pid()"
+                        ") t",
+                        (self.app_name,),
+                    )
+                    row = cur.fetchone()
+                    if row and row[0]:
+                        self.kill_times.append(cut_at)
+        except BaseException as exc:
+            self.errors.append(exc)
+
+    def run(self) -> RunResult:
+        self.start = time.monotonic()
+        listener = threading.Thread(target=self.listener, daemon=True)
+        listener.start()
+        if not self.listening.wait(10):
+            self.stop.set()
+            raise RuntimeError("listener could not subscribe within 10 seconds")
+        if self.errors:
+            raise self.errors[0]
+
+        writer = threading.Thread(target=self.writer, daemon=True)
+        injector = threading.Thread(target=self.injector, daemon=True)
+        writer.start()
+        injector.start()
+        writer.join()
+        injector.join()
+
+        # Give in-flight notifications time to arrive before counting.
+        time.sleep(self.config.drain)
+        self.stop.set()
+        listener.join(timeout=5)
+
+        if self.errors:
+            raise self.errors[0]
+
+        end = self.now()
+        for killed in self.kill_times:
+            back = next((t for t in self.resubscribe_times if t >= killed), end)
+            self.result.windows.append(Window(start=killed, end=back))
+            # Each resubscribe belongs to one fault.
+            if back in self.resubscribe_times:
+                self.resubscribe_times.remove(back)
+        self.result.duration = end
+        return self.result
+
+
+def run(config: RunConfig) -> RunResult:
+    setup(config.dsn)
+    return _Run(config).run()

gapwatch-0.1.0/tests/test_checker.py

@@ -0,0 +1,60 @@
+from gapwatch.checker import Window, check
+
+
+def test_everything_delivered_in_order():
+    report = check([1, 2, 3], [1, 2, 3])
+    assert report.ok
+    assert report.delivery_rate == 1.0
+    assert report.missing == []
+
+
+def test_missing_changes_are_grouped_into_ranges():
+    report = check(list(range(1, 11)), [1, 2, 6, 7, 10])
+    assert report.missing == [3, 4, 5, 8, 9]
+    assert report.missing_ranges == [(3, 5), (8, 9)]
+    assert report.delivered == 5
+    assert not report.ok
+
+
+def test_duplicates_are_counted_once_per_extra_copy():
+    report = check([1, 2, 3], [1, 2, 2, 2, 3])
+    assert report.duplicates == {2: 3}
+    assert report.to_dict()["duplicates"] == 2
+    assert report.missing == []
+
+
+def test_duplicates_do_not_count_as_out_of_order():
+    report = check([1, 2, 3], [1, 2, 3, 2])
+    assert report.out_of_order == 0
+
+
+def test_out_of_order_counts_late_first_deliveries():
+    report = check([1, 2, 3, 4], [1, 3, 2, 4])
+    assert report.out_of_order == 1
+
+
+def test_unknown_values_are_ignored():
+    report = check([1, 2], [1, 99, 2])
+    assert report.ok
+
+
+def test_empty_run_is_ok():
+    report = check([], [])
+    assert report.ok
+    assert report.delivery_rate == 1.0
+
+
+def test_missing_changes_are_attributed_to_disconnect_windows():
+    sent = [1, 2, 3, 4, 5, 6]
+    sent_at = {1: 0.1, 2: 1.1, 3: 1.2, 4: 2.0, 5: 3.1, 6: 4.0}
+    windows = [Window(1.0, 1.5), Window(3.0, 3.5)]
+    report = check(sent, [1, 4, 6], sent_at, windows)
+    assert report.missing_by_window == [2, 1]
+    assert report.missing_outside_windows == 0
+
+
+def test_missing_outside_windows_is_reported_separately():
+    windows = [Window(1.0, 1.5)]
+    report = check([1, 2], [], {1: 1.2, 2: 9.0}, windows)
+    assert report.missing_by_window == [1]
+    assert report.missing_outside_windows == 1

gapwatch-0.1.0/tests/test_listen_notify.py

@@ -0,0 +1,59 @@
+"""Runs against a real Postgres. Skipped unless GAPWATCH_TEST_DSN is set."""
+
+import os
+
+import pytest
+
+from gapwatch.checker import check
+from gapwatch.cli import main
+from gapwatch.listen_notify import RunConfig, cleanup, run
+
+DSN = os.environ.get("GAPWATCH_TEST_DSN")
+pytestmark = pytest.mark.skipif(not DSN, reason="set GAPWATCH_TEST_DSN to run")
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    yield
+    cleanup(DSN)
+
+
+def test_no_faults_means_nothing_lost():
+    result = run(RunConfig(dsn=DSN, count=300, rate=0, faults=0, drain=1.0))
+    report = check(result.sent, result.received)
+    assert report.ok, report.to_dict()
+    assert result.windows == []
+
+
+def test_cutting_the_connection_loses_changes_inside_the_window():
+    result = run(RunConfig(dsn=DSN, count=1000, rate=200, faults=2, reconnect_delay=0.5, seed=1))
+    report = check(result.sent, result.received, result.sent_at, result.windows)
+    assert len(result.windows) == 2
+    assert report.missing, "expected LISTEN/NOTIFY to miss changes while disconnected"
+    # Nearly every lost change should fall inside a disconnect window.
+    assert sum(report.missing_by_window) >= len(report.missing) * 0.9
+    assert report.duplicates == {}
+
+
+def test_cli_exit_code_reflects_loss(tmp_path):
+    out = tmp_path / "report.json"
+    code = main(
+        [
+            "run",
+            "--dsn",
+            DSN,
+            "--count",
+            "400",
+            "--rate",
+            "200",
+            "--faults",
+            "1",
+            "--reconnect-delay",
+            "0.5",
+            "--json",
+            str(out),
+            "--fail-on-loss",
+        ]
+    )
+    assert code == 1
+    assert out.exists()