http-extract

Strict, synchronous extraction of HTTP request metadata using http types. The default API is framework-independent; an optional axum feature adds socket-peer extraction from ConnectInfo request extensions.

The crate keeps transport facts separate from Header assertions. Values from Forwarded, X-Forwarded-*, and provider-specific client-IP fields are raw and untrusted until the deployment establishes an explicit proxy trust boundary.

Install

Default features provide all common extractors:

[dependencies]
http-extract = "0.1"

Select only the API families an application uses:

[dependencies]
http-extract = { version = "0.1", default-features = false, features = [
  "authority",
  "content-type",
] }

API

Header functions contain the parsing logic. Matching Request functions are convenience wrappers that delegate through request.headers().

See the feature and API map for exact function names and return types.

Client IP boundary

extract_client_ip checks these Header sources in order:

1. RFC 7239 Forwarded;
2. X-Forwarded-For;
3. X-Real-IP;
4. CF-Connecting-IP.

This standard-first order is a library convention, not an RFC-defined precedence or trust policy. extract_client_ip_with_headers accepts an explicit ordered slice of ClientIpHeader values for deployment-specific selection. A malformed first-present source fails instead of falling through.

extract_socket_ip reads Axum ConnectInfo<SocketAddr> when available, then a direct SocketAddr request extension; it never reads Headers. extract_proxy_client_ip checks the Header order above and falls back to that peer only when all Headers in CLIENT_IP_HEADERS are absent. Header-derived values remain untrusted unless the deployment enforces a trusted-proxy boundary.

Read the client IP trust boundary before using a Header-derived IP for authorization, rate limiting, or auditing.

Features

Default features are api-key, authority, authorization, client-ip, client-ip-headers, content-type, forwarded, request-id, and x-forwarded.

• client-ip enables its Header parsing dependencies;
• content-type enables the optional mime dependency;
• non-default axum enables client-ip and the optional Axum dependency;
• --no-default-features leaves only Error and the generic Header helpers.

The default normal dependency tree does not include Axum, Tower, Tokio, tracing, or OpenTelemetry. See the feature guide for copyable configurations.

Errors and sensitive values

Missing optional metadata returns Ok(None). Duplicate, non-text, and invalid fields return the crate-wide Error; errors identify only the field name and category, never its value.

Authorization credentials and API keys are returned only by their explicit extractors. Do not log or echo those values, cookies, request bodies, complete query strings, or raw forwarding fields.

Standards

The crate implements narrow extraction behavior, not complete protocol or authentication implementations:

• HTTP Semantics, RFC 9110, including field semantics, authority, and Content-Type;
• Forwarded, RFC 7239, limited to continuous for= IP chains and subject to its security considerations;
• Bearer, RFC 6750 Section 2.1 and Basic, RFC 7617 Section 2, used only for lightweight scheme recognition without authentication or Basic decoding.

X-Forwarded-* and provider-specific client-IP fields are de facto or vendor conventions, not IETF standards. See standards and compatibility for the supported boundary.

Axum example

The runnable Axum example demonstrates peer extraction, request metadata, client-IP selection, error handling, and safe observable output:

cargo run --example axum-demo --features axum

The full guide is available in the docs mdBook sources. The crate declares Rust 1.96.0 and is licensed under MIT or Apache-2.0.