topcoat_router/

route.rs

#[cfg(feature = "fs")]
mod directory;

use std::{
    any::Any,
    borrow::Cow,
    collections::HashMap,
    num::NonZeroUsize,
    ops::Index,
    pin::Pin,
    sync::{
        Arc, LazyLock,
        atomic::{AtomicUsize, Ordering},
    },
};

#[cfg(feature = "fs")]
pub use directory::*;
use topcoat_core::{
    context::{ContextMap, Cx},
    error::Result,
};

use crate::{
    Body, Endpoint, EndpointIndex, HrefTarget, IntoPath, Layer, Methods, Next, OwnedMethods, Path,
    Terminal, response::Response, route, route_endpoint,
};

/// The future returned by [`Route::handle`]: a boxed, `Send` future borrowing
/// the route and its request context.
pub type RouteFuture<'cx> = Pin<Box<dyn Future<Output = Result<Response>> + Send + 'cx>>;

/// The identity of a registered handler.
///
/// Ids are drawn from a process-wide counter with [`new`](RouteId::new), so
/// every handler in an application gets a distinct one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct RouteId(usize);

impl RouteId {
    /// Draws the next id from the process-wide counter.
    ///
    /// A handler calls this once and keeps the result as its identity.
    #[must_use]
    #[allow(clippy::new_without_default)]
    pub fn new() -> Self {
        static NEXT: AtomicUsize = AtomicUsize::new(0);
        Self(NEXT.fetch_add(1, Ordering::Relaxed))
    }
}

/// A single routable endpoint: a set of HTTP methods, a URL path, and a
/// handler.
///
/// This is the core primitive a [`Router`](crate::Router) dispatches to.
/// Register any `Route` with [`RouterBuilder::route`](crate::RouterBuilder::route).
pub trait Route: Send + Sync + 'static {
    /// The identity of this route's handler.
    fn id(&self) -> RouteId;

    /// The HTTP methods this route responds to.
    fn methods(&self) -> Methods<'_>;

    /// The URL path this route handles.
    fn path(&self) -> &Path;

    /// The values attached to this route, such as metadata that describes it.
    ///
    /// Defaults to an empty map.
    fn context(&self) -> ContextMap {
        ContextMap::new()
    }

    /// Handles a request, producing a response.
    fn handle<'cx>(&'cx self, cx: &'cx Cx, body: Body) -> RouteFuture<'cx>;

    /// Returns whether this route handles the current request.
    ///
    /// Only the handler is compared, so a route is current for every value its
    /// path parameters take, whatever the request's query or fragment.
    ///
    /// # Panics
    ///
    /// Panics if the request matched no route: either its path matched no
    /// endpoint, or the endpoint holds no route for the request's method.
    fn is_current(&self, cx: &Cx) -> bool {
        route(cx).id() == self.id()
    }
}

impl<R: Route + ?Sized> Route for &'static R {
    fn id(&self) -> RouteId {
        (**self).id()
    }

    fn methods(&self) -> Methods<'_> {
        (**self).methods()
    }

    fn path(&self) -> &Path {
        (**self).path()
    }

    fn context(&self) -> ContextMap {
        (**self).context()
    }

    fn handle<'cx>(&'cx self, cx: &'cx Cx, body: Body) -> RouteFuture<'cx> {
        (**self).handle(cx, body)
    }
}

#[cfg(feature = "discover")]
inventory::collect!(&'static dyn Route);

/// The async handler function backing a [`RouteFn`].
pub type RouteHandlerFn = for<'cx> fn(cx: &'cx Cx, body: Body) -> RouteFuture<'cx>;

/// A [`Route`] backed by a plain handler function.
///
/// Turns a function into a route without implementing [`Route`] on a struct,
/// pairing it with the methods and path it serves.
#[derive(Debug, Clone)]
pub struct RouteFn {
    /// The identity of this route's handler.
    id: RouteId,
    /// The HTTP methods this route responds to.
    methods: OwnedMethods,
    /// The URL path this route handles.
    path: Cow<'static, Path>,
    /// The handler function that produces the response.
    handle: RouteHandlerFn,
    /// The values attached to this route.
    context: ContextMap,
}

impl RouteFn {
    /// Creates a new route with explicit methods, path, and handler function.
    ///
    /// The methods are anything convertible into [`OwnedMethods`]: a single
    /// [`Method`](crate::Method), a `&'static [Method]`, a `Vec<Method>`, or
    /// [`Methods::Any`] to respond to every method.
    ///
    /// ```rust
    /// use topcoat::{
    ///     context::Cx,
    ///     router::{Body, Method, RouteFn, RouteFuture},
    /// };
    ///
    /// fn handler(_cx: &Cx, _body: Body) -> RouteFuture<'_> {
    ///     Box::pin(async move { unimplemented!() })
    /// }
    ///
    /// let form = RouteFn::new(&[Method::GET, Method::POST], "/form", handler);
    /// ```
    ///
    /// # Panics
    ///
    /// Panics if `path` is a string that is not a well-formed route path.
    #[track_caller]
    pub fn new(
        methods: impl Into<OwnedMethods>,
        path: impl IntoPath,
        handle: RouteHandlerFn,
    ) -> Self {
        Self {
            id: RouteId::new(),
            methods: methods.into(),
            path: path.into_path(),
            handle,
            context: ContextMap::new(),
        }
    }

    /// Adds `value` to the context of this route.
    ///
    /// The value shadows an earlier value of the same type. Read it during
    /// a request with [`context`](topcoat_core::context::context).
    #[must_use]
    pub fn with<T>(mut self, value: T) -> Self
    where
        T: Any + Send + Sync,
    {
        self.context.insert(value);
        self
    }
}

impl Route for RouteFn {
    fn id(&self) -> RouteId {
        self.id
    }

    fn methods(&self) -> Methods<'_> {
        self.methods.as_methods()
    }

    fn path(&self) -> &Path {
        &self.path
    }

    fn context(&self) -> ContextMap {
        self.context.clone()
    }

    fn handle<'cx>(&'cx self, cx: &'cx Cx, body: Body) -> RouteFuture<'cx> {
        (self.handle)(cx, body)
    }
}

impl HrefTarget for RouteFn {
    #[track_caller]
    fn path<'cx>(&self, cx: &'cx Cx) -> &'cx Path {
        match route_endpoint(cx, self.id) {
            Some(endpoint) => endpoint.path(),
            None => panic!(
                "route `{}` is not registered on the router serving this request",
                self.path
            ),
        }
    }
}

/// The position of a route in a router's [`Routes`] table.
///
/// Stored offset by one in a [`NonZeroUsize`] so that `Option<RouteIndex>`
/// occupies a single word, keeping an endpoint's per-method table dense.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct RouteIndex(NonZeroUsize);

impl RouteIndex {
    /// Wraps a route's position in the table.
    pub(crate) fn new(index: usize) -> Self {
        Self(NonZeroUsize::new(index.wrapping_add(1)).expect("route index overflow"))
    }

    /// Returns the wrapped position.
    pub(crate) fn get(self) -> usize {
        self.0.get() - 1
    }
}

/// A route paired with the layers that wrap it.
pub(crate) struct RouteWithLayers {
    /// The route itself.
    route: Box<dyn Route>,
    /// The layers wrapping this route, precomputed at build time from the
    /// route's path (group segments included) and ordered from least- to
    /// most-specific so the outermost layer runs first.
    layers: Box<[Arc<dyn Layer>]>,
    /// The route's context, built once when the router is built, or `None`
    /// when it holds no values.
    context: Option<Arc<ContextMap>>,
    /// The endpoint serving this route.
    endpoint: EndpointIndex,
}

impl RouteWithLayers {
    /// Returns the endpoint serving this route.
    pub(crate) fn endpoint(&self) -> EndpointIndex {
        self.endpoint
    }

    /// Returns the route's context, or `None` when it holds no values.
    pub(crate) fn shared_context(&self) -> Option<&Arc<ContextMap>> {
        self.context.as_ref()
    }
}

impl Route for RouteWithLayers {
    fn id(&self) -> RouteId {
        self.route.id()
    }

    fn methods(&self) -> Methods<'_> {
        self.route.methods()
    }

    fn path(&self) -> &Path {
        self.route.path()
    }

    fn context(&self) -> ContextMap {
        self.context.as_deref().cloned().unwrap_or_default()
    }

    fn handle<'cx>(&'cx self, cx: &'cx Cx, body: Body) -> RouteFuture<'cx> {
        Next::new(&self.layers, Terminal::Route(&*self.route)).run(cx, body)
    }
}

/// A route registered on a [`Router`](crate::Router), as visited by
/// [`Router::routes`](crate::Router::routes).
///
/// It describes the route without a request: the path and methods it is
/// served at and the values attached to it.
#[derive(Clone, Copy)]
pub struct RegisteredRoute<'router> {
    route: &'router RouteWithLayers,
    endpoint: &'router Endpoint,
}

impl<'router> RegisteredRoute<'router> {
    /// Pairs `route` with the endpoint serving it.
    pub(crate) fn new(route: &'router RouteWithLayers, endpoint: &'router Endpoint) -> Self {
        Self { route, endpoint }
    }

    /// The identity of the route's handler.
    #[must_use]
    pub fn id(&self) -> RouteId {
        self.route.id()
    }

    /// The URL path the route is served at.
    ///
    /// Parameters keep their `{name}` form. Group segments are not part of
    /// it, because they never reach the URL.
    #[must_use]
    pub fn path(&self) -> &'router Path {
        self.endpoint.path()
    }

    /// The HTTP methods the route responds to.
    #[must_use]
    pub fn methods(&self) -> Methods<'router> {
        self.route.methods()
    }

    /// The route's context: the values of the layers and layouts that wrap
    /// it, followed by its own.
    ///
    /// Values registered on the router builder are not part of it. Read them
    /// with [`Router::context`](crate::Router::context).
    #[must_use]
    pub fn context(&self) -> &'router ContextMap {
        static EMPTY: LazyLock<ContextMap> = LazyLock::new(ContextMap::new);
        match self.route.shared_context() {
            Some(context) => context,
            None => &EMPTY,
        }
    }
}

/// The routes registered on a router, in registration order, indexed by
/// [`RouteIndex`].
///
/// Routes are [`push`](Self::push)ed as the router is built, then only
/// queried: [`endpoint`](Self::endpoint) resolves a route's [`RouteId`] to the
/// endpoint serving it, and indexing by [`RouteIndex`] resolves a position
/// back to the route and its layers.
#[derive(Default)]
pub(crate) struct Routes {
    routes: Vec<RouteWithLayers>,
    endpoint_lookup: HashMap<RouteId, EndpointIndex>,
}

impl Routes {
    /// Registers `route` as served by `endpoint`, wrapped by `layers` and
    /// with the values of `context`, returning the [`RouteIndex`] that now
    /// identifies the registration.
    pub(crate) fn push(
        &mut self,
        route: Box<dyn Route>,
        endpoint: EndpointIndex,
        layers: Box<[Arc<dyn Layer>]>,
        context: ContextMap,
    ) -> RouteIndex {
        let index = RouteIndex::new(self.routes.len());
        self.endpoint_lookup.insert(route.id(), endpoint);
        let context = (!context.is_empty()).then(|| Arc::new(context));
        self.routes.push(RouteWithLayers {
            route,
            layers,
            context,
            endpoint,
        });
        index
    }

    /// Returns the endpoint serving the route registered under `id`, or `None` if
    /// this router holds no route with that identity.
    pub(crate) fn endpoint(&self, id: RouteId) -> Option<EndpointIndex> {
        self.endpoint_lookup.get(&id).copied()
    }

    /// Returns the number of routes registered so far.
    pub(crate) fn len(&self) -> usize {
        self.routes.len()
    }

    /// Iterates over the routes in registration order.
    pub(crate) fn iter(&self) -> impl Iterator<Item = &RouteWithLayers> {
        self.routes.iter()
    }
}

impl Index<RouteIndex> for Routes {
    type Output = RouteWithLayers;

    fn index(&self, index: RouteIndex) -> &Self::Output {
        &self.routes[index.get()]
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // -- RouteIndex --

    #[test]
    fn route_index_wraps_and_unwraps() {
        let index = RouteIndex::new(7);
        assert_eq!(index.get(), 7);
    }

    #[test]
    fn route_index_zero_is_a_real_index() {
        // The offset keeps index 0 representable despite the non-zero backing.
        let index = RouteIndex::new(0);
        assert_eq!(index.get(), 0);
    }

    #[test]
    fn option_route_index_stays_one_word() {
        assert_eq!(
            std::mem::size_of::<Option<RouteIndex>>(),
            std::mem::size_of::<usize>()
        );
    }
}