http-handle 0.0.5

Install

cargo add http-handle

Or add to Cargo.toml:

[dependencies]
http-handle = "0.0.5"

You need Rust 1.88.0 or later. Works on macOS, Linux, and Windows.

Overview

HTTP Handle is a lightweight static-file HTTP server library. Start with Server::new for quick prototyping, graduate to ServerBuilder for policy configuration, and switch to the async perf_server modes (high-perf / high-perf-multi-thread) for production throughput. Single binary, no runtime dependencies beyond libc.

v0.0.5 highlights:

• Static-file fast path: pre-serialised response cache + sendfile (Linux) hits 180 k req/s on Linux/arm64 (high-perf-mt mode) — see docs/PERFORMANCE.md.
• HTTP/1.1 keep-alive on both the sync and async server paths.
• Five start modes: start(), start_with_thread_pool(n), start_with_pooling(workers, max), start_with_graceful_shutdown(timeout), plus the async start_high_perf / start_high_perf_multi_thread.
• HTTP/2 (h2c) with feature = "http2".
• HTTP/3 ALPN routing + fallback chain with feature = "http3-profile" (QUIC termination is on the v0.2 roadmap; see docs/HTTP3_DESIGN.md).
• Enterprise primitives: TLS / mTLS policy, API-key + JWT verifiers, RBAC + ABAC, hot-reload TOML config, multi-tenant isolation, distributed rate limiter, OTLP-shaped telemetry.

Features

#![deny(unsafe_code)] at the crate root with three documented exceptions (libc::sendfile, two test-module env-var mutations).

Usage

use http_handle::Server;

fn main() -> std::io::Result<()> {
    let server = Server::new("127.0.0.1:8080", "./public");
    server.start()
}

For a complete capability-to-example matrix (basic server, builder pattern, graceful shutdown, feature-gated modules like async / HTTP/2 / streaming / enterprise auth), see docs/EXAMPLES.md.

Examples

30 one-word examples cover every public API and feature flag. Each is registered as a [[example]] target in Cargo.toml and follows a shared layout (animated spinner + checkmark output via examples/support.rs).

The friction-free way: scripts/example.sh knows the feature mapping, so you don't need to remember which Cargo flag each demo needs.

./scripts/example.sh hello              # core demos: no features
./scripts/example.sh enterprise         # auto-attaches --features enterprise
./scripts/example.sh dhat --release     # extra cargo flags pass through
./scripts/example.sh --list             # print every name

cargo run --example all builds and drives every demo in sequence.

Core (no features required):

Per Cargo feature flag (one example per flag — copy-paste ready):

Tooling / runners:

FAQ

Short answers to the questions that come up most often. The long-form matrix lives in docs/FAQ.md.

Which start* should I use? Default to Server::start() for prototyping. For production: start_with_pooling(workers, max_conns) on the sync path, or start_high_perf_multi_thread(server, limits, None) on the async path. The async multi-thread mode is the throughput leader on every Linux row in docs/PERFORMANCE.md.

When does sync win, and when does async win? Sync's thread-per-connection model is competitive on memory-rich hosts with zero per-request I/O wait. Async (high-perf / high-perf-mt) wins on memory-constrained hosts, mixed-I/O workloads (DB / upstream awaits), and any deployment where the OS thread cap matters.

Are the perf numbers realistic for my workload? They're upper bounds for a small static body over loopback. The Linux row (180 k req/s on high-perf-mt) is more representative for production than the macOS row because it tests the real epoll networking path. Reproduce with scripts/load_test.sh (host) or scripts/linux_bench.sh (container).

Can I run this over HTTPS? Not in-process today — enterprise::TlsPolicy is configuration-only. Terminate TLS at a reverse proxy (nginx, Caddy, ALB) and proxy plaintext HTTP/1.1 or h2c to http-handle over loopback. In-process rustls termination is on the v0.1 roadmap.

What about HTTP/3? ALPN routing + fallback chain ship as feature = "http3-profile". QUIC termination + h3 frames are deferred to v0.2 (design proposal in docs/HTTP3_DESIGN.md).

Can I plug in my own request handler? Not yet — the crate is a static-file server with configurable policies. A request-handler trait is on the v0.1 roadmap. Today, run http-handle for /static/* and a dynamic framework (axum, actix-web) for the rest.

error: target 'enterprise' requires the features: 'enterprise' — how do I run feature-gated examples? Use the wrapper: ./scripts/example.sh <name>. It auto-resolves the right --features flag. Or copy the literal command from the ## Examples table above.

How does the response cache work? v0.0.5 added a pre-serialised (head_prefix, body) cache on the high-perf static-file fast path, keyed by (canonical_path, mtime, file_len), capped at 256 entries ~16 MiB total. Hits skip the syscall + format work; the per-request cost on a hit is one Connection: header format and one write_all. Above-threshold files (>= sendfile_threshold_bytes) skip the cache entirely so the OOM guard remains intact.

For deployment patterns (nginx, Kubernetes), security model (rate limiter, traversal protection, body cap), tuning knobs, and 20+ more answers, see docs/FAQ.md.

Migrating from 0.0.4 → 0.0.5

Request::headers changed from HashMap<String, String> to Vec<(String, String)> for lower per-request allocation pressure and faster lookup at typical header counts. The Request::header(name) accessor is unchanged; only direct construction and iteration are affected.

// before (0.0.4)
let mut headers = std::collections::HashMap::new();
headers.insert("content-type".to_string(), "text/plain".to_string());
let request = Request {
    method: "GET".into(),
    path: "/".into(),
    version: "HTTP/1.1".into(),
    headers,
};

// after (0.0.5)
let request = Request {
    method: "GET".into(),
    path: "/".into(),
    version: "HTTP/1.1".into(),
    headers: vec![("content-type".into(), "text/plain".into())],
};

See CHANGELOG.md for the full breaking-change list.

Development

cargo build        # Build the project
cargo test         # Run all tests
cargo clippy       # Lint with Clippy
cargo fmt          # Format with rustfmt

See CONTRIBUTING.md for setup, signed commits, and PR guidelines.

THE ARCHITECT ᛫ Sebastien Rousseau THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

License

Dual-licensed under Apache 2.0 or MIT, at your option.