Crate http_extract

Expand description

Strict, trust-aware extraction of HTTP request metadata.

This crate operates primarily on http types and does not require a web framework, Tower, tracing, or OpenTelemetry. An opt-in axum feature adds only transport-peer extraction from Axum request extensions. Forwarding fields are never trusted implicitly.

The crate root exposes small synchronous extractors for coherent field responsibilities. Applications compose only the functions they need at their framework boundary; this crate does not impose a request-context aggregate or an asynchronous adapter. Cargo features gate field-specific APIs; disabling default features leaves the shared Header helpers and Error available, and enabling a feature exposes only its documented API and dependencies.

§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().

Feature/API family	Purpose
`api_key`	`X-API-Key`, then `Api-Key` fallback
`authority`	URI authority and strict `Host` extraction
`authorization`	Raw Authorization plus lightweight Bearer/Basic scheme routing
`client_ip`	Socket-peer helpers and default/custom Header selection
`client_ip_headers`	Common provider and proxy client-IP fields
`content_type`	Strict `Content-Type` parsing into `mime::Mime`
`forwarded`	RFC 7239 `Forwarded` `for=` IP chains
`request_id`	`X-Request-Id`, then `Request-Id` fallback
`x_forwarded`	`X-Forwarded-For` and `X-Forwarded-Proto` parsing
`header`	Strict singular-field helpers and append-without-replace utility

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:

RFC 7239 Forwarded;
X-Forwarded-For;
X-Real-IP;
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.

Both functions return raw Header assertions. Security-sensitive consumers such as rate limiters should first verify the socket peer and use only a Header that a trusted proxy overwrites. extract_peer_ip returns an out-of-band socket peer; with the optional axum feature, extract_axum_peer_address and extract_axum_peer_ip read Axum’s ConnectInfo<SocketAddr> extension.

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.

Structs§

HeaderMap: A specialized multimap for header names and values.
HeaderName: Represents an HTTP header field name
HeaderValue: Represents an HTTP header field value.
Request: Represents an HTTP request.

Enums§

ClientIpHeader: A supported client IP Header and its parsing rule.
Error: An error produced while extracting request metadata.

Constants§

API_KEY: The fallback Api-Key field name.
BASIC_SCHEME: The Basic scheme.
BEARER_SCHEME: The Bearer scheme.
CF_CONNECTING_IP: The CF-Connecting-IP field name.
CLIENT_IP_HEADERS: The default Header lookup order used by extract_client_ip.
CLOUDFRONT_VIEWER_ADDRESS: The CloudFront-Viewer-Address field name.
FLY_CLIENT_IP: The Fly-Client-IP field name.
FORWARDED: The standardized Forwarded field name from RFC 7239, Section 4.
REQUEST_ID: The fallback Request-Id field name.
SCHEME_SEPARATOR: The space character that separates the scheme from the credentials.
TRUE_CLIENT_IP: The True-Client-IP field name.
X_API_KEY: The preferred X-API-Key field name.
X_ENVOY_EXTERNAL_ADDRESS: The X-Envoy-External-Address field name.
X_FORWARDED_FOR: The de facto, non-IETF X-Forwarded-For field name.
X_FORWARDED_PROTO: The de facto, non-IETF X-Forwarded-Proto field name.
X_REAL_IP: The X-Real-IP field name.
X_REQUEST_ID: The preferred X-Request-Id field name.

Functions§

append_header_value: Append one already validated field value without replacing existing values.
extract_axum_peer_address: Extract the Axum transport peer stored in a request extension.
extract_axum_peer_ip: Extract the Axum socket peer IP stored in a request extension.
extract_client_ip: Extract a raw client IP assertion using the default field order.
extract_client_ip_with_headers: Extract a raw client IP assertion using caller-defined fields and order.
extract_header_api_key: Extract an API key from request fields.
extract_header_authority: Extract a strict, singular, syntactically valid Host authority.
extract_header_authorization: Extract the singular Authorization field as text.
extract_header_basic_credentials: Extract raw Basic credentials from the Authorization field.
extract_header_bearer_token: Extract raw Bearer credentials from the Authorization field.
extract_header_cf_connecting_ip: Extract the raw, untrusted IP asserted by CF-Connecting-IP.
extract_header_cloudfront_viewer_address: Extract an untrusted client IP from AWS CloudFront’s CloudFront-Viewer-Address IP:port value.
extract_header_content_type: Extract and parse a singular Content-Type field as a media type.
extract_header_fly_client_ip: Extract the raw, untrusted IP asserted by Fly-Client-IP.
extract_header_forwarded_for: Extract RFC 7239 Forwarded for= values as an untrusted IP chain.
extract_header_request_id: Extract a request ID from request fields.
extract_header_true_client_ip: Extract an untrusted client IP asserted by True-Client-IP.
extract_header_x_envoy_external_address: Extract an untrusted client IP asserted by Envoy’s X-Envoy-External-Address.
extract_header_x_forwarded_for: Extract all X-Forwarded-For field lines as an untrusted asserted IP chain.
extract_header_x_forwarded_proto: Extract all X-Forwarded-Proto field lines as untrusted protocol tokens.
extract_header_x_real_ip: Extract the raw, untrusted IP asserted by X-Real-IP.
extract_peer_address: Return a transport peer address supplied out-of-band by an adapter.
extract_peer_ip: Return the IP address of a transport peer supplied out-of-band by an adapter.
extract_request_api_key: Extract an API key from a complete request.
extract_request_authority: Extract the authority from a complete request.
extract_request_authorization: Extract the raw Authorization field from a complete request.
extract_request_basic_credentials: Extract raw Basic credentials from a complete request.
extract_request_bearer_token: Extract raw Bearer credentials from a complete request.
extract_request_cf_connecting_ip: Extract CF-Connecting-IP from a complete request.
extract_request_cloudfront_viewer_address: Extract CloudFront-Viewer-Address from a complete request.
extract_request_content_type: Extract and parse Content-Type from a complete request.
extract_request_fly_client_ip: Extract Fly-Client-IP from a complete request.
extract_request_forwarded_for: Extract the untrusted Forwarded for= IP chain from a complete request.
extract_request_request_id: Extract a request ID from a complete request.
extract_request_true_client_ip: Extract True-Client-IP from a complete request.
extract_request_x_envoy_external_address: Extract X-Envoy-External-Address from a complete request.
extract_request_x_forwarded_for: Extract the untrusted X-Forwarded-For chain from a complete request.
extract_request_x_forwarded_proto: Extract untrusted X-Forwarded-Proto tokens from a complete request.
extract_request_x_real_ip: Extract X-Real-IP from a complete request.
extract_rightmost_forwarded: Extract the rightmost Forwarded for= IP address from a header.
extract_rightmost_x_forwarded_for: Extract the rightmost X-Forwarded-For IP address from a header.
extract_single_header_text: Extract a singular field as text without silently discarding invalid bytes.
extract_single_header_value: Extract a field value only when the field has at most one field line.