HTTP Adapters Overview

Toni doesn't handle HTTP itself. That concern belongs to the adapter — a thin integration layer that bridges Toni's routing and DI system to an actual HTTP server.

This separation means your application logic is completely decoupled from the HTTP runtime. Switching adapters is a one-line change.

Why pluggable adapters?

Different workloads have different runtime characteristics:

• I/O-bound workloads (database queries, API calls, file reads) benefit from cooperative multitasking — many concurrent lightweight tasks. Axum + Tokio is built for this.
• CPU-bound workloads (image processing, data transformation, cryptography) benefit from true parallelism across OS threads. Actix-web's actor model is purpose-built for this.

Toni doesn't pick for you. Your choice of adapter is a deployment concern, not an architectural one.

Choosing an adapter

For most applications — REST APIs, BFF layers, backend services — toni-axum is the natural choice. It pairs well with the Tokio ecosystem (sqlx, reqwest, tonic, etc.).

Reach for toni-actix if you have CPU-intensive per-request work or if you're integrating into an existing Actix-web deployment.

The HttpAdapter trait

You can implement your own adapter for any HTTP server:

pub trait HttpAdapter: Send + Sync {
    fn register_route(&mut self, route: RouteDefinition);
    fn register_websocket(&mut self, path: &str, gateway: Arc<GatewayWrapper>);
    async fn listen(self, port: u16, hostname: &str);
}

Toni calls register_route for each resolved route during startup, then calls listen when app.listen(port, host) is invoked. The adapter translates Toni's routing abstractions into the underlying server's format.

Sections in this chapter

• Axum Adapter — setup and Axum-specific configuration
• Actix-web Adapter — setup and Actix-specific configuration
• Custom Adapters — bring your own HTTP server