superduperfastapi 0.1.1

A from-scratch FastAPI-compatible framework with a Rust core.

superduperfastapi

superduperfastapi is a from-scratch FastAPI-compatible framework with a Rust core. The target is a drop-in replacement for existing FastAPI apps, with the hot request path handled by Rust wherever this implementation can preserve FastAPI behavior.

This project is in pre-school-alpha phase. Expect bugs, missing edge cases, rough packaging, and surprising failures. Do not treat it as production-ready without your own compatibility and load testing.

This project was built with Codex's /goal feature: the implementation work was tracked as a sequence of explicit performance and compatibility goals, with audits and benchmark artifacts generated for each goal.

When present locally, the upstream FastAPI checkout in references/fastapi is a behavior and test reference only. Runtime code must not import upstream FastAPI.

Install

From PyPI, once published:

uv pip install superduperfastapi

Local development build:

.venv/bin/python -m pip install maturin
.venv/bin/maturin develop

Package build:

.venv/bin/maturin build --release

The package depends on Pydantic v2. It does not depend on upstream FastAPI. The wheel includes the superduperfastapi package plus local fastapi and starlette compatibility shims for drop-in imports.

Drop-In Imports

Native import:

from superduperfastapi import FastAPI

FastAPI-compatible import:

from fastapi import FastAPI

In this repository, PYTHONPATH=python makes fastapi resolve to python/fastapi, a compatibility shim that re-exports superduperfastapi. The reference runner verifies this before executing upstream tests.

Minimal App

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    count: int

@app.post("/items")
def create_item(item: Item):
    return {"name": item.name, "total": item.count + 1}

Rust Server

The Rust HTTP/1.1 server is exposed through the local core module:

from superduperfastapi._core import core

core.serve(app, "127.0.0.1", 8000, 0)

core.serve_once(app) is used by tests for one-request loopback checks.

Fast Path Coverage

SuperDuperFastAPI builds Rust route specs for supported routes and dispatches those routes through the Rust core. Covered fast-path areas include:

• route matching with a Rust route index/trie
• path, query, header, and cookie primitive params
• primitive application/x-www-form-urlencoded form params
• primitive multipart File() bytes params, UploadFile params, and repeated file lists
• JSON request bodies through Pydantic-core validators
• response-model validation and serialization through Pydantic-core
• direct Rust JSON response construction for plain JSON-compatible returns
• built-in JSON, HTML, plain text, redirect, streaming, and file response classes
• sync and async endpoints/dependencies for the covered dependency graph
• request-scope sync/async generator dependencies with teardown on the native path
• Security(...) dependencies for API-key, HTTP bearer/basic, OAuth2 password-bearer, and scoped SecurityScopes helpers
• simple StaticFiles(directory=...) mounts
• direct Response returns, background tasks, request injection, and app state
• built-in CORS, GZip, trusted-host, and HTTPS redirect middleware
• user @app.middleware("http") routes through Rust dispatch
• custom add_middleware(...) ASGI middleware through the Rust bridge
• Rust-side 422 response construction for validation errors

The compatibility matrix records whether each covered feature is passed, fallback, unsupported, or broken.

Benchmarks

Benchmark summaries are written under benchmarks/results/.

benchmark	summary
plain JSON	benchmarks/results/bombardier_summary.md
CRUD endpoint matrix	benchmarks/results/crud_bombardier_summary.md
dependency graph matrix	benchmarks/results/dependency_bombardier_summary.md
multipart upload matrix	benchmarks/results/multipart_bombardier_summary.md
response model matrix	benchmarks/results/response_model_bombardier_summary.md
security dependency matrix	benchmarks/results/security_bombardier_summary.md
route count scaling	benchmarks/results/route_count_bombardier_summary.md
validation-heavy payloads	benchmarks/results/validation_bombardier_summary.md
OpenAPI generation	benchmarks/results/openapi_generation_summary.md
JSONable response matrix	benchmarks/results/jsonable_bombardier_summary.md
user middleware matrix	benchmarks/results/middleware_bombardier_summary.md

Run a benchmark:

.venv/bin/python benchmarks/run_validation_bombardier.py
.venv/bin/python benchmarks/run_dependency_bombardier.py
.venv/bin/python benchmarks/run_openapi_generation.py

Examples

Runnable examples live in examples/. Each example is a standalone uv run --script file with inline dependencies that install superduperfastapi from PyPI:

uv run --script examples/basic.py
uv run --script examples/async_await.py
uv run --script examples/middleware.py
uv run --script examples/rust_server_once.py

Compatibility Audits

.venv/bin/python scripts/audit_fastapi_compatibility.py
.venv/bin/python scripts/audit_middleware_fast_path.py
.venv/bin/python scripts/audit_validation_errors.py
.venv/bin/python scripts/audit_openapi_parity.py
.venv/bin/python scripts/audit_packaging.py
.venv/bin/python scripts/audit_goal_progress.py
.venv/bin/python scripts/classify_fastapi_features.py

These write Markdown and JSON evidence into benchmarks/results/. The feature matrix exits non-zero if any generated row is broken.

Verification

Local unit suite:

PYTHONPATH=python .venv/bin/python -m unittest discover -s tests

Rust core tests:

cargo test --manifest-path rust/superduperfastapi-core/Cargo.toml

Full recursive FastAPI reference subset:

.venv/bin/python scripts/run_reference_subset.py references/fastapi/tests

Current verified reference result: 3117 passed, 14 skipped, 5 xfailed.

Publishing

Publishing is handled by .github/workflows/publish-pypi.yml. It publishes only when a pull request is merged with the release label. The published package name is superduperfastapi, and the version is read from pyproject.toml.

Configure PyPI trusted publishing for the GitHub repository before running the workflow. The workflow runs on GitHub releases and can also be started manually with workflow_dispatch.

Current Gaps

The long-term target is maximum request-path performance while preserving drop-in FastAPI behavior. Remaining work includes deeper dependency graph optimization, response-model hot-path tuning, reducing any future intentional Python fallback areas, and hardening production packaging.