Runtime modules

Most Rally apps import only a few rally/runtime/* modules directly. Generated code uses more of them behind the scenes.

effect

Generated Rally browser functions are the primary way pages talk to the server. They send a typed page-local request and deliver the response back to your update function.

Broadcast effects are for page handlers that need to push a message to more than one connection. Call them from your server-side handler when something changes that multiple clients care about.

effect.navigate pushes a URL on the client side without a full page load. For arbitrary Lustre effects, import lustre/effect directly.

db

db.open creates a SQLite connection at startup. It configures WAL mode, sets a busy timeout, and enables foreign keys.

db.query wraps your SQL calls with timing logs so slow queries show up in your system message log. db.transaction uses SAVEPOINTs, which means transactions can nest safely.

db.one returns the single row from a result set, or None if the set is empty. For encoding values into SQL parameters, db.bool_to_int and db.nullable_text handle the common cases.

system

system.start runs during app startup to initialize the system database. The system DB stores message logs and the job queue.

When your app has background jobs and no OTP supervision tree, use system.start_with_jobs. It starts the job runner alongside the system DB, but the runner is not supervised.

If your app has a supervisor, use system.supervised_job_runner and add the returned child specification to your tree. system.start_job_runner is the direct start function behind that child specification.

session

session handles generation and extraction of session cookies. It creates cryptographically random session IDs and produces the Set-Cookie header with the right flags for your environment. Auth flows depend on it to associate requests with sessions, and SSR uses it to identify the connection before the WebSocket upgrades.

auth

rally/runtime/auth defines shared policy and load-result types for auth-aware pages. Required and Optional are the policy values used by the intended page-auth contract, and LoadResult carries page data, redirects, and cookies for auth-aware server rendering.

Current generated apps should treat app identity lookup and authorization as app-owned. Rally ships the runtime auth helpers and generated mount auth checks, but the fuller src/<namespace>/auth.gleam convention is still intended design, not the current generated app contract.

env

The env module parses the APP_ENV environment variable to determine which environment the app is running in. In production, session cookies get the Secure flag and browser console logging stays off. During development these restrictions are relaxed so you can work over plain HTTP and see client-side log output.

test_db

test_db gives you an in-memory SQLite database for tests. It applies your migrations the first time, then caches the schema so repeated test setups skip the migration step.