Ocre

Ocre is a Rails-like Rust web framework for Cloudflare Workers, designed to run on the Workers free plan and to be written by AI agents: generators write plain, readable Rust (models, controllers, templates, migrations) into your app, and the ocre CLI builds, runs and deploys it.

An Ocre app is one Worker compiled to WebAssembly. It stores data in D1 (SQLite), renders HTML with askama templates and htmx, or serves JSON (and optionally GraphQL). Everything it uses is on Cloudflare’s free plan: Workers, D1, Queues (background jobs), Cron Triggers, R2 (files), Durable Objects (WebSockets), KV (cache) and Email Routing.

cargo install --git https://github.com/tgeselle/ocre.rs ocre-cli
ocre new qa --starter qa --yes
cd qa
ocre dev        # http://localhost:8787: a live Q&A app
ocre deploy     # https://qa.<your-subdomain>.workers.dev

Status: early. The APIs described here are the ones in the repository’s main branch; there is no stable release yet.

How these docs are organized

The Rust API of the ocre crate is documented item by item in the rustdoc reference, and on one page in the API index.

For AI agents

• Every page is also plain Markdown: add .md to its URL (/guides/models is /guides/models.md).
• /llms.txt lists every page with a one-line description; /llms-full.txt is all pages in one file.
• Pages are self-contained: prerequisites, complete code, the commands to run and their expected output. Rust examples marked as checked compile against a real generated app.
• Each generated app has an AGENTS.md with the conventions, commands and free-plan limits of that app; read it first, then these docs for details.
• With --json, every ocre command prints exactly one JSON object on stdout and never prompts (see CLI commands).

Installation

This page installs the tools an Ocre app needs (Rust through rustup with the WebAssembly target, Node.js 22 for Cloudflare’s cf CLI, and the ocre CLI), checks the installation, and creates a first app with ocre new, either through the guided setup or with flags.

Before you start

You need:

• macOS, Linux or Windows with a terminal, and git if you want ocre new --git or to install from a clone.
• About 2 GB of disk space for the Rust toolchain and the Cargo build cache.
• A Cloudflare account only when you deploy. Everything on this page, and ocre dev, works without one.

Install Rust with rustup

Ocre apps compile to WebAssembly (wasm32-unknown-unknown), so the Rust toolchain must be able to add that target. Install Rust with rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

Every generated app also has a rust-toolchain.toml that asks rustup for the stable toolchain with this target:

[toolchain]
channel = "stable"
targets = ["wasm32-unknown-unknown"]

Do not use Homebrew’s rust formula (brew install rust). It installs rustc and cargo without rustup: they ship only the standard library of your own machine, cannot add the wasm32-unknown-unknown target, and ignore rust-toolchain.toml. ocre dev and ocre deploy detect it and stop (see Troubleshooting). On macOS, brew install rustup is fine: it is rustup, and its rustup and cargo commands work as above once $(brew --prefix rustup)/bin is on your PATH.

Install Node.js

The CLI runs Cloudflare’s cf CLI for local development, deploys and every Cloudflare API call. Install Node.js 22 or newer (cf’s minimum), which provides npm and npx. You do not install cf yourself: each app pins it in its own package.json, with wrangler (which cf delegates the build to, and which Ocre uses for local database commands) and typescript, and ocre new runs npm install in the new app. Outside an app (ocre login before your first app), the CLI runs npx --yes cf@1.0.0-beta.5.

cf sends anonymous usage telemetry by default; it prints a notice about it on stderr. To opt out, run npx cf cli telemetry disable once, or set CF_SEND_TELEMETRY=false in your environment. Ocre does not change that choice for you.

If you used an earlier Ocre, whose apps ran wrangler with a wrangler.toml: cf keeps its own login, separate from wrangler’s, so run ocre login once again, and convert each app with Upgrading from wrangler.toml.

Install the ocre CLI

Install the ocre binary from the Git repository:

cargo install --git https://github.com/tgeselle/ocre.rs ocre-cli

The package is ocre-cli; the command it installs is ocre (in ~/.cargo/bin, which rustup puts on your PATH). From a clone of the repository, install the same binary with:

git clone https://github.com/tgeselle/ocre.rs
cd ocre.rs
cargo install --path crates/ocre-cli

Run the same command again to upgrade. Ocre has no release on crates.io yet; apps depend on the ocre crate from the same Git repository.

Check the installation

ocre --version

ocre 0.2.0

ocre --help

Ocre: Rails-like Rust web framework for Cloudflare Workers, free plan first.

Usage: ocre [OPTIONS] <COMMAND>

Commands:
  new       Create a new app in ./<NAME>. In a terminal, asks for anything not given by flags
  login     Log in to Cloudflare (opens a browser) unless already logged in
  generate  Generate code (alias: `g`)
  migrate   Apply D1 migrations (local database unless --remote)
  db        Database tasks: seed, reset
  sql       Run SQL on the D1 database (local unless --remote) and print the rows
  dev       Apply local migrations, then run the app with `cf dev`
  deploy    Deploy to Cloudflare and apply remote migrations
  secret    Print a new random secret, like `rails secret`: a value for SECRET_KEY_BASE
  routes    List the app's HTTP routes, read from its source (no build)
  i18n      Translations: checks of the locale files (see `ocre g locale`)
  help      Print this message or the help of the given subcommand(s)

Options:
      --json     Print one JSON object on stdout; send tool logs to stderr. Never prompts
  -h, --help     Print help
  -V, --version  Print version

ocre <command> --help describes each command and its flags; the CLI reference documents them all.

Create an app with the guided setup

In a terminal, ocre new asks for everything its flags did not answer:

ocre new

The questions, in order (each one is skipped when the matching flag was given):

The setup then creates the app, runs npm install in it, deploys it if you said yes, and ends with a “Next steps” note (cd <name>, ocre dev, ocre deploy, plus ocre login when you skipped the login) and either Your app is live at <url> or Happy building!. Esc or Ctrl-C cancels with error: cancelled.

Create an app with flags (agents and scripts)

The guided setup only runs when stdin and stdout are a terminal and neither --yes nor --json was given. Otherwise ocre new never prompts: flags decide, and anything not given takes an opt-in default (full-stack, empty starter, no Cloudflare login, no git, no deploy; the npm install still runs).

ocre new blog --yes

  create  blog/Cargo.toml
  create  blog/cloudflare.config.ts
  create  blog/wrangler.config.ts
  create  blog/package.json
  create  blog/tsconfig.json
  create  blog/rust-toolchain.toml
  create  blog/.gitignore
  create  blog/AGENTS.md
  create  blog/migrations/.gitkeep
  create  blog/public/robots.txt
  create  blog/src/lib.rs
  create  blog/templates/layout.html
  create  blog/templates/home.html
  create  blog/.dev.vars
  npm install (cf 1.0.0-beta.5, wrangler 4.144.0)

Next:
  cd blog
  ocre dev
  ocre deploy

With --json, the same result is one JSON object on stdout, and the exit code is 0 on success, 1 on failure:

ocre new other --json --yes

{"command":"new","created":["other/Cargo.toml","other/cloudflare.config.ts","other/wrangler.config.ts","other/package.json","other/tsconfig.json","other/rust-toolchain.toml","other/.gitignore","other/AGENTS.md","other/migrations/.gitkeep","other/public/robots.txt","other/src/lib.rs","other/templates/layout.html","other/templates/home.html","other/.dev.vars"],"next":["cd other","ocre dev","ocre deploy"],"ok":true,"ran":["npm install (cf 1.0.0-beta.5, wrangler 4.144.0)"]}

--starter blog also runs the scaffold generator for Post title:string body:text published:boolean and lists its files (src/models/post.rs, migrations/0001_create_posts.sql, src/posts.rs, templates/posts/*.html…). --starter qa builds the app of the tutorial: it runs ocre g auth, ocre g scaffold Event name:string public_id:token user:references and ocre g scaffold Question event:references body:text votes:integer answered:boolean --realtime, then writes the room over the generated files; --api --starter qa stops with the qa starter has HTML pages; it cannot be API-only. --api writes an API-only src/lib.rs, no templates/, and adds [package.metadata.ocre] mode = "api" to Cargo.toml.

What ocre new creates

The app has no Cloudflare resources yet: the first ocre deploy creates the D1 database and the SECRET_KEY_BASE secret. The tutorial continues from here.

Troubleshooting

These are the errors the CLI prints for a broken setup, with the hint it gives. With --json they come as {"ok": false, "error": ..., "hint": ...}.

Homebrew’s rust, or any toolchain without the WebAssembly target (ocre dev, ocre deploy):

error: the wasm32-unknown-unknown target is not installed for rustc at /opt/homebrew/Cellar/rust/1.90.0
hint: use a rustup toolchain (Homebrew's `rust` has no wasm target) and run `rustup target add wasm32-unknown-unknown`

Fix: brew uninstall rust, install rustup as above, then rustup target add wasm32-unknown-unknown. which rustc should print a path under ~/.cargo/bin (or Homebrew’s rustup prefix).

With rustup installed but another Rust first in PATH, the hint says so (this rustc is not rustup's but comes first in PATH ...). ocre dev and ocre deploy stop before building, but a plain cargo check --target wasm32-unknown-unknown in that shell fails with error[E0463]: can't find crate for core``: the same cause. Put export PATH="$HOME/.cargo/bin:$PATH" last in your shell profile (Homebrew’s rustup formula: /opt/homebrew/opt/rustup/bin), or uninstall Homebrew’s rust; ocre doctor runs the same check.

No Rust at all:

error: rustc not found
hint: install Rust with rustup: https://rustup.rs

No Node.js (ocre new without --no-install):

error: npm not found
hint: install Node.js 22 or newer (it provides npm), or pass --no-install and run `npm install` in the app later

The app’s npm packages not installed (after ocre new --no-install, or in a fresh clone), for ocre dev and ocre deploy (local database commands such as ocre migrate say the app's wrangler is not installed (node_modules/.bin/wrangler) with the same fix):

error: the app's npm packages are not installed (node_modules/.bin/cf, node_modules/.bin/wrangler)
hint: run `npm install` in /path/to/blog (needs Node.js 22 or newer)

An app command run outside an app:

error: no cloudflare.config.ts found in this directory or its parents
hint: run this command inside an Ocre app, or create one with `ocre new <name>`

ocre new errors: an invalid name (here ocre new Blog --yes), no name without a terminal (ocre new --yes), and a directory that already exists (the error shows its absolute path):

error: invalid app name `Blog`
hint: use lowercase letters, digits and dashes, starting with a letter (max 63), e.g. `my-blog`

error: missing app name
hint: run `ocre new <name>`, or run `ocre new` in a terminal for the guided setup

error: `/path/to/blog` already exists
hint: choose another name or remove the directory

See also

• Tutorial: a live Q&A app: build, run and deploy a first app.
• CLI commands: every command and flag, including ocre new.
• Deployment: what ocre deploy creates on Cloudflare.
• Configuration: cloudflare.config.ts, .dev.vars, variables and secrets.
• Upgrading from wrangler.toml: converting an app made by an earlier Ocre.

Tutorial: a live Q&A app

This tutorial builds a live Q&A app with Ocre, step by step: hosts sign up and create events, anyone with an event’s link asks questions and votes for them, and the list reorders live on every open screen over WebSockets. Along the way it covers generators, accounts, ownership checks, realtime channels, validations, request tests and a deploy to the Cloudflare Workers free plan.

Before you start

• The tools from Installation: Rust through rustup with the wasm32-unknown-unknown target, Node.js 22 or newer, and the ocre CLI (ocre --version prints ocre 0.2.0).
• About 30 minutes. Nothing here needs a Cloudflare account until Deploy; the whole app runs locally.
• curl, to follow along from a terminal, and a browser for the live part: every page is a normal HTML page at http://localhost:8787.

The commands and outputs on this page come from a real run, except Deploy, which is described from the CLI’s code. Outputs that change from run to run (dates, random ids, cookie values) will differ on your machine. The finished app is also a starter: ocre new qa --starter qa creates it in one command.

Create the app

ocre new qa --yes
cd qa

  create  qa/Cargo.toml
  create  qa/cloudflare.config.ts
  create  qa/wrangler.config.ts
  create  qa/package.json
  create  qa/tsconfig.json
  create  qa/rust-toolchain.toml
  create  qa/rustfmt.toml
  create  qa/.gitignore
  create  qa/AGENTS.md
  create  qa/migrations/.gitkeep
  create  qa/public/robots.txt
  create  qa/tests/app.rs
  create  qa/src/lib.rs
  create  qa/templates/layout.html
  create  qa/templates/home.html
  create  qa/templates/error.html
  create  qa/.dev.vars
  npm install (cf 1.0.0-beta.5, wrangler 4.144.0)

Next:
  cd qa
  ocre dev
  ocre deploy

--yes skips the guided setup and keeps its defaults: a full-stack app (HTML pages), the empty starter, no Git repository, no Cloudflare login. ocre new then runs npm install in the app, which installs Cloudflare’s cf CLI (with the wrangler it delegates builds to, and typescript) at the versions pinned in package.json; pass --no-install to skip it when offline. Without --yes, in a terminal, ocre new qa asks those questions instead (see Installation).

The app is a Rust crate compiled to WebAssembly and run as one Cloudflare Worker. src/lib.rs is the entry point and the router; generators add modules under its // ocre:modules line and routes under // ocre:routes. templates/layout.html loads htmx and sets hx-boost="true" on <body>, so links and forms swap the page body instead of reloading it, and every page still works without JavaScript (see htmx). AGENTS.md summarizes the app’s conventions and commands for AI agents.

Hosts: accounts

Hosts sign up to create events; the audience never needs an account. ocre g auth writes sign-up, login, logout, password reset and magic links into the app:

ocre g auth

  create  migrations/0001_create_users.sql
  create  migrations/0002_create_auth_tokens.sql
  create  migrations/0003_create_api_keys.sql
  create  src/models/mod.rs
  create  src/models/user.rs
  create  src/models/api_key.rs
  create  src/models/auth_token.rs
  create  src/auth_api.rs
  create  src/auth.rs
  create  src/registrations.rs
  create  src/sessions.rs
  create  src/passwords.rs
  create  src/confirmations.rs
  create  templates/auth/signup.html
  create  templates/auth/login.html
  create  templates/auth/account.html
  create  templates/auth/magic_link_new.html
  create  templates/auth/magic_link_show.html
  create  templates/auth/password_new.html
  create  templates/auth/password_edit.html
  create  templates/auth/confirmation_show.html
  update  src/lib.rs
  update  cloudflare.config.ts

Next:
  ocre migrate
  ocre dev
  open http://localhost:8787/signup

The code is the app’s own: src/auth.rs holds the extractors handlers take, CurrentUser (signed in, otherwise redirected to /login) and OptionalUser (signed in or not). See Authentication for every file.

Events

An event belongs to a host and has a public link. Generate it with a user reference and a random public id:

ocre g scaffold Event name:string public_id:token user:references

  create  migrations/0004_create_events.sql
  create  src/models/event.rs
  create  tests/factories/mod.rs
  create  tests/factories/event.rs
  create  src/events.rs
  create  templates/events/index.html
  create  templates/events/show.html
  create  templates/events/new.html
  create  templates/events/edit.html
  create  templates/events/_form.html
  create  tests/events.rs
  update  src/models/user.rs
  update  src/models/mod.rs
  update  src/lib.rs

Next:
  ocre migrate
  ocre dev
  open http://localhost:8787/events

• public_id:token gives each event 22 random URL-safe characters, set by create, and the generated pages use it in URLs instead of the integer id: /events/c1wWvvdHUcKW080CDwgf6A, which nobody can guess or enumerate. That link is what a host shares.
• user:references adds user_id with a foreign key to users, event.user(&ctx) on the event and user.events(&ctx, page) on the user.

Questions, live

Questions belong to an event. --realtime makes the generated pages live: every create, edit and delete is pushed to every open list over a WebSocket.

ocre g scaffold Question event:references body:text votes:integer answered:boolean --realtime

  create  migrations/0005_create_questions.sql
  create  src/models/question.rs
  create  tests/factories/question.rs
  create  src/questions.rs
  create  templates/questions/index.html
  create  templates/questions/show.html
  create  templates/questions/new.html
  create  templates/questions/edit.html
  create  templates/questions/_form.html
  create  templates/questions/_row.html
  create  tests/questions.rs
  create  src/realtime.rs
  update  src/models/event.rs
  update  src/models/mod.rs
  update  tests/factories/mod.rs
  update  src/lib.rs
  update  Cargo.toml
  update  cloudflare.config.ts
  update  templates/layout.html

Next:
  ocre migrate
  ocre dev
  open http://localhost:8787/questions
  open http://localhost:8787/questions in a second window, then create a question

The first --realtime scaffold sets up the pieces every live page needs:

Apply the five migrations and start the app:

ocre migrate
ocre dev

ocre dev builds the Worker and serves it at http://localhost:8787 with a local D1 database and the Durable Objects running in workerd, Cloudflare’s runtime.

Try the generated pages: open http://localhost:8787/signup and create an account, then http://localhost:8787/events/new and create an event, then open http://localhost:8787/questions in two windows and create a question (event 1) in one of them: it appears in the other without a reload. From a terminal, with the same steps done by curl:

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -c jar.txt http://localhost:8787/signup -d 'email=ada@example.com&password=correct horse'
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://localhost:8787/events -d 'name=Friday all-hands&user_id=1'
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://localhost:8787/questions -d 'event_id=1&body=Will there be pizza?&votes=0'
curl -s http://localhost:8787/ocre/dev/realtime/sent.json

303 http://localhost:8787/
303 http://localhost:8787/events/1SPmf4grPih32uDXg8GP-g
303 http://localhost:8787/questions/1
[{"id":1,"channel":"questions","message":"<tbody hx-swap-oob=\"afterbegin:#questions\"><tr id=\"question_1\"><td>1</td><td>Will there be pizza?</td><td>0</td><td>false</td><td><a href=\"/questions/1\">Show</a> <a href=\"/questions/1/edit\">Edit</a></td></tr></tbody>"}]

/ocre/dev/realtime/sent.json lists the recent broadcasts (in ocre dev only; deployed apps answer 404). The message is HTML: htmx’s WebSocket extension reads its hx-swap-oob attribute and inserts the row at the top of the element with id questions in every open page.

Two things are wrong with these generated pages for a Q&A app, and the next sections fix them. The second request created an event for user 1 without being signed in, because the form takes user_id like any other field. And every question of every event lands on one page, /questions, with edit buttons for everyone.

Events belong to their host

The host of an event is the signed-in user, never a form field. In src/events.rs, the form keeps only the name, and to_new takes the host’s id:

/// What the new and edit forms submit. The host is the signed-in user, never
/// a form field.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct EventForm {
    pub name: String,
}

impl EventForm {
    fn from_record(record: &Event) -> Self {
        Self { name: record.name.clone() }
    }

    /// Runs the model's checks, so the form shows every error at once
    /// (database checks run in `create`).
    fn to_new(&self, user_id: i64) -> Result<NewEvent> {
        let new = NewEvent { name: self.name.clone(), user_id };
        new.validate().finish()?;
        Ok(new)
    }

    fn to_changes(&self) -> Result<EventChanges> {
        let changes = EventChanges { name: Some(self.name.clone()), user_id: None };
        changes.validate().finish()?;
        Ok(changes)
    }
}

Remove the User field from templates/events/_form.html, so it only has the name:

{% if !errors.is_empty() %}
  <ul class="errors">
    {% for error in errors %}<li>{{ error.full_message() }}</li>{% endfor %}
  </ul>
{% endif %}
  <label>Name <input name="name" value="{{ form.name }}" required placeholder="Friday all-hands"></label>

The handlers that create or change an event take CurrentUser, and a small helper refuses other users with a 403:

/// The event `id`, when `user` hosts it: other users get a 403.
async fn hosted(ctx: &Ctx, user: &User, id: i64) -> Result<Event> {
    let record = event::find(ctx, id).await?.or_404()?;
    if record.user_id != user.id {
        return Err(Error::Forbidden);
    }
    Ok(record)
}

/// The events the signed-in user hosts, newest first.
async fn index(State(ctx): State<Ctx>, CurrentUser(user): CurrentUser, flash: Flash) -> Result<Html<String>> {
    render(&IndexView { flash, events: event::for_users(&ctx, &[user.id]).await? })
}

async fn new(CurrentUser(_): CurrentUser) -> Result<Html<String>> {
    render(&NewView { form: EventForm::default(), errors: vec![] })
}

async fn create(
    State(ctx): State<Ctx>,
    CurrentUser(user): CurrentUser,
    session: Session,
    Form(form): Form<EventForm>,
) -> Result<Response> {
    let created = match form.to_new(user.id) {
        Ok(new) => event::create(&ctx, new).await,
        Err(err) => Err(err),
    };
    match created {
        Ok(record) => {
            session.flash("notice", "Your event is ready: share its link.")?;
            Ok(Redirect::to(&paths::show(&record.public_id)).into_response())
        }
        Err(Error::Invalid(errors)) => {
            Ok((StatusCode::UNPROCESSABLE_ENTITY, render(&NewView { form, errors })?).into_response())
        }
        Err(err) => Err(err),
    }
}

edit, update and delete take CurrentUser(user): CurrentUser too and start with hosted(&ctx, &user, id).await?;. The use lines gain crate::auth::{CurrentUser, OptionalUser} and crate::models::user::User. The complete file is src/events.rs of the qa starter.

IndexView loses its page field: event::for_users, generated by user:references, returns the host’s events without pagination. templates/events/index.html becomes the host’s list:

{% extends "layout.html" %}

{% block title %}Your events{% endblock %}

{% block content %}
<h1>Your events</h1>
{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
{% if let Some(alert) = flash.alert() %}<p class="alert">{{ alert }}</p>{% endif %}
<p><a class="button" href="{{ paths::new() }}">New event</a></p>

{% if events.is_empty() %}
<p class="empty">No events yet: create one, then share its link with your audience.</p>
{% else %}
<ul class="events">
  {% for event in events %}
  <li><a href="{{ paths::show(event.public_id) }}">{{ event.name }}</a> <span class="muted">created {{ event.created_at }}</span></li>
  {% endfor %}
</ul>
{% endif %}
{% endblock %}

The room

An event’s page becomes its room: the event’s name, the link to share, a form to ask, and the live list of its questions, most voted first. Questions get their own routes under the event, and the generated question pages go away:

rm templates/questions/index.html templates/questions/show.html templates/questions/new.html \
   templates/questions/edit.html templates/questions/_form.html templates/questions/_row.html

Two queries go in the model, src/models/question.rs, after for_events:

/// The questions of an event as the room shows them: open ones first, most
/// voted first (oldest first on a tie), then answered ones. At most 200.
pub async fn for_event(ctx: &Ctx, event_id: i64) -> Result<Vec<Question>> {
    query()
        .eq("event_id", event_id)
        .order_asc("answered")
        .order_desc("votes")
        .order_asc("id")
        .limit(200)
        .all(&ctx.db()?)
        .await
}

/// Adds one vote. A single UPDATE, so votes arriving at the same moment are
/// all counted. `None` when there is no question with this id.
pub async fn vote(ctx: &Ctx, id: i64) -> Result<Option<Question>> {
    let sql = "UPDATE questions SET votes = votes + 1, updated_at = datetime('now') WHERE id = ?1 RETURNING *";
    ctx.db()?.first(sql, params![id]).await
}

src/questions.rs is rewritten for the room. Replace it with:

//! Questions in an event's room: the audience asks and votes, the host marks
//! questions answered or deletes them. After each change the event's list is
//! rendered again and broadcast (channels in src/realtime.rs), so it reorders
//! live in every open room.

use askama::Template;
use axum::{
    Form, Router,
    extract::{Path, State},
    http::{StatusCode, Uri},
    response::{IntoResponse, Redirect, Response},
    routing::post,
};
use ocre::{Ctx, Error, Flash, Htmx, OptionExt, Result, Session, realtime, render};
use serde::Deserialize;

use crate::auth::{CurrentUser, OptionalUser};
use crate::events;
use crate::models::event::{self, Event};
use crate::models::question::{self, NewQuestion, Question, QuestionChanges};
use crate::models::user::User;

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/events/{id}/questions", post(ask))
        .route("/questions/{id}/vote", post(vote))
        .route("/questions/{id}/answer", post(answer))
        .route("/questions/{id}/delete", post(delete))
}

pub mod paths {
    use std::fmt::Display;

    /// `id` is the event's public id.
    pub fn ask(id: impl Display) -> String {
        format!("/events/{id}/questions")
    }

    pub fn vote(id: impl Display) -> String {
        format!("/questions/{id}/vote")
    }

    pub fn answer(id: impl Display) -> String {
        format!("/questions/{id}/answer")
    }

    pub fn delete(id: impl Display) -> String {
        format!("/questions/{id}/delete")
    }
}

/// What the ask form submits.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct QuestionForm {
    pub body: String,
}

/// The question list of a room, also sent to open rooms on every change.
/// `host` adds the moderation buttons.
#[derive(Template)]
#[template(path = "questions/_list.html")]
struct ListView<'a> {
    questions: &'a [Question],
    host: bool,
}

/// The channel every visitor of the room listens to.
pub fn channel(event: &Event) -> String {
    format!("event:{}", event.public_id)
}

/// The host's channel: the same list, with moderation buttons.
pub fn host_channel(event: &Event) -> String {
    format!("host:{}", event.public_id)
}

/// Sends the event's current list to both channels. Best effort: a failed
/// broadcast is logged by Ocre and never fails the request.
async fn broadcast(ctx: &Ctx, event: &Event) -> Result<()> {
    let questions = question::for_event(ctx, event.id).await?;
    let audience = render(&ListView { questions: &questions, host: false })?.0;
    let host = render(&ListView { questions: &questions, host: true })?.0;
    realtime::broadcast(ctx, &channel(event), &realtime::update("questions", &audience)).await.ok();
    realtime::broadcast(ctx, &host_channel(event), &realtime::update("questions", &host)).await.ok();
    Ok(())
}

async fn ask(
    State(ctx): State<Ctx>,
    session: Session,
    flash: Flash,
    OptionalUser(user): OptionalUser,
    uri: Uri,
    Path(key): Path<String>,
    Form(form): Form<QuestionForm>,
) -> Result<Response> {
    let event = event::find_by_public_id(&ctx, &key).await?.or_404()?;
    let new = NewQuestion { event_id: event.id, body: form.body.trim().to_owned(), votes: 0, answered: false };
    match question::create(&ctx, new).await {
        Ok(_) => {
            broadcast(&ctx, &event).await?;
            session.flash("notice", "Your question is in.")?;
            Ok(Redirect::to(&events::paths::show(&key)).into_response())
        }
        Err(Error::Invalid(errors)) => {
            let room = events::room(&ctx, flash, &uri, event, user, form, errors).await?;
            Ok((StatusCode::UNPROCESSABLE_ENTITY, room).into_response())
        }
        Err(err) => Err(err),
    }
}

/// Session key: the questions this browser voted for.
const VOTED: &str = "voted";

/// One vote per question and browser; voting again changes nothing.
async fn vote(State(ctx): State<Ctx>, session: Session, Htmx(is_htmx): Htmx, Path(id): Path<i64>) -> Result<Response> {
    let record = question::find(&ctx, id).await?.or_404()?;
    let event = record.event(&ctx).await?.or_404()?;
    let mut voted: Vec<i64> = session.get(VOTED)?.unwrap_or_default();
    if !voted.contains(&id) {
        question::vote(&ctx, id).await?;
        // The session is a cookie (4 KB at most): remember the last 200 votes.
        if voted.len() >= 200 {
            voted.remove(0);
        }
        voted.push(id);
        session.insert(VOTED, &voted)?;
        broadcast(&ctx, &event).await?;
    }
    Ok(done(is_htmx, &event))
}

/// Marks a question answered, or open again.
async fn answer(
    State(ctx): State<Ctx>,
    CurrentUser(user): CurrentUser,
    Htmx(is_htmx): Htmx,
    Path(id): Path<i64>,
) -> Result<Response> {
    let (record, event) = hosted(&ctx, &user, id).await?;
    let changes = QuestionChanges { answered: Some(!record.answered), ..Default::default() };
    question::update(&ctx, id, changes).await?;
    broadcast(&ctx, &event).await?;
    Ok(done(is_htmx, &event))
}

async fn delete(
    State(ctx): State<Ctx>,
    CurrentUser(user): CurrentUser,
    Htmx(is_htmx): Htmx,
    Path(id): Path<i64>,
) -> Result<Response> {
    let (_, event) = hosted(&ctx, &user, id).await?;
    question::delete(&ctx, id).await?;
    broadcast(&ctx, &event).await?;
    Ok(done(is_htmx, &event))
}

/// The question `id` and its event, when `user` hosts that event.
async fn hosted(ctx: &Ctx, user: &User, id: i64) -> Result<(Question, Event)> {
    let record = question::find(ctx, id).await?.or_404()?;
    let event = record.event(ctx).await?.or_404()?;
    if event.user_id != user.id {
        return Err(Error::Forbidden);
    }
    Ok((record, event))
}

/// htmx buttons get a 204 (the broadcast updates the page); a plain form
/// post goes back to the room.
fn done(is_htmx: bool, event: &Event) -> Response {
    if is_htmx {
        StatusCode::NO_CONTENT.into_response()
    } else {
        Redirect::to(&events::paths::show(&event.public_id)).into_response()
    }
}

What it does:

• One list, rendered on the server. After any change, broadcast loads the event’s questions in their room order and sends the whole list, rendered by templates/questions/_list.html, wrapped by realtime::update("questions", ...): htmx replaces the contents of #questions in every open room. Sending the list rather than one row is what makes it reorder live when votes change the ranking. It costs one D1 query and two Durable Object requests per change; the messages measured about 350 bytes per question for the audience and 800 for the host (with its buttons), so about 70 KB and 160 KB at the 200-question cap.
• Two channels. The audience and the host see the same list, except that the host’s has “Mark answered” and “Delete” buttons. A broadcast reaches everyone on a channel, so each version goes to its own channel: event:<public id> and host:<public id>.
• One vote per browser. The session (a signed, encrypted cookie that every visitor has) remembers the questions this browser voted for. An anonymous visitor who clears their cookies can vote again, as in most live Q&A tools; votes that must be unique per person need accounts.
• htmx buttons. The vote and moderation buttons post with htmx and get a 204 No Content: the layout tells htmx not to swap anything for a 204, and the broadcast updates the page, the voter’s included. Without JavaScript, the same forms post normally and the handler redirects back to the room.
• Moderation is the host’s. answer and delete take CurrentUser (visitors are sent to /login) and hosted answers 403 to other users.

The room page is the event’s show. In src/events.rs, ShowView gets the room’s data and show renders it through room, which ask also calls to show the form’s errors (the file’s use lines gain http::Uri, crate::models::question::{self, Question} and crate::questions::{self, QuestionForm}):

/// The room: the event, the ask form and the live question list.
#[derive(Template)]
#[template(path = "events/show.html")]
struct ShowView {
    flash: Flash,
    event: Event,
    /// The signed-in user hosts this event: moderation buttons and the
    /// host's channel.
    host: bool,
    /// The full link to share with the audience.
    link: String,
    questions: Vec<Question>,
    form: QuestionForm,
    errors: Vec<FieldError>,
}

impl ShowView {
    /// The channel this page listens to (src/realtime.rs).
    fn channel(&self) -> String {
        if self.host { questions::host_channel(&self.event) } else { questions::channel(&self.event) }
    }
}

async fn show(
    State(ctx): State<Ctx>,
    flash: Flash,
    OptionalUser(user): OptionalUser,
    uri: Uri,
    Id(id, ..): Id,
) -> Result<Html<String>> {
    let record = event::find(&ctx, id).await?.or_404()?;
    room(&ctx, flash, &uri, record, user, QuestionForm::default(), vec![]).await
}

/// Renders the room of `event`; the ask form shows `form` and `errors`.
pub async fn room(
    ctx: &Ctx,
    flash: Flash,
    uri: &Uri,
    event: Event,
    user: Option<User>,
    form: QuestionForm,
    errors: Vec<FieldError>,
) -> Result<Html<String>> {
    let host = user.is_some_and(|user| user.id == event.user_id);
    let link = format!("{}{}", crate::auth::origin(uri), paths::show(&event.public_id));
    let questions = question::for_event(ctx, event.id).await?;
    render(&ShowView { flash, event, host, link, questions, form, errors })
}

templates/events/show.html:

{% extends "layout.html" %}

{% block title %}{{ event.name }}{% endblock %}

{% block content %}
{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
{% if let Some(alert) = flash.alert() %}<p class="alert">{{ alert }}</p>{% endif %}

<section class="room-head">
  <p class="eyebrow">Live Q&amp;A</p>
  <h1>{{ event.name }}</h1>
  <p class="share">Share this link: <code>{{ link }}</code></p>
  {% if host %}
  <div class="host-tools">
    <p>You host this event. <a href="{{ paths::edit(event.public_id) }}">Rename</a> · <a href="{{ paths::index() }}">Your events</a></p>
    <form action="{{ paths::delete(event.public_id) }}" method="post" hx-confirm="Delete this event and its questions?">
      <button class="link danger" type="submit">Delete event</button>
    </form>
  </div>
  {% endif %}
</section>

<form class="ask" action="{{ crate::questions::paths::ask(event.public_id) }}" method="post">
  {% if !errors.is_empty() %}
  <ul class="errors">
    {% for error in errors %}<li>{{ error.full_message() }}</li>{% endfor %}
  </ul>
  {% endif %}
  <label>Your question <textarea name="body" rows="2" maxlength="280" required placeholder="Ask anything…">{{ form.body }}</textarea></label>
  <button type="submit">Ask</button>
</form>

{# Live updates: htmx's WebSocket extension (loaded by layout.html) swaps in the list every change broadcasts (src/questions.rs, channels in src/realtime.rs). #}
<div hx-ext="ws" ws-connect="/realtime/{{ self.channel() }}">
  <div id="questions">{% include "questions/_list.html" %}</div>
</div>
{% endblock %}

And the list both the page and the broadcasts use, templates/questions/_list.html:

{# The room's question list: rendered in the page and broadcast to open rooms on every change (src/questions.rs). `host` adds the moderation buttons. #}
{% if questions.is_empty() %}
<p class="empty">No questions yet. Be the first to ask.</p>
{% else %}
<ol class="questions">
  {% for question in questions %}
  {% let vote = crate::questions::paths::vote(question.id) %}
  <li id="question_{{ question.id }}" class="question{% if question.answered %} answered{% endif %}">
    <form action="{{ vote }}" method="post" hx-post="{{ vote }}" hx-swap="none">
      <button class="vote" type="submit" title="Vote for this question"{% if question.answered %} disabled{% endif %}>▲<span>{{ question.votes }}</span></button>
    </form>
    <p class="body">{{ question.body }}</p>
    {% if question.answered %}<span class="badge">Answered</span>{% endif %}
    {% if host %}
    {% let answer = crate::questions::paths::answer(question.id) %}
    {% let delete = crate::questions::paths::delete(question.id) %}
    <div class="moderate">
      <form action="{{ answer }}" method="post" hx-post="{{ answer }}" hx-swap="none">
        <button class="link" type="submit">{% if question.answered %}Reopen{% else %}Mark answered{% endif %}</button>
      </form>
      <form action="{{ delete }}" method="post" hx-post="{{ delete }}" hx-swap="none" hx-confirm="Delete this question?">
        <button class="link danger" type="submit">Delete</button>
      </form>
    </div>
    {% endif %}
  </li>
  {% endfor %}
</ol>
{% endif %}

askama escapes {{ question.body }}, so a question containing HTML shows as text, in the page and in broadcasts. The starter’s templates/events/index.html (the host’s events), templates/home.html (the landing page) and templates/layout.html (navigation and styles) are plain HTML; copy them from ocre new demo --starter qa or write your own.

Who may listen

src/realtime.rs decides who may open which channel. The room’s channels are named after the event’s public id, so knowing the link is what lets a visitor in; the host’s channel also needs the host’s session. Replace connect (and add OptionExt to the ocre imports, with use crate::auth::OptionalUser; and use crate::models::event;):

/// Opens a WebSocket on `channel` for whoever may listen to it:
/// `event:<public id>`, an event's room, is open to everyone with the link;
/// `host:<public id>`, the same list with moderation buttons, only to the
/// event's host. Unknown channels and events are a 404.
async fn connect(
    State(ctx): State<Ctx>,
    Path(channel): Path<String>,
    OptionalUser(user): OptionalUser,
    upgrade: WebSocketUpgrade,
) -> Result<Response> {
    match channel.as_str() {
        // ocre:channels
        name => {
            let (kind, key) = name.split_once(':').or_404()?;
            let record = event::find_by_public_id(&ctx, key).await?.or_404()?;
            match kind {
                "event" => {}
                "host" => {
                    let user = user.ok_or(Error::Unauthorized)?;
                    if user.id != record.user_id {
                        return Err(Error::Forbidden);
                    }
                }
                _ => return Err(Error::NotFound),
            }
        }
    }
    upgrade.connect(&ctx, &channel).await
}

Browsers send the session cookie with the WebSocket handshake, so OptionalUser works there like in any handler. Keep the // ocre:channels line: later --realtime scaffolds add their channel under it, before the catch-all arm.

Try the room

With ocre dev running (it rebuilds on every change), sign in as the host, create an event, then ask and vote as a visitor with another cookie jar:

curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -c host.txt -b host.txt http://localhost:8787/login -d 'email=ada@example.com&password=correct horse'
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -c host.txt -b host.txt http://localhost:8787/events -d 'name=Friday all-hands'
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" http://localhost:8787/events -d 'name=Sneaky'

303 http://localhost:8787/
303 http://localhost:8787/events/c1wWvvdHUcKW080CDwgf6A
303 http://localhost:8787/login

The visitor without an account is sent to the login page. Now the audience, with the event’s public id from the redirect:

EVENT=c1wWvvdHUcKW080CDwgf6A
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -c guest.txt -b guest.txt http://localhost:8787/events/$EVENT/questions -d 'body=Will there be pizza?'
curl -s -o /dev/null -w "%{http_code}\n" -c guest.txt -b guest.txt http://localhost:8787/events/$EVENT/questions -d 'body=When is the next release?'
curl -s -o /dev/null -w "%{http_code}\n" -c guest.txt -b guest.txt -H 'HX-Request: true' -X POST http://localhost:8787/questions/3/vote
curl -s -o /dev/null -w "%{http_code}\n" -c guest.txt -b guest.txt -H 'HX-Request: true' -X POST http://localhost:8787/questions/3/vote
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -b guest.txt -X POST http://localhost:8787/questions/2/answer
curl -s -o /dev/null -w "%{http_code} %{redirect_url}\n" -b host.txt -X POST http://localhost:8787/questions/2/answer

303 http://localhost:8787/events/c1wWvvdHUcKW080CDwgf6A
303
204
204
303 http://localhost:8787/login
303 http://localhost:8787/events/c1wWvvdHUcKW080CDwgf6A

ocre sql runs a query on the local database:

ocre sql "SELECT id, event_id, body, votes, answered FROM questions"

id | event_id | body                      | votes | answered
---+----------+---------------------------+-------+---------
1  | 1        | Will there be pizza?      | 0     | 0
2  | 2        | Will there be pizza?      | 0     | 1
3  | 2        | When is the next release? | 1     | 0
(3 rows)

Question 1 is the one asked on the generated /questions page earlier. The second vote of the same browser changed nothing, and only the host’s request marked question 2 answered. In a browser, open the event’s link in two windows (one signed in as the host, one private window): a question asked in one appears in the other, and a vote moves it up on both.

Validate questions

A question needs at least 3 characters, and at most 280 so the room stays readable. In src/models/question.rs, NewQuestion::validate gets two rules:

impl NewQuestion {
    /// Checks that need no database; `create` adds uniqueness and references.
    pub fn validate(&self) -> Validator {
        let mut v = Validator::new();
        v.required("body", &self.body);
        v.min_length("body", &self.body, 3);
        v.max_length("body", &self.body, 280);
        v.safe_integer("votes", self.votes);
        v
    }
}

question::create runs it, so every way of creating a question gets the rules. ask turns the error into a 422 that shows the room again with the message above the form:

curl -s -c guest.txt -b guest.txt http://localhost:8787/events/$EVENT/questions -d 'body=hi' -w "%{http_code}\n" | grep -E "<li>Body|^4"

    <li>Body is too short (minimum is 3 characters)</li>
422

See Validations for every rule.

Test it

Request tests send HTTP requests to the app running in workerd, with a fresh local database. Replace the generated tests/events.rs and tests/questions.rs, which tested the CRUD pages, with tests of the room. tests/questions.rs, shortened to its helpers and two tests:

use ocre::testing::{Client, sequence, sql};

/// A signed-up host and the public id of their new event.
fn host_with_event() -> (Client, String) {
    let mut client = Client::new();
    // Unique across test files, which share the test database.
    let email = format!("host{}-{}@example.com", std::process::id(), sequence());
    client.post("/signup", &[("email", email.as_str()), ("password", "correct horse")]).assert_status(303);
    let created = client.post("/events", &[("name", "Q&A")]);
    let location = created.assert_status(303).location().unwrap_or_default().to_owned();
    (client, location.trim_start_matches("/events/").to_owned())
}

/// `client` asks `body` in the room `event`; returns the question's id.
fn ask(client: &mut Client, event: &str, body: &str) -> i64 {
    client.post(&format!("/events/{event}/questions"), &[("body", body)]).assert_redirect_to(&format!("/events/{event}"));
    let rows = sql(&format!("SELECT id FROM questions WHERE body = {}", ocre::testing::quote(body)));
    rows[0]["id"].as_i64().expect("the question is saved")
}

#[test]
#[ignore = "request test: run with `ocre test --e2e`"]
fn a_question_appears_live_in_every_room() {
    let (_, event) = host_with_event();
    let mut visitor = Client::new();
    ask(&mut visitor, &event, "Will there be pizza?");
    visitor.get(&format!("/events/{event}")).assert_contains("Will there be pizza?");
    let sent = visitor.broadcasts();
    let audience = sent.iter().rev().find(|b| b.channel == format!("event:{event}")).expect("sent to the room");
    assert!(audience.message.contains("Will there be pizza?"), "{}", audience.message);
    assert!(!audience.message.contains("Mark answered"), "no moderation for the audience");
    let host = sent.iter().rev().find(|b| b.channel == format!("host:{event}")).expect("sent to the host");
    assert!(host.message.contains("Mark answered"), "{}", host.message);
}

#[test]
#[ignore = "request test: run with `ocre test --e2e`"]
fn each_browser_votes_once_per_question() {
    let (_, event) = host_with_event();
    let mut first = Client::new().htmx();
    let id = ask(&mut first, &event, "Can we get the slides?");
    first.post(&format!("/questions/{id}/vote"), &()).assert_status(204);
    first.post(&format!("/questions/{id}/vote"), &()).assert_status(204);
    assert_eq!(votes(id), 1);
    Client::new().htmx().post(&format!("/questions/{id}/vote"), &()).assert_status(204);
    assert_eq!(votes(id), 2);
}

Each Client keeps its own cookies, like a browser; .htmx() adds the HX-Request header; broadcasts() returns what the app sent to its channels. The starter’s test files also check validation, ordering by votes, moderation rights, the host’s pages and that visitors need no account. Run them:

ocre test --e2e

The command checks the build for wasm32-unknown-unknown, migrates a separate test database, starts the app once and runs every test file (12 request tests here); cargo’s output ends with:

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.21s
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 4.77s

See Testing an Ocre app for unit tests, factories and browser tests.

List the routes

ocre routes reads the routes from src/lib.rs and the modules it merges, without building. A filter keeps the routes whose method, path or handler contains it; here, the app’s own routes without the auth pages:

ocre routes

METHOD  PATH                    HANDLER
GET     /                       home
GET     /events                 events::index
POST    /events                 events::create
GET     /events/new             events::new
GET     /events/{id}            events::show
POST    /events/{id}            events::update
POST    /events/{id}/delete     events::delete
GET     /events/{id}/edit       events::edit
POST    /events/{id}/questions  questions::ask
POST    /questions/{id}/answer  questions::answer
POST    /questions/{id}/delete  questions::delete
POST    /questions/{id}/vote    questions::vote
GET     /realtime/{channel}     realtime::connect
GET     /up                     up

The full list also has the account routes of ocre g auth (/signup, /login, /logout, /account, /passwords/..., /magic_link/..., /confirmations/..., /api/auth/...).

Deploy

Deploying needs a Cloudflare account (the free plan is enough) and a login of Cloudflare’s cf CLI. The commands in this section were not run for this page: the behavior below is described from the CLI’s code.

Log in

ocre login

If cf already has a login (or CLOUDFLARE_API_TOKEN is set), nothing opens. Otherwise it runs cf auth login, which opens the browser to approve access. The command then prints Logged in to Cloudflare as <email>. A login with several accounts needs accountId: "...", at the top of cloudflare.config.ts (ocre new --account-id writes it). cf also sends anonymous usage telemetry by default; npx cf cli telemetry disable turns it off.

Email in production

Sign-up, login and the room send no email and work without it. The magic-link and password-reset forms do: in production .dev.vars does not apply, and with MAIL_ADAPTER unset they answer 500 and the log names the fix. To turn them on, pick an adapter; on the free plan, Resend sends to any recipient (free: 100 emails a day, 3,000 a month, one domain, September 2026):

1. In cloudflare.config.ts, in worker.env, uncomment MAIL_ADAPTER: bindings.text("resend"), and set MAIL_FROM to an address on a domain verified in Resend, for example MAIL_FROM: bindings.text("Live Q&A <noreply@yourdomain.com>"),.
2. Store the API key as a secret: put RESEND_API_KEY=<key> in .prod.vars (git-ignored), then run ocre secrets push RESEND_API_KEY --file .prod.vars. A Worker must exist before it can have secrets, so run this after the first ocre deploy if the Worker is new.

See Email for the cloudflare adapter and Configuration for every variable.

ocre deploy

ocre deploy

In order, ocre deploy:

1. Checks the locale files (when the app has translations) and the wasm32-unknown-unknown target, as ocre dev does.
2. Looks up the D1 database named in cloudflare.config.ts (qa) with cf d1 list and creates it the first time.
3. Creates the other Cloudflare resources cloudflare.config.ts names that are missing: queues, R2 buckets, KV namespaces without an id. This app uses none of them; the Durable Object namespace of the realtime channels is created by the deploy itself, from the OcreChannel export.
4. Asks cf workers secrets list whether the Worker has SECRET_KEY_BASE. A new Worker has none, so a fresh random one is uploaded with the deploy and saved in .prod.vars. An existing secret is never replaced, since that would sign every user out.
5. Applies the pending migrations to the production database (cf d1 migrations apply), before the new code goes live.
6. Deploys with cf deploy --secrets-file, which builds the Worker in release mode (optimized for size, slower to compile than ocre dev) and uploads it. The secrets file (.wrangler/ocre-secrets.json, deleted afterwards) holds the new SECRET_KEY_BASE, or {}: it is passed on every deploy because cf keeps the Worker’s other secrets only when one is given.

cf’s own output is shown as it runs; the command then ends with:

Created the SECRET_KEY_BASE secret on Cloudflare
Saved it in .prod.vars (git-ignored): back it up, Cloudflare never gives it back

https://qa.<your-subdomain>.workers.dev

The first two lines appear only on the deploy that created the secret. With --json, the result is {"command": "deploy", "ok": true, "secret_created": true, "secret_saved": ".prod.vars", "url": "https://qa.<your-subdomain>.workers.dev"}. Run ocre deploy again after each change: every deploy migrates the database first, so the new code never runs against an old schema.

Free-plan limits that matter for this app (September 2026, Workers limits, Durable Objects pricing): 100,000 Worker requests a day and 10 ms of CPU per request, and 100,000 Durable Object requests a day. Each question, vote or moderation is one Worker request and two Durable Object requests (one per channel); each browser that opens a room adds one of each for its WebSocket, then costs nothing while it waits, since the channel’s object hibernates, and messages the server sends are free. A room of 300 people who each vote ten times uses about 3,300 Worker requests (plus page loads) and 6,300 Durable Object requests. Free-plan limits lists the rest.

Next steps

• Realtime: channels, broadcasts from jobs, presence, relaying client messages.
• Models and migrations: queries, associations, changing columns with ocre g migration.
• Authentication: CurrentUser, ownership checks, OAuth, JWTs and API keys.
• Controllers and routing, Views, helpers and forms and htmx: handlers, templates, partial updates with htmx.
• Background jobs and schedules: send a summary to the host after the event, clean up old events every night.
• Deployment: environments, secrets, custom domains.
• CLI commands and Generators: every command and flag.

Models and migrations

A model is a generated Rust file, src/models/<model>.rs, that holds every query and rule about one D1 table, and migrations are numbered SQL files that create and change those tables. This page explains the generated model section by section (queries, callbacks, associations, enums), the ocre::Query builder, transactions, how to change the schema and undo a change, encrypted columns, several databases, and what is not supported.

Before you start

• An Ocre app created with ocre new (see Installation). The examples use the blog starter (ocre new blog --starter blog), whose Post model has title:string body:text published:boolean.
• ocre dev or ocre migrate applies migrations to the local database; nothing here needs a Cloudflare account until you add --remote.
• Free plan (September 2026, D1 pricing): 5 million rows read and 100,000 rows written a day, 5 GB of storage in total; D1 limits: 500 MB per database, 50 queries per Worker invocation, 100 bound parameters per query. Rows read counts every row a query scans, not only those it returns.

Generate a model

ocre g model <Model> field:type... writes the migration that creates the table and the model file, and registers the module in src/models/mod.rs:

ocre g model Author name:string^ bio:text?

  create  migrations/0002_create_authors.sql
  create  src/models/author.rs
  update  src/models/mod.rs

Next:
  ocre migrate
  cargo check --target wasm32-unknown-unknown

Field types are string, text, rich_text, integer, float, decimal, boolean, date, time, datetime, uuid, references, attachment, json and enum:<value>,<value>...; the suffix ? makes a field optional (NULL allowed) and ^ unique, and a lock_version:integer field turns on optimistic locking; public_id:token gives each row a random id that the generated pages and APIs use in URLs instead of the integer id (see Field types). Field types lists the SQL and Rust type of each. ocre g scaffold and ocre g api create the model the same way when it does not exist yet (see Generators). The suffixes change what a references field generates (see Associations): author:references? is an optional parent (ON DELETE SET NULL), user:references^ a one-to-one link (has one).

The migration:

CREATE TABLE authors (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    bio TEXT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE UNIQUE INDEX index_authors_on_name ON authors (name);

Every table gets id, created_at and updated_at (UTC text such as 2026-09-29 04:36:41). Apply it with ocre migrate (or just run ocre dev, which migrates first).

The model file, section by section

src/models/author.rs is plain Rust you own: read it, change it, add to it. Controllers (HTML pages, JSON API, GraphQL resolvers) call its functions instead of writing SQL, so a rule written here applies everywhere.

The record struct

/// A row of the `authors` table.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Author {
    pub id: i64,
    pub name: String,
    pub bio: Option<String>,
    pub created_at: String,
    pub updated_at: String,
}

One field per column, deserialized from D1 rows by column name. Optional fields are Option. Booleans need a helper, because SQLite stores them as INTEGER 0/1; the blog starter’s Post has:

    #[serde(deserialize_with = "ocre::bool_from_sql")]
    pub published: bool,

JSON columns use ocre::json_from_sql (ocre::optional_json_from_sql for optional ones) the same way.

New and Changes

/// Values for a new author.
#[derive(Debug, Clone, Deserialize)]
pub struct NewAuthor {
    pub name: String,
    #[serde(default, deserialize_with = "ocre::optional")]
    pub bio: Option<String>,
}

/// Changes to a author: absent fields keep their value; for optional fields
/// `Some(None)` clears it.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct AuthorChanges {
    pub name: Option<String>,
    #[serde(default, deserialize_with = "ocre::patch")]
    pub bio: Option<Option<String>>,
}

NewAuthor is the input of create: every required field, optional fields as Option. AuthorChanges is the input of update: every field is Option, and None keeps the stored value. Optional columns are Option<Option<T>>: None keeps, Some(None) clears, Some(Some(value)) sets. Both structs deserialize from JSON bodies, so the JSON API takes them directly; ocre::optional and ocre::patch also treat an empty string as “no value”, which is what HTML forms send (see JSON APIs).

AuthorChanges::changed() lists the fields a change sets (["name"]), Rails’ changed and *_changed?: a before_update callback can act only when a field changes (if changes.changed().contains(&"email") { ... }). The previous values are one find(ctx, id) away when a callback needs them (*_was). There is no other dirty tracking: records are plain values, and nothing saves them behind your back.

validate()

impl NewAuthor {
    /// Checks that need no database; `create` adds uniqueness and references.
    pub fn validate(&self) -> Validator {
        let mut v = Validator::new();
        v.required("name", &self.name);
        v
    }
}

validate() returns an ocre::Validator holding every failed check, without touching the database. Generated rules: required for non-optional string/text, format checks for date, time, datetime, decimal and uuid, safe_integer for integers, file rules for attachments. AuthorChanges::validate() checks only the fields being changed. Add your own rules here; Validations lists every check.

Queries

all, count, find and find_many are one line each on top of query():

pub fn query() -> Query<Author> {
    Query::table("authors")
}

pub async fn find(ctx: &Ctx, id: i64) -> Result<Option<Author>> {
    query().eq("id", id).first(&ctx.db()?).await
}

page is an ocre::Page (limit 1 to 100, default 50; offset from 0); handlers get it from ?limit=&offset=, other code builds one with Page::new(limit, offset)?. Every function returns ocre::Result, so handlers use ?. Missing records are None/false, not errors: the handler decides, usually with .or_404()?.

create and update add the checks that need the database to the validate() errors, then fail with all of them at once:

pub async fn create(ctx: &Ctx, mut new: NewAuthor) -> Result<Author> {
    before_create(ctx, &mut new).await?;
    let db = ctx.db()?;
    let mut v = new.validate();
    {
        let name = &new.name;
        v.check("name", db.exists("SELECT 1 FROM authors WHERE name = ?1 LIMIT 1", params![name]).await?, "has already been taken");
    }
    v.finish()?;
    let record: Author = db
        .first("INSERT INTO authors (name, bio) VALUES (?1, ?2) RETURNING *", params![new.name, new.bio])
        .await?
        .ok_or_else(|| Error::internal("INSERT ... RETURNING returned no row"))?;
    after_create(ctx, &record).await?;
    Ok(record)
}

A unique field (^) gets the “has already been taken” check (in update, AND id != ?2 excludes the record itself); a references field gets “must exist”. The UNIQUE index and the REFERENCES constraint in the migration stay as the last line of defense.

update writes only the fields that are Some, with one CASE WHEN per column, and refreshes updated_at:

    let updated: Option<Author> = db
        .first(
            "UPDATE authors SET name = CASE WHEN ?1 THEN ?2 ELSE name END, bio = CASE WHEN ?3 THEN ?4 ELSE bio END, updated_at = datetime('now') WHERE id = ?5 RETURNING *",
            params![changes.name.is_some(), changes.name, changes.bio.is_some(), changes.bio.flatten(), id],
        )
        .await?;

Callbacks

The end of every model file holds six private functions that create, update and delete call, like Rails’ callbacks. They do nothing until you fill them in:

Every controller, JSON API and GraphQL resolver goes through create/update/delete, so a callback runs for all of them. An Err returned by a before_* callback stops the operation before anything is written; for example, keeping authors that still have tasks (Task from ocre g model Task title:string status:enum:open,done author:references?):

/// Before the DELETE of the author `id`: return an error to keep it.
async fn before_delete(ctx: &Ctx, id: i64) -> Result<()> {
    let has_tasks = crate::models::task::query().eq("author_id", id).exists(&ctx.db()?).await?;
    let mut v = Validator::new();
    v.check("tasks", has_tasks, "must be deleted first");
    v.finish()
}

delete then answers Error::Invalid (422, “Tasks must be deleted first”) and the author stays. The HTML scaffold shows it on the error page; JSON clients get it in fields.

An Err from an after_* callback is returned to the caller, but the write it follows is already done: D1 keeps no transaction open between two queries. Writes that must succeed or fail together go into one db.batch. Bulk operations (update_all, delete_all, hand-written SQL) and ON DELETE CASCADE run no callback.

The rest of Rails’ callback API maps to plain code in these functions:

Associations

A references field connects two models. With the blog starter:

ocre g scaffold Comment author:string body:text post:references

The migration adds post_id INTEGER NOT NULL REFERENCES posts(id) ON DELETE CASCADE and an index on post_id. Deleting a post deletes its comments in the database (attached files of cascaded rows are not deleted from R2; see File storage). The generator writes both sides:

// src/models/comment.rs: belongs to
impl Comment {
    /// The post this comment belongs to.
    pub async fn post(&self, ctx: &Ctx) -> Result<Option<crate::models::post::Post>> {
        crate::models::post::find(ctx, self.post_id).await
    }

    // ocre:associations
}

// src/models/post.rs: has many, added under the `// ocre:associations` marker
impl Post {
    // ocre:associations
    /// Comments of this post, newest first.
    pub async fn comments(&self, ctx: &Ctx, page: Page) -> Result<Vec<crate::models::comment::Comment>> {
        ctx.db()?
            .all(
                "SELECT * FROM comments WHERE post_id = ?1 ORDER BY id DESC LIMIT ?2 OFFSET ?3",
                params![self.id, page.limit, page.offset],
            )
            .await
    }
}

In a handler: let comments = post.comments(&ctx, page).await?; and let post = comment.post(&ctx).await?;. Keep the // ocre:associations and // ocre:models markers: later generators insert code after them.

The suffixes and the shape of the model choose the kind of association:

With Tagging from the command above, the blog starter’s Post gets:

    /// Tags of this post, through taggings, most recently linked first.
    pub async fn tags(&self, ctx: &Ctx, page: ocre::Page) -> Result<Vec<crate::models::tag::Tag>> {
        ctx.db()?
            .all(
                "SELECT tags.* FROM tags JOIN taggings ON taggings.tag_id = tags.id WHERE taggings.post_id = ?1 ORDER BY taggings.id DESC LIMIT ?2 OFFSET ?3",
                params![self.id, page.limit, page.offset],
            )
            .await
    }

Tag a post with tagging::create(&ctx, NewTagging { post_id, tag_id }).await? and untag it with tagging::query().eq("post_id", post_id).eq("tag_id", tag_id).delete_all(&ctx.db()?).await?.

Each references field also writes two eager-loading functions in the model that holds it, to load the association of a whole list in one query per 100 ids (see Avoid N+1 queries):

Association options, the Ocre way

Rails configures associations with options; in Ocre each one is a line of code in the model, where you can read it:

A counter cache and touch, in the child model (src/models/comment.rs, with comments_count added to posts by ocre g migration add_comments_count_to_posts comments_count:integer):

/// After the INSERT: count the comment on its post and touch the post.
async fn after_create(ctx: &Ctx, comment: &Comment) -> Result<()> {
    let sql = "UPDATE posts SET comments_count = comments_count + 1, updated_at = datetime('now') WHERE id = ?1";
    ctx.db()?.execute(sql, params![comment.post_id]).await?;
    Ok(())
}

/// After the DELETE, with the deleted row.
async fn after_delete(ctx: &Ctx, comment: &Comment) -> Result<()> {
    let sql = "UPDATE posts SET comments_count = comments_count - 1, updated_at = datetime('now') WHERE id = ?1";
    ctx.db()?.execute(sql, params![comment.post_id]).await?;
    Ok(())
}

Each callback costs one row written. Bulk deletes (delete_all, ON DELETE CASCADE) skip it: recount with UPDATE posts SET comments_count = (SELECT COUNT(*) FROM comments WHERE comments.post_id = posts.id) when you use them.

Polymorphic references

A record that may belong to one of several models (Rails’ belongs_to :commentable, polymorphic: true) takes a polymorphic field listing them:

ocre g scaffold Comment body:text commentable:polymorphic:post,photo

It becomes two fields: commentable_type, an enum of the models’ singular names (CommentableType::Post, stored as 'post'), and commentable_id, an integer, with an index on the pair. SQLite cannot declare a foreign key to two tables, so create (and update, when a change sets both) checks that the record exists: Commentable must exist otherwise. The model gets an enum of the records and an accessor:

// src/models/comment.rs
pub enum Commentable {
    Post(crate::models::post::Post),
    Photo(crate::models::photo::Photo),
}

let parent = comment.commentable(&ctx).await?; // Option<Commentable>: None once the record is deleted
match parent {
    Some(Commentable::Post(post)) => { /* ... */ }
    Some(Commentable::Photo(photo)) => { /* ... */ }
    None => {}
}

Each listed model gets the has-many side, post.comments(ctx, page) (a query on commentable_type = 'post'). Add ? for an optional reference (commentable:polymorphic:post,photo?). Deleting a post does not delete its comments (there is no foreign key): delete them in the post’s before_delete. The models must exist before the field names them; a model may list itself (subject:polymorphic:note,post? on Note).

Enum fields

status:enum:open,done stores one of a fixed list of values. The migration keeps the text and refuses anything else:

    status TEXT NOT NULL CHECK (status IN ('open', 'done')),

and the model gets a Rust enum named after the field, used in the row, New and Changes structs:

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize, Serialize)]
pub enum Status {
    #[default]
    #[serde(rename = "open")]
    Open,
    #[serde(rename = "done")]
    Done,
}

Status::ALL lists the values in order (for select boxes), as_str() and Display give the stored text, FromStr parses it, and IntoParam binds it, so task::query().eq("status", Status::Done) is the scope Rails generates as Task.done. The first value is the Default. JSON bodies send the text ("status": "done"); an unknown value fails deserialization with a 400. HTML scaffold forms parse the text with v.one_of("status", &form.status), which adds “is not included in the list” (see Validations). Values must be distinct snake_case words; an enum cannot be unique (^), and --graphql does not support enum fields yet.

Adding a value later means changing the CHECK, which SQLite cannot alter: add the variant, then rebuild the table with ocre g migration rebuild_tasks (see Generate a migration).

Rich text fields

body:rich_text is Action Text without its extra table: formatted text (bold, links, headings, lists, quotes, code) typed in the Trix editor, the one Rails uses, and kept as HTML in a TEXT column of the record.

ocre g scaffold Article title:string body:rich_text

• Stored safe. create and update run the HTML through ocre::security::sanitize before writing it: scripts, styles, event handlers and javascript: links are gone before the row exists, whatever the client sent (the JSON API included).
• Validated on its text. A required rich text field checks v.required("body", &ocre::security::strip_tags(body)), so an empty editor (<div><br></div>) is “can’t be blank”.
• Forms. The scaffold’s _form.html loads Trix 2.1.19 from unpkg.com (allowed by the generated Content-Security-Policy: script-src and style-src list https://unpkg.com) and renders <input type="hidden" id="article_body" name="body"><trix-editor input="article_body"></trix-editor>; the editor fills the hidden input, which the form submits like any field. The toolbar’s file button is hidden: files belong in an attachment field.
• Rendering. {{ article.body|rich_text }} prints the HTML (sanitized again on the way out, a few microseconds of CPU); {{ article.body|plain_text|truncate(80) }} prints its text, as the index page does (Rails’ to_plain_text). Both filters come from ocre::filters (use ocre::filters; in the controller, which the scaffold writes).
• Style. Trix’s stylesheet styles the editor; style the rendered HTML with your own CSS (dd div, .content h1…), the equivalent of Rails’ action_text/contents/_content partial.

Apps created before rich_text existed need "https://unpkg.com" added to style_src in content_security_policy() (src/lib.rs), or the editor shows without its styles.

Migrations

Migrations live in migrations/, named NNNN_<name>.sql (four digits, one more than the highest existing number). ocre migrate applies them in file-name order and records each applied name in the d1_migrations table:

ocre sql "SELECT id, name FROM d1_migrations"

id | name
---+---------------------------
1  | 0001_create_posts.sql
2  | 0002_create_authors.sql
3  | 0003_create_comments.sql
4  | 0004_add_slug_to_posts.sql
5  | 0005_create_products.sql
(5 rows)

A migration runs once per database. Editing an applied file changes nothing where it already ran (its name is recorded) but changes what a new database gets, so local and production schemas drift. Never edit an applied migration; write a new one.

Generate a migration

ocre g migration <name> [arguments...] infers the SQL from the name, as Rails does. The first names take fields (name:type), the others column names or nothing:

Index, rename and drop migrations need no schema file:

ocre g migration add_index_to_posts published created_at
ocre g migration rename_body_to_content_in_posts

-- Migration: add_index_to_posts
-- Applied once, in file-name order. Never edit a migration after it has been applied.
CREATE INDEX index_posts_on_published_and_created_at ON posts (published, created_at);

-- Migration: rename_body_to_content_in_posts
-- Applied once, in file-name order. Never edit a migration after it has been applied.
ALTER TABLE posts RENAME COLUMN body TO content;

Renames, drops and rebuilds end with the “update the model in src/models/ to match the new columns” step: the struct fields and the SQL of the model still use the old names. A renamed table keeps its index names (index_tags_on_label on labels), so remove_index_from_labels label would not find it; drop it by its real name in a hand-written migration. add_index_to_posts without columns fails with hint: list them in index order, without types, e.g. `ocre g migration add_index_to_posts author_id created_at` .

ocre g migration add_slug_to_posts slug:string?

  create  migrations/0004_add_slug_to_posts.sql

Next:
  ocre migrate
  update the model in src/models/ to match the new columns

-- Migration: add_slug_to_posts
-- Applied once, in file-name order. Never edit a migration after it has been applied.
ALTER TABLE posts ADD COLUMN slug TEXT;

Existing rows need a value for a new column. Optional columns get NULL; required ones get a default ('' for text, dates and times, 0 for numbers, '{}' for JSON, 0 for booleans, the first value for an enum). References and attachments added to an existing table must be optional:

ocre g migration add_author_to_posts author:references

error: `author_id` must be optional when added to an existing table
hint: SQLite adds reference columns as NULL for existing rows: use `name:references?`

A required unique column (slug:string^) fails on a table with two rows or more: every row gets the default '', and the unique index refuses the duplicates (UNIQUE constraint failed). Add it as slug:string?^ (a unique index allows many NULLs), fill it, then enforce presence in validate().

Other names give an empty migration, with only the two comment lines; write the SQL yourself:

ocre g migration backfill_slugs

-- Migration: backfill_slugs
-- Applied once, in file-name order. Never edit a migration after it has been applied.
UPDATE posts SET slug = lower(replace(title, ' ', '-')) WHERE slug IS NULL;

A name the generator cannot read with fields is refused:

error: cannot tell which table `fix_things` changes
hint: name it `create_<table>`, `add_<columns>_to_<table>` or `remove_<columns>_from_<table>`

Apply migrations

Check what is pending, then apply it. Here after ocre g migration add_views_to_posts views:integer:

ocre migrate --status

 ⛅️ wrangler 4.143.0
────────────────────
Resource location: local
...
Migrations to be applied:
┌─────────────────────────────┐
│ Name                        │
├─────────────────────────────┤
│ 0006_add_views_to_posts.sql │
└─────────────────────────────┘

Next:
  ocre migrate

With --json, the pending names are in pending:

ocre migrate --status --json

{"command":"migrate","next":["ocre migrate"],"ok":true,"pending":["0006_add_views_to_posts.sql"]}

ocre migrate runs the app’s wrangler on the local database (wrangler d1 migrations apply DB --local, see Why wrangler still appears) and shows its output:

ocre migrate

...
? About to apply 1 migration(s)
Your database may not be available to serve requests during the migration, continue?
🤖 Using fallback value in non-interactive context: yes
🌀 Executing on local database blog (DB) from .wrangler/state/v3/d1:
🌀 To execute on your remote database, add a --remote flag to your wrangler command.
🚣 2 commands executed successfully.
┌─────────────────────────────┬────────┐
│ name                        │ status │
├─────────────────────────────┼────────┤
│ 0006_add_views_to_posts.sql │ ✅     │
└─────────────────────────────┴────────┘

Each migration file runs as one unit: when a statement fails, none of the file’s statements stay applied and the migration stays pending. For a file whose second statement inserts into a missing table:

✘ [ERROR] no such table: nope_table: SQLITE_ERROR
...
error: `wrangler d1 migrations apply DB --local` failed (exit status: 1)
hint: read the wrangler output above; the first error line names the cause

Fix the file (it was never applied) and run ocre migrate again. Add --remote to either command for the production database on Cloudflare. ocre deploy applies remote migrations itself (see Deployment), and ocre dev applies local ones before starting.

The schema file

ocre db schema writes the database’s current CREATE statements to db/schema.sql (Rails’ structure.sql), read from sqlite_master; --remote dumps the production database instead:

ocre migrate && ocre db schema

  create  db/schema.sql

-- Schema of the local D1 database, written by `ocre db schema` from sqlite_master.
-- A snapshot for reading: migrations/ are the source of truth. Run `ocre db schema` again after `ocre migrate`.

CREATE TABLE authors (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    bio TEXT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE UNIQUE INDEX index_authors_on_name ON authors (name);
...

It is the quickest way for a person or an agent to see every table at once. Nothing loads it: a new database is always built by replaying migrations/ (Rails’ schema.rb/structure.sql in one SQL format). Commit it if you want schema changes visible in code review, and regenerate it after each ocre migrate.

Column options, constraints and comments

Migrations are SQL, so Rails’ column modifiers and table options are SQLite syntax in the file (edit a generated migration before applying it, or write one with a name the generator does not read):

Change a column: rebuild the table

SQLite’s ALTER TABLE can add, drop and rename columns, but not change a column’s type, NOT NULL, DEFAULT, CHECK or REFERENCES. For those, SQLite’s documented answer is to rebuild the table. ocre g migration rebuild_<table> writes that migration from the table’s definition in db/schema.sql (run ocre db schema first):

ocre g migration rebuild_authors

-- Migration: rebuild_authors
-- Applied once, in file-name order. Never edit a migration after it has been applied.
-- Rebuilds `authors` to change what ALTER TABLE cannot (a column's type, NOT NULL,
-- DEFAULT, CHECK or REFERENCES): edit the CREATE TABLE below, and keep both
-- column lists of the INSERT in step with it.
PRAGMA defer_foreign_keys = true;
CREATE TABLE authors_new (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    bio TEXT,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);
INSERT INTO authors_new (id, name, bio, created_at, updated_at) SELECT id, name, bio, created_at, updated_at FROM authors;
DROP TABLE authors;
ALTER TABLE authors_new RENAME TO authors;
CREATE UNIQUE INDEX index_authors_on_name ON authors (name);
PRAGMA defer_foreign_keys = false;

Edit the CREATE TABLE authors_new (for example bio TEXT NOT NULL DEFAULT '', or a new value in an enum’s CHECK), keep the two column lists of the INSERT in step, then ocre migrate. D1 applies the file as one unit, so a failed copy (a row that breaks the new NOT NULL) leaves the old table untouched. Test it on the local database with real-looking data before --remote.

A table that other tables reference cannot be rebuilt this way: dropping it would run their ON DELETE CASCADE or SET NULL, because D1 enforces foreign keys. The generator refuses:

error: `comments` references `posts`: rebuilding it would delete or clear their rows
hint: D1 enforces foreign keys, so dropping `posts` runs ON DELETE on `comments`; add a new column and backfill it instead

Without db/schema.sql it answers hint: run `ocre migrate` then `ocre db schema`: the rebuild copies the table's current definition.

Undo a migration

D1 migrations only go forward: D1 (and cf) have d1 migrations apply and list, and no command that runs a migration backwards, so Ocre has no down migrations, no rollback and no redo. Undo a change the way it was made, with a new migration:

Locally, when the migration was never deployed, the shortcut is to fix the file and start over: ocre db reset deletes the local database, applies every migration and loads the seeds.

In production, when a migration or a bad UPDATE/DELETE destroyed data, D1 Time Travel restores the whole database to any minute of the last 7 days on the Workers Free plan (30 days on Workers Paid), at no cost and without any setup:

npx cf d1 list --name <database_name>                                   # its uuid
npx cf d1 time-travel get-bookmark <uuid> --timestamp 2026-09-29T10:00:00+00:00
npx cf d1 time-travel restore <uuid> --timestamp 2026-09-29T10:00:00+00:00

A restore overwrites everything written since that minute, including the d1_migrations rows: the migrations applied after it become pending again. Delete or fix those files before the next ocre deploy, which would apply them again. Note the current bookmark (get-bookmark without --timestamp) first, to go back to if the restore itself was a mistake (restore <uuid> --bookmark <it>). <database_name> is the name of the DB binding in cloudflare.config.ts; these commands act on the remote database only.

Data migrations

Keep schema changes and data changes apart (Rails’ maintenance-task advice):

• A small, one-off fix of existing rows (a backfill with a single UPDATE ... SET slug = lower(replace(title, ' ', '-'))) can be its own migration: ocre g migration backfill_slugs writes an empty numbered file for the SQL. It runs once, locally and on ocre deploy, in order with the schema changes.
• A change that needs Rust (computing values, calling an API) or touches many rows is a job: it processes a batch per run within the CPU limit and enqueues itself with a cursor for the rest (see Background jobs), started once with ocre schedules run or from an admin route. It can run again safely if it skips rows already done.
• Change the code to accept both shapes before the data moves, and remove the old shape in a later deploy.

Seeds, reset and ad-hoc SQL

ocre db seed runs db/seeds.sql (you create it; ocre new does not):

-- db/seeds.sql
INSERT INTO posts (title, body, published) VALUES ('Hello', 'First post', 1);
INSERT INTO posts (title, body, published) VALUES ('Draft', 'Not yet', 0);
INSERT INTO authors (name, bio) VALUES ('Ada', 'Mathematician');

ocre db seed            # local; --remote for production
ocre db reset           # local only: delete .wrangler/state/v3/d1, apply every migration, load db/fixtures and db/seeds.sql
ocre sql "SELECT id, title, published, slug FROM posts"

id | title | published | slug
---+-------+-----------+-----
1  | Hello | 1         | NULL
2  | Draft | 0         | NULL
(2 rows)

ocre sql accepts several statements separated by ;, runs on the local database unless --remote, and with --json returns D1’s results in rows:

{"command":"sql","ok":true,"rows":[{"meta":{"duration":1},"results":[{"id":1,"title":"Hello"}],"success":true}]}

Seeds run every time you call ocre db seed: write them so a second run does no harm (INSERT OR IGNORE, or run them after ocre db reset). Queries from the CLI count toward the D1 quotas like any other. See CLI commands for every flag.

The other database commands: ocre db create (--remote creates the D1 database on Cloudflare when missing), ocre db version (the last applied migration; --remote too), and, on the local database only, ocre db drop, ocre db truncate (empties every app table, keeps the schema and d1_migrations), ocre db seed --replant (truncate, then seed; Loco’s seed --reset) and ocre db prepare (applies pending migrations, and seeds a database it just created; safe to run any time). See CLI commands.

Fixtures

Fixtures are Rails-style named rows, one YAML (or JSON) file per table in db/fixtures/ (Loco’s src/fixtures). ocre db seed loads them first, then runs db/seeds.sql; either may be missing. ocre db reset and a fresh ocre db prepare load both too.

# db/fixtures/authors.yml
ada:
  name: Ada
  bio: Mathematician

# db/fixtures/posts.yml
DEFAULTS: &defaults       # never inserted: values shared with `<<: *defaults`
  published: true
hello:
  <<: *defaults
  title: Hello from $LABEL # $LABEL is the row's label: "Hello from hello"
  author: ada              # author_id = the id of the row labelled `ada`
draft:
  <<: *defaults
  id: 42                   # explicit id
  title: Draft
  published: false
  tags: [rust, d1]         # sequences and mappings are stored as JSON text

Each file’s table is emptied first (DELETE FROM, foreign keys deferred), then gets one INSERT per row, so loading twice gives the same rows. A row without id gets Rails’ stable id for its label (crc32(label) % (2^30 - 1)), so author: ada works without knowing ada’s id. author: ada becomes author_id when the word author_id appears in migrations/*.sql; the label is looked up in the authors fixtures first, else in the only file that defines it. --from <dir> loads another directory, e.g. ocre db seed --from test/fixtures.

Fixtures load into the local database only: they replace table rows, and Ocre never deletes production data. ocre db seed --remote refuses when there are fixtures to load; put production data in db/seeds.sql.

ocre db dump writes the other way: each app table (or --tables posts,authors) to db/fixtures/<table>.yml, one row per label <table>_<id> with its explicit id, readable by ocre db seed. It never overwrites a file without --force; --dir <dir> writes elsewhere, --remote reads the production database (one SELECT * per table, a D1 row read per row). BLOB columns come back as JSON arrays of bytes, loaded as text.

Static data

Read-only data that never changes at runtime (countries, plans, a price list; Loco’s data/ loaders) belongs in the binary, not in D1: include_str!("../data/countries.json") compiles the file in, and a LazyLock parses it once per Worker instance. Reading it costs no D1 row and no request; the file adds its size to the WebAssembly binary (3 MB compressed on the free plan), and changing it is a deploy.

// src/models/countries.rs
use std::sync::LazyLock;

use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct Country {
    pub code: String,
    pub name: String,
}

/// In an app: `include_str!("../../data/countries.json")`.
const COUNTRIES_JSON: &str = r#"[{"code": "FR", "name": "France"}, {"code": "JP", "name": "Japan"}]"#;

/// Parsed on first use, then shared by every request of this Worker instance.
static COUNTRIES: LazyLock<Vec<Country>> =
    LazyLock::new(|| ocre::serde_json::from_str(COUNTRIES_JSON).expect("data/countries.json is valid"));

pub fn country(code: &str) -> Option<&'static Country> {
    COUNTRIES.iter().find(|country| country.code == code)
}

Data migrations

Migrations change the schema; changing existing rows (backfilling a new column, splitting a name) is a data migration. A single UPDATE ... WHERE ... in the SQL migration is fine for small tables. For large ones, write a job that walks the table with query().batches(..) a few batches per run and enqueues itself with the last id until next returns None: each run stays within the 50 queries and 10 ms of CPU of a free-plan invocation, and D1 never runs one statement over millions of rows.

Update the model after a migration

A migration changes the table, not the Rust code. After add_slug_to_posts slug:string?, change src/models/post.rs in five places (the generator’s “Next” line reminds you):

// 1. The record struct: one field per column.
pub struct Post {
    // ...
    pub slug: Option<String>,
}

// 2. NewPost: optional input.
pub struct NewPost {
    // ...
    #[serde(default, deserialize_with = "ocre::optional")]
    pub slug: Option<String>,
}

// 3. PostChanges: keep / clear / set.
pub struct PostChanges {
    // ...
    #[serde(default, deserialize_with = "ocre::patch")]
    pub slug: Option<Option<String>>,
}

// 4. create: the column and its placeholder.
    db.first(
        "INSERT INTO posts (title, body, published, slug) VALUES (?1, ?2, ?3, ?4) RETURNING *",
        params![new.title, new.body, new.published, new.slug],
    )

// 5. update: one CASE WHEN per column, placeholders renumbered.
    db.first(
        "UPDATE posts SET title = CASE WHEN ?1 THEN ?2 ELSE title END, body = CASE WHEN ?3 THEN ?4 ELSE body END, published = CASE WHEN ?5 THEN ?6 ELSE published END, slug = CASE WHEN ?7 THEN ?8 ELSE slug END, updated_at = datetime('now') WHERE id = ?9 RETURNING *",
        params![changes.title.is_some(), changes.title, changes.body.is_some(), changes.body, changes.published.is_some(), changes.published, changes.slug.is_some(), changes.slug.flatten(), id],
    )

Add rules for the new field to both validate() functions if it needs any. Then fix what the compiler reports in the controllers: the HTML scaffold’s PostForm in src/posts.rs (a slug: String field, from_record, to_new, to_changes) and templates/posts/_form.html; a GraphQL node and input in src/<plural>_api.rs. Check with:

cargo check --target wasm32-unknown-unknown

A removed column goes the other way: delete the field from the three structs, the SQL and the forms. SELECT * keeps working as long as the struct has no field the table lacks (serde ignores extra columns).

The query builder

ocre::Query<T> builds one SELECT on one table, step by step, and runs it on D1. Every model’s query() starts one with the row type set (post::query() is Query::<Post>::table("posts")), so terminal methods return Posts. It is a thin layer over SQL, not an ORM: each method adds one clause, nothing runs until a terminal method, and the SQL it sends is predictable.

Two rules keep it safe from SQL injection:

• Values (eq, is_in, contains…) are always bound parameters, never written into the SQL.
• Column names and SQL fragments are &'static str: they come from your code, not from a request. To sort by a column the visitor picks, match their input onto a fixed name, as below.

Scopes and a search

Scopes are plain functions taking and returning a Query; scope(f) applies one, and they take arguments like any function. Put them in the model file, below query():

// src/models/post.rs, below query() (shown as a module of its own)
use ocre::{Ctx, Direction, Page, Paginated, Query, Result};

use crate::models::post::{self, Post};

/// Published posts only.
pub fn published(query: Query<Post>) -> Query<Post> {
    query.eq("published", true)
}

/// Titles containing `term`; `%` and `_` in it match literally.
pub fn titled(query: Query<Post>, term: &str) -> Query<Post> {
    query.contains("title", term)
}

/// A page of published posts, optionally filtered, sorted by a column the
/// visitor picks from a fixed list.
pub async fn search(ctx: &Ctx, term: Option<&str>, sort: &str, direction: Direction, page: Page) -> Result<Paginated<Post>> {
    let mut query = post::query().scope(published);
    if let Some(term) = term {
        query = query.scope(|q| titled(q, term));
    }
    // The column comes from this match, never from the request.
    let column = match sort {
        "title" => "title",
        _ => "created_at",
    };
    query.order_by(column, direction).order_desc("id").paginate(&ctx.db()?, page).await
}

search(&ctx, Some("50% off"), "title", Direction::Desc, page) with ?limit=20 sends two queries, the rows and the total:

SELECT * FROM posts WHERE published = ?1 AND title LIKE ?2 ESCAPE '\' ORDER BY title DESC, id DESC LIMIT ?3 OFFSET ?4
-- params: 1, '%50\% off%', 20, 0
SELECT COUNT(*) AS count FROM posts WHERE published = ?1 AND title LIKE ?2 ESCAPE '\'

contains escapes %, _ and \ with ocre::escape_like (Rails’ sanitize_sql_like); use escape_like yourself in hand-written LIKE SQL.

ocre::Paginated<T> serializes as {"items": [...], "total": 42, "limit": 20, "offset": 0} and has current_page(), total_pages(), has_next(), has_previous(), next_page(), previous_page() (each an Option<Page>) and map(f) to turn rows into view structs. The total costs a second query that reads every matching row: on a large table, prefer all with page.next(rows.len()) links (see Controllers).

ocre::Direction deserializes from asc or desc (any case; asc by default), so a handler takes it straight from the query string:

// src/post_search.rs
use axum::{
    Router,
    extract::{Query, State},
    routing::get,
};
use ocre::{ApiResult, Ctx, Direction, Json, Page, Paginated};
use serde::Deserialize;

use crate::models::post::{self, Post};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/api/posts/search", get(search))
}

#[derive(Deserialize)]
pub struct Search {
    #[serde(default)]
    pub q: String,
    #[serde(default)]
    pub sort: String,
    #[serde(default)]
    pub direction: Direction,
}

/// `GET /api/posts/search?q=rust&sort=title&direction=desc&limit=20`
async fn search(State(ctx): State<Ctx>, page: Page, Query(search): Query<Search>) -> ApiResult<Json<Paginated<Post>>> {
    let mut query = post::query().eq("published", true);
    let term = search.q.trim();
    if !term.is_empty() {
        query = query.any(|q| q.contains("title", term).contains("body", term));
    }
    let column = if search.sort == "title" { "title" } else { "created_at" };
    Ok(Json(query.order_by(column, search.direction).paginate(&ctx.db()?, page).await?))
}

(axum::extract::Query reads the query string; ocre::Query is the builder. Import only one of them under that name.)

Conditions

Conditions combine with AND, in the order they are added. The column argument may be qualified (comments.author) after a join.

The builder numbers every placeholder ?1, ?2... in the final SQL, including those of where_sql and having, so fragments mix freely with the other methods:

post::query()
    .any(|q| q.is_null("slug").eq("slug", ""))
    .not(|q| q.eq("published", false))
    .where_sql("created_at >= datetime('now', ?)", params!["-7 days"])
// SELECT * FROM posts WHERE (slug IS NULL OR slug = ?1) AND NOT (published = ?2) AND (created_at >= datetime('now', ?3))

Order, limits, columns, joins, groups

Running a query

Terminal methods take &Db (&ctx.db()?, or &ctx.db_named("...")? for another database) and return ocre::Result:

update_all and delete_all ignore joins, order and limits, skip validations and callbacks, do not touch updated_at unless you list it, and, without any condition, change every row of the table. delete_all leaves the R2 files of attachment columns in place.

For batches and custom calls, to_statement(), count_statement(), exists_statement(), value_statement(expr), aggregate_statement(expr), update_statement(sets), delete_statement() and explain_statement() return the ocre::Statement (SQL plus parameters) without running it: put several in one transaction, or check the SQL in a unit test.

batches pages by id (keyset pagination), so the hundredth batch costs the same as the first, unlike OFFSET. A Worker invocation may run 50 queries on the free plan: walk a large table from a job or a scheduled task, a few batches per run, and store batches.after() (the last id) to resume the next run with .resume_after(Some(id)).

A model’s default scope (Rails’ default_scope) is its query(): add the condition there (Query::table("posts").is_null("deleted_at") for soft-deleted rows) and every generated function, controller and API applies it; Query::table("posts") or unscope_where() is the unscoped query. Block-level scoping (Post.where(..).scoping { }) has no equivalent: pass the query or a scope function to the code that needs it.

A few calculations, eager loads and bulk changes on the blog’s tables:

// src/models/stats.rs
use ocre::{Ctx, IntoParam, Result, params};
use serde::{Deserialize, Serialize};

use crate::models::{
    comment,
    post::{self, Post},
    product,
};

/// One row per post: columns of the SELECT, by name.
#[derive(Debug, Deserialize, Serialize)]
pub struct CommentCount {
    pub post_id: i64,
    pub comments: i64,
}

/// The ten posts with the most comments (two or more).
pub async fn busiest_posts(ctx: &Ctx) -> Result<Vec<CommentCount>> {
    comment::query()
        .select::<CommentCount>("post_id, COUNT(*) AS comments")
        .group_by("post_id")
        .having("COUNT(*) >= ?", params![2])
        .order_desc("comments")
        .limit(10)
        .all(&ctx.db()?)
        .await
}

/// Posts `author` commented on, newest first (a JOIN, one query).
pub async fn commented_by(ctx: &Ctx, author: &str) -> Result<Vec<Post>> {
    post::query()
        .select::<Post>("posts.*")
        .distinct()
        .join("JOIN comments ON comments.post_id = posts.id")
        .eq("comments.author", author)
        .order_desc("posts.id")
        .limit(20)
        .all(&ctx.db()?)
        .await
}

/// The average price, `None` when there is no product.
pub async fn average_price(ctx: &Ctx) -> Result<Option<f64>> {
    product::query().aggregate(&ctx.db()?, "AVG(price)").await
}

/// Ids of the latest drafts.
pub async fn draft_ids(ctx: &Ctx) -> Result<Vec<i64>> {
    post::query().eq("published", false).order_desc("id").limit(100).pluck(&ctx.db()?, "id").await
}

/// Whether a post has any comment: stops at the first one.
pub async fn has_comments(ctx: &Ctx, post_id: i64) -> Result<bool> {
    comment::query().eq("post_id", post_id).exists(&ctx.db()?).await
}

/// Unpublishes the given posts in one statement; returns how many changed.
pub async fn unpublish(ctx: &Ctx, ids: &[i64]) -> Result<usize> {
    post::query()
        .is_in("id", ids.iter().copied())
        .update_all(&ctx.db()?, vec![("published", false.into_param())])
        .await
}

/// Deletes the comments of an author (no callbacks run).
pub async fn purge_author(ctx: &Ctx, author: &str) -> Result<usize> {
    comment::query().eq("author", author).delete_all(&ctx.db()?).await
}

/// Posts nobody commented on yet (`NOT EXISTS`, one index lookup per post).
pub async fn uncommented(ctx: &Ctx) -> Result<Vec<Post>> {
    post::query().where_missing("comments", "post_id").order_desc("id").limit(20).all(&ctx.db()?).await
}

/// Walks every post, 100 at a time (a job or scheduled task: one query per batch).
pub async fn count_words(ctx: &Ctx) -> Result<usize> {
    let db = ctx.db()?;
    let mut batches = post::query().batches(100, |post| post.id);
    let mut words = 0;
    while let Some(posts) = batches.next(&db).await? {
        words += posts.iter().map(|post| post.body.split_whitespace().count()).sum::<usize>();
    }
    Ok(words)
}

/// The product with this name, created when missing. `name` has a UNIQUE
/// index: when two requests race, the loser reads the winner's row.
pub async fn product_named(ctx: &Ctx, name: &str) -> Result<product::Product> {
    let db = ctx.db()?;
    product::query()
        .eq("name", name)
        .create_or_first(&db, || async {
            let sql = "INSERT INTO products (name, price) VALUES (?1, 0) RETURNING *";
            db.first(sql, params![name]).await?.ok_or_else(|| ocre::Error::internal("no row returned"))
        })
        .await
}

busiest_posts sends SELECT post_id, COUNT(*) AS comments FROM comments GROUP BY post_id HAVING (COUNT(*) >= ?1) ORDER BY comments DESC LIMIT ?2, and commented_by sends SELECT DISTINCT posts.* FROM posts JOIN comments ON comments.post_id = posts.id WHERE comments.author = ?1 ORDER BY posts.id DESC LIMIT ?2.

Rows read are what D1 bills: count, aggregate and paginate’s total read every matching row, exists and first stop early, and a filter or order on a column without an index scans the whole table. references and ^ columns are indexed; add others with ocre g migration add_index_to_<table> <columns>.

SQLite tells whether a query uses an index (query.explain(&db).await? returns the same detail lines from code). Paste the SQL (with a sample value in place of each ?N) into EXPLAIN QUERY PLAN on the local database; SEARCH ... USING INDEX is good, SCAN <table> reads every row:

ocre sql "EXPLAIN QUERY PLAN SELECT * FROM comments WHERE post_id = 1"

id | parent | notused | detail
---+--------+---------+--------------------------------------------------------------
3  | 0      | 61      | SEARCH comments USING INDEX index_comments_on_post_id (post_id=?)
(1 row)

Custom queries

When the builder does not fit (a subquery, UNION, INSERT ... ON CONFLICT, a window function, a report across tables), write the SQL. Every query goes through ctx.db()?, the DB binding of cloudflare.config.ts, with ?1, ?2... placeholders and params![...]. Never build SQL with format! from user input: values bound as parameters cannot change the statement.

params! accepts strings, integers, f64, bool (bound as 1/0), Option (None binds NULL) and serde_json::Value (bound as JSON text), mixed freely. A failed query is Error::Internal: the client gets a 500 “Internal server error”, and the Worker log gets the D1 message and the SQL. The full API is in the rustdoc of Db.

Queries on one table belong in its model file, next to the generated functions. Queries across tables can go in a module of their own under src/models/ (add pub mod reports; under // ocre:models in src/models/mod.rs):

// src/models/reports.rs
use ocre::{Ctx, Page, Result, escape_like, params};
use serde::{Deserialize, Serialize};

use crate::models::post::Post;

/// One row of `posts_with_comment_counts`: columns of the SELECT, by name.
#[derive(Debug, Deserialize, Serialize)]
pub struct PostSummary {
    pub id: i64,
    pub title: String,
    #[serde(deserialize_with = "ocre::bool_from_sql")]
    pub published: bool,
    pub comments: i64,
}

/// Posts with their number of comments, in one query (a JOIN, not one
/// COUNT per post).
pub async fn posts_with_comment_counts(ctx: &Ctx, page: Page) -> Result<Vec<PostSummary>> {
    ctx.db()?
        .all(
            "SELECT posts.id, posts.title, posts.published, COUNT(comments.id) AS comments
             FROM posts LEFT JOIN comments ON comments.post_id = posts.id
             GROUP BY posts.id ORDER BY posts.id DESC LIMIT ?1 OFFSET ?2",
            params![page.limit, page.offset],
        )
        .await
}

/// Published posts whose title contains `term`.
pub async fn search_published(ctx: &Ctx, term: &str) -> Result<Vec<Post>> {
    let pattern = format!("%{}%", escape_like(term));
    ctx.db()?
        .all(
            "SELECT * FROM posts WHERE published = ?1 AND title LIKE ?2 ESCAPE '\\' ORDER BY id DESC LIMIT 20",
            params![true, pattern],
        )
        .await
}

/// Unpublishes every post older than `days`; returns how many changed.
pub async fn unpublish_older_than(ctx: &Ctx, days: i64) -> Result<usize> {
    ctx.db()?
        .execute(
            "UPDATE posts SET published = 0, updated_at = datetime('now')
             WHERE published = 1 AND created_at < datetime('now', '-' || ?1 || ' days')",
            params![days],
        )
        .await
}

format! builds the LIKE pattern, a value bound to ?2, not the SQL; escape_like makes a % or _ typed by the user match literally (with ESCAPE '\' in the SQL). Returned as JSON from a handler (Ok(Json(reports::posts_with_comment_counts(&ctx, page).await?))), on the seeded database with three comments added:

[{"id":2,"title":"Draft","published":false,"comments":1},{"id":1,"title":"Hello","published":true,"comments":2}]

Things to know about D1 values:

• Booleans are INTEGER 0/1: bind a bool with params!, read it with #[serde(deserialize_with = "ocre::bool_from_sql")], compare in SQL with published = 1.
• Integers come back as JavaScript numbers, exact only within ±ocre::MAX_SAFE_INTEGER (2^53 - 1 = 9007199254740991). A larger value cannot be read back into i64, so generated models validate integer fields with v.safe_integer(..), and an i64 beyond it is bound as decimal text.
• Dates are TEXT: created_at is YYYY-MM-DD HH:MM:SS in UTC; compare with SQLite’s datetime('now', '-7 days'). ocre::now() gives the current Unix time in seconds (std::time::SystemTime::now() panics in WebAssembly).
• JSON columns hold JSON text: bind a serde_json::Value, read it with ocre::json_from_sql.
• Indexes: rows read counts every row scanned. WHERE and ORDER BY on an unindexed column scan the whole table; references and ^ fields are indexed, add others with CREATE INDEX in a migration.

Avoid N+1 queries

Loading a list and then one related record per item runs 1 + N queries: slow, N times the rows read, and limited to 50 queries per request on the free plan. Ocre has no lazy loading to detect (an association is an async function you call), so the rule is simply: never call an association or find in a loop. Load the whole list’s associations at once with the generated preload_<parents> (belongs to), for_<parents> (has many) or find_many, which use WHERE id IN (...) (100 ids per query):

// src/models/feed.rs
use ocre::{Ctx, Page, Result};
use serde::Serialize;

use crate::models::{
    comment::{self, Comment},
    post::{self, Post},
};

#[derive(Serialize)]
pub struct CommentWithPost {
    pub comment: Comment,
    pub post: Option<Post>,
}

/// The latest comments with their post: 2 queries for the whole page,
/// instead of 1 + one `comment.post(ctx)` per comment.
pub async fn recent_comments(ctx: &Ctx, page: Page) -> Result<Vec<CommentWithPost>> {
    let comments = comment::all(ctx, page).await?;
    let posts = comment::preload_posts(ctx, &comments).await?;
    Ok(comments
        .into_iter()
        .map(|comment| {
            let post = posts.get(&comment.post_id).cloned();
            CommentWithPost { comment, post }
        })
        .collect())
}

#[derive(Serialize)]
pub struct PostWithComments {
    pub post: Post,
    pub comments: Vec<Comment>,
}

/// A page of posts with all their comments: 2 queries, whatever the page size.
pub async fn posts_with_comments(ctx: &Ctx, page: Page) -> Result<Vec<PostWithComments>> {
    let posts = post::all(ctx, page).await?;
    let ids: Vec<i64> = posts.iter().map(|post| post.id).collect();
    let mut comments = comment::for_posts(ctx, &ids).await?;
    Ok(posts
        .into_iter()
        .map(|post| {
            let (mine, rest) = comments.drain(..).partition(|comment| comment.post_id == post.id);
            comments = rest;
            PostWithComments { post, comments: mine }
        })
        .collect())
}

Returned as JSON with ?limit=2:

[{"comment":{"id":3,"author":"Cy","body":"On two","post_id":2,"created_at":"2026-09-29 04:50:08","updated_at":"2026-09-29 04:50:08"},"post":{"id":2,"title":"Draft","body":"Not yet","published":false,"created_at":"2026-09-29 04:48:44","updated_at":"2026-09-29 04:49:13"}},{"comment":{"id":2,"author":"Bob","body":"Second","post_id":1,"created_at":"2026-09-29 04:50:08","updated_at":"2026-09-29 04:50:08"},"post":{"id":1,"title":"Hello","body":"First post","published":true,"created_at":"2026-09-29 04:48:44","updated_at":"2026-09-29 04:48:44"}}]

preload_posts returns a HashMap<i64, Post> keyed by id (rows come in no particular order, and missing ids are skipped). for_posts is not paginated: use it for a page of parents, not for a whole table. For aggregates (counts, sums), prefer one JOIN ... GROUP BY query as in busiest_posts and posts_with_comment_counts above.

Many rows in one query

A free-plan invocation runs 50 D1 queries, and D1 binds at most 100 parameters per statement, so writing rows one by one does not scale. ocre::bulk writes many rows in one statement: the rows go as one JSON array parameter, unpacked by SQLite’s json_each.

#[derive(serde::Serialize)]
struct Play {
    track_id: i64,
    played_at: String,
}

let insert = ocre::bulk::insert("plays", &["track_id", "played_at"], &plays)?;
let inserted = ctx.db()?.execute(&insert.sql, insert.params).await?; // one query, however many rows

Rows are structs or maps (anything serializing to a JSON object); each listed column is read by name, a missing one is NULL. Booleans are stored as 1/0, nested values as JSON text. The builders return a Statement, so several go into one db.batch to apply together. They skip the models’ validations and callbacks, like Rails’ insert_all: validate first when the data comes from users. Table and column names must be plain identifiers (never user input); a D1 statement is limited in size, so send a few thousand small rows at a time (rows.chunks(500)).

Transactions

D1 runs every statement in auto-commit mode, and refuses BEGIN TRANSACTION and SAVEPOINT from a Worker. The unit of atomicity is db.batch(statements): D1 runs the statements in order, in one round trip, and when one fails none of them is applied. There is no transaction left open while Rust code runs, so a batch cannot read a value and decide what to write next.

// src/models/merging.rs
use ocre::{Ctx, IntoParam, Result, Statement, params};

use crate::models::{comment, post};

/// Moves every comment of post `from` to post `into`, then deletes `from`:
/// all three statements are applied, or none. `false` when `from` did not exist.
pub async fn merge_posts(ctx: &Ctx, from: i64, into: i64) -> Result<bool> {
    let move_comments = comment::query().eq("post_id", from).update_statement(vec![("post_id", into.into_param())]);
    let touch = Statement::new("UPDATE posts SET updated_at = datetime('now') WHERE id = ?1", params![into]);
    let delete_post = post::query().eq("id", from).delete_statement();
    // The rows changed by each statement, in order.
    let changed = ctx.db()?.batch(vec![move_comments, touch, delete_post]).await?;
    Ok(changed[2] == 1)
}

/// Takes `quantity` from a product's stock only if that much is left. The
/// check and the write are one statement, so two requests at the same moment
/// cannot both take the last item.
pub async fn take_stock(ctx: &Ctx, product_id: i64, quantity: i64) -> Result<bool> {
    let changed = ctx
        .db()?
        .execute(
            "UPDATE products SET stock = stock - ?1, updated_at = datetime('now') WHERE id = ?2 AND stock >= ?1",
            params![quantity, product_id],
        )
        .await?;
    Ok(changed == 1)
}

What this means in practice:

• Each generated create, update and delete writes with one statement, so it is atomic on its own. Their uniqueness and “must exist” checks are separate reads: keep the UNIQUE index and REFERENCES constraint as the real guarantee.
• Writes to several rows or tables that must succeed together go into one batch: build the statements with Statement::new(sql, params![..]) or the builder’s *_statement() methods. Callbacks and validations do not run for them.
• A decision based on a value (“only if enough stock is left”, “only if still a draft”) goes into the WHERE of the write, and the number of rows changed tells whether it happened. Optimistic locking is the generated form of this rule.
• A batch counts the rows read and written by each statement, as if each ran alone; it saves round trips, not quota.
• Work that must happen after a write but may fail independently (an email, a call to another API) goes in a background job enqueued after the write, not in the batch.

Optimistic locking

Two people open the same record, both save: without a check, the second save silently overwrites the first. A lock_version:integer field (Rails’ magic column) makes update refuse the stale one:

ocre g scaffold Article title:string body:rich_text lock_version:integer
# or on an existing table:
ocre g migration add_lock_version_to_articles lock_version:integer

The column is lock_version INTEGER NOT NULL DEFAULT 0. The record has pub lock_version: i64; NewArticle has no such field (a new row starts at 0); ArticleChanges has pub lock_version: Option<i64>, the version the change was made from. update bumps and checks it in the same statement:

UPDATE articles SET ..., lock_version = lock_version + 1, updated_at = datetime('now')
WHERE id = ?4 AND (?5 IS NULL OR lock_version = ?5) RETURNING *

When no row comes back although the id exists, update returns Error::Conflict (409, “This article was changed by someone else since you opened it: reload it and apply your changes again.”), Rails’ StaleObjectError. lock_version: None skips the check (code that updates without having read the row).

• HTML scaffolds put <input type="hidden" name="lock_version" value="{{ form.lock_version }}"> in the edit form; a stale submit shows the 409 error page.
• JSON APIs return lock_version with every record; clients send it back in PATCH bodies ({"title": "New", "lock_version": 3}) and get a JSON 409 when someone else saved first. GraphQL patches take lockVersion.
• Cost: nothing extra on success; one SELECT 1 (one row read) to tell a conflict from a missing id.

Pessimistic locking (SELECT ... FOR UPDATE, with_lock) has no D1 equivalent: D1 never holds a transaction open while Rust runs. For “check then write” on one row, put the check in the WHERE of the write, as in take_stock under Transactions.

Encrypted columns

ocre::encryption encrypts a column’s value in Rust before it reaches D1 and decrypts it when the row is read, like Rails’ encrypts. Someone who reads the database (a leaked export, the D1 console) sees only ciphertext. The cipher is AES-256-GCM, with keys derived from SECRET_KEY_BASE (HKDF-SHA256, separate from the cookie key); a changed value fails to decrypt instead of giving a wrong result. Two field types go in the row struct:

Both deserialize by decrypting, bind as a parameter by encrypting (IntoParam), serialize to JSON as the plain value, and print Encrypted(..) in Debug output and logs. Declare the column TEXT (a value takes about 4/3 of its length plus 42 characters) and write the model by hand or edit a generated one: the generators have no encrypted field type. For a contacts table made with ocre g migration create_contacts email:string^ phone:string?:

// src/models/contact.rs
use ocre::{
    Ctx, Error, Query, Result,
    encryption::{self, Deterministic, Encrypted},
    params,
};
use serde::{Deserialize, Serialize};

/// A row of `contacts`: `email` and `phone` are stored encrypted.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Contact {
    pub id: i64,
    pub email: Deterministic,
    pub phone: Option<Encrypted>,
    pub created_at: String,
    pub updated_at: String,
}

pub fn query() -> Query<Contact> {
    Query::table("contacts")
}

/// Emails are normalized before encryption, so lookups ignore case.
fn normalize(email: &str) -> String {
    email.trim().to_lowercase()
}

pub async fn create(ctx: &Ctx, email: &str, phone: Option<String>) -> Result<Contact> {
    ctx.db()?
        .first(
            "INSERT INTO contacts (email, phone) VALUES (?1, ?2) RETURNING *",
            params![Deterministic::from(normalize(email)), phone.map(Encrypted::from)],
        )
        .await?
        .ok_or_else(|| Error::internal("INSERT ... RETURNING returned no row"))
}

/// Deterministic encryption makes `WHERE email = ?1` work.
pub async fn find_by_email(ctx: &Ctx, email: &str) -> Result<Option<Contact>> {
    query().eq("email", Deterministic::from(normalize(email))).first(&ctx.db()?).await
}

/// During a key rotation, rows written with the previous key have another
/// text: look for every candidate.
pub async fn find_by_email_during_rotation(ctx: &Ctx, email: &str) -> Result<Option<Contact>> {
    let candidates = encryption::installed()?.deterministic_candidates(&normalize(email));
    query().is_in("email", candidates).first(&ctx.db()?).await
}

/// Rewrites a batch of rows with the current key (run it from a job until
/// it returns 0).
pub async fn reencrypt(ctx: &Ctx, after_id: i64) -> Result<usize> {
    let db = ctx.db()?;
    let rows = query().gt("id", after_id).order_asc("id").limit(20).all(&db).await?;
    for row in &rows {
        db.execute(
            "UPDATE contacts SET email = ?1, phone = ?2 WHERE id = ?3",
            params![row.email.clone(), row.phone.clone(), row.id],
        )
        .await?;
    }
    Ok(rows.len())
}

contact.email.as_str() (or {{ contact.email }} in a template, through Display) is the plain value. Things to know:

• Keys. Ctx installs them the first time a Worker instance handles a request: one key derivation, then microseconds of CPU per value. Without a valid SECRET_KEY_BASE (64 characters or more), reading an encrypted row fails with a 500 whose log names the fix, and binding one writes NULL. Losing SECRET_KEY_BASE loses the data: keep a copy.
• Rotation. Put the old secret in SECRET_KEY_BASE_PREVIOUS (comma-separated for several) when you change SECRET_KEY_BASE (see Security): old values still decrypt, new writes use the new key. Deterministic lookups need deterministic_candidates until a job such as reencrypt has rewritten every row; then drop the previous secret.
• Existing plain rows. To encrypt a column that already has data, read it with encryption::installed()?.decrypt_or_plaintext(&text) (plain text passes through, like Rails’ support_unencrypted_data) while a job rewrites the rows.
• What does not work on encrypted columns: LIKE, ranges, ORDER BY and aggregates (the database sees only ciphertext), and a UNIQUE index on an Encrypted column. Validate the plain value before encrypting it.
• Tests. Native code that reads encrypted values calls encryption::install(Encryptor::new(&secret, &[])?) first.

Several databases

An app can use several D1 databases, for example to keep analytics or audit logs out of the main one (each database has its own 500 MB limit on the free plan; the account’s 5 GB of storage and daily row quotas are shared). Each is a bindings.d1(...) entry in worker.env of cloudflare.config.ts, with its own binding name, and its own migrations folder:

DB: bindings.d1({ name: "blog" }),
ANALYTICS: bindings.d1({ name: "blog-analytics" }), // migrations in migrations/analytics/

ctx.db()? is the DB binding; ctx.db_named("ANALYTICS")? returns the other one as the same ocre::Db, so every query method and the builder’s terminal methods work on it:

// src/models/page_view.rs
use ocre::{Ctx, Query, Result, params};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct PageView {
    pub id: i64,
    pub path: String,
    pub created_at: String,
}

pub fn query() -> Query<PageView> {
    Query::table("page_views")
}

pub async fn record(ctx: &Ctx, path: &str) -> Result<()> {
    ctx.db_named("ANALYTICS")?.execute("INSERT INTO page_views (path) VALUES (?1)", params![path]).await?;
    Ok(())
}

pub async fn views_of(ctx: &Ctx, path: &str) -> Result<i64> {
    query().eq("path", path).count(&ctx.db_named("ANALYTICS")?).await
}

A missing binding is a 500 whose log says which bindings.d1(...) entry to add. The Ocre CLI manages only the DB database (ocre migrate, ocre sql, ocre db ..., and ocre deploy, which creates and migrates it); manage the others with cf in production:

mkdir -p migrations/analytics
npx cf d1 migrations create create_page_views --dir migrations/analytics   # an empty numbered file to fill in
npx cf d1 create --name blog-analytics                                   # once, before the first deploy
npx cf d1 list --name blog-analytics                                     # its uuid
npx cf d1 migrations apply <uuid> --dir migrations/analytics             # production

Locally, cf 1.0.0-beta.5 cannot migrate a local database yet (see Why wrangler still appears); do what Ocre does for DB and run the app’s wrangler with a small config of its own, db/analytics-d1.json:

{"name": "blog", "compatibility_date": "2026-09-01", "d1_databases": [{"binding": "ANALYTICS", "database_name": "blog-analytics", "migrations_dir": "../migrations/analytics"}]}

node_modules/.bin/wrangler d1 migrations apply ANALYTICS --local -c db/analytics-d1.json --persist-to .wrangler/state

--persist-to .wrangler/state is the state ocre dev uses, so the local Worker sees the tables.

Queries cannot join tables of two databases and a batch runs on one database: load ids from one, then find_many-style is_in queries on the other.

Read replicas

D1 can keep read-only copies of a database near the Workers that use it (read replication, free). Ocre routes queries through D1 sessions so each visitor still reads what they wrote (Rails’ automatic role switching):

1. turn replication on for the database (dashboard: D1 > database > Settings);
2. set the variable in cloudflare.config.ts (and D1_REPLICAS=on in .dev.vars to try it locally, where there is no replica):

D1_REPLICAS: bindings.text("on"),

Then every request served by ocre::serve uses one session per database: a GET or HEAD may start on any replica, other methods start on the primary, and later queries of the request see the earlier ones. After a request that wrote, the response sets ocre_d1_<binding> (HttpOnly, 5 minutes) with the session’s bookmark, and the visitor’s next requests resume from it, so the page shown after a form has the new row. Read-only responses set no cookie and stay cacheable. Jobs, crons and email handlers query the primary. Nothing changes in the models: ctx.db() returns the session. See ocre::replicas.

Form objects and plain structs

Rails’ Active Model makes a plain Ruby class behave like a model: attributes, validations, callbacks, naming, serialization. In Ocre any struct already does, with serde and ocre::Validator, so a form that is not a table (a contact form, a sign-up that writes two tables, a search) is a struct with a validate() function:

// src/models/contact_form.rs
use ocre::{Result, Validator};
use serde::{Deserialize, Serialize};

/// The contact form: no table, but typed fields, defaults and validations.
#[derive(Debug, Default, Deserialize, Serialize)]
#[serde(default)]
pub struct ContactForm {
    pub name: String,
    pub email: String,
    pub message: String,
    pub accept_terms: bool,
    /// Never serialized back to a client (Rails' `except:`).
    #[serde(skip_serializing)]
    pub honeypot: String,
}

impl ContactForm {
    /// Rails' `valid?` / `errors`: every failed check at once.
    pub fn validate(&self) -> Validator {
        let mut v = Validator::new();
        v.required("name", &self.name).email("email", &self.email).min_length("message", &self.message, 10);
        v.acceptance("accept_terms", self.accept_terms).absence("honeypot", &self.honeypot);
        v
    }

    /// Rails' `validate!`: `Error::Invalid` (422) with every message.
    pub fn validate_strict(&self) -> Result<()> {
        self.validate().finish()
    }
}

A handler takes it with Form(form): Form<ContactForm> (or Json), calls form.validate().finish()?, then does the work: send the email, or call two models’ create in turn. How each Active Model module maps:

What is not supported

Ocre models are generated Rust over SQL, not an ORM, and D1 is SQLite behind an HTTP API. These Rails features have no equivalent; the second column is what to do instead:

See also

• Validations: every Validator check, and how errors reach forms and JSON
• Controllers and routing: calling the model from handlers
• JSON APIs and GraphQL: the model behind /api/<plural> and /graphql
• Generators, Field types, CLI commands
• Free-plan limits
• API index and the rustdoc

Validations

Validations check input before it reaches the database: ocre::Validator collects every failed rule with Rails’ messages, and finish() turns them into Error::Invalid, a 422 that HTML forms show next to the typed values and JSON APIs report per field. This page lists every check, where rules belong, and what clients receive.

Before you start

• An Ocre app from ocre new, with a model from ocre g model, ocre g scaffold or ocre g api (see Models and migrations). The examples use the blog starter (ocre new blog --starter blog), ocre g scaffold Comment author:string body:text post:references and ocre g api Product name:string^ price:float stock:integer? --graphql.
• Validations run in the Worker and cost a little CPU and no binding call, except the database checks (uniqueness, references), which each read about one row with the indexes the generators create.

How a validation works

// src/models/signup_rules.rs
use ocre::{Result, Validator};

pub fn check_signup(name: &str, email: &str, age: i64) -> Result<()> {
    let mut v = Validator::new();
    v.required("name", name).max_length("name", name, 50);
    v.email("email", email);
    v.range("age", age, 13..=120);
    v.finish()
}

Each check records an error when it fails and returns &mut Validator, so checks chain. Nothing stops at the first failure: finish() returns Ok(()) when every check passed, or Err(Error::Invalid(errors)) with all of them. An error is an ocre::FieldError { field, message }: the message has no field name ("can't be blank"), and full_message() adds the humanized name ("Name can't be blank"; post_id becomes Post).

Messages are English. Each check also records Rails’ translation key (error.key(): blank, too_long…), so i18n.full_message("post", &error) and i18n.error_message("post", &error) give them in the visitor’s language, from the app’s locale files or the built-in French, German, Spanish, Italian, Portuguese and Dutch messages: see Translations.

Every check

Messages are the exact strings Ocre adds (Rails’ wording).

The comparisons take any PartialOrd + Display value, so they also compare YYYY-MM-DD dates as text (v.greater_than("ends_on", &ends_on, &starts_on)). For a length range, chain min_length and max_length.

.message("...") right after a check replaces its message when it failed (Rails’ message:): v.required("body", &body).message("write something first"). It only changes the check just before it.

The other methods: Validator::new(), v.merge(other) (adds the errors another validator collected), v.is_valid() (no error so far), v.errors() (the FieldErrors so far, in order) and v.finish(). File rules and v.file are covered in File storage. The API reference is in the rustdoc of Validator.

A complete set of rules, with a custom one, behind a JSON endpoint:

// src/reservations.rs
use axum::{Router, routing::post};
use ocre::{ApiResult, Created, Ctx, Json, Validator};
use serde::{Deserialize, Serialize};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/api/reservations", post(create))
}

const SLOTS: &[&str] = &["lunch", "dinner"];

#[derive(Debug, Deserialize, Serialize)]
pub struct NewReservation {
    pub name: String,
    pub email: String,
    pub guests: i64,
    pub slot: String,
    /// `YYYY-MM-DD`
    pub date: String,
    /// `YYYY-MM-DD HH:MM`, optional
    #[serde(default)]
    pub arrives_at: Option<String>,
    #[serde(default)]
    pub promo_code: Option<String>,
    #[serde(default)]
    pub deposit_cents: Option<i64>,
}

impl NewReservation {
    pub fn validate(&self) -> Validator {
        let mut v = Validator::new();
        v.required("name", &self.name).max_length("name", &self.name, 100);
        v.email("email", &self.email);
        v.range("guests", self.guests, 1..=12);
        v.inclusion("slot", &self.slot, SLOTS);
        v.date("date", &self.date);
        if let Some(arrives_at) = &self.arrives_at {
            v.datetime("arrives_at", arrives_at);
        }
        if let Some(code) = &self.promo_code {
            v.min_length("promo_code", code, 6);
        }
        if let Some(cents) = self.deposit_cents {
            v.safe_integer("deposit_cents", cents);
        }
        // A rule of your own: any condition plus a message.
        v.check("guests", self.slot == "lunch" && self.guests > 8, "must be 8 or fewer at lunch");
        v
    }
}

async fn create(Json(new): Json<NewReservation>) -> ApiResult<Created<NewReservation>> {
    new.validate().finish()?;
    Ok(Created(new))
}

Registered in src/lib.rs (mod reservations; under // ocre:modules, .merge(reservations::routes()) under // ocre:routes) and called while ocre dev runs:

curl -s -X POST http://localhost:8787/api/reservations -H 'Content-Type: application/json' \
  -d '{"name": "", "email": "ada@", "guests": 10, "slot": "lunch", "date": "2026-02-30", "arrives_at": "2026-02-01 25:00", "promo_code": "abc", "deposit_cents": 9007199254740992}'

{"error":{"fields":{"arrives_at":["is not a valid date and time"],"date":["is not a valid date"],"deposit_cents":["must be less than or equal to 9007199254740991"],"email":["is invalid"],"guests":["must be 8 or fewer at lunch"],"name":["can't be blank"],"promo_code":["is too short (minimum is 6 characters)"]},"message":"Validation failed","status":422}}

Status 422, every failed field at once. The other messages:

curl -s -X POST http://localhost:8787/api/reservations -H 'Content-Type: application/json' \
  -d '{"name": "Ada", "email": "ada@example.com", "guests": 2, "slot": "brunch", "date": "2026-10-01"}'

{"error":{"fields":{"slot":["is not included in the list"]},"message":"Validation failed","status":422}}

With a 101-character name and "guests": 0:

{"error":{"fields":{"guests":["must be greater than or equal to 1"],"name":["is too long (maximum is 100 characters)"]},"message":"Validation failed","status":422}}

A valid body is echoed with 201 Created:

curl -s -X POST http://localhost:8787/api/reservations -H 'Content-Type: application/json' \
  -d '{"name": "Ada", "email": "ada@example.com", "guests": 2, "slot": "dinner", "date": "2026-10-01", "arrives_at": "2026-10-01T19:30"}'

{"name":"Ada","email":"ada@example.com","guests":2,"slot":"dinner","date":"2026-10-01","arrives_at":"2026-10-01T19:30","promo_code":null,"deposit_cents":null}

A body that does not deserialize (a missing required field, a string where a number is expected, invalid JSON) never reaches validate(): ocre::Json answers 400 with serde’s explanation (see JSON APIs).

Forms: confirmation, acceptance, formats and enums

A signup form uses the checks Rails apps reach for on accounts, and a filter form parses a generated enum (Status from ocre g model Task title:string status:enum:open,done author:references?):

// src/signup_form.rs
use ocre::{Result, Validator};
use serde::Deserialize;

use crate::models::task::Status;

const RESERVED: &[&str] = &["admin", "root", "support"];

/// What the signup form sends: every field is text, the checkbox a bool.
#[derive(Debug, Default, Deserialize)]
#[serde(default)]
pub struct SignupForm {
    pub username: String,
    pub password: String,
    pub password_confirmation: String,
    pub age: String,
    pub zip: String,
    /// Hidden with CSS: people leave it empty, bots fill it in.
    pub website: String,
    /// An unticked checkbox sends nothing, hence `#[serde(default)]`.
    pub terms_of_service: bool,
}

impl SignupForm {
    pub fn validate(&self) -> Result<()> {
        let mut v = Validator::new();
        let username_char = |c: char| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_';
        v.min_length("username", &self.username, 3).max_length("username", &self.username, 20);
        v.format("username", &self.username, username_char).message("may only contain a-z, 0-9 and _");
        v.exclusion("username", &self.username, RESERVED);
        v.min_length("password", &self.password, 12);
        v.confirmation("password", &self.password, &self.password_confirmation);
        if let Some(age) = v.number::<i64>("age", &self.age) {
            v.greater_than_or_equal_to("age", age, 16);
        }
        v.length("zip", &self.zip, 5);
        v.absence("website", &self.website);
        v.acceptance("terms_of_service", self.terms_of_service);
        v.finish()
    }
}

/// A filter such as `?status=done`; blank means no filter.
pub fn status_filter(text: &str) -> Result<Option<Status>> {
    let mut v = Validator::new();
    let status = v.optional_one_of::<Status>("status", text);
    v.finish()?;
    Ok(status)
}

With username=Admin!, password=short, password_confirmation=shorter, age=15, zip=7500, website=http://spam.example and no terms_of_service, validate() fails with these messages, in this order (full_message()):

Username may only contain a-z, 0-9 and _
Password is too short (minimum is 12 characters)
Password confirmation doesn't match Password
Age must be greater than or equal to 16
Zip is the wrong length (should be 5 characters)
Website must be blank
Terms of service must be accepted

The confirmation error is on password_confirmation, so a form shows it next to the second field. status_filter("archived") fails with “Status is not included in the list”; status_filter("done") returns Some(Status::Done).

Where rules live

Data rules belong in the model, src/models/<model>.rs, so the HTML pages, the JSON API and GraphQL enforce the same ones:

A generated create, for Comment (post:references):

pub async fn create(ctx: &Ctx, mut new: NewComment) -> Result<Comment> {
    before_create(ctx, &mut new).await?;
    let db = ctx.db()?;
    let mut v = new.validate();
    {
        let post_id = &new.post_id;
        v.check("post_id", !db.exists("SELECT 1 FROM posts WHERE id = ?1 LIMIT 1", params![*post_id]).await?, "must exist");
    }
    v.finish()?;
    let record: Comment = db
        .first("INSERT INTO comments (author, body, post_id) VALUES (?1, ?2, ?3) RETURNING *", params![new.author, new.body, new.post_id])
        .await?
        .ok_or_else(|| Error::internal("INSERT ... RETURNING returned no row"))?;
    after_create(ctx, &record).await?;
    Ok(record)
}

The database checks add to the validate() errors, so a JSON client gets both kinds in one answer:

curl -s -X POST http://localhost:8787/api/products -H 'Content-Type: application/json' \
  -d '{"name": "Teapot", "price": 3, "stock": 9007199254740992}'

{"error":{"fields":{"name":["has already been taken"],"stock":["must be less than or equal to 9007199254740991"]},"message":"Validation failed","status":422}}

In update, the uniqueness check excludes the record itself (AND id != ?2): renaming product 3 to an existing name is refused, saving product 1 with its own name is not. update checks only the fields being changed.

Add rules to validate(); add database rules to create/update next to the generated ones, with v.check(field, db.exists(sql, params).await?, message). Keep the UNIQUE index and REFERENCES constraint in the migration too: two requests at the same moment can both pass the check, and the constraint then fails the second insert with a 500.

What clients receive

Error::Invalid has status 422. How it is shown depends on the handler.

HTML forms re-render

The scaffold’s create and update handlers (src/<plural>.rs) match Error::Invalid and render the form again with the errors and the values as typed:

        Err(Error::Invalid(errors)) => {
            Ok((StatusCode::UNPROCESSABLE_ENTITY, render(&NewView { form, errors })?).into_response())
        }

templates/<plural>/_form.html lists them with full_message():

{% if !errors.is_empty() %}
  <ul class="errors">
    {% for error in errors %}<li>{{ error.full_message() }}</li>{% endfor %}
  </ul>
{% endif %}

curl -s -X POST http://localhost:8787/comments -d 'author=Ada&body=Nice&post_id=99'

...
<form action="/comments" method="post">

  <ul class="errors">
    <li>Post must exist</li>
  </ul>

  <label>Author <input name="author" value="Ada" required></label>
  <label>Body <textarea name="body" rows="5" required>Nice</textarea></label>
  <label>Post <input type="number" step="1" name="post_id" value="99" required></label>
  <button type="submit">Create comment</button>
</form>
...

The form struct keeps every field as text (PostForm, CommentForm), so a typo in a number is a field error rather than a failed request: to_new() parses with v.number(..), then merges the model’s validate(). The form’s own checks run first; the database checks run in create only when they pass, so a form with a blank body and an unknown post shows “Body can’t be blank” first, then “Post must exist” on the next submit.

The same pattern, written by hand for the API’s Product model (price:float stock:integer?) plus a free-form JSON field:

// src/product_form.rs
use ocre::{Result, Validator, serde_json::Value};
use serde::Deserialize;

use crate::models::product::NewProduct;

/// What an HTML form sends: every field is text.
#[derive(Debug, Default, Deserialize)]
#[serde(default)]
pub struct ProductForm {
    pub name: String,
    pub price: String,
    pub stock: String,
    pub specs: String,
}

impl ProductForm {
    /// Parses the text, then runs the model's rules, so the form shows every
    /// error at once.
    pub fn to_new(&self) -> Result<(NewProduct, Option<Value>)> {
        let mut v = Validator::new();
        let new = NewProduct {
            name: self.name.clone(),
            price: v.number("price", &self.price).unwrap_or_default(),
            stock: v.optional_number("stock", &self.stock),
        };
        let specs = v.optional_json("specs", &self.specs);
        v.merge(new.validate()).finish()?;
        Ok((new, specs))
    }
}

Posted as name=&price=abc&stock=12x&specs={bad to a JSON handler that calls form.to_new()?, it answers:

{"error":{"fields":{"name":["can't be blank"],"price":["is not a number"],"specs":["is not valid JSON"],"stock":["is not a number"]},"message":"Validation failed","status":422}}

and name=Pan&price=12.5&stock=&specs={"size":"L"} parses to price 12.5, stock None and specs {"size":"L"}.

An HTML handler that returns Error::Invalid with ? instead of re-rendering gets Ocre’s plain error page, status 422:

<h1>422</h1><p>Validation failed</p><ul><li>Title can&#39;t be blank</li><li>Contact email is invalid</li></ul>

JSON APIs report fields

Handlers returning ocre::ApiResult turn Error::Invalid into a 422 whose fields object maps each field to its messages, as shown above. The same shape comes back from create and update in every generated JSON API (ocre g api); see JSON APIs.

GraphQL puts fields in extensions

GraphQL resolvers convert the error with ?; the response is a 200 with the error in errors, the status and fields in extensions:

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "mutation { createProduct(input: {name: \"\", price: 30}) { id } }"}'

{"data":null,"errors":[{"message":"Validation failed","locations":[{"line":1,"column":12}],"path":["createProduct"],"extensions":{"fields":{"name":["can't be blank"]},"status":422}}]}

Custom rules

v.check(field, failed, message) covers any rule: pass the condition that means failure and a message without the field name. Cross-field rules, rules on the current time and rules needing the database all use it:

// src/models/event_rules.rs
use ocre::{Ctx, Result, Validator, params};

/// `starts_on` and `ends_on` are `YYYY-MM-DD`, so text order is date order.
pub fn check_dates(v: &mut Validator, starts_on: &str, ends_on: &str) {
    let mut dates = Validator::new();
    dates.date("starts_on", starts_on).date("ends_on", ends_on);
    let both_valid = dates.is_valid();
    v.merge(dates);
    v.check("ends_on", both_valid && ends_on < starts_on, "must be on or after the start date");
}

/// Database rule: at most 20 comments per post.
pub async fn check_comment_quota(ctx: &Ctx, post_id: i64) -> Result<()> {
    let full = ctx
        .db()?
        .exists("SELECT 1 FROM comments WHERE post_id = ?1 LIMIT 1 OFFSET 19", params![post_id])
        .await?;
    let mut v = Validator::new();
    v.check("post_id", full, "has too many comments");
    v.finish()
}

The separate dates validator tells whether both dates parsed (is_valid()), so a malformed date reports one error, not two; merge then adds its errors to v. Call such functions from the model’s validate() (checks without the database) or create/update (database checks), before finish().

Rails’ validation options, the Ocre way

Rails declares validations with options; in Ocre a rule is a line of Rust in validate(), so the options are ordinary code:

See also

• Models and migrations: the generated validate(), create and update
• Controllers and routing and Views, helpers and forms: the scaffold’s form handling
• JSON APIs and GraphQL: error JSON, 400 versus 422
• File storage: Rules and v.file for uploads
• Field types: which checks each type gets
• API index and the rustdoc of Validator

Controllers and routing

Controllers in Ocre are plain axum handlers grouped in one module per resource, each with a routes() function merged into the router in src/lib.rs, and a paths module that builds the URLs of its pages. This page walks through the generated scaffold controller, then covers routing (nested resources, namespaces, redirects), what a handler can read from the request and answer, error pages, and middleware. Templates and forms are in Views, helpers and forms, interactivity in htmx, CSS and JavaScript in Assets.

Before you start

• A full-stack Ocre app from ocre new (not --api: API-only apps have no templates; see JSON APIs). The examples use the blog starter, ocre new blog --starter blog, whose src/posts.rs is the scaffold of Post title:string body:text published:boolean.
• ocre dev running to try the pages (it serves http://localhost:8787 unless you pass --port).
• Free plan (September 2026, Workers limits): 100,000 requests a day and 10 ms of CPU per request. Awaiting D1 does not count as CPU; rendering a template is plain string building, a fraction of a millisecond for a normal page.

Generate a scaffold

ocre g scaffold Comment author:string body:text post:references

  create  migrations/0003_create_comments.sql
  create  src/models/comment.rs
  create  src/comments.rs
  create  templates/comments/index.html
  create  templates/comments/show.html
  create  templates/comments/new.html
  create  templates/comments/edit.html
  create  templates/comments/_form.html
  update  src/models/post.rs
  update  src/models/mod.rs
  update  src/lib.rs

Next:
  ocre migrate
  ocre dev
  open http://localhost:8787/comments

The model is explained in Models and migrations; this page covers src/comments.rs (the controller); the templates are described in Views. In an API-only app, ocre g scaffold generates a JSON API instead.

Routes

routes() at the top of the controller lists every route of the resource (Rails’ resources :posts):

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/posts", get(index).post(create))
        .route("/posts/new", get(new))
        .route("/posts/{id}", get(show).post(update))
        .route("/posts/{id}/edit", get(edit))
        .route("/posts/{id}/delete", post(delete))
}

Update and delete use POST because HTML forms can only send GET and POST. Rails simulates PATCH/DELETE with a hidden _method field; Ocre keeps the routes the browser actually sends, so the pages work without JavaScript and without method overriding. JSON APIs use real PATCH and DELETE (see JSON APIs). To drop an action (Rails’ only:/except:), delete its route and handler; to rename a path (path:), edit the strings here and in paths.

Paths use axum 0.8 syntax: {id} is a parameter, {*rest} a wildcard. A path no route matches gets the app’s 404 page (see Error pages).

Path helpers

Below routes(), the paths module builds the URL of each page (Rails’ posts_path, new_post_path, post_path(post), edit_post_path(post)):

pub mod paths {
    use std::fmt::Display;

    pub fn index() -> &'static str {
        "/posts"
    }

    pub fn new() -> &'static str {
        "/posts/new"
    }

    pub fn show(id: impl Display) -> String {
        format!("/posts/{id}")
    }

    pub fn edit(id: impl Display) -> String {
        format!("/posts/{id}/edit")
    }

    pub fn delete(id: impl Display) -> String {
        format!("/posts/{id}/delete")
    }
}

Handlers redirect with them (Redirect::to(&paths::show(record.id))) and templates link with them: askama resolves paths next to the template’s struct, so the controller’s templates write <a href="{{ paths::edit(post.id) }}">, and any other module crate::posts::paths::show(id). Changing a URL is then one edit in routes() and one in paths. Attachment fields add one function per file (paths::avatar(id)). They are plain functions, so a custom URL helper (Rails’ direct, default_url_options such as a locale prefix) is a function you add, with the parameters it needs.

List the routes

ocre routes reads src/lib.rs and the modules it merges or nests, without building the app, and prints every route; an argument filters by method, path or handler (case-insensitive substring):

ocre routes comments

METHOD  PATH                   HANDLER
GET     /comments              comments::index
POST    /comments              comments::create
GET     /comments/new          comments::new
GET     /comments/{id}         comments::show
POST    /comments/{id}         comments::update
POST    /comments/{id}/delete  comments::delete
GET     /comments/{id}/edit    comments::edit

It finds .route("<path>", ...) calls, follows .merge(<module>::routes()) and .nest("<prefix>", <module>::routes()) into src/<module>.rs (or src/<module>/mod.rs), and knows that ocre::graphql::routes(..) serves GET and POST /graphql. Routes whose handler is a closure, and routers built inline or in variables, are skipped. --json returns the list in routes:

{"command":"routes","ok":true,"routes":[{"handler":"posts::index","method":"GET","path":"/posts"},{"handler":"posts::create","method":"POST","path":"/posts"},...]}

Register a module in src/lib.rs

src/lib.rs is the Worker’s entry point and the app’s router. Generators add modules and routes after two marker comments, which must stay in place:

// ocre:modules
mod comments;
mod posts;
mod models;

#[event(fetch)]
async fn fetch(req: HttpRequest, env: Env, _ctx: Context) -> worker::Result<worker::web_sys::Response> {
    ocre::serve(routes(), req, env).await
}

fn routes() -> Router<Ctx> {
    Router::new()
        .route("/", get(home))
        .route("/up", get(up))
        // ocre:routes
        .merge(comments::routes())
        .merge(posts::routes())
        .fallback(not_found)
        .layer(map_response(error_page))
        .layer(content_security_policy())
        .layer(permissions_policy())
}

For a module you write by hand, add mod <name>; under // ocre:modules and .merge(<name>::routes()) under // ocre:routes. ocre::serve wraps the router with sessions, CSRF protection, CORS and security headers (see Sessions, flash and security), and builds the per-request Ctx. / is the root route (Rails’ root), /up the health check. .fallback and the error-page layer come after the routes (see Error pages), followed by the Content-Security-Policy and Permissions-Policy layers (see Security); after ocre g locale, .layer(ocre::i18n::layer(&LOCALES)) must stay the very last call.

Routing recipes

axum’s Router covers Rails’ routing DSL with ordinary method calls. One module showing the common shapes:

// src/library.rs
use axum::{
    Router,
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Redirect, Response},
    routing::get,
};
use ocre::{Ctx, OptionExt, Result, Session};

use crate::models::{comment, post};

pub fn routes() -> Router<Ctx> {
    Router::new()
        // Nested resource (Rails' `resources :posts do resources :comments end`).
        .route("/posts/{post_id}/comments/{id}", get(post_comment))
        // Singular resource (Rails' `resource :profile`): no id, the session says whose.
        .route("/profile", get(profile))
        // Member and collection routes: more paths under the resource.
        .route("/posts/{id}/preview", get(preview))
        .route("/posts/drafts", get(drafts))
        // Redirects (Rails' `get "/articles/:id", to: redirect("/posts/%{id}")`).
        .route("/articles", get(|| async { Redirect::permanent("/posts") }))
        .route("/articles/{id}", get(|Path(id): Path<i64>| async move { Redirect::permanent(&format!("/posts/{id}")) }))
        // Glob (Rails' `get "pages/*path"`): `path` is the rest, e.g. `help/billing`.
        .route("/pages/{*path}", get(page))
        // Namespace (Rails' `namespace :admin`): every admin route under /admin.
        .nest("/admin", admin_routes())
}

fn admin_routes() -> Router<Ctx> {
    Router::new().route("/", get(|| async { "Admin home" })).route("/posts/{id}", get(preview))
}

/// Both ids come from the path, in order; a comment of another post is a 404.
async fn post_comment(State(ctx): State<Ctx>, Path((post_id, id)): Path<(i64, i64)>) -> Result<String> {
    let comment = comment::find(&ctx, id).await?.filter(|c| c.post_id == post_id).or_404()?;
    Ok(comment.body)
}

async fn profile(session: Session) -> Result<Response> {
    match session.get::<i64>("user_id")? {
        Some(id) => Ok(format!("user {id}").into_response()),
        None => Ok(Redirect::to("/login").into_response()),
    }
}

async fn preview(State(ctx): State<Ctx>, Path(id): Path<i64>) -> Result<String> {
    Ok(post::find(&ctx, id).await?.or_404()?.title)
}

async fn drafts() -> &'static str {
    "drafts"
}

async fn page(Path(path): Path<String>) -> Response {
    match path.as_str() {
        "help/billing" => "Billing help".into_response(),
        _ => StatusCode::NOT_FOUND.into_response(),
    }
}

/posts/drafts and /posts/{id} can coexist: axum prefers the static segment. A typed parameter is its constraint (Rails’ constraints: { id: /\d+/ }): Path<i64> answers 400 Bad Request to /posts/abc, with the app’s error page. Everything else:

Handlers and extractors

A handler is an async fn whose arguments are axum extractors and whose return type implements IntoResponse. Every Ocre type is Send, so handlers need no annotation unless they await a future from another crate that is not (see Futures that are not Send). Params are typed per source instead of Rails’ merged params hash, and a form or JSON struct lists exactly the fields it accepts, which replaces strong parameters.

The extractor that reads the body (Form, Json, Multipart) must be the last argument, an axum rule. axum’s Form, Json and body extractors refuse bodies over 2 MB with 413 (Loco’s limit_payload); a route that needs more adds .layer(axum::extract::DefaultBodyLimit::max(10 * 1024 * 1024)). Workers accept request bodies up to 100 MB. After ocre g auth, CurrentUser and BearerUser are extractors too (see Authentication); an extractor is also how Ocre does Rails’ before_action: a handler that takes CurrentUser only runs for signed-in users.

Cookies other than the session go through the Cookies extractor (Rails’ cookies, cookies.signed, cookies.encrypted); values tied to the visitor’s session belong in the Session, which is signed and encrypted.

Futures that are not Send

axum requires a handler’s future to be Send. Ocre’s types are, but a future holding a JavaScript value is not: worker::Fetch, reqwest in WebAssembly, wasm_bindgen_futures::JsFuture, a D1 or KV handle from worker itself. Awaiting one in a handler fails to compile at the route, far from the cause:

error[E0277]: the trait bound `fn() -> impl Future<Output = Result<..., ...>> {remote}: Handler<_, _>` is not satisfied
  |
5 |     Router::new().route("/remote", get(remote))
  |                                    --- ^^^^^^ unsatisfied trait bound
  = note: Consider using `#[axum::debug_handler]` to improve the error message

Put #[worker::send] on the handler: it wraps its future in worker::send::SendFuture, which is sound because a Worker runs your code on one thread. For a single call inside a larger function, wrap only that future: worker::send::SendFuture::new(async { ... }).await. Functions that Ocre’s generated code calls from handlers (a model method, a job’s perform) need the same wrapping when they await such a future.

Calling other services

Ocre has no HTTP client of its own; two work in a Worker:

• reqwest with default-features = false: in WebAssembly it calls the Worker’s fetch, with its usual API (json, headers, query strings). cargo add reqwest --no-default-features --features json.
• worker::Fetch, the worker crate’s thin wrapper over fetch.

use axum::Json;
use ocre::{Error, Result};

#[worker::send] // reqwest's futures hold JavaScript values
async fn rates() -> Result<Json<serde_json::Value>> {
    let rates = reqwest::get("https://api.example.com/rates")
        .await
        .map_err(|err| Error::internal(format!("rates API: {err}")))?
        .json()
        .await
        .map_err(|err| Error::internal(format!("rates API: {err}")))?;
    Ok(Json(rates))
}

Each call is a subrequest: 50 per invocation on the free plan (counted with the other calls a job makes, see Long jobs). Cache answers that change slowly with ocre::cache::fetch, and put secrets (API keys) in Worker secrets read with ctx.config().

Responses

ocre::Error and its statuses:

? converts worker::Error and askama errors into Error::Internal. For a missing record, option.or_404()? (trait ocre::OptionExt) turns None into Error::NotFound. Mapping errors to responses (Rails’ rescue_from) is a match on the Error in the handler, as the scaffold does for Error::Invalid, or a map_response layer for the whole app, as for error pages.

Formats (respond_to)

ocre::Format reads the Accept header, so one action can serve a page to browsers and JSON to API clients (Rails’ respond_to, Loco’s RespondTo):

use askama::Template;
use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Response},
};
use ocre::{Ctx, Format, Json, OptionExt, Result, render};

use crate::models::post::{self, Post};

#[derive(Template)]
#[template(source = "<h1>{{ post.title }}</h1><p>{{ post.body }}</p>", ext = "html")]
struct PostPage {
    post: Post,
}

/// GET /posts/{id}: HTML for browsers, JSON for `Accept: application/json`.
async fn show(State(ctx): State<Ctx>, format: Format, Path(id): Path<i64>) -> Result<Response> {
    let post = post::find(&ctx, id).await?.or_404()?;
    Ok(match format {
        Format::Html => render(&PostPage { post })?.into_response(),
        Format::Json => Json(post).into_response(),
        _ => StatusCode::NOT_ACCEPTABLE.into_response(),
    })
}

curl -s http://localhost:8787/posts/1 -H 'Accept: application/json'

{"id":1,"title":"Hello","body":"First","published":true,"created_at":"2026-09-29 10:00:00","updated_at":"2026-09-29 10:00:00"}

A missing Accept, */* and text/html are Html; browsers get HTML. Other representations (Rails’ request variants, a phone layout) are another match arm or another view struct chosen from a header.

Format::Markdown (Accept: text/markdown) pairs with the ocre::Markdown response (text/markdown; charset=utf-8), to offer a page to LLM clients and command-line readers as Markdown (Rails 8.1’s format.md and render markdown:):

use axum::response::{Html, IntoResponse, Response};
use ocre::{Format, Markdown};

/// GET /about: HTML, or Markdown for `Accept: text/markdown`.
async fn about(format: Format) -> Response {
    let (title, body) = ("About", "We make ochre.");
    match format {
        Format::Markdown => Markdown(format!("# {title}\n\n{body}\n")).into_response(),
        _ => Html(format!("<h1>{title}</h1><p>{body}</p>")).into_response(),
    }
}

Files and downloads

ocre::storage::send_data sends bytes the handler built as a file (Rails’ send_data), with the right Content-Type, Content-Length and a sanitized Content-Disposition file name:

use axum::{extract::State, response::Response};
use ocre::{Ctx, Page, Result, storage::{Disposition, send_data}};

use crate::models::post;

/// GET /posts.csv: the latest 100 posts as a spreadsheet.
async fn export(State(ctx): State<Ctx>) -> Result<Response> {
    let mut csv = String::from("id,title,published\n");
    for post in post::all(&ctx, Page::new(100, 0)?).await? {
        csv.push_str(&format!("{},\"{}\",{}\n", post.id, post.title.replace('"', "\"\""), post.published));
    }
    Ok(send_data(csv, "posts.csv", "text/csv", Disposition::Download))
}

Files stored in R2 go out with ocre::storage::serve (Rails’ send_file and Rack::Sendfile): the Worker hands R2’s stream to Cloudflare without copying it through WebAssembly, and answers Range and If-None-Match requests (see File storage). Generated data should stay small: the body is built in memory (128 MB per Worker) and within the 10 ms of CPU.

Streaming: Server-Sent Events

ocre::sse::stream(state, step) streams events while they are produced (Rails’ ActionController::Live with SSE): the handler returns at once, then Ocre calls step for each event and the Worker sends it to the client right away, until step returns None. Pace events with ocre::sleep(duration), which waits without using CPU:

use std::time::Duration;

use axum::{Router, extract::Path, response::IntoResponse, routing::get};
use ocre::{Ctx, sse::{self, Event}};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/imports/{id}/progress", get(progress))
}

/// `data: 25`, `data: 50`... one second apart, then `event: done`.
async fn progress(Path(id): Path<i64>) -> impl IntoResponse {
    sse::stream(Some(0u32), move |percent: Option<u32>| async move {
        let percent = percent?;
        ocre::sleep(Duration::from_secs(1)).await;
        Some(match percent {
            100 => (Event::default().event("done").data(format!("import {id} finished")), None),
            p => (Event::default().data((p + 25).to_string()), Some(p + 25)),
        })
    })
}

<progress id="bar" max="100"></progress>
<script>
  const source = new EventSource("/imports/1/progress");
  source.onmessage = (event) => { document.getElementById("bar").value = event.data; };
  source.addEventListener("done", () => source.close());
</script>

On the free plan: only each step’s work counts toward the 10 ms of CPU, not the waits, and a response may stream as long as the client stays connected. The whole stream is one request, so its binding calls share the per-request limits (50 subrequests, D1 queries included): a stream cannot poll D1 every second for minutes. EventSource reconnects about 3 s after a stream ends, each time a new request, so send a last event on which the page calls source.close(). To push changes to many open pages (a new comment for everyone), use WebSockets on a Durable Object instead (see Realtime).

Error pages

ocre new generates templates/error.html and two functions in src/lib.rs (Rails’ public/404.html, 422.html and 500.html, rendered with the app’s layout):

/// Paths no route matches: the 404 error page.
async fn not_found() -> Error {
    Error::NotFound
}

#[derive(Template)]
#[template(path = "error.html")]
struct ErrorView<'a> {
    error: &'a ErrorPage,
}

/// Renders error responses (404, 422, 500...) with templates/error.html.
async fn error_page(response: Response) -> Response {
    ocre::error_page(response, |error| render(&ErrorView { error }))
}

routes() ends with .fallback(not_found) and .layer(map_response(error_page)). ocre::error_page renders the template for every ocre::Error a handler returns, for the fallback’s 404, and for axum’s plain-text rejections (a path that does not parse, a form that does not deserialize), whose message is the status name (Bad Request). It keeps the status and headers, and leaves pages that set their own status (a form answered with 422) and JSON errors alone. The template gets an ocre::ErrorPage: error.status ({{ error.status.as_u16() }}), error.message and, for a 422, error.fields:

{% extends "layout.html" %}

{% block title %}{{ error.message }}{% endblock %}

{% block content %}
<h1>{{ error.message }}</h1>
{% if !error.fields.is_empty() %}
<ul class="errors">
  {% for field in error.fields %}<li>{{ field.full_message() }}</li>{% endfor %}
</ul>
{% endif %}
<p>Error {{ error.status.as_u16() }}. <a href="/">Back to the home page</a></p>
{% endblock %}

curl -s -w '\n%{http_code}\n' http://localhost:8787/posts/999

...<h1>Not found</h1>...
404

A 500 shows Internal server error; the cause goes to the Worker logs only. If the template itself fails, the plain page (<h1>500</h1><p>Internal server error</p>) is sent and the failure logged. Requests refused by Ocre’s own middleware (a cross-site form post, an unknown host) keep a short text answer. A Rust panic aborts the Worker instance, which Cloudflare answers with its own 500 page: return Err instead of unwrap() in handlers. API-only apps have a JSON fallback: {"error": {"status": 404, "message": "Not found"}}.

The scaffold controller

src/posts.rs, as generated by the blog starter, in order.

The form struct holds what the browser submits, as text, so a typo in a number becomes a field error rather than a rejected request:

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default)]
pub struct PostForm {
    pub title: String,
    pub body: String,
    /// Unchecked checkboxes are not submitted.
    pub published: bool,
}

from_record fills it for the edit page; to_new and to_changes parse it into the model’s NewPost and PostChanges and run the model’s validate() (see Validations).

One template struct per page, each bound to a file in templates/posts/:

#[derive(Template)]
#[template(path = "posts/index.html")]
struct IndexView {
    flash: Flash,
    page: Page,
    posts: Vec<Post>,
}

Reading handlers call the model and render:

async fn index(State(ctx): State<Ctx>, flash: Flash, page: Page) -> Result<Html<String>> {
    render(&IndexView { flash, page, posts: post::all(&ctx, page).await? })
}

async fn show(State(ctx): State<Ctx>, flash: Flash, Path(id): Path<i64>) -> Result<Html<String>> {
    render(&ShowView { flash, post: post::find(&ctx, id).await?.or_404()? })
}

The index page links to the neighbouring pages with Page::previous and Page::next, which guesses from a full page that more rows follow (no COUNT(*), which would read every row):

<nav class="pagination">
  {% if let Some(previous) = page.previous() %}<a href="?{{ previous.query() }}" rel="prev">Previous</a>{% endif %}
  {% if let Some(next) = page.next(posts.len()) %}<a href="?{{ next.query() }}" rel="next">Next</a>{% endif %}
</nav>

Writing handlers follow Rails’ pattern: on success, set a flash and redirect; on Error::Invalid, render the form again with status 422 and the typed values; any other error goes up with its status:

async fn create(State(ctx): State<Ctx>, session: Session, Form(form): Form<PostForm>) -> Result<Response> {
    let created = match form.to_new() {
        Ok(new) => post::create(&ctx, new).await,
        Err(err) => Err(err),
    };
    match created {
        Ok(record) => {
            session.flash("notice", "Post was successfully created.")?;
            Ok(Redirect::to(&paths::show(record.id)).into_response())
        }
        Err(Error::Invalid(errors)) => {
            Ok((StatusCode::UNPROCESSABLE_ENTITY, render(&NewView { form, errors })?).into_response())
        }
        Err(err) => Err(err),
    }
}

curl -si -X POST http://localhost:8787/posts -d 'title=Third&body=Hello+again'

HTTP/1.1 303 See Other
Location: /posts/3
Set-Cookie: _ocre_session=...; HttpOnly; SameSite=Lax; Path=/
...

The next GET /posts/3 with that cookie shows <p class="notice">Post was successfully created.</p>, and the flash is gone after it. delete returns Error::NotFound when the model’s delete returns false.

A controller of your own

A page listing unpublished posts, with a search box, in a new module. Templates can also be inline (source = "...", ext = "html"); files under templates/ are usual for anything longer:

// src/drafts.rs
use askama::Template;
use axum::{
    Router,
    extract::{Path, Query, State},
    response::Html,
    routing::get,
};
use ocre::{Ctx, Flash, OptionExt, Page, Result, params, render};
use serde::Deserialize;

use crate::models::post::Post;

pub fn routes() -> Router<Ctx> {
    Router::new().route("/drafts", get(index)).route("/drafts/{id}", get(show))
}

/// `?q=` filters by title; `?limit=&offset=` come from `Page`.
#[derive(Deserialize)]
struct Search {
    #[serde(default)]
    q: String,
}

#[derive(Template)]
#[template(
    source = r#"{% extends "layout.html" %}
{% block title %}Drafts{% endblock %}
{% block content %}
<h1>Drafts</h1>
{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
<form method="get"><input name="q" value="{{ q }}"> <button>Search</button></form>
<ul>
{% for post in posts %}<li><a href="/drafts/{{ post.id }}">{{ post.title }}</a></li>{% endfor %}
</ul>
{% endblock %}"#,
    ext = "html"
)]
struct IndexView {
    flash: Flash,
    q: String,
    posts: Vec<Post>,
}

#[derive(Template)]
#[template(
    source = r#"{% extends "layout.html" %}
{% block title %}{{ post.title }}{% endblock %}
{% block content %}<h1>{{ post.title }}</h1><p>{{ post.body }}</p>{% endblock %}"#,
    ext = "html"
)]
struct ShowView {
    post: Post,
}

async fn index(
    State(ctx): State<Ctx>,
    flash: Flash,
    page: Page,
    Query(search): Query<Search>,
) -> Result<Html<String>> {
    let posts = ctx
        .db()?
        .all(
            "SELECT * FROM posts WHERE published = 0 AND title LIKE ?1 ORDER BY id DESC LIMIT ?2 OFFSET ?3",
            params![format!("%{}%", search.q), page.limit, page.offset],
        )
        .await?;
    render(&IndexView { flash, q: search.q, posts })
}

async fn show(State(ctx): State<Ctx>, Path(id): Path<i64>) -> Result<Html<String>> {
    let post: Post = ctx
        .db()?
        .first("SELECT * FROM posts WHERE id = ?1 AND published = 0", params![id])
        .await?
        .or_404()?;
    render(&ShowView { post })
}

Register it (mod drafts; and .merge(drafts::routes()) in src/lib.rs), then with the seeded posts “Hello” (published) and “Draft”:

curl -s 'http://localhost:8787/drafts?q=Dra'

...
  <main>
<h1>Drafts</h1>

<form method="get"><input name="q" value="Dra"> <button>Search</button></form>
<ul>
<li><a href="/drafts/2">Draft</a></li>
</ul>
</main>
...

GET /drafts/1 (published) answers the 404 page, and GET /drafts/abc the 400 page (Bad Request). The SQL is here to keep the example in one file; in an app, put it in src/models/post.rs as a drafts(ctx, term, page) function (see Models).

Middleware

Middleware wraps handlers to run code before and after them. ocre::serve always runs, outermost first: security headers, host authorization, CORS, cross-origin request protection, and the session cookie (see Sessions, flash and security). The app adds its own with .layer(..) on the whole router or .route_layer(..) on the routes declared so far; the last layer added runs first. axum’s middleware::from_fn turns an async fn into a layer; its arguments are extractors followed by the request and next. ocre::serve puts the Ctx in the request’s extensions, so a middleware reaches the bindings with Extension<Ctx>:

use axum::{
    Extension, Router,
    extract::Request,
    http::{HeaderValue, StatusCode},
    middleware::{self, Next},
    response::{IntoResponse, Response},
    routing::get,
};
use ocre::{Ctx, RequestId};

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/admin/stats", get(|| async { "stats" }))
        // Only the routes above: an admin check (Rails' `before_action` on a controller).
        .route_layer(middleware::from_fn(admin_only))
        .route("/status", get(|| async { "OK" }))
        // Every route of this router.
        .layer(middleware::from_fn(request_id_header))
        .layer(middleware::from_fn(maintenance))
}

async fn admin_only(req: Request, next: Next) -> Response {
    let is_admin = req.headers().get("x-admin-token").is_some_and(|token| token == "let-me-in");
    if !is_admin {
        return StatusCode::FORBIDDEN.into_response();
    }
    next.run(req).await
}

/// Echoes the request id so a user can quote it in a bug report (Loco's `request_id`).
async fn request_id_header(RequestId(id): RequestId, req: Request, next: Next) -> Response {
    let mut response = next.run(req).await;
    if let Ok(value) = HeaderValue::from_str(&id) {
        response.headers_mut().insert("x-request-id", value);
    }
    response
}

/// Maintenance mode: `MAINTENANCE: bindings.text("on")` in cloudflare.config.ts (or
/// in the dashboard) answers 503 everywhere but /up, without a new build.
async fn maintenance(Extension(ctx): Extension<Ctx>, req: Request, next: Next) -> Response {
    let on = ctx.env().var("MAINTENANCE").is_ok_and(|value| value.to_string() == "on");
    if on && req.uri().path() != "/up" {
        let headers = [("retry-after", "600")];
        return (StatusCode::SERVICE_UNAVAILABLE, headers, "Down for maintenance, back soon.").into_response();
    }
    next.run(req).await
}

To turn away outdated browsers (Rails’ allow_browser versions: :modern), add ocre::security::AllowBrowser to the page routes. modern() allows Safari 17.2, Chrome and Edge 120, Firefox 121 and Opera 106 and later, and refuses Internet Explorer; older browsers get 406 Not Acceptable and a short “please upgrade your browser” page. Requests without a User-Agent, or from clients that are not browsers (bots, curl, uptime checks), always pass. It reads one header: no binding call, microseconds of CPU.

use axum::{Router, routing::get};
use ocre::{Ctx, security::{AllowBrowser, Browser}};

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/dashboard", get(|| async { "dashboard" }))
        // Rails' `allow_browser versions: :modern`, with Safari 16.4 accepted too.
        .route_layer(AllowBrowser::modern().minimum(Browser::Safari, 16, 4))
        // Declared after the layer: API clients are never turned away.
        .route("/api/status", get(|| async { "OK" }))
}

Replace the page with .page(html) (an HTML string, e.g. a rendered template).

Rate limiting per action uses the Workers Rate Limiting binding through ocre::security::rate_limit (see Security). Loco’s and Rails’ other middleware map to the platform:

Static files and the health check

Files in public/ (CSS, images, robots.txt, favicon.ico) are served by Workers Static Assets before the Worker runs: they cost no Worker request and no CPU. See Assets for caching, CSS and JavaScript tooling.

GET /up answers 200 OK with the body OK whenever the Worker runs, like Rails’ /up; point uptime monitors at it. Keep it free of database queries:

curl -si http://localhost:8787/up

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
content-security-policy: default-src 'self'; script-src 'self' https://unpkg.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; object-src 'none'; base-uri 'self'; frame-ancestors 'self'
permissions-policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-permitted-cross-domain-policies: none
x-xss-protection: 0

OK

See also

• Views, helpers and forms: templates, layouts, partials, view helpers and forms
• htmx: boosted navigation, partial responses, inline editing
• Assets: CSS, JavaScript and images
• Models and migrations: the functions controllers call
• Validations: errors and form re-rendering
• JSON APIs and GraphQL: ocre g api, ApiResult, Json
• Sessions, flash and security: sessions, flash, CSRF, CORS, headers
• Authentication: CurrentUser and protected pages
• Realtime: live updates with htmx and WebSockets
• Generators, CLI commands
• API index and the rustdoc

Views, helpers and forms

Views in Ocre are askama templates compiled into the Worker: a template is a Rust struct whose fields are the template’s variables, so a typo in a variable name or a missing value is a compile error, not a blank page in production. This page covers layouts and partials, the view helpers (numbers, dates, text), forms with validation errors, and responses in other formats (XML, CSV, plain text). Interactivity with htmx has its own page, htmx.

Before you start

• A full-stack app from ocre new (API-only apps have no templates). The examples use the blog starter (ocre new blog --starter blog), whose Post has title, body, published, created_at and updated_at.
• Rendering is plain string building inside the Worker: a normal page takes a fraction of a millisecond of the free plan’s 10 ms of CPU per request, and costs no binding call. Templates are compiled in, so ocre dev rebuilds the Worker to show a change (save a .rs file under src/ if only a template changed).

Templates

A view is a struct deriving askama::Template, rendered with ocre::render, which returns Result<Html<String>>:

#[derive(Template)]
#[template(path = "posts/show.html")]
struct ShowView {
    flash: Flash,
    post: Post,
}

async fn show(State(ctx): State<Ctx>, flash: Flash, Path(id): Path<i64>) -> Result<Html<String>> {
    render(&ShowView { flash, post: post::find(&ctx, id).await?.or_404()? })
}

path = "posts/show.html" is a file under templates/. Short templates can live in the Rust file with source = "..." and ext = "html" (the extension decides escaping: html escapes, txt does not). Rails’ conventions map to askama as follows:

Layouts

templates/layout.html is the application layout. Pages extend it and fill its blocks, the equivalent of yield and content_for:

{% extends "layout.html" %}

{% block title %}Post {{ post.id }}{% endblock %}

{% block content %}
<h1>{{ post.title }}</h1>
{% endblock %}

A block the page does not fill keeps the layout’s default ({% block title %}blog{% endblock %} in the layout). Add named regions (Rails’ yield :sidebar) by adding blocks to the layout: {% block sidebar %}{% endblock %}. A section layout (Rails’ nested layouts) is a template that extends layout.html and defines new blocks for its pages:

{# templates/admin/layout.html #}
{% extends "layout.html" %}
{% block content %}
<nav><a href="/admin/posts">Posts</a> · <a href="/admin/users">Users</a></nav>
{% block admin %}{% endblock %}
{% endblock %}

Admin pages then {% extends "admin/layout.html" %} and fill admin. A page that needs no layout (an email, a fragment for htmx) simply does not extend one.

templates/error.html is the page for errors (404, 422, 500…); see Controllers.

Partials and components

{% include "posts/_form.html" %} inserts another template, which sees the including template’s variables (Rails’ partials; the scaffold’s new.html and edit.html share _form.html this way). To give a partial a differently named variable (Rails’ locals: and as:), bind it first with {% let %}:

{% for comment in post_comments %}
  {% let item = comment %}
  {% include "comments/_comment.html" %}
{% endfor %}

Macros are components with arguments (Rails’ partials with locals, view components):

{% macro field(name, label, value, errors) %}
<label>{{ label }} <input name="{{ name }}" value="{{ value }}"></label>
{% for error in errors %}{% if error.field == name %}<span class="errors">{{ error.message }}</span>{% endif %}{% endfor %}
{% endmacro %}

{% call field("title", "Title", form.title, errors) %}{% endcall %}

{% call %} needs its {% endcall %}; anything between the two is the caller body, which the macro prints with {{ caller() }} (a block component, like a Rails partial rendered with a block). Macros defined in another file are imported with {% import "forms.html" as forms %} and called with {% call forms::field(...) %}{% endcall %}.

Collections

use askama::Template;
use axum::{extract::State, response::Html};
use ocre::{Ctx, Page, Result, filters, render};

use crate::models::post::{self, Post};

#[derive(Template)]
#[template(
    source = r#"{% extends "layout.html" %}
{% block content %}
<ol>
{% for post in posts %}
  <li class="{{ ocre::helpers::class_names([("post", true), ("draft", !post.published)]) }}">
    <a href="/posts/{{ post.id }}">{{ post.title|truncate(60) }}</a>
    · {{ post.body|wordcount }} words · {{ post.created_at|time_ago_in_words }} ago
  </li>
  {% if !loop.last %}<hr>{% endif %}
{% else %}
  <li>No posts yet.</li>
{% endfor %}
</ol>
{% endblock %}"#,
    ext = "html"
)]
struct IndexView {
    posts: Vec<Post>,
}

async fn index(State(ctx): State<Ctx>, page: Page) -> Result<Html<String>> {
    render(&IndexView { posts: post::all(&ctx, page).await? })
}

View helpers

ocre::helpers has Rails’ formatting helpers as plain functions, and ocre::filters exposes them to templates as askama filters. askama finds custom filters in a module named filters where the template struct is defined, so a controller brings them in with use ocre::filters; (as the example above does):

askama’s own filters cover the rest: truncate(n), wordcount, linebreaks / linebreaksbr / paragraphbreaks (simple_format), pluralize ({{ n }} post{{ n|pluralize }}), filesizeformat, urlencode, upper, lower, title, capitalize, json, fmt ({{ ratio|fmt("{:.2}") }}) and format ({{ "{:?}"|format(value) }}, Rails’ debug inside a <pre>). Time filters read Unix seconds or the TEXT timestamps D1 stores (2026-09-29 14:05:00, UTC); number filters read any number. Other text passes through unchanged. They are English; translated text comes from Translations.

Your own helpers (Rails’ app/helpers) are either methods on the view struct, called as {{ self.method() }} or {{ method() }}, or filters. To add filters, make the filters module yours and re-export Ocre’s:

use askama::Template;

mod filters {
    pub use ocre::filters::*;

    /// `{{ post.title|shout }}`: `HELLO!`.
    #[askama::filter_fn]
    pub fn shout(value: impl std::fmt::Display, _: &dyn askama::Values) -> askama::Result<String> {
        Ok(format!("{}!", value.to_string().to_uppercase()))
    }
}

#[derive(Template)]
#[template(source = "<h1>{{ title|shout }}</h1><p>{{ views|number_with_delimiter }} views</p>", ext = "html")]
struct Banner {
    title: String,
    views: i64,
}

impl Banner {
    /// A helper method, called as `{{ reading_time() }}` in the template.
    fn reading_time(&self) -> String {
        format!("{} min", self.views / 200 + 1)
    }
}

Links and buttons are HTML: <a href="{{ paths::show(post.id) }}"> (the scaffold’s path helpers replace link_to and url_for), a <form method="post"> with a button replaces button_to, <a href="mailto:{{ user.email }}"> replaces mail_to. There is no tag builder: templates are HTML. sanitize and strip_tags for user-supplied HTML are in ocre::security (see Security).

Forms

A form posts to a handler that deserializes it into a struct with axum’s Form extractor. The scaffold’s pattern keeps every field as text until it is validated, so a typo in a number becomes a field error, and renders the form again with status 422 and the typed values when validation fails:

use askama::Template;
use axum::{
    Form, Router,
    http::StatusCode,
    response::{IntoResponse, Redirect, Response},
    routing::get,
};
use ocre::{FieldError, Result, Validator, render};
use serde::Deserialize;

pub fn routes() -> Router<ocre::Ctx> {
    Router::new().route("/newsletter", get(new).post(create))
}

/// What the form submits. `#[serde(default)]`: a missing field is empty and
/// an unchecked checkbox is `false`.
#[derive(Debug, Default, Deserialize)]
#[serde(default)]
struct SignupForm {
    email: String,
    frequency: String,
    age: String,
    terms: bool,
}

#[derive(Template)]
#[template(
    source = r#"{% extends "layout.html" %}
{% macro errors_for(errors, name) %}{% for error in errors %}{% if error.field == name %}<small class="errors">{{ error.message }}</small>{% endif %}{% endfor %}{% endmacro %}
{% block content %}
<form action="/newsletter" method="post">
  <label>Email <input type="email" name="email" value="{{ form.email }}" required></label>
  {% call errors_for(errors, "email") %}{% endcall %}
  <label>Frequency
    <select name="frequency">
      {% for (value, label) in self.frequencies() %}
      <option value="{{ value }}"{% if self.chosen(value) %} selected{% endif %}>{{ label }}</option>
      {% endfor %}
    </select>
  </label>
  <label>Age <input type="number" name="age" value="{{ form.age }}"></label>
  {% call errors_for(errors, "age") %}{% endcall %}
  <label><input type="checkbox" name="terms" value="true"{% if form.terms %} checked{% endif %}> I accept the terms</label>
  {% call errors_for(errors, "terms") %}{% endcall %}
  <button type="submit">Subscribe</button>
</form>
{% endblock %}"#,
    ext = "html"
)]
struct SignupView {
    form: SignupForm,
    errors: Vec<FieldError>,
}

impl SignupView {
    /// The choices of the select (a helper method of the view).
    fn frequencies(&self) -> [(&'static str, &'static str); 2] {
        [("weekly", "Every week"), ("monthly", "Every month")]
    }

    /// Whether `value` is the submitted frequency.
    fn chosen(&self, value: &str) -> bool {
        self.form.frequency == value
    }
}

async fn new() -> Result<Response> {
    Ok(render(&SignupView { form: SignupForm::default(), errors: vec![] })?.into_response())
}

async fn create(Form(form): Form<SignupForm>) -> Result<Response> {
    let mut v = Validator::new();
    v.email("email", &form.email);
    v.inclusion("frequency", &form.frequency, &["weekly", "monthly"]);
    let age: Option<i64> = v.optional_number("age", &form.age);
    if let Some(age) = age {
        v.greater_than_or_equal_to("age", age, 13);
    }
    v.acceptance("terms", form.terms);
    if !v.is_valid() {
        let errors = v.errors().to_vec();
        return Ok((StatusCode::UNPROCESSABLE_ENTITY, render(&SignupView { form, errors })?).into_response());
    }
    // ...store the subscription...
    Ok(Redirect::to("/").into_response())
}

Rails’ form helpers map to HTML inputs:

axum’s Form reads one value per name. For a list of values or of records in one form (Rails’ tag_ids[], fields_for and accepts_nested_attributes_for), use ocre::NestedForm, which reads Rails’ bracketed names.

Lists and nested records in one form

ocre::NestedForm<T> is axum’s Form with Rails’ naming rules: order[note] fills the field note of the struct in order, repeated tag_ids[] make a Vec, and lines[0][qty], lines[1][qty] make a Vec of structs in index order. A name sent twice keeps the last value, so the hidden 0 before a checkbox works as in Rails, and numbers and booleans are parsed from the text (1, true, on are true; empty is false, or None for an Option). A body that does not fit T is a 400 naming the field.

Nested attributes are plain code: the form sends each line with its id (empty for a new one) and a _destroy checkbox, and the handler turns them into statements that batch applies together, all or none:

use axum::{Router, extract::{Path, State}, response::Redirect, routing::post};
use ocre::{Ctx, NestedForm, Result, Statement, Validator, params};
use serde::Deserialize;

pub fn routes() -> Router<Ctx> {
    Router::new().route("/orders/{id}/lines", post(update_lines))
}

/// `<input name="lines[0][id]" type="hidden" value="7">`,
/// `<input name="lines[0][product]">`, `<input name="lines[0][qty]" type="number">`,
/// `<input name="lines[0][_destroy]" type="checkbox" value="1">`; then `lines[1][...]`...
#[derive(Deserialize)]
struct LinesForm {
    #[serde(default)]
    lines: Vec<LineFields>,
}

#[derive(Deserialize)]
struct LineFields {
    id: Option<i64>,
    product: String,
    qty: i64,
    #[serde(default, rename = "_destroy")]
    destroy: bool,
}

async fn update_lines(
    State(ctx): State<Ctx>,
    Path(order_id): Path<i64>,
    NestedForm(form): NestedForm<LinesForm>,
) -> Result<Redirect> {
    let mut v = Validator::new();
    let mut statements = Vec::new();
    for line in form.lines {
        match (line.id, line.destroy) {
            (Some(id), true) => statements
                .push(Statement::new("DELETE FROM lines WHERE id = ?1 AND order_id = ?2", params![id, order_id])),
            // Rails' `reject_if: :all_blank`: an empty new line is ignored.
            (None, _) if line.product.trim().is_empty() => {}
            (id, _) => {
                v.required("product", &line.product);
                v.greater_than("qty", line.qty, 0);
                statements.push(match id {
                    Some(id) => Statement::new(
                        "UPDATE lines SET product = ?1, qty = ?2 WHERE id = ?3 AND order_id = ?4",
                        params![line.product, line.qty, id, order_id],
                    ),
                    None => Statement::new(
                        "INSERT INTO lines (order_id, product, qty) VALUES (?1, ?2, ?3)",
                        params![order_id, line.product, line.qty],
                    ),
                });
            }
        }
    }
    v.finish()?;
    ctx.db()?.batch(statements).await?;
    Ok(Redirect::to(&format!("/orders/{order_id}")))
}

Every statement names the order, so a form cannot touch another order’s lines. A search form with filter[status]=open in the query string uses the same rules: NestedForm reads the query on GET.

Other formats

A template with ext = "xml" escapes for XML, which covers RSS and Atom feeds (Rails’ Builder templates and atom_feed):

use askama::Template;
use axum::{extract::State, http::header, response::IntoResponse};
use ocre::{Ctx, Page, Result};

use crate::models::post::{self, Post};

#[derive(Template)]
#[template(
    source = r#"<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Blog</title>
  <id>https://blog.example/</id>
  <updated>{% if let Some(post) = posts.first() %}{{ post.updated_at|strftime("%FT%TZ") }}{% endif %}</updated>
  {% for post in posts %}
  <entry>
    <id>https://blog.example/posts/{{ post.id }}</id>
    <title>{{ post.title }}</title>
    <updated>{{ post.updated_at|strftime("%FT%TZ") }}</updated>
    <content type="text">{{ post.body }}</content>
  </entry>
  {% endfor %}
</feed>"#,
    ext = "xml"
)]
struct Feed {
    posts: Vec<Post>,
}

mod filters {
    pub use ocre::filters::*;
}

async fn feed(State(ctx): State<Ctx>) -> Result<impl IntoResponse> {
    let posts = post::all(&ctx, Page::new(20, 0)?).await?;
    let xml = Feed { posts }.render()?;
    Ok(([(header::CONTENT_TYPE, "application/atom+xml; charset=utf-8")], xml))
}

Plain text is a String (text/plain), JavaScript is ([(header::CONTENT_TYPE, "text/javascript")], body), and a CSV or any generated file goes out with ocre::storage::send_data (see Controllers). One handler answering HTML or JSON uses ocre::Format (Rails’ respond_to, see Controllers).

Structured data, sitemap and llms.txt

ocre::seo covers what search engines and language models read besides the page itself:

• ocre::seo::json_ld(&data) turns any serializable value (serde_json::json!({...}) or a struct) into <script type="application/ld+json">...</script> for the page’s <head>: Organization, FAQPage, BreadcrumbList… The JSON is escaped for HTML (<, >, & become \u003c, \u003e, \u0026), so a value containing </script> cannot end the element and the data parses back unchanged. In a template: {{ ocre::seo::json_ld(&faq)|safe }}.
• ocre::seo::Sitemap builds /sitemap.xml (add, or add_localized for a page in every locale with hreflang alternates and x-default; 50,000 URLs per file). It is a response: return it from a handler.
• ocre::seo::LlmsTxt builds /llms.txt (llmstxt.org): a title, a one-line summary, optional details and sections of links.

ocre g seo writes src/seo.rs with both routes and PAGES, the list of public pages (path, title, description) they share; records with a page of their own (posts, products) go in sitemap with their updated_at as lastmod. The base URL comes from APP_URL (added to .dev.vars; set it in worker.env for production), and public/robots.txt should name the sitemap (Sitemap: https://<your host>/sitemap.xml). For translated pages, see canonical and hreflang.

Localized views

Translated text comes from locales/*.yml through the I18n extractor, passed to the view as a field ({{ i18n.t("posts.title") }}; see Translations). For pages whose whole markup differs per language (Rails’ show.fr.html.erb), define one view struct per language and pick it with match i18n.locale().

See also

• htmx: boosted navigation, partial responses, inline editing, live validation
• Controllers and routing: routes, paths, requests, error pages
• Validations: model rules and error messages
• Assets: CSS, JavaScript and images in public/
• The askama book for the full template syntax

htmx

Ocre pages get their interactivity from htmx: HTML attributes send requests, and the HTML fragments handlers answer are swapped into the page. There is no JavaScript to write or build for the common cases, every page still works without JavaScript, and handlers stay ordinary axum handlers rendering askama templates. This page covers boosted navigation (Rails’ Turbo Drive), partial responses (Turbo Frames), inline editing, validation as you type, live search, infinite scroll and redirects from htmx requests.

Before you start

• A full-stack app from ocre new; its templates/layout.html loads htmx 2 from unpkg and turns on boosted navigation. The examples use the blog starter (ocre new blog --starter blog).
• Every htmx request is a normal Worker request: it counts toward the free plan’s 100,000 requests a day and 10 ms of CPU each. Swapping a fragment instead of a page saves bytes and rendering time, not requests: trigger requests on user actions (click, change, revealed, delay:300ms), not on timers.

Boosted navigation

The generated layout puts hx-boost="true" on <body>: links and forms load the next page with an AJAX request and swap its <body> without a full reload, then update the URL and history (Rails’ Turbo Drive). Redirects are followed, so the scaffold’s “create, then redirect to the record” works unchanged. Without JavaScript, the same links and forms work as usual.

<meta name="htmx-config" content='{"responseHandling": [{"code": "204", "swap": false}, {"code": "...", "swap": true}]}'>
...
<body hx-boost="true">

The htmx-config line makes htmx swap error responses too (by default it ignores 4xx and 5xx bodies), so a form answered with 422 and its errors, or the error page of a 404, shows up like any page. Opt a link or form out with hx-boost="false": the scaffold does it for file links, so the browser downloads or displays the file itself.

hx-confirm asks before sending (Rails’ data-turbo-confirm); the scaffold’s delete button uses it:

<form action="{{ paths::delete(post.id) }}" method="post" hx-boost="true" hx-confirm="Delete this post?">
  <button type="submit">Delete post</button>
</form>

Partial responses

Every htmx request carries HX-Request: true; the ocre::Htmx extractor reads it, so one handler can answer a fragment to htmx and a redirect to a plain form post (Rails’ Turbo Frames). A “Publish” button that updates the post’s status in place:

// src/publishing.rs
use askama::Template;
use axum::{
    Router,
    extract::{Path, State},
    response::{IntoResponse, Redirect, Response},
    routing::post,
};
use ocre::{Ctx, Htmx, OptionExt, Result, Session, render};

use crate::models::post::{self, Post, PostChanges};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/posts/{id}/publish", post(publish))
}

/// The fragment htmx swaps into the page: the same element, updated.
#[derive(Template)]
#[template(
    source = r#"<span id="post-{{ post.id }}-status">{% if post.published %}Published{% else %}Draft{% endif %}</span>"#,
    ext = "html"
)]
struct StatusPartial {
    post: Post,
}

async fn publish(
    State(ctx): State<Ctx>,
    Htmx(is_htmx): Htmx,
    session: Session,
    Path(id): Path<i64>,
) -> Result<Response> {
    let changes = PostChanges { published: Some(true), ..Default::default() };
    let post = post::update(&ctx, id, changes).await?.or_404()?;
    if is_htmx {
        // htmx request: answer with the fragment only.
        return Ok(render(&StatusPartial { post })?.into_response());
    }
    // Plain form post (JavaScript disabled): full redirect, as usual.
    session.flash("notice", "Post was published.")?;
    Ok(Redirect::to(&format!("/posts/{}", post.id)).into_response())
}

In templates/posts/show.html, the status and a form that htmx takes over:

<p><span id="post-{{ post.id }}-status">{% if post.published %}Published{% else %}Draft{% endif %}</span></p>
<form action="/posts/{{ post.id }}/publish" method="post"
      hx-post="/posts/{{ post.id }}/publish" hx-target="#post-{{ post.id }}-status" hx-swap="outerHTML">
  <button type="submit">Publish</button>
</form>

curl -s -X POST http://localhost:8787/posts/2/publish -H 'HX-Request: true'

<span id="post-2-status">Published</span>

Without the header, the same request gets 303 See Other with Location: /posts/2. Keep fragments in their own template (a _status.html file, or an inline template as above) and reuse them from the full page, so both render the same markup. htmx requests from your own pages are same-origin, so Ocre’s CSRF check lets them through with no token (see Security).

Inline editing

Click a title to edit it in place; save or cancel swaps the title back. The same TitleForm fragment comes back with status 422 and the errors when the title is invalid:

// src/titles.rs
use askama::Template;
use axum::{
    Form, Router,
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Response},
    routing::get,
};
use ocre::{Ctx, Error, FieldError, OptionExt, Result, render};
use serde::Deserialize;

use crate::models::post::{self, PostChanges};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/posts/{id}/title", get(show).post(update)).route("/posts/{id}/title/edit", get(edit))
}

#[derive(Template)]
#[template(
    source = r#"<h1 id="title" hx-get="/posts/{{ id }}/title/edit" hx-swap="outerHTML" title="Click to edit">{{ title }}</h1>"#,
    ext = "html"
)]
struct TitleView {
    id: i64,
    title: String,
}

#[derive(Template)]
#[template(
    source = r##"<form id="title" hx-post="/posts/{{ id }}/title" hx-swap="outerHTML">
  <input name="title" value="{{ title }}" autofocus>
  {% for error in errors %}<small class="errors">{{ error.message }}</small>{% endfor %}
  <button type="submit">Save</button>
  <button type="button" hx-get="/posts/{{ id }}/title" hx-target="#title" hx-swap="outerHTML">Cancel</button>
</form>"##,
    ext = "html"
)]
struct TitleForm {
    id: i64,
    title: String,
    errors: Vec<FieldError>,
}

#[derive(Deserialize)]
struct TitleParams {
    title: String,
}

async fn show(State(ctx): State<Ctx>, Path(id): Path<i64>) -> Result<Response> {
    let post = post::find(&ctx, id).await?.or_404()?;
    Ok(render(&TitleView { id, title: post.title })?.into_response())
}

async fn edit(State(ctx): State<Ctx>, Path(id): Path<i64>) -> Result<Response> {
    let post = post::find(&ctx, id).await?.or_404()?;
    Ok(render(&TitleForm { id, title: post.title, errors: vec![] })?.into_response())
}

async fn update(State(ctx): State<Ctx>, Path(id): Path<i64>, Form(params): Form<TitleParams>) -> Result<Response> {
    let changes = PostChanges { title: Some(params.title.clone()), ..Default::default() };
    let checked = changes.validate().finish();
    let updated = match checked {
        Ok(()) => post::update(&ctx, id, changes).await,
        Err(err) => Err(err),
    };
    match updated {
        Ok(post) => Ok(render(&TitleView { id, title: post.or_404()?.title })?.into_response()),
        Err(Error::Invalid(errors)) => {
            let form = TitleForm { id, title: params.title, errors };
            Ok((StatusCode::UNPROCESSABLE_ENTITY, render(&form)?).into_response())
        }
        Err(err) => Err(err),
    }
}

The show page includes the title fragment: <h1 id="title" hx-get="/posts/{{ post.id }}/title/edit" hx-swap="outerHTML">{{ post.title }}</h1>.

Validation as you type

A field checks itself when it loses focus: htmx posts the whole form to a validation endpoint (hx-include="closest form") and swaps the field’s message. The endpoint runs the model’s own rules, so the messages are the ones the form shows on submit:

use askama::Template;
use axum::{Form, extract::Path, response::Html};
use ocre::{FieldError, Result, render};
use serde::Deserialize;

use crate::models::post::NewPost;

#[derive(Default, Deserialize)]
#[serde(default)]
struct Draft {
    title: String,
    body: String,
    published: bool,
}

#[derive(Template)]
#[template(source = "{% for error in errors %}{{ error.message }} {% endfor %}", ext = "html")]
struct FieldMessages {
    errors: Vec<FieldError>,
}

/// POST /posts/validate/{field}: the messages of one field, empty when it is valid.
async fn validate(Path(field): Path<String>, Form(draft): Form<Draft>) -> Result<Html<String>> {
    let new = NewPost { title: draft.title, body: draft.body, published: draft.published };
    let errors = new.validate().errors().iter().filter(|error| error.field == field).cloned().collect();
    render(&FieldMessages { errors })
}

<label>Title
  <input name="title" value="{{ form.title }}"
         hx-post="/posts/validate/title" hx-include="closest form" hx-trigger="blur changed"
         hx-target="next .field-error">
</label>
<small class="field-error errors"></small>

Register it with .route("/posts/validate/{field}", post(validate)). Checks that need the database (uniqueness) stay in create, where the form shows them after submit; a validation endpoint that queries D1 costs rows read on every blur.

Live search

hx-trigger="input changed delay:300ms" waits for a pause in typing, so a search costs one request per pause, not per keystroke:

<input type="search" name="q" placeholder="Search posts"
       hx-get="/posts/search" hx-trigger="input changed delay:300ms, search" hx-target="#results">
<ul id="results"></ul>

The handler returns the <li> rows only. Escape the user’s text in LIKE patterns with ocre::escape_like (see Models).

Infinite scroll

The last item of a page asks for the next page when it scrolls into view (hx-trigger="revealed"), and the answer is inserted after it. The same handler serves the full page to a first visit and the items only to htmx:

use askama::Template;
use axum::{extract::State, response::Html};
use ocre::{Ctx, Htmx, Page, Result, render};

use crate::models::post::{self, Post};

#[derive(Template)]
#[template(
    source = r#"{% for post in posts %}
<li{% if loop.last %}{% if let Some(next) = page.next(posts.len()) %} hx-get="/feed?{{ next.query() }}" hx-trigger="revealed" hx-swap="afterend"{% endif %}{% endif %}>{{ post.title }}</li>
{% endfor %}"#,
    ext = "html"
)]
struct Items {
    page: Page,
    posts: Vec<Post>,
}

#[derive(Template)]
#[template(source = r#"{% extends "layout.html" %}{% block content %}<ul>{{ items|safe }}</ul>{% endblock %}"#, ext = "html")]
struct FeedView {
    items: String,
}

/// GET /feed: 50 posts, then 50 more each time the last one scrolls into view.
async fn feed(State(ctx): State<Ctx>, Htmx(is_htmx): Htmx, page: Page) -> Result<Html<String>> {
    let posts = post::all(&ctx, page).await?;
    let Html(items) = render(&Items { page, posts })?;
    if is_htmx {
        return Ok(Html(items));
    }
    render(&FeedView { items })
}

items|safe is fine here: items is HTML askama rendered and escaped. Page::next guesses from a full page that more rows follow, without a COUNT(*) query (D1 bills every row a count reads). A classic “Previous / Next” navigation uses the same Page methods; the scaffold’s index pages have one.

Redirecting from an htmx request

htmx follows a 303 inside the request and swaps the result into the target, which is right for boosted navigation but wrong when an inline widget should end on another page. ocre::HxRedirect answers 200 with the HX-Redirect header, and htmx performs a full navigation:

use axum::response::{IntoResponse, Redirect, Response};
use ocre::{Htmx, HxRedirect};

/// After an inline "Create" in a modal, go to the new record's page.
async fn created(Htmx(is_htmx): Htmx) -> Response {
    let target = "/posts/7".to_owned();
    if is_htmx { HxRedirect(target).into_response() } else { Redirect::to(&target).into_response() }
}

Updating several parts of a page

A response can update elements outside its target with out-of-band swaps (Rails’ Turbo Streams over HTTP): any element with hx-swap-oob="true" and an id replaces the element with the same id. ocre::realtime sends the same kind of fragments over WebSockets to every open page (see Realtime).

<li id="post_7">Updated title</li>
<span id="post-count" hx-swap-oob="true">12 posts</span>

JavaScript beyond htmx

For behaviour htmx does not cover (a date picker, a chart), put the script in public/ and load it with <script src="/app.js" defer> (see Assets). Prefer script files to inline <script> blocks and onclick= attributes, which a Content Security Policy blocks (see Security). Rails’ Stimulus controllers map to small scripts that attach to data- attributes, or to a library such as Alpine.js loaded the same way.

See also

• Views, helpers and forms: templates, layouts, partials and forms
• Controllers and routing: handlers and extractors
• Realtime: live updates for every visitor
• The htmx reference for every attribute

Assets: CSS, JavaScript and images

Files in an Ocre app’s public/ directory are served by Workers Static Assets: Cloudflare answers them from its edge before the Worker runs, so they cost no Worker request, no CPU and no free-plan quota. There is no asset pipeline to run: a file in public/ is deployed as it is by ocre deploy, and build tools (Tailwind, esbuild) are optional steps that write into public/. This page covers serving, caching, CSS and JavaScript tooling, and single-page apps.

Before you start

• An app from ocre new. Its wrangler.config.ts has:

  assetsDirectory: "public",
  

• Free plan (September 2026): static asset requests are free and unlimited, and do not count toward the Worker’s 100,000 requests a day. Each file can be up to 25 MiB, and a Worker version up to 20,000 files (limits).

Serving files

public/robots.txt is /robots.txt, public/css/app.css is /css/app.css. A file wins over a route with the same path, and requests no file matches go to the Worker. Reference files by their path in templates:

<link rel="stylesheet" href="/css/app.css">
<script src="/js/app.js" defer></script>
<link rel="icon" href="/favicon.ico">
<img src="/images/logo.svg" alt="Logo" width="120" height="40">

These are Rails’ stylesheet_link_tag, javascript_include_tag, favicon_link_tag and image_tag: templates are HTML, and there is no digest to resolve (see Caching below). ocre dev serves public/ the same way, uncached, and picks up changes without a rebuild.

Uploaded files (avatars, attachments) do not belong in public/: they go to R2 (see File storage). Static asset responses do not pass through the Worker, so they do not get Ocre’s security headers; add headers to them with _headers below.

Caching

By default Cloudflare serves every static file with Cache-Control: public, max-age=0, must-revalidate and an ETag (a hash of the file). Browsers keep the file and revalidate it on each use; Cloudflare answers 304 Not Modified from its edge while the file is unchanged, and the new version as soon as you deploy. That is why Ocre needs no fingerprinted file names (Rails’ digests and .manifest.json): a deploy is never hidden by a stale cache, and a revalidation is a small free request.

For files that never change under a given name (vendored libraries with a version in the path, fonts), long caching saves even the revalidation. A public/_headers file sets headers per path; it is not served itself:

/vendor/*
  Cache-Control: public, max-age=31536000, immutable

/fonts/*
  Cache-Control: public, max-age=31536000, immutable
  Access-Control-Allow-Origin: *

Put a version in those paths (/vendor/chart-4.4.1.min.js) so a new version gets a new URL. Cloudflare compresses text files (HTML, CSS, JavaScript, JSON, SVG) with Brotli or gzip on its own, for static files and Worker responses alike; there is no compression to configure. Cloudflare is also the CDN: there is no asset_host to set.

CSS

Plain CSS in public/ needs no tooling. The generated layout keeps its few rules in a <style> block; move them to public/css/app.css as they grow.

Tailwind CSS runs without Node through its standalone CLI (Rails’ tailwindcss-rails). Download the binary for your platform from the Tailwind releases, then:

/* assets/app.css */
@import "tailwindcss";
@source "../templates";

./tailwindcss -i assets/app.css -o public/css/app.css --minify           # once
./tailwindcss -i assets/app.css -o public/css/app.css --watch            # while `ocre dev` runs

@source "../templates" makes Tailwind scan the askama templates for class names. To build CSS on every build, chain the command before the Worker build in wrangler.config.ts:

build: { command: './tailwindcss -i assets/app.css -o public/css/app.css --minify && cargo install -q "worker-build@^0.8" && worker-build ${OCRE_BUILD:---release}' },

Sass, PostCSS or Bootstrap builds (Rails’ cssbundling-rails) work the same way: any command that writes into public/, chained in build.command. Commit the tool’s configuration, not its output, if you build on deploy; commit the output if you would rather not install the tool on every machine.

JavaScript

htmx covers most interactivity with no JavaScript of your own (see htmx). The layout loads it from unpkg; to serve it yourself, download htmx.min.js into public/vendor/htmx-2.0.4.min.js and change the <script src>.

For your own scripts, plain ES modules need no bundler. An import map (Rails’ importmap-rails) maps bare names to files in public/:

<script type="importmap" nonce="{{ nonce }}">
{ "imports": { "chart.js": "/vendor/chart-4.4.1.js", "app": "/js/app.js" } }
</script>
<script type="module" src="/js/main.js"></script>

The generated Content-Security-Policy (content_security_policy() in src/lib.rs) allows scripts only from the app and https://unpkg.com, and no inline scripts, which includes inline import maps. Put the module entry point in a file (/js/main.js above, which starts with import "app";), and for the import map add NONCE to script_src and pass nonce: ocre::security::CspNonce from the handler to the template, as the page’s nonce field. A CDN other than unpkg goes into script_src too (see Security). To bundle npm packages (Rails’ jsbundling-rails), run esbuild, Bun or Rollup in build.command of wrangler.config.ts, writing into public/js/ (add the bundler to package.json with npm install --save-dev esbuild):

build: { command: 'npx esbuild assets/js/app.js --bundle --minify --outfile=public/js/app.js && cargo install -q "worker-build@^0.8" && worker-build ${OCRE_BUILD:---release}' },

Single-page apps

An app whose front end is a single-page app (React, Vue, Svelte) builds it into public/, serves JSON from the Worker (see JSON APIs), and lets client-side routes survive a reload with Cloudflare’s SPA fallback: every navigation request no file matches gets public/index.html.

// cloudflare.config.ts, in worker
assets: { notFoundHandling: "single-page-application" },

Requests to the API still reach the Worker: they are not navigations (fetch() sends Sec-Fetch-Mode: cors). Ocre’s generators produce htmx pages, not SPA code.

Rails comparison

See also

• Views, helpers and forms: templates and the layout
• htmx: interactivity without writing JavaScript
• Security: Content Security Policy for scripts and styles
• Deployment: what ocre deploy uploads

JSON APIs and GraphQL

The ocre g api generator writes a JSON REST resource under /api/<plural> whose handlers call the model, and --graphql exposes the same resource on /graphql; errors are JSON with the HTTP status, field errors included. This page covers the generated API, hand-written JSON endpoints, GraphQL, API-only apps and cross-origin clients.

Before you start

• An Ocre app from ocre new (full-stack or --api). The examples use ocre g api Product name:string^ price:float stock:integer? --graphql in the blog starter app, and ocre dev serving http://localhost:8787.
• Nothing else: no binding beyond the DB database every app has.
• Free plan (September 2026): 100,000 requests a day and 10 ms of CPU per request (Workers limits); D1 counts every row a query scans (D1 pricing), which is why lists are capped at 100 rows. GraphQL costs more, see GraphQL.

Generate an API

ocre g api Product name:string^ price:float stock:integer? --graphql

  create  migrations/0005_create_products.sql
  create  src/models/product.rs
  create  src/products_api.rs
  create  src/graphql.rs
  update  src/models/mod.rs
  update  src/lib.rs
  update  Cargo.toml

Next:
  ocre migrate
  ocre dev
  curl http://localhost:8787/api/products
  open http://localhost:8787/graphql

Without --graphql, only the migration, the model and src/products_api.rs are written and registered. When the model already exists (after ocre g model or ocre g scaffold), it is reused and only the API is added; the fields are still required on the command line, so pass the model’s. In an API-only app, ocre g scaffold does the same as ocre g api. See Generators.

Routes

The whole controller:

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/api/products", get(index).post(create))
        .route("/api/products/{id}", get(show).patch(update).delete(delete))
}

/// One page (`?limit=&offset=`), with a `Link` header to the next and previous pages.
async fn index(State(ctx): State<Ctx>, page: Page) -> ApiResult<(PageLinks, Json<Vec<Product>>)> {
    let products = product::all(&ctx, page).await?;
    Ok((page.links("/api/products", products.len()), Json(products)))
}

async fn show(State(ctx): State<Ctx>, Path(id): Path<i64>) -> ApiResult<Json<Product>> {
    Ok(Json(product::find(&ctx, id).await?.or_404()?))
}

async fn create(State(ctx): State<Ctx>, Json(new): Json<NewProduct>) -> ApiResult<Created<Product>> {
    Ok(Created(product::create(&ctx, new).await?))
}

async fn update(
    State(ctx): State<Ctx>,
    Path(id): Path<i64>,
    Json(changes): Json<ProductChanges>,
) -> ApiResult<Json<Product>> {
    Ok(Json(product::update(&ctx, id, changes).await?.or_404()?))
}

async fn delete(State(ctx): State<Ctx>, Path(id): Path<i64>) -> ApiResult<StatusCode> {
    if product::delete(&ctx, id).await? { Ok(StatusCode::NO_CONTENT) } else { Err(Error::NotFound.into()) }
}

Every rule is in the model (src/models/product.rs, see Models), so the API, HTML pages and GraphQL share it. The request and response bodies are the model’s structs: NewProduct for POST, ProductChanges for PATCH, Product for responses.

Try it with curl

Create (201):

curl -s -X POST http://localhost:8787/api/products \
  -H 'Content-Type: application/json' \
  -d '{"name": "Teapot", "price": 24.5, "stock": 12}'

{"id":1,"name":"Teapot","price":24.5,"stock":12,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"}

An optional field can be left out (-i shows the status line and headers):

curl -si -X POST http://localhost:8787/api/products \
  -H 'Content-Type: application/json' \
  -d '{"name": "Mug", "price": 8}'

HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json
...
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
...

{"id":2,"name":"Mug","price":8.0,"stock":null,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"}

List and show:

curl -s 'http://localhost:8787/api/products?limit=10'

[{"id":2,"name":"Mug","price":8.0,"stock":null,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"},{"id":1,"name":"Teapot","price":24.5,"stock":12,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"}]

curl -s http://localhost:8787/api/products/1

{"id":1,"name":"Teapot","price":24.5,"stock":12,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"}

Update the price and clear the stock; name is not sent, so it stays:

curl -s -X PATCH http://localhost:8787/api/products/1 \
  -H 'Content-Type: application/json' \
  -d '{"price": 19.9, "stock": null}'

{"id":1,"name":"Teapot","price":19.9,"stock":null,"created_at":"2026-09-29 04:49:11","updated_at":"2026-09-29 04:49:11"}

Delete (204, empty body), then the record is gone:

curl -si -X DELETE http://localhost:8787/api/products/2

HTTP/1.1 204 No Content
...

curl -s -w '\n%{http_code}\n' -X DELETE http://localhost:8787/api/products/2

{"error":{"message":"Not found","status":404}}
404

Errors

Every error is a JSON object {"error": {"status", "message"}} with the same HTTP status; a failed validation adds fields. Internal errors answer Internal server error and log the details (D1 message, SQL) to the Worker log, never to the client.

Validation errors list every field at once, including the database checks (unique names):

curl -s -X POST http://localhost:8787/api/products \
  -H 'Content-Type: application/json' \
  -d '{"name": "Teapot", "price": 3, "stock": 9007199254740992}'

{"error":{"fields":{"name":["has already been taken"],"stock":["must be less than or equal to 9007199254740991"]},"message":"Validation failed","status":422}}

curl -s -X POST http://localhost:8787/api/products \
  -H 'Content-Type: application/json' \
  -d '{"name": " ", "price": 3}'

{"error":{"fields":{"name":["can't be blank"]},"message":"Validation failed","status":422}}

A body that does not fit the struct is a 400 with serde’s explanation, before any validation:

curl -s -X POST http://localhost:8787/api/products -H 'Content-Type: application/json' -d '{"name": "Cup"}'

{"error":{"message":"Failed to deserialize the JSON body into the target type: missing field `price` at line 1 column 15","status":400}}

curl -s -X POST http://localhost:8787/api/products -H 'Content-Type: application/json' -d '{"name": "Cup", "price": "cheap"}'

{"error":{"message":"Failed to deserialize the JSON body into the target type: price: invalid type: string \"cheap\", expected f64 at line 1 column 32","status":400}}

curl -s -X POST http://localhost:8787/api/products -H 'Content-Type: application/json' -d '{"name": "Cup",'

{"error":{"message":"Failed to parse the request body as JSON: EOF while parsing a value at line 1 column 15","status":400}}

curl -s -X POST http://localhost:8787/api/products -d 'name=Cup&price=2'

{"error":{"message":"Expected request with `Content-Type: application/json`","status":400}}

Pagination errors:

curl -s 'http://localhost:8787/api/products?limit=500'
curl -s 'http://localhost:8787/api/products?offset=-1'
curl -s 'http://localhost:8787/api/products?limit=abc'

{"error":{"message":"limit must be between 1 and 100","status":400}}
{"error":{"message":"offset must be 0 or more","status":400}}
{"error":{"message":"Failed to deserialize query string: limit: invalid digit found in string","status":400}}

A PATCH to an unknown id is a 404 ({"error":{"message":"Not found","status":404}}), as is GET.

Pagination, versions and formats

List endpoints read ?limit=&offset= with ocre::Page and answer a Link header (RFC 8288, GitHub’s convention) pointing to the neighbouring pages:

curl -si 'http://localhost:8787/api/products?limit=2&offset=2'

HTTP/1.1 200 OK
Content-Type: application/json
link: </api/products?limit=2&offset=4>; rel="next", </api/products?limit=2&offset=0>; rel="prev", </api/products?limit=2&offset=0>; rel="first"
...

next is there when the page is full (Page::next): Ocre does not run a COUNT(*), which would read every row of the table from D1’s daily 5 million. A client follows next until it is absent; the last page may be empty when the total is a multiple of limit. An endpoint that must report a total runs its own count (see Models).

Versions are path prefixes: keep the current routes in a module and nest it, then nest the next version’s module beside it when the contract changes (the routes then read /products inside the module):

fn routes() -> Router<Ctx> {
    Router::new()
        .nest("/api/v1", products_v1::routes())
        .nest("/api/v2", products_v2::routes())
        // ocre:routes
}

ocre routes lists nested routes with their prefix. One action that serves HTML to browsers and JSON to API clients reads the Accept header with ocre::Format (see Controllers). Every error has the same shape, {"error": {"status": ..., "message": ..., "fields": ...}} (see Errors), including unmatched paths in API-only apps.

Optional fields and partial updates

The model’s input structs decide what a JSON body may contain:

pub struct NewProduct {
    pub name: String,
    pub price: f64,
    #[serde(default, deserialize_with = "ocre::optional")]
    pub stock: Option<i64>,
}

pub struct ProductChanges {
    pub name: Option<String>,
    pub price: Option<f64>,
    #[serde(default, deserialize_with = "ocre::patch")]
    pub stock: Option<Option<i64>>,
}

ocre::optional (in NewProduct) reads the same inputs into Option<i64>: missing, null and "" are None. Accepting numbers as strings and empty strings as “no value” lets the same structs read HTML forms. For required fields in ProductChanges (name, price), a missing key or null both keep the value; {"name": ""} is sent to validation and refused with can't be blank. Optional json fields are the exception: they use #[serde(default)] in New<Model> and #[serde(default, deserialize_with = "ocre::patch_json")] in <Model>Changes, so a JSON string stays a string instead of being parsed (see Field types).

Hand-written JSON endpoints

Any handler can be a JSON endpoint: return ApiResult<T> (an alias of Result<T, ApiError>), take bodies with ocre::Json<T>, and use ? on anything returning ocre::Result, since ApiError converts from ocre::Error and worker::Error.

An endpoint with counts across tables, and one that changes a single field through the model:

// src/stats_api.rs
use axum::{
    Router,
    extract::{Path, State},
    routing::{get, put},
};
use ocre::{ApiResult, Ctx, Error, Json, OptionExt, params};
use serde::{Deserialize, Serialize};

use crate::models::post::{self, Post, PostChanges};

pub fn routes() -> Router<Ctx> {
    Router::new()
        .route("/api/stats", get(stats))
        .route("/api/posts/{id}/published", put(set_published))
}

#[derive(Deserialize, Serialize)]
struct Stats {
    posts: i64,
    published: i64,
    comments: i64,
}

/// GET /api/stats: three counts in one query.
async fn stats(State(ctx): State<Ctx>) -> ApiResult<Json<Stats>> {
    let sql = "SELECT (SELECT COUNT(*) FROM posts) AS posts,
                      (SELECT COUNT(*) FROM posts WHERE published = 1) AS published,
                      (SELECT COUNT(*) FROM comments) AS comments";
    let stats = ctx.db()?.first::<Stats>(sql, params![]).await?;
    Ok(Json(stats.ok_or_else(|| Error::internal("SELECT of counts returned no row"))?))
}

#[derive(Deserialize)]
struct Publish {
    published: bool,
}

/// PUT /api/posts/{id}/published with {"published": true}: goes through the
/// model, so its validations apply.
async fn set_published(
    State(ctx): State<Ctx>,
    Path(id): Path<i64>,
    Json(body): Json<Publish>,
) -> ApiResult<Json<Post>> {
    let changes = PostChanges { published: Some(body.published), ..Default::default() };
    Ok(Json(post::update(&ctx, id, changes).await?.or_404()?))
}

Register it in src/lib.rs (mod stats_api; under // ocre:modules, .merge(stats_api::routes()) under // ocre:routes). In the blog app, with the Comment scaffold:

curl -s http://localhost:8787/api/stats

{"posts":2,"published":1,"comments":0}

curl -s -X PUT http://localhost:8787/api/posts/2/published -H 'Content-Type: application/json' -d '{"published": true}'

{"id":2,"title":"Draft","body":"Not yet","published":true,"created_at":"2026-09-29 04:48:44","updated_at":"2026-09-29 04:49:13"}

curl -s -X PUT http://localhost:8787/api/posts/2/published -H 'Content-Type: application/json' -d '{"published": "yes"}'
curl -s -X PUT http://localhost:8787/api/posts/42/published -H 'Content-Type: application/json' -d '{"published": true}'

{"error":{"message":"Failed to deserialize the JSON body into the target type: published: invalid type: string \"yes\", expected a boolean at line 1 column 19","status":400}}
{"error":{"message":"Not found","status":404}}

Handlers of HTML pages return ocre::Result and render errors as HTML; JSON handlers return ApiResult. Use one or the other per handler.

GraphQL

--graphql adds, for each resource, these operations on POST /graphql, and the GraphiQL editor on GET /graphql (open http://localhost:8787/graphql in a browser):

The resolvers are in src/products_api.rs, below the REST handlers, and call the same model functions. src/graphql.rs builds the schema once per Worker instance and merges each resource’s query and mutation objects after the // ocre:graphql-queries and // ocre:graphql-mutations markers. In ProductPatch, optional fields are MaybeUndefined: omitted keeps, null clears.

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "{ products(limit: 5) { id name price stock } }"}'

{"data":{"products":[{"id":1,"name":"Teapot","price":19.9,"stock":null}]}}

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "mutation { createProduct(input: {name: \"Kettle\", price: 30}) { id name stock } }"}'

{"data":{"createProduct":{"id":3,"name":"Kettle","stock":null}}}

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "mutation { updateProduct(id: 3, patch: {stock: null, price: 28}) { id price stock } }"}'

{"data":{"updateProduct":{"id":3,"price":28.0,"stock":null}}}

Errors follow GraphQL conventions: the HTTP status is 200 and the error is in errors, with Ocre’s status (and validation fields) in extensions:

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "mutation { createProduct(input: {name: \"\", price: 30}) { id } }"}'

{"data":null,"errors":[{"message":"Validation failed","locations":[{"line":1,"column":12}],"path":["createProduct"],"extensions":{"fields":{"name":["can't be blank"]},"status":422}}]}

curl -s -X POST http://localhost:8787/graphql -H 'Content-Type: application/json' \
  -d '{"query": "mutation { deleteProduct(id: 99) }"}'

{"data":null,"errors":[{"message":"Not found","locations":[{"line":1,"column":12}],"path":["deleteProduct"],"extensions":{"status":404}}]}

product(id: 99) returns {"data":{"product":null}}. A body that is not a GraphQL request is a 400: {"errors":[{"message":"invalid GraphQL request: expected ident at line 1 column 2"}]}.

Cost on the free plan: GraphQL is opt-in (the graphql feature of ocre in Cargo.toml, which the first --graphql enables, plus the async-graphql dependency). It adds about 1.1 MB to the WebAssembly binary and 20-60 ms of CPU each time a new Worker instance starts (measured with wrangler tail), against 10 ms per request on the free plan, which Cloudflare tolerates when overruns are infrequent. Add it only when a client needs GraphQL; each resolver’s queries cost the same D1 rows as the REST handler.

API-only apps

ocre new <name> --api creates an app without templates or askama: ocre is built with default-features = false (no html feature), Cargo.toml records [package.metadata.ocre] mode = "api", and ocre g scaffold generates JSON APIs. Its src/lib.rs answers GET / with a JSON status:

#[derive(Serialize)]
struct Status {
    app: &'static str,
    status: &'static str,
}

async fn status() -> Json<Status> {
    Json(Status { app: "shop", status: "ok" })
}

ocre new shop --api --yes
cd shop
ocre g scaffold Item name:string

  create  src/models/mod.rs
  create  migrations/0001_create_items.sql
  create  src/models/item.rs
  create  src/items_api.rs
  update  src/lib.rs

Next:
  ocre migrate
  ocre dev
  curl http://localhost:8787/api/items

Without the html feature, errors that would otherwise be HTML pages (such as a missing session secret) are JSON too.

Calling the API from another origin (CORS)

A browser frontend served from another origin (a separate SPA, a mobile web view) needs that origin listed in the ALLOWED_ORIGINS Worker variable, comma-separated, in cloudflare.config.ts:

// in worker.env
ALLOWED_ORIGINS: bindings.text("https://app.example.com"),

Listed origins get CORS headers (methods GET, POST, PUT, PATCH, DELETE; headers Content-Type, Authorization, Accept; credentials allowed) and pass the CSRF check; unlisted ones get neither. A preflight from the listed origin:

curl -si -X OPTIONS http://localhost:8787/api/products \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type'

HTTP/1.1 200 OK
Content-Length: 0
Access-Control-Allow-Origin: https://app.example.com
Allow: GET,HEAD,POST
Vary: origin
access-control-allow-credentials: true
access-control-allow-headers: content-type,authorization,accept
access-control-allow-methods: GET,POST,PUT,PATCH,DELETE
...

A browser request from an unlisted site that changes data is refused with a plain-text 403:

curl -s -X DELETE http://localhost:8787/api/products/3 -H 'Origin: https://evil.example' -H 'Sec-Fetch-Site: cross-site'

Forbidden: cross-site request. Add the origin to ALLOWED_ORIGINS to allow it.

Clients that are not browsers (curl, servers, mobile apps) send no Origin or Sec-Fetch-Site header and are not affected. See Sessions, flash and security and Configuration.

Authentication

APIs are public until you protect them. After ocre g auth, take BearerUser(user): BearerUser (from crate::auth_api) in a handler, before Json(..): it accepts Authorization: Bearer <JWT or API key> and answers a JSON 401 with WWW-Authenticate: Bearer otherwise. Tokens come from POST /api/auth/token; API keys from POST /api/auth/keys. Filter queries by user.id for records a user owns. See Authentication.

See also

• Models and migrations: the model behind every API
• Validations: rules and the 422 fields object
• Controllers and routing: routing and extractors in general
• Authentication: BearerUser, JWTs and API keys
• File storage: attachments in JSON APIs (PUT /api/<plural>/{id}/<file>)
• Generators, Configuration, Free-plan limits
• API index and the rustdoc

Sessions, flash and security

This guide shows how an Ocre app keeps per-visitor state in an encrypted session cookie, shows one-time flash messages, and what ocre::serve does for every request to protect it: host checks, cross-site request (CSRF) checks, CORS, security headers and cookie flags. It then covers the helpers an app calls itself (rate limiting, safe queries and parameters, files, user HTML) and ends with what is not included, so you know what to add yourself.

Before you start

• An app created with ocre new. Everything on this page is built into the ocre crate and applied by ocre::serve in src/lib.rs; no generator is needed.
• The SECRET_KEY_BASE secret (see Configuration). ocre new writes a random one to .dev.vars for ocre dev; ocre deploy uploads a new one to the Worker the first time (see Keys and rotation).
• The outputs below come from an app created with ocre new shop --starter blog, served by ocre dev on the default port 8787.

What every request goes through

ocre::serve(routes(), req, env) wraps the app’s router with five layers, outermost first:

None of these layers makes a D1, KV or network call: they cost a little CPU and no free-plan quota. Generated full-stack apps add a Content-Security-Policy and a Permissions-Policy layer in src/lib.rs (see Content-Security-Policy and Permissions-Policy).

Sessions

A handler takes session: ocre::Session as an argument (an axum extractor) and reads or writes values by key. Values are anything serde can serialize; they are stored as JSON.

Every method returns ocre::Result, so use ?. Changes are sent back as one Set-Cookie header when the handler returns. A request that does not change the session sends no cookie; taking pending flash messages out counts as a change.

The session is a cookie, like Rails’ default cookie store: no D1 rows, no KV operations, nothing on the server.

• Encrypted and authenticated. The cookie value is JSON encrypted with AES-256-GCM, with a key derived from SECRET_KEY_BASE. Clients can neither read nor change it. A cookie that does not decrypt (tampered, truncated, or encrypted with a key that is neither SECRET_KEY_BASE nor listed in SECRET_KEY_BASE_PREVIOUS) is ignored: the request starts with an empty session, no error.
• 4 KB at most. Browsers drop cookies over 4096 bytes (name, value and attributes). When a change would make the cookie larger, the response is a 500 and the log says the session cookie would be <n> bytes; browsers drop cookies over 4096. Fix: store ids in the session, not records. Store ids and short strings, never records, and never secrets such as tokens or passwords.
• Cookie flags. The cookie is _ocre_session, Path=/, HttpOnly (JavaScript cannot read it), SameSite=Lax, and Secure when the request came over HTTPS (always on *.workers.dev; not on http://localhost). By default it has no Max-Age: it lasts until the browser session ends or the app clears it; session.remember_for(seconds) makes it persistent (see Expiry and remember me).
• Clearing. When the session becomes empty, the cookie is deleted (Max-Age=0).

Store a value in the session

This module stores a visitor’s theme in the session and confirms the change with a flash message. It needs nothing but the ocre new app: add mod preferences; under // ocre:modules and .merge(preferences::routes()) under // ocre:routes in src/lib.rs.

// src/preferences.rs
use askama::Template;
use axum::{
    Form, Router,
    response::{Html, Redirect},
    routing::{get, post},
};
use ocre::{Ctx, Error, Flash, Result, Session, render};
use serde::Deserialize;

pub fn routes() -> Router<Ctx> {
    Router::new().route("/preferences", get(show).post(update)).route("/preferences/reset", post(reset))
}

/// Session key; the value is a short string, never a record.
const THEME: &str = "theme";

#[derive(Template)]
#[template(
    source = r#"{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
<p>Theme: {{ theme }}</p>
<form method="post" action="/preferences">
  <select name="theme"><option>light</option><option>dark</option></select>
  <button>Save</button>
</form>"#,
    ext = "html"
)]
struct PreferencesView {
    flash: Flash,
    theme: String,
}

#[derive(Deserialize)]
struct PreferencesForm {
    theme: String,
}

async fn show(session: Session, flash: Flash) -> Result<Html<String>> {
    let theme = session.get::<String>(THEME)?.unwrap_or_else(|| "light".to_owned());
    render(&PreferencesView { flash, theme })
}

async fn update(session: Session, Form(form): Form<PreferencesForm>) -> Result<Redirect> {
    if form.theme != "light" && form.theme != "dark" {
        return Err(Error::bad_request("theme must be light or dark"));
    }
    session.insert(THEME, &form.theme)?;
    session.flash("notice", "Preferences saved.")?;
    Ok(Redirect::to("/preferences"))
}

async fn reset(session: Session) -> Result<Redirect> {
    if session.remove(THEME)? {
        session.flash("notice", "Preferences reset.")?;
    }
    Ok(Redirect::to("/preferences"))
}

In a real page, put the markup in templates/preferences/show.html with {% extends "layout.html" %} and use #[template(path = "preferences/show.html")]; the inline source keeps the example in one file.

Try it with ocre dev running and a cookie jar (-c saves cookies, -b sends them):

curl -s -c jar.txt -b jar.txt -X POST http://localhost:8787/preferences -d theme=dark -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s -c jar.txt -b jar.txt -D - http://localhost:8787/preferences
curl -s -c jar.txt -b jar.txt http://localhost:8787/preferences

303 http://localhost:8787/preferences
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: text/html; charset=utf-8
Set-Cookie: _ocre_session=1ik14hJ5am+ra2dQbLBTz921QqhYB+TbkHC+SAM1DpFW8Tv9OVP7cOV74D8%3D; HttpOnly; SameSite=Lax; Path=/
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-permitted-cross-domain-policies: none
x-xss-protection: 0

<p class="notice">Preferences saved.</p>
<p>Theme: dark</p>
...

<p>Theme: dark</p>
...

The first page shows the flash message and sends a new cookie (the message was taken out of the session); the second shows the theme without it. A forged cookie is simply ignored:

curl -s -H 'Cookie: _ocre_session=abc' http://localhost:8787/preferences

<p>Theme: light</p>
...

And the 400 from Error::bad_request is rendered as an HTML error page:

curl -s -b jar.txt -X POST http://localhost:8787/preferences -d theme=pink

<h1>400</h1><p>theme must be light or dark</p>

Flash messages

A flash message is shown once, on the next page, usually after a redirect (“Post was successfully created.”). Set it with session.flash(kind, message)? before returning a Redirect; the next handler takes flash: ocre::Flash and passes it to its template. Taking Flash removes the messages from the session, so a reload does not show them again.

Kinds are free-form; generated code uses notice and alert, and generated templates show them like this:

{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
{% if let Some(alert) = flash.alert() %}<p class="alert">{{ alert }}</p>{% endif %}

Setting a second message of the same kind in one request replaces the first. session.clear() keeps pending flash messages, so “Signed out.” survives the logout that empties the session. Flash messages live in the session cookie, so they count toward its 4 KB: keep them to a sentence.

For a message on the page being rendered (Rails’ flash.now), add it to the Flash the view gets, without touching the session: render(&EditView { flash: flash.now("alert", "Check the highlighted fields."), .. }). To carry the messages one more request (Rails’ flash.keep), for example when a page redirects again before showing them, call session.keep_flash(&flash)?.

Cookies

The session is the place for per-visitor state. For cookies that outlive it or that other parts of the site read, take ocre::Cookies in the handler (Rails’ cookies, cookies.signed and cookies.encrypted):

use std::time::Duration;
use ocre::{Cookies, Result};

async fn preferences(cookies: Cookies) -> Result<String> {
    cookies.set("theme", "dark", Some(Duration::from_secs(365 * 86_400)))?;       // readable and changeable by the browser
    cookies.set_signed("seen_banner", "1", None)?;                                 // readable, tamper-proof (HMAC)
    cookies.set_encrypted("remember_token", "a1b2c3", Some(Duration::from_secs(30 * 86_400)))?; // hidden and tamper-proof
    Ok(format!("{:?} {:?}", cookies.get("theme"), cookies.signed("seen_banner")?))
}

get, signed and encrypted read the request’s cookies (None when absent, or changed by the client for the last two); remove(name) deletes one. Cookies set by a handler go out with the response, HttpOnly, SameSite=Lax, Path=/ and Secure over HTTPS. Signed and encrypted cookies use keys derived from SECRET_KEY_BASE, and values made with a key of SECRET_KEY_BASE_PREVIOUS still read. The session cookie’s name (_ocre_session) is refused.

Keys and rotation

SECRET_KEY_BASE must be set and at least 64 characters long. ocre secret prints a new random value (128 hex characters):

ocre secret

Where it comes from:

Two keys are derived from it: the session cookie key, and (with a fixed label) the HS256 key of ocre::jwt (see Authentication). When the secret is missing or shorter than 64 characters, requests that write the session, or read a session cookie they received, answer 500, and the log names the fix: the SECRET_KEY_BASE secret is not set. Fix: run `ocre secret`, put the value in .dev.vars as SECRET_KEY_BASE=... for `ocre dev` (`ocre new` does this), and deploy with `ocre deploy`, which uploads it.

Replacing the secret alone signs everyone out. Existing cookies no longer decrypt, so every visitor starts with an empty session, and every JWT fails to verify. This is the way to invalidate all cookie sessions at once, for example after a leak: put a new value from ocre secret in .prod.vars (git-ignored) as SECRET_KEY_BASE=..., then

ocre secrets push SECRET_KEY_BASE --file .prod.vars

Changing the value in .dev.vars and restarting ocre dev shows the effect: a browser that was signed in is redirected to /login by the next CurrentUser page, and an old JWT gets 401 {"error":{"message":"Unauthorized","status":401}}. For a planned rotation that keeps everyone signed in, see Rotating SECRET_KEY_BASE without signing everyone out.

Cross-site request forgery (CSRF)

Forms need no token. Instead, Ocre checks where each request comes from, the check Go 1.25 ships as http.CrossOriginProtection:

1. GET, HEAD and OPTIONS requests pass (they must not change data), except WebSocket handshakes, which are checked like forms because browsers send cookies with them.
2. A request whose Origin is listed in ALLOWED_ORIGINS passes.
3. When the browser sent Sec-Fetch-Site (all current browsers do), same-origin and none (typed in the address bar, bookmarks) pass; anything else (cross-site, same-site) is refused.
4. Older browsers that send only Origin: it must match the Host header, else the request is refused.
5. A request with neither header passes: it does not come from a web page, so it cannot carry a victim’s cookies by accident (curl, server-to-server calls, mobile apps).

A refused request never reaches the handler. It gets a plain-text 403:

curl -si -X POST http://localhost:8787/preferences -H 'Sec-Fetch-Site: cross-site' -d theme=dark

HTTP/1.1 403 Forbidden
Transfer-Encoding: chunked
Content-Type: text/plain; charset=utf-8
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-permitted-cross-domain-policies: none
x-xss-protection: 0

Forbidden: cross-site request. Add the origin to ALLOWED_ORIGINS to allow it.

With only an Origin that does not match the host (older browsers):

curl -si -X POST http://localhost:8787/preferences -H 'Origin: https://evil.example' -d theme=dark

HTTP/1.1 403 Forbidden
...
Forbidden: cross-origin request. Add the origin to ALLOWED_ORIGINS to allow it.

The same form posted from the app’s own pages carries Sec-Fetch-Site: same-origin and goes through:

curl -si -X POST http://localhost:8787/preferences -H 'Sec-Fetch-Site: same-origin' -d theme=dark

HTTP/1.1 303 See Other
Content-Length: 0
Location: /preferences
Set-Cookie: _ocre_session=w+0WnN%2FE6WOBxLRb+F69geJp1HvSBUuO9%2FQlgsaoC1cNBkPpegmJbFic45skI6OmixjEaRl52s1TSas1fRpkqRqL0k8otB9akF60KBkTSKGQ+7DTYQ%3D%3D; HttpOnly; SameSite=Lax; Path=/
...

Consequences for app code:

• Change data only in POST, PUT, PATCH and DELETE handlers. A GET handler that changes data is not protected. Generated scaffolds follow this (POST /posts/{id}/delete, POST /logout).
• htmx requests (hx-post, hx-delete…) and your own fetch() calls from the app’s pages are same-origin and pass. There is no token to put in a <meta> tag or send in a header (Rails’ csrf_meta_tags): the browser’s Sec-Fetch-Site header does that job.
• The session cookie is also SameSite=Lax: browsers do not send it with cross-site POSTs at all, a second layer for the same attack.
• A refused request never reaches a handler, so nothing needs undoing when the check fails: no session is read, and a “remember me” cookie cannot sign it in.

ALLOWED_ORIGINS: another site calling the app

When a separate frontend (another domain, a local dev server on another port) must call the app from the browser, list its origins in the ALLOWED_ORIGINS Worker variable, comma-separated, in worker.env of cloudflare.config.ts (or in .dev.vars for ocre dev):

// cloudflare.config.ts, in worker.env
ALLOWED_ORIGINS: bindings.text("https://app.example.com, https://admin.example.com"),

Spaces and a trailing / are ignored; invalid entries are skipped. The listed origins get two things:

• CORS: preflights are answered, with credentials allowed (the browser may send cookies), methods GET, POST, PUT, PATCH, DELETE, request headers Content-Type, Authorization, Accept.
• CSRF trust: their unsafe requests pass the cross-origin check.

With ALLOWED_ORIGINS=https://app.example.com in .dev.vars, a preflight from that origin:

curl -si -X OPTIONS http://localhost:8787/api/notes \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: authorization, content-type'

HTTP/1.1 200 OK
Content-Length: 0
Access-Control-Allow-Origin: https://app.example.com
Allow: GET,HEAD,POST
Vary: origin
access-control-allow-credentials: true
access-control-allow-headers: content-type,authorization,accept
access-control-allow-methods: GET,POST,PUT,PATCH,DELETE
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-permitted-cross-domain-policies: none
x-xss-protection: 0

A cross-site POST from https://app.example.com now gets 303 See Other with Access-Control-Allow-Origin: https://app.example.com; the same request from any other origin still gets 403. When the variable is unset or empty, no CORS layer is added and only same-origin browser requests may change data. List only origins you control: a listed origin can act with the visitor’s cookies.

Security headers

Every response gets Rails’ default headers. Captured from GET /up:

curl -sI http://localhost:8787/up

HTTP/1.1 200 OK
Content-Length: 2
Content-Type: text/plain; charset=utf-8
referrer-policy: strict-origin-when-cross-origin
x-content-type-options: nosniff
x-frame-options: SAMEORIGIN
x-permitted-cross-domain-policies: none
x-xss-protection: 0

A handler that sets one of these headers keeps its own value. The same way, a handler can add headers Ocre does not send, such as a Content-Security-Policy:

// src/report.rs
use axum::{
    Router,
    http::header,
    response::{Html, IntoResponse},
    routing::get,
};
use ocre::Ctx;

pub fn routes() -> Router<Ctx> {
    Router::new().route("/report", get(report))
}

async fn report() -> impl IntoResponse {
    (
        [
            // Not sent by Ocre: added here.
            (header::CONTENT_SECURITY_POLICY, "default-src 'self'"),
            // Sent by Ocre as strict-origin-when-cross-origin: this value wins.
            (header::REFERRER_POLICY, "no-referrer"),
        ],
        Html("<p>Quarterly report</p>"),
    )
}

Static files in public/ are served by Cloudflare before the Worker runs, so they do not get these headers; add them with a _headers file if needed.

Escaping in templates

askama escapes every {{ value }} in .html templates. A post titled <script>alert(1)</script> is shown as text:

<tr><td>&#60;script&#62;alert(1)&#60;/script&#62;</td><td>Hi</td>...

Rules:

• Never apply |safe to user input; it turns escaping off.
• .txt templates (plain-text email bodies) are not escaped, which is correct for plain text; do not reuse them for HTML.
• HTML built with format! is not escaped. Build HTML in templates, or escape values yourself.
• Values inside <script> or event attributes need JSON encoding, not HTML escaping; avoid putting user input there.

SQL injection

D1 queries take ?1, ?2 placeholders and a params![...] list; the values never become SQL text, so they cannot inject SQL:

ctx.db()?.first("SELECT * FROM users WHERE email = ?1", params![email]).await

The Query builder (post::query().eq("published", true)...) binds every value the same way, and takes column names, joins, where_sql fragments and sort terms as &'static str: they can only come from your code, never from request text. is_in with an empty list matches no row instead of writing invalid or unbounded SQL, and contains, starts_with and ends_with escape % and _ in the searched text.

Never build SQL with format! from user input. When a column or sort order comes from the request, match it onto a fixed column name:

// src/post_search.rs
use axum::{
    Json, Router,
    extract::{Query as Params, State},
    routing::get,
};
use ocre::{Ctx, Direction, Result};
use serde::Deserialize;

use crate::models::post::{self, Post};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/posts/search", get(search))
}

/// The only two parameters read from the query string; others are ignored.
#[derive(Deserialize)]
struct SearchParams {
    #[serde(default)]
    q: String,
    sort: Option<String>,
}

async fn search(State(ctx): State<Ctx>, Params(params): Params<SearchParams>) -> Result<Json<Vec<Post>>> {
    // The column comes from this list, never from the request text.
    let (column, direction) = match params.sort.as_deref() {
        Some("title") => ("title", Direction::Asc),
        _ => ("created_at", Direction::Desc),
    };
    let posts = post::query()
        .eq("published", true)
        .contains("title", &params.q)
        .order_by(column, direction)
        .limit(20)
        .all(&ctx.db()?)
        .await?;
    Ok(Json(posts))
}

GET /posts/search?q=rust&sort=title runs SELECT * FROM posts WHERE published = ?1 AND title LIKE ?2 ESCAPE '\' ORDER BY title ASC LIMIT ?3; sort=id;DROP TABLE posts sorts by created_at.

Only the fields you declare (strong parameters)

Handlers read forms and JSON bodies into a struct (Form<PostForm>, Json<NewPost>, Query<SearchParams>). serde fills only the fields the struct declares and ignores the others, so the struct is the allowlist that Rails’ params.require(...).permit(...) builds: a request that adds user_id=1 or "admin": true changes nothing unless the struct has that field. Keep fields a visitor must not choose out of the form structs, and set them in the handler instead, like the owner from CurrentUser (see Records that belong to a user). Add #[serde(deny_unknown_fields)] to a struct to reject such requests instead of ignoring the extra fields.

Types do the rest of Rails’ parameter checks: a missing field, or text where the struct wants a number, a bool or a list, is rejected before the handler runs (400 or 422), so a handler never receives nil or an array where it expected one value. Optional fields are Option<T> (or #[serde(default)]), which you handle explicitly.

Validating formats

Validator::format(field, value, |c| ...) checks every character of the whole value against a predicate. There is no regular expression engine in Ocre, so Rails’ pitfall of ^ and $ matching at line breaks (a value with a newline and a script after a valid first line) does not exist: the whole value passes or it does not. For position rules, add a check (value.starts_with("https://")), and for common formats use email, uuid, date, datetime, decimal and the other Validator methods. If you add the regex crate yourself, anchor patterns with \A and \z (or ^/$ without the multi-line flag), which match only the start and end of the text.

Expiry and remember me

session.expire_in(seconds)? stores an expiry time inside the encrypted cookie; after it the session starts empty (a copied or replayed cookie stops working too). session.remember_for(seconds)? does the same and makes the cookie persistent (Max-Age), for “Remember me”. session.expires_at()? reads it; session.clear()? removes it. Keep balances, nonces and other state that must not be replayed in D1, not in the cookie. Server-side revocation of individual sessions is generated by ocre g auth --db-sessions.

Rotating SECRET_KEY_BASE without signing everyone out

List old values (newest first, comma-separated) in the SECRET_KEY_BASE_PREVIOUS secret: cookies encrypted with them are still read and re-encrypted with the current key, and JWTs signed with them still verify. Worker secrets cannot be read back, so keep the value you replace. In .prod.vars (git-ignored):

SECRET_KEY_BASE_PREVIOUS=<the current value>
SECRET_KEY_BASE=<a new value from `ocre secret`>

ocre secrets push SECRET_KEY_BASE_PREVIOUS SECRET_KEY_BASE --file .prod.vars

Remove SECRET_KEY_BASE_PREVIOUS after the longest session lifetime. ocre secrets list shows which secrets are set locally and in production; ocre secrets push NAME... --file .prod.vars uploads values.

Content-Security-Policy and Permissions-Policy

Generated apps add both in src/lib.rs (content_security_policy() and permissions_policy()): scripts only from the app and unpkg.com (htmx), no inline scripts or on*= handlers, object-src 'none', frame-ancestors 'self'; camera, microphone, geolocation, payment and USB off. Policies are ocre::security::ContentSecurityPolicy and PermissionsPolicy values added with .layer(...); a handler’s own header, or a nested router’s layer, overrides them for a route. .report_only() sends Content-Security-Policy-Report-Only; .report_uri("/csp-reports") / .report_to("csp") collect violations. For an inline script add NONCE to script_src, take nonce: ocre::security::CspNonce in the handler and write <script nonce="{{ nonce }}"> (a new random nonce per request).

Rate limiting

ocre::security::rate_limit(&ctx, "BINDING", &key).await? counts one request for key against a Workers Rate Limiting binding and returns Error::TooManyRequests (429, “Too many requests. Try again later.”) when the key is over the binding’s limit. Rails’ rate_limit to:, within:, by: maps onto the binding’s limit, its period (10 or 60 seconds) and the key you build. ocre g auth already limits its login, sign-up, emailed-link, token and deletion routes with the AUTH_RATE_LIMITER binding (see Authentication).

For your own route, add a binding with its own name and namespace to worker.env of cloudflare.config.ts:

// `namespace`: any integer, unique in your Cloudflare account
FEEDBACK_RATE_LIMITER: bindings.rateLimit({ namespace: "4242", simple: { limit: 3, period: 60 } }),

and call it before the expensive part of the handler:

// src/feedback.rs
use axum::{
    Form, Router,
    extract::State,
    http::HeaderMap,
    response::Redirect,
    routing::post,
};
use ocre::{Ctx, Error, Result, Session, security::rate_limit};
use serde::Deserialize;

pub fn routes() -> Router<Ctx> {
    Router::new().route("/feedback", post(create))
}

#[derive(Deserialize)]
struct FeedbackForm {
    message: String,
}

async fn create(
    State(ctx): State<Ctx>,
    headers: HeaderMap,
    session: Session,
    Form(form): Form<FeedbackForm>,
) -> Result<Redirect> {
    // One counter per client IP address (Cloudflare's CF-Connecting-IP).
    let ip = ocre::remote_ip(&headers).map_or_else(|| "unknown".to_owned(), |ip| ip.to_string());
    rate_limit(&ctx, "FEEDBACK_RATE_LIMITER", &format!("feedback:{ip}")).await?;
    if form.message.trim().is_empty() {
        return Err(Error::bad_request("write a message"));
    }
    // ... store or email the message ...
    session.flash("notice", "Thanks for your feedback.")?;
    Ok(Redirect::to("/"))
}

Past three requests a minute from the same address, POST /feedback gets the 429 error page (JSON handlers answer {"error":{"status":429,"message":"Too many requests. Try again later."}}). Key by user id (format!("export:{}", user.id)) for signed-in actions. The binding is on the free plan, costs no D1, KV or Durable Object operation, and ocre dev simulates it. Counters are per Cloudflare location and approximate, so it is a brake, not an exact quota. A missing binding is a 500 whose log names the bindings.rateLimit(...) entry to add.

HTTPS and HSTS

Workers are reached over HTTPS: *.workers.dev and custom domains get certificates from Cloudflare. On HTTPS requests Ocre adds Strict-Transport-Security: max-age=63072000 (two years) and marks the session cookie Secure. What Rails’ force_ssl does beyond that is configured outside the app or by hand:

• Redirect HTTP to HTTPS: on a custom domain, turn on Always Use HTTPS in the Cloudflare dashboard (SSL/TLS > Edge Certificates); Cloudflare then redirects before the Worker runs.
• Other HSTS options (includeSubDomains, preload): set the header yourself, in a handler or a layer in src/lib.rs; a header set by the app wins over Ocre’s.

Files: downloads and uploads

• Sending data (Rails’ send_data): ocre::storage::send_data(bytes, "report.csv", "text/csv", Disposition::Download) sets Content-Type, Content-Length and a Content-Disposition with a cleaned file name. Types a browser could run (HTML, SVG, XML, JavaScript) are sent as application/octet-stream, even with Disposition::Inline. When cells come from users, prefix values starting with =, +, - or @ with ' so spreadsheets do not run them as formulas.
• Sending stored files (Rails’ send_file): files live in R2, not on a disk, so there is no path to traverse. ocre::storage::serve(&ctx, &attachment, &headers, Disposition::Inline) streams an attachment by its random key, with the same type rules, Range and If-None-Match.
• Upload names: the uploader’s file name loses its directories (../../x, C:\x) and control characters and is cut to 200 characters; it is only shown in Content-Disposition, never used as the storage key (<prefix>/<22 random characters>). The R2 bucket is not public and nothing in it is executed; files reach browsers only through your handlers, so check that the user may see the record first. See File storage.

User-supplied CSS and markup

• ocre::security::sanitize drops style attributes and <style> elements, so user HTML cannot restyle the page (CSS injection, as in the MySpace worm) or load images through url(...). Keep style out of the lists you pass to sanitize_with.
• Never put user text inside a <style> element or a style="..." attribute; offer choices from a fixed list instead (a theme name that selects one of your CSS classes).
• Markup languages (Markdown, Textile): convert with a library of your choice, then pass the resulting HTML through sanitize before inserting it with |safe, since these converters let raw HTML through.
• The generated Content-Security-Policy is a second layer if some HTML slips through: scripts only from the app and unpkg.com, no javascript: URLs or on*= handlers, and fonts only from the app, so injected CSS cannot run code or load remote fonts (it still allows inline styles, which the generated layout uses).

Shell commands

A Worker cannot start processes: there is no system, exec or shell, so command-line injection has no target. Code that must call another program does it over HTTP (worker::Fetch) with arguments encoded as JSON or form data, never pasted into a command string on the other side.

Dependency and code scanning

Rails runs Brakeman and bundler-audit by default. For an Ocre app, run in the app directory, for example in CI next to cargo test:

cargo install cargo-audit --locked
cargo audit                              # dependencies with known vulnerabilities (RustSec advisory database)
cargo clippy --target wasm32-unknown-unknown -- -D warnings   # Rust lints on the Worker code

cargo deny check advisories (from cargo-deny) does the same check as cargo audit and can also enforce licenses and banned crates. Enable Dependabot or Renovate on the repository to get pull requests for updated crates. Ocre does not set these up in new apps.

More helpers

What is not included

• A force_ssl switch: see HTTPS and HSTS.
• Roles, two-factor authentication and account lockout: see Authentication.
• Dependency scanning in new apps: see Dependency and code scanning.

See also

• Authentication: users, login, JWTs, API keys, ownership checks.
• Security model: why Ocre chose these defaults.
• Configuration: SECRET_KEY_BASE, ALLOWED_ORIGINS and other variables.
• Controllers and routing and Views, helpers and forms: handlers, templates and forms.
• ocre secret and ocre deploy.
• Rust API: Session, Flash, ALLOWED_ORIGINS, or the API index.

Authentication

This guide adds users to an Ocre app with ocre g auth: sign-up, login (“remember me”) and logout pages, magic links, password resets and email confirmation by email, account deletion, rate limits, JWTs and API keys for JSON clients, and optionally sessions tracked in D1 (--db-sessions) and “Continue with GitHub / Google” (--oauth). It then shows how to protect pages and endpoints and restrict records to their owner. All of it is generated app code you can read and change; the framework only provides small primitives (password hashing, tokens, JWTs, rate limits, OAuth).

Before you start

• An app created with ocre new, full-stack or API-only (--api). ocre g auth runs once per app and refuses to run when a User model or a users table exists.
• The SECRET_KEY_BASE secret, used for session cookies and JWTs; ocre new writes one to .dev.vars (see Sessions, flash and security).
• For magic links and password resets in production: a mail adapter (MAIL_ADAPTER, see Email). In ocre dev the emails are printed in the console.
• The outputs below come from an app created with ocre new shop --starter blog, served by ocre dev on the default port 8787.

Generate authentication

ocre g auth

In a full-stack app:

  create  migrations/0002_create_users.sql
  create  migrations/0003_create_auth_tokens.sql
  create  migrations/0004_create_api_keys.sql
  create  src/models/user.rs
  create  src/models/api_key.rs
  create  src/models/auth_token.rs
  create  src/auth_api.rs
  create  src/auth.rs
  create  src/registrations.rs
  create  src/sessions.rs
  create  src/passwords.rs
  create  src/confirmations.rs
  create  templates/auth/signup.html
  create  templates/auth/login.html
  create  templates/auth/account.html
  create  templates/auth/magic_link_new.html
  create  templates/auth/magic_link_show.html
  create  templates/auth/password_new.html
  create  templates/auth/password_edit.html
  create  templates/auth/confirmation_show.html
  update  src/models/mod.rs
  update  src/lib.rs
  update  cloudflare.config.ts

Next:
  ocre migrate
  ocre dev
  open http://localhost:8787/signup

cloudflare.config.ts gets the rate limiter used by every route that checks a password or sends an email (see Rate limiting), after the // ocre:env marker:

// `ocre g auth`: login, sign-up, token and emailed-link routes allow 10 attempts
// a minute per IP address and Cloudflare location (Workers Rate Limiting,
// free plan, no storage used). `period` is 10 or 60 seconds.
AUTH_RATE_LIMITER: bindings.rateLimit({ namespace: "3530462", simple: { limit: 10, period: 60 } }),

The namespace is derived from the app name; two Workers of an account with the same id share counters.

Then apply the migrations and start the app:

ocre migrate
ocre dev

What each file holds, and which ones an API-only app (ocre new --api) gets:

Two options add more, in full-stack apps only:

In an API-only app the output is:

  create  migrations/0001_create_users.sql
  create  migrations/0002_create_api_keys.sql
  create  src/models/mod.rs
  create  src/models/user.rs
  create  src/models/api_key.rs
  create  src/auth_api.rs
  update  src/lib.rs
  update  cloudflare.config.ts

Next:
  ocre migrate
  ocre dev
  curl -X POST http://localhost:8787/api/auth/signup -H 'content-type: application/json' -d '{"email":"ada@example.com","password":"correct horse"}'

Running it a second time fails:

error: this app already has a User model or a users table
hint: `ocre g auth` creates both and runs once per app; to start over, remove src/models/user.rs and the create_users migration

Run ocre routes to see every route the generator added.

Sign-up, login and logout

The HTML flows are ordinary forms; the examples use curl with a cookie jar (-c saves cookies, -b sends them) to show what a browser gets.

A visitor who opens a protected page is sent to /login, and the page is remembered:

curl -si -c jar.txt -b jar.txt http://localhost:8787/account

HTTP/1.1 303 See Other
Content-Length: 0
Location: /login
Set-Cookie: _ocre_session=OomyKZrKiIV5EQpPSEG9Ce4hmLjenLFK8MCStDD4c0RVxh4hgPGVu4hMn%2FKFAmNCCW0v0WmFNC3IfOX6ch2l1qvsfg+X%2FjJmaAexvIoNgANOYmXUhTSzyuvNoO2FZK+D0+8D2Q%3D%3D; HttpOnly; SameSite=Lax; Path=/
...

Signing up creates the user, signs them in and returns to that page:

curl -si -c jar.txt -b jar.txt http://localhost:8787/signup -d 'email=ada@example.com&password=correct horse'

HTTP/1.1 303 See Other
Content-Length: 0
Location: /account
Set-Cookie: _ocre_session=HZlSU2bCVeNT7CWPgmbw2p6DaYDY9S%2FOB3S8Wu%2FiKTdXxippgjk2zgYIuqY6JvzqswPId3bRHmAF7SYVfWT0MZI0Hrv6legGNBfwImUsSW06alc2QQRbh5tC6livVjw%3D; HttpOnly; SameSite=Lax; Path=/
...

GET /account now shows the flash message, the user, and a reminder to confirm the address (see Email confirmation):

<h1>Your account</h1>
<p class="notice">Welcome! Your account is ready. Check your email to confirm your address.</p>
...
  <dt>Email</dt><dd>ada@example.com</dd>
  <dt>Member since</dt><dd>2026-09-29 04:32:55</dd>
...
  <p class="alert">Your email address is not confirmed yet.</p>
...

Invalid input re-renders the form with status 422 and every message at once (emails are compared without case):

curl -s http://localhost:8787/signup -d 'email=ADA@example.com&password=short'

...
  <ul class="errors">
    <li>Password is too short (minimum is 8 characters)</li><li>Email has already been taken</li>
  </ul>
...

Log out (POST, so other sites cannot log users out with a link), then log in:

curl -s -c jar.txt -b jar.txt -X POST http://localhost:8787/logout -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s -c jar.txt -b jar.txt http://localhost:8787/login -d 'email=ada@example.com&password=wrong' -o /dev/null -w '%{http_code}\n'
curl -s -c jar.txt -b jar.txt http://localhost:8787/login -d 'email=Ada@Example.com&password=correct horse' -o /dev/null -w '%{http_code} %{redirect_url}\n'

303 http://localhost:8787/
422
303 http://localhost:8787/

The failed login re-renders the form with “Invalid email or password.” whether the email or the password was wrong. After a successful login the user goes back to the page that asked for it (only a path of this app: ocre::security::url_from refuses anything else), or /.

Remember me and session expiry

Every sign-in lasts two weeks (SESSION_SECONDS in src/auth.rs). The expiry time is stored inside the encrypted session cookie and checked on every request, so a copied cookie stops working after it too. Without “Remember me” the cookie ends with the browser session; with the box ticked (remember_me=1) it is persistent:

curl -si -c jar.txt -b jar.txt http://localhost:8787/login -d 'email=ada@example.com&password=correct horse&remember_me=1' | grep -i set-cookie

Set-Cookie: _ocre_session=...; HttpOnly; SameSite=Lax; Path=/; Max-Age=1209600

sign_in calls session.remember_for(SESSION_SECONDS) or session.expire_in(SESSION_SECONDS); use the same methods of ocre::Session for other expiring state (see Sessions, flash and security).

Magic links

GET /magic_link shows a form asking for an email; POST /magic_link emails a sign-in link valid 15 minutes. The answer is the same redirect to /login (“If an account exists for that email, a sign-in link is on its way.”) whether or not the address has an account:

curl -s http://localhost:8787/magic_link -d 'email=ada@example.com' -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s http://localhost:8787/magic_link -d 'email=nobody@example.com' -o /dev/null -w '%{http_code} %{redirect_url}\n'

303 http://localhost:8787/login
303 http://localhost:8787/login

With MAIL_ADAPTER=log (what ocre new puts in .dev.vars) the email is printed in the ocre dev output:

[ocre mail] not sent (MAIL_ADAPTER = "log")
From: shop <noreply@example.com>
To: ada@example.com
Subject: Your sign-in link

Open this link within 15 minutes to sign in:

http://localhost:8787/magic_link/e_ZL4u_uKZl0rYbpJe82lyqwQUPnFZTCOzUC59bGE2E

If you did not ask for it, ignore this email.

[ocre mail] HTML version:
<p><a href="http://localhost:8787/magic_link/e_ZL4u_uKZl0rYbpJe82lyqwQUPnFZTCOzUC59bGE2E">Sign in</a> (valid 15 minutes).</p><p>If you did not ask for it, ignore this email.</p>
[ocre mail] end

Opening the link (GET) shows a page with a “Sign in” button; the button POSTs to the same URL, which uses the token up and signs in. Mail scanners that follow links therefore do not consume it. A second use fails:

curl -s -c jar.txt -b jar.txt -X POST http://localhost:8787/magic_link/e_ZL4u_uKZl0rYbpJe82lyqwQUPnFZTCOzUC59bGE2E -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s -c jar.txt -b jar.txt -X POST http://localhost:8787/magic_link/e_ZL4u_uKZl0rYbpJe82lyqwQUPnFZTCOzUC59bGE2E -o /dev/null -w '%{http_code} %{redirect_url}\n'

303 http://localhost:8787/
303 http://localhost:8787/magic_link

The second redirect carries the alert “That sign-in link is invalid or has expired.” Requesting a new link cancels the previous one.

Password reset

GET /passwords/new asks for an email; POST /passwords emails a reset link (same answer whether or not the account exists):

curl -s http://localhost:8787/passwords -d 'email=ada@example.com' -o /dev/null -w '%{http_code} %{redirect_url}\n'

303 http://localhost:8787/login

[ocre mail] not sent (MAIL_ADAPTER = "log")
From: shop <noreply@example.com>
To: ada@example.com
Subject: Reset your password

Open this link within 15 minutes to choose a new password:

http://localhost:8787/passwords/B8iQKwfm0L86-KOJuVtrep857CdZO0yfERAlZ3ntLFs
...

GET /passwords/{token} shows the form (an invalid or expired token redirects to /passwords/new with an alert). POST /passwords/{token} checks password and password_confirmation, then uses the token up, changes the password and redirects to /login:

T=B8iQKwfm0L86-KOJuVtrep857CdZO0yfERAlZ3ntLFs
curl -s http://localhost:8787/passwords/$T -d 'password=new password&password_confirmation=typo' -w '\n%{http_code}\n'
curl -s http://localhost:8787/passwords/$T -d 'password=new password 2&password_confirmation=new password 2' -o /dev/null -w '%{http_code} %{redirect_url}\n'

...
  <ul class="errors">
    <li>Password confirmation doesn&#39;t match Password</li>
  </ul>
...
422
303 http://localhost:8787/login

A validation error does not use the token up, so the user can correct the form. The reset also confirms the email address (the link was opened from the mailbox). A password change does not sign out other browsers with cookie sessions; with --db-sessions, “Sign out everywhere else” does (see Sessions tracked in D1).

Email confirmation

Sign-up emails a confirmation link valid 24 hours (src/confirmations.rs); the account works before it is confirmed:

[ocre mail] not sent (MAIL_ADAPTER = "log")
From: shop <noreply@example.com>
To: ada@example.com
Subject: Confirm your email address

Confirm your email address by opening this link within 24 hours:

http://localhost:8787/confirmations/<token>
...

Like magic links, GET /confirmations/{token} shows a button and POST uses the token up, sets users.confirmed_at and redirects to /account with “Thanks, your email address is confirmed.” An invalid, expired or used link gets “That confirmation link is invalid or has expired.” The account page of an unconfirmed user has a “Send a new confirmation link” button (POST /confirmations). Signing in with a magic link, resetting the password or signing in with an OAuth provider whose email is verified also confirms the address.

Pages that need a confirmed address take ConfirmedUser instead of CurrentUser (next section).

Protect HTML pages

Take one of the extractors from src/auth.rs as a handler argument:

They read user_id from the session and load the user with one D1 query (with --db-sessions, one query joining the session and the user). This module adds a dashboard for signed-in users and a greeting for everyone; register it with mod dashboard; under // ocre:modules and .merge(dashboard::routes()) under // ocre:routes in src/lib.rs:

// src/dashboard.rs
use askama::Template;
use axum::{Router, extract::State, response::Html, routing::get};
use ocre::{Ctx, Flash, Result, render};

use crate::{
    auth::{CurrentUser, OptionalUser},
    models::{
        api_key::{self, ApiKey},
        user::User,
    },
};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/dashboard", get(show)).route("/hello", get(hello))
}

#[derive(Template)]
#[template(
    source = r#"{% if let Some(notice) = flash.notice() %}<p class="notice">{{ notice }}</p>{% endif %}
<h1>Dashboard of {{ user.email }}</h1>
<ul>{% for key in keys %}<li>{{ key.name }}</li>{% endfor %}</ul>
<form method="post" action="/logout"><button>Log out</button></form>"#,
    ext = "html"
)]
struct DashboardView {
    flash: Flash,
    user: User,
    keys: Vec<ApiKey>,
}

/// Visitors are redirected to /login, then back here after logging in.
async fn show(State(ctx): State<Ctx>, CurrentUser(user): CurrentUser, flash: Flash) -> Result<Html<String>> {
    let keys = api_key::for_user(&ctx, user.id).await?;
    render(&DashboardView { flash, user, keys })
}

/// Works for everyone; greets signed-in users by email.
async fn hello(OptionalUser(user): OptionalUser) -> String {
    match user {
        Some(user) => format!("Hello, {}", user.email),
        None => "Hello, visitor".to_owned(),
    }
}

Run against ocre dev, signed out then signed in:

curl -s -c jar.txt -b jar.txt http://localhost:8787/dashboard -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s -c jar.txt -b jar.txt http://localhost:8787/login -d 'email=Ada@Example.com&password=correct horse' -o /dev/null -w '%{http_code} %{redirect_url}\n'
curl -s -c jar.txt -b jar.txt http://localhost:8787/dashboard
curl -s -b jar.txt http://localhost:8787/hello; echo
curl -s http://localhost:8787/hello; echo

303 http://localhost:8787/login
303 http://localhost:8787/dashboard
<p class="notice">Signed in.</p>
<h1>Dashboard of ada@example.com</h1>
<ul></ul>
<form method="post" action="/logout"><button>Log out</button></form>
Hello, ada@example.com
Hello, visitor

To sign a user in from your own code (after an invitation, say), call auth::sign_in(&session, &user)?: it empties the session first, stores only the user id, and returns the path to redirect to. Sign out with auth::sign_out(&session)?. Never put more than the id in the session.

JSON clients: JWTs and API keys

JSON clients cannot rely on the session cookie; they send Authorization: Bearer <token>, where the token is a JWT or an API key. These routes come from src/auth_api.rs:

Sign up and get a JWT:

curl -s -X POST http://localhost:8787/api/auth/signup -H 'content-type: application/json' \
  -d '{"email":"grace@example.com","password":"correct horse"}'
curl -s -X POST http://localhost:8787/api/auth/token -H 'content-type: application/json' \
  -d '{"email":"grace@example.com","password":"correct horse"}'

{"id":2,"email":"grace@example.com","created_at":"2026-09-29 04:35:02","updated_at":"2026-09-29 04:35:02"}
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyIiwiaWF0IjoxNzkwNjU2NTAyLCJleHAiOjE3OTA2NjAxMDJ9.tucAZ1VrmMVeU7i0etJVIr568y13Iit2xJwJdsXs4Ag","token_type":"Bearer","expires_in":3600}

Wrong credentials, or a missing or invalid token, get a JSON 401 with WWW-Authenticate: Bearer:

curl -si -X POST http://localhost:8787/api/auth/token -H 'content-type: application/json' \
  -d '{"email":"grace@example.com","password":"nope"}'

HTTP/1.1 401 Unauthorized
Transfer-Encoding: chunked
Content-Type: application/json
WWW-Authenticate: Bearer
...

{"error":{"message":"Unauthorized","status":401}}

Use the JWT, then create a long-lived API key with it:

TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
curl -s http://localhost:8787/api/auth/me -H "Authorization: Bearer $TOKEN"
curl -s -X POST http://localhost:8787/api/auth/keys -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"name":"CI deploys"}'
curl -s http://localhost:8787/api/auth/keys -H "Authorization: Bearer $TOKEN"

{"id":2,"email":"grace@example.com","created_at":"2026-09-29 04:35:02","updated_at":"2026-09-29 04:35:02"}
{"key":"5DNdPEYb0h2uCpRSUS4jFm-i05HI1DthdAgyL5tL_aY","api_key":{"id":1,"user_id":2,"name":"CI deploys","last_used_at":null,"created_at":"2026-09-29 04:35:11"}}
[{"id":1,"user_id":2,"name":"CI deploys","last_used_at":null,"created_at":"2026-09-29 04:35:11"}]

The key works like a JWT: Authorization: Bearer 5DNd.... It is used in the next sections as $KEY, and revoked at the end of Records that belong to a user.

JWTs versus API keys:

Bearer requests without an Origin or Sec-Fetch-Site header (curl, servers, mobile apps) pass the CSRF check; a separate browser frontend on another origin needs ALLOWED_ORIGINS (see Sessions, flash and security).

Protect JSON endpoints

Take BearerUser(user): BearerUser from src/auth_api.rs. It accepts a JWT (anything with dots) or an API key, loads the user, and otherwise answers the JSON 401 above; a deleted user’s tokens stop working. Put it before Json(..) in the arguments (axum runs the body extractor last).

This endpoint returns one of the caller’s API keys. The user_id condition in the query is the ownership check: another user’s key is “not found”, exactly like a missing one, so the answer reveals nothing. Register it like the dashboard module:

// src/my_keys_api.rs
use axum::{
    Router,
    extract::{Path, State},
    routing::get,
};
use ocre::{ApiResult, Ctx, Json, OptionExt, Result, params};

use crate::{auth_api::BearerUser, models::api_key::ApiKey};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/api/my/keys/{id}", get(show))
}

/// One of the user's API keys. The `user_id` condition is the ownership
/// check: another user's key is "not found", exactly like a missing one.
pub async fn find_owned(ctx: &Ctx, user_id: i64, id: i64) -> Result<Option<ApiKey>> {
    ctx.db()?
        .first(
            "SELECT id, user_id, name, last_used_at, created_at FROM api_keys WHERE id = ?1 AND user_id = ?2",
            params![id, user_id],
        )
        .await
}

/// 401 JSON without a valid `Authorization: Bearer <JWT or API key>`.
async fn show(State(ctx): State<Ctx>, BearerUser(user): BearerUser, Path(id): Path<i64>) -> ApiResult<Json<ApiKey>> {
    Ok(Json(find_owned(&ctx, user.id, id).await?.or_404()?))
}

With Grace’s API key, then with a JWT of Ada (user 1, from POST /api/auth/token with her email and password):

KEY=5DNdPEYb0h2uCpRSUS4jFm-i05HI1DthdAgyL5tL_aY
ADA=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiaWF0IjoxNzkwNjU2NTE3LCJleHAiOjE3OTA2NjAxMTd9.j6v-x42xurVULPJno1bh4lxP038jiRKVAFqac45QZoY

curl -s http://localhost:8787/api/my/keys/1 -H "Authorization: Bearer $KEY"
curl -s http://localhost:8787/api/my/keys/1 -H "Authorization: Bearer $ADA" -w ' %{http_code}\n'

{"id":1,"user_id":2,"name":"CI deploys","last_used_at":"2026-09-29 04:35:17","created_at":"2026-09-29 04:35:11"}
{"error":{"message":"Not found","status":404}} 404

last_used_at was set by the first request made with the key.

Records that belong to a user

Give a table a user_id column with references, then filter every query by the signed-in user’s id.

ocre g model Note title:string user:references

  create  migrations/0005_create_notes.sql
  create  src/models/note.rs
  update  src/models/user.rs
  update  src/models/mod.rs

Next:
  ocre migrate
  cargo check --target wasm32-unknown-unknown

The migration has user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE (a user’s notes are deleted with the user) and an index on user_id. src/models/note.rs gets note.user(&ctx), and src/models/user.rs gets the list query, already filtered by owner:

impl User {
    // ocre:associations
    /// Notes of this user, newest first.
    pub async fn notes(&self, ctx: &Ctx, page: ocre::Page) -> Result<Vec<crate::models::note::Note>> {
        ctx.db()?
            .all(
                "SELECT * FROM notes WHERE user_id = ?1 ORDER BY id DESC LIMIT ?2 OFFSET ?3",
                params![self.id, page.limit, page.offset],
            )
            .await
    }
}

A JSON API over the notes then takes the owner from the token, never from the request body, and answers 404 for other users’ notes:

// src/notes_api.rs
use axum::{
    Router,
    extract::{Path, State},
    routing::get,
};
use ocre::{ApiResult, Created, Ctx, Error, Json, Page};
use serde::Deserialize;

use crate::{
    auth_api::BearerUser,
    models::note::{self, NewNote, Note},
};

pub fn routes() -> Router<Ctx> {
    Router::new().route("/api/notes", get(index).post(create)).route("/api/notes/{id}", get(show))
}

#[derive(Deserialize)]
struct NoteInput {
    title: String,
}

async fn index(State(ctx): State<Ctx>, BearerUser(user): BearerUser, page: Page) -> ApiResult<Json<Vec<Note>>> {
    Ok(Json(user.notes(&ctx, page).await?))
}

async fn create(State(ctx): State<Ctx>, BearerUser(user): BearerUser, Json(input): Json<NoteInput>) -> ApiResult<Created<Note>> {
    // The owner comes from the token, never from the request body.
    Ok(Created(note::create(&ctx, NewNote { title: input.title, user_id: user.id }).await?))
}

async fn show(State(ctx): State<Ctx>, BearerUser(user): BearerUser, Path(id): Path<i64>) -> ApiResult<Json<Note>> {
    match note::find(&ctx, id).await? {
        Some(note) if note.user_id == user.id => Ok(Json(note)),
        _ => Err(Error::NotFound.into()),
    }
}

Grace creates a note; Ada cannot see it:

curl -s -X POST http://localhost:8787/api/notes -H "Authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{"title":"Buy flour"}'
curl -s http://localhost:8787/api/notes/1 -H "Authorization: Bearer $ADA" -w ' %{http_code}\n'
curl -s http://localhost:8787/api/notes -H "Authorization: Bearer $ADA"; echo

{"id":1,"title":"Buy flour","user_id":2,"created_at":"2026-09-29 04:35:17","updated_at":"2026-09-29 04:35:17"}
{"error":{"message":"Not found","status":404}} 404
[]

Finally, Grace revokes her API key; it stops working at once:

curl -s -X DELETE http://localhost:8787/api/auth/keys/1 -H "Authorization: Bearer $KEY" -w '%{http_code}\n'
curl -s http://localhost:8787/api/auth/me -H "Authorization: Bearer $KEY" -w ' %{http_code}\n'

204
{"error":{"message":"Unauthorized","status":401}} 401

Rules for owned records:

• Filter in SQL (WHERE id = ?1 AND user_id = ?2) for updates and deletes, so one statement both checks and acts; api_key::revoke in src/models/api_key.rs does this.
• Answer Error::NotFound for other users’ records, so ids of other users’ data are not confirmed. Use Error::Forbidden (403) when the user may know the record exists but may not change it (a shared document that only its owner edits).
• The HTML scaffold pages of ocre g scaffold do not check ownership; add CurrentUser and the user_id filter to each handler that should be private.

Add a column to users

Add a migration, apply it, then update the model by hand (the generator does not edit user.rs):

ocre g migration add_name_to_users name:string?
ocre migrate

  create  migrations/0006_add_name_to_users.sql

Next:
  ocre migrate
  update the model in src/models/ to match the new columns

-- Migration: add_name_to_users
-- Applied once, in file-name order. Never edit a migration after it has been applied.
ALTER TABLE users ADD COLUMN name TEXT;

In src/models/user.rs: add pub name: Option<String>, to User (it is serialized in JSON answers; keep #[serde(skip_serializing)] for anything secret), pub name: String, to NewUser (missing in a form or JSON body means empty, thanks to #[serde(default)]), a rule in NewUser::validate (v.max_length("name", &self.name, 100);), and the column in the INSERT of create:

    let name = Some(new.name.trim()).filter(|name| !name.is_empty());
    db.first(
        "INSERT INTO users (email, password_digest, name) VALUES (?1, ?2, ?3) RETURNING *",
        params![email, password_digest, name],
    )

For the HTML sign-up, add <label>Name <input name="name"></label> to templates/auth/signup.html. The JSON sign-up takes it right away:

curl -s -X POST http://localhost:8787/api/auth/signup -H 'content-type: application/json' \
  -d '{"email":"linus@example.com","password":"correct horse","name":"Linus"}'
curl -s -X POST http://localhost:8787/api/auth/signup -H 'content-type: application/json' \
  -d '{"email":"bad","password":"short"}'

{"id":3,"email":"linus@example.com","name":"Linus","created_at":"2026-09-29 04:42:46","updated_at":"2026-09-29 04:42:46"}
{"error":{"fields":{"email":["is invalid"],"password":["is too short (minimum is 8 characters)"]},"message":"Validation failed","status":422}}

Account deletion

POST /account/delete with confirmation (the password, or the email address for users without one) deletes the user and signs out; tokens, API keys, sessions and identities go with it (ON DELETE CASCADE). JSON clients send DELETE /api/auth/me with {"password": "..."}: 204, or 403 for a wrong password.

Rate limiting

Every route that checks a password or sends an email calls throttle(&ctx, &headers, "login") (in src/auth_api.rs), which counts one attempt per action and client IP address (ocre::remote_ip) with ocre::security::rate_limit against the AUTH_RATE_LIMITER Workers Rate Limiting binding. Over 10 a minute the answer is 429 Too Many Requests (JSON: {"error":{"status":429,"message":"Too many requests. Try again later."}}). The binding is on the free plan, uses no D1 or KV operation, and ocre dev simulates it; counters are per Cloudflare location and approximate. Change limit and period (10 or 60 seconds) in cloudflare.config.ts.

Sessions tracked in D1

With ocre g auth --db-sessions, each sign-in is a row of user_sessions (IP address, browser, last activity, expiry) and the cookie holds a random token whose SHA-256 digest finds the row (Rails 8’s Session model). /account/sessions lists the signed-in devices, “Sign out” ends one, “Sign out everywhere else” ends all others; deleting a row signs that device out on its next request. Cost: every signed-in request reads the session and its user (one query, 2 D1 rows); last_seen_at is written at most once an hour.

Continue with GitHub or Google

With ocre g auth --oauth github,google, the login page gets one button per provider. src/oauth.rs runs the OAuth 2.0 code flow with PKCE through ocre::oauth: POST /auth/{provider} stores a random state and PKCE verifier in the session and redirects to the provider; GET /auth/{provider}/callback checks the state, trades the code for a token, reads the profile, and signs in the user linked to that account (identities table), else the user with the same verified email (then linked), else a new confirmed user without a password. Register an OAuth app with the callback URL https://<your host>/auth/<provider>/callback (and one for http://localhost:8787), put GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET (or GOOGLE_...) in .dev.vars, and upload them with ocre secrets push GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET --file .prod.vars (a git-ignored file of NAME=value lines). A sign-in costs 2 or 3 subrequests of the 50 a free-plan request may make.

Framework primitives

The generated code is built on these ocre items; use them for your own flows (invitations, email confirmation, one-time codes):

Store only token::digest(&token) for secrets you email or show once, and look rows up by digest, as src/models/auth_token.rs and src/models/api_key.rs do. The full signatures are in the API index and the rustdoc of ocre::password, ocre::token and ocre::jwt.

Before going public

• Mail. Magic links and password resets call ocre::mail::send. Without MAIL_ADAPTER in production, POST /magic_link and POST /passwords answer 500 and the log says cannot send email: MAIL_ADAPTER is not set. Fix: .... For sign-up and reset mail to any address on the free plan, use Resend (100 emails a day, 3,000 a month, September 2026); see Email.
• Rate limiting. Keep the AUTH_RATE_LIMITER entry in cloudflare.config.ts (see Rate limiting): each password check costs about 5.5 ms of CPU, and every emailed link costs a send from your mail quota. Its counters are per Cloudflare location and approximate; with a custom domain, a Cloudflare WAF rate limiting rule on /login, /signup, /magic_link, /passwords and /api/auth/* adds a limit before the Worker runs (see Deployment).
• OAuth. With --oauth, put the provider’s ..._CLIENT_ID and ..._CLIENT_SECRET in .prod.vars and upload them with ocre secrets push GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET --file .prod.vars, and register the production callback URL with the provider.
• Secret. ocre deploy creates SECRET_KEY_BASE on the first deploy; never commit .dev.vars.

Security choices

In short (the reasoning is in Security model):

• Passwords: PBKDF2-HMAC-SHA256 with 100,000 iterations through WebCrypto, the most Workers accept (OWASP recommends 600,000; bcrypt or argon2 in WebAssembly would not fit in 10 ms of CPU). A login with an unknown email hashes too, so response times do not reveal accounts.
• Sessions: the encrypted cookie holds only user_id (with --db-sessions, a random session token whose digest finds the D1 row) and its expiry; login empties the session first, logout clears it. CurrentUser only returns to local paths (no open redirect).
• Emailed tokens: 256 random bits, stored as SHA-256 digests, valid 15 minutes (email confirmation links: a day), used up by one DELETE ... RETURNING (single use even under concurrent requests); a new request cancels the previous link; links open a page whose button POSTs. Links use the request’s origin.
• JWTs: HS256 only, key derived from SECRET_KEY_BASE with a fixed label (so it differs from the cookie key); no separate JWT_SECRET. Rotating SECRET_KEY_BASE signs everyone out of sessions and tokens at once, unless the old value is kept in SECRET_KEY_BASE_PREVIOUS for a while (see Rotating SECRET_KEY_BASE without signing everyone out).
• API keys: 256 random bits shown once, stored as SHA-256 digests, revocable; last_used_at written at most once an hour to save D1 writes.

What is not included

• Revoking cookie sessions before they expire, unless you use --db-sessions.
• Roles and permissions: Error::Forbidden is there for your own checks.
• Revoking a JWT before it expires (use API keys for long-lived access).

See also

• ocre g auth in the generators reference.
• Sessions, flash and security: sessions, CSRF, ALLOWED_ORIGINS, headers.
• Email: mail adapters for magic links and password resets.
• JSON APIs and GraphQL: ApiResult, errors, pagination.
• Models and migrations: references, migrations, associations.
• Security model.