carlos / todomvc-bakeoff Public

Download this file

1	# 🤖 todo-go
2
3	TodoMVC for the CARLOS bakeoff, written in Go. It's live at
4	[https://todo-go.bfj.oncarlos.com](https://todo-go.bfj.oncarlos.com).
5
6	The server renders every page, and every change is a plain form POST,
7	so the whole app works with JavaScript turned off. One small ES module
8	(`web/static/app.js`) makes it behave like the reference TodoMVC when
9	JavaScript is on: double-click to edit, Escape to cancel, and checkboxes
10	that act without a page load.
11
12	## The stack, and why
13
14	| Piece | Choice | Why |
15	|---|---|---|
16	| HTTP server and routing | `net/http` from the standard library | Since Go 1.22 the standard `ServeMux` matches methods and path parameters (`POST /todos/{id}/toggle`), which is all this app needs. A router library would add a dependency and nothing else |
17	| Templates | `html/template` | Escapes by context, so a todo titled `<img onerror=…>` shows as text. Templates and static files are embedded in the binary with `embed` |
18	| SQLite | `modernc.org/sqlite` | A pure-Go translation of SQLite, so the binary builds with `CGO_ENABLED=0` and cross-compiles to linux-arm64 with no C toolchain. It's the driver the CARLOS family uses |
19	| Database access | `database/sql`, hand-written SQL | Five short queries. Two pools: one connection for writes (SQLite allows one writer at a time, so writes queue in Go instead of fighting over the lock) and a few read-only connections |
20	| Migrations | A Go slice of SQL strings, each recorded in a `todo_migrations` table once applied | Append-only by construction. No migration tool needed for one table |
21	| JavaScript | One ES module, no framework, no build step | It sends the same form POSTs with an `X-Todo-Fragment` header and swaps in the HTML the server returns, so all rendering stays in one template |
22	| Logging | `log/slog` | Standard library, structured, to stderr |
23
24	The only third-party dependency is `modernc.org/sqlite` (see `DEPS`); the
25	rest of `go.sum` is what it pulls in.
26
27	## How it fits the platform
28
29	- The binary is started as `todo-go --socket <path> --db <path>` and
30	listens on that unix socket. For local runs it takes
31	`--listen 127.0.0.1:<port>` instead, and refuses any address that
32	isn't loopback.
33	- It reads its hostname from `CARLOS_HOST`. With it set, POSTs must come
34	from `https://$CARLOS_HOST` (or carry no `Origin` at all) and the
35	cookie is marked `Secure`.
36	- `GET /healthz` checks the database answers; `GET /api/version` returns
37	the git short SHA baked in at build time.
38	- SQLite runs in WAL mode in one file. Startup is a few milliseconds,
39	and SIGTERM finishes in-flight requests, closes the database and
40	exits 0.
41
42	## Each visitor's list
43
44	A visitor's first request sets a `todo_list` cookie holding 32 random
45	bytes (`HttpOnly; SameSite=Lax; Path=/`, plus `Secure` on Carloku). The
46	database keys each todo by the SHA-256 of that cookie, never the cookie
47	itself. Issued lists are recorded in a `todo_lists` table, and a cookie
48	the app can't parse or never issued just gets a new one and an empty
49	list, so nobody can choose their own list identity. An id that isn't in your list answers 404, whoever it belongs to.
50
51	## Honest trade-offs
52
53	- **Trust class C (2026-10-23).** Todo titles are stored as plain text.
54	The server, and anyone with a copy of the database or its replicas,
55	can read them. That's a deliberate choice for a public demo.
56	- A list lasts as long as its cookie. Clearing cookies loses it, and
57	there's no way to carry a list to another browser.
58
59	## Build, run, test, deploy
60
61	Put the toolchain on `PATH` first: `source ../../scripts/env.sh`.
62
63	| Command | What it does |
64	|---|---|
65	| `make build` | Builds for this machine into `dist/app` |
66	| `make build-arm64` | Builds the static linux-arm64 binary into `dist/app-linux-arm64`. `COLD=1` passes `-a` to recompile every package |
67	| `make test` | Checks the stylesheets still match `shared/`, then runs `go vet` and `go test` |
68	| `make clean` | Removes `dist/` |
69	| `make clean-deps` | The same as `clean`. Go keeps compiled packages in the shared `GOCACHE`, which this repo leaves alone; use `COLD=1` for a from-scratch build |
70	| `make bump` / `make unbump` | Changes a constant in `web/web.go` (the file with the `GET /` handler) and puts it back |
71	| `make deploy` | Ships `dist/app-linux-arm64` with `carlos deploy`. Set `MESSAGE="…"` to describe the change |
72
73	Run it locally:
74
75	```sh
76	make build
77	./dist/app --listen 127.0.0.1:8080 --db "$TMPDIR/todo-go.db"
78	```
79
80	Then run the shared behaviour suite against it from the repo root:
81	`scripts/test-app.sh http://127.0.0.1:8080`.
82
83	Before a deploy, `scripts/boot-check.sh dist/app-linux-arm64` starts the
84	arm64 binary under qemu on a unix socket and checks it answers and exits
85	cleanly.
86
87	## Layout
88
89	| Path | What |
90	|---|---|
91	| `main.go` | Flags, listener, signal handling |
92	| `internal/todo/` | The SQLite store, its migrations, and its tests |
93	| `web/web.go` | Routes, handlers, cookie and origin checks |
94	| `web/templates/page.html` | The page, and the `list` fragment app.js swaps in |
95	| `web/static/` | TodoMVC's CSS (copied byte for byte from `shared/`), `app.css`, `nojs.css` (loaded only inside `<noscript>`) and `app.js` |
96