@cloudflare/sandbox 0.0.0-104f455 → 0.0.0-153e416

package/src/clients/file-client.ts

@@ -1,5 +1,6 @@
 import type {
   DeleteFileResult,
+  FileExistsResult,
   ListFilesOptions,
   ListFilesResult,
   MkdirResult,
@@ -266,4 +267,29 @@ export class FileClient extends BaseHttpClient {
       throw error;
     }
   }
+
+  /**
+   * Check if a file or directory exists
+   * @param path - Path to check
+   * @param sessionId - The session ID for this operation
+   */
+  async exists(
+    path: string,
+    sessionId: string
+  ): Promise<FileExistsResult> {
+    try {
+      const data = {
+        path,
+        sessionId,
+      };
+
+      const response = await this.post<FileExistsResult>('/api/exists', data);
+
+      this.logSuccess('Path existence checked', `${path} (exists: ${response.exists})`);
+      return response;
+    } catch (error) {
+      this.logError('exists', error);
+      throw error;
+    }
+  }
 }

package/src/clients/index.ts

@@ -59,5 +59,6 @@ export type {
 export type {
   CommandsResponse,
   PingResponse,
+  VersionResponse,
 } from './utility-client';
 export { UtilityClient } from './utility-client';

package/src/clients/utility-client.ts

@@ -17,6 +17,13 @@ export interface CommandsResponse extends BaseApiResponse {
   count: number;
 }
 
+/**
+ * Response interface for getting container version
+ */
+export interface VersionResponse extends BaseApiResponse {
+  version: string;
+}
+
 /**
  * Request interface for creating sessions
  */
@@ -91,4 +98,22 @@ export class UtilityClient extends BaseHttpClient {
       throw error;
     }
   }
+
+  /**
+   * Get the container version
+   * Returns the version embedded in the Docker image during build
+   */
+  async getVersion(): Promise<string> {
+    try {
+      const response = await this.get<VersionResponse>('/api/version');
+
+      this.logSuccess('Version retrieved', response.version);
+      return response.version;
+    } catch (error) {
+      // If version endpoint doesn't exist (old container), return 'unknown'
+      // This allows for backward compatibility
+      this.logger.debug('Failed to get container version (may be old container)', { error });
+      return 'unknown';
+    }
+  }
 }

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 });
@@ -105,7 +114,8 @@ export async function proxyToSandbox<E extends SandboxEnv>(
 
 function extractSandboxRoute(url: URL): RouteInfo | null {
   // Parse subdomain pattern: port-sandboxId-token.domain (tokens mandatory)
-  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*[^.-]|[^.-])-([a-zA-Z0-9_-]{12,20})\.(.+)$/);
+  // Token is always exactly 16 chars (generated by generatePortToken)
+  const subdomainMatch = url.hostname.match(/^(\d{4,5})-([^.-][^.]*?[^.-]|[^.-])-([a-z0-9_-]{16})\.(.+)$/);
 
   if (!subdomainMatch) {
     return null;

package/src/sandbox.ts

@@ -13,6 +13,7 @@ import type {
   ProcessOptions,
   ProcessStatus,
   RunCodeOptions,
+  SandboxOptions,
   SessionOptions,
   StreamOptions
 } from "@repo/shared";
@@ -28,25 +29,32 @@ import {
   validatePort
 } from "./security";
 import { parseSSEStream } from "./sse-parser";
+import { SDK_VERSION } from "./version";
 
-export function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string, options?: {
-  baseUrl: string
-}) {
+export function getSandbox(
+  ns: DurableObjectNamespace<Sandbox>,
+  id: string,
+  options?: SandboxOptions
+) {
   const stub = getContainer(ns, id);
 
   // Store the name on first access
   stub.setSandboxName?.(id);
 
-  if(options?.baseUrl) {
+  if (options?.baseUrl) {
     stub.setBaseUrl(options.baseUrl);
   }
 
+  if (options?.sleepAfter !== undefined) {
+    stub.setSleepAfter(options.sleepAfter);
+  }
+
   return stub;
 }
 
 export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   defaultPort = 3000; // Default port for the container's Bun server
-  sleepAfter = "3m"; // Sleep the sandbox if no requests are made in this timeframe
+  sleepAfter: string | number = "10m"; // Sleep the sandbox if no requests are made in this timeframe
 
   client: SandboxClient;
   private codeInterpreter: CodeInterpreter;
@@ -118,6 +126,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     }
   }
 
+  // RPC method to set the sleep timeout
+  async setSleepAfter(sleepAfter: string | number): Promise<void> {
+    this.sleepAfter = sleepAfter;
+  }
+
   // RPC method to set environment variables
   async setEnvVars(envVars: Record<string, string>): Promise<void> {
     // Update local state for new sessions
@@ -149,6 +162,54 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
 
   override onStart() {
     this.logger.debug('Sandbox started');
+
+    // Check version compatibility asynchronously (don't block startup)
+    this.checkVersionCompatibility().catch(error => {
+      this.logger.error('Version compatibility check failed', error instanceof Error ? error : new Error(String(error)));
+    });
+  }
+
+  /**
+   * Check if the container version matches the SDK version
+   * Logs a warning if there's a mismatch
+   */
+  private async checkVersionCompatibility(): Promise<void> {
+    try {
+      // Get the SDK version (imported from version.ts)
+      const sdkVersion = SDK_VERSION;
+
+      // Get container version
+      const containerVersion = await this.client.utils.getVersion();
+
+      // If container version is unknown, it's likely an old container without the endpoint
+      if (containerVersion === 'unknown') {
+        this.logger.warn(
+          'Container version check: Container version could not be determined. ' +
+          'This may indicate an outdated container image. ' +
+          'Please update your container to match SDK version ' + sdkVersion
+        );
+        return;
+      }
+
+      // Check if versions match
+      if (containerVersion !== sdkVersion) {
+        const message =
+          `Version mismatch detected! SDK version (${sdkVersion}) does not match ` +
+          `container version (${containerVersion}). This may cause compatibility issues. ` +
+          `Please update your container image to version ${sdkVersion}`;
+
+        // Log warning - we can't reliably detect dev vs prod environment in Durable Objects
+        // so we always use warning level as requested by the user
+        this.logger.warn(message);
+      } else {
+        this.logger.debug('Version check passed', { sdkVersion, containerVersion });
+      }
+    } catch (error) {
+      // Don't fail the sandbox initialization if version check fails
+      this.logger.debug('Version compatibility check encountered an error', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
   }
 
   override onStop() {
@@ -177,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
@@ -223,7 +294,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
         this.logger.debug('Default session initialized', { sessionId });
       } catch (error: any) {
         // If session already exists (e.g., after hot reload), reuse it
-        if (error?.message?.includes('already exists') || error?.message?.includes('Session')) {
+        if (error?.message?.includes('already exists')) {
           this.logger.debug('Reusing existing session after reload', { sessionId });
           this.defaultSession = sessionId;
           // Persist to storage in case it wasn't saved before
@@ -636,6 +707,11 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     return this.client.files.listFiles(path, session, options);
   }
 
+  async exists(path: string, sessionId?: string) {
+    const session = sessionId ?? await this.ensureDefaultSession();
+    return this.client.files.exists(path, session);
+  }
+
   async exposePort(port: number, options: { name?: string; hostname: string }) {
     // Check if hostname is workers.dev domain (doesn't support wildcard subdomains)
     if (options.hostname.endsWith('.workers.dev')) {
@@ -873,6 +949,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       renameFile: (oldPath, newPath) => this.renameFile(oldPath, newPath, sessionId),
       moveFile: (sourcePath, destPath) => this.moveFile(sourcePath, destPath, sessionId),
       listFiles: (path, options) => this.client.files.listFiles(path, sessionId, options),
+      exists: (path) => this.exists(path, sessionId),
 
       // Git operations
       gitCheckout: (repoUrl, options) => this.gitCheckout(repoUrl, { ...options, sessionId }),

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * SDK version - automatically synchronized with package.json by Changesets
+ * 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.11';

package/tests/file-client.test.ts

@@ -1,5 +1,6 @@
 import type {
   DeleteFileResult,
+  FileExistsResult,
   ListFilesResult,
   MkdirResult,
   MoveFileResult,
@@ -584,6 +585,81 @@ database:
     });
   });
 
+  describe('exists', () => {
+    it('should return true when file exists', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/test.txt',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/test.txt', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(true);
+      expect(result.path).toBe('/workspace/test.txt');
+    });
+
+    it('should return false when file does not exist', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/nonexistent.txt',
+        exists: false,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/nonexistent.txt', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(false);
+    });
+
+    it('should return true when directory exists', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/workspace/some-dir',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      const result = await client.exists('/workspace/some-dir', 'session-exists');
+
+      expect(result.success).toBe(true);
+      expect(result.exists).toBe(true);
+    });
+
+    it('should send correct request payload', async () => {
+      const mockResponse: FileExistsResult = {
+        success: true,
+        path: '/test/path',
+        exists: true,
+        timestamp: '2023-01-01T00:00:00Z',
+      };
+
+      mockFetch.mockResolvedValue(new Response(JSON.stringify(mockResponse), { status: 200 }));
+
+      await client.exists('/test/path', 'session-test');
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('/api/exists'),
+        expect.objectContaining({
+          method: 'POST',
+          body: JSON.stringify({
+            path: '/test/path',
+            sessionId: 'session-test',
+          })
+        })
+      );
+    });
+  });
+
   describe('error handling', () => {
     it('should handle network failures gracefully', async () => {
       mockFetch.mockRejectedValue(new Error('Network connection failed'));

package/tests/get-sandbox.test.ts

@@ -0,0 +1,110 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { getSandbox } from '../src/sandbox';
+
+// Mock the Container module
+vi.mock('@cloudflare/containers', () => ({
+  Container: class Container {
+    ctx: any;
+    env: any;
+    sleepAfter: string | number = '10m';
+    constructor(ctx: any, env: any) {
+      this.ctx = ctx;
+      this.env = env;
+    }
+  },
+  getContainer: vi.fn(),
+}));
+
+describe('getSandbox', () => {
+  let mockStub: any;
+  let mockGetContainer: any;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    // Create a fresh mock stub for each test
+    mockStub = {
+      sleepAfter: '10m',
+      setSandboxName: vi.fn(),
+      setBaseUrl: vi.fn(),
+      setSleepAfter: vi.fn((value: string | number) => {
+        mockStub.sleepAfter = value;
+      }),
+    };
+
+    // Mock getContainer to return our stub
+    const containers = await import('@cloudflare/containers');
+    mockGetContainer = vi.mocked(containers.getContainer);
+    mockGetContainer.mockReturnValue(mockStub);
+  });
+
+  it('should create a sandbox instance with default sleepAfter', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox');
+
+    expect(sandbox).toBeDefined();
+    expect(sandbox.setSandboxName).toHaveBeenCalledWith('test-sandbox');
+  });
+
+  it('should apply sleepAfter option when provided as string', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      sleepAfter: '5m',
+    });
+
+    expect(sandbox.sleepAfter).toBe('5m');
+  });
+
+  it('should apply sleepAfter option when provided as number', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      sleepAfter: 300, // 5 minutes in seconds
+    });
+
+    expect(sandbox.sleepAfter).toBe(300);
+  });
+
+  it('should apply baseUrl option when provided', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      baseUrl: 'https://example.com',
+    });
+
+    expect(sandbox.setBaseUrl).toHaveBeenCalledWith('https://example.com');
+  });
+
+  it('should apply both sleepAfter and baseUrl options together', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      sleepAfter: '10m',
+      baseUrl: 'https://example.com',
+    });
+
+    expect(sandbox.sleepAfter).toBe('10m');
+    expect(sandbox.setBaseUrl).toHaveBeenCalledWith('https://example.com');
+  });
+
+  it('should not apply sleepAfter when not provided', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox');
+
+    // Should remain default value from Container
+    expect(sandbox.sleepAfter).toBe('10m');
+  });
+
+  it('should accept various time string formats for sleepAfter', () => {
+    const mockNamespace = {} as any;
+    const testCases = ['30s', '1m', '10m', '1h', '2h'];
+
+    for (const timeString of testCases) {
+      // Reset the mock stub for each iteration
+      mockStub.sleepAfter = '3m';
+
+      const sandbox = getSandbox(mockNamespace, `test-sandbox-${timeString}`, {
+        sleepAfter: timeString,
+      });
+
+      expect(sandbox.sleepAfter).toBe(timeString);
+    }
+  });
+});