@cloudflare/sandbox 0.4.18 → 0.5.2

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

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/git-client.test.ts

@@ -1,5 +1,5 @@
+import type { GitCheckoutResult } from '@repo/shared';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { GitCheckoutResponse } from '../src/clients';
 import { GitClient } from '../src/clients/git-client';
 import {
   GitAuthenticationError,
@@ -35,12 +35,8 @@ describe('GitClient', () => {
 
   describe('repository cloning', () => {
     it('should clone public repositories successfully', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: true,
-        stdout:
-          "Cloning into 'react'...\nReceiving objects: 100% (1284/1284), done.",
-        stderr: '',
-        exitCode: 0,
         repoUrl: 'https://github.com/facebook/react.git',
         branch: 'main',
         targetDir: 'react',
@@ -59,15 +55,11 @@ describe('GitClient', () => {
       expect(result.success).toBe(true);
       expect(result.repoUrl).toBe('https://github.com/facebook/react.git');
       expect(result.branch).toBe('main');
-      expect(result.exitCode).toBe(0);
     });
 
     it('should clone repositories to specific branches', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: true,
-        stdout: "Cloning into 'project'...\nSwitching to branch 'development'",
-        stderr: '',
-        exitCode: 0,
         repoUrl: 'https://github.com/company/project.git',
         branch: 'development',
         targetDir: 'project',
@@ -89,11 +81,8 @@ describe('GitClient', () => {
     });
 
     it('should clone repositories to custom directories', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: true,
-        stdout: "Cloning into 'workspace/my-app'...\nDone.",
-        stderr: '',
-        exitCode: 0,
         repoUrl: 'https://github.com/user/my-app.git',
         branch: 'main',
         targetDir: 'workspace/my-app',
@@ -115,12 +104,8 @@ describe('GitClient', () => {
     });
 
     it('should handle large repository clones with warnings', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: true,
-        stdout:
-          "Cloning into 'linux'...\nReceiving objects: 100% (8125432/8125432), 2.34 GiB, done.",
-        stderr: 'warning: filtering not recognized by server',
-        exitCode: 0,
         repoUrl: 'https://github.com/torvalds/linux.git',
         branch: 'master',
         targetDir: 'linux',
@@ -137,15 +122,11 @@ describe('GitClient', () => {
       );
 
       expect(result.success).toBe(true);
-      expect(result.stderr).toContain('warning:');
     });
 
     it('should handle SSH repository URLs', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: true,
-        stdout: "Cloning into 'private-project'...\nDone.",
-        stderr: '',
-        exitCode: 0,
         repoUrl: 'git@github.com:company/private-project.git',
         branch: 'main',
         targetDir: 'private-project',
@@ -175,8 +156,6 @@ describe('GitClient', () => {
             JSON.stringify({
               success: true,
               stdout: `Cloning into '${repoName}'...\nDone.`,
-              stderr: '',
-              exitCode: 0,
               repoUrl: body.repoUrl,
               branch: body.branch || 'main',
               targetDir: body.targetDir || repoName,
@@ -320,11 +299,8 @@ describe('GitClient', () => {
     });
 
     it('should handle partial clone failures', async () => {
-      const mockResponse: GitCheckoutResponse = {
+      const mockResponse: GitCheckoutResult = {
         success: false,
-        stdout: "Cloning into 'repo'...\nReceiving objects:  45% (450/1000)",
-        stderr: 'error: RPC failed\nfatal: early EOF',
-        exitCode: 128,
         repoUrl: 'https://github.com/problematic/repo.git',
         branch: 'main',
         targetDir: 'repo',
@@ -341,8 +317,6 @@ describe('GitClient', () => {
       );
 
       expect(result.success).toBe(false);
-      expect(result.exitCode).toBe(128);
-      expect(result.stderr).toContain('RPC failed');
     });
   });
 
@@ -434,9 +408,6 @@ describe('GitClient', () => {
         new Response(
           JSON.stringify({
             success: true,
-            stdout: "Cloning into 'private-repo'...\nDone.",
-            stderr: '',
-            exitCode: 0,
             repoUrl:
               'https://oauth2:ghp_token123@github.com/user/private-repo.git',
             branch: 'main',
@@ -463,9 +434,6 @@ describe('GitClient', () => {
         new Response(
           JSON.stringify({
             success: true,
-            stdout: "Cloning into 'react'...\nDone.",
-            stderr: '',
-            exitCode: 0,
             repoUrl: 'https://github.com/facebook/react.git',
             branch: 'main',
             targetDir: '/workspace/react',