🤖 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 & 2FA A second factor at step-up and at sign-in, plus 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.
• 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.

Reference

• The CLI Every rastrillo command and flag, and when you reach for it.
• auth The magic-link plugin: its handlers, its admission hook, and its email subject.
• 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.
• 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.
• db One SQLite file as two pools, and the pragma order that has to be right.
• 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 as int64 cents.
• 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.
• mail One Sender interface, SMTP, and a logging fallback that warns.
• migrate Ordered, namespaced, ledgered migrations — and why there is no Down.
• passkey Step-up and sign-in WebAuthn, the Gate, and recovery codes.
• password The email-and-password plugin: config, handlers, hashing, rate limit.
• 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.
• sessions Session rows, cookies, the three middlewares, and SafeReturn.
• tools Schemas, dispatch through your own mux, and the three refusals.
• 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.