The web framework companion to CARLOS: libraries you already know — GORM, chi, html/template — on a middle layer that gets sessions, CSRF, and owner scoping right, shipped to a platform that only bills you when someone shows up.
written, in examples/notes — accounts, sessions, owner-scoped CRUD, a background export | 270 lines |
|---|---|
| proving Bob can never read Alice's notes — or her bookmarks, or her export — the isolation suite, in CI | 1,177 lines |
| client-side JavaScript required, new DSLs, config formats | 0 |
🤖 This page was written by an LLM, on the ideas, instruction, and editing of humans. AI-written text here is always marked, visibly, like this — that's factor X.
Libraries you already know, SQLite, and files you can read — nothing decided behind your back.
html/template — no bespoke DSL to learn, and nothing your Go experience (or your model's training data) doesn't already cover. errors.Is(err, gorm.ErrDuplicatedKey) just works. Rastrillo supplies the parts that are hard to get right twice, not a new language for the parts that aren't.__Host- cookies on https and step-up re-auth (RequireFresh) for sensitive routes. CSRF is an origin check on every mutating request; no tokens to mint or forget. Failed sign-ins are rate-limited per account. And owner scoping has one contract: a row that isn't yours is a row that doesn't exist — 404, never 403 — enforced in examples/notes by a two-user isolation suite that runs in CI.SKILL.md at the repo root is the whole app story — the file shape, the scoping rules, the mass-assignment rule, the identity plugins — budgeted under 15,000 bytes and reviewed like code. It's what an agent loads instead of the framework source, and what a person reads first. The docs are part of the artifact, not an afterthought.rastrillo.Resolve and Serve speak the CARLOS platform's activation contract end to end — hibernating instances, carlos-app@ systemd unit tenants, plain instances, and a bare dev fallback, no separate integration per deployment shape. Hibernation is the cost-efficiency receipt: your app isn't running when nobody's knocking, and the platform wakes it when someone does.go build with CGO_ENABLED=0 gets you the whole app — SQLite compiled in via pure-Go modernc.org/sqlite under an owned GORM dialector, a writer pool capped at one connection and a reader pool that keeps WAL reads flowing. No bundler, no codegen service, no runtime to babysit, and not one line of client-side JavaScript by default.Generated, not interpreted — the declarative path beside the code path: mix them per resource, move a resource between them freely, use either or both.
name = "ticket_types"route = "/admin/ticket_types"store = "exclusive"[list]columns = [{ field = "Name" }, { field = "Price", kind = "money" }, { field = "Status" }]search = true[[list.filters]]field = "Status"values = ["draft", "on_sale", "sold_out"][form]basics = [{ name = "Name", required = true }, { name = "Price", kind = "money", required = true }, { name = "Status" }]advanced = [{ name = "MaxPerOrder" }]rastrillo generate wrote from itfiles committed under gen/, diffable in review like any code | 25 |
|---|---|
lines of plain Go, SQL, HTML, and locale keys — each action opens with one form.Parse call, the same documented helper a hand-written handler uses | 1,202 |
| actions, wired into the router — list, create, show, edit, and the delete flow | 9 |
| screens — a list with search, a working Status filter and paging; a two-tier form; a show page; a delete confirm | 4 |
| typed store — schema, additive migrations, sqlc queries | 1 |
| TOML parsed at request time | 0 |
required = true is server-side: the generated actions 400 with the field's own message, re-rendered in the form. There is no actions/ directory in this app at all — examples/tickets is manifest-only, and it's the framework's own regression suite. Add scope = "user" and every generated query is owner-filtered by the signed-in subject — someone else's row answers 404, the same contract the hand-written path enforces; examples/notes runs a declared, scoped resource beside hand-written handlers under one two-user isolation suite. And when a generated screen stops being enough, eject it: the file becomes yours, and the generator leaves it alone.
Deployedlive · real edge
Rastrillo's example app is deployed on a real CARLOS platform right now: real S3-backed storage, a real edge, a real certificate, a hibernating instance that wakes when you knock. hello.bdf.oncarlos.com — the same framework you'll have running locally two minutes from now, actually shipped (/api/version names the exact commit). This site is served the same way.
Nothing to install but Go: clone, run, and try to break the isolation yourself.
git clone https://github.com/rastrilloorg/rastrillo && cd rastrillo/examples/notesexamples/notes is the front-door example: accounts, sessions, CSRF, flash, and owner-scoped notes — 163 lines of domain code.
CGO_ENABLED=0 go run ./cmd/notes -addr localhost:8080Visit localhost:8080 — sign up, write a note. Open a private window, sign up as someone else, and try to reach the first account's note by URL: 404. That isolation is the framework's owner-scoping contract, and the same check runs as a test suite in CI.
go install amadan.net/rastrillo/rastrillo/cmd/rastrillo@latest
rastrillo new myapp && cd myapp && go mod tidy && go test ./...The scaffold is the same five-file shape, tests passing before you write a line. Then read SKILL.md — the whole app story in one file. Building with an agent? That file is exactly what it should load.
CARLOS is self-hostable — one binary, a bucket, and DNS. No PaaS account to sign up for.
brew install carlosframework/tap/carlosOr grab a binary directly from carlosframework/releases.
GOOS=linux GOARCH=arm64 go build -o myapp-binary ./cmd/myappcarlos ship -app myapp -version $(git rev-parse --short HEAD) myapp-binary
carlos promote -app myapp <version> stable
carlos add -app myapp -kind instance myapp.yourdomain.comThe same sequence — against a real S3-backed bucket, a real edge, a real certificate — that put rastrillo's own example live at hello.bdf.oncarlos.com. Standing up the box, bucket, and DNS is the one-off part; from then on every deploy is ship then promote.
A young framework that ships its status on its homepage — this list moves when the work lands, not before.
db (GORM on cgo-free SQLite, split writer/reader pools, translated constraint errors), sessions (revocable rows, step-up RequireFresh), csrf, flash, form, view, scope — each importable alone, tested alonerastrillo/auth — the family default sign-in: magic-link email that auto-upgrades to Keymail when the address has a claimed inbox, over keymaildev/signinrastrillo/password — classic email+password on the sessions core: stdlib PBKDF2, per-account rate limiting, one non-oracle failure messageSKILL.md — the authoring contract, under 15,000 bytes, reviewed like code: what an agent loads instead of the framework sourceexamples/notes — accounts, sessions, CSRF, flash, owner-scoped CRUD, and a background export in 270 domain lines, with a two-user isolation suite in CIrastrillo/crypto — the family envelope: P-256 sealing and signing, invite derivation and key wrapping, a WebCrypto JS twin — all pinned by golden vectors from real consumersrastrillo/webauthn — passkeys, verify-only, with a test authenticator and the browser module includedrastrillo/eventlog — the mergeable store shape: append-only streams, pure Derive, deterministic merge pinned by vectorsrastrillo/blobs — content-addressed bytes on the platform's object store, presigned URLs, sealed E2EE wrapperrastrillo.Resolve/Serve/Run — the full platform activation contract, hibernate and systemd tenants includedT/Tf with fallback, a ship-gate catalog checkrastrillo/ui — the component vocabulary: 27 partials, documented class idioms, design tokens — light and dark, WCAG AA enforced by tests, zero JavaScriptResource generates store, actions, screens, and locale keys — an optional, equal alternative to hand-written handlers, mixed per resource; generated actions compose the same documented form.Parse/view helpers a hand-written app uses; examples/tickets is its regression suitestore = "mergeable" generates the same screens over an eventlog-backed store: each record one append-only stream, deletes appended as tombstones, every read derived by replaying the merged history; examples/tickets' announcements resource is the generated proof, tombstone test includedscope = "user" owner-filters every generated query by the session subject, so someone else's row answers 404, the same contract the hand-written path enforces; examples/notes mixes a declared, scoped resource beside its hand handlers, proven by one two-user isolation suiterastrillo new — scaffolds the middle-layer five-file shape with a passing test suite out of the box; the declarative path stays one TOML away (manifest/README.md carries the mounting recipe)rastrillo/passkey — the WebAuthn second factor, both places it belongs: on the step-up seam (enroll while signed in, satisfy RequireFresh with an assertion instead of a full re-sign-in) and at first sign-in (Gate on the identity plugins' SecondFactor hook: a verified first factor becomes a pending half-session only an assertion completes — the minted session names both factors) — single-use, subject-bound challenges and half-sessions throughout. And the escape hatch (v0.14.0): ten single-use recovery codes, minted behind step-up and shown once, redeem a lost passkey at the gate by plain form POST — no JavaScript, because that's exactly when WebAuthn isn't working; sign-in only, so step-up still takes a real assertionjobs gives a goroutine an owner-scoped handle and a status page that works with scripts off: a noscript refresh while it runs, a 303 to the result when it's done. The one script in the framework is rastrillo.js, a ~130-line app-owned shim that polls HTML fragments for the smooth version — no JS required, htmx a choice rather than a dependency; examples/notes ships a background export under the same isolation suite. Bounded, too (v0.13.0): an owner holds at most four running jobs, and a stuck one is failed after fifteen minutes, its slot freed. And pushed (v0.15.0): status pages ride Server-Sent Events where the browser supports them — heartbeats, per-write deadlines, a bounded stream — and fall back to plain polling on their ownrastrillo/carlos (v0.19.0) — scheduled work on a platform that keeps your app asleep: carlos.Tick is the constant-time bearer check that separates a real platform tick from an internet request to the same public path, TickOccurrence is the dedupe key that stays the same across at-least-once redelivery, and ScheduleAt/ScheduleCancel register one-shot timers that live in the box's registry rather than in your process, so a restart loses none of them; recurring schedules are declared from outside the app with carlos schedule set, and the app's whole part is a guarded handlereventlog.Ingest is the seam waiting for it, and until it lands, generated mergeable ids stay writer-localCREATE; changing a manifest's fields is still the app's own ALTER, not a generated diff"app" today; threading the session's actor into store events is the recorded follow-up