Path, query, and headers

Read request parts through typed parameters and distinguish missing values from malformed ones.

Extractors convert an HTTP request into the types an action needs. Reading path, query, and header values does not consume the request body.

Path and query#

Path<T> deserializes route parameters and Query<T> deserializes the query string using Serde. DTO field names match the route/query names. The controller example shows the complete file.

#[get("/:id")]
async fn read(
    &self,
    Path(path): Path<UserPath>,
    Query(query): Query<UserQuery>,
) -> Result<UserView, HttpApiError> {
    Ok(UserView {
        id: path.id,
        name: query.language.unwrap_or_else(|| "tr".into()),
    })
}

The linked example defines UserPath, UserQuery, and UserView. For repeated query keys, choose a DTO that supports multiple values. Path decoding is strict; invalid parameters are rejected.

Headers and optional values#

TypedHeader<T> uses a headers::Header decoder. A missing required header or malformed value causes rejection. Option<TypedHeader<T>> returns None only when the header is absent; it does not accept a malformed value as valid.

Other request parts#

Extractor	Use
`RequestCookies`	Read the cookie jar; `get` can also return an error
`Principal`	Get an identity that has already been verified; 401 if absent
`Option<Principal>`	Get the identity if present
`Local<T>`	Get an owned clone of a request-local value
`Option<Local<T>>`	Get `None` when the local value is absent
`ClientIp`	Get the trusted client IP calculated by the transport
`Service<T>`	Resolve a service from the active request scope
`ExecutionCancellation`	Observe the request's cancellation signal

Prefer Local<Arc<T>> for large local values. A missing required Local<T> is an internal state error. The Principal extractor does not authenticate; it reads the identity verified by a guard.

Parameter order#

Request-parts and service parameters come first, followed by at most one body consumer, then any permitted raw request/response capabilities. Body ownership explains why this order matters.