Fix WebSocket connections through exposed ports (#156)

* Add WebSocket support for exposed sandbox ports

WebSocket upgrade requests previously failed because containerFetch()
uses JSRPC which cannot serialize the upgrade handshake. WebSocket
requests now route through Container's fetch() instead.

* Add E2E test for WebSocket connections

* Add changeset

Author: ghostwriternr

.changeset/fix-websocket-routing.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/sandbox": patch
+---
+
+Fix WebSocket upgrade requests through exposed ports

package-lock.json

@@ -33,20 +33,22 @@
     "@types/node": "^24.1.0",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
+    "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^4.7.0",
     "@vitest/ui": "^3.2.4",
     "fast-glob": "^3.3.3",
     "happy-dom": "^20.0.0",
+    "pkg-pr-new": "^0.0.60",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "tsup": "^8.5.0",
     "tsx": "^4.20.3",
     "turbo": "^2.5.8",
     "typescript": "^5.8.3",
-    "pkg-pr-new": "^0.0.60",
     "vite": "^7.1.11",
     "vitest": "^3.2.4",
-    "wrangler": "^4.42.2"
+    "wrangler": "^4.42.2",
+    "ws": "^8.18.3"
   },
   "private": true,
   "packageManager": "[email protected]"

package.json

@@ -27,7 +27,7 @@
     "docker:local": "cd ../.. && docker build -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox-test:$npm_package_version .",
     "docker:publish": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox:$npm_package_version --push .",
     "docker:publish:beta": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile --build-arg SANDBOX_VERSION=$npm_package_version -t cloudflare/sandbox:$npm_package_version-beta --push .",
-    "test": "vitest run --config vitest.config.ts",
+    "test": "vitest run --config vitest.config.ts \"$@\"",
     "test:e2e": "cd ../.. && vitest run --config vitest.e2e.config.ts \"$@\""
   },
   "exports": {

packages/sandbox/package.json

@@ -1,4 +1,5 @@
 import { createLogger, type LogContext, TraceContext } from "@repo/shared";
+import { switchPort } from "@cloudflare/containers";
 import { getSandbox, type Sandbox } from "./sandbox";
 import {
   sanitizeSandboxId,
@@ -70,6 +71,14 @@ export async function proxyToSandbox<E extends SandboxEnv>(
       }
     }
 
+    // Detect WebSocket upgrade request
+    const upgradeHeader = request.headers.get('Upgrade');
+    if (upgradeHeader?.toLowerCase() === 'websocket') {
+      // WebSocket path: Must use fetch() not containerFetch()
+      // This bypasses JSRPC serialization boundary which cannot handle WebSocket upgrades
+      return await sandbox.fetch(switchPort(request, port));
+    }
+
     // Build proxy request with proper headers
     let proxyUrl: string;
 
@@ -96,7 +105,7 @@ export async function proxyToSandbox<E extends SandboxEnv>(
       duplex: 'half',
     });
 
-    return sandbox.containerFetch(proxyRequest, port);
+    return await sandbox.containerFetch(proxyRequest, port);
   } catch (error) {
     logger.error('Proxy routing error', error instanceof Error ? error : new Error(String(error)));
     return new Response('Proxy routing error', { status: 500 });

packages/sandbox/src/request-handler.ts

@@ -238,7 +238,17 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
         await this.ctx.storage.put('sandboxName', name);
       }
 
-      // Determine which port to route to
+      // Detect WebSocket upgrade request
+      const upgradeHeader = request.headers.get('Upgrade');
+      const isWebSocket = upgradeHeader?.toLowerCase() === 'websocket';
+
+      if (isWebSocket) {
+        // WebSocket path: Let parent Container class handle WebSocket proxying
+        // This bypasses containerFetch() which uses JSRPC and cannot handle WebSocket upgrades
+        return await super.fetch(request);
+      }
+
+      // Non-WebSocket: Use existing port determination and HTTP routing logic
       const port = this.determinePort(url);
 
       // Route to the appropriate port