justrach / turboAPI

TurboAPI FastAPI-compatible Python framework. Zig HTTP core. 20x faster. Drop-in replacement · Zig-native validation · Zero-copy responses · Free-threading · dhi models Status · Quick Start · Benchmarks · Architecture · Migrate · Why Python? · Observability · Security --- Status > **Alpha software — read before using in production** > > TurboAPI works and has 275+ passing tests, but: > - **No TLS** — put nginx or Caddy in front for HTTPS > - **No slow-loris protection** — requires a reverse proxy with read timeouts > - **No configurable max body size** — hardcoded 16MB cap > - **WebSocket support** is in progress, not production-ready > - **HTTP/2** is not yet implemented > - **Free-threaded Python 3.14t** is itself relatively new — some C extensions may not be thread-safe > > See SECURITY.md for the full threat model and deployment recommendations. | What works today | What's in progress | |--------------------------------------------------------|------------------------------------------| | 150k req/s (22x FastAPI) on Apple Silicon | WebSocket support | | FastAPI-compatible route decorators | HTTP/2 and TLS | | Zig HTTP server with 24-thread pool + keep-alive | Cloudflare Workers WASM target | | Zig-native JSON schema validation (dhi) | Fiber-based concurrency (via zag) | | Zero-alloc response pipeline (stack buffers) | | | Zig-native CORS (0% overhead, pre-rendered headers) | | | Response caching for noargs handlers | | | Static routes (pre-rendered at startup) | | | Async handler support | | | Full security stack (OAuth2, Bearer, API Key) | | | Python 3.14t free-threaded support | | | Native FFI handlers (C/Zig, no Python at all) | | | Fuzz-tested HTTP parser, router, validator | | --- ⚡ Quick Start **Requirements:** Python 3.14+ free-threaded ( ), Zig 0.15+ Option 1: Docker (easiest) This builds Python 3.14t from source, compiles the Zig backend, and runs the example app. Hit to verify. Option 2: Local install The app also exposes an ASGI fallback — you can use to test your route definitions before building the native backend, but this is pure-Python and much slower. For production, always use with the compiled Zig backend. --- Benchmarks All numbers verified with correct, identical JSON responses. , Python 3.14t free-threaded, Apple Silicon M3 Pro. HTTP Throughput (no database) | Endpoint | TurboAPI | FastAPI | Speedup | |---|---|---|---| | GET /health (static) | 179,113/s | 11,168/s | **16.0x** | | GET / | 175,549/s | 11,252/s | **15.6x** | | GET /json | 171,971/s | 10,721/s | **16.0x** | | GET /users/123 | 175,332/s | 9,775/s | **17.9x** | | POST /items | 155,687/s | 8,667/s | **18.0x** | | GET /status201 | 173,475/s | 11,991/s | **14.5x** | | **Average** | | | **16.3x** | Avg latency: TurboAPI 0.13ms / FastAPI 9.3ms Caching TurboAPI has two optional caching layers. Both can be disabled via environment variables: | Cache | What it does | Env var to disable | |---|---|---| | **Response cache** | Caches handler return values after first call. Subsequent requests for the same route skip Python entirely. | | | **DB result cache** | Caches SELECT query results with 30s TTL, 10K max entries, per-table invalidation on writes. | | | **DB cache TTL** | Override the default 30-second TTL. | | **The numbers above are measured with response cache disabled** ( ). The speedup comes from the Zig HTTP server and radix router, not from caching. With response cache enabled, throughput is ~1-3% higher (cache hit avoids the Python→Zig→Python round-trip for repeated calls). For database benchmarks, will measure true per-request Postgres performance. With DB caching on, cached reads hit a Zig HashMap instead of Postgres — useful in production but not a fair framework comparison. How it works • **Static routes**: — response pre-rendered at startup, single • **Response caching**: noargs handlers cached after first Python call — subsequent requests skip Python entirely • **Zero-arg GET**: — no tuple/kwargs allocation • **Parameterized GET**: with Zig-assembled positional args — no , no kwargs dict • **POST (dhi model)**: Zig validates JSON schema **before** acquiring the GIL — invalid bodies return without touching Python • **CORS**: Zig-native — headers pre-rendered once at startup, injected via . **0% overhead** (was 24% with Python middleware). OPTIONS preflight handled in Zig. ⚙️ Architecture Request lifecycle Every HTTP request flows through the same pipeline. The key idea: Python only runs your business logic. Everything else — parsing, routing, validation, response writing — happens in Zig. What "zero-copy" means On the response path, Zig calls to get a pointer to the Python string's internal buffer, then calls directly on the socket. No , no temporary buffers, no heap allocation. The Python string stays alive because we hold a reference to it. Handler classification At startup, each route is analyzed once and assigned the lightest dispatch path: | Handler type | What it skips | When used | |-----------------------|----------------------------------------------------------------|----------------------------------------| | | Python entirely — no GIL, no interpreter | C/Zig shared library handlers | | | GIL lookup, tuple/kwargs alloc — uses | Zero-param handlers | | | — Zig parses JSON and builds Python dict | with a param | | | header parsing, body parsing, regex | handlers with path/query params | | | header parsing, regex | without model params | | | nothing — full Python dispatch | , middleware, complex types | Zig-side JSON parsing (model_sync) For routes, the JSON request body is parsed **twice in Zig, zero times in Python**: • **dhi validation** — parses the JSON and validates field types, constraints ( , , etc.), nested objects, and unions. Invalid requests get a without acquiring the GIL. • **Python dict construction** — in recursively converts the parsed tree into Python objects ( , , , , , , ). The resulting dict is passed to the handler as .…