Skip to main content

rocket/route/
route.rs

1use std::fmt;
2use std::borrow::Cow;
3
4use crate::http::{uri, Method, MediaType};
5use crate::route::{Handler, RouteUri, BoxFuture};
6use crate::sentinel::Sentry;
7
8/// A request handling route.
9///
10/// A route consists of exactly the information in its fields. While a `Route`
11/// can be instantiated directly, doing so should be a rare or nonexistent
12/// event. Instead, a Rocket application should use Rocket's
13/// [`#[route]`](macro@crate::route) series of attributes to generate a `Route`.
14///
15/// ```rust
16/// # #[macro_use] extern crate rocket;
17/// # use std::path::PathBuf;
18/// #[get("/route/<path..>?query", rank = 2, format = "json")]
19/// fn route_name(path: PathBuf) { /* handler procedure */ }
20///
21/// use rocket::http::{Method, MediaType};
22///
23/// let route = routes![route_name].remove(0);
24/// assert_eq!(route.name.unwrap(), "route_name");
25/// assert_eq!(route.method, Some(Method::Get));
26/// assert_eq!(route.uri, "/route/<path..>?query");
27/// assert_eq!(route.rank, 2);
28/// assert_eq!(route.format.unwrap(), MediaType::JSON);
29/// ```
30///
31/// Note that the `rank` and `format` attribute parameters are optional. See
32/// [`#[route]`](macro@crate::route) for details on macro usage. Note also that
33/// a route's mounted _base_ becomes part of its URI; see [`RouteUri`] for
34/// details.
35///
36/// # Routing
37///
38/// A request is _routed_ to a route if it has the highest precedence (lowest
39/// rank) among all routes that [match](Route::matches()) the request. See
40/// [`Route::matches()`] for details on what it means for a request to match.
41///
42/// Note that a single request _may_ be routed to multiple routes if a route
43/// forwards. If a route fails, the request is instead routed to the highest
44/// precedence [`Catcher`](crate::Catcher).
45///
46/// ## Collisions
47///
48/// Two routes are said to [collide](Route::collides_with()) if there exists a
49/// request that matches both routes. Colliding routes present a routing
50/// ambiguity and are thus disallowed by Rocket. Because routes can be
51/// constructed dynamically, collision checking is done at
52/// [`ignite`](crate::Rocket::ignite()) time, after it becomes statically
53/// impossible to add any more routes to an instance of `Rocket`.
54///
55/// Note that because query parsing is always lenient -- extra and missing query
56/// parameters are allowed -- queries do not directly impact whether two routes
57/// collide.
58///
59/// ## Resolving Collisions
60///
61/// Collisions are resolved through _ranking_. Routes with lower ranks have
62/// higher precedence during routing than routes with higher ranks. Thus, routes
63/// are attempted in ascending rank order. If a higher precedence route returns
64/// an `Outcome` of `Forward`, the next highest precedence route is attempted,
65/// and so on, until a route returns `Success` or `Error`, or there are no
66/// more routes to try. When all routes have been attempted, Rocket issues a
67/// `404` error, handled by the appropriate [`Catcher`](crate::Catcher).
68///
69/// ## Default Ranking
70///
71/// Most collisions are automatically resolved by Rocket's _default rank_. The
72/// default rank prefers static components over dynamic components in both paths
73/// and queries: the _more_ static a route's path and query are, the lower its
74/// rank and thus the higher its precedence.
75///
76/// There are three "colors" to paths and queries:
77///   1. `static` - all components are static
78///   2. `partial` - at least one, but not all, components are dynamic
79///   3. `wild` - all components are dynamic
80///
81/// Static paths carry more weight than static queries. The same is true for
82/// partial and wild paths. This results in the following default ranking
83/// table:
84///
85/// | path    | query   | rank |
86/// |---------|---------|------|
87/// | static  | static  | -12  |
88/// | static  | partial | -11  |
89/// | static  | wild    | -10  |
90/// | static  | none    | -9   |
91/// | partial | static  | -8   |
92/// | partial | partial | -7   |
93/// | partial | wild    | -6   |
94/// | partial | none    | -5   |
95/// | wild    | static  | -4   |
96/// | wild    | partial | -3   |
97/// | wild    | wild    | -2   |
98/// | wild    | none    | -1   |
99///
100/// Recall that _lower_ ranks have _higher_ precedence.
101///
102/// ### Example
103///
104/// ```rust
105/// use rocket::Route;
106/// use rocket::http::Method;
107///
108/// macro_rules! assert_rank {
109///     ($($uri:expr => $rank:expr,)*) => {$(
110///         let route = Route::new(Method::Get, $uri, rocket::route::dummy_handler);
111///         assert_eq!(route.rank, $rank);
112///     )*}
113/// }
114///
115/// assert_rank! {
116///     "/?foo" => -12,                 // static path, static query
117///     "/foo/bar?a=b&bob" => -12,      // static path, static query
118///     "/?a=b&bob" => -12,             // static path, static query
119///
120///     "/?a&<zoo..>" => -11,           // static path, partial query
121///     "/foo?a&<zoo..>" => -11,        // static path, partial query
122///     "/?a&<zoo>" => -11,             // static path, partial query
123///
124///     "/?<zoo..>" => -10,             // static path, wild query
125///     "/foo?<zoo..>" => -10,          // static path, wild query
126///     "/foo?<a>&<b>" => -10,          // static path, wild query
127///
128///     "/" => -9,                      // static path, no query
129///     "/foo/bar" => -9,               // static path, no query
130///
131///     "/a/<b>?foo" => -8,             // partial path, static query
132///     "/a/<b..>?foo" => -8,           // partial path, static query
133///     "/<a>/b?foo" => -8,             // partial path, static query
134///
135///     "/a/<b>?<b>&c" => -7,           // partial path, partial query
136///     "/a/<b..>?a&<c..>" => -7,       // partial path, partial query
137///
138///     "/a/<b>?<c..>" => -6,           // partial path, wild query
139///     "/a/<b..>?<c>&<d>" => -6,       // partial path, wild query
140///     "/a/<b..>?<c>" => -6,           // partial path, wild query
141///
142///     "/a/<b>" => -5,                 // partial path, no query
143///     "/<a>/b" => -5,                 // partial path, no query
144///     "/a/<b..>" => -5,               // partial path, no query
145///
146///     "/<b>/<c>?foo&bar" => -4,       // wild path, static query
147///     "/<a>/<b..>?foo" => -4,         // wild path, static query
148///     "/<b..>?cat" => -4,             // wild path, static query
149///
150///     "/<b>/<c>?<foo>&bar" => -3,     // wild path, partial query
151///     "/<a>/<b..>?a&<b..>" => -3,     // wild path, partial query
152///     "/<b..>?cat&<dog>" => -3,       // wild path, partial query
153///
154///     "/<b>/<c>?<foo>" => -2,         // wild path, wild query
155///     "/<a>/<b..>?<b..>" => -2,       // wild path, wild query
156///     "/<b..>?<c>&<dog>" => -2,       // wild path, wild query
157///
158///     "/<b>/<c>" => -1,               // wild path, no query
159///     "/<a>/<b..>" => -1,             // wild path, no query
160///     "/<b..>" => -1,                 // wild path, no query
161/// }
162/// ```
163#[derive(Clone)]
164pub struct Route {
165    /// The name of this route, if one was given.
166    pub name: Option<Cow<'static, str>>,
167    /// The method this route matches, or `None` to match any method.
168    pub method: Option<Method>,
169    /// The function that should be called when the route matches.
170    pub handler: Box<dyn Handler>,
171    /// The route URI.
172    pub uri: RouteUri<'static>,
173    /// The rank of this route. Lower ranks have higher priorities.
174    pub rank: isize,
175    /// The media type this route matches against, if any.
176    pub format: Option<MediaType>,
177    /// The discovered sentinels.
178    pub(crate) sentinels: Vec<Sentry>,
179    /// The file, line, and column where the route was defined, if known.
180    pub(crate) location: Option<(&'static str, u32, u32)>,
181}
182
183impl Route {
184    /// Creates a new route with the given method, path, and handler with a base
185    /// of `/` and a computed [default rank](#default-ranking).
186    ///
187    /// The URI is normalized before use. Unlike a strict [`Origin`](uri::Origin),
188    /// route URIs are allowed to contain any UTF-8 characters.
189    ///
190    /// # Panics
191    ///
192    /// Panics if `path` is not a valid Rocket route URI.
193    ///
194    /// # Example
195    ///
196    /// ```rust
197    /// use rocket::Route;
198    /// use rocket::http::Method;
199    /// # use rocket::route::dummy_handler as handler;
200    ///
201    /// // this is a route matching requests to `GET /`
202    /// let index = Route::new(Method::Get, "/", handler);
203    /// assert_eq!(index.rank, -9);
204    /// assert_eq!(index.method, Some(Method::Get));
205    /// assert_eq!(index.uri, "/");
206    /// ```
207    #[track_caller]
208    pub fn new<M: Into<Option<Method>>, H: Handler>(method: M, uri: &str, handler: H) -> Route {
209        Route::ranked(None, method.into(), uri, handler)
210    }
211
212    /// Creates a new route with the given rank, method, path, and handler with
213    /// a base of `/`. If `rank` is `None`, the computed [default
214    /// rank](#default-ranking) is used.
215    ///
216    /// The URI is normalized before use. Unlike a strict [`Origin`](uri::Origin),
217    /// route URIs are allowed to contain any UTF-8 characters.
218    ///
219    /// # Panics
220    ///
221    /// Panics if `path` is not a valid Rocket route URI.
222    ///
223    /// # Example
224    ///
225    /// ```rust
226    /// use rocket::Route;
227    /// use rocket::http::Method;
228    /// # use rocket::route::dummy_handler as handler;
229    ///
230    /// let foo = Route::ranked(1, Method::Post, "/foo?bar", handler);
231    /// assert_eq!(foo.rank, 1);
232    /// assert_eq!(foo.method, Some(Method::Post));
233    /// assert_eq!(foo.uri, "/foo?bar");
234    ///
235    /// let foo = Route::ranked(None, Method::Post, "/foo?bar", handler);
236    /// assert_eq!(foo.rank, -12);
237    /// assert_eq!(foo.method, Some(Method::Post));
238    /// assert_eq!(foo.uri, "/foo?bar");
239    /// ```
240    #[track_caller]
241    pub fn ranked<M, H, R>(rank: R, method: M, uri: &str, handler: H) -> Route
242        where M: Into<Option<Method>>,
243              H: Handler + 'static,
244              R: Into<Option<isize>>,
245    {
246        let uri = RouteUri::new("/", uri);
247        let rank = rank.into().unwrap_or_else(|| uri.default_rank());
248        Route {
249            name: None,
250            format: None,
251            sentinels: Vec::new(),
252            handler: Box::new(handler),
253            location: None,
254            method: method.into(),
255            rank,
256            uri,
257        }
258    }
259
260    /// Prefix `base` to any existing mount point base in `self`.
261    ///
262    /// If the current mount point base is `/`, then the base is replaced by
263    /// `base`. Otherwise, `base` is prefixed to the existing `base`.
264    ///
265    /// Panics if `base` is not a valid route URI without dynamic parameters.
266    ///
267    /// ```rust
268    /// use rocket::Route;
269    /// use rocket::http::Method;
270    /// # use rocket::route::dummy_handler as handler;
271    ///
272    /// // The default base is `/`.
273    /// let index = Route::new(Method::Get, "/foo/bar", handler);
274    ///
275    /// // Since the base is `/`, rebasing replaces the base.
276    /// let rebased = index.rebase("/boo");
277    /// assert_eq!(rebased.uri.base(), "/boo");
278    ///
279    /// // Now every rebase prefixes.
280    /// let rebased = rebased.rebase("/base");
281    /// assert_eq!(rebased.uri.base(), "/base/boo");
282    ///
283    /// // Rebasing to `/` does nothing.
284    /// let rebased = rebased.rebase("/");
285    /// assert_eq!(rebased.uri.base(), "/base/boo");
286    ///
287    /// // Note that trailing slashes are preserved:
288    /// let index = Route::new(Method::Get, "/foo", handler);
289    /// let rebased = index.rebase("/boo/");
290    /// assert_eq!(rebased.uri.base(), "/boo/");
291    /// ```
292    #[track_caller]
293    pub fn rebase(mut self, base: &str) -> Self {
294        let base = uri::Origin::parse_base(base)
295            .expect("expected valid route base")
296            .into_normalized();
297        let new_base = match self.uri.base().as_str() {
298            "/" => base.path().to_string(),
299            _ => format!("{}{}", base.path(), self.uri.base()),
300        };
301
302        self.uri = RouteUri::new(&new_base, &self.uri.unmounted_origin.to_string());
303        self
304    }
305
306    /// Maps the `base` of this route using `mapper`, returning a new `Route`
307    /// with the returned base.
308    ///
309    /// **Note:** Prefer to use [`Route::rebase()`] whenever possible!
310    ///
311    /// `mapper` is called with the current base. The returned `String` is used
312    /// as the new base if it is a valid URI. If the returned base URI contains
313    /// a query, it is ignored. Returns an error if the base produced by
314    /// `mapper` is not a valid route URI without dynamic parameters.
315    ///
316    /// # Example
317    ///
318    /// ```rust
319    /// use rocket::Route;
320    /// use rocket::http::Method;
321    /// # use rocket::route::dummy_handler as handler;
322    ///
323    /// let index = Route::new(Method::Get, "/foo/bar", handler);
324    /// assert_eq!(index.uri.base(), "/");
325    /// assert_eq!(index.uri.unmounted().path(), "/foo/bar");
326    /// assert_eq!(index.uri.path(), "/foo/bar");
327    ///
328    /// # let old_index = index;
329    /// # let index = old_index.clone();
330    /// let mapped = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
331    /// assert_eq!(mapped.uri.base(), "/boo/");
332    /// assert_eq!(mapped.uri.unmounted().path(), "/foo/bar");
333    /// assert_eq!(mapped.uri.path(), "/boo/foo/bar");
334    ///
335    /// // Note that this produces different `base` results than `rebase`!
336    /// # let index = old_index.clone();
337    /// let rebased = index.rebase("/boo");
338    /// assert_eq!(rebased.uri.base(), "/boo");
339    /// assert_eq!(rebased.uri.unmounted().path(), "/foo/bar");
340    /// assert_eq!(rebased.uri.path(), "/boo/foo/bar");
341    /// ```
342    pub fn map_base<'a, F>(mut self, mapper: F) -> Result<Self, uri::Error<'static>>
343        where F: FnOnce(uri::Origin<'a>) -> String
344    {
345        let base = mapper(self.uri.base);
346        self.uri = RouteUri::try_new(&base, &self.uri.unmounted_origin.to_string())?;
347        Ok(self)
348    }
349}
350
351impl fmt::Debug for Route {
352    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
353        f.debug_struct("Route")
354            .field("name", &self.name)
355            .field("method", &self.method)
356            .field("uri", &self.uri)
357            .field("rank", &self.rank)
358            .field("format", &self.format)
359            .finish()
360    }
361}
362
363/// Information generated by the `route` attribute during codegen.
364#[doc(hidden)]
365pub struct StaticInfo {
366    /// The route's name, i.e, the name of the function.
367    pub name: &'static str,
368    /// The route's method.
369    pub method: Option<Method>,
370    /// The route's URi, without the base mount point.
371    pub uri: &'static str,
372    /// The route's format, if any.
373    pub format: Option<MediaType>,
374    /// The route's handler, i.e, the annotated function.
375    pub handler: for<'r> fn(&'r crate::Request<'_>, crate::Data<'r>) -> BoxFuture<'r>,
376    /// The route's rank, if any.
377    pub rank: Option<isize>,
378    /// Route-derived sentinels, if any.
379    /// This isn't `&'static [SentryInfo]` because `type_name()` isn't `const`.
380    pub sentinels: Vec<Sentry>,
381    /// The file, line, and column where the route was defined.
382    pub location: (&'static str, u32, u32),
383}
384
385#[doc(hidden)]
386impl From<StaticInfo> for Route {
387    fn from(info: StaticInfo) -> Route {
388        // This should never panic since `info.path` is statically checked.
389        let uri = RouteUri::new("/", info.uri);
390
391        Route {
392            name: Some(info.name.into()),
393            method: info.method,
394            handler: Box::new(info.handler),
395            rank: info.rank.unwrap_or_else(|| uri.default_rank()),
396            format: info.format,
397            sentinels: info.sentinels.into_iter().collect(),
398            location: Some(info.location),
399            uri,
400        }
401    }
402}