Struct HttpRequest 

pub struct HttpRequest {
    pub method: Method,
    pub path: ByteStr,
    pub headers: HeaderMap,
    pub body: Bytes,
    pub path_params: RouteParams,
    pub extensions: Extensions,
    /* private fields */
}

HTTP request wrapper

The path and body are Bytes-backed, so cloning a request is a handful of refcount bumps rather than a deep copy of the target and payload.

Fields

method: Method

The request method.

Was a String. An unrecognized token is carried as Method::Other rather than rejected here; routing answers it with 404 (crate::Error::RouteNotFound) since no route can match the token.

path: ByteStr

The raw request target, query string included.

Was a String. A ByteStr so it can be a slice of the connection read buffer once the serve path moves onto armature-h1; Deref<Target = str> keeps &req.path working wherever a &str is wanted.

headers: HeaderMap

Request headers stored in a SmallVec-backed HeaderMap.

For typical requests (<12 headers) this is stored inline on the stack, avoiding the per-request HashMap heap allocation on the read path. The API is HashMap-compatible (get/insert/iter/contains_key/…), with case-insensitive header name lookup.

body: Bytes

The request body.

Was a Vec<u8> shadowed by an optional Bytes that could disagree with it. One field, always authoritative.

path_params: RouteParams

extensions: Extensions

Type-safe extensions for storing application state.

Use this to pass typed data to handlers without DI container lookups. Access via the State<T> extractor for zero-cost state retrieval.

Implementations

impl HttpRequest

Extension methods for HttpRequest to support content negotiation.

pub fn accept(&self) -> Accept

Get the Accept header parsed into media types.

pub fn accept_language(&self) -> AcceptLanguage

Get the Accept-Language header parsed into language tags.

pub fn accept_encoding(&self) -> AcceptEncoding

Get the Accept-Encoding header parsed into encodings.

pub fn accept_charset(&self) -> AcceptCharset

Get the Accept-Charset header parsed into charsets.

pub fn accepts(&self, media_type: &MediaType) -> bool

Check if the client accepts a specific media type.

pub fn prefers_json(&self) -> bool

Check if the client prefers JSON over HTML.

pub fn prefers_html(&self) -> bool

Check if the client prefers HTML over JSON.

pub fn negotiate_media_type<'a>( &self, available: &'a [MediaType], ) -> Option<&'a MediaType>

Negotiate the best media type from available options.

pub fn negotiate_language<'a>( &self, available: &'a [LanguageTag], ) -> Option<&'a LanguageTag>

Negotiate the best language from available options.

pub fn negotiate_encoding(&self, available: &[Encoding]) -> Option<Encoding>

Negotiate the best encoding from available options.

impl HttpRequest

pub fn new(method: impl Into<Method>, path: impl Into<ByteStr>) -> Self

Create a request.

Generic in the method so every existing HttpRequest::new("GET", …) call site compiles unchanged.

pub fn with_extensions_capacity( method: impl Into<Method>, path: impl Into<ByteStr>, capacity: usize, ) -> Self

Create a new request with pre-allocated extensions capacity.

pub fn with_bytes_body( method: impl Into<Method>, path: impl Into<ByteStr>, body: Bytes, ) -> Self

Create a new request with a Bytes body (zero-copy).

This is the most efficient way to create a request from Hyper’s body, as it avoids copying the body data.

pub fn set_body_bytes(&mut self, bytes: Bytes)

Set the body (zero-copy).

pub fn body_bytes(&self) -> Bytes

The body as Bytes. A refcount bump, not a copy.

pub fn body_slice(&self) -> &[u8]

The body as a byte slice.

pub fn body_ref(&self) -> &[u8]

The body as a byte slice.

pub fn path_str(&self) -> &str

The request target as a string, query string included.

pub fn path_only(&self) -> &str

The request target with any query string removed.

This is what routing matches on, and what most callers mean when they say “the path” — path/path_str are the raw target, which is what the query is parsed out of.

pub fn request_body(&self) -> RequestBody

Get the body as a RequestBody (zero-copy wrapper).

pub fn has_bytes_body(&self) -> bool

Whether the body holds anything.

Kept for call-site compatibility from when the body could live in either of two fields; it is always Bytes now.

pub fn method_str(&self) -> &str

The method as a string, for logging and for code that compares tokens.

pub fn set_body(&mut self, body: Vec<u8>)

Set the body from a Vec<u8>, taking over its allocation.

pub fn from_parts( method: impl Into<Method>, path: impl Into<ByteStr>, headers: HashMap<String, String>, body: Vec<u8>, path_params: HashMap<String, String>, query_params: HashMap<String, String>, ) -> Self

Create a request from all parts (for compatibility in tests).

pub fn insert_extension<T: Send + Sync + 'static>(&mut self, value: T)

Insert a typed value into request extensions.

Use this to pass application state to handlers.

Example

let mut request = HttpRequest::new("GET", "/");
request.insert_extension(app_state);

pub fn insert_extension_arc<T: Send + Sync + 'static>(&mut self, value: Arc<T>)

Insert an Arc-wrapped value into request extensions.

This is more efficient when you already have an Arc.

pub fn extension<T: Send + Sync + 'static>(&self) -> Option<&T>

Get a reference to a typed extension.

Returns None if no value of this type exists.

pub fn extension_arc<T: Send + Sync + 'static>(&self) -> Option<Arc<T>>

Get an Arc reference to a typed extension.

pub fn json<T: for<'de> Deserialize<'de>>(&self) -> Result<T, Error>

Parse the request body as JSON.

With the simd-json feature enabled, this uses SIMD-accelerated parsing which can be 2-3x faster on modern x86_64 CPUs.

Example

let user: CreateUser = request.json()?;

pub fn form<T: for<'de> Deserialize<'de>>(&self) -> Result<T, Error>

Parse URL-encoded form data

pub fn form_map(&self) -> Result<HashMap<String, String>, Error>

Parse URL-encoded form data into a HashMap

pub fn multipart(&self) -> Result<Vec<FormField>, Error>

Parse multipart form data

pub fn param(&self, name: &str) -> Option<&str>

A captured route parameter, as UTF-8.

pub fn param_bytes(&self, name: &str) -> Option<&Bytes>

A captured route parameter, raw.

pub fn push_param(&mut self, name: &str, value: impl Into<Bytes>)

Add one captured route parameter, interning its name.

The router uses HttpRequest::set_params with names already interned at registration; this is for callers assembling a request by hand. The interner is hard-capped (crate::param_intern::MAX_INTERNED), so feeding this a request-derived name cannot grow the process without bound — past the cap the name resolves to crate::param_intern::OVERFLOW_NAME and the parameter is no longer retrievable by its own name.

pub fn set_params(&mut self, params: RouteParams)

Replace the captured parameters. Called by the router.

pub fn query_string(&self) -> Option<&str>

The raw query string, without the ?.

pub fn query(&self) -> QueryView<'_>

A parsed view of the query string.

Parses on the first call and memoizes; a handler that never calls this pays nothing. Note the shape change: this used to take a name and return one value — that accessor is now HttpRequest::query_param.

pub fn push_query_param( &mut self, name: impl AsRef<str>, value: impl AsRef<str>, )

Append a query parameter to the target, percent-encoding both sides.

The query lives in path now, so this is how a caller adds one without hand-assembling the target. Any memoized parse is discarded, since the target it was parsed from no longer describes this request.

pub fn query_param(&self, name: &str) -> Option<&str>

The first query value for name.

impl HttpRequest

Extension methods for HttpRequest related to caching.

pub fn cache_control(&self) -> Option<CacheControl>

Get the Cache-Control header from the request.

pub fn allows_cached(&self) -> bool

Check if the request allows cached responses.

pub fn max_stale(&self) -> Option<u64>

Get the max-stale tolerance from the request.

pub fn cache_key(&self) -> CacheKey

Generate a cache key for this request.

pub fn cache_key_with_vary(&self, vary_headers: &[&str]) -> CacheKey

Generate a cache key with Vary headers.

Trait Implementations

impl Clone for HttpRequest

fn clone(&self) -> HttpRequest

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ConditionalRequest for HttpRequest

fn conditional_headers(&self) -> ConditionalHeaders

Get parsed conditional headers from the request.

fn if_none_match(&self) -> Option<ETagList>

Get the If-None-Match header as an ETag list.

fn if_match(&self) -> Option<ETagList>

Get the If-Match header as an ETag list.

fn if_modified_since(&self) -> Option<SystemTime>

Get the If-Modified-Since header as a SystemTime.

fn if_unmodified_since(&self) -> Option<SystemTime>

Get the If-Unmodified-Since header as a SystemTime.

fn if_none_match_matches(&self, etag: &ETag) -> bool

Check if If-None-Match contains a matching ETag (weak comparison).

fn if_match_matches(&self, etag: &ETag) -> bool

Check if If-Match contains a matching ETag (strong comparison).

fn not_modified_since(&self, last_modified: SystemTime) -> bool

Check if If-Modified-Since indicates the resource hasn’t changed.

fn modified_since_precondition(&self, last_modified: SystemTime) -> bool

Check if If-Unmodified-Since precondition fails.

fn evaluate_conditionals( &self, etag: Option<&ETag>, last_modified: Option<SystemTime>, ) -> Option<u16>

Evaluate all conditional headers and return the appropriate response.

impl CorrelatedRequest for HttpRequest

fn correlation_context(&self) -> CorrelationContext

Get the correlation context from the request.

fn correlation_id(&self) -> Option<String>

Get the correlation ID.

fn request_id(&self) -> Option<String>

Get the request ID.

fn trace_id(&self) -> Option<String>

Get the trace ID.

fn span_id(&self) -> Option<String>

Get the span ID.

impl Debug for HttpRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromRequest for HttpRequest

fn from_request(request: &HttpRequest) -> Result<Self, Error>

Extract data from the request

impl<S> Service<HttpRequest> for LoggingService<S>

where S: Service<HttpRequest, Response = HttpResponse, Error = Error> + Clone + Send + Sync + 'static, S::Future: Send,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, req: HttpRequest) -> Self::Future

Process a request.

impl<S> Service<HttpRequest> for TimeoutService<S>

where S: Service<HttpRequest, Response = HttpResponse, Error = Error> + Clone + Send + Sync + 'static, S::Future: Send,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, req: HttpRequest) -> Self::Future

Process a request.

impl<S> Service<HttpRequest> for RequestIdService<S>

where S: Service<HttpRequest, Response = HttpResponse, Error = Error> + Clone + Send + Sync + 'static, S::Future: Send,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, req: HttpRequest) -> Self::Future

Process a request.

impl<H, Fut> Service<HttpRequest> for HandlerService<H, ()>

where H: Fn() -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Result<HttpResponse, Error>> + Send + 'static,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, _req: HttpRequest) -> Self::Future

Process a request.

impl<H, Fut> Service<HttpRequest> for HandlerService<H, (HttpRequest,)>

where H: Fn(HttpRequest) -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Result<HttpResponse, Error>> + Send + 'static,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, req: HttpRequest) -> Self::Future

Process a request.

impl<H, Fut, E1> Service<HttpRequest> for ExtractorHandlerService<H, (E1,)>

where H: Fn(E1) -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Result<HttpResponse, Error>> + Send + 'static, E1: Extract + Send + 'static,

type Response = HttpResponse

Response type.

type Error = Error

Error type.

type Future = Pin<Box<dyn Future<Output = Result<HttpResponse, Error>> + Send>>

Future type.

fn call(&self, req: HttpRequest) -> Self::Future

Process a request.