Struct ServerRouter 

pub struct ServerRouter { /* private fields */ }

Unified router with hierarchical routing support

Supports multiple API styles:

• FastAPI-style: Function-based routes
• DRF-style: ViewSets with automatic CRUD
• Django-style: Class-based views

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

// Create a users sub-router
let users_router = ServerRouter::new()
    .with_namespace("users")
    .function("/export/", Method::GET, |_req| async { Ok(Response::ok()) });

// Verify users router has namespace
assert_eq!(users_router.namespace(), Some("users"));

// Create root router
let router = ServerRouter::new()
    .with_prefix("/api/v1/")
    .with_namespace("v1")
    .function("/health/", Method::GET, |_req| async { Ok(Response::ok()) })
    .mount("/users/", users_router);

// Verify root router configuration
assert_eq!(router.prefix(), "/api/v1/");
assert_eq!(router.namespace(), Some("v1"));

// Generated URLs:
// /api/v1/health/
// /api/v1/users/export/

Implementations

impl ServerRouter

pub fn new() -> ServerRouter

Create a new ServerRouter

Examples

use reinhardt_urls::routers::ServerRouter;

let router = ServerRouter::new();

pub fn with_prefix(self, prefix: impl Into<String>) -> ServerRouter

Set the prefix for this router

Examples

use reinhardt_urls::routers::ServerRouter;

let router = ServerRouter::new()
    .with_prefix("/api/v1");

pub fn with_namespace(self, namespace: impl Into<String>) -> ServerRouter

Set the namespace for this router

Examples

use reinhardt_urls::routers::ServerRouter;

let router = ServerRouter::new()
    .with_namespace("v1");

pub fn with_di_context(self, ctx: Arc<InjectionContext>) -> ServerRouter

Set the DI context for this router

Examples

use reinhardt_urls::routers::ServerRouter;
use reinhardt_di::{InjectionContext, SingletonScope};
use std::sync::Arc;

let singleton_scope = Arc::new(SingletonScope::new());
let di_ctx = Arc::new(InjectionContext::builder(singleton_scope).build());
let router = ServerRouter::new()
    .with_di_context(di_ctx);

pub fn with_middleware<M>(self, mw: M) -> ServerRouter

where M: Middleware + 'static,

Add middleware to this router

Examples

use reinhardt_urls::routers::ServerRouter;
use reinhardt_middleware::LoggingMiddleware;

let router = ServerRouter::new()
    .with_middleware(LoggingMiddleware::new());

pub fn exclude(self, pattern: &str) -> ServerRouter

Exclude a URL path from the most recently added middleware.

Paths ending with / are treated as prefix matches: any request path starting with the given prefix will skip the middleware. Paths without trailing / require an exact match.

This method operates on the last middleware added via with_middleware(). Multiple .exclude() calls accumulate exclusions on the same middleware.

Panics

Panics if no middleware has been added yet.

Examples

use reinhardt_urls::routers::ServerRouter;
use reinhardt_middleware::LoggingMiddleware;

let router = ServerRouter::new()
    .with_middleware(LoggingMiddleware::new())
        .exclude("/api/auth/")    // prefix: skips /api/auth/*
        .exclude("/health");      // exact: skips only /health

pub fn mount(self, prefix: &str, child: ServerRouter) -> ServerRouter

Mount a child router at the given prefix

Panics

Panics if the prefix is non-empty, not “/” and doesn’t end with “/”. This follows Django’s URL configuration conventions.

Also panics if the prefix contains a path parameter placeholder (e.g. /orgs/{org}/). Mount prefixes are matched as literal strings, so placeholders would silently cause all child routes to return 404. Use route() with the full path on the child router instead, or mount at a literal prefix.

Examples

use reinhardt_urls::routers::ServerRouter;

let users_router = ServerRouter::new()
    .with_namespace("users");

let router = ServerRouter::new()
    .with_prefix("/api")
    .mount("/users/", users_router);  // Note: trailing slash required

// Verify the router was created successfully
assert_eq!(router.prefix(), "/api");

Using “/” for root mounting is also valid:

use reinhardt_urls::routers::ServerRouter;

let app_router = ServerRouter::new();
let router = ServerRouter::new().mount("/", app_router);

pub fn mount_mut(&mut self, prefix: &str, child: ServerRouter)

Mount a child router (mutable version)

Examples

use reinhardt_urls::routers::ServerRouter;

let mut router = ServerRouter::new();
let users_router = ServerRouter::new();

router.mount_mut("/users/", users_router);

pub fn group(self, routers: Vec<ServerRouter>) -> ServerRouter

Add multiple child routers at once

Examples

use reinhardt_urls::routers::ServerRouter;

let users = ServerRouter::new().with_prefix("/users");
let posts = ServerRouter::new().with_prefix("/posts");

let router = ServerRouter::new()
    .group(vec![users, posts]);

// Verify the router was created successfully
assert_eq!(router.prefix(), "");

impl ServerRouter

pub fn validate_routes(&self) -> Result<(), Vec<String>>

Validate all routes by compiling them and returning any errors.

Call this at application startup to detect invalid route patterns early. Returns Ok(()) if all routes compiled successfully, or Err with a list of compilation error messages.

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

let router = ServerRouter::new()
    .function("/users/{id}", Method::GET, handler);

// Validate routes at startup
assert!(router.validate_routes().is_ok());

pub fn validate_route_names(&self) -> Result<(), Vec<String>>

Validate that no duplicate route names exist among all collected routes.

Returns Ok(()) if all names are unique, or Err(errors) with details about each duplicate.

impl ServerRouter

pub fn prefix(&self) -> &str

Get the prefix of this router

pub fn namespace(&self) -> Option<&str>

Get the namespace of this router

pub fn children_count(&self) -> usize

Get the number of child routers

pub fn get_registered_middleware(&self) -> Vec<MiddlewareInfo>

Get all registered middleware information

Returns a deduplicated list of middleware registered on this router and all child routers. The order reflects registration order.

pub fn get_all_routes( &self, ) -> Vec<(String, Option<String>, Option<String>, Vec<Method>)>

Get all routes from this router and its children

Returns a vector of tuples containing (full_path, name, namespace, methods). This recursively collects routes from all child routers.

Examples

let router = ServerRouter::new()
    .with_prefix("/api/v1")
    .function("/users", Method::GET, handler);

let routes = router.get_all_routes();
// Returns: [("/api/v1/users", None, None, vec![Method::GET])]

pub fn get_full_namespace( &self, parent_namespace: Option<&str>, ) -> Option<String>

Get the fully qualified namespace for this router

Returns the complete namespace chain from root to this router. For example, if this router has namespace “users” and its parent has “v1”, this returns “v1:users”.

Arguments

• parent_namespace - The parent router’s namespace (if any)

Examples

let router = ServerRouter::new().with_namespace("users");
assert_eq!(router.get_full_namespace(Some("v1")), Some("v1:users".to_string()));
assert_eq!(router.get_full_namespace(None), Some("users".to_string()));

pub fn register_all_routes(&mut self) -> Vec<String>

Register all routes with the URL reverser

This recursively registers all routes from this router and its children with their fully qualified names (namespace:name format).

Examples

let mut router = ServerRouter::new()
    .with_namespace("v1");

// After registering routes, you can reverse them:
router.register_all_routes();
let url = router.reverse("v1:users:detail", &[("id", "123")]);

pub fn add_name_alias(&mut self, alias: &str, canonical: &str)

Register an alias for a route name in this router’s reverser.

See UrlReverser::add_name_alias for details.

pub fn reverse(&self, name: &str, params: &[(&str, &str)]) -> Option<String>

Reverse a URL by route name

Supports hierarchical namespace notation (e.g., “v1:users:detail”).

Arguments

• name - The route name, optionally with namespace (e.g., “users-detail” or “v1:users-detail”)
• params - URL parameters as key-value pairs

Examples

let router = ServerRouter::new()
    .with_namespace("v1");

// Reverse with namespace
let url = router.reverse("v1:users:detail", &[("id", "123")]).unwrap();
assert_eq!(url, "/users/123/");

// Reverse without namespace (searches all routes)
let url = router.reverse("users-detail", &[("id", "123")]).unwrap();

impl ServerRouter

pub fn function<F, Fut>( self, path: &str, method: Method, func: F, ) -> ServerRouter

where F: Fn(Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Response, Error>> + Send + 'static,

Register a function-based route (FastAPI-style)

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

async fn health_check(_req: Request) -> Result<Response> {
    Ok(Response::ok())
}

let router = ServerRouter::new()
    .function("/health", Method::GET, health_check);

pub fn handler_with_method<H>( self, path: &str, method: Method, handler: H, ) -> ServerRouter

where H: Handler + 'static,

Register a route with a Handler trait implementation and HTTP method

This method accepts a type that implements the Handler trait, allowing for stateful handlers and a more object-oriented approach. Unlike handler(), this method requires specifying an HTTP method.

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;
use reinhardt_http::{Request, Response, Result};
use reinhardt_http::Handler;
use async_trait::async_trait;

#[derive(Clone)]
struct ArticleHandler;

#[async_trait]
impl Handler for ArticleHandler {
    async fn handle(&self, _request: Request) -> Result<Response> {
        Ok(Response::ok())
    }
}

let router = ServerRouter::new()
    .handler_with_method("/articles", Method::GET, ArticleHandler);

pub fn route<F, Fut>(self, path: &str, method: Method, func: F) -> ServerRouter

where F: Fn(Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Response, Error>> + Send + 'static,

Register a route (alias for function)

This method is an alias for function and provides the same functionality. Use it when you prefer the route naming convention.

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

async fn health_check(_req: Request) -> Result<Response> {
    Ok(Response::ok())
}

let router = ServerRouter::new()
    .route("/health", Method::GET, health_check);

pub fn function_named<F, Fut>( self, path: &str, method: Method, name: &str, func: F, ) -> ServerRouter

where F: Fn(Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Response, Error>> + Send + 'static,

👎Deprecated since 0.2.0:

Use #[get("/path", name = "name")] + .endpoint() instead

Register a named function-based route (FastAPI-style with URL reversal)

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

let mut router = ServerRouter::new()
    .with_namespace("api")
    .function_named("/health", Method::GET, "health", health_check);

router.register_all_routes();
let url = router.reverse("api:health", &[]).unwrap();
assert_eq!(url, "/health");

pub fn handler_with_method_named<H>( self, path: &str, method: Method, name: &str, handler: H, ) -> ServerRouter

where H: Handler + 'static,

👎Deprecated since 0.2.0:

Use #[get("/path", name = "name")] + .endpoint() instead

Register a named route with a Handler trait implementation and HTTP method

This method accepts a type that implements the Handler trait, allowing for stateful handlers with URL reversal support.

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;
use reinhardt_http::{Request, Response, Result};
use reinhardt_http::Handler;
use async_trait::async_trait;

#[derive(Clone)]
struct ArticleHandler;

#[async_trait]
impl Handler for ArticleHandler {
    async fn handle(&self, _request: Request) -> Result<Response> {
        Ok(Response::ok())
    }
}

let mut router = ServerRouter::new()
    .with_namespace("api")
    .handler_with_method_named("/articles", Method::GET, "list_articles", ArticleHandler);

router.register_all_routes();
let url = router.reverse("api:list_articles", &[]).unwrap();
assert_eq!(url, "/articles");

pub fn route_named<F, Fut>( self, path: &str, method: Method, name: &str, func: F, ) -> ServerRouter

where F: Fn(Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<Response, Error>> + Send + 'static,

👎Deprecated since 0.2.0:

Use #[get("/path", name = "name")] + .endpoint() instead

Register a named route (alias for function_named)

This method is an alias for function_named and provides the same functionality. Use it when you prefer the route naming convention.

Examples

use reinhardt_urls::routers::ServerRouter;
use hyper::Method;

let mut router = ServerRouter::new()
    .with_namespace("api")
    .route_named("/health", Method::GET, "health", health_check);

router.register_all_routes();
let url = router.reverse("api:health", &[]).unwrap();
assert_eq!(url, "/health");

pub fn viewset<V>(self, prefix: &str, viewset: V) -> ServerRouter

where V: ViewSet + 'static,

Register a ViewSet (DRF-style)

Examples

use reinhardt_urls::routers::ServerRouter;

let router = ServerRouter::new()
    .viewset("/users", UserViewSet);

pub fn viewset_with_actions<V, M>( self, prefix: &str, viewset: V, _marker: PhantomData<M>, ) -> ServerRouter

where V: ViewSet + 'static, M: 'static,

Same as Self::viewset at runtime, but carries a PhantomData<M> marker that #[url_patterns] recovers at expansion time to discover #[action]-decorated methods on the impl block M.

M is purely a name-bearing token. Users write PhantomData::<MyViewSetImpl> as the third argument. The bound is M: 'static so the marker’s std::any::type_name is reachable for the marker→runtime bridge below.

Phase 5.1 of Issue #4507: in addition to delegating to Self::viewset, this method calls reinhardt_views::viewsets::bridge_marker_actions_to_viewset to copy every action submitted under type_name::<M>() into the runtime-keyed register_action(type_name::<V>(), ...) slot, so the dispatcher’s ViewSet::get_extra_actions lookup finds them under the concrete ViewSet’s type name (not the marker’s).

The marker-keyed submissions themselves are produced by a #[ctor::ctor] startup function emitted by #[viewset(basename = "...")] impl M { #[action(...)] fn ... } (the ctor path is the production registration mechanism today; the helper additionally drains an inventory collection for forward-compatibility once const_type_name stabilizes and inventory::submit! becomes usable for marker-keyed registrations). Because #[ctor] runs at process startup on non-wasm targets, the marker bridge is a no-op on wasm (gated by #[cfg(not(target_family = "wasm"))] at the emitter site).

Refs Issue #4507.

pub fn endpoint<F, E>(self, f: F) -> ServerRouter

where F: FnOnce() -> E, E: EndpointInfo + Handler + 'static,

Register an endpoint using EndpointInfo trait

This method accepts a factory function that returns a View type implementing both EndpointInfo and Handler traits. The path, HTTP method, and name are automatically extracted from the EndpointInfo implementation.

Examples

use reinhardt_urls::routers::ServerRouter;

// Pass the function directly (no () needed)
let router = ServerRouter::new()
    .endpoint(list_users);

pub fn view<V>(self, path: &str, view: V) -> ServerRouter

where V: Handler + 'static,

Register a class-based view (Django-style)

Examples

use reinhardt_urls::routers::ServerRouter;

let view = ArticleListView;
let router = ServerRouter::new()
    .view("/articles", view);

pub fn view_named<V>(self, path: &str, name: &str, view: V) -> ServerRouter

where V: Handler + 'static,

👎Deprecated since 0.2.0:

Use #[get("/path", name = "name")] + .endpoint() instead

Register a named class-based view (Django-style with URL reversal)

Examples

use reinhardt_urls::routers::ServerRouter;

let view = ArticleListView;
let mut router = ServerRouter::new()
    .with_namespace("articles")
    .view_named("/articles", "list", view);

router.register_all_routes();
let url = router.reverse("articles:list", &[]).unwrap();
assert_eq!(url, "/articles");

pub fn handler<H>(self, path: &str, handler: H) -> ServerRouter

where H: Handler + 'static,

Register a handler directly (recommended method)

This method allows you to pass a handler directly without wrapping it in Arc. The Arc wrapping is handled internally for you.

Examples

use reinhardt_urls::routers::ServerRouter;

// No Arc::new() needed!
let router = ServerRouter::new()
    .handler("/custom", CustomHandler);

pub fn handler_arc(self, path: &str, handler: Arc<dyn Handler>) -> ServerRouter

Register a handler that is already wrapped in Arc (low-level API)

This is provided for cases where you already have an Arc<dyn Handler>. In most cases, you should use handler() instead.

Examples

use reinhardt_urls::routers::ServerRouter;

let handler = Arc::new(CustomHandler);
let router = ServerRouter::new()
    .handler_arc("/custom", handler);

pub fn with_route_middleware<M>(self, middleware: M) -> ServerRouter

where M: Middleware + 'static,

Add middleware to the last registered function route

Examples

use reinhardt_urls::routers::ServerRouter;
use reinhardt_middleware::LoggingMiddleware;
use hyper::Method;

let router = ServerRouter::new()
    .function("/health", Method::GET, health)
    .with_route_middleware(LoggingMiddleware::new());

Trait Implementations

impl Debug for ServerRouter

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

Formats the value using the given formatter.

impl Default for ServerRouter

fn default() -> ServerRouter

Returns the “default value” for a type.

impl Handler for ServerRouter

Handler implementation for ServerRouter

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

where 'life0: 'async_trait, ServerRouter: 'async_trait,

Handles an HTTP request and produces a response.

impl RegisterViewSet for ServerRouter

Implement RegisterViewSet trait for ServerRouter

This allows ViewSetBuilder to directly register handlers to the router.

fn register_handler(&mut self, path: &str, handler: Arc<dyn Handler>)

Register a handler at the given path