Introduction

zapline is a web framework for Rust that brings three things together:

• FastAPI-level ergonomics. You write plain async fns with typed arguments, and you get request parsing, validation, errors, and interactive OpenAPI docs automatically.
• Enterprise-grade structure. It includes dependency injection, layered configuration, lifecycle hooks, plugins, guards and policies, observability, and health checks. These are the building blocks large teams expect from Spring Boot, NestJS or ASP.NET Core.
• Top-tier performance. Thread-per-core runtimes, zero-allocation routing, and no per-request cost for features you don't use. On equal hardware, zapline outperforms axum and actix-web in its own benchmark suite.

use zapline::prelude::*;

#[get("/hello/{name}")]
async fn hello(Path(name): Path<String>) -> String {
    format!("Hello, {name}!")
}

fn main() -> std::io::Result<()> {
    App::new().mount(hello).run("0.0.0.0:8080")
}

Philosophy

1. The common case is one line. Each feature has a default that works out of the box: App::openapi(...), .plugin(Health::new()), .wrap(Cors::permissive()).
2. Everything is overridable. Defaults are built from public traits and builders, so you can swap any piece.
3. Pay only for what you use. Optional features sit behind Cargo features and extension points. An app that doesn't use metrics runs exactly the same code path as if metrics didn't exist.
4. Testable by default. app.test() runs the whole pipeline in-process with no sockets.

How this guide is organized

• Getting started gets an app running and explains the CLI.
• Core concepts covers the request pipeline: routing, extractors, responses, errors and middleware.
• Building APIs, Security, Realtime & content and Operations cover the batteries.
• The Reference lists every Cargo feature and explains how the framework is put together.

Quickstart

On Windows, install the Visual Studio C++ Build Tools first and use PowerShell. See Platform support.

With the CLI (recommended)

cargo install --path crates/zapline-cli     # installs `zapline` and `cargo zapline`
zapline new my-api                          # templates: minimal | api (default) | full
cd my-api
zapline dev                                 # build, run, live-reload the browser on every change

Open http://localhost:8080/docs for the interactive API docs, and run cargo test for the generated tests.

Or skip the project entirely: zapline new hello.rs && zapline dev hello.rs gives you the same in a single file, dependencies declared at its top (One-file apps).

By hand

[dependencies]
zapline = "0.1"

[dev-dependencies]
tokio = { version = "1", features = ["full"] }

use zapline::prelude::*;

// `#[model]` derives Debug, Clone, Serialize, Deserialize, JsonSchema and Validate.
#[model]
struct Todo {
    #[validate(length(min = 1, max = 200))]
    title: String,
    done: bool,
}

/// Create a todo.
#[post("/todos", tag = "todos", status = 201)]
async fn create(Valid(Json(todo)): Valid<Json<Todo>>) -> (StatusCode, Json<Todo>) {
    (StatusCode::CREATED, Json(todo))
}

/// Say hello.
#[get("/hello/{name}")]
async fn hello(Path(name): Path<String>) -> String {
    format!("Hello, {name}!")
}

pub fn app() -> App {
    App::new()
        .mount((create, hello))
        .openapi(OpenApi::new("Todos", "0.1.0"))
}

fn main() -> std::io::Result<()> {
    app().run("0.0.0.0:8080")
}

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn rejects_empty_titles() {
        let res = app().test().post("/todos").json(&serde_json::json!({"title": "", "done": false})).send().await;
        assert_eq!(res.status(), 422);
    }
}

What you get:

• POST /todos parses and validates the body. Invalid input returns 422 with per-field details.
• /openapi.json and Swagger UI at /docs are generated from the signatures and doc comments.
• A thread-per-core server with graceful shutdown on SIGINT/SIGTERM.

Next, read Routing and Extractors, or browse the runnable examples with cargo run -p zapline-examples --example <name>.

One-file apps

A whole zapline app can live in a single .rs file, with no Cargo.toml, no src/ and no project directory. It is good for prototypes, internal tools, webhooks, demos, bug reports and code an AI assistant hands you in one piece.

zapline new hello.rs      # write a starter: routes, a validated JSON model, OpenAPI docs, tests
zapline dev hello.rs      # serve on http://localhost:8080, rebuild and live-reload on every save
zapline run hello.rs      # build (cached) and run it
./hello.rs                # the same, through its shebang line
zapline test hello.rs     # run the #[cfg(test)] tests inside the file

The first build compiles zapline once. After that, every one-file app on the machine shares those compiled dependencies, and running an unchanged file starts it right away: cargo is not invoked at all.

The file

#!/usr/bin/env -S zapline run
//! Hands out ids.
//!
//! ```cargo
//! [dependencies]
//! uuid = { version = "1", features = ["v4"] }
//! ```

use zapline::prelude::*;

#[get("/ids/new")]
async fn new_id() -> String {
    uuid::Uuid::new_v4().to_string()
}

fn main() -> std::io::Result<()> {
    App::new().mount(new_id).run("0.0.0.0:8080")
}

• The shebang line is optional. With it (and chmod +x), the file runs as ./app.rs; everything after the file name goes to the app.
• Dependencies go in a cargo block inside the leading //! comment, in Cargo.toml syntax. The block is optional too.
• The rest is ordinary Rust. rustc ignores the shebang, and the header is a doc comment, so the file is still valid Rust that rustfmt and clippy accept.

Dependencies

zapline, serde, serde_json and tokio are always available, so most apps need no header at all:

List one of them only to change it. An entry without a version, path or git source keeps the default version, so zapline = { features = ["ws", "sqlite"] } just adds features. Any other crate is added the usual way: uuid = "1".

A header may contain these tables: [package] (only edition, rust-version, version, description, authors, license), [dependencies], [dev-dependencies], [target.'cfg(...)'.dependencies], [features], [profile.*], [patch.*] and [lints]. The package name comes from the file name, and the file itself is the only target, so [[bin]], [lib], [workspace] and build scripts are not allowed. The edition defaults to 2021.

Relative path = "..." dependencies are relative to the file, not to the hidden project, so a script next to a zapline checkout can use zapline = { path = "zapline/crates/zapline" }. zapline new hello.rs --zapline-path <checkout> writes that line for you.

Commands

Options for zapline run come before the file; anything after the file belongs to the app, so ./app.rs --release passes --release to the app.

Errors point at your file

A mistake in the header is reported at its line and column, like a compiler error, and nothing is built:

error: app.rs:7:15: invalid ```cargo block: invalid basic string, expected `"`

Compiler errors and warnings name the real file and line too, because the generated project's binary target is your file itself, not a copy. include_str!("data.txt") and #[path] modules resolve next to the file.

How it works

zapline run app.rs turns the file into a cargo project in the user cache directory and builds that:

~/.cache/zapline/                       ($XDG_CACHE_HOME/zapline; %LOCALAPPDATA%\zapline on Windows)
├── scripts/<hash of the file's path>/
│   ├── Cargo.toml                      [[bin]] path = "/abs/path/app.rs", deps from the header
│   ├── Cargo.lock                      kept between runs: versions stay put until you change the header
│   └── .cargo/config.toml              build.target-dir = the shared target below
└── target/                             one target directory for every one-file app

• One project per file path. Edit the file and the same project is reused; move it and it gets a new one. The binary is named after the file plus a short hash, so api.rs files in different directories never overwrite each other in the shared target directory.
• Shared target directory. Dependencies are compiled once for all scripts (per version and feature set, as cargo does). CARGO_TARGET_DIR still wins when set.
• No cargo for an unchanged file. After a build, zapline records the executable together with a hash of the generated manifest. On the next run it compares the executable's age with every source file in the dep-info that cargo writes next to it (the script, files it includes, and the sources of path dependencies) and with the manifests of path dependencies. If nothing is newer, it starts the executable directly (a few milliseconds); otherwise it runs cargo build, which recompiles only what changed.
• On unix, zapline run replaces itself with the app (exec), so signals, the exit code and stdin are the app's own.

Delete ~/.cache/zapline at any time to reclaim the space; it is rebuilt on demand.

Editor support

rust-analyzer needs a Cargo.toml. Point it at the hidden one:

zapline run --print-manifest app.rs
# ~/.cache/zapline/scripts/1f2e3d4c5b6a7980/Cargo.toml

and add that path to rust-analyzer.linkedProjects in your editor settings (VS Code: "rust-analyzer.linkedProjects": ["/home/you/.cache/zapline/scripts/.../Cargo.toml"]).

Growing into a project

When the file gets big, create a project with zapline new my-app and move the code over: handlers and models go to src/lib.rs (or src/routes/), main to src/main.rs, the header's dependencies to Cargo.toml, and the tests to tests/. Everything else (the API, the test client, zapline dev) works the same.

Cheatsheet

One runnable file showing the canonical way to do each common task: models with validation, handlers, errors, dependency injection, middleware, route groups, OpenAPI, health checks and in-process tests. When there are several ways to do something, this is the one the guide, the CLI generators and AGENTS.md use.

//! The zapline cheatsheet: one file, the canonical way to do each common
//! task. It is included verbatim in the guide (`docs/src/cheatsheet.md`) and
//! in `llms.txt`, so it doubles as compact context for AI assistants.
//!
//!     cargo run -p zapline-examples --example cheatsheet
//!     cargo test -p zapline-examples --example cheatsheet

use std::collections::BTreeMap;
use std::sync::{Arc, RwLock};

use zapline::middleware::{Cors, SetRequestId};
use zapline::prelude::*;

// ---- Models: `#[model]` derives serde, JsonSchema (OpenAPI) and, with `#[validate]` rules, Validate.
// Doc comments become OpenAPI descriptions.

/// A note.
#[model]
pub struct Note {
    pub id: u64,
    pub text: String,
}

/// Body of `POST /notes`.
#[model]
pub struct NewNote {
    #[validate(length(min = 1, max = 500))]
    pub text: String,
}

/// Query string of `GET /notes`.
#[model]
pub struct Page {
    pub limit: Option<usize>,
}

// ---- Services: a trait behind `Dep<dyn Trait>` so tests can swap it.

pub trait Notes: Send + Sync {
    fn list(&self, limit: usize) -> Vec<Note>;
    fn get(&self, id: u64) -> Option<Note>;
    fn add(&self, text: String) -> Note;
}

#[derive(Default)]
pub struct MemNotes(RwLock<BTreeMap<u64, Note>>);

impl Notes for MemNotes {
    fn list(&self, limit: usize) -> Vec<Note> {
        self.0
            .read()
            .unwrap()
            .values()
            .take(limit)
            .cloned()
            .collect()
    }
    fn get(&self, id: u64) -> Option<Note> {
        self.0.read().unwrap().get(&id).cloned()
    }
    fn add(&self, text: String) -> Note {
        let mut map = self.0.write().unwrap();
        let note = Note {
            id: map.len() as u64 + 1,
            text,
        };
        map.insert(note.id, note.clone());
        note
    }
}

// ---- Handlers: route macro + async fn; arguments are extractors.

/// List notes.
#[get("/notes", tag = "notes")]
async fn list_notes(notes: Dep<dyn Notes>, Query(page): Query<Page>) -> Json<Vec<Note>> {
    Json(notes.list(page.limit.unwrap_or(50).min(200)))
}

/// Fetch one note. Unknown ids are a 404 with a stable error code.
#[get("/notes/{id}", tag = "notes")]
async fn get_note(notes: Dep<dyn Notes>, Path(id): Path<u64>) -> Result<Json<Note>> {
    let note = notes
        .get(id)
        .ok_or_else(|| Error::not_found().with_code("note_not_found"))?;
    Ok(Json(note))
}

/// Create a note. Invalid bodies get a 422 with per-field details.
#[post("/notes", tag = "notes", status = 201)]
async fn create_note(
    notes: Dep<dyn Notes>,
    Valid(Json(new)): Valid<Json<NewNote>>,
) -> (StatusCode, Json<Note>) {
    (StatusCode::CREATED, Json(notes.add(new.text)))
}

// ---- Middleware: a plain async fn.

async fn powered_by(req: Request, next: Next) -> Response {
    let mut res = next.run(req).await;
    res.headers_mut()
        .insert("x-powered-by", HeaderValue::from_static("zapline"));
    res
}

// ---- The app: one function that tests and `main` share.

pub fn app(notes: Arc<dyn Notes>) -> App {
    App::new()
        .provide_dyn::<dyn Notes>(notes)
        .wrap(SetRequestId::new())
        .wrap(Cors::permissive())
        .wrap(powered_by)
        .nest(
            "/api",
            Routes::new().mount((list_notes, get_note, create_note)),
        )
        .plugin(Health::new()) // /health, /health/live, /health/ready
        .openapi(OpenApi::new("Notes", "1.0.0")) // /openapi.json + /docs
}

fn main() -> std::io::Result<()> {
    app(Arc::new(MemNotes::default())).run("0.0.0.0:8080")
}

// ---- Tests: in-process, no sockets.

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[tokio::test]
    async fn create_then_fetch() {
        let client = app(Arc::new(MemNotes::default())).test();

        let res = client
            .post("/api/notes")
            .json(&json!({"text": "hi"}))
            .send()
            .await;
        assert_eq!(res.status(), 201);
        let note: Note = res.json();

        let res = client.get(&format!("/api/notes/{}", note.id)).send().await;
        assert_eq!(res.status(), 200);
        assert_eq!(res.header("x-powered-by"), Some("zapline"));
    }

    #[tokio::test]
    async fn validation_and_not_found() {
        let client = app(Arc::new(MemNotes::default())).test();
        let res = client
            .post("/api/notes")
            .json(&json!({"text": ""}))
            .send()
            .await;
        assert_eq!(res.status(), 422);
        let res = client.get("/api/notes/99").send().await;
        assert_eq!(res.status(), 404);
    }
}

Viewing this on GitHub? The code block above only renders on the docs site; the file itself is examples/examples/cheatsheet.rs.

Run it with cargo run -p zapline-examples --example cheatsheet and open http://localhost:8080/docs.

Everything else in one line each

Project layout & the CLI

The zapline CLI scaffolds projects, generates code, runs a live-reloading dev server, and talks to your app to print its routes or export its OpenAPI document. Install it with cargo install zapline-cli. You can call it as zapline <cmd> or cargo zapline <cmd>.

-C <dir> runs any command as if it had been started in <dir>.

Missing features

Most of zapline is opt-in, so code copied from the guide can need a feature the project does not have yet. Plain cargo check only says could not find `ws` in `zapline`. zapline check and zapline test add the fix:

error[E0432] src/routes/chat.rs:1:14: unresolved import `zapline::ws`
    could not find `ws` in `zapline`
    hint: enable the `ws` feature: zapline add ws
error[E0599] src/lib.rs:12:10: no method named `views` found for struct `zapline::App` in the current scope
    method not found in `zapline::App`
    hint: enable the `views` feature: zapline add views
error[E0425] src/routes/posts.rs:8:20: cannot find type `Db` in this scope
    not found in this scope
    hint: enable the `sqlite` or `postgres` feature: zapline add sqlite

The hint covers unresolved imports and paths (zapline::ws, zapline::auth::Jwt), unknown types (WebSocketUpgrade, Views, Db, JwtConfig, Cache...) and builder methods that a feature adds (App::views, App::database, Storage::s3...). It only appears when none of the features that provide the name is on, so an error that has another cause gets no hint. The check and test MCP tools show the same hint, and add_feature applies it.

Generated layout (api template)

my-api/
├── Cargo.toml
├── src/
│   ├── main.rs          # thin: builds the app and runs it
│   ├── lib.rs           # pub fn app() -> App  (tests use it too)
│   ├── models.rs
│   └── routes/
│       ├── mod.rs       # install(app): plugins between zapline:routes markers
│       ├── health.rs
│       └── users.rs     # pub fn mount(app: App) -> App
├── tests/               # in-process tests using App::test()
├── Dockerfile, .dockerignore, .env.example
└── .github/workflows/ci.yml

Each route module exposes pub fn mount(app: App) -> App, which makes it a plugin. routes/mod.rs installs the modules between // zapline:routes:start and // zapline:routes:end. zapline generate resource inserts new modules there.

The dev loop: zapline dev

zapline dev is a Vite-style loop for a Rust app. Run it in the project and open the address your app prints (http://localhost:8080 for the templates):

$ zapline dev
    Watching src/, config/, migrations/, Cargo.toml, build.rs, .env
    Watching templates/, static/ (browser reload, no rebuild)
    Building todo
       Proxy http://localhost:8080 with live reload
     Running `target/debug/todo` (pid 4242) at http://localhost:8080

What each kind of change does:

The swap has no downtime: while cargo compiles, every request is still answered by the previous version. The new binary starts next to it, and requests move over only once it answers HTTP; the old process then finishes its in-flight requests and exits (SIGTERM, then a kill after 5 seconds). If the new version crashes during startup, the old one keeps serving and the overlay says so.

The overlay appears in every open page and in pages you open while the build is broken. Press Esc to hide it; the next good build clears it and reloads the page. A page opened before the very first build finishes shows "Building..." and reloads by itself once the app is up.

zapline dev sets ZAPLINE_DEV=1 for the app, so 500 responses show the real error, templates and asset hashes are read again even in a --release build, and translations loaded with I18n::load are re-read when a file changes. --no-proxy turns all of this browser side off and runs the app directly: rebuild, stop the old process, start the new one.

How it works

browser ──▶ zapline dev proxy (the app's address, e.g. :8080)
              │  /__zapline/events   server-sent events: reload, css, problem, ...
              │  /__zapline/client.js
              └─▶ app on a free loopback port (127.0.0.1:41234)

1. zapline dev starts the app with ZAPLINE_DEV_PROXY=<file>. App::run then listens on a free loopback port instead of the address you gave it and writes both addresses to that file (zapline::dev::ENV_DEV_PROXY). Nothing else in the app changes, and without ZAPLINE_DEV=1 the variable is ignored.
2. The CLI listens on the app's own address and forwards every request to the app. HTML pages get one tag before </head>: <script src="/__zapline/client.js" defer> (fragments such as htmx partials are left alone). An external script, so a script-src 'self' policy allows it; with a nonce-based Content-Security-Policy the page's nonce is reused. Pages are fetched uncompressed so the tag can be added. A page that arrives in one go gets its new length; a page the app streams (it pauses for a moment while writing, or is over 32 MiB) is forwarded as it arrives, with the tag added on the way. Everything else (JSON, assets, streams, server-sent events, WebSocket upgrades) passes through untouched.
3. The client opens an EventSource on /__zapline/events. The CLI classifies each file change (Rust or asset), and pushes reload, css, building, problem (the parsed cargo build --message-format=json errors) or clear.
4. Each forwarded request opens its own connection to the app, so pointing the proxy at a new version takes effect on the very next request.
5. The proxy tells the app who the browser is with X-Forwarded-For, plus a random per-run key (ZAPLINE_DEV_PROXY_KEY in the app's environment, x-zapline-dev-proxy on each request). The app's local-only pages (the dev console at /_dev, the dev inbox, dev error pages, an unguarded admin) trust that X-Forwarded-For only when the key matches, and answer only when it names a single loopback address. So they work through the proxy from your machine, while a client reaching a proxy bound to 0.0.0.0 from elsewhere, or anything else that sends a forwarding header, still gets a 404.

The cost in production is zero: the proxy is part of the CLI, and the app side is one environment check in App::run at startup. Some limits:

• Apps served with TLS (ServerConfig::tls), on a Unix socket, or with App::serve on your own listener are run directly (no proxy), as with --no-proxy. An app that has not reported its address 60 seconds after starting (it does not use App::run, or its startup is that slow) is restarted without the proxy, so it binds its own address, and the session stays direct.
• The browser talks HTTP/1.1 to the proxy; the app may still serve HTTP/2 to other clients.
• Each open tab holds one event-stream connection; browsers allow about six HTTP/1.1 connections per host, so keep fewer than that many tabs of the app open.
• The proxy remembers the app's address from the last run, so the overlay also works when the first build of a session fails. On the very first run in a project it learns the address when the app first starts.

Database-backed resources

In a project with migrations/ (the fullstack template), zapline g resource writes everything a Rails or Phoenix scaffold does, as plain code you own:

zapline g resource author name
zapline g resource post title body:text published_on:date author:references

Add ? for an optional field: a nullable column and an Option<T>; an optional reference uses ON DELETE SET NULL. Dates, times and UUIDs come from zapline::chrono and zapline::uuid; the generator turns on zapline's chrono (and uuid) feature in Cargo.toml, so you don't add those crates yourself. A json field takes any JSON value in the API; in forms its textarea shows the stored value as JSON and zapline::extract::json_text parses what comes back (malformed JSON is a 422 naming the field). JSON fields are not sortable or filterable.

Resource fields

Modifiers go after the type, before or after the ?:

zapline g resource user email:string:unique name
zapline g resource review body:text product:references rating:int:index

Unique columns get a unique index rather than an inline UNIQUE, so a later zapline g migration remove_email_from_users can drop the column on SQLite too. A bool can't be unique. References are always indexed.

A reference gets a ?author_id= filter on the list, GET /api/authors/{id}/posts (the author's posts, paged like the main list; 404 for an unknown author), and an author <select> in the forms that shows each author's name (or title, label, email, username, the first required text column, or the id: read from the authors migration). Rows link to the author's page when it has one. Creating or updating a post for an author that doesn't exist answers 422 with code author_not_found, before the generic 409 foreign_key_violation would.

• Another table name: author:ref:users names the column and the error code after author (author_id, author_not_found) and points the foreign key at users.
• Generate the parent first: when no migration creates the parent's table, the generator stops with run zapline g resource author first and writes nothing (Postgres won't create a foreign key to a missing table, and the migration must run after the parent's).
• The same table: an optional reference to the resource's own table works, zapline g resource category name parent:ref:categories? (or category:references?), with GET /api/categories/{id}/categories listing the children. A required one is refused: the first row would have nothing to point at.
• Two references to one table (author:ref:users editor:ref:users?) get no nested route, since /api/users/{id}/posts would be ambiguous; the generator says so, and ?author_id= filters the list instead.

PUT replaces every field; PATCH takes any subset ({"title": "New"}) and leaves the rest. Both set updated_at.

Migrations from the command line

zapline g migration writes the SQL for the project's dialect from the migration's name, with the same field syntax. Each migration is a reversible pair: the .up.sql file and a .down.sql file that undoes it (DROP COLUMN, ADD COLUMN, DROP TABLE), which zapline db rollback runs:

zapline g migration add_published_at_to_posts published_at:datetime?
zapline g migration add_views_to_posts views:int=0     # the default existing rows get
zapline g migration add_email_to_users                 # the column from the name: email TEXT
zapline g migration add_category_to_posts category:references?
zapline g migration remove_legacy_flag_from_posts
zapline g migration create_tags name slug              # id, fields, created_at, updated_at

-- migrations/20261023101500_add_published_at_to_posts.up.sql
ALTER TABLE posts ADD COLUMN published_at TIMESTAMPTZ;
-- migrations/20261023101500_add_published_at_to_posts.down.sql
ALTER TABLE posts DROP COLUMN published_at;

A required column added to a table that has rows needs a value for them: the one after = (views:int=0, status=draft, due:date=2026-01-01, pinned:bool=true), otherwise text gets DEFAULT '', numbers DEFAULT 0 (with a note naming the file, in case that is not what you want) and booleans FALSE. Dates, UUIDs and references have no zero value, so give one with = or add them as optional (due:date?), fill them in, then tighten the column in a later migration. On SQLite, DROP COLUMN needs 3.35 or newer (sqlx bundles one). Any other name with fields creates that table; without fields you get an empty pair (like zapline db new). Rolling back a remove_ migration brings the columns back empty: optional, or with their defaults.

The resource follows the table

When zapline g resource made the table, the module records what it was generated from on a // zapline:resource post title:string ... line near its top. add_<cols>_to_<table> and remove_<cols>_from_<table> then update src/routes/<table>.rs, its pages (templates/<table>/*.html) and its test (tests/<table>.rs): the structs, every query and its binds, listing()'s sort, search and filters, the forms, the table and the show page, the test bodies. The app keeps compiling, and crud_round_trip checks the new columns through POST, GET, the list, PUT and PATCH.

The update is a three-way merge, like git merge-file: the resource is generated with the old fields and with the new ones, and the difference is applied to your files, so your own edits stay. The result is what g resource would write today with the new fields, plus your changes. A file you edited right where the new code goes is left untouched, and the lines to add or remove are printed; if that file is the module, no file is changed, so the module, pages and test never disagree. A hand-written module without the // zapline:resource line (such as the fullstack template's todos, or one generated by an older zapline) gets the fields to add instead. Removing a column of a generated resource also gives the down file the column's real type.

How routes and openapi work

Both commands run your app with an environment variable. The app prints or writes what was asked for and exits before binding a port or running startup hooks:

• ZAPLINE_PRINT_ROUTES=1: App::run prints the route table as JSON and exits.
• ZAPLINE_EXPORT_OPENAPI=<path>: the OpenAPI plugin writes the spec and exits.

So the commands are safe to run without databases or other services, for example in CI to check a committed openapi.json.

Typed clients: zapline client

zapline client -o web/src/api.ts turns the app's OpenAPI document into one TypeScript file with no dependencies (it uses fetch, so it runs in browsers, Node 18+, Deno and Bun):

• an interface per schema, with the doc comments of your Rust types;
• createClient({ baseUrl?, headers?, fetch?, credentials?, csrf? }) and a ready same-origin api, with one method per operation, named after its operationId (the handler name, prefixed with its module when two modules share a name: usersList, postsList). Path parameters come first, then the body, then a query object, then per-call options ({ signal, headers });
• ApiError for non-2xx responses, with status, and zapline's code and details; a ValidationError for 422s, whose fields are typed by the request body.

import { api, ApiError, isValidationError } from "./api";

try {
  await api.createUser({ name: "", email: "ada@example.com" });
} catch (e) {
  if (isValidationError(e, "createUser")) e.fields.name;   // FieldError[] | undefined
  else if (e instanceof ApiError && e.status === 409) { /* ... */ }
}

A .js or .mjs output (zapline client -o static/api.js) gets the same client as an ES module with JSDoc types. Routes that answer with HTML (htmx pages and fragments) are left out. Files pass tsc --strict --exactOptionalPropertyTypes --noUncheckedIndexedAccess and are only rewritten when they change.

zapline dev regenerates clients after every successful build, before the app restarts: frontend/src/api.ts when the project has a frontend/ directory, the ts/js files of a [client] table in zapline.toml, or --client <file>. Change a Rust struct, save, and your frontend's type checker sees the change: end-to-end types without a shared schema language. See Typed frontends for the whole workflow, including /_zapline/api.js for pages without a build step.

AI assistants: zapline mcp

zapline mcp is a Model Context Protocol server on stdin/stdout. It lets Claude Code, Cursor, Zed, VS Code and other MCP clients call zapline directly, and every tool answers in as few tokens as it can:

When the app does not compile, routes, openapi and the db_* tools answer with the compile errors (as check would) instead of "build failed", and when the app exits with an error, its last stderr lines are included. Any answer that mentions a diagnostic code (ZL0004 in a startup error, a panic in a test) ends with that code's fix.

Live tools: debugging the running app

While the app runs under zapline dev with the dev console, the assistant can look at it directly instead of asking you to copy logs:

They find the app through target/zapline-dev.addr, which zapline dev makes the app write (or $ZAPLINE_URL, $ADDR/$PORT, then http://127.0.0.1:8080; each tool also takes a url). The console only answers requests from this machine, and nothing here exists in a release build. A typical loop: the assistant edits a handler, zapline dev restarts the app, call_route shows a 500 with ZL0044, the fix says .database(Database::from_env()), the assistant adds it, and call_route returns 200.

Register it from the project directory:

claude mcp add zapline -- zapline mcp          # Claude Code

{ "mcpServers": { "zapline": { "command": "zapline", "args": ["mcp"] } } }

The second form is the mcp.json / settings entry most other clients use.

Coming from other frameworks

FastAPI

Spring Boot / ASP.NET Core / NestJS

axum

zapline will feel familiar. Extractors, IntoResponse and State work the same way. The differences:

• App::run(addr) gives you a tuned thread-per-core server, with no #[tokio::main] and no serve glue.
• There's no tower Service/Layer stack. Middleware is async fn(Request, Next) -> Response.
• State is keyed by type, so you can register many types and the router has no S generic parameter.
• OpenAPI, validation, DI, configuration, auth, sessions, metrics and health checks are built in.

actix-web

• Route macros look the same (#[get("/")]), and they also document the route in OpenAPI.
• Handlers and state are Send, so any Tokio-ecosystem library works.
• Both use thread-per-core runtimes. zapline uses SO_REUSEPORT listeners and hyper's HTTP stack.

Routing

Registering routes

There are three equivalent styles. Use whichever reads best.

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

// 1. Attribute macros (also generate OpenAPI docs from the signature)
#[get("/users/{id}")]
async fn get_user(Path(id): Path<u64>) -> String { format!("user {id}") }

// 2. Builder methods with named functions
async fn list_users() -> &'static str { "[]" }

fn app() -> App {
    App::new()
        .mount(get_user)
        .get("/users", list_users)
        // 3. Closures
        .get("/ping", || async { "pong" })
}
}

#[route("/items", method = "GET", method = "POST")] registers one handler for several methods. Mount several macro routes at once with a tuple: .mount((get_user, create_user, delete_user)).

Path patterns

Static segments take priority over parameters, so /users/me and /users/{id} can coexist. Parameters are percent-decoded. Trailing slashes are significant. To make /users/ match /users, use NormalizePath.

Groups and nesting

Routes is a group of routes. It can carry its own middleware and metadata, and you can nest it under a prefix:

#![allow(unused)]
fn main() {
let admin = Routes::new()
    .get("/stats", stats)
    .delete("/users/{id}", ban_user)
    .wrap(require_admin);          // only applies to this group

let app = App::new()
    .nest("/admin", admin)         // -> /admin/stats, /admin/users/{id}
    .nest("/api/v1", api_v1());    // versioning is just nesting
}

Groups can be built in other modules or crates and merged with .merge(routes) or .mount(routes).

Methods, 404 and 405

• A path registered for some methods returns 405 Method Not Allowed with an Allow header for any other method.
• HEAD is served automatically by the GET handler (with no body).
• Unknown paths return a JSON 404. Use .fallback(handler) to customize it, for example to serve a SPA.
• .any(path, handler) matches every method that isn't otherwise registered on that path.

Route metadata

Every route carries a typed metadata map. Plugins use it: OpenAPI stores summaries and tags there, auth stores required roles, and rate limiting stores per-route policies. You can attach your own:

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Audit(&'static str);

let app = App::new()
    .post("/payments", pay).meta(Audit("payments"))
    .wrap_route(|req: Request, next: Next| async move {
        if let Some(Audit(kind)) = req.route().and_then(|r| r.meta::<Audit>()) {
            println!("audit: {kind}");
        }
        next.run(req).await
    });
}

Routes::meta_all(value) applies metadata to every route in a group.

Performance notes

Routing is a radix-tree lookup (matchit) followed by a fixed-slot method match. Route parameters are stored as byte ranges into the request path, inline for up to 4 parameters, so routing never allocates.

Extractors

Handler arguments are extractors: types that know how to build themselves from the request. A handler can take up to 12 arguments. Every argument except the last must be a parts extractor, meaning it doesn't read the body. The last argument may consume the body.

#![allow(unused)]
fn main() {
#[post("/orgs/{org}/members")]
async fn add_member(
    State(db): State<Db>,                 // app state
    Path(org): Path<String>,              // route parameter
    Query(opts): Query<AddOptions>,       // query string
    user: CurrentUser<Claims>,            // auth (see the Security chapter)
    Json(body): Json<NewMember>,          // body: must be last
) -> Result<StatusCode> { /* ... */ }
}

If an extractor fails, its error response is returned and the handler isn't called. For example, a bad path parameter gives a 400 and a wrong content type gives a 415. Rejections carry a stable code, and details that locate the problem:

POST /orders  {"items": [{"qty": "x"}]}

HTTP/1.1 422 Unprocessable Entity
{"error":"invalid request body: invalid type: string \"x\", expected u32",
 "code":"invalid_body","details":{"column":22,"line":1,"path":"items[0].qty"}}

Built-in extractors

Feature modules add more: Valid<T>, Dep<T>, BackgroundTasks, BearerToken, Jwt<C>, CurrentUser<U>, CookieJar, Session, Multipart, BodyStream, WebSocketUpgrade, RequestId. Each is covered in its own chapter.

Path parameters in detail

#![allow(unused)]
fn main() {
#[get("/users/{id}")]                      async fn a(Path(id): Path<u64>) {}
#[get("/repos/{owner}/{name}")]            async fn b(Path((owner, name)): Path<(String, String)>) {}

#[derive(serde::Deserialize)]
struct RepoPath { owner: String, name: String }
#[get("/repos/{owner}/{name}/issues")]     async fn c(Path(p): Path<RepoPath>) {}
}

Numbers, booleans, chars, enums (unit variants) and Option<T> are parsed from the textual value. A value that doesn't parse returns 400 with a message that names the parameter.

Body limits

Every buffering extractor enforces the app's body limit (default 2 MiB, configurable with App::body_limit(bytes)). Oversized bodies are rejected with 413 before they're read in full when Content-Length is known, and as soon as the limit is crossed otherwise.

Writing your own extractor

Implement FromRequestParts (or FromRequest to consume the body). Both use async fn:

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

pub struct Tenant(pub String);

impl FromRequestParts for Tenant {
    async fn from_request_parts(req: &mut Request) -> Result<Self> {
        req.headers()
            .get("x-tenant")
            .and_then(|v| v.to_str().ok())
            .map(|t| Tenant(t.to_owned()))
            .ok_or_else(|| Error::bad_request("missing x-tenant header").with_code("missing_tenant"))
    }
}

async fn handler(Tenant(t): Tenant) -> String { t }
}

An extractor can do async work too, such as looking up a session or calling a service. To compute a value only once per request when several extractors need it, wrap it in Cached<T> (see Dependency injection).

Responses

A handler can return anything that implements IntoResponse:

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

// `status = 201` documents the status the handler picks at run time.
#[post("/users", status = 201)]
async fn create(Json(u): Json<NewUser>) -> Result<(StatusCode, Json<User>)> {
    let user = save(u).await?;
    Ok((StatusCode::CREATED, Json(user)))
}

async fn download() -> impl IntoResponse {
    (
        [(header::CONTENT_DISPOSITION, HeaderValue::from_static("attachment; filename=\"report.csv\""))],
        "id,name\n1,ada\n",
    )
}
}

Streaming responses such as Server-Sent Events, file downloads and NDJSON are covered in Server-Sent Events & streaming.

Custom response types

#![allow(unused)]
fn main() {
struct Csv(String);

impl IntoResponse for Csv {
    fn into_response(self) -> Response {
        ([(zapline::header::CONTENT_TYPE, HeaderValue::from_static("text/csv"))], self.0).into_response()
    }
}
}

Errors

zapline has one error type, zapline::Error, and one result alias, zapline::Result<T>.

#![allow(unused)]
fn main() {
#[get("/users/{id}")]
async fn get_user(State(db): State<Db>, Path(id): Path<u64>) -> Result<Json<User>> {
    let user = db.find(id).await?                // any std::error::Error -> 500
        .ok_or_else(Error::not_found)?;          // explicit client error -> 404
    Ok(Json(user))
}
}

Rules

• Any std::error::Error converts into a 500 with ?. The underlying error is logged (through tracing when enabled) and never sent to the client. The client sees {"error":"internal server error"}.

• Client errors are explicit. Use the constructors: bad_request(msg), unauthorized(), forbidden(), not_found(), conflict(msg), unprocessable(msg), too_many_requests(), service_unavailable(msg), payload_too_large(), unsupported_media_type(msg), or Error::new(status, msg).

• Errors are structured. Each one renders as JSON:

  { "error": "validation failed", "code": "validation_error", "details": [ ... ] }
  

  code and details are omitted when unset.

#![allow(unused)]
fn main() {
Err(Error::conflict("email already registered")
    .with_code("email_taken")                       // stable, machine-readable
    .with_details(json!({ "field": "email" }))      // structured context
    .with_header(header::RETRY_AFTER, HeaderValue::from_static("30")))
}

Customizing the error format

Every error response includes an ErrorReport (status, message, code, details) in its extensions. That covers extractor rejections, handler errors, 404s and 405s. App::error_handler re-renders all of them in one place. For example, to emit RFC 7807 application/problem+json:

#![allow(unused)]
fn main() {
App::new().error_handler(|e: &ErrorReport| {
    let body = serde_json::json!({
        "type": "about:blank",
        "title": e.status.canonical_reason(),
        "status": e.status.as_u16(),
        "detail": e.message,
        "code": e.code,
    });
    (e.status, [(header::CONTENT_TYPE, HeaderValue::from_static("application/problem+json"))], body.to_string())
        .into_response()
})
}

Domain errors

Map your own error enums into zapline::Error once, and ? will work everywhere:

#![allow(unused)]
fn main() {
enum AppError { NotFound, Db(sqlx::Error) }

impl From<AppError> for zapline::Error {
    fn from(e: AppError) -> Self {
        match e {
            AppError::NotFound => Error::not_found().with_code("user_not_found"),
            AppError::Db(e) => Error::internal("database error").with_source(e),
        }
    }
}
}

(Implement From for your error type instead of std::error::Error. Otherwise, the blanket conversion turns it into a plain 500.)

Diagnostic codes

The mistakes you make while building an app (a dependency nobody provides, a duplicate route, a config key nobody set, a template that does not parse, a request body that does not match its type) have stable codes, ZL0001 to ZL0091. Each has a title, the cause, and the fix written as the code to add. The code appears wherever the mistake surfaces:

$ cargo run
startup failed: 500 Internal Server Error: resource `my_app::Settings` is not registered [ZL0004]
  fix: Register it first: .state(value) // value: my_app::Settings; or res.insert(value) in an earlier on_startup hook
  see: zapline explain ZL0004

Codes are never renumbered or reused, so they are safe to search for, to match on in tests and to put in a bug report. They are diagnostics for developers: the JSON your clients see keeps its own code (missing_dependency, invalid_json), and the ZL code is never added to it.

#![allow(unused)]
fn main() {
let err = Resources::default().dep::<Repo>().unwrap_err();
assert_eq!(err.code(), Some("missing_dependency")); // sent to clients
assert_eq!(err.diagnostic_code(), Some("ZL0002")); // for you
}

The registry lives in one file, crates/zapline/src/codes.in, also available as zapline::codes::ALL and zapline::codes::lookup("ZL0002"). The index below is generated from it.

The dev error page

In a debug build, App::dev_errors() turns every 500 and every panic into a page that says what broke, for requests from your own machine:

#![allow(unused)]
fn main() {
App::new()
    .dev_errors()        // also on with .dev_console(), and whenever ZAPLINE_DEV=1 (zapline dev sets it)
    .mount(routes)
    .run("127.0.0.1:8080")
}

• Browsers (Accept: text/html) get an HTML page with the real error and its causes, the code and its fix, the file and line of a panic, the request with its headers (credentials hidden), and a Copy fix prompt block: one click copies a ready-made prompt for your AI assistant with the request, the error, the cause and the suggested fix.

• JSON clients get RFC 9457 application/problem+json:

  {"type":"https://samsamurai301.github.io/zapline/errors.html#zl0002","title":"No provider for a dependency",
   "status":500,"detail":"no provider registered for `my_app::Repo`","error":"no provider registered for `my_app::Repo`",
   "code":"ZL0002","error_code":"missing_dependency","fix":".provide(value) // value: my_app::Repo; ...",
   "request":"GET /orders"}
  

  (error repeats detail so clients that read the usual {"error": ..} keep working; error_code is the client-facing code.)

• Rejected requests (a 4xx the framework recognized, such as invalid_json) keep their normal body and gain an x-zapline-diagnostic: ZL0062 header.

It is safe to leave in. A release build compiles it out (.dev_errors() does nothing), requests from other machines or through a proxy get the usual generic error, and when it is off nothing is added to the request path: the middleware is installed when the app is built, only if dev errors are on.

Code index

ZL0001

State not registered. A handler takes State<T>, but no value of that exact type was registered. State is looked up by type, so State<Arc<Db>> and State<Db> are different keys.

App::new().state(value) // value: T; or in a startup hook: res.insert(value)

ZL0002

No provider for a dependency. A handler takes Dep<T> (or code calls res.dep::<T>()), but nothing provides T. Providers are registered on the app before it starts.

.provide(value) // value: T; to build it at startup: .provide_with(|res: Resources| async move { Ok(value) }); for a trait object: .provide_dyn::<dyn Trait>(Arc::new(imp))

ZL0003

A dependency failed to initialize. The factory given to provide_with / provide_injected returned an error, so the app did not start. The message ends with the factory's own error.

Fix the cause named in the message; inside the factory, resolve what it needs with res.dep::<Other>()? and register Other before it

ZL0004

Resource not registered. Resources::require::<T>() found no value of type T. Startup hooks run in the order they were registered, so a hook can only require what an earlier hook or .state(..) inserted.

Register it first: .state(value) // value: T; or res.insert(value) in an earlier on_startup hook

ZL0005

Request extension missing. A handler takes Extension<T>, but no middleware inserted a T into this request's extensions, or the middleware runs after the handler is reached.

In a middleware that runs before the handler: req.extensions_mut().insert(value); // value: T, installed with .wrap(..) or .wrap_route(..)

ZL0010

Duplicate route. Two handlers were registered for the same method and path. zapline refuses to pick one silently; zapline routes prints the whole table.

Remove one of the two registrations of T, or change its method or path

ZL0011

Invalid or conflicting route path. The router cannot add this path: two routes give the same segment different parameter names (/users/{id} and /users/{name}), a catch-all is not the last segment, or a brace is unbalanced.

Use one parameter name per position (/users/{id} everywhere) and keep catch-alls last: /files/{*path}

ZL0012

Route metadata without a route. Routes::meta(..) (or App::meta) attaches metadata to the route registered just before it, and none was registered yet.

Call it right after the route: .get("/x", handler).meta(value)

ZL0013

Route information used before routing. MatchedPath (or req.route()) was used in global middleware, which runs before the router has matched the request.

Install that middleware after routing: .wrap_route(mw) instead of .wrap(mw)

ZL0020

Cargo feature not enabled. The app asks for something that is compiled only with a zapline Cargo feature that is off.

In Cargo.toml: zapline = { version = "0.1", features = ["T"] }

ZL0021

Database URL does not match the backend. The database URL names one backend (postgres://, sqlite://) while the app's Database uses the other, usually because only one of the postgres and sqlite features is enabled.

Use a URL for the compiled backend (T), or enable the other feature: zapline = { version = "0.1", features = ["postgres"] } and Database::postgres(url)

ZL0030

Config file unreadable. A configuration file exists but cannot be read (permissions, a directory in its place, invalid UTF-8).

Fix the file's permissions or contents: T

ZL0031

Config file malformed. A TOML layer (config/default.toml, config/<profile>.toml) or .env does not parse. The message gives the file and the line.

Fix the syntax at the reported line; TOML strings need quotes: name = "value"

ZL0032

Config key missing. The settings struct has a required field that no layer sets.

Set T in config/default.toml, or as an environment variable (APP__ prefix, __ between levels, e.g. APP__SERVER__PORT=8080), or make the field Option<_> / #[serde(default)]

ZL0033

Config value has the wrong type. A config value does not deserialize into the field's type. The message says which layer set it.

Give T a value of the field's type in the layer named in the message (numbers unquoted: port = 8080)

ZL0034

Invalid config profile name. The profile (APP_PROFILE or Config::builder().profile(..)) contains characters other than ASCII letters, digits, - and _.

Use a plain name: APP_PROFILE=production

ZL0040

Database URL not set. Database::from_env() reads DATABASE_URL (or the variable you named), and it is not set.

Add to .env: DATABASE_URL=sqlite://app.db?mode=rwc (or postgres://user:pass@localhost/app)

ZL0041

Cannot connect to the database. The pool could not open a connection at startup: the server is down, the credentials are wrong, or a SQLite file cannot be created.

Check DATABASE_URL; for SQLite add ?mode=rwc so the file is created; for Postgres start it, e.g. docker run -p 5432:5432 -e POSTGRES_PASSWORD=pass postgres

ZL0042

Migrations unreadable. The migrations directory exists but its files cannot be read or are not named <version>_<name>.sql.

Create migrations with: zapline db new <name> (names them <timestamp>_<name>.sql)

ZL0043

Migration failed. A migration's SQL failed, or an applied migration was edited (its checksum changed). Applied migrations are immutable.

Fix the SQL of the migration named in the message; to change an applied one, add a new migration: zapline db new fix_<name> (in development you can also delete the SQLite file)

ZL0044

No database registered. A handler takes Db, but the app never called .database(..). With both the postgres and sqlite features on, Db means Postgres; use SqliteDb for SQLite.

App::new().database(Database::from_env())

ZL0045

Database registered too late. Jobs and seed data use the pool that .database(..) creates at startup, so it has to be registered before them.

App::new().database(Database::from_env()).jobs(Jobs::new().register::<MyJob>()).seed(|db| async move { Ok(()) })

ZL0046

No seed data. zapline db seed ran, but the app has no seed function.

.seed(|db| async move { Factory::new("todos").create(&db).await?; Ok(()) }) // after .database(..)

ZL0050

No templates registered. A handler takes Views, but the app has no template directory.

App::new().views("templates")

ZL0051

Template error. A template does not exist, does not parse, or failed while rendering (an undefined filter, a wrong type). The message names the template and line. Templates are found relative to the working directory, i.e. the project root under cargo run.

Fix the template at the reported line; extend layouts with {% extends "base.html" %} and pass every variable the template uses: views.render("page.html", context! { title })

ZL0060

Path parameter rejected. A Path<T> parameter did not parse into its type, e.g. /users/abc for Path<u64>. The client gets 400 invalid_path.

Send a value of the parameter's type, or take it as text: Path(id): Path<String>

ZL0061

Query string rejected. Query<T> could not deserialize the query string: a missing required field or a value of the wrong type. The client gets 400 invalid_query.

Make optional fields Option<_> or #[serde(default)] in the query struct

ZL0062

Malformed JSON body. The body of a Json<T> request is not valid JSON. details has the line and column. The client gets 422 invalid_json.

Send valid JSON with Content-Type: application/json, e.g. curl -H 'content-type: application/json' -d '{"name":"x"}'

ZL0063

JSON body has the wrong shape. The body is valid JSON but does not match T: a missing field, a wrong type, an unknown variant. details.path points at the value. The client gets 422 invalid_body.

Match the request type, or relax it: Option<_> / #[serde(default)] for fields clients may leave out

ZL0064

Wrong Content-Type. Json<T> needs application/json and Form<T> needs application/x-www-form-urlencoded. The client gets 415 unsupported_media_type.

Send the header: Content-Type: application/json (fetch: headers: { 'content-type': 'application/json' })

ZL0065

Form body rejected. Form<T> could not deserialize the form. The client gets 422 invalid_form.

Name the inputs like the struct's fields; checkboxes are absent when unchecked, so use #[serde(default)] bool

ZL0066

Validation failed. Valid<T> ran the struct's #[validate(..)] rules and some failed. details lists them per field. The client gets 422 validation_error.

Send values that pass the rules shown in details, or change the rules: #[validate(length(min = 1))]

ZL0067

Body too large. The request body is larger than the app's limit (2 MiB by default). The client gets 413.

Raise the limit: App::new().body_limit(16 * 1024 * 1024); or stream the body with BodyStream

ZL0068

Body too slow. The client took longer than ServerConfig::body_read_timeout (30s by default) to send a buffered request body. The client gets 408 and the connection is closed, so slow senders cannot hold connections open.

Raise the timeout: app.server_config_mut().body_read_timeout = Some(Duration::from_secs(120)); or stream large uploads with BodyStream or Multipart

ZL0070

No mailer registered. A handler takes Mailer, but the app has none.

App::new().mailer(Mailer::from_env()?) // SMTP_URL; without it, mail goes to the dev inbox at /_dev/mail

ZL0071

No cache registered. A handler takes Cache, but the app has none.

App::new().cache(Cache::memory())

ZL0072

No Redis registered. A handler takes Redis, but the app has none.

App::new().redis(Redis::from_env()?) // REDIS_URL=redis://localhost:6379

ZL0073

No cookie key. Signed or private cookies (and sessions) need a key, and none was registered.

App::new().cookie_key(zapline::cookies::key_from_env("SESSION_SECRET")?) // 32+ random bytes: openssl rand -base64 48

ZL0074

No CSRF middleware. A handler takes CsrfToken, but the Csrf middleware that issues tokens is not installed.

App::new().wrap(Csrf::new())

ZL0075

JWT not configured. JWT extraction or signing needs a JwtConfig, and none was registered.

App::new().jwt(JwtConfig::hs256(std::env::var("JWT_SECRET")?))

ZL0076

No translations registered. A handler takes Locale, but the app has no translations.

App::new().i18n(I18n::load("locales")?)

ZL0077

No file storage registered. A handler takes Storage, but the app has none.

App::new().storage(Storage::from_env()?) // a local directory, or S3 when S3_BUCKET is set

ZL0078

Authorization misconfigured. A route requires roles or scopes, but nothing checks them after routing, or a Guard was installed as global middleware. Policies fail closed: the route answers 500 instead of letting the request through.

Check roles after routing: .wrap_route(Authenticate::new(authenticator).authorize()) or .wrap_route(guard), never .wrap(guard)

ZL0080

Handler panicked. A handler or middleware panicked. The panic was caught and answered with 500. Panics usually come from unwrap(), expect() or indexing.

Return an error instead of panicking: replace .unwrap() with ? (or .ok_or_else(Error::not_found)?) in the function at the reported location

ZL0081

Unhandled error. An error reached the client as a 500 through ?: any std error converts into a logged 500 with a generic message. Client mistakes should get a 4xx instead.

Map expected failures to client errors: .ok_or_else(Error::not_found)? or .map_err(|e| Error::bad_request(e.to_string()))?; keep real failures as Error::internal("what failed").with_source(e)

ZL0090

Dev console not mounted. The live tools of zapline mcp read the running app's /_dev console, which this app does not serve. It exists only in debug builds.

App::new().dev_console() // debug builds only; does nothing in release

ZL0091

Dev app not running. Nothing answers at the app's address. The live tools need the app running, ideally under zapline dev, which records its address in target/zapline-dev.addr.

Start it: zapline dev (or pass the address: url = "http://127.0.0.1:8080")

Middleware

Middleware is an async function that receives the request plus next, the rest of the pipeline:

#![allow(unused)]
fn main() {
use std::time::Instant;
use zapline::prelude::*;

async fn timing(req: Request, next: Next) -> Response {
    let start = Instant::now();
    let mut res = next.run(req).await;
    let ms = start.elapsed().as_secs_f64() * 1000.0;
    res.headers_mut().insert("server-timing", HeaderValue::from_str(&format!("app;dur={ms:.2}")).unwrap());
    res
}

App::new().wrap(timing);
}

Middleware can short-circuit by returning a response without calling next.run. It can also modify the request (headers, extensions, URI) before passing it on, and modify the response afterwards. For configurable middleware, implement the Middleware trait on a struct.

Where middleware runs

request ─▶ global (App::wrap) ─▶ routing ─▶ route (App::wrap_route) ─▶ group (Routes::wrap) ─▶ handler

Middleware runs in the order it was added (the first wrap is the outermost layer).

Passing data to handlers

Insert typed values into the request extensions and read them with Extension<T>:

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct Tenant(String);

async fn tenant(mut req: Request, next: Next) -> Response {
    let t = req.headers().get("x-tenant").and_then(|v| v.to_str().ok()).unwrap_or("default").to_owned();
    req.extensions_mut().insert(Tenant(t));
    next.run(req).await
}

async fn handler(Extension(Tenant(t)): Extension<Tenant>) -> String { t }
}

Built-in middleware

See Hardening middleware for configuration details.

State, lifecycle & plugins

State

Register any Clone + Send + Sync + 'static value and extract it with State<T>:

#![allow(unused)]
fn main() {
#[derive(Clone)]
struct AppConfig { greeting: String }

let app = App::new()
    .state(AppConfig { greeting: "hi".into() })
    .get("/", |State(cfg): State<AppConfig>| async move { cfg.greeting });
}

State is keyed by type, so you can register as many types as you want. State<T> clones T for each request, so wrap large or mutable data in an Arc (connection pools are already cheap to clone). For trait objects and services, prefer Dep<T>.

Startup and shutdown hooks

Resources that need async setup, such as database pools, caches, clients or warmed data, belong in a startup hook. Hooks run in registration order before the server accepts connections. Anything a hook inserts into Resources becomes available as State<T>:

#![allow(unused)]
fn main() {
App::new()
    .on_startup(|res: Resources| async move {
        let url = res.require::<Settings>()?.database_url;
        res.insert(Db::connect(&url).await?);      // -> State<Db>
        Ok(())
    })
    .on_shutdown(|res: Resources| async move {
        if let Some(db) = res.get::<Db>() { db.close().await; }
    })
}

• If a startup hook fails, App::run returns the error and never binds the port.
• Shutdown hooks run in reverse order, after the server has drained its connections.
• Hooks run on a small long-lived system runtime. Resources created there, like pool connections and background jobs, keep being driven for the life of the server.
• In tests, App::test() runs startup hooks lazily on the first request. Call client.start().await to run them eagerly, and client.shutdown().await to run the shutdown hooks.

Plugins

A plugin is a reusable bundle of routes, middleware, state and hooks. Any function FnOnce(App) -> App is a plugin:

#![allow(unused)]
fn main() {
pub fn admin_console(app: App) -> App {
    app.nest("/admin", admin_routes())
       .on_startup(|res| async move { /* ... */ Ok(()) })
}

App::new().plugin(admin_console);
}

For configurable plugins, implement the Plugin trait on a struct. The built-in OpenApi, Health and Metrics plugins all do this.

Build hooks

App::on_build(|routes: &[&'static RouteInfo]| -> Routes) runs once the route table is final. A plugin can inspect every route and its metadata, then add more routes. This is how /openapi.json is generated once at startup instead of on each request:

#![allow(unused)]
fn main() {
App::new().on_build(|routes| {
    let listing: Vec<String> = routes.iter().map(|r| r.path().to_owned()).collect();
    Routes::new().get("/_routes", move || {
        let body = listing.join("\n");
        async move { body }
    })
})
}

Builder-time storage

App::extensions_mut() is a typed map that plugins can use to share configuration while the app is being assembled.

Testing

App::test() turns an app into an in-process client. It runs the full pipeline (global middleware, routing, route middleware, extractors, handlers, error rendering) without opening a socket, so tests are fast and deterministic.

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

fn app() -> App {
    App::new().mount((create_user, get_user))
}

#[tokio::test]
async fn creates_and_fetches_a_user() {
    let client = app().test();

    let res = client
        .post("/users")
        .json(&serde_json::json!({ "name": "ada", "email": "ada@example.com" }))
        .send()
        .await;
    assert_eq!(res.status(), StatusCode::CREATED);
    let created: User = res.json();

    let res = client.get(&format!("/users/{}", created.id)).send().await;
    assert_eq!(res.status(), 200);
    assert_eq!(res.json::<User>().name, "ada");
}
}

Request builder

#![allow(unused)]
fn main() {
use zapline::test::MultipartForm;

let form = MultipartForm::new()
    .text("title", "Holiday")
    .file("photo", "beach.png", "image/png", png_bytes);
let res = client.post("/upload").multipart(form).send().await;
}

Response helpers

status(), headers(), header(name) -> Option<&str>, header_all(name) -> Vec<&str>, text(), bytes(), json::<T>() (panics with the body text if parsing fails) and cookie(name), which returns the response's Set-Cookie for that cookie with its attributes (value(), path(), max_age(), http_only(), is_removal()...).

assert_status(..) and assert_header(name, value) return the response, so they chain, and their panic messages include the response body:

#![allow(unused)]
fn main() {
client.post("/users").json(&new_user).send().await
    .assert_status(StatusCode::CREATED)
    .assert_header("content-type", "application/json");
// panics with: expected status 201, got 422 Unprocessable Entity
//              response body: {"error":"invalid request body: missing field `email`",...}
}

Cookies and sessions

app.test() is stateless: each request carries only the headers you set. .with_cookies() gives the client a cookie store, shared by its clones, that works like a browser's: it keeps every Set-Cookie it is allowed to and sends the matching cookies back in one Cookie header. That makes login flows one line per step:

#![allow(unused)]
fn main() {
let browser = app().test().with_cookies();
browser.post("/login").json(&credentials).send().await.assert_status(200);
browser.get("/me").send().await.assert_status(200);
browser.post("/logout").send().await;
assert_eq!(browser.cookie("zapline.sid"), None);
}

Calling .with_cookies() again starts a separate store, e.g. for a second user. The store applies the rules browsers do (RFC 6265 and 6265bis):

Cookies you set with .header("cookie", ..) are sent first and win over stored ones with the same name.

Origins and cross-site requests

Relative URIs go to http://localhost unless you pick the site with .base_url("https://app.example.com"): requests then get a Host header, and https makes them secure (ConnInfo::secure). Absolute URIs (client.get("https://api.example.com/x")) use their own origin.

.from_origin(url) sends a request as if a page on url started it with a link or a form, and .fetch_from(url) as a fetch with credentials. They add the Origin and Sec-Fetch-Site/Sec-Fetch-Mode headers a browser would, and the store applies SameSite. Sites are compared like browsers do, by scheme and registrable domain, using a short built-in list of multi-label public suffixes (co.uk, github.io, ...) instead of the full Public Suffix List. So you can test CSRF defenses against what a browser would really send:

#![allow(unused)]
fn main() {
let browser = app().test().with_cookies().base_url("https://app.example.com");
browser.post("/login").json(&credentials).send().await.assert_status(200);

// A form on another site: the Lax session cookie stays home, and
// `SameOrigin` refuses the request.
browser.post("/transfer").from_origin("https://evil.example").send().await.assert_status(403);
// A sibling subdomain is the same site, and the cookie goes along.
browser.post("/transfer").from_origin("https://blog.example.com").send().await;
}

To look inside the store:

#![allow(unused)]
fn main() {
// JavaScript can read the CSRF token but never the session id.
let js = browser.document_cookie("https://app.example.com/");
assert!(js.contains("__Host-zapline.csrf=") && !js.contains("zapline.sid"));

// evil.example.com can plant a cookie for all of example.com, but not a __Host- one.
assert!(browser.set_cookie("https://evil.example.com/", "csrf=x; Domain=example.com"));
assert!(!browser.set_cookie("https://evil.example.com/", "__Host-csrf=x; Domain=example.com; Path=/; Secure"));
}

Not modelled: redirects are not followed, there is no per-domain cookie limit or eviction, and the Chrome "Lax+POST" two-minute exception for cookies without a SameSite attribute is not applied.

Fuzz every route

Your OpenAPI document already says what every route accepts and returns, so zapline can write the tedious tests for you. client.fuzz() walks the document and sends each operation a few hundred requests generated from its own JSON Schemas:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn every_route_survives_fuzzing() {
    app().test().fuzz().await.assert_clean();
}
}

For every operation it sends, in this order:

• a typical valid request, using schema examples when there are some;
• boundary values that are still valid: empty and maximum-length strings, unicode (combining marks, emoji, right-to-left text, NUL), 0, -1 and the limits of each integer type (u8::MAX, i32::MIN...), tiny and huge floats, empty and long arrays, objects with only their required fields or with all of them;
• invalid input: each required parameter and field missing, wrong types, numbers out of range, strings shorter than minLength or longer than maxLength, unknown enum variants and properties, malformed and deeply nested JSON, the wrong content type, a body one byte over the size limit;
• random requests (a third of their values at the boundaries) until the budget of 100 requests per operation is spent.

A response is a failure when:

Each failure is reported once per operation and kind, after shrinking: optional parameters and fields are dropped and strings and arrays shortened for as long as the same failure reproduces. The report gives the minimal request and a line of test code that replays it:

zapline fuzz: 6 operations, 642 requests, seed 24301: 2 failures

1) GET /ratio/{n} (ratio): panicked: attempt to divide by zero at src/routes/math.rs:12:5
   case: boundary integer for path parameter `n` (hit by 8 requests)
   request: GET /ratio/0
   response: none
   reproduce: client.request(Method::GET, "/ratio/0").send().await

2) GET /stats (stats): response does not match its schema (1 error)
   - /count: expected integer, got string "many"
   case: valid request (hit by 100 requests)
   request: GET /stats
   response: 200 OK {"count":"many"}
   reproduce: client.request(Method::GET, "/stats").send().await

rerun the same requests with ZAPLINE_FUZZ_SEED=24301

Paste the reproduce: line into a regular test to keep the bug fixed. The fuzzer checks the app against the document its OpenApi plugin serves (including .modify(..) hooks), or one generated with the default settings when there is no plugin, so a failure is either a bug in the handler or a gap in the docs: both are worth fixing.

Configuration

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

let report = app()
    .test()
    .fuzz()
    .config(
        FuzzConfig::new()
            .seed(7)                        // same seed, same requests
            .cases(500)                     // requests per operation
            .bearer("test-token")           // sent with every request
            .header("x-tenant", "acme")
            .timeout(Duration::from_secs(1))
            .allow_status(409)              // accepted from every operation
            .only("/admin")                 // operation id, `METHOD /path` or path prefix
            .skip("POST /webhooks"),
    )
    .await;
for failure in report.failures() {
    println!("{} -> {}", failure.request(), failure.kind());
}
report.assert_clean();
}

Runs are deterministic: the requests depend only on the seed and the document, and each operation has its own stream of cases, so adding a route does not change what the others get. When the test does not set them, the ZAPLINE_FUZZ_SEED and ZAPLINE_FUZZ_CASES environment variables choose the seed and the budget, which is how zapline fuzz --seed 7 --cases 1000 explores further without editing the test.

The app keeps its state across cases, as a real server would: requests that create things create them, so later GETs see real data. Each request comes from its own peer address, so per-IP rate limits don't turn the run into a wall of 429s. Operations documented as WebSocket upgrades or server-sent event streams are skipped and listed in the report; an undocumented event stream is recognized by its text/event-stream content type and not read past its headers. After its first timeout an operation gets no further cases. Request schemas use the JSON Schema subset schemars emits; pattern and string formats are not checked by the validator (values for common formats such as email, uuid and date-time are still generated correctly).

Projects created with zapline new include this test as tests/fuzz.rs; zapline fuzz runs it and prints the report.

Lifecycle in tests

Startup hooks run on the first request. Use client.start().await to run them up front, client.resources().await to inspect state, and client.shutdown().await to run shutdown hooks. To swap real dependencies for fakes, register replacements before calling .test(). Registering the same type again replaces the earlier value:

#![allow(unused)]
fn main() {
let client = app().provide_dyn::<dyn UserRepo>(Arc::new(FakeRepo::default())).test();
}

Real sockets

When a feature needs a real connection (WebSockets, TLS, HTTP/2), serve on an ephemeral port:

#![allow(unused)]
fn main() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await?;
let addr = listener.local_addr()?;
tokio::spawn(app().serve(listener));
// connect to `addr` with any client
}

Snapshot tests from real traffic

Click through your app once and keep what happened as a regression test. In a debug build the dev console can record every request and the response it got; saved, they replay through app.test() on every cargo test.

1. Record. Start the app with zapline dev --record (it sets ZAPLINE_RECORD=1), or press Start recording at /_dev. Then use the app: a browser, curl, your frontend.

2. Save. Run zapline snap signup, or name the snapshot in the console and press Save as snapshot test. You get tests/snapshots/signup.json and, the first time, tests/snapshots.rs:

   #![allow(unused)]
   fn main() {
   #[tokio::test]
   async fn recorded_traffic() {
       my_app::app()
           .test()
           .replay_snapshots("tests/snapshots")
           .await;
   }
   }

3. Run. cargo test replays every file in tests/snapshots/ in name order, each request in recorded order. A response must have the recorded status and body, or the test fails with a diff:

   1 of 5 recorded response(s) changed:
   
   tests/snapshots/signup.json #4 POST /users
     body (- recorded, + actual):
         {
           "code": "email_taken",
       -   "error": "email already registered"
       +   "error": "that email is taken"
         }
   
   If the new responses are right, accept them with ZAPLINE_UPDATE_SNAPSHOTS=1 cargo test
   

4. Accept changes. When the new responses are right, ZAPLINE_UPDATE_SNAPSHOTS=1 cargo test --test snapshots rewrites the snapshot files that changed (and only those), each as the replay saw it: every exchange in an updated file is stored with the ids and values of this run, so the requests after a changed response still line up on the next run. Review the change in your diff like any other code.

What may differ between runs

Values that legitimately change are compared by kind, not by value, in JSON and in HTML or text bodies alike:

Ids also carry forward. When the recording's POST /users answered {"id": 7} and the replay's answers {"id": 1}, the requests after it are sent with 1 where the recording had 7: in path segments (/users/7 becomes /users/1), in id fields of the query, form or JSON body (user_id=7), and in the expected responses (an HTML page's hx-delete="/users/7"). Ids of three digits or more, UUIDs and tokens are replaced wherever they appear as a word; a bare 7 elsewhere is left alone, since it is more likely a count or a page number. So a session recorded against a database full of data replays against an empty test database.

Credentials and cookies

Authorization, Cookie, Proxy-Authorization, X-Api-Key, X-Auth-Token and CSRF token headers are never recorded: the snapshot says "[redacted]" and the replay does not send them (CSRF headers carry the replay's own token, see below). Each snapshot file replays with a fresh cookie jar, like a new browser, so a recorded login sets the session cookie that the following requests use. For bearer tokens and API keys, give the replay a test credential:

#![allow(unused)]
fn main() {
app().test()
    .replay_snapshots("tests/snapshots")
    .header("authorization", "Bearer test-token")
    .await;
}

Secret-looking fields of the query, a JSON body (at any depth) or a urlencoded form are recorded as "[redacted]" too, in requests and responses: names containing password, secret, token, csrf, xsrf or api_key, or ending in _hash. So a login form, a reset link's ?token= and a JWT in a login response never land in a snapshot file. A redacted response value matches whatever the replay answers. To replay a recorded login, give the replay the value to send in place of each redacted field:

#![allow(unused)]
fn main() {
app().test()
    .replay_snapshots("tests/snapshots")
    .secret("password", "test-password")
    .await;
}

CSRF tokens need nothing: a CSRF-protected app (Csrf) mints a new token for each replay's browser, so the replay sends the token from its CSRF cookie (a cookie whose name contains csrf or xsrf, such as zapline.csrf) in each recorded CSRF form field, JSON key and header (x-csrf-token, as htmx sends it), the way the page's form or script would.

Other parts of a body (HTML pages, multipart uploads, plain text) are recorded as they are: record with throwaway dev accounts.

What is recorded

The method, path, query, the headers that affect a response (accept, accept-language, content-type, host, origin, referer, sec-fetch-site, if-none-match, x-requested-with and htmx's hx-*), the body, the status, the content type and the response body. JSON bodies are stored as JSON, text as text and anything else as base64, so the files read well in a review.

Not recorded: the console's own requests, static files (CSS, scripts, images, fonts), WebSocket upgrades, and requests whose body is streamed or over 64 KiB. A response that is streamed (SSE), compressed or over 64 KiB is recorded without its body ("body_not_recorded"), and only its status is compared; an update run fills the body in.

Replay API

TestClient::replay_snapshots(path) takes a directory or a single file and returns a zapline::test::Replay:

Snapshots share the app instance (and its state) in a run. For a fresh app per snapshot, replay each file with its own client: app().test().replay_snapshots("tests/snapshots/signup.json").await.

Dev console

One call gives a running app a page that shows what it is made of and what it is doing:

use zapline::prelude::*;

#[get("/")]
async fn index() -> &'static str { "hi" }

fn main() -> std::io::Result<()> {
    App::new()
        .dev_console()
        .mount(index)
        .run("127.0.0.1:8080")
}

Open http://localhost:8080/_dev. Projects created with zapline new (except minimal) already have it.

Safe to leave in

• Debug builds only. In a release build (cargo build --release, the Dockerfiles) .dev_console() does nothing: no route, no middleware, no cost.
• This machine only. Requests from any other address get a 404, so a debug build bound to 0.0.0.0 doesn't show its routes or jobs to the network.

The console's own requests are not listed under recent requests.

.dev_console() also turns on the dev error page: a 500 or a panic answers your browser with the error, its code, the fix and a Copy fix prompt block for your AI assistant.

JSON for tools

GET /_dev/api serves the same data as JSON, newest first, for scripts and for the live tools of zapline mcp:

{"requests":[{"method":"GET","path":"/orders","status":500,"micros":812,"code":"ZL0002"}],
 "errors":[{"at_ms":1767225600000,"method":"GET","path":"/orders","status":500,"code":"ZL0002",
            "error_code":"missing_dependency","message":"no provider registered for `app::Repo`",
            "fix":".provide(value) // value: app::Repo; ..."}],
 "routes":[{"method":"GET","path":"/orders"}]}

location (src/routes/orders.rs:42:17) is set for panics. Like the page, it answers only this machine.

Recording requests as tests

The console can record full request/response pairs and save them as snapshot tests that replay on every cargo test:

• Start recording with the button, or start the app with ZAPLINE_RECORD=1 (zapline dev --record). With the variable, recording starts with the app and is kept in target/zapline/recording.jsonl, so the restarts zapline dev does after each change don't lose it. Recording started from the button lives in memory.
• Save with the console's form or zapline snap <name>: the recording goes to tests/snapshots/<name>.json, plus tests/snapshots.rs (which replays them) if the project has none. Saving empties the recording, so the next snapshot starts fresh.
• Authorization, Cookie and API key header values are never recorded, and neither are password, token, secret, CSRF and API key fields of queries, JSON bodies and forms (they are saved as "[redacted]"; see credentials). Static files, the console's own requests and WebSocket upgrades are skipped.

While not recording, the console's middleware checks one flag per request and does nothing else. In release builds there is no console and no recorder at all.

The console's routes for this, all local-only: GET /_dev/recordings returns the current recording as snapshot JSON; POST /_dev/recordings/start, /stop, /clear, and /save (form field name; answers JSON when the request accepts application/json, which is what zapline snap uses). The POST routes also refuse cross-site requests, so a web page can't drive them.

OpenAPI & interactive docs

Add one line, and your API documents itself: an OpenAPI 3.1 spec at /openapi.json plus Swagger UI at /docs.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use zapline::openapi::OpenApi;
use zapline::prelude::*;

#[derive(Serialize, Deserialize, JsonSchema)]
struct Book {
    id: u64,
    title: String,
}

/// Get a book.
///
/// Returns 404 when the book does not exist.
#[get("/books/{id}", tag = "books")]
async fn get_book(Path(id): Path<u64>) -> Option<Json<Book>> {
    (id == 1).then(|| Json(Book { id, title: "Dune".into() }))
}

fn main() -> std::io::Result<()> {
    App::new()
        .mount(get_book)
        .openapi(OpenApi::new("Bookshelf", "1.0.0"))
        .run("0.0.0.0:8080")
}

The route macros read the doc comment and the handler signature (Path<T>, Query<T>, Json<T>, Option<T>, Result<T>, ...) and the plugin turns the route table into a spec. The spec is generated once, at startup, and served as static bytes, so documentation costs nothing per request.

Requirements:

• Cargo features openapi (on by default, implies json) and macros (on by default) for the automatic parts.

• Types appear in the spec when they implement JsonSchema. #[model] derives it for you (along with serde and Validate) with no extra dependency. The plain derive expands to paths in the schemars crate, so add it to your Cargo.toml:

  schemars = "1"
  

  If you would rather not depend on schemars directly, point the derive at the re-export with #[schemars(crate = "zapline::openapi::schemars")] (the trait is zapline::openapi::JsonSchema).

Types without JsonSchema still work as handler arguments and return values. They are simply not described.

What is described automatically

For routes registered with a macro (#[get], #[post], #[route], ...), the arguments and the return type are inspected:

Operation IDs default to the handler's function name (builder routes get <method>_<path>, such as get_users_id). Duplicates get a suffix, so mounting the same handler twice is fine.

Macro arguments

Everything after the path in #[get("/path", ...)] documents the route. #[route] takes the same arguments plus method = "...".

Unknown arguments, duplicates (summary twice) and bad values are compile errors that list what is allowed.

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

/// Create a user.
///
/// The new user receives a welcome email. Emails must be **unique**.
#[post("/users", tags("users", "admin"), status = 201, security = "bearer")]
async fn create_user(Json(name): Json<String>) -> (StatusCode, Json<String>) {
    (StatusCode::CREATED, Json(name))
}

#[get("/v1/users", deprecated, operation_id = "listUsersV1")]
async fn old_list() -> Json<Vec<String>> {
    Json(vec![])
}

#[get("/internal/debug", hidden)]
async fn debug() -> &'static str {
    "ok"
}
}

Doc comments

The doc comment of a macro route becomes the operation text: the first paragraph is the summary (its lines are joined into one) and the rest is the description, rendered as CommonMark. summary = ".." and description = ".." take precedence. Doc comments on JsonSchema struct fields become property descriptions, too.

Routes without macros

Routes registered with .get(..), .post(..) and friends have no signature to probe, so describe them with builder methods. They apply to the most recently registered route, on both App and Routes, and they panic if no route has been registered yet.

#![allow(unused)]
fn main() {
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use zapline::prelude::*;

#[derive(Deserialize, JsonSchema)]
struct ReindexOptions {
    full: bool,
}

#[derive(Serialize, JsonSchema)]
struct Report {
    documents: u64,
}

async fn reindex(Json(opts): Json<ReindexOptions>) -> Json<Report> {
    Json(Report { documents: if opts.full { 1000 } else { 10 } })
}

fn app() -> App {
    App::new()
        .get("/health", || async { "ok" })
        .summary("Liveness probe")
        .tag("ops")
        .post("/reindex", reindex)
        .summary("Rebuild the search index")
        .request_body::<ReindexOptions>()
        .response::<Report>(200, "The rebuild report")
        .api_doc(|doc| {
            doc.response_empty(202, "Rebuild queued")
                .error_response(409, "A rebuild is already running");
        })
}
}

OperationDoc has more methods for unusual routes: request_body_as::<T>(content_type), request_body_raw(content_type), success::<T>(content_type), success_raw(content_type), success_empty(), default_error(), redirect(), success_status(code), path_params::<T>(), query_params::<T>() and param::<T>(ParamIn::Header, "x-tenant", required).

Groups

Routes::tag_all and Routes::security_all set defaults for every route in a group, including routes added later. Route-level tags are added after the group's. A route's own security replaces the group's. When groups are nested, the innermost group that sets a default wins.

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

fn admin() -> Routes {
    Routes::new()
        .get("/stats", || async { "stats" })
        .summary("Admin statistics")
        .delete("/cache", || async { StatusCode::NO_CONTENT })
        .tag_all("admin")
        .security_all("bearer")
}

fn app() -> App {
    App::new().nest("/admin", admin())
}
}

The OpenApi plugin

OpenApi::new(title, version) is a plugin, installed with App::openapi(..). All other methods are optional:

#![allow(unused)]
fn main() {
use zapline::openapi::{DocsUi, OpenApi};
use zapline::prelude::*;

fn app() -> App {
    App::new().get("/", || async { "hi" }).openapi(
        OpenApi::new("My API", "1.2.0")
            .description("Everything about my service.")
            .server("https://api.example.com")
            .server_with("https://staging.example.com", "Staging")
            .tag("users", "User management")
            .bearer_auth("bearer")
            .docs(DocsUi::Swagger, "/docs")
            .docs(DocsUi::Scalar, "/reference")
            .docs(DocsUi::Redoc, "/redoc"),
    )
}
}

The documentation routes themselves never appear in the spec.

Docs UIs

The pages are plain HTML rendered once at startup. Their assets load from jsDelivr with exact pinned versions and Subresource Integrity hashes, so a compromised CDN cannot inject code. In an air-gapped network, mirror the npm packages (the files must be byte-identical) and call .cdn("https://npm.internal.example").

Security schemes

Declare the schemes on the plugin, then opt routes in with security = "name" (macro), .security("name") (builder) or Routes::security_all("name") (group).

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

#[get("/me", security = "bearer")]
async fn me() -> &'static str {
    "ada"
}

fn app() -> App {
    App::new().mount(me).openapi(
        OpenApi::new("Secure API", "1.0.0")
            .bearer_auth("bearer")                      // Authorization: Bearer <jwt>
            .api_key_auth("api_key", "x-api-key")       // a header
            .basic_auth("basic"),
    )
}
}

OpenApi::security(name) makes a scheme the default for all operations instead.

Documenting a scheme does not enforce anything, and enforcing something does not document it. Authentication policies such as .require_roles(..) (see Authentication & authorization) are separate from the security metadata: use both.

Schemas

Request bodies are described the way they deserialize and responses the way they serialize, because the two can differ (Option<T> fields are optional in a request but always present in a response, serde defaults, and so on). When the schemas of one type differ, the request side is published as <Name>Input, otherwise one component is shared. All named types go under components/schemas, and the framework's error body is published as Error.

#[derive(JsonSchema)] follows serde attributes (rename, default, skip, flatten, ...). It also recognizes validator rules, so #[validate(length(min = 1, max = 64))] becomes minLength / maxLength, range becomes minimum / maximum and email becomes format: email. See Validation.

Custom extractors and responses

A macro route documents an argument or return type when it implements ApiInput / ApiOutput. Implement them for your own types:

#![allow(unused)]
fn main() {
use zapline::extract::FromRequestParts;
use zapline::openapi::{ApiInput, OperationDoc, ParamIn};
use zapline::prelude::*;

struct TenantId(String);

impl FromRequestParts for TenantId {
    async fn from_request_parts(req: &mut Request) -> Result<Self> {
        let value = req.headers().get("x-tenant").and_then(|v| v.to_str().ok());
        value
            .map(|v| TenantId(v.to_owned()))
            .ok_or_else(|| Error::bad_request("missing x-tenant header"))
    }
}

impl ApiInput for TenantId {
    fn describe_input(op: &mut OperationDoc) {
        op.param::<String>(ParamIn::Header, "x-tenant", true);
    }
}

#[get("/reports")]
async fn reports(TenantId(tenant): TenantId) -> String {
    tenant
}
}

The framework's own security extractors (BearerToken, Jwt, CurrentUser, ...) do not document themselves. Add security = "..." to the route.

Exporting the spec

Set ZAPLINE_EXPORT_OPENAPI to a file path and run your app. The plugin writes the spec as pretty-printed JSON and exits (status 0) from its build hook, before any port is bound and before any startup hook runs:

ZAPLINE_EXPORT_OPENAPI=openapi.json cargo run --bin my-api

The zapline openapi command does exactly this for you (see Project layout & the CLI). It is what you want in CI, to publish the spec or to generate client SDKs. Do not set the variable in a test environment: App::test() builds the app too, and the process would exit.

In tests, generate the spec without starting anything and assert on it:

#![allow(unused)]
fn main() {
use zapline::openapi::{spec_for, OpenApi};
use zapline::prelude::*;

#[test]
fn health_is_documented() {
    let app = App::new().get("/health", || async { "ok" }).summary("Liveness probe");
    let spec = spec_for(app, OpenApi::new("Test", "1.0.0"));
    assert_eq!(spec["openapi"], "3.1.0");
    assert_eq!(spec["paths"]["/health"]["get"]["summary"], "Liveness probe");
}
}

zapline::openapi::export_spec(&spec, path) is the function behind the environment variable. An app asked for a spec without the OpenAPI plugin exits with code 78 instead of starting to serve.

Typed clients

The spec also drives typed clients for your frontend: a TypeScript file that zapline dev keeps current, and, with OpenApi::new(..).client_js(), an ES module with JSDoc types served at /_zapline/api.js for pages without a build step. zapline::openapi::codegen::{typescript, javascript} are the generators. See Typed frontends.

Limitations

• Only routes registered with a macro are documented from their signature. Builder routes need explicit .response::<T>() / .request_body::<T>() calls.
• A handler returning impl IntoResponse gets a generic success response, because its type cannot be named. Document it with .response::<T>(..). Wrappers such as Result<impl IntoResponse> still get the error response.
• Generic handler functions cannot be inspected. Their macro arguments still apply.
• .any(..) routes and methods OpenAPI cannot express (CONNECT, custom methods) are left out.
• Auth policies, Multipart, Dep<T>, CurrentUser<U> and other extractors do not appear in the spec unless they implement ApiInput. For uploads, use .api_doc(|d| { d.request_body_raw("multipart/form-data"); }).
• An operation cannot opt out of a global OpenApi::security(..) default. Use .modify(..) to set "security": [] on a path yourself, or declare security per route or group instead.
• Response headers are documented only for redirects.
• The docs pages need the browser to reach the CDN (or your mirror). The JSON spec does not.

Typed frontends (TypeScript & no-build JS)

Your Rust handlers are the API contract. zapline turns the OpenAPI document it already generates into a typed client, and keeps that client current while you work: change a struct, save, and the frontend's type checker points at every call that no longer fits. There is no schema language to maintain, no generator to install, and no npm package in between.

Two flavors come from the same document:

Both use fetch only, so they run in browsers, Node 18+, Deno and Bun, and both pass tsc --strict --exactOptionalPropertyTypes --noUncheckedIndexedAccess.

Live TypeScript with zapline dev

Put your frontend in frontend/ and run zapline dev. After every successful build, before the new binary starts, zapline exports the spec from it and writes frontend/src/api.ts. The file is only rewritten when it changes, so vite, tsc --watch and your editor react exactly once, and dev tells you what moved:

    Building my-app
      Client updated frontend/src/api.ts (+archiveTask ~createTask)
     Running target/debug/my-app (pid 4242)

(+ added, - removed, ~ changed arguments or result.) A Rust change that breaks the frontend now shows up as a red squiggle in the .tsx file within a second of saving the .rs file.

To put the client somewhere else, or to also write the JavaScript module to disk, add a zapline.toml next to Cargo.toml (or the same keys under [package.metadata.zapline.client] in Cargo.toml):

[client]
ts = "web/src/api.ts"     # TypeScript client
js = "static/js/api.js"   # ES module with JSDoc types
# enabled = false         # turn off the frontend/ default

zapline dev --client path/to/api.ts overrides the settings for one run and --no-client turns clients off. zapline client (no -o) writes the configured files once, which is what you want in CI. If the project has a frontend/ directory but the app has no OpenAPI plugin, dev says so once and carries on.

To fail CI when a committed client is stale, compare it with a fresh one in a Rust test:

use zapline::openapi::{codegen, spec_for};

#[test]
fn frontend_client_is_current() {
    let spec = spec_for(my_app::app(), my_app::api());
    let fresh = codegen::typescript(&spec).unwrap().source;
    let committed = std::fs::read_to_string("frontend/src/api.ts").unwrap();
    assert!(committed == fresh, "run `zapline client` and commit frontend/src/api.ts");
}

Using the client

Methods are named after operation ids (the handler name: create_task becomes createTask). Path parameters come first, then the body, then a query object, then per-call options:

import { api, createClient, isValidationError, type Task } from "./api";

const page = await api.listTasks({ status: "todo", limit: 20 }); // query is typed: status is "todo" | "doing" | "done"
const task: Task = await api.getTask(42);
await api.updateTask(42, { status: "done" });
await api.upload(42, { file: input.files![0]!, note: "scan" }); // multipart: a FormData or a plain object
const res = await api.events();                                 // SSE / NDJSON: the raw Response, to stream
const csv: Blob = await api.export();                           // binary bodies resolve to a Blob

// Your own instance: base URL, auth headers, cookies, a custom fetch.
const remote = createClient({
  baseUrl: "https://api.example.com",
  headers: async () => ({ authorization: `Bearer ${await token()}` }),
  credentials: "include",
});
await remote.getTask(1, { signal: AbortSignal.timeout(5000) });

api is a ready same-origin instance. Each method's doc comment carries the route (POST /tasks), the handler's doc comment, and the error responses it documents, so hovering a call shows what the server says about it. Field constraints from #[validate(..)] and #[serde(default)] appear on the interfaces as @minLength, @maximum, @default and so on.

What the generator maps:

Routes that answer with HTML (htmx pages and fragments) are left out.

Errors, typed

Every non-2xx response throws an ApiError with status, zapline's code and details, the decoded body, and the operation that failed. A 422 that lists field errors (from Valid<T>, or a body field of the wrong type) throws a ValidationError instead, whose fields are keyed by the request body's field names:

try {
  await api.createTask(form);
} catch (e) {
  if (isValidationError(e, "createTask")) {
    e.fields.title?.[0]?.message;  // "length must be between 1 and 80"; `title` autocompletes
    e.messageFor("priority");      // the first message for a field, or undefined
    e.errors;                      // every FieldError { field, code, message, params }
  } else if (e instanceof ApiError && e.status === 404) {
    // ...
  }
}

isValidationError(e, "createTask") only matches errors thrown by that method, which is what lets TypeScript know the field names (they are listed per method in the exported ValidationFields interface). Nested fields use paths such as address.zip and items[0].name.

In a browser, unsafe requests (POST, PUT, PATCH, DELETE) copy zapline's CSRF cookie into the x-csrf-token header, so pages behind Csrf work without extra code. Pass csrf: { cookie, header } if you renamed them, or csrf: false.

No build step: /_zapline/api.js

For server-rendered pages, add .client_js() to the OpenAPI plugin:

App::new()
    .mount((list_tasks, create_task))
    .openapi(OpenApi::new("Tasks", "1.0.0").client_js())

The app then serves /_zapline/api.js, generated once at startup from the same spec (nothing per request, and nothing at all without .client_js()). It is public like /openapi.json, even behind Authenticate::required(). Use it from any page:

<script type="module">
  import { api, isValidationError } from "/_zapline/api.js";

  const form = document.querySelector("#new-task");
  const title = form.querySelector("[name=title]");
  title.addEventListener("input", () => title.setCustomValidity(""));
  form.addEventListener("submit", async (ev) => {
    ev.preventDefault();
    try {
      const task = await api.createTask({ title: title.value });
      location.hash = `task-${task.id}`;
    } catch (e) {
      if (isValidationError(e, "createTask")) {
        title.setCustomValidity(e.messageFor("title") ?? "");
        form.reportValidity();
      }
    }
  });
</script>

The module carries the same types as JSDoc (@typedef, @param, @returns) and starts with // @ts-check. Editors read JSDoc from files on disk, so for autocomplete in your own .js files also write a copy next to them with js = "static/js/api.js" in zapline.toml (or zapline client -o static/js/api.js) and import that path. With // @ts-check at the top of your script, VS Code then flags a wrong field name or a missing argument just as it would in TypeScript.

Limitations

• Error responses are typed as ApiError / ValidationError; a handler's own error details stay unknown.
• Only the lowest documented 2xx response is typed. A handler that answers 200 or 201 with different bodies needs an explicit .response::<T>(..) per status and gets the first.
• Streaming responses (SSE, NDJSON) resolve to the raw Response; for SSE in a browser, new EventSource(url) is usually simpler.
• Editors cannot see a module that only exists at a URL: /_zapline/api.js gives a page the client at runtime, and the on-disk copy gives your editor the types.

Validation

Wrap an extractor in Valid and derive Validate on the type. Bad input never reaches your handler.

#![allow(unused)]
fn main() {
use serde::Deserialize;
use validator::Validate;
use zapline::prelude::*;
use zapline::validate::Valid;

#[derive(Deserialize, Validate)]
struct NewUser {
    #[validate(length(min = 1, max = 64))]
    name: String,
    #[validate(email)]
    email: String,
}

#[post("/users", status = 201)]
async fn create_user(Valid(Json(user)): Valid<Json<NewUser>>) -> StatusCode {
    println!("creating {} <{}>", user.name, user.email);
    StatusCode::CREATED
}
}

Requirements:

• Cargo feature validate (on by default, implies json).

• #[model] derives Validate (plus serde and JsonSchema) without adding any crate. The plain derive expands to paths in the validator crate, so add it to your Cargo.toml:

  validator = { version = "0.21", features = ["derive"] }
  

  zapline::validate re-exports the crate (zapline::validate::validator, plus Validate, ValidationError and ValidationErrors). To skip the direct dependency, put #[validate(crate = "zapline::validate::validator")] on the struct.

Which extractors

Valid<E> works with Json<T>, Form<T>, Query<T> and Path<T>, where T: Validate. It derefs to the wrapped extractor (which derefs to T) and destructures like the examples show.

#![allow(unused)]
fn main() {
use serde::Deserialize;
use validator::Validate;
use zapline::prelude::*;
use zapline::validate::Valid;

#[derive(Deserialize, Validate)]
struct Page {
    #[validate(range(min = 1, max = 100))]
    size: u32,
    #[validate(length(max = 10))]
    q: Option<String>,
}

#[derive(Deserialize, Validate)]
struct Ids {
    #[validate(range(min = 1))]
    id: u64,
}

#[get("/things/{id}")]
async fn list(Valid(Path(ids)): Valid<Path<Ids>>, page: Valid<Query<Page>>) -> String {
    // `page` derefs through `Valid` and `Query` to `Page`.
    format!("{}:{}", ids.id, page.size)
}
}

The wrapped extractor runs first, so its own failures are unchanged: a wrong content type is still a 415, an oversized body a 413, malformed JSON or a missing field a 422 (without validation details), and an unparsable query string or path parameter a 400. Only a value that deserializes but breaks a rule produces the validation error below.

The 422 response

A failed validation lists every broken rule, not just the first one:

{
  "error": "validation failed",
  "code": "validation_error",
  "details": [
    { "code": "length", "field": "address.zip", "message": "zip must have 5 digits", "params": { "equal": 5 } },
    { "code": "range", "field": "age", "message": "must be at least 18 and at most 120", "params": { "max": 120, "min": 18 } },
    { "code": "no_spaces", "field": "contacts[1].handle", "message": "must not contain spaces", "params": {} },
    { "code": "length", "field": "contacts[1].name", "message": "length must be at least 1", "params": { "min": 1 } },
    { "code": "email", "field": "email", "message": "must be a valid email address", "params": {} },
    { "code": "length", "field": "password", "message": "must be at least 8 characters", "params": { "min": 8 } }
  ]
}

Each entry of details has:

The list is sorted by field, so responses are stable. Rejected values are never echoed back, which keeps passwords and tokens out of error responses and logs.

details is the standard details member of a zapline error, so App::error_handler can re-render it, and the OpenAPI spec documents the 422 automatically.

Nested structs and lists

Add #[validate(nested)] to fields whose type also derives Validate. List items are reported with their index:

#![allow(unused)]
fn main() {
use serde::Deserialize;
use validator::Validate;

#[derive(Deserialize, Validate)]
struct Address {
    #[validate(length(equal = 5, message = "zip must have 5 digits"))]
    zip: String,
}

#[derive(Deserialize, Validate)]
struct Contact {
    #[validate(length(min = 1))]
    name: String,
}

#[derive(Deserialize, Validate)]
struct Customer {
    #[validate(nested)]
    address: Address,            // -> address.zip
    #[validate(nested)]
    contacts: Vec<Contact>,      // -> contacts[1].name
}
}

validator records one kind of error per field. If a list breaks its own rule (#[validate(length(max = 2), nested)] with three items), you get that error first, and the item errors appear once it passes.

Built-in rules

These are validator 0.21's rules; see its documentation for all options.

Every rule accepts message = ".." (shown to the client) and code = "..".

Custom validators

A field validator takes a reference to the value and returns Result<(), ValidationError>. The error code and message end up in the response:

#![allow(unused)]
fn main() {
use std::borrow::Cow;
use serde::Deserialize;
use validator::{Validate, ValidationError};

fn no_spaces(value: &str) -> Result<(), ValidationError> {
    if value.contains(' ') {
        return Err(ValidationError::new("no_spaces")
            .with_message(Cow::Borrowed("must not contain spaces")));
    }
    Ok(())
}

#[derive(Deserialize, Validate)]
struct Handle {
    #[validate(custom(function = "no_spaces"))]
    handle: String,
}
}

Rules that involve several fields are struct-level validators. Their field is empty (or the parent's path when nested):

#![allow(unused)]
fn main() {
use std::borrow::Cow;
use serde::Deserialize;
use validator::{Validate, ValidationError};

fn check_total(order: &Totals) -> Result<(), ValidationError> {
    if order.a + order.b > 10 {
        return Err(ValidationError::new("total")
            .with_message(Cow::Borrowed("a + b must be <= 10")));
    }
    Ok(())
}

#[derive(Deserialize, Validate)]
#[validate(schema(function = "check_total"))]
struct Totals {
    a: u32,
    b: u32,
}
}

Validators here must be synchronous and pure. For checks that need the database ("is this email taken?"), do them in the handler and return Error::conflict(..).with_code("email_taken").

Validating by hand

Valid is a convenience around two public functions. Use them when the data doesn't come from an extractor, or to merge validation with your own checks:

#![allow(unused)]
fn main() {
use serde::Deserialize;
use validator::Validate;
use zapline::prelude::*;
use zapline::validate::validation_error;

#[derive(Deserialize, Validate)]
struct Link {
    #[validate(url)]
    link: String,
}

async fn save(Json(body): Json<Link>) -> Result<String> {
    // A plain `?` on `ValidationErrors` would produce a 500, like any other
    // `std::error::Error`. `validation_error` builds the same 422 as `Valid`.
    body.validate().map_err(validation_error)?;
    Ok(body.link)
}
}

zapline::validate::field_errors(&errors) returns the flattened, sorted Vec<FieldError> if you want to build your own response.

HTML forms

A JSON 422 is right for an API client, but a browser that posts a form needs the form back, with a message next to each field. For pages, take ValidForm<T> (feature views) instead of Valid<Form<T>>: it runs the same rules but hands the outcome to the handler as a Result, and views.render_invalid re-renders the form as a 422 with {{ errors.field }} and {{ old.field }}:

use zapline::view::{context, ValidForm, Views};

#[post("/signup")]
async fn signup(views: Views, ValidForm(form): ValidForm<SignUp>) -> Result<Response> {
    let form = match form {
        Ok(form) => form,
        Err(invalid) => return views.render_invalid("signup.html", context! {}, invalid),
    };
    // ...
    Ok(Redirect::to("/").into_response())
}

The messages are the ones listed above; fields that don't parse at all get "must be a number" or "is required". Struct-level (schema) errors appear as {{ errors._form }}. FormErrors::from(&validation_errors) and FormErrors::from_error(&err) convert by hand. See Views: Forms.

OpenAPI

Valid<Json<T>> documents the request body exactly like Json<T> and adds a 422 Validation Error response. The #[validate(..)] rules are visible to #[derive(JsonSchema)], so length, range and email also appear in the schema as minLength, maximum, format: email and so on. See OpenAPI & interactive docs.

Dependency injection

Register a service once with App::provide, receive it in any handler with Dep<T>:

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

struct Greeter {
    greeting: String,
}

#[get("/hello/{name}")]
async fn hello(greeter: Dep<Greeter>, Path(name): Path<String>) -> String {
    format!("{}, {name}!", greeter.greeting)
}

fn app() -> App {
    App::new()
        .provide(Greeter { greeting: "Hello".into() })
        .mount(hello)
}
}

Providers are app-wide singletons stored behind an Arc. Dep<T> derefs to T, and extracting it costs one lookup plus a reference-count increment. T may be a trait object (Dep<dyn UserRepo>), which is what makes layers swappable in tests. Dep<T> is a parts extractor, so it can appear in any argument position.

If nothing provides T, the extractor fails with a 500 and the code missing_dependency.

Registering providers

Registering the same type again replaces the earlier provider, including a factory that has not run yet. The last registration wins, whichever kind it was.

Layers: controller → service → repository

A Spring-style application keeps HTTP concerns in thin controllers, business rules in services, and storage behind a repository trait:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zapline::di::Dep;
use zapline::prelude::*;

// Repository layer: a trait, so tests can swap in a mock.
trait UserRepo: Send + Sync {
    fn name(&self, id: u64) -> Option<String>;
}

struct InMemoryUsers;

impl UserRepo for InMemoryUsers {
    fn name(&self, id: u64) -> Option<String> {
        (id == 1).then(|| "ada".to_owned())
    }
}

// Service layer: business rules; knows nothing about HTTP except `Error`.
struct UserService {
    repo: Arc<dyn UserRepo>,
}

impl UserService {
    fn greeting(&self, id: u64) -> Result<String> {
        let name = self.repo.name(id).ok_or_else(Error::not_found)?;
        Ok(format!("hello, {name}"))
    }
}

// Controller layer: thin handlers.
#[get("/users/{id}/greeting")]
async fn greeting(users: Dep<UserService>, Path(id): Path<u64>) -> Result<String> {
    users.greeting(id)
}

fn app() -> App {
    App::new()
        .provide_dyn::<dyn UserRepo>(Arc::new(InMemoryUsers))
        .provide_with(|res: Resources| async move {
            Ok(UserService { repo: res.dep::<dyn UserRepo>()? })
        })
        .mount(greeting)
}
}

The factory receives Resources, and res.dep::<T>() resolves a provider. Factories run at startup, in registration order (interleaved with on_startup hooks), before the server accepts connections:

• A factory can resolve every value registered with provide, provide_arc or provide_dyn (those are available immediately) and every factory registered before it.
• A factory that fails aborts startup. App::run returns an error that names the type (dependency ... failed to initialize: ...), and the port is never bound.
• A factory returns zapline::Result<T>, so ? works on anything that converts into zapline::Error.

For a real database, the pool is just another factory:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zapline::di::Dep;
use zapline::prelude::*;

struct Pool;

impl Pool {
    async fn connect(_url: &str) -> Result<Pool> {
        Ok(Pool)
    }
}

struct OrderService {
    pool: Arc<Pool>,
}

fn app() -> App {
    App::new()
        .provide_with(|_res: Resources| async move { Pool::connect("postgres://localhost/app").await })
        .provide_with(|res: Resources| async move {
            Ok(OrderService { pool: res.dep::<Pool>()? })
        })
}
}

To return a trait object from a factory, use provide_dyn_with. Annotate the Arc<dyn Trait> so the compiler knows which trait object you mean:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zapline::prelude::*;

trait Mailer: Send + Sync {
    fn send(&self, to: &str, body: &str);
}

struct SmtpMailer;

impl Mailer for SmtpMailer {
    fn send(&self, _to: &str, _body: &str) {}
}

fn app() -> App {
    App::new().provide_dyn_with(|_res: Resources| async move {
        let mailer: Arc<dyn Mailer> = Arc::new(SmtpMailer); // connect, authenticate, ...
        Ok(mailer)
    })
}
}

Injecting by trait: Inject

When a service just collects other providers, implement Inject instead of writing a closure. The method is synchronous and runs at startup:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zapline::di::Inject;
use zapline::prelude::*;

struct Db;

struct Repo {
    db: Arc<Db>,
}

impl Inject for Repo {
    fn inject(res: &Resources) -> Result<Self> {
        Ok(Repo { db: res.dep::<Db>()? })
    }
}

fn app() -> App {
    App::new().provide(Db).provide_injected::<Repo>()
}
}

Providers outside handlers

Resources::dep::<T>() resolves a provider anywhere you have Resources: startup hooks, shutdown hooks, scheduled jobs, background workers (see Background tasks) and plugins. In middleware, use req.state::<Arc<T>>().

Overriding providers in tests

Build the real app, then replace the pieces you don't want. Because the last registration wins, even a factory that has not run yet is replaced, and it never runs:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use zapline::prelude::*;

trait UserRepo: Send + Sync {
    fn name(&self, id: u64) -> Option<String>;
}

struct MockRepo;

impl UserRepo for MockRepo {
    fn name(&self, _id: u64) -> Option<String> {
        Some("mock".to_owned())
    }
}

fn app() -> App {
    // The application, as built in production (see above).
    App::new().get("/users/{id}", |repo: zapline::di::Dep<dyn UserRepo>, Path(id): Path<u64>| async move {
        repo.name(id).ok_or_else(Error::not_found)
    })
}

#[tokio::test]
async fn greets_with_a_mock_repository() {
    let client = app()
        .override_provider::<dyn UserRepo>(Arc::new(MockRepo))
        .test();

    let res = client.get("/users/7").send().await;
    assert_eq!(res.text(), "mock");
}
}

override_provider is provide_arc with a name that says what you mean. See Testing for the test client.

Request scope: Cached<T>

Providers are singletons. For a value that is computed per request (the current user, the tenant, a database transaction), implement FromRequestParts for it and extract it as Cached<T>. The first extraction runs T's extractor and stores the result in the request; later ones in the same request (in route middleware, then in the handler) get a clone:

#![allow(unused)]
fn main() {
use zapline::di::Cached;
use zapline::extract::FromRequestParts;
use zapline::prelude::*;

#[derive(Clone)]
struct Tenant(String);

impl FromRequestParts for Tenant {
    async fn from_request_parts(req: &mut Request) -> Result<Self> {
        // Imagine a database lookup here: it runs once per request.
        let id = req.headers().get("x-tenant").and_then(|v| v.to_str().ok());
        id.map(|id| Tenant(id.to_owned()))
            .ok_or_else(|| Error::bad_request("missing x-tenant header"))
    }
}

/// Route middleware: reject unknown tenants early. The handler reuses the lookup.
async fn require_tenant(mut req: Request, next: Next) -> Response {
    match Cached::<Tenant>::resolve(&mut req).await {
        Ok(_) => next.run(req).await,
        Err(e) => e.into_response(),
    }
}

async fn dashboard(Cached(tenant): Cached<Tenant>) -> String {
    format!("dashboard of {}", tenant.0)
}

fn app() -> App {
    App::new().get("/dashboard", dashboard).wrap_route(require_tenant)
}
}

T must be FromRequestParts + Clone + Sync + 'static.

Dep<T>, State<T> and Resources

All three read from the same typed registry (Resources), keyed by type:

A provider is stored under the key Arc<T>, which is why State<Arc<T>> reaches it too. Prefer Dep<T> for services and trait objects, State<T> for small Clone values, and Resources when you are outside a request.

Configuration

Load layered settings into your own struct, then hand it to the app:

use serde::Deserialize;
use zapline::config::{Config, Secret};
use zapline::di::Dep;
use zapline::prelude::*;

#[derive(Clone, Deserialize)]
struct Settings {
    server: Server,
    database: Database,
}

#[derive(Clone, Deserialize)]
struct Server {
    host: String,
    port: u16,
}

#[derive(Clone, Deserialize)]
struct Database {
    url: Secret<String>,   // never printed by Debug/Display
    pool: u32,
}

async fn info(settings: Dep<Settings>) -> String {
    format!("pool size {}", settings.database.pool)
}

fn main() -> std::io::Result<()> {
    let settings: Settings = Config::load()?.extract()?;
    let addr = (settings.server.host.clone(), settings.server.port);
    App::new()
        .config(settings)          // State<Settings> and Dep<Settings>
        .get("/info", info)
        .run(addr)
}

Requires the Cargo feature config (on by default; it adds the toml crate). ConfigError converts into std::io::Error and into zapline::Error, so ? works in main and in handlers.

Layers

Config::load() merges these layers, lowest precedence first:

Tables are deep-merged: a later layer overrides single keys and keeps the siblings. A production.toml that only sets [database] url leaves database.pool from default.toml alone.

# config/default.toml
[server]
host = "127.0.0.1"
port = 8080

[database]
url = "postgres://localhost/app"
pool = 5

# config/production.toml
[server]
host = "0.0.0.0"

[database]
pool = 20

APP_ENV=production APP__DATABASE__URL=postgres://db.internal/app ./my-app

Profiles

The active profile is, in order: the builder's .profile(..), the APP_ENV environment variable, ZAPLINE_ENV, and finally development. An empty variable counts as unset. APP_ENV follows the configured prefix, so with .env_prefix("MYAPP") it is MYAPP_ENV. Both can also be set in the .env file. config.profile() returns the name, which you can use to switch behavior (for example, to require TLS in production).

Profile names may only contain ASCII letters, digits, - and _, so APP_ENV=../../etc can never reach the file system. Anything else is a ConfigError::InvalidProfile.

Environment variables

Names are PREFIX, then the path segments, all joined by the separator (default __). Segments are lowercased, and an existing key with different casing matches case-insensitively:

Values are interpreted leniently, so you never need to quote anything in a shell:

• An environment value becomes a TOML scalar or array only if that round-trips exactly (8080, true, 1.5, [1, 2]). Otherwise it stays a string. So 007, 0x1F and 1.10 are kept as written.
• Typed extraction is lenient where environment variables need it: "8080" reads as a number, 8080 as a string, "a,b" as a list, and yes, on, 1 as true.
• Field and enum variant names match case-insensitively when there is no exact match.

.env files

KEY=value, export KEY=value, # comments, inline comments after unquoted values ( # ...), 'single' quotes (literal), and "double" quotes with \n \r \t \" \\ \$ escapes. Quoted values may span lines. Variables are not expanded (${VAR} stays literal). Values from .env feed the environment layer and profile selection, but are never exported into the process, and real environment variables always win. A malformed file is an error that names the line.

The builder

Config::load() is Config::builder().standard().build(). Use the builder for anything else:

#![allow(unused)]
fn main() {
use zapline::config::Config;

fn load() -> Result<Config, zapline::config::ConfigError> {
    Config::builder()
        .toml_str("[server]\nport = 8080")        // embedded defaults
        .file_optional("config/default.toml")
        .file_optional("config/{profile}.toml")   // {profile} is replaced
        .dotenv(".env")
        .env_prefix("MYAPP")                      // MYAPP__SERVER__PORT
        .set_default("server.workers", 4)         // below every other layer
        .set("server.tls", false)                 // above every other layer
        .build()
}
}

Layers merge in this order: set_default values, then files and TOML strings in the order added, then the environment (including .env), then set overrides.

env_source makes configuration trivially testable, without touching real environment variables:

#![allow(unused)]
fn main() {
use zapline::config::Config;

#[test]
fn environment_overrides_files() {
    let config = Config::builder()
        .toml_str("[database]\nurl = \"postgres://localhost/dev\"\npool = 5")
        .env_prefix("MYAPP")
        .env_source([("MYAPP__DATABASE__POOL", "20")])
        .build()
        .unwrap();
    assert_eq!(config.get::<u32>("database.pool").unwrap(), 20);
}
}

Reading values

#![allow(unused)]
fn main() {
use zapline::config::Config;

fn read(config: &Config) -> Result<(), zapline::config::ConfigError> {
    let port: u16 = config.get("server.port")?;
    let workers: usize = config.get_or("server.workers", 4)?;
    let first_host: String = config.get("hosts[0]")?;
    let timeout: Option<u64> = config.get("server.timeout_secs")?;
    println!("{port} {workers} {first_host} {timeout:?}");
    Ok(())
}
}

Use #[serde(default)] and #[serde(deny_unknown_fields)] on your settings structs as usual. The latter turns a typo such as prot = 8080 into an error that names the key.

Using settings in the app

App::config(settings) registers the value as both State<T> and Dep<T> (it needs T: Clone + Send + Sync + 'static). Pass it to services in provider factories with res.dep::<Settings>()?:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use serde::Deserialize;
use zapline::prelude::*;

#[derive(Clone, Deserialize)]
struct Settings {
    greeting: String,
}

struct Greeter {
    greeting: String,
}

fn app(settings: Settings) -> App {
    App::new()
        .config(settings)
        .provide_with(|res: Resources| async move {
            let settings: Arc<Settings> = res.dep::<Settings>()?;
            Ok(Greeter { greeting: settings.greeting.clone() })
        })
}
}

See Dependency injection for how factories work. You can also register the Config itself with .state(config) to read dynamic keys in handlers.

Secrets

Secret<T> wraps a value that must not end up in logs. Its Debug and Display print [REDACTED], it deserializes transparently (a Secret<String> field reads a plain string), and it is not Serialize, so it cannot be returned from a handler by accident. Read the value with .expose(). The method name is easy to grep for:

#![allow(unused)]
fn main() {
use zapline::config::Secret;

fn demo() {
    let key = Secret::new("hunter2".to_string());
    assert_eq!(format!("{key:?}"), "[REDACTED]");
    assert_eq!(key.expose(), "hunter2");
}
}

Config's own Debug output lists only the profile and the top-level keys, never values.

Inject secrets through environment variables (APP__DATABASE__URL=...) rather than committing them to config/*.toml.

Error messages

Configuration errors name the key, the expected type and the layer that set the value:

invalid config key `server.port`: invalid value: string "eighty", expected u16 (set by env `APP__SERVER__PORT`)
invalid config key `server.port`: invalid value: integer `70000`, expected u16 (set by string #1)
missing config key `database.url`
invalid config key `s.prot`: unknown key, expected one of `port` (set by string #1)
config file `config/nope.toml`: No such file or directory (os error 2)
config file `config/bad.toml` is invalid: TOML parse error at line 2, column 8 ...
config file `.env` is invalid: line 2: expected `KEY=value`
invalid config profile "pro d": use ASCII letters, digits, `-` and `_`

ConfigError is an enum (Io, Parse, Missing, Invalid, InvalidProfile) with .key() for the key path. When one reaches a request handler through ? it becomes a 500 whose details stay in the server log, so a bad configuration value is never shown to clients.

Background tasks & scheduled jobs

Queue work from a handler with BackgroundTasks, run periodic or cron jobs with App::schedule, and run long-lived workers with App::background. All three are stopped cleanly on shutdown.

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

async fn send_welcome_email(address: String) -> Result<()> {
    // talk to the mail server...
    Ok(())
}

#[post("/signup")]
async fn signup(tasks: BackgroundTasks, Json(address): Json<String>) -> StatusCode {
    tasks.spawn(send_welcome_email(address));   // runs after this handler returns
    StatusCode::CREATED
}
}

zapline::tasks is always compiled in; there is no Cargo feature to enable.

BackgroundTasks

BackgroundTasks is an extractor holding a queue. tasks.spawn(future) adds to it, and the queued futures run after the handler returns:

• They run in order, one after another, on the current runtime. The response doesn't wait for them.
• They start when the extractor (and every clone of it) is dropped, which normally happens when the handler function finishes. This is whatever the handler returns, an error included. Queue tasks after the fallible work, or call tasks.clear() on failure.
• A task may return () or Result<(), E> where E: Display. Errors and panics are logged (through tracing when enabled, otherwise on stderr) and never affect the client or the server.
• A task must be Send + 'static. Dep<T> is an Arc underneath, so clone it into the task.
• If the app has a job, a worker, or sets App::tasks_grace_period, shutdown waits for queued tasks (see Shutdown and the grace period). Without any of these, tasks still queued when the process exits can be cut off.
• Tasks live in memory. If the process crashes or is killed before they run, they are lost. For work that must not be lost, use durable jobs, which are stored in the database and retried.

#![allow(unused)]
fn main() {
use zapline::di::Dep;
use zapline::prelude::*;
use zapline::tasks::BackgroundTasks;

struct Mailer;

impl Mailer {
    async fn send_receipt(&self, order_id: u64) -> Result<()> {
        println!("receipt for order {order_id}");
        Ok(())
    }
}

async fn save_order(items: Vec<String>) -> Result<u64> {
    Ok(items.len() as u64)
}

#[post("/orders")]
async fn create_order(
    tasks: BackgroundTasks,
    mailer: Dep<Mailer>,
    Json(items): Json<Vec<String>>,
) -> Result<(StatusCode, Json<u64>)> {
    let id = save_order(items).await?;              // fallible work first
    let mailer = mailer.clone();
    tasks.spawn(async move { mailer.send_receipt(id).await });
    Ok((StatusCode::CREATED, Json(id)))
}
}

Scheduled jobs

App::schedule(schedule, job) runs a closure periodically for the lifetime of the app. The closure receives Resources (use res.dep::<T>() to reach your providers) and returns a future producing () or Result<(), E: Display>:

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::prelude::*;
use zapline::tasks::Schedule;

fn app() -> App {
    App::new()
        .schedule(
            Schedule::every(Duration::from_secs(300)).name("refresh-cache"),
            |_res: Resources| async move {
                // refresh a cache; returning Err(..) is logged and the schedule goes on
                Ok::<_, Error>(())
            },
        )
        .schedule(
            Schedule::cron("0 9 * * MON-FRI").name("standup-digest"),   // 09:00 UTC on weekdays
            |_res: Resources| async move {
                println!("sending the digest");
            },
        )
        .schedule(
            Schedule::daily_at(3, 30).name("nightly-report"),   // 03:30 UTC
            |_res: Resources| async move {
                println!("building the nightly report");
            },
        )
}
}

Refine a schedule with modifiers:

Things to know:

• A job starts from a startup hook registered at that point in the builder chain, so it can use every provider registered before it.
• Errors and panics are logged, and the schedule continues.
• Jobs and workers run on the app's small "system" runtime (two threads, the one that runs startup hooks), not on the per-core request runtimes. A busy job can't stall a request's core, but it shares those two threads with every other job, so move blocking or CPU-heavy work to tokio::task::spawn_blocking.
• Each running instance of your app runs its own schedule. With several replicas, a job runs once per replica. For work that must run once per tick across the cluster, use a cron job instead: .jobs(|q| q.cron("0 3 * * *", NightlyReport {})).
• schedule.next_after(time) and schedule.delay_until_next(time) tell you when a schedule fires next, without running it.

With the Metrics plugin installed, every run is counted and timed, labelled by the schedule's name (task). Without the plugin nothing is recorded.

In debug builds the dev console lists every schedule with its next run, run and failure counts, and how the last run went.

Long-running workers

App::background(worker) runs an async closure once, for the lifetime of the app: a queue consumer, a cache refresher, a websocket client. It receives Resources and a Shutdown signal and should return when the signal fires:

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::prelude::*;
use zapline::tasks::Shutdown;

fn app() -> App {
    App::new().background(|_res: Resources, shutdown: Shutdown| async move {
        loop {
            tokio::select! {
                _ = shutdown.wait() => break,
                _ = tokio::time::sleep(Duration::from_millis(500)) => {
                    // poll a queue, flush a buffer...
                }
            }
        }
    })
}
}

A worker that returns an error or panics is logged and not restarted. Wrap the loop yourself if you want retries.

Shutdown

Shutdown is a cloneable signal:

As soon as the app has a job, a worker, or a custom grace period, Shutdown is also registered as state, so handlers can react to it. For example, to end a long poll early instead of holding up the drain:

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::prelude::*;
use zapline::tasks::Shutdown;

async fn poll(State(shutdown): State<Shutdown>) -> &'static str {
    tokio::select! {
        _ = shutdown.wait() => "shutting down, retry elsewhere",
        _ = tokio::time::sleep(Duration::from_secs(30)) => "nothing new",
    }
}

fn app() -> App {
    App::new().tasks_grace_period(Duration::from_secs(10)).get("/poll", poll)
}
}

Testing a worker needs no app at all:

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

async fn worker(shutdown: Shutdown) -> u32 {
    let mut ticks = 0;
    loop {
        tokio::select! {
            _ = shutdown.wait() => return ticks,
            _ = tokio::time::sleep(Duration::from_millis(5)) => ticks += 1,
        }
    }
}

#[tokio::test]
async fn worker_stops_when_signalled() {
    let (trigger, shutdown) = Shutdown::channel();
    let handle = tokio::spawn(worker(shutdown));
    tokio::time::sleep(Duration::from_millis(30)).await;
    trigger.trigger();
    assert!(handle.await.unwrap() > 0);
}
}

Shutdown and the grace period

When the server stops, shutdown hooks run after the connections have drained (see State, lifecycle & plugins). The task supervisor then:

1. Fires Shutdown, which stops schedules and tells workers to return.
2. Waits for workers, queued BackgroundTasks and overlapping job runs to finish.
3. After the grace period, aborts whatever is still running and logs a warning.

The grace period defaults to 10 seconds (zapline::tasks::DEFAULT_GRACE_PERIOD). Change it with App::tasks_grace_period(Duration).

The grace period comes on top of the time the server spends draining connections (see Server: TLS, HTTP/2, graceful shutdown). Size your orchestrator's termination timeout for both; see Deployment.

Tests

App::test() starts jobs and workers together with the other startup hooks, on the first request. Call client.start().await to start them eagerly and client.shutdown().await to stop them and wait for the drain. Scheduled jobs with long periods never fire inside a short test, so test the job's logic as a plain function and keep the schedule thin.

Cron schedules

Cron expressions say when something runs. zapline uses them in two places:

#![allow(unused)]
fn main() {
use zapline::db::Database;
use zapline::jobs::Job;
use zapline::prelude::*;
use zapline::tasks::Schedule;

#[model]
struct InvoiceRun {}

impl Job for InvoiceRun {
    const NAME: &'static str = "invoice_run";
    async fn run(self, _res: Resources) -> Result<()> { Ok(()) }
}

fn app() -> App {
    App::new()
        .database(Database::from_env())
        // Each instance: every 5 minutes during office hours, UTC.
        .schedule(Schedule::cron("*/5 8-18 * * MON-FRI").name("warm-cache"), |_res: Resources| async move {
            // ...
        })
        // The cluster: 02:00 Paris time on the 1st, enqueued once.
        .jobs(|q| q.cron("CRON_TZ=Europe/Paris 0 2 1 * *", InvoiceRun {}))
}
}

zapline::cron is always compiled in. Only IANA time zone names (Europe/Paris) need the tz feature.

Syntax

Five fields, or six with seconds first:

┌───────────── second (0-59)          only in the 6-field form
│ ┌─────────── minute (0-59)
│ │ ┌───────── hour (0-23)
│ │ │ ┌─────── day of month (1-31)
│ │ │ │ ┌───── month (1-12 or JAN-DEC)
│ │ │ │ │ ┌─── day of week (0-7 or SUN-SAT; 0 and 7 are Sunday)
│ │ │ │ │ │
0 30 9 * * MON-FRI      09:30:00 on weekdays
  30 9 * * MON-FRI      the same, 5 fields

Each field is a comma-separated list of:

Extensions in the day fields (from Quartz):

When both day fields are restricted (neither starts with * or ?), a day matches if either matches, as in classic cron: 0 0 1 * MON runs on the 1st and every Monday. If one of them starts with * or ?, both must match: 0 0 */2 * MON runs on Mondays that fall on an odd date.

Macros:

Expressions are checked when the app is built: a typo panics with the reason (invalid cron expression `0 25 * * *`: hour `25` is out of range 0-23), and so does an expression that can never match, such as 0 0 30 2 *. To handle errors yourself, for example for a schedule read from configuration, parse it first:

#![allow(unused)]
fn main() {
use zapline::cron::Cron;
use zapline::tasks::Schedule;

fn schedule_from_config(expr: &str) -> Result<Schedule, zapline::cron::CronError> {
    let cron: Cron = expr.parse()?;
    Ok(Schedule::cron(cron))
}
}

Time zones

An expression runs in UTC unless it starts with CRON_TZ=<zone> (or TZ=<zone>):

zapline = { version = "0.1", features = ["tz"] }

With tz, zone rules come from the system's time zone database (/usr/share/zoneinfo on Linux and macOS; bundled on Windows), through the jiff crate. Without it, an IANA name is an error that says to enable the feature. You can also set the zone in code with Cron::with_timezone(Tz::parse("Europe/Paris")?).

Fields are matched against the local time: CRON_TZ=+05:30 0 1 * * MON runs at 01:00 on Mondays in that zone, which is Sunday 19:30 UTC.

Daylight-saving time

Wall clocks skip an hour in spring and repeat one in autumn. zapline handles both without surprises:

• Clocks go forward (02:00 jumps to 03:00): a time that doesn't exist that day, such as 30 2 * * *, runs once, at the jump (03:00 local). A schedule with several times in the missing hour also runs just once there.
• Clocks go back (02:00 returns to 01:00): a time that happens twice, such as 30 1 * * *, runs once, the first time. A schedule whose hour field covers every hour, such as */15 * * * *, keeps its rhythm through both passes, so it never pauses for an hour.

UTC and fixed offsets have no daylight-saving changes, which is why they are the default.

Inspecting a schedule

Cron computes fire times without running anything, which is handy in tests and admin pages:

#![allow(unused)]
fn main() {
use std::time::{Duration, UNIX_EPOCH};
use zapline::cron::Cron;

let cron = Cron::parse("0 0 L * *")?;                // midnight on the last day of each month
let jan_1_2024 = UNIX_EPOCH + Duration::from_secs(1_704_067_200);
let next: Vec<_> = cron.upcoming(jan_1_2024).take(2).collect();
assert_eq!(next[0], UNIX_EPOCH + Duration::from_secs(1_706_659_200)); // 2024-01-31
assert_eq!(next[1], UNIX_EPOCH + Duration::from_secs(1_709_164_800)); // 2024-02-29
Ok::<(), zapline::cron::CronError>(())
}

In debug builds the dev console lists every scheduled task with its next run, and every cron job with its next enqueue.

Caching

zapline::cache (feature cache, included in full) has three tools. Pick by what you want to skip:

Cache: values

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::cache::Cache;
use zapline::prelude::*;

#[model]
struct Stats { users: u64 }

#[get("/stats")]
async fn stats(cache: Cache) -> Result<Json<Stats>> {
    let stats = cache
        .get_or_set("stats", Duration::from_secs(60), || async {
            Ok(Stats { users: 42 }) // the expensive part
        })
        .await?;
    Ok(Json(stats))
}

let app = App::new().cache(Cache::memory()).mount(stats);
}

get_or_set is the one to reach for. When 500 requests miss at once, one computes and the rest wait for it (no stampede). Errors aren't cached.

Name keys like posts:42 so a write can drop a whole family with delete_prefix.

ResponseCache: whole pages

#![allow(unused)]
fn main() {
use zapline::cache::ResponseCache;

let app = App::new().nest(
    "/blog",
    Routes::new().mount((index, post)).wrap(ResponseCache::new(Duration::from_secs(300))),
);
}

Repeats are answered from memory with x-cache: HIT. It only keeps responses that are safe to share:

• GET or HEAD with no Authorization or Cookie header, so logged-in users always get their own page;
• a 200 with a buffered body, no Set-Cookie, and no Cache-Control: private, no-store or no-cache.

The query string, Accept and HX-Request are part of the key, so htmx fragments and full pages don't mix. When the handler set no Cache-Control, public, max-age=<ttl> is added, so CDNs and browsers help too.

ETag: conditional requests

#![allow(unused)]
fn main() {
let app = App::new().wrap(zapline::cache::ETag);
}

200 responses to GET get a weak ETag (a hash of the body). A browser that sends it back in If-None-Match gets an empty 304 Not Modified. Streamed bodies are left alone. Static files have their own ETags already.

Databases

zapline::db connects your app to Postgres or SQLite through sqlx: a connection pool created at startup, SQL migrations applied automatically, a Db extractor, a readiness check, and database errors that become the right HTTP status.

[dependencies]
zapline = { version = "0.1", features = ["sqlite"] }   # or "postgres", or both
sqlx = { version = "0.8", default-features = false, features = ["derive"] }   # for #[derive(FromRow)]

use serde::Serialize;
use zapline::db::{sqlx, Database, Db};
use zapline::prelude::*;

#[derive(Serialize, sqlx::FromRow)]
struct Post { id: i64, title: String }

#[get("/posts/{id}")]
async fn get_post(db: Db, Path(id): Path<i64>) -> Result<Json<Post>> {
    let post = sqlx::query_as::<_, Post>("SELECT id, title FROM posts WHERE id = ?")
        .bind(id)
        .fetch_one(&*db)   // no row → 404
        .await?;
    Ok(Json(post))
}

fn main() -> std::io::Result<()> {
    App::new()
        .database(Database::from_env())   // DATABASE_URL
        .mount(get_post)
        .run("0.0.0.0:8080")
}

Connecting

Pool settings: .max_connections(n) (default 4 × CPUs, at least 10), .min_connections(n), .acquire_timeout(d) (default 5 s; a request that can't get a connection in time gets a 503).

With both features enabled, Db and Database default to Postgres; use SqliteDb (or Db<sqlx::Sqlite>) and Database::sqlite(url) for SQLite.

Queries

Db dereferences to sqlx::Pool, so every sqlx API works: .fetch_one(&*db), .execute(&*db), and db.begin().await? for a transaction (commit with tx.commit().await?; dropping it rolls back).

? on a sqlx::Error gives:

Resources made by zapline g resource turn the two 409s into errors that name the field: 422 author_not_found for a reference to a row that doesn't exist, 409 email_taken for a duplicate in an email:string:unique column (see Resource fields). The generated write_error function shows how: on a foreign-key violation it checks which parent is missing, on a unique violation it matches the index name (users_email_key).

List endpoints: paging, sorting, filters, search

Listing turns the query string into a safe, paged query. Callers get pagination, sorting, filters and search; you write one expression:

#![allow(unused)]
fn main() {
use zapline::db::{sqlx, Db, ListParams, Listing, Paged};

#[get("/api/posts")]
async fn list(db: Db, params: ListParams) -> Result<Json<Paged<Post>>> {
    let page = Listing::new("posts", "id, title, published, author_id")
        .sortable(["title", "published"])
        .search(["title", "body"])
        .filter_bool("published")
        .filter_int("author_id")
        .fetch(&db, &params)
        .await?;
    Ok(Json(page))
}
}

GET /api/posts?q=rust&published=true&sort=-id&limit=20&offset=40 returns:

{"items": [...], "total": 57, "limit": 20, "offset": 40}

Nothing from the request reaches the SQL text: values are bound as parameters, and sort columns must be on the allow-list. Bad input is a 400 with code invalid_sort, invalid_filter or invalid_page, and the message lists what's allowed.

For per-user or per-tenant lists, .scope("user_id", user.id) adds a condition the request can't remove. zapline generate resource writes a listing() like this for every resource, with sorting on every column but long text, search on the text fields and a filter per string, number, boolean and reference field; a reference (author:references) also gets a nested list, GET /api/authors/{id}/posts, which is listing().scope("author_id", id). It works on SQLite and Postgres, and ListParams documents limit, offset, sort and q in the OpenAPI spec.

Migrations

Migrations are plain SQL files in migrations/, applied in version order, each exactly once (sqlx tracks them in _sqlx_migrations). Each one is a pair: <version>_<name>.up.sql does the change and <version>_<name>.down.sql undoes it.

zapline db new create_posts     # migrations/20261022062406_create_posts.up.sql + .down.sql
zapline db migrate              # apply pending migrations, then exit

The app also applies pending migrations at startup, so zapline dev and deploys need no extra step. Turn that off with Database::from_env().migrate(false), or read them from elsewhere with .migrations("db/migrations"). .migrations(zapline::embed!("migrations")) compiles them into the binary, with the same checksums as the files (One binary). zapline db migrate runs your app with ZAPLINE_MIGRATE=up, so it uses exactly the URL and settings the app uses.

In Docker, copy migrations/ next to the binary (the generated Dockerfiles do).

Writing them for you

zapline g migration writes both halves from the name and field:type arguments (CLI):

zapline g migration create_tags name slug                             # CREATE TABLE / DROP TABLE
zapline g migration add_published_at_to_posts published_at:datetime?   # ADD COLUMN / DROP COLUMN
zapline g migration add_views_to_posts views:int=0                     # ... with the default existing rows get
zapline g migration remove_legacy_from_posts legacy:bool               # DROP COLUMN / ADD COLUMN
zapline g migration backfill_slugs                                     # an empty pair to fill in

A required column added to an existing table gets a default so the rows already there stay valid: the one after =, or '', 0, FALSE; dates, UUIDs, JSON and references need an = value or have to be optional there. :unique and :index work here too (add_slug_to_posts slug:string?:unique) and add the index; the down file, and a later remove_ migration, drop it before the column. When the table came from zapline g resource, its module, pages and test are updated to read and write the new columns, your own edits kept (The resource follows the table). zapline g resource and g auth write their down file (DROP TABLE) too.

Status, rollback, redo, reset

zapline db status               # every migration, applied or not, and edited files
zapline db rollback             # revert the last migration with its .down.sql
zapline db rollback --steps 3   # ... or the last three, newest first
zapline db redo                 # revert the last one and apply it again
zapline db reset                # revert everything, migrate, run the seed (development)

VERSION         NAME                APPLIED AT           STATE                  DOWN
20260101000000  create todos        2026-10-23 08:54:03  applied                yes
20261022062406  add email to users  2026-10-23 08:54:03  CHANGED since applied  yes
20261023090000  create comments     -                    pending                yes

2 applied, 1 pending

CHANGED since applied means the file was edited after it ran: the app refuses to start until it matches again (edit a migration that already shipped by adding a new one instead). zapline db status then exits non-zero and names the file to restore, as it does for an applied migration whose file was deleted, so a CI step can catch both. Nothing is reverted unless every migration involved has a down file; a one-way migration from an older project (<version>_<name>.sql) becomes reversible when you add <version>_<name>.down.sql next to it. zapline db new keeps writing one-way files in a project whose migrations are all one-way, unless you pass --reversible.

Every command but new runs your app with ZAPLINE_MIGRATE=status|up|down:<n>|redo|reset (plus ZAPLINE_SEED=1 for reset), so it uses exactly the URL and settings the app uses; the app does the work and exits instead of serving. The same commands are there in code, for tests and one-off tools:

use zapline::db::{Migrations, MigrationState};

let migrations = Migrations::open("migrations").await?;
migrations.up(&pool).await?;
let pending = migrations
    .status(&pool)
    .await?
    .iter()
    .filter(|m| m.state == MigrationState::Pending)
    .count();
migrations.down(&pool, 1).await?;

Guard rails

Rolling back drops tables, so production is protected twice:

• zapline db rollback, redo and reset refuse --release (a release build) and APP_ENV/ZAPLINE_ENV=production unless you add --force.
• The app itself, built in release mode, refuses ZAPLINE_MIGRATE=down:<n>, redo and reset unless ZAPLINE_ALLOW_DESTRUCTIVE=1 is set (--force sets it).

The MCP tools db_rollback, db_redo and db_reset need confirm=true, so an assistant has to ask first.

Dates, times and UUIDs

Turn on zapline's chrono and uuid features and use zapline::chrono and zapline::uuid in models: sqlx, serde and the OpenAPI schema (format: date, date-time, uuid) all understand them, with no extra dependencies. zapline g resource turns the features on when its fields need them.

use zapline::chrono::{DateTime, NaiveDate, Utc};
use zapline::uuid::Uuid;

#[model]
#[derive(sqlx::FromRow)]
pub struct Event {
    pub id: i64,
    pub day: NaiveDate,             // DATE on Postgres, TEXT ("2026-01-31") on SQLite
    pub starts_at: DateTime<Utc>,   // TIMESTAMPTZ / TEXT
    pub token: Uuid,                // UUID / BLOB
    pub created_at: DateTime<Utc>,  // DEFAULT CURRENT_TIMESTAMP works on both
}

#[model]
pub struct NewEvent {
    pub day: NaiveDate,
    // Accepts RFC 3339 and what <input type="datetime-local"> sends ("2026-01-31T09:30", as UTC).
    #[serde(deserialize_with = "zapline::extract::datetime")]
    pub starts_at: DateTime<Utc>,
}

zapline::extract::optional_datetime is the same for an Option<DateTime<Utc>> field (empty means None).

JSON columns

With the sqlite or postgres feature, sqlx reads and binds serde_json::Value (re-exported as zapline::db::sqlx::types::JsonValue) for a JSONB column on Postgres and a TEXT one on SQLite, and sqlx::types::Json<T> for your own type. zapline g resource settings prefs:json generates such a column.

use zapline::db::sqlx::types::JsonValue;

#[model]
#[derive(sqlx::FromRow)]
pub struct Settings {
    pub id: i64,
    pub prefs: JsonValue,           // JSONB on Postgres, TEXT on SQLite
}

#[model]
pub struct NewSettings {
    // A JSON body sends {"prefs": {"theme": "dark"}}; a form's <textarea> sends the text.
    #[serde(deserialize_with = "zapline::extract::json_text")]
    pub prefs: JsonValue,
}

zapline::extract::json_text parses a string that holds a JSON object or array, reads an empty string as null (so Option<JsonValue> is None; add #[serde(default)]), and leaves other values alone. Malformed JSON is a 422 naming the field. In templates, {{ item.prefs|tojson }} writes the value back as JSON.

Postgres can query into JSONB (WHERE prefs->>'theme' = $1); SQLite has json_extract(prefs, '$.theme'). Neither is portable, so write those queries for the dialect you use.

Seed data

Demo or development data goes in App::seed, after .database(..):

use zapline::db::{Database, Factory};

App::new()
    .database(Database::from_env())
    .seed(|db| async move {
        Factory::new("todos").set("title", "Try zapline").create(&db).await?;
        Factory::new("todos").set("done", true).create_many(&db, 5).await?;
        Ok(())
    })

zapline db seed     # migrate, run the seed once, exit

Normal runs and tests never run it. zapline db seed starts the app with ZAPLINE_SEED=1, like db migrate, so it uses the app's own DATABASE_URL. Running it twice inserts the rows twice. The fullstack template comes with a seed.

Health

use zapline::db::DbCheck;

App::new()
    .database(Database::from_env())
    .plugin(Health::new().check("database", DbCheck::new()));   // /health/ready pings the database

Testing

Each Database::sqlite_memory() is a fresh, empty database with your migrations applied, so tests run in parallel without stepping on each other:

fn app(db: Database) -> App {
    App::new().database(db).mount((list_posts, create_post))
}

fn main() -> std::io::Result<()> {
    app(Database::from_env()).run("0.0.0.0:8080")
}

#[tokio::test]
async fn creates_a_post() {
    let client = app(Database::sqlite_memory()).test();
    let res = client.post("/posts").json(&serde_json::json!({"title": "Hi"})).send().await;
    assert_eq!(res.status(), 201);
}

Test data with Factory

Factory inserts a row and fills in every column you don't set that the database requires (NOT NULL, no default), read from the schema: unique numbers, text like title 7, user7@example.com for email columns, false, the current time, {} for JSON. A required foreign key gets a parent row, made the same way. Set only what the test is about:

use zapline::db::{sqlx, DefaultDb, Factory};

#[tokio::test]
async fn lists_only_published_posts() {
    let client = app(Database::sqlite_memory()).test();
    let pool: sqlx::Pool<DefaultDb> = client.resources().await.require().unwrap();

    Factory::new("posts").set("published", true).create_many(&pool, 2).await.unwrap();
    Factory::new("posts").set("published", false).create(&pool).await.unwrap();   // its author is created too

    let posts: Vec<serde_json::Value> = client.get("/posts").send().await.json();
    assert_eq!(posts.len(), 2);
}

create returns a Record: get("title") as text, int("id"), json() with typed numbers and booleans (compare it with your API's response), or parse::<Post>() into your own type. .null("column") stores NULL. It works on SQLite and Postgres, in tests and in seeds.

If your SQL is portable between SQLite and Postgres you can test against SQLite and run Postgres in production; otherwise point a test at a real Postgres with Database::postgres(url).

Going further

Ecosystem has complete, tested apps for transactions, savepoints and idempotency keys with sqlx, and for SeaORM, Diesel and Leptos.

Ecosystem: sqlx, SeaORM, Diesel, Leptos

zapline has no ORM of its own and no opinion on which one you use. Whatever you pick plugs into the same three hooks:

1. A startup factory opens the pool and runs migrations (App::database for sqlx, App::provide_with for anything else). If it fails, run returns the error and the port is never bound.
2. A service built from the pool by a second factory, received in handlers as Dep<Service> (see Dependency injection).
3. A readiness check that pings the database through the same pool (see Health checks).

Four complete, tested apps live in examples/ecosystem. Each runs on SQLite with nothing to install:

cd examples/ecosystem
cargo test                  # all four (their own workspace and Cargo.lock)
cd seaorm && cargo run      # http://localhost:8080 , API docs at /docs

Transactions with sqlx

Db (and the Pool in resources) is a plain sqlx pool, so a transaction is begin, your queries on &mut *tx, then commit. Returning early with ? drops the transaction, and sqlx rolls it back:

pub async fn transfer(&self, t: &NewTransfer, key: Option<&str>) -> Result<Outcome> {
    // SQLite: take the write lock up front, so concurrent writers wait on the
    // busy timeout instead of failing with "database is locked".
    let mut tx = self.pool.begin_with("BEGIN IMMEDIATE").await?;
    if let Some(key) = key {
        if let Some(previous) = find_by_key(&mut tx, key).await? {
            return replay(previous, t);      // a retry: nothing moves twice
        }
    }
    let created = move_money(&mut tx, t, key).await?;   // debit, credit, record
    tx.commit().await?;
    Ok(Outcome::Created(created))
}

Three rules from the ledger example carry over to any app:

• Check and change in one statement. UPDATE accounts SET balance_cents = balance_cents - $1 WHERE id = $2 AND balance_cents >= $1 can't be raced; a SELECT followed by an UPDATE can. Look at rows_affected() to tell why nothing changed.

• Savepoints for partial success. tx.begin() inside a transaction issues SAVEPOINT; commit releases it and rollback undoes only that part:

  let mut savepoint = tx.begin().await?;
  match move_money(&mut savepoint, transfer, None).await {
      Ok(created) => { savepoint.commit().await?; items.push(BatchItem::ok(i, created)); }
      Err(e) => { savepoint.rollback().await?; items.push(BatchItem::failed(i, &e)); }
  }

• Idempotency keys are a UNIQUE column read and written in the same transaction: a retried POST with the same Idempotency-Key header gets the original result (200), and the same key with a different body is a 422.

A health check can verify more than connectivity. The ledger's checks that money is conserved:

App::new()
    .database(db)
    .provide_with(|res: Resources| async move {
        let pool: SqlitePool = res.require()?;   // registered by .database(..)
        Ok(Ledger::new(pool))
    })
    .plugin(
        Health::new()
            .check("database", DbCheck::new())
            .check("books", |res: Resources| async move {
                res.dep::<Ledger>()?.check_books().await
            }),
    )

On Postgres, use begin() instead of BEGIN IMMEDIATE: the conditional UPDATE locks the row.

SeaORM

Leave zapline's sqlite/postgres features off; SeaORM has its own pool. Open it (and migrate) in a factory, then build services from it:

App::new()
    .provide_with(|_res: Resources| async move {
        let db = sea_orm::Database::connect(options).await.map_err(db_error)?;
        Migrator::up(&db, None).await.map_err(db_error)?;
        Ok(db)
    })
    .provide_with(|res: Resources| async move {
        Ok(Blog::new(res.dep::<DatabaseConnection>()?))
    })
    .plugin(Health::new().check("database", DatabasePing))

DbErr and zapline::Error are both foreign to your crate, so convert with a function instead of ? alone. Map them to the codes zapline uses for sqlx, so clients see one vocabulary:

pub fn db_error(e: DbErr) -> Error {
    match e.sql_err() {
        Some(SqlErr::UniqueConstraintViolation(_)) => {
            return Error::conflict("already exists").with_code("unique_violation");
        }
        Some(SqlErr::ForeignKeyConstraintViolation(_)) => {
            return Error::conflict("referenced row does not exist or is still in use")
                .with_code("foreign_key_violation");
        }
        _ => {}
    }
    match e {
        DbErr::RecordNotFound(_) => Error::not_found(),
        DbErr::ConnectionAcquire(_) => Error::service_unavailable("database busy").with_code("db_pool_timeout"),
        other => Error::internal(other.to_string()),   // logged, not sent
    }
}

Transactions use SeaORM's closure form; returning Err from it rolls back every step:

self.db.transaction::<_, (), DbErr>(|txn| Box::pin(async move {
    post::Entity::update_many()
        .col_expr(post::Column::AuthorId, Expr::value(into_id))
        .filter(post::Column::AuthorId.eq(from_id))
        .exec(txn).await?;
    author::Entity::delete_by_id(from_id).exec(txn).await?;
    if let Some(name) = merge.rename_to {
        let mut active: author::ActiveModel = into.into();
        active.name = Set(name);
        active.update(txn).await?;                   // a taken name undoes both steps above
    }
    Ok(())
})).await

Return API types from handlers (#[model] structs with OpenAPI schemas), not entities; a From<post::Model> impl keeps the mapping in one place.

Diesel

Diesel is synchronous: run it on tokio's blocking pool, never directly in a handler. The example's whole adapter is one method:

pub async fn run<T, F>(&self, f: F) -> Result<T>
where
    T: Send + 'static,
    F: FnOnce(&mut SqliteConnection) -> Result<T, DbError> + Send + 'static,
{
    let pool = self.0.clone();
    let result = tokio::task::spawn_blocking(move || {
        let mut conn = pool.get().map_err(|_| DbError::PoolTimeout)?;
        f(&mut conn)
    })
    .await
    .map_err(|_| Error::internal("database task panicked"))?;
    Ok(result?)
}

DbError is your own type, so impl From<diesel::result::Error> for DbError and impl From<DbError> for zapline::Error are allowed, and ? works on both sides of the closure. Migrations are compiled in with embed_migrations!("migrations") and applied in the factory that builds the pool. On SQLite, conn.immediate_transaction(|conn| ..) takes the write lock up front; with a conditional UPDATE .. RETURNING, thirty concurrent orders for the last ten units give exactly ten 201s and twenty 409 out_of_stocks.

diesel-async also fits: register its pool with provide_with and await queries in the service directly.

Leptos (server-side rendering)

Leptos components render to HTML strings with its ssr feature, so a zapline handler can load data as usual and return the rendered page:

use leptos::prelude::*;

pub fn render<F: FnOnce() -> V, V: IntoView>(view: F) -> Html<String> {
    let owner = Owner::new();                       // a reactive scope per render
    let body = owner.with(|| view().to_html());
    Html(format!("<!DOCTYPE html>{body}"))
}

#[get("/")]
async fn home(db: Db) -> Result<Html<String>> {
    let notes = all_notes(&db).await?;
    Ok(render(move || view! {
        <Page title="Notes">
            <NotesBoard notes=notes error=None draft=String::new()/>
        </Page>
    }))
}

Forms post to ordinary zapline routes, which answer with Redirect::to("/") (Post/Redirect/Get), or with status 422 and the page re-rendered with the error and the user's input. Leptos escapes text, so user content can't inject markup. For browser interactivity, build a second crate with Leptos's hydrate feature to WASM and serve its pkg/ directory with ServeDir; the server side stays the same.

If you prefer templates to components, zapline's own views (MiniJinja + htmx) need no extra crates.

Views & htmx

zapline::view (feature views) renders HTML with MiniJinja templates (Jinja2 syntax: {{ value }}, {% for %}, {% extends %}, {% block %}). It is built for htmx: the same template renders a whole page for a normal visit and just one block for an htmx request, so there is no separate "partials" folder to keep in sync.

use zapline::prelude::*;
use zapline::view::{context, Hx, HxRequest, Views};

#[get("/todos")]
async fn todos(views: Views, hx: HxRequest, db: Db) -> Result<Html<String>> {
    let todos = load_todos(&db).await?;
    views.page_or_block(&hx, "todos.html", "list", context! { todos })
}

#[post("/todos")]
async fn add(db: Db, Form(new): Form<NewTodo>) -> Result<Response> {
    insert_todo(&db, new).await?;
    Ok(Hx::trigger("todos-changed").with(StatusCode::CREATED))
}

fn main() -> std::io::Result<()> {
    App::new().views("templates").mount((todos, add)).run("0.0.0.0:8080")
}

templates/todos.html:

{% extends "base.html" %}
{% block content %}
  <form hx-post="/todos" hx-swap="none">
    <input name="title" required> <button>Add</button>
  </form>
  <ul id="list" hx-get="/todos" hx-trigger="todos-changed from:body">
    {% block list %}
      {% for t in todos %}<li>{{ t.title }}</li>{% endfor %}
    {% endblock %}
  </ul>
{% endblock %}

API

Values are HTML-escaped automatically in .html templates. Use {{ value | safe }} only for HTML you produced yourself.

Forms: errors next to each field

A rejected form should come back with a message next to each field and what the user typed still in the inputs. ValidForm<T> parses and validates a form post without rejecting it, and views.render_invalid shows the form again:

use serde::{Deserialize, Serialize};
use validator::Validate;
use zapline::prelude::*;
use zapline::session::Flash;
use zapline::view::{context, FormErrors, Invalid, ValidForm, Views};

#[derive(Deserialize, Serialize, Validate)]
struct NewPost {
    #[validate(length(min = 1, max = 200))]
    title: String,
    views: i64,
}

#[get("/posts/new")]
async fn new_post(views: Views) -> Result<Html<String>> {
    views.render("posts/new.html", context! {})
}

#[post("/posts")]
async fn create(views: Views, flash: Flash, db: Db, ValidForm(form): ValidForm<NewPost>) -> Result<Response> {
    let post = match form {
        Ok(post) => post,
        // 422 with `errors` and `old` in the template context.
        Err(invalid) => return views.render_invalid("posts/new.html", context! {}, invalid),
    };
    if title_taken(&db, &post.title).await? {
        // Checks only the handler can make render the same way.
        let errors = FormErrors::one("title", "is already used");
        return views.render_invalid("posts/new.html", context! {}, Invalid::new(errors, &post));
    }
    insert(&db, &post).await?;
    flash.success("Post created");
    Ok(flash.redirect("/posts")) // 303, or HX-Redirect for htmx
}

templates/posts/new.html:

{% extends "base.html" %}
{% block content %}
<form id="post-form" hx-post="/posts">
  {% block form %}
  {% if errors._form %}<p role="alert">{{ errors._form }}</p>{% endif %}
  <label>Title <input name="title" value="{{ old.title }}" aria-invalid="{{ 'true' if errors.title else 'false' }}"></label>
  {% if errors.title %}<small class="error">{{ errors.title }}</small>{% endif %}
  <label>Views <input name="views" type="number" value="{{ old.views }}"></label>
  {% if errors.views %}<small class="error">{{ errors.views }}</small>{% endif %}
  <button>Save</button>
  {% endblock %}
</form>
{% endblock %}

• ValidForm<T> gives the handler Ok(T), or Err(Invalid { errors, old }). Fields that don't parse get a message (views=abc: "must be a number"; empty or missing: "is required"); once every field parses, the validator rules run, with the same messages as the JSON 422 (Validation). Only a request that isn't a form at all (wrong Content-Type, too large) is rejected, like Form<T>.
• errors is a FormErrors: {{ errors.title }} is the first message for title, undefined (falsy) when the field is fine; {{ errors._form }} holds errors about the whole form. Build one by hand with FormErrors::one(field, msg) / .add(field, msg), or from any error with FormErrors::from_error(&err).
• old holds the submitted values by field name, HTML-escaped like any value. Fields whose names look secret (password, token, secret, *_hash) are never echoed back.
• Both are empty globals in every template, so the same template renders the blank form and the rejected one.
• render_invalid answers 422 Unprocessable Entity. For a normal form post it renders the whole page. For htmx it renders only {% block form %} (the inside of the <form>; the whole template if it has no such block). When the form has an id but posts somewhere else (hx-target="#list", a create form above a list), it adds HX-Retarget: #post-form and HX-Reswap: innerHTML, so the messages land in the form instead of the list.

htmx does not swap error responses by default. Allow 422 once, in the layout:

<script>
  // Invalid forms come back as 422 with the form re-rendered: swap it in.
  document.addEventListener("htmx:beforeSwap", (e) => {
    if (e.detail.xhr.status === 422) { e.detail.shouldSwap = true; e.detail.isError = false; }
  });
</script>

Apps created with zapline new --template fullstack have this in templates/base.html, and zapline g resource and zapline g auth generate forms that work this way.

Flash messages

With sessions (cookies feature and a SessionLayer), Flash queues one-time messages for the next page, and every template sees the waiting ones as flash:

use zapline::session::Flash;

#[post("/posts/{id}/delete")]
async fn delete(flash: Flash, db: Db, Path(id): Path<i64>) -> Result<Response> {
    delete_post(&db, id).await?;
    flash.success("Post deleted"); // also .error(..), .info(..), .warning(..)
    Ok(flash.redirect("/posts"))
}

{# base.html #}
<div id="flash">
  {% for m in flash %}<p role="status" class="flash flash-{{ m.level }}">{{ m.message }}</p>{% endfor %}
</div>

• A message stays in the session until something reads it: the first template that uses flash (later reads in the same request see the same list), or flash.take() in a handler (for JSON clients). A message queued while rendering a page shows on that page.
• flash.redirect(to) answers 303 See Other, or HX-Redirect for htmx (which then loads the whole page, where the flash shows).
• An htmx request answered in place (a fragment, no redirect) gets its new messages right away as HX-Trigger: {"flash": {"messages": [{"level": "success", "message": "Saved"}]}}, merged with any HX-Trigger the handler set. Show them as toasts with a few lines of script listening for the flash event (e.detail.messages); the fullstack layout does.
• No cost when unused: flash is a lazy template global. A page reads the session store only when a small marker cookie (zapline.sid.flash) says a message is waiting.

Hot reload

In debug builds templates are read from disk on every render: edit a template and refresh, no rebuild. Under zapline dev you don't even refresh: open pages reload by themselves when a template changes (also with --release, since ZAPLINE_DEV=1 keeps reloading on). Release builds load each template once. To ship the templates inside the binary, pass App::views(zapline::embed!("templates")): release builds then read them from memory, and debug builds still read the directory, so hot reload keeps working (One binary). Otherwise copy templates/ next to the binary when you deploy (the generated Dockerfiles do).

Errors

A template error (missing template, syntax error, unknown filter) is a 500. Under zapline dev (which sets ZAPLINE_DEV=1) the response carries the full message with file and line; in production it is logged and the client gets a generic message.

Durable jobs

Work that must not be lost (emails, webhooks, image processing, billing) goes in a job: a struct stored in your database until a worker has run it. Jobs survive restarts and deploys, are retried with backoff when they fail, and are shared by every instance of the app.

use zapline::db::Database;
use zapline::jobs::{Job, Jobs};
use zapline::prelude::*;

#[model]
struct SendWelcome {
    user_id: i64,
}

impl Job for SendWelcome {
    const NAME: &'static str = "send_welcome";

    async fn run(self, res: Resources) -> Result<()> {
        // load the user with res.require::<..>()?, send the email...
        Ok(())
    }
}

#[post("/signup")]
async fn signup(jobs: Jobs) -> Result<StatusCode> {
    // create the user...
    jobs.enqueue(SendWelcome { user_id: 1 }).await?;
    Ok(StatusCode::CREATED)
}

fn main() -> std::io::Result<()> {
    App::new()
        .database(Database::from_env())
        .jobs(|queue| queue.register::<SendWelcome>())
        .mount(signup)
        .run("0.0.0.0:8080")
}

Requirements: the postgres or sqlite feature, and json (on by default). zapline g job <name> writes the struct, its registration and a test for you.

Writing a job

• The struct is the payload, stored as JSON: keep it small (ids, not whole records). #[model] derives what it needs.
• NAME identifies the job type in the database. Keep it stable when you rename or move the struct, or queued jobs will find no handler.
• run gets the app's Resources, so it can use everything a handler can: res.require::<Pool<Postgres>>()?, res.require::<Mailer>()?, your own services.
• Return Err (or panic) to have the job retried. MAX_ATTEMPTS (default 5) caps the runs.
• Jobs run at least once: if a worker dies mid-run, the job runs again after its lease expires. Make jobs safe to repeat (check before you charge, upsert instead of insert).

Enqueueing

Jobs is an extractor, and also available from Resources (res.require::<Jobs>()?), so a job can enqueue follow-up jobs. Enqueueing a type that isn't registered in .jobs(..) is an error that names the missing .register::<T>().

All three return Ok(true) when the job was stored, and Ok(false) when it was a duplicate (below).

Unique jobs, priorities and queues

Three optional items on Job shape how a type is queued:

#![allow(unused)]
fn main() {
impl Job for ReindexProduct {
    const NAME: &'static str = "reindex_product";
    const QUEUE: &'static str = "search";   // default "default"
    const PRIORITY: i32 = -1;               // default 0; higher runs first

    // At most one queued or running job per product.
    fn unique_key(&self) -> Option<String> {
        Some(self.product_id.to_string())
    }

    async fn run(self, res: Resources) -> Result<()> { /* ... */ Ok(()) }
}
}

• unique_key: while a job of this type with the same key is queued or running, enqueueing another stores nothing and returns Ok(false), so ten edits in a row reindex once. A partial unique index on (name, unique_key) enforces it, across instances too. Once the job has finished (or failed for good), the key is free. enqueue reports duplicates itself instead of a separate enqueue_unique, because uniqueness is a property of the job type: every caller gets it, whether or not it checks the result.
• PRIORITY: due jobs are claimed highest priority first, then oldest first. A password-reset email (10) overtakes a backlog of newsletters (-5).
• QUEUE: by default an instance's workers take jobs from every queue its registered types use. .queues(..) gives each queue its own workers instead, so a flood in one can't hold up another:

#![allow(unused)]
fn main() {
App::new()
    .database(Database::from_env())
    .jobs(|queue| {
        queue
            .register::<SendWelcome>()
            .register::<ReindexProduct>()
            .queues([("default", 4), ("search", 1)])   // or .queues(["default", "search"]) with .workers(n) each
    })
}

An instance only works the queues it lists, so a dedicated search worker is the same app started with .queues([("search", 8)]).

Workers, retries and failures

App::jobs starts the workers at startup and stops them at shutdown, after their current job (within App::tasks_grace_period).

A failed run is retried after 5 s, 20 s, 80 s, 5 min, 21 min (capped at 1 h) until MAX_ATTEMPTS. Then the job stays in the table with status failed and its last error. Finished jobs are deleted.

#![allow(unused)]
fn main() {
let stats = jobs.stats().await?;      // JobStats { queued, running, failed }
for job in jobs.failed(20).await? {   // newest first: id, name, queue, attempts, last_error, payload
    if job.name == "obsolete_job" {
        jobs.discard(job.id).await?;  // delete it (also cancels a queued job)
    }
}
let n = jobs.retry_failed().await?;   // queue every failed job again
}

retry_failed leaves a failed job alone when a newer job holds its unique key. In debug builds, the dev console shows the queue and the latest failures, with a button that retries them all and a Discard button on each failed job, plus per-job counts when metrics are on and every cron job with its next enqueue.

The table is zapline_jobs (created at startup), so plain SQL works for anything else: SELECT name, last_error FROM zapline_jobs WHERE status = 'failed'. A table created by an older zapline gets the queue, priority and unique_key columns added at startup; existing rows land in the default queue at priority 0.

On Postgres, workers claim jobs with FOR UPDATE SKIP LOCKED, so any number of instances share one queue without running a job twice. SQLite serializes writes, which gives the same guarantee for a single server.

Cron jobs

queue.cron(expr, job) enqueues job every time a cron expression matches, and registers the job type if you haven't:

#![allow(unused)]
fn main() {
use zapline::db::Database;
use zapline::jobs::Job;
use zapline::prelude::*;

#[model]
struct SendDigest {
    period: String,
}

impl Job for SendDigest {
    const NAME: &'static str = "send_digest";

    async fn run(self, _res: Resources) -> Result<()> {
        // build and send the digest for self.period
        Ok(())
    }
}

fn app() -> App {
    App::new()
        .database(Database::from_env())
        .jobs(|queue| {
            queue
                .cron("0 8 * * MON-FRI", SendDigest { period: "daily".into() })
                .cron("CRON_TZ=+01:00 0 8 * * MON", SendDigest { period: "weekly".into() })
        })
}
}

Unlike App::schedule, which runs in every instance, a cron job is enqueued once per tick for the whole cluster, however many instances share the database:

• Each tick is a row in zapline_cron (key: the job name and the expression; value: the next tick). At the tick, instances race to move it forward in a transaction; only the one that moves it inserts the job, in the same transaction.
• The job is then an ordinary job: any worker runs it, with retries and backoff.
• Only instances with workers enqueue (.workers(0) web instances don't).
• If every instance was down at a tick, the job is enqueued once when the first instance comes back, then the schedule resumes. Missed ticks don't pile up.
• The job's fields are serialized once, at startup: every tick enqueues the same payload. Schedule the same job type with different payloads on different expressions, as above. Scheduling one type twice on the same expression panics at startup, and so does an invalid expression.
• Changing a job's expression starts a new row; the old one is ignored.

Metrics

Install the Metrics plugin (.plugin(Metrics::new()), in any order with .jobs(..)) and the queue exports these series on GET /metrics, labelled by job name. Without the plugin nothing is recorded:

Useful alerts: increase(jobs_dead_total[1h]) > 0, and a failure ratio of rate(jobs_failed_total[5m]) / rate(jobs_started_total[5m]). Counters are per instance, so sum by (job) across instances. The queue depth is in the table: jobs.stats() or SELECT status, COUNT(*) FROM zapline_jobs GROUP BY status.

Testing jobs

With .workers(0) nothing runs in the background, and run_pending runs the due jobs on the spot, so tests are deterministic:

#![allow(unused)]
fn main() {
let client = App::new()
    .database(Database::sqlite_memory())
    .jobs(|queue| queue.register::<SendWelcome>().workers(0))
    .test();
let jobs: Jobs = client.resources().await.require()?;

client.post("/signup").send().await.assert_status(201);
assert_eq!(jobs.run_pending().await?, 1);
}

Jobs or background tasks?

Use background tasks for best-effort work (an audit log line, a cache warm-up) and jobs for everything a user would notice missing.

Email

zapline::mail sends email over SMTP in production, keeps it in a dev inbox you can open in the browser while developing, and captures it in tests.

use zapline::mail::{Email, Mailer};
use zapline::prelude::*;

#[post("/invite")]
async fn invite(mail: Mailer) -> Result<&'static str> {
    mail.send(
        Email::to("ada@example.com")
            .subject("You're invited")
            .text("Join us: https://example.com/join")
            .html("<p>Join us: <a href=\"https://example.com/join\">example.com</a></p>"),
    )
    .await?;
    Ok("sent")
}

fn main() -> zapline::Result<()> {
    App::new()
        .mailer(Mailer::from_env()?)
        .mount(invite)
        .run("0.0.0.0:8080")?;
    Ok(())
}

Requirements: the mail feature (included in full).

Configuration

Mailer::from_env() reads:

Without SMTP_URL, a debug build uses the outbox described below, and a release build refuses to start, so production never drops mail silently.

Mailer::smtp(url) and Mailer::outbox() build the two kinds directly, and .default_from(addr) sets the sender in code.

Recipients and headers

#![allow(unused)]
fn main() {
Email::to("ada@example.com")
    .and_to("grace@example.com")       // more `To` recipients
    .cc("team@example.com")             // visible copies
    .bcc("audit@example.com")           // blind copies
    .reply_to("support@example.com")
    .header("List-Unsubscribe", "<https://example.com/unsubscribe?u=42>")
    .subject("Release notes")
    .text("...");
}

Blind copies go to the SMTP envelope only: the sent message has no Bcc header, so no recipient can see them. header(name, value) adds any other header; sending fails with a clear error for a value with a line break (header injection), a name that isn't a valid header name, or a header that has its own method (To, Subject, Content-Type, ...).

Attachments and inline images

#![allow(unused)]
fn main() {
let email = Email::to(&user.email)
    .subject("Your invoice")
    .text("Your invoice is attached.")
    .html(r#"<img src="cid:logo" alt="Acme"><p>Your invoice is attached.</p>"#)
    .attach("invoice-42.pdf", "application/pdf", pdf_bytes)
    .inline("logo", "image/png", logo_png);
}

attach adds a file the recipient can download; inline embeds an image the HTML shows with src="cid:<id>". Together they may be at most MAX_ATTACHMENT_BYTES (10 MiB, before base64 makes them a third larger): a larger email fails to send, and fails to enqueue, with an error that says so. For big files, send a storage link instead.

email.to_mime(default_from) returns the message exactly as it would be sent, for saving as an .eml file or checking in tests.

Templated email: zapline g mailer

With the views feature, Email::template renders the subject and both bodies from templates in the app's templates/ directory:

#![allow(unused)]
fn main() {
use zapline::view::{context, Views};

#[post("/signup")]
async fn signup(views: Views, mail: Mailer, Json(form): Json<Signup>) -> Result<StatusCode> {
    let url = format!("https://app.example.com/confirm?t={}", token(&form.email));
    let email = Email::to(&form.email)
        .template(&views, "mail/welcome", context! { name => form.name, url })?;
    mail.send(email).await?;
    Ok(StatusCode::CREATED)
}
}

templates/mail/welcome.html is the HTML body; its {% block subject %} is the subject, so it fits in <title> (and in a shared layout that other emails extend):

<title>{% block subject %}Welcome, {{ name }}{% endblock %}</title>
<p>Hi {{ name }}, please <a href="{{ url }}">confirm your address</a>.</p>

templates/mail/welcome.txt, when it exists, is the plain-text body (not HTML-escaped). Without it the text part is made from the HTML: paragraphs and line breaks kept, links as label (url), lists as - item. Either template may be missing, not both.

zapline g mailer welcome writes all of it: src/mail/welcome.rs with pub fn welcome(views: &Views, to: &str) -> Result<Email>, declared in src/mail/mod.rs (and pub mod mail; in src/lib.rs), the two templates, and tests/welcome_email.rs, which renders the email, sends it to an outbox mailer and checks the subject, the recipient and both bodies. It turns on the mail and views features and tells you what is left to register on the app.

The dev inbox

An outbox mailer sends nothing. It logs each message and serves the last 50 at GET /_dev/mail: subject, recipients (with blind copies listed apart, since the message itself doesn't carry them), the HTML body in a sandboxed frame with its inline images, an HTML / text toggle with clickable links in the text, download links for attachments, and the whole message as an .eml file. Sign-up confirmations and password-reset links work end to end on your machine with no mail server. The page only exists when the outbox is in use, and the dev console links it.

Sending in the background

Sending inline makes the request wait for the SMTP server and fail if it is down. With a database, Email is also a durable job: register it once and enqueue messages instead of sending them.

#![allow(unused)]
fn main() {
App::new()
    .database(Database::from_env())
    .mailer(Mailer::from_env()?)
    .jobs(|queue| queue.register::<Email>());

// in a handler
jobs.enqueue(Email::to(&user.email).subject("Welcome").text(body)).await?;
}

A failed send is retried with backoff (5 s, 20 s, 80 s, ...). Attachments travel with the job (stored base64 in its payload).

Testing

#![allow(unused)]
fn main() {
let mailer = Mailer::outbox();
let client = App::new().mailer(mailer.clone()).mount(invite).test();

client.post("/invite").send().await.assert_status(200);
let sent = mailer.sent();
assert_eq!(sent[0].to, ["ada@example.com"]);
assert!(sent[0].text.as_deref().unwrap().contains("/join"));
}

Email is a plain struct with public fields (to, cc, bcc, subject, text, html, headers, attachments), so assertions can look at anything. Generated emails come with such a test (zapline g mailer).

Admin panel

App::admin serves an admin panel for every table in your database: browse, search, sort and page through rows, and create, edit and delete them through forms. There is no code per table. It reads the schema on each request, so a table added by a new migration shows up on the next reload.

#![allow(unused)]
fn main() {
App::new()
    .database(Database::from_env())
    .admin(|admin| admin) // http://localhost:8080/admin
}

It works on SQLite and Postgres and needs no extra Cargo feature. The fullstack template turns it on.

Who can open it

Without protect, the panel behaves like the dev console: it exists only in debug builds and answers only requests from the same machine. In a release build that call does nothing, so it can stay in the code.

To use it in production, protect it with a middleware that decides who is an admin. The panel is then served in every build, to whoever the middleware lets through:

#![allow(unused)]
fn main() {
use zapline::middleware::Next;

async fn admins_only(mut req: Request, next: Next) -> Response {
    let user = match CurrentUser::from_request_parts(&mut req).await {
        Ok(CurrentUser(user)) => user,
        Err(_) => return Redirect::to("/login").into_response(),
    };
    let admins = std::env::var("ADMIN_EMAILS").unwrap_or_default();
    // Anyone can sign up with any address: trust it only once its owner
    // has proved it (a used reset link, a GitHub/Google login).
    if !admins.split(',').any(|e| e.trim().eq_ignore_ascii_case(&user.email))
        || !user.email_verified
    {
        return Error::forbidden().into_response();
    }
    next.run(req).await
}

app.admin(|admin| admin.protect(admins_only))
}

zapline g auth generates this: the accounts listed in ADMIN_EMAILS get in once their owner has proved the address (by using a password reset link, or by logging in with GitHub/Google), others get 403, and visitors are sent to /login. Calling admin again replaces the earlier setup, which is how the generated auth::mount protects the panel that the template turned on.

Form posts must come from the same site: a request whose Origin doesn't match its Host gets 403 cross_origin, on top of the SameSite=Lax session cookie.

What it shows

Rows are edited by their primary key; tables without a single-column primary key are browse-only, and .read_only() makes the whole panel browse-only.

Lists and forms

The list shows 50 rows per page, newest first (by primary key). Click a column header to sort by it, again to reverse. The search box matches text, JSON and date columns case-insensitively (% and _ are literal), and a number also matches the primary key.

In the forms, an empty field means NULL when the column allows it, and the column's default when creating a row. Numbers are checked before anything is written. If the database refuses a change (a unique email taken, a missing required value), the form comes back with the database's message and what you typed.

With both postgres and sqlite enabled, admin uses Postgres; use admin_in::<sqlx::Sqlite>(..) for SQLite.

Translations (i18n)

With the i18n feature, an app can speak several languages. Put one TOML file per language in locales/, register them, and take a Locale in handlers:

# locales/en.toml
hello = "Hello, {name}!"

[inbox]
count.zero = "No messages"
count.one = "{count} message"
count.other = "{count} messages"

# locales/fr.toml
hello = "Bonjour, {name} !"
inbox.count.one = "{count} message"
inbox.count.other = "{count} messages"

#![allow(unused)]
fn main() {
use zapline::i18n::{I18n, Locale};

#[get("/hello/{name}")]
async fn hello(t: Locale, name: Path<String>) -> String {
    t.t_with("hello", &[("name", &name.0)])
}

App::new()
    .i18n(I18n::load("locales")?)
    .mount(hello)
}

The file name is the language tag (en, fr, pt-BR), and nested tables become dotted keys (inbox.count.one). I18n::messages(lang, toml) adds a language from a string instead, for example one embedded with include_str!.

Under zapline dev, translations loaded with I18n::load are read again when a file in the directory changes, and open pages reload: no restart. A file with a syntax error keeps the last good messages (the error goes to stderr). Outside zapline dev (no ZAPLINE_DEV=1) they are loaded once.

Which language

For each request, Locale is the first available language from:

1. ?lang=fr in the URL. The app then remembers it in a lang cookie (one year, SameSite=Lax), so a language switcher is just links: <a href="?lang=fr">Français</a>.
2. The lang cookie.
3. The Accept-Language header, by its weights.
4. The default: en if there is an en.toml, otherwise the first file alphabetically, or the one set with .default_lang("de").

Tags match exactly (ignoring case) or by their main part: pt-BR uses pt.toml when there is no pt-BR.toml, and de-AT uses de.toml.

Messages

A message missing in the visitor's language falls back to the default language, then to the key itself, so a gap shows on the page rather than failing it. I18n::missing() lists the gaps, which makes a good test:

#![allow(unused)]
fn main() {
#[test]
fn every_language_is_complete() {
    let i18n = I18n::load("locales").unwrap();
    assert_eq!(i18n.missing(), []);
}
}

The dev console shows each language with its message count and missing keys.

Plurals. plural picks key.one, key.few, key.many, key.other and so on by the language's rules (CLDR rules for integers, built in for English, French, Portuguese, Spanish, German, Russian, Ukrainian, Polish, Czech, Arabic, Japanese, Chinese, Korean and the many languages that follow one of their patterns). A key.zero message, when the language has one, is used for 0 in any language. All forms come from one language: if the visitor's language lacks the key, the default language's forms and rules are used.

In templates

With the views feature, pass the Locale into the context and call it:

#![allow(unused)]
fn main() {
#[get("/")]
async fn index(views: Views, t: Locale) -> Result<Html<String>> {
    views.render("index.html", context! { t, unread: 3 })
}
}

<html lang="{{ t.lang }}">
<h1>{{ t("hello", name=user.name) }}</h1>
<p>{{ t.plural("inbox.count", unread) }}</p>

Translated text is escaped like any other value.

If you cache pages with ResponseCache, the language is part of the page: cache only pages that don't depend on it, or vary the cache by language.

Authentication & authorization

Authenticate a group of routes with JWTs, then declare who may call what, next to the route:

#![allow(unused)]
fn main() {
use zapline::auth::{Authenticate, Claims, CurrentUser, JwtConfig};
use zapline::prelude::*;

async fn me(CurrentUser(claims): CurrentUser<Claims>) -> String {
    format!("hello {}", claims.sub)
}

async fn purge_cache() -> &'static str {
    "purged"
}

fn app() -> App {
    let api = Routes::new()
        .get("/me", me)
        .delete("/cache", purge_cache)
        .require_roles(["admin"])         // authorization: declarative, next to the route
        .wrap(Authenticate::jwt());       // authentication: who is calling?

    App::new()
        .jwt(JwtConfig::hs256(std::env::var("JWT_SECRET").expect("JWT_SECRET")))
        .nest("/api", api)
}
}

Authentication is split in two so each part can be swapped:

1. Authentication (who is it?) is done by an Authenticator, run by the Authenticate route middleware. It stores the user for the CurrentUser<U> extractor.
2. Authorization (may they?) is declared as route policies (.require_auth(), .require_roles(..), .require_scopes(..)) and enforced by Authenticate (with .authorize()) or by Guard.

Policies fail closed: a route with a policy can never become public because a middleware was forgotten or installed in the wrong place. See Policies fail closed.

Cargo features: everything here is always available except JWT, which needs jwt (it pulls in jsonwebtoken), and password hashing, which needs password. CSRF is in Cookies, sessions & CSRF.

Accounts in one command: zapline g auth

For apps with users who sign up with an email and password, generate the whole thing instead of assembling it. In a project with a database (the fullstack template, or any project with migrations/):

zapline g auth

It also enables zapline's cookies, mail, oauth and password features, adds SESSION_SECRET, SMTP_URL, MAIL_FROM, APP_URL, ADMIN_EMAILS and the GitHub/Google client variables to .env.example, and compiles Argon2 optimized in debug builds, so tests stay fast.

Password reset. POST /api/auth/forgot (or the /forgot page) emails a link to APP_URL/reset?token=... and answers the same whether or not the account exists; the email goes out after the response, so timing doesn't tell either. The token is 256 random bits, stored only as a SHA-256 digest, valid for an hour and usable once; using it sets the new password, logs the user in and voids the account's other reset links. While developing, without SMTP_URL, the emails appear in the dev inbox at /_dev/mail, so the whole flow works on your machine.

Log in with GitHub or Google. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET (or the GOOGLE_ pair) and the login and sign-up pages show "Continue with GitHub"; providers without credentials are simply left out. Register the callback APP_URL/auth/github/callback (or /auth/google/callback) with the provider. The first social login links the identity to the account with the same verified email, or creates an account without a usable password ("Forgot your password?" sets one); later logins use the link. Sign-up doesn't check the address, so someone could open an account with another person's email ahead of them: when the real owner then logs in with GitHub or Google, that account's password is dropped and its sessions end.

Admins. The accounts in ADMIN_EMAILS get into /admin only after the address is proved: by using a reset link sent to it, or by a GitHub/Google login with it. Until then they get 403 email_unverified, so signing up first with the boss's address gets an attacker nowhere. See Social login for the pieces underneath.

Protect a handler by taking the generated extractor; it answers 401 login_required when nobody is logged in:

#![allow(unused)]
fn main() {
use crate::routes::auth::CurrentUser;

#[get("/api/notes")]
async fn my_notes(db: Db, CurrentUser(user): CurrentUser) -> Result<Json<Vec<Note>>> {
    let notes = sqlx::query_as::<_, Note>("SELECT * FROM notes WHERE user_id = $1")
        .bind(user.id)
        .fetch_all(&*db)
        .await?;
    Ok(Json(notes))
}
}

Take Option<CurrentUser> to serve visitors and users differently. The generated code is yours to change: it is about 200 lines with no framework magic.

What it does for you: passwords hashed with Argon2id on the blocking thread pool; a fresh session id at login (no session fixation); changing the password logs out every other session (a session_version column); sign-up, log-in and reset requests limited to 10 a minute per client IP (set TRUSTED_PROXIES behind a proxy); requests from other sites refused (SameOrigin, CSRF protection with nothing to add to forms); the same error and the same timing for an unknown email and a wrong password (password::verify_missing); sessions in the database, so logins survive restarts and deploys; HttpOnly, SameSite=Lax cookies, Secure in release builds. In production set SESSION_SECRET to 32 or more random bytes (openssl rand -base64 48): release builds refuse to start without it.

Passwords

With the password feature, zapline::auth::password hashes and checks passwords with Argon2id (OWASP parameters, PHC strings that carry their salt and parameters):

#![allow(unused)]
fn main() {
use zapline::auth::password;

let hash = password::hash("correct horse battery staple").await?;
assert!(password::verify("correct horse battery staple", &hash).await?);
}

Both run on the blocking thread pool, since a hash takes tens of milliseconds by design. password::verify_missing(pw) spends the same time and returns false: call it when the account doesn't exist. hash_blocking and verify_blocking are the synchronous versions.

Social login (OAuth)

With the oauth feature, App::oauth adds "log in with GitHub/Google/..." using the authorization-code flow with PKCE. Register a provider, then handle its callback with the OAuthLogin extractor:

#![allow(unused)]
fn main() {
use zapline::auth::oauth::{OAuth, OAuthLogin};

#[get("/auth/github/callback")]
async fn github_done(login: OAuthLogin, session: Session) -> Result<Redirect> {
    // login.user: provider, id, email, email_verified, name, avatar_url, raw
    let user_id = find_or_create_user(&login.user).await?;
    session.regenerate();
    session.insert("user_id", user_id)?;
    Ok(Redirect::to(login.next.as_deref().unwrap_or("/")))
}

let app = App::new()
    .oauth(OAuth::from_env("github")?) // GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
    .mount(github_done);
}

Send people to /auth/github (optionally ?next=/settings) to start. That route redirects to the provider with a random state and a PKCE challenge, kept in a short-lived HttpOnly cookie scoped to /auth. On the way back, OAuthLogin checks the state, exchanges the code (sending the PKCE verifier) and fetches the profile. It answers 400 invalid_oauth_state for a forged or replayed callback, 401 oauth_denied when the user cancelled at the provider, 401 oauth_failed when the provider rejects the code, and 404 for a provider that isn't registered. next is kept only when it is a local path, so it can't be used as an open redirect.

.scopes([...]) replaces the scopes, .redirect_url(url) overrides the callback URL (by default APP_URL + /auth/{name}/callback, or the request's host when APP_URL is unset), and .endpoints(..) points a built-in provider at a test double. Only trust user.email for account linking when user.email_verified is true.

Credential extractors

Three extractors read credentials without any setup. Missing or malformed credentials are rejected with 401, a WWW-Authenticate challenge and a stable error code: missing_credentials or invalid_credentials.

Use Option<BearerToken> (or any of the others) for optional credentials. The extractors never compare secrets for you. Do it in constant time:

#![allow(unused)]
fn main() {
use zapline::auth::{constant_time_eq, ApiKey, BasicAuth, BearerToken};
use zapline::prelude::*;

async fn admin(token: BearerToken) -> Result<&'static str> {
    if !constant_time_eq(token.token(), "let-me-in") {
        return Err(Error::forbidden());
    }
    Ok("welcome")
}

async fn metrics(auth: BasicAuth) -> Result<&'static str> {
    if !auth.verify("ops", "correct horse battery staple") {
        return Err(auth.reject());          // 401 invalid_credentials + Basic challenge
    }
    Ok("# metrics")
}

async fn report(key: ApiKey) -> Result<&'static str> {
    if !key.verify_any(["k-123", "k-456"]) {
        return Err(key.reject());
    }
    Ok("report")
}
}

constant_time_eq(a, b) compares byte strings without leaking their contents through timing (only a length difference is visible). BasicAuth::verify and ApiKey::verify_any always run every comparison. All three types redact their secrets in Debug output.

Customize where the credentials come from by registering a config as state:

#![allow(unused)]
fn main() {
use zapline::auth::{ApiKeyConfig, BasicAuthConfig};
use zapline::prelude::*;

fn app() -> App {
    App::new()
        .state(BasicAuthConfig::new("admin area"))                           // realm in the challenge
        .state(ApiKeyConfig::new().header("x-token").query_param("api_key")) // keys in URLs end up in logs: prefer headers
}
}

JWT

Needs the jwt feature. Register a JwtConfig with App::jwt, then either extract claims with Jwt<C> or authenticate a group with Authenticate::jwt().

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::auth::{Claims, Jwt, JwtConfig};
use zapline::prelude::*;

// Issue a token (for example in a login handler).
async fn login(State(jwt): State<JwtConfig>) -> Result<String> {
    let claims = Claims::new("user-1")
        .roles(["admin"])
        .scopes(["reports:read"])
        .claim("tenant", "acme");
    jwt.encode(&claims)
}

// Verify one: the `Jwt` extractor validates the bearer token and yields its claims.
async fn whoami(Jwt(claims): Jwt) -> String {
    claims.sub
}

fn app() -> App {
    let jwt = JwtConfig::hs256("an-example-secret-of-at-least-32-bytes")
        .issuer("https://auth.example.com")
        .audience("api")
        .ttl(Duration::from_secs(15 * 60));

    App::new().jwt(jwt).post("/login", login).get("/whoami", whoami)
}
}

Jwt<C> defaults to Claims. Use Jwt<MyClaims> for your own claims type (C: Deserialize). A missing token is 401 missing_credentials, an expired one 401 token_expired and anything else wrong 401 invalid_token, all with a Bearer challenge. Without App::jwt(..) the extractor fails with 500 auth_misconfigured.

JwtConfig

The configured algorithm is pinned, so a token cannot choose its own (no alg: none, no HS/RS confusion). With several keys, each key keeps its own algorithm: a token naming an RS256 key with alg: HS256 is rejected. exp is required and validated, nbf is validated when present, and tokens longer than 16 KiB are rejected before parsing. encode fills in a missing iat, exp (now + ttl), iss and aud.

Claims

Build claims with Claims::new(sub), then .roles(..), .scopes(..), .claim(key, value), .expires_in(duration), .expires_at(unix_secs), .issuer(..) and .audience(..). claims.has_role("admin") and claims.has_scope("x") are available too.

For your own claims type, implement HasRoles and use JwtAuthenticator:

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use zapline::auth::{Authenticate, CurrentUser, HasRoles, JwtAuthenticator};
use zapline::prelude::*;

#[derive(Clone, Serialize, Deserialize)]
struct AppClaims {
    sub: String,
    exp: u64,
    #[serde(default)]
    roles: Vec<String>,
    tenant: String,
}

impl HasRoles for AppClaims {
    fn roles(&self) -> &[String] {
        &self.roles
    }
}

async fn tenant(CurrentUser(c): CurrentUser<AppClaims>) -> String {
    c.tenant
}

fn api() -> Routes {
    Routes::new()
        .get("/tenant", tenant)
        .wrap(Authenticate::new(JwtAuthenticator::<AppClaims>::new()).required().authorize())
}
}

Key rotation

A JwtConfig holds a key ring: the key that signs, and every key that still verifies. Tokens name their key in the kid header, and the ring picks the key by that name. A JwtKey is one entry: a kid, an algorithm and the key material.

Pass None for the private key to get a key that only verifies. Three methods change the ring while the app runs. Every clone of the config shares the ring, so calling them on the State<JwtConfig> a handler extracted takes effect for the whole app:

#![allow(unused)]
fn main() {
use zapline::auth::{Claims, JwtConfig, JwtKey};
use zapline::prelude::*;

fn jwt() -> Result<JwtConfig> {
    let current = std::env::var("JWT_SECRET")?;
    let jwt = JwtConfig::hs256(current).key_id("2026-10");
    // Tokens signed with last month's key keep working until they expire.
    if let Ok(previous) = std::env::var("JWT_SECRET_PREVIOUS") {
        jwt.add_key(JwtKey::hs256("2026-09", previous)?);
    }
    Ok(jwt)
}

// Rotate without a restart, for example from an admin endpoint.
async fn rotate(State(jwt): State<JwtConfig>) -> Result<&'static str> {
    let next = std::env::var("JWT_SECRET_NEXT")?;
    jwt.rotate(JwtKey::hs256("2026-11", next)?)?;
    Ok("rotated")
}
}

How a key is picked:

• If the token's kid names a key in the ring, only that key is tried. The key's algorithm must match the token's alg.
• Keys without a kid (a config built without .key_id(..)) accept any kid with their algorithm, so configs that predate key ids keep working.
• A token without kid verifies only when the choice is unambiguous: a key without a kid, or a ring with a single key.
• Otherwise the token is 401 invalid_token, or it is looked up in the remote JWK Set when one is configured.

A config with a single unnamed key (the usual JwtConfig::hs256(secret)) verifies without reading the token header, as before. Rotations live in memory. When several instances sign tokens, give each instance the same keys at startup with add_key, or let one service issue tokens and have the others follow its JWK Set.

Publishing your keys

App::serve_jwks(path) serves the public half of every RSA, EC and Ed25519 key in the registered config as a JWK Set (RFC 7517). HMAC keys are never published. The set is read on every request, so a rotation shows up at once. Responses carry Cache-Control: public, max-age=300, and the route is left out of the OpenAPI document.

#![allow(unused)]
fn main() {
use zapline::auth::{JwtConfig, JwtKey};
use zapline::prelude::*;

fn app() -> Result<App> {
    let public = std::fs::read("keys/2026-10.pub.pem")?;
    let private = std::fs::read("keys/2026-10.pem")?;
    let key = JwtKey::es256_pem("2026-10", &public, Some(&private))?;
    Ok(App::new()
        .jwt(JwtConfig::from_key(key).issuer("https://auth.example.com"))
        .serve_jwks("/.well-known/jwks.json"))
}
}

jwt.public_jwks() returns the same set (a JwkSet) if you serve it some other way.

To rotate without failing any request, publish the next key first with jwt.add_key(next_public_key). Wait at least as long as verifiers cache the set, then switch with jwt.rotate(next_key). Zapline verifiers don't need the wait: they refetch the set when a token names a key they haven't seen.

Tokens from an identity provider (JWKS)

With the jwks feature, a config can verify tokens signed by keys that an identity provider publishes at its jwks_uri: Auth0, Okta, Keycloak, Cognito, Entra ID, Google, or another zapline app's serve_jwks.

#![allow(unused)]
fn main() {
use std::time::Duration;
use zapline::auth::{Authenticate, Jwks, JwtConfig};
use zapline::prelude::*;

fn app() -> App {
    let issuer = "https://example.eu.auth0.com/";
    let jwt = JwtConfig::from_jwks(Jwks::discover(issuer))
        .issuer(issuer)
        .audience("https://api.example.com");
    App::new()
        .jwt(jwt)
        .nest("/api", Routes::new().get("/me", || async { "hi" }).wrap(Authenticate::jwt()))
}
}

Jwks::new(url) takes the JWK Set URL directly. Jwks::discover(issuer) reads jwks_uri from {issuer}/.well-known/openid-configuration (OpenID Connect Discovery) and checks that the document names the same issuer. JwtConfig::hs256(secret).jwks(..) combines your own keys with the provider's: local kids are checked first and never cause a fetch.

How the cache behaves:

• Startup. App::jwt fetches the set before the server starts accepting requests. This is best effort: if the provider is down, the failure is logged and the first request tries again.
• TTL. Keys are fresh for .ttl(..) (default 10 minutes). After that, the next request still verifies with the cached keys while a background task refreshes them. No request waits for a refresh of keys it already has.
• Unknown kid. A token naming a key the cache doesn't have triggers a refresh, so a provider's rotation is picked up at once. Refreshes happen at most once per .min_refresh_interval(..) (default 30 s), however many made-up kids arrive. Concurrent requests share one fetch.
• Timeouts. A request waits at most .timeout(..) (default 5 s) for a fetch.
• Failures. On an error status, malformed JSON, a set with no usable keys, or a timeout, the cached keys are kept and keep verifying (stale on error). A token whose key the cache can't have while the provider is failing gets 503 jwks_unavailable, not a misleading 401.

The algorithm comes from the JWK's alg, or from its key type when alg is absent: RS256 for RSA, ES256/ES384 for P-256/P-384, EdDSA for Ed25519. Keys whose alg doesn't fit their key type, symmetric (oct) keys, encryption keys ("use": "enc") and unknown key types are skipped. .algorithms([Algorithm::RS256]) narrows the set further. HMAC algorithms are never accepted from a remote set, so a public key can't be turned into an HMAC secret.

jwt.decode(token) is synchronous and uses only cached keys. A key it is missing is fetched in the background. The Jwt extractor, Authenticate::jwt() and jwt.verify(token).await wait for the fetch.

Custom authenticators

Anything that can turn a request into a user (sessions, API keys looked up in a database, mTLS, an external identity provider) is an Authenticator. Return:

• Ok(None) when the request carries no credentials for this scheme,
• Ok(Some(user)) when they are valid,
• Err(..), typically a 401, when they are present but invalid.

#![allow(unused)]
fn main() {
use zapline::auth::{constant_time_eq, Authenticate, Authenticator, CurrentUser, HasRoles};
use zapline::prelude::*;

#[derive(Clone)]
struct User {
    name: String,
    roles: Vec<String>,
}

impl HasRoles for User {
    fn roles(&self) -> &[String] {
        &self.roles
    }
}

struct StaticKeys;

impl Authenticator for StaticKeys {
    type User = User;

    async fn authenticate(&self, req: &Request) -> Result<Option<User>> {
        let Some(key) = req.headers().get("x-api-key") else {
            return Ok(None);
        };
        if constant_time_eq(key.as_bytes(), "k-admin") {
            return Ok(Some(User { name: "ops".into(), roles: vec!["admin".into()] }));
        }
        Err(Error::unauthorized().with_code("invalid_credentials"))
    }
}

async fn who(CurrentUser(user): CurrentUser<User>) -> String {
    user.name
}

fn admin() -> Routes {
    Routes::new()
        .get("/stats", || async { "stats" })
        .require_roles(["admin"])
        .get("/who", who)
        .wrap(Authenticate::new(StaticKeys).authorize())
}
}

A closure Fn(&Request) -> impl Future<Output = Result<Option<User>>> works as an authenticator too:

#![allow(unused)]
fn main() {
use zapline::auth::{Authenticate, CurrentUser};
use zapline::prelude::*;

fn api() -> Routes {
    let auth = Authenticate::new(|req: &Request| {
        let user = req.headers().get("x-user").and_then(|v| v.to_str().ok()).map(str::to_owned);
        async move { Ok(user) }
    })
    .required();

    Routes::new()
        .get("/me", |CurrentUser(name): CurrentUser<String>| async move { name })
        .wrap(auth)
}
}