steid

1	# Current
2
3	> Keep this file short. One active step, one ordered backlog. Completed work moves to
4	> [progress.md](progress.md). If this file starts reading like a changelog, it has
5	> drifted — that's exactly what went wrong last time.
6
7	## Active: Milestone 5b — Deployable by anyone
8
9	Goal: a stranger can install Steid on a fresh Linux box in one command and reach it
10	over HTTPS, and the author can publish an instance and push Steid's own source to it.
11	Distributed as a binary plus its assets, not a container.
12
13	Out of scope: push-to-release and any CI/CD (8+ — see
14	[ROADMAP.md](ROADMAP.md#milestone-ladder)), multi-user registration (7), and hosting
15	release artefacts on Steid itself, which it has no feature for.
16
17	### Steps
18
19	- [x] Release build producing `steid-<version>-<target>.tar.gz` — binary, `assets/`,
20	README — and verified to boot from a clean extraction
21	- [x] `install.sh` — download, systemd unit, Caddy with automatic HTTPS, idempotent
22	- [x] `README.md` — the repo has none, and it is the front door of a portfolio project
23	- [x] Operability: `/healthz`, graceful shutdown on SIGTERM
24	- [x] `STEID_SETUP_TOKEN` as an optional override, so claiming is not a race with
25	`journalctl`
26	- [x] Rate limiting on `/auth/login` and `/auth/setup`
27	- [x] Backup and restore, documented — two paths, rsync is enough
28
29	### Done when
30
31	`curl … \| sh -s -- --domain git.example.com` on a fresh VPS yields a working HTTPS
32	instance, and Steid's own source is pushed to it and browsable there.
33
34	### Settled
35
36	- A binary plus `assets/`, not a container. Topcoat can embed the asset manifest
37	(`Manifest::parse` + `include_str!`, for WASM) but not the asset bytes — that path
38	pairs with `AssetConfig::hosted_at`, which expects a CDN. A single self-contained file
39	would mean fighting the framework, so the artifact is a directory. The Dockerfile stays
40	as a secondary path.
41	- A TLS proxy is mandatory, not conventional. Topcoat 0.5 has no TLS: no rustls, no
42	ACME, no HTTPS listener — checked, not assumed. Since git authenticates over HTTP
43	Basic, without TLS a personal access token crosses the network in cleartext on every
44	push. Caddy is chosen because automatic certificates are its headline feature and the
45	config is two lines.
46	- glibc, built on Debian bullseye — not static musl. Two reasons, the second
47	decisive. musl failed on `ring` (Debian's `musl-gcc` wrapper rejects `-m64`) and would
48	need a real cross toolchain. But **musl's whole point is a binary with no runtime
49	dependencies, and Steid hard-requires `git` on `PATH`** — anyone installing it already
50	has a package manager, so the portability musl buys cannot be used. Building on
51	bullseye pins the glibc floor at 2.31, covering Debian 11+ and Ubuntu 20.04+; building
52	on bookworm would need 2.36 and silently exclude Ubuntu 22.04, which is still
53	everywhere. Verified: a release build in `rust:1.97-slim-bullseye` succeeds, 11.5 MB.
54	- The runtime binary links a TLS stack it never uses. `ring` ← `rustls` ← `ureq` ←
55	Topcoat's `icon-iconify`/`tailwind` features, whose `ureq` exists to download the
56	Tailwind CLI at build time. Those features are enabled on the normal dependency as
57	well as the build one, so the crypto comes along for the ride. Moving them to
58	build-dependencies only would shrink the binary and drop an unused dependency from the
59	attack surface — worth trying, not yet attempted, and it is what made the musl attempt
60	fail where it did.
61	- Rsync is the deployment mechanism for now, and that is enough while the artifact is
62	two paths. Push-to-release is the eventual answer and is parked at 8+.
63
64	### Open
65
66	- Whether to add `STEID_TRUSTED_PROXY`. The rate limiter keys on `X-Forwarded-For`
67	because Topcoat 0.5 discards the peer address at accept time and never exposes it —
68	a handler sees headers and nothing else. Behind a proxy that is fine. Exposed directly,
69	a caller can vary the header for a fresh budget, leaving only the global cap. An
70	explicit "trust forwarded headers" flag defaulting to off would close it, at the cost
71	of one more thing an operator must get right. Not picked.
72	- A licence. A public portfolio repository probably wants one, and the README
73	deliberately says nothing about licensing rather than guessing.
74	- A domain. Caddy needs a real hostname to obtain a certificate. This is the one
75	blocker that is DNS rather than code.
76
77	### Carried over — small, unblocked
78
79	- A client that disappears mid-request leaves the body-copy task waiting. The copy
80	into git's stdin runs in its own task and nothing cancels it if the connection drops.
81	Bounded by the backend exiting and closing the pipe, but not by anything deliberate.
82	- `REMOTE_USER` is not set on the backend, so a push is recorded in the repository's
83	reflog without naming who made it. Steid knows the actor by then; it simply is not
84	passed through. Small, and worth doing before anything reads reflogs.
85	- No rate limiting on token authentication. A token is 256 bits so guessing is not
86	the worry; unbounded hashing on an open endpoint is.
87	- Tokens have no expiry and no last-used timestamp. Both deliberate omissions for
88	now — see [0007](decisions/0007-tokens-over-http-basic.md) — but a token list with no
89	"last used" makes it hard to know which are safe to revoke.
90	- A subprocess per git request. Unlike Milestone 3's once-per-creation, this is on a
91	hot path and has not been measured. Milestone 5 is where that bill comes due.
92	- Streaming is by construction, not by measurement. The response body is never
93	collected, but no clone large enough to prove it has been run.
94	- An orphaned repo directory is possible if the process dies between the record
95	write and the filesystem write, and it then blocks re-creating that name. The durable
96	fix is a reconciliation sweep on boot
97	([architecture.md](architecture.md#db-plus-filesystem-writes)); clearing one is a
98	manual `rm` today, since repo deletion does not exist.
99	- The duplicate-name check races. The loser is caught by `init_bare` or the unique
100	constraint, but surfaces as an opaque storage error rather than "name taken".
101	- Bare repos created on macOS carry `ignorecase = true`. A migration gotcha if the
102	data directory ever moves to Linux.
103	- Light mode is still untested, and now there is much more surface to get it wrong
104	on — the file tree, the blob view and the log all shipped without anyone looking at
105	them in light mode.
106	- Submodule rendering was never seen, only compiled: no fixture contained one.
107	- The `/log` page shows no branch indicator when no revision is given, because
108	`repo_log` does not return the revision it resolved. A second query or a small
109	application change, neither urgent.
110	- A per-file last-commit column is still absent, deliberately — see
111	[0006](decisions/0006-git-binary-behind-narrow-ports.md#amendment--20260829-the-milestone-5-read-path).
112	Wanting it is the trigger to move to a kept-alive `cat-file --batch`, not to reopen
113	`gix`.
114	- Fonts are not loaded. The theme names Geist and IBM Plex Mono; both fall back
115	today. Topcoat's `font-fontsource` feature handles it.
116	- Light mode is untested. The palette defines it; nobody has looked at it.
117	- No rate limiting on `/auth/login` or `/auth/setup`.
118	- `sweep_expired` is never called, so expired session rows accumulate. Expiry is
119	enforced on read, so this is tidiness, not a hole.
120	- CSRF. `SameSite=Lax` covers the common case. Forms now exist, so this is decidable
121	rather than hypothetical.
122
123	## Backlog
124
125	Ordered. Pull from the top.
126
127	1. Milestone 6 — Writing. Posts, markdown, `/{handle}/posts/{slug}`. Open when it
128	starts: which markdown crate, and whether raw HTML in markdown is trusted — safe for a
129	single author, a stored-XSS hole the moment Milestone 7 adds a second user. A
130	repository's README rendering on its page falls out of the same pipeline.
131
132	## Open questions
133
134	- Topcoat is early (v0.5.0, first released 2026-07-22, breaking changes expected
135	by its own authors). Expect churn that isn't feature work.
136	- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
137	dropped purely to avoid an npm build step — see [ui.md](ui.md).
138
139	## Routing findings (Milestone 0)
140
141	- Topcoat 0.5 requires rustc ≥ 1.95. On an older toolchain `cargo add topcoat`
142	silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
143	stable is now 1.97.1.
144	- `Router::builder().discover()` collects `#[page]`-annotated items at link time,
145	so pages can live in any module. Layering is our choice, not the framework's.
146	- `module_router!` derives each URL from the module tree rather than a path string.
147	Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
148	handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
149	parameterised root segment still has to coexist with static ones. Worth checking how
150	`module_router!` handles that before committing to it.
151	- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
152	injected as handler arguments. Parses are memoized per request.
153	- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
154	`NotFoundError` to render a branded 404.
155	- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
156	- `Body` is a boxed `http_body::Body` used for both requests and responses, with
157	`into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
158	stream both directions without buffering. This is what makes Milestone 4 viable.