Struct rocket::route::Route[][src]

pub struct Route {
    pub name: Option<Cow<'static, str>>,
    pub method: Method,
    pub handler: Box<dyn Handler>,
    pub uri: RouteUri<'static>,
    pub rank: isize,
    pub format: Option<MediaType>,
    // some fields omitted
}
Expand description

A request handling route.

A route consists of exactly the information in its fields. While a Route can be instantiated directly, doing so should be a rare or nonexistent event. Instead, a Rocket application should use Rocket’s #[route] series of attributes to generate a Route.

#[get("/route/<path..>?query", rank = 2, format = "json")]
fn route_name(path: PathBuf) { /* handler procedure */ }

use rocket::http::{Method, MediaType};

let route = routes![route_name].remove(0);
assert_eq!(route.name.unwrap(), "route_name");
assert_eq!(route.method, Method::Get);
assert_eq!(route.uri, "/route/<path..>?query");
assert_eq!(route.rank, 2);
assert_eq!(route.format.unwrap(), MediaType::JSON);

Note that the rank and format attribute parameters are optional. See #[route] for details on macro usage. Note also that a route’s mounted base becomes part of its URI; see RouteUri for details.

Routing

A request matches a route iff:

  • The route’s method matches that of the incoming request.
  • The route’s format (if any) matches that of the incoming request.
    • If route specifies a format, it only matches requests for that format.
    • If route doesn’t specify a format, it matches requests for any format.
    • A route’s format matches against the Accept header in the request when the route’s method supports_payload() and Content-Type header otherwise.
    • Non-specific Accept header components (*) match anything.
  • All static components in the route’s path match the corresponding components in the same position in the incoming request.
  • All static components in the route’s query string are also in the request query string, though in any position. If there is no query in the route, requests with and without queries match.

Rocket routes requests to matching routes.

Collisions

Two routes are said to collide if there exists a request that matches both routes. Colliding routes present a routing ambiguity and are thus disallowed by Rocket. Because routes can be constructed dynamically, collision checking is done at ignite time, after it becomes statically impossible to add any more routes to an instance of Rocket.

Note that because query parsing is always lenient – extra and missing query parameters are allowed – queries do not directly impact whether two routes collide.

Resolving Collisions

Collisions are resolved through ranking. Routes with lower ranks have higher precedence during routing than routes with higher ranks. Thus, routes are attempted in ascending rank order. If a higher precedence route returns an Outcome of Forward, the next highest precedence route is attempted, and so on, until a route returns Success or Failure, or there are no more routes to try. When all routes have been attempted, Rocket issues a 404 error, handled by the appropriate Catcher.

Default Ranking

Most collisions are automatically resolved by Rocket’s default rank. The default rank prefers static components over dynamic components in both paths and queries: the more static a route’s path and query are, the lower its rank and thus the higher its precedence.

There are three “colors” to paths and queries:

  1. static - all components are static
  2. partial - at least one, but not all, components are dynamic
  3. wild - all components are dynamic

Static paths carry more weight than static queries. The same is true for partial and wild paths. This results in the following default ranking table:

pathqueryrank
staticstatic-12
staticpartial-11
staticwild-10
staticnone-9
partialstatic-8
partialpartial-7
partialwild-6
partialnone-5
wildstatic-4
wildpartial-3
wildwild-2
wildnone-1

Recall that lower ranks have higher precedence.

Example

use rocket::Route;
use rocket::http::Method;

macro_rules! assert_rank {
    ($($uri:expr => $rank:expr,)*) => {$(
        let route = Route::new(Method::Get, $uri, rocket::route::dummy_handler);
        assert_eq!(route.rank, $rank);
    )*}
}

assert_rank! {
    "/?foo" => -12,                 // static path, static query
    "/foo/bar?a=b&bob" => -12,      // static path, static query
    "/?a=b&bob" => -12,             // static path, static query

    "/?a&<zoo..>" => -11,           // static path, partial query
    "/foo?a&<zoo..>" => -11,        // static path, partial query
    "/?a&<zoo>" => -11,             // static path, partial query

    "/?<zoo..>" => -10,             // static path, wild query
    "/foo?<zoo..>" => -10,          // static path, wild query
    "/foo?<a>&<b>" => -10,          // static path, wild query

    "/" => -9,                      // static path, no query
    "/foo/bar" => -9,               // static path, no query

    "/a/<b>?foo" => -8,             // partial path, static query
    "/a/<b..>?foo" => -8,           // partial path, static query
    "/<a>/b?foo" => -8,             // partial path, static query

    "/a/<b>?<b>&c" => -7,           // partial path, partial query
    "/a/<b..>?a&<c..>" => -7,       // partial path, partial query

    "/a/<b>?<c..>" => -6,           // partial path, wild query
    "/a/<b..>?<c>&<d>" => -6,       // partial path, wild query
    "/a/<b..>?<c>" => -6,           // partial path, wild query

    "/a/<b>" => -5,                 // partial path, no query
    "/<a>/b" => -5,                 // partial path, no query
    "/a/<b..>" => -5,               // partial path, no query

    "/<b>/<c>?foo&bar" => -4,       // wild path, static query
    "/<a>/<b..>?foo" => -4,         // wild path, static query
    "/<b..>?cat" => -4,             // wild path, static query

    "/<b>/<c>?<foo>&bar" => -3,     // wild path, partial query
    "/<a>/<b..>?a&<b..>" => -3,     // wild path, partial query
    "/<b..>?cat&<dog>" => -3,       // wild path, partial query

    "/<b>/<c>?<foo>" => -2,         // wild path, wild query
    "/<a>/<b..>?<b..>" => -2,       // wild path, wild query
    "/<b..>?<c>&<dog>" => -2,       // wild path, wild query

    "/<b>/<c>" => -1,               // wild path, no query
    "/<a>/<b..>" => -1,             // wild path, no query
    "/<b..>" => -1,                 // wild path, no query
}

Fields

name: Option<Cow<'static, str>>

The name of this route, if one was given.

method: Method

The method this route matches against.

handler: Box<dyn Handler>

The function that should be called when the route matches.

uri: RouteUri<'static>

The route URI.

rank: isize

The rank of this route. Lower ranks have higher priorities.

format: Option<MediaType>

The media type this route matches against, if any.

Implementations

impl Route[src]

pub fn new<H: Handler>(method: Method, uri: &str, handler: H) -> Route[src]

Creates a new route with the given method, path, and handler with a base of / and a computed default rank.

Panics

Panics if path is not a valid Rocket route URI.

Example

use rocket::Route;
use rocket::http::Method;

// this is a rank 1 route matching requests to `GET /`
let index = Route::new(Method::Get, "/", handler);
assert_eq!(index.rank, -9);
assert_eq!(index.method, Method::Get);
assert_eq!(index.uri, "/");

pub fn ranked<H, R>(rank: R, method: Method, uri: &str, handler: H) -> Route where
    H: Handler + 'static,
    R: Into<Option<isize>>, 
[src]

Creates a new route with the given rank, method, path, and handler with a base of /. If rank is None, the computed default rank is used.

Panics

Panics if path is not a valid Rocket route URI.

Example

use rocket::Route;
use rocket::http::Method;

let foo = Route::ranked(1, Method::Post, "/foo?bar", handler);
assert_eq!(foo.rank, 1);
assert_eq!(foo.method, Method::Post);
assert_eq!(foo.uri, "/foo?bar");

let foo = Route::ranked(None, Method::Post, "/foo?bar", handler);
assert_eq!(foo.rank, -12);
assert_eq!(foo.method, Method::Post);
assert_eq!(foo.uri, "/foo?bar");

pub fn map_base<'a, F>(self, mapper: F) -> Result<Self, Error<'static>> where
    F: FnOnce(Origin<'a>) -> String
[src]

Maps the base of this route using mapper, returning a new Route with the returned base.

mapper is called with the current base. The returned String is used as the new base if it is a valid URI. If the returned base URI contains a query, it is ignored. Returns an error if the base produced by mapper is not a valid origin URI.

Example

use rocket::Route;
use rocket::http::{Method, uri::Origin};

let index = Route::new(Method::Get, "/foo/bar", handler);
assert_eq!(index.uri.base(), "/");
assert_eq!(index.uri.unmounted_origin.path(), "/foo/bar");
assert_eq!(index.uri.path(), "/foo/bar");

let index = index.map_base(|base| format!("{}{}", "/boo", base)).unwrap();
assert_eq!(index.uri.base(), "/boo");
assert_eq!(index.uri.unmounted_origin.path(), "/foo/bar");
assert_eq!(index.uri.path(), "/boo/foo/bar");

Trait Implementations

impl Clone for Route[src]

fn clone(&self) -> Route[src]

Returns a copy of the value. Read more

fn clone_from(&mut self, source: &Self)1.0.0[src]

Performs copy-assignment from source. Read more

impl Debug for Route[src]

fn fmt(&self, f: &mut Formatter<'_>) -> Result[src]

Formats the value using the given formatter. Read more

impl Display for Route[src]

fn fmt(&self, f: &mut Formatter<'_>) -> Result[src]

Formats the value using the given formatter. Read more

impl<'r> FromRequest<'r> for &'r Route[src]

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>(
    request: &'r Request<'life0>
) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>> where
    'r: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 
[src]

Derives an instance of Self from the incoming request metadata. Read more

Auto Trait Implementations

impl !RefUnwindSafe for Route

impl Send for Route

impl Sync for Route

impl Unpin for Route

impl !UnwindSafe for Route

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

pub fn type_id(&self) -> TypeId[src]

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

pub fn borrow(&self) -> &T[src]

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

pub fn borrow_mut(&mut self) -> &mut T[src]

Mutably borrows from an owned value. Read more

impl<T> From<T> for T[src]

pub fn from(t: T) -> T[src]

Performs the conversion.

impl<T> Instrument for T[src]

fn instrument(self, span: Span) -> Instrumented<Self>[src]

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

fn in_current_span(self) -> Instrumented<Self>[src]

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

pub fn into(self) -> U[src]

Performs the conversion.

impl<T> IntoCollection<T> for T

pub fn into_collection<A>(self) -> SmallVec<A> where
    A: Array<Item = T>, 

Converts self into a collection.

pub fn mapped<U, F, A>(self, f: F) -> SmallVec<A> where
    F: FnMut(T) -> U,
    A: Array<Item = U>, 

impl<T> Same<T> for T

type Output = T

Should always be Self

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

The resulting type after obtaining ownership.

pub fn to_owned(&self) -> T[src]

Creates owned data from borrowed data, usually by cloning. Read more

pub fn clone_into(&self, target: &mut T)[src]

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

impl<T> ToString for T where
    T: Display + ?Sized
[src]

pub default fn to_string(&self) -> String[src]

Converts the given value to a String. Read more

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

Performs the conversion.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

Performs the conversion.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>, 

pub fn vzip(self) -> V