Toxi Web Framework
A web framework for Rust (previously Oxidite). Build APIs, microservices, serverless functions, and full-stack apps.
Built by Meshack Bahati Ouma
What is Toxi?
Toxi is a Rust web framework for building APIs, microservices, serverless functions, and full-stack applications. It provides routing, extractors, middleware, an ORM with auto-diff migrations, authentication (JWT, OAuth2, RBAC, PBAC), server-side templates, WebSockets and SSE, background job queues, caching, file storage, email delivery, and OpenAPI documentation. The toxi-cli tool scaffolds projects, runs migrations, and provides a development server.
Each component is distributed as a separate crate. Use them independently or enable them all through the toxi facade with feature flags.
Crates
toxi-core: Routing, hyper HTTP server, and type-safe extractors (Json,Path,Query,State,Form,Cookies,Body).toxi-db: ORM with async validation rules (length,range,email,url,regex,custom,unique), relationships (has_many,has_one,belongs_to), and auto-diff schema migrations.toxi-auth: RBAC/PBAC, API keys, JWT sessions, and OAuth2 integration.toxi-realtime: WebSockets, Server-Sent Events (SSE), and Redis-backed event broadcasting.toxi-queue: Background job execution with automatic retries and dead-letter queues.toxi-cache: Caching with in-memory and Redis backends.toxi-storage: Storage API with local disk and S3/Cloudinary/ImageKit backends.toxi-template: Lightweight server-side rendering (SSR) templates.toxi-openapi: Automatic Swagger UI/OpenAPI 3.0 document generation.toxi-cli: Project scaffolding, migrations, code generators, and an interactive console.
ORM Features
The built-in ORM provides:
- Compile-time checks: Procedural macros verify handler extractor bindings and model queries at compile time.
- Eager loading: Static helper methods (
eager_load_posts,eager_load_profile) execute batched SQLINqueries to prevent N+1 queries. - Auto-diff migrations: The CLI parses your Rust struct models, diffs them against the live database schema, and generates migrations automatically.
Benchmarks
Public benchmarks are not yet available. See STATUS.md for current feature completeness.
Installation
Install the Toxi CLI tool to get started:
# Install from source (recommended for development)
# Or install from crates.io (when published)
Getting Started
Quick Start
Create a new Toxi project in seconds:
Then run your application:
# Navigate to your project
# Start the development server
Your application will be available at http://127.0.0.1:8080.
Hello World Example
Here's a simple "Hello World" example:
use *;
async
async
Alternative: The manual approach using
Router::new()→router.get(...)→Server::new(router).listen(addr)works identically.
Using Extractors
Extractors deserialize request data from common formats:
use *;
use Deserialize;
// Handle JSON requests
async
// Handle form data
async
// Handle query parameters
async
// Handle path parameters
async
// Access cookies
async
// Access raw body
async
Core Concepts
Routers and Handlers
Toxi uses a clean routing system with async handlers:
use *;
async
async
async
Alternative: The manual approach using
Router::new()→router.get(...)→Server::new(router).listen(addr)works identically.
Request Handling
Toxi provides several extractors to handle different types of requests:
- Json: Extracts and deserializes JSON from request body
- Form: Extracts and deserializes form data
- Query: Extracts and deserializes query parameters
- Path: Extracts and deserializes path parameters
- Cookies: Extracts cookies as HashMap
- Body: Extracts raw request body as String
- State: Extracts application state from request extensions
API Versioning
Toxi supports multiple API versioning strategies:
use *;
// URL-based versioning
async
async
// Version-specific routes
router.get;
router.get;
Error Handling
Toxi provides comprehensive error handling with appropriate HTTP status codes:
use *;
async
async
async
Documentation
Complete documentation is available in the docs/ directory:
- Getting Started - Your first Toxi application
- Core Concepts - Fundamental architecture and concepts
- API Documentation - Complete API reference
- Framework Features - Framework features and capabilities
- Added Features - Recently added features and improvements
- Database Guide - ORM and database operations
- Authentication Guide - Authentication and authorization
- Templating Guide - Server-side rendering
- Middleware Guide - Adding functionality with middleware
- CLI Tools - Command-line interface
Architecture
Toxi is composed of modular crates that can be used independently:
| Crate | Description |
|---|---|
toxi |
Main crate with prelude and convenience exports |
toxi-core |
Core HTTP server, routing, and extractors |
toxi-db |
Database ORM with migrations and relationships |
toxi-auth |
Authentication and authorization |
toxi-template |
Template engine for server-side rendering |
toxi-middleware |
Common middleware implementations |
toxi-cli |
Command-line tools for project management |
toxi-config |
Configuration management |
toxi-cache |
Caching utilities |
toxi-queue |
Background job processing |
toxi-realtime |
Real-time features (WebSockets, SSE) |
toxi-mail |
Email sending capabilities |
toxi-storage |
File storage (local and S3) |
toxi-openapi |
OpenAPI/Swagger integration |
toxi-macros |
Procedural macros |
toxi-security |
Security utilities |
toxi-testing |
Testing utilities |
toxi-utils |
Common utilities |
Testing
Toxi provides comprehensive testing utilities:
use *;
use TestClient;
Deployment
Deploy your Toxi application with any Rust-compatible hosting provider:
# Build for release
# Run the application
For containerized deployment:
FROM rust:latest
WORKDIR /app
COPY . .
RUN cargo build --release
CMD ["./target/release/my-app"]
Contributing
Contributions are welcome! Please read our Contributing Guide.
License
MIT OR Apache-2.0 - see LICENSE for details.