@cloudflare/sandbox 0.4.9 → 0.4.11

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/sandbox-sdk"
   },
   "description": "A sandboxed environment for running commands",
   "dependencies": {
-    "@cloudflare/containers": "^0.0.28"
+    "@cloudflare/containers": "^0.0.29"
   },
   "devDependencies": {
     "@repo/shared": "^0.0.0"
@@ -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": {

package/src/request-handler.ts

@@ -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 });

package/src/sandbox.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

package/src/version.ts

@@ -3,4 +3,4 @@
  * 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
  */
-export const SDK_VERSION = '0.4.9';
+export const SDK_VERSION = '0.4.11';

package/tests/request-handler.test.ts

@@ -0,0 +1,240 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { proxyToSandbox, type SandboxEnv } from '../src/request-handler';
+import type { Sandbox } from '../src/sandbox';
+
+// Mock getSandbox from sandbox.ts
+vi.mock('../src/sandbox', () => {
+  const mockFn = vi.fn();
+  return {
+    getSandbox: mockFn,
+    Sandbox: vi.fn(),
+  };
+});
+
+// Import the mock after vi.mock is set up
+import { getSandbox } from '../src/sandbox';
+
+describe('proxyToSandbox - WebSocket Support', () => {
+  let mockSandbox: Partial<Sandbox>;
+  let mockEnv: SandboxEnv;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    // Mock Sandbox with necessary methods
+    mockSandbox = {
+      validatePortToken: vi.fn().mockResolvedValue(true),
+      fetch: vi.fn().mockResolvedValue(new Response('WebSocket response')),
+      containerFetch: vi.fn().mockResolvedValue(new Response('HTTP response')),
+    };
+
+    mockEnv = {
+      Sandbox: {} as any,
+    };
+
+    vi.mocked(getSandbox).mockReturnValue(mockSandbox as Sandbox);
+  });
+
+  describe('WebSocket detection and routing', () => {
+    it('should detect WebSocket upgrade header (case-insensitive)', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+        },
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      // Should route through fetch() for WebSocket
+      expect(mockSandbox.fetch).toHaveBeenCalledTimes(1);
+      expect(mockSandbox.containerFetch).not.toHaveBeenCalled();
+    });
+
+    it('should set cf-container-target-port header for WebSocket', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+        },
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      expect(mockSandbox.fetch).toHaveBeenCalledTimes(1);
+      const fetchCall = vi.mocked(mockSandbox.fetch as any).mock.calls[0][0] as Request;
+      expect(fetchCall.headers.get('cf-container-target-port')).toBe('8080');
+    });
+
+    it('should preserve original headers for WebSocket', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+          'Sec-WebSocket-Key': 'test-key-123',
+          'Sec-WebSocket-Version': '13',
+          'User-Agent': 'test-client',
+        },
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      const fetchCall = vi.mocked(mockSandbox.fetch as any).mock.calls[0][0] as Request;
+      expect(fetchCall.headers.get('Upgrade')).toBe('websocket');
+      expect(fetchCall.headers.get('Sec-WebSocket-Key')).toBe('test-key-123');
+      expect(fetchCall.headers.get('Sec-WebSocket-Version')).toBe('13');
+      expect(fetchCall.headers.get('User-Agent')).toBe('test-client');
+    });
+  });
+
+  describe('HTTP routing (existing behavior)', () => {
+    it('should route HTTP requests through containerFetch', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/api/data', {
+        method: 'GET',
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      // Should route through containerFetch() for HTTP
+      expect(mockSandbox.containerFetch).toHaveBeenCalledTimes(1);
+      expect(mockSandbox.fetch).not.toHaveBeenCalled();
+    });
+
+    it('should route POST requests through containerFetch', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/api/data', {
+        method: 'POST',
+        body: JSON.stringify({ data: 'test' }),
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      expect(mockSandbox.containerFetch).toHaveBeenCalledTimes(1);
+      expect(mockSandbox.fetch).not.toHaveBeenCalled();
+    });
+
+    it('should not detect SSE as WebSocket', async () => {
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/events', {
+        headers: {
+          'Accept': 'text/event-stream',
+        },
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      // SSE should use HTTP path, not WebSocket path
+      expect(mockSandbox.containerFetch).toHaveBeenCalledTimes(1);
+      expect(mockSandbox.fetch).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Token validation', () => {
+    it('should validate token for both WebSocket and HTTP requests', async () => {
+      const wsRequest = new Request('https://8080-sandbox-token12345678901.example.com/ws', {
+        headers: { 'Upgrade': 'websocket' },
+      });
+
+      await proxyToSandbox(wsRequest, mockEnv);
+      expect(mockSandbox.validatePortToken).toHaveBeenCalledWith(8080, 'token12345678901');
+
+      vi.clearAllMocks();
+
+      const httpRequest = new Request('https://8080-sandbox-token12345678901.example.com/api');
+      await proxyToSandbox(httpRequest, mockEnv);
+      expect(mockSandbox.validatePortToken).toHaveBeenCalledWith(8080, 'token12345678901');
+    });
+
+    it('should reject requests with invalid token', async () => {
+      vi.mocked(mockSandbox.validatePortToken as any).mockResolvedValue(false);
+
+      const request = new Request('https://8080-sandbox-invalidtoken1234.example.com/ws', {
+        headers: { 'Upgrade': 'websocket' },
+      });
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      expect(response?.status).toBe(404);
+      expect(mockSandbox.fetch).not.toHaveBeenCalled();
+
+      const body = await response?.json();
+      expect(body).toMatchObject({
+        error: 'Access denied: Invalid token or port not exposed',
+        code: 'INVALID_TOKEN',
+      });
+    });
+
+    it('should reject reserved port 3000', async () => {
+      // Port 3000 is reserved as control plane port and rejected by validatePort()
+      const request = new Request('https://3000-sandbox-anytoken12345678.example.com/status', {
+        method: 'GET',
+      });
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      // Port 3000 is reserved and should be rejected (extractSandboxRoute returns null)
+      expect(response).toBeNull();
+      expect(mockSandbox.validatePortToken).not.toHaveBeenCalled();
+      expect(mockSandbox.containerFetch).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Port routing', () => {
+    it('should route to correct port from subdomain', async () => {
+      const request = new Request('https://9000-sandbox-token12345678901.example.com/api', {
+        method: 'GET',
+      });
+
+      await proxyToSandbox(request, mockEnv);
+
+      expect(mockSandbox.validatePortToken).toHaveBeenCalledWith(9000, 'token12345678901');
+    });
+  });
+
+  describe('Non-sandbox requests', () => {
+    it('should return null for non-sandbox URLs', async () => {
+      const request = new Request('https://example.com/some-path');
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      expect(response).toBeNull();
+      expect(mockSandbox.fetch).not.toHaveBeenCalled();
+      expect(mockSandbox.containerFetch).not.toHaveBeenCalled();
+    });
+
+    it('should return null for invalid subdomain patterns', async () => {
+      const request = new Request('https://invalid-pattern.example.com');
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      expect(response).toBeNull();
+    });
+  });
+
+  describe('Error handling', () => {
+    it('should handle errors during WebSocket routing', async () => {
+      (mockSandbox.fetch as any).mockImplementation(() => Promise.reject(new Error('Connection failed')));
+
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+        },
+      });
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      expect(response?.status).toBe(500);
+      const text = await response?.text();
+      expect(text).toBe('Proxy routing error');
+    });
+
+    it('should handle errors during HTTP routing', async () => {
+      (mockSandbox.containerFetch as any).mockImplementation(() => Promise.reject(new Error('Service error')));
+
+      const request = new Request('https://8080-sandbox-token12345678901.example.com/api');
+
+      const response = await proxyToSandbox(request, mockEnv);
+
+      expect(response?.status).toBe(500);
+    });
+  });
+});

package/tests/sandbox.test.ts

@@ -1,23 +1,36 @@
 import type { DurableObjectState } from '@cloudflare/workers-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Sandbox } from '../src/sandbox';
+import { Container } from '@cloudflare/containers';
 
 // Mock dependencies before imports
 vi.mock('./interpreter', () => ({
   CodeInterpreter: vi.fn().mockImplementation(() => ({})),
 }));
 
-vi.mock('@cloudflare/containers', () => ({
-  Container: class Container {
+vi.mock('@cloudflare/containers', () => {
+  const MockContainer = class Container {
     ctx: any;
     env: any;
     constructor(ctx: any, env: any) {
       this.ctx = ctx;
       this.env = env;
     }
-  },
-  getContainer: vi.fn(),
-}));
+    async fetch(request: Request): Promise<Response> {
+      // Mock implementation - will be spied on in tests
+      return new Response('Mock Container fetch');
+    }
+    async containerFetch(request: Request, port: number): Promise<Response> {
+      // Mock implementation for HTTP path
+      return new Response('Mock Container HTTP fetch');
+    }
+  };
+
+  return {
+    Container: MockContainer,
+    getContainer: vi.fn(),
+  };
+});
 
 describe('Sandbox - Automatic Session Management', () => {
   let sandbox: Sandbox;
@@ -462,4 +475,80 @@ describe('Sandbox - Automatic Session Management', () => {
       expect(sandbox.client.ports.exposePort).toHaveBeenCalled();
     });
   });
+
+  describe('fetch() override - WebSocket detection', () => {
+    let superFetchSpy: any;
+
+    beforeEach(async () => {
+      await sandbox.setSandboxName('test-sandbox');
+
+      // Spy on Container.prototype.fetch to verify WebSocket routing
+      superFetchSpy = vi.spyOn(Container.prototype, 'fetch')
+        .mockResolvedValue(new Response('WebSocket response'));
+    });
+
+    afterEach(() => {
+      superFetchSpy?.mockRestore();
+    });
+
+    it('should detect WebSocket upgrade header and route to super.fetch', async () => {
+      const request = new Request('https://example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+          'Connection': 'Upgrade',
+        },
+      });
+
+      const response = await sandbox.fetch(request);
+
+      // Should route through super.fetch() for WebSocket
+      expect(superFetchSpy).toHaveBeenCalledTimes(1);
+      expect(await response.text()).toBe('WebSocket response');
+    });
+
+    it('should route non-WebSocket requests through containerFetch', async () => {
+      // GET request
+      const getRequest = new Request('https://example.com/api/data');
+      await sandbox.fetch(getRequest);
+      expect(superFetchSpy).not.toHaveBeenCalled();
+
+      vi.clearAllMocks();
+
+      // POST request
+      const postRequest = new Request('https://example.com/api/data', {
+        method: 'POST',
+        body: JSON.stringify({ data: 'test' }),
+        headers: { 'Content-Type': 'application/json' },
+      });
+      await sandbox.fetch(postRequest);
+      expect(superFetchSpy).not.toHaveBeenCalled();
+
+      vi.clearAllMocks();
+
+      // SSE request (should not be detected as WebSocket)
+      const sseRequest = new Request('https://example.com/events', {
+        headers: { 'Accept': 'text/event-stream' },
+      });
+      await sandbox.fetch(sseRequest);
+      expect(superFetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('should preserve WebSocket request unchanged when calling super.fetch()', async () => {
+      const request = new Request('https://example.com/ws', {
+        headers: {
+          'Upgrade': 'websocket',
+          'Sec-WebSocket-Key': 'test-key-123',
+          'Sec-WebSocket-Version': '13',
+        },
+      });
+
+      await sandbox.fetch(request);
+
+      expect(superFetchSpy).toHaveBeenCalledTimes(1);
+      const passedRequest = superFetchSpy.mock.calls[0][0] as Request;
+      expect(passedRequest.headers.get('Upgrade')).toBe('websocket');
+      expect(passedRequest.headers.get('Sec-WebSocket-Key')).toBe('test-key-123');
+      expect(passedRequest.headers.get('Sec-WebSocket-Version')).toBe('13');
+    });
+  });
 });