CLAUDE.md

1# TurboAPI — Project Guide
2 
3## What is this?
4 
5A high-performance Python web framework with a Zig HTTP backend. Drop-in FastAPI-compatible API.
6 
7## Requirements
8 
9- **Python 3.14+** (free-threaded `3.14t` recommended)
10- **Zig 0.16+** (for building the native backend)
11- **uv** (Python package manager)
12 
13## Building
14 
15```bash
16# Build the Zig native backend (auto-detects Python, dhi fetched via build.zig.zon)
17python zig/build_turbonet.py --install
18 
19# Install the Python package in dev mode
20uv pip install -e ".[dev]"
21 
22# Or just use Docker
23docker compose up --build
24```
25 
26## Running Tests
27 
28```bash
29# Python tests (requires Python 3.14t)
30uv run --python 3.14t python -m pytest tests/ -p no:anchorpy
31 
32# Zig unit tests (includes fuzz seed corpus + WebSocket codec)
33cd zig && zig build test
34 
35# Zig continuous fuzzing (runs indefinitely)
36cd zig && zig build test --fuzz
37```
38 
39**Known test exclusions:**
40- `anchorpy` plugin — causes import error, disable with `-p no:anchorpy`
41 
42## Benchmarks
43 
44```bash
45uv run --python 3.14t python benchmarks/run_benchmarks.py
46```
47 
48Current numbers: ~140k req/s, 0.16ms avg latency, 8-9x faster than FastAPI.
49 
50## Project Structure
51 
52```
53zig/src/
54  server.zig         — HTTP server core (TCP, parsing, dispatch)
55  router.zig         — Radix trie router
56  dhi_validator.zig  — JSON schema validator (pre-GIL)
57  py.zig             — Python C API helpers
58zig/build.zig        — Zig build system
59 
60python/turboapi/
61  main_app.py        — TurboAPI class (public API)
62  middleware.py       — CORS, rate limiting, gzip, etc.
63  security.py        — Auth helpers (OAuth2, JWT, API keys)
64  models.py          — Request/Response models
65  routing.py         — Router and APIRouter
66  request_handler.py — Python-side request handling
67 
68tests/               — pytest test suite (275+ tests)
69benchmarks/          — Performance benchmarks
70```
71 
72## Key Conventions
73 
74- Zig backend builds via `python zig/build_turbonet.py` (NOT `zig build` directly — it needs `-Dpy-include`)
75- dhi dependency is fetched automatically via `build.zig.zon` — no manual cloning needed
76- Pre-commit hooks run ruff lint + Zig build + smoke test
77- The `feature/community-feedback` branch has the latest security fixes and fuzz tests
78- FFI native handlers use borrowed pointers (no heap alloc) — see ABI contract in `server.zig`
79