`; [frontend-htmx](frontend-htmx.md#assets--cache-busting-kernelassetsrs)). An mtime check can't do this: Tailwind 4 doesn't rewrite unchanged output. ```rust // src/kernel/css.rs (next to missing_classes) /// The development CSS banner: the CSS is missing, or stale (template classes with no rule). pub fn css_warning() -> Option { if let Some(problem) = crate::kernel::assets::app_css_problem() { return Some(problem); } let missing = missing_classes()?; let first = missing.first()?; Some(format!( "{CSS_BUILT} is stale: {} template class(es) have no CSS rule (first: {first}). bin/dev rebuilds it.", missing.len() )) } // the Ctx extractor: css_warning: if s.config.is_development() { crate::kernel::css::css_warning() } else { None }, ``` ## No `confirm()` dialogs in kernel pages Kernel pages aren't boosted, so `hx-confirm` never fires there, and a native `confirm()` dialog would block the browser smoke tool. Destructive kernel actions are either cheap and dev-only (mailbox **Clear all**, deleting a job: no prompt), or go through a **server-rendered confirmation page** ("Retry 1,234 jobs?", which posts back with `confirmed=1`). If an app page needs a quick confirm, use `data-confirm="…"` on the form, handled in `static/app.js` (`submit` listener calling `confirm()`), and make browser tests accept dialogs (`page.on('dialog', d => d.accept())`). ## Pending migrations Like Rails' pending-migration error page and Phoenix's "There are pending migrations" screen: a database behind the code shows a clear page, not a "no such table" 500. `src/controllers/migrations.rs` (generated by `new`): ```rust /// Read-only: never creates seaql_migrations (a fresh database reports every migration pending). pub async fn pending(db: &DatabaseConnection) -> Result, DbErr> { Ok(Migrator::get_pending_migrations_read_only(db).await?.iter().map(|m| m.name().to_owned()).collect()) } pub async fn guard(State(s): State, OriginalUri(uri): OriginalUri, req: Request, next: Next) -> Response; pub async fn run(State(s): State, Form(f): Form) -> Result; // POST /dev/migrations ``` | Environment | Behavior | |-------------|----------| | development | `routes.rs` adds `app.layer(from_fn_with_state(state.clone(), migrations::guard))` **after** the routes and the `.fallback(...)` are added (a layer only wraps what exists when it's applied, so a fallback added later would skip the guard and unknown paths would 404 instead of showing the page). Every request except `/static/*`, `/up` and `POST /dev/migrations` gets a **503 "N pending migrations" page** (kernel layout, so it works before any app table exists) listing them, with a **Run migrations** button: a CSRF-protected form posting `return_to=` to `/dev/migrations`, which runs `Migrator::up`, flashes "Ran N migrations." and redirects back (only to same-site paths) | | production | **Never auto-migrates**: the entrypoint runs `app db migrate` before `serve` ([deployment](deployment.md)). The guard and `/dev/migrations` aren't mounted. `GET /up` returns **503 "pending migrations"** while any is pending, so a deploy that skipped migrating never goes healthy | | worker (`app worker`, inline worker) | Before starting, checks `pending()`. If any are pending it logs **once** `pending migrations: run \`app db migrate\`; worker waiting`, rechecks every 5s (stopping cleanly on shutdown), then logs `migrations applied; worker starting`. It never spams errors against missing tables | **Nothing in `serve` may read an app table before the listener is up.** The guard renders from the kernel layout and `seaql_migrations` alone; everything else that touches app tables at boot (realtime's pub/sub and cluster, the inline worker, a cache warm-up) waits for `pending()` to be empty ([realtime](realtime.md#kernel-spec-srckernelpubsubrs)). **Fresh-database smoke**, after any change to `serve` or to what starts at boot (`bin/dev` migrates first, so it never shows this): ```sh mkdir -p storage/pids && rm -f storage/fresh.sqlite3 PORT=4321 DATABASE_URL='sqlite://storage/fresh.sqlite3?mode=rwc' sh -c 'echo $$ > storage/pids/serve-4321.pid; exec cargo run -q -- serve' & sleep 5 curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4321/ # 503: the pending-migrations page, not a crash curl -s -o /dev/null -w '%{http_code}\n' -X POST -H 'Sec-Fetch-Site: same-origin' -d return_to=/ http://localhost:4321/dev/migrations # 303 sleep 6; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4321/up # 200; the log says "migrations applied; realtime starting" kill "$(cat storage/pids/serve-4321.pid)"; rm -f storage/pids/serve-4321.pid storage/fresh.sqlite3* ``` `bin/dev` runs `cargo run -- db migrate` before serving, and again on every rebuild (`cargo watch -x 'run -q -- db migrate' -x 'run -- serve'`), so the page is mostly seen after a `git pull` with the server stopped, or after a rollback. Tests (`kernel_web_test.rs`): a fully rolled-back dev DB shows the page (with the migration names, the button and `return_to`), `/up` is 503, the kernel stylesheet still loads, the button applies all and redirects back with the flash, no open redirect; production with one pending: `/up` 503, `/` unaffected, `/dev/migrations` 404. ## Browser smoke HTTP tests can't see boosted navigation, `` swaps, the back/forward cache or CSP violations. After changing kernel pages (or the app layout's links into them), drive a real browser: 1. **Preferred: the chrome-devtools MCP** (navigate, click, screenshot, `list_console_messages`), in an isolated context. 2. **When it can't attach** (Chrome's profile lock, CI, a script): the framework ships a ready smoke that launches the installed Chrome headless with a throwaway profile: ```sh BASE=http://localhost:3000 bash .offrails/tools/browser-smoke/run.sh # Linux: CHROME=/usr/bin/google-chrome BASE=… bash .offrails/tools/browser-smoke/run.sh ``` It opens `/dev` directly (styled?; an app's home need not link to it) → seeds 3 mails with the **Send a test email** button (each lands on its message, `/dev/mailbox/`, with the flash "Sent a test email to your mailbox."; the list then shows at least 3) → opens one (styled, sandboxed iframe) → **Clear all** → Back (none of the cleared messages comes back) → Forward (judged by the cleared messages' ids, not an empty list: other smokes `verify --full` runs alongside sign in, and an auth part's "New sign-in" email may arrive meanwhile) → (when `/dev` has an **Enqueue a test job** button) opens and deletes the job → Back (redirected to the list, flash shown), and fails on any CSP violation. Every step waits with `waitForNavigation`/`waitForSelector`, with no fixed sleeps, and seeds only through the dev-only buttons, so it needs no app routes. 3. **Multi-tab live updates** (any app with live pages): open N tabs in one profile on a live page, change something once, and assert every tab updates. It catches the HTTP/1.1 connection pool and an undersized per-user cap ([realtime](realtime.md#many-tabs-stall-http11-vs-http2)). The app supplies a small scenario module, `tests/e2e/live-tabs.scenario.mjs`: `export const path` (the live page), optional `login(page, base)`, `mutate(page, base)` returning a token, and `seen(page, token)` returning whether a tab shows it (the full contract is the header of `.offrails/tools/browser-smoke/smoke-live-tabs.mjs`): ```sh SCENARIO=tests/e2e/live-tabs.scenario.mjs BASE=https://localhost:3000 TABS=12 \ bash .offrails/tools/browser-smoke/run.sh live-tabs ``` It exits 1 if any tab misses the update, and says whether the page was on HTTP/1.1. Run it with 12 and 40 tabs after any realtime change. 4. **Login sticks** (every app with accounts; part of the UI check in the Definition of Done): a real browser with **no certificate overrides** fills and submits the real login (or sign-up) form, then proves a fresh page load is still logged in. It catches the dev-TLS trap above and any cookie a browser refuses (`Secure` on http, `__Host-` with a `Domain`). The scenario exports `login(page, base)` and `loggedIn(page)`: ```sh SCENARIO=tests/e2e/smoke.scenario.mjs BASE= bash .offrails/tools/browser-smoke/run.sh login ``` 5. **axe in both color schemes:** axe-core (WCAG 2.2 AA) on each path with `prefers-color-scheme` emulated light, then dark; logged-out paths from `PATHS` or the scenario's `a11yPaths`, and `a11yAuthPaths` after `login`. It finds a `bg-white` card left light under a body that turned dark. The app's Playwright suite ([test-standards §10](test-standards.md#10-accessibility-wcag-22-aa-in-every-theme)) stays the CI gate; this is the framework's own check, and it needs no Node in the app: ```sh SCENARIO=tests/e2e/smoke.scenario.mjs BASE=… bash .offrails/tools/browser-smoke/run.sh a11y ``` 6. **Every page after a boosted link** (every htmx app): each GET page in `docs/routes.md` on a full load, then reached through a boosted link from `/`; the same buttons must react, with no console errors, and no page may load its own scripts in ``. Signed out, then signed in as the demo account. No npm install (Node ≥ 18 and the installed Chrome); `verify --full` runs it when `BASE` is set ([testing](testing.md#browser-smoke-boosted-navigation)): ```sh BASE= node .offrails/tools/browser-smoke/smoke-boosted.mjs # from the app root ``` **Every smoke launches Chrome without certificate overrides** and starts with a preflight: an untrusted HTTPS certificate fails it with the explanation above, before any check runs. Verified in the reference app: against a forced self-signed certificate (`DEV_CERT_SELF_SIGNED=1`) `login` and `live-tabs` fail at the preflight; against the plain-HTTP fallback and against a trusted certificate both pass, and `live-tabs` reaches 12/12 tabs over h2. **Why it lives in `.offrails/tools/` and not in the app:** htmx-mode apps have no Node toolchain or `package.json`, and this check isn't part of the Definition of Done or CI. So `run.sh` installs `puppeteer-core` (pinned, verified 2026-10-12: 25.13.0, which needs **Node ≥ 22.12**; Node 24 LTS recommended) and `axe-core` (4.13.0) once into `~/.cache/offrails/browser-smoke` and runs a copy of the script from there. The app's dependency tree, lockfiles and stack rules are untouched, and inertia/spa apps use the same script. It's optional tooling for agents and humans; the guaranteed checks remain the Rust tests above. Verified against the bookshelf app: 11/11 checks pass. Removing `hx-boost="false"` from the dev link, or omitting `includeIndicatorStyles:false`, makes it fail. ## For agents These endpoints are your eyes on the running app. Use them in the "ran the app and exercised it" step of the [Definition of Done](../workflow.md#definition-of-done). **Start with introspection**; it answers most "why doesn't X work" questions before you read code: ```sh curl -s $URL/dev/introspect.json | jq '.migrations, .css, .realtime, .url' # $URL: what bin/dev printed (-k never needed) cargo run -q -- introspect | jq '.routes[] | select(.path | test("books"))' curl -s "$URL/dev/mailbox/latest.json?to=ada@example.com" # did the email go out? follow .links[0] cargo run -- jobs list --state discarded --json # did a job fail? cargo run -- jobs stats # is anything stuck? curl -s $URL/dev/system | grep -i pending # forgot to migrate? ``` ================================================================ FILE: guides/errors-and-logging.md (https://rustoffrails.org/docs/guides/errors-and-logging.md) ================================================================ # Errors & Logging > **TL;DR** > - One `AppError` enum in `src/error.rs` maps to responses per flavor (HTML, htmx, Inertia, JSON); handlers use `?`, never `unwrap`. > - Records the user may not know exist are `NotFound`, not `Forbidden`; unique violations go through `sql_err()`, never message matching. > - Panics render the standalone 500 page (`CatchPanicLayer::custom`); error pages are standalone templates with no DB access that load `app.js` for Back/Forward. > - Log once, in `IntoResponse`, with `tracing` (JSON in production); `/up` uses `kernel::db::ping`. > > Read the rest when adding an error variant, changing error pages, or wiring logging. **Use the part.** The `dev-dashboard` [parts](samples.md#the-samples) are this guide built, tested on SQLite and Postgres and security-reviewed, with more on top: traces as waterfalls, a live log tail and insights that rank what's failing, in development; and the `jobs-dashboard` sample groups job errors by root cause. When the product needs this, add the part rather than writing it from this guide: `cargo offrails add-part dev-dashboard` (dependencies come first; [workflow](../workflow.md#when-the-product-grows-a-need-add-the-part)). Keep its `// SECURITY:` markers and the tests its CHECKS.md cites. This guide stays the spec: hand-write from it only when no part fits, or the human declined the part. | Rails | Off Rails | |-------|-----------| | `rescue_from` / exceptions app | `AppError` + `impl IntoResponse` in `src/error.rs` | | `ActiveRecord::RecordNotFound` → 404 | `AppError::NotFound` (and `DbErr::RecordNotFound` maps to it) | | `ActiveRecord::RecordInvalid` → 422 | `AppError::Invalid(Errors)` | | `public/404.html`, `500.html` | `templates/errors/404.html`, `500.html` (htmx); `errors/Show` page (inertia); JSON (api) | | `Rails.logger` | `tracing` | | `config.log_tags = [:request_id]` | `TraceLayer` span with `request_id` | | `/up` | `GET /up`: `kernel::db::ping` (`SELECT 1`), returns 200 or 503 | | Sentry/Honeybadger gems | Only if the interview or a spec asks (log the decision) | ## `src/error.rs` ```rust #[derive(Debug, thiserror::Error)] pub enum AppError { #[error("not found")] NotFound, #[error("unauthorized")] Unauthorized, // not logged in #[error("forbidden")] Forbidden, // logged in, not allowed #[error("invalid")] Invalid(Errors), // validation failed #[error("too many requests")] TooManyRequests, // kernel/rate_limit.rs #[error("unavailable")] Unavailable, // overloaded: pool acquire timed out, live re-fetch gate full #[error(transparent)] Db(DbErr), #[error(transparent)] Template(#[from] askama::Error), #[error(transparent)] Internal(#[from] anyhow::Error), } impl From for AppError { fn from(e: DbErr) -> Self { match e { DbErr::RecordNotFound(_) => AppError::NotFound, // The pool had no free connection within acquire_timeout (5 s): overloaded, not broken. DbErr::ConnectionAcquire(ConnAcquireErr::Timeout) => AppError::Unavailable, other => AppError::Db(other), } } } // + From for AppError → Internal ``` ## Response mapping | Variant | htmx (HTML) | inertia | `/api/*` (JSON) | |---------|-------------|---------|-----------------| | `NotFound` | 404 + `errors/404.html` | 404 `errors/Show` `{status: 404}` | 404 `{"error":"not_found"}` | | `Unauthorized` | 303 → `paths::new_session()` (htmx request: `HX-Redirect` header) | 409 + `X-Inertia-Location: /session/new` (or 303 for a full visit) | 401 `{"error":"unauthorized"}` | | `Forbidden` | 403 + `errors/403.html` | 403 `errors/Show` | 403 `{"error":"forbidden"}` | | `Invalid(e)` | 422 + the `errors/_invalid.html` fragment, a list of full messages (fallback; handlers normally re-render the form themselves) | errors map → `_errors` cookie + **303 redirect back** to `Referer` (fallback: the form's GET path); see frontend-inertia | 422 `{"errors": {"field": ["msg"]}}` | | `TooManyRequests` | 429 | 429 | 429 + `Retry-After` | | `Unavailable` | 503 + `Retry-After: 1` + `errors/500.html` with "busy, retry" wording (htmx fragment requests: empty body) | 503 `errors/Show` | 503 + `Retry-After: 1` `{"error":"unavailable"}` | **Overload is 503 + `Retry-After`, never 408 and never a 30 s hang.** Three things produce it: the pool's `acquire_timeout` (5 s, `kernel::db::connect`), the live re-fetch gate ([realtime](realtime.md#keep-re-fetches-from-starving-user-requests)), and the request `TimeoutLayer` (30 s, `StatusCode::SERVICE_UNAVAILABLE`). The timeout's response comes from tower-http with no headers, so `error::retry_after` (an `axum::middleware::map_response` just outside the timeout, [routing](routing.md#middleware)) adds `Retry-After: 1` to any 503 that lacks one. 408 means the client was too slow to send its request; under a thundering herd the server was the slow one, and a 408 made browsers and proxies treat it as the client's fault. Test: with the gate full, a live re-fetch gets 503 with `Retry-After`; `From` maps `ConnectionAcquire(Timeout)` to `Unavailable` (a unit test). | `Db`, `Template`, `Internal` | 500 + `errors/500.html` | 500 `errors/Show` | 500 `{"error":"internal"}` | **The router fallback is marked.** `controllers::errors::not_found` (the router's `.fallback`) returns `([("x-route-fallback", "1")], AppError::NotFound)`, and `shape_errors` copies that header onto the page it renders. A handler's own 404 (no such record) carries no marker. `security_test.rs`'s routability check uses this to tell "not routed" from "not found" for parameterized paths too. - **How it's wired** (verified in the reference app). `IntoResponse` can't see the request, so: 1. `impl IntoResponse for AppError` returns a bare status response carrying a private `ErrorReport { status, errors: Option, detail: Option }` in its **response extensions**. It logs the 500s here (once). 2. `pub async fn shape_errors(State(state): State, req: Request, next: Next) -> Response`, mounted with `from_fn_with_state`, classifies the request into a `ResponseFlavor`: - `Api` when the path starts with `/api` **or `/streams/`, or `Accept` contains `text/event-stream`**. A logged-out stream must get a 401, not a 303 to the login page: `EventSource` can't follow a redirect to HTML (it errors and retries forever), and the stream path would become the `return_to` page after login; - `Inertia` when `X-Inertia` is present; - `Htmx` when `HX-Request` is present; - `Html` otherwise. It stores the flavor as a request extension, runs the request, and rewrites any response carrying an `ErrorReport` into the flavor's response from the table above: a JSON body, the `_errors` cookie + 303, `HX-Redirect`, or an error page. 3. It sits **outside** the CSRF layer. tower-http's `CsrfLayer::with_rejection_response(|_| AppError::Forbidden.into_response())` makes CSRF rejections flow through the same shaping. Handlers just return `AppError`. This is the one place error responses are shaped. - **Error pages never touch the DB** and never need the layout's current user. They're standalone Askama templates: `templates/errors/{404,403,500}.html`, with no `{% extends %}` and no `ctx`. The page links `/static/app.css` without a digest, and loads `/static/app.js` (`defer`), which reloads on Back/Forward: ```js // static/app.js: error pages have no htmx, so the browser's history needs a nudge window.addEventListener("pageshow", (e) => { if (e.persisted) location.reload(); }); window.addEventListener("popstate", () => { if (!window.htmx) location.reload(); }); ``` Without it, going Forward from a 404 changes the URL but not the page. `500.html` takes `detail: Option`, which is set only in development. - **Never leak internals.** 500 bodies are generic in every environment. Development may add the error chain to the HTML 500 page when `config.env == Development`, and nowhere else. - **Log every 500** at `error!` with the full chain (`{err:#}` / `?err`) inside the request span, so it carries the `request_id`. Log 4xx at `debug!`, or not at all. - Panics: `tower_http::catch_panic::CatchPanicLayer::custom(error::panic_response)` (feature `catch-panic`), so a panic becomes a logged 500 rendered with the standalone `errors/500.html` page, not a dropped connection or a bare text body. It sits outside `shape_errors`, so `shape_errors` can't style it: `panic_response(Box) -> Response` logs the panic message (`String` or `&str` payload) at error level and renders the page itself, without detail. ## Logging `main.rs` initializes `tracing-subscriber` once, as a registry with room for the layers an optional [sample](samples.md) adds (the dev dashboard's log tail and traces) beside the formatter: ```rust use tracing_subscriber::{EnvFilter, Layer, Registry, layer::SubscriberExt, util::SubscriberInitExt}; fn init_tracing(config: &Config) { let filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| { EnvFilter::new(match config.env { AppEnv::Production => "info", _ => "info,myapp=debug,tower_http=debug", }) }); let layers: Vec + Send + Sync>> = vec![ // samples: tracing layers ]; let registry = tracing_subscriber::registry().with(sample_layers(layers)).with(filter); match config.log_format { LogFormat::Json => registry.with(tracing_subscriber::fmt::layer().json()).init(), LogFormat::Pretty => registry.with(tracing_subscriber::fmt::layer()).init(), } } /// The samples' layers, or none at all. // WHY: an empty `Vec` layer answers `Interest::never()` for every callsite, which silences the // whole subscriber (no log line at all, warnings included); `None` is a true no-op // (test: an_app_without_sample_layers_still_logs). fn sample_layers( layers: Vec + Send + Sync>>, ) -> Option + Send + Sync>>> { (!layers.is_empty()).then_some(layers) } #[cfg(test)] mod tests { use super::*; #[test] fn an_app_without_sample_layers_still_logs() { let subscriber = tracing_subscriber::registry() .with(sample_layers(Vec::new())) .with(EnvFilter::new("info")); tracing::subscriber::with_default(subscriber, || { assert!(tracing::enabled!(tracing::Level::WARN)); assert!(!tracing::enabled!(tracing::Level::DEBUG)); }); } } ``` Never pass the `Vec` itself to `.with(…)`: with no layers in it, the app logs **nothing**, not even the boot warnings (found in the samples' host app, whose log went silent; the test above fails on that version). Verified with tracing-subscriber 0.3.23, 2026-10-16. - `TraceLayer::new_for_http().make_span_with(...)` creates a span per request with `method`, `path` (the matched route, not the raw URI with ids, when available), and `request_id` from `SetRequestIdLayer` (`MakeRequestUuid`) + `PropagateRequestIdLayer` (header `x-request-id`). - **Log structured events, not prose:** `info!(post_id = post.id, user_id = user.id, "post published")`. - Workers: one span per job with `job_id`, `worker`, `queue`, `attempt` ([jobs](jobs.md#observability)). - **Never log** passwords, session tokens, reset tokens, `Authorization`/`Cookie` headers, full email bodies, or `DATABASE_URL`/`SMTP_URL` (they contain credentials). Implement `Debug` manually for `Config` (an allowlist: [config](config.md#srcconfigrs)) and for any struct holding a secret. - SeaORM SQL logging stays off (`sqlx_logging(false)`) except while debugging locally. ### Redacting stored error text Error messages quote what failed, and what failed is often a URL with its credentials (`https://deploy:hunter2@api.example.com/v1/hooks?token=…`), or an emailed link with its token. Logging them is bad enough; **storing** them (a job's `errors`, shown on `/admin/jobs`, searched, printed by `app jobs show`) keeps the secret for weeks and shows it to every admin. Text that is stored or shown after the fact goes through `kernel::redact::text` first. `src/kernel/redact.rs`, whole (from the samples' host app, trimmed to free text; compiled, clippy-clean and tested with Rust 1.99, edition 2024, 2026-10-16): ```rust //! Free text with secrets replaced by `[redacted]`, for text that is stored or shown after the //! fact (a job's failure message, an error shown on a dashboard): a URL's `user:password@`, its //! random-looking path segments and secret query values; `key=value` pairs whose key names a //! secret (`password=…`, `api_key=…`); long random-looking words (tokens). //! GUIDE: .offrails/guides/errors-and-logging.md#redacting-stored-error-text /// What a secret becomes. pub const REDACTED: &str = "[redacted]"; /// APP: names whose value is always a secret, whatever it looks like (`x_token` matches `token`). pub const SECRET_PARAMS: &[&str] = &[ "token", "code", "key", "secret", "password", "signature", "sig", "otp", ]; /// A word at least this long that looks random (base64url or hex, with a digit or a capital) is /// treated as a token. const RANDOM_MIN_LEN: usize = 20; // SECURITY: errors often quote the URL that failed, with its credentials; stored or shown error // text goes through here first (test: secrets_in_free_text_are_redacted). pub fn text(s: &str) -> String { let mut out = String::with_capacity(s.len()); let mut word = String::new(); for c in s.chars() { if c.is_whitespace() || matches!(c, '"' | '\'' | '<' | '>' | '(' | ')' | '[' | ']' | '{' | '}' | ',' | ';' | '`') { out.push_str(&word_redacted(&word)); word.clear(); out.push(c); } else { word.push(c); } } out.push_str(&word_redacted(&word)); out } fn word_redacted(word: &str) -> String { if word.is_empty() { return String::new(); } if let Some((scheme, rest)) = word.split_once("://") { let split = rest.find(['/', '?', '#']).unwrap_or(rest.len()); let (authority, tail) = rest.split_at(split); let host = match authority.rsplit_once('@') { Some((_, host)) => format!("{REDACTED}@{host}"), None => authority.to_owned(), }; let (before_fragment, fragment) = match tail.split_once('#') { Some((b, f)) => (b, Some(f)), None => (tail, None), }; let (p, q) = match before_fragment.split_once('?') { Some((p, q)) => (p, Some(q)), None => (before_fragment, None), }; let mut out = format!("{scheme}://{host}{}", path(p)); if let Some(q) = q { out.push('?'); out.push_str(&query(q)); } if let Some(f) = fragment { out.push('#'); out.push_str(&query(f)); } return out; } if let Some((k, v)) = word.split_once(['=', ':']) && !k.is_empty() && !v.is_empty() && (is_secret_param(k.trim_start_matches(['-', '?', '&'])) || looks_random(v)) { let sep = &word[k.len()..k.len() + 1]; return format!("{k}{sep}{REDACTED}"); } if looks_random(word.trim_end_matches(['.', ':'])) { return REDACTED.to_owned(); } word.to_owned() } /// A URL path with random-looking segments (tokens in emailed links) redacted. fn path(path: &str) -> String { path.split('/') .map(|s| if looks_random(s) { REDACTED } else { s }) .collect::>() .join("/") } fn query(q: &str) -> String { q.split('&') .map(|pair| match pair.split_once('=') { Some((k, v)) if is_secret_param(k) || looks_random(v) => format!("{k}={REDACTED}"), Some(_) => pair.to_owned(), None if looks_random(pair) => REDACTED.to_owned(), None => pair.to_owned(), }) .collect::>() .join("&") } fn is_secret_param(name: &str) -> bool { let name = name.to_ascii_lowercase(); SECRET_PARAMS.iter().any(|p| name == *p || name.ends_with(&format!("_{p}"))) } /// Long, URL-safe, and not a lowercase slug: base64url tokens, hex digests, signed blobs. fn looks_random(s: &str) -> bool { s.len() >= RANDOM_MIN_LEN && s.bytes().all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.' | b'~' | b'%')) && s.bytes().any(|b| b.is_ascii_digit() || b.is_ascii_uppercase()) } #[cfg(test)] mod tests { use super::*; const TOKEN: &str = "q8Zr2mX0kLwP4vN7tY1sB9cD3fG6hJ5aE2uI8oQ4rTw"; #[test] fn secrets_in_free_text_are_redacted() { let shown = text(&format!( "GET https://deploy:hunter2@api.example.com/v1/hooks?token=abc123&page=2 failed: 401 (key {TOKEN}); retry with password=swordfish" )); for secret in ["deploy", "hunter2", "abc123", TOKEN, "swordfish"] { assert!(!shown.contains(secret), "{secret} in {shown}"); } assert_eq!( shown, "GET https://[redacted]@api.example.com/v1/hooks?token=[redacted]&page=2 failed: 401 (key [redacted]); retry with password=[redacted]" ); assert_eq!(text(&format!("https://app.example/login_links/{TOKEN}")), "https://app.example/login_links/[redacted]"); // Ordinary text is untouched, and redacting twice changes nothing. let plain = "charging card 42: connection refused (os error 61) at hooks.partner.invalid:443"; assert_eq!(text(plain), plain); assert_eq!(text(&shown), shown); assert_eq!(text("postgres://u:p@db/app"), "postgres://[redacted]@db/app"); } } ``` It's for text, after the fact. It never replaces the rules above: secrets stay out of job args, logs and error pages to begin with. ## Spans **The rule (one, everywhere: the guides, the generators, the snippets, the parts' READMEs):** | What | Attribute | Why | |------|-----------|-----| | a controller action, a public model or service fn, a job's `perform`, a mailer fn | `#[tracing::instrument(skip_all)]` (the default level, INFO) | one or a few per request: production traces name the work | | a helper called many times per request (in a loop, per row), or a step only worth seeing while debugging | `#[tracing::instrument(level = "debug", skip_all)]` | free in production (the filter is `info`: the span is never built); the dev dashboard shows it | | anything | never without `skip_all` | arguments are secrets and personal data more often than not | So each request's traces (the `dev-dashboard` part's waterfalls, any OpenTelemetry layer) name the work it did. The template's actions follow it; so do generated code and the snippets. Add a field only when it's safe and useful, e.g. `#[tracing::instrument(skip_all, fields(id))]` for a record id. **Never put secrets or personal data in span fields** (passwords, tokens, emails, names, request bodies): `skip_all` is the default for that reason, and span fields reach logs and dashboards. ## Health check `GET /up` (in `controllers/health.rs`) calls `kernel::db::ping(&db)` (a `SELECT 1`; raw SQL stays in the kernel) with a 2s timeout and returns `200 "ok"`, or `503` when the database doesn't answer or migrations are pending ([dev-tools](dev-tools.md#pending-migrations)). It doesn't require auth, CSRF, sessions, or logging at info level. Deploy healthchecks point here. ## Gotchas agents get wrong - `.unwrap()` on a query result in a handler, which turns a 404 into a panic. Use `?` and `.ok_or(AppError::NotFound)`. - Returning `Forbidden` for records the user shouldn't know exist. Return `NotFound` when existence itself is private (other users' records). - Matching on `DbErr` message strings. Use `sql_err()` (see models.md). - Logging the same error twice (once in the handler, once in `IntoResponse`). Log in one place: `IntoResponse`. - `anyhow` in model signatures. Models return `AppError`. `anyhow` is for jobs, tasks, `main`, and the `Internal` variant. ================================================================ FILE: guides/frontend-htmx.md (https://rustoffrails.org/docs/guides/frontend-htmx.md) ================================================================ # Frontend: `htmx` mode (Hotwire → htmx) > **TL;DR** > - Askama HTML + htmx 2 (vendored) + Tailwind standalone; no Node except islands. > - The layout's `htmx-config` is required: swap 422/429/5xx (`responseHandling`), `allowEval:false` + `includeIndicatorStyles:false` (CSP), `historyCacheSize:0` + `refreshOnHistoryMiss:true`. > - Extensions (sse) load in the layout, never a page head; links into kernel pages carry `hx-boost="false"`; a 422 re-render sends `HX-Push-Url: false`. > - Fragments for `HX-Request`, full pages otherwise; small behaviors in `static/app.js` (no inline scripts); assets are digested and immutable. > > - Optional: [instant navigation for content sites](#instant-navigation-for-content-sites-optional-recipe) (View Transitions, a CSS progress bar, a versioned stale-while-revalidate service worker, prefetch on intent). > > Read the rest when building pages or partials, adding JS behavior, or using islands. Server-rendered HTML, made dynamic by htmx attributes. No Node, no bundler, no build step for JS. CSS comes from the Tailwind standalone binary. ## Setup (done by `generators/new.md`) **htmx:** vendor the latest **2.x** (this framework's syntax and config are htmx 2; htmx 4 is on npm's `next` tag and is not adopted). **Never type a version from memory.** unpkg resolves the major for you: ```sh mkdir -p static/vendor for pkg in htmx.org/dist/htmx.min.js htmx-ext-sse/dist/sse.min.js; do url=$(curl -sSLf -o /dev/null -w '%{url_effective}' "https://unpkg.com/${pkg%%/*}@2/${pkg#*/}") # → …/htmx.org@2.0.11/dist/htmx.min.js name=${pkg%%/*}; ver=$(printf '%s' "$url" | sed -E "s|.*/${name}@([^/]+)/.*|\1|") curl -sSLf "$url" -o "static/vendor/${name%.org}-$ver.min.js" # htmx-2.0.11.min.js, htmx-ext-sse-2.2.4.min.js done ``` The version lives in the filename. `kernel/assets.rs` finds each file by an exact key (`vendor/htmx-2.`, `vendor/htmx-ext-sse-`) that a test proves matches exactly one file ([assets](#assets--cache-busting-kernelassetsrs)). Verified 2026-10: htmx 2.0.11, htmx-ext-sse 2.2.4. **Tailwind (v4 standalone CLI):** the agent looks up the current v4 tag once (`curl -sSLf -o /dev/null -w '%{url_effective}' https://github.com/tailwindlabs/tailwindcss/releases/latest` → `…/tag/v4.3.3`) and writes it into **`bin/setup-tailwind`** as `TAILWIND_VERSION=v4.3.3`, so every machine, CI and the Docker build get the same binary. `bin/setup` and the Dockerfile both call `bin/setup-tailwind`, which downloads and verifies `bin/tailwindcss` (git-ignored, and in `.dockerignore`). It's `#!/bin/sh`, `set -eu`, then: ```sh os=$(uname -s | sed 's/Darwin/macos/;s/Linux/linux/'); arch=$(uname -m | sed 's/x86_64/x64/;s/aarch64/arm64/') asset="tailwindcss-$os-$arch" # macos-arm64, macos-x64, linux-x64, linux-arm64 (-musl variants exist for Alpine) base="https://github.com/tailwindlabs/tailwindcss/releases/download/$TAILWIND_VERSION" bin/tailwindcss --help 2>/dev/null | grep -q "${TAILWIND_VERSION#v}" && exit 0 # already the pinned version curl -sSLf "$base/$asset" -o bin/tailwindcss && chmod +x bin/tailwindcss curl -sSLf "$base/sha256sums.txt" | grep "/$asset\$" | awk '{print $1" bin/tailwindcss"}' | shasum -a 256 -c - ``` ```css /* assets/app.css */ @import "tailwindcss"; @source "../templates"; /* Askama templates; @source paths are relative to this file */ @source "../static/app.js"; @source "../web/src/islands"; /* ISLANDS: yes only */ /* htmx's own indicator styles, because includeIndicatorStyles is off (CSP) */ .htmx-indicator { opacity: 0; } .htmx-request .htmx-indicator, .htmx-request.htmx-indicator { opacity: 1; transition: opacity 200ms ease-in; } ``` Build: `bin/tailwindcss -i assets/app.css -o static/app.css --minify` (`--watch` in `bin/dev`; `--watch=always` if stdin may close). Verified with v4.3.3: classes inside Askama `{% if %}` blocks are picked up. ## Hotwire → htmx | Hotwire | htmx | |---------|------| | Turbo Drive | `hx-boost="true"` on ``. Links and forms become AJAX with history | | Turbo Frame | `hx-get`/`hx-post` + `hx-target="#id"` + `hx-select="#id"` (or return a partial) | | Turbo Stream (append/replace/remove) | `hx-swap-oob="true"` elements in the response, or `hx-swap="beforeend"` | | `data-turbo-confirm` | `hx-confirm="Delete this post?"` | | `turbo_stream_from` (broadcasts) | SSE extension, see `realtime.md` | | Stimulus controllers | `static/app.js` with event delegation (below) | | Lazy-loaded frame | `hx-get="…" hx-trigger="load"` (or `revealed`) | | Turbo morphing refresh | `hx-get` the region on an SSE signal (`realtime.md`) | ## Required config: swap 422 responses By default htmx **does not swap 4xx responses**, so failed forms would silently do nothing. Put this in the layout ``. The defaults it extends (verified in htmx 2.0.11) are `204` no swap, `[23]..` swap, `[45]..` error. `allowEval: false` and `includeIndicatorStyles: false` keep htmx inside the CSP (no `eval`, no injected `