The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }; |