@cloudflare/sandbox 0.10.3 → 0.11.0

package/dist/bridge/index.js

@@ -1,6 +1,6 @@
 import "../dist-B_eXrP83.js";
-import "../errors-8Hvune8K.js";
-import { h as streamFile, n as getSandbox } from "../sandbox-B-MUmsli.js";
+import "../errors-COsTRno_.js";
+import { C as streamFile, b as validatePort, n as getSandbox, v as SandboxSecurityError, x as validateTunnelName } from "../sandbox-DQxTkLyY.js";
 import { DurableObject, env } from "cloudflare:workers";
 import { Hono } from "hono";
 
@@ -267,6 +267,50 @@ const OPENAPI_SCHEMA = {
 					example: "/mnt/data"
 				} }
 			},
+			TunnelRequest: {
+				type: "object",
+				properties: { name: {
+					type: "string",
+					description: "Subdomain prefix for a named tunnel, such as `app`. Do not pass a full hostname. Omit to create or reuse an ephemeral tunnel.",
+					example: "app"
+				} }
+			},
+			Tunnel: {
+				type: "object",
+				required: [
+					"id",
+					"port",
+					"url",
+					"hostname",
+					"createdAt"
+				],
+				properties: {
+					id: { type: "string" },
+					port: {
+						type: "integer",
+						description: "Container port served by the tunnel.",
+						example: 8080
+					},
+					url: {
+						type: "string",
+						format: "uri",
+						example: "https://app.example.com"
+					},
+					hostname: {
+						type: "string",
+						example: "app.example.com"
+					},
+					createdAt: {
+						type: "string",
+						format: "date-time"
+					},
+					name: {
+						type: "string",
+						description: "Present for named tunnels only.",
+						example: "app"
+					}
+				}
+			},
 			ErrorResponse: {
 				type: "object",
 				required: ["error", "code"],
@@ -290,7 +334,8 @@ const OPENAPI_SCHEMA = {
 							"pool_error",
 							"mount_error",
 							"unmount_error",
-							"session_error"
+							"session_error",
+							"tunnel_error"
 						]
 					}
 				}
@@ -439,6 +484,103 @@ const OPENAPI_SCHEMA = {
 				}
 			}
 		} },
+		"/v1/sandbox/{id}/tunnel/{port}": {
+			post: {
+				operationId: "createTunnel",
+				summary: "Create or reuse a tunnel for a sandbox port",
+				description: "Returns an existing tunnel for the port when one is already recorded, or provisions one when needed. The service must already be listening inside the sandbox. Omit `name` for an ephemeral `*.trycloudflare.com` tunnel, or pass `name` to choose the subdomain prefix for a named tunnel. Use a value such as `app`, not a full hostname.",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "Ephemeral tunnel",
+					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+				}, {
+					lang: "curl",
+					label: "Named tunnel",
+					source: "curl -X POST https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"app\"}'"
+				}],
+				parameters: [{
+					name: "id",
+					in: "path",
+					required: true,
+					schema: { type: "string" },
+					description: "Sandbox instance name."
+				}, {
+					name: "port",
+					in: "path",
+					required: true,
+					schema: {
+						type: "integer",
+						minimum: 1024,
+						maximum: 65535
+					},
+					description: "Container port to tunnel. Port 3000 is reserved."
+				}],
+				requestBody: {
+					required: false,
+					content: { "application/json": { schema: { $ref: "#/components/schemas/TunnelRequest" } } }
+				},
+				responses: {
+					"200": {
+						description: "Tunnel created or reused.",
+						content: { "application/json": { schema: { $ref: "#/components/schemas/Tunnel" } } }
+					},
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"502": {
+						description: "Tunnel creation failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "tunnel failed: cloudflared could not be found",
+								code: "tunnel_error"
+							}
+						} }
+					}
+				}
+			},
+			delete: {
+				operationId: "deleteTunnel",
+				summary: "Delete the tunnel for a sandbox port",
+				description: "Stops the tunnel process for the port and removes any named-tunnel Cloudflare resources tracked by the sandbox.",
+				"x-codeSamples": [{
+					lang: "curl",
+					label: "Delete tunnel",
+					source: "curl -X DELETE https://$HOST/v1/sandbox/my-sandbox/tunnel/8080 \\\n  -H \"Authorization: Bearer $SANDBOX_API_KEY\""
+				}],
+				parameters: [{
+					name: "id",
+					in: "path",
+					required: true,
+					schema: { type: "string" },
+					description: "Sandbox instance name."
+				}, {
+					name: "port",
+					in: "path",
+					required: true,
+					schema: {
+						type: "integer",
+						minimum: 1024,
+						maximum: 65535
+					},
+					description: "Container port whose tunnel should be deleted. Port 3000 is reserved."
+				}],
+				responses: {
+					"204": { description: "Tunnel deleted or already absent." },
+					"400": { $ref: "#/components/responses/InvalidRequest" },
+					"401": { $ref: "#/components/responses/Unauthorized" },
+					"502": {
+						description: "Tunnel deletion failed.",
+						content: { "application/json": {
+							schema: { $ref: "#/components/schemas/ErrorResponse" },
+							example: {
+								error: "tunnel failed: cleanup failed",
+								code: "tunnel_error"
+							}
+						} }
+					}
+				}
+			}
+		},
 		"/v1/sandbox/{id}/file/{path}": {
 			get: {
 				operationId: "readFile",
@@ -1632,6 +1774,24 @@ function hasCredentials(options) {
 function isStringArray(value) {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function parseTunnelOptions(rawBody) {
+	if (!rawBody.trim()) return void 0;
+	let body;
+	try {
+		body = JSON.parse(rawBody);
+	} catch {
+		return errorJson("Invalid JSON body", "invalid_request", 400);
+	}
+	if (!body || typeof body !== "object" || Array.isArray(body) || body.name === void 0) return;
+	if (typeof body.name !== "string") return errorJson("name must be a string when provided", "invalid_request", 400);
+	try {
+		validateTunnelName(body.name);
+	} catch (err) {
+		if (err instanceof SandboxSecurityError) return errorJson(err.message, "invalid_request", 400);
+		throw err;
+	}
+	return { name: body.name };
+}
 function validateMountOptions(options, binding) {
 	if ("endpoint" in options && !hasEndpoint(options)) return errorJson("options.endpoint must be a string when provided", "invalid_request", 400);
 	if (binding !== void 0 && typeof binding !== "string") return errorJson("binding must be a string when provided", "invalid_request", 400);
@@ -1865,6 +2025,30 @@ function createBridgeApp(config) {
 			return errorJson(`write failed: ${err instanceof Error ? err.message : String(err)}`, "workspace_archive_write_error", 502);
 		}
 	});
+	app.post(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const options = parseTunnelOptions(await c.req.text());
+		if (options instanceof Response) return options;
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			const tunnel = await sandbox.tunnels.get(port, options);
+			return c.json(tunnel);
+		} catch (err) {
+			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
+		}
+	});
+	app.delete(`${apiPrefix}/sandbox/:id/tunnel/:port`, async (c) => {
+		const port = Number(c.req.param("port"));
+		if (!validatePort(port)) return errorJson("Invalid port", "invalid_request", 400);
+		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
+		try {
+			await sandbox.tunnels.destroy(port);
+			return c.body(null, 204);
+		} catch (err) {
+			return errorJson(`tunnel failed: ${err instanceof Error ? err.message : String(err)}`, "tunnel_error", 502);
+		}
+	});
 	app.get(`${apiPrefix}/sandbox/:id/running`, async (c) => {
 		const sandbox = getSandbox$1(getSandboxNs(c.env), c.get("containerUUID"));
 		try {