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 5 — Repo browsing
8
9	Goal: a repository's contents are readable on the web — the file tree at a ref, a
10	single file's contents, and the commit log. A visitor can look at code without cloning
11	it, which is the first time the profile behaves like a portfolio rather than a list of
12	names.
13
14	Out of scope: editing files, diffs, blame, syntax highlighting, rendering a README as
15	markdown (that wants the markdown pipeline Milestone 6 brings), search, and a
16	last-commit-per-file column — see Open, where that one is a decision rather than an
17	omission.
18
19	### Steps
20
21	- [x] Web: the clone URL on the repository page — no plumbing, and Milestone 4 made it
22	true
23	- [ ] Domain: `ObjectId`, `RefName`, `TreeEntry` — value objects before any adapter,
24	per [0006](decisions/0006-git-binary-behind-narrow-ports.md)
25	- [ ] Application: `GitQuery` port — `resolve_ref`, `list_tree`, `read_blob`, `log`
26	- [ ] Infrastructure: adapter over the `git` binary, through the existing `git_command`
27	- [ ] Application: `browse_repo` read model, reusing `view_repo`'s visibility rule
28	- [ ] Web: the tree page, and the repository page showing its default branch
29	- [ ] Web: the blob page, and the commit log
30	- [ ] Verify in a browser against a real repository, including an empty one
31
32	### Done when
33
34	A visitor can open a public repository from a profile, see its files at the default
35	branch, click into a directory and then a file and read its contents, and open the commit
36	log. A private repository shows none of this to someone who may not see it. An empty
37	repository says so rather than erroring.
38
39	### Settled
40
41	- Value objects come first. A query port returning `String`s is an anaemic
42	pass-through that pushes validation into the page, which
43	[0006](decisions/0006-git-binary-behind-narrow-ports.md) rejected in advance.
44
45	- The read path stays on the `git` binary, one process per query, with
46	`cat-file --batch` as the named upgrade and `gix` closed off — reasoning, the
47	measurement, and the reopening conditions in
48	[0006](decisions/0006-git-binary-behind-narrow-ports.md#amendment--20260829-the-milestone-5-read-path).
49	- `GitQuery` is a shared handle in app context, not constructed per request the way
50	the SQLite adapters are. Stage 1 does not need the sharing; stage 2 owns live
51	subprocesses and cannot work without it. The port gives us the seam, not the lifetime,
52	and getting the lifetime wrong now means touching every page later.
53	- The public origin is derived from the request, never configured. An instance is
54	deployable anywhere without being told its own address: the `Host` header plus
55	`X-Forwarded-Proto` when a proxy terminates TLS in front of it. One less thing to get
56	wrong in a deployment, and it makes the clone URL correct on localhost and in
57	production without a branch.
58	- Tree URLs use a separator — `/{handle}/repos/{name}/tree/{ref}/-/{path}`.
59	Unambiguous by construction where candidate splits would cost a ref lookup, which is
60	another fork on every page.
61	- The commit log shows 50 and does not page in v1.
62	- No per-file last-commit column in v1. The direct consequence of the above: at one
63	fork per entry a twenty-file directory is ~230ms. If it is missed, that is the trigger
64	to climb to stage 2 rather than to reopen `gix`.
65	- Fork/exec is ~11–12ms per call, and it is the process, not the query. Measured on
66	a 201-commit repository, averaged over 50 runs each: `rev-parse` 11.2ms, `ls-tree`
67	11.7ms, `cat-file` 11.6ms, `log -20` 11.8ms, `for-each-ref` 14.4ms. The work is
68	free; starting git is not — which matches the ~13ms `git init --bare` measured in
69	Milestone 3. A three-call page therefore costs ~35ms of pure overhead. That is the
70	number the Open decision below turns on, and it is why a per-file last-commit column is
71	a decision and not a detail: at one call per entry, a twenty-file directory is ~230ms
72	before any real work.
73
74	### Open
75
76	- The ref-versus-path ambiguity in the URL. `/{handle}/repos/{name}/tree/{ref}/{path}`
77	is unparseable in general, because a ref may contain slashes: `tree/feature/x/README`
78	splits two ways. GitHub resolves it by trying candidate splits against the real ref
79	list; GitLab inserts a `/-/` separator. A third option is a single-segment ref with the
80	path after it, refusing refs with slashes. This is a URL shape, so it is expensive to
81	change later. Recommendation: the separator. Candidate splits cost a ref lookup —
82	another fork on every page — which the decision above makes more expensive, and a
83	separator is unambiguous by construction rather than by lookup.
84	- How a blob page handles what is not source code. Binary files, invalid UTF-8, and
85	very large files all arrive at the same page. Deciding beats discovering.
86	- How far back the commit log goes before it needs paging.
87
88	### Watch for
89
90	- An empty repository has no `HEAD`. Steid creates repositories empty, and
91	Milestone 4 made it easy to have one that was never pushed to. `rev-parse HEAD` fails
92	rather than returning nothing, and the repository page must say "nothing here yet"
93	instead of erroring.
94	- A blob is not necessarily text. Binary files, invalid UTF-8, and very large files
95	all reach the same page. Decide what each does rather than discovering it.
96	- Paths in URLs reach the filesystem indirectly, via git rather than directly, but a
97	path is still user input arriving at a subprocess argument. `--` before path arguments,
98	as `init_bare` already does.
99	- The commit log is unbounded. A repository with 50,000 commits needs a limit before
100	the page renders one.
101
102	### Carried over — small, unblocked
103
104	- A client that disappears mid-request leaves the body-copy task waiting. The copy
105	into git's stdin runs in its own task and nothing cancels it if the connection drops.
106	Bounded by the backend exiting and closing the pipe, but not by anything deliberate.
107	- `REMOTE_USER` is not set on the backend, so a push is recorded in the repository's
108	reflog without naming who made it. Steid knows the actor by then; it simply is not
109	passed through. Small, and worth doing before anything reads reflogs.
110	- No rate limiting on token authentication. A token is 256 bits so guessing is not
111	the worry; unbounded hashing on an open endpoint is.
112	- Tokens have no expiry and no last-used timestamp. Both deliberate omissions for
113	now — see [0007](decisions/0007-tokens-over-http-basic.md) — but a token list with no
114	"last used" makes it hard to know which are safe to revoke.
115	- A subprocess per git request. Unlike Milestone 3's once-per-creation, this is on a
116	hot path and has not been measured. Milestone 5 is where that bill comes due.
117	- Streaming is by construction, not by measurement. The response body is never
118	collected, but no clone large enough to prove it has been run.
119	- An orphaned repo directory is possible if the process dies between the record
120	write and the filesystem write, and it then blocks re-creating that name. The durable
121	fix is a reconciliation sweep on boot
122	([architecture.md](architecture.md#db-plus-filesystem-writes)); clearing one is a
123	manual `rm` today, since repo deletion does not exist.
124	- The duplicate-name check races. The loser is caught by `init_bare` or the unique
125	constraint, but surfaces as an opaque storage error rather than "name taken".
126	- Bare repos created on macOS carry `ignorecase = true`. A migration gotcha if the
127	data directory ever moves to Linux.
128	- Fonts are not loaded. The theme names Geist and IBM Plex Mono; both fall back
129	today. Topcoat's `font-fontsource` feature handles it.
130	- Light mode is untested. The palette defines it; nobody has looked at it.
131	- No rate limiting on `/auth/login` or `/auth/setup`.
132	- `sweep_expired` is never called, so expired session rows accumulate. Expiry is
133	enforced on read, so this is tidiness, not a hole.
134	- CSRF. `SameSite=Lax` covers the common case. Forms now exist, so this is decidable
135	rather than hypothetical.
136
137	## Backlog
138
139	Ordered. Pull from the top.
140
141	1. Milestone 6 — Writing. Posts, markdown, `/{handle}/posts/{slug}`. Still open
142	whether writing or projects/showcases is the better first portfolio feature.
143
144	## Open questions
145
146	- Topcoat is early (v0.5.0, first released 2026-07-22, breaking changes expected
147	by its own authors). Expect churn that isn't feature work.
148	- Topcoat ships Tailwind without Node, which reopens the design system attempt #1
149	dropped purely to avoid an npm build step — see [ui.md](ui.md).
150
151	## Routing findings (Milestone 0)
152
153	- Topcoat 0.5 requires rustc ≥ 1.95. On an older toolchain `cargo add topcoat`
154	silently resolves to an empty `topcoat v0.0.0` placeholder instead of failing. Local
155	stable is now 1.97.1.
156	- `Router::builder().discover()` collects `#[page]`-annotated items at link time,
157	so pages can live in any module. Layering is our choice, not the framework's.
158	- `module_router!` derives each URL from the module tree rather than a path string.
159	Still deferred. Application routes now group cleanly (`auth/login`, `api/me`), but
160	handles sit at the root ([0004](decisions/0004-root-handles-grouped-routes.md)), so a
161	parameterised root segment still has to coexist with static ones. Worth checking how
162	`module_router!` handles that before committing to it.
163	- Path and query params are read from `Cx` via `path_param!` / `#[query_params]`, not
164	injected as handler arguments. Parses are memoized per request.
165	- Layouts wrap by path prefix and nest outermost-first, and a layout can catch a page's
166	`NotFoundError` to render a branded 404.
167	- `HOST` / `PORT` configure the bind address, so `STEID_LISTEN_ADDR` is gone.
168	- `Body` is a boxed `http_body::Body` used for both requests and responses, with
169	`into_data_stream()` to read and `Body::new()` to wrap a stream — pack data can
170	stream both directions without buffering. This is what makes Milestone 4 viable.