Skip to main content

Crate runique

Crate runique 

Source
Expand description

§Runique — Django-inspired Rust Framework

Rust Tests passing License Version Crates.io Runique

Runique is a web framework built on Axum, focused on type-safe forms, security middleware, template rendering, ORM integration, and a code-generated admin workflow.

Current state: active development. The framework source of truth is the runique crate. demo-app is used as a validation/testing application for framework behavior.

🌍 Languages: English | Français

§What this repository contains

  • runique/ → framework crate (main product)
  • demo-app/ → test/validation app for framework development
  • docs/ → EN/FR documentation

Workspace version (source of truth): 2.1.21.

§Core capabilities

  • Type-safe form system (forms, extractors, validators, renderers)
  • Routing macros and URL helpers
  • Tera template integration and context helpers
  • Security middleware (CSRF, CSP, allowed hosts, sanitization, auth/session)
  • SeaORM integration + migration tooling
  • Flash message system
  • Admin beta (admin! macro + daemon-generated CRUD code)

Main public modules are exposed from runique/src/lib.rs.

§Installation

git clone https://github.com/seb-alliot/runique
cd runique
cargo build --workspace
cargo test --workspace

Detailed guide: Installation

§Quick usage

use runique::prelude::*;

#[tokio::main]
async fn main() {
    let config = RuniqueConfig::from_env();
    let app = RuniqueApp::builder(config).build().await.unwrap();
    app.run().await.unwrap();
}

§CLI (actual commands)

runique provides:

  • runique new <name>
  • runique start [--main src/main.rs] [--admin src/admin.rs]
  • runique create-superuser
  • runique makemigrations --entities src/entities --migrations migration/src [--force false]
  • runique migration up|down|status --migrations migration/src

⚠️ Warning — rolling back migrations runique makemigrations generates migrations while preserving the chronological order of the migration system. When you need to roll a migration back, prefer the SeaORM CLI: it keeps the migration tracking table synchronized with the actual schema state. Mixing rollback tooling can desynchronize migration tracking.

§Admin beta status

Admin daemon behavior in start:

  • checks whether .with_admin(...) exists in src/main.rs
  • starts the admin watcher when enabled
  • otherwise exits with an explicit hint

Admin resources are declared in src/admin.rs using admin!.

The workflow:

  1. parse admin! declarations
  2. generate admin code under src/admins/
  3. refresh on changes with watcher mode

Current beta limits:

  • mostly resource-level permissions
  • generated folder overwrite (src/admins/)
  • iterative hardening still in progress

Admin docs: Admin

§Features and database backends

Default features:

  • orm
  • all-databases

Selectable backends:

  • sqlite
  • postgres
  • mysql
  • mariadb

§Test and coverage snapshot

  • Reported tests: 2380+ passing
  • Coverage snapshot (2026-06-17, package runique):
    • Functions: 78.17%
    • Lines: 77.26%
    • Regions: 75.46%
cargo llvm-cov --tests --package runique --ignore-filename-regex "admin" --summary-only

§Sessions

CleaningMemoryStore replaces the default MemoryStore with automatic expired-session cleanup, a two-tier watermark system (128 MB / 256 MB), and priority-based protection for authenticated sessions.

  • Low watermark: background purge of expired anonymous sessions
  • High watermark: synchronous emergency purge + 503 refusal if still exceeded
  • protect_session(&session, duration_secs) — marks an anonymous session as untouchable until a given timestamp
  • user_id key — automatically protects authenticated sessions

Full reference: Sessions

§Environment variables

All behavior is configurable via .env. Key variables:

RUNIQUE_SESSION_CLEANUP_SECS=60
RUNIQUE_SESSION_LOW_WATERMARK=134217728
RUNIQUE_SESSION_HIGH_WATERMARK=268435456
SECRET_KEY=your-secret-key
DATABASE_URL=sqlite://db.sqlite3

Full reference: Environment variables

§Documentation

§Project status

For the detailed, continuously updated state report, see PROJECT_STATUS.md.

§Resources

§License

MIT — see LICENSE

Re-exports§

pub use forms::Prisme;
pub use anyhow;
pub use argon2;
pub use async_trait;
pub use axum;
pub use chrono;
pub use hmac;
pub use regex;
pub use sea_orm;
pub use serde;
pub use serde_json;
pub use sha2;
pub use tera;
pub use tokio;
pub use tower;
pub use tower_http;
pub use tower_sessions;
pub use uuid;
pub use dotenvy;
pub use pulldown_cmark;

Modules§

admin
Admin module — administration interface: routes, configuration, reloading daemon, permissions, forms.
app
App module — RuniqueAppBuilder constructor, final RuniqueApp application, build errors, and staging.
auth
Authentication — session, guards, permissions, password reset.
config
Application configuration — server, security, static files, router.
context
Request context — extractors, Request template, extensions, and Tera filters.
db
Database configuration and connection — DatabaseConfig and SeaORM connection helper.
engine
Runique engine — RuniqueEngine centralizes all shared dependencies (Tera, DB, config, registries).
errors
Framework errors — RuniqueError, ErrorContext, ErrorType, and RuniqueResult.
flash
Flash messages — session storage, levels (success/error/info/warning), Axum extractor.
forms
Form system — fields, validation, Tera rendering, Prisme extractor, model forms.
macros
Macros du framework — admin, BDD (objects), contexte Tera, formulaires, routeur, templates.
middleware
Runique middlewares — security (CSP, CSRF, hosts), session, rate limit, error handling.
migration
Migration module — DSL definitions, schemas, columns, FKs, indexes, hooks, relations, and utilities.
prelude
utils
Cross-cutting framework utilities — type aliases, constants, i18n, password, CSRF, mailer, CLI…

Macros§

admin
context
context_update
define_enum_kind
delegate_to_kind
error
extend
Declares a framework table extension — used by makemigrations to generate the corresponding ALTER TABLE ADD COLUMN statements. Has no effect at compile time.
flash_now
impl_form_access
impl_from_error
impl_objects
Adds a Django-style objects manager to a SeaORM entity.
info
model
runique_log
Emits a tracing event at the configured dynamic level.
search
search_cond
success
tpl
tpls
urlpatterns
view
warning

Structs§

LazyLock
A value which is initialized on the first access.