Skip to main content

rocket/router/
matcher.rs

1use crate::{Route, Request, Catcher};
2use crate::router::Collide;
3use crate::http::Status;
4use crate::route::Color;
5
6impl Route {
7    /// Returns `true` if `self` matches `request`.
8    ///
9    /// A [_match_](Route#routing) occurs when:
10    ///
11    ///   * The route's method matches that of the incoming request.
12    ///   * Either the route has no format _or_:
13    ///     - If the route's method supports a payload, the request's
14    ///       `Content-Type` is [fully specified] and [collides with] the
15    ///       route's format.
16    ///     - If the route's method does not support a payload, the request
17    ///       either has no `Accept` header or it [collides with] with the
18    ///       route's format.
19    ///   * All static segments in the route's URI match the corresponding
20    ///     components in the same position in the incoming request URI.
21    ///   * The route URI has no query part _or_ all static segments in the
22    ///     route's query string are in the request query string, though in any
23    ///     position.
24    ///
25    /// [fully specified]: crate::http::MediaType::specificity()
26    /// [collides with]: Route::collides_with()
27    ///
28    /// For a request to be routed to a particular route, that route must both
29    /// `match` _and_ have the highest precedence among all matching routes for
30    /// that request. In other words, a `match` is a necessary but insufficient
31    /// condition to determine if a route will handle a particular request.
32    ///
33    /// The precedence of a route is determined by its rank. Routes with lower
34    /// ranks have higher precedence. [By default](Route#default-ranking), more
35    /// specific routes are assigned a lower ranking.
36    ///
37    /// # Example
38    ///
39    /// ```rust
40    /// use rocket::Route;
41    /// use rocket::http::Method;
42    /// # use rocket::local::blocking::Client;
43    /// # use rocket::route::dummy_handler as handler;
44    ///
45    /// // This route handles GET requests to `/<hello>`.
46    /// let a = Route::new(Method::Get, "/<hello>", handler);
47    ///
48    /// // This route handles GET requests to `/здрасти`.
49    /// let b = Route::new(Method::Get, "/здрасти", handler);
50    ///
51    /// # let client = Client::debug(rocket::build()).unwrap();
52    /// // Let's say `request` is `GET /hello`. The request matches only `a`:
53    /// let request = client.get("/hello");
54    /// # let request = request.inner();
55    /// assert!(a.matches(&request));
56    /// assert!(!b.matches(&request));
57    ///
58    /// // Now `request` is `GET /здрасти`. It matches both `a` and `b`:
59    /// let request = client.get("/здрасти");
60    /// # let request = request.inner();
61    /// assert!(a.matches(&request));
62    /// assert!(b.matches(&request));
63    ///
64    /// // But `b` is more specific, so it has lower rank (higher precedence)
65    /// // by default, so Rocket would route the request to `b`, not `a`.
66    /// assert!(b.rank < a.rank);
67    /// ```
68    #[tracing::instrument(level = "trace", name = "matching", skip_all, ret)]
69    pub fn matches(&self, request: &Request<'_>) -> bool {
70        methods_match(self, request)
71            && paths_match(self, request)
72            && queries_match(self, request)
73            && formats_match(self, request)
74    }
75}
76
77impl Catcher {
78    /// Returns `true` if `self` matches errors with `status` that occurred
79    /// during `request`.
80    ///
81    /// A [_match_](Catcher#routing) between a `Catcher` and a (`Status`,
82    /// `&Request`) pair occurs when:
83    ///
84    ///   * The catcher has the same [code](Catcher::code) as
85    ///     [`status`](Status::code) _or_ is `default`.
86    ///   * The catcher's [base](Catcher::base()) is a prefix of the `request`'s
87    ///     [normalized](crate::http::uri::Origin#normalization) URI.
88    ///
89    /// For an error arising from a request to be routed to a particular
90    /// catcher, that catcher must both `match` _and_ have higher precedence
91    /// than any other catcher that matches. In other words, a `match` is a
92    /// necessary but insufficient condition to determine if a catcher will
93    /// handle a particular error.
94    ///
95    /// The precedence of a catcher is determined by:
96    ///
97    ///   1. The number of _complete_ segments in the catcher's `base`.
98    ///   2. Whether the catcher is `default` or not.
99    ///
100    /// Non-default routes, and routes with more complete segments in their
101    /// base, have higher precedence.
102    ///
103    /// # Example
104    ///
105    /// ```rust
106    /// use rocket::Catcher;
107    /// use rocket::http::Status;
108    /// # use rocket::local::blocking::Client;
109    /// # use rocket::catcher::dummy_handler as handler;
110    ///
111    /// // This catcher handles 404 errors with a base of `/`.
112    /// let a = Catcher::new(404, handler);
113    ///
114    /// // This catcher handles 404 errors with a base of `/bar`.
115    /// let b = a.clone().map_base(|_| format!("/bar")).unwrap();
116    ///
117    /// # let client = Client::debug(rocket::build()).unwrap();
118    /// // Let's say `request` is `GET /` that 404s. The error matches only `a`:
119    /// let request = client.get("/");
120    /// # let request = request.inner();
121    /// assert!(a.matches(Status::NotFound, &request));
122    /// assert!(!b.matches(Status::NotFound, &request));
123    ///
124    /// // Now `request` is a 404 `GET /bar`. The error matches `a` and `b`:
125    /// let request = client.get("/bar");
126    /// # let request = request.inner();
127    /// assert!(a.matches(Status::NotFound, &request));
128    /// assert!(b.matches(Status::NotFound, &request));
129    ///
130    /// // Note that because `b`'s base' has more complete segments that `a's,
131    /// // Rocket would route the error to `b`, not `a`, even though both match.
132    /// let a_count = a.base().segments().filter(|s| !s.is_empty()).count();
133    /// let b_count = b.base().segments().filter(|s| !s.is_empty()).count();
134    /// assert!(b_count > a_count);
135    /// ```
136    pub fn matches(&self, status: Status, request: &Request<'_>) -> bool {
137        self.code.map_or(true, |code| code == status.code) && base_matches(self, request)
138    }
139}
140
141fn base_matches(catcher: &Catcher, req: &Request<'_>) -> bool {
142    // Like a route's, the base isn't percent-decoded but the request path is.
143    let base = catcher.base();
144    let req_segments = req.uri().path().segments();
145    if base.raw_segments().count() > req_segments.num() {
146        return false;
147    }
148
149    base.raw_segments().zip(req_segments).all(|(a, b)| a.is_empty() || a == b)
150}
151
152fn methods_match(route: &Route, req: &Request<'_>) -> bool {
153    trace!(?route.method, request.method = %req.method());
154    route.method.map_or(true, |method| method == req.method())
155}
156
157fn paths_match(route: &Route, req: &Request<'_>) -> bool {
158    trace!(route.uri = %route.uri, request.uri = %req.uri());
159    let route_segments = &route.uri.metadata.uri_segments;
160    let req_segments = req.uri().path().segments();
161
162    // A route can never have more segments than a request. Recall that a
163    // trailing slash is considering a segment, albeit empty.
164    if route_segments.len() > req_segments.num() {
165        return false;
166    }
167
168    // requests with longer paths only match if we have dynamic trail (<a..>).
169    if req_segments.num() > route_segments.len() && !route.uri.metadata.dynamic_trail {
170        return false;
171    }
172
173    // We've checked everything beyond the zip of their lengths already.
174    for (route_seg, req_seg) in route_segments.iter().zip(req_segments.clone()) {
175        if route_seg.dynamic_trail {
176            return true;
177        }
178
179        if !route_seg.dynamic && route_seg.value != req_seg {
180            return false;
181        }
182    }
183
184    true
185}
186
187fn queries_match(route: &Route, req: &Request<'_>) -> bool {
188    trace!(
189        route.query = route.uri.query().map(display),
190        route.query.color = route.uri.metadata.query_color.map(debug),
191        request.query = req.uri().query().map(display),
192    );
193
194    if matches!(route.uri.metadata.query_color, None | Some(Color::Wild)) {
195        return true;
196    }
197
198    let route_query_fields = route.uri.metadata.static_query_fields.iter();
199    for (key, val) in route_query_fields {
200        if let Some(query) = req.uri().query() {
201            if !query.segments().any(|req_seg| req_seg == (key, val)) {
202                debug!(key, val, request.query = %query, "missing static query");
203                return false;
204            }
205        } else {
206            debug!(key, val, "missing static query (queryless request)");
207            return false;
208        }
209    }
210
211    true
212}
213
214fn formats_match(route: &Route, req: &Request<'_>) -> bool {
215    trace!(
216        route.format = route.format.as_ref().map(display),
217        request.format = req.format().map(display),
218    );
219
220    let route_format = match route.format {
221        Some(ref format) => format,
222        None => return true,
223    };
224
225    match route.method.and_then(|m| m.allows_request_body()) {
226        Some(true) => match req.format() {
227            Some(f) if f.specificity() == 2 => route_format.collides_with(f),
228            _ => false
229        },
230        _ => match req.format() {
231            Some(f) => route_format.collides_with(f),
232            None => true
233        }
234    }
235}
236
237#[cfg(test)]
238mod tests {
239    use crate::local::blocking::Client;
240    use crate::route::{Route, dummy_handler};
241    use crate::http::{Method, Method::*, MediaType, ContentType, Accept};
242
243    fn req_matches_route(a: &'static str, b: &'static str) -> bool {
244        let client = Client::debug_with(vec![]).expect("client");
245        let route = Route::ranked(0, Get, b, dummy_handler);
246        route.matches(&client.get(a))
247    }
248
249    #[test]
250    fn request_route_matching() {
251        assert!(req_matches_route("/a/b?a=b", "/a/b?<c>"));
252        assert!(req_matches_route("/a/b?a=b", "/<a>/b?<c>"));
253        assert!(req_matches_route("/a/b?a=b", "/<a>/<b>?<c>"));
254        assert!(req_matches_route("/a/b?a=b", "/a/<b>?<c>"));
255        assert!(req_matches_route("/?b=c", "/?<b>"));
256
257        assert!(req_matches_route("/a/b?a=b", "/a/b"));
258        assert!(req_matches_route("/a/b", "/a/b"));
259        assert!(req_matches_route("/a/b/c/d?", "/a/b/c/d"));
260        assert!(req_matches_route("/a/b/c/d?v=1&v=2", "/a/b/c/d"));
261
262        assert!(req_matches_route("/a/b", "/a/b?<c>"));
263        assert!(req_matches_route("/a/b", "/a/b?<c..>"));
264        assert!(req_matches_route("/a/b?c", "/a/b?c"));
265        assert!(req_matches_route("/a/b?c", "/a/b?<c>"));
266        assert!(req_matches_route("/a/b?c=foo&d=z", "/a/b?<c>"));
267        assert!(req_matches_route("/a/b?c=foo&d=z", "/a/b?<c..>"));
268        assert!(req_matches_route("/a/b?c=foo&d=z", "/a/b?c=foo&<c..>"));
269        assert!(req_matches_route("/a/b?c=foo&d=z", "/a/b?d=z&<c..>"));
270
271        assert!(req_matches_route("/", "/<foo>"));
272        assert!(req_matches_route("/a", "/<foo>"));
273        assert!(req_matches_route("/a", "/a"));
274        assert!(req_matches_route("/a/", "/a/"));
275
276        assert!(req_matches_route("//", "/"));
277        assert!(req_matches_route("/a///", "/a/"));
278        assert!(req_matches_route("/a/b", "/a/b"));
279
280        assert!(!req_matches_route("/a///", "/a"));
281        assert!(!req_matches_route("/a", "/a/"));
282        assert!(!req_matches_route("/a/", "/a"));
283        assert!(!req_matches_route("/a/b", "/a/b/"));
284
285        assert!(!req_matches_route("/a", "/<a>/"));
286        assert!(!req_matches_route("/a/", "/<a>"));
287        assert!(!req_matches_route("/a/b", "/<a>/b/"));
288        assert!(!req_matches_route("/a/b", "/<a>/<b>/"));
289
290        assert!(!req_matches_route("/a/b/c", "/a/b?<c>"));
291        assert!(!req_matches_route("/a?b=c", "/a/b?<c>"));
292        assert!(!req_matches_route("/?b=c", "/a/b?<c>"));
293        assert!(!req_matches_route("/?b=c", "/a?<c>"));
294
295        assert!(!req_matches_route("/a/", "/<a>/<b>/<c..>"));
296        assert!(!req_matches_route("/a/b", "/<a>/<b>/<c..>"));
297
298        assert!(!req_matches_route("/a/b?c=foo&d=z", "/a/b?a=b&<c..>"));
299        assert!(!req_matches_route("/a/b?c=foo&d=z", "/a/b?d=b&<c..>"));
300        assert!(!req_matches_route("/a/b", "/a/b?c"));
301        assert!(!req_matches_route("/a/b", "/a/b?foo"));
302        assert!(!req_matches_route("/a/b", "/a/b?foo&<rest..>"));
303        assert!(!req_matches_route("/a/b", "/a/b?<a>&b&<rest..>"));
304    }
305
306    fn req_matches_format<S1, S2>(m: Method, mt1: S1, mt2: S2) -> bool
307        where S1: Into<Option<&'static str>>, S2: Into<Option<&'static str>>
308    {
309        let client = Client::debug_with(vec![]).expect("client");
310        let mut req = client.req(m, "/");
311        if let Some(mt_str) = mt1.into() {
312            if m.allows_request_body() == Some(true) {
313                req.replace_header(mt_str.parse::<ContentType>().unwrap());
314            } else {
315                req.replace_header(mt_str.parse::<Accept>().unwrap());
316            }
317        }
318
319        let mut route = Route::new(m, "/", dummy_handler);
320        if let Some(mt_str) = mt2.into() {
321            route.format = Some(mt_str.parse::<MediaType>().unwrap());
322        }
323
324        route.matches(&req)
325    }
326
327    #[test]
328    fn test_req_route_mt_collisions() {
329        assert!(req_matches_format(Post, "application/json", "application/json"));
330        assert!(req_matches_format(Post, "application/json", "application/*"));
331        assert!(req_matches_format(Post, "application/json", "*/json"));
332        assert!(req_matches_format(Post, "text/html", "*/*"));
333
334        assert!(req_matches_format(Get, "application/json", "application/json"));
335        assert!(req_matches_format(Get, "text/html", "text/html"));
336        assert!(req_matches_format(Get, "text/html", "*/*"));
337        assert!(req_matches_format(Get, None, "*/*"));
338        assert!(req_matches_format(Get, None, "text/*"));
339        assert!(req_matches_format(Get, None, "text/html"));
340        assert!(req_matches_format(Get, None, "application/json"));
341
342        assert!(req_matches_format(Post, "text/html", None));
343        assert!(req_matches_format(Post, "application/json", None));
344        assert!(req_matches_format(Post, "x-custom/anything", None));
345        assert!(req_matches_format(Post, None, None));
346
347        assert!(req_matches_format(Get, "text/html", None));
348        assert!(req_matches_format(Get, "application/json", None));
349        assert!(req_matches_format(Get, "x-custom/anything", None));
350        assert!(req_matches_format(Get, None, None));
351        assert!(req_matches_format(Get, None, "text/html"));
352        assert!(req_matches_format(Get, None, "application/json"));
353
354        assert!(req_matches_format(Get, "text/html, text/plain", "text/html"));
355        assert!(req_matches_format(Get, "text/html; q=0.5, text/xml", "text/xml"));
356
357        assert!(!req_matches_format(Post, None, "text/html"));
358        assert!(!req_matches_format(Post, None, "text/*"));
359        assert!(!req_matches_format(Post, None, "*/text"));
360        assert!(!req_matches_format(Post, None, "*/*"));
361        assert!(!req_matches_format(Post, None, "text/html"));
362        assert!(!req_matches_format(Post, None, "application/json"));
363
364        assert!(!req_matches_format(Post, "application/json", "text/html"));
365        assert!(!req_matches_format(Post, "application/json", "text/*"));
366        assert!(!req_matches_format(Post, "application/json", "*/xml"));
367        assert!(!req_matches_format(Get, "application/json", "text/html"));
368        assert!(!req_matches_format(Get, "application/json", "text/*"));
369        assert!(!req_matches_format(Get, "application/json", "*/xml"));
370
371        assert!(!req_matches_format(Post, None, "text/html"));
372        assert!(!req_matches_format(Post, None, "application/json"));
373    }
374}