🤖 Documentation

Rastrillo is the CARLOS web framework. You write GORM models, net/http handlers on a chi router, and html/template pages — all ordinary Go. Rastrillo supplies the parts that are tedious to get right twice: the database opener, the session store, identity plugins, CSRF, owner scoping, form helpers, background jobs.

These pages cover everything it does. Start with Getting started if you have never used it, or The shape of an app if you have just run rastrillo new and want to know what the files are for.

Each page stands on its own, so you can arrive from a search engine or a link and not be lost.

Start here

• Getting started Install the CLI, scaffold an app, and get it serving.
• The shape of an app Five files plus migrations.go, and why main.go calls Resolve rather than Run.
• Compare The Go framework field, and the better answer when it is not this one.

Building an app

• Data GORM models, and the two-pool SQLite handle db.Open returns.
• Migrations Numbered, applied once at boot, ledgered — and the two rules that cost data if you get them wrong.
• Scoping The one seam every owned query goes through, and why a row that isn't yours answers 404.
• Forms Reading input without ever binding a request onto a model.
• Sessions Signed-in state as real rows, CSRF without tokens, and step-up.
• Passwords The email-and-password plugin: its two callbacks, and its shared rate limit.
• Magic links Passwordless sign-in by emailed link, and the sessions.UserID trap that comes with it.
• Passkeys A WebAuthn second factor at step-up and at sign-in.
• Second factors & TOTP The half-session every factor completes, authenticator-app codes, and recovery codes that need no JavaScript.
• Background jobs Observable goroutines, their two bounds, and a status page that works with scripts off.
• Templates & UI One template per page, twenty-four partials, and the tokens stylesheet you own.
• Your app's design system Customising what the framework ships, where your own components go, and upgrading without drift.
• Icons Eleven slugs that mean the same thing in every app, three delivery modes, and pinned versions.
• Localization Locale resolution, catalogs, and the gate that runs under --check only.
• Upgrading templates Add the localizer to every template call with migrate-templates, then work through what it lists.
• Manifests The declarative path: two stores, three field kinds, and where it honestly stops.
• Assets Fingerprinted static files, and the three files delivered once and owned by you.
• Agents & tools Actions as agent-callable tools, the consent gate, and the sidecar loop.
• Testing The scaffolded harness, serving without a listener, and the one gate definition.
• Deploying The platform contract Serve implements, hibernation, and the schema-neutral first deploy.

Addons

• Addons Modules that ship outside the framework, the four rules they follow, and how to fetch their skills.
• Writing an addon Choose between core and an addon, then build one and get it listed.

Reference

• The CLI Every rastrillo command and flag, and when you reach for it.
• assertion Pass an authenticated identity from one exact HTTPS origin to another.
• auth The magic-link plugin: its handlers, its admission hook, and its email subject.
• background Keep track of work nobody waits for, and stop it before the database closes.
• blobs Content-addressed bytes over S3, a directory, or a table.
• carlos Receiving a scheduled tick, and asking the platform for a one-shot one.
• clientip The visitor's address behind your proxies, read from the right of X-Forwarded-For.
• crypto The family envelope, its wire formats, and the golden vectors that pin them.
• csrf Same-origin enforcement for state-changing requests, with no tokens.
• currency Format, seed and parse an amount in any currency, in the reader's language.
• db One SQLite file as two pools, and the pragma order that has to be right.
• dbtest A migrated database for every test, copied from a template built once.
• eventlog Append-only streams, a pure fold, and the deterministic merge order.
• flash One-shot notices in a cookie: display state, not a record.
• form Field parsing, the error map, and money in any currency.
• gormlite The SQLite dialector, and the double-registration panic it avoids.
• harness A browser-drive rig: localhost origin, virtual authenticator, real Chromium.
• jobs Start, Get, the two bounds, and the three handlers.
• keyring One seed per person: purpose derivation, passkey wraps, member grants, and the last-wrap guard.
• lastsignin The sign-in screen's memory of how this browser got in last, and the seam that ends a sign-in attempt.
• locales One pack of CLDR data per language, the boot check on the languages you offer, and the probe that runs it.
• mail One Sender interface, SMTP, and a logging fallback that warns.
• migrate Ordered, namespaced, ledgered migrations — and why there is no Down.
• money Parse decimal amounts into signed `int64` minor units with `money`. The package uses only the Go standard library.
• nodetest Run a Node script from a Go test, and fail on CI when node is missing.
• passkey Step-up and sign-in WebAuthn, the Gate, and recovery codes.
• password The email-and-password plugin: config, handlers, hashing, rate limit.
• perf Server-Timing, time budgets and per-route percentiles, as middleware.
• perftest Fails the build when a screen or a cold start is slower than perf's budgets.
• budget Measures how long a test package takes, so `rastrillo budget test` can hold it to its time budget.
• pow The front door for a public form: bound proof of work, sealed challenge, honeypot.
• rastrillo The root package: entrypoints, Options, Ctx, locales, assets, icons, agents, manifest types.
• scope Owner-filtered GORM scopes: the one seam every owned query goes through.
• secondfactor The half-session between a first factor and its session: hold, complete, strike, recovery codes.
• sessions Session rows, cookies, the three middlewares, and SafeReturn.
• table One table as a CSV or XLSX download, safe from CSV formula injection.
• tools Schemas, dispatch through your own mux, and the three refusals.
• totp Authenticator apps: enrolment and the QR, sign-in and step-up, and secrets sealed at rest.
• ui Partials, template funcs, and the three vendored assets you own.
• view Render, Fail and ParseID for a generated action.
• vault The Pegamento vault's client half: sealed named blobs, wrapped seeds per method, and the enrol/restore handoff.
• vectors Golden vectors that pin an app's JS derivation engine to its Go one, and kass's canonical() rule.
• webauthn The two ceremonies, the six refusals, and what is deliberately not checked.
• xlsx Read and write .xlsx workbooks of strings, with the standard library alone.