Ferro Framework

Ferro is a Rust web framework optimized for AI-assisted authoring. It is built for developers whose primary authoring tool is a coding agent (Claude Code, Cursor, and similar), and exposes every subsystem through an in-process MCP (Model Context Protocol) server. An agent connected to your project reads routes, models, handlers, validations, and generation context as tool calls — not by parsing source.

The defining feature is service projections: declare a service and intent, get a working UI. The ferro-projections crate (shipped in v9.0) maps typed model pipelines to rendered views, so an agent can scaffold an end-to-end CRUD or workflow surface from a single declaration. At v1.0 the output is visual (HTML via JSON-UI, shipped in v10.0); the underlying model is designed to support additional rendering modalities over time.

There is no bundled agent UI. ferro-mcp is the introspection layer your agent talks to.

What's included

• Service projections — typed model→UI pipelines via ferro-projections
• JSON-UI — server-rendered, server-driven UIs with 30+ components and a plugin system
• MCP introspection — a full suite of tools via ferro-mcp for agent-assisted development
• Routing and middleware — macro-based routes, typed extractors, middleware pipeline
• Database — SeaORM-based models, migrations, and query builder
• Validation — declarative rule sets with structured errors
• Authentication — session-based auth with guards and policies
• Inertia.js — full-stack React/TypeScript with compile-time component validation
• Events, queues, notifications, broadcasting — async workflows out of the box
• Storage and caching — pluggable backends (local/S3, in-memory/Redis)
• Localization, theming, Stripe, AI, WhatsApp — first-party crates for common needs
• Deploy and CI scaffolding — ferro do:init, ferro ci:init, ferro doctor

Quick Example

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response, Router, AuthMiddleware, Inertia};

#[handler]
pub async fn index(req: Request) -> Response {
    let users = User::find().all(&db).await?;

    Inertia::render(&req, "Users/Index", UsersProps { users })
}

pub fn routes() -> Router {
    Router::new()
        .get("/users", index)
        .middleware(AuthMiddleware)
}
}

Agents can generate this automatically. Connect ferro-mcp to your AI agent and use code_templates to scaffold handlers, list_routes to explore your API, and get_handler to read implementation details of any existing handler.

Philosophy

Agent-first authoring — Ferro is designed for the case where a human directs an AI agent and the agent writes the code. Every subsystem exposes typed introspection so the agent can reason about the application without guessing.

Projection over hand-assembly — UIs are derived from typed services and intents, not hand-wired component trees. The framework prefers declarations the agent can generate and refine.

Convention over configuration — Predictable file layout and naming so introspection produces useful answers and generated code lands in the right place.

Type safety — Routes, Inertia component paths, JSON-UI views, and database queries are validated at compile time. Mistakes surface as build errors the agent can read and fix.

Async-first — Built on Tokio.

Status

Ferro is pre-1.0. Breaking changes are allowed between minor versions until 1.0.

Getting Started

To start building, see the Installation guide. To wire an AI agent to your project via ferro-mcp, see Working with Agents.

Installation

Requirements

The Ferro CLI installs toolchain-free via Homebrew (below). The following are only needed to build and run a scaffolded app:

• Rust 1.88+ (with Cargo) — to build the app (no OpenSSL needed; the scaffold uses rustls)
• Node.js 18+ (for the frontend dev server)
• PostgreSQL, SQLite, or MySQL — SQLite is the default, no setup required

Installing the CLI

Homebrew (macOS and Linux — recommended)

No Rust toolchain required:

brew install albertogferrario/ferro/ferro

curl installer (macOS and Linux)

curl -fsSL https://raw.githubusercontent.com/albertogferrario/ferro/main/scripts/install.sh | sh

Cargo (requires Rust)

cargo install ferro-cli

Or build from source:

git clone https://github.com/albertogferrario/ferro.git
cd ferro
cargo install --path ferro-cli

Creating a New Project

ferro new my-app

This will:

1. Create a new directory my-app
2. Initialize a Rust workspace
3. Set up the frontend with React and TypeScript
4. Configure the database
5. Initialize git repository

Options

# Skip interactive prompts
ferro new my-app --no-interaction

# Skip git initialization
ferro new my-app --no-git

Starting Development

cd my-app
ferro serve

This starts both the backend (port 8080) and frontend (port 5173) servers.

Server Options

# Custom ports
ferro serve --port 3000 --frontend-port 3001

# Backend only
ferro serve --backend-only

# Frontend only
ferro serve --frontend-only

# Skip TypeScript generation
ferro serve --skip-types

AI Development Setup

For AI-assisted development with Claude, Cursor, or VS Code:

ferro boost:install

This configures the MCP server and adds project guidelines for your editor.

Next Steps

• Quick Start - Build your first feature
• Directory Structure - Understand the project layout

Quick Start

Build a simple user listing feature in 5 minutes.

1. Create Migration

ferro make:migration create_users_table

Edit src/migrations/m_YYYYMMDD_create_users_table.rs:

#![allow(unused)]
fn main() {
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Users::Table)
                    .col(ColumnDef::new(Users::Id).big_integer().primary_key().auto_increment())
                    .col(ColumnDef::new(Users::Name).string().not_null())
                    .col(ColumnDef::new(Users::Email).string().not_null().unique_key())
                    .col(ColumnDef::new(Users::CreatedAt).timestamp().not_null())
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager.drop_table(Table::drop().table(Users::Table).to_owned()).await
    }
}

#[derive(Iden)]
enum Users {
    Table,
    Id,
    Name,
    Email,
    CreatedAt,
}
}

Run the migration:

ferro db:migrate

2. Sync Database to Models

ferro db:sync

This generates src/models/users.rs with SeaORM entity definitions.

3. Create Controller

ferro make:controller users

Edit src/controllers/users_controller.rs:

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response, Inertia, InertiaProps};
use crate::models::users::Entity as User;

#[handler]
pub async fn index(req: Request) -> Response {
    let db = req.db();
    let users = User::find().all(db).await?;

    Inertia::render(&req, "Users/Index", UsersIndexProps { users })
}

#[derive(InertiaProps)]
pub struct UsersIndexProps {
    pub users: Vec<crate::models::users::Model>,
}
}

4. Create Inertia Page

ferro make:inertia Users/Index

Edit frontend/src/pages/Users/Index.tsx:

import { InertiaProps } from '@/types/inertia-props';

interface User {
  id: number;
  name: string;
  email: string;
}

interface Props {
  users: User[];
}

export default function UsersIndex({ users }: Props) {
  return (
    <div className="container mx-auto p-4">
      <h1 className="text-2xl font-bold mb-4">Users</h1>
      <ul className="space-y-2">
        {users.map((user) => (
          <li key={user.id} className="p-2 border rounded">
            <strong>{user.name}</strong> - {user.email}
          </li>
        ))}
      </ul>
    </div>
  );
}

5. Add Route

Edit src/routes.rs:

#![allow(unused)]
fn main() {
use ferro::Router;
use crate::controllers::users_controller;

pub fn routes() -> Router {
    Router::new()
        .get("/users", users_controller::index)
}
}

6. Generate TypeScript Types

ferro generate-types

This creates frontend/src/types/inertia-props.ts from your Rust props.

7. Run the Server

ferro serve

Visit http://localhost:5173/users to see your user listing.

What's Next?

• Add validation to user creation
• Implement authentication
• Add middleware for protected routes

Working with Agents

Ferro is built agent-first: agents get the same structural understanding of your application that developers do, via MCP (Model Context Protocol). Routes, models, handlers, validations, services, and code generation hints are all accessible as tool calls — no file-reading required.

Setting Up ferro-mcp

Ferro's CLI binary doubles as an MCP server. The same ferro binary you use for migrations and scaffolding exposes a full suite of introspection tools when invoked with the mcp subcommand. There is no separate binary to install — build your project and the MCP server is ready.

cargo build
# ferro binary is now at target/debug/ferro (development) or target/release/ferro (production)

MCP Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ferro": {
      "command": "/path/to/your/app/target/debug/ferro",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Restart Claude Desktop after saving. Use target/release/ferro for production builds.

Claude Code (.claude.json)

Place at project root as .claude.json (project-scope, applies to this repo only) or ~/.claude.json (user-scope, applies to all projects):

{
  "mcpServers": {
    "ferro": {
      "command": "/path/to/your/app/target/debug/ferro",
      "args": ["mcp"],
      "type": "stdio"
    }
  }
}

Generic stdio (any MCP-compatible host)

Any MCP host that supports stdio transport (Cursor, Windsurf, etc.) uses this pattern:

{
  "mcpServers": {
    "ferro": {
      "command": "/path/to/ferro",
      "args": ["mcp"]
    }
  }
}

The type: "stdio" field is optional — stdio is the default transport for most hosts.

The Discovery Loop

The core agent workflow follows three steps:

1. Orient — Call application_info to understand the project: installed crates, configured features, database details, and overall application structure.

2. Explore — Use feature-specific tools to drill into the area of interest. Exploring routes: list_routes then explain_route. Understanding data: list_models then explain_model then model_usages. Diagnosing a problem: last_error or diagnose_error.

3. Generate — Call code_templates or generation_context to get scaffolding hints, then execute the appropriate CLI command to produce the actual code.

This loop repeats at each level of depth. An agent scaffolding a feature might call application_info once, list_routes to check for conflicts, explain_model to understand related data, and code_templates to identify the right CLI command — all before writing a single line of code.

Common Workflows

Exploring a new codebase

An agent joining an unfamiliar Ferro project starts with application_info to get the full picture: what crates are installed, what features are active, what database is configured. It follows with list_routes to map the API surface and list_models to understand the data layer. Within minutes the agent has the structural knowledge that a developer would need days to accumulate by reading source files.

Diagnosing a build or runtime error

When a build fails or a request errors, the agent calls last_error to retrieve the most recent error Ferro captured, then diagnose_error with the error text to get a structured root-cause analysis with suggested fixes. The agent does not need to read log files or trace through stack frames manually.

Understanding models and their relationships

For features that involve data, the agent calls list_models to get all model names, explain_model on the relevant models to understand their fields and constraints, and model_usages to see where a model is referenced across the codebase. relation_map gives a full graph of model relationships. This is enough context to generate correct queries, validations, and forms without reading individual source files.

Generating code from templates

When an agent needs to scaffold a handler, model, or migration, it calls code_templates to get the list of available templates and their generation hints. Each template specifies the CLI command that produces it. The agent selects the appropriate template, reads the hint, and calls the CLI command. The scaffolded code follows Ferro conventions and integrates with the project's existing structure.

Agent-to-CLI Workflow

The bridge between MCP introspection and code generation is explicit in Ferro: MCP tools return generation_hints that point directly to the CLI command that scaffolds the code.

End-to-end example: scaffolding a new model

1. The agent calls code_templates and receives a list of templates. The model template entry includes:

   generation_hint: "Use `ferro make:scaffold <ModelName>` to scaffold a new model with migration"
   

2. The agent reads the hint, identifies the CLI command: ferro make:scaffold.

3. The agent executes the CLI command:

   ferro make:scaffold Post
   

4. Ferro generates src/models/post.rs and a timestamped migration file with the correct SeaORM structure.

5. The agent reads the generated file using get_handler or directly, confirms the structure matches intent, and proceeds to add fields or relationships.

The key insight: the agent never guesses the CLI command syntax. generation_context and code_templates always provide the canonical invocation. The agent's job is to select the right template and supply the right arguments — the framework handles the rest.

Other generation hints flow the same way:

• code_templates → ferro make:action — scaffold a request handler
• code_templates → ferro make:migration — scaffold a database migration
• code_templates → ferro make:job — scaffold a background job
• generation_context for the current route → ferro make:controller with the matching name

Troubleshooting

"command not found" when starting the MCP server

The binary path in the MCP config must point to the ferro binary, not ferro-mcp. The binary is at target/debug/ferro (development) or target/release/ferro (production). There is no standalone ferro-mcp binary.

"No tools available" after connecting

Check the JSON syntax in your config file — a trailing comma or missing bracket will silently prevent the server from loading. Validate with a JSON linter. Also confirm the binary path is absolute, not relative.

Tools return stale data after code changes

The ferro MCP server reads your source code at startup. After changing models, routes, or handlers, rebuild the project (cargo build) and restart your MCP host so the server reloads with the updated source.

application_info shows missing features

Features are detected from Cargo.toml dependencies. If a crate is not in your workspace's Cargo.toml, it will not appear in application_info. Add the dependency and rebuild.

See Also

• MCP Bridge — ferro-api-mcp, the consumer-facing API MCP server that exposes your application's REST API to external agents (separate from the framework introspection covered here)

Directory Structure

A Ferro project follows a convention-based structure inspired by Laravel.

my-app/
├── Cargo.toml              # Rust dependencies
├── .env                    # Environment configuration
├── src/
│   ├── main.rs             # Application entry point
│   ├── routes.rs           # Route definitions
│   ├── bootstrap.rs        # Global middleware registration
│   ├── actions/            # Business logic handlers
│   ├── controllers/        # HTTP controllers
│   ├── middleware/         # Custom middleware
│   ├── models/             # Database entities (SeaORM)
│   ├── migrations/         # Database migrations
│   ├── services/           # Service implementations
│   ├── requests/           # Form request validation
│   ├── events/             # Event definitions
│   ├── listeners/          # Event listeners
│   ├── jobs/               # Background jobs
│   ├── notifications/      # Notification classes
│   └── tasks/              # Scheduled tasks
├── frontend/
│   ├── src/
│   │   ├── pages/          # Inertia.js React components
│   │   ├── components/     # Reusable UI components
│   │   ├── types/          # TypeScript type definitions
│   │   └── main.tsx        # Frontend entry point
│   ├── package.json        # Node dependencies
│   └── vite.config.ts      # Vite configuration
├── storage/
│   ├── app/                # Application files
│   └── logs/               # Log files
└── public/
    └── storage/            # Symlink to storage/app/public

Key Directories

src/actions/

Business logic that doesn't fit neatly into controllers. Actions are invocable classes for complex operations.

#![allow(unused)]
fn main() {
// src/actions/create_user.rs
#[derive(Action)]
pub struct CreateUser {
    user_service: Arc<dyn UserService>,
}

impl CreateUser {
    pub async fn execute(&self, data: CreateUserData) -> Result<User> {
        // Business logic here
    }
}
}

src/controllers/

HTTP handlers grouped by resource. Generated with ferro make:controller.

#![allow(unused)]
fn main() {
// src/controllers/users_controller.rs
#[handler]
pub async fn index(req: Request) -> Response { ... }

#[handler]
pub async fn store(req: Request, form: CreateUserForm) -> Response { ... }
}

src/models/

SeaORM entity definitions. Generated with ferro db:sync.

src/middleware/

Custom middleware for request/response processing.

src/events/ and src/listeners/

Event-driven architecture. Events dispatch to multiple listeners.

src/jobs/

Background job definitions for queue processing.

frontend/src/pages/

Inertia.js page components. Path determines the route component.

pages/Users/Index.tsx  →  Inertia::render("Users/Index", ...)
pages/Dashboard.tsx    →  Inertia::render("Dashboard", ...)

Configuration Files

.env

Environment-specific configuration:

APP_ENV=local
APP_DEBUG=true
DATABASE_URL=sqlite:database.db
REDIS_URL=redis://localhost:6379

Cargo.toml

Rust dependencies. Ferro crates are added here.

frontend/package.json

Node.js dependencies for the React frontend.

Generated Directories

These directories are created automatically:

• target/ - Rust build artifacts
• node_modules/ - Node.js dependencies
• frontend/dist/ - Built frontend assets

Storage

The storage/ directory holds application files:

# Create public storage symlink
ferro storage:link

This links public/storage → storage/app/public for publicly accessible files.

Routing

Ferro provides an expressive routing API similar to Laravel.

Basic Routes

Define routes in src/routes.rs:

#![allow(unused)]
fn main() {
use ferro::Router;

pub fn routes() -> Router {
    Router::new()
        .get("/", home)
        .get("/users", users::index)
        .post("/users", users::store)
        .put("/users/:id", users::update)
        .delete("/users/:id", users::destroy)
}
}

Route Parameters

Parameters are extracted from the URL path:

#![allow(unused)]
fn main() {
#[handler]
pub async fn show(req: Request, id: i64) -> Response {
    // id is extracted from /users/:id
    let user = User::find_by_id(id).one(&db).await?;
    Ok(json!(user))
}
}

Optional Parameters

Use Option<T> for optional parameters:

#![allow(unused)]
fn main() {
#[handler]
pub async fn index(req: Request, page: Option<i64>) -> Response {
    let page = page.unwrap_or(1);
    // ...
}
}

Route Groups

Group routes with shared middleware or prefixes:

#![allow(unused)]
fn main() {
pub fn routes() -> Router {
    Router::new()
        .group("/api", |group| {
            group
                .get("/users", api::users::index)
                .post("/users", api::users::store)
                .middleware(ApiAuthMiddleware)
        })
        .group("/admin", |group| {
            group
                .get("/dashboard", admin::dashboard)
                .middleware(AdminMiddleware)
        })
}
}

Root routes inside a group

A "/" route inside a non-root group matches both the bare prefix and the prefix with a trailing slash. Other paths concatenate normally.

#![allow(unused)]
fn main() {
Router::new()
    .group("/s/{slug}", |r| {
        r.get("/", show_item)        // matches /s/foo AND /s/foo/
         .get("/edit", edit_item)    // matches /s/foo/edit
    })
}

A trailing slash on the group prefix is stripped before concatenation, so group("/api/", ...) with a child /x route produces /api/x, not /api//x (double-slash). Route introspection via get_registered_routes() and ferro-mcp list_routes reports one entry per logical handler — the canonical path without trailing slash.

Named Routes

#![allow(unused)]
fn main() {
Router::new()
    .get("/users/:id", users::show).name("users.show")
}

Generate URLs:

#![allow(unused)]
fn main() {
let url = route("users.show", [("id", "1")]);
// => "/users/1"
}

Resource Routes

Generate CRUD routes for a resource:

#![allow(unused)]
fn main() {
Router::new()
    .resource("/users", users_controller)
}

This creates:

Route Middleware

Apply middleware to specific routes:

#![allow(unused)]
fn main() {
Router::new()
    .get("/dashboard", dashboard)
    .middleware(AuthMiddleware)
}

Or to groups:

#![allow(unused)]
fn main() {
Router::new()
    .group("/admin", |group| {
        group
            .get("/users", admin::users)
            .middleware(AdminMiddleware)
    })
}

Fallback Routes

Handle 404s:

#![allow(unused)]
fn main() {
Router::new()
    .get("/", home)
    .fallback(not_found)
}

Route Constraints

Validate route parameters:

#![allow(unused)]
fn main() {
Router::new()
    .get("/users/:id", users::show)
    .where_("id", r"\d+")  // Must be numeric
}

API Routes

For JSON APIs, typically group under /api:

#![allow(unused)]
fn main() {
Router::new()
    .group("/api/v1", |api| {
        api
            .get("/users", api::users::index)
            .post("/users", api::users::store)
            .middleware(ApiAuthMiddleware)
    })
}

View Routes

For simple views without controller logic:

#![allow(unused)]
fn main() {
Router::new()
    .view("/about", "About", AboutProps::default())
}

Redirect Routes

#![allow(unused)]
fn main() {
Router::new()
    .redirect("/old-path", "/new-path")
    .redirect_permanent("/legacy", "/modern")
}

Route Caching

In production, routes are compiled at build time for optimal performance.

Middleware

Ferro provides a powerful middleware system for intercepting and processing HTTP requests before they reach your route handlers. Middleware can inspect, modify, or short-circuit requests, and also post-process responses.

Generating Middleware

The fastest way to create a new middleware is using the Ferro CLI:

ferro make:middleware Auth

This command will:

1. Create src/middleware/auth.rs with a middleware stub
2. Update src/middleware/mod.rs to export the new middleware

Examples:

# Creates AuthMiddleware in src/middleware/auth.rs
ferro make:middleware Auth

# Creates RateLimitMiddleware in src/middleware/rate_limit.rs
ferro make:middleware RateLimit

# You can also include "Middleware" suffix (same result)
ferro make:middleware CorsMiddleware

Generated file:

#![allow(unused)]
fn main() {
//! Auth middleware

use ferro::{async_trait, Middleware, Next, Request, Response};

/// Auth middleware
pub struct AuthMiddleware;

#[async_trait]
impl Middleware for AuthMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        // TODO: Implement middleware logic
        next(request).await
    }
}
}

Overview

Middleware sits between the incoming request and your route handlers, allowing you to:

• Authenticate and authorize requests
• Log requests and responses
• Add CORS headers
• Rate limit requests
• Transform request/response data
• And much more

Creating Middleware

To create middleware, define a struct and implement the Middleware trait:

#![allow(unused)]
fn main() {
use ferro::{async_trait, HttpResponse, Middleware, Next, Request, Response};

pub struct LoggingMiddleware;

#[async_trait]
impl Middleware for LoggingMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        // Pre-processing: runs before the route handler
        println!("--> {} {}", request.method(), request.path());

        // Call the next middleware or route handler
        let response = next(request).await;

        // Post-processing: runs after the route handler
        println!("<-- Request complete");

        response
    }
}
}

The handle Method

The handle method receives:

• request: The incoming HTTP request
• next: A function to call the next middleware in the chain (or the route handler)

You can:

• Continue the chain: Call next(request).await to pass control to the next middleware
• Short-circuit: Return a response early without calling next()
• Modify the request: Transform the request before calling next()
• Modify the response: Transform the response after calling next()

Short-Circuiting Requests

Return early to block a request from reaching the route handler:

#![allow(unused)]
fn main() {
use ferro::{async_trait, HttpResponse, Middleware, Next, Request, Response};

pub struct AuthMiddleware;

#[async_trait]
impl Middleware for AuthMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        // Check for Authorization header
        if request.header("Authorization").is_none() {
            // Short-circuit: return 401 without calling the route handler
            return Err(HttpResponse::text("Unauthorized").status(401));
        }

        // Continue to the route handler
        next(request).await
    }
}
}

Registering Middleware

Ferro supports three levels of middleware:

1. Global Middleware

Global middleware runs on every request. Register it in bootstrap.rs using the global_middleware! macro:

#![allow(unused)]
fn main() {
// src/bootstrap.rs
use ferro::{global_middleware, DB};
use crate::middleware;

pub async fn register() {
    // Initialize database
    DB::init().await.expect("Failed to connect to database");

    // Global middleware runs on every request (in registration order)
    global_middleware!(middleware::LoggingMiddleware);
    global_middleware!(middleware::CorsMiddleware);
}
}

2. Route Middleware

Apply middleware to individual routes using the .middleware() method:

#![allow(unused)]
fn main() {
// src/routes.rs
use ferro::{routes, get, post};
use crate::controllers;
use crate::middleware::AuthMiddleware;

routes! {
    get("/", controllers::home::index).name("home"),
    get("/public", controllers::home::public),

    // Protected route - requires AuthMiddleware
    get("/protected", controllers::dashboard::index).middleware(AuthMiddleware),
    get("/admin", controllers::admin::index).middleware(AuthMiddleware),
}
}

3. Route Group Middleware

Apply middleware to a group of routes that share a common prefix:

#![allow(unused)]
fn main() {
use ferro::Router;
use crate::middleware::{AuthMiddleware, ApiMiddleware};

Router::new()
    // Public routes (no middleware)
    .get("/", home_handler)
    .get("/login", login_handler)

    // API routes with shared middleware
    .group("/api", |r| {
        r.get("/users", list_users)
         .post("/users", create_user)
         .get("/users/{id}", show_user)
    })
    .middleware(ApiMiddleware)

    // Admin routes with auth middleware
    .group("/admin", |r| {
        r.get("/dashboard", admin_dashboard)
         .get("/settings", admin_settings)
    })
    .middleware(AuthMiddleware)
}

Middleware attached to a group applies uniformly to root-path routes inside the group, covering both /prefix and /prefix/ variants.

Middleware Execution Order

Middleware executes in the following order:

1. Global middleware (in registration order)
2. Route group middleware
3. Route-level middleware
4. Route handler

For responses, the order is reversed (post-processing happens in reverse order).

Request → Global MW → Group MW → Route MW → Handler
                                              ↓
Response ← Global MW ← Group MW ← Route MW ← Handler

Practical Examples

CORS Middleware

#![allow(unused)]
fn main() {
use ferro::{async_trait, Middleware, Next, Request, Response, HttpResponse};

pub struct CorsMiddleware;

#[async_trait]
impl Middleware for CorsMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        let response = next(request).await;

        // Add CORS headers to the response
        match response {
            Ok(mut res) => {
                res = res
                    .header("Access-Control-Allow-Origin", "*")
                    .header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
                    .header("Access-Control-Allow-Headers", "Content-Type, Authorization");
                Ok(res)
            }
            Err(mut res) => {
                res = res
                    .header("Access-Control-Allow-Origin", "*");
                Err(res)
            }
        }
    }
}
}

Rate Limiting Middleware

#![allow(unused)]
fn main() {
use ferro::{async_trait, Middleware, Next, Request, Response, HttpResponse};
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;

pub struct RateLimitMiddleware {
    requests: Arc<AtomicUsize>,
    max_requests: usize,
}

impl RateLimitMiddleware {
    pub fn new(max_requests: usize) -> Self {
        Self {
            requests: Arc::new(AtomicUsize::new(0)),
            max_requests,
        }
    }
}

#[async_trait]
impl Middleware for RateLimitMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        let count = self.requests.fetch_add(1, Ordering::SeqCst);

        if count >= self.max_requests {
            return Err(HttpResponse::text("Too Many Requests").status(429));
        }

        next(request).await
    }
}
}

Request Timing Middleware

#![allow(unused)]
fn main() {
use ferro::{async_trait, Middleware, Next, Request, Response};
use std::time::Instant;

pub struct TimingMiddleware;

#[async_trait]
impl Middleware for TimingMiddleware {
    async fn handle(&self, request: Request, next: Next) -> Response {
        let start = Instant::now();
        let path = request.path().to_string();

        let response = next(request).await;

        let duration = start.elapsed();
        println!("{} completed in {:?}", path, duration);

        response
    }
}
}

Security Headers

The SecurityHeaders middleware adds OWASP-recommended HTTP security headers to all responses. It is registered by default in new projects generated with ferro new.

Default Headers

Customization

#![allow(unused)]
fn main() {
use ferro::{global_middleware, SecurityHeaders};

// Default (recommended for most apps)
global_middleware!(SecurityHeaders::new());

// Production with HTTPS
global_middleware!(SecurityHeaders::new().with_hsts());

// Custom frame options (allow same-origin iframes)
global_middleware!(SecurityHeaders::new()
    .x_frame_options("SAMEORIGIN"));

// Custom CSP for specific needs
global_middleware!(SecurityHeaders::new()
    .content_security_policy("default-src 'self'; script-src 'self'"));

// Disable a specific header
global_middleware!(SecurityHeaders::new()
    .without("X-Frame-Options"));
}

HSTS

HSTS (HTTP Strict Transport Security) is off by default because it breaks localhost development over HTTP. Enable it in production:

#![allow(unused)]
fn main() {
// Standard HSTS (max-age=1year, includeSubDomains)
global_middleware!(SecurityHeaders::new().with_hsts());

// HSTS with preload directive
global_middleware!(SecurityHeaders::new().with_hsts_preload());
}

with_hsts_preload() adds the preload directive. Only enable this if you have submitted your domain to the HSTS preload list. Preload is permanent -- removing a domain takes months.

Notes

• The default CSP includes 'unsafe-inline' and 'unsafe-eval' for compatibility with Inertia.js and Vite. Tighten these directives for production if your setup allows it.
• Security headers apply to both success and error responses.
• Headers are applied during response post-processing (after the route handler runs).
• Static files served directly by Ferro bypass middleware. Use a reverse proxy (e.g., nginx) for static file headers in production.

File Organization

The recommended file structure for middleware:

src/
├── middleware/
│   ├── mod.rs          # Re-export all middleware
│   ├── auth.rs         # Authentication middleware
│   ├── logging.rs      # Logging middleware
│   └── cors.rs         # CORS middleware
├── bootstrap.rs        # Register global middleware
├── routes.rs           # Apply route-level middleware
└── main.rs

src/middleware/mod.rs:

#![allow(unused)]
fn main() {
mod auth;
mod logging;
mod cors;

pub use auth::AuthMiddleware;
pub use logging::LoggingMiddleware;
pub use cors::CorsMiddleware;
}

Summary

Controllers

Controllers group related request handling logic.

Creating Controllers

ferro make:controller Users

This creates src/controllers/users_controller.rs:

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response, json};

#[handler]
pub async fn index(req: Request) -> Response {
    // List users
    Ok(json!({"users": []}))
}

#[handler]
pub async fn show(req: Request, id: i64) -> Response {
    // Show single user
    Ok(json!({"id": id}))
}

#[handler]
pub async fn store(req: Request) -> Response {
    // Create user
    Ok(json!({"created": true}))
}

#[handler]
pub async fn update(req: Request, id: i64) -> Response {
    // Update user
    Ok(json!({"updated": id}))
}

#[handler]
pub async fn destroy(req: Request, id: i64) -> Response {
    // Delete user
    Ok(json!({"deleted": id}))
}
}

The Handler Macro

The #[handler] macro provides:

1. Automatic parameter extraction from path, query, body
2. Dependency injection for services
3. Error handling conversion

#![allow(unused)]
fn main() {
#[handler]
pub async fn show(
    req: Request,           // Always available
    id: i64,                // From path parameter
    user_service: Arc<dyn UserService>,  // Injected service
) -> Response {
    let user = user_service.find(id).await?;
    Ok(json!(user))
}
}

Route Registration

Register controller methods in src/routes.rs:

#![allow(unused)]
fn main() {
use crate::controllers::users_controller;

pub fn routes() -> Router {
    Router::new()
        .get("/users", users_controller::index)
        .get("/users/:id", users_controller::show)
        .post("/users", users_controller::store)
        .put("/users/:id", users_controller::update)
        .delete("/users/:id", users_controller::destroy)
}
}

Inertia Controllers

For Inertia.js responses:

#![allow(unused)]
fn main() {
use ferro::{Inertia, InertiaProps, Request, Response};
use crate::models::users::Entity as User;

#[handler]
pub async fn index(req: Request) -> Response {
    let db = req.db();
    let users = User::find().all(db).await?;

    Inertia::render(&req, "Users/Index", UsersIndexProps { users })
}

#[derive(InertiaProps)]
pub struct UsersIndexProps {
    pub users: Vec<crate::models::users::Model>,
}
}

Form Handling with SavedInertiaContext

When handling forms, you need to call req.input() which consumes the request. To render validation errors with Inertia, save the context first:

#![allow(unused)]
fn main() {
use ferro::{Inertia, InertiaProps, Request, Response, SavedInertiaContext, Validate, serde_json};

#[derive(InertiaProps)]
pub struct LoginProps {
    pub errors: Option<serde_json::Value>,
}

#[derive(Deserialize, Validate)]
pub struct LoginRequest {
    #[validate(email(message = "Please enter a valid email"))]
    pub email: String,
    #[validate(length(min = 1, message = "Password is required"))]
    pub password: String,
}

#[handler]
pub async fn login(req: Request) -> Response {
    // Save Inertia context BEFORE consuming request
    let ctx = SavedInertiaContext::from(&req);

    // This consumes the request
    let form: LoginRequest = req.input().await?;

    // Validate - use saved context for error responses
    if let Err(errors) = form.validate() {
        return Inertia::render_ctx(
            &ctx,
            "auth/Login",
            LoginProps { errors: Some(serde_json::json!(errors)) },
        ).map(|r| r.status(422));
    }

    // Process login...
    redirect!("/dashboard").into()
}
}

Key points:

• SavedInertiaContext::from(&req) captures path and Inertia headers
• Inertia::render_ctx(&ctx, ...) renders using saved context
• Use this pattern when you need to both read the body AND render Inertia responses

Form Validation

Use form requests for validation:

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response};

#[derive(FormRequest)]
pub struct CreateUserRequest {
    #[validate(required, email)]
    pub email: String,

    #[validate(required, min(8))]
    pub password: String,
}

#[handler]
pub async fn store(req: Request, form: CreateUserRequest) -> Response {
    // form is already validated
    let user = User::create(form.email, form.password).await?;
    Ok(Redirect::to("/users"))
}
}

Service Injection

Inject services via the #[service] system:

#![allow(unused)]
fn main() {
#[handler]
pub async fn store(
    req: Request,
    form: CreateUserRequest,
    user_service: Arc<dyn UserService>,
    mailer: Arc<dyn Mailer>,
) -> Response {
    let user = user_service.create(form).await?;
    mailer.send_welcome(user.email).await?;

    Ok(Redirect::to("/users"))
}
}

Actions

For complex operations, use Actions:

ferro make:action CreateUser

#![allow(unused)]
fn main() {
// src/actions/create_user.rs
use ferro::handler;
use std::sync::Arc;

#[derive(Action)]
pub struct CreateUser {
    user_service: Arc<dyn UserService>,
    mailer: Arc<dyn Mailer>,
}

impl CreateUser {
    pub async fn execute(&self, data: CreateUserData) -> Result<User> {
        let user = self.user_service.create(data).await?;
        self.mailer.send_welcome(&user).await?;
        Ok(user)
    }
}
}

Use in controller:

#![allow(unused)]
fn main() {
#[handler]
pub async fn store(req: Request, form: CreateUserRequest, action: CreateUser) -> Response {
    let user = action.execute(form.into()).await?;
    Ok(Redirect::to(format!("/users/{}", user.id)))
}
}

Resource Controllers

A resource controller handles all CRUD operations:

API Controllers

For JSON APIs:

#![allow(unused)]
fn main() {
#[handler]
pub async fn index(req: Request) -> Response {
    let users = User::find().all(&req.db()).await?;

    Ok(json!({
        "data": users,
        "meta": {
            "total": users.len()
        }
    }))
}
}

With pagination:

#![allow(unused)]
fn main() {
#[handler]
pub async fn index(req: Request, page: Option<i64>, per_page: Option<i64>) -> Response {
    let page = page.unwrap_or(1);
    let per_page = per_page.unwrap_or(15);

    let paginator = User::find()
        .paginate(&req.db(), per_page as u64);

    let users = paginator.fetch_page(page as u64 - 1).await?;
    let total = paginator.num_items().await?;

    Ok(json!({
        "data": users,
        "meta": {
            "current_page": page,
            "per_page": per_page,
            "total": total
        }
    }))
}
}

See also

For POST handlers that mutate state and redirect on every code path, use #[action]. It preserves Ok(()) and bare ? ergonomics while handling the 303 redirect, session flash, and back-compat query string automatically.

Action Handlers

#[action] is the attribute macro for POST-style handlers that mutate state and then redirect. It is a sibling of #[handler] — choose #[action] when the handler's natural completion is a 303 redirect (success or error); choose #[handler] for HTMX partials, JSON endpoints, GET pages, or anything that does not redirect on every code path.

When to use #[action]

Use #[action] when the handler:

• Receives a POST (or PUT / PATCH / DELETE) form submission.
• Mutates state (creates, updates, deletes a record).
• Redirects to a list or detail page on success.
• Should redirect (often back to the same page) on error, surfacing the failure as a flash message.

Keep #[handler] for handlers that render a response: GET pages, JSON APIs, HTMX partials, file downloads.

Quick example

#![allow(unused)]
fn main() {
use ferro::{action, ActionError, ActionResult, Request};

#[action(redirect_to = "/dashboard/pages")]
pub async fn publish_by_id(req: Request, id: i64) -> ActionResult {
    let page = Page::find_by_id(id).await?
        .ok_or(ActionError::not_found("Page not found"))?;
    page.publish().await?;
    Ok(())
}
}

On success the user is redirected to /dashboard/pages with a 303. On any Err, the user is redirected to the same URL with ?error=<kind>&msg=<text> appended and a session flash entry written under the _action slot.

The macro shape

#![allow(unused)]
fn main() {
#[action(redirect_to = "/path", method = "POST")]
}

• redirect_to — required. The success-path redirect target. Must be a same-origin path (starting with /).
• method — optional. Default "POST". Currently informational; it documents the intended method but does not affect routing. Wire the route in your routes.rs as usual.

The user-written signature uses req: Request (not &mut Request). The macro generates the mutable binding internally — Request passes by value in the function signature, and the macro rebinds it as &mut Request before handing it to the user body.

Return type — ActionResult

#![allow(unused)]
fn main() {
pub type ActionResult = Result<(), ActionError>;
}

The success expression is Ok(()) — there is no helper type to construct. The error side is ActionError (described below).

? ergonomics

Inside an #[action] body, ? works directly on:

• Result<_, String>
• Result<_, &'static str>
• Result<_, FrameworkError>
• Result<_, sea_orm::DbErr>

The macro wraps the body in an async move { ... }.await block typed as ActionResult, so ? propagates to ActionResult, not to the outer Response-returning function. This is what makes bare ? work on the error types above.

For any other error type implementing std::fmt::Display, use the .action_err() extension method:

#![allow(unused)]
fn main() {
use ferro::ActionResultExt;

let value = some_external_call()
    .action_err()?;
}

.action_err() converts any Display error into an ActionError::msg(e.to_string()).

ActionError — constructors and builders

#![allow(unused)]
fn main() {
ActionError::msg("Something went wrong");           // kind = Generic
ActionError::not_found("Page not found");           // kind = NotFound
ActionError::forbidden("You don't own this page");  // kind = Forbidden
ActionError::unauthorized("Please sign in");        // kind = Unauthorized
}

Builder methods (consuming mut self -> Self):

#![allow(unused)]
fn main() {
ActionError::msg("Saved as draft")
    .with_flash(FlashVariant::Warning)         // override the banner variant
    .redirect_to("/dashboard/pages/123/edit"); // override the redirect target
}

redirect_to(...) on ActionError is the error-side redirect override. The most common use is unauthorized() — ferro does not know your application's sign-in path, so configure it explicitly:

#![allow(unused)]
fn main() {
if !user.is_authenticated() {
    return Err(ActionError::unauthorized("Please sign in")
        .redirect_to("/your-login-path"));
}
}

Ferro intentionally does not ship a default authentication redirect. Consumer applications supply the path. This keeps ferro-* crates project-agnostic (no hardcoded sign-in routes).

Success-side overrides

Request exposes two setter methods for overriding the success path:

#![allow(unused)]
fn main() {
#[action(redirect_to = "/dashboard/pages")]
pub async fn create(req: Request) -> ActionResult {
    let new_page = Page::create(...).await?;
    req.redirect_to(format!("/dashboard/pages/{}", new_page.id));
    req.flash("created");
    Ok(())
}
}

• req.redirect_to(url) — overrides the configured redirect_to on the success path. Validated as same-origin; external URLs are silently ignored (see Security below).
• req.flash(key) — records a success flash key. On the next page render, the consumer template reads the _action flash slot to surface the success message.

Both setters take effect only on the success path. On Err, they are ignored; ActionError's own redirect_override and flash_variant apply instead.

The override surface is split by code path: success-side overrides live on Request (where the success handler has access); error-side overrides live on ActionError (where the error is constructed). This makes each override discoverable at its natural call site.

Flash transport

#[action] writes a JSON payload to the session flash slot _action:

{
  "variant": "error",
  "message": "Page not found"
}

variant is one of error, warning, info, or success. Templates use this to choose the banner's CSS class.

Consumer templates read the flash via:

#![allow(unused)]
fn main() {
let action_flash = session.get_flash::<serde_json::Value>("_action");
// Pass to the view.
}

get_flash ages the value — the next render after the redirect sees it; subsequent renders do not.

Back-compat query string

For templates not yet wired to read session flash, #[action] also appends a query string to the redirect URL:

• Error path: ?error=<kind>&msg=<percent-encoded-message>
• Success path: ?success=<flash-key-or-1>

where <kind> is the snake_case ActionKind value: generic, not_found, forbidden, unauthorized. This fallback exists for incremental migration and may be removed in a future ferro release once session flash reading is universal in consumer templates.

Security

The action runtime applies three mitigations. Consumers should be aware of each.

Flash message escaping (T-180-01)

ActionError::message is treated as untrusted user-facing display text. It may originate from a database error reflecting a query parameter, a parsed form field, or any other input the handler touches.

Consumer templates MUST HTML-escape the flash message before rendering. Ferro stores the message verbatim in the JSON flash payload; escaping is the template's responsibility.

Safe rendering example:

{% if action_flash %}
  <div class="flash flash--{{ action_flash.variant }}">
    {{ action_flash.message | escape }}
  </div>
{% endif %}

Open-redirect mitigation (T-180-02)

Both the error-side ActionError::redirect_to(...) and the success-side req.redirect_to(...) are validated as same-origin at the moment the redirect is built. URLs not starting with /, or starting with // (scheme-relative), are silently rejected and the request falls back to the configured #[action(redirect_to = "...")] target. A tracing::warn! records the rejection.

To redirect to an external URL, use a dedicated #[handler] that constructs the redirect explicitly.

Log-injection mitigation (T-180-03)

tracing::error! is called on the error path with the handler name and error message. Control characters in the message (\n, \r, \t, NUL, etc.) are stripped before the call so structured log sinks see a single-line value. This is defense-in-depth — JSON log formatters escape control characters anyway, but plain-text sinks benefit.

The query-string fallback (?msg=...) uses standard percent-encoding so control characters in the URL are encoded, not interpreted.

Before / after

A typical action handler before #[action]:

Before

#![allow(unused)]
fn main() {
#[handler]
pub async fn publish_by_id(req: Request, id: i64) -> Response {
    let page = Page::find_by_id(id).await
        .map_err(|e| error_response(500, &format!("DB error: {e}")))?
        .ok_or_else(|| error_response(404, "Page not found"))?;
    if page.tenant_id != current_tenant_id {
        return Err(error_response(403, "Not authorized"));
    }
    match page.publish().await {
        Ok(()) => Redirect::to("/dashboard/pages?success=published").into(),
        Err(err_msg) => {
            let encoded: String = pct_encode(&err_msg);
            Redirect::to(format!("/dashboard/pages?error=publish&msg={}", encoded)).into()
        }
    }
}
}

On any failure the browser is stranded at the POST URL displaying a 500 page.

After

#![allow(unused)]
fn main() {
#[action(redirect_to = "/dashboard/pages")]
pub async fn publish_by_id(req: Request, id: i64) -> ActionResult {
    let page = Page::find_by_id(id).await?
        .ok_or(ActionError::not_found("Page not found"))?;
    if page.tenant_id != current_tenant_id {
        return Err(ActionError::forbidden(""));
    }
    page.publish().await?;
    Ok(())
}
}

Every failure is a 303 redirect to /dashboard/pages with a flash message and a back-compat query string. The browser does not strand at the POST URL.

error_response! macro

For handlers that return Response (not ActionResult), the error_response! macro produces a bare HttpResponse suitable for use inside .map_err(...) and .ok_or_else(...) error arms:

use ferro::error_response;

let record = Entity::find_by_id(id)
    .one(db)
    .await
    .map_err(|e| ferro::error_response!(500, e.to_string()))?
    .ok_or_else(|| ferro::error_response!(404, "Not found"))?;

The macro returns an HttpResponse with a JSON body {"message": "..."} and the given status code. It does not wrap the value in Ok(...) — the ? operator in the error arm does the unwrapping.

See also

• Controllers — for the routing layer that mounts handlers.
• Request & Response — for non-redirecting response types.

Request & Response

The Request Object

Every handler receives a Request object:

#![allow(unused)]
fn main() {
#[handler]
pub async fn show(req: Request) -> Response {
    // Use request data
}
}

Accessing Request Data

#![allow(unused)]
fn main() {
// Path: /users/123
let id = req.param::<i64>("id")?;

// Query: /users?page=2&sort=name
let page = req.query::<i64>("page").unwrap_or(1);
let sort = req.query::<String>("sort");

// Headers
let auth = req.header("Authorization");
let content_type = req.content_type();

// Method and path
let method = req.method();
let path = req.path();
let full_url = req.url();
}

Request Body

#![allow(unused)]
fn main() {
// JSON body
let data: CreateUserData = req.json().await?;

// Form data
let form: HashMap<String, String> = req.form().await?;

// Raw body
let bytes = req.body_bytes().await?;
let text = req.body_string().await?;
}

File Uploads

#![allow(unused)]
fn main() {
let file = req.file("avatar").await?;

// File properties
let filename = file.filename();
let content_type = file.content_type();
let size = file.size();

// Save file
file.store("avatars").await?;
// or
file.store_as("avatars", "custom-name.jpg").await?;
}

Authentication

#![allow(unused)]
fn main() {
// Check if authenticated
if req.is_authenticated() {
    let user = req.user()?;
    println!("Hello, {}", user.name);
}

// Get optional user
if let Some(user) = req.user_optional() {
    // ...
}
}

Session Data

#![allow(unused)]
fn main() {
// Read session
let user_id = req.session().get::<i64>("user_id");

// Write session (needs mutable access)
req.session_mut().set("flash", "Welcome back!");

// Flash messages
let flash = req.session().flash("message");
}

Cookies

#![allow(unused)]
fn main() {
// Read cookie
let token = req.cookie("remember_token");

// Cookies are typically set on responses
}

Database Access

#![allow(unused)]
fn main() {
let db = req.db();
let users = User::find().all(db).await?;
}

Responses

Handlers return Response which is Result<HttpResponse, HttpResponse>:

#![allow(unused)]
fn main() {
pub type Response = Result<HttpResponse, HttpResponse>;
}

JSON Responses

#![allow(unused)]
fn main() {
#[handler]
pub async fn index(req: Request) -> Response {
    Ok(json!({
        "users": users,
        "total": 100
    }))
}

// Or using HttpResponse directly
Ok(HttpResponse::json(data))
}

HTML Responses

#![allow(unused)]
fn main() {
Ok(HttpResponse::html("<h1>Hello</h1>"))
}

Text Responses

#![allow(unused)]
fn main() {
Ok(HttpResponse::text("Hello, World!"))
}

Inertia Responses

#![allow(unused)]
fn main() {
// Basic Inertia response
Inertia::render(&req, "Users/Index", props)

// With saved context (for form handlers)
let ctx = SavedInertiaContext::from(&req);
let form = req.input().await?;  // Consumes request
Inertia::render_ctx(&ctx, "Users/Form", props)
}

See Controllers - Form Handling for complete examples.

Redirects

#![allow(unused)]
fn main() {
// Simple redirect
Ok(Redirect::to("/dashboard"))

// Redirect back
Ok(Redirect::back(&req))

// Redirect with flash message
Ok(Redirect::to("/users").with("success", "User created!"))

// Named route redirect
Ok(Redirect::route("users.show", [("id", "1")]))
}

Status Codes

#![allow(unused)]
fn main() {
// Success codes
Ok(HttpResponse::ok(body))
Ok(HttpResponse::created(body))
Ok(HttpResponse::no_content())

// Error codes
Err(HttpResponse::bad_request("Invalid input"))
Err(HttpResponse::unauthorized("Please login"))
Err(HttpResponse::forbidden("Access denied"))
Err(HttpResponse::not_found("User not found"))
Err(HttpResponse::server_error("Something went wrong"))
}

Custom Status

#![allow(unused)]
fn main() {
Ok(HttpResponse::json(data).status(202))
}

Response Headers

#![allow(unused)]
fn main() {
Ok(HttpResponse::json(data)
    .header("X-Custom", "value")
    .header("Cache-Control", "no-cache"))
}

Cookies

#![allow(unused)]
fn main() {
Ok(HttpResponse::json(data)
    .cookie(Cookie::new("token", "abc123"))
    .cookie(Cookie::new("remember", "true")
        .http_only(true)
        .secure(true)
        .max_age(Duration::days(30))))
}

Binary Responses

Serve raw binary data (images, PDFs, generated files):

#![allow(unused)]
fn main() {
// Serve binary with explicit content type
Ok(HttpResponse::bytes(png_bytes)
    .header("Content-Type", "image/png"))

// File download with Content-Disposition
Ok(HttpResponse::download(pdf_bytes, "report.pdf"))
}

download() auto-detects Content-Type from the filename extension and sets the Content-Disposition: attachment header.

For static files served from public/, use the built-in static file serving (no handler needed).

Error Handling

Return errors as HttpResponse:

#![allow(unused)]
fn main() {
#[handler]
pub async fn show(req: Request, id: i64) -> Response {
    let user = User::find_by_id(id)
        .one(&req.db())
        .await?
        .ok_or_else(|| HttpResponse::not_found("User not found"))?;

    Ok(json!(user))
}
}

Domain Errors

Use #[domain_error] for typed errors:

#![allow(unused)]
fn main() {
#[domain_error]
pub enum UserError {
    #[error("User not found")]
    #[status(404)]
    NotFound,

    #[error("Email already taken")]
    #[status(409)]
    EmailTaken,
}

#[handler]
pub async fn store(req: Request) -> Response {
    let result = create_user().await?; // ? converts UserError to HttpResponse
    Ok(json!(result))
}
}

Form Requests

For automatic validation:

#![allow(unused)]
fn main() {
#[derive(FormRequest)]
pub struct CreateUserRequest {
    #[validate(required, email)]
    pub email: String,

    #[validate(required, min(8))]
    pub password: String,

    #[validate(same("password"))]
    pub password_confirmation: String,
}

#[handler]
pub async fn store(req: Request, form: CreateUserRequest) -> Response {
    // form is validated, safe to use
    Ok(json!({"email": form.email}))
}
}

If validation fails, Ferro automatically returns a 422 response with errors.

InlineBudget & RequestTelemetry

Two request-scoped primitives for HTML inline-vs-preload decisioning and in-process sampled telemetry.

When to use InlineBudget

InlineBudget decides at request time whether a chunk of bytes should be inlined into the HTML response or preloaded via <link rel=preload>. Use it when:

• The response renders payloads of varying size depending on tenant or context.
• Inlining everything would risk crossing a payload-size cliff (HTML parse cost on the client).
• A pre-built static fallback URL exists for the same byte payload.

RequestTelemetry records sampled time-series telemetry into an in-process ring buffer keyed by (key, scope). Use it when:

• Operator dashboards need recent samples of a metric without round-tripping through an external telemetry system.
• Per-tenant or per-route slicing is useful for diagnostics.
• The "lost on process restart" semantic is acceptable.

Quick example

use ferro_rs::{Decision, Request, RequestTelemetry, Sample};
use serde_json::json;

async fn render_page(req: &mut Request, products: Vec<Product>) -> String {
    let products_json = serde_json::to_string(&products).unwrap_or_default();
    let payload_bytes = products_json.len();

    let body = "<div>...</div>";

    let html = match req.inline_budget(
        "products_payload",
        payload_bytes,
        "/_/bootstrap/products.json",
    ) {
        Decision::Inline => format!(
            "<script id='__products' type='application/json'>{products_json}</script>{body}",
        ),
        Decision::Preload(url) => format!(
            r#"<link rel="preload" as="fetch" href="{url}" crossorigin>{body}"#,
        ),
    };

    // Telemetry: record the payload byte count scoped to the tenant.
    req.telemetry_record_scoped(
        "products_payload_size",
        Some("tenant:42"),
        Sample::now(json!({ "bytes": payload_bytes })),
    );

    html
}

// Operator dashboard handler:
async fn ops_payload_distribution() -> Vec<Sample> {
    RequestTelemetry::snapshot("products_payload_size", Some("tenant:42"))
}

The Decision enum

pub enum Decision {
    Inline,
    Preload(String),
}

Match on Decision::Inline to emit the bytes inline; match on Decision::Preload(url) to emit a <link rel=preload href=url> and serve the same bytes from url separately. The URL is whatever the caller passed as fallback_url — there is no rewriting.

Threshold configuration

The threshold is read from AppConfig::inline_budget_threshold_bytes. Default: 102_400 (100 KiB).

Override via env var:

INLINE_BUDGET_BYTES=204800  # 200 KiB

Or programmatically:

use ferro_rs::{AppConfigBuilder, Config};

let cfg = AppConfigBuilder::default()
    .inline_budget_threshold_bytes(204_800)
    .build();

// Register the built config with the container so `req.inline_budget(...)`
// will pick up the override. Building the config without registering it has
// no effect — `decide()` reads from the container, not from a local binding.
Config::register(cfg);

If you skip the Config::register(cfg) step, inline_budget silently falls back to the INLINE_BUDGET_BYTES env var or to [ferro_rs::DEFAULT_INLINE_BUDGET_THRESHOLD_BYTES] (currently 100 KiB).

The threshold is global — there is no per-key override in v1. If your application needs heterogeneous budgets per key, file an issue requesting req.inline_budget_with_limit(key, bytes, fallback_url, limit).

Warning channel

The first time cumulative bytes for a given key crosses the threshold within a single request, InlineBudget emits a structured tracing::warn! with the following fields:

The warning fires exactly once per (key, request). Subsequent calls past the threshold for the same key in the same request return Decision::Preload silently (no warning spam).

The fallback_url field is logged with Display formatting. Do NOT pass user-controlled input as fallback_url; the field is intended for compile-time-shaped strings designed by the application developer.

When to use RequestTelemetry

RequestTelemetry is a per-key in-process ring buffer for sampled time-series telemetry. Use it for operator-visible metrics that:

• Have low cardinality on the (key, scope) axis.
• Benefit from per-tenant or per-route slicing.
• Do not require cross-process aggregation (use Prometheus or OpenTelemetry for that).

Each (key, scope) bucket holds at most 128 samples — oldest dropped on overflow. The store is process-global and lost on process restart.

Sample shape

pub struct Sample {
    pub recorded_at: std::time::SystemTime,
    pub value: serde_json::Value,
}

impl Sample {
    pub fn now(value: serde_json::Value) -> Self;
    pub fn at(when: std::time::SystemTime, value: serde_json::Value) -> Self;
}

recorded_at uses SystemTime (wall-clock) so samples remain comparable across process restarts. value is a serde_json::Value so heterogeneous payloads from different writers can share a snapshot reader.

Sample payload size is unbounded and caller-controlled. Keep payloads small — a few hundred bytes is typical for an operator-dashboard sample (a couple of numeric fields, a tenant id, maybe a route pattern). The ring buffer holds [ferro_rs::RING_BUFFER_CAPACITY] samples per (key, scope), so the per-bucket memory ceiling is payload_size × RING_BUFFER_CAPACITY. The framework does not enforce a per-sample size cap; that is caller discipline, the same framing as the (key, scope) cardinality note above.

Writer methods

impl Request {
    pub fn telemetry_record(&mut self, key: &str, sample: Sample);
    pub fn telemetry_record_scoped(&mut self, key: &str, scope: Option<&str>, sample: Sample);
}

telemetry_record(key, sample) is equivalent to telemetry_record_scoped(key, None, sample). Both methods take &mut self for API uniformity with inline_budget; neither mutates the request itself.

Reader — snapshot

impl RequestTelemetry {
    pub fn snapshot(key: &str, scope: Option<&str>) -> Vec<Sample>;
    pub fn keys() -> Vec<(String, Option<String>)>;
    pub fn clear();
}

snapshot returns a clone of every sample currently in the (key, scope) bucket in FIFO order. Empty if no samples have been recorded.

keys lists every (key, scope) pair that has at least one recorded sample. Useful for operator dashboards that need to enumerate available metrics.

clear drops every sample in every bucket — intended for operator-driven resets (e.g. post-deploy).

The reader API is internal Rust. If exposed on an HTTP endpoint, the consumer is responsible for authorization — RequestTelemetry itself enforces no access control.

Scope conventions

scope is Option<&str>; callers pick the convention. Recommended formats:

These are conventions, not constraints — the storage layer treats scope as an opaque Option<&str>.

Lost-on-restart semantic

The ring buffer is in-process memory. Process restart drops every sample. This is by design — RequestTelemetry is for recent operator-visible signal, not long-term metrics retention. For cross-process aggregation, export selected metrics to Prometheus, OpenTelemetry, or a custom DB sink.

Key cardinality

The (key, scope) axis has no enforced upper bound on cardinality. Callers MUST NOT derive key or scope strings from user input — a unique key per user creates unbounded growth of the global store. Use a fixed vocabulary controlled by application code.

End-to-end example

The "Quick example" section above is the canonical end-to-end example. It exercises both primitives in one handler: inline_budget decides inline-vs-preload for the products payload, then telemetry_record_scoped records the byte count under a per-tenant scope. The operator handler uses RequestTelemetry::snapshot to read recent samples for that tenant's bucket.

Events & Listeners

Ferro provides a Laravel-inspired event system for decoupling your application components. Events represent something that happened, while listeners react to those events.

Creating Events

Using the CLI

Generate a new event:

ferro make:event OrderPlaced

This creates src/events/order_placed.rs:

#![allow(unused)]
fn main() {
use ferro::Event;

#[derive(Clone)]
pub struct OrderPlaced {
    pub order_id: i64,
    pub user_id: i64,
    pub total: f64,
}

impl Event for OrderPlaced {
    fn name(&self) -> &'static str {
        "OrderPlaced"
    }
}
}

Event Requirements

Events must implement:

• Clone - Events may be sent to multiple listeners
• Send + Sync + 'static - For async safety
• Event trait - Provides the event name

Creating Listeners

Using the CLI

Generate a new listener:

ferro make:listener SendOrderConfirmation

This creates src/listeners/send_order_confirmation.rs:

#![allow(unused)]
fn main() {
use ferro::{Listener, Error, async_trait};
use crate::events::OrderPlaced;

pub struct SendOrderConfirmation;

#[async_trait]
impl Listener<OrderPlaced> for SendOrderConfirmation {
    async fn handle(&self, event: &OrderPlaced) -> Result<(), Error> {
        tracing::info!("Sending confirmation for order {}", event.order_id);
        // Send email logic...
        Ok(())
    }
}
}

Listener Trait Methods

Registering Listeners

Register listeners in src/bootstrap.rs:

#![allow(unused)]
fn main() {
use ferro::{App, EventDispatcher};
use crate::events::OrderPlaced;
use crate::listeners::{SendOrderConfirmation, UpdateInventory, NotifyWarehouse};

pub async fn register() {
    // ... other setup ...

    let dispatcher = App::event_dispatcher();

    // Register listeners for OrderPlaced event
    dispatcher.listen::<OrderPlaced, _>(SendOrderConfirmation);
    dispatcher.listen::<OrderPlaced, _>(UpdateInventory);
    dispatcher.listen::<OrderPlaced, _>(NotifyWarehouse);
}
}

Closure Listeners

For simple cases, use closures:

#![allow(unused)]
fn main() {
dispatcher.on::<OrderPlaced, _, _>(|event| async move {
    tracing::info!("Order {} placed!", event.order_id);
    Ok(())
});
}

Dispatching Events

Ergonomic API (Recommended)

Call .dispatch() directly on events:

#![allow(unused)]
fn main() {
use crate::events::OrderPlaced;

// In a controller or service
OrderPlaced {
    order_id: 123,
    user_id: 456,
    total: 99.99,
}
.dispatch()
.await?;
}

Fire and Forget

Dispatch without waiting for listeners:

#![allow(unused)]
fn main() {
OrderPlaced {
    order_id: 123,
    user_id: 456,
    total: 99.99,
}
.dispatch_sync();  // Returns immediately
}

Using the Dispatcher Directly

#![allow(unused)]
fn main() {
use ferro::dispatch;

dispatch(OrderPlaced {
    order_id: 123,
    user_id: 456,
    total: 99.99,
}).await?;
}

Queued Listeners

For long-running tasks, queue listeners for background processing:

#![allow(unused)]
fn main() {
use ferro::{Listener, ShouldQueue, Error, async_trait};
use crate::events::OrderPlaced;

pub struct GenerateInvoicePDF;

// Mark as queued
impl ShouldQueue for GenerateInvoicePDF {
    fn queue(&self) -> &'static str {
        "invoices"  // Send to specific queue
    }

    fn delay(&self) -> Option<u64> {
        Some(30)  // Wait 30 seconds before processing
    }

    fn max_retries(&self) -> u32 {
        5
    }
}

#[async_trait]
impl Listener<OrderPlaced> for GenerateInvoicePDF {
    async fn handle(&self, event: &OrderPlaced) -> Result<(), Error> {
        // This runs in a background worker
        tracing::info!("Generating PDF for order {}", event.order_id);
        Ok(())
    }
}
}

Stopping Propagation

Stop subsequent listeners from running:

#![allow(unused)]
fn main() {
impl Listener<OrderPlaced> for FraudChecker {
    async fn handle(&self, event: &OrderPlaced) -> Result<(), Error> {
        if self.is_fraudulent(event) {
            return Err(Error::msg("Fraudulent order detected"));
        }
        Ok(())
    }

    fn should_stop_propagation(&self) -> bool {
        true  // Other listeners won't run if this fails
    }
}
}

Example: Order Processing

#![allow(unused)]
fn main() {
// events/order_placed.rs
#[derive(Clone)]
pub struct OrderPlaced {
    pub order_id: i64,
    pub user_id: i64,
    pub items: Vec<OrderItem>,
    pub total: f64,
}

impl Event for OrderPlaced {
    fn name(&self) -> &'static str { "OrderPlaced" }
}

// listeners/send_order_confirmation.rs
pub struct SendOrderConfirmation;

#[async_trait]
impl Listener<OrderPlaced> for SendOrderConfirmation {
    async fn handle(&self, event: &OrderPlaced) -> Result<(), Error> {
        let user = User::find(event.user_id).await?;
        Mail::to(&user.email)
            .subject("Order Confirmation")
            .template("emails/order-confirmation", event)
            .send()
            .await?;
        Ok(())
    }
}

// listeners/update_inventory.rs
pub struct UpdateInventory;

#[async_trait]
impl Listener<OrderPlaced> for UpdateInventory {
    async fn handle(&self, event: &OrderPlaced) -> Result<(), Error> {
        for item in &event.items {
            Product::decrement_stock(item.product_id, item.quantity).await?;
        }
        Ok(())
    }
}

// bootstrap.rs
dispatcher.listen::<OrderPlaced, _>(SendOrderConfirmation);
dispatcher.listen::<OrderPlaced, _>(UpdateInventory);
}

Best Practices

1. Keep events immutable - Events are data, not behavior
2. Use descriptive names - Past tense for things that happened (OrderPlaced, UserRegistered)
3. Include all needed data - Listeners shouldn't need to fetch additional data
4. Queue heavy operations - Use ShouldQueue for emails, PDFs, external APIs
5. Handle failures gracefully - Listeners should not break on individual failures
6. Test listeners in isolation - Unit test each listener independently

MCP Tools

Use list_events to discover all registered events and listeners in the project.

list_events

Returns all Event implementations found in src/events/, each with the event name, fields, and which listeners are registered to handle it. Use this to understand the event graph before adding new listeners or debugging dispatch issues.

Queues & Background Jobs

Ferro provides a database-backed queue for processing jobs asynchronously. The queue uses the application's existing DatabaseConnection — no separate external queue server is needed. The WorkerLoop runs in-process inside Application::run and is started automatically when at least one job type is registered.

Atomic claim is dual-backend:

• Postgres — SELECT … FOR UPDATE SKIP LOCKED inside a transaction
• SQLite — raw BEGIN IMMEDIATE + UPDATE … RETURNING

Both paths claim exactly one job per cycle; two workers on the same table cannot double-claim a row.

Setup

Migration

Register CreateJobsTable in your application's Migrator alongside your own migrations:

#![allow(unused)]
fn main() {
use ferro_queue::CreateJobsTable;
use sea_orm_migration::prelude::*;

pub struct Migrator;

#[async_trait::async_trait]
impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            Box::new(CreateJobsTable),
            // ... your own migrations
        ]
    }
}
}

Registration

Register job types in your bootstrap before the server starts. The framework's server boot path (inside Application::run) detects registered job types and spawns a WorkerLoop automatically — no separate process or CLI command required.

#![allow(unused)]
fn main() {
// src/bootstrap.rs
use ferro::queue::Queue;
use crate::jobs::{ProcessPayment, SendEmail, GenerateReport};

pub async fn register() {
    // Register job types — the framework auto-starts the WorkerLoop.
    Queue::register::<ProcessPayment>();
    Queue::register::<SendEmail>();
    Queue::register::<GenerateReport>();
}
}

Environment Variables

# Queue driver: "sync" for development (jobs run inline), any other value for background.
# IMPORTANT: when QUEUE_CONNECTION is UNSET it defaults to "sync" — background
# processing is OFF unless you set this to a non-sync value (e.g. "db").
QUEUE_CONNECTION=db

# Default queue name
QUEUE_DEFAULT=default

# Maximum concurrent jobs per worker instance
QUEUE_MAX_CONCURRENT=10

QUEUE_CONNECTION defaults to sync when unset. In sync mode jobs run inline during the HTTP request — no background worker, no database polling — and .delay() / .on_queue() are ignored. Set any other value (e.g. db) to enable background processing. If jobs are registered while the queue is in sync mode, the server logs a startup warning, since this combination is usually unintended in production.

Creating Jobs

Using the CLI

ferro make:job ProcessPayment

This creates src/jobs/process_payment.rs:

#![allow(unused)]
fn main() {
use ferro::queue::{Job, Error, async_trait};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProcessPayment {
    pub order_id: i64,
    pub amount: f64,
}

#[async_trait]
impl Job for ProcessPayment {
    async fn handle(&self) -> Result<(), Error> {
        tracing::info!("Processing payment for order {}", self.order_id);
        // Payment processing logic...
        Ok(())
    }

    fn max_retries(&self) -> u32 {
        3
    }
}
}

Job Trait Methods

Retry Delay Default

The default retry_delay uses full-jitter exponential backoff: rand(0..=min(cap, base × 2^attempt)) where base = 5 s and cap = 15 min. Override it on individual job types:

#![allow(unused)]
fn main() {
fn retry_delay(&self, attempt: u32) -> std::time::Duration {
    // Fixed 30-second delay regardless of attempt count.
    std::time::Duration::from_secs(30)
}
}

Idempotency Keys

Provide idempotency_key() to prevent duplicate jobs when the same event fires more than once. Enqueue skips insertion when a pending or claimed row with the same (job_type, idempotency_key) already exists:

#![allow(unused)]
fn main() {
impl Job for SendInvoice {
    fn idempotency_key(&self) -> Option<String> {
        Some(format!("send-invoice-{}", self.invoice_id))
    }

    async fn handle(&self) -> Result<(), Error> {
        // Will only run once per invoice_id even if dispatched multiple times.
        Ok(())
    }
}
}

Dispatching Jobs

Basic Dispatch

#![allow(unused)]
fn main() {
use crate::jobs::ProcessPayment;

ProcessPayment {
    order_id: 123,
    amount: 99.99,
}
.dispatch()
.await?;
}

With Delay

#![allow(unused)]
fn main() {
use std::time::Duration;

ProcessPayment { order_id: 123, amount: 99.99 }
    .delay(Duration::from_secs(300))  // Run after 5 minutes
    .dispatch()
    .await?;
}

To Specific Queue

#![allow(unused)]
fn main() {
ProcessPayment { order_id: 123, amount: 99.99 }
    .on_queue("high-priority")
    .dispatch()
    .await?;
}

Combining Options

#![allow(unused)]
fn main() {
ProcessPayment { order_id: 123, amount: 99.99 }
    .delay(Duration::from_secs(60))
    .on_queue("payments")
    .dispatch()
    .await?;
}

WorkerLoop Configuration

The framework creates a WorkerLoop with WorkerConfig::default() when job types are registered. Override the configuration by calling WorkerLoop::new(config) directly if you need custom settings.

#![allow(unused)]
fn main() {
use ferro::queue::{WorkerConfig, WorkerLoop};
use std::time::Duration;

let config = WorkerConfig {
    queues: vec!["high-priority".into(), "default".into()],
    max_jobs: 20,
    sleep_duration: Duration::from_millis(500),
    visibility_timeout: Duration::from_secs(300), // 5 min default
    ..Default::default()
};
}

CPU-Heavy Jobs

The WorkerLoop runs on the async executor. Jobs that do CPU-bound work (PDF rendering, image processing, compression) must wrap that work in tokio::task::spawn_blocking to avoid starving the executor of threads and blocking other jobs from running:

#![allow(unused)]
fn main() {
use ferro::queue::{Job, Error, async_trait};

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct RenderDocumentPdfJob {
    pub document_id: i64,
}

#[async_trait]
impl Job for RenderDocumentPdfJob {
    async fn handle(&self) -> Result<(), Error> {
        let document_id = self.document_id;

        // spawn_blocking moves CPU work off the async executor thread pool.
        tokio::task::spawn_blocking(move || {
            // CPU-intensive PDF rendering here...
            render_pdf(document_id)
        })
        .await
        .map_err(|e| Error::custom(format!("spawn_blocking join: {e}")))?
        .map_err(|e| Error::custom(format!("render_pdf: {e}")))
    }
}

fn render_pdf(_document_id: i64) -> Result<(), String> {
    // synchronous rendering work
    Ok(())
}
}

This applies to any job doing significant CPU work: document rendering, image resizing, compression, or large in-memory data transformations.

Error Handling

Automatic Retries

Failed jobs are automatically retried based on max_retries() and retry_delay(). After all retries are exhausted, the job is parked as failed with the error message recorded:

#![allow(unused)]
fn main() {
impl Job for ProcessPayment {
    fn max_retries(&self) -> u32 {
        5
    }

    async fn failed(&self, error: &Error) {
        tracing::error!(
            order_id = self.order_id,
            error = %error,
            "Payment processing permanently failed"
        );
        // Notify, update order status, etc.
    }
}
}

Stuck Job Reaper

The worker runs a reaper before each claim cycle. Jobs that have been claimed for longer than the visibility_timeout (default 5 min) are:

• Reset to pending with attempts + 1 if they have retries remaining
• Parked as failed if they have exhausted max_retries

This recovers from worker crashes without any manual intervention.

Graceful Shutdown

On SIGTERM or Ctrl-C the worker stops claiming new jobs, waits for in-flight jobs to finish, and resets any claimed rows it held back to pending — those jobs will be claimed by the next worker instance.

Failed Job Inspection

Failed jobs are stored in the jobs table with status = 'failed'. Inspect them via the debug endpoint or ferro-mcp:

# Debug endpoint (requires APP_ENV=local or DEBUG_MODE=true)
curl http://localhost:3000/_ferro/queue/stats
curl http://localhost:3000/_ferro/queue/jobs

Migration Guide

The following table maps the previous external-broker API to the current DB-backed API.

Gestiscilo Consumer Migration (Phase 188)

The following job types migrate in gestiscilo Phase 188. Each keeps its Job implementation unchanged; only the registration and migration registration change:

Add Box::new(ferro_queue::CreateJobsTable) to your Migrator::migrations() list (one-time migration). The failed_jobs table (if present) can be dropped after migration — failed job history is now in jobs WHERE status='failed'.

MCP Tools

Use these tools to monitor and debug queue state during development and in running applications.

list_jobs

Returns all Job implementations found in src/jobs/, including the job struct name, max retries, and timeout configuration. Use this to audit what jobs exist before dispatching or debugging failures.

job_history

Returns recent failed job history from jobs WHERE status='failed': job name, error message, attempt count, and timestamp. Use this to diagnose jobs that are permanently failing.

queue_status

Returns current queue depth and pending job counts per queue name. Use this to check whether a queue is backed up.

Notifications

Ferro provides a Laravel-inspired multi-channel notification system. Send notifications via mail, database, Slack, and more through a unified API.

Configuration

Environment Variables

Configure notifications in your .env file:

# Mail Driver: smtp (default) or resend
MAIL_DRIVER=smtp

# SMTP Configuration (when MAIL_DRIVER=smtp)
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls

# Resend Configuration (when MAIL_DRIVER=resend)
RESEND_API_KEY=re_xxxxxxxxxxxxx

# Shared (all drivers)
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="My App"

# Slack
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz

Bootstrap Setup

In src/bootstrap.rs, initialize notifications:

#![allow(unused)]
fn main() {
use ferro::{NotificationConfig, NotificationDispatcher};

pub async fn register() {
    // ... other setup ...

    // Configure notifications from environment
    let config = NotificationConfig::from_env();
    NotificationDispatcher::configure(config);
}
}

Manual Configuration

#![allow(unused)]
fn main() {
use ferro::{NotificationConfig, MailConfig, NotificationDispatcher};

// SMTP (default)
let config = NotificationConfig::new()
    .mail(
        MailConfig::new("smtp.example.com", 587, "noreply@example.com")
            .credentials("user", "pass")
            .from_name("My App")
    )
    .slack_webhook("https://hooks.slack.com/services/...");

NotificationDispatcher::configure(config);

// Resend
let config = NotificationConfig::new()
    .mail(
        MailConfig::resend("re_xxxxxxxxxxxxx", "noreply@example.com")
            .from_name("My App")
    );

NotificationDispatcher::configure(config);
}

Creating Notifications

Using the CLI

Generate a new notification:

ferro make:notification OrderShipped

This creates src/notifications/order_shipped.rs:

#![allow(unused)]
fn main() {
use ferro::{Notification, Channel, MailMessage};

pub struct OrderShipped {
    pub order_id: i64,
    pub tracking_number: String,
}

impl Notification for OrderShipped {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Mail]
    }

    fn to_mail(&self) -> Option<MailMessage> {
        Some(MailMessage::new()
            .subject("Your order has shipped!")
            .body(format!("Tracking: {}", self.tracking_number)))
    }
}
}

Notification Trait Methods

Making Entities Notifiable

Implement Notifiable on your User model:

#![allow(unused)]
fn main() {
use ferro::{Notifiable, Channel, async_trait};

pub struct User {
    pub id: i64,
    pub email: String,
    pub slack_webhook: Option<String>,
}

impl Notifiable for User {
    fn route_notification_for(&self, channel: Channel) -> Option<String> {
        match channel {
            Channel::Mail => Some(self.email.clone()),
            Channel::Database => Some(self.id.to_string()),
            Channel::Slack => self.slack_webhook.clone(),
            _ => None,
        }
    }

    fn notifiable_id(&self) -> String {
        self.id.to_string()
    }
}
}

Notifiable Trait Methods

Sending Notifications

Basic Usage

#![allow(unused)]
fn main() {
use crate::notifications::OrderShipped;

// In a controller or service
let user = User::find(user_id).await?;
user.notify(OrderShipped {
    order_id: 123,
    tracking_number: "ABC123".into(),
}).await?;
}

Available Channels

Mail Channel

Send emails via SMTP or Resend:

#![allow(unused)]
fn main() {
impl Notification for WelcomeEmail {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Mail]
    }

    fn to_mail(&self) -> Option<MailMessage> {
        Some(MailMessage::new()
            .subject("Welcome to Our Platform")
            .body("Thanks for signing up!")
            .html("<h1>Welcome!</h1><p>Thanks for signing up!</p>")
            .cc("admin@example.com")
            .bcc("archive@example.com")
            .reply_to("support@example.com"))
    }
}
}

MailMessage Methods

Database Channel

Store notifications for in-app display:

#![allow(unused)]
fn main() {
use ferro::{Notification, Channel, DatabaseMessage};

impl Notification for OrderStatusChanged {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Database]
    }

    fn to_database(&self) -> Option<DatabaseMessage> {
        Some(DatabaseMessage::new("order_status_changed")
            .data("order_id", self.order_id)
            .data("status", &self.status)
            .data("message", format!("Order #{} is now {}", self.order_id, self.status)))
    }
}
}

DatabaseMessage Methods

Slack Channel

Send Slack webhook notifications:

#![allow(unused)]
fn main() {
use ferro::{Notification, Channel, SlackMessage, SlackAttachment};

impl Notification for DeploymentComplete {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Slack]
    }

    fn to_slack(&self) -> Option<SlackMessage> {
        Some(SlackMessage::new("Deployment completed successfully!")
            .channel("#deployments")
            .username("Deploy Bot")
            .icon_emoji(":rocket:")
            .attachment(
                SlackAttachment::new()
                    .color("good")
                    .title("Deployment Details")
                    .field("Environment", &self.environment, true)
                    .field("Version", &self.version, true)
                    .footer("Deployed by CI/CD")
            ))
    }
}
}

SlackMessage Methods

SlackAttachment Methods

Multi-Channel Notifications

Send to multiple channels at once:

#![allow(unused)]
fn main() {
impl Notification for OrderPlaced {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Mail, Channel::Database, Channel::Slack]
    }

    fn to_mail(&self) -> Option<MailMessage> {
        Some(MailMessage::new()
            .subject("Order Confirmation")
            .body(format!("Order #{} placed successfully", self.order_id)))
    }

    fn to_database(&self) -> Option<DatabaseMessage> {
        Some(DatabaseMessage::new("order_placed")
            .data("order_id", self.order_id)
            .data("total", self.total))
    }

    fn to_slack(&self) -> Option<SlackMessage> {
        Some(SlackMessage::new(format!("New order #{} for ${:.2}", self.order_id, self.total)))
    }
}
}

Example: Complete Notification

#![allow(unused)]
fn main() {
// notifications/order_shipped.rs
use ferro::{Notification, Channel, MailMessage, DatabaseMessage, SlackMessage, SlackAttachment};

pub struct OrderShipped {
    pub order_id: i64,
    pub tracking_number: String,
    pub carrier: String,
    pub estimated_delivery: String,
}

impl Notification for OrderShipped {
    fn via(&self) -> Vec<Channel> {
        vec![Channel::Mail, Channel::Database, Channel::Slack]
    }

    fn to_mail(&self) -> Option<MailMessage> {
        Some(MailMessage::new()
            .subject(format!("Order #{} has shipped!", self.order_id))
            .html(format!(r#"
                <h1>Your order is on its way!</h1>
                <p>Order #{} has been shipped via {}.</p>
                <p><strong>Tracking:</strong> {}</p>
                <p><strong>Estimated Delivery:</strong> {}</p>
            "#, self.order_id, self.carrier, self.tracking_number, self.estimated_delivery)))
    }

    fn to_database(&self) -> Option<DatabaseMessage> {
        Some(DatabaseMessage::new("order_shipped")
            .data("order_id", self.order_id)
            .data("tracking_number", &self.tracking_number)
            .data("carrier", &self.carrier))
    }

    fn to_slack(&self) -> Option<SlackMessage> {
        Some(SlackMessage::new("Order shipped!")
            .attachment(
                SlackAttachment::new()
                    .color("#36a64f")
                    .title(format!("Order #{}", self.order_id))
                    .field("Carrier", &self.carrier, true)
                    .field("Tracking", &self.tracking_number, true)
                    .field("ETA", &self.estimated_delivery, false)
            ))
    }
}

// Usage in controller
let user = User::find(order.user_id).await?;
user.notify(OrderShipped {
    order_id: order.id,
    tracking_number: "1Z999AA10123456784".into(),
    carrier: "UPS".into(),
    estimated_delivery: "January 15, 2026".into(),
}).await?;
}

Environment Variables Reference

Best Practices

1. Use descriptive notification names - OrderShipped not Notification1
2. Include all needed data - Pass everything the notification needs
3. Keep notifications focused - One notification per event
4. Use database for in-app - Combine with UI notification center
5. Handle failures gracefully - Log errors, don't crash on send failures
6. Test notifications - Verify each channel works in development

MCP Tools

Use code_templates with the notifications category to generate starter code for new notification classes without looking up the API.

code_templates

Returns ready-to-use code snippets for common notification patterns. Pass category: "notifications" to get templates for mail, database, and Slack channels, along with the Notifiable trait implementation. Useful when scaffolding a new notification type quickly.

WhatsApp Channel

Send transactional notifications via the WhatsApp Cloud API (Meta). The WhatsApp adapter delegates to ferro-whatsapp, which owns its global state via the static WhatsApp::init facade.

Setup

1. Initialize ferro-whatsapp once at app startup (typically in bootstrap.rs):

   #![allow(unused)]
   fn main() {
   use ferro_whatsapp::{WhatsApp, WhatsAppConfig};
   
   let wa_config = WhatsAppConfig::from_env(Box::new(|phone| {
       // phone-validation hook — your allowlist or regex check
       phone.starts_with("39")
   })).expect("WHATSAPP_* env vars not set");
   WhatsApp::init(wa_config);
   }

2. Enable the channel in NotificationConfig:

   #![allow(unused)]
   fn main() {
   use ferro::{NotificationConfig, NotificationDispatcher};
   
   let config = NotificationConfig::from_env()    // reads WHATSAPP_ENABLED
       .with_whatsapp_enabled(true);              // or set programmatically
   NotificationDispatcher::configure(config);
   }

   Default is false. When disabled, the dispatcher emits a structured "channel not configured" log and returns Ok(()) — ferro-whatsapp is never touched, so WhatsApp::init is not required.

3. Implement Notifiable to provide the recipient phone:

   #![allow(unused)]
   fn main() {
   use ferro::{Notifiable, NotificationChannel};
   
   impl Notifiable for User {
       fn route_notification_for(&self, channel: NotificationChannel) -> Option<String> {
           match channel {
               NotificationChannel::WhatsApp => self.phone.clone(),
               // ... other channels ...
               _ => None,
           }
       }
   }
   }

4. Implement Notification::to_whatsapp:

   #![allow(unused)]
   fn main() {
   use ferro::{Notification, NotificationChannel, WhatsAppMessage};
   
   impl Notification for OrderShipped {
       fn via(&self) -> Vec<NotificationChannel> {
           vec![NotificationChannel::WhatsApp]
       }
   
       fn to_whatsapp(&self) -> Option<WhatsAppMessage> {
           Some(WhatsAppMessage::text(format!(
               "Your order #{} has shipped — tracking {}",
               self.order_id, self.tracking
           )))
       }
   }
   }

   For approved Meta templates use WhatsAppMessage::template(name, language, parameters).

In-App (SSE) Channel

Real-time in-app notifications dispatch through two legs in sequence:

1. Persistence — written via your DatabaseNotificationStore implementation
2. Real-time fanout — published via ferro-broadcast to channel user.{notifiable_id} with event Notification.{notification_type}

If either leg fails the dispatch returns an error — there is no partial-success silent fallback. The persistence-first ordering ensures the broadcaster can replay missed events from the store on client reconnect.

Setup

#![allow(unused)]
fn main() {
use std::sync::Arc;
use ferro::{Broadcaster, InAppConfig, NotificationConfig, NotificationDispatcher};

let broker = Arc::new(Broadcaster::new());
let store: Arc<dyn ferro::DatabaseNotificationStore> = Arc::new(MyDatabaseStore::new());

let config = NotificationConfig::from_env()
    .with_in_app(InAppConfig {
        broker: broker.clone(),
        store: store.clone(),
    })
    .with_database_store(store);    // shared with Channel::Database — same Arc

NotificationDispatcher::configure(config);
}

Authorization note: The InApp adapter publishes to user.{id} channels. You must configure ferro-broadcast's ChannelAuthorizer to enforce who can subscribe to those channels. See Broadcasting for the auth setup.

Implementing Notifications

#![allow(unused)]
fn main() {
use ferro::{InAppMessage, InAppSeverity, Notification, NotificationChannel};

impl Notification for OrderShipped {
    fn via(&self) -> Vec<NotificationChannel> {
        vec![NotificationChannel::InApp]
    }

    fn to_in_app(&self) -> Option<InAppMessage> {
        Some(
            InAppMessage::new("OrderShipped")
                .data(serde_json::json!({
                    "order_id": self.order_id,
                    "tracking": self.tracking,
                }))
                .severity(InAppSeverity::Success),
        )
    }
}
}

Mail Attachments

MailMessage::attachment(filename, content_type, bytes) adds an inline binary attachment. The builder is fallible — it returns Err(Error::AttachmentTooLarge) when bytes.len() exceeds the 25 MB per-attachment cap. Multiple calls accumulate.

#![allow(unused)]
fn main() {
use ferro::MailMessage;

let pdf_bytes: Vec<u8> = std::fs::read("/tmp/invoice.pdf")?;

let mail = MailMessage::new()
    .subject("Your invoice is attached")
    .body("Hi, please find your invoice attached.")
    .attachment("invoice.pdf", "application/pdf", pdf_bytes)?;
}

Attachments work on both mail drivers:

• SMTP (lettre): ferro-notifications builds a multipart/mixed email with one SinglePart per attachment when attachments is non-empty. When empty, the existing single-part path is used (zero regression for non-attachment emails).
• Resend (HTTP API): attachments are base64-encoded and sent as attachments: [{ filename, content }] in the JSON payload. Resend has its own 40 MB total-per-email cap which the framework does NOT enforce — Resend surfaces it via API error.

The 25 MB cap is per-attachment and enforced before any allocation past 25 MB:

#![allow(unused)]
fn main() {
let huge: Vec<u8> = vec![0; 30 * 1024 * 1024];
match MailMessage::new().attachment("big.bin", "application/octet-stream", huge) {
    Err(ferro::NotificationError::AttachmentTooLarge { filename, size, limit }) => {
        eprintln!("Rejected '{filename}': {size} bytes exceeds {limit}-byte limit");
    }
    _ => unreachable!(),
}
}

Broadcasting

Ferro provides a WebSocket broadcasting system for real-time communication. Push events to connected clients through public, private, and presence channels. The server handles WebSocket connections at /_ferro/ws with automatic heartbeat, timeout, and subscription management.

Setup

Registering the Broadcaster

In bootstrap.rs, create a Broadcaster and register it as a singleton. The broadcaster manages all connected clients and channel subscriptions.

#![allow(unused)]
fn main() {
use ferro::{Broadcaster, BroadcastConfig, App};

pub async fn register() {
    let broadcaster = Broadcaster::with_config(BroadcastConfig::from_env());
    App::singleton(broadcaster);
}
}

The framework automatically intercepts WebSocket upgrade requests to /_ferro/ws when a Broadcaster is registered. No additional route configuration is needed for the WebSocket endpoint itself.

Manual Configuration

Instead of reading from environment variables, configure the broadcaster directly:

#![allow(unused)]
fn main() {
use ferro::{Broadcaster, BroadcastConfig};
use std::time::Duration;

let config = BroadcastConfig::new()
    .max_subscribers_per_channel(100)
    .max_channels(50)
    .heartbeat_interval(Duration::from_secs(30))
    .client_timeout(Duration::from_secs(60))
    .allow_client_events(true);

let broadcaster = Broadcaster::with_config(config);
}

Channel Types

Channel type is determined by the channel name prefix:

#![allow(unused)]
fn main() {
// Public - anyone can subscribe
"orders"
"notifications"

// Private - requires authorization
"private-orders.123"
"private-user.456"

// Presence - tracks online members
"presence-chat.1"
"presence-room.gaming"
}

Channel Authorization

Private and presence channels require an authorizer. Implement the ChannelAuthorizer trait and attach it to the broadcaster.

Implementing a Channel Authorizer

#![allow(unused)]
fn main() {
use ferro::{AuthData, ChannelAuthorizer};

pub struct AppChannelAuth;

#[async_trait::async_trait]
impl ChannelAuthorizer for AppChannelAuth {
    async fn authorize(&self, data: &AuthData) -> bool {
        // data.socket_id   - client's WebSocket connection ID
        // data.channel     - channel name being requested
        // data.auth_token  - user ID from session auth (set by broadcasting_auth)

        match data.channel.as_str() {
            c if c.starts_with("private-orders.") => {
                let order_id: i64 = c
                    .strip_prefix("private-orders.")
                    .and_then(|s| s.parse().ok())
                    .unwrap_or(0);
                // Check if user owns this order
                check_order_ownership(data.auth_token.as_deref(), order_id).await
            }
            c if c.starts_with("presence-chat.") => {
                // Allow all authenticated users to join chat
                data.auth_token.is_some()
            }
            _ => false,
        }
    }
}
}

Registering the Authorizer

Chain .with_authorizer() when creating the broadcaster:

#![allow(unused)]
fn main() {
let broadcaster = Broadcaster::with_config(BroadcastConfig::from_env())
    .with_authorizer(AppChannelAuth);
App::singleton(broadcaster);
}

Auth Endpoint

Clients connecting to private or presence channels must authenticate through an HTTP endpoint. Ferro provides broadcasting_auth, a handler that bridges session authentication with channel authorization.

Registering the Auth Route

#![allow(unused)]
fn main() {
use ferro::broadcasting_auth;

Route::post("/broadcasting/auth", broadcasting_auth)
    .middleware(SessionAuthMiddleware);
}

The handler:

1. Verifies the user is authenticated via session (Auth::id())
2. Receives channel_name and socket_id from the client
3. Calls Broadcaster::check_auth() with the user's ID as the auth token
4. Returns 200 with auth confirmation if authorized, 401 if unauthenticated, 403 if unauthorized
5. For presence channels, includes channel_data with user_id

Private Channel Auth Flow

The full authorization flow for private and presence channels:

1. Client connects to ws://host/_ferro/ws and receives a socket_id
2. Client sends HTTP POST to /broadcasting/auth with channel_name and socket_id
3. Server validates session auth and calls the registered ChannelAuthorizer
4. If authorized, client receives auth confirmation
5. Client sends a subscribe message over WebSocket with the auth token
6. Server subscribes the client to the channel

Broadcasting from Handlers

Fluent Builder API

The Broadcast builder provides a chainable interface for sending events:

#![allow(unused)]
fn main() {
use ferro::{Broadcast, Broadcaster, App};
use std::sync::Arc;

#[handler]
pub async fn update_order(req: Request, id: Path<i32>) -> Response {
    let db = req.db();
    let order = update_order_in_db(db, *id).await?;

    let broadcaster = App::get::<Broadcaster>().ok_or_else(|| HttpResponse::internal_server_error())?;
    let broadcast = Broadcast::new(Arc::new(broadcaster));

    broadcast
        .channel(&format!("orders.{}", id))
        .event("OrderUpdated")
        .data(&order)
        .send()
        .await
        .ok();

    Ok(json!(order))
}
}

Excluding the Sender

When a client triggers an action, exclude them from the broadcast to avoid echo:

#![allow(unused)]
fn main() {
broadcast
    .channel("chat.1")
    .event("NewMessage")
    .data(&message)
    .except(&socket_id)
    .send()
    .await?;
}

Direct Broadcaster API

For simpler cases, call broadcast() or broadcast_except() directly:

#![allow(unused)]
fn main() {
let broadcaster = App::get::<Broadcaster>().expect("Broadcaster not registered");

// Broadcast to all subscribers
broadcaster.broadcast("orders", "OrderCreated", &order).await?;

// Broadcast excluding a specific client
broadcaster
    .broadcast_except("chat.1", "MessageSent", &msg, &sender_socket_id)
    .await?;
}

Client Connection

Clients connect via standard WebSocket to the /_ferro/ws endpoint. All messages use JSON.

JavaScript Client

const ws = new WebSocket('ws://localhost:8080/_ferro/ws');

ws.onopen = () => {
    console.log('Connected');
};

ws.onmessage = (event) => {
    const msg = JSON.parse(event.data);

    switch (msg.type) {
        case 'connected':
            console.log('Socket ID:', msg.socket_id);
            // Subscribe to public channel
            ws.send(JSON.stringify({
                type: 'subscribe',
                channel: 'orders'
            }));
            break;

        case 'subscribed':
            console.log('Subscribed to:', msg.channel);
            break;

        case 'subscription_error':
            console.error('Failed:', msg.channel, msg.error);
            break;

        case 'event':
            console.log('Event:', msg.event, msg.data);
            break;

        case 'member_added':
            console.log('Joined:', msg.user_id, msg.user_info);
            break;

        case 'member_removed':
            console.log('Left:', msg.user_id);
            break;

        case 'pong':
            // Keepalive response
            break;

        case 'error':
            console.error('Error:', msg.message);
            break;
    }
};

Subscribing to Private Channels

Private channels require an auth token. The client first authenticates via the HTTP endpoint, then includes the token in the subscribe message:

async function subscribePrivate(ws, socketId, channel) {
    // Step 1: Get auth token from server
    const res = await fetch('/broadcasting/auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include', // Send session cookie
        body: JSON.stringify({
            channel_name: channel,
            socket_id: socketId
        })
    });

    if (!res.ok) {
        throw new Error('Authorization failed');
    }

    const data = await res.json();

    // Step 2: Subscribe with auth token
    ws.send(JSON.stringify({
        type: 'subscribe',
        channel: channel,
        auth: data.auth
    }));
}

Whisper (Client Events)

Whisper messages are client-to-client events forwarded through the server. They are useful for ephemeral state like typing indicators and cursor positions. The sender is excluded from receiving the message.

// Send a whisper
ws.send(JSON.stringify({
    type: 'whisper',
    channel: 'private-chat.1',
    event: 'typing',
    data: { name: 'Alice' }
}));

Whisper requires allow_client_events: true in configuration (enabled by default) and the sender must be subscribed to the channel.

Message Protocol

Client to Server

All client messages are JSON with a type field:

// Subscribe to a channel
{"type": "subscribe", "channel": "orders"}

// Subscribe to a private channel with auth
{"type": "subscribe", "channel": "private-orders.1", "auth": "token"}

// Unsubscribe
{"type": "unsubscribe", "channel": "orders"}

// Whisper (client event)
{"type": "whisper", "channel": "chat", "event": "typing", "data": {"name": "Alice"}}

// Keepalive ping
{"type": "ping"}

Server to Client

// Connection established
{"type": "connected", "socket_id": "uuid-v4-here"}

// Subscription confirmed
{"type": "subscribed", "channel": "orders"}

// Subscription failed
{"type": "subscription_error", "channel": "private-secret", "error": "Authorization required"}

// Unsubscribed
{"type": "unsubscribed", "channel": "orders"}

// Broadcast event
{"type": "event", "event": "OrderUpdated", "channel": "orders", "data": {"id": 1}}

// Presence member joined
{"type": "member_added", "channel": "presence-chat.1", "user_id": "42", "user_info": {"name": "Alice"}}

// Presence member left
{"type": "member_removed", "channel": "presence-chat.1", "user_id": "42"}

// Keepalive response
{"type": "pong"}

// Error
{"type": "error", "message": "Invalid message format"}

Presence Channels

Presence channels extend private channels with member tracking. When users join or leave, events are automatically broadcast to all channel members.

Subscribing with Member Info

On the server side, presence subscriptions include member metadata:

#![allow(unused)]
fn main() {
use ferro::PresenceMember;

let member = PresenceMember::new(socket_id, user_id)
    .with_info(serde_json::json!({
        "name": user.name,
        "avatar": user.avatar_url,
    }));

broadcaster
    .subscribe(&socket_id, "presence-chat.1", Some(&auth_token), Some(member))
    .await?;
}

Member Events

The server automatically broadcasts when members join or leave:

• member_added -- includes user_id and user_info
• member_removed -- includes user_id

Querying Channel Members

#![allow(unused)]
fn main() {
if let Some(channel) = broadcaster.get_channel("presence-chat.1") {
    for member in channel.get_members() {
        println!("User {} is online", member.user_id);
    }
}
}

Configuration

Environment Variables

Connection Management

The WebSocket connection handler runs a tokio::select! loop that manages:

• Incoming frames -- client messages dispatched to the broadcaster
• Server messages -- broadcast events forwarded to the client
• Heartbeat -- periodic ping/pong to detect stale connections

Clients that exceed BROADCAST_CLIENT_TIMEOUT without activity are disconnected. The server sends Close frames on clean shutdown and removes the client from all subscribed channels.

Monitoring

#![allow(unused)]
fn main() {
let broadcaster = App::get::<Broadcaster>().expect("Broadcaster not registered");

// Connection stats
let clients = broadcaster.client_count();
let channels = broadcaster.channel_count();

// Channel details
if let Some(channel) = broadcaster.get_channel("orders") {
    println!("{} subscribers", channel.subscriber_count());
}

# MCP Tools

Use `list_broadcast_channels` to inspect active WebSocket channels at runtime.

## `list_broadcast_channels`

Returns all currently active broadcast channels with subscriber count, channel type (public, private, presence), and connected client IDs. Use this to verify that clients have subscribed to the expected channels or to diagnose subscription failures.
}

Storage

Ferro provides a unified file storage abstraction inspired by Laravel's filesystem. Work with local files, memory storage, and cloud providers through a consistent API.

Configuration

Environment Variables

Configure storage in your .env file:

# Default disk (local, public, or s3)
FILESYSTEM_DISK=local

# Local disk settings
FILESYSTEM_LOCAL_ROOT=./storage
FILESYSTEM_LOCAL_URL=

# Public disk settings (for web-accessible files)
FILESYSTEM_PUBLIC_ROOT=./storage/public
FILESYSTEM_PUBLIC_URL=/storage

# S3 disk settings (requires s3 feature)
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=your-bucket
AWS_URL=https://your-bucket.s3.amazonaws.com

Bootstrap Setup

In src/bootstrap.rs, configure storage:

#![allow(unused)]
fn main() {
use ferro::{App, Storage, StorageConfig};
use std::sync::Arc;

pub async fn register() {
    // ... other setup ...

    // Create storage with environment config
    let config = StorageConfig::from_env();
    let storage = Arc::new(Storage::with_storage_config(config));

    // Store in app state for handlers to access
    App::set_storage(storage);
}
}

Manual Configuration

#![allow(unused)]
fn main() {
use ferro::{Storage, StorageConfig, DiskConfig};

let config = StorageConfig::new("local")
    .disk("local", DiskConfig::local("./storage"))
    .disk("public", DiskConfig::local("./storage/public").with_url("/storage"))
    .disk("uploads", DiskConfig::local("./uploads").with_url("/uploads"));

let storage = Storage::with_storage_config(config);
}

Basic Usage

Storing Files

#![allow(unused)]
fn main() {
use ferro::Storage;

// Store string content
storage.put("documents/report.txt", "Report content").await?;

// Store bytes
storage.put("images/photo.jpg", image_bytes).await?;

// Store with visibility options
use ferro::PutOptions;

storage.put_with_options(
    "private/secret.txt",
    "secret content",
    PutOptions::new().visibility(Visibility::Private),
).await?;
}

Retrieving Files

#![allow(unused)]
fn main() {
// Get as bytes
let contents = storage.get("documents/report.txt").await?;

// Get as string
let text = storage.get_string("documents/report.txt").await?;

// Check if file exists
if storage.exists("documents/report.txt").await? {
    println!("File exists!");
}
}

Deleting Files

#![allow(unused)]
fn main() {
// Delete a single file
storage.delete("temp/cache.txt").await?;

// Delete a directory and all contents
storage.disk("local")?.delete_directory("temp").await?;
}

Copying and Moving

#![allow(unused)]
fn main() {
// Copy a file
storage.copy("original.txt", "backup/original.txt").await?;

// Move/rename a file
storage.rename("old-name.txt", "new-name.txt").await?;
}

Multiple Disks

Switching Disks

#![allow(unused)]
fn main() {
// Use the default disk
storage.put("file.txt", "content").await?;

// Use a specific disk
let public_disk = storage.disk("public")?;
public_disk.put("images/logo.png", logo_bytes).await?;

// Get file from specific disk
let file = storage.disk("uploads")?.get("user-upload.pdf").await?;
}

Disk Configuration

Each disk is configured independently:

#![allow(unused)]
fn main() {
use ferro::{StorageConfig, DiskConfig};

let config = StorageConfig::new("local")
    // Main storage disk
    .disk("local", DiskConfig::local("./storage/app"))
    // Publicly accessible files
    .disk("public", DiskConfig::local("./storage/public").with_url("/storage"))
    // Temporary files
    .disk("temp", DiskConfig::local("/tmp/app"))
    // Memory disk for testing
    .disk("testing", DiskConfig::memory());
}

File URLs

Public URLs

#![allow(unused)]
fn main() {
// Get the public URL for a file
let url = storage.disk("public")?.url("images/logo.png").await?;
// Returns: /storage/images/logo.png

// With a custom URL base
let config = DiskConfig::local("./uploads")
    .with_url("https://cdn.example.com/uploads");
// url() returns: https://cdn.example.com/uploads/images/logo.png
}

Temporary URLs

For files that need time-limited access:

#![allow(unused)]
fn main() {
use std::time::Duration;

// Get a temporary URL (useful for S3 presigned URLs)
let disk = storage.disk("s3")?;
let temp_url = disk.temporary_url(
    "private/document.pdf",
    Duration::from_secs(3600), // 1 hour
).await?;
}

File Information

Metadata

#![allow(unused)]
fn main() {
let disk = storage.disk("local")?;

// Get file size
let size = disk.size("document.pdf").await?;
println!("File size: {} bytes", size);

// Get full metadata
let metadata = disk.metadata("document.pdf").await?;
println!("Path: {}", metadata.path);
println!("Size: {}", metadata.size);
println!("MIME type: {:?}", metadata.mime_type);
println!("Last modified: {:?}", metadata.last_modified);
}

Visibility

#![allow(unused)]
fn main() {
use ferro::{PutOptions, Visibility};

// Store with private visibility
storage.put_with_options(
    "private/data.json",
    json_data,
    PutOptions::new().visibility(Visibility::Private),
).await?;

// Store with public visibility
storage.put_with_options(
    "public/image.jpg",
    image_data,
    PutOptions::new().visibility(Visibility::Public),
).await?;
}

Directory Operations

Listing Files

#![allow(unused)]
fn main() {
let disk = storage.disk("local")?;

// List files in a directory (non-recursive)
let files = disk.files("documents").await?;
for file in files {
    println!("File: {}", file);
}

// List all files recursively
let all_files = disk.all_files("documents").await?;
for file in all_files {
    println!("File: {}", file);
}

// List directories
let dirs = disk.directories("documents").await?;
for dir in dirs {
    println!("Directory: {}", dir);
}
}

Creating Directories

#![allow(unused)]
fn main() {
let disk = storage.disk("local")?;

// Create a directory
disk.make_directory("uploads/2024/01").await?;

// Delete a directory and contents
disk.delete_directory("temp").await?;
}

Available Drivers

Local Driver

Stores files on the local filesystem:

#![allow(unused)]
fn main() {
let config = DiskConfig::local("./storage")
    .with_url("https://example.com/storage");
}

Memory Driver

Stores files in memory (useful for testing):

#![allow(unused)]
fn main() {
let config = DiskConfig::memory()
    .with_url("https://cdn.example.com");
}

S3 Driver

Enable the s3 feature:

[dependencies]
ferro = { version = "0.1", features = ["s3"] }

Example: File Upload Handler

#![allow(unused)]
fn main() {
use ferro::{Request, Response, Storage};
use std::sync::Arc;

async fn upload_file(
    request: Request,
    storage: Arc<Storage>,
) -> Response {
    // Get uploaded file from multipart form
    let file = request.file("document")?;

    // Generate unique filename
    let filename = format!(
        "uploads/{}/{}",
        chrono::Utc::now().format("%Y/%m/%d"),
        file.name()
    );

    // Store the file
    storage.disk("public")?
        .put(&filename, file.bytes())
        .await?;

    // Get the public URL
    let url = storage.disk("public")?
        .url(&filename)
        .await?;

    Response::json(&serde_json::json!({
        "success": true,
        "url": url,
    }))
}
}

Example: Avatar Upload with Validation

#![allow(unused)]
fn main() {
use ferro::{Request, Response, Storage, PutOptions, Visibility};
use std::sync::Arc;

async fn upload_avatar(
    request: Request,
    storage: Arc<Storage>,
    user_id: i64,
) -> Response {
    let file = request.file("avatar")?;

    // Validate file type
    let allowed_types = ["image/jpeg", "image/png", "image/webp"];
    if !allowed_types.contains(&file.content_type()) {
        return Response::bad_request("Invalid file type");
    }

    // Validate file size (max 5MB)
    if file.size() > 5 * 1024 * 1024 {
        return Response::bad_request("File too large");
    }

    // Delete old avatar if exists
    let old_path = format!("avatars/{}.jpg", user_id);
    if storage.exists(&old_path).await? {
        storage.delete(&old_path).await?;
    }

    // Store new avatar
    let path = format!("avatars/{}.{}", user_id, file.extension());
    storage.disk("public")?
        .put_with_options(
            &path,
            file.bytes(),
            PutOptions::new().visibility(Visibility::Public),
        )
        .await?;

    let url = storage.disk("public")?.url(&path).await?;

    Response::json(&serde_json::json!({
        "avatar_url": url,
    }))
}
}

CDN

CDN Edge URLs

Configure a CDN base URL for a disk to serve stored files from an edge node rather than the storage origin. The primary configuration surface is the provider-agnostic quartet:

# Provider-agnostic CDN quartet (preferred)
# CDN_PROVIDER: none | digitalocean | bunny | cloudflare
CDN_URL=https://cdn.example.com
CDN_PROVIDER=digitalocean
CDN_PURGE_TOKEN=your-api-token
CDN_PURGE_ZONE=your-cdn-endpoint-id

CDN_URL drives Disk::cdn_url(). CDN_PROVIDER selects the purge adapter; CDN_PROVIDER=none makes purge() a logged no-op. CDN_URL (display) and CDN_PROVIDER (purge) are independent — a deployment can serve assets through a CDN URL with no purge provider configured.

Deprecated fallbacks (one release window): the following legacy env vars are still read as fallbacks and emit a tracing::warn! deprecation notice on use. Migrate to the quartet.

Or set it programmatically:

#![allow(unused)]
fn main() {
use ferro_storage::DiskConfig;

let config = DiskConfig::local("./storage/public")
    .with_url("https://origin.example.com/storage")
    .with_cdn_url("https://cdn.example.com/storage");
}

Disk::cdn_url(path) and Storage::cdn_url(path) return the CDN edge URL when a CDN base is configured, or fall back to the origin url() otherwise:

#![allow(unused)]
fn main() {
// With CDN configured — returns "https://cdn.example.com/storage/images/logo.png"
let url = storage.disk("public")?.cdn_url("images/logo.png").await?;

// Without CDN configured — falls back to origin URL
let url = storage.disk("local")?.cdn_url("images/logo.png").await?;
}

The CDN URL computation is pure string composition at the facade layer — no network call is made. Double slashes are normalized: a trailing slash on the base and a leading slash on the path produce a single slash in the result.

Cache Invalidation

The PurgeApi trait abstracts CDN cache invalidation across providers:

#![allow(unused)]
fn main() {
use ferro_storage::PurgeApi;

#[async_trait]
pub trait PurgeApi: Send + Sync {
    async fn purge(&self, paths: &[String]) -> Result<(), Error>;
}
}

Paths are relative (e.g. "index.html", "assets/*"). Implementations handle batching, rate limiting, and full-URL construction internally.

DigitalOcean Spaces CDN Adapter

The DoSpacesCdn adapter is the default, batteries-included implementation. It calls the DigitalOcean CDN purge API (DELETE /v2/cdn/endpoints/{id}/cache) and encapsulates:

• Batching: at most 50 file paths per request (the DO API limit).
• Rate limiting: an internal sliding-window throttle enforces at most 5 requests per 10-second window.
• Wildcard paths: "assets/*" counts as one file slot, not an expanded set.
• Missing endpoint id: when CDN_PURGE_ZONE is unset, purge() is a logged no-op that returns Ok(()). Applications without a CDN endpoint continue to work without error.

CDN_PROVIDER=digitalocean
CDN_PURGE_ZONE=your-cdn-endpoint-id
CDN_PURGE_TOKEN=your-do-api-token

#![allow(unused)]
fn main() {
use ferro_storage::{DoSpacesCdn, DoSpacesCdnConfig, PurgeApi};

let purger = DoSpacesCdn::new(DoSpacesCdnConfig::from_env());

// Purge a set of paths after a deployment promote
purger.purge(&[
    "index.html".to_string(),
    "de/index.html".to_string(),
]).await?;
}

The DIGITALOCEAN_ACCESS_TOKEN is never written to logs. DoSpacesCdnConfig implements a hand-written Debug that prints <redacted> for the token field.

Feature-gated Adapters

Bunny CDN and Cloudflare CDN adapters are available behind optional cargo features. They are not compiled into the default dependency graph:

[dependencies]
ferro-storage = { version = "0.2", features = ["cdn-bunny"] }
# or
ferro-storage = { version = "0.2", features = ["cdn-cloudflare"] }

Bunny CDN (cdn-bunny): calls POST https://api.bunny.net/purge?url={full_url}&async=false per path with an AccessKey header. Set CDN_PROVIDER=bunny, CDN_URL, and CDN_PURGE_TOKEN (the Bunny access key).

#![allow(unused)]
fn main() {
use ferro_storage::{BunnyCdn, BunnyCdnConfig, PurgeApi};

let purger = BunnyCdn::new(BunnyCdnConfig::from_env());
purger.purge(&["index.html".to_string()]).await?;
}

Cloudflare CDN (cdn-cloudflare): calls POST /zones/{zone_id}/purge_cache with {"files": [...full_urls...]} and Bearer auth. Set CDN_PROVIDER=cloudflare, CDN_URL, CDN_PURGE_TOKEN (the CF API token), and CDN_PURGE_ZONE (the CF zone id).

#![allow(unused)]
fn main() {
use ferro_storage::{CloudflareCdn, CloudflareCdnConfig, PurgeApi};

let purger = CloudflareCdn::new(CloudflareCdnConfig::from_env());
purger.purge(&["index.html".to_string()]).await?;
}

Promote → Purge Sequence

The standard deployment workflow is a two-call sequence: promote the new deployment, then purge the affected HTML keys:

#![allow(unused)]
fn main() {
use ferro_storage::{DoSpacesCdn, DoSpacesCdnConfig, PurgeApi};

// After ferro_deployments::promote(...)
let purger = DoSpacesCdn::new(DoSpacesCdnConfig::from_env());
purger.purge(&html_keys).await?;
}

Purge policy: purge only the non-hashed HTML keys after a promote. Content-hashed asset URLs (e.g. app.a1b2c3d4.js) are immutable — their content never changes at the same URL, so purging them is unnecessary and consumes rate-limit budget. Purging * invalidates the entire CDN cache; reserve that for deliberate full-cache invalidation.

Environment Variables Reference

Best Practices

1. Use meaningful disk names - public, uploads, backups instead of disk1
2. Set appropriate visibility - Use private for sensitive files
3. Organize files by date - uploads/2024/01/file.pdf prevents directory bloat
4. Use the public disk for web assets - Images, CSS, JS that need URLs
5. Use memory driver for tests - Fast and isolated testing
6. Clean up temporary files - Delete files that are no longer needed
7. Validate uploads - Check file types and sizes before storing

MCP Tools

Use code_templates with the storage category to generate file upload and storage handler patterns.

code_templates

Returns ready-to-use code snippets for file upload handling, including multipart parsing, extension validation, and disk selection. Pass category: "storage" to get templates for single-file upload, avatar upload with validation, and temporary URL generation.

Caching

Ferro provides a unified caching API with support for multiple backends, cache tags for bulk invalidation, and the convenient "remember" pattern for lazy caching.

Configuration

Environment Variables

Configure caching in your .env file:

# Cache driver (memory or redis)
CACHE_DRIVER=memory

# Key prefix for all cache entries
CACHE_PREFIX=myapp

# Default TTL in seconds
CACHE_TTL=3600

# Memory store capacity (max entries)
CACHE_MEMORY_CAPACITY=10000

# Redis URL (required if CACHE_DRIVER=redis)
REDIS_URL=redis://127.0.0.1:6379

Bootstrap Setup

In src/bootstrap.rs, configure caching:

#![allow(unused)]
fn main() {
use ferro::{App, Cache};
use std::sync::Arc;

pub async fn register() {
    // ... other setup ...

    // Create cache from environment variables
    let cache = Arc::new(Cache::from_env().await?);

    // Store in app state for handlers to access
    App::set_cache(cache);
}
}

Manual Configuration

#![allow(unused)]
fn main() {
use ferro::{Cache, CacheConfig};
use std::time::Duration;

// In-memory cache with custom config
let config = CacheConfig::new()
    .with_ttl(Duration::from_secs(1800))
    .with_prefix("myapp");

let cache = Cache::memory().with_config(config);

// Redis cache
let cache = Cache::redis("redis://127.0.0.1:6379").await?;
}

Basic Usage

Storing Values

#![allow(unused)]
fn main() {
use std::time::Duration;

// Store a value with specific TTL
cache.put("user:1", &user, Duration::from_secs(3600)).await?;

// Store with default TTL
cache.put_default("user:1", &user).await?;

// Store forever (10 years TTL)
cache.forever("config:settings", &settings).await?;
}

Retrieving Values

#![allow(unused)]
fn main() {
// Get a value
let user: Option<User> = cache.get("user:1").await?;

if let Some(user) = user {
    println!("Found user: {}", user.name);
}

// Check if key exists
if cache.has("user:1").await? {
    println!("User is cached");
}
}

Removing Values

#![allow(unused)]
fn main() {
// Remove a single key
cache.forget("user:1").await?;

// Remove all cached values
cache.flush().await?;
}

Pull (Get and Remove)

#![allow(unused)]
fn main() {
// Get value and remove it from cache
let session: Option<Session> = cache.pull("session:abc123").await?;
}

Remember Pattern

The remember pattern retrieves a cached value or computes and caches it if missing:

#![allow(unused)]
fn main() {
use std::time::Duration;

// Get from cache or compute if missing
let users = cache.remember("users:active", Duration::from_secs(3600), || async {
    // This only runs if "users:active" is not in cache
    User::where_active().all().await
}).await?;

// Remember forever
let config = cache.remember_forever("app:config", || async {
    load_config_from_database().await
}).await?;
}

This pattern is excellent for:

• Database query results
• API responses
• Expensive computations
• Configuration that rarely changes

Cache Tags

Tags allow you to group related cache entries for bulk invalidation.

Storing with Tags

#![allow(unused)]
fn main() {
use std::time::Duration;

// Store with a single tag
cache.tags(&["users"])
    .put("user:1", &user, Duration::from_secs(3600))
    .await?;

// Store with multiple tags
cache.tags(&["users", "admins"])
    .put("admin:1", &admin, Duration::from_secs(3600))
    .await?;

// Remember with tags
let user = cache.tags(&["users"])
    .remember("user:1", Duration::from_secs(3600), || async {
        User::find(1).await
    })
    .await?;
}

Flushing Tags

#![allow(unused)]
fn main() {
// Flush all entries tagged with "users"
cache.tags(&["users"]).flush().await?;

// This removes:
// - "user:1" (tagged with ["users"])
// - "admin:1" (tagged with ["users", "admins"])
}

Tag Use Cases

#![allow(unused)]
fn main() {
// Cache user data
cache.tags(&["users", &format!("user:{}", user.id)])
    .put(&format!("user:{}", user.id), &user, ttl)
    .await?;

// Cache user's posts
cache.tags(&["posts", &format!("user:{}:posts", user.id)])
    .put(&format!("user:{}:posts", user.id), &posts, ttl)
    .await?;

// When user is updated, flush their cache
cache.tags(&[&format!("user:{}", user.id)]).flush().await?;

// When any user data changes, flush all user cache
cache.tags(&["users"]).flush().await?;
}

Atomic Operations

Increment and Decrement

#![allow(unused)]
fn main() {
// Increment a counter
let views = cache.increment("page:views", 1).await?;
println!("Page has {} views", views);

// Increment by more than 1
let score = cache.increment("player:score", 100).await?;

// Decrement
let stock = cache.decrement("product:stock", 1).await?;
}

Cache Backends

Memory Store

Fast in-memory caching backed by moka. Best for:

• Single-server deployments
• Development/testing
• Non-critical cache data

#![allow(unused)]
fn main() {
// Default capacity (10,000 entries)
let cache = Cache::memory();

// Custom capacity
let store = MemoryStore::with_capacity(50_000);
let cache = Cache::new(Arc::new(store));
}

The memory store is bounded: when capacity is reached, least-recently-used entries are evicted automatically. Each entry respects its own TTL — expired entries are never returned and are cleaned up proactively by the cache engine. Counters (increment/decrement) share the same capacity bound.

Redis Store

Distributed caching with Redis. Best for:

• Multi-server deployments
• Persistent cache (survives restarts)
• Shared cache across services

#![allow(unused)]
fn main() {
let cache = Cache::redis("redis://127.0.0.1:6379").await?;

// With authentication
let cache = Cache::redis("redis://:password@127.0.0.1:6379").await?;

// With database selection
let cache = Cache::redis("redis://127.0.0.1:6379/2").await?;
}

Enable the Redis backend in Cargo.toml:

[dependencies]
ferro = { version = "0.1", features = ["redis-backend"] }

Example: API Response Caching

#![allow(unused)]
fn main() {
use ferro::{Request, Response, Cache};
use std::sync::Arc;
use std::time::Duration;

async fn get_products(
    request: Request,
    cache: Arc<Cache>,
) -> Response {
    let category = request.param("category")?;

    // Cache key based on category
    let cache_key = format!("products:category:{}", category);

    // Get from cache or fetch from database
    let products = cache.remember(&cache_key, Duration::from_secs(300), || async {
        Product::where_category(&category).all().await
    }).await?;

    Response::json(&products)
}
}

Example: User Session Caching

#![allow(unused)]
fn main() {
use ferro::Cache;
use std::sync::Arc;
use std::time::Duration;

async fn cache_user_session(
    cache: Arc<Cache>,
    user_id: i64,
    session: &UserSession,
) -> Result<(), Error> {
    // Cache with user-specific tag for easy invalidation
    cache.tags(&["sessions", &format!("user:{}", user_id)])
        .put(
            &format!("session:{}", session.id),
            session,
            Duration::from_secs(86400), // 24 hours
        )
        .await
}

async fn invalidate_user_sessions(
    cache: Arc<Cache>,
    user_id: i64,
) -> Result<(), Error> {
    // Flush all sessions for this user
    cache.tags(&[&format!("user:{}", user_id)]).flush().await
}
}

Example: Rate Limiting with Cache

#![allow(unused)]
fn main() {
use ferro::Cache;
use std::sync::Arc;

async fn check_rate_limit(
    cache: Arc<Cache>,
    user_id: i64,
    limit: i64,
) -> Result<bool, Error> {
    let key = format!("rate_limit:user:{}", user_id);

    // Increment the counter
    let count = cache.increment(&key, 1).await?;

    // Set TTL on first request (1 minute window)
    if count == 1 {
        // Note: For production, use Redis SETEX or similar
        // This is a simplified example
    }

    Ok(count <= limit)
}
}

Environment Variables Reference

Best Practices

1. Use meaningful cache keys - user:123:profile not key1
2. Set appropriate TTLs - Balance freshness vs performance
3. Use tags for related data - Makes invalidation easier
4. Cache at the right level - Cache complete objects, not fragments
5. Handle cache misses gracefully - Always have a fallback
6. Use remember pattern - Cleaner code, less boilerplate
7. Prefix keys in production - Avoid collisions between environments
8. Monitor cache hit rates - Identify optimization opportunities

MCP Tools

Use cache_inspect to examine live cache state without writing debug code.

cache_inspect

Returns cached keys matching an optional prefix filter, along with their TTL, size, and tags. Use this to verify that values are being cached correctly, diagnose cache miss rates, or inspect which keys are tagged for bulk invalidation.

Authentication

Ferro provides session-based authentication with an Auth facade, Authenticatable trait, UserProvider interface, password hashing (bcrypt), and route protection middleware.

Quick Start

Scaffold a complete auth system with one command:

ferro make:auth

This generates:

• User migration with email and password fields
• Authenticatable implementation on your User model
• DatabaseUserProvider for user retrieval
• AuthController with register, login, and logout handlers
• Routes with auth/guest middleware

Configuration

Session

Authentication state is stored in server-side sessions. Configure via environment variables:

Load configuration from environment:

#![allow(unused)]
fn main() {
use ferro::SessionConfig;

let config = SessionConfig::from_env();
}

Session Expiry

Ferro enforces two independent session timeouts per OWASP recommendations:

• Idle timeout (SESSION_LIFETIME): Sessions expire after a period of inactivity. Default: 2 hours.
• Absolute timeout (SESSION_ABSOLUTE_LIFETIME): Sessions expire after a fixed duration regardless of activity. Default: 30 days. Prevents stolen sessions from being kept alive indefinitely.

Both timeouts are enforced server-side. The session cookie's Max-Age is set to the longer of the two values.

For high-security applications, OWASP recommends shorter values:

Session Invalidation

Destroy sessions for security-sensitive operations like password changes:

#![allow(unused)]
fn main() {
// Logout all other devices (keeps current session)
if let Some(result) = Auth::logout_other_devices().await {
    let destroyed_count = result?;
}

// Logout and invalidate current session
Auth::logout_and_invalidate();
}

Use logout_other_devices() after password changes to invalidate potentially compromised sessions on other devices.

For admin/security flows that need to invalidate sessions for any user:

#![allow(unused)]
fn main() {
use ferro::{invalidate_all_for_user, DatabaseSessionDriver};

let store = DatabaseSessionDriver::new(idle_lifetime, absolute_lifetime);
let destroyed = invalidate_all_for_user(&store, user_id, None).await?;
}

Password Hashing

Ferro uses bcrypt with a default cost factor of 12 (same as Laravel). The cost factor is not configurable via environment variables -- change it by calling hashing::hash_with_cost() directly.

The Authenticatable Trait

Implement Authenticatable on your User model to enable Auth::user() and Auth::user_as::<T>().

#![allow(unused)]
fn main() {
use ferro::Authenticatable;
use std::any::Any;

impl Authenticatable for User {
    fn auth_identifier(&self) -> i64 {
        self.id as i64
    }

    fn as_any(&self) -> &dyn Any {
        self
    }
}
}

Methods

User Provider

The UserProvider trait retrieves users from your data store. Register it in bootstrap.rs to enable Auth::user().

#![allow(unused)]
fn main() {
use ferro::{UserProvider, Authenticatable, FrameworkError};
use async_trait::async_trait;
use std::sync::Arc;

pub struct DatabaseUserProvider;

#[async_trait]
impl UserProvider for DatabaseUserProvider {
    async fn retrieve_by_id(
        &self,
        id: i64,
    ) -> Result<Option<Arc<dyn Authenticatable>>, FrameworkError> {
        let user = User::query()
            .filter(Column::Id.eq(id as i32))
            .first()
            .await?;
        Ok(user.map(|u| Arc::new(u) as Arc<dyn Authenticatable>))
    }
}
}

Methods

Registration

Register the provider in bootstrap.rs:

#![allow(unused)]
fn main() {
bind!(dyn UserProvider, DatabaseUserProvider);
}

Auth Facade

The Auth struct provides static methods for all authentication operations.

Checking Authentication State

#![allow(unused)]
fn main() {
use ferro::Auth;

// Check if a user is authenticated
if Auth::check() {
    // ...
}

// Check if the user is a guest
if Auth::guest() {
    // ...
}

// Get the authenticated user's ID
if let Some(user_id) = Auth::id() {
    println!("User ID: {}", user_id);
}

// Get the ID as a different type (e.g., i32 for SeaORM)
let user_id: i32 = Auth::id_as().expect("must be authenticated");
}

Logging In

#![allow(unused)]
fn main() {
// Log in by user ID
// Regenerates session ID (prevents session fixation) and CSRF token
Auth::login(user_id);

// Log in with "remember me"
Auth::login_remember(user_id, &remember_token);
}

Logging Out

#![allow(unused)]
fn main() {
// Clear authentication state, regenerate CSRF token
Auth::logout();

// Destroy entire session (logout everywhere)
Auth::logout_and_invalidate();
}

Credential Validation

#![allow(unused)]
fn main() {
// Attempt authentication: validates credentials, logs in on success
let result = Auth::attempt(|| async {
    let user = find_user_by_email(&email).await?;
    match user {
        Some(u) if ferro::verify(&password, &u.password_hash)? => Ok(Some(u.id as i64)),
        _ => Ok(None),
    }
}).await?;

if result.is_some() {
    // Authenticated and logged in
}

// Validate credentials without logging in (e.g., password confirmation)
let valid = Auth::validate(|| async {
    let user_id = Auth::id().expect("called inside Auth::validate so user is authenticated");
    let user = find_user_by_id(user_id).await?;
    Ok(ferro::verify(&password, &user.password_hash)?)
}).await?;
}

Retrieving the Current User

#![allow(unused)]
fn main() {
// Get as trait object
if let Some(user) = Auth::user().await? {
    println!("User #{}", user.auth_identifier());
}

// Get as concrete type (requires Authenticatable + Clone)
if let Some(user) = Auth::user_as::<User>().await? {
    println!("Welcome, {}!", user.name);
}
}

Method Reference

Handler Extractors

For ergonomic access to the current user in handler signatures, Ferro provides typed extractors that work as handler parameters.

AuthUser<T>

Injects the authenticated user directly into the handler. Returns 401 Unauthenticated if no user is logged in.

#![allow(unused)]
fn main() {
use ferro::{handler, AuthUser, Response, HttpResponse};
use crate::models::users;

#[handler]
pub async fn profile(user: AuthUser<users::Model>) -> Response {
    Ok(HttpResponse::json(serde_json::json!({
        "id": user.id,
        "name": user.name,
        "email": user.email
    })))
}
}

OptionalUser<T>

Same as AuthUser<T>, but returns None for guests instead of a 401 error.

#![allow(unused)]
fn main() {
use ferro::{handler, OptionalUser, Response, HttpResponse};
use crate::models::users;

#[handler]
pub async fn home(user: OptionalUser<users::Model>) -> Response {
    let greeting = match user.as_ref() {
        Some(u) => format!("Welcome back, {}!", u.name),
        None => "Welcome, guest!".to_string(),
    };
    Ok(HttpResponse::json(serde_json::json!({"greeting": greeting})))
}
}

Deref Behavior

Both AuthUser<T> and OptionalUser<T> implement Deref, so you access fields directly on the wrapper:

• AuthUser<T> derefs to T -- use user.name, not user.0.name
• OptionalUser<T> derefs to Option<T> -- use user.as_ref(), user.is_some(), etc.

Limitations

AuthUser and OptionalUser count as a FromRequest parameter. Only one FromRequest parameter is allowed per handler signature, so they cannot be combined with FormRequest types in the same handler. If you need both the authenticated user and the request body, use Request and call Auth::user_as::<T>() manually:

#![allow(unused)]
fn main() {
#[handler]
pub async fn update_profile(req: Request) -> Response {
    let user: users::Model = Auth::user_as::<users::Model>().await?
        .ok_or_else(|| HttpResponse::json(serde_json::json!({"error": "Unauthenticated"})).status(401))?;
    let input: UpdateInput = req.json().await?;
    // ... use both user and input
}
}

Password Hashing

Ferro provides bcrypt hashing functions re-exported at the crate root.

#![allow(unused)]
fn main() {
use ferro::{hash, verify, needs_rehash};

// Hash a password (bcrypt, cost 12)
let hashed = ferro::hash("my_password")?;

// Verify a password against a stored hash (constant-time comparison)
let valid = ferro::verify("my_password", &hashed)?;

// Check if a hash was created with a lower cost factor
if ferro::needs_rehash(&stored_hash) {
    let new_hash = ferro::hash(&password)?;
    // Update stored hash
}
}

Custom Cost Factor

#![allow(unused)]
fn main() {
use ferro::hashing;

// Hash with a specific cost (higher = slower + more secure)
let hashed = hashing::hash_with_cost("my_password", 14)?;
}

Middleware

AuthMiddleware

Protects routes that require authentication.

#![allow(unused)]
fn main() {
use ferro::{AuthMiddleware, group, get};

// API routes: returns 401 JSON for unauthenticated requests
group!("/api")
    .middleware(AuthMiddleware::new())
    .routes([...]);

// Web routes: redirects to login page
group!("/dashboard")
    .middleware(AuthMiddleware::redirect_to("/login"))
    .routes([...]);
}

Inertia-aware: When an Inertia request hits AuthMiddleware::redirect_to(), it returns a 409 response with X-Inertia-Location header instead of a 302 redirect. This tells the Inertia client to perform a full page visit to the login URL.

GuestMiddleware

Protects routes that should only be accessible to unauthenticated users (login, register pages).

#![allow(unused)]
fn main() {
use ferro::{GuestMiddleware, group, get};

group!("/")
    .middleware(GuestMiddleware::redirect_to("/dashboard"))
    .routes([
        get!("/login", auth::show_login),
        get!("/register", auth::show_register),
    ]);
}

Authenticated users visiting these routes are redirected to the specified path. Also Inertia-aware.

Login-resume contract (OAuth/MCP)

When ferro-mcp-oauth's /authorize endpoint receives an unauthenticated request, it stores the in-flight authorize URL in the session and redirects to the app login page. After authentication the login handler must redirect back to that stored URL so the OAuth flow resumes and an authorization code is issued.

Contract

Any login method — synchronous password, asynchronous magic-link, future SSO — must call oauth_resume_redirect(default) (or take_oauth_return_to()) after establishing the session to participate in the OAuth flow. A handler that redirects to a fixed dashboard instead will never resume the authorize request.

Adoption

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::oauth_resume_redirect;

// After Auth::login(user_id):
return oauth_resume_redirect("/");
}

oauth_resume_redirect returns ferro::Response and is used with a bare return, not ?. It redirects to the stored authorize URL when an OAuth flow is in progress, or to the supplied default when it is not.

Available helpers

Open-redirect invariant

The stored URL is written exclusively by the /authorize handler from a URL it constructs itself — never from user-supplied input. The default argument is a static internal path supplied by the caller. The helper therefore never redirects to an attacker-controlled URL.

Worked example

The bundled sample app's magic-link verify handler is the canonical example of a separate-request login method that uses oauth_resume_redirect to resume the OAuth flow after token verification.

Login and Registration Example

Register Handler

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response, Auth, json_response, Validator};

#[handler]
pub async fn register(req: Request) -> Response {
    let data: serde_json::Value = req.json().await?;

    // Validate input
    let errors = Validator::new()
        .rule("name", rules![required(), string(), min(2)])
        .rule("email", rules![required(), email()])
        .rule("password", rules![required(), string(), min(8), confirmed()])
        .validate(&data);

    if errors.fails() {
        return json_response!(422, {
            "message": "Validation failed.",
            "errors": errors
        });
    }

    // Hash password
    let password = data["password"].as_str().ok_or_else(|| HttpResponse::bad_request())?;
    let password_hash = ferro::hash(password)?;

    // Insert user
    let user = User::insert(NewUser {
        name: data["name"].as_str().ok_or_else(|| HttpResponse::bad_request())?.to_string(),
        email: data["email"].as_str().ok_or_else(|| HttpResponse::bad_request())?.to_string(),
        password: password_hash,
    }).await?;

    // Log in
    Auth::login(user.id as i64);

    json_response!(201, { "message": "Registered." })
}
}

Login Handler

#![allow(unused)]
fn main() {
#[handler]
pub async fn login(req: Request) -> Response {
    let data: serde_json::Value = req.json().await?;

    let errors = Validator::new()
        .rule("email", rules![required(), email()])
        .rule("password", rules![required(), string()])
        .validate(&data);

    if errors.fails() {
        return json_response!(422, {
            "message": "Validation failed.",
            "errors": errors
        });
    }

    let email = data["email"].as_str().ok_or_else(|| HttpResponse::bad_request())?;
    let password = data["password"].as_str().ok_or_else(|| HttpResponse::bad_request())?;

    // Attempt authentication
    let result = Auth::attempt(|| async {
        let user = User::find_by_email(email).await?;
        match user {
            Some(u) if ferro::verify(password, &u.password)? => Ok(Some(u.id as i64)),
            _ => Ok(None),
        }
    }).await?;

    match result {
        Some(_) => json_response!(200, { "message": "Authenticated." }),
        None => json_response!(401, { "message": "Invalid credentials." }),
    }
}
}

Logout Handler

#![allow(unused)]
fn main() {
#[handler]
pub async fn logout(_req: Request) -> Response {
    Auth::logout();
    json_response!(200, { "message": "Logged out." })
}
}

Route Registration

#![allow(unused)]
fn main() {
use ferro::{group, get, post, AuthMiddleware, GuestMiddleware};

// Guest-only routes (login/register pages)
group!("/")
    .middleware(GuestMiddleware::redirect_to("/dashboard"))
    .routes([
        post!("/register", auth::register),
        post!("/login", auth::login),
    ]);

// Authenticated routes
group!("/")
    .middleware(AuthMiddleware::redirect_to("/login"))
    .routes([
        post!("/logout", auth::logout),
        get!("/dashboard", dashboard::index),
    ]);
}

Security

Ferro's auth system applies these protections:

MCP Tools

Use these tools to inspect authorization policies and active session state.

list_policies

Returns all authorization policy implementations discovered in the project, including the policy struct name, the actions it governs, and the user types it checks. Use this to audit which resources have access control before adding new protected routes.

session_inspect

Returns details about the current session store: active session count, session driver in use, idle and absolute timeout configuration, and whether session invalidation is working correctly. Use this to debug authentication failures or verify session security settings.

MCP OAuth Authorization Server

ferro-mcp-oauth is a mountable crate that turns any Ferro application into an OAuth 2.1 authorization server for its MCP endpoint. It implements the authorization-code flow (RFC 6749 with PKCE, RFC 7636) and the device authorization grant (RFC 8628), backed by the same JWT issuer so both flows produce tokens with identical audience binding and tenant scoping.

Quick Start

Add ferro-mcp-oauth to your Cargo.toml and mount the handlers in app/src/routes.rs:

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::handlers::{
    authorization_server_handler, authorize_get, authorize_post,
    device_authorization, device_verification_get, device_verification_post,
    protected_resource_handler, register_client, token_exchange,
};

routes! {
    // OAuth discovery (public)
    get!("/.well-known/oauth-protected-resource", protected_resource_handler),
    get!("/.well-known/oauth-authorization-server", authorization_server_handler),

    // Authorization-code flow (session + tenant)
    group!("/", {
        get!("/authorize", authorize_get),
        post!("/authorize", authorize_post),
    }).middleware(
        TenantMiddleware::new()
            .resolver(SessionUserTenantResolver::new())
            .on_failure(TenantFailureMode::Allow),
    ),

    // Dynamic Client Registration + token exchange (public)
    post!("/register", register_client),
    post!("/token", token_exchange),

    // Device Authorization Grant (public — no session)
    post!("/device_authorization", device_authorization),

    // Device verification page (session + tenant, Allow so unauthenticated visitors reach login)
    group!("/", {
        get!("/device", device_verification_get),
        post!("/device", device_verification_post),
    }).middleware(
        TenantMiddleware::new()
            .resolver(SessionUserTenantResolver::new())
            .on_failure(TenantFailureMode::Allow),
    ),
}
}

Run the database migration once:

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::CreateOauthClientsTable;

// In your bootstrap or migration runner
CreateOauthClientsTable::up(&db).await?;
}

Configuration

Authorization-Code Flow

The standard browser-based OAuth 2.1 flow with PKCE:

1. Client registers via POST /register (Dynamic Client Registration, RFC 7591).
2. Client redirects the browser to GET /authorize with response_type=code, client_id, redirect_uri, code_challenge (S256), and state.
3. If the user is unauthenticated, the handler stores the in-flight URL and redirects to the app login page. After authentication the login handler calls oauth_resume_redirect to return to the authorize endpoint.
4. Authenticated user sees a consent page; on approval an authorization code is issued and the browser is redirected to redirect_uri with code and state.
5. Client exchanges the code at POST /token with grant_type=authorization_code and code_verifier (PKCE proof).

Device Authorization Grant (RFC 8628)

The device grant is the MCP auth path for clients that cannot complete a same-device browser redirect: headless CLI tools, cross-device logins, and passwordless flows.

Step 1 — Request a device code

The device (CLI, daemon, or headless client) sends its client_id to the public endpoint:

POST /device_authorization
Content-Type: application/x-www-form-urlencoded

client_id=<registered_client_id>

Response (RFC 8628 §3.2):

{
  "device_code": "<opaque high-entropy string>",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://your-app.example.com/device",
  "verification_uri_complete": "https://your-app.example.com/device?user_code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}

Step 2 — User authorizes on any device

The user opens verification_uri (or scans the QR code for verification_uri_complete) on any browser — a phone, tablet, or desktop — and follows the flow:

1. If unauthenticated: redirected to the app login page via the Phase 202 resume contract; returns to /device automatically after authentication.
2. Enters or confirms the user_code.
3. Sees the consent page (same approve/deny UI as the authorization-code flow).
4. On approval: user_id and tenant_id are captured from the session and bound to the grant. The device receives an access_token on the next poll.

Step 3 — Poll for the token

While the user completes Step 2, the device polls POST /token at intervals ≥ interval seconds:

POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=<device_code>&client_id=<client_id>

Response codes (RFC 8628 §3.5):

Token identity

Tokens issued by the device grant are minted by the same jwt.rs path as the authorization-code grant, with identical sub, aud, iss, and tenant_id claims. There is one token issuer; the device grant is an alternate entry point, not a parallel path.

Discovery Metadata

Both flows are advertised in the RFC 8414 authorization-server metadata:

GET /.well-known/oauth-authorization-server

{
  "issuer": "https://your-app.example.com",
  "authorization_endpoint": "https://your-app.example.com/authorize",
  "token_endpoint": "https://your-app.example.com/token",
  "registration_endpoint": "https://your-app.example.com/register",
  "device_authorization_endpoint": "https://your-app.example.com/device_authorization",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}

Validating Bearer Tokens

At the MCP endpoint, call validate_bearer to verify and decode incoming tokens:

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::{validate_bearer, BearerCheck};

match validate_bearer(&req) {
    BearerCheck::Valid(claims) => {
        // claims.sub  — user id
        // claims.tenant_id — tenant id (None for single-tenant apps)
    }
    BearerCheck::Missing => { /* 401 */ }
    BearerCheck::Invalid(reason) => { /* 401 with reason */ }
}
}

Security Notes

• CSRF: The consent and device-verification POST handlers use constant-time comparison (subtle::ConstantTimeEq) on session CSRF tokens.
• Tenant binding: tenant_id is captured from the session at consent/approval time, not from form input. The TenantFailureMode::Allow mode ensures unauthenticated visitors reach the login redirect rather than a 403.
• Single-use codes: Authorization codes and device codes are forgotten from cache immediately after a successful token exchange (get-then-forget discipline).
• Device code entropy: device_code is a 256-bit URL-safe random string (same entropy as PKCE authorization codes). user_code uses the RFC 8628 §6.1 unambiguous consonant charset (BCDFGHJKLMNPQRSTVWXZ) and is accepted case-insensitively with or without the hyphen.
• Rate limiting: The polling slow_down response enforces a minimum interval between polls. Additional rate limiting on POST /device_authorization is not implemented; apply an upstream reverse-proxy limit if needed.

MCP Per-Tenant API-Key Auth

ferro-mcp-oauth supports two authentication paths on the single /mcp endpoint: OAuth JWT (browser-based authorization-code flow and device grant) and a per-tenant API key. Both paths resolve to the same tenant context and produce the same BearerCheck::Authenticated outcome.

Authentication Paths

The MCP endpoint reads the Authorization: Bearer <token> header on every request. The token shape determines which validation branch runs:

Both branches produce BearerCheck::Authenticated(principal) on success, where principal is a JSON object with sub, tenant_id, and scope fields. The downstream tool dispatcher receives the same context regardless of which path was taken.

The mcp_api_keys Table

API keys are stored as SHA-256 hashes — the plaintext key is never persisted.

CREATE TABLE mcp_api_keys (
    id          BIGINT PRIMARY KEY AUTOINCREMENT,
    tenant_id   BIGINT NOT NULL,
    key_hash    TEXT NOT NULL,          -- SHA-256 hex of the raw key
    scope       TEXT NOT NULL DEFAULT 'read',
    revoked_at  TIMESTAMP WITH TIME ZONE NULL,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL,
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL
);

CREATE UNIQUE INDEX idx_mcp_api_keys_key_hash ON mcp_api_keys (key_hash);
CREATE        INDEX idx_mcp_api_keys_tenant_id ON mcp_api_keys (tenant_id);

ferro-mcp-oauth ships the canonical schema as a migration struct. The consumer app runs it once at bootstrap:

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::CreateMcpApiKeysTable;

CreateMcpApiKeysTable::up(&db).await?;
}

Generating and Storing a Key

generate_mcp_api_key returns the plaintext key once, alongside the hash to store. The plaintext is never passed to any persistence layer.

#![allow(unused)]
fn main() {
use ferro_mcp_oauth::{generate_mcp_api_key, CreateMcpApiKeysTable};

// Generate
let (raw_key, key_hash) = generate_mcp_api_key();
// raw_key  — a "ferro_"-prefixed 49-character BASE62 token; present this to the operator
// key_hash — SHA-256 hex; insert this into mcp_api_keys

// Insert (using your preferred query layer)
db.execute(Statement::from_sql_and_values(
    DbBackend::Sqlite,
    "INSERT INTO mcp_api_keys (tenant_id, key_hash, scope, created_at, updated_at)
     VALUES (?, ?, ?, datetime('now'), datetime('now'))",
    [tenant_id.into(), key_hash.into(), "read_write".into()],
)).await?;
}

Generated keys are ferro_ followed by 43 random BASE62 characters (49 characters total). The prefix makes API keys unambiguously distinguishable from JWTs at the routing branch point.

Key Rotation

Rotation uses a soft-revoke pattern: issue a new key and set revoked_at on the old one. Do not delete rows — the audit trail is preserved.

-- Revoke the old key
UPDATE mcp_api_keys SET revoked_at = NOW() WHERE id = ?;
-- Insert new key (using generate_mcp_api_key as above)

validate_api_key treats any non-null revoked_at as BearerCheck::Invalid.

Scope Model

Each key carries a scope field: read or read_write.

The scope check on tools/call is enforced server-side before tool dispatch, independently of the listing filter. A client that bypasses tools/list and calls a write tool directly with a read-scoped key receives a -32603 error with message "scope insufficient".

Scope is orthogonal to tenant ability. scope governs the credential's permission (what this particular key may do). ServiceDef.mcp_ability governs the tenant's capability (what the tenant's account permits). Both checks apply independently.

Using an API Key

Present the raw key as a Bearer token:

Authorization: Bearer ferro_<token>

curl https://your-app.example.com/mcp \
  -H "Authorization: Bearer ferro_Ab3Cd..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Security Properties

• Plaintext never stored. Only the SHA-256 hex hash of the key is written to the database.
• Fail-closed. Any lookup error, unknown key, or revoked key returns BearerCheck::Invalid — the same rejection path as an invalid JWT.
• Cross-tenant isolation. The validator checks expected_tenant against the tenant_id column; a key issued to tenant A returns BearerCheck::Forbidden if presented on a tenant-B-scoped request.
• Scope re-check at dispatch. tools/call re-evaluates the key scope before dispatching any write tool, so a tools/list filter bypass does not grant elevated access.

Agent-Operable App (Consumer MCP)

A Ferro application can expose its own data and guarded actions to an AI agent through a per-tenant MCP endpoint. The tools an agent sees are derived from the same ServiceDef projections that drive the visual and text renderers — reads, guarded writes, and a natural-language turn — so an agent operates the business through the same authorization, tenant-scoping, and guard rules as the dashboard.

This page is an end-to-end worked example. It builds on the two authentication pages — MCP OAuth Authorization Server and MCP Per-Tenant API-Key Auth — which secure the /mcp endpoint; here we add the projection-derived tools, write dispatch, confirmation gating, and the inbound intent loop on top of them.

The example domain

An order-fulfillment workflow: an order moves through a guarded state machine (draft → submitted → approved → shipped → delivered/cancelled), where approval requires a manager. The agent should be able to list a tenant's orders and advance their state — but a destructive transition must be confirmed, and a non-manager must not be able to approve.

Step 1 — Define the projection with guarded actions

The tool surface is derived entirely from a ServiceDef. Opting a projection into MCP (mcp_exposed) and declaring its actions is all that is required — no per-tool code.

#![allow(unused)]
fn main() {
use ferro::{
    ActionDef, DataType, FieldMeaning, GuardDef, ServiceDef, StateDef, StateMachine, Transition,
};

pub fn service_def() -> ServiceDef {
    ServiceDef::new("order")
        .mcp_exposed(true)            // expose this projection over /mcp
        .tenant_column("tenant_id")   // every query/write is scoped to this column
        .mcp_ability("view-orders")   // Gate ability required to call the read tool
        .display_name("Order")
        .field("id", DataType::Integer, FieldMeaning::Identifier)
        .field("customer_name", DataType::String, FieldMeaning::EntityName)
        .field("total", DataType::Float, FieldMeaning::Money)
        .field("status", DataType::String, FieldMeaning::Status)
        .field("created_at", DataType::DateTime, FieldMeaning::CreatedAt)
        .state_machine(
            StateMachine::new("order_lifecycle")
                .initial("draft")
                .state(StateDef::new("draft"))
                .state(StateDef::new("submitted"))
                .state(StateDef::new("approved"))
                .state(StateDef::new("shipped"))
                .state(StateDef::new("delivered").final_state())
                .state(StateDef::new("cancelled").final_state())
                .transition(Transition::new("draft", "submit", "submitted"))
                .transition(Transition::new("submitted", "approve", "approved").guard("is_manager"))
                .transition(Transition::new("submitted", "reject", "cancelled"))
                .transition(Transition::new("approved", "ship", "shipped"))
                .transition(Transition::new("shipped", "deliver", "delivered"))
                .transition(Transition::new("draft", "cancel", "cancelled")),
        )
        .guard(GuardDef::new("is_manager").display_name("Manager Approval Required"))
        .action(ActionDef::new("submit").transition_trigger("submit"))
        .action(
            ActionDef::new("approve")
                .transition_trigger("approve")
                .precondition("is_manager"),
        )
        .action(ActionDef::new("ship").transition_trigger("ship"))
        .belongs_to("customer", "user")
        .has_many("line_items", "line_item")
}
}

This single definition derives the entire tool surface:

An action's transition_trigger marks it destructive, which is what synthesizes the two-step confirmation tools. A precondition (here is_manager) is the guard re-evaluated server-side at call time.

Step 2 — Mount the endpoint

The MCP endpoint is a single route group behind the bearer + tenant middleware. The optional /mcp/chat route adds the natural-language turn (Step 5).

#![allow(unused)]
fn main() {
group!("/", {
    post!("/mcp", controllers::mcp::handle).name("mcp.endpoint"),
    post!("/mcp/chat", controllers::mcp_chat::handle_chat).name("mcp.chat"),
})
.middleware(BearerAuthMiddleware { mcp_config: McpServerConfig::from_env() })
.middleware(
    TenantMiddleware::new()
        .resolver(JwtClaimResolver::new("tenant_id", crate::tenant_lookup::get()))
        .on_failure(TenantFailureMode::Forbidden),
);
}

BearerAuthMiddleware accepts either an OAuth JWT or a per-tenant ferro_ API key (see the two auth pages); both resolve to the same tenant context, which the dispatch paths read.

Step 3 — Wire the write dispatcher

Reads need no wiring. Writes need a WriteDispatcher: an executor that performs the mutation tenant-scoped, and a guard evaluator that re-checks preconditions against the live database. The framework never trusts the agent's view of guards — the evaluator runs at call time and is fail-closed (an unknown guard name is denied, not allowed).

#![allow(unused)]
fn main() {
pub(crate) fn make_write_dispatcher() -> WriteDispatcher {
    WriteDispatcher {
        executor: Box::new(|action_name, inputs, tenant_id, db| {
            let action_name = action_name.to_string();
            let id_val = inputs["id"].as_i64();
            let db = db.clone();
            Box::pin(async move {
                let id = id_val
                    .ok_or_else(|| ferro_mcp_server::Error::Validation("missing id".into()))?;

                // find_for_tenant: filter by id AND tenant_id — None => cross-tenant denial.
                let order = Entity::find_by_id(id as i32)
                    .filter(Column::TenantId.eq(tenant_id))
                    .one(&db).await
                    .map_err(|e| ferro_mcp_server::Error::Database(e.to_string()))?
                    .ok_or_else(|| ferro_mcp_server::Error::Validation(
                        "not found or cross-tenant access denied".into()))?;

                let new_status = match action_name.as_str() {
                    "submit" => "submitted",
                    "approve" => "approved",
                    "ship" => "shipped",
                    _ => return Err(ferro_mcp_server::Error::ActionNotFound(action_name)),
                };

                let mut active: OrderActive = order.into();
                active.status = Set(new_status.to_string());
                let updated = active.update(&db).await
                    .map_err(|e| ferro_mcp_server::Error::Database(e.to_string()))?;
                Ok(json!({ "id": updated.id, "status": updated.status }))
            })
        }),
        guard_evaluator: Box::new(|guard_name, tenant_id, _inputs, db| {
            let guard_name = guard_name.to_string();
            let db = db.clone();
            Box::pin(async move {
                match guard_name.as_str() {
                    "is_manager" => Ok(check_is_manager(tenant_id, &db).await), // live DB check
                    // Fail-closed: an unrecognized guard is denied, never silently allowed.
                    _ => Err(ferro_mcp_server::Error::GuardFailed(format!(
                        "unknown guard '{guard_name}': no evaluator registered"))),
                }
            })
        }),
    }
}

pub(crate) fn exposed_services() -> Vec<ServiceDef> {
    vec![crate::projections::order::service_def()]
}
}

The executor's find_by_id(id).filter(tenant_id) pattern is what makes cross-tenant writes structurally impossible: a row owned by another tenant resolves to None and the call fails before any mutation.

Step 4 — Confirmation gating for destructive actions

Enable the confirmation feature and provide a store. Every action with a transition_trigger is then gated by a two-step request_confirm_<action> → confirm_<action> flow; calling the destructive tool directly returns a confirmation_required error instead of executing.

# Cargo.toml
[features]
confirmation = ["ferro-mcp-server/confirmation", "dep:ferro-ai"]

#![allow(unused)]
fn main() {
static CONFIRMATION_STORE: OnceLock<ferro_ai::InMemoryConfirmationStore> = OnceLock::new();

pub(crate) fn confirmation_store() -> &'static ferro_ai::InMemoryConfirmationStore {
    CONFIRMATION_STORE.get_or_init(ferro_ai::InMemoryConfirmationStore::new)
}
}

request_confirm_<action> validates inputs, re-evaluates guards, and mints a single-use, cfm_-prefixed token bound to (tenant, action, record) with a TTL (default 300s); confirm_<action> consumes the token exactly once, re-evaluates guards again, and executes. The TTL is configured through McpServerConfig.

Step 5 — The inbound natural-language turn (/mcp/chat)

/mcp/chat accepts { "message": "..." }, classifies it to a tool + arguments with ferro-ai::Classifier, and routes the result through the same read/write/confirm machinery — it adds no parallel dispatch logic. The classifier output is treated as untrusted: a classified tool name and arguments pass the identical validation, guard re-evaluation, and tenant scoping as any direct tool call.

Enable the ai-live feature (it implies confirmation and pulls the live provider) and the endpoint instantiates AnthropicProvider from the environment:

[features]
ai-live = ["ferro-mcp-server/ai-live", "ferro-mcp-server/confirmation", "dep:ferro-ai", "ferro-ai/llm", "confirmation"]

The loop is CI-testable without live-LLM spend: with FERRO_AI_LIVE_EVAL unset it runs from recorded transcript fixtures through a reqwest-free replay provider, exercising every branch with no network. Set FERRO_AI_LIVE_EVAL=1 (with ANTHROPIC_API_KEY) to make a real call; the live path announces an estimated cost before the first request. A low-confidence classification returns a needs_clarification response rather than dispatching to the wrong tool.

What the agent sees — a real session

Authenticated as a tenant (here tenant 1, "Acme"), an agent lists the tools and operates on real data. The tool surface and responses below are the actual endpoint output.

tools/list returns the derived surface:

["list_order", "submit", "approve", "ship",
 "request_confirm_submit", "confirm_submit",
 "request_confirm_approve", "confirm_approve",
 "request_confirm_ship", "confirm_ship"]

tools/call list_order returns only the caller's rows, with a structured result:

{ "result": {
    "content": [{ "type": "text", "text": "{\"rows\":[ ... ],\"total\":2}" }],
    "structuredContent": { "rows": [
        { "id": 1, "customer_name": "Alice Acme", "total": 120.0, "status": "submitted", "tenant_id": 1 },
        { "id": 2, "customer_name": "Alice Acme", "total": 85.5,  "status": "delivered", "tenant_id": 1 }
    ], "total": 2 },
    "isError": false } }

Calling a destructive tool directly is blocked:

// tools/call submit { "id": 1 }
{ "result": {
    "structuredContent": { "error_kind": "confirmation_required",
        "message": "use request_confirm_submit first",
        "request_tool": "request_confirm_submit" },
    "isError": true } }

The two-step flow mints a token, then executes once:

// tools/call request_confirm_submit { "id": 1 }
{ "result": { "structuredContent": {
    "confirmation_token": "cfm_…", "expires_in_seconds": 300 }, "isError": false } }

// tools/call confirm_submit { "confirmation_token": "cfm_…", "id": 1 }
{ "result": { "structuredContent": {
    "status": "ok", "action": "submit", "result": { "id": 1, "status": "submitted" } },
    "isError": false } }

// replay the same token => rejected (single-use)
{ "result": { "structuredContent": { "error_kind": "confirmation_expired" }, "isError": true } }

Security properties

Every property is enforced server-side, regardless of what the agent (or a prompt-injected message) claims:

• Tenant isolation — reads and writes are scoped to the authenticated tenant's tenant_column; a cross-tenant id resolves to None and the call fails. tenant_id comes from the authenticated principal, never from tool arguments.
• Guard re-evaluation — preconditions (is_manager) are checked against the live database at call time, fail-closed; the classifier's or agent's view of guards is never trusted.
• Confirmation — destructive actions require a server-minted, single-use, TTL-bound token; the same token cannot be replayed.
• Authorization — read tools require the projection's mcp_ability via the app Gate; the natural-language read path enforces the same ability as the direct path.
• Untrusted classification — /mcp/chat arguments enter the identical validation and dispatch pipeline as any direct call; classification is an entry point, not a trust shortcut.

See also

• MCP OAuth Authorization Server — the browser authorization-code and device flows.
• MCP Per-Tenant API-Key Auth — the ferro_ key path for headless agents.
• Multi-Tenancy — the tenant context the dispatch paths read.

Multi-Tenancy

Ferro provides built-in support for multi-tenant applications using a shared-schema approach where every tenant shares the same database schema. Each tenant's data is isolated by a tenant_id foreign key column, enforced at the query layer via TenantScope.

The middleware resolves the current tenant once per request, stores it in task-local context, and makes it available to handlers and query scopes without requiring explicit parameter passing.

Overview

The multi-tenancy system has three components:

1. TenantMiddleware — resolves the tenant from the incoming request using a pluggable resolver strategy.
2. TenantContext — the resolved tenant data (id, slug, name, plan), available as a handler parameter via FromRequest.
3. TenantScope — a query scope that filters database queries by the current tenant's ID.

Quick Start

Add TenantMiddleware to your application in bootstrap.rs:

#![allow(unused)]
fn main() {
use ferro::{
    global_middleware, TenantMiddleware, SubdomainResolver, DbTenantLookup,
    TenantFailureMode,
};
use std::sync::Arc;

pub fn register() {
    let lookup = Arc::new(DbTenantLookup::new(
        // Find tenant ID by slug
        |slug: String| async move {
            tenant::Entity::find()
                .filter(tenant::Column::Slug.eq(&slug))
                .one(DB::get())
                .await
                .ok()
                .flatten()
                .map(|t| t.id)
        },
        // Find full tenant by ID
        |id: i64| async move {
            tenant::Entity::find_by_id(id)
                .one(DB::get())
                .await
                .ok()
                .flatten()
                .map(|t| TenantContext {
                    id: t.id,
                    slug: t.slug,
                    name: t.name,
                    plan: t.plan,
                })
        },
    ));

    global_middleware!(
        TenantMiddleware::new()
            .resolver(SubdomainResolver {
                base_domain_parts: 2,
                tenant_lookup: lookup,
            })
            .on_failure(TenantFailureMode::NotFound)
    );
}
}

This configuration resolves the tenant from the request subdomain (e.g., acme.yourapp.com resolves to tenant slug acme) and returns 404 if no tenant is found.

Resolver Strategies

Four built-in resolvers cover the most common patterns. Multiple resolvers can be chained — the first one that returns Some wins.

Subdomain Resolver

Extracts the tenant slug from the request subdomain.

#![allow(unused)]
fn main() {
SubdomainResolver {
    base_domain_parts: 2, // strips last 2 parts: yourapp.com
    tenant_lookup: lookup,
}
}

• When to use: SaaS applications with per-tenant subdomains (acme.yourapp.com).
• base_domain_parts: 2 means yourapp.com is the base — the first segment before it is the slug.
• For app.yourapp.com (3 parts), use base_domain_parts: 2 and app. is the slug.

Header Resolver

Extracts the tenant slug from a custom HTTP header.

#![allow(unused)]
fn main() {
HeaderResolver {
    header_name: "X-Tenant-ID".to_string(),
    tenant_lookup: lookup,
}
}

• When to use: API clients, internal services, or mobile apps where the client explicitly sends the tenant identifier.

Path Resolver

Extracts the tenant slug from a route parameter.

#![allow(unused)]
fn main() {
PathResolver {
    param_name: "tenant".to_string(),
    tenant_lookup: lookup,
}
}

Route: /t/:tenant/dashboard

• When to use: Applications where the tenant is embedded in the URL path (e.g., /t/acme/dashboard).

JWT Claim Resolver

Extracts the tenant slug from a JWT claim stored in request extensions.

#![allow(unused)]
fn main() {
JwtClaimResolver {
    claim_field: "tenant_id".to_string(),
    tenant_lookup: lookup,
}
}

• When to use: Stateless APIs where an upstream JWT middleware has already parsed the token and stored claims in the request extensions as serde_json::Value.
• Requires upstream middleware to insert parsed JWT claims into req.extensions.

Chaining Resolvers

Multiple resolvers are tried in order — the first to return Some is used:

#![allow(unused)]
fn main() {
TenantMiddleware::new()
    .resolver(HeaderResolver { header_name: "X-Tenant".to_string(), tenant_lookup: lookup.clone() })
    .resolver(SubdomainResolver { base_domain_parts: 2, tenant_lookup: lookup })
    .on_failure(TenantFailureMode::Allow)
}

Handler Extraction

TenantContext implements FromRequest and can be used as a handler parameter directly:

#![allow(unused)]
fn main() {
use ferro::{handler, TenantContext, Response, json};

#[handler]
pub async fn dashboard(tenant: TenantContext) -> Response {
    Ok(json!({
        "tenant": tenant.name,
        "plan": tenant.plan,
    }))
}
}

The handler will receive a 400 error if no tenant context is available (i.e., the route is not behind TenantMiddleware). Use this to enforce that handlers always have a tenant.

You can also read the tenant anywhere in a call chain using current_tenant():

#![allow(unused)]
fn main() {
use ferro::current_tenant;

pub async fn some_service() -> Option<String> {
    current_tenant().map(|t| t.slug)
}
}

current_tenant() returns None outside a TenantMiddleware scope.

Query Scoping

Use TenantScope to filter queries by the current tenant's ID. This prevents data from leaking between tenants.

#![allow(unused)]
fn main() {
use ferro::{TenantScope, ScopedQuery};

// Fetch all posts belonging to the current tenant
let posts = post::Entity::scoped(TenantScope(post::Column::TenantId))
    .all()
    .await?;
}

TenantScope(column) implements Scope<E> — it reads the current tenant's ID from task-local context and applies .filter(column.eq(tenant_id)) to the query.

Panic Behavior

TenantScope panics with a clear message if called outside a TenantMiddleware scope:

TenantScope used outside TenantMiddleware scope — ensure this route is behind TenantMiddleware

This is intentional. Using TenantScope without middleware is a programming error, not a runtime condition. The panic surfaces the mistake immediately in development rather than silently returning unscoped data.

Failure Modes

TenantFailureMode controls what happens when the resolver cannot find a tenant:

#![allow(unused)]
fn main() {
TenantMiddleware::new()
    .resolver(SubdomainResolver { ... })
    .on_failure(TenantFailureMode::Allow) // allow public pages without tenant
}

With Allow, current_tenant() returns None for unresolved requests. Handlers that require a tenant should use TenantContext as a parameter — which returns a 400 error — rather than calling current_tenant() directly.

Custom TenantLookup

DbTenantLookup covers the most common case: a tenants table with slug and id columns. For custom schemas, implement TenantLookup directly:

#![allow(unused)]
fn main() {
use ferro::{TenantLookup, TenantContext};
use async_trait::async_trait;

pub struct MyCustomLookup;

#[async_trait]
impl TenantLookup for MyCustomLookup {
    async fn find_by_slug(&self, slug: &str) -> Option<TenantContext> {
        // Custom lookup logic — read from DB, cache, config, etc.
        todo!()
    }
}
}

The TenantLookup trait is object-safe (Arc<dyn TenantLookup>), so resolvers can share a single lookup instance across threads.

Background Jobs

Jobs dispatched from tenant-scoped handlers automatically carry the current tenant's ID in the payload. When a worker processes the job, it restores the full TenantContext before execution — so current_tenant() works inside job handlers the same way it does in HTTP handlers.

Setup

Register the capture hook and configure the worker with a tenant scope provider during bootstrap:

#![allow(unused)]
fn main() {
use ferro::{
    Worker, WorkerConfig, Queue, register_tenant_capture_hook,
    current_tenant,
    tenant::{DbTenantLookup, FrameworkTenantScopeProvider},
};
use std::sync::Arc;

// Register once at startup. Called at dispatch time to capture the current tenant ID.
register_tenant_capture_hook(|| current_tenant().map(|t| t.id));

// Build the lookup (same instance used by TenantMiddleware).
let lookup = Arc::new(DbTenantLookup::new(
    |slug| Box::pin(async move { /* find by slug */ None }),
    |id| Box::pin(async move { /* find by id */ None }),
));

// Attach the scope provider to the worker.
let worker = Worker::new(Queue::connection(), WorkerConfig::default())
    .with_tenant_scope(Arc::new(FrameworkTenantScopeProvider::new(lookup)));
}

register_tenant_capture_hook is a no-op if called more than once — only the first registration takes effect.

Using current_tenant() in Jobs

Job handlers can call current_tenant() directly, without any extra setup:

#![allow(unused)]
fn main() {
use ferro::{Job, Error, current_tenant};

#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct SendWelcomeEmail;

#[async_trait::async_trait]
impl Job for SendWelcomeEmail {
    async fn handle(&self) -> Result<(), Error> {
        let tenant = current_tenant().expect("job must run inside tenant scope");
        // send email for tenant.name ...
        Ok(())
    }
}
}

Dispatching on Behalf of a Tenant

In admin or system contexts where no ambient tenant scope exists (CLI commands, webhooks, scheduled tasks), use .for_tenant(id) to explicitly attach a tenant ID to the job:

#![allow(unused)]
fn main() {
use ferro::queue_dispatch;

// Runs the job in the scope of tenant 42, regardless of current context.
queue_dispatch(SendWelcomeEmail)
    .for_tenant(42)
    .dispatch()
    .await?;
}

Behavior When Tenant Not Found

If the worker cannot resolve the tenant ID stored in the payload (tenant deleted, DB unavailable), the job fails with QueueError::TenantNotFound. The worker follows the normal retry/failed-queue flow based on the job's retry configuration.

Safety Notes

Every query on tenant-owned tables must use TenantScope. Unscoped queries silently return data from all tenants.

#![allow(unused)]
fn main() {
// WRONG: returns posts from all tenants
let all_posts = post::Entity::query().all().await?;

// CORRECT: returns posts for the current tenant only
let tenant_posts = post::Entity::scoped(TenantScope(post::Column::TenantId))
    .all()
    .await?;
}

Cache keys must be tenant-prefixed. When caching tenant-specific data, prefix keys with the tenant ID to prevent cross-tenant cache pollution:

#![allow(unused)]
fn main() {
let key = format!("tenant:{}:feature_flags", tenant.id);
}

Routes that access tenant data must be behind TenantMiddleware. Use route groups or apply the middleware globally. Calling TenantScope on a route that is not behind the middleware panics in development, surfacing the misconfiguration early.

API Resources

API Resources provide a transformation layer between your database models and the JSON responses your API returns. They decouple your database schema from your API contract, letting you control exactly which fields are exposed, how they're named, and under what conditions they appear.

Basic Usage

Derive Macro

The simplest way to create a resource is with #[derive(ApiResource)]:

#![allow(unused)]
fn main() {
use ferro::ApiResource;

#[derive(ApiResource)]
pub struct UserResource {
    pub id: i32,
    pub name: String,
    pub email: String,
}
}

This generates a Resource trait implementation that serializes id, name, and email into a JSON object.

Model Conversion

Link a resource to a database model with the model attribute to generate a From<Model> implementation:

#![allow(unused)]
fn main() {
use ferro::ApiResource;

#[derive(ApiResource)]
#[resource(model = "crate::models::entities::users::Model")]
pub struct UserResource {
    pub id: i32,
    pub name: String,
    pub email: String,
    #[resource(skip)]
    pub password: String,
    #[resource(skip)]
    pub remember_token: Option<String>,
    #[resource(skip)]
    pub created_at: String,
    #[resource(skip)]
    pub updated_at: String,
}
}

The struct must include all fields from the model. Use #[resource(skip)] to exclude fields from JSON output while keeping them available programmatically.

Field Attributes

#![allow(unused)]
fn main() {
use ferro::ApiResource;

#[derive(ApiResource)]
pub struct ProfileResource {
    pub id: i32,
    #[resource(rename = "display_name")]
    pub name: String,
    pub email: String,
    #[resource(skip)]
    pub password_hash: String,
}
}

Output: {"id": 1, "display_name": "Alice", "email": "alice@example.com"}

ResourceMap Builder

For conditional fields or complex logic, implement the Resource trait manually using ResourceMap:

#![allow(unused)]
fn main() {
use ferro::{Resource, ResourceMap, Request};
use serde_json::json;

struct UserResource {
    id: i32,
    name: String,
    email: String,
    is_admin: bool,
    internal_notes: Option<String>,
}

impl Resource for UserResource {
    fn to_resource(&self, _req: &Request) -> serde_json::Value {
        ResourceMap::new()
            .field("id", json!(self.id))
            .field("name", json!(self.name))
            .when("email", self.is_admin, || json!(self.email))
            .when_some("notes", &self.internal_notes)
            .merge_when(self.is_admin, || vec![
                ("role", json!("admin")),
                ("permissions", json!(["read", "write", "delete"])),
            ])
            .build()
    }
}
}

Builder Methods

All methods preserve insertion order in the output.

Response Helpers

The Resource trait provides response methods for common patterns:

#![allow(unused)]
fn main() {
use ferro::Resource;

// Direct JSON response
let response = resource.to_response(&req);
// Output: {"id": 1, "name": "Alice", "email": "alice@example.com"}

// Wrapped in data envelope
let response = resource.to_wrapped_response(&req);
// Output: {"data": {"id": 1, "name": "Alice", "email": "alice@example.com"}}

// Wrapped with additional top-level fields
let response = resource.to_response_with(&req, json!({"meta": {"version": "v1"}}));
// Output: {"data": {"id": 1, ...}, "meta": {"version": "v1"}}
}

Handler Integration

Use resources in handlers by converting models and calling response helpers:

#![allow(unused)]
fn main() {
use ferro::{handler, Auth, HttpResponse, Request, Resource, Response};
use crate::resources::UserResource;
use crate::models::users;

#[handler]
pub async fn profile(req: Request) -> Response {
    let user = Auth::user_as::<users::Model>()
        .await?
        .ok_or_else(|| HttpResponse::json(
            serde_json::json!({"message": "Unauthenticated."})
        ).status(401))?;

    let resource = UserResource::from(user);
    Ok(resource.to_wrapped_response(&req))
}
}

The From<Model> implementation (generated by the model attribute) handles the conversion. The to_wrapped_response method produces a {"data": {...}} envelope.

CLI Scaffolding

Generate a new resource with the CLI:

# Basic resource
ferro make:resource UserResource

# With model attribute for From<Model> generation
ferro make:resource UserResource --model entities::users::Model

# Name without "Resource" suffix is auto-appended
ferro make:resource User
# Creates UserResource in src/resources/user_resource.rs

The generated file includes the derive macro template with commented examples for rename and skip attributes.

When to Use

Derive macro (#[derive(ApiResource)]):

• Simple field selection from a model
• Static field renaming
• Excluding sensitive fields (passwords, tokens)

Manual ResourceMap:

• Conditional fields based on user role or request context
• Computed fields not present in the model
• Merging data from multiple sources
• Dynamic field inclusion logic

Resource Collections

ResourceCollection wraps a Vec<T: Resource> and produces a standard JSON envelope. Use it for any endpoint returning a list of resources.

Simple Collection

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Resource, ResourceCollection, Response};
use crate::resources::UserResource;

#[handler]
pub async fn index(req: Request) -> Response {
    let db = req.db();
    let users = User::find().all(db).await?;

    let resources: Vec<UserResource> = users.into_iter()
        .map(UserResource::from)
        .collect();

    let collection = ResourceCollection::new(resources);
    Ok(collection.to_response(&req))
}
}

Output:

{
  "data": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ]
}

Additional Metadata

Add extra top-level fields alongside data with .additional():

#![allow(unused)]
fn main() {
let collection = ResourceCollection::new(resources)
    .additional(json!({"meta": {"version": "v1"}}));

Ok(collection.to_response(&req))
// Output: {"data": [...], "meta": {"version": "v1"}}
}

Collection Mapping Shortcut

Resource::collection() maps a slice of resources to their JSON representations without constructing a full ResourceCollection:

#![allow(unused)]
fn main() {
let users: Vec<UserResource> = /* ... */;
let json_values = UserResource::collection(&users, &req);
// Returns: Vec<serde_json::Value>
}

Pagination

PaginationMeta computes page metadata and ResourceCollection::paginated() produces the standard paginated envelope. Integrates with SeaORM's PaginatorTrait.

PaginationMeta

#![allow(unused)]
fn main() {
use ferro::PaginationMeta;

let meta = PaginationMeta::new(page, per_page, total);
}

PaginationMeta::new() accepts a 1-indexed page number (the value from API query parameters). It computes last_page, from, and to automatically. SeaORM's fetch_page() is 0-indexed -- pass page - 1 to SeaORM and the raw page to PaginationMeta.

Paginated Handler

#![allow(unused)]
fn main() {
use ferro::{handler, PaginationMeta, Request, Resource, ResourceCollection, Response};
use sea_orm::PaginatorTrait;
use crate::resources::UserResource;

#[handler]
pub async fn index(req: Request) -> Response {
    let db = req.db();
    let page: u64 = req.query("page").unwrap_or(1);
    let per_page: u64 = req.query("per_page").unwrap_or(15);

    let paginator = User::find()
        .order_by_desc(users::Column::Id)
        .paginate(db, per_page);

    let items = paginator.fetch_page(page - 1).await?;  // 0-indexed
    let total = paginator.num_items().await?;

    let resources: Vec<UserResource> = items.into_iter()
        .map(UserResource::from)
        .collect();

    let meta = PaginationMeta::new(page, per_page, total);  // 1-indexed
    Ok(ResourceCollection::paginated(resources, meta).to_response(&req))
}
}

JSON Output Format

{
  "data": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "/users?page=1",
    "last": "/users?page=3",
    "prev": null,
    "next": "/users?page=2"
  }
}

Pagination links are relative URLs. Existing query parameters (e.g., sort=name) are preserved in links.

Relationship Inclusion

Ferro uses explicit batch-loading for relationships. All related data is loaded before resource construction -- never inside to_resource(). This prevents N+1 queries by design.

when_loaded (belongs_to / has_one)

when_loaded() looks up a key in a HashMap. If the key exists, the field is included in the output. If absent, the field is omitted.

#![allow(unused)]
fn main() {
use ferro::{Resource, ResourceMap, Request};
use std::collections::HashMap;
use serde_json::{json, Value};

struct PostResource {
    post: posts::Model,
    authors: HashMap<i32, users::Model>,
}

impl Resource for PostResource {
    fn to_resource(&self, req: &Request) -> Value {
        ResourceMap::new()
            .field("id", json!(self.post.id))
            .field("title", json!(self.post.title))
            .when_loaded("author", &self.post.author_id, &self.authors, |user| {
                json!({"id": user.id, "name": &user.name})
            })
            .build()
    }
}
}

when_loaded_many (has_many)

when_loaded_many() operates on HashMap<K, Vec<M>>. An empty vec is still included (loaded but empty); a missing key means the field is omitted entirely.

#![allow(unused)]
fn main() {
struct UserResource {
    user: users::Model,
    posts: HashMap<i32, Vec<posts::Model>>,
}

impl Resource for UserResource {
    fn to_resource(&self, req: &Request) -> Value {
        ResourceMap::new()
            .field("id", json!(self.user.id))
            .field("name", json!(self.user.name))
            .when_loaded_many("posts", &self.user.id, &self.posts, |items| {
                json!(items.iter().map(|p| {
                    json!({"id": p.id, "title": &p.title})
                }).collect::<Vec<_>>())
            })
            .build()
    }
}
}

Complete Paginated Handler with Relationships

#![allow(unused)]
fn main() {
use ferro::{handler, PaginationMeta, Request, Resource, ResourceCollection, ResourceMap, Response};
use sea_orm::PaginatorTrait;
use std::collections::HashMap;
use serde_json::{json, Value};

struct UserWithPostsResource {
    user: users::Model,
    posts_map: HashMap<i32, Vec<posts::Model>>,
}

impl Resource for UserWithPostsResource {
    fn to_resource(&self, _req: &Request) -> Value {
        ResourceMap::new()
            .field("id", json!(self.user.id))
            .field("name", json!(self.user.name))
            .when_loaded_many("posts", &self.user.id, &self.posts_map, |items| {
                json!(items.iter().map(|p| {
                    json!({"id": p.id, "title": &p.title})
                }).collect::<Vec<_>>())
            })
            .build()
    }
}

#[handler]
pub async fn index(req: Request) -> Response {
    let db = req.db();
    let page: u64 = req.query("page").unwrap_or(1);
    let per_page: u64 = 15;

    // 1. Paginate parent entity
    let paginator = User::find()
        .order_by_asc(users::Column::Id)
        .paginate(db, per_page);
    let users = paginator.fetch_page(page - 1).await?;
    let total = paginator.num_items().await?;

    // 2. Batch load relations for this page
    let user_ids: Vec<i32> = users.iter().map(|u| u.id).collect();
    let posts_map: HashMap<i32, Vec<posts::Model>> = Post::find()
        .filter(posts::Column::UserId.is_in(user_ids))
        .all(db)
        .await?
        .into_iter()
        .fold(HashMap::new(), |mut map, post| {
            map.entry(post.user_id).or_default().push(post);
            map
        });

    // 3. Map to resources with relations
    let resources: Vec<UserWithPostsResource> = users.into_iter()
        .map(|u| UserWithPostsResource {
            user: u,
            posts_map: posts_map.clone(),
        })
        .collect();

    // 4. Return paginated collection
    let meta = PaginationMeta::new(page, per_page, total);
    Ok(ResourceCollection::paginated(resources, meta).to_response(&req))
}
}

Anti-Patterns

N+1 inside to_resource(): Never call database queries inside to_resource(). All data must be loaded before resource construction.

#![allow(unused)]
fn main() {
// BAD: queries the database for every resource
impl Resource for UserResource {
    fn to_resource(&self, req: &Request) -> Value {
        let posts = Post::find()  // N+1 query!
            .filter(posts::Column::UserId.eq(self.user.id))
            .all(db).await;
        // ...
    }
}
}

Paginating joined queries: SeaORM's find_with_related() (SelectTwoMany) does not support .paginate(). Always paginate the parent entity first, then batch-load relations for the fetched page.

#![allow(unused)]
fn main() {
// BAD: won't compile
let results = User::find()
    .find_with_related(Post)
    .paginate(db, 15);  // SelectTwoMany has no PaginatorTrait

// GOOD: paginate parent, then batch load
let users = User::find().paginate(db, 15).fetch_page(0).await?;
// Then load posts for these users in a second query

# MCP Tools

Use `list_resources` to discover all API resource types defined in the project.

## `list_resources`

Returns all structs that implement the `Resource` trait, including their fields, any `skip` or `rename` annotations, and the model they wrap. Use this to understand what data is exposed in API responses before modifying a resource or adding a new endpoint.
}

REST API Scaffold

Ferro generates a production-ready REST API from existing models with one command. The scaffold includes CRUD controllers, API key authentication, rate limiting, OpenAPI documentation, and request validation types.

Quick Start

# Generate API for all models
ferro make:api --all

# Generate for specific models
ferro make:api User Post

# Skip confirmation prompts
ferro make:api --all --yes

After generation, wire the scaffold into your application:

1. Add mod api; to src/main.rs or src/lib.rs
2. Register api_routes() in your route configuration
3. Register docs_routes() for API documentation
4. Register ApiKeyProviderImpl as a service: App::bind::<dyn ApiKeyProvider>(Box::new(ApiKeyProviderImpl));
5. Run ferro db:migrate to create the api_keys table
6. Generate your first API key programmatically

Generated Files

ferro make:api generates the following files for each model:

Infrastructure files (generated once):

Existing files are never overwritten. If a file already exists, it is skipped with an info message.

API Key Authentication

Key Format

API keys follow the fe_{env}_{random} pattern:

• fe_live_ prefix for production keys
• fe_test_ prefix for test/development keys
• 43 random base62 characters for the secret portion

Full key length: 51 characters (e.g., fe_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcde).

Generating Keys

#![allow(unused)]
fn main() {
use ferro::generate_api_key;

let key = generate_api_key("live");

// Show the raw key to the user exactly once
println!("Your API key: {}", key.raw_key);

// Store these in the database
// key.prefix — first 16 chars, used for DB lookup (unhashed)
// key.hashed_key — SHA-256 hex digest, used for verification
}

The raw key is never stored. After creation, only the prefix and hash are persisted. If the user loses the key, a new one must be generated.

Storage Schema

The generated api_keys migration creates:

An index on prefix enables fast key lookup.

Verification Flow

1. Extract Bearer {key} from the Authorization header
2. Look up the key record by prefix (first 16 characters)
3. Check revocation (revoked_at IS NULL)
4. Check expiry (expires_at not passed)
5. Constant-time SHA-256 hash comparison via subtle::ConstantTimeEq
6. Check required scopes against granted scopes
7. Store ApiKeyInfo in request extensions for downstream handlers

ApiKeyProvider Trait

The middleware resolves an ApiKeyProvider from the service container. Implement this trait to connect to any key store:

#![allow(unused)]
fn main() {
use ferro::{async_trait, ApiKeyProvider, ApiKeyInfo};

pub struct MyKeyProvider;

#[async_trait]
impl ApiKeyProvider for MyKeyProvider {
    async fn verify_key(&self, raw_key: &str) -> Result<ApiKeyInfo, ()> {
        let prefix = &raw_key[..16.min(raw_key.len())];
        // Look up by prefix, verify hash, return metadata
        // ...
        Ok(ApiKeyInfo {
            id: record.id,
            name: record.name,
            scopes: vec!["read".to_string(), "write".to_string()],
        })
    }
}
}

Register in bootstrap:

#![allow(unused)]
fn main() {
App::bind::<dyn ApiKeyProvider>(Box::new(MyKeyProvider));
}

The generated ApiKeyProviderImpl in src/providers/api_key_provider.rs provides a complete database-backed implementation with revocation and expiry checks.

API Key Management

CLI Key Generation

Generate API keys from the command line without writing code:

ferro make:api-key "My App"

Options:

Example with test environment:

ferro make:api-key "Dev Bot" --env test

Output includes:

• Raw key (e.g., fe_live_aBcDeFg...) -- shown once, store securely
• Prefix -- first 16 characters, used for database lookup
• Hashed key -- SHA-256 hex digest for verification
• SQL insert -- ready-to-run INSERT statement
• Rust snippet -- copy-paste SeaORM code

The raw key is displayed only once. If lost, generate a new key.

Creating Keys Programmatically

#![allow(unused)]
fn main() {
use ferro::generate_api_key;
use sea_orm::{EntityTrait, Set};
use crate::models::api_key;

let key = generate_api_key("live");

let record = api_key::ActiveModel {
    name: Set("Production Bot".to_string()),
    prefix: Set(key.prefix),
    hashed_key: Set(key.hashed_key),
    scopes: Set(Some(serde_json::to_string(&["read", "write"]).expect("serialization is infallible"))),
    ..Default::default()
};

api_key::Entity::insert(record)
    .exec(&db)
    .await?;

// Return key.raw_key to the user (show once)
}

Revoking Keys

Set revoked_at to the current timestamp. The provider checks this before verifying the hash:

#![allow(unused)]
fn main() {
use sea_orm::{EntityTrait, Set, IntoActiveModel};
use chrono::Utc;

let mut key: api_key::ActiveModel = record.into_active_model();
key.revoked_at = Set(Some(Utc::now()));
key.update(&db).await?;
}

Key Expiration

Set expires_at when creating the key. The provider rejects keys past their expiration:

#![allow(unused)]
fn main() {
use chrono::{Utc, Duration};

let record = api_key::ActiveModel {
    expires_at: Set(Some(Utc::now() + Duration::days(90))),
    // ...
    ..Default::default()
};
}

Scope-Based Permissions

Scopes are stored as a JSON array in the scopes column. The middleware checks required scopes against granted scopes:

#![allow(unused)]
fn main() {
use ferro::ApiKeyMiddleware;

// Require any valid API key
group!("/api/v1")
    .middleware(ApiKeyMiddleware::new())
    .routes([...]);

// Require specific scopes
group!("/api/v1/admin")
    .middleware(ApiKeyMiddleware::scopes(&["admin"]))
    .routes([...]);
}

A key with ["*"] in its scopes bypasses all scope checks (wildcard).

Accessing Key Info in Handlers

After middleware verification, ApiKeyInfo is available in request extensions:

#![allow(unused)]
fn main() {
use ferro::{handler, Request, Response, HttpResponse, ApiKeyInfo};

#[handler]
pub async fn index(req: Request) -> Response {
    let key_info = req.get::<ApiKeyInfo>().ok_or_else(|| HttpResponse::unauthorized())?;
    println!("Request from: {} (scopes: {:?})", key_info.name, key_info.scopes);
    // ...
}
}

Field Selection

By default, make:api auto-excludes sensitive fields from generated API resources. Fields matching these patterns are omitted:

• password, password_hash, hashed_password
• secret, token, api_key, hashed_key
• remember_token

Matching is case-insensitive, exact match only. A field named token_count is not excluded.

Custom Exclusion

Exclude additional fields with --exclude:

ferro make:api --all --exclude password_hash,secret_token

Multiple fields are comma-separated. Custom exclusions stack with auto-exclusion.

Including All Fields

Override auto-exclusion with --include-all:

ferro make:api --all --include-all

When --include-all is set, no auto-exclusion is applied. Custom --exclude fields are still honored:

# Include all fields except internal_notes
ferro make:api --all --include-all --exclude internal_notes

Verifying Your API

After scaffolding and wiring routes, verify the setup with ferro api:check:

ferro api:check

The command runs four sequential checks:

1. Server connectivity -- can the CLI reach your server?
2. Spec available -- does /api/openapi.json return a response?
3. Spec valid -- is the response a valid OpenAPI 3.x document?
4. Auth working -- does the API key authenticate successfully?

With Authentication

ferro api:check --api-key fe_live_...

Custom URL

ferro api:check --url http://localhost:3000

Custom Spec Path

ferro api:check --spec-path /api/docs/openapi.json

On success, api:check prints a ready-to-copy ferro-api-mcp command for MCP integration.

Endpoints

The generated routes follow standard REST conventions under /api/v1/:

List Resources

GET /api/v1/{resource}?page=1&per_page=15

curl -H "Authorization: Bearer fe_live_..." \
     "https://example.com/api/v1/users?page=1&per_page=15"

Response:

{
  "data": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 42,
    "last_page": 3,
    "from": 1,
    "to": 15
  },
  "links": {
    "first": "/api/v1/users?page=1",
    "last": "/api/v1/users?page=3",
    "prev": null,
    "next": "/api/v1/users?page=2"
  }
}

per_page is capped at 100.

Create Resource

POST /api/v1/{resource}

curl -X POST -H "Authorization: Bearer fe_live_..." \
     -H "Content-Type: application/json" \
     -d '{"name": "Charlie", "email": "charlie@example.com"}' \
     "https://example.com/api/v1/users"

Response (201):

{
  "data": {"id": 3, "name": "Charlie", "email": "charlie@example.com"}
}

Show Resource

GET /api/v1/{resource}/{id}

curl -H "Authorization: Bearer fe_live_..." \
     "https://example.com/api/v1/users/1"

Response:

{
  "data": {"id": 1, "name": "Alice", "email": "alice@example.com"}
}

Update Resource

PUT /api/v1/{resource}/{id}

curl -X PUT -H "Authorization: Bearer fe_live_..." \
     -H "Content-Type: application/json" \
     -d '{"name": "Alice Smith"}' \
     "https://example.com/api/v1/users/1"

Response:

{
  "data": {"id": 1, "name": "Alice Smith", "email": "alice@example.com"}
}

Update handlers use conditional field assignment (if let Some), so only included fields are modified.

Delete Resource

DELETE /api/v1/{resource}/{id}

curl -X DELETE -H "Authorization: Bearer fe_live_..." \
     "https://example.com/api/v1/users/1"

Response:

{"message": "Deleted"}

OpenAPI Documentation

The scaffold includes auto-generated OpenAPI 3.0 documentation:

How Specs Are Built

The OpenAPI spec builder reads from the Ferro route registry:

1. Filters routes matching the /api/ prefix
2. Generates operations with auto-summaries (e.g., GET /api/v1/users becomes "List users")
3. Extracts path parameters from {param} patterns
4. Groups endpoints by resource name as tags
5. Adds API key security scheme (Authorization header)

Specs and HTML are cached via OnceLock -- generated once on first request, zero cost per subsequent request.

Configuration

#![allow(unused)]
fn main() {
use ferro::{OpenApiConfig, build_openapi_spec, get_registered_routes};

let config = OpenApiConfig {
    title: "My API".to_string(),
    version: "1.0.0".to_string(),
    description: Some("Application API".to_string()),
    api_prefix: "/api/".to_string(),
};

let spec = build_openapi_spec(&config, &get_registered_routes());
}

The generated src/api/docs.rs reads the APP_NAME environment variable for the title.

Rate Limiting

Generated API routes include Throttle::named("api") middleware. Define the limiter in bootstrap.rs:

#![allow(unused)]
fn main() {
use ferro::{RateLimiter, Limit};

RateLimiter::define("api", |_req| {
    Limit::per_minute(60)
});
}

The default configuration allows 60 requests per minute per client IP. Adjust the limit or segment by API key:

#![allow(unused)]
fn main() {
use ferro::{ApiKeyInfo, RateLimiter, Limit};

RateLimiter::define("api", |req| {
    match req.get::<ApiKeyInfo>() {
        Some(key) => Limit::per_minute(1000).by(format!("key:{}", key.id)),
        None => Limit::per_minute(60),
    }
});
}

See Rate Limiting for full documentation on time windows, multiple limits, custom responses, and cache backends.

MCP Tools

Ferro's MCP server provides four CRUD tools for direct database access without the HTTP API layer. These enable AI agents to manage application data programmatically.

crud_create

Create a new record for any model:

{
  "model": "User",
  "data": {"name": "Alice", "email": "alice@example.com"}
}

Returns the created record as JSON.

crud_list

List records with optional filtering and pagination:

{
  "model": "User",
  "filters": {"status": "active"},
  "page": 1,
  "per_page": 25
}

Returns records array with total, page, and per_page metadata. Per-page is capped at 100.

crud_update

Update an existing record by primary key:

{
  "model": "User",
  "id": 1,
  "data": {"name": "Alice Smith"}
}

Returns the updated record as JSON.

crud_delete

Delete a record by primary key:

{
  "model": "User",
  "id": 1
}

Returns a confirmation message.

How It Works

The MCP CRUD tools:

1. Parse model metadata via syn AST visitor (same pattern as ferro make:api)
2. Validate field names against the model struct definition
3. Build parameterized SQL using sea_orm::Statement::from_sql_and_values
4. Execute against the project's configured database
5. Use RETURNING * on Postgres, last_insert_rowid() fallback on SQLite

All queries use parameterized statements to prevent SQL injection. Timestamp fields (created_at, updated_at) are excluded from required-field validation since they typically have database defaults.

Customization

Adding Custom Endpoints

Add routes to the generated src/api/routes.rs:

#![allow(unused)]
fn main() {
pub fn api_routes() -> GroupBuilder {
    group!("/api/v1")
        .middleware(ApiKeyMiddleware::new())
        .middleware(Throttle::named("api"))
        .routes([
            // Generated CRUD routes...
            get!("/users", user_api::index),
            post!("/users", user_api::store),
            // Custom endpoints
            post!("/users/:id/activate", user_api::activate),
            get!("/stats", stats_api::overview),
        ])
}
}

Modifying Response Format

Edit the generated resource in src/resources/{model}_resource.rs. Use ResourceMap for conditional fields:

#![allow(unused)]
fn main() {
impl Resource for UserResource {
    fn to_resource(&self, _req: &Request) -> serde_json::Value {
        ResourceMap::new()
            .field("id", json!(self.id))
            .field("name", json!(self.name))
            .when("email", self.is_admin, || json!(self.email))
            .build()
    }
}
}

See API Resources for full documentation on ResourceMap, conditional fields, and relationship inclusion.

Adding Relationships

Load related data in the controller before constructing resources:

#![allow(unused)]
fn main() {
#[handler]
pub async fn show(req: Request, user: user::Model) -> Response {
    let db = ferro::DB::connection()
        .map_err(|e| HttpResponse::json(json!({"error": e.to_string()})).status(500))?;
    let posts = Post::find()
        .filter(posts::Column::UserId.eq(user.id))
        .all(&db)
        .await
        .map_err(|e| HttpResponse::json(json!({"error": e.to_string()})).status(500))?;

    let mut resource = UserResource::from(&user);
    // Add posts to the response
    // ...
    Ok(resource.to_wrapped_response(&req))
}
}

Custom Validation Rules

Edit the generated request types in src/requests/{model}_request.rs:

#![allow(unused)]
fn main() {
#[request]
pub struct CreateUserRequest {
    #[validate(length(min = 1, max = 255))]
    pub name: String,
    #[validate(email)]
    pub email: String,
    #[validate(length(min = 8))]
    pub password: String,
}
}

See Validation for all available validation rules.

Custom Scopes

Define application-specific scopes and check them in handlers:

#![allow(unused)]
fn main() {
// In route registration
group!("/api/v1/admin")
    .middleware(ApiKeyMiddleware::scopes(&["admin"]))
    .routes([...]);

// In handler, check additional granular permissions
#[handler]
pub async fn destroy(req: Request, user: user::Model) -> Response {
    let key = req.get::<ApiKeyInfo>().ok_or_else(|| HttpResponse::unauthorized())?;
    if !key.scopes.contains(&"users:delete".to_string()) {
        return Err(HttpResponse::json(json!({"error": "Missing users:delete scope"})).status(403));
    }
    // proceed with deletion
}
}

Security

MCP Bridge (ferro-api-mcp)

ferro-api-mcp is a standalone binary that bridges any Ferro REST API to the Model Context Protocol (MCP). AI agents can discover and call your API endpoints as MCP tools without custom integration code.

Quick Start Workflow

From scaffold to working MCP integration in seven steps:

1. Scaffold the API:

   ferro make:api --all
   

2. Wire routes in src/main.rs:

   #![allow(unused)]
   fn main() {
   mod api;
   // In route registration:
   api::routes::api_routes()
   api::docs::docs_routes()
   }

3. Run the migration:

   ferro db:migrate
   

4. Generate an API key:

   ferro make:api-key "My Key"
   

   Save the raw key -- it is shown only once.

5. Start the server:

   cargo run
   

6. Verify the setup:

   ferro api:check --api-key fe_live_...
   

7. Add MCP config to your AI agent (see MCP Host Configuration below).

How It Works

1. Reads the OpenAPI spec from your Ferro app's /api/docs/openapi.json endpoint
2. Converts each API operation into an MCP tool with typed input schemas
3. Runs as a stdio MCP server that AI agents connect to
4. Supports x-mcp vendor extensions for customizing tool names, descriptions, hints, and visibility

Prerequisites

• A Ferro app with make:api scaffold (see REST API)
• The API running and accessible (e.g., ferro serve on localhost:8080)
• An API key generated via ferro make:api setup

Setup

Building

cargo build --release -p ferro-api-mcp

Binary location: target/release/ferro-api-mcp

CLI Options

ferro-api-mcp [OPTIONS] --spec-url <URL>

Options:
  --spec-url <URL>    URL to fetch the OpenAPI spec from
  --api-key <KEY>     API key for Authorization header (optional)
  --base-url <URL>    Override the base URL for API calls
  --log-level <LEVEL> Log level: debug, info, warn, error [default: info]
  --dry-run           Validate spec and print tool summary without starting server

Validating Setup

ferro-api-mcp --spec-url http://localhost:8080/api/docs/openapi.json \
  --api-key your-api-key \
  --dry-run

Expected output:

Fetched spec: 4521 bytes

ferro-api-mcp v0.1.0
API: My App
Base URL: http://localhost:8080/
Tools: 5 registered

Tools:
  - list_users: List all users with pagination.
  - create_user: Create a new user.
  - show_user: Retrieve a single user by ID.
  - update_user: Update an existing user.
  - delete_user: Delete a user by ID.

Dry run complete. 5 tools validated.

MCP Host Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "my-app": {
      "command": "/path/to/ferro-api-mcp",
      "args": [
        "--spec-url", "http://localhost:8080/api/docs/openapi.json",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Claude Code

Add to .claude.json (project-level) or ~/.claude.json (global):

{
  "mcpServers": {
    "my-app": {
      "command": "/path/to/ferro-api-mcp",
      "args": [
        "--spec-url", "http://localhost:8080/api/docs/openapi.json",
        "--api-key", "your-api-key"
      ]
    }
  }
}

Cursor

Add via Settings > MCP Servers:

{
  "my-app": {
    "command": "/path/to/ferro-api-mcp",
    "args": [
      "--spec-url", "http://localhost:8080/api/docs/openapi.json",
      "--api-key", "your-api-key"
    ]
  }
}

x-mcp Extensions

Ferro's build_openapi_spec() automatically emits x-mcp vendor extensions on each operation. ferro-api-mcp reads these at startup to customize tool behavior.

These are emitted automatically by the framework. No configuration is needed. ferro-api-mcp uses the extension values as overrides, falling back to auto-generated names and descriptions when extensions are absent.

Route Customization

Override the auto-generated MCP metadata on individual routes using builder methods:

#![allow(unused)]
fn main() {
use ferro::{group, get, post, delete, ApiKeyMiddleware};

group!("/api/v1")
    .middleware(ApiKeyMiddleware::new())
    .routes([
        get!("/users", user_api::index)
            .mcp_tool_name("search_users")
            .mcp_description("Search users by name or email with pagination")
            .mcp_hint("Use page and per_page params for large result sets"),

        post!("/users", user_api::store)
            .mcp_description("Create a new user account"),

        delete!("/users/:id/sessions", user_api::clear_sessions)
            .mcp_hidden(),  // Exclude from MCP tools
    ])
}

Available Methods

Group-Level Defaults

Set MCP defaults at the group level. Route-level overrides take precedence:

#![allow(unused)]
fn main() {
group!("/api/v1/internal")
    .mcp_hidden()  // Hide all routes in this group
    .routes([
        get!("/health", internal_api::health),
        get!("/metrics", internal_api::metrics),
    ])
}

How It Works

Customizations are stored in the route registry and emitted as x-mcp vendor extensions in the OpenAPI spec. ferro-api-mcp reads these extensions at startup, using them as overrides over auto-generated values.

Troubleshooting

Base URL Resolution

ferro-api-mcp resolves the API base URL in this order:

1. --base-url flag (explicit override)
2. servers[0].url from the OpenAPI spec
3. Origin of the --spec-url (scheme + host + port)

This means most setups need only --spec-url. Use --base-url when the API server is behind a reverse proxy or on a different host than the spec endpoint.

Rate Limiting

Ferro provides cache-backed rate limiting through the Throttle middleware. Define named limiters with dynamic, per-request rules or apply inline limits directly on routes. Rate counters use the framework's Cache facade -- in-memory by default, Redis for multi-server deployments.

Defining Rate Limiters

Register named limiters in bootstrap.rs (or a service provider). Each limiter receives the incoming Request and returns one or more Limit values.

Basic Limiter

#![allow(unused)]
fn main() {
use ferro::{RateLimiter, Limit};

pub fn register_rate_limiters() {
    RateLimiter::define("api", |_req| {
        Limit::per_minute(60)
    });
}
}

Auth-Based Segmentation

Use the request to vary limits by authentication state:

#![allow(unused)]
fn main() {
use ferro::{RateLimiter, Limit, Auth};

RateLimiter::define("api", |req| {
    match Auth::id() {
        Some(id) => Limit::per_minute(120).by(format!("user:{}", id)),
        None => Limit::per_minute(60),
    }
});
}

Unauthenticated requests default to the client IP as the rate limit key. Authenticated users get a higher limit keyed by their user ID.

Multiple Limits

Return a Vec<Limit> to enforce several windows simultaneously. The first limit exceeded triggers a 429 response.

#![allow(unused)]
fn main() {
use ferro::{RateLimiter, Limit};

RateLimiter::define("login", |req| {
    let ip = req.header("X-Forwarded-For")
        .and_then(|s| s.split(',').next())
        .unwrap_or("unknown")
        .trim()
        .to_string();

    vec![
        Limit::per_minute(500),           // Global burst cap
        Limit::per_minute(5).by(ip),      // Per-IP cap
    ]
});
}

Applying to Routes

Named Throttle

Reference a registered limiter by name with Throttle::named():

#![allow(unused)]
fn main() {
use ferro::Throttle;

routes! {
    group!("/api", {
        get!("/users", controllers::users::index),
        get!("/users/{id}", controllers::users::show),
    }).middleware(Throttle::named("api")),

    group!("/auth", {
        post!("/login", controllers::auth::login),
    }).middleware(Throttle::named("login")),
}
}

Inline Throttle

For simple cases that do not need a named registration:

#![allow(unused)]
fn main() {
use ferro::Throttle;

get!("/health", controllers::health::check)
    .middleware(Throttle::per_minute(10))
}

Inline limits support the same time windows: per_second, per_minute, per_hour, per_day.

The Limit Struct

Limit describes how many requests are allowed in a time window.

Constructors

Key Segmentation

By default, rate limits are keyed by client IP (from X-Forwarded-For or X-Real-IP headers). Override with .by():

#![allow(unused)]
fn main() {
// Per-user limit
Limit::per_minute(120).by(format!("user:{}", user_id))

// Per-API-key limit
Limit::per_minute(1000).by(api_key)
}

Custom 429 Response

Override the default JSON error with .response():

#![allow(unused)]
fn main() {
use ferro::HttpResponse;

Limit::per_minute(60).response(|| {
    HttpResponse::json(serde_json::json!({
        "error": "Quota exceeded",
        "upgrade_url": "https://example.com/pricing"
    })).status(429)
})
}

Response Headers

Every response from a throttled route includes rate limit headers:

When a request is rejected (429), an additional header is included:

Example Headers

Successful request:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 38

Rate limited request (429):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 38
Retry-After: 38

Cache Backend

Rate limiting uses the framework's Cache facade for counter storage. The algorithm is fixed-window counters with atomic INCR + EXPIRE operations.

# .env for multi-server deployments
CACHE_DRIVER=redis
REDIS_URL=redis://127.0.0.1:6379

Cache keys follow the pattern rate_limit:{name}:{identifier}:{window} and expire automatically after each window.

Fail-Open Behavior

Rate limiting is designed to never cause application errors:

• Cache unavailable: Requests are allowed with a warning logged to stderr.
• Named limiter not registered: Requests are allowed with a warning logged to stderr.
• Expire call fails: The counter still works; the key may persist longer than intended.

Rate limiting failures never produce 500 errors. The system prioritizes availability over strict enforcement.

MCP Tools

Use list_rate_limiters to inspect all configured rate limiters in the project.

list_rate_limiters

Returns all named rate limiters registered via RateLimiter::define(), including the limiter name, limit values, time windows, and which routes apply the limiter via Throttle::named(). Use this to audit rate limiting coverage before adding new API endpoints.

Database

Ferro provides a SeaORM-based database layer with Laravel-like API, automatic route model binding, fluent query builder, and testing utilities.

Configuration

Environment Variables

Configure database in your .env file:

# Database connection URL (required)
DATABASE_URL=postgres://user:pass@localhost:5432/mydb

# For SQLite:
# DATABASE_URL=sqlite://./database.db

# Connection pool settings
DB_MAX_CONNECTIONS=10
DB_MIN_CONNECTIONS=1
DB_CONNECT_TIMEOUT=30

# Enable SQL query logging
DB_LOGGING=false

Bootstrap Setup

In src/bootstrap.rs, configure the database:

#![allow(unused)]
fn main() {
use ferro::{Config, DB, DatabaseConfig};

pub async fn register() {
    // Register database configuration
    Config::register(DatabaseConfig::from_env());

    // Initialize the database connection
    DB::init().await.expect("Failed to connect to database");
}
}

Manual Configuration

#![allow(unused)]
fn main() {
use ferro::{Config, DB, DatabaseConfig};

// Build configuration programmatically
let config = DatabaseConfig::builder()
    .url("postgres://localhost/mydb")
    .max_connections(20)
    .min_connections(5)
    .connect_timeout(60)
    .logging(true)
    .build();

// Initialize with custom config
DB::init_with(config).await?;
}

Basic Usage

Getting a Connection

#![allow(unused)]
fn main() {
use ferro::DB;

// Get the database connection
let conn = DB::connection()?;

// Use with SeaORM queries
let users = User::find().all(conn.inner()).await?;

// Shorthand
let conn = DB::get()?;
}

Checking Connection Status

#![allow(unused)]
fn main() {
use ferro::DB;

if DB::is_connected() {
    let conn = DB::connection()?;
    // Perform database operations
}
}

Models

Ferro provides Laravel-like traits for SeaORM entities.

Defining a Model

#![allow(unused)]
fn main() {
use sea_orm::entity::prelude::*;
use ferro::{Model, ModelMut};

#[derive(Clone, Debug, DeriveEntityModel)]
#[sea_orm(table_name = "users")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
    pub email: String,
    pub created_at: DateTime,
    pub updated_at: DateTime,
}

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {}

impl ActiveModelBehavior for ActiveModel {}

// Add Ferro's Model traits for convenient methods
impl ferro::Model for Entity {}
impl ferro::ModelMut for Entity {}
}

Reading Records

#![allow(unused)]
fn main() {
use ferro::models::user;

// Find all records
let users = user::Entity::all().await?;

// Find by primary key
let user = user::Entity::find_by_pk(1).await?;

// Find or return error
let user = user::Entity::find_or_fail(1).await?;

// Get first record
let first = user::Entity::first().await?;

// Count all records
let count = user::Entity::count_all().await?;

// Check if any exist
if user::Entity::exists_any().await? {
    println!("Users exist!");
}
}

Creating Records

ActiveValue is re-exported from the ferro facade as ferro::ActiveValue, so generated and hand-written code can import it from ferro without a direct sea_orm dependency:

use ferro::ActiveValue; // equivalent to use sea_orm::ActiveValue

#![allow(unused)]
fn main() {
use sea_orm::Set;
use ferro::models::user;

let new_user = user::ActiveModel {
    name: Set("John Doe".to_string()),
    email: Set("john@example.com".to_string()),
    ..Default::default()
};

let user = user::Entity::insert_one(new_user).await?;
println!("Created user with id: {}", user.id);
}

Updating Records

#![allow(unused)]
fn main() {
use ferro::models::user::User;

// Find and update with builder pattern
let user = User::find_or_fail(1).await?;
let updated = user
    .update()
    .set_name("Updated Name")
    .save()
    .await?;
}

The UpdateBuilder tracks which fields were modified and only sends those to the database. It automatically updates the updated_at timestamp.

For nullable fields, use clear_*() to set a column to NULL:

#![allow(unused)]
fn main() {
let updated = user
    .update()
    .clear_bio()
    .save()
    .await?;
}

Deleting Records

#![allow(unused)]
fn main() {
use ferro::models::user;

// Delete by primary key
let rows_deleted = user::Entity::delete_by_pk(1).await?;
println!("Deleted {} rows", rows_deleted);
}

Save (Insert or Update)

#![allow(unused)]
fn main() {
use sea_orm::Set;
use ferro::models::user;

// Save will insert if no primary key, update if present
let model = user::ActiveModel {
    name: Set("Jane Doe".to_string()),
    email: Set("jane@example.com".to_string()),
    ..Default::default()
};

let saved = user::Entity::save_one(model).await?;
}

Query Builder

The fluent query builder provides an Eloquent-like API.

Basic Queries

#![allow(unused)]
fn main() {
use ferro::models::todo::{self, Column};

// Get all records
let todos = todo::Entity::query().all().await?;

// Get first record
let todo = todo::Entity::query().first().await?;

// Get first or error
let todo = todo::Entity::query().first_or_fail().await?;
}

Filtering

#![allow(unused)]
fn main() {
use ferro::models::todo::{self, Column};

// Single filter
let todos = todo::Entity::query()
    .filter(Column::Active.eq(true))
    .all()
    .await?;

// Multiple filters (AND)
let todo = todo::Entity::query()
    .filter(Column::Title.eq("My Task"))
    .filter(Column::Id.gt(5))
    .first()
    .await?;

// Using SeaORM conditions
use sea_orm::Condition;

let todos = todo::Entity::query()
    .filter(
        Condition::any()
            .add(Column::Priority.eq("high"))
            .add(Column::DueDate.lt(chrono::Utc::now()))
    )
    .all()
    .await?;
}

Ordering

#![allow(unused)]
fn main() {
use ferro::models::todo::{self, Column};

// Order ascending
let todos = todo::Entity::query()
    .order_by_asc(Column::Title)
    .all()
    .await?;

// Order descending
let todos = todo::Entity::query()
    .order_by_desc(Column::CreatedAt)
    .all()
    .await?;

// Multiple orderings
let todos = todo::Entity::query()
    .order_by_desc(Column::Priority)
    .order_by_asc(Column::Title)
    .all()
    .await?;
}

Pagination

#![allow(unused)]
fn main() {
use ferro::models::todo;

// Limit results
let todos = todo::Entity::query()
    .limit(10)
    .all()
    .await?;

// Offset and limit (pagination)
let page = 2;
let per_page = 10;

let todos = todo::Entity::query()
    .offset((page - 1) * per_page)
    .limit(per_page)
    .all()
    .await?;
}

Counting and Existence

#![allow(unused)]
fn main() {
use ferro::models::todo::{self, Column};

// Count matching records
let count = todo::Entity::query()
    .filter(Column::Active.eq(true))
    .count()
    .await?;

// Check if any exist
let has_active = todo::Entity::query()
    .filter(Column::Active.eq(true))
    .exists()
    .await?;
}

Advanced Queries

#![allow(unused)]
fn main() {
use ferro::models::todo;

// Get underlying SeaORM Select for advanced operations
let select = todo::Entity::query()
    .filter(Column::Active.eq(true))
    .into_select();

// Use with SeaORM directly
let conn = DB::connection()?;
let todos = select
    .join(JoinType::LeftJoin, todo::Relation::User.def())
    .all(conn.inner())
    .await?;
}

Route Model Binding

Ferro automatically resolves models from route parameters.

Automatic Binding

#![allow(unused)]
fn main() {
use ferro::{handler, json_response, Response};
use ferro::models::user;

// The 'user' parameter is automatically resolved from the route
#[handler]
pub async fn show(user: user::Model) -> Response {
    json_response!({ "name": user.name, "email": user.email })
}

// Route definition: get!("/users/{user}", controllers::user::show)
// The {user} parameter is parsed as the primary key and the model is fetched
}

How It Works

1. Route parameter {user} is extracted from the URL
2. The parameter value is parsed as the model's primary key type
3. The model is fetched from the database
4. If not found, a 404 response is returned automatically
5. If the parameter can't be parsed, a 400 response is returned

Custom Route Binding

For custom binding logic, implement the RouteBinding trait:

#![allow(unused)]
fn main() {
use ferro::{RouteBinding, FrameworkError};
use async_trait::async_trait;

#[async_trait]
impl RouteBinding for user::Model {
    fn param_name() -> &'static str {
        "user"
    }

    async fn from_route_param(value: &str) -> Result<Self, FrameworkError> {
        // Custom logic: find by email instead of ID
        let conn = DB::connection()?;
        user::Entity::find()
            .filter(user::Column::Email.eq(value))
            .one(conn.inner())
            .await?
            .ok_or_else(|| FrameworkError::model_not_found("User"))
    }
}
}

Migrations

Ferro uses SeaORM migrations with a timestamp-based naming convention.

Creating Migrations

# Create a new migration
ferro make:migration create_posts_table

# Creates: src/migrations/m20240115_143052_create_posts_table.rs

Migration Structure

#![allow(unused)]
fn main() {
use sea_orm_migration::prelude::*;

#[derive(DeriveMigrationName)]
pub struct Migration;

#[async_trait::async_trait]
impl MigrationTrait for Migration {
    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .create_table(
                Table::create()
                    .table(Posts::Table)
                    .if_not_exists()
                    .col(
                        ColumnDef::new(Posts::Id)
                            .integer()
                            .not_null()
                            .auto_increment()
                            .primary_key(),
                    )
                    .col(ColumnDef::new(Posts::Title).string().not_null())
                    .col(ColumnDef::new(Posts::Content).text().not_null())
                    .col(
                        ColumnDef::new(Posts::CreatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .col(
                        ColumnDef::new(Posts::UpdatedAt)
                            .timestamp()
                            .not_null()
                            .default(Expr::current_timestamp()),
                    )
                    .to_owned(),
            )
            .await
    }

    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
        manager
            .drop_table(Table::drop().table(Posts::Table).to_owned())
            .await
    }
}

#[derive(DeriveIden)]
enum Posts {
    Table,
    Id,
    Title,
    Content,
    CreatedAt,
    UpdatedAt,
}
}

Running Migrations

# Run all pending migrations
ferro db:migrate

# Rollback the last batch
ferro db:rollback

# Rollback all and re-run
ferro db:fresh

# Check migration status
ferro db:status

Testing

Ferro provides utilities for isolated database testing.

Test Database

#![allow(unused)]
fn main() {
use ferro::test_database;
use ferro::models::user;

#[tokio::test]
async fn test_create_user() {
    // Creates fresh in-memory SQLite with migrations
    let db = test_database!();

    // Your test code - DB::connection() automatically uses test database
    let new_user = user::ActiveModel {
        name: Set("Test User".to_string()),
        email: Set("test@example.com".to_string()),
        ..Default::default()
    };

    let user = user::Entity::insert_one(new_user).await.unwrap();
    assert!(user.id > 0);

    // Query directly
    let found = user::Entity::find_by_id(user.id)
        .one(db.conn())
        .await
        .unwrap();
    assert!(found.is_some());
}
}

Custom Migrator

#![allow(unused)]
fn main() {
use ferro::TestDatabase;

#[tokio::test]
async fn test_with_custom_migrator() {
    let db = TestDatabase::fresh::<my_crate::CustomMigrator>()
        .await
        .unwrap();

    // Test code here
}
}

Isolation

Each TestDatabase creates a completely isolated in-memory database:

• Fresh database for each test
• Migrations are run automatically
• No interference between tests
• Automatically cleaned up when dropped

Dependency Injection

Use the Database type alias with dependency injection:

#![allow(unused)]
fn main() {
use ferro::{injectable, Database};

#[injectable]
pub struct CreateUserAction {
    #[inject]
    db: Database,
}

impl CreateUserAction {
    pub async fn execute(&self, email: &str) -> Result<user::Model, Error> {
        let new_user = user::ActiveModel {
            email: Set(email.to_string()),
            ..Default::default()
        };

        new_user.insert(self.db.conn()).await
    }
}
}

Environment Variables Reference

Supported Databases

Best Practices

1. Use migrations - Never modify database schema manually
2. Implement Model traits - Get convenient static methods for free
3. Use QueryBuilder - Cleaner API than raw SeaORM queries
4. Leverage route binding - Automatic 404 handling for missing models
5. Test with test_database! - Isolated, repeatable tests
6. Use dependency injection - Cleaner code with #[inject] db: Database
7. Enable logging in development - DB_LOGGING=true for debugging
8. Set appropriate pool sizes - Match your expected concurrency

MCP Tools

Ferro provides seven database-focused MCP tools covering schema inspection, query execution, migration status, model analysis, and relationship mapping.

database_schema

• Returns: All tables with column names, types, nullability, defaults, and indexes
• When to use: Understand the current database structure; verify a migration ran correctly; check column types before writing a query

database_query

• Returns: Query results as JSON rows
• When to use: Run ad-hoc SELECT queries against the live database to inspect data; debug unexpected values; validate seeded test data. Read-only — does not support INSERT, UPDATE, or DELETE.

list_migrations

• Returns: All migration files with their status (applied or pending), applied-at timestamp, and the migration name
• When to use: Check whether pending migrations need to be run; verify the current migration state before deployment

list_models

• Returns: All SeaORM entity structs found in src/models/, with field names, types, and SeaORM column annotations
• When to use: Discover all models in the project; find the correct field names before writing a query or resource

explain_model

• Returns: Detailed breakdown of one model: fields, types, relations, and any Ferro trait implementations (Model, ModelMut, RouteBinding)
• When to use: Deep-dive into a single model's structure; verify that the correct traits are implemented; understand relation definitions

model_usages

• Returns: All locations in source code that reference a given model, grouped by file and usage type (query, insert, update, delete, relation)
• When to use: Understand how widely a model is used before changing its schema; find all query sites when adding a new filter condition

relation_map

• Returns: A graph of all model relationships: belongs-to, has-many, and many-to-many edges derived from SeaORM Relation enums
• When to use: Visualize the entity relationship diagram; verify that relations are defined correctly on both sides; plan batch loading strategies to avoid N+1 queries

Atomic Updates

The ferro-orm crate exposes GuardedUpdate<E>, a typed builder that compiles to a single UPDATE … WHERE … SQL statement. It replaces the hand-rolled read → check → write pattern wherever a column's value is conditionally mutated — counter decrements, status transitions, optimistic concurrency checks. The database engine's per-statement atomicity (SQLite serial writer, Postgres READ COMMITTED) is the entire correctness mechanism; GuardedUpdate adds the chainable surface and the rows-affected → GuardedError mapping on top.

The Anti-Pattern: read → check → write

A typical conditional update without GuardedUpdate looks like this:

// Anti-pattern — do not write this.
let unit = inventory_units::Entity::find_by_id(unit_id)
    .one(&conn)
    .await?
    .ok_or(Error::NotFound)?;

if unit.quantity < needed {
    return Err(Error::InsufficientCapacity);
}

let mut active: inventory_units::ActiveModel = unit.into();
active.quantity = Set(active.quantity.unwrap() - needed);
active.update(&conn).await?;

Two concurrent callers can both pass the if unit.quantity < needed check before either writes. Both then write the decrement, and capacity is exceeded. The read-check-write round trip leaves a race window between the SELECT and the UPDATE.

The Replacement: GuardedUpdate

The same operation as a single statement:

use ferro_orm::{GuardedUpdate, ColumnTrait};
use sea_orm::sea_query::Expr;

GuardedUpdate::new(inventory_units::Entity)
    .filter(inventory_units::Column::Id.eq(unit_id))
    .filter(inventory_units::Column::Quantity.gte(needed))
    .set_expr(
        inventory_units::Column::Quantity,
        Expr::col(inventory_units::Column::Quantity).sub(needed),
    )
    .exec_one(&conn)
    .await?;

One round trip, one statement. The database atomically tests both id = unit_id and quantity >= needed; if both hold, the row is decremented in the same statement. If either fails, exec_one returns Err(GuardedError::NoRowsAffected) — capacity is exhausted or the row no longer exists.

API

GuardedUpdate::new(entity)

Construct an empty builder targeting a SeaORM entity.

.filter(condition)

Add a filter expression. Multiple .filter(...) calls are AND-combined onto an internal Condition. Accepts anything implementing IntoCondition — typically Column::field.eq(value) or any SimpleExpr.

.set_expr(column, expression) and .set_value(column, value)

Set a column. set_expr takes a SimpleExpr (for value-derived updates such as Expr::col(Column::Quantity).sub(1)); set_value takes a Value (for literal assignments). Both are chainable; multiple calls set multiple columns in one statement. Insertion order is preserved; later sets to the same column override earlier ones.

.exec_one(&conn) vs .exec_at_most_one(&conn)

Both methods compile and execute the UPDATE against a &impl ConnectionTrait (works equally with &DatabaseConnection or &DatabaseTransaction):

Use exec_one when predicate failure is the operative signal (capacity exhausted, pre-condition unmet) and should surface as an error. Use exec_at_most_one when predicate failure is a normal outcome that should not pollute error logs (e.g., refreshing a session that may have expired).

Common Patterns

Counter decrement

The canonical race-free counter decrement (inventory, queue capacity, rate limit budget):

GuardedUpdate::new(counters::Entity)
    .filter(counters::Column::Id.eq(counter_id))
    .filter(counters::Column::Quantity.gte(needed))
    .set_expr(
        counters::Column::Quantity,
        Expr::col(counters::Column::Quantity).sub(needed),
    )
    .exec_one(&conn)
    .await?;

Status transition

Atomic state machine transition with multi-column update — set the new status and the timestamp in the same statement:

use ferro_orm::Value;
use chrono::Utc;

GuardedUpdate::new(reservations::Entity)
    .filter(reservations::Column::Id.eq(handle_id))
    .filter(reservations::Column::Status.eq("held"))
    .set_value(
        reservations::Column::Status,
        Value::String(Some(Box::new("committed".into()))),
    )
    .set_value(
        reservations::Column::CommittedAt,
        Value::ChronoDateTimeUtc(Some(Box::new(Utc::now()))),
    )
    .exec_one(&conn)
    .await?;

Optimistic update (predicate failure is normal)

Refresh a session's last_seen_at if the token is valid and not expired. If the session expired between issue and now, this is a normal outcome, not an error log:

let updated = GuardedUpdate::new(sessions::Entity)
    .filter(sessions::Column::Token.eq(&token))
    .filter(sessions::Column::ExpiresAt.gt(now))
    .set_value(
        sessions::Column::LastSeenAt,
        Value::ChronoDateTimeUtc(Some(Box::new(now))),
    )
    .exec_at_most_one(&conn)
    .await?;

if !updated {
    return Err(AuthError::SessionExpired);
}

Atomicity Guarantee (and Its Limit)

GuardedUpdate guarantees atomicity per statement, not per builder. The single UPDATE … WHERE … SQL statement is atomic at the database engine level — SQLite's serial writer and Postgres's READ COMMITTED semantics both ensure that the predicate test and the row mutation cannot interleave with another concurrent statement on the same row.

However, a caller building .set_expr(qty - 1) and then reading the resulting qty value in a separate query without a transaction re-introduces a race window between the two queries. The crate's responsibility is to make the conditional UPDATE itself race-free; bracketing it in a transaction (when post-update inspection is required) is the caller's responsibility.

If the post-update row state is needed, wrap the GuardedUpdate and the subsequent SELECT in the same DatabaseTransaction:

use sea_orm::TransactionTrait;

let txn = conn.begin().await?;
GuardedUpdate::new(counters::Entity)
    .filter(counters::Column::Id.eq(1))
    .set_expr(
        counters::Column::Quantity,
        Expr::col(counters::Column::Quantity).sub(1),
    )
    .exec_one(&txn)
    .await?;
let row = counters::Entity::find_by_id(1).one(&txn).await?;
txn.commit().await?;

Errors

Every variant's Display impl is prefixed "guarded: " for log greppability — matches the workspace convention used by other ferro crate error types (e.g. "wallet: ", "config: ").

Postgres vs SQLite

GuardedUpdate is dialect-agnostic; the SQL it emits is standard UPDATE … WHERE …. SQLite enforces per-statement atomicity via its serial writer; Postgres enforces it via READ COMMITTED (the default isolation level) — both are sufficient for the contract.

UPDATE … RETURNING is not currently supported; SeaORM does not yet abstract it cleanly across dialects. Callers needing the post-update row should re-fetch inside the same transaction (see above).

Audit Log

Ferro's ferro-audit crate provides an append-only structured before/after audit log for state-changing operations. Every recorded entry captures what happened — for forensic investigation, regulatory evidence, and state replay. The crate ships a SeaORM migration that consumer apps register in their own Migrator, plus a chainable builder API for recording entries and pure functions for replaying them.

Audit entries are the historical twin of ferro-events: events are "something happened, react now"; audit entries are "something happened, here is the evidence forever".

The Anti-Pattern

Without a structured audit log, applications either log to unstructured text (tracing::info!), persist ad-hoc JSON columns on every domain table, or rely on database transaction logs that disappear when the storage engine rolls. Each approach loses information: unstructured logs are hard to query, ad-hoc JSON columns drift across tables, transaction logs are operational data not preserved evidence.

// Anti-pattern: scattered logging with no structure
tracing::info!(user = %user_id, "decremented inventory unit {} by {}", unit_id, qty);

// Anti-pattern: ad-hoc JSON column on every table
inventory_unit.history.push(json!({ "action": "adjust", "qty": qty, "user": user_id }));

Neither approach lets you answer "what was this unit's history?" without writing custom query code per domain table, and neither preserves before/after state for replay.

The Replacement

ferro-audit provides a typed, queryable audit primitive:

use ferro_audit::{AuditEntry, AuditActor, AuditTarget};
use serde_json::json;

AuditEntry::record("inventory.stock.adjust")
    .actor(AuditActor::User(user_id.to_string()))
    .target(AuditTarget::new("inventory.unit", unit_id.to_string()))
    .before(json!({ "quantity": old }))
    .after(json!({ "quantity": new }))
    .reason("order_committed")
    .write(&conn)
    .await?;

One row in the audit_log table per state change. Query helpers traverse it by target, by actor, or globally. The reconstruct_state helper folds the recorded after payloads into the current state.

API

AuditEntry::record(action) -> AuditEntryBuilder

Entry point. action is a dotted-namespace verb (e.g. "inventory.stock.adjust", "user.password_reset_requested") — required, only validation is non-empty. The builder defaults actor to AuditActor::System and all other fields to None.

Builder methods (all consuming self, returning Self)

Query helpers

For pagination or custom filters, drop down to SeaORM directly via the re-exported AuditLogEntity.

Retention

AuditActor

Typed enum, stringly-keyed so ferro doesn't bind to a consumer's user-id type:

AuditTarget

Open struct so ferro doesn't bind to a closed set of target types:

pub struct AuditTarget {
    pub kind: String,  // "inventory.unit", "user", "checkout.session"
    pub id: String,    // consumer-stringified primary key
}

The dotted-namespace convention for kind (and for action) is a convention, not enforced at compile time. Use it for consistency across your audit codebase.

Schema

The audit_log table created by CreateAuditLogTable:

Indexes:

Register the migration in your Migrator:

use ferro_audit::CreateAuditLogTable;

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            Box::new(CreateAuditLogTable),
            // ... your app migrations
        ]
    }
}

Replay

history_for_target(&target, &conn) returns the entries in ascending order. Pair it with reconstruct_state to fold the recorded after payloads into the current state:

use ferro_audit::{history_for_target, reconstruct_state, AuditTarget};

let target = AuditTarget::new("inventory.unit", "abc");
let entries = history_for_target(&target, &conn).await?;
let final_state = reconstruct_state(&entries);

The fold is a shallow object merge: keys from newer entries overwrite older keys at the top level. Nested objects and arrays are replaced wholesale, not deep-merged. A consumer needing deep-merge runs its own fold over the Vec<AuditEntry>.

Returns None if the slice is empty or no entry has a non-None after. Returns Some(non_object_value) if any entry's after is a non-object — that value replaces the running state from that point on (useful for "tombstone" patterns like recording after: "DELETED").

Retention and Pruning

Audit trails are evidence. Aggressive pruning is usually wrong. GDPR / privacy law may force retention limits; in that case, 1–3 years is the conventional default. Run prune_older_than from a scheduled job in your application — ferro-queue is the natural fit.

PII responsibility: ferro-audit does NOT automatically redact before / after payloads. The caller must remove or hash PII fields BEFORE passing JSON to the builder. The audit_log table is treated as a normal application table for backup and access-control purposes; design accordingly.

Errors

AuditError variants:

Missing target is NOT an error — it emits a tracing::warn! diagnostic and the write succeeds (audit must never refuse a write). Pure events (without a target) are intentional in the model.

Postgres vs SQLite

ferro-audit works against both backends transparently. The before / after columns use SeaORM's json() column type (stored as TEXT in SQLite, native json in Postgres); the id and correlation_id columns use the uuid() column type (TEXT in SQLite, native uuid in Postgres). serde_json::Value round-trips identically on both. Tests run against in-memory SQLite for speed; production deployments on Postgres get the same semantics.

Reservations

ferro-reservation is a generic resource reservation kernel for the Ferro framework. Capacity-constrained apps — booking, ticketing, checkout, queue admission, rate limiting — all need the same primitive: hold N units of a resource for a deadline, then commit or release. This crate provides it as a typed, race-free state machine with automatic audit emission and event broadcast. No hand-rolled read → check → write SQL required.

The Anti-Pattern

Without a kernel, every consumer writes the same fragile code:

// BAD: read-check-write has a race window
let current = db.query("SELECT held FROM inventory WHERE id = ?", id).await?;
if current.held + qty <= capacity {
    db.execute("UPDATE inventory SET held = held + ? WHERE id = ?", qty, id).await?;
} else {
    return Err(NoCapacity);
}

Under concurrent load, two callers can both observe held = 4 (capacity = 5) and both execute the UPDATE, leaving held = 6 > capacity. The fix is structural: fold the check into the UPDATE statement so the database enforces atomicity. ferro-reservation uses [ferro-orm::GuardedUpdate] under the hood to make every state transition race-free by construction.

The Replacement

use ferro_reservation::{ReservationKernel, ReservationContext, Resource, ReleaseReason};
use std::time::Duration;

struct InventoryUnitResource { /* db reference, business rules */ }

#[async_trait::async_trait]
impl Resource for InventoryUnitResource {
    type Key = ProductId;
    type Window = BookingWindow;
    const KIND: &'static str = "inventory.unit";

    async fn capacity<C: ConnectionTrait>(&self, conn: &C, key: &Self::Key, _w: &Self::Window)
        -> Result<u32, ReservationError> { /* ... */ }
    async fn held<C: ConnectionTrait>(&self, conn: &C, key: &Self::Key, w: &Self::Window)
        -> Result<u32, ReservationError> { /* ... */ }
}

// Construct once at application start
let kernel = ReservationKernel::new(db.clone(), InventoryUnitResource::new());

// Hold during payment
let ctx = ReservationContext::user(user_id.to_string()).with_correlation(request_id);
let handle = kernel.hold(&conn, key, window, 1, Duration::from_secs(15 * 60), &ctx).await?;

// Commit or release based on payment outcome
match stripe_result {
    Ok(_)  => kernel.commit(&conn, handle, &ctx).await?,
    Err(_) => kernel.release(&conn, handle, ReleaseReason::PaymentFailed, &ctx).await?,
}

State Diagram

              hold()                  commit()
   ──────────────▶ held ──────────────────────▶ committed
                    │
                    │ release(reason)
                    ▼
                released

              hold()
   ──────────────▶ held ─── ttl ─────────────▶ expired
                                 run_sweep_once()

Terminal states (committed, released, expired) have no outgoing transitions. Any attempt surfaces as ReservationError::ConflictingState.

Resource Trait

Consumers implement Resource to define their capacity model:

#[async_trait]
pub trait Resource: Send + Sync + 'static {
    type Key: Hash + Eq + Clone + Send + Sync + Serialize + DeserializeOwned;
    type Window: PartialEq + Clone + Send + Sync + Serialize + DeserializeOwned;

    const KIND: &'static str;

    async fn capacity<C: ConnectionTrait>(
        &self,
        conn: &C,
        key: &Self::Key,
        window: &Self::Window,
    ) -> Result<u32, ReservationError>;

    async fn held<C: ConnectionTrait>(
        &self,
        conn: &C,
        key: &Self::Key,
        window: &Self::Window,
    ) -> Result<u32, ReservationError>;
}

• Key identifies a resource instance (ProductId, ShowId, ApiClientId, ...).
• Window scopes capacity (a date+time range for booking, () for non-windowed resources).
• KIND is a &'static str dotted-namespace constant — convention mirrors ferro-audit's action/target convention ("inventory.unit", "checkout.slot", "api.quota").

Multi-tenancy is a Key concern: include the tenant identifier in Key, not as a kernel-level parameter. The kernel does not scope queries by tenant automatically.

Lifecycle Methods

handle is taken by value in commit / release / extend — use-once is a compile-time guarantee. Reusing a handle after commit or release is a compile error.

hold sequence:

1. Call R::capacity(&conn, &key, &window).
2. Call R::held(&conn, &key, &window).
3. If held + quantity > capacity → Err(Insufficient { requested, available, capacity }).
4. INSERT one reservations row with status = 'held', expires_at = now() + ttl.
5. Write one AuditEntry with action = "reservation.held" via ferro-audit.
6. Emit ReservationEvent::Held via ferro-events.
7. Return ReservationHandle.

The capacity check, the INSERT, and the audit write all execute inside a single SERIALIZABLE transaction. The kernel atomically arbitrates concurrent holds at the database level — no application-layer mutex is required. The conflict-losing task receives ReservationError::Insufficient. See the Consistency Model section.

ReservationContext

Per-call audit metadata bundle:

pub struct ReservationContext {
    pub actor: AuditActor,
    pub correlation_id: Option<Uuid>,
    pub tenant_id: Option<String>,
    pub reason: Option<String>,
}

impl ReservationContext {
    pub fn system() -> Self;
    pub fn user(user_id: impl Into<String>) -> Self;
    pub fn job(name: impl Into<String>) -> Self;
    pub fn anonymous() -> Self;

    pub fn with_correlation(self, id: Uuid) -> Self;
    pub fn with_tenant(self, t: impl Into<String>) -> Self;
    pub fn with_reason(self, r: impl Into<String>) -> Self;
}

The actor is recorded on every audit entry written during the state transition. The optional fields propagate to the audit log when populated. Builder methods follow the consuming mut self → Self convention used across the framework.

TTL and the Sweeper

hold(...) accepts a ttl: Duration. The persisted expires_at is computed at hold time as now() + ttl. run_sweep_once() scans for held rows whose expires_at is in the past, transitions them to expired, and emits one audit entry and one event per row.

The crate has no ferro-queue runtime dependency — consumers schedule sweeps with their preferred mechanism. Three idiomatic patterns:

Pattern 1: ferro-queue Job

struct SweepReservations;

impl ferro_queue::Job for SweepReservations {
    async fn handle(self) -> Result<(), Error> {
        KERNEL.run_sweep_once().await?;
        Ok(())
    }
}

// Schedule every 60 seconds via your queue's recurring-job API

Pattern 2: tokio::time::interval

tokio::spawn(async {
    let mut tick = tokio::time::interval(Duration::from_secs(60));
    loop {
        tick.tick().await;
        if let Err(e) = KERNEL.run_sweep_once().await {
            tracing::warn!(error = %e, "sweep failed");
        }
    }
});

Pattern 3: Cron-driven CLI

// e.g. your-app reservation:sweep
fn main() {
    let rt = tokio::runtime::Runtime::new().unwrap();
    rt.block_on(async {
        KERNEL.run_sweep_once().await.expect("sweep");
    });
}

SweepReport { expired_count, scanned_at } is returned for observability. A consistent non-zero expired_count across successive sweeps indicates a backlog; schedule sweeps more frequently. The sweeper processes at most 500 rows per call; subsequent calls drain the backlog.

The sweeper is idempotent under concurrent execution. If two sweeper tasks race on the same expired row, only one wins the guarded held → expired transition; the other gets zero rows affected and skips that row silently.

ReservationEvent Subscription

Every state transition dispatches a ReservationEvent via ferro-events. Subscribe with ferro_events::global_dispatcher():

ferro_events::global_dispatcher()
    .on::<ReservationEvent, _, _>(|event: ReservationEvent| {
        Box::pin(async move {
            match event {
                ReservationEvent::Held { id, quantity, .. } => {
                    // notify a live dashboard, update a cache, etc.
                }
                ReservationEvent::Committed { id, .. } => { /* ... */ }
                ReservationEvent::Released { id, reason, .. } => { /* ... */ }
                ReservationEvent::Expired { id, .. } => { /* ... */ }
            }
            Ok(())
        })
    });

Event dispatch is best-effort. If dispatch fails, the kernel logs at tracing::warn! and returns Ok(()) — the state change is already committed to the database. Consumers needing durable replay use the audit log.

Audit Log Inspection

Every state transition writes one [ferro_audit::AuditEntry] with action = "reservation.{held|committed|released|expired|extended}" and target = AuditTarget::new("reservation", id.to_string()). The full history for a reservation:

let target = ferro_audit::AuditTarget::new("reservation", id.to_string());
let history = ferro_audit::history_for_target(&target, &conn).await?;
let final_state = ferro_audit::reconstruct_state(&history);

reconstruct_state performs a shallow merge of after payloads in created_at ASC order; the resulting value reflects the most recently written state fields.

Audit emission is unconditional. If AuditEntry::write fails (e.g., the audit_log table is missing), the kernel returns ReservationError::Audit but the DB state transition is already committed. See Operational Footguns.

Common Patterns

Slot hold during online checkout

Resource::Key = ProductId. Hold for 15 minutes during Stripe payment; on payment_intent.succeeded webhook commit, on payment_intent.payment_failed release with ReleaseReason::PaymentFailed. If the user abandons, the sweeper transitions the row to expired automatically.

Ticket reservations

Resource::Key = ShowId, Resource::Window = (). capacity = venue.seat_count, held = sum of held + committed reservations. A short TTL (e.g., 5 minutes) prevents zombie holds from blocking legitimate purchasers.

API rate-limit buckets

Resource::Key = ApiClientId, Resource::Window = MinuteBucket. capacity = client.rate_limit, held = requests_in_bucket. The kernel rejects holds beyond capacity with Insufficient. Combine with run_sweep_once on a per-minute cron to garbage-collect expired buckets.

Schema

The migration creates a single reservations table:

-- 12 columns
id              UUID PRIMARY KEY DEFAULT gen_random_uuid()  -- client-generated UUIDv4
resource_kind   VARCHAR NOT NULL      -- "inventory.unit", "checkout.slot"
resource_key    JSON NOT NULL         -- serialized Resource::Key
window          JSON NULL             -- serialized Resource::Window; NULL when Window = ()
quantity        INTEGER NOT NULL
status          VARCHAR NOT NULL      -- "held" | "committed" | "released" | "expired"
expires_at      TIMESTAMP NOT NULL
held_at         TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
committed_at    TIMESTAMP NULL
released_at     TIMESTAMP NULL
release_reason  VARCHAR NULL
tenant_id       VARCHAR NULL

-- 2 indexes
idx_reservations_kind_key_window_status  -- (resource_kind, resource_key, window, status)
idx_reservations_status_expires           -- (status, expires_at) — sweeper scan path

Register the migration in your Migrator alongside ferro-audit's:

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            Box::new(ferro_audit::CreateAuditLogTable),
            Box::new(ferro_reservation::CreateReservationsTable),
            // ... your app migrations
        ]
    }
}

Errors

ReservationError is the single error enum:

Display prefix is "reservation: …" for log greppability across the workspace.

Consistency Model

State transitions (commit, release, extend) are race-free on both SQLite and Postgres: each is a single UPDATE … WHERE status = 'held' AND id = ? statement executed via [ferro-orm::GuardedUpdate]. Per-statement atomicity ensures concurrent callers cannot both succeed on the same row; one wins and the other gets ConflictingState.

hold: The capacity check, INSERT, and audit write execute inside a SERIALIZABLE transaction (sea_orm::IsolationLevel::Serializable). On SQLite the transaction aligns with the WAL single-writer model; on Postgres it prevents phantom reads between the SELECT and INSERT. If two concurrent tasks race on the same (key, window), the database serializes them — exactly one succeeds and the other receives ReservationError::Insufficient. No application-layer mutex is needed.

A conflict-losing task on Postgres may receive SQLSTATE 40001 (serialization failure); the kernel translates this to ReservationError::Insufficient before returning to the caller. The error contract is uniform across backends.

commit, release, and extend via GuardedUpdate are race-free on both dialects (single UPDATE … WHERE statement).

Operational Footguns

1. Audit failure does not roll back state. If AuditEntry::write fails for any reason (database connection lost, audit_log table missing), the kernel returns ReservationError::Audit AFTER the DB row has already been transitioned. The state change is committed; only the audit record is missing. Monitor for ReservationError::Audit in your error-handling layer.

2. Event dispatch is best-effort. ferro_events::dispatch failure logs at tracing::warn! but does not propagate. Use the audit log for durable replay of state transitions.

3. No upper cap on extend. A held reservation can be extended indefinitely. Consumers wanting a hard TTL ceiling must enforce it at the call site before calling extend.

Derive Macros

Ferro provides two derive macros that eliminate boilerplate for database models and validation. FerroModel scaffolds CRUD operations on SeaORM entities; ValidateRules co-locates validation rules with struct field definitions.