@cloudflare/sandbox 0.0.0-7de28be → 0.0.0-7edbfa9

package/tests/sse-parser.test.ts

@@ -0,0 +1,291 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  asyncIterableToSSEStream,
+  parseSSEStream,
+  responseToAsyncIterable
+} from '../src/sse-parser';
+
+function createMockSSEStream(events: string[]): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      const encoder = new TextEncoder();
+      for (const event of events) {
+        controller.enqueue(encoder.encode(event));
+      }
+      controller.close();
+    }
+  });
+}
+
+describe('SSE Parser', () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  describe('parseSSEStream', () => {
+    it('should parse valid SSE events', async () => {
+      const stream = createMockSSEStream([
+        'data: {"type":"start","command":"echo test"}\n\n',
+        'data: {"type":"stdout","data":"test\\n"}\n\n',
+        'data: {"type":"complete","exitCode":0}\n\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(3);
+      expect(events[0]).toEqual({ type: 'start', command: 'echo test' });
+      expect(events[1]).toEqual({ type: 'stdout', data: 'test\n' });
+      expect(events[2]).toEqual({ type: 'complete', exitCode: 0 });
+    });
+
+    it('should handle empty data lines', async () => {
+      const stream = createMockSSEStream([
+        'data: \n\n',
+        'data: {"type":"stdout","data":"valid"}\n\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({ type: 'stdout', data: 'valid' });
+    });
+
+    it('should skip [DONE] markers', async () => {
+      const stream = createMockSSEStream([
+        'data: {"type":"start"}\n\n',
+        'data: [DONE]\n\n',
+        'data: {"type":"complete"}\n\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(2);
+      expect(events[0]).toEqual({ type: 'start' });
+      expect(events[1]).toEqual({ type: 'complete' });
+    });
+
+    it('should handle malformed JSON gracefully', async () => {
+      const stream = createMockSSEStream([
+        'data: invalid json\n\n',
+        'data: {"type":"stdout","data":"valid"}\n\n',
+        'data: {incomplete\n\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({ type: 'stdout', data: 'valid' });
+    });
+
+    it('should handle empty lines and comments', async () => {
+      const stream = createMockSSEStream([
+        '\n',
+        '   \n',
+        ': this is a comment\n',
+        'data: {"type":"test"}\n\n',
+        '\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({ type: 'test' });
+    });
+
+    it('should handle chunked data properly', async () => {
+      // Simulate chunked delivery where data arrives in parts
+      const stream = new ReadableStream({
+        start(controller) {
+          const encoder = new TextEncoder();
+          // Send partial data
+          controller.enqueue(encoder.encode('data: {"typ'));
+          controller.enqueue(encoder.encode('e":"start"}\n\n'));
+          controller.enqueue(encoder.encode('data: {"type":"end"}\n\n'));
+          controller.close();
+        }
+      });
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(2);
+      expect(events[0]).toEqual({ type: 'start' });
+      expect(events[1]).toEqual({ type: 'end' });
+    });
+
+    it('should handle remaining buffer data after stream ends', async () => {
+      const stream = createMockSSEStream(['data: {"type":"complete"}']);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({ type: 'complete' });
+    });
+
+    it('should support cancellation via AbortSignal', async () => {
+      const controller = new AbortController();
+      const stream = createMockSSEStream(['data: {"type":"start"}\n\n']);
+      controller.abort();
+
+      await expect(async () => {
+        for await (const event of parseSSEStream(stream, controller.signal)) {
+        }
+      }).rejects.toThrow('Operation was aborted');
+    });
+
+    it('should handle non-data SSE lines', async () => {
+      const stream = createMockSSEStream([
+        'event: message\n',
+        'id: 123\n',
+        'retry: 3000\n',
+        'data: {"type":"test"}\n\n'
+      ]);
+
+      const events: any[] = [];
+      for await (const event of parseSSEStream(stream)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(1);
+      expect(events[0]).toEqual({ type: 'test' });
+    });
+  });
+
+  describe('responseToAsyncIterable', () => {
+    it('should convert Response with SSE stream to AsyncIterable', async () => {
+      const mockBody = createMockSSEStream([
+        'data: {"type":"start"}\n\n',
+        'data: {"type":"end"}\n\n'
+      ]);
+
+      const mockResponse = {
+        ok: true,
+        body: mockBody
+      } as Response;
+
+      const events: any[] = [];
+      for await (const event of responseToAsyncIterable(mockResponse)) {
+        events.push(event);
+      }
+
+      expect(events).toHaveLength(2);
+      expect(events[0]).toEqual({ type: 'start' });
+      expect(events[1]).toEqual({ type: 'end' });
+    });
+
+    it('should throw error for non-ok response', async () => {
+      const mockResponse = {
+        ok: false,
+        status: 500,
+        statusText: 'Internal Server Error'
+      } as Response;
+
+      await expect(async () => {
+        for await (const event of responseToAsyncIterable(mockResponse)) {
+          // Should not reach here
+        }
+      }).rejects.toThrow('Response not ok: 500 Internal Server Error');
+    });
+
+    it('should throw error for response without body', async () => {
+      const mockResponse = {
+        ok: true,
+        body: null
+      } as Response;
+
+      await expect(async () => {
+        for await (const event of responseToAsyncIterable(mockResponse)) {
+          // Should not reach here
+        }
+      }).rejects.toThrow('No response body');
+    });
+  });
+
+  describe('asyncIterableToSSEStream', () => {
+    it('should convert AsyncIterable to SSE-formatted ReadableStream', async () => {
+      async function* mockEvents() {
+        yield { type: 'start', command: 'test' };
+        yield { type: 'stdout', data: 'output' };
+        yield { type: 'complete', exitCode: 0 };
+      }
+
+      const stream = asyncIterableToSSEStream(mockEvents());
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+
+      const chunks: string[] = [];
+      let done = false;
+
+      while (!done) {
+        const { value, done: readerDone } = await reader.read();
+        done = readerDone;
+        if (value) {
+          chunks.push(decoder.decode(value));
+        }
+      }
+
+      const fullOutput = chunks.join('');
+      expect(fullOutput).toBe(
+        'data: {"type":"start","command":"test"}\n\n' +
+          'data: {"type":"stdout","data":"output"}\n\n' +
+          'data: {"type":"complete","exitCode":0}\n\n' +
+          'data: [DONE]\n\n'
+      );
+    });
+
+    it('should use custom serializer when provided', async () => {
+      async function* mockEvents() {
+        yield { name: 'test', value: 123 };
+      }
+
+      const stream = asyncIterableToSSEStream(mockEvents(), {
+        serialize: (event) => `custom:${event.name}=${event.value}`
+      });
+
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      const { value } = await reader.read();
+
+      expect(decoder.decode(value!)).toBe('data: custom:test=123\n\n');
+    });
+
+    it('should handle errors in async iterable', async () => {
+      async function* mockEvents() {
+        yield { type: 'start' };
+        throw new Error('Async iterable error');
+      }
+
+      const stream = asyncIterableToSSEStream(mockEvents());
+      const reader = stream.getReader();
+
+      await reader.read();
+      await expect(reader.read()).rejects.toThrow('Async iterable error');
+    });
+  });
+});

package/tests/utility-client.test.ts

@@ -0,0 +1,339 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type {
+  CommandsResponse,
+  PingResponse,
+  VersionResponse
+} from '../src/clients';
+import { UtilityClient } from '../src/clients/utility-client';
+import { SandboxError } from '../src/errors';
+
+// Mock data factory for creating test responses
+const mockPingResponse = (
+  overrides: Partial<PingResponse> = {}
+): PingResponse => ({
+  success: true,
+  message: 'pong',
+  uptime: 12345,
+  timestamp: '2023-01-01T00:00:00Z',
+  ...overrides
+});
+
+const mockCommandsResponse = (
+  commands: string[],
+  overrides: Partial<CommandsResponse> = {}
+): CommandsResponse => ({
+  success: true,
+  availableCommands: commands,
+  count: commands.length,
+  timestamp: '2023-01-01T00:00:00Z',
+  ...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>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+
+    client = new UtilityClient({
+      baseUrl: 'http://test.com',
+      port: 3000
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('health checking', () => {
+    it('should check sandbox health successfully', async () => {
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(mockPingResponse()), { status: 200 })
+      );
+
+      const result = await client.ping();
+
+      expect(result).toBe('pong');
+    });
+
+    it('should handle different health messages', async () => {
+      const messages = ['pong', 'alive', 'ok'];
+
+      for (const message of messages) {
+        mockFetch.mockResolvedValueOnce(
+          new Response(JSON.stringify(mockPingResponse({ message })), {
+            status: 200
+          })
+        );
+
+        const result = await client.ping();
+        expect(result).toBe(message);
+      }
+    });
+
+    it('should handle concurrent health checks', async () => {
+      mockFetch.mockImplementation(() =>
+        Promise.resolve(new Response(JSON.stringify(mockPingResponse())))
+      );
+
+      const healthChecks = await Promise.all([
+        client.ping(),
+        client.ping(),
+        client.ping()
+      ]);
+
+      expect(healthChecks).toHaveLength(3);
+      healthChecks.forEach((result) => {
+        expect(result).toBe('pong');
+      });
+
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
+
+    it('should detect unhealthy sandbox conditions', async () => {
+      const errorResponse = {
+        error: 'Service Unavailable',
+        code: 'HEALTH_CHECK_FAILED'
+      };
+
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(errorResponse), { status: 503 })
+      );
+
+      await expect(client.ping()).rejects.toThrow();
+    });
+
+    it('should handle network failures during health checks', async () => {
+      mockFetch.mockRejectedValue(new Error('Network connection failed'));
+
+      await expect(client.ping()).rejects.toThrow('Network connection failed');
+    });
+  });
+
+  describe('command discovery', () => {
+    it('should discover available system commands', async () => {
+      const systemCommands = ['ls', 'cat', 'echo', 'grep', 'find'];
+
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(mockCommandsResponse(systemCommands)), {
+          status: 200
+        })
+      );
+
+      const result = await client.getCommands();
+
+      expect(result).toEqual(systemCommands);
+      expect(result).toContain('ls');
+      expect(result).toContain('grep');
+      expect(result).toHaveLength(systemCommands.length);
+    });
+
+    it('should handle minimal command environments', async () => {
+      const minimalCommands = ['sh', 'echo', 'cat'];
+
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(mockCommandsResponse(minimalCommands)), {
+          status: 200
+        })
+      );
+
+      const result = await client.getCommands();
+
+      expect(result).toEqual(minimalCommands);
+      expect(result).toHaveLength(3);
+    });
+
+    it('should handle large command environments', async () => {
+      const richCommands = Array.from({ length: 150 }, (_, i) => `cmd_${i}`);
+
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(mockCommandsResponse(richCommands)), {
+          status: 200
+        })
+      );
+
+      const result = await client.getCommands();
+
+      expect(result).toEqual(richCommands);
+      expect(result).toHaveLength(150);
+    });
+
+    it('should handle empty command environments', async () => {
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(mockCommandsResponse([])), { status: 200 })
+      );
+
+      const result = await client.getCommands();
+
+      expect(result).toEqual([]);
+      expect(result).toHaveLength(0);
+    });
+
+    it('should handle command discovery failures', async () => {
+      const errorResponse = {
+        error: 'Access denied to command list',
+        code: 'PERMISSION_DENIED'
+      };
+
+      mockFetch.mockResolvedValue(
+        new Response(JSON.stringify(errorResponse), { status: 403 })
+      );
+
+      await expect(client.getCommands()).rejects.toThrow();
+    });
+  });
+
+  describe('error handling and resilience', () => {
+    it('should handle malformed server responses gracefully', async () => {
+      mockFetch.mockResolvedValue(
+        new Response('invalid json {', { status: 200 })
+      );
+
+      await expect(client.ping()).rejects.toThrow(SandboxError);
+    });
+
+    it('should handle network timeouts and connectivity issues', async () => {
+      const networkError = new Error('Network timeout');
+      mockFetch.mockRejectedValue(networkError);
+
+      await expect(client.ping()).rejects.toThrow(networkError.message);
+    });
+
+    it('should handle partial service failures', async () => {
+      // First call (ping) succeeds
+      mockFetch.mockResolvedValueOnce(
+        new Response(JSON.stringify(mockPingResponse()), { status: 200 })
+      );
+
+      // Second call (getCommands) fails
+      const errorResponse = {
+        error: 'Command enumeration service unavailable',
+        code: 'SERVICE_UNAVAILABLE'
+      };
+
+      mockFetch.mockResolvedValueOnce(
+        new Response(JSON.stringify(errorResponse), { status: 503 })
+      );
+
+      const pingResult = await client.ping();
+      expect(pingResult).toBe('pong');
+
+      await expect(client.getCommands()).rejects.toThrow();
+    });
+
+    it('should handle concurrent operations with mixed success', async () => {
+      let callCount = 0;
+      mockFetch.mockImplementation(() => {
+        callCount++;
+        if (callCount % 2 === 0) {
+          return Promise.reject(new Error('Intermittent failure'));
+        } else {
+          return Promise.resolve(
+            new Response(JSON.stringify(mockPingResponse()))
+          );
+        }
+      });
+
+      const results = await Promise.allSettled([
+        client.ping(), // Should succeed (call 1)
+        client.ping(), // Should fail (call 2)
+        client.ping(), // Should succeed (call 3)
+        client.ping() // Should fail (call 4)
+      ]);
+
+      expect(results[0].status).toBe('fulfilled');
+      expect(results[1].status).toBe('rejected');
+      expect(results[2].status).toBe('fulfilled');
+      expect(results[3].status).toBe('rejected');
+    });
+  });
+
+  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();
+      expect(minimalClient).toBeInstanceOf(UtilityClient);
+    });
+
+    it('should initialize with full options', () => {
+      const fullOptionsClient = new UtilityClient({
+        baseUrl: 'http://custom.com',
+        port: 8080
+      });
+      expect(fullOptionsClient).toBeInstanceOf(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);
+  });
+});

package/tests/wrangler.jsonc

@@ -0,0 +1,35 @@
+{
+  "name": "sandbox-test",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-05-06",
+  "compatibility_flags": ["nodejs_compat"],
+
+  "observability": {
+    "enabled": true
+  },
+
+  "containers": [
+    {
+      "class_name": "Sandbox",
+      "image": "../Dockerfile",
+      "name": "sandbox",
+      "max_instances": 1
+    }
+  ],
+
+  "durable_objects": {
+    "bindings": [
+      {
+        "class_name": "Sandbox",
+        "name": "Sandbox"
+      }
+    ]
+  },
+
+  "migrations": [
+    {
+      "new_sqlite_classes": ["Sandbox"],
+      "tag": "v1"
+    }
+  ]
+}

package/tsconfig.json

@@ -1,3 +1,11 @@
 {
-  "extends": "../../tsconfig.base.json"
+  "extends": "@repo/typescript-config/base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "types": ["node", "@cloudflare/workers-types"],
+    "lib": ["ES2022"],
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["tests/**", "node_modules", "dist"]
 }

package/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: 'src/index.ts',
+  outDir: 'dist',
+  dts: {
+    sourcemap: true,
+    resolve: ['@repo/shared']
+  },
+  sourcemap: true,
+  format: 'esm'
+});