Struct poem::Route

pub struct Route { /* private fields */ }

Routing object

You can match the full path or wildcard path, and use the Path extractor to get the path parameters.

Errors

• NotFoundError

Example

use poem::{
    get, handler,
    http::{StatusCode, Uri},
    web::Path,
    Endpoint, Request, Route,
};

#[handler]
async fn a() {}

#[handler]
async fn b(Path((group, name)): Path<(String, String)>) {
    assert_eq!(group, "foo");
    assert_eq!(name, "bar");
}

#[handler]
async fn c(Path(path): Path<String>) {
    assert_eq!(path, "d/e");
}

let app = Route::new()
    // full path
    .at("/a/b", get(a))
    // capture parameters
    .at("/b/:group/:name", get(b))
    // capture tail path
    .at("/c/*path", get(c))
    // match regex
    .at("/d/<\\d+>", get(a))
    // capture with regex
    .at("/e/:name<\\d+>", get(a));

// /a/b
let resp = app
    .call(Request::builder().uri(Uri::from_static("/a/b")).finish())
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);

// /b/:group/:name
let resp = app
    .call(
        Request::builder()
            .uri(Uri::from_static("/b/foo/bar"))
            .finish(),
    )
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);

// /c/*path
let resp = app
    .call(Request::builder().uri(Uri::from_static("/c/d/e")).finish())
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);

// /d/<\\d>
let resp = app
    .call(Request::builder().uri(Uri::from_static("/d/123")).finish())
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);

// /e/:name<\\d>
let resp = app
    .call(Request::builder().uri(Uri::from_static("/e/123")).finish())
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);

Nested

use poem::{
    handler,
    http::{StatusCode, Uri},
    Endpoint, Request, Route,
};

#[handler]
fn index() -> &'static str {
    "hello"
}

let app = Route::new().nest("/foo", Route::new().at("/bar", index));

let resp = app
    .call(
        Request::builder()
            .uri(Uri::from_static("/foo/bar"))
            .finish(),
    )
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);
assert_eq!(resp.into_body().into_string().await.unwrap(), "hello");

Nested no strip

use poem::{
    handler,
    http::{StatusCode, Uri},
    Endpoint, Request, Route,
};

#[handler]
fn index() -> &'static str {
    "hello"
}

let app = Route::new().nest_no_strip("/foo", Route::new().at("/foo/bar", index));

let resp = app
    .call(
        Request::builder()
            .uri(Uri::from_static("/foo/bar"))
            .finish(),
    )
    .await
    .unwrap();
assert_eq!(resp.status(), StatusCode::OK);
assert_eq!(resp.into_body().into_string().await.unwrap(), "hello");

Implementations

impl Route

pub fn new() -> Route

Create a new routing object.

pub fn at<E>(self, path: impl AsRef<str>, ep: E) -> Self where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Add an Endpoint to the specified path.

Panics

Panic when there are duplicates in the routing table.

pub fn try_at<E>(self, path: impl AsRef<str>, ep: E) -> Result<Self, RouteError> where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Attempts to add an Endpoint to the specified path.

pub fn nest<E>(self, path: impl AsRef<str>, ep: E) -> Self where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Nest a Endpoint to the specified path and strip the prefix.

Panics

Panic when there are duplicates in the routing table.

pub fn try_nest<E>(
    self,
    path: impl AsRef<str>,
    ep: E
) -> Result<Self, RouteError> where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Attempts to nest a Endpoint to the specified path and strip the prefix.

pub fn nest_no_strip<E>(self, path: impl AsRef<str>, ep: E) -> Self where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Nest a Endpoint to the specified path, but do not strip the prefix.

Panics

Panic when there are duplicates in the routing table.

pub fn try_nest_no_strip<E>(
    self,
    path: impl AsRef<str>,
    ep: E
) -> Result<Self, RouteError> where
    E: IntoEndpoint,
    E::Endpoint: 'static, 

Attempts to nest a Endpoint to the specified path, but do not strip the prefix.

Trait Implementations

impl Default for Route

fn default() -> Route

Returns the “default value” for a type.

impl Endpoint for Route

type Output = Response

Represents the response of the endpoint.

fn call<'life0, 'async_trait>(
    &'life0 self,
    req: Request
) -> Pin<Box<dyn Future<Output = Result<Self::Output>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Get the response to the request.

fn get_response<'life0, 'async_trait>(
    &'life0 self,
    req: Request
) -> Pin<Box<dyn Future<Output = Response> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Get the response to the request and return a Response.