The best way to control Claude Code, Codex and more from any computer or phone

main
ts 247 lines 8.96 KB
Raw
1 import { RuntimeContext } from "alchemy/RuntimeContext";
2 import * as Effect from "effect/Effect";
3 import * as Stream from "effect/Stream";
4 /**
5 * The clone-bundle alarm job (DESIGN.md §12.2) — the v2 serving plane.
6 *
7 * A clone is, on the wire, exactly one pack containing the closure of the
8 * advertised refs. v1 recomputes that pack per clone (walk the commit graph,
9 * walk every tree, emit every object). A **bundle** computes it once, after
10 * pushes settle, and stores it in R2 under a key derived from the ref
11 * snapshot it covers:
12 *
13 * ```
14 * {repoId}/bundles/bundle-{refsHash}.pack
15 * ```
16 *
17 * Serving a clone then becomes "stream these bytes" — no closure walk, no
18 * per-object reads, no compression. Because the key is content-addressed by
19 * its ref snapshot, the bytes are immutable and therefore cacheable at every
20 * edge PoP, and the Worker can stream them straight to the client without
21 * the Durable Object touching a single pack byte.
22 *
23 * The pack is streamed to R2 with a **precomputed content length** (every
24 * entry is `varint(type,size) + zdata`, and both are known from the object
25 * index), so bundling a large repo never buffers the pack in memory.
26 */
27 import { BlobStoreError, type BlobStoreShape } from "../BlobStore.ts";
28 import { encodeTypeSize, makeSha1, type Oid, type PackEntryType } from "../Protocol/ObjectCodec.ts";
29 import { sidebandFramedLength, sidebandRechunk } from "../Protocol/Sideband.ts";
30 import { StoreError, type ManifestEntry } from "../Protocol/Store.ts";
31 import { bundleKey, bundleSidebandKey } from "../Store/Keys.ts";
32
33 /** A ref as it appears in a bundle's covered snapshot. */
34 export interface BundleRef {
35 readonly name: string;
36 readonly oid: string;
37 }
38
39 /**
40 * What a repo records about its current bundle (stored as JSON in the
41 * `config` table under `bundle`).
42 */
43 export interface BundleInfo {
44 /** sha1 over the sorted `name oid` lines the bundle covers. */
45 readonly refsHash: string;
46 /** Full R2 key of the pack. */
47 readonly key: string;
48 /** Object count inside the pack. */
49 readonly objectCount: number;
50 /** Exact byte length of the pack. */
51 readonly size: number;
52 /** The ref snapshot this bundle covers. */
53 readonly refs: ReadonlyArray<BundleRef>;
54 /** Epoch millis the bundle was cut. */
55 readonly createdAt: number;
56 }
57
58 /**
59 * Repos larger than this are not bundled in v2.0 — the win is clone-storm
60 * absorption on ordinary repos, and an unbounded bundle job would monopolise
61 * the alarm budget. (The streaming multipart upgrade lifts this.)
62 */
63 export const MAX_BUNDLE_BYTES = 512 * 1024 * 1024;
64
65 /**
66 * sha1 over the sorted `"<name> <oid>"` lines — the identity of a ref
67 * snapshot. Two repos states with the same refs produce the same hash, so
68 * the bundle key is stable and immutable.
69 */
70 export const hashRefs = (refs: ReadonlyArray<BundleRef>): string => {
71 const hash = makeSha1();
72 const lines = [...refs]
73 .map((ref) => `${ref.name} ${ref.oid}`)
74 .sort()
75 .join("\n");
76 hash.update(new TextEncoder().encode(lines));
77 return hash.digestHex();
78 };
79
80 /**
81 * Exact byte length of the pack `entries` will produce: the 12-byte header,
82 * each entry's varint type/size header plus its stored zdata, and the
83 * 20-byte trailer. Lets the bundle stream straight into R2 without
84 * buffering.
85 */
86 export const packByteLength = (entries: ReadonlyArray<ManifestEntry>): number => {
87 let total = 12 + 20;
88 for (const entry of entries) {
89 total += encodeTypeSize(entry.type as PackEntryType, entry.size).length + entry.zsize;
90 }
91 return total;
92 };
93
94 /** Dependencies of {@link runBundleJob}. */
95 export interface BundleJobOptions {
96 readonly repoId: string;
97 readonly refs: ReadonlyArray<BundleRef>;
98 /** The full-clone manifest (closure of every ref). */
99 readonly entries: ReadonlyArray<ManifestEntry>;
100 /** Emits the pack for `entries` — `RepoObject`'s `packStream`. */
101 readonly packStream: (
102 entries: ReadonlyArray<ManifestEntry>,
103 ) => Stream.Stream<Uint8Array, StoreError>;
104 readonly blobs: BlobStoreShape;
105 readonly maxBytes?: number | undefined;
106 }
107
108 /**
109 * Cuts a clone bundle for the given ref snapshot and returns what to record
110 * on the repo. Returns `undefined` when the repo is too large to bundle in
111 * v2.0 or has no refs (nothing to clone).
112 */
113 export const runBundleJob = (
114 options: BundleJobOptions,
115 ): Effect.Effect<BundleInfo | undefined, StoreError> =>
116 Effect.gen(function* () {
117 if (options.refs.length === 0 || options.entries.length === 0) {
118 return undefined;
119 }
120 const size = packByteLength(options.entries);
121 if (size > (options.maxBytes ?? MAX_BUNDLE_BYTES)) {
122 return undefined;
123 }
124 const refsHash = yield* Effect.sync(() => hashRefs(options.refs));
125 const key = bundleKey(options.repoId, refsHash);
126
127 // The pack streams straight into R2 (its byte length is known up front),
128 // so a large bundle is never buffered. StoreError may surface from the
129 // stream itself (an object read failing mid-pack); R2Error from the put.
130 yield* options.blobs
131 .put(
132 key,
133 options
134 .packStream(options.entries)
135 .pipe(Stream.mapError((error) => new BlobStoreError({ reason: error.reason }))),
136 { contentLength: size },
137 )
138 .pipe(
139 Effect.mapError((error: BlobStoreError) =>
140 StoreError.make({ reason: `blob put ${key}: ${error.reason}` }),
141 ),
142 Effect.provide(RuntimeContext.phantom),
143 );
144
145 // The pre-framed twin (Keys.ts `bundleSidebandKey`): one more pass over
146 // the same entries, framed deterministically so the length is known.
147 const sidebandKey = bundleSidebandKey(options.repoId, refsHash);
148 yield* options.blobs
149 .put(
150 sidebandKey,
151 options.packStream(options.entries).pipe(
152 Stream.mapError((error) => new BlobStoreError({ reason: error.reason })),
153 sidebandRechunk(1),
154 ),
155 { contentLength: sidebandFramedLength(size) },
156 )
157 .pipe(
158 Effect.mapError((error: BlobStoreError) =>
159 StoreError.make({
160 reason: `blob put ${sidebandKey}: ${error.reason}`,
161 }),
162 ),
163 Effect.provide(RuntimeContext.phantom),
164 );
165
166 return {
167 refsHash,
168 key,
169 objectCount: options.entries.length,
170 size,
171 refs: options.refs,
172 createdAt: Date.now(),
173 } satisfies BundleInfo;
174 });
175
176 /**
177 * Decides whether a recorded bundle can serve this fetch (DESIGN.md §12.2,
178 * tier 1 "exact match").
179 *
180 * The bundle holds the closure of the refs it covers, so it is safe for any
181 * request that:
182 *
183 * - brings no `have`s and no shallow state (it is a *clone*, not an
184 * incremental fetch — otherwise the client would receive objects it
185 * already has, which is legal but wasteful, or miss the negotiation the
186 * protocol promised), and
187 * - wants only oids the bundle actually covers.
188 *
189 * Extra objects in a pack are legal, so a superset bundle serves a
190 * single-branch clone fine.
191 */
192 export const bundleCovers = (
193 bundle: BundleInfo,
194 request: {
195 readonly wants: ReadonlyArray<Oid>;
196 readonly haves: ReadonlyArray<Oid>;
197 readonly depth?: number | undefined;
198 readonly clientShallow: ReadonlyArray<Oid>;
199 },
200 ): boolean => {
201 const uncovered = bundleUncovered(bundle, request);
202 return uncovered !== undefined && uncovered.length === 0;
203 };
204
205 /**
206 * How much of a request this bundle can serve (DESIGN.md §21.2).
207 *
208 * - `undefined` — unusable: the request negotiates (haves) or is
209 * shallow. Serve dynamically.
210 * - `[]` — the bundle covers every want: stream its bytes verbatim.
211 * - non-empty — the wants the bundle does not name directly. Their
212 * closure, computed with the bundle's refs as haves, is a delta pack
213 * the Worker concatenates onto the bundle.
214 *
215 * A want the bundle does not *name* is usually still mostly IN it — the
216 * ordinary case is `main` having moved a few commits past the snapshot,
217 * so the bundle holds all but the new objects. Union completeness holds
218 * regardless: the bundle carries closure(bundle refs), the delta carries
219 * closure(wants) minus that, so together they cover closure(wants) with
220 * no duplicate entries. Only the *size* of the delta varies, and the
221 * caller drops the splice when it stops being a saving.
222 *
223 * The partial case is what keeps the fast path alive on a repo that is
224 * being pushed to: previously ANY ref moving after the bundle was cut
225 * made a clone's want-set uncovered, dropping every clone back onto the
226 * Durable Object until the next full re-cut.
227 */
228 export const bundleUncovered = (
229 bundle: BundleInfo,
230 request: {
231 readonly wants: ReadonlyArray<Oid>;
232 readonly haves: ReadonlyArray<Oid>;
233 readonly depth?: number | undefined;
234 readonly clientShallow: ReadonlyArray<Oid>;
235 },
236 ): ReadonlyArray<Oid> | undefined => {
237 if (
238 request.haves.length > 0 ||
239 request.depth !== undefined ||
240 request.clientShallow.length > 0 ||
241 request.wants.length === 0
242 ) {
243 return undefined;
244 }
245 const covered = new Set(bundle.refs.map((ref) => ref.oid));
246 return request.wants.filter((want) => !covered.has(want));
247 };