@cloudflare/sandbox 1.0.1 → 1.0.3

package/README.md

@@ -99,7 +99,7 @@ npm run check
 npm test
 ```
 
-[Testing](docs/testing.md) explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. [Releasing](docs/releasing.md) explains how maintainers publish the package and its image.
+[Testing](docs/testing.md) explains what these commands check, how to build behind a TLS-inspecting proxy, and how to test in production. [Releasing](docs/releasing.md) explains how to describe a change for the release notes, and how maintainers publish the package and its image.
 
 ## License
 

package/dist/index.mjs

@@ -968,7 +968,10 @@ function readBytes(payload, offset, length) {
 }
 function decodeText(bytes) {
 	try {
-		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		return new TextDecoder("utf-8", {
+			fatal: true,
+			ignoreBOM: true
+		}).decode(bytes);
 	} catch (cause) {
 		throw protocolError("sandbox-shim returned invalid UTF-8 in directory entry name", cause);
 	}
@@ -985,11 +988,12 @@ async function readFile(container, path, options) {
 		stderr: "pipe"
 	});
 	let control;
-	let output;
+	let stdout;
 	try {
 		control = session.openStderrControl();
-		output = session.openStdoutReader();
+		stdout = new StdoutReader(session.openStdoutReader());
 		const opening = await control.readFrame();
+		stdout.stopReadingAhead();
 		if (opening.kind === "fileError") {
 			await control.expectEnd();
 			await session.settle();
@@ -1001,17 +1005,69 @@ async function readFile(container, path, options) {
 		if (opening.kind !== "success") throw protocolError("sandbox-shim returned data before file bytes");
 		const terminal = readTerminalControl(control);
 		terminal.catch(() => void 0);
-		return new Response(responseBody(session, control, output, terminal, path));
+		return new Response(responseBody(session, control, stdout, terminal, path));
 	} catch (error) {
-		terminateRead(session, control, output, error);
+		terminateRead(session, control, stdout, error);
 		throw error;
 	}
 }
-function responseBody(session, control, output, terminalFrame, path) {
+/**
+* Reads the shim's stdout, reading ahead until `readFile` has the opening frame from stderr.
+*
+* A container transport can carry stdout and stderr over one connection with shared backpressure,
+* and can deliver file bytes before the opening frame, or between its fragments. The rest of the
+* frame then arrives only after something reads stdout. The shim writes the whole opening frame
+* before any file byte, so the read-ahead stops once that frame is complete. After that, the
+* response body reads stdout on demand, so the caller's pace applies backpressure again.
+*
+* The read-ahead has no size limit, because stopping before the frame is complete would bring the
+* hang back. How much it holds depends on how far the transport lets stdout run ahead of stderr.
+*/
+var StdoutReader = class {
+	#reader;
+	#chunks = [];
+	#pending;
+	#readingAhead = true;
+	constructor(reader) {
+		this.#reader = reader;
+		this.#readNext();
+	}
+	/** Stops reading ahead. Chunks already read stay queued for `read()`. */
+	stopReadingAhead() {
+		this.#readingAhead = false;
+	}
+	read() {
+		const chunk = this.#chunks.shift();
+		if (chunk !== void 0) return Promise.resolve({
+			done: false,
+			value: chunk
+		});
+		const pending = this.#pending ?? this.#reader.read();
+		this.#pending = void 0;
+		return pending;
+	}
+	discard(reason) {
+		this.#reader.cancel(reason).then(() => this.#reader.releaseLock(), () => this.#reader.releaseLock());
+	}
+	releaseLock() {
+		this.#reader.releaseLock();
+	}
+	#readNext() {
+		const read = this.#reader.read();
+		this.#pending = read;
+		read.then((result) => {
+			if (this.#pending !== read || result.done) return;
+			this.#pending = void 0;
+			this.#chunks.push(result.value);
+			if (this.#readingAhead) this.#readNext();
+		}, () => void 0);
+	}
+};
+function responseBody(session, control, stdout, terminalFrame, path) {
 	return new ReadableStream({
 		pull: async (controller) => {
 			try {
-				const next = await session.waitFor(output.read());
+				const next = await session.waitFor(stdout.read());
 				if (!next.done) {
 					controller.enqueue(next.value);
 					return;
@@ -1025,16 +1081,16 @@ function responseBody(session, control, output, terminalFrame, path) {
 					}, terminal.errno, terminal.detail);
 				}
 				if (terminal.kind !== "success") throw protocolError("sandbox-shim returned data after file bytes");
-				output.releaseLock();
+				stdout.releaseLock();
 				control.releaseLock();
 				session.finish();
 				controller.close();
 			} catch (error) {
-				terminateRead(session, control, output, error);
+				terminateRead(session, control, stdout, error);
 				controller.error(error);
 			}
 		},
-		cancel: (reason) => terminateRead(session, control, output, reason)
+		cancel: (reason) => terminateRead(session, control, stdout, reason)
 	});
 }
 async function readTerminalControl(control) {
@@ -1042,10 +1098,10 @@ async function readTerminalControl(control) {
 	await control.expectEnd();
 	return frame;
 }
-function terminateRead(session, control, output, reason) {
+function terminateRead(session, control, stdout, reason) {
 	session.terminate();
 	control?.discard(reason);
-	if (output !== void 0) output.cancel(reason).then(() => output.releaseLock(), () => output.releaseLock());
+	stdout?.discard(reason);
 }
 //#endregion
 //#region src/files/stat-file.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Structured workspace file operations for Cloudflare sandboxes",
   "license": "Apache-2.0",
   "repository": {
@@ -23,6 +23,6 @@
   },
   "dependencies": {
     "aws4fetch": "1.0.20",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   }
 }