Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_text/tests/annealer_corpus/rocket_route.rs

15.4 KiB, 1 run

created by r1870400018:11810, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

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 /// # Panics
188 ///
189 /// Panics if `path` is not a valid Rocket route URI.
190 ///
191 /// A valid route URI is any valid [`Origin`](uri::Origin) URI that is
192 /// normalized, that is, does not contain any empty segments except for an
193 /// optional trailing slash. Unlike a strict `Origin`, route URIs are also
194 /// allowed to contain any UTF-8 characters.
195 ///
196 /// # Example
197 ///
198 /// ```rust
199 /// use rocket::Route;
200 /// use rocket::http::Method;
201 /// # use rocket::route::dummy_handler as handler;
202 ///
203 /// // this is a route matching requests to `GET /`
204 /// let index = Route::new(Method::Get, "/", handler);
205 /// assert_eq!(index.rank, -9);
206 /// assert_eq!(index.method, Some(Method::Get));
207 /// assert_eq!(index.uri, "/");
208 /// ```
209 #[track_caller]
210 pub fn new<M: Into<Option<Method>>, H: Handler>(method: M, uri: &str, handler: H) -> Route {
211 Route::ranked(None, method.into(), uri, handler)
212 }
213
214 /// Creates a new route with the given rank, method, path, and handler with
215 /// a base of `/`. If `rank` is `None`, the computed [default
216 /// rank](#default-ranking) is used.
217 ///
218 /// # Panics
219 ///
220 /// Panics if `path` is not a valid Rocket route URI.
221 ///
222 /// A valid route URI is any valid [`Origin`](uri::Origin) URI that is
223 /// normalized, that is, does not contain any empty segments except for an
224 /// optional trailing slash. Unlike a strict `Origin`, route URIs are also
225 /// allowed to contain any UTF-8 characters.
226 ///
227 /// # Example
228 ///
229 /// ```rust
230 /// use rocket::Route;
231 /// use rocket::http::Method;
232 /// # use rocket::route::dummy_handler as handler;
233 ///
234 /// let foo = Route::ranked(1, Method::Post, "/foo?bar", handler);
235 /// assert_eq!(foo.rank, 1);
236 /// assert_eq!(foo.method, Some(Method::Post));
237 /// assert_eq!(foo.uri, "/foo?bar");
238 ///
239 /// let foo = Route::ranked(None, Method::Post, "/foo?bar", handler);
240 /// assert_eq!(foo.rank, -12);
241 /// assert_eq!(foo.method, Some(Method::Post));
242 /// assert_eq!(foo.uri, "/foo?bar");
243 /// ```
244 #[track_caller]
245 pub fn ranked<M, H, R>(rank: R, method: M, uri: &str, handler: H) -> Route
246 where M: Into<Option<Method>>,
247 H: Handler + 'static,
248 R: Into<Option<isize>>,
249 {
250 let uri = RouteUri::new("/", uri);
251 let rank = rank.into().unwrap_or_else(|| uri.default_rank());
252 Route {
253 name: None,
254 format: None,
255 sentinels: Vec::new(),
256 handler: Box::new(handler),
257 location: None,
258 method: method.into(),
259 rank,
260 uri,
261 }
262 }
263
264 /// Prefix `base` to any existing mount point base in `self`.
265 ///
266 /// If the the current mount point base is `/`, then the base is replaced by
267 /// `base`. Otherwise, `base` is prefixed to the existing `base`.
268 ///
269 /// ```rust
270 /// use rocket::Route;
271 /// use rocket::http::Method;
272 /// # use rocket::route::dummy_handler as handler;
273 /// # use rocket::uri;
274 ///
275 /// // The default base is `/`.
276 /// let index = Route::new(Method::Get, "/foo/bar", handler);
277 ///
278 /// // Since the base is `/`, rebasing replaces the base.
279 /// let rebased = index.rebase(uri!("/boo"));
280 /// assert_eq!(rebased.uri.base(), "/boo");
281 ///
282 /// // Now every rebase prefixes.
283 /// let rebased = rebased.rebase(uri!("/base"));
284 /// assert_eq!(rebased.uri.base(), "/base/boo");
285 ///
286 /// // Rebasing to `/` does nothing.
287 /// let rebased = rebased.rebase(uri!("/"));
288 /// assert_eq!(rebased.uri.base(), "/base/boo");
289 ///
290 /// // Note that trailing slashes are preserved:
291 /// let index = Route::new(Method::Get, "/foo", handler);
292 /// let rebased = index.rebase(uri!("/boo/"));
293 /// assert_eq!(rebased.uri.base(), "/boo/");
294 /// ```
295 pub fn rebase(mut self, base: uri::Origin<'_>) -> Self {
296 let new_base = match self.uri.base().as_str() {
297 "/" => base.path().to_string(),
298 _ => format!("{}{}", base.path(), self.uri.base()),
299 };
300
301 self.uri = RouteUri::new(&new_base, &self.uri.unmounted_origin.to_string());
302 self
303 }
304
305 /// Maps the `base` of this route using `mapper`, returning a new `Route`
306 /// with the returned base.
307 ///
308 /// **Note:** Prefer to use [`Route::rebase()`] whenever possible!
309 ///
310 /// `mapper` is called with the current base. The returned `String` is used
311 /// as the new base if it is a valid URI. If the returned base URI contains
312 /// a query, it is ignored. Returns an error if the base produced by
313 /// `mapper` is not a valid origin URI.
314 ///
315 /// # Example
316 ///
317 /// ```rust
318 /// use rocket::Route;
319 /// use rocket::http::Method;
320 /// # use rocket::route::dummy_handler as handler;
321 /// # use rocket::uri;
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(uri!("/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}