Crate http_handle

Expand description

Http Handle logo

§HTTP Handle (http-handle)

A Rust-based HTTP server for serving static websites.

• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines

§Architectural Overview

Use http-handle to serve static content fast, then scale to production policies without rewriting your core server path.

Follow this critical path:

Build and configure a server (Server / ServerBuilder).
Parse incoming HTTP requests into typed request data.
Generate and emit policy-aware HTTP responses.

§Feature List

Core Serving: Static file routing, MIME detection, custom 404 pages, and request/response primitives.
Operational Safety: Directory traversal protection, graceful shutdown, and configurable timeout handling.
Performance Paths: Sync + async serving, precompressed asset negotiation (br / gzip / zstd), and high-performance runtime mode.
Protocol Growth: HTTP/2 support and HTTP/3 profile/fallback policy primitives.
Enterprise Controls: TLS/mTLS policy, API key/JWT auth hooks, RBAC/ABAC adapters, and runtime config reload patterns.
Scale Features: Distributed rate limiting, tenant isolation, observability hooks, and runtime auto-tuning.

§Platform Support Matrix

http-handle is validated with portability conformance tests and CI coverage across Unix-like targets.

Platform	Status	Notes
macOS	Supported	Primary development workflow and CI coverage.
Linux	Supported	Production target for deployments and containers (validated on Ubuntu CI; Debian-compatible runtime assumptions).
Windows (MSVC)	Supported	Tier-1 target in the portability policy and CI matrix.
WSL (Windows Subsystem for Linux)	Supported	Uses Linux target behavior in WSL runtime.

§Installation

Add this to your Cargo.toml:

[dependencies]
http-handle = "0.0.4"

Minimum supported Rust version (MSRV): 1.88.0.

§Quick Start

Start with Server::new. Move to ServerBuilder when you need explicit policy controls.

use http_handle::Server;

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

The server listens on 127.0.0.1:8080 and serves files from ./public.

§Documentation

Primary API docs: docs.rs/http-handle
GitHub Pages mirror: https://sebastienrousseau.github.io/http-handle/

Local docs rendering (with docs.rs feature-gate badges):

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --open --all-features

Supporting docs:

Portability matrix: docs/PORTABILITY_MATRIX.md
Protocol support: docs/PROTOCOL_SUPPORT.md
Tutorials: docs/TUTORIALS.md
Architecture diagrams: docs/ARCHITECTURE.md
Benchmark reproducibility: docs/BENCHMARK_REPRODUCIBILITY.md
Benchmark claim governance: docs/BENCHMARK_CLAIM_GOVERNANCE.md
Security findings SLA policy: docs/SECURITY_SLA_POLICY.md
SLO/SLI and error-budget release policy: docs/SLO_SLI_POLICY.md
OpenTelemetry pipeline policy: docs/OTEL_PIPELINE_POLICY.md
Error causes and recovery: docs/ERRORS_AND_RECOVERY.md
Deprecation and migration policy: docs/DEPRECATION_POLICY.md
LTS and lifecycle policy: docs/LTS_POLICY.md
Supply chain and scorecard policy: docs/SLSA_POLICY.md, docs/SCORECARD_POLICY.md
Container hardening: docs/CONTAINER_SECURITY_POLICY.md
Distributed rate limiting: docs/DISTRIBUTED_RATE_LIMITING.md
Tenant isolation: docs/TENANT_ISOLATION.md
Runtime auto-tuning: docs/RUNTIME_AUTOTUNE.md
Release transition plan: docs/RELEASE_TRANSITION_v0.0.3.md
Next milestone execution plan: docs/EXECUTION_PLAN_v0.0.4.md
Branch issue progress tracker: docs/ISSUE_PROGRESS.md
Migration guide: docs/MIGRATION_GUIDE.md
Recipes: docs/RECIPES.md
Changelog: CHANGELOG.md

§Release Publication

crates.io publishing is tag-driven. After merge to main, publish by pushing a v* tag (for example v0.0.4) or by manually running the publish workflow.

§Examples

Run any example:

cargo run --example example_name

Start with these examples:

server_example: Build a server and serve a document root.
server_builder_example: Apply headers, CORS, and timeout policies.
feature_async_server: Run the async accept path.
feature_http2_server: Start the HTTP/2 path behind the http2 feature.
feature_enterprise_authorization: Enforce RBAC authorization for an HTTP request.
feature_runtime_autotune: Derive runtime limits from host profile.

Examples index: docs/EXAMPLES.md.

§Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

§License

This project is licensed under the GNU Affero General Public License v3.0.

§Acknowledgements

Special thanks to all contributors who have helped build the http-handle library.

Re-exports§

pub use error::ServerError;
pub use language::Language;
pub use language::LanguageDetector;
pub use server::ConnectionPool;
pub use server::Server;
pub use server::ServerBuilder;
pub use server::ShutdownSignal;
pub use server::ThreadPool;

Modules§

async_runtime: Async runtime helpers for panic-safe blocking execution.
async_serverasync: Async Tokio server entrypoints.
batchbatch: Batch processing utilities for concurrent file reads.
distributed_rate_limitdistributed-rate-limit: Distributed rate-limiting adapters and backend contracts.
enterpriseenterprise: Enterprise policy primitives for transport security, auth, telemetry, and runtime profiles.
error: Error model for runtime, parsing, and policy operations.
http2_serverhttp2: HTTP/2 server entrypoints (feature-gated).
http3_profilehttp3-profile: HTTP/3 production profile primitives.
language: Lightweight language detection with runtime-customizable patterns.
observability: Observability initialization helpers.
optimizedoptimized: Zero-allocation lookup helpers for hot-path operations.
perf_serverhigh-perf: High-performance async-first HTTP/1 server primitives.
protocol_state: Protocol byte-classification helpers for fuzzing and conformance tests.
request: HTTP/1.x request parsing and validation.
response: HTTP response construction and serialization.
runtime_autotuneautotune: Runtime auto-tuning helpers based on detected host resource profile.
server: Core HTTP server runtime.
streamingstreaming: Pull-based chunked streaming utilities for large files.
tenant_isolationmulti-tenant: Multi-tenant configuration isolation and secret-provider helpers.