@ricsam/isolate-client 0.1.14 → 0.1.16

package/README.md

@@ -37,7 +37,7 @@ const runtime = await client.createRuntime({
   console: {
     onEntry: (entry) => console.log("[isolate]", entry),
   },
-  fetch: async (request) => fetch(request),
+  fetch: async (url, init) => fetch(url, init),
 });
 
 // Execute code (always ES module mode)
@@ -145,6 +145,7 @@ interface Namespace {
 - Namespaced runtimes are cached on dispose and evicted via LRU when `maxIsolates` limit is reached
 - Cross-client reuse is allowed - any connection can reuse a namespace by ID
 - A namespace can only have one active runtime at a time; creating a second runtime with the same namespace ID while one is active will fail
+- Concurrent createRuntime calls for the same namespace are rejected with `Namespace "<id>" creation already in progress`
 
 ## Module Loader
 
@@ -270,6 +271,93 @@ const runtime = await client.createRuntime({
 });
 ```
 
+## WebSocket Client Callback
+
+Control outbound WebSocket connections from isolate code. The callback lets you allow, block, or proxy WebSocket connections:
+
+```typescript
+const runtime = await client.createRuntime({
+  webSocket: async (url: string, protocols: string[]) => {
+    // Block connections to certain hosts
+    if (url.includes("blocked.com")) {
+      return null; // Connection blocked
+    }
+
+    // Proxy to a different server
+    if (url.includes("internal")) {
+      return new WebSocket("wss://proxy.example.com" + new URL(url).pathname);
+    }
+
+    // Allow connection normally
+    return new WebSocket(url, protocols.length > 0 ? protocols : undefined);
+  },
+});
+
+// Isolate code can now use WHATWG WebSocket API
+await runtime.eval(`
+  const ws = new WebSocket("wss://api.example.com/stream");
+
+  ws.onopen = () => {
+    console.log("Connected!");
+    ws.send("Hello server");
+  };
+
+  ws.onmessage = (event) => {
+    console.log("Received:", event.data);
+  };
+
+  ws.onclose = (event) => {
+    console.log("Closed:", event.code, event.reason);
+  };
+`);
+```
+
+### WebSocket Callback Behavior
+
+| Return Value | Behavior |
+|--------------|----------|
+| `WebSocket` instance | Use this WebSocket for the connection |
+| `null` | Block the connection (isolate receives error + close events) |
+| `Promise<WebSocket>` | Async - wait for WebSocket |
+| `Promise<null>` | Async - block the connection |
+| Throws/rejects | Block the connection with error |
+
+### What "Blocked" Looks Like in the Isolate
+
+When a connection is blocked, the isolate sees it as a failed connection (similar to server unreachable):
+
+```javascript
+const ws = new WebSocket("wss://blocked.com");
+
+ws.onerror = (event) => {
+  // Fires first
+  console.log("Connection failed");
+};
+
+ws.onclose = (event) => {
+  // Then fires with:
+  console.log(event.code);      // 1006 (Abnormal Closure)
+  console.log(event.reason);    // "Connection blocked"
+  console.log(event.wasClean);  // false
+};
+
+// ws.onopen never fires
+```
+
+### Default Behavior
+
+If no `webSocket` callback is provided, connections are allowed automatically:
+
+```typescript
+// No callback - all WebSocket connections are auto-allowed
+const runtime = await client.createRuntime({});
+
+await runtime.eval(`
+  // This will connect directly
+  const ws = new WebSocket("wss://echo.websocket.org");
+`);
+```
+
 ## Test Environment
 
 Enable test environment to run tests inside the sandbox:
@@ -327,19 +415,27 @@ type TestEvent =
 
 ## Playwright Integration
 
-Run browser automation with untrusted code. **The client owns the browser** - you provide the Playwright page object:
+Run browser automation with untrusted code. Public API is handler-first:
+
+```typescript
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
+
+playwright: { handler: defaultPlaywrightHandler(page) }
+```
 
 ### Script Mode (No Tests)
 
 ```typescript
 import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage();
 
 const runtime = await client.createRuntime({
   playwright: {
-    page,
+    handler: defaultPlaywrightHandler(page),
+    timeout: 30000, // Default timeout for operations
     onEvent: (event) => {
       // Unified event handler for all playwright events
       if (event.type === "browserConsoleLog") {
@@ -374,6 +470,7 @@ Combine `testEnvironment` and `playwright` for browser testing. Playwright exten
 
 ```typescript
 import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
 
 const browser = await chromium.launch({ headless: true });
 const page = await browser.newPage();
@@ -391,7 +488,7 @@ const runtime = await client.createRuntime({
   },
   testEnvironment: true, // Provides describe, it, expect
   playwright: {
-    page,
+    handler: defaultPlaywrightHandler(page),
     console: true, // Routes browser logs through the console handler above
   },
 });
@@ -418,6 +515,141 @@ await runtime.dispose();
 await browser.close();
 ```
 
+### File Operations (Screenshots, PDFs, File Uploads)
+
+For security, file system access requires explicit callbacks. Without these callbacks, operations with file paths will throw errors:
+
+```typescript
+import { chromium } from "playwright";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
+
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage();
+
+const runtime = await client.createRuntime({
+  testEnvironment: true,
+  playwright: {
+    handler: defaultPlaywrightHandler(page, {
+      // Callback for writing screenshots and PDFs to disk
+      writeFile: async (filePath: string, data: Buffer) => {
+        // Validate path, then write
+        if (!filePath.startsWith("/allowed/output/")) {
+          throw new Error("Write not allowed to this path");
+        }
+        await fs.writeFile(filePath, data);
+      },
+      // Callback for reading files for setInputFiles()
+      readFile: async (filePath: string) => {
+        // Validate path, then read
+        if (!filePath.startsWith("/allowed/uploads/")) {
+          throw new Error("Read not allowed from this path");
+        }
+        const buffer = await fs.readFile(filePath);
+        return {
+          name: path.basename(filePath),
+          mimeType: "application/octet-stream", // Determine from extension
+          buffer,
+        };
+      },
+    }),
+  },
+});
+
+await runtime.eval(`
+  test('file operations', async () => {
+    await page.goto('data:text/html,<input type="file" id="upload" />');
+
+    // Screenshot with path - calls writeFile callback
+    const base64 = await page.screenshot({ path: '/allowed/output/screenshot.png' });
+    // base64 is always returned, writeFile is called additionally
+
+    // PDF with path - calls writeFile callback
+    await page.pdf({ path: '/allowed/output/document.pdf' });
+
+    // File upload with path - calls readFile callback
+    await page.locator('#upload').setInputFiles('/allowed/uploads/test.txt');
+
+    // File upload with buffer data - no callback needed
+    await page.locator('#upload').setInputFiles([{
+      name: 'inline.txt',
+      mimeType: 'text/plain',
+      buffer: new TextEncoder().encode('Hello, World!'),
+    }]);
+  });
+`);
+```
+
+**Behavior without callbacks:**
+- `screenshot()` / `pdf()` without path: Returns base64 string (works without callback)
+- `screenshot({ path })` / `pdf({ path })` without `writeFile`: Throws error
+- `setInputFiles('/path')` without `readFile`: Throws error
+- `setInputFiles([{ name, mimeType, buffer }])`: Works without callback (inline data)
+
+### Multi-Page Testing
+
+For tests that need multiple pages or browser contexts, provide `createPage` and/or `createContext` callbacks:
+
+```typescript
+import { chromium } from "playwright";
+import { defaultPlaywrightHandler } from "@ricsam/isolate-playwright/client";
+
+const browser = await chromium.launch({ headless: true });
+const browserContext = await browser.newContext();
+const page = await browserContext.newPage();
+
+const runtime = await client.createRuntime({
+  testEnvironment: true,
+  playwright: {
+    handler: defaultPlaywrightHandler(page, {
+      // Called when isolate code calls context.newPage(); receive the BrowserContext and call context.newPage()
+      createPage: async (context) => context.newPage(),
+      // Called when isolate code calls browser.newContext()
+      createContext: async (options) => browser.newContext(options),
+    }),
+  },
+});
+
+await runtime.eval(`
+  test('multi-page test', async () => {
+    // Create additional pages
+    const page2 = await context.newPage();
+
+    // Navigate independently
+    await page.goto('https://example.com/page1');
+    await page2.goto('https://example.com/page2');
+
+    // Work with multiple pages
+    await page.locator('#button').click();
+    await page2.locator('#input').fill('text');
+
+    await page2.close();
+  });
+
+  test('multi-context test', async () => {
+    // Create isolated context (separate cookies, storage)
+    const ctx2 = await browser.newContext();
+    const page2 = await ctx2.newPage();
+
+    // Cookies are isolated between contexts
+    await context.addCookies([{ name: 'test', value: '1', domain: 'example.com', path: '/' }]);
+    const ctx1Cookies = await context.cookies();
+    const ctx2Cookies = await ctx2.cookies();
+
+    expect(ctx1Cookies.some(c => c.name === 'test')).toBe(true);
+    expect(ctx2Cookies.some(c => c.name === 'test')).toBe(false);
+
+    await ctx2.close();
+  });
+`);
+```
+
+**Behavior without lifecycle callbacks:**
+- `context.newPage()` without `createPage`: Throws error
+- `browser.newContext()` without `createContext`: Throws error
+- `context.cookies()`, `context.addCookies()`, `context.clearCookies()`: Work without callbacks
+
 ## Runtime Interface
 
 ```typescript
@@ -476,8 +708,8 @@ interface RemoteTestEnvironmentHandle {
 }
 
 interface RemotePlaywrightHandle {
-  getCollectedData(): Promise<CollectedData>;
-  clearCollectedData(): Promise<void>;
+  getCollectedData(): CollectedData;
+  clearCollectedData(): void;
 }
 ```