spikard-http

High-performance HTTP server for Spikard with a complete tower-http middleware stack, JSON Schema validation, and cross-language handler execution.

Status & Badges

Features

Axum-based routing - Fast, ergonomic router with zero-allocation path matching
Tower middleware stack - Compression (gzip/brotli), rate limiting, timeouts, CORS, request IDs, auth
JSON Schema validation - Request/response validation against JSON schemas
Cross-language handlers - Handler trait for Python, Node.js, Ruby, PHP, and WASM bindings
OpenAPI generation - Automatic OpenAPI 3.1 and AsyncAPI spec generation
WebSocket & SSE support - Real-time bidirectional and server-sent event communication
Graceful shutdown - Proper shutdown handling with in-flight request completion
Static file serving - Efficient static file serving with caching support

Architecture

Components

router - Translates route metadata into strongly typed Rust handlers with path extraction
validation - Enforces JSON schemas for headers, cookies, query params, and request bodies
server - Wraps Axum/Tokio bootstrapping and exposes configuration via ServerConfig
handler - Language-agnostic Handler trait for FFI integration
middleware - Tower middleware stack with sensible defaults

Performance

Native Rust implementation using Axum and tower-http middleware. Benchmarks on macOS (Darwin 24.6.0) with 50 concurrent connections:

Workload	Throughput	Mean Latency	P95 Latency	P99 Latency	Memory
Baseline	165,228 req/s	0.30ms	0.36ms	0.45ms	17.4 MB
JSON Bodies	pending	pending	pending	pending	pending
Multipart Forms	pending	pending	pending	pending	pending
URL-Encoded	pending	pending	pending	pending	pending

Architecture Highlights:

Zero-overhead abstraction: Handler trait with Pin<Box<dyn Future>> enables language-agnostic integration
Tower middleware stack: Compression, rate limiting, timeouts, and CORS with minimal latency impact
Efficient routing: Axum's path matching with zero allocations for static routes
Low memory baseline: ~17 MB with efficient memory pooling and minimal allocations

The native Rust implementation provides ~38% higher throughput compared to Python bindings while maintaining even lower latency characteristics. Startup time averages 1.01s with first response in 908ms.

Full benchmark methodology: tools/benchmark-harness/

Installation

[dependencies]
spikard-http = "0.2.0"
tokio = { version = "1", features = ["full"] }
axum = "0.8"

Optional Features

[dependencies]
spikard-http = { version = "0.2.0", features = ["di"] }

di - Enables dependency injection support

Quick Start

use spikard_http::{ServerConfig, start_server};
use spikard_core::{RouteConfig, Request, Response};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig {
        host: "0.0.0.0".to_string(),
        port: 8080,
        ..Default::default()
    };

    // Create routes with schemas
    let routes = vec![
        RouteConfig::get("/health")
            .handler("health", |_req| async {
                Ok(Response::new(200).with_body(r#"{"status": "ok"}"#))
            }),
    ];

    start_server(config, routes).await?;
    Ok(())
}

Middleware Stack

The default middleware stack (in order):

Compression - gzip/brotli compression (configurable)
Request ID - Unique request tracking
Timeout - Request timeout enforcement
Rate Limit - Per-IP rate limiting (if configured)
Authentication - JWT/Bearer token validation (if configured)
User-Agent - User agent parsing and validation
CORS - Cross-origin resource sharing (if configured)
Handler - Your application logic

See ServerConfig documentation for detailed configuration options.

Validation

Validate requests against JSON schemas:

use spikard_http::validation::ValidateRequest;
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "age": { "type": "integer", "minimum": 0 }
    },
    "required": ["name"]
});

request.validate_body(&schema)?;

Development

Build with cargo build -p spikard-http or task build:http
Execute tests and fixture validations via cargo test -p spikard-http
Benchmarks: tools/benchmark-harness/
When altering schemas, sync the Python fixtures and regenerate bindings before rerunning the CLI

spikard-http 0.8.3