@cloudflare/sandbox 0.6.11 → 0.7.1

package/dist/index.js

@@ -1,5 +1,5 @@
-import { a as isExecResult, c as shellEscape, d as TraceContext, f as Execution, g as getEnvString, h as extractRepoName, i as isWSStreamChunk, l as createLogger, m as GitLogger, n as isWSError, o as isProcess, p as ResultImpl, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createNoOpLogger } from "./dist-c_xYW5i_.js";
-import { t as ErrorCode } from "./errors-BCXUmJUn.js";
+import { _ as getEnvString, a as isExecResult, c as shellEscape, d as TraceContext, f as Execution, g as filterEnvVars, h as extractRepoName, i as isWSStreamChunk, l as createLogger, m as GitLogger, n as isWSError, o as isProcess, p as ResultImpl, r as isWSResponse, s as isProcessStatus, t as generateRequestId, u as createNoOpLogger, v as partitionEnvVars } from "./dist-D9B_6gn_.js";
+import { t as ErrorCode } from "./errors-Bzl0ZNia.js";
 import { Container, getContainer, switchPort } from "@cloudflare/containers";
 
 //#region src/errors/classes.ts
@@ -2216,6 +2216,19 @@ var CodeInterpreter = class {
 	}
 };
 
+//#endregion
+//#region src/pty/proxy.ts
+async function proxyTerminal(stub, sessionId, request, options) {
+	if (!sessionId || typeof sessionId !== "string") throw new Error("sessionId is required for terminal access");
+	if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") throw new Error("terminal() requires a WebSocket upgrade request");
+	const params = new URLSearchParams({ sessionId });
+	if (options?.cols) params.set("cols", String(options.cols));
+	if (options?.rows) params.set("rows", String(options.rows));
+	const ptyUrl = `http://localhost/ws/pty?${params}`;
+	const ptyRequest = new Request(ptyUrl, request);
+	return stub.fetch(switchPort(ptyRequest, 3e3));
+}
+
 //#endregion
 //#region src/request-handler.ts
 async function proxyToSandbox(request, env) {
@@ -2254,15 +2267,18 @@ async function proxyToSandbox(request, env) {
 		let proxyUrl;
 		if (port !== 3e3) proxyUrl = `http://localhost:${port}${path}${url.search}`;
 		else proxyUrl = `http://localhost:3000${path}${url.search}`;
+		const headers = {
+			"X-Original-URL": request.url,
+			"X-Forwarded-Host": url.hostname,
+			"X-Forwarded-Proto": url.protocol.replace(":", ""),
+			"X-Sandbox-Name": sandboxId
+		};
+		request.headers.forEach((value, key) => {
+			headers[key] = value;
+		});
 		const proxyRequest = new Request(proxyUrl, {
 			method: request.method,
-			headers: {
-				...Object.fromEntries(request.headers),
-				"X-Original-URL": request.url,
-				"X-Forwarded-Host": url.hostname,
-				"X-Forwarded-Proto": url.protocol.replace(":", ""),
-				"X-Sandbox-Name": sandboxId
-			},
+			headers,
 			body: request.body,
 			duplex: "half"
 		});
@@ -2273,21 +2289,29 @@ async function proxyToSandbox(request, env) {
 	}
 }
 function extractSandboxRoute(url) {
-	const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*?[^.-]|[^.-])-([a-z0-9_-]{16})\.(.+)$/);
-	if (!subdomainMatch) return null;
-	const portStr = subdomainMatch[1];
-	const sandboxId = subdomainMatch[2];
-	const token = subdomainMatch[3];
-	subdomainMatch[4];
+	const dotIndex = url.hostname.indexOf(".");
+	if (dotIndex === -1) return null;
+	const subdomain = url.hostname.slice(0, dotIndex);
+	url.hostname.slice(dotIndex + 1);
+	const firstHyphen = subdomain.indexOf("-");
+	if (firstHyphen === -1) return null;
+	const portStr = subdomain.slice(0, firstHyphen);
+	if (!/^\d{4,5}$/.test(portStr)) return null;
 	const port = parseInt(portStr, 10);
 	if (!validatePort(port)) return null;
+	const rest = subdomain.slice(firstHyphen + 1);
+	const lastHyphen = rest.lastIndexOf("-");
+	if (lastHyphen === -1) return null;
+	const sandboxId = rest.slice(0, lastHyphen);
+	const token = rest.slice(lastHyphen + 1);
+	if (!/^[a-z0-9_]+$/.test(token) || token.length === 0 || token.length > 63) return null;
+	if (sandboxId.length === 0 || sandboxId.length > 63) return null;
 	let sanitizedSandboxId;
 	try {
 		sanitizedSandboxId = sanitizeSandboxId(sandboxId);
-	} catch (error) {
+	} catch {
 		return null;
 	}
-	if (sandboxId.length > 63) return null;
 	return {
 		port,
 		sandboxId: sanitizedSandboxId,
@@ -2540,7 +2564,7 @@ function buildS3fsSource(bucket, prefix) {
 * 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.6.11";
+const SDK_VERSION = "0.7.1";
 
 //#endregion
 //#region src/sandbox.ts
@@ -2555,7 +2579,27 @@ function getSandbox(ns, id, options) {
 	if (options?.sleepAfter !== void 0) stub.setSleepAfter(options.sleepAfter);
 	if (options?.keepAlive !== void 0) stub.setKeepAlive(options.keepAlive);
 	if (options?.containerTimeouts) stub.setContainerTimeouts(options.containerTimeouts);
-	return Object.assign(stub, { wsConnect: connect(stub) });
+	const defaultSessionId = `sandbox-${effectiveId}`;
+	const enhancedMethods = {
+		createSession: async (opts) => {
+			return enhanceSession(stub, await stub.createSession(opts));
+		},
+		getSession: async (sessionId) => {
+			return enhanceSession(stub, await stub.getSession(sessionId));
+		},
+		terminal: (request, opts) => proxyTerminal(stub, defaultSessionId, request, opts),
+		wsConnect: connect(stub)
+	};
+	return new Proxy(stub, { get(target, prop) {
+		if (typeof prop === "string" && prop in enhancedMethods) return enhancedMethods[prop];
+		return target[prop];
+	} });
+}
+function enhanceSession(stub, rpcSession) {
+	return {
+		...rpcSession,
+		terminal: (request, opts) => proxyTerminal(stub, rpcSession.id, request, opts)
+	};
 }
 function connect(stub) {
 	return async (request, port) => {
@@ -2657,14 +2701,23 @@ var Sandbox = class extends Container {
 		await this.ctx.storage.put("keepAliveEnabled", keepAlive);
 	}
 	async setEnvVars(envVars) {
+		const { toSet, toUnset } = partitionEnvVars(envVars);
+		for (const key of toUnset) delete this.envVars[key];
 		this.envVars = {
 			...this.envVars,
-			...envVars
+			...toSet
 		};
-		if (this.defaultSession) for (const [key, value] of Object.entries(envVars)) {
-			const exportCommand = `export ${key}='${value.replace(/'/g, "'\\''")}'`;
-			const result = await this.client.commands.execute(exportCommand, this.defaultSession);
-			if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
+		if (this.defaultSession) {
+			for (const key of toUnset) {
+				const unsetCommand = `unset ${key}`;
+				const result = await this.client.commands.execute(unsetCommand, this.defaultSession);
+				if (result.exitCode !== 0) throw new Error(`Failed to unset ${key}: ${result.stderr || "Unknown error"}`);
+			}
+			for (const [key, value] of Object.entries(toSet)) {
+				const exportCommand = `export ${key}=${shellEscape(value)}`;
+				const result = await this.client.commands.execute(exportCommand, this.defaultSession);
+				if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
+			}
 		}
 	}
 	/**
@@ -3422,7 +3475,7 @@ var Sandbox = class extends Container {
 			const requestOptions = {
 				...options?.processId !== void 0 && { processId: options.processId },
 				...options?.timeout !== void 0 && { timeoutMs: options.timeout },
-				...options?.env !== void 0 && { env: options.env },
+				...options?.env !== void 0 && { env: filterEnvVars(options.env) },
 				...options?.cwd !== void 0 && { cwd: options.cwd },
 				...options?.encoding !== void 0 && { encoding: options.encoding },
 				...options?.autoCleanup !== void 0 && { autoCleanup: options.autoCleanup }
@@ -3590,6 +3643,30 @@ var Sandbox = class extends Container {
 		const session = sessionId ?? await this.ensureDefaultSession();
 		return this.client.files.exists(path, session);
 	}
+	/**
+	* Expose a port and get a preview URL for accessing services running in the sandbox
+	*
+	* @param port - Port number to expose (1024-65535)
+	* @param options - Configuration options
+	* @param options.hostname - Your Worker's domain name (required for preview URL construction)
+	* @param options.name - Optional friendly name for the port
+	* @param options.token - Optional custom token for the preview URL (1-16 characters: lowercase letters, numbers, hyphens, underscores)
+	*                       If not provided, a random 16-character token will be generated automatically
+	* @returns Preview URL information including the full URL, port number, and optional name
+	*
+	* @example
+	* // With auto-generated token
+	* const { url } = await sandbox.exposePort(8080, { hostname: 'example.com' });
+	* // url: https://8080-sandbox-id-abc123random4567.example.com
+	*
+	* @example
+	* // With custom token for stable URLs across deployments
+	* const { url } = await sandbox.exposePort(8080, {
+	*   hostname: 'example.com',
+	*   token: 'my-token-v1'
+	* });
+	* // url: https://8080-sandbox-id-my-token-v1.example.com
+	*/
 	async exposePort(port, options) {
 		if (options.hostname.endsWith(".workers.dev")) throw new CustomDomainRequiredError({
 			code: ErrorCode.CUSTOM_DOMAIN_REQUIRED,
@@ -3598,11 +3675,17 @@ var Sandbox = class extends Container {
 			httpStatus: 400,
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		const sessionId = await this.ensureDefaultSession();
-		await this.client.ports.exposePort(port, sessionId, options?.name);
 		if (!this.sandboxName) throw new Error("Sandbox name not available. Ensure sandbox is accessed through getSandbox()");
-		const token = this.generatePortToken();
+		let token;
+		if (options.token !== void 0) {
+			this.validateCustomToken(options.token);
+			token = options.token;
+		} else token = this.generatePortToken();
 		const tokens = await this.ctx.storage.get("portTokens") || {};
+		const existingPort = Object.entries(tokens).find(([p, t]) => t === token && p !== port.toString());
+		if (existingPort) throw new SecurityError(`Token '${token}' is already in use by port ${existingPort[0]}. Please use a different token.`);
+		const sessionId = await this.ensureDefaultSession();
+		await this.client.ports.exposePort(port, sessionId, options?.name);
 		tokens[port.toString()] = token;
 		await this.ctx.storage.put("portTokens", tokens);
 		return {
@@ -3652,12 +3735,21 @@ var Sandbox = class extends Container {
 			this.logger.error("Port is exposed but has no token - bug detected", void 0, { port });
 			return false;
 		}
-		return storedToken === token;
+		if (storedToken.length !== token.length) return false;
+		const encoder = new TextEncoder();
+		const a = encoder.encode(storedToken);
+		const b = encoder.encode(token);
+		return crypto.subtle.timingSafeEqual(a, b);
+	}
+	validateCustomToken(token) {
+		if (token.length === 0) throw new SecurityError(`Custom token cannot be empty.`);
+		if (token.length > 16) throw new SecurityError(`Custom token too long. Maximum 16 characters allowed. Received: ${token.length} characters.`);
+		if (!/^[a-z0-9_]+$/.test(token)) throw new SecurityError(`Custom token must contain only lowercase letters (a-z), numbers (0-9), and underscores (_). Invalid token provided.`);
 	}
 	generatePortToken() {
 		const array = new Uint8Array(12);
 		crypto.getRandomValues(array);
-		return btoa(String.fromCharCode(...array)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "").toLowerCase();
+		return btoa(String.fromCharCode(...array)).replace(/\+/g, "_").replace(/\//g, "_").replace(/=/g, "").toLowerCase();
 	}
 	constructPreviewUrl(port, sandboxId, hostname, token) {
 		if (!validatePort(port)) throw new SecurityError(`Invalid port number: ${port}. Must be between 1024-65535 and not reserved.`);
@@ -3690,11 +3782,11 @@ var Sandbox = class extends Container {
 	*/
 	async createSession(options) {
 		const sessionId = options?.id || `session-${Date.now()}`;
-		const mergedEnv = {
+		const filteredEnv = filterEnvVars({
 			...this.envVars,
 			...options?.env ?? {}
-		};
-		const envPayload = Object.keys(mergedEnv).length > 0 ? mergedEnv : void 0;
+		});
+		const envPayload = Object.keys(filteredEnv).length > 0 ? filteredEnv : void 0;
 		await this.client.utils.createSession({
 			id: sessionId,
 			...envPayload && { env: envPayload },
@@ -3734,13 +3826,10 @@ var Sandbox = class extends Container {
 			timestamp: response.timestamp
 		};
 	}
-	/**
-	* Internal helper to create ExecutionSession wrapper for a given sessionId
-	* Used by both createSession and getSession
-	*/
 	getSessionWrapper(sessionId) {
 		return {
 			id: sessionId,
+			terminal: null,
 			exec: (command, options) => this.execWithSession(command, sessionId, options),
 			execStream: (command, options) => this.execStreamWithSession(command, sessionId, options),
 			startProcess: (command, options) => this.startProcess(command, options, sessionId),
@@ -3774,9 +3863,15 @@ var Sandbox = class extends Container {
 				sessionId
 			}),
 			setEnvVars: async (envVars) => {
+				const { toSet, toUnset } = partitionEnvVars(envVars);
 				try {
-					for (const [key, value] of Object.entries(envVars)) {
-						const exportCommand = `export ${key}='${value.replace(/'/g, "'\\''")}'`;
+					for (const key of toUnset) {
+						const unsetCommand = `unset ${key}`;
+						const result = await this.client.commands.execute(unsetCommand, sessionId);
+						if (result.exitCode !== 0) throw new Error(`Failed to unset ${key}: ${result.stderr || "Unknown error"}`);
+					}
+					for (const [key, value] of Object.entries(toSet)) {
+						const exportCommand = `export ${key}=${shellEscape(value)}`;
 						const result = await this.client.commands.execute(exportCommand, sessionId);
 						if (result.exitCode !== 0) throw new Error(`Failed to set ${key}: ${result.stderr || "Unknown error"}`);
 					}
@@ -3933,5 +4028,5 @@ async function collectFile(stream) {
 }
 
 //#endregion
-export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, streamFile };
+export { BucketMountError, CodeInterpreter, CommandClient, FileClient, GitClient, InvalidMountConfigError, MissingCredentialsError, PortClient, ProcessClient, ProcessExitedBeforeReadyError, ProcessReadyTimeoutError, S3FSMountError, Sandbox, SandboxClient, UtilityClient, asyncIterableToSSEStream, collectFile, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyTerminal, proxyToSandbox, responseToAsyncIterable, streamFile };
 //# sourceMappingURL=index.js.map