Intelligent, Security-Conscious, and Designed for Effortless Productivity

Because With Rullst, We Rule! Rullst is a modular Rust framework suite built on Tokio, Axum, Tower, and SQLx for full-stack applications and the product workflows around them. Version 13 is in prerelease: 13.0.0-alpha.4 is published and is the 13.0 feature freeze. The v12 line reached end of life on 16 October 2026. Use the capability and release documents to distinguish implemented behavior from roadmap work and application-specific responsibilities. This book is built from the main branch, which can be ahead of the latest prerelease; the v13 Preview chapters describe features that are new in v13.

Welcome to the Rullst documentation. Build a small application, understand the code behind it, then explore the tools that fit your next idea.

New here? Start with the guided learning path →

Choose a generated application, a hand-written first route or a JSON API. Each path tells you what to run, what to expect and where to go next.

Documentation Hub

• ✨ Why Rullst?
• 📖 Getting Started & Starters
• 🤖 Rullst AI: Developing with Autonomous Agents
• 📊 Rullst Studio: Real-Time Monitoring & Radar
• ⚙️ Rullst Nexus: Explicit Admin CMS
• 💳 Rullst Capital: SaaS Billing & Revenue Dashboard
• 🧠 Integrating AI into Rullst
• 🍳 Rullst Cookbook & Tutorials
• 📜 Framework Spec
• 🗺️ Blueprints Roadmap
• 💻 CLI Reference
• 🛡️ Audit Report
• 📦 View on Crates.io

For AI assistants

The site publishes llms.txt, an index of every page of this book in reading order, and llms-full.txt, the full Markdown of those pages in one file. Both are generated from this book’s sources each time it is published, so they describe the same main branch.

Learn the foundations, then explore

• 🚀 Measured performance: Criterion suites and CI track regressions; application latency must be measured on the target workload.
• 🧩 Server-rendered UI: html! and HTMX-oriented scaffolds are the audited default. LiveView and Wasm Island primitives exist, while turnkey Leptos/Dioxus adapters remain roadmap work.
• 📖 Interactive Scalar Docs (/docs): cargo rullst make:scalar scaffolds an OpenAPI viewer for your reviewed specification.
• ☸️ Kubernetes manifests: cargo rullst make:k8s scaffolds manifests that probe /health and /ready.
• 📡 Rullst Radar & Prometheus: Process/Tokio observations and a Prometheus text exporter, with unavailable probes reported explicitly.
• 🛡️ Local AI option: Use an Ollama endpoint when prompts should stay on infrastructure you control; network isolation remains a deployment duty.
• 📦 Batteries Included: ORM (rullst-orm), Auth, Revenue Dashboard, Jobs, Mail, Scheduler, Cache, Security.

Your first idea, running in Rust

You do not need to understand every Rullst crate before writing your first application. Start small, make one thing work, and learn what each layer does as your product needs it.

This guide targets the v13 prerelease, 13.0.0-alpha.4. The v12 line reached end of life on 16 October 2026 and a new 12.x project no longer resolves its dependencies, so install the CLI and pin the framework with the exact version, as Getting Started shows: Cargo never selects a prerelease on its own. Upgrading an existing application? Follow the v13 migration guide. This book is built from main, where v13 is in development.

Pick your starting line

For the simplest first experiment, choose Blank + SQLite, or Blank with --no-database if you do not need persistence yet. The larger SaaS starter, and the LMS, ERP, Portfolio and Blog examples, have more moving parts and longer first builds. You can explore them after your toolchain and local workflow are working.

A small loop that teaches a lot

1. Run it. Reach the local page or JSON endpoint before adding features.
2. Find the code. Open src/main.rs, then the generated controllers, models and pages that exist in your chosen starter.
3. Make one visible change. Edit a heading or response field. With cargo rullst dev, watch the rebuild and process restart; with plain cargo run, stop and restart it yourself.
4. Break something safely. Introduce a small syntax error in your local experiment. Read the compiler diagnostic, correct it and save again. The supervisor keeps the old application running when compilation fails.
5. Verify the result. Reload the page or repeat the request. A successful build is only the first check; the response should do what you intended.

See exact restart and state boundaries. Do not use production databases or credentials for this exercise.

Build your understanding, one layer at a time

Looking for a type, a feature or a connected REST learning path? Use the API reference index to move between the guides and the versioned Rust documentation.

You can use an AI assistant while learning. Ask it to explain the generated files, point to the exact APIs and show a failing test before a bug fix. Treat its output as a proposed change, not as proof. Rullst’s architecture specification is the common reference for both of you.

When the first run does not work

If you are still stuck, share the command, operating system, Rust version, framework commit and a minimal reproduction in an issue or on Discord. Remove secrets and personal data first. Send security vulnerabilities privately using the security policy.

Before this becomes a real product

A generated app is a foundation, not a deployment approval. Review authentication, ownership, secrets, database backups and migrations, external provider setup and release status. Start with the security architecture, choose features using the capability status, check each crate’s maturity tier (Core, Extension or Experimental), and measure your own workload.

Ready? Create your first application →

Getting Started

Welcome to the Rullst Getting Started guide!

Your goal: install the matching v13 CLI, generate a small application, open it locally and make your first change. Prefer to write the first route yourself? Use Zero to Hello Rullst.

Rullst is a strictly typed Rust framework suite for full-stack applications, designed around explicit APIs, measurable performance, and defense-in-depth defaults.

1. Installation

First, ensure you have Rust installed. The official and recommended way is to visit rustup.rs.

For macOS and Linux:

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

For Windows: Download and run rustup-init.exe from the website.

Next, install the Rullst CLI from the same release train as the framework. This book is built from main, where v13 is in development. The v12 line reached end of life on 16 October 2026 (12.3.0 was its last release, and a new 12.x project no longer resolves its dependencies after crates.io yanked the zip releases its Studio needs), so install the v13 prerelease. Name its exact version: Cargo never selects a prerelease on its own, so neither a plain cargo install cargo-rullst nor ^13 installs it:

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked

Pin the framework the same way in Cargo.toml ("=13.0.0-alpha.4"); the v13 migration guide explains why and what changed.

Source reviewers who intentionally need checkout-local changes can instead clone this repository and install the CLI from that exact checkout. On main this installs the v13 development CLI:

git clone --branch main https://github.com/Rullst/Rullst.git
cd Rullst
cargo install --locked --path cargo-rullst
cd ..

When installed from source, the CLI reuses the exact checkout from which it was compiled, even when project creation is invoked from another directory, provided that checkout has not been moved or deleted. Generated manifests therefore contain absolute path dependencies and are not portable. Running from the repository root remains an explicit fallback. Prefer the published prerelease and its matching registry packages for ordinary applications.

Cargo installs the cargo-rullst and rullst executables into $CARGO_HOME/bin (~/.cargo/bin by default). To install elsewhere, set CARGO_INSTALL_ROOT or pass --root <dir>. To remove the CLI, run:

cargo uninstall cargo-rullst

Add the same --root <dir> if you installed with one.

2. Creating Your First Project

Run the create wizard with the name of your application (or run cargo rullst alone and choose Create New Project on its home screen):

cargo rullst new my_app

The wizard asks its questions in a terminal and writes nothing until you confirm. Esc goes back one question.

1. Starter: Blank, API or SaaS, each with a one-line description and a preview of the files it generates (see Rullst Starters).
2. Database: the primary database. SQLite is the simplest local first run; PostgreSQL, MySQL and MariaDB need their database service running.
3. Features: optional features such as AI, Redis or a storage add-on. Selecting none is valid; a storage add-on is not another primary database.
4. Review: the files and the commands it will run. Choose Create the project, Back to change an answer, or Cancel to exit without creating anything.

For a database-backed app, the CLI then compiles the new application once and runs its initial migration, and prints three numbered next steps: cd my_app, cargo rullst dev and the local URL of the generated welcome page, by default http://127.0.0.1:3000:

cd my_app
cargo rullst dev

Open the local URL reported by the command. Find the generated page code, change a heading and save. Confirm that the changed page appears after the successful rebuild/restart. Stop development with Ctrl+C before moving or removing the project directory.

cargo rullst new my_app --default --dry-run prints the plan, its file tree and the commands without creating anything, and cargo rullst tour walks through the main commands without changing a project. Without a terminal (in CI or a script), new needs --default; flags such as --blueprint and --database answer their questions. See the CLI reference.

Prefer a small deterministic starter without navigating the wizard?

cargo rullst new first_app --default --blueprint blank --database sqlite \
  --skip-initial-migration
cd first_app
cargo rullst dev

The first build compiles every dependency and can take several minutes (about two and a half minutes for the Blank starter on the machine measured in Build times, which also has tips). --skip-initial-migration defers the generator’s bootstrap work; the development command runs the initial migration before starting a generated database-backed app. Never point this learning project at a production database.

Tip

The cargo rullst dev command compiles the project and starts the local server. Saving changes triggers a real rebuild and supervised process restart; a failed build leaves the previous application serving. The same-origin browser client refreshes after the new process responds with its generation marker. In-memory state resets. No hot-reload scaffold option is required. See the CLI reference.

The CLI deliberately generates one audited application profile: Active Record with server-rendered html! views and HTMX enhancement. The framework still exposes lower-level repository and client-runtime foundations for application-owned integration. See the Architecture Choices Guide.

3. Rullst Starters

cargo rullst new generates one of three starters. The wizard asks which one (or pass --blueprint blank, api or saas); each uses the Rullst color scheme and server-rendered HTML/HTMX patterns, and allocation and latency depend on the generated page and runtime.

Blank

Use Case: Custom, from-scratch development. This is the minimal template powered by server-rendered html! views and HTMX without a project-local JavaScript bundle. It includes a simple reactive counter to demonstrate server-driven communication. Other frontend foundations remain available as application APIs, but are not advertised as equivalent generated starters.

API

Use Case: Headless JSON services. The Blank starter without HTML (--blueprint api, or --api): JSON routes, an example write route protected by a bearer API_TOKEN written to .env, and the same production security baseline. It can run without a database (--no-database) or with Turso as its primary.

SaaS

Use Case: Subscription-based products and billing. An opinionated SaaS starting point, pre-wired with:

• User authentication (login, signup, session management, sign out everywhere, password change and password reset by email with links built from RULLST_PUBLIC_ORIGIN).
• Stripe pricing panels and subscription checkout views.
• Secure user dashboard and a Nexus admin for signed-in administrators.

Larger example applications

Up to 13.0.0-alpha.3 the CLI also generated LMS, Blog, Portfolio and ERP starters. Since 13.0.0-alpha.4 they are complete applications in the repository’s examples/ directory — examples/lms (courses, lessons, an accessible player, enrollment and owner-bound progress), examples/erp (products, stock and orders), examples/portfolio (a developer showcase edited in Nexus) and the examples/blog showcase — tested in the workspace. Copy one to start a bigger application; cargo rullst new --blueprint lms (or erp, portfolio, blog) creates nothing and names the example instead.

Tip

Starter evolution: Starters are continuously checked by generator smoke tests. Treat generated code as an application starting point: inspect its configuration and rerun cargo check and security tests after customization.

Local Studio and Nexus access

The SaaS starter (and the LMS, ERP, Portfolio and Blog examples) expose visible buttons for both control surfaces during local development:

• Nexus is mounted at /nexus and accepts only a verified loopback peer in a debug build, so the first local click needs no placeholder password.
• Studio starts as a separate debug-only service at http://127.0.0.1:5555.

This convenience cannot be enabled in a release binary through RULLST_ENV or the legacy APP_ENV alias. A release build does not start the generated Studio task, and Nexus needs a real sign-in:

• SaaS (and the LMS example) admit the user signed in to the application whose users.is_admin column is true, checked on every request; no extra credentials. Grant the first administrator with your database client (UPDATE users SET is_admin = TRUE WHERE email = '[email protected]';); that administrator can grant others from the Users model in Nexus. See using the application’s sign-in.
• The Portfolio and ERP examples require unique NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD values (Basic Auth behind verified TLS). Without them the application starts without /nexus (the ERP without its back office) and prints one line naming the missing variable; see serving the application without Nexus. The blog example needs the same variables in a release build and does not start without them.

Put production Nexus behind a verified TLS boundary; do not expose Studio publicly. Studio has no production mode: it runs only in debug builds and on loopback.

4. Database configuration and specialized stores

The wizard deliberately makes two separate decisions:

1. Choose the primary SQLx Active Record backend: SQLite, PostgreSQL, MySQL, or MariaDB. MariaDB uses the MySQL wire protocol but has its own executable container contract. The Blank starter (web page or JSON API) can instead select Turso/libSQL as its primary database, through a separate adapter that has no Nexus, Studio database pages, Schema migrations, artisan! or SQLx query builder.
2. Optionally add side stores: Turso/libSQL edge SQL, MongoDB documents, DuckDB analytics, SurrealDB documents/graph reads, Qdrant vectors or Redis structures. They use their own APIs and do not replace the primary pool.

Database Support lists what each backend works with; read it before you choose.

After generation, the default flow compiles the new application once and runs its initial migration. A clean first build can take several minutes for the larger SaaS starter. Use --skip-initial-migration when the network database is not yet configured, then run cargo rullst db:migrate from the generated project. cargo rullst dev applies pending migrations when it starts, but a deployed server never does: run the binary’s db:migrate command on each release, as described in Before the first deploy.

The non-interactive flags mirror the second step:

cargo rullst new edge_app --default --database mariadb --turso --mongodb \
  --skip-initial-migration

Automation can pin the supported starter, database and optional runtime capabilities. The application architecture is intentionally fixed to Active Record plus server-rendered html!/HTMX:

cargo rullst new subscriptions --default --blueprint saas \
  --database postgres --ai \
  --skip-initial-migration

For a blank application with no primary relational database, use the explicit --no-database flag. It cannot be combined with --database. Generated SQLx profiles disable the default features of Rullst’s umbrella and rullst-orm dependencies and select exactly one strict relational backend, so a chosen PostgreSQL/MySQL/MariaDB profile is not accidentally compiled through an implicit SQLite default.

To create a Turso-primary API using the current bounded blank starter:

cargo rullst new edge_api --default --api --database turso \
  --skip-initial-migration
cd edge_api
cargo rullst db:migrate

The generated .env selects a persistent, real-SQL offline fallback and does not invent a SQLx DATABASE_URL:

TURSO_DATABASE_URL=mock_local
TURSO_AUTH_TOKEN=
TURSO_OFFLINE_PATH=turso-development.db

To use Turso Cloud, put the token in its own variable rather than in the URL:

turso db create my-app-db
turso db tokens create my-app-db

TURSO_DATABASE_URL=libsql://my-app-db-username.turso.io
TURSO_AUTH_TOKEN=replace-with-a-secret-token

The familiar derive explicitly selects the Turso backend:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "users", backend = "turso")]
struct User {
    id: i64,
    name: String,
}
}

User::all(), find, save, create, delete, count, filtering, ordering and pagination then execute through the primary TursoOrm store. make:model --migration, make:migration, db:migrate, db:status, and db:rollback preserve this backend. The current first-class scaffold contract is deliberately limited to the Blank and API starters; the SQLx-specific SaaS starter rejects --database turso until ported. Transparent embedded-replica synchronization is not claimed.

TursoStore remains available for prepared SQL, bounded result materialization, transactions and checksummed migrations in either primary or additive configurations. See Polyglot Persistence for complete setup, security constraints and examples for every optional store.

Build Times

Most of the time spent waiting on a Rullst application is cargo build or cargo rullst dev rebuilding it after an edit. This page states what a generated project does to keep those builds short, the measured effect on the three starters, and other things you can try.

What cargo rullst new writes

Since 13.0.0-alpha.4 every generated Cargo.toml has a development profile next to the release profile:

[profile.dev]
debug = "line-tables-only"

[profile.dev.package."*"]
debug = false

• Your package keeps line tables. Panic messages and the frames of your own code in a RUST_BACKTRACE=1 backtrace still show the file and line (at ./src/main.rs:2:11). Frames inside dependencies show the function name without a file and line.
• Dependencies are built without debug information. Their debug information was about half of a debug binary and 41 % of target/: the API starter’s binary went from 83.7 MB to 41.5 MB and its target/ directory from 2.47 GB to 1.45 GB.
• Nothing else changes. Optimisation level, incremental compilation, overflow checks and debug assertions keep Cargo’s development defaults. cargo test uses the same settings (Cargo’s test profile inherits dev), and release builds are unchanged.
• For a debugger that shows local variables, set debug = true in both sections (or delete them). Cargo then rebuilds everything once.

The SaaS starter also no longer declares rullst-connect: its code does not use it, and cargo rullst make:oauth enables the facade’s oauth-* feature instead. Its first build compiles 12 fewer packages.

The generated .cargo/config.toml is unchanged: on Linux it sets -C split-debuginfo=unpacked and selects mold or lld when the generating machine has one, and Git ignores it. With the profile above, split debug information made no measurable difference on Linux (API starter: 146.0 s with it and 149.1 s without for a cold build, 1.34 s and 1.40 s for a rebuild after an edit). macOS already uses unpacked debug information by default and was not measured.

Measurements

Measured on 29 October 2026 with the 13.0.0-alpha.4 development source. The numbers describe these starters on this one machine; they are not a prediction for other applications or hardware.

• Applications: cargo rullst new <name> --default --skip-initial-migration, plus --api or --blueprint saas (SQLite; rullst features orm, strict-sqlite and studio, and nexus, auth, mail and capital for SaaS), with path dependencies on the framework source and the repository’s Cargo.lock, built --offline. Before is the same source without the two changes above.
• Toolchain: Rust 1.99.1, x86_64-unknown-linux-gnu, linked by rustc’s bundled rust-lld (LLD 23.1.1; the default for this target since Rust 1.90). Neither mold nor lld was installed, so the generated .cargo/config.toml selected no linker.
• Machine: AMD Ryzen 5 7520U (8 logical CPUs), 3.4 GiB RAM, NVMe disk, CARGO_BUILD_JOBS=2, a shared workstation; no other Cargo process ran during a measurement.
• Commands: wall-clock time from /usr/bin/time of cargo build --offline and cargo check --offline. Cold starts from an empty target/ (dependencies already downloaded). Edit changes one string literal in a handler (src/main.rs for Blank and API, src/controllers/auth_controller.rs for SaaS) and rebuilds; touch only updates that file’s timestamp. Cold builds: mean of two runs; rebuilds: median of five.

Cold checks are one run each; checks after touch are the median of three. cargo check generates no code and links nothing, so the profile changes it little; its target/ still went from 1.11 to 0.81 GB (SaaS: 1.26 to 0.92 GB). Removing rullst-connect alone, with full debug information, took the cold SaaS build from 203.7 s to 194.1 s and its cold check from 137.9 s to 135.2 s (one run each).

Other development settings, measured the same way on the API starter (one run each):

Line tables for your own package cost nothing measurable, while those of the dependencies cost about ten seconds of every cold build. Without split debug information (no .cargo/config.toml), the full-debug link was also the largest process of the build: 1.2 GiB, against 0.7 to 0.8 GiB for every other setting.

Where a cold build spends its time

cargo build --timings writes target/cargo-timings/cargo-timing.html with the time of every compiled unit. In the generated API and SaaS builds above the longest single unit was the build script of aws-lc-sys, the cryptography library behind the HTTPS client, at about 52 s; then rullst-core (about 13 s), jsonschema (about 9 s) and the SQLite library bundled by libsqlite3-sys (about 6 s). Until 13.0.0-alpha.3 some crates, SQLite among them, were compiled twice: once for SQLx’s compile-time macros and once for the application (see below). None of this depends on your code, so it is paid again only after cargo clean, a toolchain update or a change of features or profile.

Rullst keeps aws-lc-rs as the TLS crypto provider, for rustls’ post-quantum hybrid key exchange, so the aws-lc-sys build script stays in a project’s first build. Since 13.0.0-alpha.4 SQLx shares it (tls-rustls-aws-lc-rs, also in generated projects) instead of compiling rustls’ ring backend as a second provider. Later builds reuse it, and the dependency layer of the generated Dockerfile (the cargo-chef approach) caches it in images; moving TLS to ring is not planned. ring remains a small primitives library (HMAC, digests, randomness, signatures) that the crates using those primitives depend on directly, because it also builds for wasm and edge targets (see cryptography providers).

SQLx macros and the Nexus assistant

Rullst never uses sqlx::query!, but until 13.0.0-alpha.3 rullst-orm and rullst-core enabled SQLx’s macros feature for #[derive(FromRow)]. Every application therefore also compiled sqlx-macros, sqlx-macros-core and, for them, a build-host copy of SQLx, its SQLite driver and the bundled SQLite library. Since 13.0.0-alpha.4 #[derive(Orm)] implements FromRow itself and no Rullst crate enables SQLx’s macros (see the migration guide); the SaaS starter’s Nexus also leaves out its AI assistant and rullst-ai unless the project is created with AI (nexus-ai). cargo tree -i sqlx-macros prints nothing for the Blank, API and SaaS starters.

Measured on the same machine on 29 October 2026 (Rust 1.99.0, CARGO_BUILD_JOBS=2, cold cargo build --offline --timings, mean of two runs, no other Cargo or rustc process during a run). Before is the alpha.4 development source just before this change. The machine is shared, so treat a few seconds as noise: the two SaaS runs after the change took 163.6 s and 144.8 s.

The 62 units no longer built are the two SQLx macro crates and the build-host copies of SQLx, its SQLite driver and their dependencies, the longest being a second run of the SQLite build script (about 12 s); the SaaS starter also drops rullst-ai. An application that enables SQLx’s derive or macros feature itself, for #[derive(sqlx::FromRow)] on its own structs or sqlx::query!, compiles them again.

Tips

• Use cargo check while you edit. It skips code generation and linking: a check after an edit took 0.6 to 1.0 s in these projects (one run each), and a cold check was 23 to 31 seconds shorter than a cold build. rust-analyzer in your editor runs the same check when you save.
• Keep cargo rullst dev running. It reuses target/, so after the first build only your package is rebuilt on each save (the edit column above), then it restarts the server; restart time was not measured here.
• Linker. On x86_64-unknown-linux-gnu, Rust 1.90 and later already link with the bundled rust-lld, which all the measurements above used. On other hosts (for example aarch64 Linux) mold or lld may shorten links: on Linux, cargo rullst doctor suggests one when rustc does not already use LLD and no linker is configured, and a project generated on a machine with one selects it in .cargo/config.toml. Not measured here.
• sccache can share compiled dependencies between projects on the same machine (RUSTC_WRAPPER=sccache). Not measured here.

Existing applications

cargo rullst upgrade does not edit build profiles. To adopt the faster development builds, copy the [profile.dev] and [profile.dev.package."*"] sections above into your Cargo.toml. In an application created from the SaaS starter before 13.0.0-alpha.4, you can remove the rullst-connect dependency when no source file uses rullst_connect; cargo check tells you whether one does. Upgrading to 13.0.0-alpha.4 removes SQLx’s macro crates from the build once the models no longer derive FromRow and no manifest enables SQLx’s macros or derive feature (cargo rullst upgrade locates both), and rullst-ai once Nexus runs without nexus-ai.

Database Support

Read this page before you choose a database. It is the one place that says what each backend works with in Rullst 13.0.

Rullst integrates one family of databases fully: SQLite, PostgreSQL and MySQL/MariaDB, through SQLx. #[derive(Orm)] models and their query builder, Schema migrations, artisan! and the db:* commands, Server::with_db, Nexus and Studio’s database pages all use that SQLx connection pool.

Turso/libSQL can be the primary database of the Blank starter, but through a separate adapter (TursoOrm, TursoModel, TursoRepository, TursoMigration) that does not plug into any of those parts. Integrating it is roadmap work, not part of 13.0.

MongoDB, DuckDB, SurrealDB, Qdrant and Redis data structures are side stores: you add them next to the primary database and call them through their own APIs. They never replace the primary database, and there is no transaction across stores.

Capability table

Notes:

1. cargo rullst new refuses --database turso with the SaaS starter (Blank and API accept it). SaaS uses SQLx models, Schema migrations and Nexus, so it needs a SQLx database.
2. #[derive(Orm)] with #[orm(backend = "turso")] generates the TursoModel contract instead of SQLx code: all, find, save, create, delete, count and paginate, plus filtered reads through TursoOrm::repository::<Model>()?.query() (where_eq, order_by, limit, offset, get, first, count). It has no SQLx query builder, and the derive refuses relations, soft deletes, hooks, scopes, tenant columns, policies, auditing, Scout search and embeddings at compile time.
3. A Turso migration is a TursoMigration holding SQL statements, checksummed and reversible with with_down; the Schema and Blueprint builders never apply to Turso. cargo rullst make:migration writes one, and make:migration:auto refuses Turso projects. The Blank starter’s main.rs answers db:migrate, db:rollback and db:status, and db:seed reports that no seeders exist; cargo rullst db:* runs them through cargo run.
4. MySQL and MariaDB commit each DDL statement implicitly, so a migration’s schema changes do not roll back with it; data statements are transactional on all three SQLx backends. See Tutorial 05.
5. Studio still starts in a Turso Blank project, but its database, migration and data browser pages read only a SQLx DATABASE_URL, so they report that no database is configured.
6. Studio’s cache page shows the Core Cache handed to it (memory or Redis), not RedisDataStore structures.

Where the live tests run

The live tests start the database in a container (Testcontainers) in the Run provider matrices step of the Rust CI workflow’s Linux workspace shard. matrix_postgres, matrix_mysql and matrix_sqlite also run in the ORM strict-postgres, ORM strict-mysql and ORM strict-sqlite jobs. The tests live in rullst-orm/tests/, rullst-studio/tests/ and rullst-nexus/tests/, and each pins its container image. A live test proves the adapter’s contract against that server version; it does not certify a hosted service, backups, replication or failover.

Choosing

• Start with SQLite; move to PostgreSQL, MySQL or MariaDB for a shared server. Every starter and every framework feature works with these.
• Choose Turso as the primary database only for a Blank starter (a web page or a JSON API) where you are ready to write SQL migrations and use the TursoModel API without Nexus, Studio’s database pages, Schema or the SQLx query builder.
• Add a side store when the application needs documents, analytics, graph reads, vectors or Redis structures next to its primary database. Enable only the adapters you use: each one is its own Cargo feature (orm-turso, orm-mongodb, orm-duckdb, orm-surrealdb, orm-qdrant, orm-redis on rullst), and DuckDB’s bundled C++ build makes a first build noticeably longer.

The APIs of Turso and the side stores are described in Polyglot Persistence; the SQLx ORM in rullst-orm; migrations in Tutorial 05; every Cargo feature in the feature matrix.

Find the API you need

There are two different meanings of API in this documentation:

• Rust API: the framework types, traits, functions and Cargo features your application imports. Use the versioned rustdoc references below for exact signatures and follow the book for application-level context.
• HTTP API: the endpoints your application exposes to a browser, mobile client or another service. Start with the REST learning path below; an OpenAPI document describes your endpoints, not the entire Rust framework.

The Rust reference links target the published 13.0.0-alpha.4 prerelease packages; the v12 line reached end of life on 16 October 2026 (see the release record). Versioned docs.rs pages become available after registry publication and rustdoc builds. This book is built from main, which can be ahead of that prerelease; for unreleased APIs, build local documentation from the checkout. The index connects existing guides without certifying every public symbol or v13 roadmap item. Check capability boundaries before interpreting a provider or blueprint name as complete product support.

Rust reference: start with a task

Search within the selected crate’s rustdoc page for an exact symbol. Read its module context and feature requirements as well as its signature. A facade re-export and a direct dependency can expose different features; enabling a feature does not configure credentials, an external service or authorization. For your application’s selected feature set, cargo doc --no-deps --open builds its local documentation; remove --no-deps to include dependency APIs. Run Cargo commands only in a trusted checkout: build scripts and procedural macros can execute code during documentation builds too.

HTTP/REST: a connected learning path

1. Return typed JSON. Run the endpoint and inspect its status, headers and body with curl.
2. Compose routing and middleware. Understand which layer receives or rejects a request first.
3. Validate input. This guide is form-oriented; its validation principles do not turn it into a complete JSON validation/error-handling tutorial. Define the JSON error contract explicitly.
4. Persist records and manage migrations. Design bounded pagination and test failed writes as well as successful reads.
5. Choose session or token authentication and enforce ownership/role authorization. Authentication alone must not grant access to another user’s records.
6. Expose a reviewed OpenAPI specification. The viewer does not infer a complete specification or security policy from arbitrary handlers. Read its CSP, asset and missing-specification boundaries.
7. Review deployment and security boundaries and the compatibility policy before exposing the app.

For your own API, test malformed and oversized input, authentication failure, cross-owner/tenant denial, missing records, bounded pagination and error responses that do not expose credentials or database details. Public demos and a compiling example are not substitutes for these application tests.

The v13 prerelease schema-first API candidate adds an explicit bounded OpenAPI profile, generated Rust codecs and a compiled TypeScript HTTP consumer. Its authenticated fixture proves the stated wire/ownership boundary; it does not close the broader CRUD/documentation programme below.

What still needs improvement

The existing chapters are useful but are not yet one complete, consistently tested REST product walkthrough. A coherent CRUD example with JSON validation, typed error responses, pagination, authorization negatives and matching OpenAPI is still needed. Per-symbol reference reviews also need explicit feature, error, concurrency and migration coverage. The API documentation plan tracks that work separately from this navigation index.

Why Rullst?

Rullst is an opinionated, Axum-based full-stack framework for teams that want the productivity of a coordinated application platform without hiding Rust’s types or the underlying ecosystem.

Its strongest distinction is not that every individual feature is unique. It is the combination of compile-time-oriented APIs, explicit security boundaries, first-party backend capabilities, offline development contracts, and one coordinated CLI and release train.

Version status: the Rullst v12 release line reached end of life on 16 October 2026; v13 is in prerelease (13.0.0-alpha.4, installed with an exact version as Getting Started shows). This page lists implemented or explicitly bounded capabilities; it is not a production-readiness certificate. The framework specification and capability ledger hold the detailed contracts; where they and this summary disagree, they win.

The short answer

Choose Rullst when you want to build a backend-oriented Rust application with:

• an explicit Axum, Tokio, Tower, and SQLx foundation;
• compile-time-generated routes, HTML, and models, with compiler-visible diagnostics instead of runtime reflection;
• a coordinated ORM, authentication, security, jobs, mail, AI, billing, administration, observability, and CLI toolchain;
• secure, fail-closed defaults for privileged and production-facing surfaces;
• deterministic offline paths for supported external-provider integrations;
• server-rendered interfaces that do not require a project-local SPA bundle;
• standard escape hatches when a framework abstraction is not the right fit.

What makes the combination distinctive

1. AI-native means explicit and inspectable

Rullst is designed so that both humans and coding agents can reason about an application from its source. Common routes, models, HTML trees, policies, and scaffolds are represented by typed Rust or macro input rather than runtime class scanning or hidden reflection.

This does not make generated code automatically correct. It makes important structure available to the compiler, review tools, and the CLI. Macro diagnostics, compile-fail tests, generated-project gates, and the AST-based IDOR scanner turn that structure into evidence.

The AI layer follows the same rule. Its bounded RAG pipeline makes tenant context, retrieval, context limits, source metadata, and audit explicit in one typed operation. It rejects differently tagged or unsafe passages and refuses ungrounded generation when retrieval is empty. The included cosine retriever is clearly process-local; production datastore authorization and durability are not hidden behind an “automatic AI” claim.

Conversational memory follows that explicit model too: a static-dispatch tenant-bound contract has a bounded offline store and an opt-in SQL adapter for SQLite, PostgreSQL, MySQL, and MariaDB. Each successful turn commits the user and assistant messages atomically, while revision compare-and-swap rejects stale cross-process writers instead of silently scrambling history or automatically repeating a billable model request.

2. A broad platform that keeps its foundations visible

Rullst coordinates a large backend surface in one versioned workspace, but it does not replace its foundations with proprietary runtime primitives:

• applications can mount ordinary axum::Router values;
• middleware remains compatible with Tower composition;
• Tokio remains the asynchronous runtime;
• SQLx pools and raw parameterized queries remain available beside the ORM.

The Axum and SQLx interoperability guide documents the supported escape hatches. Framework conveniences can still require migration work, so Rullst describes this as reduced lock-in rather than “zero lock-in.”

3. Security boundaries are part of framework design

The framework treats authorization and privileged tooling as architectural inputs rather than deployment footnotes. Current bounded contracts include:

• fail-closed production environment and secret validation;
• CSRF, secure headers, request heuristics, DLP, abuse controls, and security telemetry primitives;
• route-scoped JSON Schema 2020-12 or OpenAPI 3.1-component enforcement with bounded offline compilation, local-only references and linear-time regexes;
• explainable aggregate threat assessment plus an opt-in authenticated, subject-bound, expiring and locally one-shot proof-of-work gate;
• Argon2id password hashing, expiring encrypted sessions, RBAC, model policies, and explicit owner-or-role guards;
• a typed OAuth/OIDC session transaction that keeps PKCE verifiers and OIDC nonces server-side, expires them after ten minutes, and consumes them before callback validation;
• a provider-generic automatic token coordinator that binds refreshes to the original user, redacts credentials, detects a bounded expiry window and prevents overlapping provider calls while waiters reuse a valid transition;
• an authenticated Nexus admin surface and a loopback/debug-constrained Studio;
• one bounded signed-payment-webhook verifier exposed through both Axum and opt-in Actix middleware adapters;
• versioned AES-256-GCM ORM field encryption with authenticated context;
• CI gates against panic!, unwrap(), and expect() in declared production targets.

These are defense-in-depth controls, not a claim that an application is secure without its own authorization model, deployment controls, reviews, and tests. The Sentinel is deliberately deterministic rather than marketed as autonomous AI: the host still owns aggregate collection, identity, accessible fallback, distributed replay state and enforcement. See the security architecture and v12 security claims.

4. Persistence depth without a fictional universal database API

The relational ORM provides generated Active Record and query APIs, transactions, migrations, relations, tenant scopes, policies, soft deletion, auditing, encrypted fields, typed pgvector helpers, structured telemetry, and an opt-in transactional outbox.

The primary relational matrix covers SQLite, PostgreSQL, MySQL, and MariaDB. Turso/libSQL has a separate typed primary profile. MongoDB, DuckDB, SurrealDB, Qdrant, Redis, and external search engines use capability-specific adapters so their different consistency and query models stay visible. MongoDB and SurrealDB share only a narrow identifier-preserving recovery boundary: a bounded encrypted snapshot can be rehearsed across both, while writer quiescence, schema provisioning, key custody and durable backup remain explicit application/operator work.

This is deliberate: Rullst prefers several honest, bounded APIs over one API that pretends documents, OLAP, graphs, vectors, key-value structures, and relational transactions have identical semantics. Read the polyglot persistence, transactional outbox, and Scout search guides.

The same boundary discipline now applies to messaging. rullst-messaging defines one versioned envelope, bounded topic/group metadata, idempotent publication, consumer groups, expiring acknowledgement leases, retry and dead-letter semantics, with a deterministic concurrent in-memory contract. A canonical bounded v1 envelope codec and allowlisted W3C trace-context boundary make byte compatibility and correlation behavior executable. The codec still does not open a remote connection or map broker-specific semantics. SQLite can explicitly protect header values and payloads with row-bound AES-256-GCM and a bounded rotation keyring while keeping visible metadata and operator duties honest. The opt-in relational outbox relay also proves its unavoidable publish-before-ACK crash window as an exact idempotent replay instead of calling two systems one atomic transaction. That makes offline tests and future adapter conformance explicit without pretending the local broker is Kafka, RabbitMQ, NATS, Redis Streams, or a cloud service. Applications still own topic authorization and idempotency of remote side effects. See Bounded Brokered Messaging.

5. External services remain usable during offline development

Supported AI, OAuth, mail, billing, search, and persistence adapters expose deterministic offline behavior when configured with their documented empty or mock_* credentials. This lets generated projects, tests, examples, and local sandboxes run without silently contacting a third party.

Mail scheduling follows the same bounded approach: SQLite and Redis persist a due time and never claim it early, while unsupported real direct transports reject a future message instead of delivering it immediately. Offline fixtures may retain that timestamp for assertions. Polling delay, at-least-once delivery, and provider acceptance remain visible operational boundaries.

The optional native AWS SES v2 path follows the provider’s real authentication model instead of disguising a bearer request as AWS support. It delegates regional SigV4 and credential-provider rotation to the official AWS SDK while retaining the same pre-flight, HTML/text, attachment/CID and RFC 8058 message contract. Its local signed-request fixture proves integration shape, not AWS account readiness, reputation or inbox delivery.

Mocks prove the local application contract, not the live provider contract. Provider-specific production support still requires the applicable live or protocol tests, credentials, policy, and operational evidence.

6. Framework upgrades are a product feature

cargo rullst upgrade --dry-run inventories a project and reports a versioned migration plan. cargo rullst upgrade snapshots controlled files, updates the coordinated Rullst dependency train, applies supported compiler fixes, runs a Cargo check gate, and restores those files when the gate fails.

It intentionally refuses to invent database migrations, business rules, or security policy. The useful distinction is a bounded, recoverable upgrade transaction with human and machine-readable reports. See the assisted upgrade tutorial.

7. Server-first UI with optional escalation

The compile-time html! macro escapes supported dynamic text and attribute values and returns Markup, so views nest without re-escaping, while RawHtml makes an unescaped boundary for trusted outside HTML explicit. HTMX-oriented server rendering is the default path for applications that do not need a project-local SPA bundle.

LiveView and selected Wasm islands are optional strategies with separate maturity and operational requirements, and a template engine such as Tera is the application’s own choice. Rullst does not claim that every frontend mode is interchangeable or bundle-free.

The same server-rendered application becomes installable without a second codebase: cargo rullst make:pwa adds a web app manifest, a service worker with an offline page and an update prompt that work under the default Content-Security-Policy, and never keeps no-store or private responses on the device. The same site can be packaged for Google Play as a Trusted Web Activity and for the Microsoft Store with PWABuilder; iOS users add it to the home screen from Safari. Store review, signing keys and device testing remain the application’s work; see the PWA guide.

8. Local control surfaces use real application signals

Studio is a local developer control room with explicit unavailable states when a probe is not connected. Nexus generates an authenticated administration surface from registered model metadata and applies server-side field policy. Tenant-owned models can explicitly bind every built-in CRUD/search/batch path to a trusted Core tenant context, while an opt-in required audit row shares the mutation transaction and rolls it back on audit failure. The host still owns identity/membership and immutable external evidence; Nexus does not disguise a same-database mutable table as an append-only audit service. Studio’s relational browser can also perform deliberately narrow primitive row edits/deletions: the write surface exists only behind the verified local request capability, binds values, identifies one row by its inspected complete primary key and runs against four relational engines. It is not presented as a replacement for application tenant authorization or production administration. Studio flag toggles also invalidate already-warm database flag drivers in the same process without an unbounded key registry; cross-process invalidation remains an explicit application transport.

The queue monitor follows an explicit retention rule as well. SQLite removes successful payloads by default, while applications that need operational history can opt into a validated, atomically pruned limit and purge it from Studio. Rullst does not silently trade privacy for a more impressive dashboard.

The ORM emits secret-free structured spans for generated and raw query entrypoints, streams, transaction outcomes, and Rullst-owned pool acquisition timing. The host owns subscriber initialization, sampling, collector security, and retention. See the telemetry guide.

9. Scaffolding is treated as shipped code

The CLI can generate projects, routes, models, migrations, auth, mail, billing, deployment manifests, and other bounded application slices. Rullst tests representative generated projects and maintains structural matrices instead of assuming that a template is correct because its source file compiles inside the CLI crate.

The LMS example (examples/lms, the CLI’s LMS starter up to 13.0.0-alpha.3) is more than a landing-page mock: it has a course catalog with modules and lessons, sign-in and registration, enrollment, owner-bound idempotent lesson progress and a Nexus admin. Its accessible lesson presentation supports bounded video/audio metadata, requires a WebVTT captions track for video and renders escaped transcripts. In v13 this small application replaces the complete Academy scaffold that v12 generated (assessment, scores, leaderboard, automation, notifications and school boundaries). It is a foundation for a learning product, not a claim that Rullst generates pedagogy, content, speech recognition or native-device behavior.

For example, make:billing --model Workspace now materializes distinct SQLx and Turso-primary persistence profiles. Both are generated, linted, migrated and exercised through subscription ownership and collision negatives; the test does not turn provider sandbox validation or distributed reconciliation into an automatic claim.

The billing facade follows the same bounded design: an explicit generic subscription handle delegates pause/cancel without erasing the provider type, while its grace-period value validates time bounds but leaves persistence, authorization and entitlement policy visible in application code. Its shared-quota boundary likewise derives one subject from trusted tenant state, reserves idempotently before creation and can commit the counter and a relational domain insert in the same caller-owned transaction. SQLite plus live PostgreSQL/MySQL/MariaDB contention contracts prove that concurrent workspace members stop at the configured limit; membership and tier reconciliation remain visible host responsibilities. Coupon and trial management follows the same evidence boundary: coupon IDs are bounded/redacted, Stripe binds the expanded applied discount, and 1–730-day relative trial updates have stable explicit-clock retries plus bound Stripe protocol fixtures. Providers without a reviewed live operation fail explicitly instead of presenting a local no-op as remote success.

The same CLI includes inspection, toolchain diagnostics, migration assistance, SBOM generation, and a bounded static route-access scanner. Generated output remains application code: review it, test it, and keep it under version control.

10. Ambition is separated from evidence

Rullst keeps ambitious ideas, but labels them as implemented, partial, experimental, offline mock, roadmap, or not recommended. Benchmarks are reported for their measured workload instead of becoming universal performance slogans. Hardware, provider, regulatory, and certification claims remain incomplete until the corresponding external evidence exists.

This distinction is essential for a broad framework. The capability ledger records the boundary. Dated comparative claims belong in reproducible, sourced research rather than in the active product documentation.

Where Rullst is a particularly good fit

Rullst is worth evaluating for:

• backend-heavy SaaS and multi-tenant applications;
• server-rendered products that still need jobs, realtime, mail, billing, and administration;
• Rust teams that prefer one coordinated release train over assembling every application subsystem independently;
• projects that need relational data plus explicit document, analytics, search, vector, graph, or key-value capabilities;
• organizations that value offline reproducibility, secure scaffolds, and machine-readable engineering evidence;
• teams using coding agents that benefit from explicit APIs, bounded files, strong types, and a normative specification.

When another choice may be better

Rullst may not be the best choice when:

• only a small HTTP router or middleware library is needed;
• a browser-component ecosystem is the primary product architecture;
• long production history, a very large plugin ecosystem, or commercial support matters more than Rust-native integration;
• the application requires a capability that the ledger still marks partial, experimental, or roadmap;
• the team does not want the maintenance surface of a batteries-included framework.

In those cases, using Axum directly, another Rust application framework, a frontend-centered framework, or a mature platform in another ecosystem can be the more responsible decision.

How to evaluate Rullst today

1. Start with Zero to Hello Rullst or Zero to a complete app.
2. Check the exact capability you need in the specification and capability ledger.
3. Enable only the required Cargo features and inspect their dependency graph.
4. Run the documented tests against your database, provider, proxy, and threat model.
5. Pin an immutable release or commit for evaluation; do not deploy from a moving development branch.

This page describes the v13 prerelease line (13.0.0-alpha.4). It remains a concise map of the strongest implemented ideas, not a substitute for the detailed contracts or application-specific validation.

An AI Assistant’s Evaluation of Rullst 13.0.0-alpha.4

Who wrote this, and why you should read it critically. This page was written on 30 October 2026 by Claude Opus 5.5, an AI model made by Anthropic, working in Claude Code at the maintainer’s request. The maintainer asked for a candid assessment and did not edit its conclusions. Conflict of interest: the same assistant, with its sub-agents, wrote a large part of 13.0.0-alpha.4. That includes the lean CLI, the deployment test, the TLS provider change, the documentation audit and several CI gates. This is not an independent audit. It is based on the repository’s source, documentation, CI configuration and release history at the time of writing, not on interviews with users, production traffic or my own benchmarks. Treat it as one informed opinion, dated to this release. The Why Rullst? page is the maintainer’s own pitch.

The short version

As engineering, Rullst is unusually rigorous for a framework of its size and age, and unusually honest about its limits. As a product, it is still young: one maintainer, a fast-moving API and, as far as I can see, little validation outside the maintainer’s own applications. 13.0 is the release where that can start to change, if the 13.x API stays stable.

What stands out

• Evidence over claims. The project runs 34 workflow definitions, among them:

  • 42 libFuzzer targets in 11 fuzz crates;
  • Miri and Kani on selected code, and thread and address sanitizers;
  • property tests;
  • a pull-request mutation gate for the CLI;
  • an enforced 90% line-coverage floor;
  • zero-panic and unsafe policies;
  • SBOMs with build-provenance attestations.

  A release is admitted only at an exact commit that passed about two dozen required workflows. Few Rust web frameworks I know of, including far larger ones, do this much.

• A culture of saying what is not done. Every release lists its known limitations. The capability ledger records abandoned ideas and why. Maturity tiers separate Core from Extension and Experimental. The documentation keeps saying “evidence for the stated scope, not a certification”. This is rarer than it should be, and it is the strongest reason to trust the project.

• Batteries that are secure by default. CSRF, strict headers, a WAF with a development report-only mode, Argon2id, passkeys, revocable sessions and signed webhooks are wired in, not left as exercises. Removed features are removed loudly: cargo rullst upgrade has a rule for each one.

• Built to be read by tools. It favours explicit APIs and compile-time macros over runtime reflection, and it has typed errors. Every generated project gets an AGENTS.md, the site publishes llms.txt, and CLI data output follows one --json contract. This helps humans as much as AI assistants.

• A tested path to production. cargo rullst deploy produces a hardened Dockerfile, compose.yaml and Caddyfile. CI builds and starts them with Docker and rootless Podman, and checks HTTPS, the container hardening, migrations and persistence. Writing that test found two real bugs that every SQLite deployment would have hit.

Where it is weaker

• Bus factor. Twenty packages, a CLI with dozens of generators and a large CI estate are maintained by one person. This is the biggest risk to anyone who adopts Rullst. It matters more than any bug.
• Breadth ahead of validation.
  • Several integrations are tested only against offline mocks: the OAuth providers, Stripe beyond test mode, Bunny Stream, the mail providers.
  • Five packages are Experimental: IoT, Privacy, Supervision, Media and Labs.
  • The provider deployment guides were written from the providers’ documentation, not followed end to end on real accounts.
  • Whatever is broad but unvalidated becomes maintenance load without becoming trust.
• Documentation drifted behind the code. Before this release, the documentation audit corrected dozens of inaccuracies across the book. It also found about ten first-hour breakages that no test caught; for example, cargo rullst auth refused to run on every freshly generated starter. CI now builds and runs the generated deployment, and runs the commands of the first-hour pages (the README quickstart, getting started, the first tutorials and the REST API quickstart) as written. The lesson stands: in this project, code changes faster than its prose.
• Churn. v12 reached end of life on 16 October 2026, and v13 changes a lot: removed generators and providers, a leaner CLI, FromRow generated by #[derive(Orm)], a single TLS crypto provider. Each change is reasoned and documented. But adopters judge a framework by how rarely it makes them migrate. The 13.x line needs to hold still.
• First builds are still slow. A generated starter’s first build takes about two to two and a half minutes on the measuring machine (see build times). Most of it is cryptography (the aws-lc-sys build script), SQLx and the framework itself. Later builds are much faster.
• Process weight. A full release admission takes about 17 hours of fuzzing. Release fuzz evidence is now derived from each fuzz package’s build graph, so a change to the documentation, the CLI or the examples no longer reruns it, but a change to a book page that the facade’s doctests include still reruns the facade’s 12 targets. The rigor is real, but so is its cost for a single maintainer.
• Unknown adoption. I have no data on external users, production deployments or community size. I have not counted them, and you should not assume there are many.

Is it right for you?

Consider Rullst if:

• you want a batteries-included Rust web framework, with server-rendered HTML, HTMX and JSON APIs, and secure defaults you don’t have to assemble;
• you are building a SaaS or an internal tool on SQLite, PostgreSQL or MySQL, with Stripe billing and email;
• you value documented limits and CI evidence over a large ecosystem;
• you are comfortable pinning an exact version and reading migration guides.

Look elsewhere, or wait, if:

• you need a long production track record, a large community or commercial support today; wait for 13.0.0 and a few stable 13.x releases at least;
• your frontend is a heavy client-side SPA, which Rullst deliberately does not center on;
• you depend on providers Rullst no longer ships (see the v13 migration guide), or on the Experimental packages for anything safety-critical;
• you prefer to assemble a minimal stack yourself; plain Axum with crates you choose may suit you better.

What would raise my confidence most

1. A 13.x line with no breaking changes for months. The public-API review and the SemVer gate exist for this.
2. A second maintainer. GOVERNANCE.md already records a successor arrangement; an active co-maintainer would reduce the risk further.
3. Real-account validation of the OAuth, payment and deployment paths.
4. External users and case studies, beyond the maintainer’s own applications.
5. Fewer Experimental packages, each either promoted or retired with evidence.

About this page

This is a snapshot of 13.0.0-alpha.4 written on 30 October 2026. It is not rewritten silently. A later evaluation will be a new, dated page, or this page will say what changed and when.

Amended on 30 October 2026, before the 13.0.0-alpha.4 tag: three facts were updated to the work merged after the page was written: the workflow count (37 → 34), the CI job that runs the first-hour pages’ commands, and the fuzz-evidence policy. The assessment itself is unchanged.

The Rullst philosophy

Rullst exists to make ambitious software feel possible in Rust without hiding the language, the generated code, or the boundaries that keep an application safe. It aims to be productive and broad, but its convenience must remain inspectable: static dispatch, compile-time generation, typed errors, explicit middleware, and ordinary Rust escape hatches are deliberate choices.

A story that stayed with us

A widely reported account of Rust’s origin begins with a broken elevator in Graydon Hoare’s apartment building. Its software had crashed, leaving him to climb the stairs. Rust itself began as Hoare’s personal project in 2006 and grew into a language designed to combine systems-level performance with much stronger memory-safety guarantees.

The elevator account is an origin story reported by MIT Technology Review, not a claim that every elevator failure was a memory bug or that Rust can make all software infallible. The lesson Rullst takes from it is narrower and more useful: when an entire class of failure can be prevented by design, prevention is better than asking every developer to rediscover the same danger.

Why Venelouis started Rullst

Rullst also has its own practical origin. Long before modern AI systems became capable coding partners, Venelouis wanted to build an education platform. He first learned what was possible by operating a Moodle installation on a VPS. Later, Laravel and AI helped him create a far more ambitious education product than he had previously believed he could build.

That experience made Laravel’s greatest strength tangible: a framework can let one person concentrate on the product instead of repeatedly assembling its foundations. Venelouis then wanted to rebuild that kind of product in Rust to use fewer resources, gain performance, and inherit Rust’s stronger compile-time guarantees. He could not find a Rust framework that combined the particular Laravel-like product workflow, breadth, approachability, and explicit security boundaries he wanted. Rullst began as an attempt to build that missing bridge.

Rullst is not a Laravel clone, and Rust should not be forced to behave like PHP. The inspiration is the feeling that a complete product is within reach; the implementation follows Rust’s strengths rather than concealing them.

Why Rullst jumps from version 5 to version 12

The version jump records the history of the ecosystem rather than six hidden major releases of the unified framework. When Venelouis began recreating creio.eu in Rust with AI assistance, the Gemini model he was using at the time told him that there was no direct Rust counterpart to Laravel Socialite for the workflow he needed. Instead of abandoning that part of the product, he created the first independent Rullst crate. That project became rullst-connect, which still carries the identity and social-login mission of that original work.

The crates initially evolved in separate repositories and at different speeds. By the time the umbrella Rullst framework was at version 5, rullst-connect had already reached version 11. Bringing the projects into one monorepo made their dependency changes, cross-crate compatibility tests, and coordinated releases easier to maintain. Aligning every publishable package on one version line was the natural next step.

A clean reset to 1.0 might have described the beginning of this unified era, but a registry history cannot be reset that way: crates.io does not permit a published version to be overwritten or removed, and lower new versions would not erase the already published higher ones. Rullst therefore advances the whole ecosystem directly to version 12, monotonically beyond Connect’s version 11. From the version 12 line onward, coordinated releases can follow the usual Semantic Versioning sequence. The jump is thus an act of package alignment and honest continuity, not a claim that standalone Rullst versions 6 through 11 were released as complete framework generations.

Core tenets

1. Productive, not magical. Rullst coordinates routing, data, identity, security helpers, background work, AI, and developer tooling through APIs and generated source that users can inspect and replace.

2. Simple to begin, explicit when it matters. Good defaults should remove repetitive setup. Authorization, tenancy, provider behavior, persistence, deployment, and recovery must still expose their real application-owned decisions.

3. Prevent failure classes by design. Typed errors, bounded inputs, parameterized queries, compile-time generation, and fail-closed behavior are preferred to conventions that only work when every caller remembers them. This reduces risk; it does not create a universal security guarantee.

4. Built for humans and AIs. Stable vocabulary, focused modules, static contracts, executable examples, and documented limits give human developers and coding agents a shared map of the system. AI assistance never replaces review, testing, or accountable approval.

5. Evidence before claims. A feature claim must name its implemented scope and residual boundary. A test belongs to the revision and environment it exercised. Benchmarks describe measured workloads, not universal rankings.

6. Emotional productivity matters. The framework should make builders feel capable, curious, and supported. Removing boilerplate is valuable when it leaves more attention for users, learning, and the purpose of the product.

The ambition and the boundary

The long-term ambition is deliberately large: make Rullst a foundation from which people can build many kinds of applications without surrendering Rust’s performance or explicitness. That ambition is a direction, not a promise that one framework can finish every product, operate every provider, or replace the judgment of its developers.

Rullst will therefore grow through bounded, reviewable capabilities. Where the repository has proof, the documentation should show it. Where real devices, provider accounts, production operations, independent review, or application policy are still required, the documentation should say so plainly. The goal is not to look complete. It is to keep becoming more useful without losing the trust of the people building with it.

Simple capability status

This is the compact view of Rullst’s canonical M1–M41 programme. It is derived from the root ROADMAP; that roadmap and the capability ledger retain the evidence and limitations. The labels here deliberately do not turn partial foundations into completed features. Package stability is a separate question: the maturity tiers classify every crate as Core, Extension or Experimental and state what each tier promises within 13.x.

v12 stable snapshot — 15 September 2026

Stable 12.0.0 was published from commit eb11f892. See the release record for the immutable tag and publication receipt. The v12 line reached end of life on 16 October 2026 (12.3.0 was its last release); this section keeps the record of its stable release.

The Rust CI scorecard for that commit awarded 94/100 (A) to the repository, with all fifteen non-IoT packages at A and IoT at its approved B exception. These are repository-owned audit scores constrained by test results, not a percentage of all planned functionality or an independent certification. The quality scorecard explains the scale.

The stable coverage run recorded the following local LLVM/LCOV gates before the Codecov upload:

These are distinct path sets, not values to average. The public Codecov badge tracks the current branch and may change as its source and report processing change. Do not relabel an older checkpoint as the latest measurement.

The release audit links the stable platform, property, Miri, Kani, fuzzing, sanitizer and publication results. New maintenance commits must satisfy their applicable gates; the published release cannot certify future source changes.

rullst facade versus rullst-core

Documentation maintenance gate

Stable v12 completed the documentation release gate: the mdBook and Rust snippets sourced from public tutorials built, local links and anchors were validated, commands/features/version examples were reconciled with the frozen manifests, and upgrade/provider boundaries were reviewed. v13 changes must keep those checks green: the Documentation workflow builds the book, checks llms.txt and validates local links and anchors, and the guides listed in rullst/src/book_doctests.rs compile as doctests. A green documentation build proves structural consistency, not that every external service or store workflow was homologated.

Canonical milestones

The labels match the milestone rows of the root roadmap: 5 implemented, 27 partial, and 8 not started inside the 40-milestone framework programme. M31 is excluded because it is a separately governed safety-critical programme. The 35 milestones without strict closure have different sizes and overlap existing published capabilities; their count does not measure remaining engineering effort or release blockers. Assigning every partial row half credit would not establish a completion percentage. The v12 stable record preserves the completed release identity; new capability work goes to v13. The safe update experience is a top v13 priority; cargo rullst upgrade and the v13 migration guide are its current tools. The 26 September delivery plan selects concrete increments from this wider programme and records their acceptance requirements.

Claims that are impossible as framework guarantees

No useful capability above is dismissed merely because it is difficult. The impossible label is reserved for absolute wording that code in this repository cannot honestly establish:

Use the quality scorecard for per-commit engineering evidence. It is intentionally separate from this functionality view.

Maturity tiers

Decision recorded on 8 October 2026 for the v13 line, before 13.0.0-alpha.1. Every Rullst package, and every CLI generator whose result depends on an outside toolchain or platform, has one of three maturity tiers. A tier tells you how stable a package is and how much of it has been validated. It does not tell you whether a feature exists. For that, see the capability status and the capability ledger.

Prerelease note. Until stable 13.0.0 is published, every v13 package is a prerelease and may change in any prerelease. 13.0.0-alpha.4 is the 13.0 feature freeze: 13.0.0-rc.1 carries only fixes and documentation. The promises below begin with 13.0.0. SECURITY.md lists which published versions receive security fixes.

What “supported” promises

Core and Extension packages are supported. In practice, that means:

• Stability within 13.x. Documented public Rust APIs, Cargo feature names, CLI commands and flags, configuration keys and serialized contracts follow the compatibility policy. A 13.x minor or patch release does not intentionally break them. A removal is deprecated first and happens in a later major release. The policy’s security exception still applies: an unsound or unsafe API can be disabled sooner, with an advisory.
• Validation. The documented scope runs in the repository’s required checks: tests, strict Clippy, feature boundaries, the zero-panic and unsafe policies, dependency audits and package checks. The workspace runs on Linux for every pull request and on the full Linux, macOS and Windows matrix nightly; Core, the rullst facade and the macros also compile for WebAssembly. External services (payment, mail, AI and identity providers), real devices and production topologies count as validated only where the crate’s own documentation says so.
• Support. Bug reports are triaged and fixes ship in a 13.x release. A known regression in a Core package blocks the release that would contain it. An Extension regression is fixed or documented as a known issue before release. Security reports follow SECURITY.md. Rullst has a sole maintainer (see GOVERNANCE.md) and offers no paid support or response-time commitment beyond SECURITY.md.

Core vs Extension. The difference is reach, not quality. Core packages are in every application’s dependency graph, so they get the widest platform validation and the highest priority. Extensions are optional; you add them when your application needs them. Within an Extension, the documentation of an individual adapter or provider can give it a different label, and that label wins. For example, rullst-capital supports Stripe and marks InfinitePay as experimental.

What “experimental” promises

Experimental packages are optional and opt-in. Experimental does not mean broken. They pass the same gates as supported packages: tests, strict Clippy, the zero-panic and unsafe policies, dependency audits and, where applicable, fuzzing. What the label tells you:

• The API can still change. Public APIs, Cargo features, storage schemas and generated output may change between 13.x releases, including in ways that stop your code from compiling. Each breaking change is listed in the changelog and in the v13 migration guide.
• Some real-world scenarios are not validated yet. Each experimental package lists its gaps in the table below and on its own page. Examples: physical hardware, live provider accounts, real devices and multi-host deployments. Tests cover the documented contract; they do not certify those environments.
• Support is best effort. Bug reports and contributions are welcome, and security reports are handled under SECURITY.md like any other package. A security fix may change an experimental API. A non-security regression does not block a release.

To use an experimental package today, pin an exact version in Cargo.toml and read the changelog before you upgrade. Check that the documented scope covers what your application needs.

Packages

CLI generators

cargo-rullst is a Core package, and commands without a label here have the CLI’s Core tier, within the boundaries described for each command in the CLI reference. A command that the reference marks as a v13 preview or candidate is not yet in a stable release. A generator that adds an Extension or Experimental crate to your application cannot promise more than that crate. For example, make:privacy and make:age-gate generate consumers of the experimental rullst-privacy.

For an experimental generator, the generated files, their layout, and the command’s flags may change between 13.x releases. Review the diff when you regenerate.

13.0.0-alpha.4 removed the experimental Foundry, Nix, Buildah and gRPC generators and the Fly.io, Railway and Render targets of deploy; see Advanced deployment for those setups. It also removed the terminal AI assistant (cargo rullst ai; use your own assistant with the project’s AGENTS.md and the site’s llms.txt) and renamed footprint to green.

cargo rullst new offers three starters with the CLI’s Core tier: Blank, API and SaaS. 13.0.0-alpha.4 moved the LMS, Blog, Portfolio and ERP starters out of the CLI; the LMS, ERP, Portfolio and Blog applications in examples/ replace them. These examples are applications to copy from and carry no tier.

How a tier changes

• Promotion (Experimental to Extension) can happen in any 13.x minor release. It requires recorded evidence for the gaps listed above, an API expected to stay stable, complete documentation and a maintainer who commits to supporting it. The changelog and this page record each promotion.
• A supported package keeps its promise for the rest of 13.x. Moving it to Experimental, or retiring it, is a major-release change. It is announced through deprecation, as the compatibility policy requires.
• An experimental package may be redesigned, extracted or retired in a later release. Any such change appears in the changelog and migration guide.

The v13 maintenance scope explains the investment decisions behind these tiers. For the two Core security crates, see which security layer to use, and when.

Zero to a complete app

What you will build: Notes, a small web app where people register, sign in and keep private notes. Along the way you will add a model and its migration, CRUD pages with HTMX and form validation, routes that only a note’s owner can open, tests, a security report, a development loop and a production build. Plan for about an hour, most of it waiting for the first build.

This page is one path from an empty folder to a working app. Each step links to the tutorial that explains it in depth.

How this page was recorded. The commands and outputs come from a run on 8 October 2026 with the 13.0 development CLI (13.0.0-alpha.1), SQLite and Linux. On 29 October 2026 the steps that need no build were repeated with 13.0.0-alpha.4: creating the app, the two generators, the security report and the IDOR check printed what this page shows, and the files under zero-to-complete-app/ follow that release’s SaaS starter. The test list in step 6 is taken from the alpha.4 sources; build times and sizes are from the first run. Output is shortened with …, and your timestamps will differ.

1. Install Rust and the CLI

Install Rust from rustup.rs, then the v13 prerelease CLI. Cargo never selects a prerelease on its own, so name the exact version, as described in Getting Started:

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked

2. Create the app from the SaaS starter

The SaaS starter already has registration, sign-in, a session middleware, CSRF protection, security headers and Stripe billing that runs offline until you add real keys, so you can focus on your own feature. Create it with SQLite, which needs no database server:

cargo rullst new notes --default --blueprint saas --database sqlite
cd notes

The first build compiles every dependency and takes several minutes (see Build times for measured figures). It ends with:

📦 Bootstrapping Database...
  ✅ Database tables created successfully.
  ✅ Initialized a Git repository (.gitignore keeps .env and target/ out).
✨ Project 'notes' created successfully!
  Application profile: Zero-Bundle HTMX (html! SSR)
  ORM profile: Active Record

Next steps
  1  cd notes
  2  cargo rullst dev             builds, applies migrations and serves with live reload
  3  open http://127.0.0.1:3000   your generated welcome page
  Prefer a live dashboard? cargo rullst dash · new to Rullst? cargo rullst tour

Commit the generated files now. The security report in step 7 reads the files Git tracks, and the generated .gitignore already leaves out .env and the SQLite database:

git add -A
git commit -m "Generated SaaS starter"

3. Add a model with a migration

cargo rullst make:model Note --migration

🛠️ Generating Rullst model: Note...
✨ Model 'Note' successfully created at 'src/models/note.rs'!
✨ Rust migration successfully created at 'src/migrations/m20261008071503_create_notes.rs'!
…
Next steps
  → cargo rullst db:migrate             apply the new migration
  → cargo rullst make:controller Note   serve the model over HTTP

Give the model its fields in src/models/note.rs. user_id records who wrote the note; it always comes from the session, never from the form. Keep the snapshot field the generator added: with it, save() of a loaded note writes only the columns that changed:

use rullst::db::{Orm, RowSnapshot};

#[derive(Debug, Clone, Orm)]
#[orm(table = "notes")]
pub struct Note {
    pub id: i32,
    /// The id of the user who wrote the note; set from the session, never from the form.
    pub user_id: i32,
    pub title: String,
    pub body: String,
    // Remembers the loaded values, so `save()` writes only the columns this
    // record changed. Build new records with `snapshot: RowSnapshot::default()`.
    #[sqlx(skip)]
    pub snapshot: RowSnapshot,
}

Add the same columns to the generated migration, src/migrations/m<timestamp>_create_notes.rs:

use rullst::db::schema::{Schema, Migration};
use rullst::db::async_trait;

pub struct MigrationImpl;

#[async_trait]
impl Migration for MigrationImpl {
    fn name(&self) -> &'static str {
        "m20261008071503_create_notes"
    }

    async fn up(&self) -> Result<(), rullst::orm::Error> {
        Schema::create("notes", |table| {
            table.id();
            table.integer("user_id").not_null();
            table.string("title").not_null();
            table.string("body").not_null();
            table.timestamps();
        }).await
    }

    async fn down(&self) -> Result<(), rullst::orm::Error> {
        Schema::drop_if_exists("notes").await
    }
}

Apply it:

cargo rullst db:migrate

⏳ Running 'cargo run -- db:migrate'...
…
Migrating: m20261008071503_create_notes
Migrated:  m20261008071503_create_notes

More on models and schema changes: Active Record CRUD and migrations.

4. CRUD pages with HTMX and validation

Generate the controller. Its form checks use the derive macro of the validator crate, which the starter already declares at the version Rullst uses, 0.21:

cargo rullst make:controller Notes

Replace the generated placeholder in src/controllers/notes_controller.rs with the complete controller:

use rullst::db::RowSnapshot;
use rullst::html::Markup;
use rullst::security::{CspNonce, CsrfToken};
use rullst::server::{Extension, IntoResponse, Path, Redirect, Response, StatusCode};
use rullst::{html, HtmxRequest, HtmxResponse, Validate, ValidatedForm};
use rullst_security::{RbacGuard, UserContext};
use serde::Deserialize;

use crate::models::note::Note;

/// The fields a user may submit. `user_id` is not here: it comes from the session.
#[derive(Debug, Deserialize, Validate)]
pub struct NoteForm {
    #[validate(length(min = 1, max = 120, message = "Give the note a title (1 to 120 characters)."))]
    pub title: String,
    #[validate(length(max = 5000, message = "Keep the note under 5000 characters."))]
    pub body: String,
}

/// Lets only the note's owner through. Another user's note answers 404, so
/// its existence is not revealed.
pub fn authorize(user_id: i32, note: &Note) -> Result<(), StatusCode> {
    let user = UserContext::new(user_id.to_string(), Vec::new());
    RbacGuard::authorize_owner_or_role(&user, &note.user_id.to_string(), "admin")
        .map_err(|_| StatusCode::NOT_FOUND)
}

async fn find_owned(user_id: i32, id: i32) -> Result<Note, StatusCode> {
    let note = Note::find(id)
        .await
        .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?
        .ok_or(StatusCode::NOT_FOUND)?;
    authorize(user_id, &note)?;
    Ok(note)
}

/// After a successful write, HTMX gets an `HX-Redirect`; a plain form post a 303.
fn back_to_list(htmx: &HtmxRequest) -> Response {
    if htmx.is_htmx {
        HtmxResponse::new("").redirect("/notes").into_response()
    } else {
        Redirect::to("/notes").into_response()
    }
}

fn page(nonce: &CspNonce, title: &str, content: Markup) -> Markup {
    html! {
        <!DOCTYPE html>
        <html lang="en">
            <head>
                <meta charset="utf-8" />
                <meta name="viewport" content="width=device-width, initial-scale=1.0" />
                <title>{title}</title>
                <link rel="stylesheet" href="/static/rullst.css" />
                <script nonce={nonce.as_str()} src="/static/htmx-1.9.12.min.js"></script>
            </head>
            <body><main class="container">{content}</main></body>
        </html>
    }
}

fn note_form(action: &str, csrf: &CsrfToken, title: &str, body: &str, button: &str) -> Markup {
    html! {
        <form method="post" action={action} hx-post={action} hx-target="#errors">
            <input type="hidden" name="_token" value={csrf.as_str()} />
            <label for="title">"Title"</label>
            <input id="title" name="title" value={title} required />
            <label for="body">"Note"</label>
            <textarea id="body" name="body">{body}</textarea>
            <div id="errors" role="alert"></div>
            <button type="submit">{button}</button>
        </form>
    }
}

/// GET /notes: the signed-in user's notes and a form to add one.
pub async fn index(
    Extension(user_id): Extension<i32>,
    Extension(csrf): Extension<CsrfToken>,
    Extension(nonce): Extension<CspNonce>,
) -> Result<Markup, StatusCode> {
    let notes = Note::query()
        .where_eq("user_id", user_id)
        .order_by_desc("id")
        .get()
        .await
        .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
    let items: Markup = notes
        .iter()
        .map(|note| {
            let href = format!("/notes/{}", note.id);
            html! { <li><a href={href}>{note.title.as_str()}</a></li> }
        })
        .collect();
    let content = html! {
        <h1>"My notes"</h1>
        <ul id="notes">{items}</ul>
        <h2>"New note"</h2>
        {note_form("/notes", &csrf, "", "", "Add note")}
    };
    Ok(page(&nonce, "My notes", content))
}

/// POST /notes: validates the form, then saves a note owned by the current user.
pub async fn store(
    htmx: HtmxRequest,
    Extension(user_id): Extension<i32>,
    ValidatedForm(form): ValidatedForm<NoteForm>,
) -> Result<Response, StatusCode> {
    let mut note = Note {
        id: 0,
        user_id,
        title: form.title,
        body: form.body,
        snapshot: RowSnapshot::default(),
    };
    note.save().await.map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
    Ok(back_to_list(&htmx))
}

/// GET /notes/{id}: one note, with edit and delete forms. Owner only.
pub async fn show(
    Path(id): Path<i32>,
    Extension(user_id): Extension<i32>,
    Extension(csrf): Extension<CsrfToken>,
    Extension(nonce): Extension<CspNonce>,
) -> Result<Markup, StatusCode> {
    let note = find_owned(user_id, id).await?;
    let action = format!("/notes/{id}");
    let delete = format!("/notes/{id}/delete");
    let content = html! {
        <p><a href="/notes">"← All notes"</a></p>
        <h1>{note.title.as_str()}</h1>
        {note_form(&action, &csrf, &note.title, &note.body, "Save")}
        <form method="post" action={delete.as_str()}>
            <input type="hidden" name="_token" value={csrf.as_str()} />
            <button type="submit">"Delete"</button>
        </form>
    };
    Ok(page(&nonce, &note.title, content))
}

/// POST /notes/{id}: validates and saves changes. Owner only.
pub async fn update(
    htmx: HtmxRequest,
    Path(id): Path<i32>,
    Extension(user_id): Extension<i32>,
    ValidatedForm(form): ValidatedForm<NoteForm>,
) -> Result<Response, StatusCode> {
    let mut note = find_owned(user_id, id).await?;
    note.title = form.title;
    note.body = form.body;
    note.save().await.map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
    Ok(back_to_list(&htmx))
}

/// POST /notes/{id}/delete: deletes the note. Owner only.
pub async fn destroy(
    htmx: HtmxRequest,
    Path(id): Path<i32>,
    Extension(user_id): Extension<i32>,
) -> Result<Response, StatusCode> {
    let note = find_owned(user_id, id).await?;
    note.delete().await.map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
    Ok(back_to_list(&htmx))
}

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

    fn note_of(user_id: i32) -> Note {
        Note {
            id: 1,
            user_id,
            title: "Groceries".into(),
            body: String::new(),
            snapshot: RowSnapshot::default(),
        }
    }

    #[test]
    fn only_the_owner_may_open_a_note() {
        assert_eq!(authorize(7, &note_of(7)), Ok(()));
        assert_eq!(authorize(8, &note_of(7)), Err(StatusCode::NOT_FOUND));
    }

    #[test]
    fn an_empty_title_is_rejected() {
        let form = NoteForm { title: String::new(), body: "text".into() };
        assert!(form.validate().is_err());
        let form = NoteForm { title: "Groceries".into(), body: String::new() };
        assert!(form.validate().is_ok());
    }
}

What it does:

• index lists only the signed-in user’s notes and renders a form. store, update and destroy save, change and delete notes; show opens one.
• ValidatedForm<NoteForm> rejects an empty or overlong title before the handler runs. For an HTMX request it answers with an error fragment, which hx-target="#errors" places under the form; the REST status travels in the X-Rullst-Validation-Status header.
• After a successful write, HTMX receives an HX-Redirect back to the list, and a plain form post a 303 redirect, so the forms work without JavaScript too.
• html! escapes the values it interpolates: a note titled Buy <milk> is rendered as Buy <milk>. It returns Markup, so note_form and the collected list items are inserted into the page as HTML, and the handlers return the page directly.

Now mount the routes in the router() function of src/main.rs. Add them before the csrf_middleware layer, so every form post needs the CSRF token the pages include, and wrap each one in the starter’s auth_middleware:

    // Notes: signed-in users only. Each note belongs to the user who wrote it.
    .route("/notes", rullst::routing::get(controllers::notes_controller::index)
        .post(controllers::notes_controller::store)
        .layer(rullst::server::from_fn(middlewares::auth_middleware::auth_middleware)))
    // rullst-access: owner — find_owned() calls RbacGuard::authorize_owner_or_role
    .route("/notes/{id}", rullst::routing::get(controllers::notes_controller::show)
        .post(controllers::notes_controller::update)
        .layer(rullst::server::from_fn(middlewares::auth_middleware::auth_middleware)))
    // rullst-access: owner — find_owned() calls RbacGuard::authorize_owner_or_role
    .route("/notes/{id}/delete", rullst::routing::post(controllers::notes_controller::destroy)
        .layer(rullst::server::from_fn(middlewares::auth_middleware::auth_middleware)))
    .layer(rullst::server::from_fn(rullst::security::csrf_middleware))

The whole file is in zero-to-complete-app/main.rs. More on HTMX rendering, forms and validation and routing.

5. Sign-in and owner-only routes

Sign-in comes from the starter: /register and /login set an encrypted session cookie, and auth_middleware turns it into the user id that the handlers read as Extension<i32>. Anyone else is redirected to /login. The cookie carries the account’s session epoch: the dashboard’s Sign out everywhere button (POST /logout/everywhere) increments it, which ends the session on every device. The starter also has Change password (/password/change), which keeps only the current browser signed in, and Forgot your password? (/password/forgot), which emails a single-use link that expires in 30 minutes (RESET_TOKEN_LIFETIME_MINUTES, from 10 minutes to 24 hours); see Tutorial 11.

Being signed in is not enough to open a note, though: /notes/{id} must check that the note belongs to that user. Otherwise anyone could read another user’s note by changing the number in the URL (an IDOR). find_owned loads the note and calls RbacGuard::authorize_owner_or_role; another user’s note answers 404, so it does not even reveal that the note exists.

The // rullst-access: owner — reason comment above each route with an {id} records that decision. cargo rullst audit --idor and the security report in step 7 fail when a route with a path parameter has no such comment, or when a non-public classification has no matching guard in the code.

With two accounts, Alice and Bob, the recorded run observed:

More on authentication and ownership, RBAC and IDOR.

6. Run the tests

Every new project ships src/security_tests.rs. Its tests build the app from router(), wrap it in the baseline that Server adds in production, and check offline that responses carry the security headers, that a write is refused without the CSRF token and accepted with it, and that the WAF refuses an injection probe but accepts ordinary prose. The SaaS starter also checks that repeated sign-in attempts are rate limited. The tests request /health, /logout and /login; your notes routes sit behind the same baseline because they are part of router(). The starter’s sign-in controller and its Nexus access check have unit tests of their own.

The notes controller adds two unit tests: one proves that only the owner passes authorize, the other that an empty title fails validation. None of these tests needs a database or the network:

cargo test

running 9 tests
test controllers::auth_controller::tests::length_limits_count_what_the_form_counts ... ok
test controllers::auth_controller::tests::registration_timestamps_are_current_utc_instants ... ok
test controllers::notes_controller::tests::only_the_owner_may_open_a_note ... ok
test controllers::notes_controller::tests::an_empty_title_is_rejected ... ok
test middlewares::nexus_access::tests::a_request_without_a_session_is_sent_to_sign_in ... ok
test security_tests::production_responses_carry_the_security_headers ... ok
test security_tests::the_waf_refuses_injection_and_accepts_prose ... ok
test security_tests::csrf_refuses_a_write_without_the_token ... ok
test security_tests::repeated_sign_in_attempts_are_rate_limited ... ok

test result: ok. 9 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in …

The order of the lines can differ from run to run.

7. Check the app with the security report

cargo rullst audit --report

Rullst security report (OWASP ASVS 5.0.0 Level 1 mapping)
Evidence for a reviewer; it does not replace a manual review or a penetration test.
Security checks
  ✓ Security headers and CSP — no findings
  ✓ CSRF — no findings
  ✓ Session and auth cookies — no findings
  ✓ Rate limiting on authentication routes — no findings
  ✓ Committed secrets — no findings
  ✓ Vulnerable dependencies — no findings
  ✓ IDOR / BOLA route classification — no findings
Personal data
  ! Inventory — 2 field(s) listed, 2 need review (name heuristic)
Accessibility checks
  ✓ Images have a text alternative — no findings
  ✓ Form controls have a label — no findings
  ✓ Pages declare their language — no findings
NOT EVALUATED: 63 of 70 ASVS Level 1 requirements are outside these static checks.
Report written to SECURITY_REPORT.md

SECURITY_REPORT.md lists the two fields to review: the email columns of the starter’s User and BillingCustomer models. The vulnerable-dependency check needs cargo-audit installed. To see the IDOR check work, delete one rullst-access comment and run cargo rullst audit --idor: it fails and names the route. See the security report guide.

8. Develop with live reload

cargo rullst dev

Tip: run `cargo rullst dash` for live requests/s, latency, errors and database metrics.
Building the application...
Running initial db:migrate...
Nothing to migrate.
📊 Rullst Studio running on http://127.0.0.1:5555
🚀 SaaS server starting on port 3000...
…
Rullst framework serving on http://127.0.0.1:3000
…
Auto-reload: watching source, assets and configuration; successful builds restart the application.

Open http://127.0.0.1:3000/register, create an account, then go to http://127.0.0.1:3000/notes. Saving a source file rebuilds and restarts the app; a failed build keeps the previous one running. cargo rullst dash runs the same loop inside a terminal dashboard with live requests, latency, errors and database metrics. When one request repeats the same ORM operation three or more times, the dashboard adds a POSSIBLE N+1 QUERIES panel with the route, the operation and the count; see the N+1 query warning. Stop either with Ctrl+C. See supervised auto-reload and the dash reference.

9. Build for production and deploy

cargo rullst build

🚀 Starting Rullst production build pipeline (Release Mode: true)...
⚙️ Executing cargo build --release...
    Finished `release` profile [optimized] target(s) in 5m 48s
📦 Pre-compressing static assets in static/ directory...
…
✨ Pre-compression finished: processed 2 files, generated 2 .br files and 2 .zst files.
🎉 Rullst production build completed successfully!

The release binary is target/release/notes (15.3 MiB in the recorded run). Cargo builds it with the [profile.release] that cargo rullst new wrote into Cargo.toml: thin LTO, one codegen unit and stripped symbols. panic stays unwind, so one panicking handler cannot stop the server.

The build also writes Brotli and Zstandard copies of the files in static/, which the server prefers; run it again after changing an asset. The /static mount also sets cache headers. A file name with a content hash, such as app.3f9a2c1b.css, is cached for a year as immutable; other files, such as the starter’s rullst.css, get Cache-Control: no-cache and are revalidated with their ETag. Started with the development .env, the binary answered 200 on /health, redirected /notes to /login, and served /static/rullst.css Brotli-compressed with no-cache and an ETag.

Measure the build with cargo rullst green (Experimental). On its own, cargo rullst green --path /health starts the release binary with RULLST_ENV=production, which the SaaS starter refuses until the production billing settings exist:

error: App could not be started
  What happened  the app exited during start-up (exit status: 1).
                 Last stderr lines:
                 Error: BillingConfigError("production billing requires real credentials, a strong webhook secret, an HTTPS redirect URL, and an explicit plan allowlist")

Until then, either pass --env staging, which the starter accepts with its mock billing credentials, or start ./target/release/notes with the development .env and measure it from a second terminal:

cargo rullst green --url http://127.0.0.1:3000 --path /health --bench

The report lists what it measured, each with its method: the binary size of the running executable, the idle resident memory, the number of third-party packages in Cargo.lock and, because of --bench, the app’s CPU time during a 10-second loopback load and the CPU time per request. The container image size is NOT MEASURED until you name an image with --image. The figures describe one run on one machine, with the load generator on the same machine; compare runs only on the same setup. green measures no energy: a carbon figure appears only as an SCI estimate from your own --cpu-watts and --grid-intensity. See efficiency figures for an app.

Before it serves real users:

• create a production environment file with RULLST_ENV=production, a new APP_KEY and the billing settings described in the generated BILLING.md; never reuse the development .env;
• check that file with cargo rullst deploy:doctor --env-file .env.production. Run against the development .env, it fails with [FAIL] environment_target, because that file does not set RULLST_ENV=production;
• choose a platform: guided container deployment (cargo rullst deploy writes a Dockerfile, compose.yaml and Caddyfile for a Linux VM; see Deploy to a Linux VM), Kubernetes, or a container from cargo rullst dockerize. Run migrations once per release, before starting the new version.

Where next

• Read the generated AGENTS.md before asking an AI assistant to change the app, and see the CLI reference for every command.
• Add background jobs, email or real billing. Work that can wait, such as reports and exports, can be deferred to an allowed time window.
• Before launch, read the security architecture and check each crate’s maturity tier.

Tutorial 01: From Zero to Hello Rullst 🚀

What you will build: one complete web application with a typed route and server-rendered HTML. No database account or AI provider is needed. By the end, you will be able to point to the handler that produced the page in your browser.

Choose a different starting path · Next: CLI generators

This tutorial takes a new developer from installing Rust to a running Rullst web application. It targets the v13 prerelease 13.0.0-alpha.4. The v12 line reached end of life on 16 October 2026 (see the release record); existing v12 applications follow the v13 migration guide.

1. Install Rust and Cargo

On Linux or macOS, use the official rustup installer:

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

On Windows, download rustup from rustup.rs or run:

winget install --id Rustlang.Rustup

Restart the terminal if necessary, then verify the toolchain:

rustc --version
cargo --version

Rullst v13 requires Rust 1.96.0 or newer, the MSRV recorded in the compatibility policy. Run rustup update if rustc --version reports an older release.

2. Create a project

cargo new my_first_app
cd my_first_app

Every command below must run in this directory, where Cargo.toml lives.

3. Add Rullst

Add the v13 prerelease from crates.io. Name its exact version: Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026, so a plain cargo add rullst would pick an unmaintained 12.x:

cargo add rullst@=13.0.0-alpha.4
cargo add tokio --features full

Cargo records the resolved dependency graph in Cargo.lock. Commit that file for an application so its checkout remains reproducible, and review future dependency updates before deployment.

4. Define the first route

Replace src/main.rs with:

use rullst::{html, routes, Markup, Server};

async fn home() -> Markup {
    html! {
        <div class="min-h-screen bg-slate-900 text-emerald-400 flex flex-col items-center justify-center font-sans">
            <h1 class="text-5xl font-extrabold mb-4">"Hello, Rullst! 📜🦀"</h1>
            <p class="text-slate-400 text-lg">"Your first typed route is running."</p>
        </div>
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![
        get("/" => home)
    ];

    Server::new(app).run(3000).await?;
    Ok(())
}

The fallible server startup uses ?, so bind and runtime failures are returned to the process instead of causing a framework-originated panic.

5. Run the application

Start the server:

cargo run

The first build compiles every dependency and can take several minutes (Build times). When the terminal prints Rullst framework serving on http://127.0.0.1:3000, open http://127.0.0.1:3000. Stop the server with Ctrl+C.

Make it yours: change the heading to your project name, restart with cargo run, and confirm the response changed. The example’s utility class names do not install Tailwind by themselves; seeing an unstyled page is not a server failure. The Blank and SaaS starters of the CLI ship a local stylesheet (static/rullst.css).

If the port is already occupied, stop the conflicting process you own or start on another port with PORT=3001 cargo run: the PORT variable (from the environment, then .env) takes precedence over the .run(3000) argument. Keep the terminal output: it is the first place to look for a build or startup diagnostic.

6. Continue with the CLI

The CLI can generate complete starters and project modules. Install the v13 prerelease from crates.io (name the exact version; Cargo never picks a prerelease on its own):

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked
cargo rullst --version

The second command prints rullst 13.0.0-alpha.4. Tutorial 02 creates a project with it; the hand-written my_first_app is not needed there.

The CLI’s new generator targets the CLI’s own framework version. A CLI built from a source checkout of main is the v13 development line: it emits absolute path dependencies to that exact checkout, including when invoked elsewhere. Keep such a checkout in place and review its sources before sharing a generated project. See the CLI reference for every command and boundary.

Key takeaways

• The rullst::html! macro generates ordinary Rust string-building code and escapes dynamic values. It returns Markup, which a handler returns as text/html and another html! inserts as HTML. Rendering still performs the allocations/work implied by the generated template.
• Boolean HTML attributes inside html! are written bare (required) or conditionally (checked?={is_done} writes checked or nothing). Presence is the value, so disabled="false" would still disable the control.
• Fallible handlers can return Result<Response, YourAppError> using an application-defined error that converts the relevant typed framework/domain errors; server startup propagates ServerError with ?.
• The moving main branch is an integration source, not an immutable release artifact. For a reproducible application, pin the exact crates.io version (=13.0.0-alpha.4) and commit Cargo.lock.

Create Your First Rullst REST API

Your result: a typed JSON response you can verify from another terminal. Start here when your frontend is a separate app, mobile client or integration. Explore all beginner paths or the complete API learning-path index.

This quickstart creates one runnable JSON endpoint without a database or an AI provider. It targets the v13 prerelease 13.0.0-alpha.4; the v12 line reached end of life (see the release record). You need Rust 1.96.0 or newer (Tutorial 01 shows how to install it).

1. Create the application

cargo new first_rullst_api
cd first_rullst_api
cargo add rullst@=13.0.0-alpha.4
cargo add tokio --features macros,rt-multi-thread
cargo add serde --features derive

The exact requirement keeps this tutorial on the v13 prerelease (Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026). Commit the generated Cargo.lock so subsequent locked builds use the same resolved package versions; it does not pin an unrelated moving Git branch or automatically update the app.

2. Add a JSON route

Replace src/main.rs with:

use rullst::{Server, ServerError, routes, server::Json};
use serde::Serialize;

#[derive(Serialize)]
struct HealthResponse {
    status: &'static str,
    framework: &'static str,
}

async fn health() -> Json<HealthResponse> {
    Json(HealthResponse {
        status: "ok",
        framework: "Rullst",
    })
}

#[tokio::main]
async fn main() -> Result<(), ServerError> {
    let app = routes![
        get("/api/health" => health),
    ]
    .layer(rullst::server::from_fn(
        rullst::security::headers_middleware,
    ));

    Server::new(app).run(3000).await
}

The response is serialized from a typed Rust value. The secure-header layer is included explicitly because transport, proxy, authentication, authorization, CSRF, and application-specific input policy remain deployment responsibilities; a JSON response alone is not a production security boundary.

3. Run and verify it

Start the application:

cargo run

From another terminal, request the route:

curl -i http://127.0.0.1:3000/api/health

The body is:

{"status":"ok","framework":"Rullst"}

Stop the server with Ctrl+C.

4. Prefer a generated API foundation?

After installing the v13 CLI, it can scaffold a headless API directly. Use a different directory from the hand-written example above:

cargo rullst new generated_api --default --api --no-database \
  --skip-initial-migration
cd generated_api
cargo run

This is the API starter (the Blank starter without HTML). Its routes are registered in router() in src/main.rs, not copied from the health handler above: GET / answers with a JSON welcome message (curl http://127.0.0.1:3000/), POST /api/messages requires Authorization: Bearer <API_TOKEN> with the random token written to .env, and /health and /ready serve container probes. Use cargo rullst make:controller project --api for additional JSON controllers. Generated parameterized data routes still require explicit ownership or tenant authorization; see RBAC and IDOR protection.

Tutorial 02: CLI Automation & Generators ⚡

Your goal: generate a small piece of the application, find the resulting files and understand what still needs your code. You need the CLI installed in Tutorial 01 (cargo rullst --version prints rullst 13.0.0-alpha.4).

Rullst provides opinionated code generators (make:*) for controllers, models, migrations, and resources. The current generators register generated Rust modules when possible; they do not add application routes. make:controller and make:model also refresh the generated project map (.llms.txt, .rullst/context-map.json) and diagram.md; hand-written versions of those files are kept. Review every generated file and mount the intended routes yourself.

Create the project

Create a Blank starter with SQLite and enter it:

cargo rullst new shop --default --blueprint blank --database sqlite \
  --skip-initial-migration
cd shop

--default skips the wizard’s questions. The project has Cargo.toml, Rullst.toml, .env, src/main.rs (the routes, in router()) and a first users migration. Run every command below from this directory; the following tutorials use the same project unless they say otherwise. To see the welcome page, run cargo rullst dev and open http://127.0.0.1:3000; the first build can take several minutes.

🛠️ Essential Scaffolding Commands

Run the three commands in order: each one adds different files.

1. Generate a Controller

cargo rullst make:controller ProductsController

Creates src/controllers/products_controller.rs with placeholder index, show, store, update, and delete handlers and registers the module (pub mod controllers; in src/main.rs). Mount its page by adding a line to the routes![...] list in router():

get("/products" => controllers::products_controller::index),

After cargo rullst dev rebuilds, http://127.0.0.1:3000/products shows the generated placeholder page.

2. Generate a Model & Migration

cargo rullst make:model Product --migration

Creates the model in src/models/product.rs and a timestamped Rust migration (src/migrations/m<timestamp>_create_products.rs) that src/migrations/mod.rs registers. The model starts with an id and a snapshot field, the migration with id and timestamps; Tutorial 03 adds the columns. cargo rullst dev applies pending migrations when it starts; cargo rullst db:migrate applies them without starting the server (Tutorial 05).

3. Generate a Full-Stack Resource Starting Point

cargo rullst make:resource Category

Scaffolds a model (src/models/category.rs), its migration, a controller (src/controllers/category_controller.rs) and HTML view placeholders (views/category/index.html and views/category/form.html) in one command. Use a name that has no model yet: for an existing model or table the command skips the create-table migration. The generated controller is not a complete authorized CRUD implementation.

🔍 Static CLI Code Inspection

Inspect recognizable source declarations without launching a server:

# Inspect recognizable routes! declarations
cargo rullst inspect routes

# Print ORM models and field types
cargo rullst inspect models

Add --json for a versioned machine-readable document (see the CLI reference).

💡 Key Takeaways

• Scaffolding generators maintain architectural consistency across team members.
• cargo rullst inspect performs bounded source-text inspection. Route output recognizes explicit single-line routes! entries (get, post, put and delete); model output lists public declarations from src/models. It is not complete macro expansion or a Rust semantic analysis.
• Generators never add routes: mount each handler in router() yourself.

Tutorial 03: Active Record CRUD Operations 🗄️

rullst-orm derives a typed query builder and persistence methods from a Rust struct. The SQLx-backed model uses an i32 primary key named id; a zero value means that save() inserts, while a non-zero value means that it updates.

This tutorial continues in the shop project of Tutorial 02, whose cargo rullst make:model Product --migration wrote src/models/product.rs and src/migrations/m<timestamp>_create_products.rs.

Step 1: Define an Active Record model

Give the generated migration the columns the model will use. In its up():

Schema::create("products", |table| {
    table.id();
    table.string("name").not_null();
    table.integer("price_cents").not_null();
    table.timestamps();
}).await

Then add the matching fields to src/models/product.rs:

#![allow(unused)]
fn main() {
use rullst::db::{Orm, RowSnapshot};

#[derive(Debug, Clone, Orm)]
#[orm(table = "products")]
pub struct Product {
    pub id: i32,
    pub name: String,
    pub price_cents: i32,
    // Remembers the loaded values, so `save()` writes only the columns this
    // record changed. Build new records with `snapshot: RowSnapshot::default()`.
    #[sqlx(skip)]
    pub snapshot: RowSnapshot,
}
}

Apply the migration with cargo rullst db:migrate (or restart cargo rullst dev) before using the model. The model leaves out created_at/updated_at, so inserts keep their database defaults. If cargo rullst dev already applied the migration while it had only an id, run cargo rullst db:rollback (it reverts the last batch of migrations, including this one) and then cargo rullst db:migrate; Tutorial 05 explains both commands.

Step 2: Perform CRUD operations

Call these methods from an async handler or seeder, for example in a controller of Tutorial 02.

Create

#![allow(unused)]
fn main() {
use rullst::db::{Orm, RowSnapshot};
#[derive(Debug, Clone, Orm)]
#[orm(table = "products")]
struct Product { id: i32, name: String, price_cents: i32, #[sqlx(skip)] snapshot: RowSnapshot }
async fn create_product() -> Result<(), rullst::orm::Error> {
let mut product = Product {
    id: 0,
    name: "Starter kit".to_string(),
    price_cents: 2_500,
    snapshot: RowSnapshot::default(),
};
product.save().await?;
// `product.id` now contains the inserted primary key.
Ok(())
}
}

Read and filter

#![allow(unused)]
fn main() {
use rullst::db::{Orm, RowSnapshot};
#[derive(Debug, Clone, Orm)]
#[orm(table = "products")]
struct Product { id: i32, name: String, price_cents: i32, #[sqlx(skip)] snapshot: RowSnapshot }
async fn read_products() -> Result<(), rullst::orm::Error> {
let product = Product::find(1).await?; // Result<Option<Product>, rullst::orm::Error>
let kits = Product::query()
    .where_like("name", "%kit%")
    .get()
    .await?;
let _ = (product, kits);
Ok(())
}
}

Builder values are bound as query parameters. Column names are validated as identifiers, but they should still be application-owned constants rather than untrusted request input.

Update

#![allow(unused)]
fn main() {
use rullst::db::{Orm, RowSnapshot};
#[derive(Debug, Clone, Orm)]
#[orm(table = "products")]
struct Product { id: i32, name: String, price_cents: i32, #[sqlx(skip)] snapshot: RowSnapshot }
async fn update_product() -> Result<(), rullst::orm::Error> {
if let Some(mut product) = Product::find(1).await? {
    product.price_cents = 2_000;
    // The snapshot makes this an UPDATE of `price_cents` only.
    product.save().await?;
}
Ok(())
}
}

Delete

#![allow(unused)]
fn main() {
use rullst::db::{Orm, RowSnapshot};
#[derive(Debug, Clone, Orm)]
#[orm(table = "products")]
struct Product { id: i32, name: String, price_cents: i32, #[sqlx(skip)] snapshot: RowSnapshot }
async fn delete_product() -> Result<(), rullst::orm::Error> {
if let Some(product) = Product::find(1).await? {
    product.delete().await?;
}
Ok(())
}
}

Without a RowSnapshot field, save() on a loaded record writes every column, so the last writer wins; see the ORM guide for dirty tracking and update_partial().

Soft deletes

A deleted_at: Option<String> field opts the model into the default soft-delete contract. For a different sentinel, configure it explicitly and ensure the migration uses the same representation:

#![allow(unused)]
fn main() {
use rullst_orm::Orm;

#[derive(Debug, Clone, Orm)]
#[orm(
    table = "users",
    soft_delete(field = "is_deleted", value = "0", delval = "1")
)]
pub struct SoftUser {
    pub id: i32,
    pub name: String,
    pub is_deleted: i32,
}
}

query() applies the model’s configured scopes. unscoped() is an explicit administrative escape hatch and should not be used directly from request data.

restore() clears the soft-delete marker and force_delete() removes the row permanently. Both check the tenant and the policy (can_restore / can_force_delete) first and then run in a savepoint of the task-scoped Orm::transaction, or in their own transaction, like delete():

• force_delete() runs the before_delete/after_delete hooks and the deleting/deleted observers, writes a force_deleted audit entry on auditable models, and after commit invalidates the query cache, publishes the Redis deleted event, calls committed(Deleted) and removes the Scout document. It does not cascade to cascade_soft_delete relations.
• restore() re-reads the restored row, calls the updated and saved observers with it, writes a restored audit entry, and after commit invalidates the cache, publishes the Redis updated/saved events, calls committed(Updated) and re-indexes the Scout document. The save hooks and the saving/updating observers are not called, because restore writes only the soft-delete column. Restoring a missing or live row is a no-op, and deleting an already trashed row again fails without changing its deletion time.

Key takeaways

• save, find, all, query, and delete are generated for SQLx-backed Orm models.
• Creation uses a normal Rust struct, not a JSON map.
• CRUD errors are returned as rullst::orm::Error (the rullst_orm::Error type); a missing row is Ok(None). Saving or deleting a handle whose row was deleted meanwhile returns RecordNotFound instead of silently succeeding.
• Use a caller-owned transaction and the generated *_with_tx methods when a business operation must commit multiple writes atomically.

Tutorial 04: Data Mapper & Repository Pattern 🏗️

For domain-heavy code, Rullst exposes a small Repository<T> contract. The framework does not invent SQL for this trait: your adapter owns its pool, queries, transactions, and error type. This keeps persistence behavior explicit and makes an in-memory implementation straightforward in unit tests.

GenericRepository<T> is currently only a zero-state marker/helper. It does not accept a pool and does not provide methods such as find_one_by.

Step 1: Implement a PostgreSQL repository

This User is a plain struct, not a #[derive(Orm)] model (which implements FromRow itself), so it derives SQLx’s FromRow. Rullst does not enable SQLx’s derive macros (since 13.0.0-alpha.4): add them to your manifest with sqlx = { version = "0.9", default-features = false, features = ["derive"] }, or implement FromRow by hand.

#![allow(unused)]
fn main() {
use rullst_orm::{async_trait, sqlx, Repository};

#[derive(Debug, Clone, sqlx::FromRow)]
pub struct User {
    pub id: i64,
    pub name: String,
    pub email: String,
}

#[derive(Clone)]
pub struct PgUserRepository {
    pool: sqlx::PgPool,
}

impl PgUserRepository {
    pub fn new(pool: sqlx::PgPool) -> Self {
        Self { pool }
    }

    pub async fn find_by_email(
        &self,
        email: &str,
    ) -> Result<Option<User>, sqlx::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users WHERE email = $1",
        )
        .bind(email)
        .fetch_optional(&self.pool)
        .await
    }
}

#[async_trait]
impl Repository<User> for PgUserRepository {
    type Id = i64;
    type Error = sqlx::Error;

    async fn find_by_id(&self, id: i64) -> Result<Option<User>, Self::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users WHERE id = $1",
        )
        .bind(id)
        .fetch_optional(&self.pool)
        .await
    }

    async fn find_all(&self) -> Result<Vec<User>, Self::Error> {
        sqlx::query_as::<_, User>(
            "SELECT id, name, email FROM users ORDER BY id",
        )
        .fetch_all(&self.pool)
        .await
    }

    async fn save(&self, user: &User) -> Result<(), Self::Error> {
        sqlx::query(
            "INSERT INTO users (id, name, email) VALUES ($1, $2, $3) \
             ON CONFLICT (id) DO UPDATE SET name = $2, email = $3",
        )
        .bind(user.id)
        .bind(&user.name)
        .bind(&user.email)
        .execute(&self.pool)
        .await?;
        Ok(())
    }

    async fn delete(&self, id: i64) -> Result<(), Self::Error> {
        sqlx::query("DELETE FROM users WHERE id = $1")
            .bind(id)
            .execute(&self.pool)
            .await?;
        Ok(())
    }
}
}

All values are parameterized. SQL identifiers and the query shape remain application-owned source code.

This adapter targets PostgreSQL (PgPool, $1 placeholders) and a users table with BIGINT ids. Inside a generated project, rullst::db::Orm::pool()? returns the application’s pool as RullstPool, which is sqlx::SqlitePool with the SQLite starter and sqlx::PgPool with PostgreSQL: clone it into the adapter and write the queries for that database.

Step 2: Inject the concrete adapter through Axum state

use std::sync::Arc;
use rullst::web::axum::{
    extract::{Query, State},
    http::StatusCode,
    Json,
};
use serde::Deserialize;

#[derive(Deserialize)]
pub struct EmailQuery {
    email: String,
}

pub async fn get_user_by_email(
    State(repository): State<Arc<PgUserRepository>>,
    Query(query): Query<EmailQuery>,
) -> Result<Json<User>, StatusCode> {
    repository
        .find_by_email(&query.email)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
        .map(Json)
        .ok_or(StatusCode::NOT_FOUND)
}

rullst::Router has no with_state: build this route on an axum::Router, call .with_state(Arc::new(repository)) and mount it with merge_axum, as Tutorial 08 shows. Returning Json<User> also requires User to derive serde::Serialize. Production handlers should map internal database errors to an application error without returning query or credential details to clients.

Key takeaways

• Use derived Active Record models for direct typed CRUD.
• Use Repository<T> when the domain needs an explicit persistence boundary.
• The repository implementation, not the trait, determines the supported backend and SQL dialect.
• Add tenant/owner predicates inside repository queries where the resource is tenant- or user-scoped; dependency injection is not an authorization check.

Tutorial 05: Database Migrations & Seeders 🗄️

Rullst uses timestamped Rust migration modules for SQLx-primary projects. Turso primary projects receive explicit, reversible TursoMigration statements instead. This tutorial shows the SQLx path: Schema works with SQLite, PostgreSQL and MySQL/MariaDB only, as Database Support lists.

Step 1: Create a migration

Run this in the shop project of Tutorial 02, which already has products and categories tables:

cargo rullst make:migration create_catalog_items_table

The command creates src/migrations/m<timestamp>_create_catalog_items_table.rs and regenerates src/migrations/mod.rs. Edit the generated up and down methods:

#![allow(unused)]
fn main() {
use rullst_orm::{async_trait, schema::{ForeignKeyAction, Migration, Schema}};

pub struct MigrationImpl;

#[async_trait]
impl Migration for MigrationImpl {
    fn name(&self) -> &'static str {
        "m20260901000000_create_catalog_items_table"
    }

    async fn up(&self) -> Result<(), rullst_orm::Error> {
        Schema::create("catalog_items", |table| {
            table.id();
            table.string("name").not_null();
            // MySQL/MariaDB cannot index a TEXT column, so the indexed SKU
            // has a bounded type.
            table.string("sku").not_null().unique().col_type = "VARCHAR(64)".to_string();
            table
                .foreign_id("category_id", "categories")
                .on_delete(ForeignKeyAction::Restrict);
            table.integer("price_cents").not_null();
            table.check("price_cents >= 0");
            table.date("available_on");
            table.index(&["category_id", "available_on"]);
            table.timestamps();
        })
        .await
    }

    async fn down(&self) -> Result<(), rullst_orm::Error> {
        Schema::drop_if_exists("catalog_items").await
    }
}
}

Keep the generated timestamp/name in name(); the runner uses that stable value to record migration state. The foreign key needs the referenced table: categories comes from cargo rullst make:resource Category, and this migration, generated later, has a later timestamp and runs after it.

unique(), index(...), foreign_id(...)/foreign(...) and check(...) declare constraints and indexes with the table (see the ORM guide for every option and the generated names). PostgreSQL and SQLite create the indexes with CREATE INDEX IF NOT EXISTS right after the table; MySQL/MariaDB declare them inside CREATE TABLE.

table.timestamps() creates nullable created_at/updated_at UTC-instant columns that default to the current time: TIMESTAMPTZ on PostgreSQL, DATETIME(6) on MySQL/MariaDB and RFC 3339 text on SQLite. Read them as rullst::orm::chrono::DateTime<Utc> model fields. date(), time(), timestamp() and timestamp_tz() add single date/time columns for NaiveDate, NaiveTime, NaiveDateTime and DateTime<Utc> fields. They need a strict driver feature (strict-postgres, strict-mysql or strict-sqlite), which cargo rullst new selects: the multi-driver SQLx Any pool cannot read date/time values, so with it timestamps() keeps TEXT columns for String fields and the other date/time helpers fail on PostgreSQL and MySQL/MariaDB.

To change an existing table, use Schema::table:

#![allow(unused)]
fn main() {
use rullst_orm::schema::{ForeignKeyAction, Schema};

async fn up() -> Result<(), rullst_orm::Error> {
Schema::table("products", |table| {
    table.integer("category_id");
    table
        .foreign("category_id")
        .references("categories", "id")
        .on_delete(ForeignKeyAction::SetNull);
    table.unique_index(&["name", "category_id"]);
})
.await
}
}

SQLite cannot add constraints to an existing table: a foreign key works there only on a nullable column added in the same call, and a CHECK, a foreign key on an existing column or a NOT NULL column without a default return Error::UnsupportedSchemaChange before anything runs.

table.float(...) maps to an f64 model field: it emits DOUBLE PRECISION on PostgreSQL, DOUBLE on MySQL/MariaDB and REAL on SQLite. PostgreSQL columns created by earlier Rullst versions were single-precision REAL; migrate them explicitly (ALTER TABLE products ALTER COLUMN price TYPE DOUBLE PRECISION) before relying on f64 precision.

table.boolean(...) maps to a bool model field. PostgreSQL receives a native BOOLEAN (an integer default of 0/1 becomes FALSE/TRUE); MySQL/MariaDB and SQLite keep an INTEGER 0/1 flag. PostgreSQL columns created by earlier versions were INTEGER; migrate them with ALTER TABLE t ALTER COLUMN c TYPE BOOLEAN USING c <> 0.

Text defaults (ColumnDefault::Text) and table.enum_col(...) variants are embedded in the DDL as single-quoted literals with doubled single quotes. Schema::create rejects such text when it contains a backslash or a control character, because MySQL/MariaDB treat a backslash inside a quoted literal as an escape character by default.

Step 2: Run, inspect, and roll back migrations

cargo rullst db:migrate
cargo rullst db:status
cargo rullst db:rollback

db:rollback runs down() for the last recorded batch, in reverse order. The SQLx migration runner does not wrap the whole batch in one database transaction. By default it runs each up()/down() and then records it in the migrations table as separate statements, so a crash or lost connection in between leaves a change applied but unrecorded. A migration that returns true from within_transaction() (v13 prerelease API) runs up()/down() and its record inside one Orm::transaction instead. The template written by the ORM’s own artisan make:migration command opts in; add the method to migrations generated by cargo rullst make:migration yourself:

fn within_transaction(&self) -> bool {
    true
}

Only statements that join that transaction are covered: Schema calls, generated model methods, rullst_orm::execute_query! and raw SQL sent with Orm::raw(sql).execute() (or .map_to()). Orm::raw is the raw-SQL path that stays in the transaction:

async fn up(&self) -> Result<(), rullst_orm::Error> {
    Schema::create("tags", |table| {
        table.id();
        table.string("name").not_null();
    })
    .await?;
    // Runs in the migration's transaction, so it sees the new table and rolls
    // back with it.
    Orm::raw("CREATE UNIQUE INDEX tags_name_key ON tags (name)")
        .execute()
        .await?;
    Ok(())
}

Orm::pool() and Orm::read_pool() would hand out another connection that cannot see the transaction’s uncommitted tables and does not roll back with it. Since 13.0.0-alpha.3 they return Error::Validation, naming the migration, while such a migration’s up()/down() runs, so the migration fails and rolls back unrecorded instead of half-applying (Orm::begin_transaction() fails the same way). Keep the default false for a migration that sends queries such as sqlx::query(sql).execute(Orm::pool()?). A pool obtained before the migration ran, another crate’s pool or a task spawned from up() is not detected and still runs outside the transaction. PostgreSQL and SQLite roll the DDL back with the record; MySQL and MariaDB commit each DDL statement implicitly, so there only data changes after the last DDL statement are atomic with the record. Statements that refuse to run in a transaction block, such as PostgreSQL CREATE INDEX CONCURRENTLY, also need false. Make every migration reversible and test both directions against each supported database.

These commands use the same database as the running server: the process DATABASE_URL, then DATABASE_URL in ./.env (never overriding the process environment), then [database].url in Rullst.toml. If none is set, the command fails instead of creating a new SQLite file, and a database that cannot be initialized also fails the command with exit status 1.

Each migration’s tracking row is removed as soon as its down() succeeds. If a later down() fails, the rollback stops with that error: the migrations it already reverted are no longer recorded as applied, while the failed migration and the rest of the batch stay recorded. Fix the cause and run db:rollback again to continue from that point.

db:migrate and db:rollback hold a runner lock for the whole run on PostgreSQL (pg_advisory_lock) and MySQL/MariaDB (GET_LOCK), on a dedicated connection outside the pool. Replicas that start together therefore apply each pending migration once: a second runner waits, then finds it already recorded. The lock is released when the run ends or its process exits. A newly created migrations table also declares the migration name UNIQUE. SQLite has no cross-process advisory lock, so run a single migrator per SQLite database.

Step 3: Define and register a seeder

Create src/seeds.rs with a seeder for the Product model of Tutorial 03, and declare mod seeds; in src/main.rs:

use rullst::db::{async_trait, RowSnapshot, Seeder};
use crate::models::product::Product;

pub struct CatalogSeeder;

#[async_trait]
impl Seeder for CatalogSeeder {
    async fn run(&self) -> Result<(), rullst::orm::Error> {
        // Idempotent: a second `db:seed` finds the row and adds nothing.
        let existing = Product::query()
            .where_eq("name", "Starter kit")
            .first()
            .await?;
        if existing.is_some() {
            return Ok(());
        }
        let mut product = Product {
            id: 0,
            name: "Starter kit".to_string(),
            price_cents: 2_500,
            snapshot: RowSnapshot::default(),
        };
        product.save().await
    }
}

pub fn get_seeders() -> Vec<Box<dyn Seeder>> {
    vec![Box::new(CatalogSeeder)]
}

Register migrations and seeders before starting the server: in main(), replace the starter’s rullst::artisan!(crate::migrations::get_migrations()); with

rullst::artisan!(
    crate::migrations::get_migrations(),
    crate::seeds::get_seeders()
);

Without artisan!, Server::run still recognizes db:migrate, db:rollback, db:status and db:seed, but it has no registry to run them against: the process exits with status 1 and asks for rullst::artisan! rather than reporting “Nothing to migrate.” as a success.

Then run:

cargo rullst db:migrate
cargo rullst db:seed

db:seed first checks the registered migrations against the migrations table. While one is pending it runs no seeder and fails, instead of letting a seeder fail on a table that does not exist yet:

Validation error: 1 migration(s) pending, starting with `m20261012_create_users`: run `db:migrate` before `db:seed`

Seeders execute sequentially. Make development/CI seeders idempotent, as above, if the command may run more than once. Never commit real passwords or provider secrets; for authentication records, hash a test password with rullst-auth or create a non-login fixture.

Key takeaways

• Migrations are Rust modules, not split up/down SQL files.
• Migration names and order are generated deterministically from timestamps.
• Batch tracking exists, but batch-wide transactional rollback is not implied.
• db:seed executes only seeders explicitly registered with artisan!, and only after every registered migration is applied.

Tutorial 06: HTMX-oriented server rendering 🎨

The Blank and SaaS starters render HTML on the server and use HTMX attributes for targeted requests and fragment swaps. It does not require a project-local SPA bundle, but HTMX itself is browser JavaScript. The CLI’s HTML starters write a pinned copy to static/htmx-1.9.12.min.js, which rullst::htmx::render_page loads from the same origin; an application without those generated assets must serve that file itself. The application’s CSP must permit it.

🛠️ Step 1: Render HTMX Components

In your controller or view:

#![allow(unused)]
fn main() {
use rullst::html;
use rullst::html::Markup;

pub async fn search_users() -> Markup {
    let results = vec!["Alice", "Bob", "Charlie"];
    let rows: Markup = results
        .into_iter()
        .map(|name| html! {
            <li class="py-2 text-slate-200">{name}</li>
        })
        .collect();

    html! {
        <ul id="user-list" class="divide-y divide-slate-700">
            {rows}
        </ul>
    }
}
}

html! returns Markup, escaped HTML that a handler can return directly (text/html; charset=utf-8). Each name is escaped, and the collected rows are inserted into the list as HTML. Mount the handler in router() of src/main.rs with get("/api/users/search" => search_users),.

Composing views

Interpolating a Markup inserts it as it is, so a view built by another html! call nests without a wrapper. A String, &str or number is always escaped, so request data stays text. Declare view helpers -> Markup, collect lists with .collect::<Markup>() and use Option<Markup> for parts that may be absent:

#![allow(unused)]
fn main() {
use rullst::html;
use rullst::html::Markup;

fn badge(label: &str) -> Markup {
    html! { <span class="badge">{label}</span> }
}

let name = "<Ana>";
let flagged = true;
// `name` is escaped; the badge is inserted as HTML.
let row = html! { <li>{name}{badge("new")}</li> };
assert_eq!(row, "<li>&lt;Ana&gt;<span class=\"badge\">new</span></li>");
// `None` renders nothing.
let note = flagged.then(|| html! { <em>"flagged"</em> });
assert_eq!(html! { <p>{note}</p> }, "<p><em>flagged</em></p>");
}

rullst::html::RawHtml (or Markup::from_trusted) is only for trusted HTML produced outside html!, such as a sanitizer’s output; never wrap request data in it. A full page can start with <!DOCTYPE html>, which html! emits as written, and element names may be Rust keywords, such as SVG’s <use href="#icon" />.

💻 Step 2: Wire HTMX Attributes in Front-End HTML

<div class="max-w-md mx-auto p-6 bg-slate-800 rounded-xl shadow-md">
    <input 
        type="text" 
        name="query" 
        placeholder="Search users..." 
        class="w-full px-4 py-2 bg-slate-900 text-white rounded border border-slate-700 focus:outline-none"
        hx-get="/api/users/search"
        hx-trigger="keyup changed delay:300ms" 
        hx-target="#user-list" 
        hx-swap="outerHTML" 
    />
    
    <div id="user-list" class="mt-4 text-slate-400">
        Start typing to search...
    </div>
</div>

Put this markup in a page that loads HTMX: the starter’s home handler returns its page through rullst::htmx::render_page_with_lang, which adds the same-origin HTMX script. The search handler is a GET route because it only reads a list. GET is not a workaround for CSRF. Commands that change data, send messages or incur provider charges must not be converted to GET to avoid validation. For POST forms, including an AI chat, follow the CSRF form contract. HTMX does not automatically copy Rullst’s CSRF cookie into a header or make HTTP error bodies visible in the target element.

🧪 Step 3: Snapshot-test rendered HTML

rullst::testing::assert_html_snapshot! (v13) compares rendered HTML with tests/snapshots/<name>.html in the crate that calls it, in unit and integration tests alike. Both sides are normalised first: whitespace-only text between tags is dropped, every tag that follows another tag starts a new line, other whitespace runs collapse to one space, and quoted attribute values and the content of pre, textarea, script and style stay as written. SnapshotOptions can also replace per-request values with documented placeholders: mask_nonce() writes {NONCE} for nonce="…" attributes and 'nonce-…' CSP sources, and mask_csrf_token() writes {CSRF_TOKEN} for a name="_token" field, <meta name="csrf-token"> and X-CSRF-Token values.

#![allow(unused)]
fn main() {
use rullst::html;
use rullst::testing::{SnapshotOptions, assert_html_snapshot};

fn search_form(nonce: &str, csrf_token: &str) -> rullst::html::Markup {
    html! {
        <form method="post" action="/search">
            <input type="hidden" name="_token" value={csrf_token} />
            <input type="search" name="q" />
            <script nonce={nonce} src="/static/search.js"></script>
        </form>
    }
}

// In a #[test] function:
assert_html_snapshot!(
    "search/form",
    search_form("per-response-nonce", "per-request-token"),
    SnapshotOptions::new().mask_nonce().mask_csrf_token()
);
}

A missing snapshot fails and names the file to create; a changed one fails with a compact line diff (- snapshot, + rendered). Run the tests with RULLST_UPDATE_SNAPSHOTS=1 to write missing snapshots and overwrite changed ones, then review the files and commit them. Snapshot names use ASCII letters, digits, _, - and ., with / between folders; a name that would leave tests/snapshots is refused. The helper is test code: it panics like assert_eq! and has no production use.

💡 Key Takeaways

• Small application-owned client surface: business logic can remain on the server while HTMX coordinates browser requests.
• Partial rendering: handlers can return fragments instead of full pages. Measure page weight and latency for the actual application; no fixed size or load-time guarantee follows from the rendering style.

Tutorial 07: Forms & DTO Validation 📝

Rullst provides ValidatedForm<T> and ValidatedJson<T> extractors. They parse the request and run validator constraints before the handler is called. Invalid payloads become bounded 400, 413, 415 or 422 JSON responses. HTMX requests (HX-Request: true) instead receive an HTML error fragment with 200 OK, because HTMX 1.x and 2.x swap only successful responses by default; the X-Rullst-Validation-Status header carries the REST status. htmx swaps the fragment into the form’s hx-target with its hx-swap, so point hx-target at an error or result container rather than at the form itself.

A body that cannot be parsed gets a fixed message: 413 “Request body is too large.” for a body over the extractor limit, 415 “Unsupported request content type.” for a wrong content type, and 400 “The submitted data could not be read or has an invalid format.” for a malformed body or an unknown enum variant (422 stays reserved for failed validator constraints). The deserializer’s own text can echo request input, so it is logged at debug level on the rullst::validation target and not returned. Every message and field name in the HTMX fragment is HTML-escaped, including custom validator messages. Errors inside #[validate(nested)] structs and lists are reported under dotted and indexed paths such as address.zip and items[0].name. ValidationError’s Display and Debug list only those paths and validator codes, never the rejected values, so logging the error cannot leak a password.

Step 1: Define a validated DTO

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

#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserForm {
    #[validate(length(min = 3, max = 100))]
    pub name: String,

    #[validate(email)]
    pub email: String,

    #[validate(length(min = 12, max = 72))]
    pub password: String,
}
}

#[derive(Validate)] expands to ::validator::… paths, so the application needs a direct validator dependency. Projects generated by the v13 CLI already declare it; in an older project add the version Rullst uses:

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

length counts characters, while password hashing refuses more than 72 bytes: a 72-character password with accented or non-Latin characters passes this validator and then fails to hash. Check form.password.len() <= 72 (bytes) in the handler as well, as the controller generated by cargo rullst auth does. Add a request-body limit at the router/proxy boundary as validation happens after body extraction.

Step 2: Validate and hash before persistence

The following handler assumes the User model (src/models/user.rs) that cargo rullst auth generates in Tutorial 11:

use rullst::{html, server::StatusCode, Markup, ValidatedForm};
use rullst::auth::hash_password_async;
use rullst::db::RowSnapshot;
use rullst::orm::chrono::Utc;

pub async fn store(
    ValidatedForm(form): ValidatedForm<CreateUserForm>,
) -> Result<Markup, StatusCode> {
    // `length` counted characters; hashing refuses more than 72 bytes.
    if form.password.len() > 72 {
        return Err(StatusCode::UNPROCESSABLE_ENTITY);
    }
    let password_hash = hash_password_async(form.password)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    // The ORM inserts every field, so the model carries the `timestamps()`
    // values instead of relying on the column defaults.
    let now = Utc::now();
    let mut user = crate::models::user::User {
        id: 0,
        name: form.name.trim().to_owned(),
        email: form.email.trim().to_ascii_lowercase(),
        password_hash: Some(password_hash),
        oauth_provider: None,
        oauth_id: None,
        created_at: now,
        updated_at: now,
        // `#[orm(db_default)]` columns: inserts leave them to the database.
        is_admin: false,
        session_epoch: 0,
        snapshot: RowSnapshot::default(),
    };
    user.save()
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(html! {
        <div class="p-4 bg-emerald-900/50 text-emerald-300 rounded border border-emerald-500">
            <p>"User created successfully"</p>
        </div>
    })
}

This is a continuation snippet because the generated model lives in the application crate. The controller generated by cargo rullst auth sets the timestamps the same way with its utc_timestamp helper and also rejects a duplicate email before inserting. The checked extractor implementation itself is covered by rullst-core tests.

For a JSON endpoint, replace ValidatedForm with ValidatedJson; the DTO and handler body remain the same.

Step 3: Send the CSRF token with browser forms

Production/staging Server requests use the security baseline, including double-submit CSRF validation. A POST needs both the rullst_csrf cookie and its matching value in a form _token field or X-CSRF-Token header.

Extract the request-scoped token on the page’s GET handler. On a visitor’s first request, this is the same token that the middleware will set in the response cookie; reading the incoming cookie alone would miss it.

#![allow(unused)]
fn main() {
use rullst::{html, security::CsrfToken, server::Extension, Markup};

pub async fn message_form(
    Extension(csrf): Extension<CsrfToken>,
) -> Markup {
    html! {
        <form id="message-form" method="post" action="/messages"
              hx-post="/messages" hx-target="#message-result" hx-swap="innerHTML">
            <input type="hidden" name="_token" value={csrf.as_str()} />
            <label for="message">"Message"</label>
            <input id="message" name="message" required maxlength="600" />
            <button type="submit">"Send"</button>
        </form>
        <div id="message-result" role="status" aria-live="polite"></div>
    }
}
}

Mount GET and POST handlers in the protected application and serve the pinned HTMX asset from the same origin. This is a form-rendering snippet, not a full messaging service: /messages still needs a bounded validated DTO, application authorization and the intended domain operation. The hidden field works with both a normal URL-encoded form submission and HTMX; no global cookie-forwarding script is required. JSON requests instead need the matching header, while the browser still sends the cookie. Do not forward tokens to third-party URLs.

Serve form pages from ordinary paths. A GET for a path that looks like a static file never creates the token or sets the cookie: /robots.txt, /sitemap.xml, /favicon.ico, anything under /static/, and any path ending in .txt, .xml, .ico, .json, .css, .js, .png, .jpg, .jpeg, .svg, .webp or .wasm. Since 13.0.0-alpha.2 such a page still receives CsrfToken when the browser already has a valid rullst_csrf cookie from another page, but on a first visit there is none, and the Extension<CsrfToken> extractor fails with 500.

The development server does not automatically apply the production CSRF/WAF stack; its WAF only logs the requests production would refuse. For this extractor in development, explicitly compose rullst::server::from_fn(rullst::security::csrf_middleware) on the application router, as the generated form-enabled starters do. Nested CSRF composition with the production server is request-idempotent. Do not make the extractor optional and silently render an empty token. Exercise the production baseline over HTTPS before deployment; do not remove Secure to accommodate a production HTTP URL.

Show failures instead of a silent spinner

For the pinned HTMX 1.9.12 used by these examples, ordinary HTTP errors do not automatically replace the target content (ValidatedForm failures are the exception described above). Put the following in an application-owned, same-origin external script loaded with defer. This avoids requiring inline event handlers or weakening Content Security Policy:

const form = document.getElementById('message-form');
const status = document.getElementById('message-result');
if (form && status) {
    const showFailure = (event) => {
        if (event.detail.elt !== form) return;
        status.textContent = 'Message not sent. Reload the page and try again.';
    };
    for (const name of ['htmx:responseError', 'htmx:sendError', 'htmx:timeout']) {
        form.addEventListener(name, showFailure);
    }
    form.addEventListener('htmx:afterRequest', (event) => {
        // Validation fragments are swapped with 200 and this header.
        const rejected = event.detail.xhr.getResponseHeader('X-Rullst-Validation-Status');
        if (event.detail.elt === form && event.detail.successful && !rejected) {
            const input = form.elements.namedItem('message');
            if (input instanceof HTMLInputElement) input.value = '';
        }
    });
}

Keep the message on failure so the visitor can retry. Never insert an arbitrary server error body using innerHTML. Resetting only after success is also clearer than relying on event-order assumptions. In HTMX 1.9.12, form values have already been collected before htmx:beforeRequest; clearing an input there alone does not establish that an empty message was transmitted.

Diagnose a 403 before changing security policy

Do not log token values or session cookies. HX-Request: true is not a security exemption. Public browser chat endpoints retain CSRF and need separate abuse, rate and cost limits. The existing csrf_signed_webhook_paths configuration is only for exact POST paths authenticated by mandatory signed-webhook validation; it is not an AI-chat allowlist and does not verify signatures by itself.

Core’s htmx_csrf_contract regression tests exercise first-visit cookie/form agreement, ordinary and HTMX submissions, preservation of form data and rejection before handler execution. These in-process HTTP tests do not certify a reverse proxy, browser cookie policy, a live AI provider or application auth.

Key takeaways

• Validation is not sanitization and not authorization; enforce all three at their respective boundaries.
• Never store, log, or echo a plaintext password. Use the asynchronous Argon2id helper in request handlers.
• Enforce a unique database index on normalized email rather than relying only on a pre-insert lookup.
• Keep internal validation/database details out of production client errors.

Tutorial 08: Controllers, Routing & Middleware 🚦

Rullst’s Router wraps Axum’s router while preserving explicit Tower middleware composition. This example uses the Axum 0.8 request and Next types.

Step 1: Create a custom middleware

Generate the file with the CLI:

cargo rullst make:middleware Logger

It writes src/middlewares/logger_middleware.rs with an empty logger_middleware function and registers the module. Fill in the body, for example:

#![allow(unused)]
fn main() {
use rullst::web::axum::{
    extract::Request,
    middleware::Next,
    response::Response,
};

pub async fn logger_middleware(req: Request, next: Next) -> Response {
    let method = req.method().clone();
    let path = req.uri().path().to_owned();
    let response = next.run(req).await;

    // Prefer structured tracing in production; do not log query strings,
    // cookies, authorization headers, or request bodies by default.
    println!("[HTTP] {method} {path} -> {}", response.status());
    response
}
}

Step 2: Organize sub-routers

use rullst::{Router, Server, ServerError};
use rullst::routing::{get, post};
use rullst::web::axum::middleware;

async fn list_users() -> &'static str { "users" }
async fn create_user() -> &'static str { "created" }
async fn login() -> &'static str { "login" }

// Stand-in for the generated `logger_middleware` of Step 1.
async fn logger_middleware(
    request: rullst::web::axum::extract::Request,
    next: rullst::web::axum::middleware::Next,
) -> rullst::web::axum::response::Response {
    next.run(request).await
}

#[tokio::main]
async fn main() -> Result<(), ServerError> {
    let api = Router::new()
        .route("/users", get(list_users).post(create_user))
        .layer(middleware::from_fn(logger_middleware));

    let auth = Router::new().route("/login", post(login));
    let app = Router::new()
        .nest("/api/v1", api)
        .nest("/auth", auth);

    Server::new(app).run(3000).await
}

In the application, import the generated function (use crate::middlewares::logger_middleware::logger_middleware;) and pass it to from_fn the same way. A layer covers only the routes added before it. Use nest_axum or merge_axum when integrating a third-party raw axum::Router.

Step 3: Share application state

rullst::Router wraps an axum::Router<()>, whose handlers cannot take State<S>, so it has no with_state. Pass shared state in one of two ways:

• As a request extension. .layer(Extension(state)) inserts the value into every request, and handlers read it with Extension<T>. Rullst’s own middleware passes the CSRF token, the CSP nonce and the signed-in user id this way. Like every layer, it covers only the routes added before it.
• With Axum’s State. Build the routes that use State<S> as an axum::Router<S>, call its with_state, and mount the result with merge_axum (or nest_axum under a prefix).

use rullst::{Router, Server, ServerError};
use rullst::routing::get;
use rullst::web::axum::{self, Extension, extract::State};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    site_name: Arc<str>,
}

async fn home(Extension(state): Extension<AppState>) -> String {
    format!("Welcome to {}", state.site_name)
}

async fn about(State(state): State<AppState>) -> String {
    format!("About {}", state.site_name)
}

#[tokio::main]
async fn main() -> Result<(), ServerError> {
    let state = AppState { site_name: Arc::from("Rullst") };
    let stateful = axum::Router::new()
        .route("/about", get(about))
        .with_state(state.clone());
    let app = Router::new()
        .route("/", get(home))
        .layer(Extension(state))
        .merge_axum(stateful);

    Server::new(app).run(3000).await
}

Keep values in the state cheap to clone (Arc, connection pools): each request clones it.

Key takeaways

• Middleware order is security-sensitive. Use the canonical production baseline for secure headers, CSRF, CORS, and WAF rather than assembling those controls ad hoc.
• Authentication middleware establishes identity; handlers/repositories must still enforce resource ownership or role authorization.
• Apply request-body and concurrency limits before handlers that parse expensive or attacker-controlled input.

Tutorial 09: Environment Management & Configuration ⚙️

Rullst provides a validated runtime environment shared by its subsystems. New projects use RULLST_ENV; APP_ENV remains a legacy compatibility alias.

🛠️ Step 1: Define Environment Variables in .env

cargo rullst new already writes .env with RULLST_ENV=development, a random APP_KEY and the starter’s DATABASE_URL, plus a .env.example with a placeholder key. A hand-written project adds the file itself:

RULLST_ENV=development
PORT=3000
APP_KEY=REPLACE_WITH_YOUR_32_CHAR_RANDOM_KEY
DATABASE_URL=postgres://postgres:password@localhost:5432/my_app

Replace the placeholder with at least 32 bytes of random data, for example the output of openssl rand -base64 32: rullst-auth, which encrypts session cookies with APP_KEY, refuses shorter keys and the documented placeholders. PORT overrides the port passed to Server::run.

💻 Step 2: Access Configuration in Rust

#![allow(unused)]
fn main() {
use rullst::config::RullstConfig;

fn report_environment() -> Result<(), Box<dyn std::error::Error>> {
    let environment = RullstConfig::global().environment()?;
    // The process environment first, then `./.env`, as `Server` reads it.
    let database_is_configured =
        rullst::config::project_setting("DATABASE_URL")?.is_some();

    println!(
        "Booting Rullst in {environment} mode; database configured: {database_is_configured}"
    );
    Ok(())
}
}

Do not log DATABASE_URL: it commonly embeds a username and password. Report only whether configuration is present, and redact sensitive fields in structured telemetry.

The generated server bootstrap reads .env before applying its runtime policy. Neither Server nor the Artisan commands (db:migrate, db:seed, studio) load .env into the process environment, so std::env::var sees only real process variables there; read application settings with rullst::config::project_setting, which checks the process environment and then ./.env, and behaves the same in the server and in a seeder. Standalone utilities must load a dotenv file themselves or receive exported process variables. Environment precedence is exact: the process RULLST_ENV, legacy APP_ENV, then RULLST_ENV or APP_ENV in .env, then [app].env in Rullst.toml. Server never exports .env into the process environment; RullstConfig::environment() includes the .env step once a Server has started in the process, so it reports the environment the server enforces. Before that, and in standalone utilities, it reads only the process variables and [app].env, as Environment::detect always does. Unknown values are configuration errors rather than silently becoming development. rullst-auth cookie helpers also consult .env below the process variables and skip reading it when either is set; a malformed .env yields a fixed error that never quotes file content. A malformed or mistyped Rullst.toml fails with only its line and column, so the error can be logged without exposing app_key or connection strings.

Step 3: Configure the Browser Security Baseline

Server applies the same public apply_security_baseline composition in staging and production. CORS is deny-by-omission: list exact origins without a trailing slash, and enable credentialed cross-origin requests only when the application genuinely needs them.

[security]
csrf_same_site = "Strict"
cors_allow_origins = ["https://academy.example"]
cors_allow_credentials = false
csp = "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self' 'nonce-{NONCE}'; style-src 'self' 'nonce-{NONCE}'"
coep = "require-corp"

Wildcard, path-bearing, credential-bearing, queried or duplicate CORS origins are configuration errors, as are spellings a browser never sends: an uppercase scheme or host, or an explicit default port (:443 for HTTPS, :80 for HTTP). CORS compares the configured origin with the Origin header byte for byte. When credentials are enabled, Core still grants them only to an origin in the exact allowlist. Test the final policy behind the real TLS proxy because an intermediary can change headers and cookie behavior.

coep accepts only require-corp, credentialless, or unsafe-none. Keep the strict require-corp default for same-origin assets. If an application must load reviewed cross-origin media whose server does not emit CORP, it can explicitly select credentialless and update the relevant CSP source directive; the browser then omits credentials from those cross-origin no-CORS requests. unsafe-none lowers cross-origin isolation and should be chosen only after an application threat-model review. COEP configuration never makes an arbitrary remote origin trustworthy.

The same baseline adds Cache-Control: no-store to every response that has no Cache-Control header of its own, so pages with personal data are not stored by browsers or shared caches. Responses that should be cached, such as file downloads or calendar and RSS feeds, must set their own header; the standard /static mount already does.

💡 Key Takeaways

• Never hardcode credentials, database passwords, or JWT secrets in .rs source code.
• Add .env to .gitignore and commit .env.example to document required keys for team members.
• Prefer RULLST_ENV; keep APP_ENV only while migrating an existing project.

Tutorial 10: Static Assets & Pre-Compression 📦

The standard Server serves an existing static/ directory at /static. Production builds can create Brotli and Zstandard sidecars for eligible text and Wasm assets in that directory.

Step 1: Use the standard static directory

static/
├── css/
│   └── app.css
├── js/
│   └── app.js
└── favicon.svg

Reference those files through /static/..., for example /static/css/app.css. Server::run mounts the directory when it exists; no additional ServeDir layer is required for this standard path.

use rullst::{routes, routing::get, Server};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![get("/" => || async { "Rullst" })];
    Server::new(app).run(3000).await?;
    Ok(())
}

If you mount a different directory manually through Axum/Tower, its routing and pre-compressed negotiation become application responsibilities.

Step 2: Build production sidecars

cargo rullst build

The release-mode command builds the application and creates .br and .zst siblings for html, css, js, json, svg, wasm, xml, and txt files under static/. The standard server negotiates Brotli through ServeDir and Zstandard through its static middleware.

The server serves an existing sibling without comparing it with its source, so an asset edited after the last build would keep reaching browsers that accept br or zstd in its old form. cargo rullst dev therefore deletes every .br/.zst sibling that is not newer than its source when it starts and before each rebuild, and reports how many it removed. A sibling without a source file is kept, because it may be hand-made. Outside cargo rullst dev, rerun cargo rullst build after editing assets and before docker build copies static/ into an image.

The Zstandard middleware serves name.zst only when Accept-Encoding lists zstd with a quality above zero (zstd;q=0 is a refusal) and the path below /static/ has only plain segments. Paths with ., .., empty segments, backslashes or percent-encoding skip the .zst lookup and go to ServeDir uncompressed. Content-Encoding: zstd is added only to 2xx and 304 responses. A hand-made .zst is used only for a type the middleware can label (the generated types plus .htm, .mjs, .cjs, .map, .webmanifest, .csv, .pdf, .ttf and .otf); for any other file the uncompressed asset is served, never a .zst body typed application/octet-stream.

Verify deployed behavior rather than assuming negotiation worked:

curl --compressed -I -H 'Accept-Encoding: br' \
  http://127.0.0.1:3000/static/css/app.css
curl -I -H 'Accept-Encoding: zstd' \
  http://127.0.0.1:3000/static/css/app.css

Check Content-Encoding, Content-Type, cache headers, and Vary through the actual TLS proxy/CDN. Pre-compression avoids compression work per request; it does not eliminate file I/O or network latency.

Step 3: Cache headers

Since v13 the standard static mount sets Cache-Control itself (Rullst does not rename files; your asset tool does):

no-cache lets browsers and caches store the file but revalidate it before each use. ServeDir sends ETag and Last-Modified and answers a matching If-None-Match or If-Modified-Since with 304 Not Modified and no body. The policy is set on 2xx and 304 responses only, for every encoding (br, zstd or none). A missing file and every dynamic response keep the production security baseline’s Cache-Control: no-store.

An immutable file is never asked for again until it expires, so give an asset a new hashed name whenever its content changes, and do not hand-name a mutable file with a hash-like segment. Check the headers through your proxy or CDN:

curl -sI http://127.0.0.1:3000/static/css/app.css | grep -i -E 'cache-control|etag'
curl -sI -H 'If-None-Match: "<etag from above>"' \
  http://127.0.0.1:3000/static/css/app.css   # HTTP/1.1 304 Not Modified

Downloads and feeds

Dynamic responses keep Cache-Control: no-store unless the route chooses a policy. Since 13.0.0-alpha.2, rullst::cache_control labels the 2xx and 304 responses of a route that do not already have a Cache-Control; errors keep no-store:

#![allow(unused)]
fn main() {
use rullst::{Router, cache_control, routing::get};
use std::time::Duration;

async fn calendar_feed() -> &'static str { "BEGIN:VCALENDAR" }
async fn latest_report() -> &'static str { "report" }
let app = Router::new()
    // The same for every visitor: browsers and CDNs may keep it 5 minutes.
    .route(
        "/calendar.ics",
        get(calendar_feed).layer(cache_control::public(Duration::from_secs(300))),
    )
    // A user's own download: only their browser may keep it for an hour.
    .route(
        "/reports/latest",
        get(latest_report).layer(cache_control::private(Duration::from_secs(3600))),
    );
}

A handler can also return the policy with one response: (CacheControl::private(Duration::from_secs(60)), body). Use public only when the response is the same for every visitor, because a shared cache serves one visitor’s copy to the next. The CSRF middleware never sets its rullst_csrf cookie on a response that shared caches may store (public or s-maxage without private or no-store), so a feed fetched without cookies stays cacheable and never hands out a visitor’s token.

Key takeaways

• Use static/ for the framework’s standard asset path and build integration.
• Keep source files alongside generated sidecars in the deployed artifact.
• Content-hashed names are cached for a year as immutable; other static files are revalidated with ETag/Last-Modified.

Tutorial 11: Authentication Scaffolding 🔒

The authentication generator creates a reviewable starting point for cookie-session login and registration. It is application source code, not a hosted identity service or a claim that every production policy is automatic.

Step 1: Run the generator

The SaaS starter already contains this code: there cargo rullst auth reports that authentication is already scaffolded, writes nothing and exits successfully. In a Blank or API project with a database (SQLite, PostgreSQL, MySQL or MariaDB), such as the shop project of Tutorial 02, run from the project root:

cargo rullst auth

Those starters ship a minimal users table (id, name, created_at and updated_at, from src/migrations/m20260601000000_create_users_table.rs). The command keeps that migration as it is and adds one that extends the table, so it works whether or not cargo rullst db:migrate (or the first cargo rullst dev) already created the table, and rows already in it keep their data. Each existing row gets the placeholder email user-<id>@no-email.invalid (the reserved .invalid domain never receives mail) and no password, so it cannot sign in until you set its real email and the person resets the password.

The current command creates:

• src/models/user.rs and src/models/password_reset.rs;
• src/migrations/m<timestamp>_create_users_table.rs or, in a Blank or API starter, src/migrations/m<timestamp>_add_account_columns_to_users_table.rs (the email, password_hash, oauth_provider, oauth_id, is_admin and session_epoch columns and the unique index on email; rolling it back drops only those), src/migrations/m<timestamp>_create_password_reset_tokens_table.rs and the migrations module;
• src/controllers/auth_controller.rs and src/controllers/password_controller.rs;
• src/middlewares/auth_middleware.rs;
• src/pages/auth.rs;
• the corresponding module declarations, including controllers, middlewares, models and pages in src/lib.rs (or src/main.rs);
• in a Blank or API starter, pub use crate::models::user::User; in place of the starter’s two-field User struct in src/main.rs, so the project has one model of users (a User struct you changed is left alone); and
• a best-effort refresh of the generated .llms.txt, .rullst/context-map.json and diagram.md (a hand-written diagram.md is left unchanged).

It also enables the orm, auth and mail umbrella features in Cargo.toml. When every one of those files already exists, as in the SaaS starter or after an earlier run, it writes nothing and succeeds. It fails before writing anything when only some of them exist, when a *_create_password_reset_tokens_table.rs or *_add_account_columns_to_users_table.rs migration exists, or when a *_create_users.rs/*_create_users_table.rs migration other than the unchanged starter one creates the users table: then add the columns with cargo rullst make:migration and integrate the account files by hand, as the error message says. Turso-primary projects are not supported, and neither is a project without a database migration runner (a --no-database starter): create the project with a database so src/main.rs declares pub mod migrations; and calls rullst::artisan!(crate::migrations::get_migrations()). It does not support an auth --api flag, and it does not silently register application routes. Review the generated diff before editing it.

Step 2: Register the generated handlers

Wire the generated view, submit, logout, and authenticated routes in the application router. The exact route tree is an application decision; a typical mapping is below. Put its use lines at the top of src/main.rs, which already imports routes, and the let statements in router():

use rullst::{routing::post, server::from_fn};
use crate::controllers::auth_controller;
use crate::middlewares::auth_middleware::auth_middleware;

let public_auth = routes![
    get("/login" => auth_controller::login_view),
    get("/register" => auth_controller::register_view),
    post("/logout" => auth_controller::logout),
]
// Each credential submission runs Argon2id: budget it per client.
.route("/login", post(auth_controller::login_submit)
    .layer(from_fn(auth_controller::credential_rate_limit)))
.route("/register", post(auth_controller::register_submit)
    .layer(from_fn(auth_controller::credential_rate_limit)));

let signed_in = routes![
    get("/dashboard" => auth_controller::dashboard),
    // Ends the session on every device.
    post("/logout/everywhere" => auth_controller::logout_everywhere),
]
.layer(from_fn(auth_middleware));

Mount the password flows the same way: the reset routes are public, the change routes need auth_middleware, and every submission is rate limited.

use crate::controllers::password_controller;

let password_reset = routes![
    get("/password/forgot" => password_controller::forgot_password_view),
    get("/password/reset" => password_controller::reset_password_view),
]
// Reset requests send mail and resets run Argon2id.
.route("/password/forgot", post(password_controller::forgot_password_submit)
    .layer(from_fn(auth_controller::credential_rate_limit)))
.route("/password/reset", post(password_controller::reset_password_submit)
    .layer(from_fn(auth_controller::credential_rate_limit)));

let password_change = routes![
    get("/password/change" => password_controller::change_password_view),
]
.route("/password/change", post(password_controller::change_password_submit)
    .layer(from_fn(auth_controller::credential_rate_limit)))
.layer(from_fn(auth_middleware));

Add each group to the starter’s router in router() (src/main.rs) with .merge_axum(public_auth.into_axum()) and so on, before its .layer(rullst::server::from_fn(rullst::security::csrf_middleware)) line so that CSRF protection covers them. The SaaS starter’s router() shows the same routes registered one by one.

credential_rate_limit allows ten submissions per minute for each connecting peer. Behind a reverse proxy, configure [security] trusted_proxies so clients do not share the proxy’s budget.

Reset emails go through the Mail facade: set MAIL_DRIVER and MAIL_FROM for staging and production, and RULLST_PUBLIC_ORIGIN to the application’s HTTPS origin (for example https://app.example.com), which every reset link uses. Links are never built from the request’s Host header. Without RULLST_PUBLIC_ORIGIN, development links point to http://localhost:3000, and staging and production log an error instead of sending a link. In development the default mail driver logs only metadata, so a debug build without MAIL_DRIVER also prints the reset link to the terminal.

The emails name your product APP_NAME (process environment, then .env) or, when it is unset, the APPLICATION_NAME constant at the top of password_controller.rs, which starts as the package name. They are written in the request’s language: the locale LOCALES.layer() negotiated when the application uses rullst::i18n, otherwise the browser’s Accept-Language, matched by language to English, Brazilian Portuguese or Spanish, otherwise DEFAULT_MAIL_LOCALE (English), which you can edit there too.

The generated form pages expect the Core CSRF and CSP-nonce extensions. Apply the canonical security baseline and place authenticated routes behind the generated authentication middleware.

Step 3: Migrate and test

cargo rullst db:migrate
cargo rullst dev

Before production, exercise registration, login, logout, sign-out everywhere, password change and reset, invalid credentials, duplicate email, expired/tampered/revoked cookies and reset links, CSRF failure, rate limiting, mail delivery from your provider, and key rotation. Configure a strong APP_KEY through a secret manager and HTTPS at the edge.

What the scaffold currently enforces

• Passwords are hashed with Argon2id on Tokio’s blocking pool; plaintext is not written to the user model. At most four hashes or verifications run at once (each holds about 19 MiB); a submission that waits two seconds without capacity receives 503. Adjust MAX_CONCURRENT_PASSWORD_WORK to the host.
• Registration accepts passwords of at least 12 characters and at most 72 bytes, and normalizes email.
• Login performs a dummy password verification for unknown users to reduce the obvious account-enumeration timing difference.
• Session values use authenticated encryption and are emitted as cookie headers through rullst-auth helpers.
• The users.session_epoch column (0 for a new account) goes into every login cookie, and auth_middleware refuses a cookie whose epoch differs. User::revoke_sessions increments it in one UPDATE, ending every cookie of the account; the Sign out everywhere button (logout_everywhere) calls it. Plain logout clears only the current browser’s cookie. Call User::revoke_sessions when you deactivate an account. See encrypted sessions.
• Change password (/password/change, signed in) asks for the current password, the new one and a confirmation. A wrong current password gets the generic “The current password is incorrect”. The new password follows the registration policy. User::change_password stores the new hash and increments the session epoch in one UPDATE that only applies while the account is still at the epoch of the asking cookie; that browser receives a cookie with the new epoch and every other device is signed out. A reset link requested before the change stops working.
• Forgot password (/password/forgot) answers with the same page, after at least 400 ms, whether or not the email has an account. For an account it creates a PasswordResetToken (32 random bytes from the operating system), stores only its SHA-256 digest in password_reset_tokens with a 30-minute expiry, and emails the link in the background. The table keeps one token per account: a new request replaces the previous token, but requests for the same account less than 60 seconds apart send nothing.
• Reset link lifetime: RESET_TOKEN_LIFETIME_MINUTES in src/models/password_reset.rs (30 as generated) sets it. Change it there: a compile-time assertion keeps it from 10 minutes to 24 hours (1440), and the stored expiry, the email (“This link expires in 30 minutes.”, or “2 hours” for whole hours) and the forgot-password answer all follow it. Below 10 minutes, mail that a provider greylists or queues for a few minutes arrives after its link expired, and the user can only ask again. Above 24 hours, the link stays a working way into the account for as long as it sits in a mailbox that is synchronized to several devices, forwarded or read by someone else, while a day already covers a user who reads mail once a day. Single use and replacement by a newer request narrow that exposure but do not remove it, which is why the OWASP Forgot Password Cheat Sheet asks for short-lived tokens.
• Reset password (/password/reset?token=…) shows the form only for a live token, without caching and with Referrer-Policy: no-referrer. Submitting it deletes the token, stores the new hash and increments the session epoch in one transaction, so the link works once and every device is signed out. The user is not signed in: the page redirects to /login?reset=done. Both flows email a “password changed” notice.

These controls do not replace application review. Add account verification, abuse controls, audit policy, MFA/passkeys, per-device session management, and privacy/retention behavior according to the product’s threat model. A reset link proves only access to the mailbox; for high-value accounts, add a second factor to recovery.

Tutorial 12: JWT and Cookie Sessions 🔑

Cookie sessions and bearer JWTs are transport choices with different operational trade-offs. Neither is automatically “for web” or “for mobile,” and neither removes the need for TLS, authorization, rotation, expiry, and revocation design.

Step 1: Generate JWT middleware

cargo rullst make:jwt

This creates src/middlewares/jwt_middleware.rs, registers its module, and adds the direct jsonwebtoken, chrono, and serde dependencies when missing.

Configure a high-entropy secret plus exact issuer and audience values:

export JWT_SECRET="$(openssl rand -base64 48)"
export JWT_ISSUER="https://identity.example.test"
export JWT_AUDIENCE="rullst-api"

The generated HS256 validator requires sub, iss, aud, iat, and exp, checks expiry, and rejects secrets shorter than 32 bytes, with fewer than 12 distinct characters, or starting with mock_. It reads these variables with std::env::var on each request, so they must be set in the process environment: a value only in .env is not seen, and while one is missing a request that carries a bearer token receives 500. Keep the secret out of source control and logs.

The same file provides generate_token(user_id), which issues a token with these settings that expires after 24 hours. Call it after your own credential check, never for an unauthenticated caller.

Step 2: Protect a route group

use rullst::{Router, routing::get};
use rullst::web::axum::middleware;
use crate::middlewares::jwt_middleware::jwt_middleware;

pub fn protected_routes() -> Router {
    Router::new()
        .route("/profile", get(user_profile))
        .route("/orders", get(user_orders))
        .layer(middleware::from_fn(jwt_middleware))
}

Valid claims are inserted into request extensions. The handler must still map sub to a current account and enforce resource/tenant authorization. For long-lived systems, design key rotation and immediate revocation rather than assuming expiry alone is sufficient.

Choosing deliberately

• An HttpOnly, Secure, appropriately SameSite cookie reduces direct token reads by browser JavaScript. It does not neutralize XSS: injected code can still act as the user, and cookie requests need CSRF protection.
• A bearer token is convenient for interoperable API clients, but storage in a browser or native app is an application security decision. A stolen bearer token can be replayed until rejected or expired.
• Cookie and JWT strategies can coexist at different boundaries, but keep one authoritative identity/session lifecycle and test logout/revocation behavior.

Tutorial 13: RBAC, Ownership, and IDOR/BOLA Protection 🛡️

rullst-security provides role, owner, and tenant checks over a trusted UserContext. The framework cannot infer ownership from a route parameter: the application must load the resource and pass its stored owner/tenant identifiers to the guard.

Step 1: Authorize a trusted user context

#![allow(unused)]
fn main() {
use rullst_security::{RbacGuard, SecurityError, UserContext};

pub fn authorize_admin(user: &UserContext) -> Result<(), SecurityError> {
    RbacGuard::authorize(user, "admin")
}
}

Construct UserContext only after authentication. Roles, permissions, and tenant membership must come from trusted server-side state, not request headers or JSON supplied by the caller. In a project with the cargo rullst auth scaffold, auth_middleware inserts the signed-in account id as Extension<i32>; build the context with UserContext::new(user_id.to_string(), roles) from roles your application stores. Generated projects already depend on rullst-security.

Step 2: Check the resource record, not request ownership

#![allow(unused)]
fn main() {
use rullst_security::{RbacGuard, SecurityError, UserContext};

pub struct DocumentAccess {
    pub owner_user_id: String,
    pub tenant_id: String,
}

pub fn authorize_document_update(
    user: &UserContext,
    stored: &DocumentAccess,
) -> Result<(), SecurityError> {
    RbacGuard::authorize_tenant_owner_or_role(
        user,
        &stored.tenant_id,
        &stored.owner_user_id,
        "document-editor",
    )
}
}

Load DocumentAccess with a parameterized query by the route’s document ID. Do not accept owner_user_id or tenant_id from the update payload. The tenant guard is evaluated first and roles — including admin — do not bypass a tenant mismatch.

For particularly sensitive paths, make the database query itself tenant-scoped and then apply the guard as a second boundary. Return the same not-found/forbidden shape where revealing resource existence would leak information.

Key takeaways

• authorize checks a role (and recognizes the framework’s admin role).
• authorize_owner_or_role is safe only when the owner ID came from trusted resource state.
• Use authorize_tenant_owner_or_role for tenant-bound resources.
• A helper contributes to IDOR/BOLA prevention only when every parameterized resource route invokes it or an equivalent scoped repository policy.

Tutorial 14: RASP — Runtime Application Self-Protection ⚡

rullst-security::rasp applies bounded heuristic signatures to request targets, non-secret headers, and supported textual bodies. Its current signatures cover common SQL injection, path traversal, SSRF, shell/RCE, and JNDI indicators. It does not claim general exploit detection. The powershell keyword is not matched against the stock PowerShell product token in User-Agent (PowerShell/7.4.1, WindowsPowerShell/5.1…), so Invoke-WebRequest and Invoke-RestMethod clients are served, while execution syntax such as powershell -enc or powershell.exe in that header still blocks.

🛠️ Step 1: Mount RaspSecurityLayer in main.rs

use rullst::web::axum::Router;
use rullst_security::rasp::RaspSecurityLayer;
use rullst::Server;

#[tokio::main]
async fn main() -> Result<(), rullst::ServerError> {
    let app = Router::new()
        // ... routes
        .layer(RaspSecurityLayer::default());

    Server::new(app.into()).run(3000).await
}

🧪 Step 2: Test Malicious Attack Payload Interception

Send a percent-encoded UNION SELECT payload in the query string:

curl -i "http://localhost:3000/api/users?query=1%27%20UNION%20SELECT%20password%20FROM%20users"

For a recognized bounded signature, the layer returns 403 Forbidden and adds a process-local event to SecurityStore. A Studio instance running in the same process can display that event at http://127.0.0.1:5555/studio/security.

The body inspector accepts identity-encoded UTF-8 text, JSON, form, and XML media types up to 1 MiB. It fails closed for oversized declared bodies and encoded textual bodies that it cannot inspect. Put an independent request-body limit outside this layer as well.

🚧 What RASP does not inspect

• Cookie and Authorization headers, multipart/form-data uploads and binary bodies.
• Payloads hidden by double percent-encoding, HTML entities, SQL comments between keywords, alternative syntax or splitting across several fields.
• Anything without a listed signature.

It also refuses ordinary text that contains a signature, such as a forum post that quotes ../ or /bin/sh. Test your own forms and API payloads with the layer mounted.

In staging and production, Server already runs the Core WAF, which overlaps with RASP and buffers the same body. See which security layer to use, and when before adding both.

💡 Key Takeaways

• Inspection has runtime cost and uses bounded pattern heuristics, with possible false positives and false negatives.
• RASP is defense in depth; parameterized SQL, validation, authorization, body limits, and dependency review remain required.

Tutorial 15: Vault and ORM field encryption

Rullst can encrypt String and Option<String> model fields before they reach the database and decrypt them when a generated ORM query loads the model. The implementation uses AES-256-GCM with a fresh random nonce and an authenticated, versioned envelope.

1. Configure a current key

Generate 32 random bytes and store them as a prefixed base64 value. Do not commit this value to source control:

export RULLST_ENCRYPTION_KEY="base64:$(openssl rand -base64 32)"
export RULLST_ENCRYPTION_KEY_ID="production-2026-01"

RULLST_ENCRYPTION_KEY accepts base64:<value>, hex:<value>, or a legacy raw value containing exactly 32 UTF-8 bytes. A secret manager or KMS-backed deployment adapter should inject it at runtime. Rullst does not provide key custody.

RULLST_ENCRYPTION_KEY, RULLST_ENCRYPTION_KEY_ID and RULLST_ENCRYPTION_KEYRING are each read from the process environment first and, when the process does not set them, from .env in the current working directory, the precedence APP_KEY and rullst::config::project_setting use. The file is read on each lookup and never loaded into the process environment. In development a line such as RULLST_ENCRYPTION_KEY=base64:... in the project’s .env is therefore enough; keep .env out of version control and inject the key through the environment in production.

2. Mark model fields

#![allow(unused)]
fn main() {

#[derive(Clone, Debug, rullst_orm::Orm)]
#[orm(table = "users")]
pub struct User {
    pub id: i32,
    pub email: String,
    #[orm(encrypted)]
    pub tax_id: String,
    #[orm(encrypted)]
    pub recovery_note: Option<String>,
}
}

Generated save, update_partial, find, all, query-builder loads and streams preserve plaintext in the Rust model while storing an envelope shaped like this in the SQL column:

RULLST:v2:<key_id>:<base64url_nonce>:<base64url_ciphertext_and_tag>

The table and column names are authenticated as additional data. Copying a ciphertext into a different annotated column therefore fails decryption.

Generated secondary copies do not undo that protection. to_json(), audit rows and committed-event payloads (including Redis orm:events:* messages) carry the fixed marker "***" instead of the value, and Scout documents omit the field. save_to_redis writes the same authenticated envelope as the SQL column and get_from_redis decrypts it, while the .remember(...) query cache stores the ciphertext read from the database. Audit rows, indexes and Redis hashes written before this behavior may contain plaintext: purge, reindex or rewrite them.

SecretString fields

rullst_orm::SecretString is an alternative for a field that should be encrypted by its SQLx codec and redacted from Debug. Its serde form is never plaintext: Serialize writes a RULLST:v2 envelope under the current key (and fails without one), and Deserialize decrypts such an envelope with the current key or keyring while still accepting an ordinary string as input. Generated audit, event and search projections write "***" instead, and the .remember(...) query cache stores the envelope. A #[derive(Serialize)] on the model therefore produces ciphertext for this field; call reveal_audited() where the plaintext is deliberately required.

3. Rotate a key without downtime

Set the new current key and keep old readable keys in a JSON keyring:

export RULLST_ENCRYPTION_KEY="base64:<new-32-byte-key>"
export RULLST_ENCRYPTION_KEY_ID="production-2027-01"
export RULLST_ENCRYPTION_KEYRING='{
  "production-2026-01": "base64:<old-32-byte-key>"
}'

Reads select the key named by the envelope. A normal full save() rewrites all annotated values with the current key. Keep every key needed by existing rows until a separately monitored migration has rewritten and verified them; then remove the retired key.

4. Understand query limits

AES-GCM encryption is randomized, so the same plaintext produces different ciphertexts. Generated queries reject encrypted fields in WHERE, ORDER BY, GROUP BY, and explicit SELECT clauses rather than silently returning wrong results. pluck_string supports non-null encrypted strings; load the model for nullable encrypted strings.

For lookup, add a separate application-designed blind-index column and assess its equality-leakage and key-rotation trade-offs. Rullst does not generate a blind index automatically. Raw SQL is an explicit escape hatch and does not automatically encrypt bindings or decrypt arbitrary projections.

5. Reduce secret lifetime in memory

VaultSecret<T> redacts Debug/Display and calls Zeroize on the wrapped value when dropped:

#![allow(unused)]
fn main() {
use rullst_security::VaultSecret;

fn use_api_key() {
    let Ok(value) = std::env::var("EXAMPLE_PROVIDER_KEY") else {
        return;
    };
    let api_key = VaultSecret::new(value);
    send_request(api_key.expose_secret());
}

fn send_request(_: &str) {}
}

Zeroization is defense in depth, not secure memory. It cannot erase prior copies or prevent a debugger, core dump, swap, allocator behavior, or another process-memory capture while the secret is live.

Operational checklist

• Back up the database and keyring together, with separate access controls.
• Test restore and rotation before retiring any key.
• Restrict environment and crash-dump access.
• Never log plaintext model fields or expose them through serialization by accident. Generated to_json() already replaces encrypted fields with "***"; add #[orm(hidden)] when a field must be omitted entirely. A #[derive(Serialize)] on the model is your own serializer and still emits the decrypted value.
• Treat authentication failure as possible corruption, wrong context, wrong key, or tampering; do not replace it with an empty value.

Tutorial 16: LiveView Server-Driven UI (rullst::live) ⚡

Build a per-connection Rust component that receives JSON events and sends rendered HTML over WebSockets. The browser still needs the HTMX WebSocket extension (or a compatible client transport).

This tutorial documents the legacy per-connection API. For the v13 prerelease candidate with explicit authorization, revision conflicts, bounded reconnection and recovery after process restart, use Recoverable Live UI. Its browser module and application trait are separate; make:live does not automatically supply that contract.

🛠️ Step 1: Scaffold a LiveComponent

cargo rullst make:live CounterComponent

This creates src/live/counter_component.rs and declares it in src/live/mod.rs. Declare mod live; in the crate root yourself; the command does not edit src/main.rs or src/lib.rs.

💻 Step 2: Implement the Component Lifecycle

Edit the generated src/live/counter_component.rs, for example:

#![allow(unused)]
fn main() {
use rullst::async_trait;
use rullst::live::LiveComponent;
use serde_json::Value;

#[derive(Default)]
pub struct CounterComponent {
    pub count: i32,
}

#[async_trait]
impl LiveComponent for CounterComponent {
    async fn mount(&mut self) {
        self.count = 10;
    }

    async fn handle_event(&mut self, payload: Value) {
        if let Some(action) = payload.get("action").and_then(|v| v.as_str()) {
            match action {
                "increment" => self.count += 1,
                "decrement" => self.count -= 1,
                _ => {}
            }
        }
    }

    fn render(&self) -> String {
        format!(
            r#"<div id="counter-component" class="p-6 bg-slate-800 text-white rounded-xl">
    <h2 class="text-xl font-bold">Counter: {}</h2>
    <button ws-send name="action" value="increment" class="px-4 py-2 bg-emerald-600 rounded">+1</button>
</div>"#,
            self.count
        )
    }
}
}

💻 Step 3: Mount Component in a Controller

This route fragment belongs in the same application module where CounterComponent is in scope:

use rullst::html::Markup;
use rullst::live::Live;
use crate::live::counter_component::CounterComponent;

// `Live::mount` returns `Markup`: return it as the page, or interpolate it
// into an `html!` layout as `{component}`.
pub async fn page_handler() -> Markup {
    Live::mount::<CounterComponent>("/ws/counter").await
}

Register the page and the matching WebSocket route, for example in the routes![...] list of router():

use rullst::live::live_ws_handler;

let app = rullst::routes![
    get("/counter" => page_handler),
    get("/ws/counter" => live_ws_handler::<CounterComponent>),
];

The page must also load HTMX and its WebSocket extension (see the takeaways). The command’s own hint uses /ws/counter_component; any path works as long as Live::mount and the route name the same one.

💡 Key Takeaways

• Event payloads travel over WebSocket connections; render() produces updated HTML fragments.
• The current component state lives in one socket task. Authentication, authorization, reconnect/replay, backpressure and multi-process state remain application concerns.
• live_ws_handler accepts WebSocket frames and messages of at most 64 KiB; a larger message closes the session before it is parsed. Origin checks, connection caps and idle timeouts are still route-level policy.
• Include and pin the HTMX WebSocket extension; Rullst does not inject that browser dependency automatically.

Tutorial 17: In-process realtime and presence

Rullst Core provides bounded in-process broadcast channels and presence state. These primitives do not create an HTTP WebSocket endpoint by themselves and do not synchronize independent server processes.

Subscribe before publishing

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

use rullst::realtime::{BroadcastManager, RealtimeError, RealtimeMessage};

async fn local_exchange() -> Result<RealtimeMessage, RealtimeError> {
    let manager = Arc::new(BroadcastManager::new());
    let mut receiver = manager.get_or_create("room:general").subscribe();

    manager.publish(
        "room:general",
        "message.created",
        r#"{"sender":"alice","content":"hello"}"#,
    )?;

    receiver
        .recv()
        .await
        .map_err(|error| RealtimeError::BroadcastError(error.to_string()))
}
}

Channel uses tokio::sync::broadcast: a slow receiver can lag, and publishing without any receiver returns RealtimeError::BroadcastError.

The registry keeps a channel only while it has a subscriber or a caller holds the Arc<Channel> from get_or_create. Publishing never creates a channel, and idle channels are released by a publish that finds no receivers or by an amortized sweep when new channels are created; a released name gets a new channel on its next get_or_create. PresenceTracker counts connections: call user_left once for every user_joined (for example when each socket closes), so a user with two open tabs stays online until both close. It removes a room when its last user leaves.

Bind channels and presence to an authenticated tenant

Construct TenantContext only from trusted authentication/membership state. The wrappers validate logical names and ensure that identical room names use different backend namespaces:

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

use rullst::realtime::{
    BroadcastManager, PresenceTracker, TenantPresence, TenantRealtime,
};
use rullst::security::TenantContext;

fn publish_for_school() -> Result<(), Box<dyn std::error::Error>> {
    let context = TenantContext::try_new("school-alpha")?;
    let realtime = TenantRealtime::from_context(
        Arc::new(BroadcastManager::new()),
        &context,
    );
    let presence = TenantPresence::from_context(
        Arc::new(PresenceTracker::new()),
        &context,
    );

    let mut receiver = realtime.subscribe("course/42")?;
    presence.user_joined("course/42", "learner-7")?;
    realtime.publish("course/42", "lesson.completed", r#"{"lesson_id":9}"#)?;

    assert_eq!(presence.count_online("course/42")?, 1);
    assert!(receiver.try_recv().is_ok());
    Ok(())
}
}

The tenant wrapper limits names and payloads (64 KiB), but the application still owns authentication, room-level authorization, connection lifecycle and replay. Use rullst::live::live_ws_handler for the separate per-connection LiveComponent flow (Tutorial 16), or build an Axum WebSocket handler around these primitives. A distributed transport is still roadmap work.

Tutorial 18: Wasm Island foundation

Rullst can generate a dual-target Island function: native builds emit a host element with serialized props, while wasm32-unknown-unknown builds export a hydration function.

Generate the component

cargo rullst make:island InteractiveChart

The generated src/islands/interactive_chart.rs uses the supported macro:

#![allow(unused)]
fn main() {
use rullst::island;

#[cfg(target_arch = "wasm32")]
use wasm_bindgen::{closure::Closure, JsCast};

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InteractiveChartProps {
    pub initial_value: i32,
}

#[island]
pub fn interactive_chart(props: InteractiveChartProps) {
    #[cfg(not(target_arch = "wasm32"))]
    {
        format!(
            "<button type=\"button\" data-counter=\"{}\">Count: {}</button>",
            props.initial_value, props.initial_value
        )
    }

    #[cfg(target_arch = "wasm32")]
    {
        let mut value = props.initial_value;
        element.set_text_content(Some(&format!("Count: {value}")));

        let button = element.clone();
        let closure = Closure::<dyn FnMut()>::new(move || {
            value = value.saturating_add(1);
            button.set_text_content(Some(&format!("Count: {value}")));
        });

        if element
            .add_event_listener_with_callback("click", closure.as_ref().unchecked_ref())
            .is_ok()
        {
            closure.forget();
        }

        String::new()
    }
}
}

The element binding in the Wasm block is supplied by #[island]. The command also declares the module in src/islands/mod.rs, adds pub mod islands; to src/lib.rs (creating that file when it is absent), and adds any missing serde, serde_json, wasm-bindgen and web-sys dependencies.

On the server the island function returns rullst::html::Markup: the component’s HTML wrapped in its data-island element. Place it in a page by interpolating the call inside html!, as {interactive_chart(props)}; it is inserted as HTML, not escaped. The module belongs to the library target (src/lib.rs), so the starters’ src/main.rs imports it through the package name, with - written as _: use <package_name>::islands::interactive_chart::{interactive_chart, InteractiveChartProps};.

Build and load the artifact

cargo rullst build:client

The command parses Cargo.toml, adds cdylib to the [lib] crate-type array when needed (writing ["cdylib", "rlib"] when the key is absent), installs/checks the Wasm target and wasm-bindgen-cli, builds the library, locates the artifact using lib.name or package.name, writes bindings under static/, and generates the static/rullst-islands.js hydration orchestrator. Review these manifest, network, and toolchain side effects in CI and pin the required tools for reproducible releases. Load the orchestrator from the page with <script type="module" src="/static/rullst-islands.js"></script>, as the command output shows.

This is a useful foundation, not a complete frontend framework: routing, application state, accessibility, CSP-compatible asset delivery, cache busting, error reporting and browser E2E remain application/release work.

Tutorial 19: SaaS billing with Rullst Capital 💳

This tutorial creates a checkout adapter boundary and explains how to feed the optional local Studio view without treating it as an accounting system.

1. Scaffold and configure the selected adapter

cargo rullst make:billing --model Workspace

The command detects a relational SQLx or Turso-primary project, adds the exact orm and capital facade features once, generates a reversible matching migration, registers the models/controller/page modules, and refuses to overwrite an earlier billing scaffold. The generated runtime supports the Stripe live integration or explicit offline fixtures; BILLING_PROVIDER accepts only stripe. To bill through another gateway, implement the Capital provider traits in the application as described in Writing your own payment provider. v13 removed the other built-in adapters; see the v13 migration guide.

The generated Stripe flow persists an opaque local owner, account/test-live scope, immutable customer and checkout intents, session IDs, and event receipts. Signed Checkout/subscription notifications reconcile current provider state. Database revision fencing prevents delayed reads from replacing newer state, and event completion shares the subscription transaction.

Configure BILLING_PROVIDER=stripe, BILLING_ACCOUNT_ID, BILLING_API_KEY, BILLING_WEBHOOK_SECRET, an HTTPS BILLING_REDIRECT_URL, and the explicit BILLING_ALLOWED_PLAN_IDS recurring-price allowlist in the process environment or the project’s .env (in v13 the generated code reads the process environment first, then .env, through rullst::config::project_setting). Follow the generated BILLING.md for webhook event selection, pinned API version, CSP, recovery and migration details. Keep credentials outside source control. Test and live keys use separate persisted namespaces; mixed real/mock credentials fail closed. Live keys also require BILLING_LIVE_ACKNOWLEDGEMENT=I_UNDERSTAND_REAL_CHARGES; without it the generated live path stays unavailable.

Existing controllers are application-owned: merge the generated modules and add the billing-state/event tables through a new migration. Updating a dependency does not rewrite existing controllers or safely backfill legacy customer ownership.

2. Create a checkout session

Mount the generated authenticated checkout POST behind session/tenant ownership and CSRF verification. The form supplies only an allowlisted plan. The generated handler persists the intent before dispatch and the session ID before its HTTP 303 redirect. Repeated requests retrieve and reuse an open session. Older unknown outcomes use read-only recovery rather than new keys after provider retention.

When calling the low-level adapter directly, persist and authorize the same customer/attempt boundary explicitly:

#![allow(unused)]
fn main() {
use rullst_capital::{CapitalError, StripeCheckoutRequest, StripeProvider};

async fn checkout_url(
    stripe: &StripeProvider,
    persisted_attempt: &StripeCheckoutRequest,
) -> Result<String, CapitalError> {
    let session = stripe.create_subscription_checkout(persisted_attempt).await?;
    // Persist session.id() and its digest before returning the URL to the browser.
    Ok(session.url().to_owned())
}
}

Email is optional contact data, never the webhook owner key. The ID-bound portal uses the same persisted customer. The application supplies authentication and membership, configured products/prices, retention, entitlement/settlement policy, and actual provider-account sandbox acceptance. Navigation and session creation never grant paid access.

2.1 Handle provider failure without blindly repeating a charge

Built-in live adapters return a redacted CapitalError::Provider for outbound request construction, transport, HTTP status, bounded-response, JSON, and response-contract failures. Inspect its stable class for telemetry or a durable job decision:

#![allow(unused)]
fn main() {
use rullst_capital::{CapitalError, ProviderFailureClass};

fn provider_disposition(error: &CapitalError) -> Option<ProviderFailureClass> {
    match error {
        CapitalError::Provider(failure) => Some(failure.class()),
        _ => None,
    }
}
}

Do not turn Transient or RateLimited into an unconditional loop. Persist the original command and idempotency identity, confirm that the selected operation actually forwards that identity, cap attempts with backoff/jitter, and reconcile signed provider events. Checkout creation in the legacy unified trait does not accept an application idempotency key, so reconcile before repeating it. The shared client already applies finite timeouts, disables redirects and ambient proxies, caps JSON to one MiB, and validates returned checkout URLs as absolute credential-free HTTPS.

3. Make a bounded immediate charge when checkout is not the right flow

For a payment method already tokenized and authorized for off-session reuse at Stripe, the model deriving Billable can perform one fully specified charge:

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, StripeProvider};

async fn charge_saved_method(
    account: &(impl rullst_capital::Billable + Sync),
    stripe: &StripeProvider,
) -> Result<String, CapitalError> {
    let receipt = account
        .charge_with(
            stripe,
            2_500,
            "BRL",
            "cus_from_authoritative_state",
            "pm_from_authoritative_state",
            "order_2026_0001-attempt_1",
        )
        .await?;
    Ok(receipt.charge_id().to_string())
}
}

This deliberately is not charge(amount): currency, provider customer, tokenized payment method and retry identity cannot be inferred safely. The Stripe adapter uses Payment Intents with immediate off-session confirmation and the provider idempotency header. Only succeeded and processing are accepted; an amount/currency mismatch or a flow requiring customer action fails closed. Credentials beginning with mock_ return the same deterministic receipt with the distinct non-success ChargeStatus::Mock for an exact retry. The mock is not a mandate, durable idempotency store or live sandbox test. Other adapters return UnsupportedOperation until reviewed individually.

4. Render and deliver the invoice only after final success

Enable capital-mail on the umbrella crate (or invoice-pdf on Capital plus capital-invoice on Mail). Build the invoice from authoritative order state, then bind it to the returned receipt:

#![allow(unused)]
fn main() {
use chrono::Utc;
use rullst::capital::{ChargeReceipt, Invoice, InvoiceItem};
use rullst::mail::PaidInvoiceDelivery;

async fn deliver_invoice(receipt: &ChargeReceipt) -> Result<(), Box<dyn std::error::Error>> {
    let invoice = Invoice {
        invoice_id: "INV-2026-0001".to_string(),
        customer_email: "[email protected]".to_string(),
        date: Utc::now(),
        items: vec![InvoiceItem {
            description: "Pro subscription".to_string(),
            amount: 25.00,
        }],
        total: 25.00,
        currency: "BRL".to_string(),
    };

    let paid = invoice.bind_succeeded_charge(receipt)?;
    // Real providers require a sender on a domain verified for the account.
    let delivery = PaidInvoiceDelivery::prepare(&paid)?.from("[email protected]")?;

    // In production, atomically claim this stable key in a durable outbox.
    let _delivery_key = delivery.delivery_key();
    delivery.send().await?;
    Ok(())
}
}

The binding rejects Processing, Mock, a mismatched recipient, amount or currency. The default PDF is paginated, bounded to sixteen MiB and supports WinAnsi text (including common Portuguese characters); pass a checked TTF/OTF to Capital for other scripts. Mail applies its mandatory pre-flight before the facade queues or sends the HTML message and attachment; from re-runs it for the verified sender, which every real transport requires: none invents one.

This helper does not subscribe to webhooks by itself. Reconcile the provider event, build the authoritative invoice and insert delivery_key under a unique database constraint in the same application workflow. Mail delivery remains at least once: a crash and retry can still require provider/application deduplication.

5. Report metered usage without confusing provider identities

Use the provider-specific static trait for new code. Stripe Meter Events need a customer ID and configured event name, not a subscription-item ID:

#![allow(unused)]
fn main() {
use rullst_capital::{
    CapitalError, MeteredBillingProvider as _, StripeMeterEvent, StripeProvider,
};

async fn report_ai_exercises(stripe: &StripeProvider) -> Result<(), CapitalError> {
    let event = StripeMeterEvent::new(
        "cus_from_authoritative_state",
        "ai_exercises",
        3,
        "usage:school-7:attempt-99",
    )?;
    let receipt = stripe.report_metered_usage(&event).await?;
    assert_eq!(receipt.quantity(), 3);
    Ok(())
}
}

Stripe receives the identifier but enforces it only within a rolling window, so keep a durable application record of submitted events. A custom adapter whose provider receives no event key reports UsageDeduplication::ApplicationOutboxRequired; durable application deduplication is then mandatory. The adapter caps and binds responses, while provider sandbox/live acceptance, retry, invoice reconciliation and entitlement updates remain release and application work. Empty or mock_* API keys produce a deterministic UsageStatus::Mock, never billable evidence.

6. Verify webhooks before business processing

Mount rullst_capital::verify_webhook on the exact provider callback route as shown in the Capital crate guide. Apply any CSRF exemption only to that exact signed route. Never update access or subscription state from an unverified request.

The default replay store protects one process. For multiple processes, rullst-capital/webhook-sql provides a bounded SQL ledger for SQLite, PostgreSQL, MySQL, and MariaDB. Its middleware form claims the signed payload before dispatch and therefore does not guarantee exactly-once processing after a crash. When a subscription mutation must be atomic, use the provider’s verified stable event ID with SqlWebhookReplayStore::check_and_record_event_key_with_transaction in the same database transaction as that mutation; do not also pre-claim that event through SQL middleware. See the payment guide for setup and operational boundaries.

7. Use a bounded subscription handle and grace period

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, GracePeriod, StripeProvider};

async fn pause_with_local_policy(
    workspace: &impl rullst_capital::Billable,
    provider: &StripeProvider,
) -> Result<(), CapitalError> {
    let grace = GracePeriod::new(1_900_000_000, 1_900_604_800)?;
    let handle = workspace
        .subscription_with(provider)?
        .with_grace_period(grace);
    handle.pause().await
}
}

The grace value does not schedule the pause or grant access by itself. Persist it with authoritative subscription state, evaluate it against a trusted clock inside the entitlement check, and confirm the selected adapter’s live pause or cancel semantics.

The same statically dispatched handle validates coupon IDs and gives the historical relative-trial API its intended meaning:

#![allow(unused)]
fn main() {
use rullst_capital::{Billable as _, CapitalError, StripeProvider};

async fn grant_a_retention_offer(
    workspace: &impl rullst_capital::Billable,
    stripe: &StripeProvider,
    command_created_at: i64,
) -> Result<(), CapitalError> {
    let subscription = workspace.subscription_with(stripe)?;
    subscription.apply_coupon("RETENTION_25").await?;

    // Fifteen whole days. Persist command_created_at and reuse it on retries.
    subscription
        .extend_trial_days_at(15, command_created_at)
        .await
}
}

extend_trial(15) uses the current UTC time for interactive convenience. Workers should persist their command time and use extend_trial_days_at so a retry sends the identical expiration; set_trial_end is the explicit absolute timestamp operation. Stripe has the reviewed live coupon path and reviewed trial-update protocol fixtures; adapters without those contracts fail explicitly. Authorize the subscription owner before building the handle, serialize conflicting updates, and reconcile the signed provider webhook because trial changes can affect billing anchors and charges.

8. Enforce one shared workspace quota before creation

Enable quota-sql directly, or capital-quota-sql on the umbrella crate. The authenticated middleware must first establish the active TenantContext; do not build a billing subject from an arbitrary header or request field.

Billable::quota_request reads the limit from the subscription owner’s tier_limit implementation. A limit of Some(0) (a plan that grants none of the feature) returns QuotaError::LimitExceeded, the same denial as a used-up limit. Give every attempted creation a stable event key, normally the ID of the application command/request rather than a random value generated on every retry.

#![allow(unused)]
fn main() {
use rullst::{
    capital::{Billable as _, BillingSubject, QuotaError, SqlQuotaStore},
    security::TenantContext,
};

async fn create_project(
    workspace: &impl rullst::capital::Billable,
    tenant: &TenantContext,
    quotas: &SqlQuotaStore,
    project_id: &str,
) -> Result<bool, Box<dyn std::error::Error>> {
    let subject = BillingSubject::from_tenant(tenant)?;
    let request = workspace.quota_request(
        subject,
        "projects",
        format!("create-project:{project_id}"),
        1,
    )?;

    let mut transaction = quotas.pool().begin().await?;
    let grant = match quotas
        .reserve_with_transaction(&mut transaction, &request)
        .await
    {
        Ok(grant) => grant,
        Err(QuotaError::LimitExceeded { .. }) => {
            transaction.rollback().await?;
            return Ok(false);
        }
        Err(error) => {
            transaction.rollback().await?;
            return Err(error.into());
        }
    };

    if grant.is_replay() {
        transaction.rollback().await?;
        return Ok(true);
    }

    let inserted = rullst::orm::sqlx::query(
        "INSERT INTO projects (id, workspace_id) VALUES (?, ?)",
    )
    .bind(project_id)
    .bind(tenant.tenant_id.as_str())
    .execute(&mut *transaction)
    .await;
    if let Err(error) = inserted {
        transaction.rollback().await?;
        return Err(error.into());
    }
    transaction.commit().await?;
    Ok(true)
}
}

The placeholder above is SQLite/MySQL syntax; use $1, $2 for a raw PostgreSQL insert, or use the ORM operation that participates in the same transaction. SqlQuotaStore uses a unique event claim plus a conditional counter update, so concurrent members cannot both pass the last available unit. An exact retry returns is_replay() without consuming again; reusing the same key with different units or a different limit fails closed.

For work that cannot share the SQL transaction, QuotaGate::execute still blocks the callback before an over-limit/replayed operation and releases the reservation after an ordinary callback error. A process crash between a standalone reservation and the external side effect is intentionally conservative and needs application reconciliation; the framework never risks exceeding the quota to guess whether that external effect happened.

9. Supply an optional local revenue snapshot

RevenueDashboardManager does not derive money or subscribers from event names. After durable reconciliation, the application may call update_metrics with its authoritative snapshot and record_event with a bounded inspection record. The standalone Studio can display that process-local source at /studio/capital when it is explicitly connected. It neither auto-discovers webhook routes nor auto-syncs the application database.

Provider-hosted checkout normally keeps card collection away from the application, but the final data boundary depends on the selected provider flow, application logs, analytics, and deployment.

Tutorial 20: Background Jobs & Task Queues ⚙️

Rullst Core provides named JSON jobs, SQLite and Redis storage drivers, and a bounded-concurrency worker. Job handlers are closures registered against a stable name; there is no Job trait or process-global Queue::dispatch API.

Step 1: Scaffold a handler module

cargo rullst make:worker EmailWorker

This creates src/workers/email_worker.rs, registers it in src/workers/mod.rs (declared in src/main.rs), and provides start_workers(worker), which registers every generated handler and starts the worker. Replace the generated log-only body with the application operation. Avoid logging the complete job payload, because it can contain personal or secret data.

Step 2: Create a queue and keep its worker handle alive

Queue::sqlite needs the queue-sqlite feature of rullst, which the starters do not enable: add "queue-sqlite" to the features list of the rullst dependency in Cargo.toml. The example below registers its handler by hand; with the generated module, pass the Worker to workers::start_workers instead.

#![allow(unused)]
fn main() {
use rullst::queue::{Queue, QueueError, Worker, WorkerHandle};
use serde_json::json;

fn start_email_worker(queue: &Queue) -> Result<WorkerHandle, QueueError> {
    let mut worker = Worker::new(queue)
        .max_concurrency(8)
        .poll_interval(250);
    worker.register("email", |payload| async move {
        let recipient = payload
            .get("recipient")
            .and_then(|value| value.as_str())
            .ok_or_else(|| {
                std::io::Error::new(std::io::ErrorKind::InvalidData, "missing recipient")
            })?;

        // Call an idempotent mail service with a stable delivery key here.
        let _ = recipient;
        Ok::<(), Box<dyn std::error::Error + Send + Sync>>(())
    });
    worker.run()
}

async fn configure() -> Result<(Queue, WorkerHandle), QueueError> {
    let queue = Queue::sqlite("sqlite://queue.db?mode=rwc").await?;
    let handle = start_email_worker(&queue)?;
    queue
        .dispatch(
            "email",
            json!({"recipient": "[email protected]", "delivery_key": "welcome:42"}),
        )
        .await?;
    Ok((queue, handle))
}
}

Dropping WorkerHandle stops processing. On graceful shutdown, call handle.shutdown().await and inspect its typed error. It stops polling and cancels running handlers; the SQLite and Redis drivers requeue each job whose handler was actually cancelled, while a handler that finished first keeps its own result. The worker never cancels a claim in flight: graceful shutdown waits for the current pop, and a job claimed after shutdown was requested is requeued instead of dispatched. Dropping the handle aborts immediately, so such a claim returns only through stalled-lease recovery.

Use Queue::redis(redis_url) with the queue-redis feature when independent processes must share work. SQLite is durable local state and supports atomic claims, but it is not a distributed queue.

Failure, retry, and delivery semantics

• A handler error, panic, or timeout is recorded as failed. Core does not automatically retry it with exponential backoff.
• retry_failed_job(job_id) explicitly returns a failed job to pending state.
• SQLite and Redis recover stale processing leases and support scheduled jobs, but execution time is the first worker poll after the due timestamp.
• Queue processing is at least once around crashes and external side effects. Give provider operations stable idempotency keys and reconcile ambiguous outcomes.
• Successful payloads are deleted by default. SQLite completed history is an explicit bounded opt-in with its own privacy/access-control obligations.

See the Redis Architecture Guide for deployment boundaries.

Tutorial 21: Explicit Local AI with Ollama 🤖

Use an explicit OllamaProvider when a workload must not fall through to a configured cloud provider. AiClient::auto() is a convenience fallback chain; it is not an isolation policy when cloud API keys are also present.

You need the ai feature of rullst (cargo rullst new --ai, or cargo rullst add ai in an existing project) and an Ollama server you run and provision yourself.

Step 1: Configure the local endpoint

Add both settings to the process environment or the project’s .env:

OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_MODEL=llama3:8b

Rullst never loads .env into the process environment, so the code below reads them with rullst::config::project_setting (the process environment first, then .env), the same way the generated starters read their own settings.

Bind Ollama to loopback or a controlled private interface. Pull and license the chosen model (ollama pull llama3:8b) through a reviewed provisioning step rather than silently during a request.

Step 2: Construct the provider explicitly

#![allow(unused)]
fn main() {
use rullst::ai::{AiClient, AiError, providers::ollama::OllamaProvider};

/// Reads a setting from the process environment, then `.env`.
fn required_setting(name: &str) -> Result<String, AiError> {
    rullst::config::project_setting(name)
        .map_err(|error| AiError::ConfigError(error.to_string()))?
        .ok_or_else(|| AiError::ConfigError(format!("{name} is required")))
}

pub async fn summarize_lesson(text: &str) -> Result<String, AiError> {
    let host = required_setting("OLLAMA_HOST")?;
    let model = required_setting("OLLAMA_MODEL")?;
    let client = AiClient::new(OllamaProvider::new(host, model));

    client
        .prompt(&format!(
            "Summarize this lesson in three factual bullet points:\n{text}"
        ))
        .await
}
}

A missing setting returns AiError::ConfigError, and a server that cannot be reached returns AiError::RequestError; neither falls back to another provider.

The high-level client applies Rullst’s mandatory prompt/PII guardrails before dispatch. Model output remains untrusted: escape it for HTML, validate structured data, and never use an LLM verdict as the only authentication, authorization, malware, or abuse-control decision.

Isolation checklist

• Confirm the resolved endpoint, host firewall, container network, DNS, proxy, and telemetry configuration.
• Remove cloud-provider credentials from the process when policy requires local only; an explicit provider prevents fallback but least privilege still helps.
• Review application/Ollama logs, model caches, backups, crash dumps, and swap for sensitive data.
• Empty or mock_* Ollama hosts select deterministic offline mock behavior; a mock response is test evidence, not evidence that a live model ran.

“Local” does not prove an air gap. Verify the complete deployed data flow.

22. RAG Systems & Vector Search

Important

Dependency examples pin the v13 prerelease =13.0.0-alpha.4 exactly: Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026 (see the release record). Commit Cargo.lock for reproducible builds. Use path dependencies only when intentionally testing checkout-local changes.

Rullst provides three deliberately separate vector paths: a deterministic in-memory index in rullst-ai, parameterized PostgreSQL pgvector queries, and a bounded Qdrant HTTP adapter in rullst-orm. None silently invent tenant authorization, context budgets, an embedding model, or a production RAG policy.

In-memory retrieval

VectorIndex is useful for bounded local datasets and tests:

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = ["ai"] }
serde_json = "1.0"

#![allow(unused)]
fn main() {
use rullst::ai::VectorIndex;

let mut index = VectorIndex::new();
index.add(
    "rullst",
    vec![1.0, 0.0, 0.0],
    serde_json::json!({"text": "Rullst is a Rust framework suite."}),
);
index.add(
    "other",
    vec![0.0, 1.0, 0.0],
    serde_json::json!({"text": "An unrelated document."}),
);

let matches = index.search(&[0.9, 0.1, 0.0], 3);
assert_eq!(matches[0].1.id, "rullst");
}

The caller supplies the embedding and the limit. This process-local index is not durable, distributed, tenant-aware, or an approximate-nearest-neighbor service.

PostgreSQL + pgvector

Enable the typed vector and concrete PostgreSQL paths:

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = [
  "orm-pgvector",
  "strict-postgres",
  "ai",
] }
# `#[derive(Orm)]`, the model's `FromRow` included, expands to `rullst_orm::…`
# paths, so a crate that derives models depends on it directly.
rullst-orm = { version = "=13.0.0-alpha.4", default-features = false, features = ["strict-postgres"] }

Projects generated with cargo rullst new --database postgres already list the rullst-orm line; add orm-pgvector and ai to their rullst features.

Install the extension through a reviewed PostgreSQL migration and choose the dimension used by your embedding provider:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE knowledge_chunks (
    id SERIAL PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    content TEXT NOT NULL,
    embedding vector(1536) NOT NULL
);

The model can use the re-exported typed Vector:

#![allow(unused)]
fn main() {
use rullst::orm::{Orm, Vector};

#[derive(Clone, Debug, Orm)]
#[orm(table = "knowledge_chunks", tenant_column = "tenant_id")]
struct KnowledgeChunk {
    id: i32,
    tenant_id: String,
    content: String,
    embedding: Vector,
}
}

Generate the query embedding through a configured guarded AI client, establish the authenticated tenant scope, and then use the native operators:

#![allow(unused)]
fn main() {
use rullst::ai::AiClient;
use rullst::orm::{Orm, Vector, with_tenant};

#[derive(Clone, Debug, Orm)]
#[orm(table = "knowledge_chunks", tenant_column = "tenant_id")]
struct KnowledgeChunk {
    id: i32,
    tenant_id: String,
    content: String,
    embedding: Vector,
}

async fn retrieve(
    client: &AiClient,
    question: &str,
) -> Result<Vec<KnowledgeChunk>, Box<dyn std::error::Error>> {
let embedding = client.embed(question).await?;
let query: Vec<f64> = embedding.iter().map(|value| f64::from(*value)).collect();

let chunks = with_tenant("tenant-42", async move {
    KnowledgeChunk::query()
        .where_similar("embedding", query.clone(), 0.8)
        .order_by_cosine_distance("embedding", query)
        .limit(5)
        .get()
        .await
})
.await?;
Ok(chunks)
}
}

The two clauses use different metrics: where_similar keeps rows whose L2 distance (<->) is below the bound, while order_by_cosine_distance sorts by cosine distance (<=>). order_by_l2_distance and order_by_inner_product (<#>) are also available; choose the bound for the L2 metric.

Vector and distance values are SQL bindings, not interpolated literals. Column names use the normal identifier validation, vectors must be finite/non-empty, and the distance must be finite and non-negative. The pgvector feature also supplies SQLx encode/decode for the typed field. Rullst’s live contract creates the extension, inserts typed vectors, and executes L2 and cosine queries against a digest-pinned pgvector/pgvector container.

Qdrant dense-vector store

Use Qdrant when the application deliberately chooses a specialized external vector service rather than keeping vectors in PostgreSQL:

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = [
  "orm-qdrant",
  "ai",
] }
serde_json = "1.0"

#![allow(unused)]
fn main() {
use rullst::orm::{
    QdrantConfig, QdrantStore, VectorCollectionName, VectorDimensions,
    VectorPoint, VectorQueryLimit, VectorRepository,
};
use serde_json::{Map, Value};

async fn qdrant_example() -> Result<(), Box<dyn std::error::Error>> {
let config = QdrantConfig::new(
    std::env::var("QDRANT_URL").unwrap_or_default(),
    std::env::var("QDRANT_API_KEY").unwrap_or_default(),
);
let vectors = QdrantStore::connect_or_mock(config)?;
let collection = VectorCollectionName::new("knowledge-v1")?;
vectors
    .create_collection(&collection, VectorDimensions::new(3)?)
    .await?;

let mut payload = Map::new();
payload.insert("chunk_id".into(), Value::String("chunk-42".into()));
vectors
    .upsert(
        &collection,
        VectorPoint::new(42, vec![1.0, 0.0, 0.0], payload)?,
    )
    .await?;
let matches = vectors
    .search(
        &collection,
        &[0.9, 0.1, 0.0],
        VectorQueryLimit::new(5)?,
    )
    .await?;
let _ = matches;
Ok(())
}
}

Empty or mock_* endpoint/API-key values select the deterministic in-process backend. An explicit QdrantConfig::unauthenticated_local is available only for loopback self-hosting. The live contract is deliberately limited to one unnamed dense cosine vector per numeric point. It bounds identifiers, dimensions, finite/non-zero-norm vectors, 1 MiB object payloads, top-k, request and response memory, deadlines and redirects. It does not claim named, sparse or multivectors, arbitrary filters, hosted availability, ANN index tuning or tenant authorization. A digest-pinned Qdrant lifecycle proves the supported operations.

Orchestrate one bounded RAG operation

The compatibility build_rag_prompt helper only formats already-authorized text. Prefer RagPipeline when the application needs one typed operation for embedding, retrieval, context budgets, guarded generation, source metadata, and mandatory auditing:

#![allow(unused)]
fn main() {
use rullst::ai::rag::{RagPipeline, RagRetriever};

fn compose<R, A>(client: rullst::ai::AiClient, retriever: R, audit: A)
where
    R: RagRetriever,
    A: rullst::ai::rag::RagAuditSink,
{
let pipeline = RagPipeline::new(client, retriever, audit);
let _ = pipeline;
}
}

The retriever receives a trusted tenant context and must enforce authoritative tenant and ownership predicates in its datastore query. The pipeline also rejects differently tagged documents and refuses ungrounded generation when no safe context remains. Follow the complete Tenant-Bound RAG tutorial for the offline index, production adapter boundary, and secret-minimized audit contract.

The application still owns embedding dimension/model compatibility, durable ingestion and deletion, citation evaluation, index tuning, authorization, output policy, observability, and recovery.

Tutorial 23: Process Telemetry & Prometheus Exporter 📡

Monitor process uptime, RSS memory, CPU, Tokio scheduler-yield latency, and active tasks using Rullst Radar (rullst::radar) and Prometheus (GET /metrics).

🛠️ Step 1: Mount Prometheus Exporter

In src/main.rs:

use rullst::radar::radar_metrics_router;
use rullst::{Router, Server, ServerError};

#[rullst::runtime::main]
async fn main() -> Result<(), ServerError> {
    let app = Router::new().merge_axum(radar_metrics_router()); // Exposes GET /metrics

    Server::new(app).run(3000).await
}

In a generated project, add .merge_axum(rullst::radar::radar_metrics_router()) to the router that main passes to Server::new, then run cargo rullst dev and open http://localhost:3000/metrics.

📊 Step 2: Prometheus Metrics Scrape Output

Query GET /metrics:

# HELP rullst_uptime_seconds Process uptime in seconds.
# TYPE rullst_uptime_seconds counter
rullst_uptime_seconds 120

# HELP rullst_memory_rss_bytes Process RSS memory consumption in bytes.
# TYPE rullst_memory_rss_bytes gauge
rullst_memory_rss_bytes 24536678

# HELP rullst_cpu_usage_percent Process CPU utilization percentage.
# TYPE rullst_cpu_usage_percent gauge
rullst_cpu_usage_percent 1.25

# HELP rullst_tokio_active_tasks Total active Tokio tasks count.
# TYPE rullst_tokio_active_tasks gauge
rullst_tokio_active_tasks 4

# HELP rullst_tokio_latency_microseconds Observed Tokio scheduler yield latency in microseconds.
# TYPE rullst_tokio_latency_microseconds gauge
rullst_tokio_latency_microseconds 42

The CPU gauge needs an earlier sample in the same process, so the first collection omits it.

In a debug build the generated starters also start Studio, whose Radar page shows the same process measurements: http://127.0.0.1:5555/studio/radar.

/metrics is not authenticated by radar_metrics_router(). Restrict it with a private network, service-mesh policy, or reviewed authentication middleware; process and runtime measurements can disclose operational information.

💡 Key Takeaways

• The response is a point-in-time local snapshot and allocates its text body.
• Linux and Windows expose supported process RSS/CPU probes. Tokio task data is available only inside a Tokio runtime; unsupported probes are omitted.
• The scheduler-yield observation is not a universal request-latency target.

Tutorial 24: Interactive Scalar API Documentation 📖

Scaffold a Scalar OpenAPI documentation router served at /docs.

🛠️ Step 1: Scaffold Scalar Docs

cargo rullst make:scalar

Run it in the project root. It generates src/controllers/docs_controller.rs and declares it in src/controllers/mod.rs (creating both when they are missing) and refuses to overwrite an existing controller. The command does not edit route registration: the application must merge the router returned by docs_controller::router().

💻 Step 2: Mount in Application

docs_controller::router() returns scalar_docs_router("/openapi.json"). This self-contained example mounts the same router:

use rullst::{Router, Server};
use rullst::scalar::scalar_docs_router;

#[rullst::runtime::main]
async fn main() -> Result<(), rullst::ServerError> {
    let app = Router::new().merge_axum(scalar_docs_router("/openapi.json"));

    Server::new(app).run(3000).await
}

In a generated project, declare mod controllers; in src/main.rs if it is not there yet (the Blank and API starters have no controllers module), and merge the router where main builds the server; in the Blank and API starters that is Server::new(router().merge_axum(controllers::docs_controller::router())). Merge it there rather than inside router(): each starter’s router() adds headers_middleware, whose default Content Security Policy blocks the page’s remote and inline scripts, which leaves /docs blank.

📄 Step 3: Generate the specification and open the page

cargo rullst generate:openapi
cargo rullst dev

generate:openapi scans the project’s routes and writes openapi.json in the project root. Open http://localhost:3000/docs in your browser to try the endpoints interactively.

💡 Key Takeaways

• The current page loads a version-pinned Scalar asset from jsDelivr. A failed CDN load shows only a status page naming the OpenAPI document; it is not an offline interactive UI.
• The status-only fallback prints the configured OpenAPI location as text; it does not create an executable link from the configured value.
• In staging and production rullst::Server applies the same security headers to every route, so the default CSP blocks the remote and inline assets there. Vendor the asset and integrate the page with the application’s nonce/hash policy before using it outside local development.
• The router serves /openapi.json from the openapi.json file in the process working directory (cargo rullst generate:openapi writes it there); if it is missing or malformed, the endpoint fails with 503 Service Unavailable instead of fabricating an empty specification. Validate the release artifact in CI.

Tutorial 25: Kubernetes Manifests & Health Probes ☸️

cargo-rullst can generate a Kubernetes starter set. The files contain project name/port defaults and must be reviewed for the target cluster, registry, secrets, storage, network policy, ingress, workload identity, and security policy before deployment.

Step 1: Generate the starter manifests

cargo rullst make:k8s

The command writes deployment.yaml, service.yaml, configmap.yaml, hpa.yaml, ingress.yaml, and all-in-one.yaml under k8s/. It refuses to run when any of those files already exists, so move customized manifests aside to regenerate them, and review the diff.

Resource names, the image and the ingress host use the [package] name as a lowercase RFC 1123 label, so a package named my_app becomes my-app; tag your image with the same name. Replace the placeholder image: <name>:latest with an immutable registry reference (preferably a digest). The generated ConfigMap contains non-secret settings only; use a Kubernetes Secret/external secret manager for credentials.

The Ingress selects ingressClassName: nginx and has a tls section, so cert-manager’s ingress-shim asks the letsencrypt-prod ClusterIssuer for a certificate and stores it in the <project>-tls Secret. Replace the placeholder <project>.local host in both tls.hosts and rules with a public DNS name you control (an ACME issuer cannot certify .local), and create the issuer or change the annotation. Without TLS, the production configuration’s Secure session cookies, HSTS and Nexus Basic Auth over verified TLS do not work.

Step 2: Mount lifecycle-aware health routes

Projects created by cargo rullst new already merge rullst::health::health_router() into their router, so the generated probes answer from the first deployment: /health and /ready both return 200 while the process serves requests. To report startup, dependency and drain state on /ready instead, replace that merge with the lifecycle-aware router:

use rullst::{ApplicationLifecycle, Router, Server};
use rullst::health::{health_router_with_lifecycle, init_health_boot_time};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_health_boot_time();
    let lifecycle =
        ApplicationLifecycle::with_required_components(["database", "queue"])?;

    // Set these only after the application's own bounded checks succeed.
    lifecycle.set_component_ready("database", true)?;
    lifecycle.set_component_ready("queue", true)?;

    let app = Router::new()
        .merge_axum(health_router_with_lifecycle(lifecycle.clone()));
    Server::new(app)
        .with_lifecycle(lifecycle)
        .run(3000)
        .await?;
    Ok(())
}

/health remains process-only so an external database outage does not create a restart loop. /ready returns 503 during startup, while any registered component is unavailable, during drain, and after stop. The JSON carries only aggregate counts; it never emits the component labels or their error messages.

The version field of both probes is the Rullst framework version. To see which build of your application a Pod runs, use health_router_with_lifecycle_and_version(lifecycle.clone(), env!("CARGO_PKG_VERSION")) (or health_router_with_version instead of health_router), which adds that string as app_version.

The component registry is immutable, accepts at most 32 validated labels, and does not execute probes by itself. The application must perform bounded, timeout-protected checks and update each bit. Server marks startup complete after binding, closes new application admission before graceful shutdown, and waits through Axum for accepted requests. run_with_shutdown accepts a supervisor future when OS signals are not the desired trigger.

This is one process contract. Kubernetes removes an unready Pod from service according to its own timing; Rullst does not coordinate replica consensus, load-balancer propagation, dependency failover, preStop, or the Pod’s terminationGracePeriodSeconds. Measure those together in staging. The legacy health_router() remains the simpler process-only pair when dependency-aware admission is not requested.

Step 3: validate before applying

kubectl apply --dry-run=client -f k8s/all-in-one.yaml
kubectl diff -f k8s/all-in-one.yaml
kubectl apply -f k8s/all-in-one.yaml

The generated HPA uses autoscaling/v2 and requires a working resource metrics pipeline. Validate against the actual cluster version and admission policies.

Release checklist

• add pod/container security contexts compatible with the reviewed image user;
• define CPU/memory requests and limits from measurements;
• add PodDisruptionBudget, topology spread/anti-affinity, NetworkPolicy, and service account/workload identity as required;
• terminate TLS with a configured issuer and real hostname;
• provision durable storage only where application state truly needs it; and
• verify probes, graceful termination, migrations, rollback, and autoscaling in a staging cluster.

Tutorial 26: Guided Container Deployment 🚀

cargo rullst deploy prepares the files you need to run your application on any Linux server (a virtual machine from any provider, or your own machine) with Docker or Podman. It writes them into your project and does not contact any provider; you review them and run them yourself.

Step-by-step guides that use these files: Deploy to a Linux VM, with provider pages for Hetzner Cloud, DigitalOcean, Oracle Cloud and Google Cloud. For Nix, Buildah, Podman Quadlet or Kubernetes see Advanced deployment. The CLI no longer has provider-specific targets (Fly.io, Railway, Render) or the Foundry SSH pipeline; container platforms can still build the generated Dockerfile, but their configuration is yours to write and review.

Before the first deploy

These staging and production defaults apply to every way of deploying:

• Migrations are a separate step by default. Server::run only opens the database pool, and cargo rullst dev applies pending migrations only in development. Run the application binary’s db:migrate command once per release, before the new version serves traffic: /app/<name> db:migrate in the generated image (it has no shell), or cargo run --release -- db:migrate from a checkout. Since 13.0.0-alpha.2 the server can instead apply them at startup: see startup migrations and the container lifecycle boundary.
• Bind address. With RULLST_ENV=staging or production, the server listens on 0.0.0.0 unless HOST (or RULLST_HOST) is set in the process environment or .env. Behind a reverse proxy on the same host, set HOST=127.0.0.1 so the plain-HTTP port is reachable only through the proxy. Inside a container keep 0.0.0.0 and publish the port only to the proxy’s network. The server prints the address it listens on at startup (Rullst framework serving on http://0.0.0.0:3000 (every network interface)); since 13.0.0-alpha.2, when that is every interface and a trusted reverse proxy is configured ([security] trusted_proxies or Server::trusted_proxies), the same line suggests HOST=127.0.0.1 for a proxy on the same host outside a container network and, since 13.0.0-alpha.4, keeping HOST=0.0.0.0 when the proxy reaches the application over a container network (as in the generated compose.yaml).
• Caching. The security baseline adds Cache-Control: no-store to every response without a Cache-Control of its own; the standard /static mount sets its own. Downloads, feeds and other responses that browsers or a CDN may cache choose a policy with rullst::cache_control::public(max_age) or private(max_age) (13.0.0-alpha.2) on their route, or set the header themselves; see downloads and feeds.

Running the generated files

cargo rullst deploy

Then follow Deploy to a Linux VM.

Client addresses behind the proxy

Every deployment puts a reverse proxy in front of the application, so the socket peer of each request is the proxy. Rate limits, such as the SaaS starter’s ten login/registration submissions per client per minute, would then treat every visitor as one client. The generated Caddy container has a fixed address on the private network in compose.yaml, and cargo rullst deploy lists that address in Rullst.toml (an existing trusted_proxies list is left unchanged, with a warning):

[security]
trusted_proxies = ["172.31.250.10"]

Keep compose.yaml and Rullst.toml in step, and change the subnet if it overlaps a network on the host. For any other proxy or platform, list the networks it connects from, as documented by that platform. List only proxy networks: any host inside them can choose the client address.

Container lifecycle boundary

The Dockerfile written by cargo rullst deploy, cargo rullst dockerize or cargo rullst new --docker builds a non-root runtime image with production host/port defaults and local assets, but never an application secret. For a SQLite project (the starters’ default) the image sets DATABASE_URL=sqlite:///app/data/rullst.db?mode=rwc, so the database lives in /app/data; configure the target platform so that directory remains owned by UID/GID 10001 when attaching persistent storage (the generated compose.yaml mounts a volume there).

Apply migrations in one bounded pre-deployment job and start application replicas only after it succeeds. Running migrations inside every replica is opt-in (startup migrations), not the default. Starters created by cargo rullst new mount rullst::health::health_router(), which answers /health and /ready. An application created otherwise must mount those routes before configuring probes or monitoring; a redirect to login is not a health signal.

Startup migrations

Since 13.0.0-alpha.2 the server can apply pending migrations itself, after it opens the database pool and before it binds its port. It is off by default. Register the migrations and turn it on in code, per deployment, or both:

Server::new(router())
    .with_migrations(crate::migrations::get_migrations())
    .auto_migrate(true) // or leave it out and set RULLST_AUTO_MIGRATE=true
    .run(3000)
    .await?;

RULLST_AUTO_MIGRATE (true or false; 1/0, yes/no and on/off also work), from the process environment and then .env, overrides auto_migrate, so a deployment that runs db:migrate as a separate job can set RULLST_AUTO_MIGRATE=false. Projects that cargo rullst new generates with an SQLx database (Blank, API and SaaS) already call with_migrations but not auto_migrate, so setting RULLST_AUTO_MIGRATE=true is enough; a project generated before 13.0.0-alpha.2 needs the line above in src/main.rs. A Turso starter applies its migrations with its own db:migrate command and registers none with the server, so RULLST_AUTO_MIGRATE=true there stops startup with startup migrations failed: no migrations are registered; call Server::with_migrations: leave it unset and run db:migrate.

Replicas that start together apply each migration once: the runner holds a PostgreSQL advisory lock or a MySQL/MariaDB GET_LOCK lock, and for an SQLite file an exclusive lock on <database>.rullst-migrate.lock (left on disk), while it reads and applies the pending migrations; the others wait and then find nothing to do. If a migration fails, or migrations are enabled without a registry or a database, the server does not start: run returns ServerError::Migration and the process exits with that error. A migration must still be safe for the previous release, which keeps serving until the new replicas are ready.

Tutorial 27: Typed Dependency Injection (rullst::di) 💉

Rullst DI uses Rust types as keys and avoids runtime reflection metadata. It is not literally zero-cost: registration uses a map, resolution performs a type-indexed lookup/downcast, and each injection clones an Arc.

Step 1: Register services without embedding secrets in source

#![allow(unused)]
fn main() {
use std::sync::Arc;
use rullst::di::Container;
use rullst::security_runtime::VaultSecret;

pub struct PaymentGateway {
    api_key: VaultSecret<String>,
}

impl PaymentGateway {
    pub fn is_configured(&self) -> bool {
        !self.api_key.expose_secret().is_empty()
    }
}

pub struct UserService {
    pub gateway: Arc<PaymentGateway>,
}

pub fn configure_di() -> Result<Arc<Container>, std::env::VarError> {
    let key = std::env::var("PAYMENT_API_KEY")?;
    let mut container = Container::new();
    let gateway = Arc::new(PaymentGateway {
        api_key: VaultSecret::new(key),
    });

    container.register_arc(Arc::clone(&gateway));
    container.register(UserService { gateway });
    Ok(Arc::new(container))
}
}

security_runtime requires the umbrella security feature. The generated starters depend on rullst-security directly, so they can use rullst_security::VaultSecret instead. std::env::var reads only the process environment (Rullst never loads .env into it); use rullst::config::project_setting to fall back to .env in development. A secret manager should inject the real value in production; VaultSecret reduces accidental formatting and zeroizes its owned allocation on drop, but it is not key custody or secure memory.

Step 2: Attach the container and extract a service

use rullst::server::{Extension, Json, post};
use rullst::{Router, di::Inject};

pub async fn process_payment(
    Inject(user_service): Inject<UserService>,
) -> Json<&'static str> {
    // Use a bounded provider adapter; never log the key or full request payload.
    let _configured = user_service.gateway.is_configured();
    Json("Payment request accepted")
}

let container = configure_di()?;
let app = Router::new()
    .route("/payments", post(process_payment))
    .layer(Extension(container));

The continuation is application code because its error type and provider adapter belong to the project. Inject<T> takes T from the container and, when the container lacks it (or there is none), from an Extension<Arc<T>> layer. If neither provides it, Inject<T> fails closed with a 500 whose body is a fixed message; the missing type name is logged on the rullst::di target, never returned to the client.

Key takeaways

• Services are registered as type-safe Arc<T> singletons.
• DI controls construction and lookup; it does not provide authorization, transaction boundaries, or secret management.
• Prefer ordinary constructors when a small service graph does not benefit from a container.

Tutorial 29: IoT data and frame helpers (rullst-iot)

rullst-iot provides telemetry/state models and protocol frame builders that compile without std. Some APIs use alloc, so a bare-metal application must supply an allocator.

It also provides bounded MQTT 5 PUBLISH (MqttPublish) and CoAP request (CoapRequest) encoders. The crate does not currently read hardware registers or provide MQTT/CoAP network transport, OPC-UA, Sparkplug B, HSM, or post-quantum implementations.

Experimental. rullst-iot and the make:iot generator are in the Experimental maturity tier: the API may change between 13.x releases and nothing has been validated on physical hardware. The module status lists which modules are working implementations and which are only data models or contracts.

Add the crate

In a Rullst application, cargo rullst make:iot TemperatureSensor turns on the iot feature of rullst, writes src/iot/temperature_sensor.rs (a TemperatureSensorDevice that returns SensorTelemetry readings) and declares the iot modules. The crate is then reachable as rullst::iot, so the rullst_iot:: paths below become rullst::iot::.

A firmware crate depends on rullst-iot directly and turns off its default std feature:

[dependencies]
rullst-iot = { version = "=13.0.0-alpha.4", default-features = false }

Build a telemetry model and Modbus request

#![allow(unused)]
fn main() {
use rullst_iot::{AnomalyDetector, ModbusFrame, SensorTelemetry};

let telemetry = SensorTelemetry::new(
    "sensor-01",
    "temperature",
    38.5,
    1_700_000_000,
);
let detector = AnomalyDetector::new(25.0, 5.0);
let state = detector.evaluate(telemetry.value);

// This builds bytes for a request. Platform code must send them over a real
// serial/TCP transport and handle timeouts, retries, and the response.
let request = ModbusFrame::read_holding_registers(1, 0, 10);
assert_eq!(request.len(), 8);
let _ = state;
}

Signed firmware artifacts

Use OtaManifest and OtaManager::new_with_trusted_key to verify a firmware artifact before selecting an inactive partition. See the crate guide for the trust, persistence, and bootloader requirements that remain the integrator’s responsibility.

Experimental fixtures

The opt-in experimental-simulators feature contains explicitly named Simulated* fixtures. They are deterministic test data generators, not hardware or protocol implementations.

Tutorial 30: Axum Escape-Hatch Snapshot (cargo rullst eject) 🔓

eject generates a minimal Axum/Tokio entry point that can begin a manual migration away from Rullst’s server wrapper. It does not statically expand macros, copy the application’s route graph, convert middleware, or remove Rullst dependencies automatically.

Step 1: Generate a separate starting point

cargo rullst eject

The default output is src/ejected_main.rs; the existing src/main.rs remains unchanged. Cargo does not build src/ejected_main.rs (it is not a binary target): review it and compare it with src/main.rs; only --force (Step 2) replaces the entry point. The generated template serves a placeholder route from application_routes() and wraps it in the configured Rullst security baseline, the same apply_security_baseline step rullst::Server performs with Rullst.toml. Axum is reached through the rullst::web::axum re-export, so the template compiles without adding Axum to Cargo.toml. Without its header comment and start-up message, the template is:

use rullst::RullstConfig;
use rullst::web::axum::{Router, response::Html, routing::get};
use std::net::SocketAddr;

/// Mount the application's routes here.
fn application_routes() -> Router {
    Router::new().route("/", get(|| async { Html("<h1>Ejected Axum Server</h1>") }))
}

#[rullst::runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = if std::path::Path::new("Rullst.toml").exists() {
        RullstConfig::load_from_file("Rullst.toml").await?
    } else {
        RullstConfig::default()
    };
    let environment = config.environment()?;
    let app = rullst::apply_security_baseline(application_routes(), config.security, environment)?;

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    let listener = rullst::async_runtime::tokio::net::TcpListener::bind(addr).await?;
    rullst::web::axum::serve(
        listener,
        app.into_make_service_with_connect_info::<SocketAddr>(),
    )
    .await?;
    Ok(())
}

The baseline covers secure headers, CORS, WAF/RASP and CSRF (headers, WAF and CSRF in staging/production). Static files, rate limiting, lifecycle probes, hot reload, sessions, authentication and authorization are not included.

Move application routes into application_routes() one bounded group at a time and retain equivalent limits, telemetry, graceful shutdown, health behavior, state, and authorization tests.

Step 2: Treat --force as a deliberate replacement

cargo rullst eject --force

The hardened command first preserves the original entry point as src/main.rs.rullst-backup and refuses to overwrite an existing backup. The template does not carry over the original routes or module declarations; move them from the backup before building or deploying. Keep a normal version-control commit as the authoritative recovery path. Custom output paths are restricted to relative Rust files under src/ and existing targets are not overwritten implicitly.

Key takeaways

• Ejection is a migration aid, not a semantics-preserving compiler transform.
• The application remains responsible for dependency cleanup and replacements for ORM, auth, queues, Studio, Nexus, Capital, AI, and other selected crates.
• Run cargo fmt, strict Clippy, the complete test suite, and application security/operational checks after every migrated route group.

Tutorial 31: SaaS deployment preparation for AWS or GCP

This guide prepares a generated SaaS application for a cloud deployment. It is not an end-to-end production certification: identity, network policy, database operation, secrets, billing and recovery remain deployment responsibilities.

1. Materialize and verify the SaaS starter

Install the published 13.0.0-alpha.4 CLI with its exact version (Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026), then generate deterministically. Do not substitute the moving main branch for an immutable release artifact:

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked
cargo rullst new my_cloud_saas --default --blueprint saas --docker
cd my_cloud_saas
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Review every generated route, access policy, migration and environment placeholder before supplying live credentials.

2. Supply secrets outside source control

Use AWS Secrets Manager, Google Secret Manager or an equivalent deployment boundary for values such as APP_KEY, DATABASE_URL, provider keys, webhook secrets and, if you use encrypted model fields, RULLST_ENCRYPTION_KEY. Do not bake .env into an image (the generated .dockerignore keeps .env and .env.* out of the build context).

Set RULLST_ENV=production and make startup fail when a required production adapter or credential is missing. Empty and mock_* provider credentials are for deterministic offline development, not live operation.

3. Build and scan the exact image

docker build --pull --tag my-cloud-saas:<git-sha> .
docker inspect my-cloud-saas:<git-sha>

Pin the deployed image by digest. Run the application’s tests and a container scanner against the exact candidate. The CLI’s deploy command writes a Dockerfile, compose.yaml and Caddyfile for a Linux VM (see Deploy to a Linux VM); AWS App Runner/ECS and Google Cloud Run configuration remains explicit cloud work.

4. Configure the cloud boundary

For AWS or GCP, define and review:

• private database connectivity, TLS and least-privilege credentials;
• trusted proxy handling and the application’s external origin policy;
• ingress authentication, rate limits, body limits and request timeouts;
• readiness/liveness behavior and a bounded shutdown grace period;
• immutable image rollout and a tested rollback procedure;
• logs, metrics and alerts that avoid secrets and unnecessary PII.

Managed services have provider-specific scaling floors, quotas, cold starts and costs. Verify current provider documentation and load-test your selected region and topology rather than assuming scale-to-zero or a request rate.

5. Exercise stateful recovery

Before production traffic, rehearse migrations, backup, restore, webhook replay, field-encryption key rotation, a failed rollout and database unavailability. Health endpoints only report the checks implemented by the application; they do not create zero-downtime deployment by themselves.

Tutorial 32: Bounded security telemetry in Studio

Rullst’s honeypot, RASP and Studio security page provide local defense-in-depth signals. They are not an autonomous SOC, a universal blocker, an AI incident responder or a durable SIEM integration.

1. Compose local request controls

rullst::Server already applies secure headers and the WAF in staging and production. This example composes the rullst-security layers on a plain Axum router:

#![allow(unused)]
fn main() {
use axum::Router;
use rullst_security::{CspSecurityLayer, HoneypotLayer, HoneypotState, RaspSecurityLayer};
use std::net::SocketAddr;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
let app = Router::new()
    // Add application routes first.
    .layer(RaspSecurityLayer)
    .layer(CspSecurityLayer)
    .layer(HoneypotLayer::new(HoneypotState::default()));

let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
axum::serve(
    listener,
    app.into_make_service_with_connect_info::<SocketAddr>(),
)
.await?;
Ok(())
}
}

ConnectInfo supplies the accepted socket peer used by the honeypot. Deployments behind a proxy must establish and test a trusted client-identity boundary; the middleware deliberately does not trust arbitrary forwarding headers.

2. Understand each signal

• Honeypots match configured exact synthetic paths and keep bounded, expiring process-local bans.
• RASP performs bounded heuristic inspection for selected patterns and can have false positives and negatives.
• CSP and headers depend on the final rendered page, proxy, browser and TLS deployment.
• SecurityStore is local telemetry. An event is not HMAC-verified or durably delivered merely because it appears in Studio.

No built-in path asks an LLM to ban a peer or automatically mounts a blocking policy. The opt-in ThreatSentinel can classify three bounded, caller-supplied aggregate patterns and issue an HMAC-authenticated, subject-bound, expiring, one-shot process-local proof-of-work challenge. The application must supply trustworthy observations and subject identity, translate the outcome into an HTTP protocol, and decide where that gate belongs. It is not AI attribution, a distributed replay store, or an autonomous ban. Sensitive automated actions still require authenticated policy, limits, durable audit and human approval where appropriate.

3. Inspect the local Studio view

In a debug build the generated starters start Studio in the same process with rullst::studio::run_studio(5555), which serves only loopback peers (LocalStudioAccess::loopback_only()). Open http://127.0.0.1:5555/studio/security. The page renders this process’s current SecurityStore telemetry and keeps unavailable sources visibly unavailable. A multi-instance deployment needs a shared, authenticated event pipeline with retry, acknowledgement, retention and dead-letter handling before it can be described as an operational SIEM.

See the Threat Radar and SOC guide and the v12 security evidence ledger for exact boundaries.

Tutorial 33: Auth-bound multi-tenancy

Rullst Core can select a tenant from a request hint only after application authentication has inserted a trusted TenantMembership. A hostname, header, query parameter or request body is never sufficient proof of membership.

1. Configure the selection layer

#![allow(unused)]
fn main() {
use axum::{Extension, Router, routing::get};
use rullst_core::{
    multitenant::{TenantConfig, TenantLayer, TenantStrategy},
    security::TenantContext,
};

async fn tenant_dashboard(Extension(tenant): Extension<TenantContext>) -> String {
    format!("Selected workspace: {}", tenant.tenant_id)
}

fn tenant_routes() -> Router {
    let selection = TenantLayer::new(TenantConfig::new(TenantStrategy::Subdomain));
    Router::new()
        .route("/dashboard", get(tenant_dashboard))
        .layer(selection)
}
}

An outer, application-owned authentication layer must first validate the session/token and insert TenantMembership::try_new(...) from trusted identity claims. Without that extension, TenantLayer returns 403 Forbidden. If the requested subdomain is not in the authenticated membership set, it also returns 403. A request that names no tenant (and, with the subdomain strategy, has no with_domain_fallback) uses the membership’s default (TenantMembership::with_default, or the only tenant of a single-tenant membership) and is refused with 403 when there is none. In Axum, remember that subsequently added layers run first; test the final middleware order in-process.

TenantStrategy::Header and TenantStrategy::Parameter are also available, but they remain untrusted selection hints. Query parameters additionally leak more easily through history, referrers and access logs. The built-in subdomain parser reads the Host header, or the HTTP/2 :authority when no Host is sent, and selects the first label only for hostnames with at least three labels; a www label is never a tenant. When the apex domain sits under a multi-label public suffix such as .com.br or .co.uk, set TenantConfig::with_base_domain("escola.com.br") (added in v13): the tenant is then the label immediately to the left of that domain, and the apex itself uses with_domain_fallback (which only the subdomain strategy reads). Custom-domain ownership and trusted-proxy normalization remain application and deployment work.

2. Bind every database query

Tenant selection does not rewrite arbitrary SQL or automatically add a tenant predicate to every ORM query. Bind the authenticated tenant explicitly. This example uses SQLx directly; its #[derive(FromRow)] needs SQLx’s derive feature in your manifest, which Rullst does not enable:

#![allow(unused)]
fn main() {
use rullst_core::security::TenantContext;
use sqlx::{FromRow, PgPool};

#[derive(FromRow)]
struct Invoice {
    id: i64,
    tenant_id: String,
    total_minor: i64,
}

async fn list_tenant_invoices(
    pool: &PgPool,
    tenant: &TenantContext,
) -> Result<Vec<Invoice>, sqlx::Error> {
    sqlx::query_as::<_, Invoice>(
        "SELECT id, tenant_id, total_minor FROM invoices WHERE tenant_id = $1",
    )
    .bind(&tenant.tenant_id)
    .fetch_all(pool)
    .await
}
}

Use database constraints and, where appropriate, database-native row-level security as additional defense. Negative tests must prove that one tenant cannot read, update or delete another tenant’s records through every relevant route, repository, background job and administrative surface.

3. Operational boundaries

• TenantContext is server-selected state, not a claim accepted from JSON.
• current_tenant_id() is task-local convenience; passing an explicit TenantContext to domain/storage APIs is easier to audit.
• TenantCache, TenantStorage, TenantRealtime and TenantPresence provide validated namespaces, but applications still own business authorization and remote provider policy.
• Cross-process membership updates, custom-domain verification, database policy, audit retention and incident response are not automatic framework guarantees.

Tutorial 34: Live Analytics Dashboard (rullst::live & WebSockets) 📈

Build a per-connection analytics view with rullst::live. Feed it values from your own authoritative metrics source; the example below uses explicit state only to demonstrate the component lifecycle.

🛠️ Step 1: Create Analytics LiveComponent

cargo rullst make:live AnalyticsDashboard writes src/live/analytics_dashboard.rs and declares it in src/live/mod.rs; declare mod live; in the crate root yourself. Replace the generated counter with:

#![allow(unused)]
fn main() {
use rullst::async_trait;
use rullst::live::LiveComponent;
use serde_json::Value;

#[derive(Default)]
pub struct AnalyticsDashboard {
    pub revenue_mrr: f64,
    pub active_users: usize,
}

#[async_trait]
impl LiveComponent for AnalyticsDashboard {
    async fn mount(&mut self) {
        // Replace these initial values with an application-owned metrics query.
        self.revenue_mrr = 0.0;
        self.active_users = 0;
    }

    async fn handle_event(&mut self, payload: Value) {
        if let Some(event) = payload.get("event").and_then(|v| v.as_str()) {
            if event == "refresh" {
                self.revenue_mrr += 100.00;
                self.active_users += 1;
            }
        }
    }

    fn render(&self) -> String {
        format!(
            r#"<div id="analytics-dashboard" class="p-8 bg-slate-900 text-white rounded-2xl shadow-2xl border border-slate-800">
    <h2 class="text-2xl font-bold mb-6">Live Analytics Stream</h2>
    <div class="grid grid-cols-2 gap-6 mb-6">
        <div class="p-4 bg-slate-800 rounded-xl">
            <p class="text-slate-400 text-sm">MRR</p>
            <p class="text-3xl font-mono text-emerald-400">${:.2}</p>
        </div>
        <div class="p-4 bg-slate-800 rounded-xl">
            <p class="text-slate-400 text-sm">Active Users</p>
            <p class="text-3xl font-mono text-cyan-400">{}</p>
        </div>
    </div>
    <button ws-send name="event" value="refresh" class="px-6 py-3 bg-indigo-600 hover:bg-indigo-500 font-semibold rounded-xl">
        ⚡ Refresh Live Stream
    </button>
</div>"#,
            self.revenue_mrr, self.active_users
        )
    }
}
}

💻 Step 2: Render in View Page

use rullst::html::Markup;
use rullst::live::Live;
use crate::live::analytics_dashboard::AnalyticsDashboard;

pub async fn analytics_page() -> Markup {
    Live::mount::<AnalyticsDashboard>("/ws/analytics").await
}

Live::mount pre-renders the component inside a wrapper that opens the WebSocket; return it as the page or interpolate it into an html! layout. Register the matching upgrade route on the application’s rullst::Router (generated projects reach Axum only through rullst::web::axum):

let app = router()
    .ws("/ws/analytics", rullst::live::live_ws_handler::<AnalyticsDashboard>);

The page must also load HTMX and a pinned HTMX WebSocket extension; Rullst does not inject that browser dependency.

💡 Key Takeaways

• Rullst owns the server-side component lifecycle; a browser transport is still required.
• The current implementation re-renders an HTML fragment after each valid JSON event. It does not provide distributed state, replay, authorization or a metrics source automatically.
• Incoming events are limited to 64 KiB per WebSocket message; larger messages close the session.

Tutorial 35: Performance measurement and resilient operation

Performance is a property of a concrete application, build, host and workload. Rullst includes Criterion microbenchmarks and production helpers, but does not promise a universal latency, throughput or availability number.

1. Build an application-specific release binary

[profile.release]
opt-level = 3
lto = "thin"
codegen-units = 1
strip = "debuginfo"

Generated projects already ship a release profile with lto = "thin", codegen-units = 1 and strip = "symbols"; strip = "debuginfo" keeps symbol names for production backtraces. cargo rullst build compiles the release binary and pre-compresses static assets.

Alternative linkers such as mold or lld can improve developer link time on supported hosts. target-cpu=native can improve a host-specific binary but makes it less portable; do not put it in a generally distributed artifact without an explicit CPU baseline.

2. Configure and measure the database pool

#![allow(unused)]
fn main() {
use rullst_orm::Orm;

async fn configure() -> Result<(), rullst_orm::Error> {
Orm::init_with_options(
    "postgres://app:[email protected]/app",
    20, // maximum connections
    10, // acquire timeout in seconds
)
.await?;
Ok(())
}
}

Call it before Server::run: the server keeps an already-initialized pool instead of opening its own from DATABASE_URL. Choose limits from database capacity and measured concurrency. More connections can increase contention and resource use instead of increasing throughput.

3. Run reproducible benchmarks

In a checkout of the Rullst repository, run one group at a time with the command the benchmark workflow uses for it, for example:

cargo bench -p rullst-core --bench core_bench
cargo bench -p rullst-orm --features drivers-all --bench orm_bench

Record at least:

• exact commit, Rust version, features and release profile;
• CPU, memory, operating system and power/virtualization settings;
• database/provider version and topology;
• warm-up, sample count, concurrency and payload distribution;
• median and tail latency, throughput, errors and resource use.

Criterion microbenchmarks detect regressions in selected functions. They do not model a production network, database, proxy or user journey. For cross-framework comparisons, follow the method in the v13 framework comparison plan.

The public benchmark hub links the eight published groups: facade/HTTP, Core primitives, ORM, Auth, Connect, Security, AI and Capital. Nine Criterion binaries back those groups because ORM has both local and cross-ORM inputs. A crate without a microbenchmark is not automatically less mature: protocol vectors, generated-project compilation, restart/failure contracts, no_std target builds or whole-request tests can fit its dominant risk better. Add a new benchmark only with a stable operation, input, unit and interpretation.

The repository also contains a cross-ORM SQLite harness:

cargo bench -p rullst-orm --features strict-sqlite \
  --bench orm_comparison

It pins Diesel and SeaORM in the lockfile and gives all three ORMs one typed SQLite connection, separate database files, the same schema/unique index, 100 equivalent rows and identical WAL/synchronous/busy-timeout policy. Criterion measures primary-key lookup, indexed filtered lookup, count, ordered list-ten and insert/delete. This makes the input inspectable; it does not make the architectures identical. Diesel’s synchronous call path and the async Rullst/SeaORM executor paths remain part of what is measured.

The benchmark workflow runs it and publishes the results with the other groups. Read them as regression/comparison evidence for these five SQLite shapes only, and never generalize them to networked PostgreSQL/MySQL, concurrency, memory use or complete applications.

4. Test failure behavior separately

Availability requires deployment exercises: health/readiness semantics, timeouts, overload, cancellation, database failover, backup/restore, migration rollback and secret rotation. Miri, sanitizers, fuzzing and Kani are target-specific correctness tools; none measures availability or proves the absence of every memory error.

36. Assisted framework upgrades

Rullst v12 introduced a bounded upgrade transaction for existing applications. The goal is to make the safe, repeatable part a single command while refusing to guess about application data or security policy.

The transaction steps below were written for 12.1.0; check publication status. The v12 line reached end of life on 16 October 2026, so a v12 application moves to v13 with the v13 CLI. The v13 source rules and the rule classification are described in v12 to v13: source findings and belong to the 13.0.0-alpha.4 prerelease. Install the exact release and complete the application-specific validation below before any production rollout.

What the command can guarantee

cargo rullst upgrade can inventory the Cargo workspace, update the Rullst release train, apply compiler suggestions, require cargo check, and restore the files it controls after a failure. It cannot prove that a database upgrade, authorization rule, provider integration or deployment still behaves correctly.

The automatic transaction owns only:

• versioned Rullst dependencies in exact Cargo workspace manifests;
• the root Cargo.lock produced by Cargo resolution;
• Rust edits proposed by cargo fix;
• a cargo check --workspace --all-targets --locked gate using the application’s selected features.

The 12.1 updater writes managed requirements as =VERSION, preserving the explicitly selected release instead of allowing Cargo to choose a later patch or minor version. cargo fix resolves the candidate lockfile, and the final check must use that resolution unchanged. Review these pins before restoring any broader dependency-update policy in your application.

It never runs migrations, changes secrets, invents tenant/ownership policy, opens Nexus or Studio, contacts application providers, or marks the result production-ready.

1. Prepare the application

Create a branch, make the worktree reviewable, record the old test result, and back up every database. Prove the database backup can be restored before changing the framework.

Install the exact CLI from the same release train as the target framework. For a v12 application, that is the v13 prerelease (Cargo never selects a prerelease on its own):

cargo install cargo-rullst --version =13.0.0-alpha.4 --locked --force

The framework command does not update its own executable. This matters for v5: the already-published v5 CLI cannot gain the v12 migration engine retroactively, and the v13 CLI upgrades only from v12 or later. A v5 application first moves to v12 with the end-of-life 12.x CLI (cargo install cargo-rullst --version 12.1.0 --locked --force, as the steps below show), then to v13. Run each CLI inside the application.

2. Inspect without writing

cargo rullst upgrade --dry-run

The plan shows every dependency edit and source finding. MUST-CHANGE (BLOCKER in the 12.x CLI) means a known old API or option requires a source change; REVIEW means the code uses an API, feature or configuration whose behaviour changed and must be revalidated. Neither label means that unreported code is automatically safe.

For automation, request JSON:

cargo rullst upgrade --dry-run --json > upgrade-plan.json

The root object uses schema_version: "rullst.upgrade-plan.v1" and identifies the rule catalog, exact target, manifest changes, detected source majors, findings, automatic scope and mandatory manual gates. Consumers must reject an unknown schema version rather than silently interpreting it as v1. The v13 CLI extends v1 additively (see the v13 fields); consumers must ignore keys they do not know.

Use an explicit target to make the selected published version visible:

cargo rullst upgrade --to 13.0.0-alpha.4 --dry-run

Other targets must exist in the registry and belong to the installed CLI’s major train, so a CLI never applies rules it does not carry: a v12 CLI cannot plan a v13 migration, and the v13 CLI cannot downgrade a project.

3. Apply the transaction

After resolving or accepting every finding:

cargo rullst upgrade

Before the first write, the CLI snapshots Cargo workspace manifests, the root lockfile and Rust sources under:

target/rullst-upgrades/<UTC-run-id>/
├── files/
├── index.tsv
├── report.md
└── report.json

It then edits the TOML while preserving comments and relative order, runs compiler-provided fixes and executes the Cargo check gate. A failing gate restores the controlled files automatically and returns a non-zero status.

To deliberately keep a partial result for diagnosis:

cargo rullst upgrade --keep-on-failure

To restore a persisted snapshot after that mode or after an interrupted run:

cargo rullst upgrade \
  --restore target/rullst-upgrades/<UTC-run-id>

Restore accepts only a path-validated snapshot inside the current project’s target/rullst-upgrades directory. cargo clean deletes target, so retain a normal version-control commit or copy a needed diagnostic report before cleaning.

Recovery boundaries and 12.1.0 hardening

Stop editors, watchers and other writers before restoring. File recovery does not undo build-script/test side effects or database/external-service changes. Keep an independent version-control backup; the directory under target is not a substitute for one. A filesystem error during application can leave some files restored and others unchanged, so always review the result.

Since 12.1.0 the CLI preflights the entire backup, stages every replacement before writing originals, and rejects linked or malformed paths. It limits indexes to 8 MiB/100,000 entries, each snapshot to 64 MiB and the total to 512 MiB. Disk failure while staging leaves originals intact; failure during the later per-file apply reports progress and retains the backup. This is not an all-files atomic commit and does not defend against hostile concurrent filesystem changes. These improvements are not in 12.0.0.

4. Finish a v5 to v12 migration

This step uses the v12 CLI. The v13 CLI accepts only v12 and v13 projects, so upgrade older applications to v12 first and then to v13.

The v5 README used attribute-style routing and a server builder with no router or port. The scanner reports these markers instead of applying a global text replacement. Replace the old shape:

#[routes]
fn home() -> Response {
    // ...
}

Server::new()
    .route("/", get(home))
    .run()
    .await;

with an explicit v12 router and typed error propagation:

use rullst::{Server, response::Html, routes};

async fn home() -> Html<&'static str> {
    Html("Hello from v12")
}

#[rullst::runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let app = routes![get("/" => home)];
    Server::new(app).run(3000).await?;
    Ok(())
}

Then follow the complete v5 → v12 guide, including feature selection, disposable database migration/rollback, explicit Nexus and Studio boundaries, provider validation and authorization negatives.

5. Run the application-owned gates

At minimum:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --release

Also test the actual production feature set, restore/migrate/rollback against a production-shaped database copy, cross-user and cross-tenant denials, proxy/TLS identity, CSRF/CORS, Nexus/Studio exposure and every configured live provider.

v12 to v13: source findings

The v13 CLI carries the rullst-upgrade-rules-v4 catalog. It parses the application instead of matching text: Rust files with syn (so comments, doc comments and string literals never match an API rule, and macro bodies such as html! and routes! are read token by token), Cargo manifests with a TOML parser, and a few generated project files (.gitignore, .dockerignore, .cargo/config.toml, Foundry.toml, docker-compose.prod.yml, Kubernetes YAML, an Omni shell under omni-app/, rullst-client.ts, Dockerfile, .env/.env.example keys and release scripts). Files are read without following symbolic links; a finding records a rule and a line, never file contents. A Rust file that does not parse, is not UTF-8 or is larger than 2 MiB is listed as NOT SCANNED.

Each finding has a stable code (V13-...), a kind, a location, a one-line message and the first-column title of its row in the v13 migration guide:

Source findings (rullst-upgrade-rules-v4): 1 must-change, 2 review
  MUST-CHANGE src/views/home.rs:12 [V13-HTML-DYNAMIC-EVENT-HANDLER] a dynamic value in an `on*`/`hx-on*` attribute of `html!` no longer compiles
      migration-v13 row: `html!` event handlers
  REVIEW src/main.rs:64 [V13-RENDER-PAGE-LANGUAGE] `render_page` declares `lang="pt-BR"`; English pages should use `render_page_with_lang`
      migration-v13 row: Starter page language

• must-change: a compile-breaking or API-shape change that the code uses (for example a dynamic onclick={...} in html!, a belongs_to without foreign_key, a struct-level #[sqlx(rename_all)] on a model, a match on FieldKind without a wildcard, a utoipa 5 dependency used with Studio).
• review: the code uses an API, feature or configuration whose behaviour changed (for example Model::all(), ValidatedJson, the Mail facade, render_page, a generated .gitignore without the SQLite journal files).

A review rule is reported once per file (its first location); a must-change rule at every location. The rule classification lists which migration rows have rules. Findings never block cargo rullst upgrade, whose cargo check gate still restores the project when the code does not compile. The gate’s error names the must-change findings and repeats the guidance of V13-CAPITAL-REMOVED and V13-MAIL-REMOVED findings, which name removed APIs but are review findings. update project verify, review and apply refuse a preparation that has must-change findings and carry review findings in the plan.

Rules by release

Each rule records the release that introduced the change it reports. The rules for the 12.x to 13 changes date from 13.0.0-alpha.1; a rule added later, or reworded because a later release changed what it reports, carries that release:

A rule is dated by the first release tag whose catalog contains its code (git show v13.0.0-alpha.2:cargo-rullst/src/generators/build/upgrade/rules/catalog.rs, or git log -S'"V13-..."' on that file), checked against the CHANGELOG entry that names it; a new rule takes the next release. A unit test checks that every rule names one of these releases.

The plan takes the application’s Rullst version to be the oldest version that a Rullst requirement in the workspace manifests admits (=13.0.0-alpha.3, or 13.0.0-alpha.1, a caret requirement) or that Cargo.lock holds. When that version is a 13.0 prerelease, only the rules introduced after it apply: an alpha.3 application gets the alpha.4 rules, an alpha.2 application the seven alpha.3 rules and the alpha.4 rules, and an alpha.1 application the alpha.2, alpha.3 and alpha.4 rules, because the earlier changes are already in the version it runs. The plan says what it skipped:

Source findings (rullst-upgrade-rules-v4): 0 must-change, 1 review
  Rules: introduced after 13.0.0-alpha.2, the Rullst version this project uses; earlier rules skipped: 100 (findings hidden: 3); --all-rules applies every rule

A v12 application, or one whose version cannot be read (path dependencies without a version and no Cargo.lock), gets every rule. --all-rules applies every rule to a prerelease application too, for example to review the 12.x to 13 changes again. Project preparations (cargo rullst update) always apply every rule, because their must-change findings gate execution.

JSON plan fields

--dry-run --json keeps every rullst.upgrade-plan.v1 key. Each element of source_findings keeps path, line, code (the stable rule id), severity (BLOCKER or REVIEW) and message, and adds:

The root object adds finding_counts (must_change, review), unscanned_sources (project-relative paths), migration_guide and rule_selection: current_version (the application’s Rullst version, or null when it cannot be read), all_rules (--all-rules, and always true in project preparations), skipped_rules (rules introduced in or before current_version that were not applied) and hidden_findings (the findings those rules would have added). A consumer that ignores unknown keys reads the plan as before; findings of skipped rules are absent from source_findings and finding_counts.

Fixing the findings

Each finding names its rule and the first-column title of its row in the v13 migration guide, which says what changed and how to adapt. Fix them by hand, or with your editor’s or terminal’s AI assistant given the plan, the migration row and the project’s AGENTS.md (cargo rullst generate:ai-context); review every edit it proposes. cargo rullst ai upgrade, which proposed such fixes in earlier 13.0 prereleases, was removed in 13.0.0-alpha.4.

A practical order:

1. cargo rullst upgrade --dry-run and read every finding with its migration row.
2. Fix findings that also compile against v12 (most review items and the html!, ORM and Nexus must-change items), then run the v12 tests.
3. cargo rullst upgrade. When a fix needs a v13 API (for example utoipa 6 with Studio), run cargo rullst upgrade --keep-on-failure, fix the kept state, and finish with cargo rullst upgrade (no further version edits; it validates the result).
4. Run the application-owned gates below.

Rehearsal on generated starters

A rehearsal generates starters with a published CLI, points their Rullst dependencies at a checkout of the next version through [patch.crates-io] (the registry requirements stay, so the upgrade edits them as it would for a published release), runs cargo rullst upgrade with the newer CLI and then each project’s build, tests and Clippy.

13.0.0-alpha.2 to 13.0.0-alpha.3

The October 2026 rehearsal used the published v13.0.0-alpha.2 Linux binary, checked with sha256sum -c cli-checksums-x86_64-unknown-linux-gnu.txt from the same release, and a CLI built from main; the projects built with Rust 1.99.0. Because main still carried the alpha.2 version, the rehearsal exported it (git archive), set every package to 13.0.0-alpha.3 in that copy, patched the projects to the copy and passed --to 13.0.0-alpha.3. The published alpha.3 CLI targets its own version, so --to is not needed there.

./cargo-rullst-13.0.0-alpha.2-x86_64-unknown-linux-gnu rullst new a2-saas --default \
  --blueprint saas --database sqlite --skip-initial-migration
cargo build && cargo test            # on 13.0.0-alpha.2; commit Cargo.lock
# append [patch.crates-io] entries for every rullst package in Cargo.lock, commit
cargo rullst upgrade --dry-run --to 13.0.0-alpha.3
cargo rullst upgrade --to 13.0.0-alpha.3
# edit what the findings ask for, then
cargo build && cargo test && cargo clippy --all-targets -- -D warnings

Blank, Blank --api, SaaS and LMS starters built on alpha.2 without warnings, and 3, 3, 7 and 11 tests passed. Against the alpha.3 candidate:

V13-ORM-SKIP-MANAGED-COLUMNS is the only finding about an alpha.3 change. The other findings locate APIs whose behaviour changed between 12.x and 13.0.0-alpha.2, so they also appear on a new alpha.2 or alpha.3 starter and need no edit in an application that already runs alpha.2. After the User edit the SaaS and LMS dry runs report 3 and 5 findings, all of that kind. The rehearsal’s CLI applied every rule; the plan now skips the rules an alpha.2 application already runs with (see Rules by release), so its default dry run lists only V13-ORM-SKIP-MANAGED-COLUMNS for SaaS and LMS and nothing for Blank and Blank --api, and --all-rules lists the findings in the table.

An HTTP smoke test of each upgraded starter (db:migrate, then the server in development) passed. In SaaS and LMS, registration stored is_admin = 0 and session_epoch = 0 from the column defaults, “Sign out everywhere” raised the epoch and the earlier cookie was refused, signing in again worked and the loopback Nexus answered 200. Blank and the JSON API answered / and /health, and the API’s bearer POST /api/messages returned 201 (401 without the token).

The same starters generated by the alpha.3 CLI differ from the alpha.2 ones only in the User fields above, in the localized account mail and APP_NAME of the password controller and .env and the checked reset-link lifetime of src/models/password_reset.rs (the “Account mail language and product name” and “Generated reset link lifetime” rows; existing projects keep their code) and in the SaaS users migration, which imports through rullst::db instead of rullst_orm (both compile). The alpha.2 to alpha.3 checklist turns this into steps for a real application.

Limits: SQLite only; the starters use none of the other APIs that alpha.3 removes or changes (Omni, offline-sync, default features, Orm::transaction, mock Connect credentials), so their rules ran only in the catalog’s unit tests; no live mail, billing or OAuth provider was called.

Earlier rehearsals: v12 to v13

.github/rehearse-v12-upgrade.sh is a manual helper (not a CI job) for the v12 to v13 path; its header documents the arguments. In October 2026 it and the published 12.3.0 binary upgraded Blank, Blog, SaaS and LMS starters of the 12.0.0, 12.1.2 and 12.3.0 CLIs to the 13.0.0-alpha.1 workspace with review findings only (5 to 14 per starter, for example V13-GITIGNORE-DATABASES, V13-MODEL-ALL and V13-HEALTH-PROBES) and no source edit, with one exception: the 12.3 SaaS starter still names LemonSqueezyProvider, so cargo fix failed and the project was restored until the Lemon Squeezy branches of src/controllers/billing_controller.rs and the BILLING_STORE_ID lines of .env and .env.example were removed, as V13-CAPITAL-REMOVED describes (that edit also compiles on 12.3). Starters of the 12.0 CLI also carry the build files listed in the migration guide. Those counts predate the alpha.2 and alpha.3 rules and were not re-measured.

v12 → v13 rule classification

Every row of the v13 migration guide is classified for rullst-upgrade-rules-v4:

• (a) must-change: a compile-breaking or API-shape change detectable in application source (12 rows);
• (b) review: changed behaviour worth reviewing when the application uses the affected API, feature or configuration, which the rules locate (101 rows);
• (c) none: no application impact, or not detectable in the application (CLI behaviour, generator output for new projects, opt-in features, fixes of inputs that previously failed) (102 rows).

A row with both a must-change and a review part counts in both. The catalog has 115 rules. A row can map to several rules and a rule to several rows; when a row changes in a later release, update this table and the rule together.

Planned simpler update experience

Since 13.0.0-alpha.4 the CLI never downloads or replaces its own binary. Install a newer CLI with Cargo and its exact version (cargo install cargo-rullst --version =VERSION --locked). At most once a day, in an interactive terminal, the CLI prints that command when crates.io has a newer release of its major; see the CLI reference. The 12.1.0 to 13.0.0-alpha.3 self-updater (update check, update verify, update stage and update install) was removed; the project commands below remain.

cargo rullst update project prepare --project PATH --json copies the Git working directory into private storage and edits only the candidate’s versioned workspace dependencies. It preserves dirty and untracked source, tracked deletions and the root lockfile, including a legacy ignored lockfile. Compare before/ and candidate/ at the reported location and review preparation.json. Builds/tests are not executed and neither execution nor application is authorized. See the preparation limits and exclusions. Use update project verify --prepared PATH --dry-run to inspect its validation commands. Only after reviewing the trusted project, use --allow-project-code to authorize lockfile resolution, locked checks and tests in a fresh private copy. This is not a sandbox; tests inherit your environment and can have external effects. See the verification options and limits. Then update project review --verified PATH --json revalidates the verification record and shows the full dependency diff with a review digest. Use the returned verified_directory; the digest grants no apply authority. Explicit update project apply --verified PATH --approved-review SHA256 applies only the reviewed manifests/root lockfile. The matching recover command restores only that operation and refuses unrelated edits.

The safe-update priority proposes one guided flow for project preparation, validation and approved application. cargo rullst update guided --to VERSION --project PATH composes those commands. Each approval defaults to no and follows its complete review. Version, directories and digests are carried between steps; separate prompts govern trusted project execution/network and original-file application. --offline keeps verification local. Since 13.0.0-alpha.4 the flow no longer installs a CLI (--scope and --root were removed): install the target CLI with Cargo first. See the guided command. File recovery does not replace database backups or application acceptance tests, and updating the CLI alone never updates a deployed application.

The 12.1.0 update mechanism does not implement v13 migrations. The v13 CLI (13.0.0-alpha.4 prerelease) carries its own rule catalog (v12 to v13: source findings); update guided offers a project update only within the installed CLI’s major.

Is this unique?

No. Assisted upgrades are an established framework practice: Rails documents interactive bin/rails app:update, Angular provides ng update, and Dart offers preview/apply analysis fixes through dart fix. Microsoft’s .NET Upgrade Assistant also analyzed and changed projects, although Microsoft now marks it deprecated in favor of its modernization tooling.

Rullst’s useful distinction is the bounded composition: Cargo-workspace-aware TOML edits, a version-selected framework rule catalog, human and JSON plans, controlled snapshots, default rollback, explicit recovery and Cargo gates in one CLI flow. This is a testable design choice, not evidence that Rullst is the first or universally the best updater.

Official references:

• Upgrading Ruby on Rails
• Angular ng update
• Dart dart fix
• .NET Upgrade Assistant overview

Polyglot Persistence

Important

This page describes the v13 prerelease source, and its dependency examples pin the published 13.0.0-alpha.4 exactly: Cargo never selects a prerelease on its own, and a plain "13.0.0-alpha.4" would also accept later alphas (see the v13 migration guide). The v12 line (rullst@12) reached end of life on 16 October 2026; see the release record. Commit Cargo.lock for reproducible builds, and use path dependencies only for checkout-local review.

Rullst keeps explicit relational and specialized persistence contracts. SQLx Active Record supports SQLite, PostgreSQL, MySQL and MariaDB. The Blank starter can instead use Turso/libSQL as its primary database, through a separate typed adapter. MongoDB is for documents, DuckDB for embedded OLAP/analytics, SurrealDB for documents plus bounded read-only graph queries, Qdrant for dense vector search and Redis for selected native structures. No optional adapter silently changes the application’s primary database.

Only the SQLx backends work with the #[derive(Orm)] query builder, Schema, artisan!, Server::with_db, Nexus and Studio’s database pages. The Database Support table lists, backend by backend, what works, which cargo rullst new starters accept it and which CI test runs it against a real server.

Choose the smallest feature

Using the umbrella crate, next to the primary database profile:

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = ["strict-postgres", "orm-mongodb"] }

Available umbrella features are orm-turso, orm-mongodb, orm-duckdb, orm-surrealdb, orm-qdrant and orm-redis. Direct rullst-orm users select turso, mongodb, duckdb, surrealdb, qdrant or redis. There is no feature that enables them all: 13.0 removed the polyglot and orm-polyglot aggregates, so list the adapters the application uses.

The examples below use rullst_orm::… paths, as projects generated by cargo rullst new do: they depend on rullst-orm directly, which #[derive(Orm)] requires because it expands to rullst_orm::… paths. Code that does not derive models can use the same items through the umbrella crate as rullst::orm::….

Features are additive. Prefer one adapter unless the application genuinely uses several, and inspect the final dependency graph with:

cargo tree -e features

The project wizard first asks for a primary backend. SQLite, PostgreSQL, MySQL and MariaDB use SQLx; Turso is offered as the primary database of the Blank starter only, and its choice states what it does not integrate with. The wizard then offers the side stores, each described as one. For a hybrid SQLx application, use one or more explicit flags:

cargo rullst new edge_app --default --database mariadb --turso --mongodb \
  --qdrant --skip-initial-migration

MariaDB shares the SQLx MySQL protocol implementation but has its own live container contract. --turso is additive; --database turso is the explicit primary selection and currently rejects the SQLx-specific SaaS starter.

Turso / libSQL as the primary ORM

Turso-primary is an alternative to SQLx, not another SQLx backend. It works through TursoOrm, TursoModel, TursoRepository and TursoMigration, and does not integrate with Schema, artisan!, Server::with_db, Nexus or Studio’s database pages; #[derive(Orm)] generates the separate TursoModel API described below.

cargo rullst new edge_api --default --api --database turso
cd edge_api
cargo rullst make:model Event --migration
cargo rullst db:migrate

The generated manifest enables orm-turso without a direct SQLx dependency, and the environment contains TURSO_DATABASE_URL, TURSO_AUTH_TOKEN, and TURSO_OFFLINE_PATH rather than a fictitious DATABASE_URL. Models use the same public derive with an explicit backend:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "events", backend = "turso")]
struct Event {
    id: i64,
    label: String,
    active: bool,
}
}

Initialize once before using the generated inherent methods:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, rullst_orm::Orm)]
#[orm(table = "events", backend = "turso")]
struct Event {
    id: i64,
    label: String,
    active: bool,
}
async fn use_turso_model() -> Result<(), Box<dyn std::error::Error>> {
rullst_orm::polyglot::TursoOrm::init_from_env().await?;

let mut event = Event {
    id: 0,
    label: "started".into(),
    active: true,
};
event.save().await?;
let current = Event::find(event.id).await?;
let _ = current;
Ok(())
}
}

TursoOrm::init_from_env reads TURSO_DATABASE_URL, TURSO_AUTH_TOKEN and TURSO_OFFLINE_PATH from the process environment only. The Turso blank starter (cargo rullst new --database turso) instead reads them with rullst::config::project_setting, which falls back to ./.env without loading it into the process, and passes them to TursoConfig::new and with_offline_path; since 13.0.0-alpha.2 it no longer calls dotenvy::dotenv() or depends on dotenvy.

The typed contract includes CRUD, equality filters, ordering, bounded pagination/counts, app-assigned or generated primary keys, checksummed migrations, status, and rollback. An equality filter whose value encodes as NULL (such as Option::None) matches with IS NULL. #[orm(encrypted)] columns store randomized ciphertext, so filtering or ordering on them returns an error instead of silently matching nothing. Generated make:model and make:migration commands retain the Turso backend. It does not yet provide SQLx ORM relations, hooks, automatic timestamps, seed generation, schema auto-diff, or transparent embedded-replica synchronization. Those limits are why only the blank/API starter is currently advertised as Turso-primary. The derive rejects unsupported SQLx-specific model behaviors at compile time instead of silently ignoring their attributes.

Turso / libSQL explicit edge SQL

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    TursoConfig, TursoMigration, TursoQueryLimit, TursoStatement, TursoStore,
    TursoValue,
};

async fn use_edge_sql() -> Result<(), Box<dyn std::error::Error>> {
let config = TursoConfig::new(
    std::env::var("TURSO_DATABASE_URL").unwrap_or_default(),
    std::env::var("TURSO_AUTH_TOKEN").unwrap_or_default(),
);
let edge = TursoStore::connect(config).await?;
let create = TursoStatement::new(
    "CREATE TABLE events (id INTEGER PRIMARY KEY, label TEXT NOT NULL)",
    vec![],
)?;
edge.migrate(vec![TursoMigration::new("m20260829_events", vec![create])?])
    .await?;

edge.execute(TursoStatement::new(
    "INSERT INTO events VALUES (?1, ?2)",
    vec![TursoValue::Integer(1), TursoValue::Text("started".into())],
)?).await?;
let rows = edge.query(
    TursoStatement::new(
        "SELECT id, label FROM events WHERE id = ?1",
        vec![TursoValue::Integer(1)],
    )?,
    TursoQueryLimit::new(100)?,
).await?;
let _ = rows;
Ok(())
}
}

The live path speaks the official Hrana HTTP v3 protocol directly through the workspace’s Rustls-backed HTTP client; it does not embed the native SQLite engine or the legacy remote SDK dependency chain. URLs must use libsql:// or HTTPS; cleartext HTTP requires an explicit loopback-development opt-in. Requests reject redirects and have a 30-second deadline. Tokens and endpoint details are redacted from Debug; remote responses are capped at 16 MiB, result materialization at 1–10,000 rows, each statement at 1,024 positional parameters/8 MiB of parameter data, and each transaction at 1,024 statements/16 MiB of raw SQL plus parameters. SQL result cells can still be large, so applications must also constrain selected columns and data at the schema/query boundary.

An empty or mock_* endpoint selects a single-connection SQLite in-memory fallback, persisted to a file with TursoConfig::with_offline_path (TursoOrm::init_from_env uses TURSO_OFFLINE_PATH, default turso-development.db). It executes real SQL and migrations deterministically but does not simulate remote replication, latency, failover, or Turso Cloud. The live CI contract runs the same API against the official sqld container and proves that a failed multi-statement batch rolls back its earlier writes.

The portable document contract

MongoDB, SurrealDB, and the deterministic offline store implement the same bounded document operations:

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentId, DocumentPage, DocumentRepository,
};

fn bounded_document_inputs() -> Result<(), Box<dyn std::error::Error>> {
let collection = CollectionName::new("audit_events")?;
let id = DocumentId::new("event-2026-0001")?;
let page = DocumentPage::new(0, 50)?;
let _ = (collection, id, page);
Ok(())
}
}

Collection names use a portable ASCII identifier grammar, IDs are bounded to letters, digits, _ and -, and every list requires a 1–500 row page. Models must serialize as objects and must not own the driver ID field (_id for MongoDB, id for SurrealDB); the portable DocumentId owns that concern.

Encrypted export and crash-resumable restore

MongoDB, SurrealDB and the deterministic store also implement DocumentInventory<T>, which retains each validated identifier. That enables one deliberately conservative recovery path without pretending the engines share transactions:

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentRecoveryBinding, DocumentRecoveryKey,
    DocumentRecoveryPolicy, export_document_snapshot,
    restore_document_snapshot,
};

async fn recovery<S, D, Event>(source: &S, destination: &D) -> Result<(), Box<dyn std::error::Error>>
where
    S: rullst_orm::polyglot::DocumentInventory<Event>,
    D: rullst_orm::polyglot::DocumentInventory<Event>,
    Event: serde::Serialize + serde::de::DeserializeOwned + Send + Sync,
{
let collection = CollectionName::new("audit_events")?;
let binding = DocumentRecoveryBinding::try_new(
    "my_application.production",
    collection,
)?;
let key = DocumentRecoveryKey::try_new(
    "recovery-2026-09",
    [42_u8; 32], // load 32 random bytes from a secret manager
)?;
let policy = DocumentRecoveryPolicy::try_new(100, 10_000, 16 * 1024 * 1024)?;

// Persist this opaque envelope in application-owned durable storage.
let snapshot = export_document_snapshot(source, &binding, &key, policy).await?;
let report = restore_document_snapshot(
    destination,
    &snapshot,
    &binding,
    &key,
    policy,
).await?;
assert_eq!(report.verified(), report.inserted() + report.replayed());
Ok(())
}
}

The key uses AES-256-GCM and a fresh nonce; its authenticated data binds the rotation ID, trusted application namespace and exact collection. Key material passes through a zeroizing temporary and key/snapshot Debug output is redacted. The policy permits pages of 1–500, 1–100,000 documents and a 1 KiB–64 MiB plaintext ceiling. Models in this portability path must be JSON objects without either id or _id.

Export scans twice and refuses to seal unequal observations. This detects ordinary concurrent changes, but it is not a database snapshot isolation primitive: pause writers or use a source-side transaction/export facility. Restore accepts only an empty destination or a matching subset left by an earlier attempt. It inserts without replacement, rejects different or extra rows before mutation and verifies an exact final inventory. A failed attempt can retain earlier successful inserts, so retry the same authenticated snapshot. Keep unrelated destination writers paused until verification. The destination database, namespace and collection/table must already be provisioned where the engine requires them; schema or permission failures stay visible and are never reclassified as an empty destination.

The live release matrix exercises MongoDB → SurrealDB → MongoDB. It proves the bounded adapter contract on that runner, not backup retention, key custody, replication, point-in-time recovery, topology failover or vendor operations.

MongoDB

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    CollectionName, DocumentId, DocumentRepository, MongoDbStore,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct AuditEvent {
    action: String,
}

async fn store_audit_event() -> Result<(), Box<dyn std::error::Error>> {
let store = MongoDbStore::<AuditEvent>::connect_or_mock(
    std::env::var("MONGODB_URL").unwrap_or_default(),
    "my_application",
).await?;

store.create(
    &CollectionName::new("audit_events")?,
    &DocumentId::new("event-1")?,
    &AuditEvent { action: "login".into() },
).await?;
Ok(())
}
}

An empty URL or one beginning with mock_/mock:// selects an in-process, deterministic BTreeMap store. A non-mock URL uses the official MongoDB Rust driver. The release contract includes an optional Testcontainers CRUD suite; availability, backups, indexes, topology and authorization remain deployment responsibilities.

SurrealDB documents and graph reads

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    GraphQuery, GraphRepository, SurrealAuth, SurrealConfig, SurrealDbStore,
};

async fn read_graph() -> Result<(), Box<dyn std::error::Error>> {
let config = SurrealConfig::new(
    std::env::var("SURREALDB_URL").unwrap_or_default(),
    "main",
    "application",
    SurrealAuth::bearer(
        std::env::var("SURREALDB_TOKEN").unwrap_or_default(),
    ),
);
let store = SurrealDbStore::<serde_json::Value>::connect_or_mock(config)?;
let query = GraphQuery::read_only(
    "MATCH (person:person)-[knows:knows]->(friend:person) RETURN friend",
    100,
)?;
let rows = store.query_graph(&query).await?;
let _ = rows;
Ok(())
}
}

The adapter uses SurrealDB’s documented HTTP /key, /sql, /rpc and /gql protocol instead of embedding its BSL-licensed SDK. replace runs a typed UPDATE type::record($table, $id) through /rpc rather than PUT /key, which upserts: replacing a missing (for example concurrently deleted) document returns PolyglotError::NotFound instead of recreating it, as on MongoDB. This statement uses SurrealDB 3 function naming. It disables redirects, requires HTTPS outside loopback unless cleartext is explicitly enabled, redacts authentication in Debug, streams through a configurable 1 KiB–8 MiB memory ceiling, and sends namespace/database headers on every scoped request.

Every DocumentId is stored as a string record key, including all-digit IDs such as 9 (sent as a quoted key; SurrealDB would otherwise parse them as numbers). Inventory pages therefore follow the portable string order, 10 before 9, on SurrealDB as on MongoDB. Records written by earlier versions under an ID that SurrealDB parsed as a number, NULL or an exponent (for example 9, null or 1e5) keep that non-string key and are not found by these string IDs; rewrite them under their string key when upgrading.

Graph queries must start with MATCH; semicolons, caller-provided LIMIT, and the INSERT, SET, REMOVE, and DELETE tokens are rejected. The adapter then appends its own 1–1,000 row limit. This is a conservative read boundary, not arbitrary SurrealQL execution or a graph mutation API. The /gql endpoint requires SurrealDB 3.2 or newer and explicit experimental enablement on the 3.2 release line; the live contract pins 3.2.4 and enables that capability.

DuckDB analytics

#![allow(unused)]
fn main() {
use rullst_orm::polyglot::{
    AnalyticsRepository, AnalyticsValue, DuckDbStore, QueryLimit,
};

async fn analyze_events() -> Result<(), Box<dyn std::error::Error>> {
let analytics = DuckDbStore::in_memory().await?;
analytics.execute(
    "CREATE TABLE events (sequence BIGINT, label VARCHAR)",
    vec![],
).await?;
analytics.execute(
    "INSERT INTO events VALUES (?, ?)",
    vec![
        AnalyticsValue::Signed(1),
        AnalyticsValue::Text("started".into()),
    ],
).await?;
let rows = analytics.query(
    "SELECT sequence, label FROM events WHERE sequence >= ?",
    vec![AnalyticsValue::Signed(1)],
    QueryLimit::new(500)?,
).await?;
let _ = rows;
Ok(())
}
}

DuckDB is bundled for a predictable optional build. Its connection is guarded and every native operation runs through Tokio’s blocking worker pool. Dynamic values are prepared parameters; SQL text remains trusted application structure. Results must declare a 1–10,000 row materialization limit. Scalar, decimal, temporal, interval, geometry and binary values are preserved; unsupported complex result types fail with a typed error instead of being guessed.

Specialized Qdrant and Redis stores

Qdrant has a separate dense-vector contract rather than a document or Active Record facade. See RAG Systems & Vector Search for its bounded collection, upsert, delete and cosine-query API. The project wizard and deterministic CLI expose it as the additive --qdrant choice.

Redis native structures are also explicit and namespaced:

#![allow(unused)]
fn main() {
use rullst_orm::{
    RedisDataConfig, RedisDataKey, RedisDataStore, RedisField, RedisMember,
    RedisScanLimit, RedisStructuresRepository, RedisValue,
};

async fn redis_example() -> Result<(), Box<dyn std::error::Error>> {
let config = RedisDataConfig::new(
    std::env::var("REDIS_URL").unwrap_or_default(),
    "my-application",
    std::env::var("REDIS_USERNAME").unwrap_or_default(),
    std::env::var("REDIS_PASSWORD").unwrap_or_default(),
);
let data = RedisDataStore::connect_or_mock(config).await?;
let account = RedisDataKey::new("account:42")?;
data.hash_set(
    &account,
    &RedisField::new("display_name")?,
    &RedisValue::new("Ada")?,
).await?;
data.set_add(&account, &RedisMember::new("reader")?).await?;
let roles = data
    .set_scan(&account, RedisScanLimit::new(100)?)
    .await?;
let _ = roles;
Ok(())
}
}

The adapter also supplies atomic signed hash increments, exact membership, Sorted Set add/top ranking and exact per-structure deletion. Empty or mock_* endpoint/ACL credentials choose the deterministic fallback. Live remote Redis requires rediss://; intentionally unauthenticated development uses the loopback-only constructor. Hash values are capped at 1 MiB, members at 4 KiB, and scans/ranges at 1–1,000 accepted rows. Redis may still allocate a protocol value before client-side validation, so untrusted writers require server ACLs, quotas and isolation. Lists, Streams, cluster/failover, eviction and durable Pub/Sub are not part of this datastore contract.

What this feature does not promise

• no cross-backend transaction, replication, migration, or consistency layer;
• no claim that document databases implement SQL joins or Active Record;
• no automatic choice of a datastore based on a model;
• no managed backups, production credentials, provider homologation, indexes, cluster failover, or performance guarantee;
• no universal “support for every database”.

Run the application’s exact feature set in addition to the full workspace gates. Remote production readiness still requires a disposable live environment, negative authorization tests, backup/restore rehearsal, and operational review.

38. Transactional Outbox & Durable Effects

Use a transactional outbox when a committed database change must eventually produce an external effect even if the application process stops between the two operations. Typical examples are a webhook, an e-mail request, a search projection or a message published to another service.

after_commit is the simpler choice for a best-effort, process-local effect. Outbox is the durable choice. It stores an event in the same relational transaction as the domain mutation, then lets an independent worker claim and deliver it later.

1. Register the schema as a migration

Applications using the built-in SQLx migration runner can register the versioned migration supplied by the ORM:

#![allow(unused)]
fn main() {
use rullst_orm::OutboxMigration;
use rullst_orm::schema::migration::Migration;

fn migrations() -> Vec<Box<dyn Migration>> {
    vec![Box::new(OutboxMigration)]
}
}

In a generated project, add Box::new(rullst::db::OutboxMigration) to the vector returned by get_migrations() in src/migrations/mod.rs, then run cargo rullst db:migrate.

Outbox::install() applies the same idempotent DDL directly and is useful in tests or explicit local setup. It never runs automatically. A production team should review and track the migration through the same deployment process as its domain schema; do not create tables opportunistically while serving a request.

The built-in contract supports the SQLx relational backends: SQLite, PostgreSQL, MySQL and MariaDB. It does not span MongoDB, DuckDB, Turso or SurrealDB transactions.

2. Commit domain state and event together

Choose a stable stream boundary and a deterministic event key. A stream can represent an application or tenant, but it is only a namespace: the framework does not infer authorization from it.

#![allow(unused)]
fn main() {
use rullst_orm::{Error, Orm, Outbox};
use serde_json::json;

async fn create_invoice() -> Result<(), Error> {
Orm::transaction(|_| Box::pin(async move {
    // `?` placeholders are SQLite/MySQL syntax; PostgreSQL uses `$1, $2`.
    let insert = sqlx::query(
        "INSERT INTO invoices (id, status) VALUES (?, ?)"
    )
    .bind(123_i64)
    .bind("issued");
    rullst_orm::execute_query!(insert, execute, pool)?;

    Outbox::enqueue(
        "tenant-42",
        "invoice:123:issued:v1",
        "invoice.issued",
        &json!({"invoice_id": 123}),
    ).await?;

    Ok::<(), Error>(())
})).await?;
Ok(())
}
}

If the transaction rolls back, neither row survives. This also holds when a helper wraps enqueue in its own Orm::transaction and is called from inside another one: the nested call joins the outer transaction through a savepoint, so its outbox row commits or rolls back with the outer transaction. Calling enqueue outside Orm::transaction fails instead of silently opening an unrelated transaction. When the application already owns a raw SQLx transaction, use enqueue_with_tx(&mut transaction, ...).

(stream, event_key) is unique. Repeating the same kind and an equal JSON payload returns the existing event ID with inserted == false, also when a concurrent transaction committed that key after your transaction’s first read (MySQL/MariaDB read the row back with a locking read). Payloads are compared as JSON values, so an object serialized with its keys in another order (for example one built from a HashMap) is the same content; array order and every value still count. Reusing that key for different content is an error; it does not overwrite the original event, and the error does not echo the stream or key.

Streams and event keys are case-sensitive on every backend: order:aB3x and order:Ab3X are different keys, and a worker for tenant-a does not claim events of tenant-A. MySQL/MariaDB declare the key columns with the binary ascii_bin collation for this. A MySQL/MariaDB table created by an earlier version used the server’s case-insensitive default collation; run Outbox::install() once, for example from a new migration, to convert it in place. The conversion rebuilds the table, so schedule it like other DDL.

3. Claim, deliver and acknowledge

Each worker supplies a stable identifier, lease duration and maximum number of claims:

#![allow(unused)]
fn main() {
use rullst_orm::{Error, Outbox};

async fn deliver() -> Result<(), Error> {
if let Some(event) = Outbox::claim_next(
    "tenant-42",
    "webhook-worker-1",
    30, // lease seconds
    8,  // maximum claims
).await? {
    let payload = event.payload()?;

    // Perform the external effect. Pass event.event_key to a provider that
    // supports idempotency, or deduplicate it in the receiving service.
    let delivered = payload.get("invoice_id").is_some();

    if delivered {
        let owned = Outbox::acknowledge(event.id, event.claim_key).await?;
        if !owned {
            // The lease expired or another worker reclaimed the event.
            // Do not assume ownership or mutate the newer claim.
        }
    } else {
        Outbox::fail(
            event.id,
            event.claim_key,
            "provider temporarily unavailable",
            8,  // maximum attempts
            15, // retry delay seconds
        ).await?;
    }
}
Ok(())
}
}

An ACK or failure transition succeeds only for the exact, unexpired random claim token. A failed delivery becomes pending after the bounded delay, or dead_letter when its attempt limit is reached. If a worker dies during its final claim, the next claim sweep moves that expired event to dead-letter instead of retrying forever.

Claims, acknowledgements and failures commit on their own. Calling them inside Orm::transaction returns a validation error, because an acknowledgement there would already be durable if the handler’s transaction later rolled back. Commit the handler’s database work first, then acknowledge.

4. Understand the guarantee

The delivery guarantee is at least once:

1. the worker claims an event;
2. the external provider accepts the effect;
3. the process stops before the database ACK;
4. the lease expires and the event is delivered again.

No local database design can atomically commit an arbitrary remote HTTP side effect. Make the consumer idempotent using the stable stream/event key. Do not use a random key on every retry.

Other explicit limits:

• key fields are 1–128 characters from a bounded ASCII grammar;
• JSON payloads are at most one MiB;
• leases are 1–3,600 seconds, attempts are 1–100 and retry delays are 0–86,400 seconds;
• a failure message is 1–512 bytes without control characters;
• ordering is not guaranteed across retries or concurrent workers;
• generated observers are not automatically converted into outbox events;
• cleanup, retention, tenant authorization and the worker supervision loop belong to the application;
• monitor retry and dead-letter state through your normal database operations.

This separation keeps model saves predictable while giving applications a durable primitive where the event schema and operational policy are explicit.

5. Relay into rullst-messaging

With the umbrella messaging-orm-outbox feature, OrmOutboxRelay<B> maps one exact outbox stream to one topic on any static MessageBroker. It validates the claimed JSON, uses the stream-scoped event_key (the lowercase hex SHA-256 of the stream, /, then the event key) as the broker idempotency key, publishes and then acknowledges the exact ORM claim. Its executable crash-window test stops after the first publish, reclaims the expired event and observes an exact broker replay with only one retained message.

That bridge improves composition; it does not change the guarantee. ORM commit, broker publish and ORM ACK are not one distributed atomic transaction. Operate the claim loop, retry/dead-letter policy, cleanup, authorization and final consumer deduplication explicitly. See Bounded Brokered Messaging for the relay code.

39. Scout Search Providers

Important

Dependency examples pin the v13 prerelease =13.0.0-alpha.4 exactly: Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026 (see the release record). Commit Cargo.lock for reproducible builds. Use path dependencies only when intentionally testing checkout-local changes. The result ordering, SQL fallback, indexed-field, restore()/force_delete() projection and hit-cap rules below describe the v13 prerelease source (13.0.0-alpha.4).

Scout connects a #[orm(searchable)] SQLx model to one search backend. The model database remains authoritative; the search index is a projection updated only after a successful managed commit.

Enable the provider adapters

With the umbrella crate, add orm-scout next to the application’s primary database feature (SQLite here):

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = ["orm-scout", "strict-sqlite"] }

Or enable scout-http directly on rullst-orm. The feature supplies bounded HTTP adapters for Meilisearch, Elasticsearch and Algolia. The in-memory MockSearchEngine is available without the HTTP feature.

The examples use rullst_orm::… paths: #[derive(Orm)], the model’s FromRow included, expands to rullst_orm::… paths, so a crate that derives models depends on rullst-orm directly. Projects generated by cargo rullst new already list it.

Configure one engine

Configuration is process-wide and fail-closed if code tries to replace an already installed engine:

#![allow(unused)]
fn main() {
use rullst_orm::{MeilisearchEngine, set_search_engine};

fn configure() -> Result<(), rullst_orm::Error> {
let engine = MeilisearchEngine::new(
    std::env::var("MEILI_URL").unwrap_or_default(),
    std::env::var("MEILI_API_KEY").unwrap_or_default(),
)?;
set_search_engine(engine)?;
Ok(())
}
}

Empty or mock_* credentials deliberately select the deterministic offline store. That makes local/test behavior explicit and prevents an accidental live call with missing secrets. A keyless Meilisearch or Elasticsearch development server must be selected with MeilisearchEngine::local(...) or ElasticsearchEngine::local(...); those constructors accept only loopback HTTP. Every endpoint must be an origin URL (no credentials, path, query or fragment) using HTTPS, or HTTP on a loopback host, and redirects are disabled.

Algolia normally derives its official API origin from the application ID:

#![allow(unused)]
fn main() {
use rullst_orm::AlgoliaEngine;

fn engine() -> Result<AlgoliaEngine, rullst_orm::Error> {
AlgoliaEngine::new("APPLICATION_ID", "ADMIN_API_KEY")
}
}

AlgoliaEngine::with_endpoint exists for an explicitly configured compatible proxy and applies the same HTTPS/loopback URL policy. Never expose an indexing or admin key to browser code.

Mark and query the model

#![allow(unused)]
fn main() {
use rullst_orm::Orm;

#[derive(Clone, Debug, Orm)]
#[orm(table = "articles", searchable)]
struct Article {
    id: i32,
    title: String,
    body: String,
}

async fn find() -> Result<Vec<Article>, rullst_orm::Error> {
let results = Article::search("transactional outbox").await.get().await?;
Ok(results)
}
}

With an engine, the results follow the provider’s ranking (best hit first, also for first() and paginate()) unless you add order_by(...).

Without a configured engine, Article::search(...) falls back to a SQL LIKE over the model’s persisted columns, excluding #[orm(hidden)], #[orm(encrypted)], #[orm(masked)] and SecretString fields. % and _ in the query match literally rather than as wildcards.

Generated save/update/delete operations, restore() (re-index) and force_delete() (removal) project only after the relational commit. The indexed document omits #[orm(hidden)], #[orm(encrypted)] and #[orm(masked)] fields, so the provider never receives their values; documents indexed by earlier versions should be reindexed. Rollback produces no search write. Provider or search errors remain typed errors; they are not silently converted into an empty result.

The shared adapter boundary enforces:

• index names (the model’s table) of at most 128 bytes that start with a lowercase ASCII letter and contain only lowercase letters, digits, - or _;
• positive i32 document IDs;
• object-shaped JSON documents no larger than one MiB;
• queries no larger than 1,024 bytes and without control characters;
• at most 1,000 parsed hits and a four-MiB response body;
• five-second connect and twenty-second request deadlines;
• disabled redirects and no secret-bearing error bodies.

The hit cap (rullst_orm::scout::MAX_SEARCH_HITS) applies to the whole shared index, before generated tenant, model-wide and soft-delete scopes. For a model with such a scope, an answer of 1,000 IDs is treated as truncated and search() answers from the SQL fallback instead.

Meilisearch and Algolia asynchronous indexing tasks are awaited with a bounded poll loop. Elasticsearch uses refresh=wait_for for the adapter operations.

Choose the durability level

The generated Scout hook is process-local after commit. A provider outage is reported as PostCommit: the model row is already durable and must not be blindly inserted again. This path is suitable when the application can rebuild the index or explicitly retry.

If every projection must survive a process crash, write a versioned search event through Outbox::enqueue in the domain transaction and run the selected engine from an idempotent outbox worker. Rullst does not invent a stable event key or serialize every model hook automatically. See Transactional Outbox & Durable Effects.

Evidence boundaries

The repository runs a real update/search/delete lifecycle against a digest-pinned Meilisearch container. Elasticsearch and Algolia run deterministic offline tests plus local HTTP protocol fixtures that verify paths, headers, payloads, response bounds and ID parsing. Those fixtures do not prove a hosted Algolia account, every Elasticsearch version, cluster failover, ranking quality or production capacity.

41. Tenant-Bound RAG in One Typed Operation

Important

Dependency examples pin the v13 prerelease =13.0.0-alpha.4 exactly: Cargo never selects a prerelease on its own, and the v12 line reached end of life on 16 October 2026 (see the release record). Commit Cargo.lock for reproducible builds. Use path dependencies only when intentionally testing checkout-local changes.

Rullst’s bounded RAG pipeline turns one authenticated question into a guarded embedding, authorized retrieval request, budgeted context, grounded model call, source metadata, and a terminal audit event.

It deliberately does not hide the datastore or invent authorization. The host application still decides who may ask, which records that identity may read, how documents are ingested and deleted, and which embedding model and vector dimensions define an index.

Add the feature

[dependencies]
rullst = { version = "=13.0.0-alpha.4", default-features = false, features = ["ai"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Run the complete offline contract

An empty or mock_* OpenAI key selects Rullst’s deterministic offline provider. Its fixture embeddings have 16 dimensions, so the local index below uses the same exact dimension.

use rullst::ai::rag::{
    InMemoryRagAuditTrail, InMemoryRagRetriever, RagDocument, RagPipeline,
};
use rullst::ai::{providers::openai::OpenAiProvider, AiClient};
use rullst::security::TenantContext;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build this only from verified authentication and membership claims.
    let tenant = TenantContext::try_new("tenant:acme")?;
    let client = AiClient::new(OpenAiProvider::new("mock_rag"));
    let retriever = InMemoryRagRetriever::try_new(1_000, 16)?;

    let content = "Rullst upgrades start with cargo rullst upgrade --dry-run.";
    let vector = client.embed(content).await?;
    let document = RagDocument::try_new(
        &tenant,
        "upgrade-guide",
        content,
        0.0, // The retriever replaces this with cosine similarity.
    )?;
    retriever.upsert(&tenant, document, vector)?;

    let audit = Arc::new(InMemoryRagAuditTrail::new(1_000)?);
    let pipeline = RagPipeline::new(client, retriever, Arc::clone(&audit));
    let response = pipeline
        .answer(&tenant, "How do I preview a framework upgrade?")
        .await?;

    println!("{}", response.answer());
    for source in response.sources() {
        println!(
            "source={} score={} chars={} truncated={}",
            source.document_id(),
            source.score(),
            source.included_chars(),
            source.truncated()
        );
    }

    let events = audit.entries()?;
    println!("recorded {} terminal RAG event(s)", events.len());
    Ok(())
}

Saved as src/main.rs, cargo run prints the deterministic offline answer, one source=upgrade-guide … line and recorded 1 terminal RAG event(s).

The offline provider is a deterministic test fixture, not evidence of live model quality. In a real application, select a live provider explicitly and evaluate its configured model against a versioned domain corpus.

What the pipeline enforces

For each call, RagPipeline:

1. validates the bounded question and runs guarded embedding;
2. passes the trusted TenantContext, query vector, and bounded limit to the application retriever;
3. rejects over-returned or differently tagged documents;
4. runs prompt-injection checks and outbound PII masking on every passage;
5. truncates by per-document and total Unicode-scalar budgets;
6. refuses to generate when no safe context remains;
7. returns only source identifiers, scores, included character counts, and truncation state alongside the answer;
8. records exactly one terminal, secret-minimized audit event, or fails the operation if the required audit sink is unavailable.

Tune budgets with RagConfig::try_new(max_documents, max_document_chars, max_context_chars). The constructor accepts 1–32 documents, 1–32,768 characters per document and 1–131,072 context characters (characters are Unicode scalar values); RagPipeline::with_config accepts only an already validated configuration.

Use an authoritative production retriever

InMemoryRagRetriever is bounded and tenant-partitioned, but it is process local, nondurable, and uses an exact linear cosine scan. It is appropriate for tests, development, and small ephemeral datasets.

Production applications implement the public async RagRetriever trait over their chosen store. A PostgreSQL implementation should put the tenant predicate inside the same parameterized pgvector query that performs similarity ordering. A Qdrant implementation should apply the deployment’s reviewed tenant filter or separate-collection policy. It then creates each RagDocument from the same trusted context passed to retrieve.

The essential shape is:

async fn retrieve(
    &self,
    tenant: &TenantContext,
    query_embedding: &[f32],
    limit: usize,
) -> Result<Vec<RagDocument>, RagRetrievalError> {
    let rows = self.store
        .similar_chunks_for_tenant(&tenant.tenant_id, query_embedding, limit)
        .await
        .map_err(redacted_retrieval_error)?;

    rows.into_iter()
        .map(|row| RagDocument::try_new(tenant, row.id, row.content, row.score))
        .collect()
}

The pipeline verifies the returned tenant tag as defense in depth. That check cannot detect a datastore adapter that incorrectly read another tenant’s row and then falsely relabeled it. Authoritative tenant and ownership filtering must therefore happen in the datastore query itself.

Supply durable, minimized audit evidence

InMemoryRagAuditTrail is useful for local assertions. A single-process service can use the bounded built-in local file:

#![allow(unused)]
fn main() {
use rullst::ai::rag::DurableRagAuditTrail;
use std::sync::Arc;

let audit = Arc::new(DurableRagAuditTrail::try_open(
    "storage/audit/rag.log",
)?);
Ok::<(), Box<dyn std::error::Error>>(())
}

The trail synchronously appends a distinct versioned stream, validates every event/frame on restart and fails closed on corruption, unsafe file types, external length changes and quota exhaustion. The default ceilings are 16 MiB and 4,096 events; try_open_with_max_bytes may select a smaller byte quota. Its SHA-256 frame digest detects corruption but does not authenticate the writer. The host owns trusted directory permissions, exclusive writer access, rotation, retention, backup and export. Multi-instance deployments should implement RagAuditSink over an append-only, access-controlled destination.

The built-in event contains the tenant ID, a SHA-256 digest of the original question, document counts, included context characters, and the terminal outcome. It omits raw questions, passages, vectors, model answers, and provider error bodies. A digest is not encryption and low-entropy questions may be guessable, so do not expose the audit stream as public data.

Security and quality boundaries

• Prompt-injection filtering is heuristic defense in depth, not proof that a passage or answer is safe.
• Source metadata proves which identifiers entered the prompt; it does not prove that the model cited them faithfully or that their contents were true.
• Apply normal output encoding, domain validation, and tool authorization after generation. Never treat model text as an authorized command.
• Keep ingestion, updates, deletions, retention, embedding-model migrations, ANN tuning, backups, and disaster recovery explicit.
• Test cross-tenant denial, empty retrieval, hostile passages, provider failure, datastore failure, audit failure, and context truncation in the host application.

For the lower-level vector-store contracts, see RAG Systems & Vector Search. For the framework’s broader claims and limits, see the capability ledger.

42. Server-Bound OAuth/OIDC Sessions

Rullst Connect manages the browser-to-provider callback challenge: it generates state and PKCE for OAuth 2.0, adds a nonce for OpenID Connect, keeps those private values on the server and consumes them exactly once before validating the callback. It offers two places to keep them:

• a login challenge store (v13, from 13.0.0-alpha.3) in the application’s own database, with only an opaque id in a short-lived cookie. A Rullst application signs users in with its own encrypted session cookie, so this is the path for it, and cargo rullst make:oauth google|github|microsoft|apple generates it;
• a tower-sessions session (axum-session feature), for an Axum application that already runs a SessionManagerLayer.

Either way this removes security-sensitive plumbing from ordinary handlers. It does not choose the application’s account-linking or authorization policy.

Store-backed login

Generate it

In a project with the account model of cargo rullst auth, the SaaS starter or the LMS example (examples/lms):

cargo rullst make:oauth google      # or github, microsoft, apple
cargo rullst db:migrate

The command adds /auth/<provider> and /auth/<provider>/callback (behind the password login’s per-client rate limit), a “Sign in with …” link on the login page, an oauth_identities table (provider and subject, unique) and the oauth, oauth-<database> and application oauth-mock features. The generated callback signs the account in with make_login_cookie_with_epoch, like the password login. A provider email links or creates an account only when the provider verified it; an email that already belongs to an account is refused by default, because registration does not prove that the person who registered it owns the address. See cargo rullst make:oauth for the settings and the linking policy.

Run the command once per provider: the first one creates the shared flow (src/controllers/oauth/mod.rs), the table and its migration; each further provider adds only its module, routes, login link and settings, so Google and GitHub (or all four) share one oauth_identities table, one migration and the same linking policy. A provider identity signs in to one account; linking a second provider to an existing account follows EXISTING_ACCOUNT_POLICY.

What each provider’s identity is:

Microsoft. MICROSOFT_TENANT is required with the credentials and has no default, because it decides who can create accounts: common (any Entra ID organization and personal Microsoft accounts), organizations (any organization), consumers (personal accounts) or one directory (tenant) ID. Rullst Connect verifies the ID token against the tenant’s keys and requires an issuer https://login.microsoftonline.com/<tid>/v2.0 whose tid the tenant choice admits. Microsoft does not verify the email claim: an organization’s administrators can give a user any address, including one of another company. Treating it as verified would let any tenant administrator sign in to an account here (the “nOAuth” pattern). The generated code therefore trusts it only with xms_edov: true, Microsoft’s statement that the address’s domain is verified for the user’s organization (or that the account is a personal one). Add the optional ID-token claims email and xms_edov under Token configuration in the app registration; without them a Microsoft identity cannot create or link an account, and only identities linked before can sign in. Changing EXISTING_ACCOUNT_POLICY does not change this check.

Apple. Apple returns the callback as a cross-site form POST (response_mode=form_post). Browsers send no SameSite=Lax cookie with it, so the generated start uses ChallengeCookie::for_cross_site_post (SameSite=None; Secure), and the command lists /auth/apple/callback in csrf_signed_webhook_paths of Rullst.toml: Apple cannot send this site’s CSRF token, so instead the handler accepts the POST only with the state of the login challenge that this browser’s challenge cookie names, which another site cannot know. The client secret is a five-minute ES256 JWT that Rullst Connect signs for each code exchange from APPLE_TEAM_ID, APPLE_KEY_ID and the .p8 key in APPLE_PRIVATE_KEY (process environment or a secret store; newlines may be written as \n; the command never writes it to a file). AppleProvider::verify_signing_key stops the application at startup when the key cannot sign. Apple sends the user’s name only on the first authorization, in the unsigned user form field; the generated code uses it as the new account’s display name and for nothing else. An Apple email may be a private relay address (…@privaterelay.appleid.com): register the domain of MAIL_FROM with Apple’s Private Email Relay service, or account emails never arrive. Apple accepts only HTTPS return URLs on a registered domain, never localhost, so develop with the mock credentials.

To try a provider without registering an application, run with mock credentials and the offline provider, which sends the browser straight back to the callback (a same-site GET, Apple included) and signs in [email protected]:

GOOGLE_CLIENT_ID=mock_google GOOGLE_CLIENT_SECRET=mock_google \
  cargo run --features oauth-mock

The command prints the mock settings of the provider it added, such as MICROSOFT_TENANT=common MICROSOFT_CLIENT_ID=mock_microsoft MICROSOFT_CLIENT_SECRET=mock_microsoft. Without --features oauth-mock the application stops at startup with an error that names the feature, and staging and production refuse mock credentials.

Or write the two handlers

The store implements ChallengeStore: MemoryChallengeStore for tests and one process, or SqlChallengeStore over the application’s own SQLx pool with the sqlite, postgres or mysql feature of rullst-connect (oauth-sqlite, oauth-postgres or oauth-mysql on the rullst facade, where the module is rullst::connect::challenge). SqlChallengeStore::open creates its table, rullst_connect_login_challenges, when it is missing.

#![allow(unused)]
fn main() {
use axum::http::{HeaderMap, HeaderValue, StatusCode, header};
use axum::response::{IntoResponse, Redirect, Response};
use rullst_connect::challenge::{
    ChallengeCookie, LoginOptions, MemoryChallengeStore, begin_login, finish_login,
};
use rullst_connect::extractors::AuthCallback;
use rullst_connect::providers::GoogleProvider;

/// A redirect that also sets `cookies`.
fn redirect(target: &str, cookies: &[String]) -> Response {
    let mut response = Redirect::to(target).into_response();
    for cookie in cookies {
        if let Ok(value) = HeaderValue::from_str(cookie) {
            response.headers_mut().append(header::SET_COOKIE, value);
        }
    }
    response
}

/// `GET /auth/google`
async fn start(
    store: &MemoryChallengeStore,
    google: &GoogleProvider,
    cookie: &ChallengeCookie,
) -> Response {
    match begin_login(store, google, LoginOptions::oidc("google")).await {
        Ok(login) => redirect(login.url(), &[login.set_cookie(cookie)]),
        Err(_) => StatusCode::SERVICE_UNAVAILABLE.into_response(),
    }
}

/// `GET /auth/google/callback`
async fn callback(
    store: &MemoryChallengeStore,
    google: &GoogleProvider,
    cookie: &ChallengeCookie,
    headers: &HeaderMap,
    params: &AuthCallback,
) -> Response {
    let id = ChallengeCookie::read(
        headers
            .get_all(header::COOKIE)
            .iter()
            .filter_map(|value| value.to_str().ok()),
    );
    match finish_login(store, google, "google", id.as_deref(), params).await {
        Ok(login) if login.user().email_verified == Some(true) => {
            // Map `login.user().id` (the provider subject) to an account and
            // add the application's session cookie here.
            redirect("/dashboard", &[cookie.clear()])
        }
        Ok(_) | Err(_) => StatusCode::BAD_REQUEST.into_response(),
    }
}
}

ChallengeCookie::new("/auth/google", secure) scopes the cookie to the login routes; pass secure the way Rullst Core decides it, Environment::requires_secure_defaults(). The cookie is named rullst_oauth_challenge, so Core also adds Secure to it on every HTTPS request.

Store contract

• begin_login stores the provider name, state, PKCE verifier, nonce (OIDC only) and an optional same-site return page (ReturnPath: an absolute path, never //host or /\host), and returns a fresh ChallengeId: 256 random bits, 43 base64url characters. The challenge lives ten minutes, or less with LoginOptions::with_lifetime.
• The browser holds only the id, in an HttpOnly, SameSite=Lax cookie of at most ten minutes. SameSite=Lax still sends it with the provider’s top-level GET redirect. For a provider that POSTs the callback from its own site (Sign in with Apple), ChallengeCookie::for_cross_site_post makes it SameSite=None; Secure, the only cookie a browser attaches to that POST. Several cookies of that name with different values are refused rather than guessed.
• Stores key rows by a SHA-256 digest of the id, never the id. Consumption is one atomic removal: DELETE … RETURNING on SQLite and PostgreSQL, SELECT … FOR UPDATE then DELETE in one transaction on MySQL, a mutex in memory. Of several concurrent callbacks with one id, exactly one finds it.
• finish_login reports a missing cookie, then an unknown, altered, used or expired id, before it reads the callback; from there the challenge is consumed whatever follows. It compares the state in constant time before it trusts a provider error, then exchanges the code with the stored verifier and nonce. Errors are typed (LoginError, ChallengeError) and carry no state, code, verifier, nonce or id.
• Each store has an entry limit: a save at the limit first deletes expired challenges, then refuses with ChallengeError::CapacityExceeded (purge_expired deletes them on demand). The limit is exact on SQLite and in memory; on PostgreSQL and MySQL concurrent saves can pass it by at most their number.

Concurrent login tabs each have their own challenge, unlike the one active challenge of a tower-sessions session.

Alternative: tower-sessions

The rest of this tutorial covers the axum-session feature.

Enable the session feature

Pin the v13 prerelease exactly (Cargo never selects a prerelease on its own; the v12 line reached end of life, see the release record):

[dependencies]
rullst-connect = { version = "=13.0.0-alpha.4", features = ["axum-session"] }
tower-sessions = "0.15"

Applications should use one immutable compatible version. Add a SessionManagerLayer to the Axum router. MemoryStore is useful for local examples and tests, but it is process-local and is not a production durability or horizontal-scaling strategy.

use tower_sessions::{cookie::SameSite, MemoryStore, SessionManagerLayer};

let sessions = SessionManagerLayer::new(MemoryStore::default())
    .with_http_only(true)
    .with_same_site(SameSite::Lax)
    .with_secure(true);

let app = app.layer(sessions);

SameSite::Lax permits the ordinary top-level OAuth callback, a cross-site GET redirect, while reducing cross-site cookie exposure. It does not cover a provider that returns the callback as a cross-site POST; see Sign in with Apple. Production still requires HTTPS, a durable shared store where multiple instances are used, bounded store retention, protected keys and an explicit reverse-proxy policy.

Start OAuth 2.0 with state and PKCE

Use this path for providers such as GitHub where the application is using an OAuth authorization-code flow without an ID token:

#![allow(unused)]
fn main() {
use axum::response::Redirect;
use rullst_connect::prelude::*;
use tower_sessions::Session;

async fn start_github(
    session: Session,
    github: &GithubProvider,
) -> Result<Redirect, ConnectError> {
    let authorization = begin_oauth_session(&session, github).await?;
    Ok(Redirect::temporary(authorization.url()))
}
}

The returned URL contains the random state and the SHA-256 PKCE challenge. The 64-character verifier is serialized only in the server-side session record. OAuthAuthorization deliberately redacts its URL from Debug output.

Start OpenID Connect with nonce

Use the OIDC variant for Google or a discovered custom OIDC provider:

let authorization = begin_oidc_session(&session, &oidc_provider).await?;
Ok(Redirect::temporary(authorization.url()))

This stores another random value and sends it as nonce. The provider adapter receives that same expected nonce later and validates it against the signed ID token in the adapters whose documented contract includes ID-token validation. The query-string AuthSession callback does not support Apple; see the next section.

Sign in with Apple: form POST callback

AppleProvider always requests response_mode=form_post, which Apple requires when the name or email scope is requested. Apple then returns code, state, id_token and, on the first sign-in only, user in an application/x-www-form-urlencoded POST from appleid.apple.com. Two parts of the query-string flow do not fit that request:

• AuthSession reads the callback from the query string only, so the POST has no state to compare and the extraction fails;
• the POST is cross-site, and browsers send a cookie on a cross-site POST only when it is SameSite=None; Secure. The SameSite::Lax session cookie shown above is not sent, so the callback cannot find its stored challenge.

Do not relax the application’s authenticated session cookie to SameSite=None to work around this. Keep the Apple challenge in a dedicated, short-lived store reached through its own SameSite=None; Secure; HttpOnly cookie scoped to the Apple routes. Without the managed extractor of the next section, validate the posted form with the framework-neutral primitives:

use rullst_connect::extractors::AuthCallback;
use rullst_connect::pkce::{generate_oauth_state, generate_pkce};
use rullst_connect::prelude::*;
use rullst_connect::provider::ExchangeParams;

// Start: generate the same values the managed flow would store.
let state = generate_oauth_state();
let nonce = generate_oauth_state();
let (code_verifier, code_challenge) = generate_pkce();
let mut url = url::Url::parse(
    &apple.redirect_url_with_pkce_and_state(&code_challenge, &state),
)?;
url.query_pairs_mut().append_pair("nonce", &nonce);
// Application-provided: store the three values for ten minutes under a random
// ID and set `apple_challenge=<ID>; Path=/auth/apple; Max-Age=600; Secure;
// HttpOnly; SameSite=None` on the redirect response.
store_apple_challenge(&state, &nonce, &code_verifier).await?;

// Callback: `POST /auth/apple/callback` with a small body limit.
async fn apple_callback(
    axum::Form(callback): axum::Form<AuthCallback>,
) -> Result<ConnectUser, ConnectError> {
    // Application-provided: atomically remove the challenge named by the
    // `apple_challenge` cookie, failing if it is missing or expired.
    let challenge = take_apple_challenge().await?;
    callback.verify_state(&challenge.state)?;
    if let Some(error) = &callback.error {
        return Err(ConnectError::Provider(format!("Apple returned {error}")));
    }
    let code = callback
        .code
        .as_deref()
        .ok_or_else(|| ConnectError::Token("missing code".to_string()))?;
    apple
        .get_user(ExchangeParams {
            auth_code: code,
            code_verifier: Some(&challenge.code_verifier),
            expected_nonce: Some(&challenge.nonce),
        })
        .await
}

AuthCallback ignores the extra id_token and user fields. get_user redeems the code and verifies the returned ID token’s signature, issuer, audience, expiry and nonce. The unsigned user JSON is the only place Apple sends the user’s name; parse it separately if needed and treat it as unverified. After a successful callback, rotate or create the application’s own authenticated session as usual.

Managed form POST callback

AuthSessionForm (added in 13.0.0-alpha.1) is the form POST counterpart of AuthSession. It reads an application/x-www-form-urlencoded POST body of at most 16 KiB, ignores id_token and user, and consumes the same challenge that begin_oidc_session stored, with the same expiry, constant-time state comparison and single use. A non-POST request, another content type or an oversized body is rejected before the challenge is touched.

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

async fn apple_callback(
    callback: AuthSessionForm,
    apple: &AppleProvider,
) -> Result<ConnectUser, ConnectError> {
    apple.get_user(callback.exchange_params()?).await
}
}

The cookie requirement does not change: the session that holds the challenge must be SameSite=None; Secure. Give the Apple start and callback routes their own session layer rather than relaxing the application session:

use tower_sessions::{cookie::SameSite, MemoryStore, SessionManagerLayer};

let apple_challenges = SessionManagerLayer::new(MemoryStore::default())
    .with_name("apple_oauth_challenge")
    .with_path("/auth/apple")
    .with_http_only(true)
    .with_secure(true)
    .with_same_site(SameSite::None);

let apple_routes = Router::new()
    .route("/auth/apple/start", get(start_apple)) // begin_oidc_session
    .route("/auth/apple/callback", post(apple_callback)) // AuthSessionForm
    .layer(apple_challenges);

An inner session layer replaces the outer Session for those routes, so the callback cannot also write the application session. Hand the verified identity over with an application-owned one-time step, for example a random single-use handoff ID that expires within a minute and is redeemed by a same-site route under the application session layer.

Consume the callback

Mount AuthSession directly as an Axum extractor. Extraction parses the real query, removes and immediately saves the stored challenge, rejects expiry or a constant-time state mismatch, and makes a later sequential replay fail:

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

async fn github_callback(
    session: Session,
    callback: AuthSession,
    github: &GithubProvider,
) -> Result<UniversalProfile, ConnectError> {
    let user = github.get_user(callback.exchange_params()?).await?;

    // Rotate the browser session before establishing authenticated identity.
    session
        .cycle_id()
        .await
        .map_err(|error| ConnectError::Session(error.to_string()))?;
    session
        .insert("authenticated_user_id", &user.id)
        .await
        .map_err(|error| ConnectError::Session(error.to_string()))?;

    Ok(user.universal_profile())
}
}

Do not serialize ConnectUser as a credential store. Its public serialization already omits provider tokens, while UniversalProfile is the narrower credential-free identity projection. If an application needs provider refresh tokens, place them in a dedicated encrypted store with explicit rotation and revocation policy.

For a provider that returned both a refresh token and expires_in, construct a bounded process-local coordinator at the trusted time the token response was received:

#![allow(unused)]
fn main() {
use rullst_connect::{AutoRefreshingSession, ConnectError, ConnectUser};
use rullst_connect::prelude::ExposeSecret as _;

async fn call_authorized_endpoint(_: &str) -> Result<(), ConnectError> {
    Ok(())
}

async fn provider_request(
    github: &rullst_connect::providers::GithubProvider,
    user: &ConnectUser,
    token_received_at: u64,
) -> Result<(), ConnectError> {
    let tokens = AutoRefreshingSession::from_user_at(
        github,
        user,
        token_received_at,
    )?;
    let lease = tokens.access_token().await?;
    call_authorized_endpoint(lease.access_token().expose_secret()).await?;
    Ok(())
}
}

AutoRefreshingSession<P> checks a bounded early-expiration window and holds one async process-local refresh gate, so provider refresh calls cannot overlap and waiters reuse the first valid result. It keeps the old refresh credential if the provider does not rotate, adopts a valid rotation, requires the same provider user ID and changes state only after full validation.

Persist refresh state without storing plaintext tokens

Rullst supplies a storage-neutral authenticated envelope. The application still chooses its database/file/secret manager, but the stored token record need not invent its own cryptographic format:

#![allow(unused)]
fn main() {
use rullst_connect::{
    AutoRefreshingSession, EncryptedTokenSnapshot, Provider,
    TokenSnapshotBinding, TokenSnapshotError, TokenSnapshotKey,
};

async fn seal_current_state<P: Provider + ?Sized>(
    session: &AutoRefreshingSession<'_, P>,
    key_bytes: [u8; 32],
    local_account_id: &str,
) -> Result<EncryptedTokenSnapshot, TokenSnapshotError> {
    let state = session.state_snapshot().await;
    let binding = TokenSnapshotBinding::try_new("github", local_account_id)?;
    let key = TokenSnapshotKey::try_new("oauth-primary-2026", key_bytes)?;
    EncryptedTokenSnapshot::seal(&state, &key, &binding)
}
}

Write only EncryptedTokenSnapshot::as_str() to durable storage. On restart:

1. parse the stored string with EncryptedTokenSnapshot::try_from_envelope;
2. read its non-secret key_id() and select that 32-byte key in a secret manager;
3. rebuild the same binding from trusted provider and local-account state;
4. call open, then pass the restored state to AutoRefreshingSession::new.

The AES-256-GCM authentication tag covers the envelope version, key ID, provider and local account, so a copied record fails for another owner. The payload is bounded and revalidated after decryption. Debug output is redacted, and the envelope itself does not implement Display or Serde. The application must still commit each new generation transactionally, rotate/retain keys, authorize the account and revoke local state. Multi-process deployments also need a distributed compare-and-set/lease; retry/backoff, reauthentication and replay of the original API request are deliberately not inferred.

Lifecycle and failure semantics

The managed contract is intentionally small:

• a challenge expires ten minutes after it is created;
• there is one active challenge per browser session;
• starting a second flow replaces the first, so the older browser tab fails;
• authorization URLs must use HTTPS or exact loopback HTTP, contain no URL credentials/fragment, and preserve exactly one generated state and S256 PKCE tuple without a preconfigured nonce;
• the challenge is removed and saved before state, nonce or PKCE-dependent exchange;
• missing, mismatched, expired and later sequential callbacks fail closed;
• the form POST variant accepts only a POST with a form body of at most 16 KiB and leaves the challenge untouched when it rejects the request shape;
• provider error text is bounded before it becomes a typed error;
• callback codes, state, nonce, verifier and authorization URLs are redacted from the managed types’ Debug output.

One active challenge makes replay and lifecycle behavior unambiguous, but it is not the best UX for applications that intentionally support concurrent login tabs. Such an application should use the store-backed login, which keys each attempt by its own opaque id with the same expiry, atomic consumption, constant-time comparison and redaction properties.

The generic tower-sessions store interface does not expose a distributed compare-and-delete. Two requests that already loaded the same record can still race even though each removal is saved immediately. Provider authorization codes are themselves single-use, but account creation/linking and authenticated session establishment must still be idempotent. Deployments requiring a strict distributed callback claim should use the store-backed login, whose SQL stores consume a challenge atomically.

What the application still must prove

Before release, test the exact deployed provider and browser path:

1. The registered redirect URI exactly matches the application route and uses HTTPS outside an exact loopback development host.
2. The session cookie remains Secure and HttpOnly, uses an intentional SameSite policy, and is rotated after successful authentication.
3. Every application instance sees the same durable session store, or routing is deliberately constrained without pretending failover works.
4. Issuer, audience, signature, expiry and nonce checks pass and fail against the provider’s real or restricted environment.
5. Account creation/linking cannot attach an attacker-controlled provider identity to an existing local account.
6. Native or mobile clients do not sign in by sending a provider access token to get_user_from_token: a userinfo response does not prove the token was issued to this application’s client_id. Verify their ID token with verify_id_token (Google, OidcProvider) and a server-issued nonce.
7. Denial, timeout, provider outage and abandoned-login recovery have bounded user-visible behavior without logging credentials.

The local Rullst regressions prove generation, round-trip, mismatch, missing state, expiry, replacement, replay, typed exchange parameters and redaction, and, for the store-backed login, concurrent single consumption on SQLite (and on owned PostgreSQL and MySQL servers in CI). They are not provider certification or deployment evidence.

43. Installable Apps: PWA, Google Play and Microsoft Store