clover's git

the-knife

1	---
2	title: Registry
3	description: The registry resolves owner/name to a repository and serves listings. Keep it in a Durable Object or move it to a D1 database.
4	---
5
6	The examples use `Authentication` from
7	[Getting Started](/git/getting-started): the application's request middleware.
8
9	The registry is the index. It maps `owner/name` to a repository id,
10	enforces that names are unique, and answers listings. Two
11	implementations ship, and the rest of the graph cannot tell them
12	apart.
13
14	## Durable Object
15
16	```typescript
17	Layer.provide(Git.RegistryDurableObject)
18	```
19
20	One singleton Durable Object for the whole service. Uniqueness comes
21	from its single-threaded transactions, and listings render from
22	denormalized columns so listing a thousand repositories touches one
23	object rather than a thousand.
24
25	The Worker caches resolutions in-isolate for a minute. A stale hit
26	fails safe: each repository's Durable Object stores its own
27	`owner/name` and rejects a request addressed to a different one.
28
29	## D1
30
31	```typescript
32	const RepoIndex = Cloudflare.D1.Database("RepoIndex");
33
34	const GitLive = Git.ApiLive.pipe(
35	Layer.provide(Git.ApiHandlersLive),
36	Layer.provide(Authentication.layer),
37	Layer.provide(Git.ReposDurableObject),
38	Layer.provide(Git.RegistryD1(RepoIndex)),
39	Layer.provide(Git.HasherInline),
40	Layer.provide(Git.BlobStoreR2(GitObjects)),
41	);
42	```
43
44	Same contract, different scaling shape. D1 replicates reads, and
45	`owner/name` resolution plus `WHERE owner = ?` listing are what a
46	relational store is built for. Writes are rare by comparison: a create,
47	a delete, a summary refresh after a push.
48
49	Uniqueness moves with it. `PRIMARY KEY (owner, name)` and an insert
50	guarded by `WHERE NOT EXISTS` make the create atomic inside SQLite, so
51	a losing racer sees `RepoAlreadyExists` exactly as it does on the
52	Durable Object. The table is created on first use from the same DDL
53	the Durable Object applies.
54
55	## Choosing
56
57	| | `RegistryDurableObject` | `RegistryD1` |
58	| --- | --- | --- |
59	| Resolution reads | one object, one region, cached a minute at the Worker | replicated |
60	| Listings | denormalized columns in the object | SQL over the table |
61	| Creates per second | hundreds | hundreds |
62	| Extra resources | none | a D1 database you declare |
63
64	Start with the Durable Object. Move to D1 when the registry's single
65	region shows up in resolution latency for users far from it, or when
66	you want to query the index with SQL from elsewhere.