@cloudflare/sandbox 0.3.6 → 0.4.1

package/tests/sse-parser.test.ts

@@ -0,0 +1,290 @@
+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,266 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type {
+  CommandsResponse,
+  PingResponse
+} 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
+});
+
+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('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/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/vitest.config.ts

@@ -0,0 +1,31 @@
+import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
+
+/**
+ * Workers runtime test configuration
+ *
+ * Tests the SDK code in Cloudflare Workers environment with Durable Objects.
+ * Uses @cloudflare/vitest-pool-workers to run tests in workerd runtime.
+ *
+ * Run with: npm test
+ */
+export default defineWorkersConfig({
+  test: {
+    globals: true,
+    include: ['tests/**/*.test.ts'],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+    teardownTimeout: 10000,
+    poolOptions: {
+      workers: {
+        wrangler: {
+          configPath: './tests/wrangler.jsonc',
+        },
+        singleWorker: true,
+        isolatedStorage: false,
+      },
+    },
+  },
+  esbuild: {
+    target: 'esnext',
+  },
+});