clover's git

the-knife

1	---
2	title: Overview
3	description: One layer graph, provided once, builds the Worker and every Durable Object behind it. Each line is a decision with implementations you choose or write.
4	---
5
6	The examples use `Authentication` from
7	[Getting Started](/git/getting-started): the application's request middleware.
8
9	A git host is six decisions: what serves HTTP and who may call it,
10	where refs and objects live, how names resolve, where bulk bytes go,
11	what verifies a push, and which refs may move. Each is a
12	[Layer](/infrastructure-as-effects/layers), and you make them in one
13	graph:
14
15	```typescript
16	const GitLive = Git.ApiLive.pipe(
17	Layer.provide(Git.ApiHandlersLive),
18	Layer.provide(Authentication.layer),
19	Layer.provide(Git.ReposDurableObject),
20	Layer.provide(Git.RegistryDurableObject),
21	Layer.provide(Git.HasherInline),
22	Layer.provide(Git.BlobStoreR2(GitObjects)),
23	);
24	```
25
26	One graph, one `Effect.provide`. Build it with `Layer.*` and provide it
27	once.
28
29	## Two runtimes, one graph
30
31	A repository needs one place where a ref moves atomically. On
32	Cloudflare that is a Durable Object, and the code that moves refs runs
33	inside it. The graph does not know this. You write it once, the Worker
34	builds its side of it at cold start, and each Durable Object builds its
35	own on its first request:
36
37	```
38	GitLive
39	┌─────────────┴──────────────┐
40	Worker Repo Durable Object
41	wire, REST, GitHub facade refs, objects, pull requests
42	your middleware and policies push commit, jobs
43	BlobStore: clone bundles BlobStore: packs, spilled pushes
44	```
45
46	`Git.BlobStoreR2(GitObjects)` appears once and serves both sides: the
47	Worker streaming a clone bundle and the Durable Object writing a pack.
48	Your middleware and application policies run in the Worker request. They can
49	use the same user and database services.
50
51	## The blocks
52
53	| Block | Decides | Ships with |
54	| --- | --- | --- |
55	| [HTTP routes](/git/blocks/server) | the HTTP surface: every plane as one `HttpApi` of routes you can replace, behind your middleware | `ApiHandlersLive`, `ApiLive`, `InternalApiLive` |
56	| [Repository](/git/blocks/repositories) | where refs and objects live, the jobs that keep a repository small | `ReposDurableObject` |
57	| [Registry](/git/blocks/registry) | how `owner/name` resolves, and listings | `RegistryDurableObject`, `RegistryD1` |
58	| [Blob Store](/git/blocks/blob-store) | where packs, bundles, and large pushes go | `BlobStoreR2`, `BlobStoreS3` |
59	| [Hasher](/git/blocks/hasher) | what verifies a push, and on which compute | `HasherInline`, `HasherWorkerLoader`, `HasherLambda` |
60	| [Engine](/git/blocks/engine) | repository operations and scoped prepare/commit | `EngineLive` |
61	| [Auth](/git/blocks/auth) | application middleware and policy functions | native Effect HTTP middleware |
62
63	## Replacing a block
64
65	Every block is a `Context.Service`. Swap the Layer and nothing else in
66	the graph knows:
67
68	```diff lang="typescript"
69	const GitLive = Git.ApiLive.pipe(
70	Layer.provide(Git.ApiHandlersLive),
71	Layer.provide(Authentication.layer),
72	Layer.provide(Git.ReposDurableObject),
73	- Layer.provide(Git.RegistryDurableObject),
74	+ Layer.provide(Git.RegistryD1(RepoIndex)),
75	Layer.provide(Git.HasherInline),
76	Layer.provide(Git.BlobStoreR2(GitObjects)),
77	);
78	```
79
80	Leave one out and the Worker does not compile. The graph still requires
81	the service, and the compiler says which:
82
83	```typescript
84	const GitLive = Git.ApiLive.pipe(
85	Layer.provide(Git.ApiHandlersLive),
86	Layer.provide(Authentication.layer),
87	Layer.provide(Git.ReposDurableObject),
88	Layer.provide(Git.RegistryDurableObject),
89	Layer.provide(Git.HasherInline),
90	);
91	// Layer<Server, never, BlobStore>
92	// ^ still required; providing it to the Worker is a type error
93	```
94
95	Writing your own is implementing the contract. Each block's page shows
96	it, and the shape is always the same:
97
98	```typescript
99	const BlobStoreMine = Layer.effect(
100	Git.BlobStore,
101	Effect.gen(function* () {
102	// return a Git.BlobStoreShape
103	}),
104	);
105	```
106
107	## Where next
108
109	- [HTTP routes](/git/blocks/server) — the three planes as one `HttpApi`,
110	and replacing a route.
111	- [Recipes](/git/recipes) — which lines change for which
112	requirements.