topcoat-router 0.9.0

use std::{
    net::{IpAddr, SocketAddr},
    sync::Arc,
};

/// Byte-buffer types re-exported for use as request body extractors and as
/// response bodies.
pub use bytes::{Bytes, BytesMut};
use http::request::Parts;
use topcoat_core::{
    context::{Cx, request_context, try_request_context},
    error::Result,
    identity::Identity,
};

use crate::{Body, RemoteAddr, body_limit, error::bad_request, proxy::ClientIp, to_bytes};

/// An incoming HTTP request, carrying a [`Body`] by default.
pub type Request<T = Body> = http::Request<T>;

/// A type that can be built from an incoming request.
///
/// A page or route may accept one `FromRequest` body parameter alongside an
/// optional `cx: &Cx`. Use a built-in extractor or implement this trait for
/// custom parsing.
///
/// A handler accepts only one body parameter because the body can be consumed
/// only once.
///
/// An implementation that buffers the body should delegate the buffering to
/// [`Bytes`], which enforces the request's
/// [`body_limit`]; reading the body by hand bypasses that
/// limit.
///
/// # Examples
///
/// Implement it to parse a request in a way the built-ins don't cover. Here,
/// JSON whose body is verified against an `x-signature` header before it is
/// deserialized:
///
/// ```rust
/// # #[derive(serde::Deserialize)]
/// # struct CreateUser { name: String }
/// # fn verify_signature(_signature: &str, _bytes: &[u8]) -> topcoat::Result<()> { Ok(()) }
/// use serde::de::DeserializeOwned;
/// use topcoat::{
///     Result,
///     context::Cx,
///     router::{
///         Body,
///         error::bad_request,
///         request::{Bytes, FromRequest, headers},
///         route,
///     },
/// };
///
/// struct SignedJson<T>(T);
///
/// impl<T> FromRequest for SignedJson<T>
/// where
///     T: DeserializeOwned,
/// {
///     async fn from_request(cx: &Cx, body: Body) -> Result<Self> {
///         let signature = headers(cx)
///             .get("x-signature")
///             .and_then(|value| value.to_str().ok())
///             .ok_or_else(|| bad_request("missing x-signature header"))?;
///
///         let bytes = Bytes::from_request(cx, body).await?;
///
///         verify_signature(signature, &bytes)?;
///
///         Ok(Self(serde_json::from_slice(&bytes)?))
///     }
/// }
///
/// // Once implemented, use it like the built-in extractors:
/// #[route(POST "/api/signed")]
/// async fn signed(SignedJson(input): SignedJson<CreateUser>) -> Result<&'static str> {
///     let _ = input;
///     Ok("ok")
/// }
/// ```
pub trait FromRequest: Sized {
    /// Builds `Self` from the request context and body.
    ///
    /// Returns an error (typically [`bad_request`])
    /// when the request cannot be parsed into `Self`; the error is converted
    /// into the response sent to the client.
    fn from_request(cx: &Cx, body: Body) -> impl Future<Output = Result<Self>> + Send;
}

/// Yields the request body unchanged, leaving it unbuffered for the handler to
/// read or forward itself.
impl FromRequest for Body {
    fn from_request(_cx: &Cx, body: Body) -> impl Future<Output = Result<Self>> {
        core::future::ready(Ok(body))
    }
}

/// Buffers the entire request body into memory, rejecting a body larger than
/// the request's [`body_limit`] with `413 Content Too Large`.
impl FromRequest for Bytes {
    async fn from_request(cx: &Cx, body: Body) -> Result<Self> {
        to_bytes(body, body_limit(cx)).await
    }
}

/// Buffers the entire request body into a mutable buffer.
impl FromRequest for BytesMut {
    async fn from_request(cx: &Cx, body: Body) -> Result<Self> {
        let bytes = Bytes::from_request(cx, body).await?;
        Ok(Self::from(&bytes[..]))
    }
}

/// Buffers the request body and decodes it as UTF-8, rejecting a non-UTF-8 body
/// with `400 Bad Request`.
impl FromRequest for String {
    async fn from_request(cx: &Cx, body: Body) -> Result<Self> {
        let bytes = Bytes::from_request(cx, body).await?;
        Self::from_utf8(bytes.into()).map_err(|error| {
            bad_request(format!("request body is not valid UTF-8: {error}")).into()
        })
    }
}

/// Customizes the behavior of `Option<Self>` as a [`FromRequest`] extractor.
///
/// Implementing this trait lets `Option<Self>` be extracted from a request,
/// yielding `None` when the request carries no value for the extractor (for
/// example, a missing body) while still surfacing an error for values that are
/// present but malformed.
pub trait OptionalFromRequest: Sized {
    /// Builds `Some(Self)` from the request, or `None` when the request carries
    /// no value for this extractor.
    ///
    /// Returns an error only when a value is present but malformed.
    fn from_request(cx: &Cx, body: Body) -> impl Future<Output = Result<Option<Self>>> + Send;
}

/// Makes any [`OptionalFromRequest`] extractor optional, yielding `None` when
/// the request carries no value of that kind while still surfacing an error for
/// a value that is present but malformed.
impl<T> FromRequest for Option<T>
where
    T: OptionalFromRequest,
{
    async fn from_request(cx: &Cx, body: Body) -> Result<Self> {
        T::from_request(cx, body).await
    }
}

/// Returns the [`Parts`] of the current request.
///
/// Use this to read several request fields at once. For one field, use its
/// accessor, such as [`method`] or [`headers`].
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::parts};
///
/// async fn log_request(cx: &Cx) {
///     let parts = parts(cx);
///     println!("{} {}", parts.method, parts.uri);
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn parts(cx: &Cx) -> &Parts {
    request_context(cx)
}

/// Returns the HTTP [`Method`] of the current request.
///
/// [`Method`]: http::Method
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::method};
///
/// async fn is_post(cx: &Cx) -> bool {
///     method(cx) == http::Method::POST
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn method(cx: &Cx) -> &http::Method {
    &parts(cx).method
}

/// Returns the [`Uri`] of the current request.
///
/// [`Uri`]: http::Uri
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::uri};
///
/// async fn current_path(cx: &Cx) -> &str {
///     uri(cx).path()
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn uri(cx: &Cx) -> &http::Uri {
    &parts(cx).uri
}

/// Returns the HTTP [`Version`] of the current request.
///
/// [`Version`]: http::Version
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::version};
///
/// async fn is_http2(cx: &Cx) -> bool {
///     *version(cx) == http::Version::HTTP_2
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn version(cx: &Cx) -> &http::Version {
    &parts(cx).version
}

/// Returns the [`HeaderMap`] of the current request.
///
/// [`HeaderMap`]: http::HeaderMap
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::headers};
///
/// async fn user_agent(cx: &Cx) -> Option<&str> {
///     headers(cx).get("user-agent")?.to_str().ok()
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn headers(cx: &Cx) -> &http::HeaderMap {
    &parts(cx).headers
}

/// Returns the `Content-Type` header of the current request as a string slice,
/// or [`None`] when it is absent or not valid UTF-8.
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::content_type};
///
/// async fn is_json(cx: &Cx) -> bool {
///     content_type(cx).is_some_and(|value| value.starts_with("application/json"))
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn content_type(cx: &Cx) -> Option<&str> {
    headers(cx).get(http::header::CONTENT_TYPE)?.to_str().ok()
}

/// Returns the [`Extensions`] of the current request.
///
/// Extensions carry typed values attached to the request, typically by
/// middleware running before the handler.
///
/// [`Extensions`]: http::Extensions
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::extensions};
///
/// struct RequestId(String);
///
/// async fn request_id(cx: &Cx) -> Option<&str> {
///     extensions(cx).get::<RequestId>().map(|id| id.0.as_str())
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn extensions(cx: &Cx) -> &http::Extensions {
    &parts(cx).extensions
}

/// Returns the IP address and port of the direct connection for this request,
/// or `None` when they are unknown.
///
/// Behind a reverse proxy, this returns the proxy's address. Use
/// [`client_ip`] to read the client's IP address instead.
/// Returns `None` if the request has no [`RemoteAddr`] in its extensions,
/// as is normally the case for Unix socket connections, or if the context
/// was not created by a router.
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::remote_addr};
///
/// fn peer_port(cx: &Cx) -> Option<u16> {
///     remote_addr(cx).map(|addr| addr.port())
/// }
/// ```
#[inline]
#[must_use]
pub fn remote_addr(cx: &Cx) -> Option<SocketAddr> {
    let parts = try_request_context::<Parts>(cx)?;
    parts.extensions.get::<RemoteAddr>().map(|remote| remote.0)
}

/// Returns the client's IP address for this request, or `None`
/// when it cannot be determined.
///
/// By default, this returns the IP address from [`remote_addr`]. Behind a
/// reverse proxy, that is the proxy's address. Configure
/// [`TrustedProxies`](crate::TrustedProxies) on the router to read the
/// client's address from the proxy's header.
///
/// For a header that lists multiple addresses, Topcoat starts with the direct
/// connection and reads the list from right to left. It skips trusted proxies
/// and returns the first address it does not trust. If every address is
/// trusted, it returns the leftmost address. If the list is empty or missing,
/// it uses the direct connection's address.
///
/// Returns `None` if the direct connection's address is unknown and it is not
/// trusted through [`TrustedProxies::nearest`](crate::TrustedProxies::nearest),
/// or if an address needed from the header cannot be parsed. Headers
/// containing a single address follow the rules in
/// [`ForwardedHeader::Single`](crate::ForwardedHeader::Single). IPv4-mapped
/// IPv6 addresses are returned as IPv4.
///
/// The router determines the address before running any layers. Later changes
/// to request headers do not change this result. Returns `None` if the context
/// was not created by a router.
///
/// # Examples
///
/// ```rust
/// use topcoat::{
///     Result,
///     context::Cx,
///     router::{error::forbidden, request::client_ip},
/// };
///
/// # fn is_banned(_ip: std::net::IpAddr) -> bool { false }
/// fn reject_banned(cx: &Cx) -> Result<()> {
///     match client_ip(cx) {
///         Some(ip) if is_banned(ip) => Err(forbidden().into()),
///         _ => Ok(()),
///     }
/// }
/// ```
#[must_use]
#[track_caller]
pub fn client_ip(cx: &Cx) -> Option<IpAddr> {
    try_request_context::<ClientIp>(cx)?.0
}

/// The parts the request arrived with, shared by every dispatch.
#[derive(Debug, Clone)]
pub(crate) struct OriginalParts(pub(crate) Arc<Parts>);

/// Returns the [`Parts`] of the request as the client sent it, before any
/// rewrite or changes made by layers.
///
/// A handler reached through a [`rewrite`](crate::error::rewrite) sees the
/// rewritten request in [`parts`], which may differ in its URI and method;
/// this accessor returns the parts the request arrived with. Layers can
/// also change the current parts without a rewrite. For example,
/// [`StripPrefixLayer`](crate::StripPrefixLayer) changes the current URI
/// while leaving the original URI intact.
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::original_parts};
///
/// async fn arrived_with_header(cx: &Cx, name: &str) -> bool {
///     original_parts(cx).headers.contains_key(name)
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn original_parts(cx: &Cx) -> &Parts {
    match try_request_context::<OriginalParts>(cx) {
        Some(original) => &original.0,
        None => parts(cx),
    }
}

/// Returns the HTTP [`Method`] the client actually requested with, before
/// any rewrite.
///
/// A rewrite may dispatch the request with another method; this accessor
/// returns the one the request arrived with. For a request that was never
/// rewritten it is the same as [`method`].
///
/// [`Method`]: http::Method
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::original_method};
///
/// async fn arrived_as_post(cx: &Cx) -> bool {
///     original_method(cx) == http::Method::POST
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn original_method(cx: &Cx) -> &http::Method {
    &original_parts(cx).method
}

/// Returns the [`Uri`] the client actually requested, before any rewrite.
///
/// A handler reached through a [`rewrite`](crate::error::rewrite) sees the
/// rewritten URI in [`uri`]; this accessor returns the URI the request
/// arrived with, for example to render a form that posts back to the visible
/// URL. Layers such as [`StripPrefixLayer`](crate::StripPrefixLayer) can
/// also change the current URI without changing this original URI.
///
/// [`Uri`]: http::Uri
///
/// # Examples
///
/// ```rust
/// use topcoat::{context::Cx, router::request::original_uri};
///
/// async fn form_action(cx: &Cx) -> String {
///     original_uri(cx).path().to_owned()
/// }
/// ```
#[inline]
#[must_use]
#[track_caller]
pub fn original_uri(cx: &Cx) -> &http::Uri {
    &original_parts(cx).uri
}

/// Returns the HTTP [`Version`] of the request as the client sent it, before
/// any rewrite.
///
/// See [`original_parts`] for how a rewritten request differs from the one
/// that arrived.
///
/// [`Version`]: http::Version
#[inline]
#[must_use]
#[track_caller]
pub fn original_version(cx: &Cx) -> &http::Version {
    &original_parts(cx).version
}

/// Returns the [`HeaderMap`] of the request as the client sent it, before
/// any rewrite.
///
/// See [`original_parts`] for how a rewritten request differs from the one
/// that arrived.
///
/// [`HeaderMap`]: http::HeaderMap
#[inline]
#[must_use]
#[track_caller]
pub fn original_headers(cx: &Cx) -> &http::HeaderMap {
    &original_parts(cx).headers
}

/// Returns the `Content-Type` header of the request as the client sent it,
/// before any rewrite, as a string slice, or [`None`] when it is absent or
/// not valid UTF-8.
///
/// See [`original_parts`] for how a rewritten request differs from the one
/// that arrived.
#[inline]
#[must_use]
#[track_caller]
pub fn original_content_type(cx: &Cx) -> Option<&str> {
    original_headers(cx)
        .get(http::header::CONTENT_TYPE)?
        .to_str()
        .ok()
}

/// Returns the [`Extensions`] of the request as the client sent it, before
/// any rewrite.
///
/// See [`original_parts`] for how a rewritten request differs from the one
/// that arrived.
///
/// [`Extensions`]: http::Extensions
#[inline]
#[must_use]
#[track_caller]
pub fn original_extensions(cx: &Cx) -> &http::Extensions {
    &original_parts(cx).extensions
}

/// The header naming the identity the router installs on a request's context.
pub const IDENTITY_HEADER: &str = "x-topcoat-identity";

/// Returns the identity the current request's build starts at.
///
/// A client re-running part of a page names the identity of that part in
/// the [`IDENTITY_HEADER`], so the server derives the same identities inside
/// it as the render the client holds. A request without the header starts at
/// [`Identity::ROOT`], like a page request.
///
/// # Errors
///
/// Errors with a `400 Bad Request` if the header is present but not an
/// identity.
///
/// # Examples
///
/// ```rust
/// use topcoat::{
///     Result, context::Cx, core::identity::Identity, router::request::initial_identity,
/// };
///
/// async fn is_page_request(cx: &Cx) -> Result<bool> {
///     Ok(initial_identity(cx)? == Identity::ROOT)
/// }
/// ```
#[track_caller]
pub fn initial_identity(cx: &Cx) -> Result<Identity> {
    let Some(header) = headers(cx).get(IDENTITY_HEADER) else {
        return Ok(Identity::ROOT);
    };
    header
        .to_str()
        .ok()
        .and_then(|value| value.parse().ok())
        .ok_or_else(|| {
            bad_request(format!("expected `{IDENTITY_HEADER}` to be an identity")).into()
        })
}