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

main
ts 326 lines 11.5 KB
Raw
1 /**
2 * A pack source the parser can read WHILE the body is still arriving
3 * (DESIGN §22.6). The receive-pack handler feeds request chunks in; the
4 * parser reads forward through it; nothing waits for the upload to end.
5 *
6 * - Chunks are coalesced into fixed slabs (`SLAB_BYTES`), so a read inside
7 * one slab is a view (the parser's synchronous fast path needs views).
8 * - A read past what has arrived blocks until enough bytes exist or the
9 * body ends; a read that cannot be satisfied at end returns short.
10 * - Retention is bounded: once the parser has consumed past a slab and the
11 * retained total exceeds `retainBytes`, the oldest slab is dropped. A
12 * later read below the retained window (a delta base far behind) is
13 * served by the `fallback` reader — the spilled object, readable once the
14 * body has ended — or fails when there is none.
15 * - Backpressure: `push` waits while more than `backpressureBytes` of
16 * unconsumed bytes are buffered, so a slow parser throttles the upload
17 * instead of growing memory.
18 */
19 import * as Effect from "effect/Effect";
20 import type { RandomAccess } from "../Protocol/PackParser.ts";
21 import { StoreError } from "../Protocol/Store.ts";
22
23 // Slabs match the pump's part size so a part read is a view, not a copy.
24 export const SLAB_BYTES = 8 * 1024 * 1024;
25 export const RETAIN_BYTES = 16 * 1024 * 1024;
26 export const BACKPRESSURE_BYTES = 24 * 1024 * 1024;
27 // 24 MiB (was 8): the hasher chain runs behind the upload; with less room
28 // ahead of the pump the upload stalled on every part (DESIGN §22.7).
29
30 interface Slab {
31 readonly start: number;
32 readonly bytes: Uint8Array; // capacity SLAB_BYTES; `filled` bytes valid
33 filled: number;
34 }
35
36 interface Waiter {
37 readonly need: number;
38 readonly resume: (result: Effect.Effect<void, StoreError>) => void;
39 }
40
41 export interface StreamingSource extends RandomAccess {
42 /** Bytes received so far. */
43 readonly received: () => number;
44 /** Resolves with the total once the body has ended. */
45 readonly awaitEnd: Effect.Effect<number, StoreError>;
46 /** True once the feeder has ended the body. */
47 readonly ended: () => boolean;
48 /** The parser is done with everything below `offset`; retention may drop it. */
49 readonly release: (offset: number) => void;
50 }
51
52 export interface StreamingFeeder {
53 readonly source: StreamingSource;
54 /** Appends a chunk; waits while backpressure applies. */
55 readonly push: (chunk: Uint8Array) => Effect.Effect<void, StoreError>;
56 /**
57 * Appends without ever parking: for receivers whose consumer retains
58 * the whole body anyway (the push pump, DESIGN §22.10), backpressure
59 * buys nothing and the per-chunk Effect hop is the receive path's cost.
60 * Returns false once the source has ended or failed.
61 */
62 readonly pushSync: (chunk: Uint8Array) => boolean;
63 /** Ends the body; readers waiting past the end are woken. */
64 readonly end: () => void;
65 /**
66 * Announces that a fallback reader WILL be set (the body is being
67 * spilled): evicted reads after `end` wait for it instead of failing.
68 */
69 readonly expectFallback: () => void;
70 /** Fails every current and future read. */
71 readonly fail: (error: StoreError) => void;
72 /**
73 * Installs the reader for bytes that retention has dropped (the spilled
74 * object). Reads below the retained window wait for it and for `end`.
75 */
76 readonly setFallback: (reader: RandomAccess) => void;
77 }
78
79 export const makeStreamingSource = (options?: {
80 readonly retainBytes?: number | undefined;
81 readonly backpressureBytes?: number | undefined;
82 readonly slabBytes?: number | undefined;
83 }): StreamingFeeder => {
84 const slabBytes = options?.slabBytes ?? SLAB_BYTES;
85 const retainBytes = options?.retainBytes ?? RETAIN_BYTES;
86 const backpressureBytes = options?.backpressureBytes ?? BACKPRESSURE_BYTES;
87 const slabs: Array<Slab> = [];
88 let received = 0;
89 let retainFrom = 0; // first byte still in memory
90 let consumed = 0; // parser's release watermark
91 let ended = false;
92 let total: number | undefined;
93 let failure: StoreError | undefined;
94 let fallback: RandomAccess | undefined;
95 let fallbackExpected = false;
96 const readWaiters: Array<Waiter> = [];
97 const endWaiters: Array<(r: Effect.Effect<number, StoreError>) => void> = [];
98 const pushWaiters: Array<() => void> = [];
99 const fallbackWaiters: Array<() => void> = [];
100
101 const append = (chunk: Uint8Array) => {
102 let at = 0;
103 while (at < chunk.length) {
104 let slab = slabs[slabs.length - 1];
105 if (slab === undefined || slab.filled === slab.bytes.length) {
106 slab = { start: received, bytes: new Uint8Array(slabBytes), filled: 0 };
107 slabs.push(slab);
108 }
109 const take = Math.min(chunk.length - at, slab.bytes.length - slab.filled);
110 slab.bytes.set(chunk.subarray(at, at + take), slab.filled);
111 slab.filled += take;
112 received += take;
113 at += take;
114 }
115 };
116 const wake = () => {
117 for (let i = readWaiters.length - 1; i >= 0; i--) {
118 const w = readWaiters[i]!;
119 if (failure !== undefined) {
120 readWaiters.splice(i, 1);
121 w.resume(Effect.fail(failure));
122 } else if (received >= w.need || ended) {
123 readWaiters.splice(i, 1);
124 w.resume(Effect.void);
125 }
126 }
127 if (ended || failure !== undefined) {
128 const ws = endWaiters.splice(0);
129 for (const w of ws) {
130 w(failure !== undefined ? Effect.fail(failure) : Effect.succeed(total!));
131 }
132 }
133 };
134 /**
135 * Backpressure must never park the feeder while a reader is waiting for
136 * bytes past the buffer — that reader is the only thing that will ever
137 * consume, so parking would deadlock (a 64 KiB probe against a 1 KiB
138 * budget, or an entry larger than the budget). A waiting reader always
139 * releases the feeder.
140 */
141 const pushMayProceed = () =>
142 received - consumed <= backpressureBytes ||
143 readWaiters.length > 0 ||
144 ended ||
145 failure !== undefined;
146 const wakePush = () => {
147 if (pushMayProceed()) {
148 const ws = pushWaiters.splice(0);
149 for (const w of ws) w();
150 }
151 };
152 const trim = () => {
153 // Drop whole slabs entirely below the consumed watermark once the
154 // retained total exceeds the budget.
155 while (
156 slabs.length > 1 &&
157 received - retainFrom > retainBytes &&
158 slabs[0]!.start + slabs[0]!.filled <= consumed
159 ) {
160 const dropped = slabs.shift()!;
161 retainFrom = dropped.start + dropped.filled;
162 }
163 };
164 const waitFor = (need: number): Effect.Effect<void, StoreError> =>
165 Effect.suspend(() => {
166 if (failure !== undefined) return Effect.fail(failure);
167 if (received >= need || ended) return Effect.void;
168 return Effect.callback<void, StoreError>((resume) => {
169 readWaiters.push({ need, resume });
170 wakePush(); // a waiting reader releases a parked feeder
171 });
172 });
173 const waitForFallback: Effect.Effect<RandomAccess, StoreError> = Effect.suspend(() => {
174 if (failure !== undefined) return Effect.fail(failure);
175 if (fallback !== undefined && ended) return Effect.succeed(fallback);
176 return Effect.callback<RandomAccess, StoreError>((resume) => {
177 fallbackWaiters.push(() => {
178 resume(
179 failure !== undefined
180 ? Effect.fail(failure)
181 : fallback !== undefined
182 ? Effect.succeed(fallback)
183 : Effect.fail(
184 StoreError.make({
185 reason: "streaming source: bytes evicted and no fallback reader",
186 }),
187 ),
188 );
189 });
190 });
191 });
192 const wakeFallback = () => {
193 // Once the body has ended, evicted reads either get the fallback reader
194 // or fail — they must never wait forever. When a fallback is expected
195 // (the spill completes after the body ends), they wait for it.
196 if (ended && (fallback !== undefined || !fallbackExpected || failure !== undefined)) {
197 const ws = fallbackWaiters.splice(0);
198 for (const w of ws) w();
199 }
200 };
201
202 /** Assembles [offset, end) from retained slabs; a view when in one slab. */
203 const assemble = (offset: number, end: number): Uint8Array => {
204 let first = -1;
205 for (let i = 0; i < slabs.length; i++) {
206 const s = slabs[i]!;
207 if (offset >= s.start && offset < s.start + s.filled) {
208 first = i;
209 break;
210 }
211 }
212 if (first < 0) return new Uint8Array(0);
213 const s0 = slabs[first]!;
214 if (end <= s0.start + s0.filled) {
215 return s0.bytes.subarray(offset - s0.start, end - s0.start);
216 }
217 const out = new Uint8Array(end - offset);
218 let written = 0;
219 for (let i = first; i < slabs.length && offset + written < end; i++) {
220 const s = slabs[i]!;
221 const from = Math.max(offset, s.start) - s.start;
222 const to = Math.min(end, s.start + s.filled) - s.start;
223 if (to <= from) break;
224 out.set(s.bytes.subarray(from, to), written);
225 written += to - from;
226 }
227 return written === out.length ? out : out.subarray(0, written);
228 };
229
230 const source: StreamingSource = {
231 get size() {
232 return total ?? Number.POSITIVE_INFINITY;
233 },
234 received: () => received,
235 ended: () => ended,
236 awaitEnd: Effect.suspend(() => {
237 if (failure !== undefined) return Effect.fail(failure);
238 if (ended) return Effect.succeed(total!);
239 return Effect.callback<number, StoreError>((resume) => {
240 endWaiters.push(resume);
241 });
242 }),
243 release: (offset) => {
244 if (offset > consumed) {
245 consumed = offset;
246 trim();
247 wakePush();
248 }
249 },
250 readSync: (offset, length) => {
251 if (offset < retainFrom) return undefined;
252 const end = Math.min(offset + length, received);
253 if (end <= offset) return ended ? new Uint8Array(0) : undefined;
254 if (end < offset + length && !ended) return undefined;
255 for (const s of slabs) {
256 if (offset >= s.start && end <= s.start + s.filled) {
257 return s.bytes.subarray(offset - s.start, end - s.start);
258 }
259 }
260 return undefined;
261 },
262 evictedBeforeEnd: (offset) => offset < retainFrom && !ended,
263 read: (offset, length) =>
264 Effect.gen(function* () {
265 if (offset < retainFrom) {
266 const reader = yield* waitForFallback;
267 return yield* reader.read(offset, length);
268 }
269 yield* waitFor(offset + length);
270 if (offset < retainFrom) {
271 const reader = yield* waitForFallback;
272 return yield* reader.read(offset, length);
273 }
274 const end = Math.min(offset + length, received);
275 return end <= offset ? new Uint8Array(0) : assemble(offset, end);
276 }),
277 };
278
279 return {
280 source,
281 pushSync: (chunk) => {
282 if (failure !== undefined || ended) return false;
283 append(chunk);
284 wake();
285 return true;
286 },
287 push: (chunk) =>
288 Effect.gen(function* () {
289 if (failure !== undefined) return yield* failure;
290 if (ended) {
291 return yield* StoreError.make({ reason: "streaming source: push after end" });
292 }
293 append(chunk);
294 wake();
295 if (!pushMayProceed()) {
296 yield* Effect.callback<void>((resume) => {
297 pushWaiters.push(() => resume(Effect.void));
298 });
299 }
300 }),
301 expectFallback: () => {
302 fallbackExpected = true;
303 },
304 end: () => {
305 if (ended) return;
306 ended = true;
307 total = received;
308 wake();
309 wakePush();
310 wakeFallback();
311 },
312 fail: (error) => {
313 if (failure !== undefined) return;
314 failure = error;
315 ended = true;
316 total ??= received;
317 wake();
318 wakePush();
319 wakeFallback();
320 },
321 setFallback: (reader) => {
322 fallback = reader;
323 wakeFallback();
324 },
325 };
326 };