Skip to main content

rocket/route/
uri.rs

1use std::fmt;
2
3use crate::http::uri::{self, Origin, Path};
4use crate::http::ext::IntoOwned;
5use crate::form::ValueField;
6use crate::route::Segment;
7
8/// A route URI which is matched against requests.
9///
10/// A route URI is composed of two components:
11///
12///   * `base`
13///
14///     Otherwise known as the route's "mount point", the `base` is a static
15///     [`Origin`] that prefixes the route URI. All route URIs have a `base`.
16///     When routes are created manually with [`Route::new()`], the base
17///     defaults to `/`. When mounted via [`Rocket::mount()`], the base is
18///     explicitly specified as the first argument.
19///
20///     ```rust
21///     use rocket::Route;
22///     use rocket::http::Method;
23///     # use rocket::route::dummy_handler as handler;
24///
25///     let route = Route::new(Method::Get, "/foo/<bar>", handler);
26///     assert_eq!(route.uri.base(), "/");
27///
28///     let rocket = rocket::build().mount("/base", vec![route]);
29///     let routes: Vec<_> = rocket.routes().collect();
30///     assert_eq!(routes[0].uri.base(), "/base");
31///     ```
32///
33///   * `origin`
34///
35///     Otherwise known as the "route URI", the `origin` is an [`Origin`] with
36///     potentially dynamic (`<dyn>` or `<dyn..>`) segments. It is prefixed with
37///     the `base`. This is the URI which is matched against incoming requests
38///     for routing.
39///
40///     ```rust
41///     use rocket::Route;
42///     use rocket::http::Method;
43///     # use rocket::route::dummy_handler as handler;
44///
45///     let route = Route::new(Method::Get, "/foo/<bar>", handler);
46///     assert_eq!(route.uri, "/foo/<bar>");
47///
48///     let rocket = rocket::build().mount("/base", vec![route]);
49///     let routes: Vec<_> = rocket.routes().collect();
50///     assert_eq!(routes[0].uri, "/base/foo/<bar>");
51///     ```
52///
53/// [`Rocket::mount()`]: crate::Rocket::mount()
54/// [`Route::new()`]: crate::Route::new()
55#[derive(Debug, Clone)]
56pub struct RouteUri<'a> {
57    /// The mount point.
58    pub(crate) base: Origin<'a>,
59    /// The URI _without_ the `base` mount point.
60    pub(crate) unmounted_origin: Origin<'a>,
61    /// The URI _with_ the base mount point. This is the canonical route URI.
62    pub(crate) uri: Origin<'a>,
63    /// Cached metadata about this URI.
64    pub(crate) metadata: Metadata,
65}
66
67#[derive(Debug, Clone, Copy, PartialEq, Eq)]
68pub(crate) enum Color {
69    /// Fully static: no dynamic components.
70    Static = 3,
71    /// Partially static/dynamic: some, but not all, dynamic components.
72    Partial = 2,
73    /// Fully dynamic: no static components.
74    Wild = 1,
75}
76
77#[derive(Debug, Clone)]
78pub(crate) struct Metadata {
79    /// Segments in the route URI, including base.
80    pub uri_segments: Vec<Segment>,
81    /// Numbers of segments in `uri_segments` that belong to the base.
82    pub base_len: usize,
83    /// `(name, value)` of the query segments that are static.
84    pub static_query_fields: Vec<(String, String)>,
85    /// The "color" of the route path.
86    pub path_color: Color,
87    /// The "color" of the route query, if there is query.
88    pub query_color: Option<Color>,
89    /// Whether the path has a `<trailing..>` parameter.
90    pub dynamic_trail: bool,
91}
92
93type Result<T, E = uri::Error<'static>> = std::result::Result<T, E>;
94
95impl<'a> RouteUri<'a> {
96    /// Create a new `RouteUri`.
97    ///
98    /// Panics if  `base` or `uri` cannot be parsed as `Origin`s.
99    #[track_caller]
100    pub(crate) fn new(base: &str, uri: &str) -> RouteUri<'static> {
101        Self::try_new(base, uri).expect("expected valid route URIs")
102    }
103
104    /// Creates a new `RouteUri` from a `base` mount point and a route `uri`.
105    ///
106    /// This is a fallible variant of [`RouteUri::new`] which returns an `Err`
107    /// if `base` or `uri` cannot be parsed as [`Origin`]s.
108    /// INTERNAL!
109    #[doc(hidden)]
110    pub fn try_new(base: &str, uri: &str) -> Result<RouteUri<'static>> {
111        let mut base = Origin::parse_base(base)
112            .map_err(|e| e.into_owned())?
113            .into_normalized()
114            .into_owned();
115
116        base.clear_query();
117
118        let origin = Origin::parse_route(uri)
119            .map_err(|e| e.into_owned())?
120            .into_normalized()
121            .into_owned();
122
123        // Distinguish for routes `/` with bases of `/foo/` and `/foo`. The
124        // latter base, without a trailing slash, should combine as `/foo`.
125        let route_uri = match origin.path().as_str() {
126            "/" if !base.has_trailing_slash() => match origin.query() {
127                Some(query) => format!("{}?{}", base, query),
128                None => base.to_string(),
129            }
130            _ => format!("{}{}", base, origin),
131        };
132
133        let uri = Origin::parse_route(&route_uri)
134            .map_err(|e| e.into_owned())?
135            .into_normalized()
136            .into_owned();
137
138        let metadata = Metadata::from(&base, &uri);
139
140        Ok(RouteUri { base, unmounted_origin: origin, uri, metadata })
141    }
142
143    /// Returns the complete route URI.
144    ///
145    /// **Note:** `RouteURI` derefs to the `Origin` returned by this method, so
146    /// this method should rarely be called directly.
147    ///
148    /// # Example
149    ///
150    /// ```rust
151    /// use rocket::Route;
152    /// use rocket::http::Method;
153    /// # use rocket::route::dummy_handler as handler;
154    ///
155    /// let route = Route::new(Method::Get, "/foo/bar?a=1", handler);
156    ///
157    /// // Use `inner()` directly:
158    /// assert_eq!(route.uri.inner().query().unwrap(), "a=1");
159    ///
160    /// // Use the deref implementation. This is preferred:
161    /// assert_eq!(route.uri.query().unwrap(), "a=1");
162    /// ```
163    pub fn inner(&self) -> &Origin<'a> {
164        &self.uri
165    }
166
167    /// The base mount point of this route URI.
168    ///
169    /// # Example
170    ///
171    /// ```rust
172    /// use rocket::Route;
173    /// use rocket::http::Method;
174    /// # use rocket::route::dummy_handler as handler;
175    ///
176    /// let route = Route::new(Method::Get, "/foo/bar?a=1", handler);
177    /// assert_eq!(route.uri.base(), "/");
178    ///
179    /// let route = route.rebase("/boo");
180    /// assert_eq!(route.uri.base(), "/boo");
181    ///
182    /// let route = route.rebase("/foo");
183    /// assert_eq!(route.uri.base(), "/foo/boo");
184    /// ```
185    #[inline(always)]
186    pub fn base(&self) -> Path<'_> {
187        self.base.path()
188    }
189
190    /// The route URI _without_ the base mount point.
191    ///
192    /// # Example
193    ///
194    /// ```rust
195    /// use rocket::Route;
196    /// use rocket::http::Method;
197    /// # use rocket::route::dummy_handler as handler;
198    ///
199    /// let route = Route::new(Method::Get, "/foo/bar?a=1", handler);
200    /// let route = route.rebase("/boo");
201    ///
202    /// assert_eq!(route.uri, "/boo/foo/bar?a=1");
203    /// assert_eq!(route.uri.base(), "/boo");
204    /// assert_eq!(route.uri.unmounted(), "/foo/bar?a=1");
205    /// ```
206    #[inline(always)]
207    pub fn unmounted(&self) -> &Origin<'a> {
208        &self.unmounted_origin
209    }
210
211    /// Get the default rank of a route with this URI.
212    ///
213    /// The route's default rank is determined based on the presence or absence
214    /// of static and dynamic paths and queries. See the documentation for
215    /// [`Route::new`][`crate::Route::new`] for a table summarizing the exact default ranks.
216    ///
217    /// | path    | query   | rank |
218    /// |---------|---------|------|
219    /// | static  | static  | -12  |
220    /// | static  | partial | -11  |
221    /// | static  | wild    | -10  |
222    /// | static  | none    | -9   |
223    /// | partial | static  | -8   |
224    /// | partial | partial | -7   |
225    /// | partial | wild    | -6   |
226    /// | partial | none    | -5   |
227    /// | wild    | static  | -4   |
228    /// | wild    | partial | -3   |
229    /// | wild    | wild    | -2   |
230    /// | wild    | none    | -1   |
231    pub(crate) fn default_rank(&self) -> isize {
232        let raw_path_weight = self.metadata.path_color as u8;
233        let raw_query_weight = self.metadata.query_color.map_or(0, |c| c as u8);
234        let raw_weight = (raw_path_weight << 2) | raw_query_weight;
235
236        // We subtract `3` because `raw_path` is never `0`: 0b0100 = 4 - 3 = 1.
237        -((raw_weight as isize) - 3)
238    }
239}
240
241impl Metadata {
242    fn from(base: &Origin<'_>, uri: &Origin<'_>) -> Self {
243        let uri_segments = uri.path()
244            .raw_segments()
245            .map(Segment::from)
246            .collect::<Vec<_>>();
247
248        let query_segs = uri.query()
249            .map(|q| q.raw_segments().map(Segment::from).collect::<Vec<_>>())
250            .unwrap_or_default();
251
252        let static_query_fields = query_segs.iter().filter(|s| !s.dynamic)
253            .map(|s| ValueField::parse(&s.value))
254            .map(|f| (f.name.source().to_string(), f.value.to_string()))
255            .collect();
256
257        let static_path = uri_segments.iter().all(|s| !s.dynamic);
258        let wild_path = !uri_segments.is_empty() && uri_segments.iter().all(|s| s.dynamic);
259        let path_color = match (static_path, wild_path) {
260            (true, _) => Color::Static,
261            (_, true) => Color::Wild,
262            (_, _) => Color::Partial
263        };
264
265        let query_color = (!query_segs.is_empty()).then(|| {
266            let static_query = query_segs.iter().all(|s| !s.dynamic);
267            let wild_query = query_segs.iter().all(|s| s.dynamic);
268            match (static_query, wild_query) {
269                (true, _) => Color::Static,
270                (_, true) => Color::Wild,
271                (_, _) => Color::Partial
272            }
273        });
274
275        let dynamic_trail = uri_segments.last().map_or(false, |p| p.dynamic_trail);
276        let segments = base.path().segments();
277        let num_empty = segments.clone().filter(|s| s.is_empty()).count();
278        let base_len = segments.num() - num_empty;
279
280        Metadata {
281            uri_segments, base_len, static_query_fields, path_color, query_color, dynamic_trail
282        }
283    }
284}
285
286impl<'a> std::ops::Deref for RouteUri<'a> {
287    type Target = Origin<'a>;
288
289    fn deref(&self) -> &Self::Target {
290        self.inner()
291    }
292}
293
294impl fmt::Display for RouteUri<'_> {
295    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
296        self.uri.fmt(f)
297    }
298}
299
300impl<'a, 'b> PartialEq<Origin<'b>> for RouteUri<'a> {
301    fn eq(&self, other: &Origin<'b>) -> bool { self.inner() == other }
302}
303
304impl PartialEq<str> for RouteUri<'_> {
305    fn eq(&self, other: &str) -> bool { self.inner() == other }
306}
307
308impl PartialEq<&str> for RouteUri<'_> {
309    fn eq(&self, other: &&str) -> bool { self.inner() == *other }
310}
311
312#[cfg(test)]
313mod tests {
314    macro_rules! assert_uri_equality {
315        ($base:expr, $path:expr => $ebase:expr, $epath:expr, $efull:expr) => {
316            let uri = super::RouteUri::new($base, $path);
317            assert_eq!(uri, $efull, "complete URI mismatch. expected {}, got {}", $efull, uri);
318            assert_eq!(uri.base(), $ebase, "expected base {}, got {}", $ebase, uri.base());
319            assert_eq!(uri.unmounted(), $epath, "expected unmounted {}, got {}", $epath,
320                uri.unmounted());
321        };
322    }
323
324    #[test]
325    fn test_route_uri_composition() {
326        assert_uri_equality!("/", "/" => "/", "/", "/");
327        assert_uri_equality!("/", "/foo" => "/", "/foo", "/foo");
328        assert_uri_equality!("/", "/foo/bar" => "/", "/foo/bar", "/foo/bar");
329        assert_uri_equality!("/", "/foo/" => "/", "/foo/", "/foo/");
330        assert_uri_equality!("/", "/foo/bar/" => "/", "/foo/bar/", "/foo/bar/");
331
332        assert_uri_equality!("/foo", "/" => "/foo", "/", "/foo");
333        assert_uri_equality!("/foo", "/bar" => "/foo", "/bar", "/foo/bar");
334        assert_uri_equality!("/foo", "/bar/" => "/foo", "/bar/", "/foo/bar/");
335        assert_uri_equality!("/foo", "/?baz" => "/foo", "/?baz", "/foo?baz");
336        assert_uri_equality!("/foo", "/bar?baz" => "/foo", "/bar?baz", "/foo/bar?baz");
337        assert_uri_equality!("/foo", "/bar/?baz" => "/foo", "/bar/?baz", "/foo/bar/?baz");
338
339        assert_uri_equality!("/foo/", "/" => "/foo/", "/", "/foo/");
340        assert_uri_equality!("/foo/", "/bar" => "/foo/", "/bar", "/foo/bar");
341        assert_uri_equality!("/foo/", "/bar/" => "/foo/", "/bar/", "/foo/bar/");
342        assert_uri_equality!("/foo/", "/?baz" => "/foo/", "/?baz", "/foo/?baz");
343        assert_uri_equality!("/foo/", "/bar?baz" => "/foo/", "/bar?baz", "/foo/bar?baz");
344        assert_uri_equality!("/foo/", "/bar/?baz" => "/foo/", "/bar/?baz", "/foo/bar/?baz");
345
346        assert_uri_equality!("/foo?baz", "/" => "/foo", "/", "/foo");
347        assert_uri_equality!("/foo?baz", "/bar" => "/foo", "/bar", "/foo/bar");
348        assert_uri_equality!("/foo?baz", "/bar/" => "/foo", "/bar/", "/foo/bar/");
349        assert_uri_equality!("/foo/?baz", "/" => "/foo/", "/", "/foo/");
350        assert_uri_equality!("/foo/?baz", "/bar" => "/foo/", "/bar", "/foo/bar");
351        assert_uri_equality!("/foo/?baz", "/bar/" => "/foo/", "/bar/", "/foo/bar/");
352    }
353}