fasterapi-rs 0.1.0__tar.gz

fasterapi_rs-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Report a behavioral difference from FastAPI or a crash
+title: ""
+labels: bug
+---
+
+**Environment**
+
+- fasterapi version / commit:
+- Python version: <!-- e.g. 3.14.7 -->
+- Rust extension built? (`python -c "import fasterapi; print(fasterapi.HAS_RUST)"`):
+- Host: <!-- hyper (default) / uvicorn (FASTERAPI_UVICORN=1) / TestClient -->
+
+**What happened vs what FastAPI does**
+
+<!-- For parity bugs, a minimal app reproducing both behaviors is ideal -->
+
+```python
+# minimal reproduction
+```
+
+**Expected output**
+
+**Actual output**

fasterapi_rs-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Missing FastAPI surface or a new capability
+title: ""
+labels: enhancement
+---
+
+**FastAPI API or behavior you need**
+
+<!-- Link to FastAPI docs if it exists upstream -->
+
+**Use case**
+
+**Willing to implement it?**

fasterapi_rs-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What changed and why -->
+
+## Verification
+
+- [ ] `pytest tests/ -q` — all differential tests green
+- [ ] `maturin develop --release` after any `src/` change
+- [ ] Parity vs FastAPI verified for behavioral changes
+- [ ] Benchmarked if perf-sensitive (`benchmarks/benchmark_differential.py`)

fasterapi_rs-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+target/
+*.so
+*.pyd
+
+# Maturin / Rust
+/target/
+Cargo.lock
+
+# Test / bench artifacts
+.pytest_cache/
+.hypothesis/
+benchmark-results/
+*.prof
+examples/comparison/audit-results/
+examples/comparison/audit.db
+examples/comparison/audit_*.db
+examples/comparison/audit_*.db-*
+audit_fastapi.db*
+audit_fasterapi.db*
+
+# OS / editors
+.DS_Store
+.vscode/
+.idea/
+*.swp
+
+# Env
+.env

fasterapi_rs-0.1.0/CHANGELOG.md

@@ -0,0 +1,140 @@
+# Changelog
+
+All notable changes to fasterapi. Format follows Keep a Changelog; versions
+are `0.x` until the Hyper host promotes to default.
+
+## [Unreleased]
+
+### Added
+- **Radix-tree dispatch is live**: `FastRouter` compiles all plain routes
+  into `matchit` and answers unambiguous FULL matches in Rust; ambiguous
+  orderings, Mount/Host entries, convertor patterns, method mismatches and
+  redirects defer to Starlette's scan — byte-identical semantics.
+- **DI fan-out**: yield-free `Depends` subtrees resolve concurrently
+  (signature-ordered results, per-dep locks for `use_cache`, deterministic
+  first-exception-wins). Yield deps stay sequential to preserve teardown
+  order. Dependency validation errors now collect across all siblings like
+  FastAPI (`{"detail": [...]}` lists every failure).
+- **Fast JSON writer** (`itoa`/`ryu`, byte-wise escaping, Python-`repr`
+  float adapter): `fast_json_dumps` ~x2.5 vs compact stdlib, byte-identical
+  output (`ensure_ascii=False` contract, coerced-key quoting, `strict=`
+  mirrors `allow_nan=False`). Wired into the default response path via
+  `_FastJSONResponse`.
+- **Socket-level rate limiting on Hyper**: `RateLimiter` is now a pure-ASGI
+  middleware (no `Request` allocation); its bucket is registered on the app
+  and checked in Rust before any Python runs (`429` pre-parse). Under
+  uvicorn the same pure-ASGI path applies.
+- **Route kwargs**: `include_in_schema`, `openapi_extra`, `callbacks`,
+  `responses` (route-level merge over router default) — all wired into
+  `get_openapi`.
+- **`app.mount()`** verified for ASGI sub-apps and `StaticFiles`.
+- **`on_event("startup"|"shutdown")`** on `FastAPI`/`APIRouter` with merge
+  on `include_router` (deprecation-warned, matches FastAPI semantics).
+- **`fasterapi.openapi.webhooks`** module (import-surface parity).
+- **`FASTERAPI_MAX_BODY`** env var tunes the Hyper body cap (16 MiB default).
+- **Free-threaded support**: the extension declares `gil_used = false`
+  (PyO3 nogil-safe) — the full 87-test suite passes under `PYTHON_GIL=0`
+  on CPython 3.14t.
+- **True streaming on Hyper**: responses that keep producing past a 30ms
+  settle graduate to a real-time session — chunks flow through an mpsc into
+  Hyper's body writer (chunked encoding), the client sees incremental bytes,
+  and client disconnect cancels the app task. `receive()` now correctly
+  pends for disconnect instead of returning it eagerly.
+- **WebSocket subprotocol negotiation** on Hyper: `sec-websocket-protocol`
+  offers reach `scope["subprotocols"]`; the app's `accept(subprotocol=...)`
+  is echoed in the 101.
+- Hyper host gate run: ~x1.03 uvicorn RPS on a micro-JSON workload
+  (5453 vs 5316 rps loopback) — first parity-or-better measurement.
+- GitHub Actions CI (test matrix 3.10–3.14 + lint + wheel builds on tags)
+  and a ruff advisory gate in `pre-commit`.
+- `tests/test_parity_extended.py`: 23 differential tests — multi-dep error
+  collection, required params, DI concurrency/cache/ordering, mounts,
+  on_event, route kwargs, enum/union/nested-model validation, route
+  ordering edge cases, rate limiter, JSON writer parity.
+
+### Performance
+- **GIL-crossing batching on the Hyper host**: one Python crossing per
+  request — Rust builds the ASGI scope + `http.request` natively and hands
+  them to a cached `run_scoped` bridge callable (`OnceLock`, no per-request
+  import/getattr/`clone_ref`); the app handle is `Arc<PyObject>` and stream
+  sessions live in a Rust registry keyed by `u64`. Python-side pump drives
+  the loop via `run_forever()` + `loop.stop()` wakes with a no-poll selector
+  shim, removing ~52µs/request of `kqueue.control` syscalls. In-process
+  `run_request` ~82µs → ~15µs; serial keep-alive ~146µs → ~69µs median
+  (≈6.4k → ≈13.2k rps). `run_request` remains as a scope-building compat
+  wrapper.
+- **`AsyncExitStackMiddleware` → pure ASGI**: the request-lifetime stack is
+  now set inline without `BaseHTTPMiddleware` (no `Request` alloc, task
+  group, or in-memory streams per request). ASGI-level micro bench:
+  ~x1.25 vs fastapi (12.2k vs 9.7k req/s) — previously ~x0.45.
+- **`_solve_plan`**: per-function compiled param dispatch (kind-tagged
+  plan entries, FastAPI `dependant`-style) cached in a weakref dict —
+  no more per-request signature classification.
+- **No `dict()` materialization** on `query_params`/`headers`/`cookies` —
+  Starlette's MultiDict types already provide the needed interface.
+
+### Fixed
+- **Sync endpoints ran inline on the event loop** — any blocking handler
+  stalled all concurrent requests. Now `run_in_threadpool` like FastAPI.
+- **Required `Query`/`Header`/`Cookie` params** silently resolved to
+  `Ellipsis` (dead `param.default is empty` check) — now 422 correctly.
+- **Multi-dep 422s** collected only the first failing dep's errors —
+  now returns every failure in signature order like FastAPI.
+
+### Added (previous)
+- Rust Hyper + Tokio ASGI host spike (`serve_asgi`, `FASTERAPI_HYPER=1`,
+  `python -m fasterapi run app:app --hyper`): sockets + HTTP parsing in Rust,
+  byte-identical app behavior, lifespan, graceful SIGTERM/SIGINT shutdown,
+  413 body cap, `FASTERAPI_POOL` worker tuning.
+- Zero-copy file streaming on the Hyper host (`FileResponse` sendfile lane,
+  `Range` falls back to Starlette semantics).
+- Direct dispatch: with no user middleware, Hyper skips Starlette's
+  per-request stack (ServerError/Exception wrappers, router loop).
+- `get_openapi()` with FastAPI-identical output (operationIds, typed params,
+  `$ref` bodies, nested components, 422 contract, `servers`, securitySchemes,
+  per-op `security`), byte-identical Swagger/ReDoc/oauth2-redirect pages.
+- Auth surface: OAuth2 (password, auth-code), OpenID Connect, HTTP
+  Basic/Bearer/Digest, API-key header/query/cookie, `Security` + scopes,
+  password-grant forms (permissive + strict).
+- `BackgroundTasks` injection (shared per-request instance, FastAPI-exact
+  teardown-after-background ordering via send-inside-stack lifecycle).
+- SSE streaming (`EventSourceResponse`, `ServerSentEvent`, byte-identical frames).
+- `UploadFile`, `status`, `BackgroundTasks`, `Security`, `jsonable_encoder`,
+  `ORJSONResponse`/`UJSONResponse` shims, `middleware.*`, `staticfiles`,
+  `templating`, `logger`, `types`, `sse`, `utils` (`generate_unique_id`),
+  `param_functions`, `concurrency`, `dependencies`, `exception_handlers` modules.
+- Response-model inference from return annotations (explicit
+  `response_model=None` disables), filter flags (`include`/`exclude`/
+  `exclude_unset`/`exclude_none`/…), `deprecated` + `operationId` support.
+- Bare `dict`/`list[Item]` JSON bodies; `validate_json`/`dump_json`
+  single-pass paths; lazy body parsing; Rust scalar validators.
+- `fasterapi` console script (`fasterapi run [--reload] [--hyper]`).
+- Export-parity guard test, thread-soak tests, Hyper differential tests
+  (file bytes, 413, middleware fallback, graceful lifespan).
+- Auto-generated README parity/bench tables (`scripts/update_readme_tables.py`,
+  refreshed every commit); local bench history; free-threaded check script.
+
+### Fixed
+- Form field constraints dropped before validation.
+- `self` solved as a query param in class dependencies.
+- Instance (non-function) async dependencies never awaited.
+- `id()`-keyed caches colliding after GC (weak keys).
+- Lifespan shutdown unreachable (loop closed by `asyncio.run`); persistent
+  lifespan loop.
+- Python SIGINT disposition racing tokio shutdown (neutralized during serve).
+- `x-fasterapi-*` plan headers leaking to clients; `server` re-stamped.
+- `Vec<u8>` crossing the boundary as `list[int]` instead of `bytes`.
+
+### Performance
+- Model validation x2.2 (`validate_json`), model dump x2.9 (`dump_json`),
+  router match x3.3 (`matchit`), JSON dumps x1.1 (direct writer).
+- Hyper GET fan-out up to x1.37 with far better p90/p99; validation-heavy
+  POST trails on GIL builds (documented GIL physics).
+
+### Known limitations
+- Hyper host: HTTP/1.1 only, buffered bodies (16 MiB cap), concatenated
+  streaming, no mid-response disconnect polling, no WebSockets yet.
+- `fastapi.cli`, `fastapi.utils` v1-compat internals, `dependencies.*`
+  internals, `openapi.webhooks` are not ported (documented in migration guide).
+- Single-run loopback RPS swings ±15%; gates use a strict micro 3x plus a
+  wide macro band.

fasterapi_rs-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to fasterapi
+
+## Setup
+
+```bash
+bash scripts/quickstart.sh   # venv + deps + hooks + tests
+# or: uv venv .venv && pip install -e ".[test,bench]" && maturin develop --release
+```
+
+`pip install -e` builds the Rust extension via maturin. Pure-Python works
+without it (`fasterapi.HAS_RUST` tells you which path is live).
+
+## The one rule: parity is king
+
+fasterapi's contract is **byte-identical FastAPI behavior**. Every change
+must keep the differential suite green:
+
+```bash
+pytest tests/ -q                          # full suite (differential vs real FastAPI)
+pytest tests/test_parity_extended.py -q   # edge cases: DI, mounts, ordering, errors
+```
+
+Writing a fix? Add a **differential test first**: build the same app with
+`fastapi.FastAPI()` and `fasterapi.FastAPI()`, assert identical wire output.
+Regression tests live in `tests/test_parity*.py`.
+
+## Performance claims need numbers
+
+- Micro fast-paths: `python benchmarks/benchmark_differential.py --micro-only`
+- Full loopback: `python benchmarks/benchmark_differential.py --quick`
+- Measure end-to-end, not just primitives — a fast `matchit` lookup means
+  nothing if dispatch still routes through Python (that gap is now closed
+  via `FastRouter`; keep it that way).
+
+README tables are auto-generated — `scripts/update_readme_tables.py` runs
+on every commit via `.githooks/pre-commit`. Don't edit `PARITY:`/`BENCH:`
+blocks by hand.
+
+## Hooks
+
+```bash
+bash scripts/install_hooks.sh
+```
+
+- `pre-commit`: cargo fmt (advisory) + ruff (advisory) + README refresh + fast tests
+- `pre-push`: full parity suite (reject on failure) + perf gates
+
+## Areas with deliberate trade-offs (know before changing)
+
+- `FastRouter` falls back to Starlette's linear scan for anything it can't
+  prove identical (ambiguous pattern orderings, Mount/Host, convertor
+  patterns, method mismatches). Correctness beats speed here.
+- `_solve_inner` fans out only *yield-free* dep subtrees — yield deps stay
+  sequential because their stack-entry order determines teardown order.
+- `fast_json_loads` delegates to stdlib: measured slower at every payload
+  size (PyObject materialization dominates). The Rust JSON writer is the
+  fast path and is used in response serialization.
+- The Hyper host is experimental; `serve()` defaults to uvicorn. See
+  `docs/migration.md` for the known-differences table.
+
+## Commit style
+
+Conventional commits (`feat:`, `fix:`, `perf:`, `chore:`, `docs:`).
+Parity bugs: `fix:` + differential regression test. Perf changes:
+`perf:` + bench numbers in the commit message or README table refresh.