@cloudflare/sandbox 0.4.4 → 0.4.6

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   UtilityClient,
   getSandbox,
   proxyToSandbox
-} from "./chunk-2P3MDMNJ.js";
+} from "./chunk-YEZBBFK7.js";
 import {
   CodeInterpreter,
   Execution,
@@ -34,6 +34,7 @@ import {
   parseSSEStream,
   responseToAsyncIterable
 } from "./chunk-EKSWCBCA.js";
+import "./chunk-UZQBJBJF.js";
 export {
   CodeInterpreter,
   CommandClient,

package/dist/interpreter.d.ts

@@ -1,5 +1,5 @@
 import { CreateContextOptions, CodeContext, RunCodeOptions, Execution } from '@repo/shared';
-import { b as Sandbox } from './sandbox-CZTMzV2R.js';
+import { b as Sandbox } from './sandbox-DMlNr93l.js';
 import 'cloudflare:workers';
 import '@cloudflare/containers';
 

package/dist/request-handler.d.ts

@@ -1,4 +1,4 @@
-import { b as Sandbox } from './sandbox-CZTMzV2R.js';
+import { b as Sandbox } from './sandbox-DMlNr93l.js';
 import '@repo/shared';
 import 'cloudflare:workers';
 import '@cloudflare/containers';

package/dist/request-handler.js

@@ -1,10 +1,11 @@
 import {
   isLocalhostPattern,
   proxyToSandbox
-} from "./chunk-2P3MDMNJ.js";
+} from "./chunk-YEZBBFK7.js";
 import "./chunk-JXZMAU2C.js";
 import "./chunk-Z532A7QC.js";
 import "./chunk-EKSWCBCA.js";
+import "./chunk-UZQBJBJF.js";
 export {
   isLocalhostPattern,
   proxyToSandbox

package/dist/{sandbox-CZTMzV2R.d.ts → sandbox-DMlNr93l.d.ts}

@@ -1,5 +1,5 @@
 import * as _repo_shared from '@repo/shared';
-import { Logger, MkdirResult, WriteFileResult, ReadFileResult, DeleteFileResult, RenameFileResult, MoveFileResult, ListFilesOptions, ListFilesResult, GitCheckoutResult, CreateContextOptions, CodeContext, OutputMessage, Result, ExecutionError, PortExposeResult, PortCloseResult, PortListResult, ProcessStartResult, ProcessListResult, ProcessInfoResult, ProcessKillResult, ProcessCleanupResult, ProcessLogsResult, ISandbox, ExecOptions, ExecResult, ProcessOptions, Process, StreamOptions, SessionOptions, ExecutionSession, RunCodeOptions, ExecutionResult } from '@repo/shared';
+import { Logger, MkdirResult, WriteFileResult, ReadFileResult, DeleteFileResult, RenameFileResult, MoveFileResult, ListFilesOptions, ListFilesResult, GitCheckoutResult, CreateContextOptions, CodeContext, OutputMessage, Result, ExecutionError, PortExposeResult, PortCloseResult, PortListResult, ProcessStartResult, ProcessListResult, ProcessInfoResult, ProcessKillResult, ProcessCleanupResult, ProcessLogsResult, ISandbox, ExecOptions, ExecResult, ProcessOptions, Process, StreamOptions, SessionOptions, ExecutionSession, RunCodeOptions, ExecutionResult, SandboxOptions } from '@repo/shared';
 import { DurableObject } from 'cloudflare:workers';
 import { Container } from '@cloudflare/containers';
 
@@ -418,6 +418,11 @@ declare class UtilityClient extends BaseHttpClient {
      * @param options - Session configuration (id, env, cwd)
      */
     createSession(options: CreateSessionRequest): Promise<CreateSessionResponse>;
+    /**
+     * Get the container version
+     * Returns the version embedded in the Docker image during build
+     */
+    getVersion(): Promise<string>;
 }
 
 /**
@@ -435,12 +440,10 @@ declare class SandboxClient {
     constructor(options: HttpClientOptions);
 }
 
-declare function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string, options?: {
-    baseUrl: string;
-}): DurableObjectStub<Sandbox<unknown>>;
+declare function getSandbox(ns: DurableObjectNamespace<Sandbox>, id: string, options?: SandboxOptions): DurableObjectStub<Sandbox<unknown>>;
 declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     defaultPort: number;
-    sleepAfter: string;
+    sleepAfter: string | number;
     client: SandboxClient;
     private codeInterpreter;
     private sandboxName;
@@ -452,12 +455,18 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     constructor(ctx: DurableObject['ctx'], env: Env);
     setSandboxName(name: string): Promise<void>;
     setBaseUrl(baseUrl: string): Promise<void>;
+    setSleepAfter(sleepAfter: string | number): Promise<void>;
     setEnvVars(envVars: Record<string, string>): Promise<void>;
     /**
      * Cleanup and destroy the sandbox container
      */
     destroy(): Promise<void>;
     onStart(): void;
+    /**
+     * Check if the container version matches the SDK version
+     * Logs a warning if there's a mismatch
+     */
+    private checkVersionCompatibility;
     onStop(): void;
     onError(error: unknown): void;
     fetch(request: Request): Promise<Response>;

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
 import '@repo/shared';
 import 'cloudflare:workers';
 import '@cloudflare/containers';
-export { b as Sandbox, g as getSandbox } from './sandbox-CZTMzV2R.js';
+export { b as Sandbox, g as getSandbox } from './sandbox-DMlNr93l.js';

package/dist/sandbox.js

@@ -1,10 +1,11 @@
 import {
   Sandbox,
   getSandbox
-} from "./chunk-2P3MDMNJ.js";
+} from "./chunk-YEZBBFK7.js";
 import "./chunk-JXZMAU2C.js";
 import "./chunk-Z532A7QC.js";
 import "./chunk-EKSWCBCA.js";
+import "./chunk-UZQBJBJF.js";
 export {
   Sandbox,
   getSandbox

package/dist/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+declare const SDK_VERSION = "0.4.6";
+
+export { SDK_VERSION };

package/dist/version.js

@@ -0,0 +1,7 @@
+import {
+  SDK_VERSION
+} from "./chunk-UZQBJBJF.js";
+export {
+  SDK_VERSION
+};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/sandbox-sdk"
@@ -24,9 +24,9 @@
     "check": "biome check && npm run typecheck",
     "fix": "biome check --fix && npm run typecheck",
     "typecheck": "tsc --noEmit",
-    "docker:local": "cd ../.. && docker build -f packages/sandbox/Dockerfile -t cloudflare/sandbox-test:$npm_package_version .",
-    "docker:publish": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile -t cloudflare/sandbox:$npm_package_version --push .",
-    "docker:publish:beta": "cd ../.. && docker buildx build --platform linux/amd64,linux/arm64 -f packages/sandbox/Dockerfile -t cloudflare/sandbox:$npm_package_version-beta --push .",
+    "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:e2e": "cd ../.. && vitest run --config vitest.e2e.config.ts \"$@\""
   },

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/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() {

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.6';

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

package/tests/utility-client.test.ts

@@ -1,7 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type {
   CommandsResponse,
-  PingResponse
+  PingResponse,
+  VersionResponse
 } from '../src/clients';
 import { UtilityClient } from '../src/clients/utility-client';
 import {
@@ -25,6 +26,13 @@ const mockCommandsResponse = (commands: string[], overrides: Partial<CommandsRes
   ...overrides
 });
 
+const mockVersionResponse = (version: string = '0.4.5', overrides: Partial<VersionResponse> = {}): VersionResponse => ({
+  success: true,
+  version,
+  timestamp: '2023-01-01T00:00:00Z',
+  ...overrides
+});
+
 describe('UtilityClient', () => {
   let client: UtilityClient;
   let mockFetch: ReturnType<typeof vi.fn>;
@@ -249,6 +257,64 @@ describe('UtilityClient', () => {
     });
   });
 
+  describe('version checking', () => {
+    it('should get container version successfully', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify(mockVersionResponse('0.4.5')),
+        { status: 200 }
+      ));
+
+      const result = await client.getVersion();
+
+      expect(result).toBe('0.4.5');
+    });
+
+    it('should handle different version formats', async () => {
+      const versions = ['1.0.0', '2.5.3-beta', '0.0.1', '10.20.30'];
+
+      for (const version of versions) {
+        mockFetch.mockResolvedValueOnce(new Response(
+          JSON.stringify(mockVersionResponse(version)),
+          { status: 200 }
+        ));
+
+        const result = await client.getVersion();
+        expect(result).toBe(version);
+      }
+    });
+
+    it('should return "unknown" when version endpoint does not exist (backward compatibility)', async () => {
+      // Simulate 404 or other error for old containers
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify({ error: 'Not Found' }),
+        { status: 404 }
+      ));
+
+      const result = await client.getVersion();
+
+      expect(result).toBe('unknown');
+    });
+
+    it('should return "unknown" on network failure (backward compatibility)', async () => {
+      mockFetch.mockRejectedValue(new Error('Network connection failed'));
+
+      const result = await client.getVersion();
+
+      expect(result).toBe('unknown');
+    });
+
+    it('should handle version response with unknown value', async () => {
+      mockFetch.mockResolvedValue(new Response(
+        JSON.stringify(mockVersionResponse('unknown')),
+        { status: 200 }
+      ));
+
+      const result = await client.getVersion();
+
+      expect(result).toBe('unknown');
+    });
+  });
+
   describe('constructor options', () => {
     it('should initialize with minimal options', () => {
       const minimalClient = new UtilityClient();

package/tests/version.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from 'vitest';
+import packageJson from '../package.json';
+import { SDK_VERSION } from '../src/version';
+
+describe('Version Sync', () => {
+  test('SDK_VERSION matches package.json version', () => {
+    // Verify versions match
+    expect(SDK_VERSION).toBe(packageJson.version);
+  });
+
+  test('SDK_VERSION is a valid semver version', () => {
+    // Check if version matches semver pattern (major.minor.patch)
+    const semverPattern = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+    expect(SDK_VERSION).toMatch(semverPattern);
+  });
+});