# Runique — Django-inspired Rust Framework

![Rust](https://img.shields.io/badge/rust-1.88%2B-orange)
![Tests passing](https://img.shields.io/badge/tests-2011%2B%20passing-green)
![License](https://img.shields.io/badge/license-MIT-green)
![Version](https://img.shields.io/badge/version-2.1.7-blue)
[![Crates.io](https://img.shields.io/crates/v/runique)](https://crates.io/crates/runique)
[![Runique](https://img.shields.io/badge/Runique-brightgreen)](https://runique.io)

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](https://runique.io/readme/fr)

---

## 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.7**.

---

## 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

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

Detailed guide: [Installation](https://runique.io/docs/en/installation)

---

## Quick usage

```rust,no_run
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**
> The `makemigrations` command generates SeaORM tables while preserving the
> chronological order of the migration system.
> To ensure migration tracking remains consistent, only use the SeaORM CLI
> to apply or manage migrations.
> Using other commands may lead to migration desynchronization.

## 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](https://runique.io/docs/en/admin)

---

## Features and database backends

Default features:

- `orm`
- `all-databases`

Selectable backends:

- `sqlite`
- `postgres`
- `mysql`
- `mariadb`

---

## Test and coverage snapshot

- Reported tests: **2011+ passing**
- Coverage snapshot (`2026-05-24`, package `runique`):
  - Functions: **78.32%**
  - Lines: **76.05%**
  - Regions: **73.93%**

```bash
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](https://runique.io/docs/en/session)

---

## Environment variables

All behavior is configurable via `.env`. Key variables:

```env
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](https://runique.io/docs/en/env)

---

## Documentation

- [Installation](https://runique.io/docs/en/installation)
- [Architecture](https://runique.io/docs/en/architecture)
- [Configuration](https://runique.io/docs/en/configuration)
- [Routing](https://runique.io/docs/en/routing)
- [Forms](https://runique.io/docs/en/formulaire)
- [Model/Schema](https://runique.io/docs/en/model)
- [Templates](https://runique.io/docs/en/template)
- [ORM](https://runique.io/docs/en/orm)
- [Middlewares](https://runique.io/docs/en/middleware)
- [Flash Messages](https://runique.io/docs/en/flash)
- [Examples](https://runique.io/docs/en/exemple)
- [Admin beta](https://runique.io/docs/en/admin)
- [Sessions](https://runique.io/docs/en/session)
- [Environment variables](https://runique.io/docs/en/env)

---

## Project status

For the detailed, continuously updated state report, see [PROJECT_STATUS.md](https://github.com/seb-alliot/runique/blob/main/docs/en/PROJECT_STATUS.en.md).

## Resources

- [Changelog](https://runique.io/changelog)
- [Runique vs Django — Feature Comparison](https://runique.io/docs/en/comparatif)
- [Crates.io](https://crates.io/crates/runique)
- [Security policy](https://github.com/seb-alliot/runique/blob/main/SECURITY.md)

---

## License

MIT — see [LICENSE](https://github.com/seb-alliot/runique/blob/main/LICENSE)
