hyper-util

hyper-util fills in the gaps that hyper deliberately leaves out. hyper 1.0 is a minimal, low-level HTTP library by design, pushing concerns like connection pooling, automatic HTTP/1-or-2 protocol detection, graceful shutdown, and runtime I/O glue into separate crates — hyper-util is the official one, maintained by the same hyperium team.

It provides a legacy-style high-level client with connection pooling and proxy support, an auto server builder that negotiates HTTP/1.1 or HTTP/2 per connection, Tokio-based I/O and executor adapters that implement hyper’s Io and Executor traits, and Tower Service glue. It is a near-mandatory dependency for any production service built directly on hyper rather than a full framework like axum or actix-web.

What You Get

• A legacy high-level HTTP client (client::legacy::Client) with connection pooling, keep-alive, and HTTP/SOCKS proxy support
• An auto server builder that transparently negotiates HTTP/1.1 or HTTP/2 per incoming connection
• Tokio-based adapters (TokioIo, TokioExecutor, TokioTimer) implementing hyper’s Io, Executor, and Timer traits
• Graceful shutdown helpers (server::graceful::GracefulShutdown) for draining in-flight connections
• Tower Service glue (service::TowerToHyperService) to bridge Tower middleware into hyper’s connection handling

Common Use Cases

• Building a production HTTP client on top of hyper that needs connection pooling instead of dialing a new connection per request
• Writing a server that must serve both HTTP/1.1 and HTTP/2 clients on the same listener without manual protocol sniffing
• Wiring hyper’s low-level connection I/O to the Tokio runtime via TokioIo/TokioExecutor when hand-rolling a server or client
• Integrating Tower middleware (retries, timeouts, load balancing) into a hyper-based service using the service glue module

Under The Hood

Architecture hyper-util is organized around the same seams hyper itself exposes: client/legacy (pooled client with connect/ submodules for DNS, TCP, and proxy tunneling), server/conn/auto (protocol-detecting server builder plus graceful shutdown), rt (the Tokio adapters bridging hyper’s abstract Io/Executor/Timer traits to real Tokio types), and service (Tower interop); each module is feature-gated independently (client, client-legacy, client-pool, server-auto, tokio, etc.) so consumers only compile the pieces they use, keeping the dependency-light philosophy of the hyper ecosystem intact while still offering a batteries-included experience via the full feature.

Tech Stack Rust edition 2024 (MSRV 1.85), built directly on hyper 1.9, http/http-body 1.0, bytes, and tokio (optional, feature-gated), with tower-service/tower-layer for Tower interop, socket2 for low-level socket options in the legacy client’s connection pool, and platform-specific dependencies (system-configuration on macOS, windows-registry on Windows) for reading OS-level proxy settings.

Code Quality The crate has a large, well-organized module tree mirroring its feature flags, extensive doc comments with runnable examples gated behind required-features in [[example]] blocks (client.rs, server.rs, server_graceful.rs), and a dev-dependency set (tokio-test, tower-test, pretty_env_logger) indicating a real integration-test suite exercising pooling, graceful shutdown, and protocol negotiation; as an official hyperium crate it inherits hyper’s CI discipline around MSRV and feature-matrix testing.

API Design The API leans on Rust’s trait system to stay decoupled from any specific async runtime in principle, though in practice almost every feature assumes Tokio (rt::tokio module, tokio feature flag), which keeps the ergonomics high for the common case at the cost of being less runtime-agnostic than the name suggests; feature flags are granular enough to avoid pulling in unused code, but new users need to know which combination (client-legacy + http1 + tokio, for instance) to enable, which is documented but adds a learning step beyond a single full = true.