Struct Request 

pub struct Request { /* private fields */ }

HTTP Request wrapper providing Laravel-like access to request data

Implementations

impl Request

pub fn new(inner: Request<Incoming>) -> Self

Create a new request from a raw hyper request.

pub fn with_params(self, params: HashMap<String, String>) -> Self

Attach route parameters extracted from the URL path.

pub fn with_route_pattern(self, pattern: String) -> Self

Set the route pattern (e.g., “/users/{id}”)

pub fn route_pattern(&self) -> Option<String>

Get the route pattern for metrics grouping

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

Insert a value into the request extensions (type-map pattern)

This is async-safe unlike thread-local storage.

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

Get a reference to a value from the request extensions

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

Get a mutable reference to a value from the request extensions

pub fn method(&self) -> &Method

Get the request method

pub fn uri(&self) -> &Uri

Get the request URI

pub fn headers(&self) -> &HeaderMap

Get the request headers

pub fn path(&self) -> &str

Get the request path

pub fn set_path(&mut self, new_path: &str)

Rewrite the request path (server-side only — the browser URL is unchanged).

Replaces the URI path component while preserving the scheme, authority, and query string. Used by pre-route middleware (e.g. HostMiddleware) to map custom-domain requests onto internal slug-based routes before routing occurs.

new_path must begin with /. Panics in debug mode if it does not.

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

Get a route parameter by name (e.g., /users/{id}) Returns Err(ParamError) if the parameter is missing, enabling use of ? operator

pub fn param_as<T: FromStr>(&self, name: &str) -> Result<T, ParamError>

where T::Err: Display,

Get a route parameter parsed as a specific type

Combines param() with parsing, returning a typed value.

Example

pub async fn show(req: Request) -> Response {
    let id: i32 = req.param_as("id")?;
    // ...
}

pub fn params(&self) -> &HashMap<String, String>

Get all route parameters

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

Get a query string parameter by name

Example

// URL: /users?page=2&limit=10
let page = req.query("page"); // Some("2")
let sort = req.query("sort"); // None

pub fn query_or(&self, name: &str, default: &str) -> String

Get a query string parameter or a default value

Example

// URL: /users?page=2
let page = req.query_or("page", "1"); // "2"
let limit = req.query_or("limit", "10"); // "10"

pub fn query_as<T: FromStr>(&self, name: &str) -> Option<T>

Get a query string parameter parsed as a specific type

Example

// URL: /users?page=2&limit=10
let page: Option<i32> = req.query_as("page"); // Some(2)

pub fn query_as_or<T: FromStr>(&self, name: &str, default: T) -> T

Get a query string parameter parsed as a specific type, or a default

Example

// URL: /users?page=2
let page: i32 = req.query_as_or("page", 1); // 2
let limit: i32 = req.query_as_or("limit", 10); // 10

pub fn old(&self, field: &str) -> Option<String>

Read a previously-submitted form value from session flash.

After a POST handler calls ValidationError::with_old_input(&data).redirect_back(...), the GET handler retrieves the value with req.old("field_name") and passes it as InputProps.default_value to repopulate the form.

Reads from _flash.old._old_input.<field> without clearing (read-only semantics). Flash aging (move new→old→deleted) is handled by the session middleware at request boundaries, so multiple reads in the same GET handler are safe.

Returns None when no flash value exists, no session is active, or the key is absent.

pub fn validation_error(&self, field: &str) -> Option<String>

Read the first validation error message for a field from session flash.

After a POST handler calls errors.redirect_back(...), the GET handler calls req.validation_error("field_name") and passes the result as InputProps.error.

Reads from _flash.old._validation_errors without clearing (read-only semantics).

Returns None when no flash errors exist, no session is active, or the field has no error.

pub fn has_validation_errors(&self) -> bool

Returns true when any validation errors were flashed from a prior request.

Useful for rendering a form-wide error summary banner.

pub fn inner(&self) -> &Parts

Get a reference to the request head (method, URI, headers, version).

Previously this method returned &hyper::Request<hyper::body::Incoming>. The signature changed when the body was split out from the head to support &mut self body readers — callers that need only headers/URI/method should use the dedicated accessors (uri(), headers(), method()); callers that need the raw Parts for low-level work can use this method.

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

Get a header value by name

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

Get the Content-Type header

pub fn back_or(&self, fallback: impl Into<String>) -> String

Resolve the URL the current request was triggered from, falling back to fallback when the Referer is absent, malformed, or points off-origin.

Use to capture a “back” target at handler entry before the request body is consumed (e.g. before body_bytes). The returned String then feeds crate::http::Redirect::to to send the user back to where they came from, preserving query strings (e.g. ?tab=note) and any other URL state.

Same-origin rule mirrors crate::http::Redirect::back: absolute URLs must share the request’s Host; scheme-relative URLs are rejected.

pub fn is_inertia(&self) -> bool

Check if this is an Inertia XHR request

pub fn cookies(&self) -> HashMap<String, String>

Get all cookies from the request

Parses the Cookie header and returns a HashMap of cookie names to values.

Example

let cookies = req.cookies();
if let Some(session) = cookies.get("session") {
    println!("Session: {}", session);
}

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

Get a specific cookie value by name

Example

if let Some(session_id) = req.cookie("session") {
    // Use session_id
}

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

Get the Inertia version from request headers

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

Get partial component name for partial reloads

pub fn inertia_partial_data(&self) -> Option<Vec<&str>>

Get partial data keys for partial reloads

pub async fn body_bytes(self) -> Result<(RequestParts, Bytes), FrameworkError>

Consume the request and collect the body as bytes.

If the body has already been read via body_bytes_mut (or any other *_mut body reader), this returns the cached bytes. If the body was taken by into_parts (the legacy FormRequest extraction path), this returns an error.

pub async fn json<T: DeserializeOwned>(self) -> Result<T, FrameworkError>

Parse the request body as JSON

Consumes the request since the body can only be read once.

Example

#[derive(Deserialize)]
struct CreateUser { name: String, email: String }

pub async fn store(req: Request) -> Response {
    let data: CreateUser = req.json().await?;
    // ...
}

pub async fn form<T: DeserializeOwned>(self) -> Result<T, FrameworkError>

Parse the request body as form-urlencoded

Consumes the request since the body can only be read once.

Example

#[derive(Deserialize)]
struct LoginForm { username: String, password: String }

pub async fn login(req: Request) -> Response {
    let form: LoginForm = req.form().await?;
    // ...
}

pub async fn multipart(self) -> Result<MultipartForm, FrameworkError>

Parse the request body as multipart/form-data.

Consumes the request since the body can only be read once. The per-field byte cap is read from UPLOAD_MAX_SIZE_MB (default 10 MiB), and the per-request field cap from UPLOAD_MAX_FIELDS (default 100).

Errors

Returns FrameworkError::internal(...) with the literal message "Content-Type is not multipart/form-data or missing boundary" when the request’s Content-Type header is absent, malformed, or not a multipart value.

Example

pub async fn upload(req: Request) -> Response {
    let form = req.multipart().await?;
    let title = form.field("title").unwrap_or_default();
    let file = form.file("attachment");
    // ...
}

pub async fn file( self, field: &str, ) -> Result<Option<UploadedFile>, FrameworkError>

Parse the body as multipart/form-data and return the first file uploaded under field.

Consumes the request since the body can only be read once. Returns Ok(None) when the multipart body parses successfully but contains no file with that field name.

Example

pub async fn upload_avatar(req: Request) -> Response {
    let file = req.file("avatar").await?
        .ok_or_else(|| FrameworkError::internal("missing avatar"))?;
    // file.store(&disk, &path).await?;
    Ok(json!({"size": file.size()}))
}

pub async fn input<T: DeserializeOwned>(self) -> Result<T, FrameworkError>

Parse the request body based on Content-Type header

• application/json -> JSON parsing
• application/x-www-form-urlencoded -> Form parsing
• Otherwise -> JSON parsing (default)

Consumes the request since the body can only be read once.

pub fn into_parts(self) -> (RequestParts, Incoming)

Consume the request and return its parts along with the inner hyper request body.

Used internally by the handler macro for FormRequest extraction. Panics if the body has already been read by a *_mut method or body_bytes — FormRequest paths must own a fresh hyper body. This is consistent with the pre-Phase-180 contract: a request flows into exactly one of the two extraction paths.

pub async fn body_bytes_mut(&mut self) -> Result<Bytes, FrameworkError>

Collect the request body as bytes — &mut self variant.

First call drains the body from the wire and caches it on self. Subsequent calls return clones of the cached bytes (refcount bump). Returns an error if the body was already taken by into_parts.

Use this inside #[action]-decorated handlers where req: &mut Request.

pub async fn json_mut<T: DeserializeOwned>( &mut self, ) -> Result<T, FrameworkError>

Parse the body as JSON — &mut self variant.

First call drains and caches; subsequent calls re-parse cached bytes.

pub async fn form_mut<T: DeserializeOwned>( &mut self, ) -> Result<T, FrameworkError>

Parse the body as form-urlencoded — &mut self variant.

pub async fn input_mut<T: DeserializeOwned>( &mut self, ) -> Result<T, FrameworkError>

Parse the body based on Content-Type — &mut self variant. Mirrors input(self) semantics: form-urlencoded → form, everything else → JSON.

pub async fn multipart_mut(&mut self) -> Result<MultipartForm, FrameworkError>

Parse the body as multipart/form-data — &mut self variant.

Each call re-parses the multipart structure from the cached bytes, so calling this twice returns two independent MultipartForm values. Per-field and per-request limits read from UPLOAD_MAX_SIZE_MB and UPLOAD_MAX_FIELDS (same as the legacy multipart(self)).

pub async fn file_mut( &mut self, field: &str, ) -> Result<Option<UploadedFile>, FrameworkError>

Parse the body as multipart and return the first file under field — &mut self variant.

impl Request

pub fn flash(&mut self, key: impl Into<String>)

Record a success-side flash key for the #[action] macro runtime to write to the session _action flash slot when the handler returns Ok(()).

Has no observable effect outside an #[action]-decorated handler.

Example

#[action(redirect_to = "/dashboard/pagine")]
pub async fn create(req: Request) -> ActionResult {
    let new_id = Page::create(...).await?;
    req.redirect_to(format!("/dashboard/pagine/{new_id}"));
    req.flash("created");
    Ok(())
}

pub fn redirect_to(&mut self, url: impl Into<String>)

Record a success-side redirect override for the #[action] macro runtime to apply when the handler returns Ok(()). The URL is validated as same-origin (must start with /) when applied — external URLs are silently rejected (T-180-02).

Has no observable effect outside an #[action]-decorated handler.

Trait Implementations

impl From<&Request> for SavedInertiaContext

fn from(req: &Request) -> Self

Converts to this type from the input type.

impl FromRequest for Request

Request passes through unchanged

fn from_request<'async_trait>( req: Request, ) -> Pin<Box<dyn Future<Output = Result<Self, FrameworkError>> + Send + 'async_trait>>

where Self: 'async_trait,

Extract Self from the incoming request

impl InertiaRequest for Request

Implement the framework-agnostic InertiaRequest trait for Ferro’s Request type.

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

Get a header value by name.

fn path(&self) -> &str

Get the request path (URL path component).

fn is_inertia(&self) -> bool

Check if this is an Inertia XHR request.

fn inertia_version(&self) -> Option<&str>

Get the Inertia asset version from the request.

fn inertia_partial_data(&self) -> Option<Vec<&str>>

Get the partial reload data keys.

fn inertia_partial_component(&self) -> Option<&str>

Get the component name for partial reload.

fn accepts_json(&self) -> bool

Check if the request accepts JSON responses.