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.

Public modules expose small synchronous extractors for one coherent field responsibility. Applications compose only the modules they need at their framework boundary; this crate does not impose a request-context aggregate or an asynchronous adapter. Cargo features gate field-specific modules; disabling default features leaves the shared header helpers and Error available, and enabling a feature exposes only its documented module 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 modules 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().

Module	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 module and API map for exact function names and return types.

§Client IP boundary

client_ip::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 module.

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.

Modules§

api_key: API-key extraction from the fixed X-API-Key and Api-Key fields.
authority: Request authority and Host field extraction.
authorization: Raw extraction of the sensitive Authorization field.
client_ip: Best-effort extraction of raw client IP assertions.
client_ip_headers: Direct extraction of common single-value client IP fields.
content_type: Content-Type extraction.
forwarded: Strict extraction of untrusted client IP assertions from Forwarded.
header: Strict building blocks for HTTP field maps.
request_id: Request ID extraction with fixed common field precedence.
x_forwarded: Parsing of untrusted X-Forwarded-* header conventions.

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§

Error: An error produced while extracting request metadata.