@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 328 lines 11.6 KB
Raw
1 import zlib from "node:zlib";
2 /**
3 * The zlib boundary — the ONLY module in `src/Protocol/` allowed to touch
4 * `node:zlib` (per DESIGN §7).
5 *
6 * | Need | Tool |
7 * |-----------------------------------------------|-------------------------------|
8 * | Pack entry parsing (unknown compressed span) | `createInflate()` per entry |
9 * | One-shot inflate of an exactly-known span | `inflateSync` |
10 * | Compression at rest (delta-resolved objects) | `deflateSync` (level 6) |
11 *
12 * The streaming-inflate trick (workerd-verified on 1.20260801.1): each pack
13 * entry's zlib stream (RFC 1950) is self-terminating; `createInflate()`'s
14 * `end` event fires at `Z_STREAM_END` mid-`write` without `.end()`, and
15 * `inflate.bytesWritten` then reports the **exact compressed bytes
16 * consumed** — the only way to find the next entry.
17 * `DecompressionStream("deflate")` is disqualified for this: it errors on
18 * trailing bytes and does not report consumption.
19 */
20 import * as Effect from "effect/Effect";
21 import * as Schema from "effect/Schema";
22
23 /**
24 * Error raised on zlib failures: corrupt streams, truncated input, or an
25 * inflated output exceeding the caller's cap.
26 */
27 export class ZlibError extends Schema.TaggedError<ZlibError>()("ZlibError", {
28 reason: Schema.String,
29 }) {}
30
31 /**
32 * The result of inflating one pack entry: the inflated content and the exact
33 * number of compressed bytes consumed from the input (which locates the next
34 * entry).
35 */
36 export interface InflatedEntry {
37 readonly content: Uint8Array;
38 readonly bytesConsumed: number;
39 }
40
41 /** Feed granularity for the streaming inflater. */
42 const CHUNK = 65536;
43
44 /**
45 * Streaming-inflates exactly one zlib stream from `buf` starting at
46 * `offset`, tolerating arbitrary trailing bytes (the next pack entries).
47 *
48 * Input is fed in 64 KiB chunks; when the stream reaches `Z_STREAM_END` the
49 * `end` event fires and `bytesWritten` gives the exact compressed span.
50 * Truncated input (no `Z_STREAM_END` before the buffer ends) and corrupt
51 * streams fail with {@link ZlibError}, as does output growing past
52 * `options.maxOutput`.
53 */
54 /**
55 * Synchronous single-entry inflate — the fast path.
56 *
57 * The streaming implementation below builds a `zlib.createInflate()`
58 * Transform (EventEmitter, internal buffers) and takes an async event-loop
59 * round trip **per object**. Measured on a 13.7k-object push: ~1.49 ms of
60 * CPU per object, roughly 50x the cost of actually inflating ~2.7 KB.
61 *
62 * `_processChunk` is what Node's own `zlib.inflateSync` uses internally: it
63 * drives the engine synchronously and leaves the consumed-input count in
64 * `bytesWritten`, which is exactly the pair a pack parser needs. It is an
65 * internal API, so this returns `undefined` when it is unavailable (or
66 * behaves unexpectedly) and the caller falls back to the stream path —
67 * notably relevant on workerd, whose `node:zlib` is a compatibility shim.
68 */
69 /**
70 * Second synchronous path, on the PUBLIC API: `inflateSync(.., { info: true })`
71 * returns `{ buffer, engine }`, and `engine.bytesWritten` is the input
72 * consumed — the same pair `_processChunk` gives, without the internal.
73 * zlib stops at the deflate stream's end, so trailing pack bytes are
74 * ignored. Same `expectedSize` verification as above (a shim that returns
75 * only a first chunk is caught by it). `undefined` = use the stream path.
76 */
77 const inflateEntryInfoSync = (
78 buf: Uint8Array,
79 offset: number,
80 maxOutput: number | undefined,
81 expectedSize: number | undefined,
82 ): InflatedEntry | undefined => {
83 try {
84 const result = zlib.inflateSync(buf.subarray(offset), {
85 info: true,
86 } as zlib.ZlibOptions) as unknown as {
87 buffer?: Uint8Array;
88 engine?: { bytesWritten?: number };
89 };
90 const output = result?.buffer;
91 const bytesConsumed = result?.engine?.bytesWritten;
92 if (
93 output === undefined ||
94 typeof bytesConsumed !== "number" ||
95 bytesConsumed <= 0 ||
96 (maxOutput !== undefined && output.length > maxOutput) ||
97 (expectedSize !== undefined && output.length !== expectedSize)
98 ) {
99 return undefined;
100 }
101 return {
102 content: new Uint8Array(output.buffer, output.byteOffset, output.length),
103 bytesConsumed,
104 };
105 } catch {
106 return undefined;
107 }
108 };
109
110 const inflateEntryUnsafeSync = (
111 buf: Uint8Array,
112 offset: number,
113 maxOutput: number | undefined,
114 expectedSize: number | undefined,
115 ): InflatedEntry | undefined => {
116 const engine = zlib.createInflate() as unknown as {
117 _processChunk?: (chunk: Uint8Array, flushFlag: number) => Uint8Array;
118 bytesWritten?: number;
119 close?: () => void;
120 };
121 if (typeof engine._processChunk !== "function") {
122 engine.close?.();
123 return inflateEntryInfoSync(buf, offset, maxOutput, expectedSize);
124 }
125 try {
126 const output = engine._processChunk(buf.subarray(offset), zlib.constants.Z_SYNC_FLUSH);
127 const bytesConsumed = engine.bytesWritten;
128 if (typeof bytesConsumed !== "number" || bytesConsumed <= 0) {
129 return undefined;
130 }
131 if (maxOutput !== undefined && output.length > maxOutput) {
132 // Let the caller's streaming path produce the typed error.
133 return undefined;
134 }
135 // MUST verify: workerd's `node:zlib` shim returns only the first chunk
136 // (observed: 525,107 bytes of a 1,337,267-byte object) instead of
137 // looping like Node's implementation, and reports a plausible
138 // `bytesWritten` with it. Checking against the size the pack header
139 // already declares turns that silent truncation into a fallback.
140 if (expectedSize !== undefined && output.length !== expectedSize) {
141 // workerd's shim returned only the first output chunk: the public
142 // `inflateSync({ info })` loops to completion — try it before paying
143 // for the streaming path (measured: the entries that hit this were
144 // the only async work left in a production ingest).
145 return inflateEntryInfoSync(buf, offset, maxOutput, expectedSize);
146 }
147 return {
148 content: new Uint8Array(output.buffer, output.byteOffset, output.length),
149 bytesConsumed,
150 };
151 } catch {
152 // Corrupt stream, truncated window, or an unsupported shim — the
153 // stream path re-runs it and reports the real error.
154 return undefined;
155 } finally {
156 engine.close?.();
157 }
158 };
159
160 /**
161 * The synchronous fast path alone (DESIGN §22.5): the exact-span inflate
162 * when the whole compressed stream lies within `buf` and the platform
163 * offers a sync engine; `undefined` means "use {@link inflateEntry}".
164 */
165 export const inflateEntrySync = (
166 buf: Uint8Array,
167 offset: number,
168 options: {
169 readonly maxOutput?: number | undefined;
170 readonly expectedSize: number;
171 },
172 ): InflatedEntry | undefined =>
173 offset >= 0 && offset < buf.length
174 ? inflateEntryUnsafeSync(buf, offset, options.maxOutput, options.expectedSize)
175 : undefined;
176
177 export const inflateEntry = (
178 buf: Uint8Array,
179 offset: number,
180 options?: {
181 readonly maxOutput?: number | undefined;
182 /**
183 * The uncompressed size the pack header declares for this entry. Used
184 * to validate the synchronous fast path (see above); without it the
185 * fast path is skipped, because an unverified result cannot be trusted.
186 */
187 readonly expectedSize?: number | undefined;
188 },
189 ): Effect.Effect<InflatedEntry, ZlibError> =>
190 Effect.suspend(() => {
191 const fast =
192 offset >= 0 && offset < buf.length && options?.expectedSize !== undefined
193 ? inflateEntryUnsafeSync(buf, offset, options.maxOutput, options.expectedSize)
194 : undefined;
195 return fast === undefined ? inflateEntryStreaming(buf, offset, options) : Effect.succeed(fast);
196 });
197
198 /** The portable fallback: a real zlib stream per entry. */
199 const inflateEntryStreaming = (
200 buf: Uint8Array,
201 offset: number,
202 options?: { readonly maxOutput?: number | undefined },
203 ): Effect.Effect<InflatedEntry, ZlibError> =>
204 Effect.callback<InflatedEntry, ZlibError>((resume) => {
205 if (offset < 0 || offset >= buf.length) {
206 resume(
207 Effect.fail(
208 ZlibError.make({
209 reason: `inflate offset ${offset} out of range (buffer ${buf.length})`,
210 }),
211 ),
212 );
213 return;
214 }
215 const maxOutput = options?.maxOutput;
216 const inflater = zlib.createInflate();
217 const chunks: Array<Uint8Array> = [];
218 let outBytes = 0;
219 let settled = false;
220
221 const fail = (reason: string): void => {
222 if (settled) return;
223 settled = true;
224 inflater.destroy();
225 resume(Effect.fail(ZlibError.make({ reason })));
226 };
227
228 inflater.on("data", (chunk: Uint8Array) => {
229 if (settled) return;
230 outBytes += chunk.length;
231 if (maxOutput !== undefined && outBytes > maxOutput) {
232 fail(`inflated output exceeds ${maxOutput} bytes`);
233 return;
234 }
235 chunks.push(chunk);
236 });
237 inflater.on("error", (error: Error) => {
238 fail(`inflate failed at offset ${offset}: ${error.message}`);
239 });
240 inflater.once("end", () => {
241 if (settled) return;
242 settled = true;
243 const bytesConsumed = inflater.bytesWritten;
244 const content = new Uint8Array(outBytes);
245 let pos = 0;
246 for (const chunk of chunks) {
247 content.set(chunk, pos);
248 pos += chunk.length;
249 }
250 inflater.destroy();
251 resume(Effect.succeed({ content, bytesConsumed }));
252 });
253
254 const end = buf.length;
255 let pos = offset;
256 const feed = (): void => {
257 if (settled) return;
258 if (pos >= end) {
259 // ran out of input without Z_STREAM_END — flushing EOF surfaces the
260 // "unexpected end of file" error through the error handler above.
261 inflater.end();
262 return;
263 }
264 const next = Math.min(pos + CHUNK, end);
265 const chunk = buf.subarray(pos, next);
266 pos = next;
267 inflater.write(chunk, () => feed());
268 };
269 feed();
270
271 return Effect.sync(() => {
272 // interruption: tear the native stream down
273 if (!settled) {
274 settled = true;
275 inflater.destroy();
276 }
277 });
278 });
279
280 /**
281 * One-shot inflate of an exactly-known zlib span (e.g. a stored `zdata`
282 * BLOB). Strict: trailing garbage or truncation fails.
283 */
284 export const inflate = (data: Uint8Array): Effect.Effect<Uint8Array, ZlibError> =>
285 Effect.try({
286 try: () => new Uint8Array(zlib.inflateSync(data)),
287 catch: (error) =>
288 ZlibError.make({
289 reason: `inflateSync failed: ${error instanceof Error ? error.message : String(error)}`,
290 }),
291 });
292
293 /**
294 * One-shot deflate at the given level (default 6 — the at-rest compression
295 * level for delta-resolved objects; non-delta pack entries are stored
296 * verbatim and never re-compressed).
297 */
298 export const deflate = (data: Uint8Array, level = 6): Effect.Effect<Uint8Array, ZlibError> =>
299 Effect.try({
300 try: () => new Uint8Array(zlib.deflateSync(data, { level })),
301 catch: (error) =>
302 ZlibError.make({
303 reason: `deflateSync failed: ${error instanceof Error ? error.message : String(error)}`,
304 }),
305 });
306
307 /**
308 * Inflates a COMPLETE deflate stream whose exact span is known (DESIGN
309 * §22.8): the plain one-shot `inflateSync`, measured ~4x cheaper than the
310 * consumed-count paths on production. Verified against the declared size.
311 */
312 export const inflateExactSpan = (
313 span: Uint8Array,
314 expectedSize: number,
315 ): Effect.Effect<Uint8Array, ZlibError> =>
316 Effect.try({
317 try: () => {
318 const out = new Uint8Array(zlib.inflateSync(span));
319 if (out.length !== expectedSize) {
320 throw new Error(`inflated ${out.length} bytes, expected ${expectedSize}`);
321 }
322 return out;
323 },
324 catch: (error) =>
325 ZlibError.make({
326 reason: `inflateSync failed: ${error instanceof Error ? error.message : String(error)}`,
327 }),
328 });