rullst 12.0.0 - Docs.rs

[!IMPORTANT] Rullst v12.0.0 stable release: version 12 preserves the bounded contracts evaluated through 12.0.0-rc.1 and its documented local, hosted, security, coverage, package, CLI, and blueprint gates. Use an exact crates.io version or immutable tag rather than deploying the moving main branch. The frozen v5 branch preserves legacy source without ongoing maintenance. A versioned crates.io package or immutable tag identifies an artifact; pinning alone does not make end-of-life v5 a supported production recommendation. See the v12 release program and compatibility policy.

Start with a product	Understand the moving parts	Evolve with confidence, not guesswork
Six blueprints, a CLI-driven development loop, and local Studio/Nexus tools.	Typed APIs, generated source, and direct Axum, Tokio, Tower and SQLx integration points.	Sixteen publishable crates, backed-up upgrade tooling, and explicit release evidence.

Choose your first path: Create an application with the CLI · Build a JSON API · Explore the deployed showcase · Explore the ecosystem · Review the current audit

[!NOTE] The public showcase demonstrates Rullst application surfaces and deterministic offline provider fixtures. Its payment URLs are inspectable mock output—not live checkout, provider-account conformance, fiscal authorization, or a production certification. Studio remains a local developer tool, and protected Nexus administration is intentionally unavailable without deployment-specific credentials and policy.

🧪 See Rullst running

The companion Rullst/examples repository keeps independently deployable applications and their deployment source. These public Azure Container Apps were reachable during the v12 closeout review:

Example	Open it	What the deployment demonstrates
Rullst Showcase	Open the web showcase	A deployed Rullst blog/showcase binary with representative SSR, security-header and explicitly labelled offline-provider surfaces.
Rullst LMS Academy	Open the LMS	A separately deployed LMS-blueprint snapshot with a public course catalog and account entry points.
Source and deployment recipes	Review `Rullst/examples`	Application code, containers, workflows and the deployment audit can be inspected independently from the framework source.

These are evolving demonstration deployments maintained outside this framework repository. They prove that the named snapshots can run on Azure Container Apps; they do not certify every Rullst capability, provider, blueprint, native package or deployment configuration. A hosted example may temporarily lag the current CLI output. Native downloads are intentionally not promoted here until their platform signing and physical-device gates are independently verified.

Continuous or change-aware gate	v12 `main` status	Actual scope
Rust CI		Format, all-target/all-feature Clippy, tests on Linux/macOS/Windows, Cargo-aware doctests sourced from all 52 public tutorials, strict DB boundaries, feature boundaries, generated-code checks, and MSRV 1.96.0.
Declared MSRV		Every publishable v12 manifest declares Rust 1.96.0 and CI runs an explicit workspace all-feature check with that toolchain.
GitHub Actions lint		Validates workflow syntax, expressions, embedded shell, and full-SHA third-party Action pins.
Documentation		Builds the mdBook and rejects broken local links and anchors; scheduled/manual runs also preserve an informational external-link report.
End-to-end smoke		Boots the release blog example and verifies HTTP, security headers, form flow, and SQLite persistence.
Codecov — whole repository		The badge and link report the current complete public aggregate. Approved code candidate `a6b3bc8a`: 91.49% (76,685/83,811) with 100% patch coverage (14/14). The enforced target is ≥90% with zero tolerance.
Codecov — framework libraries		Runtime libraries are enforced separately at ≥90%. CLI and proc-macro components stay separately visible; Coverage CI uploads their real LCOV evidence with OIDC.
Cargo Audit		RustSec advisory scan with only governed, expiring exceptions.
Security exception governance		Cross-checks scanner allowlists against the owner/expiry ledger, then independently reruns Cargo Audit.
Cargo Deny		Advisory, license, ban, and source policy.
CodeQL SAST		Rust semantic analysis after an all-target/all-feature build.
OpenSSF Scorecard		The badge renders the score from the official public Scorecard JSON report; the pinned Scorecard workflow publishes OIDC-authenticated results on each `main` push and weekly. A score is evidence, not a security certification.
Cargo Machete		Unused direct dependency detection.
SemVer checks		Supported library APIs are compared with exact latest non-yanked registry baselines; never-published packages and unsupported proc-macro/binary surfaces are reported explicitly.
Zero-panics policy		Denies panic-family operations in published production targets and generated runtime templates.
Unsafe boundary		Denies new production unsafe code outside the reviewed OS/FFI allowlist.
Secret scanning		Verified-secret scan across the configured Git history range.
Spellcheck		Repository-wide typo detection.
Crate architecture policy		Compares the real publishable-crate dependency graph with a versioned, reviewed repository policy.
WebAssembly matrix		Compiles Core, the public facade and macros for browser Wasm and WASI Preview 1.
Bare-metal `no_std` matrix		Builds IoT helpers for Cortex-M and RISC-V targets; this is compile evidence, not hardware testing.
IoT integration		Host tests, signed OTA invariants, and a Cortex-M build.
IoT crypto containment		Path-aware signed OTA, Vault, advisory, and simulator-boundary checks; no PQC/HSM certification claim.
Omni desktop matrix		Generates fresh web shells and checks their Tauri crates on Linux, macOS and Windows; no installer, signing or store claim.
Omni Android compile		Generates a fresh shell and compiles an unsigned Android debug APK; no physical-device, Play testing/signing or store claim.
Omni iOS simulator		Path-aware fresh scaffold generation and compilation on a macOS iOS simulator target; no device, signing or App Store claim.
PR security evidence		Pull-request-only bounded IDOR/RBAC heuristics and CycloneDX SBOM artifact. It intentionally has no continuous `main` status.

Deep or irreversible workflows are intentionally not presented as continuously green main gates:

Deep evidence	Trigger and enforcement
Benchmark regression	Weekly, `main` push, or manual; eight published groups backed by nine Criterion benchmark binaries emit non-blocking alerts at a 20% regression.
Property testing	Weekly/manual release-mode invariant testing with 10,000 configured cases.
TSan and ASan	Daily/manual package matrices on a pinned verifier-only nightly.
Fuzzing / corpus minimization	Forty manual libFuzzer jobs; weekly/manual corpus maintenance is informational.
OWASP ZAP	Manual baseline over three release surfaces: generated REST API and complete LMS are blocking with no ignored alerts; the deliberately CDN-backed blog showcase remains an explicitly informational boundary.
Kani, Miri, mutation testing, cargo-udeps	Manual or scheduled research signals: selected Kani/Miri scopes are strict, while mutation and unused-dependency findings remain explicitly informational.
GitHub Pages	Deploys the v12 documentation from `main`; it is not a code-quality gate.
Release and provenance	Exact version tags only: full verification, package-all, evidence bundle, checksums, GitHub build-provenance attestation, changelog-derived release notes, and ordered crates.io publication. This does not claim a project-wide SLSA level or independent certification.

Scheduled events use the repository's default branch, so scheduled and continuous v12 evidence now refer to main. The recommended required-check profile and the exact scope of all 37 workflow definitions are documented in WORKFLOWS.md.

📖 Read the detailed breakdown of all CI/CD and security workflows.

🧭 Capability Status & Vision Decisions preserves ambitious features that are partial or not implemented, with an explicit recommendation and rationale for each one.

📋 Simple Capability Status and the per-commit quality scorecard keep feature progress separate from SHA-bound engineering evidence.

💡 The Rullst Philosophy

Rullst grew from Venelouis's experience building education platforms with Moodle, then Laravel and AI, and from the desire to bring that feeling of product possibility to Rust without hiding Rust's explicitness. Its APIs and generated code keep security and operational decisions reviewable by humans and coding agents. Read the complete history and design philosophy.

⚡ Quick Start: From Zero to Hero

New to Rust or Rullst? The complete walkthrough covers Rust installation, the stable v12 dependency, the first typed route, error handling, and running the server on Linux, macOS, and Windows:

📖 Build your first Rullst application with the Zero-to-Hero tutorial

🌐 Create and verify your first JSON REST API includes a complete main.rs, secure-header middleware, the run command, and a curl request.

Prefer scaffolding? Follow the v12 CLI installation guide first, then use cargo rullst new my_app and cargo rullst dev from the generated project. Install the exact stable CLI so it matches the generated framework dependency:

cargo install cargo-rullst --version 12.0.0 --locked

Prefer a minimal, hand-written application? Add the stable release and continue with the tutorial's complete src/main.rs:

cargo new my_app
cd my_app
cargo add rullst@12.0.0
cargo add tokio --features full

Keep the generated Cargo.lock, review the documented capability boundaries, and validate your own deployment. A stable framework package is not approval of an application's authentication, authorization, provider configuration, operations, or production environment; pinning legacy v5 does not restore its maintenance or resolve known risks.

Your development control room

Rullst Omni follows a web-first, platform-enhanced architecture: the Rullst web application and server remain canonical, while a generated Tauri shell packages the same experience for desktop, Android and iOS behind an exact-origin navigation boundary and no privileged remote IPC. The portable rullst.client v1 contract gives web and platform code the same bounded typed JSON envelopes without trusting client-supplied roles or ownership. The opt-in native offline-sync foundation adds account-bound encrypted snapshots, idempotent FIFO proposals, explicit conflict/resync/recovery state and a bounded push/pull coordinator over application-owned authenticated transports; platform secure-key/storage, concrete HTTP/background integration and device evidence remain application work, so the shell itself is not advertised as offline-first. See the Omni tutorial and offline-sync tutorial.

🔄 Assisted framework upgrades

The v12 CLI can plan and apply a backed-up framework upgrade from the application root:

cargo rullst upgrade --dry-run
cargo rullst upgrade

It updates the coordinated Rullst dependency train, scans known source risks, applies compiler fixes, runs a Cargo check gate, and restores controlled files after a failure. It does not migrate production data or invent application security policy. See the assisted upgrade tutorial and the v5 → v12 guide.

📚 Documentation & Community

The documentation separates stable behavior, bounded or experimental capabilities, migration guidance, and roadmap boundaries. Explore the guides and evaluate the features your application intends to enable:

👉 Explore the Official Website & Docs

🔑 Maintainer GitHub CLI installation & safe login

💬 Join the Community on Discord

Found a bug? Report an Issue

Build Rullst with us

Start as a user	Improve the framework	Help shape what comes next
Follow the Zero-to-Hero tutorial, then report the first point of friction.	Read the contribution guide, choose a bounded issue, and include evidence with the change.	Review the capability ledger, join Discord, and challenge roadmap assumptions with a concrete use case.

Documentation, tests, reproductions, accessibility reviews, provider contracts, and benchmark methodology are first-class contributions—not secondary work.

⚡ Performance: evidence over slogans

Rullst does not claim to be universally faster than every alternative. Runtime results depend on enabled features, handlers, databases, deployment settings, hardware, and workload. The implementation choices that can be inspected today are:

html! rendering: expands into escaped Rust String construction without a runtime Virtual DOM; dynamic values are escaped by the generated code.
routes! registration: expands at compile time into ordinary, typed Axum route registrations. Request matching and middleware still execute at runtime.
Bounded local primitives: Ammonia allowlist sanitization, RBAC ownership checks, AI heuristics, and the tenant-partitioned in-memory RAG retriever have explicit limits; they are not described as zero-cost.
Development build tuning: generated configuration may select an installed mold or lld. cargo rullst dev and dash rebuild and restart an owned application process, with a same-origin browser refresh after generation readiness. Failed builds keep the current application running; process-local state resets on restart. Observed reload time depends on the host and project.

Eight published Criterion benchmark groups, backed by nine benchmark binaries because the ORM group combines two, track selected microbenchmarks. Their shared-runner history is regression evidence for those inputs, not a production throughput promise. The ORM group also runs five equivalent typed-SQLite operations through pinned Rullst, Diesel and SeaORM dependencies; it preserves unfavorable results and does not claim universal superiority. The separate cross-framework harness currently measures a historical Rullst 4.x application and must not be used as v12 performance evidence until its versions and runs are refreshed.

Open the public benchmark hub for the per-crate dashboards, or read the benchmarking methodology before interpreting a number.

v12 capability highlights

🎨 Studio & Nexus: a loopback-first developer dashboard at :5555 with live telemetry, metadata-only cache inspection and producer-bound, authenticated trace ingestion with explicitly heuristic SQL diagnostics; /nexus is a fail-closed model CRUD panel with explicit metadata, opt-in trusted tenant scoping and transaction-coupled mutation audit.
🛡️ Security helpers: bounded request heuristics for selected XSS, SQLi, traversal, and command-injection indicators plus explicit role/ownership guards. These controls do not replace application authorization or testing.
🔑 Passkeys/WebAuthn: one-time challenge handling and ES256 registration and assertion verification within the documented none-attestation scope; deployments own RP/origin policy and atomic counter persistence.
🌐 Guarded AI client: supported Gemini, Claude, OpenAI, DeepSeek, Ollama, and capability-declared OpenAI-compatible transports with bounded injection heuristics, PII masking, opt-in bounded streaming/cancellation, authenticated audit export and adaptive evaluation reports without raw model content. Passing a heuristic or offline evaluation is not authorization or live-model certification.
💳 Capital adapters: Stripe and LemonSqueezy checkout/webhook adapters use cryptographic HMAC verification; Axum and opt-in Actix middleware share one bounded verifier. The included process-local metrics/event buffer is a preview helper, not an accounting ledger or authoritative MRR.
🔐 Encryption & memory hygiene: #[orm(encrypted)] transparently protects string fields on generated ORM writes/reads using versioned AES-256-GCM, authenticated table/column context, key identifiers, and keyrings. Randomized fields are intentionally not queryable without a separate blind index; key custody and OS/allocator memory exposure remain external.
🔄 Transactions: Orm::transaction scopes generated queries through CURRENT_TX, commits on success, and rolls back on failure; its current closure API returns a boxed future.
📬 Durable outbox: relational domain changes can enqueue an explicit, idempotent event in the same transaction. Lease/token claims, bounded retry and dead-letter are covered on SQLite, PostgreSQL, MySQL and MariaDB; delivery is at least once and consumers remain responsible for idempotency.
🔎 Scout search: an opt-in feature provides bounded Meilisearch, Elasticsearch and Algolia projections with deterministic offline fallbacks; only Meilisearch currently has a live pinned service contract in CI.
🧠 Typed pgvector search: orm-pgvector plus strict-postgres provides SQLx-compatible vectors and parameterized L2/cosine/inner-product queries, exercised against a digest-pinned PostgreSQL + pgvector service. The AI crate separately composes bounded tenant-aware retrieval, guarded context/generation, sources and audit; datastore authorization and index tuning remain application work.
🧭 Specialized vector and key-value stores: orm-qdrant provides bounded dense-cosine collection/upsert/delete/query operations, while orm-redis provides namespaced Hash, Set and Sorted Set operations. Deterministic fallbacks and digest-pinned live lifecycles cover both; hosted availability, cluster/failover and application authorization remain explicit.
🔄 Database introspection: cargo rullst make:models-from-db generates starter model files through parameterized SQLite/PostgreSQL/MySQL metadata queries and fail-closed identifier validation. Table module names are normalized, while columns that would require unsupported ORM remapping are rejected before files are written; bounded type mappings, keys, relations, schemas, and generated code still require review.
🔍 Static project inspection: cargo rullst inspect scans conventional routes! entries and model declarations or prints the generated JSON schema; it is not a runtime route inventory.
🛡️ Zero-panic policy: published production targets are gated against panic!, unwrap, and expect. This is an engineering policy, not a promise that applications or dependencies can never terminate unexpectedly.
⚡ Scaffolding and deployment helpers: generators cover application starting points and deployment manifests; provider CLIs, generated output, infrastructure, and production rollout remain operator-reviewed boundaries.

🌐 Web-first, with explicit frontend boundaries

The v12 wizard generates server-rendered html! pages enhanced with HTMX, or a headless JSON API from the Blank starter. It does not offer equivalent generated profiles for every lower-level frontend foundation below.

Mode	Runtime model	Important boundary
HTMX SSR	The public v12 HTML scaffold	Generated projects serve a pinned local HTMX asset; there is no required project-local SPA build. HTMX is still a browser dependency.
LiveView	Application-owned WebSocket UI foundation	Not a public v12 scaffold profile; lifecycle, origin, backpressure and reconnect behavior need integration tests.
Wasm Islands	Application-owned client WebAssembly	Not an equivalent generator profile; measure bundle size and browser compatibility per application.
Pico.css / Tera	Styling / file-template foundations	Not selectable v12 profiles. Applications own rendering, asset and escaping integration.

🔓 Standard Axum & SQLx Escape Hatches

Rullst is built on Axum, Tokio, Tower, and SQLx, and exposes standard routers and pools at important integration points. Some framework helpers and generated structures still require an explicit migration when ejecting:

Incremental Adoption: Mount existing axum::Router instances directly into rullst::server::Server.
Typed Server Functions: One concrete async Rust signature generates an explicit Axum route and matching Wasm caller over a bounded, versioned protocol—without runtime reflection or silent default values. See the server-functions tutorial.
Standard SQLx: Run raw sqlx::Pool queries alongside rullst-orm without wrappers.
Escape Hatch: Use the CLI eject output as a migration starting point and review the generated code before deployment.
📖 Read the full Axum & SQLx Migration & Escape Hatch Guide.

Choosing Rullst

Rullst is a good fit when an Axum-based application benefits from a coordinated CLI, ORM, authentication helpers, bounded background workers, provider adapters, and local developer tooling in one versioned workspace. A smaller HTTP library may be preferable when the application needs only routing and middleware; a frontend-first framework may be preferable when client component composition is the primary architecture.

For a concise, evidence-bounded explanation of the framework's strongest technical differentiators, read Why Rullst?.

Where it fits in the Rust ecosystem

This is a positioning guide, not a feature-score leaderboard. The projects solve different problems and can sometimes be used together.

Center of gravity	Consider	Why
A coordinated, backend-oriented application stack	Rullst v12	Axum-based routing plus versioned ORM, auth, security helpers, workers, provider adapters, Studio/Nexus, and CLI workflows. The stable release still requires application-specific review and deployment hardening.
A modular HTTP service assembled from selected libraries	Axum or Actix Web	Focused HTTP foundations with their own middleware ecosystems and freedom to choose the rest of the stack.
A Rails-inspired, batteries-included Axum application	Loco	A mature adjacent choice with models, controllers, jobs, mailers, auth, generators, and documented upgrades.
A reactive, isomorphic web UI	Leptos	Fine-grained reactive components spanning browser rendering, SSR, hydration, and server functions.
A shared Rust UI across web, desktop, and mobile	Dioxus	Component-centered cross-platform applications with optional full-stack Axum integration.

Rullst is not presented as universally better. Its distinctive bet is that a single, explicit CLI and release train can coordinate a broad backend stack without hiding the underlying Axum, Tokio, Tower, and SQLx integration points.

Evaluate only the features you intend to enable. In particular:

security middleware is defense-in-depth and does not replace authorization, validation, proxy configuration, or penetration testing;
generated OpenAPI, TypeScript, deployment, and ejection output requires review and compilation in the target application;
Studio is a local developer tool and Nexus requires an explicit authenticated access policy;
live NFS-e, Alipay RSA2, MQTT/CoAP transports, HSM/PQC, S3/R2, and Connect message brokers are not stable capabilities in version 12. IoT packet encoders do not imply those network or hardware integrations.
persistence support is capability-specific: SQLx Active Record targets SQLite/PostgreSQL/MySQL/MariaDB; the bounded blank/API profile can use Turso/libSQL as a typed primary; MongoDB, DuckDB, SurrealDB, Qdrant and Redis retain explicit capability APIs rather than a fictional universal ORM.

🏛️ The Rullst ecosystem

Rullst is a unified monorepo. Core, ORM, Connect, and the domain crates are versioned and tested together so compatibility regressions can be caught in one workspace; consumers should still follow SemVer notes and the release matrix for the exact version they use.

Explore the Monorepo Ecosystem:

🦀 rullst-core: Runtime-only-by-default HTTP server, routing and telemetry kernel with bounded lifecycle-aware readiness/request draining; ORM and SQLite queues are explicit features.
💾 rullst-orm: Active Record, durable opt-in outbox, Scout, pgvector, bounded Qdrant and namespaced Redis structures for SQLite/PostgreSQL/MySQL/MariaDB, a bounded Turso-primary blank/API profile, and capability APIs for MongoDB, DuckDB and SurrealDB; applications still own tenant predicates and database policy. See Polyglot Persistence, Transactional Outbox, Scout Search and RAG/Vector Search.
🛡️ rullst-auth: Passkeys/WebAuthn, Argon2id, encrypted cookie sessions, opt-in application JWT policy, and RBAC authorization.
🔒 rullst-security: Bounded RASP request heuristics, honeypot traps, HTML/CSP helpers, and an HMAC-chained audit log.
🤖 rullst-ai: Guarded provider-agnostic clients (Gemini, OpenAI, Claude, DeepSeek, Ollama), a capability-declared OpenAI-compatible local/cloud adapter, bounded SSE/cancellation, tenant-aware audited RAG, HMAC-authenticated audit export, content-free adaptive evaluation reports, structured output, and authorized local-tool foundations. See Tenant-Bound RAG.
💰 rullst-capital: SaaS MRR/ARR analytics, payment-provider adapters, bounded provider-specific coupons/trial extensions, shared idempotent Team/Workspace quotas with opt-in four-dialect SQL accounting, and bounded checksum-pinned NFS-e DPS/XSD/XMLDSig/mTLS preparation with signed-environment binding and an authenticated local command journal; live Alipay RSA2 and official NFS-e authorization remain fail-closed roadmap/external-evidence work.
🔌 rullst-connect: OAuth2/OIDC social login with strict discovery, rotating JWKS caches, bounded process-local automatic token refresh, provider/account-bound encrypted refresh snapshots, offline provider fallbacks, an explicitly mounted signed loopback IdP fixture, and an opt-in one-active-challenge tower-sessions state/PKCE/nonce transaction. Queue transports currently live in Core.
📨 rullst-messaging: Versioned bounded envelopes, topic-scoped idempotent publication, consumer-group fan-out, expiring ACK leases, retry/DLQ, a canonical envelope codec, allowlisted W3C trace context, a deterministic process-local broker and durable local SQLite with an explicit AES-256-GCM header/payload profile. Metadata remains visible and the codec is not a transport; remote Kafka/RabbitMQ/Redis Streams/NATS/cloud adapters remain roadmap work. See Bounded Brokered Messaging.
📡 rullst-iot: no_std telemetry/frame helpers, Ed25519-signed OTA manifest verification, and a durable rollback-counter CAS boundary; concrete device storage, flashing/bootloader integration, MQTT transport, HSM, and PQC remain roadmap work.
✉️ rullst-mail: Transactional email drivers with mandatory validation, background delivery, opt-in bounded attachment inspection, shared-local suppression and secret-minimized observations, plus safe fiscal-receipt and dunning scaffolds.
📊 rullst-studio: Loopback-first Developer Control Room (:5555) with live telemetry, bounded SQLx data-browser mutations, metadata-only cache inspection and producer-bound authenticated trace ingestion; it is not a remote production admin or OTLP backend.
⚙️ rullst-nexus: Fail-closed registered-model Admin CMS (/nexus) with opt-in trusted tenant scope, transaction-coupled mutation audit, and a local security-event view.
🛠️ cargo-rullst: CLI scaffolding, bounded AST IDOR checks, and deployment helpers.

Rullst is an opinionated, Axum-based full-stack framework for teams that want coordinated Rust tooling without hiding application security boundaries.

Start building · Make your first contribution · Meet the community · Website privacy notice