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

main
ts 256 lines 9.34 KB
Raw
1 /// <reference types="@cloudflare/workers-types" />
2 /**
3 * side-band-64k multiplexing.
4 *
5 * When `side-band-64k` is negotiated, binary data is carried as pkt-lines
6 * whose first payload byte is the band:
7 *
8 * - **band 1** — pack data (or the receive-pack report)
9 * - **band 2** — progress messages (client prints to stderr as `remote: `)
10 * - **band 3** — fatal error message; the client aborts
11 *
12 * Frame arithmetic: max pkt-line total 65520 = 4 length bytes + 1 band byte
13 * + **65515** data bytes, so every frame carries at most 65515 payload bytes.
14 * Legacy `side-band` (1000-byte packets) is never advertised.
15 */
16 import * as Stream from "effect/Stream";
17 import { concatBytes, utf8Encode } from "./ObjectCodec.ts";
18 import { flushPkt } from "./Pkt.ts";
19
20 /**
21 * Maximum data bytes per side-band-64k frame (65520 − 4 length − 1 band).
22 */
23 export const SIDEBAND_DATA_MAX = 65515;
24
25 /**
26 * The three side-band channels.
27 */
28 export type SidebandBand = 1 | 2 | 3;
29
30 /**
31 * Encodes a single side-band frame. The data must be at most
32 * {@link SIDEBAND_DATA_MAX} bytes — use {@link sidebandFrames} to split
33 * arbitrary payloads.
34 */
35 const HEX = "0123456789abcdef";
36
37 /** The 5-byte sideband frame header for `dataLength` payload bytes. */
38 const sidebandHeader = (band: SidebandBand, dataLength: number): Uint8Array => {
39 const total = dataLength + 5;
40 const out = new Uint8Array(5);
41 out[0] = HEX.charCodeAt((total >> 12) & 0xf);
42 out[1] = HEX.charCodeAt((total >> 8) & 0xf);
43 out[2] = HEX.charCodeAt((total >> 4) & 0xf);
44 out[3] = HEX.charCodeAt(total & 0xf);
45 out[4] = band;
46 return out;
47 };
48
49 export const sidebandFrame = (band: SidebandBand, data: Uint8Array): Uint8Array => {
50 // One allocation, one copy: header + band + payload in place.
51 const out = new Uint8Array(5 + data.length);
52 out.set(sidebandHeader(band, data.length), 0);
53 out.set(data, 5);
54 return out;
55 };
56
57 /**
58 * Splits a payload into as many side-band frames as needed (each carrying at
59 * most {@link SIDEBAND_DATA_MAX} data bytes). An empty payload produces no
60 * frames.
61 */
62 export const sidebandFrames = (band: SidebandBand, data: Uint8Array): Array<Uint8Array> => {
63 const frames: Array<Uint8Array> = [];
64 for (let pos = 0; pos < data.length; pos += SIDEBAND_DATA_MAX) {
65 frames.push(sidebandFrame(band, data.subarray(pos, pos + SIDEBAND_DATA_MAX)));
66 }
67 return frames;
68 };
69
70 /**
71 * Stream transform: wraps every chunk of a byte stream into side-band frames
72 * on the given band. Used to mux the pack stream (band 1) into the response
73 * body; the caller appends the outer flush-pkt after the wrapped stream.
74 */
75 export const wrapSideband =
76 (band: SidebandBand) =>
77 <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Stream.Stream<Uint8Array, E, R> =>
78 Stream.flatMap(stream, (chunk) =>
79 chunk.length === 0 ? Stream.empty : Stream.fromArray(sidebandFrames(band, chunk)),
80 );
81
82 /**
83 * Encodes a band-2 progress message (e.g. `Counting objects: 42, done.`).
84 * A trailing newline is appended when missing so the client's stderr stays
85 * line-buffered.
86 */
87 export const progressMessage = (message: string): Uint8Array =>
88 concatBytes(
89 sidebandFrames(
90 2,
91 utf8Encode(message.endsWith("\n") || message.endsWith("\r") ? message : `${message}\n`),
92 ),
93 );
94
95 /**
96 * Encodes a band-3 fatal error message. The client prints it and aborts the
97 * transfer; the server should end the response after sending it.
98 */
99 export const sidebandError = (message: string): Uint8Array =>
100 concatBytes(sidebandFrames(3, utf8Encode(message.endsWith("\n") ? message : `${message}\n`)));
101
102 /** Target bytes per native write from {@link pumpPackBody}. */
103 export const PUMP_READ_BYTES = 1 << 20;
104
105 /**
106 * Sideband-frames a whole chunk into ONE buffer: `ceil(n / 65515)` frames,
107 * each `header(5) + data`, laid out back to back. One memcpy per byte.
108 */
109 export const sidebandFrameAll = (band: SidebandBand, data: Uint8Array) => {
110 const frames = Math.ceil(data.length / SIDEBAND_DATA_MAX);
111 const out = new Uint8Array(data.length + frames * 5);
112 let at = 0;
113 for (let pos = 0; pos < data.length; pos += SIDEBAND_DATA_MAX) {
114 const end = Math.min(pos + SIDEBAND_DATA_MAX, data.length);
115 out.set(sidebandHeader(band, end - pos), at);
116 out.set(data.subarray(pos, end), at + 5);
117 at += 5 + (end - pos);
118 }
119 return out;
120 };
121
122 /**
123 * Pumps a pack body to the client through a native `IdentityTransformStream`
124 * (DESIGN §22.3). Returns the response body.
125 *
126 * Why this shape, measured on a 40 MiB bundle (DESIGN §22.4):
127 *
128 * - An Effect `Stream` body tops out around 15–20 MiB/s: every chunk is a
129 * fiber round trip. The raw case is a platform-to-platform `pipeTo` —
130 * zero JS per chunk — and runs at the client's line rate (71 MiB/s here).
131 * - Sideband cannot be a bare pipe: the protocol caps a frame at 65515
132 * data bytes. Writing frames one at a time into the identity stream —
133 * whether from a `TransformStream` or a manual loop — also measured
134 * ~15 MiB/s: the identity stream is unbuffered, so each `write` waits
135 * for the consumer, and 64 KiB per round trip is the ceiling.
136 * - So: read ~1 MiB at a time (BYOB `readAtLeast` on byte sources, which
137 * R2 bodies are), frame the whole read into one buffer, one `write`.
138 * 16× fewer round trips; one extra memcpy per byte (~1 ms/MiB).
139 *
140 * Errors on the source abort the writable, which errors the body the
141 * client is reading — the right signal for a truncated pack.
142 */
143 export const pumpPackBody = (options: {
144 /** Bytes before the pack (NAK/ACK lines, progress) — sent as-is. */
145 readonly prefix: Uint8Array;
146 readonly source: ReadableStream<Uint8Array>;
147 readonly sideband: boolean;
148 /**
149 * The source is ALREADY sideband-framed (a `bundleSidebandKey` object):
150 * pipe it through natively and only append the flush packet.
151 */
152 readonly framed?: boolean | undefined;
153 }): ReadableStream<Uint8Array> => {
154 const { readable, writable } = new IdentityTransformStream();
155 void (async () => {
156 const writer = writable.getWriter();
157 try {
158 await writer.write(options.prefix);
159 if (!options.sideband) {
160 writer.releaseLock();
161 await options.source.pipeTo(writable);
162 return;
163 }
164 if (options.framed === true) {
165 writer.releaseLock();
166 await options.source.pipeTo(writable, { preventClose: true });
167 const tail = writable.getWriter();
168 await tail.write(flushPkt);
169 await tail.close();
170 return;
171 }
172 for await (const chunk of readBig(options.source)) {
173 await writer.write(sidebandFrameAll(1, chunk));
174 }
175 await writer.write(flushPkt);
176 await writer.close();
177 } catch (error) {
178 await writable.abort(error).catch(() => {});
179 }
180 })();
181 return readable;
182 };
183
184 /**
185 * Yields chunks of about {@link PUMP_READ_BYTES} from a source: BYOB
186 * `readAtLeast` (a workerd extension) fills a whole buffer per read on byte
187 * streams; other streams are read as they come.
188 */
189 async function* readBig(source: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
190 let byob: ReadableStreamBYOBReader | undefined;
191 try {
192 byob = source.getReader({ mode: "byob" });
193 } catch {
194 byob = undefined;
195 }
196 if (byob === undefined) {
197 const reader = source.getReader();
198 for (;;) {
199 const { done, value } = await reader.read();
200 if (done) return;
201 if (value.length > 0) yield value;
202 }
203 }
204 const reader = byob as ReadableStreamBYOBReader & {
205 readAtLeast?: (min: number, view: Uint8Array) => Promise<ReadableStreamReadResult<Uint8Array>>;
206 };
207 let buffer = new ArrayBuffer(PUMP_READ_BYTES);
208 for (;;) {
209 const view = new Uint8Array(buffer);
210 const result =
211 reader.readAtLeast !== undefined
212 ? await reader.readAtLeast(view.byteLength, view)
213 : await reader.read(view);
214 if (result.value !== undefined && result.value.byteLength > 0) {
215 yield result.value;
216 // The buffer was transferred into `value`; take it back for reuse.
217 buffer = result.value.buffer as ArrayBuffer;
218 }
219 if (result.done) return;
220 }
221 }
222
223 /** Byte length of {@link sidebandRechunk}'s output for `size` input bytes. */
224 export const sidebandFramedLength = (size: number): number =>
225 size + 5 * Math.ceil(size / SIDEBAND_DATA_MAX);
226
227 /**
228 * Re-frames a byte stream into band frames of EXACTLY
229 * {@link SIDEBAND_DATA_MAX} data bytes (the last one shorter), independent
230 * of how the input is chunked — so the output length is a pure function
231 * of the input length ({@link sidebandFramedLength}), which an R2 put of
232 * a stream needs up front. Used to write a bundle's pre-framed twin.
233 */
234 export const sidebandRechunk =
235 (band: SidebandBand) =>
236 <E, R>(stream: Stream.Stream<Uint8Array, E, R>): Stream.Stream<Uint8Array, E, R> => {
237 let carry: Uint8Array = new Uint8Array(0);
238 const frames = (chunk: Uint8Array): Array<Uint8Array> => {
239 const data = carry.length === 0 ? chunk : concatBytes([carry, chunk]);
240 const out: Array<Uint8Array> = [];
241 let pos = 0;
242 while (data.length - pos >= SIDEBAND_DATA_MAX) {
243 out.push(sidebandFrame(band, data.subarray(pos, pos + SIDEBAND_DATA_MAX)));
244 pos += SIDEBAND_DATA_MAX;
245 }
246 carry = data.slice(pos);
247 return out;
248 };
249 return Stream.flatMap(stream, (chunk) => Stream.fromArray(frames(chunk))).pipe(
250 Stream.concat(
251 Stream.suspend(() =>
252 carry.length === 0 ? Stream.empty : Stream.succeed(sidebandFrame(band, carry)),
253 ),
254 ),
255 );
256 };