routerify 2.0.0-beta-2

A lightweight, idiomatic, composable and modular router implementation with middleware support for the Rust HTTP library hyper.rs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

use crate::regex_generator::generate_exact_match_regex;
use crate::types::RequestInfo;
use crate::Error;
use hyper::{body::HttpBody, Response};
use regex::Regex;
use std::fmt::{self, Debug, Formatter};
use std::future::Future;
use std::pin::Pin;

type HandlerWithoutInfo<B, E> = Box<dyn FnMut(Response<B>) -> HandlerWithoutInfoReturn<B, E> + Send + Sync + 'static>;
type HandlerWithoutInfoReturn<B, E> = Box<dyn Future<Output = Result<Response<B>, E>> + Send + 'static>;

type HandlerWithInfo<B, E> =
    Box<dyn FnMut(Response<B>, RequestInfo) -> HandlerWithInfoReturn<B, E> + Send + Sync + 'static>;
type HandlerWithInfoReturn<B, E> = Box<dyn Future<Output = Result<Response<B>, E>> + Send + 'static>;

/// The post middleware type. Refer to [Post Middleware](./index.html#post-middleware) for more info.
///
/// This `PostMiddleware<B, E>` type accepts two type parameters: `B` and `E`.
///
/// * The `B` represents the response body type which will be used by route handlers and the middlewares and this body type must implement
///   the [HttpBody](https://docs.rs/hyper/0.13.5/hyper/body/trait.HttpBody.html) trait. For an instance, `B` could be [hyper::Body](https://docs.rs/hyper/0.13.5/hyper/body/struct.Body.html)
///   type.
/// * The `E` represents any error type which will be used by route handlers and the middlewares. This error type must implement the [std::error::Error](https://doc.rust-lang.org/std/error/trait.Error.html).
pub struct PostMiddleware<B, E> {
    pub(crate) path: String,
    pub(crate) regex: Regex,
    // Make it an option so that when a router is used to scope in another router,
    // It can be extracted out by 'opt.take()' without taking the whole router's ownership.
    pub(crate) handler: Option<Handler<B, E>>,
}

pub(crate) enum Handler<B, E> {
    WithoutInfo(HandlerWithoutInfo<B, E>),
    WithInfo(HandlerWithInfo<B, E>),
}

impl<
        B: HttpBody + Send + Sync + Unpin + 'static,
        E: Into<Box<dyn std::error::Error + Send + Sync>> + Unpin + 'static,
    > PostMiddleware<B, E>
{
    pub(crate) fn new_with_boxed_handler<P: Into<String>>(
        path: P,
        handler: Handler<B, E>,
    ) -> crate::Result<PostMiddleware<B, E>> {
        let path = path.into();
        let (re, _) = generate_exact_match_regex(path.as_str())?;

        Ok(PostMiddleware {
            path,
            regex: re,
            handler: Some(handler),
        })
    }

    /// Creates a post middleware with a handler at the specified path.
    ///
    /// # Examples
    ///
    /// ```
    /// use routerify::{Router, Middleware, PostMiddleware};
    /// use hyper::{Response, Body};
    /// use std::convert::Infallible;
    ///
    /// # fn run() -> Router<Body, Infallible> {
    /// let router = Router::builder()
    ///      .middleware(Middleware::Post(PostMiddleware::new("/abc", |res| async move { /* Do some operations */ Ok(res) }).unwrap()))
    ///      .build()
    ///      .unwrap();
    /// # router
    /// # }
    /// # run();
    /// ```
    pub fn new<P, H, R>(path: P, mut handler: H) -> crate::Result<PostMiddleware<B, E>>
    where
        P: Into<String>,
        H: FnMut(Response<B>) -> R + Send + Sync + 'static,
        R: Future<Output = Result<Response<B>, E>> + Send + 'static,
    {
        let handler: HandlerWithoutInfo<B, E> = Box::new(move |res: Response<B>| Box::new(handler(res)));
        PostMiddleware::new_with_boxed_handler(path, Handler::WithoutInfo(handler))
    }

    /// Creates a post middleware which can access [request info](./struct.RequestInfo.html) e.g. headers, method, uri etc. It should be used when the post middleware trandforms the response based on
    /// the request information.
    ///
    /// # Examples
    ///
    /// ```
    /// use routerify::{Router, Middleware, PostMiddleware, RequestInfo};
    /// use hyper::{Response, Body};
    /// use std::convert::Infallible;
    ///
    /// async fn post_middleware_with_info_handler(res: Response<Body>, req_info: RequestInfo) -> Result<Response<Body>, Infallible> {
    ///     let headers = req_info.headers();
    ///     
    ///     // Do some response transformation based on the request headers, method etc.
    ///     
    ///     Ok(res)
    /// }
    ///
    /// # fn run() -> Router<Body, Infallible> {
    /// let router = Router::builder()
    ///      .middleware(Middleware::Post(PostMiddleware::new_with_info("/abc", post_middleware_with_info_handler).unwrap()))
    ///      .build()
    ///      .unwrap();
    /// # router
    /// # }
    /// # run();
    /// ```
    pub fn new_with_info<P, H, R>(path: P, mut handler: H) -> crate::Result<PostMiddleware<B, E>>
    where
        P: Into<String>,
        H: FnMut(Response<B>, RequestInfo) -> R + Send + Sync + 'static,
        R: Future<Output = Result<Response<B>, E>> + Send + 'static,
    {
        let handler: HandlerWithInfo<B, E> =
            Box::new(move |res: Response<B>, req_info: RequestInfo| Box::new(handler(res, req_info)));
        PostMiddleware::new_with_boxed_handler(path, Handler::WithInfo(handler))
    }

    pub(crate) fn should_require_req_meta(&self) -> bool {
        if let Some(ref handler) = self.handler {
            match handler {
                Handler::WithInfo(_) => true,
                Handler::WithoutInfo(_) => false,
            }
        } else {
            false
        }
    }

    pub(crate) async fn process(
        &mut self,
        res: Response<B>,
        req_info: Option<RequestInfo>,
    ) -> crate::Result<Response<B>> {
        let handler = self
            .handler
            .as_mut()
            .expect("A router can not be used after mounting into another router");

        match handler {
            Handler::WithoutInfo(ref mut handler) => Pin::from(handler(res))
                .await
                .map_err(|e| Error::HandlePostMiddlewareWithoutInfoRequest(e.into())),
            Handler::WithInfo(ref mut handler) => {
                Pin::from(handler(res, req_info.expect("No RequestInfo is provided")))
                    .await
                    .map_err(|e| Error::HandlePostMiddlewareWithInfoRequest(e.into()))
            }
        }
    }
}

impl<B, E> Debug for PostMiddleware<B, E> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{{ path: {:?}, regex: {:?} }}", self.path, self.regex)
    }
}