Struct Router

Source

pub struct Router<B = Body, E = Infallible> { /* private fields */ }

Available on crate feature server only.

Expand description

The router for routing path to Services or handlers.

Implementations§

Source §

impl<B, E> Router<B, E>
where B: Send + 'static, E: 'static,

Source

pub fn new() -> Self
where E: 'static,

Create a new router.

Source

pub fn route<S>(self, uri: S, method_router: MethodRouter<B, E>) -> Self
where S: AsRef<str>,

Create a route for the given path with the given MethodRouter.

The uri matcher is based on matchit. It supports normal path and parameterized path.

§Examples

§Normal path

use volo_http::server::route::{Router, get};

async fn index() -> &'static str {
    "Hello, World"
}

let router: Router = Router::new().route("/", get(index));

§Path with Named Parameters

Named parameters like /{id} match anything until the next / or the end of the path.

The params can be extract by extractor PathParamsMap:

use volo::FastStr;
use volo_http::server::{
    param::PathParamsMap,
    route::{Router, get},
};

async fn param(map: PathParamsMap) -> FastStr {
    map.get("id").unwrap().clone()
}

let router: Router = Router::new().route("/user/{id}", get(param));

Or you can use PathParams directly:

use volo::FastStr;
use volo_http::server::{
    param::PathParams,
    route::{Router, get},
};

async fn param(PathParams(id): PathParams<String>) -> String {
    id
}

let router: Router = Router::new().route("/user/{id}", get(param));

More than one params are also supported:

use volo::FastStr;
use volo_http::server::{
    param::PathParams,
    route::{Router, get},
};

async fn param(PathParams((user, post)): PathParams<(usize, usize)>) -> String {
    format!("user id: {user}, post id: {post}")
}

let router: Router = Router::new().route("/user/{user}/post/{post}", get(param));

§Path with Catch-all Parameters

Catch-all parameters start with * and match anything until the end of the path. They must always be at the end of the route.

use volo_http::server::{
    param::PathParams,
    route::{Router, get},
};

async fn index() -> &'static str {
    "Hello, World"
}

async fn fallback(PathParams(uri): PathParams<String>) -> String {
    format!("Path `{uri}` is not available")
}

let router: Router = Router::new()
    .route("/", get(index))
    .route("/index", get(index))
    .route("/{*fallback}", get(fallback));

For more usage methods, please refer to: matchit.

Source

pub fn nest(self, uri: U, router: Router<B, E>) -> Self
where U: AsRef<str>,

Create a route for the given path with a given Router and nest it into the current router.

The uri param is a prefix of the whole uri and will be stripped before calling the inner router, and the inner Router will handle uri without the given prefix, but all params will be kept.

§Examples

use volo_http::server::{
    param::PathParams,
    route::{Router, get},
};

async fn hello_world() -> &'static str {
    "Hello, World"
}
async fn handle_tid(PathParams(tid): PathParams<String>) -> String {
    tid
}
async fn uid_and_tid(PathParams((uid, tid)): PathParams<(String, String)>) -> String {
    format!("uid: {uid}, tid: {tid}")
}

let post_router = Router::new()
    // http://<SERVER>/post/
    .route("/", get(hello_world))
    // http://<SERVER>/post/114
    .route("/{tid}", get(handle_tid));
let user_router = Router::new()
    // http://<SERVER>/user/114/name
    .route("/name", get(hello_world))
    // http://<SERVER>/user/114/tid/514
    .route("/post/{tid}", get(uid_and_tid));

let router: Router = Router::new()
    .nest("/post", post_router)
    .nest("/user/{uid}/", user_router);

Source

pub fn nest_service<U, S>(self, uri: U, service: S) -> Self
where U: AsRef<str>, S: Service<ServerContext, Request, Error = E> + Send + Sync + 'static, S::Response: IntoResponse,

Create a route for the given path with a given Service and nest it into the current router.

The service will handle any uri with the param uri as its prefix.

Source

pub fn fallback<H, T>(self, handler: H) -> Self
where for<'a> H: Handler<T, B, E> + Clone + Send + Sync + 'a, T: 'static, E: 'static,

Set a global fallback for router.

If there is no route matches the current uri, router will call the fallback handler.

Default is returning “404 Not Found”.

Source

pub fn fallback_service<S>(self, service: S) -> Self
where for<'a> S: Service<ServerContext, Request, Error = E> + Send + Sync + 'a, S::Response: IntoResponse,

Set a global fallback for router.

If there is no route matches the current uri, router will call the fallback service.

Default is returning “404 Not Found”.

Source

pub fn merge(self, other: Self) -> Self

Merge another router to self.

§Panics

Panics if the two router have routes with the same path.

§Examples

use volo_http::server::route::{Router, get};

async fn index() -> &'static str {
    "Hello, World"
}

fn foo_router() -> Router {
    Router::new()
        .route("/foo/", get(index))
        .route("/foo/index", get(index))
}

fn bar_router() -> Router {
    Router::new()
        .route("/bar/", get(index))
        .route("/bar/index", get(index))
}

fn baz_router() -> Router {
    Router::new()
        .route("/baz/", get(index))
        .route("/baz/index", get(index))
}

let app = Router::new()
    .merge(foo_router())
    .merge(bar_router())
    .merge(baz_router());