modo

modo (Latin: "way, method") — a Rust web framework for small monolithic apps.

One crate. Zero proc macros. Everything you need to ship a real app — sessions, auth, background jobs, email, storage — without stitching together 15 crates and writing the glue yourself.

Built on axum 0.8, so you keep full access to the axum/tower ecosystem. Handlers are plain async fn. Routes use axum's Router. Database queries use libsql directly. No magic, no code generation, no framework lock-in.

Why modo

You need 15+ crates for a real Rust web app. Sessions, auth, background jobs, config, email, flash messages, rate limiting, CORS, CSRF — each one is a separate crate with its own patterns, its own wiring, and its own test setup. modo gives you all of it in one import.

Proc macros slow you down. They increase compile times, hide control flow, and make errors cryptic. modo uses zero proc macros. Handlers are plain functions. Routes are axum routes. What you see is what runs.

Wiring everything together is the real work. Config loading, service injection, middleware ordering, graceful shutdown — the framework should handle this, not you. With modo, it's one Registry, one run! macro, and you're done.

Quick look

use modo::{Config, Result};
use modo::axum::{Router, routing::get};
use modo::runtime::Task;

async fn hello() -> &'static str {
    "Hello, modo!"
}

#[tokio::main]
async fn main() -> Result<()> {
    let config: Config = modo::config::load("config/")?;

    let app = Router::new()
        .route("/", get(hello));

    let server = modo::server::http(app, &config.server).await?;
    modo::run!(server).await
}

What's included

Config that just works

YAML files with ${ENV_VAR} and ${ENV_VAR:default} substitution, loaded per APP_ENV. No builder, no manual env parsing, no .env ceremony.

# config/production.yaml
server:
  port: ${PORT:8080}
database:
  url: ${DATABASE_URL}

let config: Config = modo::config::load("config/")?;

Database without an ORM

SQLite via libsql. A single Database handle wraps an Arc-ed connection — clone-friendly, no pool complexity.

let pool = db::connect(&config.database).await?;
db::migrate("migrations/", &pool).await?;

Sessions with zero glue code

Database-backed, signed cookies, sliding expiry, multi-device, fingerprinting. The middleware handles the full request/response lifecycle — you just call methods.

async fn login(session: Session, JsonRequest(form): JsonRequest<LoginForm>) -> Result<()> {
    // ... validate credentials ...
    session.authenticate(user_id).await
}

async fn dashboard(session: Session) -> Result<String> {
    let uid = session.user_id().ok_or(Error::unauthorized("not logged in"))?;
    Ok(format!("Welcome, {uid}"))
}

Auth without a framework

Password hashing (Argon2id), TOTP (Google Authenticator compatible), one-time codes, backup codes, JWT with middleware, OAuth2 (GitHub, Google) — all plain functions and types, no annotations.

let hash = auth::password::hash(password, &PasswordConfig::default()).await?;
let valid = auth::password::verify(password, &hash).await?;

let totp = Totp::from_base32(secret, &TotpConfig::default())?;
let ok = totp.verify(user_code);

Background jobs as plain functions

SQLite-backed queue with retries, exponential backoff, timeouts, scheduled execution, and idempotent enqueue. Handlers use the same extraction pattern as HTTP routes.

async fn send_email(Payload(p): Payload<Email>, Service(mailer): Service<Mailer>) -> Result<()> {
    mailer.send(&p.to, &p.body).await
}

let worker = Worker::builder(&config.job, &registry)
    .register("send_email", send_email)
    .start().await;

Enqueuer::new(&pool).enqueue("send_email", &payload).await?;

Graceful shutdown in one line

The run! macro waits for SIGTERM/SIGINT, then shuts down each component in declaration order. No cancellation tokens, no orchestration code.

modo::run!(worker, server).await

Dependency injection without macros

Registry is a typed map. .add() at startup, Service<T> in handlers. No #[inject], no container config, no runtime reflection.

let mut registry = Registry::new();
registry.add(pool);
registry.add(mailer);

// In any handler:
async fn list_users(Service(pool): Service<Pool>) -> Result<Json<Vec<User>>> { ... }

Request extraction with auto-sanitization

JsonRequest<T>, FormRequest<T>, and Query<T> call your Sanitize impl before the handler runs. Define it once, applied everywhere.

Middleware you'd write anyway

Rate limiting, CORS, CSRF, compression, security headers, request tracing, panic catching, error handler — all included with sensible defaults. All standard Tower layers, not a custom system.

And the rest

Feature flags

Everything above the table is always available. The table modules are opt-in:

[dependencies]
modo-rs = { version = "0.1", features = ["auth", "templates"] }

Re-exports

modo re-exports axum, serde, serde_json, and tokio so you don't need to version-match them yourself.

Claude Code Plugin

The modo-dev plugin gives Claude Code full knowledge of modo's APIs and conventions.

/plugin marketplace add dmitrymomot/modo
/plugin install modo@modo-dev
/reload-plugins

Once installed, it activates automatically when you build with modo. Or invoke it with /modo-dev.

Development

cargo check                                        # type check
cargo test                                         # run tests
cargo test --all-features                          # run all tests
cargo clippy --all-features --tests -- -D warnings # lint
cargo fmt --check                                  # format check

License

Apache-2.0