flaxo/ghost

public

Source code of Ghost - On Ghost

you can raise PRs nowb3cc97da month ago77 lines · 3.3 KB

1	# 0011 — Deferred decisions
2
3	Status: open
4
5	Things deliberately not built yet, with the reasoning that will be needed when
6	they are.
7
8	## Authentication
9
10	`@OptionalAuth()` is currently blanket on `GitController`, so
11	`git-receive-pack` accepts anonymous pushes. Git CLI sends HTTP Basic, not the
12	Better Auth session cookie, so a dedicated guard is required. Three rules it
13	must encode:
14
15	1. `git-receive-pack` always requires authentication.
16	2. `info/refs?service=git-upload-pack` is anonymous for public repositories.
17	3. A 401 must carry
18	errors out instead of prompting for credentials.
19
20	`pushedBy` threads through `commitPush` already and is written to every entry
21	header; it is `null` until this lands.
22
23	## Repository resolution
24
25	Resolved. `toRepoId()
26	the repository and now keeps the row, so the transport carries
27	`repository.id` and both the log key and the cache path are the stable row id.
28	Renaming a user or a repository no longer orphans its log, and `getRepoPath`
29	can no longer auto-create a repository nobody owns, because every caller now
30	comes from an authorized row rather than a URL segment.
31
32	Existing deployments have logs under the old `username/repo` keys. There is no
33	migration for that: the keyspace changed, and this is a prototype.
34
35	## Entry uploads are a single PutObject
36
37	Streaming landed in [0015](0015-nothing-holds-a-packfile.md
38	still written with one `PutObject` carrying an explicit `ContentLength`. Within
39	the 5 GiB single-object limit, but a stream cannot be rewound, so any mid-flight
40	failure re-uploads the whole entry. `@aws-sdk/lib-storage`'s `Upload` would make
41	it multipart and resumable. Entries are content-addressed and idempotent, so
42	this is throughput, not correctness.
43
44	## Push failures are reported as JSON, not sideband
45
46	`NonFastForwardError` reaches `DomainErrorFilter` and renders as JSON. Git
47	clients expect failures inside the `report-status` sideband and will show an
48	unhelpful error. Needs a pkt-line status encoder on the response path.
49
50	## Checkpoints and compaction
51
52	Reading the whole log on every push is O(history). The plan is
53	`checkpoint/<repoId>/<seq>` holding a materialized ref map and live layer list,
54	after which readers fetch the newest checkpoint and only the entries beyond it.
55
56	Checkpoints are derived, immutable, and named by seq, so writing one is
57	idempotent, two racing compactors write identical bytes, and a crash mid-write
58	leaves nothing to clean up. Compaction must stay off the push critical path.
59	`compactedThroughSeq` exists in the index format for this and is currently
60	always 0.
61
62	## Garbage collection
63
64	See [0010](0010-orphans-are-garbage.md
65
66	## `.git
67
68	`git clone host/user/repo.git` and `host/user/repo` must both work. Currently
69	handled incidentally inside `getRepoPath`'s regex and `toRepoId`. It belongs in
70	a param pipe once repository lookup is real, so normalization happens once.
71
72	## Prior art worth reading first
73
74	JGit's DFS backend (`DfsRepository`, `DfsRefDatabase`, `
75	design already built and running at scale: git on blob storage with a CAS ref
76	database. The pack/ref split, the ref-CAS retry loop, and "objects need no
77	transaction" are all load-bearing there too.