@cloudflare/sandbox 0.4.11 → 0.4.12

package/dist/{sandbox-DWQVgVTY.d.ts → sandbox-CLZWpfGc.d.ts}

@@ -458,10 +458,12 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     private defaultSession;
     envVars: Record<string, string>;
     private logger;
+    private keepAliveEnabled;
     constructor(ctx: DurableObject['ctx'], env: Env);
     setSandboxName(name: string): Promise<void>;
     setBaseUrl(baseUrl: string): Promise<void>;
     setSleepAfter(sleepAfter: string | number): Promise<void>;
+    setKeepAlive(keepAlive: boolean): Promise<void>;
     setEnvVars(envVars: Record<string, string>): Promise<void>;
     /**
      * Cleanup and destroy the sandbox container
@@ -475,6 +477,11 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
     private checkVersionCompatibility;
     onStop(): void;
     onError(error: unknown): void;
+    /**
+     * Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
+     * When keepAlive is disabled, calls parent implementation which stops the container
+     */
+    onActivityExpired(): Promise<void>;
     fetch(request: Request): Promise<Response>;
     private determinePort;
     /**
@@ -516,6 +523,9 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
      * Internal session-aware execStream implementation
      */
     private execStreamWithSession;
+    /**
+     * Stream logs from a background process as a ReadableStream.
+     */
     streamProcessLogs(processId: string, options?: {
         signal?: AbortSignal;
     }): Promise<ReadableStream<Uint8Array>>;

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-DWQVgVTY.js';
+export { b as Sandbox, g as getSandbox } from './sandbox-CLZWpfGc.js';

package/dist/sandbox.js

@@ -1,11 +1,11 @@
 import {
   Sandbox,
   getSandbox
-} from "./chunk-SVWLTRHD.js";
+} from "./chunk-YE265ASX.js";
 import "./chunk-JXZMAU2C.js";
 import "./chunk-Z532A7QC.js";
 import "./chunk-EKSWCBCA.js";
-import "./chunk-FE4PJSRB.js";
+import "./chunk-UJ3TV4M6.js";
 export {
   Sandbox,
   getSandbox

package/dist/version.d.ts

@@ -3,6 +3,6 @@
  * 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.11";
+declare const SDK_VERSION = "0.4.12";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,6 +1,6 @@
 import {
   SDK_VERSION
-} from "./chunk-FE4PJSRB.js";
+} from "./chunk-UJ3TV4M6.js";
 export {
   SDK_VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/sandbox",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/sandbox-sdk"

package/src/request-handler.ts

@@ -1,5 +1,5 @@
-import { createLogger, type LogContext, TraceContext } from "@repo/shared";
 import { switchPort } from "@cloudflare/containers";
+import { createLogger, type LogContext, TraceContext } from "@repo/shared";
 import { getSandbox, type Sandbox } from "./sandbox";
 import {
   sanitizeSandboxId,

package/src/sandbox.ts

@@ -49,6 +49,10 @@ export function getSandbox(
     stub.setSleepAfter(options.sleepAfter);
   }
 
+  if (options?.keepAlive !== undefined) {
+    stub.setKeepAlive(options.keepAlive);
+  }
+
   return stub;
 }
 
@@ -64,6 +68,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
   private defaultSession: string | null = null;
   envVars: Record<string, string> = {};
   private logger: ReturnType<typeof createLogger>;
+  private keepAliveEnabled: boolean = false;
 
   constructor(ctx: DurableObject['ctx'], env: Env) {
     super(ctx, env);
@@ -131,6 +136,16 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     this.sleepAfter = sleepAfter;
   }
 
+  // RPC method to enable keepAlive mode
+  async setKeepAlive(keepAlive: boolean): Promise<void> {
+    this.keepAliveEnabled = keepAlive;
+    if (keepAlive) {
+      this.logger.info('KeepAlive mode enabled - container will stay alive until explicitly destroyed');
+    } else {
+      this.logger.info('KeepAlive mode disabled - container will timeout normally');
+    }
+  }
+
   // RPC method to set environment variables
   async setEnvVars(envVars: Record<string, string>): Promise<void> {
     // Update local state for new sessions
@@ -220,6 +235,22 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     this.logger.error('Sandbox error', error instanceof Error ? error : new Error(String(error)));
   }
 
+  /**
+   * Override onActivityExpired to prevent automatic shutdown when keepAlive is enabled
+   * When keepAlive is disabled, calls parent implementation which stops the container
+   */
+  override async onActivityExpired(): Promise<void> {
+    if (this.keepAliveEnabled) {
+      this.logger.debug('Activity expired but keepAlive is enabled - container will stay alive');
+      // Do nothing - don't call stop(), container stays alive
+    } else {
+      // Default behavior: stop the container
+      this.logger.debug('Activity expired - stopping container');
+      await super.onActivityExpired();
+    }
+  }
+
+
   // Override fetch to route internal container requests to appropriate ports
   override async fetch(request: Request): Promise<Response> {
     // Extract or generate trace ID from request
@@ -327,7 +358,6 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     const startTime = Date.now();
     const timestamp = new Date().toISOString();
 
-    // Handle timeout
     let timeoutId: NodeJS.Timeout | undefined;
 
     try {
@@ -592,8 +622,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     };
   }
 
-
-  // Streaming methods - return ReadableStream for RPC compatibility
+// Streaming methods - return ReadableStream for RPC compatibility
   async execStream(command: string, options?: StreamOptions): Promise<ReadableStream<Uint8Array>> {
     // Check for cancellation
     if (options?.signal?.aborted) {
@@ -617,6 +646,9 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
     return this.client.commands.executeStream(command, sessionId);
   }
 
+  /**
+   * Stream logs from a background process as a ReadableStream.
+   */
   async streamProcessLogs(processId: string, options?: { signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>> {
     // Check for cancellation
     if (options?.signal?.aborted) {

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.11';
+export const SDK_VERSION = '0.4.12';

package/tests/get-sandbox.test.ts

@@ -30,6 +30,7 @@ describe('getSandbox', () => {
       setSleepAfter: vi.fn((value: string | number) => {
         mockStub.sleepAfter = value;
       }),
+      setKeepAlive: vi.fn(),
     };
 
     // Mock getContainer to return our stub
@@ -107,4 +108,42 @@ describe('getSandbox', () => {
       expect(sandbox.sleepAfter).toBe(timeString);
     }
   });
+
+  it('should apply keepAlive option when provided as true', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      keepAlive: true,
+    });
+
+    expect(sandbox.setKeepAlive).toHaveBeenCalledWith(true);
+  });
+
+  it('should apply keepAlive option when provided as false', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      keepAlive: false,
+    });
+
+    expect(sandbox.setKeepAlive).toHaveBeenCalledWith(false);
+  });
+
+  it('should not call setKeepAlive when keepAlive option not provided', () => {
+    const mockNamespace = {} as any;
+    getSandbox(mockNamespace, 'test-sandbox');
+
+    expect(mockStub.setKeepAlive).not.toHaveBeenCalled();
+  });
+
+  it('should apply keepAlive alongside other options', () => {
+    const mockNamespace = {} as any;
+    const sandbox = getSandbox(mockNamespace, 'test-sandbox', {
+      sleepAfter: '5m',
+      baseUrl: 'https://example.com',
+      keepAlive: true,
+    });
+
+    expect(sandbox.sleepAfter).toBe('5m');
+    expect(sandbox.setBaseUrl).toHaveBeenCalledWith('https://example.com');
+    expect(sandbox.setKeepAlive).toHaveBeenCalledWith(true);
+  });
 });

package/tests/sandbox.test.ts

@@ -1,7 +1,7 @@
+import { Container } from '@cloudflare/containers';
 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', () => ({
@@ -48,7 +48,7 @@ describe('Sandbox - Automatic Session Management', () => {
         delete: vi.fn().mockResolvedValue(undefined),
         list: vi.fn().mockResolvedValue(new Map()),
       } as any,
-      blockConcurrencyWhile: vi.fn((fn: () => Promise<void>) => fn()),
+      blockConcurrencyWhile: vi.fn().mockImplementation(<T>(callback: () => Promise<T>): Promise<T> => callback()),
       id: {
         toString: () => 'test-sandbox-id',
         equals: vi.fn(),

package/dist/chunk-FE4PJSRB.js

@@ -1,7 +0,0 @@
-// src/version.ts
-var SDK_VERSION = "0.4.11";
-
-export {
-  SDK_VERSION
-};
-//# sourceMappingURL=chunk-FE4PJSRB.js.map