router
import std::net::http::router; · source
Types
Router
type struct Router {
routes: Array<Route>;
not_found_handler: Option<(Request) -> Response>;
method_not_allowed_handler: Option<(Request) -> Response>;
static new() -> Router;
get(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
get(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
post(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
post(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
put(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
put(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
del(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
del(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
patch(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
patch(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
head(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
head(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
options(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
options(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response) -> &Router;
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
on_not_found(mut &this, handler: (Request) -> Response) -> &Router;
on_method_not_allowed(mut &this, handler: (Request) -> Response) -> &Router;
dispatch(&this, req: Request) -> Response;
}Register routes with the per-method helpers, then hand a pointer to the server. Routes are evaluated in registration order; the first route where both method and path match wins.
/ exact root
/users exact match
/users/:id `:id` captures any non-empty segment
/files/:dir/:name two named capturesEach per-method helper has an overload taking a RouteKind, which is how you register a prefix route — one that matches as long as the pattern is a prefix of the request path, accepting trailing segments. route(method, pattern, handler) is the generic form. Every registration returns &Router, so calls chain.
on_not_found(handler) and on_method_not_allowed(handler) override the fallbacks. dispatch(req) is what the server calls.
Captured segments come back through Request::param:
function show_user(req: Request) -> Response {
match (req.param(Str::new("id"))) {
Option::Some(id) => { return Response::text(StatusCode::ok(), id.as_str()); }
Option::None => { return Response::new(StatusCode::bad_request()); }
}
}Properties
| Property | Type |
|---|---|
routes | Array<Route> |
Constructors
static new() -> Router;
static new() -> Router;Create an empty router with no registered routes and built-in fallback handlers (plain-text 404 / 405).
Methods
not_found_handler: Option<(Request) -> Response>;
method_not_allowed_handler: Option<(Request) -> Response>;
get(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
get(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a GET exact route.
get(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
get(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a GET route with explicit kind; pass RouteKind::Prefix to match any path that begins with pattern.
post(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
post(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a POST exact route.
post(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
post(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a POST route with explicit kind.
put(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
put(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a PUT exact route.
put(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
put(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a PUT route with explicit kind.
del(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
del(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a DELETE exact route.
del(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
del(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a DELETE route with explicit kind.
patch(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
patch(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a PATCH exact route.
patch(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
patch(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a PATCH route with explicit kind.
head(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
head(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register a HEAD exact route.
head(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
head(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a HEAD route with explicit kind.
options(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;
options(mut &this, pattern: Str, handler: (Request) -> Response) -> &Router;Register an OPTIONS exact route.
options(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
options(mut &this, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register an OPTIONS route with explicit kind.
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response) -> &Router;
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response) -> &Router;Register an exact route for an arbitrary Method.
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;
route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response, kind: RouteKind) -> &Router;Register a route for an arbitrary Method with explicit kind.
on_not_found(mut &this, handler: (Request) -> Response) -> &Router;
on_not_found(mut &this, handler: (Request) -> Response) -> &Router;Set a custom 404 handler. Called when no registered route matches the request path at all. The handler receives the original request with an empty params map.
on_method_not_allowed(mut &this, handler: (Request) -> Response) -> &Router;
on_method_not_allowed(mut &this, handler: (Request) -> Response) -> &Router;Set a custom 405 handler. Called when the request path matches at least one registered route but none of those routes accept the request method. The handler receives the original request with an empty params map.
dispatch(&this, req: Request) -> Response;
dispatch(&this, req: Request) -> Response;Dispatch req to the first matching route.
Route and RouteKind
type struct Route {
method: Method;
pattern: Str;
handler: (Request) -> Response;
kind: RouteKind;
}type enum RouteKind {
Exact;
Prefix;
}One registered route: the method, the pattern, the handler, and whether the pattern must match the whole path (Exact) or only lead it (Prefix).
Route
Properties
| Property | Type |
|---|---|
method | Method |
pattern | Str |
kind | RouteKind |
Methods
####### handler: (Request) -> Response;
RouteKind
Variants
| Variant | Notes |
|---|---|
Exact | All path segments must match; no trailing segments allowed. |
Prefix | The pattern must be a prefix of the path; any extra trailing segments on the request path are accepted and ignored. |
Trait implementations
Router
implement trait Drop for struct Router
Route
implement trait Drop for struct Route
type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct Router {
routes: Array<Route>;
}Method- and path-based request dispatcher.
Router.routes: Array<Route>type struct Array<T, A = GlobalAlloc> where A: Allocator {
ptr: T*;
length: i64;
capacity: i64;
alloc: A;
}Array<T, A>: growable, heap-backed, contiguous sequence.
std::collections::arraytype struct Route {
method: Method;
pattern: Str;
kind: RouteKind;
}A single registered route entry.
std::net::http::routerRouter::not_found_handler: Option<(Request) -> Response>type struct Request {
method: Method;
path: String;
version: String;
headers: Headers;
body: Array<u8>;
params: HashMap<String, String>;
}HTTP request.
std::net::http::requesttype struct Response {
status: StatusCode;
version: String;
headers: Headers;
body: Array<u8>;
}HTTP response.
std::net::http::responseRouter::method_not_allowed_handler: Option<(Request) -> Response>static name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static Router::new() -> RouterCreate an empty router with no registered routes and built-in fallback handlers (plain-text 404 / 405).
type struct Router {
routes: Array<Route>;
}Method- and path-based request dispatcher.
std::net::http::routerRouter::get(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a GET exact route.
mut &this
mut &TypeAn exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.
&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
(parameter) pattern: Strtype struct Str {
bytes: u8*;
length: u64;
}Str: a borrowed UTF-8 string slice.
std::collections::str(parameter) handler: (Request) -> Response(parameter) kind: RouteKindtype enum RouteKind {
Exact;
Prefix;
}Whether the route pattern must consume the entire request path or only a leading prefix.
std::net::http::routerRouter::post(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a POST exact route.
Router::put(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a PUT exact route.
Router::del(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a DELETE exact route.
Router::patch(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a PATCH exact route.
Router::head(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a HEAD exact route.
Router::options(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister an OPTIONS exact route.
Router::route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response) -> &RouterRegister an exact route for an arbitrary Method.
(parameter) method: Methodtype enum Method {
Get;
Head;
Post;
Put;
Delete;
Connect;
Options;
Trace;
Patch;
}HTTP method.
std::net::http::methodRouter::on_not_found(mut &this, handler: (Request) -> Response) -> &RouterSet a custom 404 handler. Called when no registered route matches the request path at all. The handler receives the original request with an empty params map.
Router::on_method_not_allowed(mut &this, handler: (Request) -> Response) -> &RouterSet a custom 405 handler. Called when the request path matches at least one registered route but none of those routes accept the request method. The handler receives the original request with an empty params map.
Router::dispatch(&this, req: Request) -> ResponseDispatch req to the first matching route.
(parameter) req: Requestfunction name<T>(param: Type) -> Ret { ... }Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.
function show_user(req: Request) -> Responsematch (subject) {
Pattern(x) => { ... }
_ => { ... }
}The primary discriminator: branches on enum variants, integers, ranges, and destructuring patterns, and the compiler rejects a match that misses a case. There is no fallthrough. As an expression it evaluates to the chosen arm's value, so every arm must produce the same type.
(parameter) req: RequestRequest::param(&this, name: Str) -> Option<String>Look up a path parameter captured by the router (e.g., :id in /users/:id). Returns an owned copy of the captured segment The caller is responsible for dropping it. Returns None when the parameter was not captured (no router, or pattern did not include a segment with that name).
static Str::new(text: string) -> StrConstruct from a NUL-terminated C-style string literal. The caller certifies that text is valid UTF-8 and outlives this view. The NUL terminator is not included in the view.
Option::Some(T)id: Stringpattern => { body }Separates a match arm's pattern from its body. Arms do not fall through.
return value;Leaves the current function with the given value. A function whose return type is not void must return one; a bare return; is for void. In an async function it completes the future with the value.
static Response::text(status: StatusCode, body: Str) -> ResponseConvenience: Response::text(StatusCode::ok(), "hello") with Content-Type text/plain; charset=utf-8 and Content-Length set.
type struct StatusCode {
code: u16;
}static StatusCode::ok() -> StatusCodeid: StringString::as_str(&this) -> StrBorrow as a Str. Invalidated by the next mutating call.
Option::Nonestatic Response::new(status: StatusCode) -> Responsestatic StatusCode::bad_request() -> StatusCodetype struct Route {
method: Method;
pattern: Str;
kind: RouteKind;
}A single registered route entry.
Route.method: MethodRoute.pattern: StrRoute::handler: (Request) -> ResponseRoute.kind: RouteKindtype enum Name {
Unit,
Payload(T),
Named { x: i32 },
}An algebraic data type. Variants may be bare or carry a tuple or struct payload, and a match on an enum must cover every variant. Name::Variant names a variant; methods are added with implement enum Name { ... }.
type enum RouteKind {
Exact;
Prefix;
}Whether the route pattern must consume the entire request path or only a leading prefix.
RouteKind::ExactAll path segments must match; no trailing segments allowed.
RouteKind::PrefixThe pattern must be a prefix of the path; any extra trailing segments on the request path are accepted and ignored.
import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
Router::route(mut &this, method: Method, pattern: Str, handler: (Request) -> Response) -> &RouterRegister an exact route for an arbitrary Method.
Route.method: MethodRoute.pattern: StrRoute::handler: (Request) -> ResponseRouter::on_not_found(mut &this, handler: (Request) -> Response) -> &RouterSet a custom 404 handler. Called when no registered route matches the request path at all. The handler receives the original request with an empty params map.
std::net::http::routerRouter::on_method_not_allowed(mut &this, handler: (Request) -> Response) -> &RouterSet a custom 405 handler. Called when the request path matches at least one registered route but none of those routes accept the request method. The handler receives the original request with an empty params map.
std::net::http::routerRouter::dispatch(&this, req: Request) -> ResponseDispatch req to the first matching route.
Router.routes: Array<Route>static Router::new() -> RouterCreate an empty router with no registered routes and built-in fallback handlers (plain-text 404 / 405).
std::net::http::routerRouter::not_found_handler: Option<(Request) -> Response>Router::method_not_allowed_handler: Option<(Request) -> Response>Router::get(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a GET exact route.
Route.kind: RouteKindRouteKind::PrefixThe pattern must be a prefix of the path; any extra trailing segments on the request path are accepted and ignored.
std::net::http::routerRouter::post(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a POST exact route.
Router::put(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a PUT exact route.
Router::del(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a DELETE exact route.
Router::patch(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a PATCH exact route.
Router::head(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister a HEAD exact route.
Router::options(mut &this, pattern: Str, handler: (Request) -> Response) -> &RouterRegister an OPTIONS exact route.
implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.
implement trait Trait for Type { ... }Introduces a trait implementation: the block supplies, for one concrete type, the method bodies the trait requires.
language referenceimplement trait Trait for Type { ... }Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.
language reference