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

main
ts 353 lines 11.7 KB
Raw
1 /**
2 * Protocol-v0 fetch/clone choreography (DESIGN §2.3, §4) as pure functions
3 * over a parsed request plus injected {@link ObjectSource} /
4 * {@link ClosureSource}.
5 *
6 * Stateless-RPC reality (HTTP): each POST is independent; the client resends
7 * all wants plus all previously-ACKed haves every round. With
8 * `multi_ack_detailed` + `no-done` and the "lazy-ready" policy the
9 * negotiation converges in ≤ 2 POSTs:
10 *
11 * - POST ends with flush (no `done`): `ACK <oid> common` per recognized
12 * have, `ACK <last> ready` once the want-closure is coverable, else `NAK`.
13 * With `no-done` the server continues straight from `ready` into the pack.
14 * - POST ends with `done`: final `ACK <last common>` (else `NAK`), then the
15 * pack — on side-band band 1 when negotiated, raw bytes otherwise.
16 * - A fresh clone is one POST: wants + flush + `done`, no haves ⇒ `NAK` +
17 * pack.
18 *
19 * Shallow (`deepen <n>`): `shallow <oid>` boundary lines (and `unshallow`
20 * for previously-shallow client tips now complete), then a flush, before the
21 * ACK/NAK section; the pack is depth-truncated.
22 */
23 import * as Effect from "effect/Effect";
24 import * as Stream from "effect/Stream";
25 import { concatBytes, isOid, type Oid } from "./ObjectCodec.ts";
26 import { packDataBytes, type PackEvent, writePack } from "./PackWriter.ts";
27 import {
28 decodePktLines,
29 flushPkt,
30 PktLineError,
31 pktPayloadText,
32 pktText,
33 ProtocolError,
34 } from "./Pkt.ts";
35 import { progressMessage, sidebandFrames } from "./Sideband.ts";
36 import type { ClosureResult, ClosureSource, ObjectSource } from "./Store.ts";
37 import { StoreError } from "./Store.ts";
38
39 /**
40 * A parsed `git-upload-pack` request body.
41 */
42 export interface UploadPackRequest {
43 /** Requested tips, in request order (first `want` carried the caps). */
44 readonly wants: ReadonlyArray<Oid>;
45 /** The client's `have` lines, in request order. */
46 readonly haves: ReadonlyArray<Oid>;
47 /** Whether the request ended with `done` (vs a bare flush). */
48 readonly done: boolean;
49 /** Capabilities requested on the first `want` line (space-separated). */
50 readonly capabilities: ReadonlySet<string>;
51 /** Depth bound from `deepen <n>`, when present. */
52 readonly depth: number | undefined;
53 /** The client's existing shallow tips (`shallow <oid>` lines). */
54 readonly clientShallow: ReadonlyArray<Oid>;
55 }
56
57 const parseOidLine = (
58 text: string,
59 keyword: string,
60 ): Effect.Effect<{ readonly oid: Oid; readonly rest: string }, ProtocolError> =>
61 Effect.suspend(() => {
62 const body = text.slice(keyword.length + 1);
63 const oid = body.slice(0, 40);
64 if (!isOid(oid)) {
65 return Effect.fail(ProtocolError.make({ reason: `malformed ${keyword} line: ${text}` }));
66 }
67 return Effect.succeed({ oid, rest: body.slice(40).trim() });
68 });
69
70 /**
71 * Parses a `git-upload-pack` request body (already gunzipped) into a
72 * {@link UploadPackRequest}. Rejects arguments we do not advertise
73 * (`deepen-since`, `deepen-not`, `filter`) with a typed
74 * {@link ProtocolError}.
75 */
76 export const parseUploadPackRequest = Effect.fn(function* (body: Uint8Array) {
77 const pkts = yield* decodePktLines(body);
78 const wants: Array<Oid> = [];
79 const haves: Array<Oid> = [];
80 const clientShallow: Array<Oid> = [];
81 const capabilities = new Set<string>();
82 let depth: number | undefined;
83 let done = false;
84 let inHaves = false;
85
86 for (const pkt of pkts) {
87 if (pkt._tag === "flush") {
88 inHaves = true;
89 continue;
90 }
91 if (pkt._tag !== "data") {
92 return yield* ProtocolError.make({
93 reason: `unexpected ${pkt._tag} packet in upload-pack request`,
94 });
95 }
96 const text = pktPayloadText(pkt.payload);
97 if (!inHaves) {
98 if (text.startsWith("want ")) {
99 const { oid, rest } = yield* parseOidLine(text, "want");
100 wants.push(oid);
101 if (rest.length > 0) {
102 for (const cap of rest.split(" ")) {
103 if (cap.length > 0) capabilities.add(cap);
104 }
105 }
106 } else if (text.startsWith("shallow ")) {
107 const { oid } = yield* parseOidLine(text, "shallow");
108 clientShallow.push(oid);
109 } else if (text.startsWith("deepen ")) {
110 const n = Number.parseInt(text.slice(7), 10);
111 if (!Number.isInteger(n) || n <= 0) {
112 return yield* ProtocolError.make({
113 reason: `invalid deepen depth: ${text}`,
114 });
115 }
116 depth = n;
117 } else if (
118 text.startsWith("deepen-since ") ||
119 text.startsWith("deepen-not ") ||
120 text.startsWith("filter ")
121 ) {
122 return yield* ProtocolError.make({
123 reason: `unsupported argument: ${text.split(" ")[0]}`,
124 });
125 } else {
126 return yield* ProtocolError.make({
127 reason: `unexpected line in want section: ${text}`,
128 });
129 }
130 } else {
131 if (text.startsWith("have ")) {
132 const { oid } = yield* parseOidLine(text, "have");
133 haves.push(oid);
134 } else if (text === "done") {
135 done = true;
136 } else {
137 return yield* ProtocolError.make({
138 reason: `unexpected line in have section: ${text}`,
139 });
140 }
141 }
142 }
143
144 if (wants.length === 0) {
145 return yield* ProtocolError.make({
146 reason: "upload-pack request has no want lines",
147 });
148 }
149 const request: UploadPackRequest = {
150 wants,
151 haves,
152 done,
153 capabilities,
154 depth,
155 clientShallow,
156 };
157 return request;
158 });
159
160 /**
161 * The outcome of one negotiation round.
162 */
163 export interface Negotiation {
164 /** Haves that exist in the store, in the client's request order. */
165 readonly common: ReadonlyArray<Oid>;
166 /** Whether the server declared `ready` (lazy-ready: any common found). */
167 readonly ready: boolean;
168 /** Whether this response continues into a pack. */
169 readonly sendPack: boolean;
170 /** The encoded ACK/NAK pkt-line section. */
171 readonly ackSection: Uint8Array;
172 }
173
174 /**
175 * Runs the v0 `multi_ack_detailed` (+ `no-done`) negotiation for one
176 * stateless round: acks `common` for each recognized have, declares `ready`
177 * as soon as any common exists, and decides whether the pack follows in this
178 * response (`done` received, or `ready` under `no-done`).
179 */
180 export const negotiate = Effect.fn(function* (request: UploadPackRequest, objects: ObjectSource) {
181 const existing = new Set(yield* objects.filterExisting(request.haves));
182 const common = request.haves.filter((oid) => existing.has(oid));
183 const noDone = request.capabilities.has("no-done");
184 const multiAckDetailed = request.capabilities.has("multi_ack_detailed");
185 const last = common[common.length - 1];
186
187 const lines: Array<Uint8Array> = [];
188 let ready = false;
189 let sendPack: boolean;
190 if (request.done) {
191 // final round: single ACK of the last common oid, else NAK, then pack
192 lines.push(last !== undefined ? pktText(`ACK ${last}`) : pktText("NAK"));
193 sendPack = true;
194 } else if (last === undefined) {
195 lines.push(pktText("NAK"));
196 sendPack = false;
197 } else if (multiAckDetailed) {
198 for (const oid of common) {
199 lines.push(pktText(`ACK ${oid} common`));
200 }
201 lines.push(pktText(`ACK ${last} ready`));
202 ready = true;
203 if (noDone) {
204 // continue straight into the pack after `ready`
205 sendPack = true;
206 } else {
207 // every non-final round ends with NAK; the client sends `done` next
208 lines.push(pktText("NAK"));
209 sendPack = false;
210 }
211 } else {
212 // legacy single-ack fallback: ack the last common, wait for `done`
213 lines.push(pktText(`ACK ${last}`));
214 ready = true;
215 sendPack = false;
216 }
217 const negotiation: Negotiation = {
218 common,
219 ready,
220 sendPack,
221 ackSection: concatBytes(lines),
222 };
223 return negotiation;
224 });
225
226 /**
227 * A fully assembled upload-pack response.
228 */
229 export interface UploadPackResponse {
230 /** The response body, streamed chunked (`HttpServerResponse.stream`). */
231 readonly body: Stream.Stream<Uint8Array, StoreError>;
232 /** Whether side-band-64k framing was negotiated. */
233 readonly sideband: boolean;
234 /** Whether this response carries a pack (vs a negotiation-only round). */
235 readonly packSent: boolean;
236 /** Number of objects in the pack (0 when `packSent` is false). */
237 readonly objectCount: number;
238 }
239
240 /** Emit a progress event on band 2 every N pack entries. */
241 const PROGRESS_EVERY = 1000;
242
243 const shallowSection = (closure: ClosureResult): Uint8Array =>
244 concatBytes([
245 ...closure.shallow.map((oid) => pktText(`shallow ${oid}`)),
246 ...closure.unshallow.map((oid) => pktText(`unshallow ${oid}`)),
247 flushPkt,
248 ]);
249
250 const muxPackEvent = (event: PackEvent): Stream.Stream<Uint8Array> =>
251 event._tag === "data"
252 ? Stream.fromArray(sidebandFrames(1, event.bytes))
253 : Stream.succeed(progressMessage(`Counting objects: ${event.written}/${event.total}\r`));
254
255 /**
256 * Runs one full upload-pack round: validates the wants, negotiates, computes
257 * the closure when a pack is due, and assembles the streaming response body
258 * (shallow section, ACK/NAK section, then the pack — sideband-muxed with
259 * band-2 progress when negotiated, raw otherwise).
260 *
261 * Wants that do not exist in the store fail with `ProtocolError`
262 * (`not our ref`); the caller converts pre-stream failures into an `ERR`
263 * pkt / HTTP status. Mid-stream `StoreError`s surface on the body stream for
264 * the caller to translate into a band-3 fatal.
265 */
266 export const uploadPack = Effect.fn(function* (
267 request: UploadPackRequest,
268 objects: ObjectSource,
269 closure: ClosureSource,
270 ) {
271 const sideband = request.capabilities.has("side-band-64k");
272
273 const existingWants = new Set(yield* objects.filterExisting(request.wants));
274 for (const want of request.wants) {
275 if (!existingWants.has(want)) {
276 return yield* ProtocolError.make({ reason: `not our ref ${want}` });
277 }
278 }
279
280 const negotiation = yield* negotiate(request, objects);
281 const shallowRequested = request.depth !== undefined || request.clientShallow.length > 0;
282
283 if (!negotiation.sendPack) {
284 // negotiation-only round: shallow section (when requested) + acks
285 const sections: Array<Uint8Array> = [];
286 if (shallowRequested) {
287 const result = yield* closure.commitClosure({
288 wants: request.wants,
289 haves: negotiation.common,
290 depth: request.depth,
291 clientShallow: request.clientShallow,
292 });
293 sections.push(shallowSection(result));
294 }
295 sections.push(negotiation.ackSection);
296 const response: UploadPackResponse = {
297 body: Stream.fromArray(sections),
298 sideband,
299 packSent: false,
300 objectCount: 0,
301 };
302 return response;
303 }
304
305 const result = yield* closure.commitClosure({
306 wants: request.wants,
307 haves: negotiation.common,
308 depth: request.depth,
309 clientShallow: request.clientShallow,
310 });
311
312 const prelude: Array<Uint8Array> = [];
313 if (shallowRequested) prelude.push(shallowSection(result));
314 prelude.push(negotiation.ackSection);
315
316 const events = writePack(result.entries, objects, {
317 progressEvery: sideband ? PROGRESS_EVERY : undefined,
318 });
319
320 const body = sideband
321 ? Stream.concat(
322 Stream.concat(
323 Stream.fromArray([
324 ...prelude,
325 progressMessage(`Enumerating objects: ${result.entries.length}, done.`),
326 ]),
327 Stream.flatMap(events, muxPackEvent),
328 ),
329 Stream.succeed(flushPkt),
330 )
331 : Stream.concat(Stream.fromArray(prelude), packDataBytes(events));
332
333 const response: UploadPackResponse = {
334 body,
335 sideband,
336 packSent: true,
337 objectCount: result.entries.length,
338 };
339 return response;
340 });
341
342 /**
343 * Convenience: parses the request body and runs {@link uploadPack} in one
344 * step.
345 */
346 export const handleUploadPack = (
347 body: Uint8Array,
348 objects: ObjectSource,
349 closure: ClosureSource,
350 ): Effect.Effect<UploadPackResponse, PktLineError | ProtocolError | StoreError> =>
351 parseUploadPackRequest(body).pipe(
352 Effect.flatMap((request) => uploadPack(request, objects, closure)),
353 );