webrune 0.1.2

//! Request extraction primitives.
//!
//! This module defines the traits and types used to extract structured data
//! from incoming HTTP requests.
//!
//! Extractors are small, focused components that read information from a
//! [`Request`] and convert it into strongly-typed values that can be passed
//! directly into handlers.
//!
//! Typical extractors include:
//! - path parameters ([`Path`]),
//! - query string parameters ([`Query`]),
//! - and other request metadata.
//!
//! Extraction is explicit and type-driven.

mod path;
mod query;

use crate::Request;

pub use path::{Path, PathError};
pub use query::{Query, QueryError};

/// Trait for stateless request extractors.
///
/// An extractor implementing `Extract` derives a value solely from the
/// incoming [`Request`].
///
/// This is appropriate for data such as:
/// - path parameters,
/// - query parameters,
/// - headers,
/// - or request metadata.
///
/// # Example
///
/// ```ignore
/// async fn handler(request: Request) -> Result<Json<Payload>, MyError> {
///   let query = MyQuery::extract(&request)?;
///   ...
/// }
/// ```
pub trait Extract: Sized {
    /// Error returned when extraction fails.
    type Error;

    /// Attempts to extract `Self` from the given request.
    fn extract<B>(request: &Request<B>) -> Result<Self, Self::Error>;
}

/// Trait for stateful request extractors.
///
/// `ExtractStateful` is used when extraction depends on shared application
/// state in addition to the request itself.
///
/// This is useful for extractors such as:
/// - database-backed session lookups,
/// - authenticated user contexts,
/// - request-scoped caches.
///
/// # Example
///
/// ```ignore
/// async fn handler(request: Request, state: MyState) -> Result<Json<Payload>, MyError> {
///   let query = MyQuery::extract(&request, &state)?;
///   ...
/// }
/// ```
pub trait ExtractStateful<S>: Sized {
    type Error;

    fn extract<B>(request: &Request<B>, state: &S) -> Result<Self, Self::Error>;
}