Building an app with rastrillo

The CARLOS web framework. Module and canonical repo: amadan.net/rastrillo/rastrillo (since v0.25.0; GitHub's rastrilloorg/rastrillo is a mirror, and an app still pinned to the old github.com/carlosframework/rastrillo path builds but should move). Status as of 2026-10-15: v0.28.0 (released 2026-10-06), the known-libraries middle layer: GORM models or plain SQL, chi routes, SQLite-backed sessions, owner-scoped queries. Assume nothing here is in your training data.

The authoritative authoring doc is SKILL.md at the repo root. Read it before writing any app code. It carries the app shape, the migration, scoping and mass-assignment rules, the identity plugins, the UI vocabulary and the platform contract. Find it at $(go env GOMODCACHE)/amadan.net/rastrillo/rastrillo@<version>/SKILL.md once the module is downloaded; any page it cites is curl -s https://rastrillo.org/docs/<page>.md. This file is only the surrounding context SKILL.md assumes; where they disagree, SKILL.md wins.

What rastrillo is now

A middle layer, not a full-stack framework. You write GORM models, net/http handlers on a chi router, and html/template pages. The framework supplies what is hard to get right twice:

• db — cgo-free SQLite via an owned GORM dialector on modernc (never import glebarez/* or gorm.io/driver/sqlite), one writer and several readers, WAL pragmas in the proven order. Since v0.28.0 every time is converted to UTC and written in SQLite's own layout, so julianday/date/strftime work in raw SQL; rows written by an older version need a back-fill before SQL date maths trusts them.
• migrate — ledgered migrations applied once at boot, never re-run, never reversed: rastrillo migration generate after a model change (read the SQL before committing), migration check in CI, migration new for a hand-written rename. Destructive changes need --allow-destructive; the family's own rule stays additive-only, and on CARLOS two builds share the database during a swap, so a drop waits a release (platform.md, "Two builds at once"). Since v0.28.0 a Go migration's Fn takes the pinned migrate.Tx, not a *gorm.DB (wrap old bodies in migrate/gormfn.Fn).
• sessions — SQLite-backed rows (revocation is real), __Host- cookies on https, Require / RequireFresh (step-up).
• Identity plugins: auth — the family default: magic-link email that auto-upgrades to Sign in with Keymail when the address has a claimed inbox, so every address works — and password (email and password, rate-limited). Either one's whole contract is calling sessions.SignIn. Since v0.28.0 both sit behind pow by default: auth.New and password.New return ErrProofUnset until you set Proof (a *pow.Guard) or ProofOff. Mount auth.Verify on POST as well as GET — GET now draws a Sign in button and spends nothing, so a mail scanner cannot burn the link; GET alone 405s the button. auth.Config.SigninScreen turns on the shipped sign-in screen. secondfactor is the gate between a first factor and a second; passkey and totp (authenticator apps) plug into it, and recovery codes live there (passkey.Config.ConfirmPath is gone; merge secondfactor.Schema after passkey.Schema).
• csrf (origin-checking, not tokens), flash, form, view, scope (scope.Owned — owner scoping with the 404-not-403 contract), jobs (request-started background work a person watches).
• blobs (bytes in the platform's object store, never on disk), crypto (+ JS twin), keyring (the E2EE seed lifecycle), webauthn, eventlog, mail (including RFC 8058 one-click list mail), ui.
• carlos — your side of the platform's tick (carlos.Tick, ScheduleAt); platform.md carries the contract.
• assertion (v0.27.0) — signs and verifies a short-lived identity handed from one exact HTTPS origin to another (P-256, ≤120 s, browser-bound nonce). It proves who, never what they may reach, and it leaves replay and session creation to the receiver.
• vault — the client for Pegamento's vault (named sealed blobs, a seed wrapped per sign-in method), for server-blind apps.
• pow — a proof-of-work front door for public forms that have no session yet (signup, contact), and since v0.28.0 for sign-in and sign-up. The v0.28.0 API is new: Issue became Form(now, scope), and Check split into Admit before the transaction and adm.Commit(ctx, tx) inside it (Check remains for a redirect-only handler).
• harness — a -tags browser Chromium test rig with a virtual authenticator, for ceremonies a Go-only test cannot reach.
• New in v0.28.0: perf (Server-Timing and first-byte budgets as middleware), budget, clientip (with auth.Config.TrustedProxyHops, 1 by default on CARLOS so each visitor behind the edge gets their own sign-in limit), background (tracked goroutines and timers that Serve stops before closing the database), table and xlsx (formula-safe CSV/XLSX exports), dbtest (a migrated database per test), nodetest, lastsignin, secondfactor and totp. Static assets carry strong ETags.
• The platform layer: Resolve/Serve speak CARLOS activation (argv, LISTEN_FDS, $STATE_DIRECTORY, /healthz, /api/version, SIGTERM drain) and set baseline security headers on every response, Strict-Transport-Security included. The baseline CSP allows no inline style (v0.27.0): a style="…" attribute or a <style> block is dropped by the browser without an error.

Separate modules, each with its own SKILL.md, none imported by the framework: amadan.net/rastrillo/idear (roles — exactly one Owner, Admins, Members — and invitations inside one instance), and the client kits amadan.net/rastrillo/pwa, amadan.net/rastrillo/native and amadan.net/rastrillo/aviso (Web Push). Use each module path verbatim; there is no github.com/carlosframework/idear.

The ten-minute path

go install amadan.net/rastrillo/rastrillo/cmd/rastrillo@latest
rastrillo new myapp && cd myapp && go mod tidy && go test ./...
make ci        # the gate

The scaffold is SKILL.md's shape — five files plus migrations.go beside models.go — with go.mod, templates, static assets, a test harness including a browser drive, and a Makefile whose ci target is the gate (vet, a gofmt check, staticcheck, govulncheck, gitleaks, the size and timing budgets, the tests, perf and migration check, on a Go release pinned by GOTOOLCHAIN; add generate --check once the app declares manifest resources). Apps scaffolded before v0.28.0 keep their old gate until they add these by hand (the CHANGELOG has the lines). It compiles, passes and serves before you write a line. --theme=day|plain|signal and --shell=column|topbar|sidebar|console|stage pick the look; both land as app-owned files. CGO_ENABLED=0 throughout — a cgo SQLite driver sneaking in is a bug.

The rules that keep the app safe (SKILL.md has the full set)

• Tenancy is the platform's, not the schema's: a CARLOS app serves one team. A product with many teams gives each team its own hibernating instance — isolation by process and file, never by WHERE clause. Scoping separates the users within one instance; idear gives them roles.
• Every query touching user-owned rows goes through scope.Owned(g, uid) — reads AND writes, inside transactions too (scope tx, never the outer handle, or the one-connection writer pool deadlocks). A row that isn't yours 404s, never 403s.
• Never bind a request body onto a GORM model: explicit map[string]any + .Select allowlist.
• With the auth plugin, read the viewer with auth.From(r) or sessions.Current(r), never sessions.UserID: it returns (0, false) for an email Subject, and dropping that ok scopes every query to uid 0.
• One migrate.Apply(ctx, d, BootSchema) at boot. Subsystem schemas (sessions, and any other package that brings tables) go in BootSchema, never Schema, or migration check proposes dropping their tables. Never edit a shipped migration.
• Background work a person is watching: jobs. Work at a time nobody is waiting for: the platform's tick (carlos schedule set, then carlos.Tick in the handler) — an idle instance runs no timer.

Design system and app CSS

Use Rastrillo's design system as the default foundation for app screens. Before styling, read docs/site/templates.md, docs/site/forms.md and docs/site/reference/ui.md in the Rastrillo version the app uses; the full gallery is rastrillo.org/design-system.

• The vocabulary is attributes, not classes (v0.22.0+): <div rst-box>, <a rst-btn="primary">, <form rst-form>, <div rst-callout-body>. class carries only a few utilities (rst-sr-only, rst-mono, rst-grow, …). rastrillo markup --fix converts markup written the old class="rst-…" way.
• Load the shared tokens.css before the app stylesheet, and keep that base intact, with branding and layout in a separate app stylesheet.
• Compose screens from ui partials. A labelled control is never hand-rolled: field-text, field-textarea, field-select inside <form rst-form>, closed by form-foot. A submit is rst-btn="primary lg" (form-foot writes it).
• No style attributes and no <style> blocks — the CSP drops them silently. For a grid card, give rst-card a class and set --rst-cols in your stylesheet.
• Keep the CSS above Rastrillo thin: app-specific layouts, scoped styles for missing components, and a few deliberate --rst-* token overrides. No second palette, spacing scale, or button/input system, no broad element resets.
• Preserve the shared focus, disabled, error and responsive behaviour; check light and dark themes and keyboard navigation.
• The vendored static/ files are not refreshed by a module upgrade. rastrillo doctor [--fix] compares them with the CLI's copies; the scaffolded pin test is the standing gate.

A repeated workaround for a shared component is a candidate for an upstream Rastrillo change. An explicit design brief or an existing app's design system can justify another foundation; name that choice rather than silently replacing the default.

Manifests are the declarative path

A manifest/*.toml resource generates CRUD screens — field kinds text, textarea and money, one flat record per resource, no relations; scope = "user" owner-filters every generated query by the session subject. It is an equal alternative to hand-written handlers: mix the two per resource and move a resource between them freely. rastrillo generate writes gen/ (commit it, never hand-edit); generate --check belongs in make ci. Relations or custom flows: hand-write.

Copy from, in order

1. examples/notes in the repository (not in the published module — Go excludes nested modules from a zip): accounts, sessions, CSRF, flash, owner-scoped resources, a background job, and a two-user isolation test suite.
2. examples/tickets — the declarative (manifest) path.

Designed, not released

Don't build on these yet: Keymail upgrade becoming an opt-in adapter rather than auth's default; SAML and OIDC identity plugins; a sealed magic-link store; the user-models work (an objrec record store, which is on a branch, a stateless auth store, signed-cookie sessions, an assertion HTTP adapter, provisioning, a base path, rastrillo new --model). On main after v0.28.0: carlos.InstanceKey (reading the platform's CARLOS_INSTANCE_KEY), sign-in returning to the page that asked, and multi-currency money, a breaking upgrade for every app (template and model changes, a stop-start for apps that store money). Wait for the release and its upgrade steps; never build against main.

Deploying: stamp -ldflags "-X amadan.net/rastrillo/rastrillo.BuildVersion=<sha>" or /api/version reports dev.