Struct Router

pub struct Router { /* private fields */ }

Routes HTTP requests within a Spin component.

Routes may contain wildcards:

• :name is a single segment wildcard. The handler can retrieve it using Params::get().
• * is a trailing wildcard (matches anything). The handler can retrieve it using Params::wildcard().

If a request matches more than one route, the match is selected according to the follow criteria:

• An exact route takes priority over any wildcard.
• A single segment wildcard takes priority over a trailing wildcard.

(This is the same logic as overlapping routes in the Spin manifest.)

Examples

Handle GET requests to a path with a wildcard, falling back to “not found”:

fn handle_route(req: Request) -> Response {
    let mut router = Router::new();
    router.get("/hello/:planet", hello_planet);
    router.any("/*", not_found);
    router.handle(req)
}

fn hello_planet(req: Request, params: Params) -> anyhow::Result<Response> {
    let planet = params.get("planet").unwrap_or("world");
    Ok(Response::new(200, format!("hello, {planet}")))
}

fn not_found(req: Request, params: Params) -> anyhow::Result<Response> {
    Ok(Response::new(404, "not found"))
}

Handle requests using a mix of synchronous and asynchronous handlers:

fn handle_route(req: Request) -> Response {
    let mut router = Router::new();
    router.get("/hello/:planet", hello_planet);
    router.get_async("/goodbye/:planet", goodbye_planet);
    router.handle(req)
}

fn hello_planet(req: Request, params: Params) -> anyhow::Result<Response> {
    todo!()
}

async fn goodbye_planet(req: Request, params: Params) -> anyhow::Result<Response> {
    todo!()
}

Route differently according to HTTP method:

fn handle_route(req: Request) -> Response {
    let mut router = Router::new();
    router.get("/user", list_users);
    router.post("/user", create_user);
    router.get("/user/:id", get_user);
    router.put("/user/:id", update_user);
    router.delete("/user/:id", delete_user);
    router.any("/user", method_not_allowed);
    router.any("/user/:id", method_not_allowed);
    router.handle(req)
}

Run the handler asynchronously:

async fn handle_route(req: Request) -> Response {
    let mut router = Router::new();
    router.get_async("/user", list_users);
    router.post_async("/user", create_user);
    router.handle_async(req).await
}

Priority when routes overlap:

fn handle_route(req: Request) -> Response {
    let mut router = Router::new();
    router.any("/*", handle_any);
    router.any("/:seg", handle_single_segment);
    router.any("/fie", handle_exact);

    // '/fie' is routed to `handle_exact`
    // '/zounds' is routed to `handle_single_segment`
    // '/zounds/fie' is routed to `handle_any`
    router.handle(req)
}

Route based on the trailing segment of a Spin wildcard route, instead of on the full path

// spin.toml
//
// [[trigger.http]]
// route = "/shop/..."

// component
fn handle_route(req: Request) -> Response {
    let mut router = Router::suffix();
    router.any("/users/*", handle_users);
    router.any("/products/*", handle_products);
    router.handle(req)
}

// '/shop/users/1' is routed to `handle_users`
// '/shop/products/1' is routed to `handle_products`

Implementations

impl Router

pub fn handle<R>(&self, request: R) -> Response

where R: TryIntoRequest, R::Error: IntoResponse,

Synchronously dispatches a request to the appropriate handler along with the URI parameters.

pub async fn handle_async<R>(&self, request: R) -> Response

where R: TryIntoRequest, R::Error: IntoResponse,

Asynchronously dispatches a request to the appropriate handler along with the URI parameters.

pub fn any<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for all methods.

pub fn any_async<F, Fut, I, O>(&mut self, path: &str, handler: F)

where F: Fn(I, Params) -> Fut + 'static, Fut: Future<Output = O> + 'static, I: TryFromRequest + 'static, I::Error: IntoResponse + 'static, O: IntoResponse + 'static,

Register an async handler at the path for all methods.

pub fn add<F, Req, Resp>(&mut self, path: &str, method: Method, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the specified HTTP method.

pub fn add_async<F, Fut, I, O>( &mut self, path: &str, method: Method, handler: F, )

where F: Fn(I, Params) -> Fut + 'static, Fut: Future<Output = O> + 'static, I: TryFromRequest + 'static, I::Error: IntoResponse + 'static, O: IntoResponse + 'static,

Register an async handler at the path for the specified HTTP method.

pub fn get<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP GET method.

pub fn get_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP GET method.

pub fn head<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP HEAD method.

pub fn head_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP HEAD method.

pub fn post<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP POST method.

pub fn post_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP POST method.

pub fn delete<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP DELETE method.

pub fn delete_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP DELETE method.

pub fn put<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP PUT method.

pub fn put_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP PUT method.

pub fn patch<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP PATCH method.

pub fn patch_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP PATCH method.

pub fn options<F, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Resp + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register a handler at the path for the HTTP OPTIONS method.

pub fn options_async<F, Fut, Req, Resp>(&mut self, path: &str, handler: F)

where F: Fn(Req, Params) -> Fut + 'static, Fut: Future<Output = Resp> + 'static, Req: TryFromRequest + 'static, Req::Error: IntoResponse + 'static, Resp: IntoResponse + 'static,

Register an async handler at the path for the HTTP OPTIONS method.

pub fn new() -> Self

Construct a new Router that matches on the full path.

pub fn suffix() -> Self

Construct a new Router that matches on the trailing wildcard component of the route.

Trait Implementations

impl Default for Router

fn default() -> Router

Returns the “default value” for a type.

impl Display for Router

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

Formats the value using the given formatter.