fastapi_rust

TL;DR

The Problem: Rust web frameworks either sacrifice developer ergonomics for performance (raw hyper) or hide allocations behind layers of abstraction (Axum + Tower). None leverage structured concurrency for cancel-correct request handling, and most require a massive dependency tree.

The Solution: fastapi_rust brings FastAPI's intuitive, type-driven API design to Rust with zero-copy HTTP parsing, compile-time route validation, and first-class integration with asupersync for structured concurrency and deterministic testing.

Why fastapi_rust?

Quick Example

use fastapi::prelude::*;

#[derive(Serialize, Deserialize, JsonSchema)]
struct Item {
    id: i64,
    name: String,
    price: f64,
}

#[get("/items/{id}")]
async fn get_item(cx: &Cx, id: Path<i64>) -> Json<Item> {
    cx.checkpoint()?;  // Cancellation-safe yield point

    Json(Item {
        id: id.0,
        name: "Widget".into(),
        price: 29.99,
    })
}

#[post("/items")]
async fn create_item(cx: &Cx, item: Json<Item>) -> Response {
    // Automatic JSON deserialization with validation
    // Wrong Content-Type -> 415
    // Parse error -> 422 with detailed location
    // Payload too large -> 413
    Response::created().json(&item.0)
}

#[get("/search")]
async fn search(
    cx: &Cx,
    q: Query<SearchParams>,           // ?q=...&limit=...
    auth: Header<Option<Bearer>>,     // Optional auth header
) -> Result<Json<Results>, HttpError> {
    // All extraction happens automatically
    // Wrong types -> compile error
    // Missing required -> 422 response
}

fn main() {
    let app = App::builder()
        .title("My API")
        .version("1.0.0")
        .route(get_item)
        .route(create_item)
        .route(search)
        .middleware(RequestIdMiddleware::new())
        .middleware(Cors::permissive())
        .build();

    // Run with asupersync (TCP server coming soon)
    // asupersync::block_on(app.serve("0.0.0.0:8000"));
}

Design Philosophy

1. Extract Spec, Never Translate

We study FastAPI's behavior and ergonomics, then implement idiomatically in Rust. No line-by-line Python translation - Rust has better tools for these problems:

• Python decorators -> Rust procedural macros
• Pydantic validation -> Compile-time type checking + serde
• ASGI lifecycle -> Structured concurrency regions
• Runtime reflection -> Compile-time code generation

2. Zero-Cost Abstractions

3. Cancel-Correct by Default

Every request handler runs in an asupersync region. Client disconnects, timeouts, and shutdowns trigger graceful cancellation:

Connection Accepted
    |
    v
+-----------------------------------------------+
|  Request Region (owns all request work)       |
|  +-------------------------------------------+|
|  |  Handler Task                             ||
|  |  +-- Dependency Task (DB query)           ||
|  |  +-- Dependency Task (cache lookup)       ||
|  |  +-- Background Task (logging)            ||
|  +-------------------------------------------+|
|                                               |
|  Region close waits for ALL tasks to finish  |
+-----------------------------------------------+
    |
    v
Response Sent (only after region quiescent)

No orphaned tasks. Client disconnect -> cancel region -> all tasks cleaned up.

4. Minimal Dependencies

Explicitly avoided: Tokio, Hyper, Axum, Tower, runtime-reflection crates. Total dependency count: 3 crates vs. 80+ for Axum.

How fastapi_rust Compares

When to Use fastapi_rust

• You need cancel-correct request handling (graceful shutdown, timeouts)
• You want compile-time route validation
• You're building with asupersync for structured concurrency
• You want deterministic tests for concurrent code
• You're familiar with FastAPI and want similar ergonomics in Rust

When to Consider Alternatives

• You need production-proven stability today (fastapi_rust is v0.1.0)
• You require WebSocket support (coming in Phase 2)
• You have existing Tokio-based infrastructure
• You need the massive ecosystem of Tower middleware

Installation

Add to Cargo.toml

[dependencies]
fastapi = "0.1.0"
asupersync = "0.1.0"
serde = { version = "1", features = ["derive"] }

From Source

git clone https://github.com/Dicklesworthstone/fastapi_rust.git
cd fastapi_rust
cargo build --release

Requirements

• Rust 1.85+ (2024 edition)
• asupersync (co-developed runtime)

Architecture

+-------------------------------------------------------------------+
|                         fastapi (facade)                           |
|   Re-exports all public types, prelude module                      |
+-------------------------------------------------------------------+
        |           |           |           |           |
        v           v           v           v           v
+-----------+ +-----------+ +-----------+ +-----------+ +-----------+
|   core    | |   http    | |  router   | |  macros   | |  openapi  |
|           | |           | |           | |           | |           |
| - Request | | - Parser  | | - Trie    | | - #[get]  | | - Schema  |
| - Response| | - Body    | | - Match   | | - #[post] | | - Builder |
| - Context | | - Query   | | - Registry| | - Derive  | | - Spec    |
| - Extract | | - Headers | |           | |           | |           |
| - Depends | | - Writer  | |           | |           | |           |
| - Error   | | - Server  | |           | |           | |           |
| - Middle. | | - Stream  | |           | |           | |           |
| - Logging | |           | |           | |           | |           |
| - Testing | |           | |           | |           | |           |
| - Shutdown| |           | |           | |           | |           |
+-----------+ +-----------+ +-----------+ +-----------+ +-----------+
        |
        v
+-------------------------------------------------------------------+
|                         asupersync                                 |
|   Structured concurrency - Cx - Regions - Budgets - Lab           |
+-------------------------------------------------------------------+

Crate Overview

Extractors

Extract typed data from requests declaratively:

use fastapi::prelude::*;

#[get("/users/{id}")]
async fn get_user(
    cx: &Cx,                           // Capability context (required)
    id: Path<i64>,                     // Path parameter: /users/123
    q: Query<SearchParams>,            // Query string: ?q=...&limit=...
    auth: Header<Authorization>,       // Required header
    accept: Header<Option<Accept>>,    // Optional header
) -> Result<Json<User>, HttpError> {
    // Types declare what you need - framework handles extraction
    // Wrong types -> compile error
    // Missing required -> 422 with FastAPI-compatible error
}

#[post("/items")]
async fn create(
    cx: &Cx,
    item: Json<CreateItem>,            // JSON body
) -> Result<Response, HttpError> {
    // 415 if wrong Content-Type
    // 413 if payload too large (configurable)
    // 422 if parse error (with location path)
}

Available Extractors

Middleware

Composable middleware with onion model execution:

use fastapi::prelude::*;

// Built-in middleware
let app = App::builder()
    .middleware(RequestIdMiddleware::new())      // Add X-Request-Id
    .middleware(RequestResponseLogger::default()) // Log all requests
    .middleware(Cors::permissive())               // CORS handling
    .middleware(RequireHeader::new("X-API-Key")) // Require header
    .middleware(AddResponseHeader::new("X-Powered-By", b"fastapi_rust"))
    .build();

// Custom middleware
struct Timing;

impl Middleware for Timing {
    async fn before(&self, ctx: &RequestContext, req: &mut Request) -> ControlFlow {
        // Store start time in context
        ControlFlow::Continue
    }

    async fn after(&self, ctx: &RequestContext, req: &Request, mut resp: Response) -> Response {
        // Add X-Response-Time header
        resp
    }
}

Execution Order

Request -> MW1.before -> MW2.before -> MW3.before -> Handler
                                                        |
Response <- MW1.after <- MW2.after <- MW3.after <- Response

First registered runs first on the way in, last on the way out (onion model).

Dependency Injection

Request-scoped dependencies with caching:

use fastapi::prelude::*;

// Define a dependency
#[derive(Clone)]
struct DatabasePool { /* ... */ }

impl FromDependency for DatabasePool {
    type Error = HttpError;

    async fn from_dependency(ctx: &RequestContext, req: &mut Request) -> Result<Self, HttpError> {
        // Resolved once per request, cached for subsequent uses
        Ok(DatabasePool::connect().await?)
    }
}

// Use in handler
#[get("/users/{id}")]
async fn get_user(
    cx: &Cx,
    id: Path<i64>,
    db: Depends<DatabasePool>,  // Automatically resolved and cached
) -> Result<Json<User>, HttpError> {
    let user = db.fetch_user(id.0).await?;
    Ok(Json(user))
}

// Override for testing
let overrides = DependencyOverrides::new()
    .with::<DatabasePool>(MockDatabase::new());

Dependency Scopes

Testing

In-process testing without network I/O:

use fastapi::testing::*;

#[test]
fn test_get_item() {
    let client = TestClient::new(app);

    let resp = client.get("/items/42")
        .header("Authorization", "Bearer token")
        .send();

    assert_eq!(resp.status(), 200);

    let item: Item = resp.json();
    assert_eq!(item.id, 42);
}

#[test]
fn test_deterministic() {
    // Same seed = same execution order for concurrent operations
    let client = TestClient::with_seed(app, 12345);

    // Reproducible even with concurrent handlers
    let resp = client.post("/items")
        .json(&new_item)
        .send();

    assert_eq!(resp.status(), 201);
}

#[test]
fn test_with_overrides() {
    let overrides = DependencyOverrides::new()
        .with::<Database>(MockDatabase::new());

    let client = TestClient::new(app)
        .with_overrides(overrides);

    // Handler receives MockDatabase instead of real one
}

Assertion Helpers

use fastapi_core::{assert_status, assert_header, assert_json};

assert_status!(resp, 200);
assert_header!(resp, "Content-Type", "application/json");
assert_json!(resp, {"id": 42, "name": "Widget"});

Error Handling

FastAPI-compatible validation errors:

// Handler returns HttpError
#[get("/items/{id}")]
async fn get_item(id: Path<i64>) -> Result<Json<Item>, HttpError> {
    if id.0 < 0 {
        return Err(HttpError::unprocessable_entity()
            .detail("ID must be positive")
            .loc(["path", "id"]));
    }
    // ...
}

Error response format (FastAPI-compatible):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["path", "id"],
      "msg": "ID must be positive",
      "input": -1
    }
  ]
}

Built-in Error Types

Graceful Shutdown

Cancel-correct shutdown with configurable grace periods:

use fastapi::prelude::*;
use fastapi_core::shutdown::*;

let app = App::builder()
    .graceful_shutdown(GracefulConfig {
        grace_period: Duration::from_secs(30),
        force_timeout: Duration::from_secs(5),
    })
    .on_shutdown(|phase| async move {
        match phase {
            ShutdownPhase::GracePeriod => {
                // Stop accepting new connections
                // Wait for in-flight requests
            }
            ShutdownPhase::ForceClose => {
                // Cancel remaining requests
            }
        }
        Ok(())
    })
    .build();

Shutdown propagates through asupersync regions - no orphaned tasks.

Configuration

use fastapi::prelude::*;

let app = App::builder()
    // Metadata
    .title("My API")
    .version("1.0.0")
    .description("A sample API built with fastapi_rust")

    // Routes
    .route(get_item)
    .route(create_item)
    .route(delete_item)

    // Middleware (order matters)
    .middleware(RequestIdMiddleware::new())
    .middleware(Cors::new(CorsConfig {
        allow_origins: vec!["https://example.com".into()],
        allow_methods: vec![Method::Get, Method::Post],
        allow_headers: vec!["Authorization".into()],
        max_age: Some(3600),
    }))

    // Shared state
    .state(DatabasePool::new())
    .state(CacheClient::new())

    // Exception handlers
    .exception_handler(|err: DatabaseError| {
        HttpError::internal().detail(err.to_string())
    })

    // Lifecycle hooks
    .on_startup(|| async {
        println!("Starting up...");
        Ok(())
    })
    .on_shutdown(|_| async {
        println!("Shutting down...");
        Ok(())
    })

    // Build
    .build();

Troubleshooting

Common Issues

Debugging Tips

// Enable request logging
.middleware(RequestResponseLogger::new(LogConfig {
    log_bodies: true,
    log_headers: true,
}))

// Check route registration
app.routes().for_each(|r| println!("{} {}", r.method, r.path));

// Deterministic test reproduction
TestClient::with_seed(app, failing_seed)

Limitations

What fastapi_rust Doesn't Do (Yet)

Known Constraints

• Requires asupersync: Won't work with Tokio (by design)
• Rust 1.85+: Uses 2024 edition features
• Early development: API will change before v1.0
• No ecosystem: Can't use Tower middleware or Axum extractors

Development Status

Phase 0: [DONE] Foundation
         - Core types (Request, Response, Error)
         - Zero-copy HTTP parser
         - Extractor system
         - Middleware abstraction

Phase 1: [IN PROGRESS] TCP Server
         - asupersync I/O integration
         - Connection handling
         - Request lifecycle

Phase 2: [PLANNED] Router + Params
         - Radix trie routing
         - Path parameter extraction
         - Route conflict detection

Phase 3: [PLANNED] Validation
         - Derive macros
         - Error formatting

Phase 4: [PARTIAL] Dependency Injection
         - Basic DI working
         - Need: scopes, overrides

Phase 5: [PARTIAL] OpenAPI
         - Spec types defined
         - Need: generation from routes

Phase 6: [PLANNED] Advanced Features
         - File uploads
         - Streaming responses
         - Background tasks

FAQ

Why "fastapi_rust"?

It's a Rust web framework inspired by Python's FastAPI, preserving the type-driven API design while achieving native performance and cancel-correctness.

Why not use Tokio/Axum?

Tokio's spawn model makes cancel-correctness difficult - tasks can outlive their scope, leading to resource leaks and subtle bugs. asupersync's structured concurrency ensures all request-related work completes or cancels together.

Can I use this in production?

Not yet. This is v0.1.0 in active development. The HTTP server implementation is pending asupersync's I/O support.

How fast is it?

We haven't benchmarked yet (no TCP server), but the architecture is designed for:

• Zero allocations on the fast path
• Zero-copy request parsing
• No runtime reflection
• Pre-allocated buffers (4KB default)

Does it support async/await?

Yes, fully. All handlers, middleware, and extractors are async-native, built on asupersync's structured concurrency model.

Why the minimal dependency approach?

Each dependency is a maintenance burden, security surface, and compile-time cost. By keeping dependencies to 3 crates, we:

• Reduce build times significantly
• Have full control over behavior
• Avoid dependency conflicts
• Make auditing practical

How do validation errors compare to FastAPI?

Identical format. The same client code that handles FastAPI 422 responses will work with fastapi_rust:

{
  "detail": [
    {"type": "missing", "loc": ["body", "email"], "msg": "Field required"}
  ]
}

About Contributions

Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

MIT license. See LICENSE.

Related Projects