hyper-middleware 0.0.9

//! The middleware and handler system module.
//!
//! It's highly inspired by [The Iron middleware & handler system](https://github.com/iron/iron/blob/master/iron/src/middleware/mod.rs) and intended to work with latest [Hyper][`hyper`] `0.14`.
//!
//! The middleware and handler system are the fundamental building blocks
//! for handling HTTP requests and generating responses with Hyper.
//!
//! # Handlers
//!
//! A `Handler` will produce a `Response` given a `Request`. Most handlers are
//! functions or closures that accept a `&mut Request` as an argument and return
//! an `Result` containing a `Response`. An `Result` is returned instead of
//! directly returning a `Response` in order to indicate a possibility of
//! failure (e.g. database timeout).
//!
//! Here's an example of a `Handler`:
//!
//! ```rust
//! use hyper_middleware::{async_trait, Handler, Request, Response, Result, Body};
//!
//! struct Application {}
//!
//! #[async_trait]
//! impl Handler for Application {
//!     async fn handle(&self, req: &mut Request) -> Result<Response> {
//!         Ok(Response::builder().body(Body::from("¡Hola!")).unwrap())
//!     }
//! }
//! ```
//!
//! # Middleware
//!
//! In situations involving more complex logic, it may be desirable to transform
//! `Request`s passed to a `Handler` or altering `Response`s sent to the
//! clients. For example, an authorization step could only allow requests sent
//! by authorized users to be passed to a `Handler` and respond to all other
//! requests with a 403 status code. To faciliate such use cases, Iron's
//! middleware system allows `Handler`s to be extended by defining middleware,
//! which will perform transformations.
//!
//! There are three types of middleware:
//!
//! * A `BeforeMiddleware` alters a `Request`. It can be useful for handling
//!   control flow (e.g. routing and authorization).
//! * An `AroundMiddleware` wraps a `Handler`, changing both the `Response`
//!   passed to the `Handler` and the returned `Response`.
//! * An `AfterMiddleware` performs `Response` post-processing. It can be used
//!   for editing headers or logging `Response`s, but it should _not_ be used for
//!   changing the body of a `Response`.
//!
//! See the documentation for each middleware for more details.
//!
//! ## Defining the middleware pipeline
//!
//! the `Middlewares` chain is a `Handler` that wraps another `Handler`. It is used to attach
//! middleware to the wrapped `Handler` using a `link` method corresponding to
//! each type of middleware. A sample middleware pipeline is shown below:
//!
//! ```rust
//! use hyper::Server;
//! use hyper_middleware::{async_trait, Handler, BeforeMiddleware, Body, Middlewares, Request, Response, Result, Service};
//!
//! struct Application {}
//!
//! #[async_trait]
//! impl Handler for Application {
//!     async fn handle(&self, req: &mut Request) -> Result<Response> {
//!         let mut resp = Response::new(Body::from("¡Hola!"));
//!         resp.headers_mut().insert(
//!             hyper::header::CONTENT_TYPE,
//!             "text/html; charset=utf-8".parse().unwrap(),
//!         );
//!         Ok(resp)
//!     }
//! }
//!
//! struct RequestLoggingMiddleware {}
//!
//! #[async_trait]
//! impl BeforeMiddleware for RequestLoggingMiddleware {
//!     async fn before(&self, req: &mut Request) -> Result {
//!         println!("{:?}", req);
//!         Ok(())
//!     }
//! }
//!
//! #[tokio::main(flavor = "multi_thread")]
//! async fn main() -> Result {
//!     let mut middlewares = Middlewares::new(Application {});
//!     // Plug in the custom middleware(s)
//!     middlewares.link_before(RequestLoggingMiddleware {});
//!
//!     let addr = ([127, 0, 0, 1], 8080).into();
//!     let service = Service::new(middlewares);
//!     let server = Server::bind(&addr).serve(service);
//!     println!("Listening on http://{}", addr);
//!
//!     // server.await?;
//!
//!     Ok(())
//! }

//! ```
//!
//! # The Request Handling Flow
//!
//! A diagram modeling the entire middleware system process is shown below:
//!
//! ```plain
//! [b] = BeforeMiddleware
//! [a] = AfterMiddleware
//! [[h]] = AroundMiddleware
//! [h] = Handler
//! ```
//!
//! With no errors, the flow looks like:
//!
//! ```plain
//! [b] -> [b] -> [b] -> [[[[h]]]] -> [a] -> [a] -> [a] -> [a]
//! ```
//!
//! A request first travels through all `BeforeMiddleware`, then a `Response` is
//! generated by the `Handler`, which can be an arbitrary nesting of
//! `AroundMiddleware`, then all `AfterMiddleware` are called with both the
//! `Request` and `Response`. After all `AfterMiddleware` have been fired, the
//! response is written back to the client.
//!
//! Iron's error handling system is pragmatic and focuses on tracking two pieces
//! of information for error receivers (other middleware):
//!
//! * The cause of the error
//! * The result (what to do about) the error.
//!
//! The cause of the error is represented simply by the error itself, and the
//! result of the error, representing the action to take in response to the
//! error, is a complete Response, which will be sent at the end of the error
//! flow.
//!
//! When an error is thrown in Iron by any middleware or handler returning an
//! `Err` variant with an `Error`, the flow of the `Request` switches to the
//! error flow, which proceeds to just call the `catch` method of middleware and
//! sidesteps the `Handler` entirely, since there is already a `Response` in the
//! error.
//!
//! A `Request` can exit the error flow by returning an Ok from any of the catch
//! methods. This resumes the flow at the middleware immediately following the
//! middleware which handled the error. It is impossible to "go back" to an
//! earlier middleware that was skipped.
//!
//! Generally speaking, returning a `5xx` error code means that the error flow
//! should be entered by raising an explicit error. Dealing with `4xx` errors is
//! trickier, since the server may not want to recognize an error that is
//! entirely the clients fault; handling of `4xx` error codes is up to to each
//! application and middleware author.
//!
//! Middleware authors should be cognizant that their middleware may be skipped
//! during the error flow. Anything that *must* be done to each `Request` or
//! `Response` should be run during both the normal and error flow by
//! implementing the `catch` method to also do the necessary action.

use async_recursion::async_recursion;
use async_trait::async_trait;
use std::sync::Arc;

use crate::{Error, Request, Response, Result};

#[async_trait]
/// `Handler`s are responsible for handling requests by creating `Response`s from those `Request`s.
pub trait Handler: Send + Sync + 'static {
    /// Produce a `Response` from a Request, with the possibility of error.
    async fn handle(&self, req: &mut Request) -> Result<Response>;
}

#[async_trait]
impl<F> Handler for F
where
    F: Send + Sync + 'static + Fn(&mut Request) -> Result<Response>,
{
    async fn handle(&self, req: &mut Request) -> Result<Response> {
        (*self)(req)
    }
}

#[async_trait]
impl Handler for Box<dyn Handler> {
    async fn handle(&self, req: &mut Request) -> Result<Response> {
        (**self).handle(req).await
    }
}

#[async_trait]
/// `BeforeMiddleware` are fired before a `Handler` is called inside of a Middlewares.
///
/// `BeforeMiddleware` are responsible for doing request pre-processing that requires
/// the ability to change control-flow, such as authorization middleware, or for editing
/// the request by modifying the headers.
///
/// `BeforeMiddleware` only have access to the Request, if you need to modify or read
/// a Response, you will need `AfterMiddleware`. Middleware which wishes to send an
/// early response that is not an error cannot be `BeforeMiddleware`, but should
/// instead be `AroundMiddleware`.
pub trait BeforeMiddleware: Send + Sync + 'static {
    /// Do whatever work this middleware should do with a `Request` object.
    async fn before(&self, _: &mut Request) -> Result<()> {
        Ok(())
    }

    /// Respond to an error thrown by a previous `BeforeMiddleware`.
    ///
    /// Returning a `Ok` will cause the request to resume the normal flow at the
    /// next `BeforeMiddleware`, or if this was the last `BeforeMiddleware`,
    /// at the `Handler`.
    async fn catch(&self, _: &mut Request, err: Error) -> Result<()> {
        Err(err)
    }
}

#[async_trait]
/// `AfterMiddleware` are fired after a `Handler` is called inside of the `Middlewares` chain.
///
/// `AfterMiddleware` receive both a `Request` and a `Response` and are responsible for doing
/// any response post-processing.
///
/// `AfterMiddleware` should *not* overwrite the contents of a `Response`. In
/// the common case, a complete response is generated by the Middlewares's `Handler` and
/// `AfterMiddleware` simply do post-processing of that Response, such as
/// adding headers or logging.
pub trait AfterMiddleware: Send + Sync + 'static {
    /// Do whatever post-processing this middleware should do.
    async fn after(&self, _: &mut Request, res: Response) -> Result<Response> {
        Ok(res)
    }

    /// Respond to an error thrown by previous `AfterMiddleware` or the `Handler`.
    ///
    /// Returning `Ok` will cause the request to resume the normal flow at the
    /// next `AfterMiddleware`.
    async fn catch(&self, _: &mut Request, err: Error) -> Result<Response> {
        Err(err)
    }
}

#[async_trait(?Send)]
/// `AroundMiddleware` are used to wrap and replace the `Handler` in the `Middlewares` chain.
///
/// `AroundMiddleware` produce `Handler`s through their `around` method, which is
/// called once on insertion into the `Middlewares` chain or can be called manually outside of a
/// `Middlewares` chain.
pub trait AroundMiddleware {
    /// Produce a `Handler` from this `AroundMiddleware` given another `Handler`.
    ///
    /// Usually this means wrapping the handler and editing the `Request` on the
    /// way in and the `Response` on the way out.
    ///
    /// This is called only once, when an `AroundMiddleware` is added to the `Middlewares` chain
    /// using `Middlewares::around`, it is passed the `Middlewares` chain's current `Handler`.
    async fn around(self, handler: Box<dyn Handler>) -> Box<dyn Handler>;
}

/// The middleware chain which can append other middlewares.
///
/// This is a canonical implementation of Iron's middleware system,
/// but Iron's infrastructure is flexible enough to allow alternate
/// systems.
pub struct Middlewares {
    befores: Vec<Box<dyn BeforeMiddleware>>,
    afters: Vec<Box<dyn AfterMiddleware>>,

    // Internal invariant: this is always Some
    handler: Option<Box<dyn Handler>>,
}

impl Middlewares {
    /// Construct a new middleware chain from a `Handler`.
    pub fn new<H>(handler: H) -> Self
    where
        H: Handler,
    {
        Self {
            befores: vec![],
            afters: vec![],
            handler: Some(Box::new(handler) as Box<dyn Handler>),
        }
    }

    /// Link both a before and after middleware to the chain at once.
    ///
    /// Middleware that have a Before and After piece should have a constructor
    /// which returns both as a tuple, so it can be passed directly to link.
    pub fn link<B, A>(&mut self, link: (B, A)) -> &mut Middlewares
    where
        A: AfterMiddleware,
        B: BeforeMiddleware,
    {
        let (before, after) = link;
        self.befores
            .push(Box::new(before) as Box<dyn BeforeMiddleware>);
        self.afters
            .push(Box::new(after) as Box<dyn AfterMiddleware>);
        self
    }

    /// Link a `BeforeMiddleware` to the `Middlewares` chain, after all previously linked
    /// `BeforeMiddleware`s.
    pub fn link_before<B>(&mut self, before: B) -> &mut Middlewares
    where
        B: BeforeMiddleware,
    {
        self.befores
            .push(Box::new(before) as Box<dyn BeforeMiddleware>);
        self
    }

    /// Link a `AfterMiddleware` to the `Middlewares` chain, after all previously linked
    /// `AfterMiddleware`s.
    pub fn link_after<A>(&mut self, after: A) -> &mut Middlewares
    where
        A: AfterMiddleware,
    {
        self.afters
            .push(Box::new(after) as Box<dyn AfterMiddleware>);
        self
    }

    /// Apply an `AroundMiddleware` to the `Handler` in this `Middlewares` chain.
    pub async fn link_around<A>(&mut self, around: A) -> &mut Middlewares
    where
        A: AroundMiddleware,
    {
        let mut handler = self.handler.take().unwrap();
        handler = around.around(handler).await;
        self.handler = Some(handler);
        self
    }
}

#[async_trait]
impl Handler for Middlewares {
    async fn handle(&self, req: &mut Request) -> Result<Response> {
        // Kick off at befores, which will continue into handler
        // then afters.
        self.continue_from_before(req, 0).await
    }
}

impl Middlewares {
    #[async_recursion]
    // Enter the error flow from a before middleware, starting
    // at the passed index.
    //
    // If the index is out of bounds for the before middleware Vec,
    // this instead behaves the same as fail_from_handler.
    async fn fail_from_before(
        &self,
        req: &mut Request,
        index: usize,
        mut err: Error,
    ) -> Result<Response> {
        // If this was the last before, yield to next phase.
        if index >= self.befores.len() {
            return self.fail_from_handler(req, err).await;
        }

        for (i, before) in self.befores[index..].iter().enumerate() {
            err = match before.catch(req, err).await {
                Err(err) => err,
                Ok(()) => return self.continue_from_before(req, index + i + 1).await,
            };
        }

        // Next phase
        self.fail_from_handler(req, err).await
    }

    // Enter the normal flow in the before middleware, starting with the passed
    // index.
    async fn continue_from_before(&self, req: &mut Request, index: usize) -> Result<Response> {
        // If this was the last beforemiddleware, start at the handler.
        if index >= self.befores.len() {
            return self.continue_from_handler(req).await;
        }

        for (i, before) in self.befores[index..].iter().enumerate() {
            match before.before(req).await {
                Ok(()) => {}
                Err(err) => return self.fail_from_before(req, index + i + 1, err).await,
            }
        }

        // Yield to next phase.
        self.continue_from_handler(req).await
    }

    // Enter the error flow from an errored handle, starting with the
    // first AfterMiddleware.
    async fn fail_from_handler(&self, req: &mut Request, err: Error) -> Result<Response> {
        // Yield to next phase, nothing to do here.
        self.fail_from_after(req, 0, err).await
    }

    // Enter the error flow from an errored after middleware, starting
    // with the passed index.
    //
    // If the index is out of bounds for the after middleware Vec,
    // this instead just returns the passed error.
    async fn fail_from_after(
        &self,
        req: &mut Request,
        index: usize,
        mut err: Error,
    ) -> Result<Response> {
        // If this was the last after, we're done.
        if index == self.afters.len() {
            return Err(err);
        }

        for (i, after) in self.afters[index..].iter().enumerate() {
            err = match after.catch(req, err).await {
                Err(err) => err,
                Ok(res) => return self.continue_from_after(req, index + i + 1, res).await,
            }
        }

        // Done
        Err(err)
    }

    // Enter the normal flow at the handler.
    async fn continue_from_handler(&self, req: &mut Request) -> Result<Response> {
        // unwrap is safe because it's always Some
        match self.handler.as_ref().unwrap().handle(req).await {
            Ok(res) => self.continue_from_after(req, 0, res).await,
            Err(err) => self.fail_from_handler(req, err).await,
        }
    }

    #[async_recursion]
    // Enter the normal flow in the after middleware, starting with the passed
    // index.
    async fn continue_from_after(
        &self,
        req: &mut Request,
        index: usize,
        mut res: Response,
    ) -> Result<Response> {
        // If this was the last after middleware, we're done.
        if index >= self.afters.len() {
            return Ok(res);
        }

        for (i, after) in self.afters[index..].iter().enumerate() {
            res = match after.after(req, res).await {
                Ok(res) => res,
                Err(err) => return self.fail_from_after(req, index + i + 1, err).await,
            }
        }

        // We made it with no error!
        Ok(res)
    }
}

#[async_trait]
impl<F> BeforeMiddleware for F
where
    F: Send + Sync + 'static + Fn(&mut Request) -> Result<()>,
{
    async fn before(&self, req: &mut Request) -> Result<()> {
        (*self)(req)
    }
}

#[async_trait]
impl BeforeMiddleware for Box<dyn BeforeMiddleware> {
    async fn before(&self, req: &mut Request) -> Result<()> {
        (**self).before(req).await
    }

    async fn catch(&self, req: &mut Request, err: Error) -> Result<()> {
        (**self).catch(req, err).await
    }
}

#[async_trait]
impl<T> BeforeMiddleware for Arc<T>
where
    T: BeforeMiddleware,
{
    async fn before(&self, req: &mut Request) -> Result<()> {
        (**self).before(req).await
    }

    async fn catch(&self, req: &mut Request, err: Error) -> Result<()> {
        (**self).catch(req, err).await
    }
}

#[async_trait]
impl<F> AfterMiddleware for F
where
    F: Send + Sync + 'static + Fn(&mut Request, Response) -> Result<Response>,
{
    async fn after(&self, req: &mut Request, res: Response) -> Result<Response> {
        (*self)(req, res)
    }
}

#[async_trait]
impl AfterMiddleware for Box<dyn AfterMiddleware> {
    async fn after(&self, req: &mut Request, res: Response) -> Result<Response> {
        (**self).after(req, res).await
    }

    async fn catch(&self, req: &mut Request, err: Error) -> Result<Response> {
        (**self).catch(req, err).await
    }
}

#[async_trait]
impl<T> AfterMiddleware for Arc<T>
where
    T: AfterMiddleware,
{
    async fn after(&self, req: &mut Request, res: Response) -> Result<Response> {
        (**self).after(req, res).await
    }

    async fn catch(&self, req: &mut Request, err: Error) -> Result<Response> {
        (**self).catch(req, err).await
    }
}

#[async_trait(?Send)]
impl<F> AroundMiddleware for F
where
    F: FnOnce(Box<dyn Handler>) -> Box<dyn Handler>,
{
    async fn around(self, handler: Box<dyn Handler>) -> Box<dyn Handler> {
        self(handler)
    }
}