racetrap 0.1.0__tar.gz

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

@@ -0,0 +1,18 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv build
+      - run: uv publish --trusted-publishing always

racetrap-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: test
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { python: "3.11", postgres: "14" }
+          - { python: "3.14", postgres: "18" }
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres }}
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 2s
+          --health-retries 30
+    env:
+      RACETRAP_TEST_DATABASE: postgresql://postgres:postgres@localhost:5432/postgres
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run pytest -q

racetrap-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.venv/
+.pytest_cache/
+dist/
+racetrap-report.html

racetrap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Gupta
+
+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.

racetrap-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: racetrap
+Version: 0.1.0
+Summary: Finds race conditions in web APIs by forcing the worst order of their SQL statements.
+Project-URL: Repository, https://github.com/w-rahul/racetrap
+Author: Rahul Gupta
+License-Expression: MIT
+License-File: LICENSE
+Keywords: concurrency,isolation,postgres,race condition,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.11
+Requires-Dist: psycopg[binary]>=3.2
+Description-Content-Type: text/markdown
+
+<img src="https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/icon.svg" width="72" alt="">
+
+# racetrap
+
+Finds race conditions in web APIs by forcing the worst order of their SQL statements.
+
+![racetrap catching a double booking, then passing once the fix is in](https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/demo.gif)
+
+## Why it exists
+
+```python
+async with conn.transaction():
+    seats = await conn.fetchval("SELECT seats_left FROM shows WHERE id = $1", show_id)
+    if seats < 1:
+        raise HTTPException(409, "sold out")
+    await conn.execute("UPDATE shows SET seats_left = $1 WHERE id = $2", seats - 1, show_id)
+    await conn.execute("INSERT INTO bookings (show_id, user_name) VALUES ($1, $2)", show_id, user)
+```
+
+This passes every test and runs inside a transaction. Still, when two people book the last seat at the same moment, both get it. At Postgres's default isolation level both requests read `seats_left = 1` before either one writes.
+
+Tests send one request at a time, so they never see it. In production it shows up rarely, under load, and nobody can reproduce it. racetrap makes it show up on demand, in a test, with the exact order of statements that caused it.
+
+## What it does
+
+racetrap sits between your app and Postgres as a proxy. For every pair of requests:
+
+1. It runs them one at a time, in both orders. Those are the correct outcomes.
+2. It runs them again, holding the first request right before each of its SQL statements in turn while the second one runs.
+3. Any result that matches neither one at a time run is a race, reported with the order that caused it.
+
+Each forced order gives the same result on every run. There is no load test and no luck involved.
+
+```
+$ racetrap examples/tickets/buggy.toml
+racetrap 0.1.0
+proxy  127.0.0.1:6499 -> localhost:5432
+app    http://127.0.0.1:8765
+
+  alice books  vs  alice books   5 orders  RACE
+  alice books  vs  bob books     5 orders  RACE
+  bob books    vs  alice books   5 orders  RACE
+  bob books    vs  bob books     5 orders  RACE
+
+4 of 4 pairs race. 34 runs in 4.7s.
+Report: racetrap-report.html
+```
+
+![The report for one race: both requests as lanes, the hold, the outcome and the fix](https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/report.png)
+
+## What it does not do
+
+- **It does not replace transactions, locks or tests.** You keep writing normal code. racetrap shows where the transaction you have is not enough, and the fix stays a line you write: `FOR UPDATE`, a conditional `UPDATE ... WHERE`, a unique constraint, or `SERIALIZABLE` with a retry.
+- **It never changes your code, and it is not for production.** Point it at a test database you can wipe. It only watches and delays SQL.
+- **It is not a load test.** It does not fire thousands of requests and hope. It forces each order once.
+- **It does not see everything.** Postgres only, two requests at a time, and locks held outside Postgres, like Redis or an in-process mutex, are invisible to it.
+
+## Benchmark
+
+`benchmarks/burst.py` does what people try without racetrap: it fires alice and bob at the same instant, 1,000 times, on the ticket example. On one Windows machine it caught the double booking in 68.5%, 81.6% and 79.8% of bursts across three runs, and the rate changed every time. racetrap caught it on every run, in all 4 pairs, named the exact order of statements, and checked the fix against every order it forced.
+
+## Try it
+
+You need Python 3.11 or newer, [uv](https://docs.astral.sh/uv/) and a Postgres you can wipe.
+
+```sh
+git clone https://github.com/w-rahul/racetrap
+cd racetrap
+uv sync
+export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
+uv run racetrap examples/tickets/buggy.toml
+uv run racetrap examples/tickets/fixed.toml
+```
+
+The first run finds the race. The second one has `FOR UPDATE` on the read and passes.
+
+To run it on your own app, install the command with `uv tool install git+https://github.com/w-rahul/racetrap` and write a scenario file.
+
+## Scenario file
+
+```toml
+app = "http://127.0.0.1:8000"
+database = "${DATABASE_URL}"
+command = "uvicorn shop:app --port 8000"
+
+setup = [
+    "TRUNCATE orders, stock RESTART IDENTITY",
+    "INSERT INTO stock VALUES (1, 1)",
+]
+
+[[request]]
+name = "alice buys"
+path = "/items/1/buy"
+json = { user = "alice" }
+
+[[request]]
+name = "bob buys"
+path = "/items/1/buy"
+json = { user = "bob" }
+```
+
+| Key | Meaning |
+| --- | --- |
+| `app` | Base URL of the app. |
+| `database` | The real Postgres, used directly for setup and snapshots. |
+| `setup` | SQL run before every order. It must reset the data. |
+| `[[request]]` | `name`, `path`, and optional `method`, `json` and `headers`. |
+| `command` | Optional. Starts the app with `DATABASE_URL` pointing at the proxy. |
+| `init` | Optional SQL run once before the app starts. |
+| `invariants` | Optional SQL that must return true after every order. |
+| `ignore` | Optional `table.column` entries to leave out of the comparison. |
+| `refs` | Optional id references without a foreign key, like `{ "orders.user_id" = "users.id" }`. |
+| `proxy`, `database_env`, `schema`, `stall_ms` | Defaults `127.0.0.1:6499`, `DATABASE_URL`, `public` and `1000`. |
+
+`${NAME}` is read from the environment. Each request is also paired with itself, which catches double submits.
+
+## How it decides
+
+The check is serializability. Every outcome must match running the two requests one after the other, in some order. racetrap compares the HTTP status of each request and the rows of every table.
+
+Values the database fills in differ between correct runs, so ids, timestamps and random values are left out, and a reference to a generated id is compared by the row it points to. A deadlock or an unretried serialization failure that turns into a 500 counts as a race. racetrap stops instead of passing if the app dies, and the exit code is 1 when any pair races, so it can fail a CI job.
+
+## Prior work
+
+Finding these bugs from database traces comes from [ACIDRain](https://www.bailis.org/papers/acidrain-sigmod2017.pdf) (SIGMOD 2017), which found 22 attacks in 12 popular e-commerce apps. [RaceDB](https://par.nsf.gov/biblio/10617180) (IEEE S&P 2025) confirms candidates by replaying them. [ChaosSQL](https://github.com/bregaldahq/chaossql) and [Deadheat](https://github.com/sanjayrawatt/deadheat) also proxy the database, but check a rule you write and randomize the timing. racetrap needs no rule and gives the same answer on every run.
+
+## License
+
+MIT

racetrap-0.1.0/README.md

@@ -0,0 +1,129 @@
+<img src="https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/icon.svg" width="72" alt="">
+
+# racetrap
+
+Finds race conditions in web APIs by forcing the worst order of their SQL statements.
+
+![racetrap catching a double booking, then passing once the fix is in](https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/demo.gif)
+
+## Why it exists
+
+```python
+async with conn.transaction():
+    seats = await conn.fetchval("SELECT seats_left FROM shows WHERE id = $1", show_id)
+    if seats < 1:
+        raise HTTPException(409, "sold out")
+    await conn.execute("UPDATE shows SET seats_left = $1 WHERE id = $2", seats - 1, show_id)
+    await conn.execute("INSERT INTO bookings (show_id, user_name) VALUES ($1, $2)", show_id, user)
+```
+
+This passes every test and runs inside a transaction. Still, when two people book the last seat at the same moment, both get it. At Postgres's default isolation level both requests read `seats_left = 1` before either one writes.
+
+Tests send one request at a time, so they never see it. In production it shows up rarely, under load, and nobody can reproduce it. racetrap makes it show up on demand, in a test, with the exact order of statements that caused it.
+
+## What it does
+
+racetrap sits between your app and Postgres as a proxy. For every pair of requests:
+
+1. It runs them one at a time, in both orders. Those are the correct outcomes.
+2. It runs them again, holding the first request right before each of its SQL statements in turn while the second one runs.
+3. Any result that matches neither one at a time run is a race, reported with the order that caused it.
+
+Each forced order gives the same result on every run. There is no load test and no luck involved.
+
+```
+$ racetrap examples/tickets/buggy.toml
+racetrap 0.1.0
+proxy  127.0.0.1:6499 -> localhost:5432
+app    http://127.0.0.1:8765
+
+  alice books  vs  alice books   5 orders  RACE
+  alice books  vs  bob books     5 orders  RACE
+  bob books    vs  alice books   5 orders  RACE
+  bob books    vs  bob books     5 orders  RACE
+
+4 of 4 pairs race. 34 runs in 4.7s.
+Report: racetrap-report.html
+```
+
+![The report for one race: both requests as lanes, the hold, the outcome and the fix](https://raw.githubusercontent.com/w-rahul/racetrap/main/docs/report.png)
+
+## What it does not do
+
+- **It does not replace transactions, locks or tests.** You keep writing normal code. racetrap shows where the transaction you have is not enough, and the fix stays a line you write: `FOR UPDATE`, a conditional `UPDATE ... WHERE`, a unique constraint, or `SERIALIZABLE` with a retry.
+- **It never changes your code, and it is not for production.** Point it at a test database you can wipe. It only watches and delays SQL.
+- **It is not a load test.** It does not fire thousands of requests and hope. It forces each order once.
+- **It does not see everything.** Postgres only, two requests at a time, and locks held outside Postgres, like Redis or an in-process mutex, are invisible to it.
+
+## Benchmark
+
+`benchmarks/burst.py` does what people try without racetrap: it fires alice and bob at the same instant, 1,000 times, on the ticket example. On one Windows machine it caught the double booking in 68.5%, 81.6% and 79.8% of bursts across three runs, and the rate changed every time. racetrap caught it on every run, in all 4 pairs, named the exact order of statements, and checked the fix against every order it forced.
+
+## Try it
+
+You need Python 3.11 or newer, [uv](https://docs.astral.sh/uv/) and a Postgres you can wipe.
+
+```sh
+git clone https://github.com/w-rahul/racetrap
+cd racetrap
+uv sync
+export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
+uv run racetrap examples/tickets/buggy.toml
+uv run racetrap examples/tickets/fixed.toml
+```
+
+The first run finds the race. The second one has `FOR UPDATE` on the read and passes.
+
+To run it on your own app, install the command with `uv tool install git+https://github.com/w-rahul/racetrap` and write a scenario file.
+
+## Scenario file
+
+```toml
+app = "http://127.0.0.1:8000"
+database = "${DATABASE_URL}"
+command = "uvicorn shop:app --port 8000"
+
+setup = [
+    "TRUNCATE orders, stock RESTART IDENTITY",
+    "INSERT INTO stock VALUES (1, 1)",
+]
+
+[[request]]
+name = "alice buys"
+path = "/items/1/buy"
+json = { user = "alice" }
+
+[[request]]
+name = "bob buys"
+path = "/items/1/buy"
+json = { user = "bob" }
+```
+
+| Key | Meaning |
+| --- | --- |
+| `app` | Base URL of the app. |
+| `database` | The real Postgres, used directly for setup and snapshots. |
+| `setup` | SQL run before every order. It must reset the data. |
+| `[[request]]` | `name`, `path`, and optional `method`, `json` and `headers`. |
+| `command` | Optional. Starts the app with `DATABASE_URL` pointing at the proxy. |
+| `init` | Optional SQL run once before the app starts. |
+| `invariants` | Optional SQL that must return true after every order. |
+| `ignore` | Optional `table.column` entries to leave out of the comparison. |
+| `refs` | Optional id references without a foreign key, like `{ "orders.user_id" = "users.id" }`. |
+| `proxy`, `database_env`, `schema`, `stall_ms` | Defaults `127.0.0.1:6499`, `DATABASE_URL`, `public` and `1000`. |
+
+`${NAME}` is read from the environment. Each request is also paired with itself, which catches double submits.
+
+## How it decides
+
+The check is serializability. Every outcome must match running the two requests one after the other, in some order. racetrap compares the HTTP status of each request and the rows of every table.
+
+Values the database fills in differ between correct runs, so ids, timestamps and random values are left out, and a reference to a generated id is compared by the row it points to. A deadlock or an unretried serialization failure that turns into a 500 counts as a race. racetrap stops instead of passing if the app dies, and the exit code is 1 when any pair races, so it can fail a CI job.
+
+## Prior work
+
+Finding these bugs from database traces comes from [ACIDRain](https://www.bailis.org/papers/acidrain-sigmod2017.pdf) (SIGMOD 2017), which found 22 attacks in 12 popular e-commerce apps. [RaceDB](https://par.nsf.gov/biblio/10617180) (IEEE S&P 2025) confirms candidates by replaying them. [ChaosSQL](https://github.com/bregaldahq/chaossql) and [Deadheat](https://github.com/sanjayrawatt/deadheat) also proxy the database, but check a rule you write and randomize the timing. racetrap needs no rule and gives the same answer on every run.
+
+## License
+
+MIT

racetrap-0.1.0/benchmarks/burst.py

@@ -0,0 +1,74 @@
+"""How often does firing two requests at the same instant catch the double booking?
+
+This is what people try without racetrap. It starts the ticket example app
+straight on the database, fires alice and bob together behind a barrier, and
+counts how often the last seat gets sold twice.
+
+    DATABASE_URL=postgresql://... uv run python benchmarks/burst.py 1000
+"""
+
+import json
+import os
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import psycopg
+
+APP = Path(__file__).parent.parent / "examples" / "tickets"
+URL = "http://127.0.0.1:8765"
+opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+def book(user, barrier):
+    req = urllib.request.Request(
+        f"{URL}/shows/1/book", data=json.dumps({"user": user}).encode(),
+        headers={"content-type": "application/json"}, method="POST",
+    )
+    barrier.wait()
+    try:
+        opener.open(req, timeout=10).close()
+    except urllib.error.HTTPError:
+        pass  # the loser gets 409, which is the correct answer
+
+
+def main(trials):
+    db = psycopg.connect(os.environ["DATABASE_URL"], autocommit=True)
+    db.execute("DROP TABLE IF EXISTS bookings, shows")
+    db.execute("CREATE TABLE shows (id int PRIMARY KEY, title text NOT NULL, seats_left int NOT NULL)")
+    db.execute("CREATE TABLE bookings (id serial PRIMARY KEY, show_id int NOT NULL REFERENCES shows, user_name text NOT NULL)")
+    app = subprocess.Popen(
+        [sys.executable, "-m", "uvicorn", "app:app", "--port", "8765", "--log-level", "warning"], cwd=APP,
+    )
+    try:
+        for _ in range(100):
+            try:
+                opener.open(URL, timeout=1).close()
+                break
+            except urllib.error.HTTPError:
+                break
+            except OSError:
+                time.sleep(0.1)
+        caught = 0
+        for _ in range(trials):
+            db.execute("TRUNCATE bookings, shows RESTART IDENTITY")
+            db.execute("INSERT INTO shows VALUES (1, 'Dune', 1)")
+            barrier = threading.Barrier(2)
+            threads = [threading.Thread(target=book, args=(u, barrier)) for u in ("alice", "bob")]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
+            caught += db.execute("SELECT count(*) FROM bookings").fetchone()[0] > 1
+        print(f"{caught} of {trials} bursts caught the double booking ({caught / trials:.1%})")
+    finally:
+        app.terminate()
+        app.wait()
+
+
+if __name__ == "__main__":
+    main(int(sys.argv[1]) if len(sys.argv) > 1 else 1000)

racetrap-0.1.0/docs/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="112" fill="#17181B"/>
+  <path d="M138 214 C 128 160 140 112 162 96 C 186 104 214 132 232 160 Z" fill="#9A968F"/>
+  <path d="M374 214 C 384 160 372 112 350 96 C 326 104 298 132 280 160 Z" fill="#9A968F"/>
+  <path d="M158 190 C 154 156 160 128 170 118 C 184 128 198 144 208 160 Z" fill="#2A2B2F"/>
+  <path d="M354 190 C 358 156 352 128 342 118 C 328 128 314 144 304 160 Z" fill="#2A2B2F"/>
+  <path d="M380 258 C 408 246 440 230 476 222 C 466 240 456 254 450 268 C 428 268 404 270 380 274 Z" fill="#E0483E"/>
+  <path d="M380 276 C 408 280 436 294 466 320 C 448 320 430 316 416 310 C 404 300 392 290 380 284 Z" fill="#B93A31"/>
+  <path d="M256 134 C 330 134 380 170 394 228 C 400 256 412 282 432 304 L 400 314 L 424 340 L 384 344 C 360 392 312 416 256 416 C 200 416 152 392 128 344 L 88 340 L 112 314 L 80 304 C 100 282 112 256 118 228 C 132 170 182 134 256 134 Z" fill="#D9D6D0"/>
+  <path d="M256 140 C 268 170 270 200 262 236 L 250 236 C 242 200 244 170 256 140 Z" fill="#5A5853"/>
+  <path d="M112 270 C 132 236 168 222 204 228 C 226 232 242 240 256 250 C 270 240 286 232 308 228 C 344 222 380 236 400 270 C 384 300 352 312 318 306 C 292 302 272 290 256 280 C 240 290 220 302 194 306 C 160 312 128 300 112 270 Z" fill="#E0483E"/>
+  <circle cx="200" cy="266" r="21" fill="#F3F1EC"/>
+  <circle cx="312" cy="266" r="21" fill="#F3F1EC"/>
+  <circle cx="209" cy="268" r="10" fill="#17181B"/>
+  <circle cx="321" cy="268" r="10" fill="#17181B"/>
+  <ellipse cx="256" cy="352" rx="74" ry="50" fill="#F3F1EC"/>
+  <path d="M232 318 C 232 306 280 306 280 318 C 280 330 264 342 256 342 C 248 342 232 330 232 318 Z" fill="#17181B"/>
+  <path d="M256 342 L 256 356 C 262 366 276 366 286 358" fill="none" stroke="#17181B" stroke-width="7" stroke-linecap="round"/>
+</svg>

racetrap-0.1.0/examples/tickets/app.py

@@ -0,0 +1,59 @@
+"""A tiny ticket shop with the race most booking code has, and two fixes."""
+
+import os
+from contextlib import asynccontextmanager
+
+import asyncpg
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+
+class Booking(BaseModel):
+    user: str
+
+
+@asynccontextmanager
+async def lifespan(app):
+    app.state.pool = await asyncpg.create_pool(os.environ["DATABASE_URL"], min_size=2)
+    yield
+    await app.state.pool.close()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+async def check_then_book(show_id, user, lock):
+    read = "SELECT seats_left FROM shows WHERE id = $1" + (" FOR UPDATE" if lock else "")
+    async with app.state.pool.acquire() as conn, conn.transaction():
+        seats = await conn.fetchval(read, show_id)
+        if not seats:
+            raise HTTPException(409, "sold out")
+        await conn.execute("UPDATE shows SET seats_left = $1 WHERE id = $2", seats - 1, show_id)
+        await conn.execute("INSERT INTO bookings (show_id, user_name) VALUES ($1, $2)", show_id, user)
+    return {"booked": user}
+
+
+@app.post("/shows/{show_id}/book")
+async def book(show_id: int, booking: Booking):
+    """Reads the seats, checks, writes. Inside a transaction. Every test passes."""
+    return await check_then_book(show_id, booking.user, lock=False)
+
+
+@app.post("/shows/{show_id}/book-locked")
+async def book_locked(show_id: int, booking: Booking):
+    """FOR UPDATE makes a second buyer wait until the first one commits."""
+    return await check_then_book(show_id, booking.user, lock=True)
+
+
+@app.post("/shows/{show_id}/book-atomic")
+async def book_atomic(show_id: int, booking: Booking):
+    """Checks and writes in one statement, so there is no gap to race in."""
+    async with app.state.pool.acquire() as conn, conn.transaction():
+        left = await conn.fetchval(
+            "UPDATE shows SET seats_left = seats_left - 1 WHERE id = $1 AND seats_left > 0 RETURNING seats_left",
+            show_id,
+        )
+        if left is None:
+            raise HTTPException(409, "sold out")
+        await conn.execute("INSERT INTO bookings (show_id, user_name) VALUES ($1, $2)", show_id, booking.user)
+    return {"booked": booking.user}

racetrap-0.1.0/examples/tickets/buggy.toml

@@ -0,0 +1,26 @@
+# One seat left. Alice and Bob both try to book it.
+
+app = "http://127.0.0.1:8765"
+database = "${DATABASE_URL}"
+command = "python -m uvicorn app:app --port 8765 --log-level warning"
+
+init = [
+    "DROP TABLE IF EXISTS bookings, shows",
+    "CREATE TABLE shows (id int PRIMARY KEY, title text NOT NULL, seats_left int NOT NULL)",
+    "CREATE TABLE bookings (id serial PRIMARY KEY, show_id int NOT NULL REFERENCES shows, user_name text NOT NULL)",
+]
+
+setup = [
+    "TRUNCATE bookings, shows RESTART IDENTITY",
+    "INSERT INTO shows VALUES (1, 'Dune', 1)",
+]
+
+[[request]]
+name = "alice books"
+path = "/shows/1/book"
+json = { user = "alice" }
+
+[[request]]
+name = "bob books"
+path = "/shows/1/book"
+json = { user = "bob" }

racetrap-0.1.0/examples/tickets/fixed.toml

@@ -0,0 +1,26 @@
+# The same shop, with FOR UPDATE on the read. Every order passes.
+
+app = "http://127.0.0.1:8765"
+database = "${DATABASE_URL}"
+command = "python -m uvicorn app:app --port 8765 --log-level warning"
+
+init = [
+    "DROP TABLE IF EXISTS bookings, shows",
+    "CREATE TABLE shows (id int PRIMARY KEY, title text NOT NULL, seats_left int NOT NULL)",
+    "CREATE TABLE bookings (id serial PRIMARY KEY, show_id int NOT NULL REFERENCES shows, user_name text NOT NULL)",
+]
+
+setup = [
+    "TRUNCATE bookings, shows RESTART IDENTITY",
+    "INSERT INTO shows VALUES (1, 'Dune', 1)",
+]
+
+[[request]]
+name = "alice books"
+path = "/shows/1/book-locked"
+json = { user = "alice" }
+
+[[request]]
+name = "bob books"
+path = "/shows/1/book-locked"
+json = { user = "bob" }

racetrap-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "racetrap"
+version = "0.1.0"
+description = "Finds race conditions in web APIs by forcing the worst order of their SQL statements."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Rahul Gupta" }]
+keywords = ["race condition", "postgres", "concurrency", "testing", "isolation"]
+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.urls]
+Repository = "https://github.com/w-rahul/racetrap"
+
+[project.scripts]
+racetrap = "racetrap.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "fastapi>=0.115", "uvicorn>=0.30", "asyncpg>=0.30"]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

racetrap-0.1.0/src/racetrap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

racetrap-0.1.0/src/racetrap/__main__.py

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