@cloudflare/sandbox 0.10.0 → 0.10.2

package/dist/{sandbox-2bHZZmy5.js → sandbox-BcEq4aUF.js}

@@ -1,9 +1,10 @@
 import { _ as GitLogger, b as getEnvString, c as parseSSEFrames, d as createNoOpLogger, f as TraceContext, g as DEFAULT_GIT_CLONE_TIMEOUT_MS, h as ResultImpl, i as isWSStreamChunk, l as shellEscape, m as Execution, n as isWSError, p as logCanonicalEvent, r as isWSResponse, t as generateRequestId, u as createLogger, v as extractRepoName, x as partitionEnvVars, y as filterEnvVars } from "./dist-B_eXrP83.js";
-import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-CBi-O-pF.js";
+import { n as getHttpStatus, r as ErrorCode, t as getSuggestion } from "./errors-8Hvune8K.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 import { AwsClient } from "aws4fetch";
-import { RpcSession } from "capnweb";
+import { RpcSession, RpcTarget } from "capnweb";
 import path from "node:path/posix";
+import { RpcTarget as RpcTarget$1 } from "cloudflare:workers";
 
 //#region src/errors/classes.ts
 /**
@@ -1784,6 +1785,17 @@ var CommandClient = class extends BaseHttpClient {
 //#endregion
 //#region src/clients/desktop-client.ts
 /**
+* Decode a base64-encoded screenshot payload into a Uint8Array.
+* Shared with the RPC client wrapper, which receives base64 over the
+* wire and needs the same `format: 'bytes'` convenience.
+*/
+function base64ToBytes(data) {
+	const binaryString = atob(data);
+	const bytes = new Uint8Array(binaryString.length);
+	for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
+	return bytes;
+}
+/**
 * Client for desktop environment lifecycle, input, and screen operations
 */
 var DesktopClient = class extends BaseHttpClient {
@@ -1828,15 +1840,10 @@ var DesktopClient = class extends BaseHttpClient {
 			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 		};
 		const response = await this.post("/api/desktop/screenshot", data);
-		if (wantsBytes) {
-			const binaryString = atob(response.data);
-			const bytes = new Uint8Array(binaryString.length);
-			for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-			return {
-				...response,
-				data: bytes
-			};
-		}
+		if (wantsBytes) return {
+			...response,
+			data: base64ToBytes(response.data)
+		};
 		return response;
 	}
 	async screenshotRegion(region, options) {
@@ -1849,15 +1856,10 @@ var DesktopClient = class extends BaseHttpClient {
 			...options?.showCursor !== void 0 && { showCursor: options.showCursor }
 		};
 		const response = await this.post("/api/desktop/screenshot/region", data);
-		if (wantsBytes) {
-			const binaryString = atob(response.data);
-			const bytes = new Uint8Array(binaryString.length);
-			for (let i = 0; i < binaryString.length; i++) bytes[i] = binaryString.charCodeAt(i);
-			return {
-				...response,
-				data: bytes
-			};
-		}
+		if (wantsBytes) return {
+			...response,
+			data: base64ToBytes(response.data)
+		};
 		return response;
 	}
 	/**
@@ -2010,7 +2012,7 @@ var DesktopClient = class extends BaseHttpClient {
 	* Get health status for a specific desktop process.
 	*/
 	async getProcessStatus(name) {
-		return await this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
+		return this.get(`/api/desktop/process/${encodeURIComponent(name)}/status`);
 	}
 };
 
@@ -2050,13 +2052,8 @@ var FileClient = class extends BaseHttpClient {
 		};
 		return await this.post("/api/write", data);
 	}
-	/**
-	* Read content from a file
-	* @param path - File path to read from
-	* @param sessionId - The session ID for this operation
-	* @param options - Optional settings (encoding)
-	*/
 	async readFile(path$1, sessionId, options) {
+		if (options?.encoding === "none") throw new Error("readFile with encoding: 'none' requires the rpc transport. Set SANDBOX_TRANSPORT=rpc.");
 		const data = {
 			path: path$1,
 			sessionId,
@@ -2143,6 +2140,13 @@ var FileClient = class extends BaseHttpClient {
 		};
 		return await this.post("/api/exists", data);
 	}
+	/**
+	* Write a file via a raw binary stream over the RPC transport.
+	* Throws on HTTP and WebSocket transports — use writeFile() with a string instead.
+	*/
+	writeFileStream(_path, _content, _sessionId) {
+		throw new Error("writeFileStream requires the rpc transport. Set SANDBOX_TRANSPORT=rpc.");
+	}
 };
 
 //#endregion
@@ -2521,6 +2525,9 @@ var UtilityClient = class extends BaseHttpClient {
 			return "unknown";
 		}
 	}
+	listSessions() {
+		throw new Error("listSessions requires the RPC transport. Set SANDBOX_TRANSPORT=rpc.");
+	}
 };
 
 //#endregion
@@ -2644,6 +2651,13 @@ var SandboxClient = class {
 	utils;
 	desktop;
 	watch;
+	/**
+	* Tunnels are RPC-only — the route-based transport does not implement them.
+	* This getter exists so the `PublicKeys<SandboxClient> satisfies
+	* PublicKeys<SandboxAPI>` compile-time check holds. Calling any method on
+	* the returned proxy throws a clear `RPC transport required` error.
+	*/
+	tunnels = createTunnelsNotImplemented();
 	transport = null;
 	constructor(options) {
 		if (options.transportMode === "websocket" && options.wsUrl) this.transport = createTransport({
@@ -2706,16 +2720,6 @@ var SandboxClient = class {
 		return this.transport?.isConnected() ?? false;
 	}
 	/**
-	* Stream a file directly to the container over a binary RPC channel.
-	*
-	* Requires the container-control path (`transport: 'rpc'`). Calling this
-	* method with the HTTP or WebSocket route transports throws an error because
-	* those transports do not support binary streaming.
-	*/
-	writeFileStream(_path, _content, _sessionId) {
-		throw new Error("writeFileStream requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.");
-	}
-	/**
 	* Connect WebSocket transport (no-op in HTTP mode)
 	* Called automatically on first request, but can be called explicitly
 	* to establish connection upfront.
@@ -2731,6 +2735,14 @@ var SandboxClient = class {
 		if (this.transport) this.transport.disconnect();
 	}
 };
+function createTunnelsNotImplemented() {
+	const message = "sandbox.tunnels.* requires the RPC transport. Enable it with transport: \"rpc\" in sandbox options.";
+	return new Proxy({}, { get() {
+		return () => {
+			throw new Error(message);
+		};
+	} });
+}
 
 //#endregion
 //#region ../shared/src/backup.ts
@@ -2777,13 +2789,15 @@ var ContainerControlConnection = class {
 	port;
 	logger;
 	retryTimeoutMs;
+	onClose;
 	constructor(options) {
 		this.containerStub = options.stub;
 		this.port = options.port ?? 3e3;
 		this.logger = options.logger ?? createNoOpLogger();
 		this.retryTimeoutMs = options.retryTimeoutMs ?? DEFAULT_RETRY_TIMEOUT_MS;
+		this.onClose = options.onClose;
 		this.transport = new DeferredTransport();
-		this.session = new RpcSession(this.transport);
+		this.session = new RpcSession(this.transport, options.localMain);
 		this.stub = this.session.getRemoteMain();
 	}
 	/**
@@ -2823,6 +2837,8 @@ var ContainerControlConnection = class {
 			this.stub[Symbol.dispose]?.();
 		} catch {}
 		if (this.ws) {
+			this.ws.removeEventListener("close", this.onWebSocketClose);
+			this.ws.removeEventListener("error", this.onWebSocketError);
 			try {
 				this.ws.close();
 			} catch {}
@@ -2839,6 +2855,42 @@ var ContainerControlConnection = class {
 	setRetryTimeoutMs(ms) {
 		this.retryTimeoutMs = ms;
 	}
+	/**
+	* Run the owner-provided `onClose` callback exactly once per call,
+	* swallowing any errors so a buggy listener can't keep the connection
+	* object in a half-torn-down state.
+	*/
+	fireOnClose() {
+		if (!this.onClose) return;
+		try {
+			this.onClose();
+		} catch (err) {
+			this.logger.warn("ContainerControlConnection onClose handler threw", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	/**
+	* WebSocket `close` listener. Defined as a bound arrow field so the
+	* same reference can be passed to both `addEventListener` and
+	* `removeEventListener` — a fresh anonymous lambda would silently
+	* fail to unbind.
+	*/
+	onWebSocketClose = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		this.logger.debug("ContainerControlConnection WebSocket closed");
+		if (wasConnected) this.fireOnClose();
+	};
+	/**
+	* WebSocket `error` listener. Same field-form rationale as
+	* {@link onWebSocketClose}.
+	*/
+	onWebSocketError = () => {
+		const wasConnected = this.connected;
+		this.connected = false;
+		this.ws = null;
+		if (wasConnected) this.fireOnClose();
+	};
 	async doConnect() {
 		try {
 			const response = await this.fetchUpgradeWithRetry();
@@ -2846,15 +2898,8 @@ var ContainerControlConnection = class {
 			const ws = response.webSocket;
 			if (!ws) throw new Error("No WebSocket in upgrade response");
 			ws.accept();
-			ws.addEventListener("close", () => {
-				this.connected = false;
-				this.ws = null;
-				this.logger.debug("ContainerControlConnection WebSocket closed");
-			});
-			ws.addEventListener("error", () => {
-				this.connected = false;
-				this.ws = null;
-			});
+			ws.addEventListener("close", this.onWebSocketClose);
+			ws.addEventListener("error", this.onWebSocketError);
 			this.ws = ws;
 			this.transport.activate(ws);
 			this.connected = true;
@@ -3134,19 +3179,16 @@ var ContainerControlClient = class {
 	busyPollTimer = null;
 	/** Tracks whether we currently believe the session is busy. */
 	busy = false;
-	/**
-	* Set the first time the poller observes `conn.isConnected() === true`,
-	* cleared in `destroyConnection()`. Lets us distinguish "the WebSocket
-	* upgrade is still in progress" (don't tear down) from "we were
-	* connected and the peer went away" (do tear down).
-	*/
-	wasEverConnected = false;
 	constructor(options) {
 		this.connOptions = {
 			stub: options.stub,
 			port: options.port,
+			localMain: options.localMain,
 			logger: options.logger,
-			retryTimeoutMs: options.retryTimeoutMs
+			retryTimeoutMs: options.retryTimeoutMs,
+			onClose: () => {
+				if (this.conn) this.destroyConnection();
+			}
 		};
 		this.idleDisconnectMs = options.idleDisconnectMs ?? DEFAULT_IDLE_DISCONNECT_MS;
 		this.busyPollIntervalMs = options.busyPollIntervalMs ?? BUSY_POLL_INTERVAL_MS;
@@ -3188,11 +3230,7 @@ var ContainerControlClient = class {
 	pollBusyState = () => {
 		const conn = this.conn;
 		if (!conn) return;
-		if (!conn.isConnected()) {
-			if (this.wasEverConnected) this.destroyConnection();
-			return;
-		}
-		this.wasEverConnected = true;
+		if (!conn.isConnected()) return;
 		const { imports, exports } = conn.getStats();
 		if (imports > IDLE_IMPORT_THRESHOLD || exports > IDLE_EXPORT_THRESHOLD) {
 			if (!this.busy) {
@@ -3225,7 +3263,7 @@ var ContainerControlClient = class {
 			if (!conn || !conn.isConnected()) return;
 			const { imports, exports } = conn.getStats();
 			if (imports <= IDLE_IMPORT_THRESHOLD && exports <= IDLE_EXPORT_THRESHOLD) {
-				this.logger.debug("Disconnecting idle capnweb connection");
+				this.logger.debug("Disconnecting idle RPC connection");
 				this.destroyConnection();
 			}
 		}, this.idleDisconnectMs);
@@ -3247,7 +3285,6 @@ var ContainerControlClient = class {
 			this.conn.disconnect();
 			this.conn = null;
 		}
-		this.wasEverConnected = false;
 	}
 	get commands() {
 		return wrapStub(this.getConnection().rpc().commands, this.renewActivity);
@@ -3271,11 +3308,37 @@ var ContainerControlClient = class {
 		return wrapStub(this.getConnection().rpc().backup, this.renewActivity);
 	}
 	get desktop() {
-		return wrapStub(this.getConnection().rpc().desktop, this.renewActivity);
+		const stub = wrapStub(this.getConnection().rpc().desktop, this.renewActivity);
+		const wire = stub;
+		return new Proxy(stub, { get(target, prop, receiver) {
+			if (prop === "screenshot") return async (options) => {
+				const { format, ...rest } = options ?? {};
+				const result = await wire.screenshot(rest);
+				return format === "bytes" ? {
+					...result,
+					data: base64ToBytes(result.data)
+				} : result;
+			};
+			if (prop === "screenshotRegion") return async (region, options) => {
+				const { format, ...rest } = options ?? {};
+				const result = await wire.screenshotRegion({
+					region,
+					...rest
+				});
+				return format === "bytes" ? {
+					...result,
+					data: base64ToBytes(result.data)
+				} : result;
+			};
+			return Reflect.get(target, prop, receiver);
+		} });
 	}
 	get watch() {
 		return wrapStub(this.getConnection().rpc().watch, this.renewActivity);
 	}
+	get tunnels() {
+		return wrapStub(this.getConnection().rpc().tunnels, this.renewActivity);
+	}
 	get interpreter() {
 		return wrapStub(this.getConnection().rpc().interpreter, this.renewActivity);
 	}
@@ -3300,9 +3363,6 @@ var ContainerControlClient = class {
 	disconnect() {
 		this.destroyConnection();
 	}
-	async writeFileStream(path$1, stream, sessionId) {
-		return this.files.writeFileStream(path$1, stream, sessionId);
-	}
 };
 
 //#endregion
@@ -3819,6 +3879,13 @@ function resolveS3fsOptions(provider, userOptions) {
 
 //#endregion
 //#region src/storage-mount/validation.ts
+/**
+* Type guard for R2Bucket binding.
+* Checks for the minimal R2Bucket interface methods we use.
+*/
+function isR2Bucket(value) {
+	return typeof value === "object" && value !== null && "put" in value && typeof value.put === "function" && "get" in value && typeof value.get === "function" && "head" in value && typeof value.head === "function" && "delete" in value && typeof value.delete === "function" && "list" in value && typeof value.list === "function";
+}
 function validatePrefix(prefix) {
 	if (!prefix.startsWith("/")) throw new InvalidMountConfigError(`Prefix must start with '/': "${prefix}"`);
 }
@@ -3829,6 +3896,13 @@ function validateBucketName(bucket, mountPath) {
 	}
 	if (!/^[a-z0-9]([a-z0-9.-]{0,61}[a-z0-9])?$/.test(bucket)) throw new InvalidMountConfigError(`Invalid bucket name: "${bucket}". Bucket names must be 3-63 characters, lowercase alphanumeric, dots, or hyphens, and cannot start/end with dots or hyphens.`);
 }
+function validateBucketBindingName(bucketBinding, mountPath) {
+	if (bucketBinding.includes(":")) {
+		const [bucketName, prefixPart] = bucketBinding.split(":");
+		throw new InvalidMountConfigError(`Bucket name cannot contain ':'. To mount a prefix, use the 'prefix' option:\n  mountBucket('${bucketName}', '${mountPath}', { ...options, prefix: '${prefixPart}' })`);
+	}
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(bucketBinding)) throw new InvalidMountConfigError(`Invalid R2 binding name: "${bucketBinding}". Binding names must start with a letter or underscore and contain only letters, numbers, or underscores.`);
+}
 /**
 * Builds the s3fs source string from bucket name and optional prefix.
 * Format: "bucket" or "bucket:/prefix/" for subdirectory mounts.
@@ -4153,7 +4227,7 @@ async function proxyTerminal(stub, sessionId, request, options) {
 
 //#endregion
 //#region src/request-handler.ts
-async function proxyToSandbox(request, env) {
+async function proxyToSandbox(request, env$1) {
 	const logger = createLogger({
 		component: "sandbox-do",
 		traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
@@ -4164,7 +4238,7 @@ async function proxyToSandbox(request, env) {
 		const routeInfo = extractSandboxRoute(url);
 		if (!routeInfo) return null;
 		const { sandboxId, port, path: path$1, token } = routeInfo;
-		const sandbox = getSandbox(env.Sandbox, sandboxId, { normalizeId: true });
+		const sandbox = getSandbox(env$1.Sandbox, sandboxId, { normalizeId: true });
 		if (port !== 3e3) {
 			if (!await sandbox.validatePortToken(port, token)) {
 				logger.warn("Invalid token access blocked", {
@@ -4250,6 +4324,513 @@ function isLocalhostPattern(hostname) {
 	return hostPart === "localhost" || hostPart === "127.0.0.1" || hostPart === "0.0.0.0";
 }
 
+//#endregion
+//#region src/storage-mount/r2-egress-handler.ts
+const XML_NS = "xmlns=\"http://s3.amazonaws.com/doc/2006-03-01/\"";
+const XML_DECL = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
+function escapeXML(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function xmlResponse(body, status = 200) {
+	return new Response(XML_DECL + body, {
+		status,
+		headers: { "Content-Type": "application/xml" }
+	});
+}
+function normalizeObjectKey(value) {
+	return value.replace(/^\/+/, "");
+}
+function trimTrailingSlashes(s) {
+	let end = s.length;
+	while (end > 0 && s[end - 1] === "/") end--;
+	return s.slice(0, end);
+}
+function parsePath(pathname) {
+	const stripped = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+	if (!stripped) return null;
+	const slash = stripped.indexOf("/");
+	if (slash === -1) return {
+		bucket: stripped,
+		key: ""
+	};
+	return {
+		bucket: stripped.slice(0, slash),
+		key: normalizeObjectKey(stripped.slice(slash + 1))
+	};
+}
+function resolveR2Bucket(env$1, name) {
+	if (typeof env$1 !== "object" || env$1 === null) return null;
+	const val = env$1[name];
+	return isR2Bucket(val) ? val : null;
+}
+function parseRange(header) {
+	if (!header) return void 0;
+	const m = header.match(/^bytes=(\d*)-(\d*)$/);
+	if (!m) return void 0;
+	const start = m[1] ? parseInt(m[1], 10) : void 0;
+	const end = m[2] ? parseInt(m[2], 10) : void 0;
+	if (start === void 0 && end !== void 0) return { suffix: end };
+	if (start !== void 0 && end !== void 0) return {
+		offset: start,
+		length: end - start + 1
+	};
+	if (start !== void 0) return { offset: start };
+}
+function buildListObjectsV2Xml(bucketName, prefix, delimiter, maxKeys, result) {
+	const contents = result.objects.map((obj) => `<Contents><Key>${escapeXML(obj.key)}</Key><LastModified>${obj.uploaded.toISOString()}</LastModified><ETag>${escapeXML(obj.httpEtag)}</ETag><Size>${obj.size}</Size><StorageClass>STANDARD</StorageClass></Contents>`).join("");
+	const commonPrefixes = result.delimitedPrefixes.map((p) => `<CommonPrefixes><Prefix>${escapeXML(p)}</Prefix></CommonPrefixes>`).join("");
+	const nextToken = result.truncated && result.cursor ? `<NextContinuationToken>${escapeXML(result.cursor)}</NextContinuationToken>` : "";
+	const keyCount = result.objects.length + result.delimitedPrefixes.length;
+	return `<ListBucketResult ${XML_NS}><Name>${escapeXML(bucketName)}</Name><Prefix>${escapeXML(prefix)}</Prefix><KeyCount>${keyCount}</KeyCount><MaxKeys>${maxKeys}</MaxKeys>` + (delimiter ? `<Delimiter>${escapeXML(delimiter)}</Delimiter>` : "") + `<IsTruncated>${result.truncated}</IsTruncated>` + nextToken + contents + commonPrefixes + `</ListBucketResult>`;
+}
+function buildLocationXml() {
+	return `<LocationConstraint ${XML_NS}/>`;
+}
+function buildInitiateMultipartUploadXml(bucketName, key, uploadId) {
+	return `<InitiateMultipartUploadResult ${XML_NS}><Bucket>${escapeXML(bucketName)}</Bucket><Key>${escapeXML(key)}</Key><UploadId>${escapeXML(uploadId)}</UploadId></InitiateMultipartUploadResult>`;
+}
+function buildCompleteMultipartUploadXml(bucketName, key, etag) {
+	return `<CompleteMultipartUploadResult ${XML_NS}><Location>http://r2.internal/${escapeXML(bucketName)}/${escapeXML(key)}</Location><Bucket>${escapeXML(bucketName)}</Bucket><Key>${escapeXML(key)}</Key><ETag>${escapeXML(etag)}</ETag></CompleteMultipartUploadResult>`;
+}
+function buildCopyObjectXml(etag, uploaded) {
+	return `<CopyObjectResult ${XML_NS}><LastModified>${uploaded.toISOString()}</LastModified><ETag>${escapeXML(etag)}</ETag></CopyObjectResult>`;
+}
+function extractXmlTagContent(segment, tagName) {
+	const openTag = `<${tagName}>`;
+	const closeTag = `</${tagName}>`;
+	const start = segment.indexOf(openTag);
+	if (start === -1) return null;
+	const contentStart = start + openTag.length;
+	const end = segment.indexOf(closeTag, contentStart);
+	if (end === -1) return null;
+	return segment.slice(contentStart, end);
+}
+function parseCompleteMultipartUploadBody(body) {
+	const parts = [];
+	let pos = 0;
+	while (pos < body.length) {
+		const start = body.indexOf("<Part>", pos);
+		if (start === -1) break;
+		const end = body.indexOf("</Part>", start + 6);
+		if (end === -1) break;
+		const segment = body.slice(start, end + 7);
+		pos = end + 7;
+		const partNumberText = extractXmlTagContent(segment, "PartNumber");
+		const etagText = extractXmlTagContent(segment, "ETag");
+		const partNumber = partNumberText ? parseInt(partNumberText, 10) : NaN;
+		if (Number.isFinite(partNumber) && etagText) parts.push({
+			partNumber,
+			etag: etagText.replace(/^"|"$/g, "")
+		});
+	}
+	return parts;
+}
+function buildResponseHeaders(obj) {
+	const headers = new Headers();
+	headers.set("ETag", obj.httpEtag);
+	headers.set("Content-Length", String(obj.size));
+	headers.set("Last-Modified", obj.uploaded.toUTCString());
+	headers.set("Accept-Ranges", "bytes");
+	if (obj.httpMetadata?.contentType) headers.set("Content-Type", obj.httpMetadata.contentType);
+	if (obj.httpMetadata?.contentDisposition) headers.set("Content-Disposition", obj.httpMetadata.contentDisposition);
+	if (obj.httpMetadata?.contentEncoding) headers.set("Content-Encoding", obj.httpMetadata.contentEncoding);
+	if (obj.httpMetadata?.contentLanguage) headers.set("Content-Language", obj.httpMetadata.contentLanguage);
+	if (obj.httpMetadata?.cacheControl) headers.set("Cache-Control", obj.httpMetadata.cacheControl);
+	return headers;
+}
+function buildContentRange(range, totalSize) {
+	if ("suffix" in range) return `bytes ${Math.max(0, totalSize - range.suffix)}-${totalSize - 1}/${totalSize}`;
+	const start = range.offset ?? 0;
+	return `bytes ${start}-${range.length !== void 0 ? start + range.length - 1 : totalSize - 1}/${totalSize}`;
+}
+function getRangeContentLength(range, totalSize) {
+	if ("suffix" in range) return Math.min(range.suffix, totalSize);
+	const start = range.offset ?? 0;
+	if (start >= totalSize) return 0;
+	const requestedLength = range.length !== void 0 ? range.length : totalSize - start;
+	return Math.min(requestedLength, totalSize - start);
+}
+function extractHttpMetadata(request) {
+	const meta = {};
+	const ct = request.headers.get("Content-Type");
+	if (ct) meta.contentType = ct;
+	const cd = request.headers.get("Content-Disposition");
+	if (cd) meta.contentDisposition = cd;
+	const ce = request.headers.get("Content-Encoding");
+	if (ce) meta.contentEncoding = ce;
+	const cl = request.headers.get("Content-Language");
+	if (cl) meta.contentLanguage = cl;
+	const cc = request.headers.get("Cache-Control");
+	if (cc) meta.cacheControl = cc;
+	return meta;
+}
+function parseCopySource(header) {
+	const sourcePath = header.split("?")[0] ?? "";
+	if (!sourcePath) return null;
+	const decoded = decodeURIComponent(sourcePath);
+	const parsed = parsePath(decoded.startsWith("/") ? decoded : `/${decoded}`);
+	return parsed ? {
+		bucket: parsed.bucket,
+		key: normalizeObjectKey(parsed.key)
+	} : null;
+}
+function normalizeStorageClass(storageClass) {
+	if (storageClass === "Standard" || storageClass === "InfrequentAccess") return storageClass;
+}
+async function putRequestBody(r2, key, request, options) {
+	const contentLength = request.headers.get("Content-Length");
+	const length = contentLength ? Number.parseInt(contentLength, 10) : NaN;
+	if (!Number.isFinite(length) || length < 0) return new Response("Bad Request: missing or invalid Content-Length", { status: 400 });
+	if (length === 0) return r2.put(key, new Uint8Array(0), options);
+	if (!request.body) return new Response("Bad Request: missing request body", { status: 400 });
+	const { readable, writable } = new FixedLengthStream(length);
+	const pipe = request.body.pipeTo(writable);
+	const result = await r2.put(key, readable, options);
+	await pipe;
+	return result;
+}
+async function handleListObjects(r2, bucketName, url, mountPrefix) {
+	const queryPrefix = normalizeObjectKey(url.searchParams.get("prefix") ?? "");
+	const delimiter = url.searchParams.get("delimiter") ?? "";
+	const maxKeys = Math.min(parseInt(url.searchParams.get("max-keys") ?? "1000", 10) || 1e3, 1e3);
+	const continuationToken = url.searchParams.get("continuation-token") ?? void 0;
+	const listOpts = {
+		prefix: (mountPrefix ? `${mountPrefix}/${queryPrefix}` : queryPrefix) || void 0,
+		delimiter: delimiter || void 0,
+		limit: maxKeys,
+		cursor: continuationToken
+	};
+	const result = await r2.list(listOpts);
+	const stripKey = mountPrefix ? (k) => k.startsWith(`${mountPrefix}/`) ? k.slice(mountPrefix.length + 1) : k : (k) => k;
+	return xmlResponse(buildListObjectsV2Xml(bucketName, queryPrefix, delimiter, maxKeys, {
+		objects: result.objects.map((obj) => ({
+			key: stripKey(obj.key),
+			uploaded: obj.uploaded,
+			httpEtag: obj.httpEtag,
+			size: obj.size
+		})),
+		delimitedPrefixes: result.delimitedPrefixes.map(stripKey),
+		truncated: result.truncated,
+		cursor: result.truncated ? result.cursor : void 0
+	}));
+}
+async function handleHeadObject(r2, key) {
+	const obj = await r2.head(key);
+	if (!obj) return new Response(null, { status: 404 });
+	return new Response(null, {
+		status: 200,
+		headers: buildResponseHeaders(obj)
+	});
+}
+async function handleGetObject(r2, key, request) {
+	const range = parseRange(request.headers.get("Range"));
+	if (!range) {
+		const obj = await r2.get(key);
+		if (!obj) return new Response(null, { status: 404 });
+		return new Response(obj.body, {
+			status: 200,
+			headers: buildResponseHeaders(obj)
+		});
+	}
+	const [headObj, rangeObj] = await Promise.all([r2.head(key), r2.get(key, { range })]);
+	if (!headObj || !rangeObj) return new Response(null, { status: 404 });
+	const headers = buildResponseHeaders(rangeObj);
+	headers.set("Content-Range", buildContentRange(range, headObj.size));
+	headers.set("Content-Length", String(getRangeContentLength(range, headObj.size)));
+	return new Response(rangeObj.body, {
+		status: 206,
+		headers
+	});
+}
+async function handlePutObject(r2, bucketName, key, request, env$1, permitted, mountPrefix) {
+	const copySourceHeader = request.headers.get("x-amz-copy-source");
+	if (copySourceHeader) {
+		const copySource = parseCopySource(copySourceHeader);
+		if (!copySource || !copySource.key) return new Response("Bad Request: invalid x-amz-copy-source", { status: 400 });
+		if (!permitted.has(copySource.bucket)) return new Response(`Access to R2 bucket "${copySource.bucket}" is not permitted. Call mountBucket() with this bucket before accessing it.`, { status: 403 });
+		const sourceBucket = copySource.bucket === bucketName ? r2 : resolveR2Bucket(env$1, copySource.bucket);
+		if (!sourceBucket) return new Response(`R2 binding "${copySource.bucket}" not found in Worker env. Ensure the binding name matches the bucket name passed to mountBucket().`, { status: 500 });
+		const sourceKey = mountPrefix && copySource.bucket === bucketName ? `${mountPrefix}/${copySource.key}` : copySource.key;
+		const sourceObject = await sourceBucket.get(sourceKey);
+		if (!sourceObject) return new Response(null, { status: 404 });
+		const httpMetadata = request.headers.get("x-amz-metadata-directive")?.toUpperCase() === "REPLACE" ? extractHttpMetadata(request) : sourceObject.httpMetadata;
+		const result$1 = await r2.put(key, sourceObject.body, {
+			httpMetadata,
+			customMetadata: sourceObject.customMetadata,
+			storageClass: normalizeStorageClass(sourceObject.storageClass)
+		});
+		return xmlResponse(buildCopyObjectXml(result$1.httpEtag, result$1.uploaded));
+	}
+	const result = await putRequestBody(r2, key, request, { httpMetadata: extractHttpMetadata(request) });
+	if (result instanceof Response) return result;
+	const headers = new Headers();
+	headers.set("ETag", result.httpEtag);
+	return new Response(null, {
+		status: 200,
+		headers
+	});
+}
+async function handleDeleteObject(r2, key) {
+	await r2.delete(key);
+	return new Response(null, { status: 204 });
+}
+async function handleCreateMultipartUpload(r2, bucketName, key, request) {
+	const httpMetadata = extractHttpMetadata(request);
+	return xmlResponse(buildInitiateMultipartUploadXml(bucketName, key, (await r2.createMultipartUpload(key, { httpMetadata })).uploadId));
+}
+async function handleUploadPart(r2, key, url, request) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	const partNumber = parseInt(url.searchParams.get("partNumber") ?? "0", 10);
+	if (!uploadId || !partNumber) return new Response("Bad Request: missing uploadId or partNumber", { status: 400 });
+	if (!request.body) return new Response("Bad Request: missing request body", { status: 400 });
+	const contentLength = request.headers.get("Content-Length");
+	const partLength = contentLength ? Number.parseInt(contentLength, 10) : NaN;
+	if (!Number.isFinite(partLength) || partLength < 0) return new Response("Bad Request: missing or invalid Content-Length", { status: 400 });
+	const upload = r2.resumeMultipartUpload(key, uploadId);
+	let part;
+	if (partLength === 0) part = await upload.uploadPart(partNumber, new Uint8Array(0));
+	else {
+		const { readable, writable } = new FixedLengthStream(partLength);
+		const pipe = request.body.pipeTo(writable);
+		part = await upload.uploadPart(partNumber, readable);
+		await pipe;
+	}
+	const headers = new Headers();
+	headers.set("ETag", `"${part.etag}"`);
+	return new Response(null, {
+		status: 200,
+		headers
+	});
+}
+async function handleCompleteMultipartUpload(r2, bucketName, key, url, request) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	if (!uploadId) return new Response("Bad Request: missing uploadId", { status: 400 });
+	const r2Parts = parseCompleteMultipartUploadBody(await request.text()).map((p) => ({
+		partNumber: p.partNumber,
+		etag: p.etag
+	}));
+	return xmlResponse(buildCompleteMultipartUploadXml(bucketName, key, (await r2.resumeMultipartUpload(key, uploadId).complete(r2Parts)).httpEtag));
+}
+async function handleAbortMultipartUpload(r2, key, url) {
+	const uploadId = url.searchParams.get("uploadId") ?? "";
+	if (!uploadId) return new Response("Bad Request: missing uploadId", { status: 400 });
+	await r2.resumeMultipartUpload(key, uploadId).abort();
+	return new Response(null, { status: 204 });
+}
+const r2EgressHandler = async (request, env$1, ctx) => {
+	const url = new URL(request.url);
+	const parsed = parsePath(url.pathname);
+	if (!parsed) return new Response("Bad Request: empty path", { status: 400 });
+	const { bucket: bucketName, key } = parsed;
+	if (!ctx.params?.buckets || !(bucketName in ctx.params.buckets)) return new Response(`Access to R2 bucket "${bucketName}" is not permitted. Call mountBucket() with this bucket before accessing it.`, { status: 403 });
+	const bucketParams = ctx.params.buckets[bucketName];
+	const rawPrefix = bucketParams.prefix;
+	const mountPrefix = rawPrefix ? trimTrailingSlashes(normalizeObjectKey(rawPrefix)) : void 0;
+	const readOnly = bucketParams.readOnly ?? false;
+	const r2 = resolveR2Bucket(env$1, bucketName);
+	if (!r2) return new Response(`R2 binding "${bucketName}" not found in Worker env. Ensure the binding name matches the bucket name passed to mountBucket().`, { status: 500 });
+	const { method } = request;
+	if (!key) {
+		if (method === "GET" && url.searchParams.has("location")) return xmlResponse(buildLocationXml());
+		if (method === "GET" && url.searchParams.get("list-type") === "2") return handleListObjects(r2, bucketName, url, mountPrefix);
+		if (method === "GET") return handleListObjects(r2, bucketName, url, mountPrefix);
+		return new Response("Method Not Allowed", { status: 405 });
+	}
+	const fullKey = mountPrefix ? `${mountPrefix}/${key}` : key;
+	const permitted = new Set(Object.keys(ctx.params.buckets));
+	if (readOnly && (method === "PUT" || method === "DELETE" || method === "POST" && (url.searchParams.has("uploads") || url.searchParams.has("uploadId")))) return new Response("Forbidden: bucket mount is read-only", { status: 403 });
+	if (method === "POST" && url.searchParams.has("uploads")) return handleCreateMultipartUpload(r2, bucketName, fullKey, request);
+	if (method === "POST" && url.searchParams.has("uploadId")) return handleCompleteMultipartUpload(r2, bucketName, fullKey, url, request);
+	if (method === "PUT" && url.searchParams.has("partNumber") && url.searchParams.has("uploadId")) return handleUploadPart(r2, fullKey, url, request);
+	if (method === "DELETE" && url.searchParams.has("uploadId")) return handleAbortMultipartUpload(r2, fullKey, url);
+	switch (method) {
+		case "HEAD": return handleHeadObject(r2, fullKey);
+		case "GET": return handleGetObject(r2, fullKey, request);
+		case "PUT": return handlePutObject(r2, bucketName, fullKey, request, env$1, permitted, mountPrefix);
+		case "DELETE": return handleDeleteObject(r2, fullKey);
+		default: return new Response("Method Not Allowed", { status: 405 });
+	}
+};
+
+//#endregion
+//#region src/tunnels/sandbox-control-callback.ts
+var SandboxControlCallbackImpl = class extends RpcTarget {
+	constructor(getHandler, logger) {
+		super();
+		this.getHandler = getHandler;
+		this.logger = logger;
+	}
+	async onTunnelExit(id, port, exitCode) {
+		const handler = this.getHandler();
+		if (!handler) {
+			this.logger.debug("onTunnelExit: no handler bound; ignoring", {
+				id,
+				port,
+				exitCode
+			});
+			return;
+		}
+		await handler(id, port, exitCode);
+	}
+};
+
+//#endregion
+//#region src/tunnels/tunnels-handler.ts
+/**
+* Tunnels namespace handler. Created once per Sandbox DO instance via
+* `createTunnelsHandler(host)` and exposed as `sandbox.tunnels`.
+*
+* Storage is the source of truth. The DO holds a `Record<portString, TunnelInfo>`
+* under the `tunnels` storage key. `Sandbox.onStart()` clears the key on every
+* container restart so any record in storage is by construction backed by a
+* running `cloudflared` process; the handler never needs to verify that
+* separately against the container.
+*/
+/** DO storage key for the `port → TunnelInfo` map. */
+const STORAGE_KEY = "tunnels";
+function validateTunnelPort(port) {
+	if (!validatePort(port)) throw new SandboxSecurityError(`Invalid port number: ${port}. Must be 1024-65535, excluding reserved ports.`);
+}
+/** 8-char hex id derived from `crypto.getRandomValues`. Unique per sandbox. */
+function shortId() {
+	const buf = new Uint8Array(4);
+	crypto.getRandomValues(buf);
+	return Array.from(buf).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function isTunnelNotFoundError(error) {
+	return (error instanceof Error ? error.message : String(error)).includes("TUNNEL_NOT_FOUND");
+}
+async function readMap(storage) {
+	return await storage.get(STORAGE_KEY) ?? {};
+}
+/**
+* Concrete `TunnelsHandler` implementation. Extends `RpcTarget` so it
+* can cross the Workers RPC boundary: the Sandbox DO is reachable from
+* Workers via Workers RPC (`stub.tunnels.get(port)`), and only
+* `RpcTarget` instances are passed by reference across that boundary.
+*/
+var TunnelsRpcTarget = class extends RpcTarget$1 {
+	#host;
+	#withPortLock;
+	constructor(host, withPortLock) {
+		super();
+		this.#host = host;
+		this.#withPortLock = withPortLock;
+	}
+	async get(port) {
+		const startTime = Date.now();
+		let outcome = "error";
+		let cacheState = "miss";
+		let caughtError;
+		try {
+			validateTunnelPort(port);
+			const info = await this.#withPortLock(port, async () => {
+				const existing = (await readMap(this.#host.storage))[port.toString()];
+				if (existing) {
+					cacheState = "hit";
+					return existing;
+				}
+				const id = `quick-${shortId()}`;
+				const spawned = await this.#host.client.tunnels.runQuickTunnel(id, port);
+				await this.#host.storage.transaction(async (txn) => {
+					const nextMap = await readMap(txn);
+					nextMap[port.toString()] = spawned;
+					await txn.put(STORAGE_KEY, nextMap);
+				});
+				return spawned;
+			});
+			outcome = "success";
+			return info;
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.#host.logger, {
+				event: "tunnel.get",
+				outcome,
+				port,
+				cacheState,
+				durationMs: Date.now() - startTime,
+				error: caughtError
+			});
+		}
+	}
+	async destroy(portOrInfo) {
+		const port = typeof portOrInfo === "number" ? portOrInfo : portOrInfo.port;
+		const startTime = Date.now();
+		let outcome = "error";
+		let caughtError;
+		let tunnelId;
+		try {
+			await this.#withPortLock(port, async () => {
+				const existing = (await readMap(this.#host.storage))[port.toString()];
+				if (!existing) return;
+				tunnelId = existing.id;
+				await this.#host.storage.transaction(async (txn) => {
+					const current = await readMap(txn);
+					delete current[port.toString()];
+					await txn.put(STORAGE_KEY, current);
+				});
+				try {
+					await this.#host.client.tunnels.destroyTunnel(existing.id);
+				} catch (error) {
+					if (!isTunnelNotFoundError(error)) throw error;
+				}
+			});
+			outcome = "success";
+		} catch (error) {
+			caughtError = error instanceof Error ? error : new Error(String(error));
+			throw error;
+		} finally {
+			logCanonicalEvent(this.#host.logger, {
+				event: "tunnel.destroy",
+				outcome,
+				port,
+				tunnelId,
+				durationMs: Date.now() - startTime,
+				error: caughtError
+			});
+		}
+	}
+	async list() {
+		const map = await readMap(this.#host.storage);
+		return Object.values(map);
+	}
+};
+function createTunnelsHandler(host) {
+	const portLocks = /* @__PURE__ */ new Map();
+	const withPortLock = (port, fn) => {
+		const next = (portLocks.get(port) ?? Promise.resolve()).then(fn, fn);
+		portLocks.set(port, next.catch(() => void 0));
+		return next;
+	};
+	const tunnels = new TunnelsRpcTarget(host, withPortLock);
+	const handleTunnelExit = async (id, port, exitCode) => {
+		const startTime = Date.now();
+		await withPortLock(port, async () => {
+			await host.storage.transaction(async (txn) => {
+				const map = await readMap(txn);
+				if (map[port.toString()]?.id === id) {
+					delete map[port.toString()];
+					await txn.put(STORAGE_KEY, map);
+				}
+			});
+			logCanonicalEvent(host.logger, {
+				event: "tunnel.exit",
+				outcome: "success",
+				port,
+				tunnelId: id,
+				exitCode: exitCode ?? void 0,
+				durationMs: Date.now() - startTime
+			});
+		});
+	};
+	return {
+		tunnels,
+		handleTunnelExit
+	};
+}
+
 //#endregion
 //#region src/version.ts
 /**
@@ -4257,11 +4838,23 @@ function isLocalhostPattern(hostname) {
 * This file is auto-updated by .github/changeset-version.ts during releases
 * DO NOT EDIT MANUALLY - Changes will be overwritten on the next version bump
 */
-const SDK_VERSION = "0.10.0";
+const SDK_VERSION = "0.10.2";
 
 //#endregion
 //#region src/sandbox.ts
+const R2_EGRESS_PROXY_TARGET_CLASS_NAME = "CloudflareSandboxR2EgressProxyTarget";
+var R2EgressProxyTarget = class extends Container {};
+Object.defineProperty(R2EgressProxyTarget, "name", { value: R2_EGRESS_PROXY_TARGET_CLASS_NAME });
+R2EgressProxyTarget.outboundHandlers = { r2EgressMount: r2EgressHandler };
+function isFetcher(value) {
+	return typeof value === "object" && value !== null && "fetch" in value && typeof value.fetch === "function";
+}
 const sandboxConfigurationCache = /* @__PURE__ */ new WeakMap();
+const R2_DEFAULT_S3FS_OPTIONS = {
+	stat_cache_expire: "60",
+	enable_noobj_cache: true,
+	multipart_size: "5"
+};
 const BACKUP_DEFAULT_TTL_SECONDS = 259200;
 const BACKUP_MAX_NAME_LENGTH = 256;
 const BACKUP_CONTAINER_DIR = "/var/backups";
@@ -4407,6 +5000,10 @@ function getSandbox(ns, id, options) {
 		desktop: new Proxy({}, { get(_, method) {
 			if (typeof method !== "string" || method === "then") return void 0;
 			return (...args) => stub.callDesktop(method, args);
+		} }),
+		tunnels: new Proxy({}, { get: (_, method) => {
+			if (typeof method !== "string" || method === "then") return void 0;
+			return (...args) => stub.callTunnels(method, args);
 		} })
 	};
 	return new Proxy(stub, { get(target, prop) {
@@ -4427,19 +5024,15 @@ function connect(stub) {
 		return await stub.fetch(portSwitchedRequest);
 	};
 }
-/**
-* Type guard for R2Bucket binding.
-* Checks for the minimal R2Bucket interface methods we use.
-*/
-function isR2Bucket(value) {
-	return typeof value === "object" && value !== null && "put" in value && typeof value.put === "function" && "get" in value && typeof value.get === "function" && "head" in value && typeof value.head === "function" && "delete" in value && typeof value.delete === "function";
-}
 var Sandbox = class Sandbox extends Container {
 	defaultPort = 3e3;
 	sleepAfter = "10m";
 	client;
 	codeInterpreter;
 	sandboxName = null;
+	tunnelsHandler = null;
+	tunnelExitHandler = null;
+	controlCallback;
 	normalizeId = false;
 	defaultSession = null;
 	containerGeneration = 0;
@@ -4538,13 +5131,30 @@ var Sandbox = class Sandbox extends Container {
 	* Dispatch method for desktop operations.
 	* Called by the client-side proxy created in getSandbox() to provide
 	* the `sandbox.desktop.status()` API without relying on RPC pipelining
-	* through property getters.
+	* through property getters which is broken when using vite-plugin.
 	*/
 	async callDesktop(method, args) {
 		if (!Sandbox.DESKTOP_METHODS.has(method)) throw new Error(`Unknown desktop method: ${method}`);
 		const client = this.client.desktop;
 		const fn = client[method];
-		if (typeof fn !== "function") throw new Error(`Unknown desktop method: ${method}`);
+		if (typeof fn !== "function") throw new Error(`sandbox.desktop missing method: ${method}`);
+		return fn.apply(client, args);
+	}
+	/**
+	* Dispatch method for tunnel operations.
+	* Called by the client-side proxy created in getSandbox() to provide
+	* the `sandbox.tunnels` API without relying on RPC pipelining
+	* through property getters which is broken when using vite-plugin.
+	*/
+	async callTunnels(method, args) {
+		if (![
+			"get",
+			"list",
+			"destroy"
+		].includes(method)) throw new Error(`Unknown tunnels method: ${method}`);
+		const client = this.tunnels;
+		const fn = client[method];
+		if (typeof fn !== "function") throw new Error(`sandbox.tunnels missing method: ${method}`);
 		return fn.apply(client, args);
 	}
 	/**
@@ -4590,6 +5200,7 @@ var Sandbox = class Sandbox extends Container {
 				port: 3e3,
 				logger: this.logger,
 				retryTimeoutMs: this.computeRetryTimeoutMs(),
+				localMain: this.controlCallback,
 				onActivity: () => {
 					this.renewActivityTimeout();
 				},
@@ -4604,9 +5215,9 @@ var Sandbox = class Sandbox extends Container {
 		}
 		return this.createSandboxClient();
 	}
-	constructor(ctx, env) {
-		super(ctx, env);
-		const envObj = env;
+	constructor(ctx, env$1) {
+		super(ctx, env$1);
+		const envObj = env$1;
 		["SANDBOX_LOG_LEVEL", "SANDBOX_LOG_FORMAT"].forEach((key) => {
 			if (envObj?.[key]) this.envVars[key] = String(envObj[key]);
 		});
@@ -4629,6 +5240,7 @@ var Sandbox = class Sandbox extends Container {
 			accessKeyId: this.r2AccessKeyId,
 			secretAccessKey: this.r2SecretAccessKey
 		});
+		this.controlCallback = new SandboxControlCallbackImpl(() => this.tunnelExitHandler, this.logger);
 		this.client = this.createClientForTransport(this.transport);
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
 		this.ctx.blockConcurrencyWhile(async () => {
@@ -4656,6 +5268,8 @@ var Sandbox = class Sandbox extends Container {
 				const previousClient = this.client;
 				this.client = this.createClientForTransport(storedTransport);
 				this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
+				this.tunnelsHandler = null;
+				this.tunnelExitHandler = null;
 				previousClient.disconnect();
 			}
 			if (storedTransport) this.hasStoredTransport = true;
@@ -4747,6 +5361,8 @@ var Sandbox = class Sandbox extends Container {
 		this.hasStoredTransport = true;
 		this.client = this.createClientForTransport(transport);
 		this.codeInterpreter = new CodeInterpreter(() => this.client.interpreter);
+		this.tunnelsHandler = null;
+		this.tunnelExitHandler = null;
 		previousClient.disconnect();
 		this.renewActivityTimeout();
 		this.logger.debug("Transport updated", { transport });
@@ -4764,7 +5380,7 @@ var Sandbox = class Sandbox extends Container {
 	* Get default timeouts with env var fallbacks and validation
 	* Precedence: SDK defaults < Env vars < User config
 	*/
-	getDefaultTimeouts(env) {
+	getDefaultTimeouts(env$1) {
 		const parseAndValidate = (envVar, name, min, max) => {
 			const defaultValue = this.DEFAULT_CONTAINER_TIMEOUTS[name];
 			if (envVar === void 0) return defaultValue;
@@ -4780,9 +5396,9 @@ var Sandbox = class Sandbox extends Container {
 			return parsed;
 		};
 		return {
-			instanceGetTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_INSTANCE_TIMEOUT_MS"), "instanceGetTimeoutMS", 5e3, 3e5),
-			portReadyTimeoutMS: parseAndValidate(getEnvString(env, "SANDBOX_PORT_TIMEOUT_MS"), "portReadyTimeoutMS", 1e4, 6e5),
-			waitIntervalMS: parseAndValidate(getEnvString(env, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
+			instanceGetTimeoutMS: parseAndValidate(getEnvString(env$1, "SANDBOX_INSTANCE_TIMEOUT_MS"), "instanceGetTimeoutMS", 5e3, 3e5),
+			portReadyTimeoutMS: parseAndValidate(getEnvString(env$1, "SANDBOX_PORT_TIMEOUT_MS"), "portReadyTimeoutMS", 1e4, 6e5),
+			waitIntervalMS: parseAndValidate(getEnvString(env$1, "SANDBOX_POLL_INTERVAL_MS"), "waitIntervalMS", 100, 5e3)
 		};
 	}
 	/**
@@ -4804,7 +5420,16 @@ var Sandbox = class Sandbox extends Container {
 			await this.mountBucketLocal(bucket, mountPath, options);
 			return;
 		}
-		await this.mountBucketFuse(bucket, mountPath, options);
+		const remoteOptions = options;
+		if (remoteOptions.endpoint === void 0) {
+			const binding = this.env[bucket];
+			if (isR2Bucket(binding)) {
+				await this.mountBucketR2Egress(bucket, mountPath, options);
+				return;
+			}
+			throw new InvalidMountConfigError(`R2 binding "${bucket}" not found in Worker env. Ensure the binding name matches the bucket binding configured in wrangler.jsonc.`);
+		}
+		await this.mountBucketFuse(bucket, mountPath, remoteOptions);
 	}
 	/**
 	* Local dev mount: bidirectional sync via R2 binding + file/watch APIs
@@ -4861,12 +5486,109 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
+	getR2EgressParams() {
+		const buckets = {};
+		for (const [, m] of this.activeMounts) if (m.mountType === "r2-egress") buckets[m.bucket] = {
+			prefix: m.prefix,
+			readOnly: m.readOnly
+		};
+		return { buckets };
+	}
+	validateR2EgressS3fsOptions(options) {
+		if (!options) return;
+		const protectedOptions = new Set(["passwd_file", "url"]);
+		for (const option of options) {
+			const [key] = option.split("=");
+			if (protectedOptions.has(key)) throw new InvalidMountConfigError(`s3fs option "${key}" cannot be overridden for R2 binding mounts`);
+		}
+	}
+	/**
+	* Credential-less R2 mount: egress interception routes s3fs requests to the
+	* R2 binding. No S3 credentials are needed in the container or Worker env.
+	*/
+	async mountBucketR2Egress(bucket, mountPath, options) {
+		const mountStartTime = Date.now();
+		const prefix = options.prefix;
+		let mountOutcome = "error";
+		let mountError;
+		try {
+			validateBucketBindingName(bucket, mountPath);
+			this.validateMountPath(mountPath);
+			this.validateR2EgressS3fsOptions(options.s3fsOptions);
+			for (const [existingMountPath, mountInfo$1] of this.activeMounts) {
+				if (mountInfo$1.mountType === "r2-egress" && mountInfo$1.bucket === bucket && mountInfo$1.prefix !== prefix) throw new InvalidMountConfigError(`R2 binding "${bucket}" is already mounted at ${existingMountPath} with a different prefix. Mount the same binding only once, or use the same prefix for additional mounts.`);
+				if (mountInfo$1.mountType === "r2-egress" && mountInfo$1.bucket === bucket && mountInfo$1.readOnly !== (options.readOnly ?? false)) throw new InvalidMountConfigError(`R2 binding "${bucket}" is already mounted at ${existingMountPath} with a different readOnly setting. Mount the same binding only once, or use the same readOnly value for additional mounts.`);
+			}
+			const passwordFilePath = this.generatePasswordFilePath();
+			await this.createPasswordFile(passwordFilePath, bucket, {
+				accessKeyId: "x",
+				secretAccessKey: "x"
+			});
+			const mountInfo = {
+				mountType: "r2-egress",
+				bucket,
+				mountPath,
+				passwordFilePath,
+				mounted: false,
+				prefix,
+				readOnly: options.readOnly ?? false
+			};
+			this.activeMounts.set(mountPath, mountInfo);
+			await this.configureR2EgressOutbound(this.getR2EgressParams());
+			await this.execInternal(`mkdir -p ${shellEscape(mountPath)}`);
+			const s3fsSource = bucket;
+			const optionsStr = shellEscape(serializeS3fsOptions({
+				passwd_file: passwordFilePath,
+				...R2_DEFAULT_S3FS_OPTIONS,
+				...parseS3fsOptions(resolveS3fsOptions("r2", options.s3fsOptions)),
+				use_path_request_style: true,
+				url: "http://r2.internal",
+				...options.readOnly ? { ro: true } : {}
+			}));
+			const mountCmd = `s3fs ${shellEscape(s3fsSource)} ${shellEscape(mountPath)} -o ${optionsStr}`;
+			this.logger.debug("r2-egress: running s3fs", { mountCmd });
+			const result = await this.execInternal(mountCmd);
+			this.logger.debug("r2-egress: s3fs exited", {
+				exitCode: result.exitCode,
+				stdout: result.stdout,
+				stderr: result.stderr
+			});
+			if (result.exitCode !== 0) throw new S3FSMountError(`S3FS mount failed: ${result.stderr || result.stdout || "Unknown error"}`);
+			const mountpointCheck = await this.execInternal(`mountpoint -q ${shellEscape(mountPath)} && echo 'FUSE_MOUNTED' || echo 'NOT_FUSE_MOUNTED'`);
+			this.logger.debug("r2-egress: mountpoint check", {
+				stdout: mountpointCheck.stdout.trim(),
+				exitCode: mountpointCheck.exitCode
+			});
+			if (mountpointCheck.stdout.trim() !== "FUSE_MOUNTED") throw new S3FSMountError(`s3fs exited 0 but mount was not established at ${mountPath}`);
+			mountInfo.mounted = true;
+			mountOutcome = "success";
+		} catch (error) {
+			mountError = error instanceof Error ? error : new Error(String(error));
+			const failedMount = this.activeMounts.get(mountPath);
+			this.activeMounts.delete(mountPath);
+			if (failedMount?.mountType === "r2-egress") await this.deletePasswordFile(failedMount.passwordFilePath).catch(() => {});
+			const remainingParams = this.getR2EgressParams();
+			await this.configureR2EgressOutbound(remainingParams).catch(() => {});
+			throw error;
+		} finally {
+			logCanonicalEvent(this.logger, {
+				event: "bucket.mount",
+				outcome: mountOutcome,
+				durationMs: Date.now() - mountStartTime,
+				bucket,
+				mountPath,
+				provider: "r2",
+				prefix,
+				error: mountError
+			});
+		}
+	}
 	/**
 	* Production mount: S3FS-FUSE inside the container
 	*/
 	async mountBucketFuse(bucket, mountPath, options) {
 		const mountStartTime = Date.now();
-		const prefix = options.prefix || void 0;
+		const prefix = options.prefix;
 		let mountOutcome = "error";
 		let mountError;
 		let passwordFilePath;
@@ -4957,6 +5679,7 @@ var Sandbox = class Sandbox extends Container {
 				}
 				mountInfo.mounted = false;
 				this.activeMounts.delete(mountPath);
+				if (mountInfo.mountType === "r2-egress") await this.configureR2EgressOutbound(this.getR2EgressParams());
 				try {
 					const cleanup = await this.execInternal(`mountpoint -q ${shellEscape(mountPath)} || rmdir ${shellEscape(mountPath)}`);
 					if (cleanup.exitCode !== 0) this.logger.warn("mount directory removal failed", {
@@ -4989,7 +5712,14 @@ var Sandbox = class Sandbox extends Container {
 		}
 	}
 	/**
-	* Validate mount options
+	* Shared validation for mount path (absolute, not already in use).
+	*/
+	validateMountPath(mountPath) {
+		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
+		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
+	}
+	/**
+	* Validate mount options for remote (FUSE) mounts
 	*/
 	validateMountOptions(bucket, mountPath, options) {
 		try {
@@ -4998,8 +5728,7 @@ var Sandbox = class Sandbox extends Container {
 			throw new InvalidMountConfigError(`Invalid endpoint URL: "${options.endpoint}". Must be a valid HTTP(S) URL.`);
 		}
 		validateBucketName(bucket, mountPath);
-		if (!mountPath.startsWith("/")) throw new InvalidMountConfigError(`Mount path must be absolute (start with /): "${mountPath}"`);
-		if (this.activeMounts.has(mountPath)) throw new InvalidMountConfigError(`Mount path "${mountPath}" is already in use by bucket "${this.activeMounts.get(mountPath)?.bucket}". Unmount the existing bucket first or use a different mount path.`);
+		this.validateMountPath(mountPath);
 	}
 	/**
 	* Generate unique password file path for s3fs credentials
@@ -5059,6 +5788,13 @@ var Sandbox = class Sandbox extends Container {
 		if (result.exitCode === 2) throw new S3FSMountError(`S3FS mount failed: ${detail || "Unknown error"}`);
 		throw new S3FSMountError(`S3FS mount failed: FUSE filesystem never appeared at ${mountPath}. ${detail ? `s3fs log: ${detail}` : "No s3fs log output captured. The s3fs daemon may have exited before writing logs."}`);
 	}
+	async unmountTrackedFuseMount(mountPath, mountInfo) {
+		if (!mountInfo.mounted) return;
+		this.logger.debug(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
+		const result = await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
+		if (result.exitCode !== 0) throw new Error(`fusermount -u failed (exit ${result.exitCode}): ${result.stderr || "unknown error"}`);
+		mountInfo.mounted = false;
+	}
 	/**
 	* In-flight `destroy()` promise. While set, concurrent callers coalesce
 	* onto the same teardown instead of triggering a second one. Cleared when
@@ -5120,10 +5856,8 @@ var Sandbox = class Sandbox extends Container {
 					this.logger.warn(`Failed to stop local sync for ${mountPath}: ${errorMsg}`);
 				}
 				else {
-					if (mountInfo.mounted) try {
-						this.logger.debug(`Unmounting bucket ${mountInfo.bucket} from ${mountPath}`);
-						await this.execInternal(`fusermount -u ${shellEscape(mountPath)}`);
-						mountInfo.mounted = false;
+					try {
+						await this.unmountTrackedFuseMount(mountPath, mountInfo);
 					} catch (error) {
 						mountFailures++;
 						const errorMsg = error instanceof Error ? error.message : String(error);
@@ -5133,6 +5867,7 @@ var Sandbox = class Sandbox extends Container {
 				}
 			}
 			await this.ctx.storage.delete("portTokens");
+			await this.ctx.storage.delete("tunnels");
 			this.client.disconnect();
 			outcome = "success";
 			await super.destroy();
@@ -5160,6 +5895,11 @@ var Sandbox = class Sandbox extends Container {
 		} catch (error) {
 			this.logger.error("Failed to restore exposed ports after container start", error instanceof Error ? error : new Error(String(error)));
 		}
+		try {
+			await this.ctx.storage.delete("tunnels");
+		} catch (error) {
+			this.logger.error("Failed to clear tunnel storage after container start", error instanceof Error ? error : new Error(String(error)));
+		}
 	}
 	/**
 	* Re-expose ports on the container runtime using tokens persisted in DO
@@ -5262,7 +6002,10 @@ var Sandbox = class Sandbox extends Container {
 		this.defaultSession = null;
 		this.defaultSessionInit = null;
 		this.client.disconnect();
+		let hadR2EgressMount = false;
 		for (const [, m] of this.activeMounts) if (m.mountType === "local-sync") await m.syncManager.stop().catch(() => {});
+		else if (m.mountType === "r2-egress") hadR2EgressMount = true;
+		if (hadR2EgressMount) await this.configureR2EgressOutbound({ buckets: {} }).catch(() => {});
 		this.activeMounts.clear();
 		await this.ctx.storage.delete("defaultSession");
 	}
@@ -6009,8 +6752,11 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async getProcess(id, sessionId) {
 		const session = sessionId ?? await this.ensureDefaultSession();
-		const response = await this.client.processes.getProcess(id);
-		if (!response.process) return null;
+		const response = await this.client.processes.getProcess(id).catch((e) => {
+			if (e instanceof ProcessNotFoundError) return null;
+			throw e;
+		});
+		if (!response?.process) return null;
 		const processData = response.process;
 		return this.createProcessFromDTO({
 			id: processData.id,
@@ -6081,7 +6827,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async writeFile(path$1, content, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
-		if (content instanceof ReadableStream) return this.client.writeFileStream(path$1, content, session);
+		if (content instanceof ReadableStream) return this.client.files.writeFileStream(path$1, content, session);
 		return this.client.files.writeFile(path$1, content, session, { encoding: options.encoding });
 	}
 	async deleteFile(path$1, sessionId) {
@@ -6098,6 +6844,7 @@ var Sandbox = class Sandbox extends Container {
 	}
 	async readFile(path$1, options = {}) {
 		const session = options.sessionId ?? await this.ensureDefaultSession();
+		if (options.encoding === "none") return this.client.files.readFile(path$1, session, { encoding: "none" });
 		return this.client.files.readFile(path$1, session, { encoding: options.encoding });
 	}
 	/**
@@ -6326,6 +7073,45 @@ var Sandbox = class Sandbox extends Container {
 			}];
 		});
 	}
+	/**
+	* Namespaced tunnel API. Quick tunnels are zero-config preview URLs
+	* backed by Cloudflare's trycloudflare service.
+	*
+	* - `tunnels.get(port)` — idempotent. Returns the cached tunnel for
+	*   `port` if one exists in DO storage, otherwise spawns a fresh
+	*   cloudflared process and persists the record.
+	* - `tunnels.list()` — records currently known to this sandbox, from
+	*   DO storage.
+	* - `tunnels.destroy(portOrInfo)` — tear down by port number or by
+	*   the record returned from `get()`.
+	*
+	* Storage is cleared on container restart (`onStart`), so URLs do
+	* not survive a container restart — the next `get(port)` call will
+	* spawn a fresh tunnel with a new URL.
+	*
+	* Requires the RPC transport. Calling this on a route-based transport
+	* throws "RPC transport required".
+	*/
+	get tunnels() {
+		this.ensureTunnelsBuilt();
+		return this.tunnelsHandler;
+	}
+	/**
+	* Lazily construct both the public tunnels handler and its sibling
+	* exit-handler callback. Called from the `tunnels` getter on first
+	* access and on every access after a transport swap clears both
+	* fields.
+	*/
+	ensureTunnelsBuilt() {
+		if (this.tunnelsHandler) return;
+		const built = createTunnelsHandler({
+			client: this.client,
+			storage: this.ctx.storage,
+			logger: this.logger
+		});
+		this.tunnelsHandler = built.tunnels;
+		this.tunnelExitHandler = built.handleTunnelExit;
+	}
 	async isPortExposed(port) {
 		try {
 			const sessionId = await this.ensureDefaultSession();
@@ -6472,9 +7258,16 @@ var Sandbox = class Sandbox extends Container {
 				...options,
 				sessionId
 			}),
-			readFile: (path$1, options) => this.readFile(path$1, {
-				...options,
-				sessionId
+			readFile: ((path$1, options) => {
+				const encoding = options?.encoding;
+				if (encoding === "none") return this.readFile(path$1, {
+					encoding: "none",
+					sessionId
+				});
+				return this.readFile(path$1, {
+					encoding,
+					sessionId
+				});
 			}),
 			readFileStream: (path$1) => this.readFileStream(path$1, { sessionId }),
 			watch: (path$1, options) => this.watch(path$1, {
@@ -7534,7 +8327,7 @@ var Sandbox = class Sandbox extends Container {
 					},
 					timestamp: (/* @__PURE__ */ new Date()).toISOString()
 				});
-				await this.client.writeFileStream(archivePath, body, backupSession);
+				await this.client.files.writeFileStream(archivePath, body, backupSession);
 			} else {
 				const archiveBuffer = await archiveObject.arrayBuffer();
 				const base64Content = Buffer.from(archiveBuffer).toString("base64");
@@ -7588,8 +8381,24 @@ var Sandbox = class Sandbox extends Container {
 			});
 		}
 	}
+	async configureR2EgressOutbound(params) {
+		const ctx = this.ctx;
+		if (!ctx.container?.interceptOutboundHttp) throw new InvalidMountConfigError("R2 binding mounts require container outbound interception support");
+		if (!ctx.exports?.ContainerProxy) throw new InvalidMountConfigError("R2 binding mounts require exporting ContainerProxy from the Worker entrypoint");
+		const fetcher = ctx.exports.ContainerProxy({ props: {
+			enableInternet: this.enableInternet,
+			containerId: this.ctx.id.toString(),
+			className: R2_EGRESS_PROXY_TARGET_CLASS_NAME,
+			outboundByHostOverrides: { "r2.internal": {
+				method: "r2EgressMount",
+				params
+			} }
+		} });
+		if (!isFetcher(fetcher)) throw new InvalidMountConfigError("R2 binding mounts require ContainerProxy to return a valid Fetcher");
+		await ctx.container.interceptOutboundHttp("r2.internal", fetcher);
+	}
 };
 
 //#endregion
 export { DesktopInvalidOptionsError as A, CommandClient as C, BackupNotFoundError as D, BackupExpiredError as E, InvalidBackupConfigError as F, ProcessExitedBeforeReadyError as I, ProcessReadyTimeoutError as L, DesktopProcessCrashedError as M, DesktopStartFailedError as N, BackupRestoreError as O, DesktopUnavailableError as P, RPCTransportError as R, DesktopClient as S, BackupCreateError as T, UtilityClient as _, BucketMountError as a, GitClient as b, MissingCredentialsError as c, parseSSEStream as d, responseToAsyncIterable as f, SandboxClient as g, streamFile as h, proxyTerminal as i, DesktopNotStartedError as j, DesktopInvalidCoordinatesError as k, S3FSMountError as l, collectFile as m, getSandbox as n, BucketUnmountError as o, CodeInterpreter as p, proxyToSandbox as r, InvalidMountConfigError as s, Sandbox as t, asyncIterableToSSEStream as u, ProcessClient as v, BackupClient as w, FileClient as x, PortClient as y, SessionTerminatedError as z };
-//# sourceMappingURL=sandbox-2bHZZmy5.js.map
+//# sourceMappingURL=sandbox-BcEq4aUF.js.map