Struct Router 

pub struct Router<S = ()> { /* private fields */ }

Axum-like routing table using matchit under the hood.

Implementations

impl<S> Router<S>

where S: Clone + Send + Sync + 'static,

pub fn new() -> Self

Create a new empty Router.

pub const fn normalize_trailing_slash(self) -> Self

Opt in to trailing-slash normalization: strips a single trailing / from the incoming request’s path before routing, so /foo and /foo/ reach the same route.

By default (matching Axum) routing is strict — /foo and /foo/ are distinct routes, and a mismatch 404s. This opts into the common convenience behavior natively, without pulling in tower/tower-http just for tower_http::normalize_path::NormalizePathLayer — this method mirrors that layer’s own semantics exactly (an in-place path normalization applied once per request, not a redirect), just built in.

Only meaningful on the outermost Router you actually .compile() (or hand to a Server) — like NormalizePathLayer, it operates on the whole incoming request before any route matching happens, so setting it on a router later merged/nested into another has no effect.

pub fn no_index(self) -> Self

Opt out of search-engine indexing — appropriate default hardening for .onion/.i2p deployments, where a crawlable mirror is itself an unintentional discovery/deanonymization leak (some operators don’t realize search engines index onion mirrors at all).

Adds X-Robots-Tag: noindex, nofollow to every response from this router (routes and fallback alike), and — unless the app already registers its own /robots.txt route — serves a blanket User-agent: *\nDisallow: / there too.

Example

use tachyon_web::{Router, get};

let router: Router = Router::new()
    .route("/", get(|| async { "hi" }))
    .no_index();

pub fn with_state<S2>(self, state: S) -> Router<S2>

where S2: Clone + Send + Sync + 'static,

Set the application state for this router, transitioning it to another (typically ()) state type — matching Axum’s Router<S>::with_state<S2>(self, state: S) -> Router<S2> signature.

S2 is almost always inferred as () since a fully-stated router is normally handed straight to a Server, but leaving it generic (rather than hardcoding Router<()>) matches Axum’s nested-router pattern, where an inner router’s state is supplied by an outer router before the two are merged/nested and the outer router still has its own, different state type to resolve later.

pub fn route(self, path: &str, method_router: MethodRouter<S>) -> Self

Add a route to the router.

Registering the same path more than once merges the method routers — e.g. .route("/x", get(a)).route("/x", post(b)) yields one route that answers both GET and POST — matching Axum. Registering the same method for the same path twice panics, also matching Axum.

pub const fn into_make_service(self) -> Self

A dummy/compatibility method that returns the router itself, matching Axum’s API when preparing a router to be run with a server listener.

pub fn serve_static(self, dir_path: impl AsRef<Path>) -> Self

Serve an entire directory as static files — the simplest, Nginx-like API.

Serves directly from disk on every request; it does not call static_dir::ServeDir::preload, so CacheConfig::enabled’s default of true has no effect here. Use serve_dir with a manually-preloaded ServeDir if you want the in-memory RAM cache.

Do not point dir_path at a directory that can ever contain files an untrusted user chose the bytes of (e.g. an upload folder mixed into the served tree) — see static_dir::ServeDir’s docs for why (in short: a user-supplied .svg served this way can carry an executable <script>).

Example

use tachyon_web::Router;

// Serve ./public/ at /, with index.html as the default.
let router = Router::new()
    .serve_static("./public");

pub fn serve_dir(self, prefix: &str, serve_dir: ServeDir) -> Self

Serve an entire static directory under a URL prefix with full configuration control.

Registers both an exact route (prefix) and a wildcard route (prefix/*path). Use serve_static() for the common case of serving a dir at /. See static_dir::ServeDir’s docs for the upload-safety warning before serving a directory that can contain user-supplied files.

pub fn serve_file(self, path: &str, file_path: &str) -> Result<Self, Error>

Natively serve a specific file on a specific route.

The file is read once at startup into a Bytes buffer. Every subsequent request is served from that buffer with zero I/O and zero allocations, rivalling include_bytes! without inflating the binary.

Errors

Returns an Err if the file cannot be read at startup.

pub fn serve_file_dynamic(self, path: &str, file_path: &str) -> Self

Natively serve a specific file on a specific route dynamically.

The file is read from disk on every request. Ideal for large files that change frequently where startup preloading is undesirable.

pub fn nest(self, prefix: &str, router: Self) -> Self

Nest another router under a given path prefix.

Seamlessly merges all routes from the sub-router into this router.

Matches Axum: handlers inside the nested router see a request Uri with prefix stripped (e.g. a request to /api/users/1 nested under /api sees /users/1), while crate::routing::extract::OriginalUri recovers the pre-strip, full path. Nesting is resolved once at compile() time — there’s no per-request recursive dispatch — so this is exactly as fast as a flat route table; only the one matched route’s prefix is ever stripped.

Deviation from Axum: the inner router’s own fallback is not carried over

In real Axum, nesting mounts the whole inner Router as a recursive sub-service, so a request under prefix that the inner router’s own routes don’t match still reaches the inner router’s fallback before ever falling through to the outer one. Because this implementation flattens the inner router’s routes into the same top-level route table (the design that keeps nesting as fast as a flat lookup — see above), there is no separate inner dispatch step left for a per-nest fallback to hook into: any path under prefix that isn’t one of the inner router’s own registered routes simply falls through to whatever Router::fallback (or the default 404) is configured on the outermost router — the inner router’s own .fallback(...), if it set one, is never called. Use Router::fallback on the outer router (or register an explicit catch-all route under prefix) if you need a per-module 404 handler.

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

Merge another router’s routes into this router.

If exactly one of the two routers has a fallback (or a method_not_allowed_fallback) configured, the merged router adopts it — matching Axum, which does the same for Router::fallback. Unlike nest (where the inner router’s fallback is deliberately never reachable — it would only ever fire for a request the outer router’s own routing already decided was unmatched, which the outer fallback already handles), merge treats both routers as peers, so silently dropping one side’s fallback would silently change which handler answers unmatched requests.

Panics

Panics if other defines a method for a path already registered in self, or if both routers already have a fallback/method_not_allowed_fallback configured — matching Axum’s Router::merge.

pub fn route_service<Svc, RespBody>(self, path: &str, service: Svc) -> Self

where Svc: Service<Request<Bytes>, Response = Response<RespBody>> + Clone + Send + Sync + 'static, Svc::Future: Send + 'static, Svc::Error: Into<Error> + Send, RespBody: Body<Data = Bytes> + Send + 'static, RespBody::Error: Into<Error>,

Mount a raw tower::Service at path, handling every HTTP method.

Requires the tower feature. Prefer .route(path, get(handler)) with a native handler where possible — this exists to bridge in pre-built Tower/tower-http services (e.g. tower_http::services::ServeFile) without a rewrite.

pub fn nest_service<Svc, RespBody>(self, prefix: &str, service: Svc) -> Self

where Svc: Service<Request<Bytes>, Response = Response<RespBody>> + Clone + Send + Sync + 'static, Svc::Future: Send + 'static, Svc::Error: Into<Error> + Send, RespBody: Body<Data = Bytes> + Send + 'static, RespBody::Error: Into<Error>,

Nest a raw tower::Service under prefix, with the mounted path rewritten relative to prefix before the service sees it (matching Axum’s nest_service).

Requires the tower feature.

pub fn fallback_service<Svc, RespBody>(self, service: Svc) -> Self

where Svc: Service<Request<Bytes>, Response = Response<RespBody>> + Clone + Send + Sync + 'static, Svc::Future: Send + 'static, Svc::Error: Into<Error> + Send, RespBody: Body<Data = Bytes> + Send + 'static, RespBody::Error: Into<Error>,

Set a raw tower::Service as the fallback for unmatched paths.

Requires the tower feature.

pub fn layer<L, RespBody>(self, layer: L) -> Self

where L: Layer<NextService<S>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Bytes>, Response = Response<RespBody>> + Send + 'static, <L::Service as Service<Request<Bytes>>>::Future: Send + 'static, <L::Service as Service<Request<Bytes>>>::Error: Into<Error> + Send, RespBody: Body<Data = Bytes> + Send + 'static, RespBody::Error: Into<Error>,

Apply a tower::Layer to every route and the fallback in this router.

Requires the tower feature. Prefer .hoop()/.hoop_at() for new code — this exists to bridge in existing Tower/tower-http layers (tracing, compression, timeouts) without rewriting them as native middleware.

pub fn route_layer<L, RespBody>(self, layer: L) -> Self

where L: Layer<NextService<S>> + Clone + Send + Sync + 'static, L::Service: Service<Request<Bytes>, Response = Response<RespBody>> + Send + 'static, <L::Service as Service<Request<Bytes>>>::Future: Send + 'static, <L::Service as Service<Request<Bytes>>>::Error: Into<Error> + Send, RespBody: Body<Data = Bytes> + Send + 'static, RespBody::Error: Into<Error>,

Apply a tower::Layer to every registered route, but not the fallback — matching Axum’s distinction between .layer() and .route_layer().

Requires the tower feature.

pub fn fallback<H, T>(self, handler: H) -> Self

where H: Handler<T, S>, T: 'static,

Set a custom fallback handler for requests that don’t match any route.

pub fn method_not_allowed_fallback<H, T>(self, handler: H) -> Self

where H: Handler<T, S>, T: 'static,

Set a custom fallback handler for requests whose path matches a route but whose method has no registered handler (the default is a bare 405 Method Not Allowed with an Allow header).

pub fn hoop<F, Fut, Res>(self, middleware: F) -> Self

where F: Fn(Request<Body>, Next<S>) -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Res> + Send + 'static, Res: IntoResponse + Send + 'static,

Apply a middleware handler to ALL routes and the fallback registered in this Router.

pub fn hoop_at<F, Fut, Res>( self, position: MiddlewarePosition, middleware: F, ) -> Self

where F: Fn(Request<Body>, Next<S>) -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Res> + Send + 'static, Res: IntoResponse + Send + 'static,

Apply a middleware handler at a specific position (First/Last) to ALL routes and the fallback.

pub async fn handle_request(&self, req: Request<Body>) -> Response<Body>

where S: Default,

Route an incoming request directly, compiling the router on the fly. Primarily useful for testing.

Panics

Panics if router compilation fails (e.g. a duplicate route was registered).

pub fn compile(self) -> Result<CompiledRouter<S>, RouterError>

where S: Default,

Build and compile the routing tree, returning a CompiledRouter.

Errors

Returns RouterError::DuplicateRoute if the same literal path somehow reaches compile() twice. In practice this can’t happen through the public API — route()/nest()/merge() all merge same-path entries (panicking on overlapping methods, matching Axum) — this is an internal invariant check, not a condition callers need to handle.

Trait Implementations

impl<S: Clone> Clone for Router<S>

fn clone(&self) -> Router<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> Debug for Router<S>

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

Formats the value using the given formatter.

impl<S> Default for Router<S>

where S: Clone + Send + Sync + 'static,

fn default() -> Self

Returns the “default value” for a type.

impl<B> Service<Request<B>> for Router<()>

where B: Body<Data = Bytes> + Send + 'static, B::Error: Into<Error>,

Lets an uncompiled, stateless crate::routing::Router be driven directly as a tower::Service — e.g. Router::new().route(...).oneshot(req) — with no separate .compile() call, matching axum::Router’s drop-in ergonomics exactly: build with .route()/.nest()/.merge()/.hoop()/ etc., then hand the same value straight to .oneshot(), a tower server, or anything else expecting a Service.

Internally this compiles the matchit route tree once, the first time call() runs, and caches the result in Router’s private compiled field — every builder method that mutates the route table resets that cache, so it’s impossible to silently dispatch against a stale tree. Every call after the first is exactly as cheap as calling the already-CompiledRouter directly; the split from axum::Router (which has no separate compiled form at all) is now purely internal.

Deliberately restricted to Router<()>, matching Axum exactly (Axum only implements Service for Router<()> too — a Router<S> for S != () hasn’t been given its state yet, so there’s nothing meaningful to serve). This is what makes plain Router::new().route(...).oneshot(req) type-check with no turbofish: Service has exactly one impl to unify against, same as in Axum. A router built with real shared state (State<T> extractors) still needs .with_state(actual_state) first, same as Axum — at that point it’s already a Router<()> too. For testing a still-generic Router<S>/CompiledRouter<S> for S != () directly, use CompiledRouter’s broader impl above via an explicit .compile().

use tachyon_web::{Router, get};
use tower::ServiceExt;

async fn handler() -> &'static str { "hi" }

let app = Router::new().route("/", get(handler));
let req = hyper::Request::builder().uri("/").body(http_body_util::Full::new(bytes::Bytes::new()))?;
let resp = app.oneshot(req).await?;

type Response = Response<Body>

Responses given by the service.

type Error = Infallible

Errors produced by the service.

type Future = Pin<Box<dyn Future<Output = Result<<Router as Service<Request<B>>>::Response, <Router as Service<Request<B>>>::Error>> + Send>>

The future response value.

fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

Returns Poll::Ready(Ok(())) when the service is able to process requests.

fn call(&mut self, req: Request<B>) -> Self::Future

Process the request and return the response asynchronously.