@cloudflare/sandbox 0.4.17 → 0.5.1

package/src/storage-mount/credential-detection.ts

@@ -0,0 +1,41 @@
+import type { BucketCredentials, MountBucketOptions } from '@repo/shared';
+import { MissingCredentialsError } from './errors';
+
+/**
+ * Detect credentials for bucket mounting from environment variables
+ * Priority order:
+ * 1. Explicit options.credentials
+ * 2. Standard AWS env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
+ * 3. Error: no credentials found
+ *
+ * @param options - Mount options
+ * @param envVars - Environment variables
+ * @returns Detected credentials
+ * @throws MissingCredentialsError if no credentials found
+ */
+export function detectCredentials(
+  options: MountBucketOptions,
+  envVars: Record<string, string | undefined>
+): BucketCredentials {
+  // Priority 1: Explicit credentials in options
+  if (options.credentials) {
+    return options.credentials;
+  }
+
+  // Priority 2: Standard AWS env vars
+  const awsAccessKeyId = envVars.AWS_ACCESS_KEY_ID;
+  const awsSecretAccessKey = envVars.AWS_SECRET_ACCESS_KEY;
+
+  if (awsAccessKeyId && awsSecretAccessKey) {
+    return {
+      accessKeyId: awsAccessKeyId,
+      secretAccessKey: awsSecretAccessKey
+    };
+  }
+
+  // No credentials found - throw error with helpful message
+  throw new MissingCredentialsError(
+    `No credentials found. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY ` +
+      `environment variables, or pass explicit credentials in options.`
+  );
+}

package/src/storage-mount/errors.ts

@@ -0,0 +1,51 @@
+/**
+ * Bucket mounting error classes
+ *
+ * These are SDK-side validation errors that follow the same pattern as SecurityError.
+ * They are thrown before any container interaction occurs.
+ */
+
+import { ErrorCode } from '@repo/shared/errors';
+
+/**
+ * Base error for bucket mounting operations
+ */
+export class BucketMountError extends Error {
+  public readonly code: ErrorCode;
+
+  constructor(message: string, code: ErrorCode = ErrorCode.BUCKET_MOUNT_ERROR) {
+    super(message);
+    this.name = 'BucketMountError';
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown when S3FS mount command fails
+ */
+export class S3FSMountError extends BucketMountError {
+  constructor(message: string) {
+    super(message, ErrorCode.S3FS_MOUNT_ERROR);
+    this.name = 'S3FSMountError';
+  }
+}
+
+/**
+ * Thrown when no credentials found in environment
+ */
+export class MissingCredentialsError extends BucketMountError {
+  constructor(message: string) {
+    super(message, ErrorCode.MISSING_CREDENTIALS);
+    this.name = 'MissingCredentialsError';
+  }
+}
+
+/**
+ * Thrown when bucket name, mount path, or options are invalid
+ */
+export class InvalidMountConfigError extends BucketMountError {
+  constructor(message: string) {
+    super(message, ErrorCode.INVALID_MOUNT_CONFIG);
+    this.name = 'InvalidMountConfigError';
+  }
+}

package/src/storage-mount/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Bucket mounting functionality
+ */
+
+export { detectCredentials } from './credential-detection';
+export {
+  BucketMountError,
+  InvalidMountConfigError,
+  MissingCredentialsError,
+  S3FSMountError
+} from './errors';
+export {
+  detectProviderFromUrl,
+  getProviderFlags,
+  resolveS3fsOptions
+} from './provider-detection';
+export type { MountInfo } from './types';

package/src/storage-mount/provider-detection.ts

@@ -0,0 +1,93 @@
+/**
+ * Provider detection and s3fs flag configuration
+ *
+ * Based on s3fs-fuse documentation:
+ * https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3
+ */
+
+import type { BucketProvider } from '@repo/shared';
+
+/**
+ * Detect provider from endpoint URL using pattern matching
+ */
+export function detectProviderFromUrl(endpoint: string): BucketProvider | null {
+  try {
+    const url = new URL(endpoint);
+    const hostname = url.hostname.toLowerCase();
+
+    if (hostname.endsWith('.r2.cloudflarestorage.com')) {
+      return 'r2';
+    }
+
+    // Match AWS S3: *.amazonaws.com or s3.amazonaws.com
+    if (
+      hostname.endsWith('.amazonaws.com') ||
+      hostname === 's3.amazonaws.com'
+    ) {
+      return 's3';
+    }
+
+    if (hostname === 'storage.googleapis.com') {
+      return 'gcs';
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get s3fs flags for a given provider
+ *
+ * Based on s3fs-fuse wiki recommendations:
+ * https://github.com/s3fs-fuse/s3fs-fuse/wiki/Non-Amazon-S3
+ */
+export function getProviderFlags(provider: BucketProvider | null): string[] {
+  if (!provider) {
+    return ['use_path_request_style'];
+  }
+
+  switch (provider) {
+    case 'r2':
+      return ['nomixupload'];
+
+    case 's3':
+      return [];
+
+    case 'gcs':
+      return [];
+
+    default:
+      return ['use_path_request_style'];
+  }
+}
+
+/**
+ * Resolve s3fs options by combining provider defaults with user overrides
+ */
+export function resolveS3fsOptions(
+  provider: BucketProvider | null,
+  userOptions?: string[]
+): string[] {
+  const providerFlags = getProviderFlags(provider);
+
+  if (!userOptions || userOptions.length === 0) {
+    return providerFlags;
+  }
+
+  // Merge provider flags with user options
+  // User options take precedence (come last in the array)
+  const allFlags = [...providerFlags, ...userOptions];
+
+  // Deduplicate flags (keep last occurrence)
+  const flagMap = new Map<string, string>();
+
+  for (const flag of allFlags) {
+    // Split on '=' to get the flag name
+    const [flagName] = flag.split('=');
+    flagMap.set(flagName, flag);
+  }
+
+  return Array.from(flagMap.values());
+}

package/src/storage-mount/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal bucket mounting types
+ */
+
+import type { BucketProvider } from '@repo/shared';
+
+/**
+ * Internal tracking information for active mounts
+ */
+export interface MountInfo {
+  bucket: string;
+  mountPath: string;
+  endpoint: string;
+  provider: BucketProvider | null;
+  passwordFilePath: string;
+  mounted: boolean;
+}

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

package/tests/base-client.test.ts

@@ -361,4 +361,222 @@ describe('BaseHttpClient', () => {
       }
     });
   });
+
+  describe('container startup retry logic', () => {
+    it('should retry 503 errors with "no container instance available"', async () => {
+      vi.useFakeTimers();
+
+      mockFetch
+        .mockResolvedValueOnce(
+          new Response('Error: There is no container instance available', {
+            status: 503
+          })
+        )
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ success: true, data: 'recovered' }), {
+            status: 200
+          })
+        );
+
+      const promise = client.testRequest<TestDataResponse>('/api/test');
+      await vi.advanceTimersByTimeAsync(5_000);
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result.success).toBe(true);
+      expect(result.data).toBe('recovered');
+
+      vi.useRealTimers();
+    });
+
+    it('should retry 500 errors with "container port not found"', async () => {
+      vi.useFakeTimers();
+
+      mockFetch
+        .mockResolvedValueOnce(
+          new Response('Connection refused: container port not found', {
+            status: 500
+          })
+        )
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ success: true }), { status: 200 })
+        );
+
+      const promise = client.testRequest('/api/test');
+      await vi.advanceTimersByTimeAsync(5_000);
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result.success).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    it('should retry 500 errors with "the container is not listening"', async () => {
+      vi.useFakeTimers();
+
+      mockFetch
+        .mockResolvedValueOnce(
+          new Response('Error: the container is not listening on port 3000', {
+            status: 500
+          })
+        )
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ success: true }), { status: 200 })
+        );
+
+      const promise = client.testRequest('/api/test');
+      await vi.advanceTimersByTimeAsync(5_000);
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result.success).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    it('should NOT retry 500 errors with "no such image"', async () => {
+      mockFetch.mockResolvedValueOnce(
+        new Response('Error: no such image: my-container:latest', {
+          status: 500
+        })
+      );
+
+      await expect(client.testRequest('/api/test')).rejects.toThrow();
+      expect(mockFetch).toHaveBeenCalledTimes(1); // No retry
+    });
+
+    it('should NOT retry 500 errors with "container already exists"', async () => {
+      mockFetch.mockResolvedValueOnce(
+        new Response('Error: container already exists', { status: 500 })
+      );
+
+      await expect(client.testRequest('/api/test')).rejects.toThrow();
+      expect(mockFetch).toHaveBeenCalledTimes(1); // No retry
+    });
+
+    it('should NOT retry 500 errors with unknown patterns', async () => {
+      mockFetch.mockResolvedValueOnce(
+        new Response('Internal server error: database connection failed', {
+          status: 500
+        })
+      );
+
+      await expect(client.testRequest('/api/test')).rejects.toThrow();
+      expect(mockFetch).toHaveBeenCalledTimes(1); // Fail-safe: don't retry
+    });
+
+    it('should NOT retry 404 or other non-500/503 errors', async () => {
+      mockFetch.mockResolvedValueOnce(
+        new Response('Not found', { status: 404 })
+      );
+
+      await expect(client.testRequest('/api/test')).rejects.toThrow();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('should respect MIN_TIME_FOR_RETRY_MS and stop retrying', async () => {
+      vi.useFakeTimers();
+
+      // Mock responses that would trigger retry
+      mockFetch.mockResolvedValue(
+        new Response('No container instance available', { status: 503 })
+      );
+
+      const promise = client.testRequest('/api/test');
+
+      // Fast-forward past retry budget (120s)
+      await vi.advanceTimersByTimeAsync(125_000);
+
+      // Should eventually give up and throw the 503 error
+      await expect(promise).rejects.toThrow();
+
+      vi.useRealTimers();
+    });
+
+    it('should use exponential backoff: 3s, 6s, 12s, 24s, 30s', async () => {
+      vi.useFakeTimers();
+      const delays: number[] = [];
+      let callCount = 0;
+
+      mockFetch.mockImplementation(async () => {
+        delays.push(Date.now());
+        callCount++;
+        // After 5 attempts, return success to avoid timeout
+        if (callCount >= 5) {
+          return new Response(JSON.stringify({ success: true }), {
+            status: 200
+          });
+        }
+        return new Response('No container instance available', { status: 503 });
+      });
+
+      const promise = client.testRequest('/api/test');
+
+      // Advance time to allow all retries
+      await vi.advanceTimersByTimeAsync(80_000);
+
+      await promise;
+
+      // Check delays between attempts (approximately)
+      // Attempt 1 at 0ms, Attempt 2 at ~3000ms, Attempt 3 at ~9000ms, etc.
+      expect(delays.length).toBeGreaterThanOrEqual(4);
+
+      vi.useRealTimers();
+    });
+
+    it('should retry multiple transient errors in sequence', async () => {
+      vi.useFakeTimers();
+
+      mockFetch
+        .mockResolvedValueOnce(
+          new Response('No container instance available', { status: 503 })
+        )
+        .mockResolvedValueOnce(
+          new Response('Container port not found', { status: 500 })
+        )
+        .mockResolvedValueOnce(
+          new Response('The container is not listening', { status: 500 })
+        )
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ success: true }), { status: 200 })
+        );
+
+      const promise = client.testRequest('/api/test');
+
+      // Advance time to allow all retries (3s + 6s + 12s = 21s)
+      await vi.advanceTimersByTimeAsync(25_000);
+
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(4);
+      expect(result.success).toBe(true);
+
+      vi.useRealTimers();
+    });
+
+    it('should handle case-insensitive error matching', async () => {
+      vi.useFakeTimers();
+
+      mockFetch
+        .mockResolvedValueOnce(
+          new Response('ERROR: CONTAINER PORT NOT FOUND', { status: 500 })
+        )
+        .mockResolvedValueOnce(
+          new Response(JSON.stringify({ success: true }), { status: 200 })
+        );
+
+      const promise = client.testRequest('/api/test');
+
+      // Advance time for first retry (3s)
+      await vi.advanceTimersByTimeAsync(5_000);
+
+      const result = await promise;
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result.success).toBe(true);
+
+      vi.useRealTimers();
+    });
+  });
 });

package/tests/get-sandbox.test.ts

@@ -44,7 +44,10 @@ describe('getSandbox', () => {
     const sandbox = getSandbox(mockNamespace, 'test-sandbox');
 
     expect(sandbox).toBeDefined();
-    expect(sandbox.setSandboxName).toHaveBeenCalledWith('test-sandbox');
+    expect(sandbox.setSandboxName).toHaveBeenCalledWith(
+      'test-sandbox',
+      undefined
+    );
   });
 
   it('should apply sleepAfter option when provided as string', () => {
@@ -146,4 +149,24 @@ describe('getSandbox', () => {
     expect(sandbox.setBaseUrl).toHaveBeenCalledWith('https://example.com');
     expect(sandbox.setKeepAlive).toHaveBeenCalledWith(true);
   });
+
+  it('should preserve sandbox ID case by default', () => {
+    const mockNamespace = {} as any;
+    getSandbox(mockNamespace, 'MyProject-ABC123');
+
+    expect(mockGetContainer).toHaveBeenCalledWith(
+      mockNamespace,
+      'MyProject-ABC123'
+    );
+  });
+
+  it('should normalize sandbox ID to lowercase when normalizeId option is true', () => {
+    const mockNamespace = {} as any;
+    getSandbox(mockNamespace, 'MyProject-ABC123', { normalizeId: true });
+
+    expect(mockGetContainer).toHaveBeenCalledWith(
+      mockNamespace,
+      'myproject-abc123'
+    );
+  });
 });

package/tests/sandbox.test.ts

@@ -42,6 +42,10 @@ vi.mock('@cloudflare/containers', () => {
       // Mock implementation for HTTP path
       return new Response('Mock Container HTTP fetch');
     }
+    async getState() {
+      // Mock implementation - return healthy state
+      return { status: 'healthy' };
+    }
   };
 
   return {
@@ -736,4 +740,121 @@ describe('Sandbox - Automatic Session Management', () => {
       expect(result.sessionId).toBe('custom-session');
     });
   });
+
+  describe('constructPreviewUrl validation', () => {
+    it('should throw clear error for ID with uppercase letters without normalizeId', async () => {
+      await sandbox.setSandboxName('MyProject-123', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'test-token-1234',
+        previewUrl: ''
+      });
+
+      await expect(
+        sandbox.exposePort(8080, { hostname: 'example.com' })
+      ).rejects.toThrow(/Preview URLs require lowercase sandbox IDs/);
+    });
+
+    it('should construct valid URL for lowercase ID', async () => {
+      await sandbox.setSandboxName('my-project', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(8080, {
+        hostname: 'example.com'
+      });
+
+      expect(result.url).toMatch(
+        /^https:\/\/8080-my-project-[a-z0-9_-]{16}\.example\.com\/?$/
+      );
+      expect(result.port).toBe(8080);
+    });
+
+    it('should construct valid URL with normalized ID', async () => {
+      await sandbox.setSandboxName('myproject-123', true);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 4000,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(4000, { hostname: 'my-app.dev' });
+
+      expect(result.url).toMatch(
+        /^https:\/\/4000-myproject-123-[a-z0-9_-]{16}\.my-app\.dev\/?$/
+      );
+      expect(result.port).toBe(4000);
+    });
+
+    it('should construct valid localhost URL', async () => {
+      await sandbox.setSandboxName('test-sandbox', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'mock-token',
+        previewUrl: ''
+      });
+
+      const result = await sandbox.exposePort(8080, {
+        hostname: 'localhost:3000'
+      });
+
+      expect(result.url).toMatch(
+        /^http:\/\/8080-test-sandbox-[a-z0-9_-]{16}\.localhost:3000\/?$/
+      );
+    });
+
+    it('should include helpful guidance in error message', async () => {
+      await sandbox.setSandboxName('MyProject-ABC', false);
+
+      vi.spyOn(sandbox.client.ports, 'exposePort').mockResolvedValue({
+        port: 8080,
+        token: 'test-token-1234',
+        previewUrl: ''
+      });
+
+      await expect(
+        sandbox.exposePort(8080, { hostname: 'example.com' })
+      ).rejects.toThrow(
+        /getSandbox\(ns, "MyProject-ABC", \{ normalizeId: true \}\)/
+      );
+    });
+  });
+
+  describe('timeout configuration validation', () => {
+    it('should reject invalid timeout values', async () => {
+      // NaN, Infinity, and out-of-range values should all be rejected
+      await expect(
+        sandbox.setContainerTimeouts({ instanceGetTimeoutMS: NaN })
+      ).rejects.toThrow();
+
+      await expect(
+        sandbox.setContainerTimeouts({ portReadyTimeoutMS: Infinity })
+      ).rejects.toThrow();
+
+      await expect(
+        sandbox.setContainerTimeouts({ instanceGetTimeoutMS: -1 })
+      ).rejects.toThrow();
+
+      await expect(
+        sandbox.setContainerTimeouts({ waitIntervalMS: 999_999 })
+      ).rejects.toThrow();
+    });
+
+    it('should accept valid timeout values', async () => {
+      await expect(
+        sandbox.setContainerTimeouts({
+          instanceGetTimeoutMS: 30_000,
+          portReadyTimeoutMS: 90_000,
+          waitIntervalMS: 1000
+        })
+      ).resolves.toBeUndefined();
+    });
+  });
 });