@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 426 lines 15.2 KB
Raw
1 /**
2 * Protocol-v0 push choreography (DESIGN §2.3, §3.6, §4) as pure functions.
3 *
4 * Request shape (`POST /git-receive-pack`):
5 *
6 * ```
7 * *PKT-LINE("shallow" SP obj-id) ; shallow clients
8 * PKT-LINE(old-oid SP new-oid SP refname NUL cap-list LF) ; first command
9 * *PKT-LINE(old-oid SP new-oid SP refname LF)
10 * flush-pkt
11 * [raw PACK bytes] ; NOT pkt-line framed
12 * ```
13 *
14 * The pack follows the flush as raw bytes and is present iff any
15 * create/update command exists (it may be an empty 0-object pack); it is
16 * absent for delete-only pushes. Clients push **thin packs** over HTTP by
17 * default — REF_DELTA bases resolve from the object store during ingest.
18 *
19 * The **empty-flush probe**: git sends a bare `0000` POST when the payload
20 * exceeds `http.postBuffer`; the server replies with an empty 200 so the
21 * client retries with the real body.
22 *
23 * The choreography splits so the Repo DO owns the transaction:
24 * {@link parseReceivePackRequest} → {@link ingestPushPack} (staging sink) →
25 * {@link checkConnectivity} → DO `transactionSync` CAS →
26 * {@link reportStatus}.
27 */
28 import * as Effect from "effect/Effect";
29 import {
30 concatBytes,
31 isOid,
32 ObjectParseError,
33 type ObjectType,
34 type Oid,
35 parseCommit,
36 parseTag,
37 parseTree,
38 treeEntryKind,
39 ZERO_OID,
40 } from "./ObjectCodec.ts";
41 import {
42 bufferRandomAccess,
43 ingestPack,
44 type IngestSummary,
45 type PackIngestError,
46 type ResolvedEntry,
47 type ThinBaseSource,
48 } from "./PackParser.ts";
49 import {
50 flushPkt,
51 PktLineError,
52 pktPayloadText,
53 pktText,
54 ProtocolError,
55 readPktLineAt,
56 } from "./Pkt.ts";
57 import { sidebandFrames } from "./Sideband.ts";
58 import { StoreError } from "./Store.ts";
59
60 // ─────────────────────────────────────────────────────────────────────────────
61 // Commands
62 // ─────────────────────────────────────────────────────────────────────────────
63
64 /**
65 * One ref update command: `old-oid SP new-oid SP refname`. `old-oid` is the
66 * client's expectation and the CAS token; zero-id old ⇒ create, zero-id new
67 * ⇒ delete.
68 */
69 export interface RefCommand {
70 readonly oldOid: Oid;
71 readonly newOid: Oid;
72 readonly ref: string;
73 }
74
75 /** The kind of a ref command derived from its zero-id sides. */
76 export type CommandKind = "create" | "update" | "delete";
77
78 /**
79 * Classifies a command: zero old-oid ⇒ `create`, zero new-oid ⇒ `delete`,
80 * else `update`.
81 */
82 export const commandKind = (command: RefCommand): CommandKind =>
83 command.oldOid === ZERO_OID ? "create" : command.newOid === ZERO_OID ? "delete" : "update";
84
85 /**
86 * A parsed `git-receive-pack` request.
87 */
88 export interface ReceivePackRequest {
89 /** Ref update commands, in request order. */
90 readonly commands: ReadonlyArray<RefCommand>;
91 /** Capabilities chosen by the client (after the NUL on the first command). */
92 readonly capabilities: ReadonlySet<string>;
93 /** `shallow` lines from shallow clients (v1: parsed, not honored). */
94 readonly shallow: ReadonlyArray<Oid>;
95 /** Byte offset of the raw pack in the body (position after the flush). */
96 readonly packOffset: number;
97 /** Whether raw pack bytes follow the flush. */
98 readonly hasPack: boolean;
99 /** `atomic` requested: all-or-nothing ref updates. */
100 readonly atomic: boolean;
101 /** `side-band-64k` requested: the report must be muxed on band 1. */
102 readonly sideband: boolean;
103 /** `report-status` or `report-status-v2` requested. */
104 readonly reportStatus: boolean;
105 }
106
107 /**
108 * The outcome of parsing a receive-pack body: the empty-flush probe (reply
109 * with an empty 200) or a real request.
110 */
111 export type ParsedReceivePack =
112 | { readonly _tag: "probe" }
113 | { readonly _tag: "request"; readonly request: ReceivePackRequest };
114
115 // control chars, space, DEL, and git's forbidden refname metacharacters
116 // oxlint-disable-next-line no-control-regex
117 const REFNAME_FORBIDDEN = new RegExp("[\\x00-\\x20\\x7f\\\\~^:?*\\[]");
118
119 const validRefName = (name: string): boolean =>
120 name.startsWith("refs/") &&
121 name.length > "refs/".length &&
122 !name.endsWith("/") &&
123 !name.includes("..") &&
124 !name.endsWith(".lock") &&
125 !REFNAME_FORBIDDEN.test(name);
126
127 const parseCommandLine = (line: string): Effect.Effect<RefCommand, ProtocolError> =>
128 Effect.suspend(() => {
129 const oldOid = line.slice(0, 40);
130 const newOid = line.slice(41, 81);
131 const ref = line.slice(82);
132 if (
133 !isOid(oldOid) ||
134 line[40] !== " " ||
135 !isOid(newOid) ||
136 line[81] !== " " ||
137 ref.length === 0
138 ) {
139 return Effect.fail(ProtocolError.make({ reason: `malformed command line: ${line}` }));
140 }
141 if (!validRefName(ref)) {
142 return Effect.fail(ProtocolError.make({ reason: `invalid refname: ${ref}` }));
143 }
144 if (oldOid === ZERO_OID && newOid === ZERO_OID) {
145 return Effect.fail(ProtocolError.make({ reason: `zero-to-zero command for ${ref}` }));
146 }
147 return Effect.succeed({ oldOid, newOid, ref });
148 });
149
150 /**
151 * Parses a `git-receive-pack` request body (already gunzipped): shallow
152 * lines, the command list (NUL-separated caps on the first command), the
153 * flush, and the position of the raw pack payload. A body containing no
154 * commands is the **empty-flush probe**.
155 */
156 export const parseReceivePackRequest = Effect.fn(function* (body: Uint8Array) {
157 const commands: Array<RefCommand> = [];
158 const capabilities = new Set<string>();
159 const shallow: Array<Oid> = [];
160 let pos = 0;
161
162 for (;;) {
163 const result = readPktLineAt(body, pos);
164 if (result._tag === "incomplete") {
165 return yield* PktLineError.make({
166 reason: `truncated receive-pack request at offset ${pos}`,
167 });
168 }
169 if (result._tag === "invalid") {
170 return yield* PktLineError.make({ reason: result.reason });
171 }
172 const pkt = result.pkt;
173 if (pkt._tag === "flush") {
174 pos = result.next;
175 break;
176 }
177 if (pkt._tag !== "data") {
178 return yield* ProtocolError.make({
179 reason: `unexpected ${pkt._tag} packet in receive-pack request`,
180 });
181 }
182 const text = pktPayloadText(pkt.payload);
183 if (text.startsWith("shallow ")) {
184 const oid = text.slice(8);
185 if (!isOid(oid)) {
186 return yield* ProtocolError.make({
187 reason: `malformed shallow line: ${text}`,
188 });
189 }
190 shallow.push(oid);
191 } else {
192 const nul = text.indexOf("\0");
193 const line = nul === -1 ? text : text.slice(0, nul);
194 if (nul !== -1) {
195 for (const cap of text.slice(nul + 1).split(" ")) {
196 if (cap.length > 0) capabilities.add(cap);
197 }
198 }
199 commands.push(yield* parseCommandLine(line));
200 }
201 pos = result.next;
202 }
203
204 if (commands.length === 0) {
205 return { _tag: "probe" } as ParsedReceivePack;
206 }
207
208 const request: ReceivePackRequest = {
209 commands,
210 capabilities,
211 shallow,
212 packOffset: pos,
213 hasPack: pos < body.length,
214 atomic: capabilities.has("atomic"),
215 sideband: capabilities.has("side-band-64k"),
216 reportStatus: capabilities.has("report-status") || capabilities.has("report-status-v2"),
217 };
218 return { _tag: "request", request } as ParsedReceivePack;
219 });
220
221 // ─────────────────────────────────────────────────────────────────────────────
222 // Ingest driver
223 // ─────────────────────────────────────────────────────────────────────────────
224
225 /**
226 * Options for {@link ingestPushPack}.
227 */
228 export interface IngestPushOptions<E, R> {
229 /** The full (gunzipped, buffered) request body. */
230 readonly body: Uint8Array;
231 /** `request.packOffset` from {@link parseReceivePackRequest}. */
232 readonly packOffset: number;
233 /** Live objects — resolves thin REF_DELTA bases. */
234 readonly store: ThinBaseSource;
235 /** Receives each resolved entry (the DO stages it under the push id). */
236 readonly sink: (entry: ResolvedEntry) => Effect.Effect<void, E, R>;
237 /** Per-object uncompressed cap; defaults to the parser's 64 MiB. */
238 readonly maxObjectSize?: number | undefined;
239 }
240
241 /**
242 * Drives {@link ingestPack} over the pack payload of a push body. A
243 * delete-only push (no pack bytes) yields an empty summary without touching
244 * the parser.
245 */
246 export const ingestPushPack = <E, R>(
247 options: IngestPushOptions<E, R>,
248 ): Effect.Effect<IngestSummary, PackIngestError | E, R> =>
249 options.packOffset >= options.body.length
250 ? Effect.succeed({ count: 0, oids: [] })
251 : ingestPack({
252 source: bufferRandomAccess(options.body.subarray(options.packOffset)),
253 store: options.store,
254 sink: options.sink,
255 maxObjectSize: options.maxObjectSize,
256 });
257
258 // ─────────────────────────────────────────────────────────────────────────────
259 // Connectivity check
260 // ─────────────────────────────────────────────────────────────────────────────
261
262 /**
263 * A staged object's identity, as needed by the connectivity walk.
264 */
265 export interface StagedObjectRef {
266 readonly oid: Oid;
267 readonly type: ObjectType;
268 }
269
270 /**
271 * The membership oracle and content reader the connectivity check needs —
272 * implemented by the Repo DO over batched SQL.
273 */
274 export interface ConnectivityDeps {
275 /** Reads a staged object's inflated content. */
276 readonly readStagedContent: (oid: Oid) => Effect.Effect<Uint8Array, StoreError>;
277 /**
278 * Filters oids down to those existing among **live** objects (batched,
279 * chunked `IN` lists; order not guaranteed).
280 */
281 readonly filterLiveExisting: (
282 oids: ReadonlyArray<Oid>,
283 ) => Effect.Effect<ReadonlyArray<Oid>, StoreError>;
284 }
285
286 /**
287 * The full connectivity check (DESIGN §3.6 step 5): collects every oid
288 * referenced by staged commits (tree, parents), staged trees (entries —
289 * gitlinks excluded, they point outside the repo), staged tags (target),
290 * plus every command's non-zero `new-oid`; then verifies membership against
291 * staged ∪ live objects. Returns the missing oids (empty = connected).
292 *
293 * This is the difference between "corrupt client" and "corrupt repo": any
294 * miss fails the push with `unpack missing objects` + all-`ng`.
295 */
296 export const checkConnectivity = Effect.fn(function* (
297 staged: ReadonlyArray<StagedObjectRef>,
298 commandNewOids: ReadonlyArray<Oid>,
299 deps: ConnectivityDeps,
300 ) {
301 const stagedSet = new Set(staged.map((s) => s.oid));
302 const referenced = new Set<Oid>();
303
304 for (const object of staged) {
305 switch (object.type) {
306 case 1: {
307 const content = yield* deps.readStagedContent(object.oid);
308 const commit = yield* parseCommit(content);
309 referenced.add(commit.tree);
310 for (const parent of commit.parents) referenced.add(parent);
311 break;
312 }
313 case 2: {
314 const content = yield* deps.readStagedContent(object.oid);
315 const entries = yield* parseTree(content);
316 for (const entry of entries) {
317 // gitlinks (mode 160000) reference commits in other repos — skip
318 if (treeEntryKind(entry.mode) !== "commit") {
319 referenced.add(entry.oid);
320 }
321 }
322 break;
323 }
324 case 4: {
325 const content = yield* deps.readStagedContent(object.oid);
326 const tag = yield* parseTag(content);
327 referenced.add(tag.object);
328 break;
329 }
330 default:
331 break; // blobs reference nothing
332 }
333 }
334 for (const oid of commandNewOids) {
335 if (oid !== ZERO_OID) referenced.add(oid);
336 }
337
338 const candidates = [...referenced].filter((oid) => !stagedSet.has(oid));
339 if (candidates.length === 0) return [] as ReadonlyArray<Oid>;
340 const live = new Set(yield* deps.filterLiveExisting(candidates));
341 return candidates.filter((oid) => !live.has(oid)).sort();
342 });
343
344 // ─────────────────────────────────────────────────────────────────────────────
345 // report-status
346 // ─────────────────────────────────────────────────────────────────────────────
347
348 /**
349 * The per-ref outcome of the CAS transaction, produced by the Repo DO and
350 * rendered by {@link reportStatus}.
351 */
352 export interface CommandResult {
353 readonly ref: string;
354 readonly ok: boolean;
355 /** Failure reason for `ng` lines (e.g. `fetch first`). */
356 readonly reason?: string | undefined;
357 }
358
359 /** Builds an `ok <ref>` result. */
360 export const okResult = (ref: string): CommandResult => ({ ref, ok: true });
361
362 /** Builds an `ng <ref> <reason>` result. */
363 export const ngResult = (ref: string, reason: string): CommandResult => ({
364 ref,
365 ok: false,
366 reason,
367 });
368
369 /**
370 * Options for {@link reportStatus}.
371 */
372 export interface ReportStatusOptions {
373 /** `"ok"` when the pack ingested cleanly, else the unpack error message. */
374 readonly unpack: string;
375 /** Per-ref results in command order. */
376 readonly results: ReadonlyArray<CommandResult>;
377 /** Wrap the report in side-band band 1 (mandatory when negotiated). */
378 readonly sideband: boolean;
379 }
380
381 /**
382 * Renders the `report-status` (and `report-status-v2` — implemented
383 * identically, with no `option` lines, which is valid) response:
384 *
385 * ```
386 * unpack ok|<error>
387 * ok <ref> | ng <ref> <reason> (per command)
388 * flush
389 * ```
390 *
391 * When the client negotiated `side-band-64k` the entire report (including
392 * its flush) is wrapped in band-1 frames followed by the outer flush —
393 * sending it unmuxed while side-band is active breaks the client.
394 */
395 export const reportStatus = (options: ReportStatusOptions): Uint8Array => {
396 const inner = concatBytes([
397 pktText(`unpack ${options.unpack}`),
398 ...options.results.map((result) =>
399 pktText(result.ok ? `ok ${result.ref}` : `ng ${result.ref} ${result.reason ?? "failed"}`),
400 ),
401 flushPkt,
402 ]);
403 return options.sideband ? concatBytes([...sidebandFrames(1, inner), flushPkt]) : inner;
404 };
405
406 /**
407 * Renders the all-failed report used for whole-push rejections: pack too
408 * large, checksum mismatch, missing objects, read-only repo. `unpack` carries
409 * the reason and every command gets an `ng` with the same reason.
410 */
411 export const failAllReport = (
412 commands: ReadonlyArray<RefCommand>,
413 reason: string,
414 sideband: boolean,
415 ): Uint8Array =>
416 reportStatus({
417 unpack: reason,
418 results: commands.map((command) => ngResult(command.ref, reason)),
419 sideband,
420 });
421
422 /** Errors the parse phase of receive-pack can produce. */
423 export type ReceivePackParseError = PktLineError | ProtocolError;
424
425 /** Errors the connectivity check can produce. */
426 export type ConnectivityError = StoreError | ObjectParseError;