Struct Router 

pub struct Router { /* private fields */ }

Router manages handler registration and protocol adapters

The router allows you to register handlers once and expose them via multiple protocols based on configuration.

Implementations

impl Router

pub fn docs_config(&self, path: &str, title: &str, version: &str) -> DocsConfig

Get documentation configuration helper

Returns a DocsConfig that can be used to serve documentation.

pub fn openapi_json(&self, title: &str, version: &str) -> String

Generate OpenAPI JSON for serving at /docs/openapi.json

This is a convenience method that generates the OpenAPI spec in JSON format ready to be served via HTTP.

pub fn openapi_json_with_description( &self, title: &str, version: &str, description: &str, ) -> String

Generate OpenAPI JSON with description

pub fn docs_html(&self, config: &DocsConfig) -> String

Generate a basic HTML page for documentation

Returns a simple HTML page that can serve as a landing page for API documentation. In production, you’d want to use a proper documentation UI like Scalar or Swagger UI.

impl Router

pub fn to_openapi(&self, title: &str, version: &str) -> Value

Generate OpenAPI 3.1 specification

This is a convenience method that creates an OpenAPI specification for all REST routes registered with this router.

pub fn to_openapi_with_description( &self, title: &str, version: &str, description: &str, ) -> Value

Generate OpenAPI 3.1 specification with description

impl Router

pub fn new() -> Self

Create a new router

pub fn with_config(config: RouterConfig) -> Self

Available on crate feature router only.

Create a new router with configuration

pub fn with_key_transform(self, transform: KeyTransform) -> Self

Set a key transformation applied to JSON args before deserialization.

When enabled, all handler args are transformed before being passed to serde_json::from_str. This is a single opt-in call that fixes key naming mismatches for all handlers.

Example

use allframe_core::router::{Router, KeyTransform};

let router = Router::new()
    .with_key_transform(KeyTransform::CamelToSnake);
// Now `{"workflowId": "abc"}` is transformed to `{"workflow_id": "abc"}`
// before any handler deserializes it.

pub fn with_state<S: Send + Sync + 'static>(self, state: S) -> Self

Add shared state for dependency injection (builder pattern).

Can be called multiple times with different types. Each state type is stored independently and looked up by TypeId at registration time. Calling twice with the same S replaces the previous value.

let router = Router::new()
    .with_state(db_pool)       // handlers can request State<Arc<DbPool>>
    .with_state(app_handle);   // handlers can request State<Arc<AppHandle>>

pub fn inject_state<S: Send + Sync + 'static>(&mut self, state: S)

Add shared state for dependency injection (mutable, non-builder).

Like with_state but takes &mut self instead of consuming self. Useful when the state is not available at router construction time (e.g., Tauri’s AppHandle which is only available during plugin setup). Calling twice with the same S replaces the previous value.

pub fn shared_states(&self) -> SharedStateMap

Returns a handle to the shared state map.

This is the same Arc used internally, so state injected through the returned handle is visible to handlers at call time. Used by BootContext to inject state during async boot.

pub fn register<F, Fut>(&mut self, name: &str, handler: F)

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a handler with a name (zero-arg, backward compatible)

pub fn register_with_args<T, F, Fut>(&mut self, name: &str, handler: F)

where T: DeserializeOwned + Send + 'static, F: Fn(T) -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a handler that receives typed, deserialized args

pub fn register_with_state<S, T, F, Fut>(&mut self, name: &str, handler: F)

where S: Send + Sync + 'static, T: DeserializeOwned + Send + 'static, F: Fn(State<Arc<S>>, T) -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a handler that receives injected state and typed args

Panics

Panics at registration time if with_state::<S>() was not called.

pub fn register_with_state_only<S, F, Fut>(&mut self, name: &str, handler: F)

where S: Send + Sync + 'static, F: Fn(State<Arc<S>>) -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a handler that receives only injected state (no args)

Panics

Panics at registration time if with_state::<S>() was not called.

pub fn register_typed<R, F, Fut>(&mut self, name: &str, handler: F)

where R: Serialize + Send + 'static, F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static,

Register a handler that returns R: Serialize (auto-serialized to JSON)

pub fn register_typed_with_args<T, R, F, Fut>(&mut self, name: &str, handler: F)

where T: DeserializeOwned + Send + 'static, R: Serialize + Send + 'static, F: Fn(T) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static,

Register a handler that accepts typed args and returns R: Serialize

pub fn register_typed_with_state<S, T, R, F, Fut>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, T: DeserializeOwned + Send + 'static, R: Serialize + Send + 'static, F: Fn(State<Arc<S>>, T) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static,

Register a handler that receives state + typed args and returns R: Serialize

pub fn register_typed_with_state_only<S, R, F, Fut>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, R: Serialize + Send + 'static, F: Fn(State<Arc<S>>) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static,

Register a handler that receives state only and returns R: Serialize

pub fn register_result<R, E, F, Fut>(&mut self, name: &str, handler: F)

where R: Serialize + Send + 'static, E: Display + Send + 'static, F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<R, E>> + Send + 'static,

Register a handler returning Result<R, E> (no args)

On Ok(value), value is serialized to JSON. On Err(e), the error is returned as a string.

pub fn register_result_with_args<T, R, E, F, Fut>( &mut self, name: &str, handler: F, )

where T: DeserializeOwned + Send + 'static, R: Serialize + Send + 'static, E: Display + Send + 'static, F: Fn(T) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<R, E>> + Send + 'static,

Register a handler returning Result<R, E> with typed args

pub fn register_result_with_state<S, T, R, E, F, Fut>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, T: DeserializeOwned + Send + 'static, R: Serialize + Send + 'static, E: Display + Send + 'static, F: Fn(State<Arc<S>>, T) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<R, E>> + Send + 'static,

Register a handler returning Result<R, E> with state + typed args

pub fn register_result_with_state_only<S, R, E, F, Fut>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, R: Serialize + Send + 'static, E: Display + Send + 'static, F: Fn(State<Arc<S>>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<R, E>> + Send + 'static,

Register a handler returning Result<R, E> with state only

pub fn handlers_count(&self) -> usize

Get the number of registered handlers (request/response only)

pub fn register_streaming<F, Fut, R>(&mut self, name: &str, handler: F)

where F: Fn(StreamSender) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static, R: IntoHandlerResult + 'static,

Register a streaming handler (no args, receives StreamSender)

pub fn register_streaming_with_args<T, F, Fut, R>( &mut self, name: &str, handler: F, )

where T: DeserializeOwned + Send + 'static, F: Fn(T, StreamSender) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static, R: IntoHandlerResult + 'static,

Register a streaming handler with typed args

pub fn register_streaming_with_state<S, T, F, Fut, R>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, T: DeserializeOwned + Send + 'static, F: Fn(State<Arc<S>>, T, StreamSender) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static, R: IntoHandlerResult + 'static,

Register a streaming handler with state and typed args

pub fn register_streaming_with_state_only<S, F, Fut, R>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, F: Fn(State<Arc<S>>, StreamSender) -> Fut + Send + Sync + 'static, Fut: Future<Output = R> + Send + 'static, R: IntoHandlerResult + 'static,

Register a streaming handler with state only (no args)

pub fn register_stream<T, St, F, Fut>(&mut self, name: &str, handler: F)

where T: IntoStreamItem + 'static, St: Stream<Item = T> + Send + 'static, F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = St> + Send + 'static,

Register a handler that returns a Stream of items (no args).

The stream is internally bridged to a StreamSender channel. Items are forwarded through a bounded channel (default capacity 64). Register a handler that returns a Stream of items (no args).

The stream is internally bridged to a StreamSender channel. Items are forwarded through a bounded channel (default capacity 64).

pub fn register_stream_with_args<T, Item, St, F, Fut>( &mut self, name: &str, handler: F, )

where T: DeserializeOwned + Send + 'static, Item: IntoStreamItem + 'static, St: Stream<Item = Item> + Send + 'static, F: Fn(T) -> Fut + Send + Sync + 'static, Fut: Future<Output = St> + Send + 'static,

Register a handler that takes typed args and returns a Stream of items.

pub fn register_stream_with_state<S, T, Item, St, F, Fut>( &mut self, name: &str, handler: F, )

where S: Send + Sync + 'static, T: DeserializeOwned + Send + 'static, Item: IntoStreamItem + 'static, St: Stream<Item = Item> + Send + 'static, F: Fn(State<Arc<S>>, T) -> Fut + Send + Sync + 'static, Fut: Future<Output = St> + Send + 'static,

Register a handler that takes state + typed args and returns a Stream of items.

pub fn is_streaming(&self, name: &str) -> bool

Check if a handler is a streaming handler

pub fn call_streaming_handler( &self, name: &str, args: &str, ) -> Result<(StreamReceiver, Pin<Box<dyn Future<Output = Result<String, String>> + Send + '_>>), String>

Call a streaming handler by name.

Creates a bounded channel, passes the sender to the handler, and returns (receiver, completion_future). The completion future resolves with the handler’s final result.

Note: the returned future borrows self. For use in contexts where a 'static future is needed (e.g., tokio::spawn), use spawn_streaming_handler instead.

pub fn spawn_streaming_handler( self: &Arc<Self>, name: &str, args: &str, ) -> Result<(StreamReceiver, JoinHandle<Result<String, String>>), String>

Spawn a streaming handler as a tokio task.

Like call_streaming_handler but returns a 'static receiver and JoinHandle, suitable for use with tokio::spawn.

pub fn describe_handler( &mut self, name: &str, args: Vec<TsField>, returns: TsType, )

Attach type metadata to a handler for TypeScript client generation

The metadata describes the handler’s argument fields and return type, which generate_ts_client() uses to generate typed async functions.

Example

use allframe_core::router::{Router, TsField, TsType};

let mut router = Router::new();
router.register("get_user", || async { r#"{"id":1}"#.to_string() });
router.describe_handler("get_user", vec![], TsType::Object(vec![
    TsField::new("id", TsType::Number),
    TsField::new("name", TsType::String),
]));

pub fn describe_streaming_handler( &mut self, name: &str, args: Vec<TsField>, item_type: TsType, final_type: TsType, )

Attach type metadata to a streaming handler for TypeScript client generation

pub fn generate_ts_client(&self) -> String

Generate a complete TypeScript client module from all described handlers

Returns a string containing TypeScript code with typed async functions for each handler that has metadata attached via describe_handler().

Example

use allframe_core::router::{Router, TsField, TsType};

let mut router = Router::new();
router.register("get_user", || async { r#"{"id":1}"#.to_string() });
router.describe_handler("get_user", vec![
    TsField::new("id", TsType::Number),
], TsType::Object(vec![
    TsField::new("id", TsType::Number),
    TsField::new("name", TsType::String),
]));

let ts_code = router.generate_ts_client();
assert!(ts_code.contains("export async function getUser"));

pub fn handler_meta(&self, name: &str) -> Option<&HandlerMeta>

Get handler metadata (for inspection/testing)

pub fn add_adapter(&mut self, adapter: Box<dyn ProtocolAdapter>)

Add a protocol adapter

pub fn has_adapter(&self, name: &str) -> bool

Check if an adapter is registered

pub fn get_adapter(&self, name: &str) -> Option<&dyn ProtocolAdapter>

Get an adapter by name

pub async fn route_request( &self, protocol: &str, request: &str, ) -> Result<String, String>

Route a request through the appropriate protocol adapter

pub async fn execute(&self, name: &str) -> Result<String, String>

Execute a handler by name (zero-arg shorthand)

pub async fn execute_with_args( &self, name: &str, args: &str, ) -> Result<String, String>

Execute a handler by name with JSON args

pub fn list_handlers(&self) -> Vec<String>

List all registered handler names (both request/response and streaming)

Returns a vector of all handler names that have been registered with this router. Used by MCP server for tool discovery.

pub async fn call_handler( &self, name: &str, request: &str, ) -> Result<String, String>

Call a handler by name with request data (JSON args)

Forwards the request string as args to the handler. Used by MCP server and Tauri plugin.

pub fn can_handle_rest(&self, _name: &str) -> bool

Check if handler can be called via REST

pub fn can_handle_graphql(&self, _name: &str) -> bool

Check if handler can be called via GraphQL

pub fn can_handle_grpc(&self, _name: &str) -> bool

Check if handler can be called via gRPC

pub fn enabled_protocols(&self) -> Vec<String>

Get list of enabled protocols

pub fn add_route(&mut self, metadata: RouteMetadata)

Add a route with metadata

This stores route metadata that can be used to generate documentation (OpenAPI, GraphQL schemas, gRPC reflection).

pub fn routes(&self) -> &[RouteMetadata]

Get all registered routes

Returns an immutable reference to all route metadata. This is used for documentation generation.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a GET route

This is a convenience method that registers both a handler and route metadata for a GET request. The handler name is automatically generated as “GET:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a POST route

This is a convenience method that registers both a handler and route metadata for a POST request. The handler name is automatically generated as “POST:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a PUT route

This is a convenience method that registers both a handler and route metadata for a PUT request. The handler name is automatically generated as “PUT:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a DELETE route

This is a convenience method that registers both a handler and route metadata for a DELETE request. The handler name is automatically generated as “DELETE:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a PATCH route

This is a convenience method that registers both a handler and route metadata for a PATCH request. The handler name is automatically generated as “PATCH:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register a HEAD route

This is a convenience method that registers both a handler and route metadata for a HEAD request. The handler name is automatically generated as “HEAD:{path}”.

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

where F: Fn() -> Fut + Send + Sync + 'static, Fut: Future<Output = String> + Send + 'static,

Register an OPTIONS route

This is a convenience method that registers both a handler and route metadata for an OPTIONS request. The handler name is automatically generated as “OPTIONS:{path}”.

pub async fn call_rest( &self, method: &str, path: &str, ) -> Result<String, String>

Call handler via REST

pub async fn call_graphql(&self, query: &str) -> Result<String, String>

Call handler via GraphQL

pub async fn call_grpc( &self, method: &str, request: &str, ) -> Result<String, String>

Call handler via gRPC

pub fn scalar(&self, title: &str, version: &str) -> String

Generate Scalar documentation HTML with default configuration

This is a convenience method that generates a complete HTML page with Scalar UI for interactive API documentation.

Arguments

• title - API title
• version - API version

Example

use allframe_core::router::Router;

let mut router = Router::new();
router.get("/users", || async { "Users".to_string() });

let html = router.scalar("My API", "1.0.0");
// Serve this HTML at /docs endpoint

pub fn scalar_docs( &self, config: ScalarConfig, title: &str, version: &str, ) -> String

Generate Scalar documentation HTML with custom configuration

This method allows full customization of the Scalar UI appearance and behavior.

Arguments

• config - Scalar configuration
• title - API title
• version - API version

Example

use allframe_core::router::{Router, ScalarConfig, ScalarTheme};

let mut router = Router::new();
router.get("/users", || async { "Users".to_string() });

let config = ScalarConfig::new()
    .theme(ScalarTheme::Light)
    .show_sidebar(false);

let html = router.scalar_docs(config, "My API", "1.0.0");

Trait Implementations

impl ContractTestable for Router

fn generate_contract_tests(&self) -> ContractTestResults

Generate contract tests for all routes

fn test_route_contract(&self, path: &str, method: &str) -> ContractTestResult

Test a specific route path and method

impl Default for Router

fn default() -> Self

Returns the “default value” for a type.