Expand description
§Toxi Web Framework
Toxi is a modular, batteries-included web framework for Rust.
Built on hyper and tokio, it provides a complete stack for building
production HTTP services — routing, ORM, authentication, real-time
communication, background jobs, caching, storage, templates, email,
and OpenAPI generation.
§Quick Start
[dependencies]
toxi = { version = "3.1.0", features = ["full"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }use toxi::prelude::*;
async fn hello(_req: Request) -> Result<Response> {
Ok(Response::text("Hello, Toxi!"))
}
#[tokio::main]
async fn main() -> Result<()> {
let mut app = Application::new(Config::load().unwrap());
app.router_mut().get("/", hello);
app.run().await
}§Feature Flags
Enable only what you need via Cargo features:
| Feature | Crate | Description |
|---|---|---|
database | toxi-db | ORM with relationships & migrations |
auth | toxi-auth | JWT, OAuth2, RBAC, 2FA, API keys |
queue | toxi-queue | Background job orchestration |
cache | toxi-cache | In-memory and Redis caching |
realtime | toxi-realtime | WebSocket and SSE |
templates | toxi-template | Server-side rendering |
mail | toxi-mail | SMTP email delivery |
storage | toxi-storage | Local and S3 file storage |
security | toxi-security | Crypto primitives |
utils | toxi-utils | String, date, validation helpers |
graphql | toxi-graphql | GraphQL integration |
plugin | toxi-plugin | Plugin lifecycle hooks |
full | all of the above | Every optional crate |
§Modular by Design
Each crate in the Toxi ecosystem can be used independently:
# Minimal: just routing and HTTP
[dependencies]
toxi-core = "3.1.0"
# Add database when needed
[dependencies]
toxi-core = "3.1.0"
toxi-db = "3.1.0"§Key Concepts
- Extractors — Typed data pulled from requests (
Json<T>,Path<T>,State<T>, etc.) - Handlers — Async functions whose parameters are extractors
- Middleware — Tower-compatible layers (CORS, logging, compression, rate limiting)
- HTTP/2 — First-class support via ALPN or
Server::with_http_version
§Learn More
Re-exports§
pub use config_helper::cors_layer_from_config;pub use toxi_middleware as middleware;pub use toxi_config as config;pub use toxi_db as db;pub use toxi_auth as auth;pub use toxi_queue as queue;pub use toxi_cache as cache;pub use toxi_realtime as realtime;pub use toxi_template as template;pub use toxi_mail as mail;pub use toxi_storage as storage;pub use toxi_security as security;pub use toxi_utils as utils;
Modules§
- app
- Re-export all items from
toxi_core. Application boot coordinator and configuration. - config_
helper - Configuration helper utilities.
- cookie
- Re-export all items from
toxi_core. Backwards-compatible re-exports for cookies and form data. Backwards-compatible cookie/form module. - error
- Re-export all items from
toxi_core. Error types and theResultalias. - extract
- Re-export the
extractmodule fromtoxi_core. Request extractors for pulling typed data from incoming requests. - mpsc
- Re-export all items from
toxi_core. Re-export oftokio::sync::mpscfor channel-based communication. A multi-producer, single-consumer queue for sending values between asynchronous tasks. - prelude
- Convenience re-exports for ergonomic imports.
- request
- Re-export all items from
toxi_core. Extension trait forRequestwith body-reading helpers. - response
- Re-export all items from
toxi_core. Response constructors and helpers. - router
- Re-export all items from
toxi_core. HTTP router with path parameters, middleware, and CORS support. - server
- Re-export all items from
toxi_core. HTTP/1.1 and HTTP/2 server loop and body adapter. - tls
- Re-export all items from
toxi_core. TLS/HTTPS support andSecureServer. - types
- Re-export all items from
toxi_core. Type aliases for requests, responses, and boxed bodies. - versioning
- Re-export all items from
toxi_core. API versioning withApiVersionandVersionedRouter. API Versioning support
Macros§
- impl_
handler_ for_ fn - Re-export
impl_handler_for_fn!— extend handler arity beyond the built-in 12 extractors: - json_
response - Re-export
json_response!— create a JSON response from inline JSON:
Structs§
- Application
- Re-export all items from
toxi_core. The application boot coordinator. Application boot coordinator. - Body
- Re-export all items from
toxi_core. Common request extractors. Extract raw request body as string - Cookies
- Re-export all items from
toxi_core. Common request extractors. Extract cookies from the request - Cors
Config - Re-export all items from
toxi_core. Router and handler types. CORS configuration for the Router - Form
- Re-export all items from
toxi_core. Common request extractors. Extract form data from the request body - Header
Map - Re-export all items from
toxi_core. Re-exports from thehttpcrate. A specialized multimap for header names and values. - Header
Value - Re-export all items from
toxi_core. Re-exports from thehttpcrate. Represents an HTTP header field value. - Json
- Re-export all items from
toxi_core. Common request extractors. Extract and deserialize JSON request body - Method
- Re-export all items from
toxi_core. Re-exports from thehttpcrate. The Request Method (VERB) - Path
- Re-export all items from
toxi_core. Common request extractors. Extract typed path parameters from the request - Path
Params - Re-export all items from
toxi_core. Common request extractors. Storage for path parameters extracted during routing. - Query
- Re-export all items from
toxi_core. Common request extractors. Extract typed query parameters from the request - Response
- Re-export all items from
toxi_core. Convenience alias:ToxiResponseasResponse. The Toxi HTTP response type. - Router
- Re-export all items from
toxi_core. Router and handler types. The central request router. - Server
- Re-export all items from
toxi_core. The HTTP server. HTTP server that listens for incoming connections and dispatches requests to a tower service. - State
- Re-export all items from
toxi_core. Common request extractors. Extract application state from request extensions - Status
Code - Re-export all items from
toxi_core. Re-exports from thehttpcrate. An HTTP status code (status-codein RFC 9110 et al.). - Toxi
Response - Re-export
ToxiRequestandToxiResponse. The Toxi HTTP response type. - Versioned
Router - Re-export all items from
toxi_core. API versioning types. Versioned router - WebSocket
Upgrade - Re-export all items from
toxi_core. Common request extractors. Extractor for WebSocket upgrade requests
Enums§
- ApiVersion
- Re-export all items from
toxi_core. API versioning types. API version - Error
- Re-export all items from
toxi_core. Core error and result types. Error type for Toxi applications. - Http
Version - Re-export all items from
toxi_core. The HTTP server. HTTP protocol version for the server.
Traits§
- BodyExt
- Re-export all items from
toxi_core. Re-export ofhttp_body_util::BodyExtfor body-reading utilities. An extension trait forhttp_body::Bodyadding various combinators and adapters - From
Request - Re-export all items from
toxi_core. Common request extractors. Extractor trait - allows types to be extracted from requests. - Handler
- Re-export all items from
toxi_core. Router and handler types. Trait for async functions that can be used as handlers - Into
Handler - Re-export all items from
toxi_core. Router and handler types. Trait that provides compile-time verification that a function is a valid handler.
Functions§
- handler_
fn - Re-export all items from
toxi_core. Router and handler types. Compile-time handler verification helper. - html
- Re-export all items from
toxi_core. Re-export response helpers for convenient access. - json
- Re-export all items from
toxi_core. Re-export response helpers for convenient access. - text
- Re-export all items from
toxi_core. Re-export response helpers for convenient access.
Type Aliases§
- Request
- Re-export all items from
toxi_core. Convenience alias:ToxiRequestasRequest. The Toxi HTTP request type. - Result
- Re-export all items from
toxi_core. Core error and result types. A specialized Result type for Toxi applications - Toxi
Request - Re-export
ToxiRequestandToxiResponse. The Toxi HTTP request type.