---
name: rust-crud
description: Scaffold a Rust CRUD web application with Axum, SQLite, Askama templates, API key auth, embedded static assets, and Docker deployment. Use when the user wants to build a new Rust web server with CRUD operations.
---

# Rust CRUD Web App

## Overview

Scaffold and build Rust CRUD web applications using Axum + SQLite + Askama templates. The result is a single binary web server with HTML pages, a JSON API, optional API key auth, and Docker deployment.

## Project Structure

```
project-name/
├── src/
│   ├── main.rs         # Entry point, starts the server
│   ├── server.rs       # Axum routes, middleware, handlers, static asset serving
│   ├── db.rs           # SQLite schema, CRUD functions, error types
│   └── auth.rs         # Session/cookie auth (when using login-based auth)
├── templates/          # Askama HTML templates
│   ├── base.html       # Base layout with blocks (title, content)
│   └── *.html          # Pages extend base.html
├── static/             # CSS, fonts, favicons (embedded via rust_embed or served via tower-http)
│   └── styles.css
├── assets/             # Favicons, fonts, images (embedded via rust_embed)
├── .env.example        # Environment variable reference
├── Dockerfile          # Multi-stage build
└── docker-compose.yml  # Compose config with volume for DB persistence
```

## Dependencies (Cargo.toml)

Use these exact crates and features:

```toml
[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
askama = "0.15"
askama_web = { version = "0.15", features = ["axum-0.8"] }
rusqlite = { version = "0.38", features = ["bundled"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
nanoid = "0.4.0"
rust-embed = "8"
dotenvy = "0.15"
subtle = "2"
tracing = "0.1"
tracing-subscriber = "0.3"
rand = "0.8"
tower-http = { version = "0.6", features = ["fs"] }
```

Only add additional crates when the specific app requires them. Do NOT include TUI crates (ratatui, crossterm), CLI crates (clap), or HTTP client crates (reqwest) unless explicitly requested.

- `tracing` + `tracing-subscriber` — structured logging, always include
- `rand` — needed for session token generation when using session-based auth
- `tower-http` — alternative to `rust-embed` for serving static files from disk (simpler during development, no recompile on asset changes)

## Database Layer (db.rs)

Pattern: single-file module with `Arc<Mutex<Connection>>` for thread-safe SQLite access.

### Structure

```rust
use nanoid::nanoid;
use rusqlite::{Connection, params};
use serde::{Deserialize, Serialize};
use std::fmt;
use std::sync::{Arc, Mutex};

pub type Db = Arc<Mutex<Connection>>;

#[derive(Debug)]
pub enum DbError {
    Sqlite(rusqlite::Error),
    LockPoisoned,
}

impl fmt::Display for DbError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            DbError::Sqlite(e) => write!(f, "Database error: {}", e),
            DbError::LockPoisoned => write!(f, "Database lock poisoned"),
        }
    }
}

impl std::error::Error for DbError {}

impl From<rusqlite::Error> for DbError {
    fn from(e: rusqlite::Error) -> Self {
        DbError::Sqlite(e)
    }
}
```

### Key patterns

- **Model struct**: derive `Serialize, Deserialize`, all fields `pub`
- **ID generation**: `nanoid!(10)` for short unique IDs
- **DB path from env**: `std::env::var("APP_DB_PATH").unwrap_or_else(|_| "app.sqlite".to_string())`
- **init_db()**: opens connection, runs `CREATE TABLE IF NOT EXISTS`, returns `Arc<Mutex<Connection>>`
- **CRUD functions**: standalone functions that take `&Db` as first param
  - `create_*` — INSERT, return created model with `last_insert_rowid()`
  - `get_*_by_short_id` — SELECT, return `Result<Option<Model>, DbError>`
  - `get_all_*` — SELECT with ORDER BY id DESC
  - `delete_*_by_short_id` — DELETE, return `Result<bool, DbError>` (rows_affected > 0)
  - `update_*_by_short_id` — UPDATE then SELECT to return updated model
- **Error handling**: `QueryReturnedNoRows` maps to `Ok(None)`, not an error

## Server Layer (server.rs)

### Embedded assets with rust_embed

```rust
use rust_embed::Embed;

#[derive(Embed)]
#[folder = "assets/"]
struct Assets;

#[derive(Embed)]
#[folder = "static/"]
struct Static;
```

Serve with handlers that match on file path and return correct MIME types:

```rust
fn mime_from_path(path: &str) -> &'static str {
    match path.rsplit('.').next().unwrap_or("") {
        "css" => "text/css",
        "js" => "application/javascript",
        "html" => "text/html",
        "png" => "image/png",
        "ico" => "image/x-icon",
        "svg" => "image/svg+xml",
        "woff" | "woff2" => "font/woff2",
        "ttf" => "font/ttf",
        "otf" => "font/otf",
        "json" | "webmanifest" => "application/json",
        _ => "application/octet-stream",
    }
}
```

### App state

```rust
#[derive(Clone)]
struct AppState {
    db: Db,
    server_config: ServerConfig,
}
```

Add domain-specific fields as needed (e.g., a highlighter, cache, etc).

### Askama templates

```rust
use askama::Template;
use askama_web::WebTemplate;

#[derive(Template)]
#[template(path = "index.html")]
struct IndexTemplate;

// Templates with data:
#[derive(Template)]
#[template(path = "item.html")]
struct ItemTemplate {
    name: String,
    content: String,
}
```

Render with `WebTemplate(MyTemplate { ... })`.

### Route structure

Two sets of routes: **web routes** (HTML pages + form submissions) and **API routes** (JSON).

**Web routes:**
- `GET /` — index page (template)
- `GET /admin` — admin panel (template)
- `POST /items` — form submission, redirects on success
- `GET /items/{short_id}` — view single item (template)

**API routes:**
- `GET /api/items` — list all (JSON)
- `POST /api/items` — create (JSON body → 201 + JSON)
- `GET /api/items/{short_id}` — get one (JSON)
- `PUT /api/items/{short_id}` — update (JSON body → JSON)
- `DELETE /api/items/{short_id}` — delete (JSON)

**Static asset routes:**
- `GET /assets/{*path}` — embedded assets (favicons, fonts, images)
- `GET /static/{*path}` — embedded static files (CSS)

### Form deserialization

```rust
#[derive(Deserialize)]
struct CreateItemForm {
    name: String,
    content: String,
}
```

Use `Form(form): Form<CreateItemForm>` for HTML forms, `Json(body): Json<CreateItem>` for API.

### Error responses

- Web handlers return `Result<..., (StatusCode, Html<String>)>`
- API handlers return `Result<..., (StatusCode, Json<serde_json::Value>)>`
- Use `serde_json::json!({"error": "message"})` for API error bodies

## Authentication

### API key auth middleware

Configurable per-endpoint authentication using an API key in the `x-api-key` header. Uses constant-time comparison via the `subtle` crate.

```rust
#[derive(Clone)]
struct ServerConfig {
    api_key: Option<String>,
    auth_endpoints: HashSet<String>,
    max_content_size: usize,
}

impl ServerConfig {
    fn from_env() -> Self {
        let api_key = std::env::var("APP_API_KEY").ok();
        let auth_endpoints = match std::env::var("APP_AUTH_ENDPOINTS") {
            Ok(val) if val.trim().eq_ignore_ascii_case("none") => HashSet::new(),
            Ok(val) => val.split(',').map(|s| s.trim().to_lowercase()).collect(),
            Err(_) => ["api_delete", "api_list", "api_update"]
                .iter().map(|s| s.to_string()).collect(),
        };
        let max_content_size = std::env::var("APP_MAX_CONTENT_SIZE")
            .ok()
            .and_then(|v| v.parse().ok())
            .unwrap_or(512_000);
        ServerConfig { api_key, auth_endpoints, max_content_size }
    }

    fn requires_auth(&self, name: &str) -> bool {
        self.auth_endpoints.contains("all") || self.auth_endpoints.contains(name)
    }
}
```

### Auth middleware function

```rust
async fn require_api_key(
    State(state): State<AppState>,
    headers: HeaderMap,
    request: Request,
    next: Next,
) -> Result<Response, (StatusCode, Json<serde_json::Value>)> {
    let server_key = match &state.server_config.api_key {
        Some(k) => k,
        None => return Err((
            StatusCode::FORBIDDEN,
            Json(serde_json::json!({"error": "No API key configured on server"})),
        )),
    };
    let provided = headers.get("x-api-key").and_then(|v| v.to_str().ok());
    match provided {
        Some(k) if k.as_bytes().ct_eq(server_key.as_bytes()).into() => {
            Ok(next.run(request).await)
        }
        _ => Err((
            StatusCode::UNAUTHORIZED,
            Json(serde_json::json!({"error": "Invalid or missing API key"})),
        )),
    }
}
```

### Dynamic route building with selective auth

Build routes dynamically based on which endpoints require auth. Authed routes get the middleware layer; open routes don't.

```rust
fn build_api_routes(state: &AppState) -> Router<AppState> {
    let config = &state.server_config;
    let auth_layer = middleware::from_fn_with_state(state.clone(), require_api_key);

    let mut authed = Router::new();
    let mut open = Router::new();

    // For each endpoint, add to authed or open router based on config
    if config.requires_auth("api_list") {
        authed = authed.route("/api/items", get(api_list));
    } else {
        open = open.route("/api/items", get(api_list));
    }
    // ... repeat for each endpoint

    let authed = authed.route_layer(auth_layer);
    authed.merge(open)
}
```

### Session/cookie auth (for web-facing apps)

When the app needs a login page instead of API key auth (e.g., personal dashboards), use session-based authentication with a custom Axum extractor. Create a separate `auth.rs` module.

**Sessions table in db.rs:**

```sql
CREATE TABLE IF NOT EXISTS sessions (
    id         INTEGER PRIMARY KEY AUTOINCREMENT,
    token      TEXT NOT NULL UNIQUE,
    expires_at TEXT NOT NULL
);
```

**Session DB functions in db.rs:**

```rust
pub fn insert_session(db: &Db, token: &str, expires_at: &str) -> Result<(), DbError> {
    let conn = db.lock().map_err(|_| DbError::LockPoisoned)?;
    conn.execute("INSERT INTO sessions (token, expires_at) VALUES (?1, ?2)", params![token, expires_at])?;
    Ok(())
}

pub fn get_session_expiry(db: &Db, token: &str) -> Result<Option<String>, DbError> {
    let conn = db.lock().map_err(|_| DbError::LockPoisoned)?;
    match conn.query_row("SELECT expires_at FROM sessions WHERE token = ?1", params![token], |row| row.get(0)) {
        Ok(val) => Ok(Some(val)),
        Err(rusqlite::Error::QueryReturnedNoRows) => Ok(None),
        Err(e) => Err(DbError::Sqlite(e)),
    }
}

pub fn delete_session(db: &Db, token: &str) -> Result<(), DbError> {
    let conn = db.lock().map_err(|_| DbError::LockPoisoned)?;
    conn.execute("DELETE FROM sessions WHERE token = ?1", params![token])?;
    Ok(())
}

pub fn prune_expired_sessions(db: &Db) -> Result<(), DbError> {
    let conn = db.lock().map_err(|_| DbError::LockPoisoned)?;
    conn.execute("DELETE FROM sessions WHERE expires_at < datetime('now')", [])?;
    Ok(())
}
```

**auth.rs module:**

```rust
use axum::{
    extract::{FromRef, FromRequestParts},
    http::request::Parts,
    response::{IntoResponse, Redirect, Response},
};
use rand::RngCore;
use subtle::ConstantTimeEq;

use crate::AppState;

/// Constant-time password comparison with fixed-length buffers.
pub fn verify_password(input: &str, expected: &str) -> bool {
    const LEN: usize = 256;
    let mut a = [0u8; LEN];
    let mut b = [0u8; LEN];
    let ib = input.as_bytes();
    let eb = expected.as_bytes();
    a[..ib.len().min(LEN)].copy_from_slice(&ib[..ib.len().min(LEN)]);
    b[..eb.len().min(LEN)].copy_from_slice(&eb[..eb.len().min(LEN)]);
    let lengths_match = subtle::Choice::from((ib.len() == eb.len()) as u8);
    (lengths_match & a.ct_eq(&b)).into()
}

/// Generate a 32-byte cryptographically random hex token.
pub fn generate_session_token() -> String {
    let mut bytes = [0u8; 32];
    rand::rngs::OsRng.fill_bytes(&mut bytes);
    bytes.iter().map(|b| format!("{:02x}", b)).collect()
}

/// Build a session cookie string.
pub fn build_session_cookie(token: &str, secure: bool) -> String {
    let mut cookie = format!("session={}; HttpOnly; SameSite=Strict; Path=/; Max-Age=604800", token);
    if secure { cookie.push_str("; Secure"); }
    cookie
}

pub fn clear_session_cookie() -> String {
    "session=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0".to_string()
}

/// Axum extractor — guards routes behind login. Redirects to /login if invalid.
pub struct AuthSession;

impl<S> FromRequestParts<S> for AuthSession
where
    S: Send + Sync,
    Arc<AppState>: FromRef<S>,
{
    type Rejection = Response;

    async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
        let state = Arc::<AppState>::from_ref(state);
        let token = extract_session_cookie(&parts.headers);
        if let Some(token) = token {
            if is_valid_session(&state, &token) {
                return Ok(AuthSession);
            }
        }
        Err(Redirect::to("/login").into_response())
    }
}

fn extract_session_cookie(headers: &axum::http::HeaderMap) -> Option<String> {
    let cookie_header = headers.get("cookie")?.to_str().ok()?;
    for part in cookie_header.split(';') {
        let part = part.trim();
        if let Some(val) = part.strip_prefix("session=") {
            let val = val.trim().to_string();
            if !val.is_empty() { return Some(val); }
        }
    }
    None
}
```

**Usage in handlers** — just add `_session: auth::AuthSession` as a parameter to protect a route:

```rust
async fn get_index(_session: auth::AuthSession, State(state): State<Arc<AppState>>) -> Response {
    // only reachable if session is valid
}
```

**Login/logout routes:**

```rust
// GET /login — render login form
// POST /login — verify password, create session, set cookie, redirect to /
// GET /logout — delete session from DB, clear cookie, redirect to /login
```

**AppState for session auth:**

```rust
pub struct AppState {
    pub db: Db,
    pub app_password: String,
    pub cookie_secure: bool,
}
```

### Environment variables

Prefix all env vars with the app name (e.g., `MYAPP_`):

| Variable | Purpose | Default |
|----------|---------|---------|
| `APP_API_KEY` | API key for auth | None (auth disabled) |
| `APP_AUTH_ENDPOINTS` | Comma-separated endpoint names, "all", or "none" | `api_delete,api_list,api_update` |
| `APP_MAX_CONTENT_SIZE` | Max request body size in bytes | `512000` |
| `APP_DB_PATH` | SQLite file path | `app.sqlite` |
| `APP_PASSWORD` | Single password for session auth (web apps) | None |
| `COOKIE_SECURE` | Set `true` for HTTPS-only cookies | `false` |

## Templates (Askama)

HTML templates live in `templates/` and use Askama syntax. Key patterns:

- Link CSS via `/static/styles.css`
- Link assets via `/assets/filename`
- Include `<meta name="theme-color" content="#121113" />`
- Forms POST to web routes (not API routes)
- Use `{{ variable }}` for template interpolation
- Use `{{ variable|safe }}` for pre-rendered HTML (e.g., syntax highlighted content)

### Template inheritance

Use a `base.html` with block sections. All pages extend it:

**templates/base.html:**
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{% block title %}APP_NAME{% endblock %}</title>
  <meta name="theme-color" content="#121113" />
  <style>
    /* base styles here */
  </style>
</head>
<body>
  <div class="container">
    {% block content %}{% endblock %}
  </div>
</body>
</html>
```

**templates/index.html:**
```html
{% extends "base.html" %}
{% block title %}Items{% endblock %}
{% block content %}
  {% if let Some(error) = error %}
    <p class="error">{{ error }}</p>
  {% endif %}
  {% for item in items %}
    <div>{{ item.name }}</div>
  {% endfor %}
{% endblock %}
```

### Flash messages via query params

Pass transient error/success messages through redirects using query parameters. No session flash needed.

**Query param struct:**
```rust
#[derive(Deserialize, Default)]
pub struct FlashQuery {
    pub error: Option<String>,
}
```

**In handlers** — redirect with message:
```rust
Redirect::to("/items/add?error=Name+is+required.").into_response()
```

**In receiving handler** — extract and pass to template:
```rust
async fn get_add(Query(q): Query<FlashQuery>) -> Response {
    render(AddTemplate { error: q.error })
}
```

**In template** — conditionally render:
```html
{% if let Some(error) = error %}
  <p class="error">{{ error }}</p>
{% endif %}
```

## Logging (tracing)

Always initialize tracing in `main()` before anything else:

```rust
tracing_subscriber::fmt::init();
```

Use throughout the app:
- `tracing::error!("DB error: {}", e)` — unrecoverable failures
- `tracing::warn!("Non-critical issue: {}", e)` — degraded but functional
- `tracing::info!("Listening on {}", addr)` — startup/lifecycle events

## main.rs

Minimal — just starts the server:

```rust
mod db;
mod server;

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();
    let host = std::env::var("HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
    let port: u16 = std::env::var("PORT")
        .ok()
        .and_then(|v| v.parse().ok())
        .unwrap_or(3000);
    server::run(host, port).await;
}
```

If the app needs CLI arguments (e.g., `--port`, `--host`), add `clap` and a simple arg struct. But default to env vars and keep main.rs minimal.

## Dockerfile

Multi-stage build:

```dockerfile
FROM rust:1-slim-bookworm AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/APP_NAME /usr/local/bin/APP_NAME
WORKDIR /data
EXPOSE 3000
CMD ["APP_NAME", "--port", "3000", "--host", "0.0.0.0"]
```

Replace `APP_NAME` with the actual binary name.

## docker-compose.yml

```yaml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - APP_API_KEY=${APP_API_KEY:-changeme}
      - APP_AUTH_ENDPOINTS=api_delete,api_list
    volumes:
      - app-data:/data
    restart: unless-stopped

volumes:
  app-data:
```

Key: use a named volume to persist the SQLite database across container restarts.

## .env.example

Always create one with all configurable env vars and sensible comments.

## Checklist

When scaffolding a new app with this pattern:

1. Create project structure (`cargo init`, add directories)
2. Set up `Cargo.toml` with dependencies
3. Write `db.rs` — schema, model struct, CRUD functions
4. Write `server.rs` — config, state, templates, handlers, auth, routes
5. Write `main.rs` — minimal entry point
6. Create `templates/` with at least an index page
7. Create `static/styles.css`
8. Create `.env.example`
9. Create `Dockerfile` and `docker-compose.yml`
10. Test: `cargo run`, verify routes work

## What NOT to include

- No external CSS frameworks unless specified 
- No ORMs — use raw rusqlite
- No connection pools — `Arc<Mutex<Connection>>` is sufficient for SQLite
- No async database drivers — rusqlite is synchronous and that's fine