Struct under::Path

pub struct Path<'a> { /* private fields */ }

A description of a path in the router.

This is generated when you call crate::Router::at, and it contains the passed prefix from that function. Here, you can specify the behavior to perform at that prefix - the Endpoints to perform on each method of that Path.

Paths are specified to have a specific format. At any point in the path, you can use a {} pattern to denote a fragment. These fragments can then be accessed in the endpoint (or any middleware) using crate::Request::fragment. A fragment should have this pattern:

{[name][:<type>]}

Where [name] is the (optional) text-based name for the fragment, and <type> is the (optional) type of the fragment (defaulting to string). There are currently six fragment types:

• oext: matches an (optional) extension; e.g. .jpeg. This can be used to allow the front-end to optionally specify the expected content-type of the response (in addition to the Accept header).
• int: matches an integer. This integer can be positive or negative, and has no bound on length; so there is no guarentee it will fit in any native number sizes.
• uint: matches an unsigned integer. This integer must be positive. It similarly has no bound on length.
• path: matches anything, including path segments (/). This is similar to the ** glob.
• uuid: matches an RFC 4122 UUID.
• none / str / s / string: matches any characters excluding a path segment (/).

Note that using an invalid type will currently cause it to panic. Non-named fragments (e.g. {}) must be indexed using numbers, 1-indexed.

Examples

let endpoint = || under::endpoints::simple(Response::empty_204); // dummy endpoint
let mut http = under::http(); // this provides us with the Router instance.
http.at("/") // this is the Path instance.
    .get(endpoint());
 // specifies a path that should be a `/users/` followed by any
 // (unsigned) integer, followed by an optional extension (`.json`).
 http.at("/users/{id:uint}{ext:oext}")
    .get(endpoint())
    .post(endpoint());
 // specifies a path that should start with `/public/`, and then
 // some text.  This is required for `dir` to work properly.
 http.at("/public/{:path}")
    .get(endpoint());
 // another example.
 http.at("/actions/{id:uuid}")
    .get(endpoint());
http.prepare();

use http::StatusCode;
eprintln!("{:#?}", http);
expect_response(&http, "/users/1", StatusCode::NO_CONTENT).await?;
expect_response(&http, "/users/1.json", StatusCode::NO_CONTENT).await?;
expect_response(&http, "/users/aaa", StatusCode::INTERNAL_SERVER_ERROR).await?;
expect_response(&http, "/public/aa/a", StatusCode::NO_CONTENT).await?;
expect_response(&http, "/public/", StatusCode::INTERNAL_SERVER_ERROR).await?;
expect_response(&http, "/actions/00000000-0000-0000-0000-000000000000", StatusCode::NO_CONTENT).await?;
expect_response(&http, "/actions/1", StatusCode::INTERNAL_SERVER_ERROR).await?;

Implementations

impl<'a> Path<'a>

pub fn at<P: AsRef<str>>(&mut self, path: P) -> Path<'_>

This appends to the prefix, creating a new Path from the current one and the given supplemental prefix. This assumes that the prefix is never terminated with a forward slash, but always prefixed with one.

Example

let mut base = http.at("/user");
base.get(user_index);
base.at("/{id}")
    .get(user_show)
    .post(user_update)
    .delete(user_destroy);

pub fn under<P: AsRef<str>, F: FnOnce(&mut Path<'_>)>(
    &mut self,
    path: P,
    f: F
) -> &mut Self

This appends to the prefix, creating a new Path from the current one and the given supplemental prefix. This assumes that the prefix is never terminated with a forward slash, but always prefixed with one.

The created Path is then yielded to the given closure, which can be used to add routes to it; the current Path is then returned.

Example

http.under("/user", |base| {
    base.get(user_index)
        .under("/{id}", |user| {
            user
                .get(user_show)
                .post(user_update)
                .delete(user_destroy);
        });
});

pub fn all<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

Creates an endpoint responding to any method at the current prefix.

Examples

let endpoint = under::endpoints::simple(Response::empty_204);
let method = http::Method::from_bytes(b"TEST")?;
http.at("/user").all(endpoint);
http.prepare();
let response = http.handle(Request::from_method("/user", method.clone())?).await?;
assert_eq!(response.status(), http::StatusCode::NO_CONTENT);
let response = http.handle(Request::post("/user")?).await?;
assert_eq!(response.status(), http::StatusCode::NO_CONTENT);

pub fn method<E: Endpoint>(&mut self, method: Method, endpoint: E) -> &mut Self

Creates an endpoint of the specified method at the current prefix.

Examples

let method = http::Method::from_bytes(b"TEST")?;
http.at("/user").method(method.clone(), endpoint);
http.prepare();
let response = http.handle(Request::from_method("/user", method)?).await?;
assert_eq!(response.status(), http::StatusCode::NO_CONTENT);

pub fn get<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

Creates a GET endpoint at the current prefix.

Examples

let mut http = under::http();
let endpoint = under::endpoints::simple(under::Response::empty_204);
http.at("/user").get(endpoint);
http.prepare();
let response = http.handle(under::Request::get("/user")?).await?;

pub fn post<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn options<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn put<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn delete<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn head<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn trace<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn connect<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

pub fn patch<E: Endpoint>(&mut self, endpoint: E) -> &mut Self

TODO.

Trait Implementations

impl<'a> Debug for Path<'a>

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

Formats the value using the given formatter.