@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/README.md

@@ -0,0 +1,571 @@
+# QuickJS Bridge System
+
+A modular system for bridging runtime APIs into QuickJS sandbox environments.
+
+## Overview
+
+The bridge system provides a clean, reusable architecture for exposing host runtime APIs to sandboxed code. Each bridge is self-contained and follows consistent patterns for:
+
+- Creating async functions that return promises
+- Managing state across calls
+- Converting between JavaScript and QuickJS types
+- Tracking promises for proper cleanup
+
+## Architecture
+
+```
+src/sandbox/bridges/
+├── types.ts              # TypeScript types for bridge system
+├── utils.ts              # Reusable bridge utilities
+├── index.ts              # Main entry point, exports all bridges
+├── fetch.ts              # Fetch API bridge (Response, Headers)
+├── response.ts           # Response constructor bridge
+├── console.ts            # Console API bridge (console.log, warn, error)
+├── text-encoder.ts       # TextEncoder bridge
+├── text-decoder.ts       # TextDecoder bridge (with stateful instances)
+└── readable-stream.ts    # ReadableStream and Reader bridges
+```
+
+## Core Utilities
+
+### BridgeContext
+
+All bridges receive a `BridgeContext` object:
+
+```typescript
+interface BridgeContext {
+  context: QuickJSContext; // QuickJS context
+  runtime: any; // QuickJS runtime
+  tracker: PromiseTracker; // Promise tracker for async ops
+  logger?: Logger; // Optional logger
+}
+```
+
+### Utility Functions
+
+#### `convertToHandle(context, value)`
+
+Converts JavaScript values to QuickJS handles:
+
+```typescript
+const handle = convertToHandle(context, { foo: 'bar' });
+context.setProp(objectHandle, 'data', handle);
+handle.dispose();
+```
+
+#### `createAsyncBridge(ctx, name, hostFn)`
+
+Creates an async function that bridges to a host function:
+
+```typescript
+const readFileHandle = createAsyncBridge(ctx, 'readFile', async path => {
+  return await fs.readFile(path, 'utf-8');
+});
+
+context.setProp(context.global, 'readFile', readFileHandle);
+readFileHandle.dispose();
+```
+
+#### `createSyncBridge(ctx, name, hostFn)`
+
+Creates a synchronous function bridge:
+
+```typescript
+const mathAbsHandle = createSyncBridge(ctx, 'abs', x => Math.abs(x));
+context.setProp(mathObj, 'abs', mathAbsHandle);
+mathAbsHandle.dispose();
+```
+
+#### `defineClass(ctx, classCode, className)`
+
+Defines an ES6 class in the sandbox using `evalCode`:
+
+```typescript
+const classHandle = defineClass(
+  ctx,
+  `
+  class MyClass {
+    constructor(value) {
+      this.value = value;
+    }
+    getValue() {
+      return this.value;
+    }
+  }
+`,
+  'MyClass'
+);
+
+if (classHandle) {
+  context.setProp(context.global, 'MyClass', classHandle);
+  classHandle.dispose();
+}
+```
+
+#### `setProperties(context, handle, props)`
+
+Sets multiple properties at once:
+
+```typescript
+setProperties(context, responseHandle, {
+  status: 200,
+  ok: true,
+  statusText: 'OK'
+});
+```
+
+#### `addMethod(context, objHandle, methodName, methodHandle)`
+
+Adds a method to an object and disposes the method handle:
+
+```typescript
+const getMethod = context.newFunction('get', nameHandle => {
+  const name = context.dump(nameHandle);
+  return context.newString(getValue(name));
+});
+
+addMethod(context, headersHandle, 'get', getMethod);
+```
+
+## Creating a New Bridge
+
+### Example: Date API Bridge
+
+```typescript
+// src/sandbox/bridges/date.ts
+import type { BridgeContext } from './types.js';
+import { createSyncBridge, createAsyncBridge } from './utils.js';
+
+export function installDate(ctx: BridgeContext): void {
+  const { context, logger } = ctx;
+
+  // Simple sync function
+  const nowHandle = createSyncBridge(ctx, 'now', () => Date.now());
+  context.setProp(context.global, 'dateNow', nowHandle);
+  nowHandle.dispose();
+
+  // Async function with delay
+  const delayHandle = createAsyncBridge(ctx, 'delay', async (ms: number) => {
+    await new Promise(resolve => setTimeout(resolve, ms));
+    return `Delayed ${ms}ms`;
+  });
+  context.setProp(context.global, 'delay', delayHandle);
+  delayHandle.dispose();
+
+  logger?.info?.('[Bridge] Date API installed');
+}
+```
+
+### Example: ES6 Class Bridge
+
+```typescript
+// src/sandbox/bridges/timer.ts
+import type { BridgeContext } from './types.js';
+import { defineClass } from './utils.js';
+
+export function installTimer(ctx: BridgeContext): void {
+  const { context, logger } = ctx;
+
+  // Track timer instances
+  const timers = new Map<number, any>();
+  let timerIdCounter = 0;
+
+  // Host function to start timer
+  const startTimerHandle = context.newFunction('__hostStartTimer', msHandle => {
+    const ms = context.dump(msHandle);
+    const timerId = ++timerIdCounter;
+
+    const handle = setTimeout(() => {
+      timers.delete(timerId);
+    }, ms);
+
+    timers.set(timerId, handle);
+    return context.newNumber(timerId);
+  });
+
+  context.setProp(context.global, '__hostStartTimer', startTimerHandle);
+  startTimerHandle.dispose();
+
+  // Define Timer class
+  const classHandle = defineClass(
+    ctx,
+    `
+    class Timer {
+      constructor(ms) {
+        this.id = __hostStartTimer(ms);
+        this.ms = ms;
+      }
+      
+      getId() {
+        return this.id;
+      }
+    }
+  `,
+    'Timer'
+  );
+
+  if (classHandle) {
+    context.setProp(context.global, 'Timer', classHandle);
+    classHandle.dispose();
+    logger?.info?.('[Bridge] Timer installed');
+  }
+}
+```
+
+### Register in `bridges/index.ts`
+
+```typescript
+export { installDate } from './date.js';
+export { installTimer } from './timer.js';
+
+// Add to installAllBridges
+export function installAllBridges(ctx: BridgeContext): void {
+  installFetch(ctx);
+  installResponse(ctx);
+  installTextEncoder(ctx);
+  installTextDecoder(ctx);
+  installDate(ctx); // Add your bridge
+  installTimer(ctx); // Add your bridge
+
+  ctx.logger?.info?.('[Bridge] All bridges installed');
+}
+```
+
+## Existing Bridges
+
+### fetch (fetch.ts)
+
+Bridges runtime's native `fetch` API with:
+
+- Full Response object (status, headers, body)
+- Headers object with `get()`, `has()`, `entries()` methods
+- Body methods: `json()`, `text()`, `arrayBuffer()`
+- ReadableStream support for response.body
+
+**Usage in sandbox:**
+
+```javascript
+const res = await fetch('https://api.example.com/data');
+const data = await res.json();
+const contentType = res.headers.get('content-type');
+```
+
+### Response (response.ts)
+
+Provides `Response` constructor for creating Response objects manually with:
+
+- Same interface as browser Response API
+- Accepts body (string, ReadableStream, Uint8Array) and init options
+- Convenience methods for consuming ReadableStreams: `text()`, `json()`, `arrayBuffer()`
+- Useful for wrapping streams, testing, and creating mock responses
+
+**Usage in sandbox:**
+
+```javascript
+// Wrap a ReadableStream for easy consumption
+const stream = someAsyncFunction(); // Returns a ReadableStream
+const response = new Response(stream);
+const text = await response.text();
+
+// Create mock response for testing
+const mockResponse = new Response('Hello World', {
+  status: 200,
+  headers: { 'Content-Type': 'text/plain' }
+});
+const data = await mockResponse.text();
+
+// Create error response
+const errorResponse = new Response('Not found', {
+  status: 404,
+  statusText: 'Not Found'
+});
+```
+
+### Console (console.ts)
+
+Bridges runtime's `console` API with:
+
+- `console.log()` - Standard logging (shown in stdout)
+- `console.warn()` - Warning messages (prefixed with [WARN])
+- `console.error()` - Error messages (prefixed with [ERROR])
+- Output is captured and returned with sandbox execution result
+- Multiple arguments are formatted and joined
+
+**Usage in sandbox:**
+
+```javascript
+console.log('Processing data...');
+const data = await fetch('https://api.example.com/data');
+console.log('Fetched items:', data.length);
+console.warn('High memory usage');
+console.error('Failed to parse:', error);
+```
+
+**Output format:**
+When using the `run_code` tool, console output is formatted with return value:
+
+```
+[stdout]
+Processing data...
+Fetched items: 42
+
+[result]
+{ success: true, ... }
+```
+
+### TextEncoder (text-encoder.ts)
+
+Bridges runtime's `TextEncoder` for encoding strings to Uint8Array.
+
+**Usage in sandbox:**
+
+```javascript
+const encoder = new TextEncoder();
+const bytes = encoder.encode('Hello, World!');
+```
+
+### TextDecoder (text-decoder.ts)
+
+Bridges runtime's `TextDecoder` with stateful instance tracking for streaming decode.
+
+**Usage in sandbox:**
+
+```javascript
+const decoder = new TextDecoder();
+
+// Streaming decode
+const text1 = decoder.decode(chunk1, { stream: true });
+const text2 = decoder.decode(chunk2, { stream: true });
+const text3 = decoder.decode(); // Final flush
+```
+
+### ReadableStream (readable-stream.ts)
+
+Bridges runtime's `ReadableStream` for response.body streaming.
+
+**Usage in sandbox:**
+
+```javascript
+const reader = response.body.getReader();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  // Process chunk (Uint8Array)
+}
+reader.releaseLock();
+```
+
+## Benefits
+
+### 1. Modularity
+
+Each bridge is self-contained in its own file, making it easy to:
+
+- Understand what it does
+- Test in isolation
+- Modify without affecting others
+- Remove if not needed
+
+### 2. Reusability
+
+Common patterns are extracted to `utils.ts`:
+
+- `createAsyncBridge` - Standard async function pattern
+- `createSyncBridge` - Standard sync function pattern
+- `defineClass` - ES6 class definition pattern
+- `convertToHandle` - Type conversion pattern
+
+### 3. Consistency
+
+All bridges follow the same structure:
+
+1. Receive `BridgeContext`
+2. Create host functions if needed
+3. Define sandbox API
+4. Log installation
+
+### 4. Extensibility
+
+Adding new bridges is straightforward:
+
+1. Create new file in `bridges/`
+2. Export installation function
+3. Register in `bridges/index.ts`
+4. Document in this file
+
+### 5. Maintainability
+
+Before: 885 lines in one function
+After: 450 lines in sandbox.ts + focused bridge modules
+
+## Common Patterns
+
+### Pattern 1: Simple Sync Function
+
+```typescript
+const fnHandle = createSyncBridge(ctx, 'funcName', (arg1, arg2) => {
+  return result;
+});
+context.setProp(context.global, 'funcName', fnHandle);
+fnHandle.dispose();
+```
+
+### Pattern 2: Async Function with Promise Tracking
+
+```typescript
+const fnHandle = createAsyncBridge(ctx, 'asyncFunc', async arg => {
+  const result = await someAsyncOperation(arg);
+  return result;
+});
+context.setProp(context.global, 'asyncFunc', fnHandle);
+fnHandle.dispose();
+```
+
+### Pattern 3: Stateful Instance Management
+
+```typescript
+const instances = new Map<number, InstanceType>();
+let idCounter = 0;
+
+const createHandle = context.newFunction('__hostCreate', () => {
+  const instance = new InstanceType();
+  const id = ++idCounter;
+  instances.set(id, instance);
+  return context.newNumber(id);
+});
+
+const useHandle = context.newFunction('__hostUse', idHandle => {
+  const id = context.dump(idHandle);
+  const instance = instances.get(id);
+  return instance.doSomething();
+});
+```
+
+### Pattern 4: ES6 Class with Host Methods
+
+```typescript
+// Register host methods
+context.setProp(context.global, '__hostCreate', createHandle);
+context.setProp(context.global, '__hostMethod', methodHandle);
+
+// Define class that uses host methods
+const classHandle = defineClass(
+  ctx,
+  `
+  class MyClass {
+    constructor(arg) {
+      this.id = __hostCreate(arg);
+    }
+    method() {
+      return __hostMethod(this.id);
+    }
+  }
+`,
+  'MyClass'
+);
+
+context.setProp(context.global, 'MyClass', classHandle);
+classHandle.dispose();
+```
+
+## Promise Tracking
+
+All async operations are automatically tracked via `BridgeContext.tracker`:
+
+```typescript
+interface PromiseTracker {
+  pendingPromises: Set<Promise<void>>; // Active promises
+  notifyNewPromise: () => void; // Signal new promise
+  newPromiseSignal: Promise<void>; // Wait for new promise
+  deferredPromises: Set<any>; // Cleanup tracking
+}
+```
+
+The `createAsyncBridge` utility handles tracking automatically. Manual tracking:
+
+```typescript
+const deferred = context.newPromise();
+tracker.deferredPromises.add(deferred);
+
+const hostPromise = someAsyncOp()
+  .then(result => {
+    deferred.resolve(convertToHandle(context, result));
+    runtime.executePendingJobs();
+  })
+  .finally(() => {
+    tracker.pendingPromises.delete(hostPromise);
+  });
+
+tracker.pendingPromises.add(hostPromise);
+tracker.notifyNewPromise();
+```
+
+## Testing Bridges
+
+Create focused tests for each bridge:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { createPromiseTracker, installDate } from '../src/sandbox/bridges/index.js';
+
+describe('Date bridge', () => {
+  it('should provide dateNow function', async () => {
+    // Setup context and tracker
+    const tracker = createPromiseTracker();
+    const ctx = { context, runtime, tracker };
+
+    // Install bridge
+    installDate(ctx);
+
+    // Test functionality
+    const result = context.evalCode('dateNow()');
+    expect(result.value).toBeGreaterThan(0);
+  });
+});
+```
+
+## Performance Considerations
+
+### Minimize Handle Creation
+
+```typescript
+// Bad - creates many handles
+for (const item of items) {
+  const handle = context.newString(item);
+  // ... use handle
+  handle.dispose();
+}
+
+// Good - batch operations
+const arrayHandle = context.newArray();
+for (let i = 0; i < items.length; i++) {
+  const itemHandle = context.newString(items[i]);
+  context.setProp(arrayHandle, i, itemHandle);
+  itemHandle.dispose();
+}
+```
+
+### Dispose Immediately
+
+```typescript
+// Dispose handles as soon as they're no longer needed
+const handle = context.newString('value');
+context.setProp(obj, 'key', handle);
+handle.dispose(); // Dispose immediately after setting
+```
+
+### Use Batch Utilities
+
+```typescript
+// Use setProperties for multiple values
+setProperties(context, handle, {
+  prop1: value1,
+  prop2: value2,
+  prop3: value3
+});
+```
+
+## See Also
+
+- [Fetch API Documentation](../docs/FETCH_API.md)
+- [Sandbox Architecture](../docs/SANDBOX_FETCH_ARCHITECTURE.md)