@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/readable-stream.ts

@@ -0,0 +1,323 @@
+/**
+ * ReadableStream bridge - Bridges runtime's ReadableStream for response.body
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import { unwrapResult } from './shared/index.js';
+
+// Internal symbol name for cached Uint8Array wrapper on context global
+const UINT8_WRAPPER_CACHE_KEY = '__cachedUint8ArrayWrapper';
+
+// Minimum chunk size before passing to QuickJS (16KB)
+// This reduces boundary crossing overhead for streams with many small chunks
+const MIN_CHUNK_SIZE = 16 * 1024;
+
+/**
+ * Get or create a cached Uint8Array wrapper function for the context.
+ * This avoids the expensive evalCode() call on every read().
+ *
+ * The cached wrapper is stored on the context's global object, so it's
+ * automatically cleaned up when the context is disposed.
+ */
+function getUint8ArrayWrapper(ctx: BridgeContext): QuickJSHandle {
+  const { context } = ctx;
+
+  // Check if we already cached the wrapper on the global
+  const cachedHandle = context.getProp(context.global, UINT8_WRAPPER_CACHE_KEY);
+  const cachedType = context.typeof(cachedHandle);
+
+  if (cachedType === 'function') {
+    // Already cached - return it (caller must dispose)
+    return cachedHandle;
+  }
+
+  // Not cached yet - dispose the undefined handle we got
+  cachedHandle.dispose();
+
+  // Create the wrapper function once - this evalCode is amortized over all reads
+  const wrapper = unwrapResult(
+    context.evalCode('(function(ab) { return new Uint8Array(ab); })'),
+    context
+  );
+
+  // Store on global for future calls — non-enumerable to hide from sandbox code
+  context.setProp(context.global, UINT8_WRAPPER_CACHE_KEY, wrapper);
+  {
+    const hideResult = context.evalCode(`
+      try {
+        Object.defineProperty(globalThis, '${UINT8_WRAPPER_CACHE_KEY}', {
+          enumerable: false, writable: false, configurable: false
+        });
+      } catch(e) {}
+      undefined;
+    `);
+    if (hideResult.error) {
+      hideResult.error.dispose();
+    } else {
+      (hideResult as { value: QuickJSHandle }).value.dispose();
+    }
+  }
+
+  // Return the handle - caller must dispose their reference
+  return wrapper;
+}
+
+/**
+ * Coalescing reader that buffers small chunks before passing to QuickJS.
+ * Reduces boundary crossing overhead for streams with many small chunks.
+ */
+class CoalescingReader {
+  private buffer: Uint8Array[] = [];
+  private bufferSize = 0;
+  private done = false;
+
+  constructor(
+    private hostReader: ReadableStreamDefaultReader<Uint8Array>,
+    private minChunkSize: number = MIN_CHUNK_SIZE
+  ) {}
+
+  /**
+   * Read and coalesce chunks until we have at least minChunkSize bytes or stream ends
+   */
+  async read(): Promise<ReadableStreamReadResult<Uint8Array>> {
+    // If we already know the stream is done, return done
+    if (this.done && this.bufferSize === 0) {
+      return { done: true, value: undefined };
+    }
+
+    try {
+      // Keep reading until we have enough data or stream ends
+      while (!this.done && this.bufferSize < this.minChunkSize) {
+        const result = await this.hostReader.read();
+
+        if (result.done) {
+          this.done = true;
+          break;
+        }
+
+        if (result.value && result.value.length > 0) {
+          this.buffer.push(result.value);
+          this.bufferSize += result.value.length;
+        }
+      }
+
+      // If we have no data and stream is done, return done
+      if (this.bufferSize === 0) {
+        return { done: true, value: undefined };
+      }
+
+      // Coalesce buffered chunks into a single Uint8Array
+      let value: Uint8Array;
+      if (this.buffer.length === 1) {
+        // Optimization: no copy needed for single chunk
+        value = this.buffer[0]!;
+      } else {
+        // Merge multiple chunks
+        value = new Uint8Array(this.bufferSize);
+        let offset = 0;
+        for (const chunk of this.buffer) {
+          value.set(chunk, offset);
+          offset += chunk.length;
+        }
+      }
+
+      // Clear buffer
+      this.buffer = [];
+      this.bufferSize = 0;
+
+      return { done: false, value };
+    } catch (e) {
+      // Reset state on error to avoid returning stale data on retry
+      this.buffer = [];
+      this.bufferSize = 0;
+      this.done = true;
+      throw e;
+    }
+  }
+
+  releaseLock(): void {
+    this.hostReader.releaseLock();
+  }
+}
+
+/**
+ * Create a bridged ReadableStreamReader object
+ */
+export function createReaderObject(
+  ctx: BridgeContext,
+  hostReader: ReadableStreamDefaultReader<Uint8Array>
+): QuickJSHandle {
+  const { context, runtime, tracker } = ctx;
+  const readerHandle = context.newObject();
+
+  // Wrap in coalescing reader to reduce boundary crossings
+  const coalescingReader = new CoalescingReader(hostReader);
+
+  // Create read() method
+  {
+    using readMethod = context.newFunction('read', () => {
+      const deferred = context.newPromise();
+      tracker.deferredPromises.add(deferred);
+
+      const hostPromise = coalescingReader
+        .read()
+        .then((result: ReadableStreamReadResult<Uint8Array>) => {
+          try {
+            // Create result object: { done: boolean, value?: Uint8Array }
+            const resultHandle = context.newObject();
+
+            context.setProp(resultHandle, 'done', result.done ? context.true : context.false);
+
+            if (result.value) {
+              // Create a Uint8Array in QuickJS from the ArrayBuffer
+              // Use slice to handle Uint8Array views into larger ArrayBuffers (e.g. Node.js Buffer)
+              const buf =
+                result.value.byteOffset === 0 &&
+                result.value.byteLength === result.value.buffer.byteLength
+                  ? result.value.buffer
+                  : result.value.buffer.slice(
+                      result.value.byteOffset,
+                      result.value.byteOffset + result.value.byteLength
+                    );
+              using arrayBufferHandle = context.newArrayBuffer(buf);
+
+              // Use cached wrapper function instead of evalCode on every read
+              using wrapperFn = getUint8ArrayWrapper(ctx);
+
+              using uint8ArrayHandle = unwrapResult(
+                context.callFunction(wrapperFn, context.undefined, arrayBufferHandle),
+                context
+              );
+              context.setProp(resultHandle, 'value', uint8ArrayHandle);
+            }
+
+            deferred.resolve(resultHandle);
+            resultHandle.dispose();
+            runtime.executePendingJobs();
+          } catch (e) {
+            using errHandle = context.newString(e instanceof Error ? e.message : String(e));
+            deferred.reject(errHandle);
+            runtime.executePendingJobs();
+          }
+        })
+        .catch((err: Error) => {
+          try {
+            using errHandle = context.newString(err.message || String(err));
+            deferred.reject(errHandle);
+            runtime.executePendingJobs();
+          } catch {
+            // Context may have been disposed
+          }
+        })
+        .finally(() => {
+          tracker.pendingPromises.delete(hostPromise);
+          tracker.deferredPromises.delete(deferred);
+        });
+
+      // Track for cleanup and race optimization
+      tracker.pendingPromises.add(hostPromise);
+      tracker.notifyNewPromise();
+
+      return deferred.handle;
+    });
+    context.setProp(readerHandle, 'read', readMethod);
+  }
+
+  // Create releaseLock() method
+  {
+    using releaseLockMethod = context.newFunction('releaseLock', () => {
+      try {
+        coalescingReader.releaseLock();
+        return context.undefined;
+      } catch (e) {
+        return context.newError(e instanceof Error ? e.message : String(e));
+      }
+    });
+    context.setProp(readerHandle, 'releaseLock', releaseLockMethod);
+  }
+
+  return readerHandle;
+}
+
+/**
+ * Create a bridged ReadableStream object
+ */
+export function createStreamObject(
+  ctx: BridgeContext,
+  hostStream: ReadableStream,
+  streamId: number,
+  hostReaders: Map<number, ReadableStreamDefaultReader>,
+  readerIdCounter: { value: number }
+): QuickJSHandle {
+  const { context } = ctx;
+  const streamHandle = context.newObject();
+
+  // Create getReader() method
+  {
+    using getReaderMethod = context.newFunction('getReader', () => {
+      try {
+        const hostReader = hostStream.getReader();
+        const readerId = ++readerIdCounter.value;
+        hostReaders.set(readerId, hostReader);
+
+        return createReaderObject(ctx, hostReader);
+      } catch (e) {
+        return context.newError(e instanceof Error ? e.message : String(e));
+      }
+    });
+    context.setProp(streamHandle, 'getReader', getReaderMethod);
+  }
+
+  // Create a host function to get the locked state dynamically
+  {
+    using getLockedFn = context.newFunction('__getLockedFn', () => {
+      return hostStream.locked ? context.true : context.false;
+    });
+
+    // Store the function on the stream object itself (scoped to this stream)
+    context.setProp(streamHandle, '__getLockedFn', getLockedFn);
+  }
+
+  // Define the 'locked' property as a getter using Object.defineProperty
+  const defineCode = `
+		(function(stream) {
+			var fn = stream.__getLockedFn;
+			Object.defineProperty(stream, 'locked', {
+				get: function() { return fn(); },
+				enumerable: true,
+				configurable: true
+			});
+			delete stream.__getLockedFn;  // Clean up the visible property
+			return stream;
+		})
+	`;
+
+  const defineResult = context.evalCode(defineCode);
+
+  if (defineResult.error) {
+    // If we can't define the getter, fall back to static property
+    const error = context.dump(defineResult.error);
+    defineResult.error.dispose();
+    ctx.logger?.warn?.(`[ReadableStream] Could not define locked getter: ${JSON.stringify(error)}`);
+    context.setProp(streamHandle, 'locked', hostStream.locked ? context.true : context.false);
+  } else {
+    // Apply the function to our stream handle
+    using defineFunc = defineResult.value;
+    const applyResult = context.callFunction(defineFunc, context.undefined, streamHandle);
+
+    if (applyResult.error) {
+      const error = context.dump(applyResult.error);
+      applyResult.error.dispose();
+      ctx.logger?.warn?.(
+        `[ReadableStream] Could not apply locked getter: ${JSON.stringify(error)}`
+      );
+      // Fallback to static property
+      context.setProp(streamHandle, 'locked', hostStream.locked ? context.true : context.false);
+    } else {
+      (applyResult as { value: QuickJSHandle }).value.dispose();
+    }
+  }
+
+  return streamHandle;
+}

package/src/sandbox/bridges/response.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from 'vitest';
+import { executeWithAsyncHost } from '../test-helper.js';
+
+describe('Response Bridge', () => {
+  it('should provide Response constructor', async () => {
+    const result = await executeWithAsyncHost(`return typeof Response`, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('function');
+  });
+
+  it('should create Response from string', async () => {
+    const code = `
+      const res = new Response('Hello World');
+      return {
+        status: res.status,
+        ok: res.ok,
+        statusText: res.statusText
+      }
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    if (!result.success) {
+      console.error('Error:', result.error);
+    }
+
+    expect(result.success).toBe(true);
+    expect(result.result.status).toBe(200);
+    expect(result.result.ok).toBe(true);
+    expect(result.result.statusText).toBe('');
+  });
+
+  it('should create Response with custom status', async () => {
+    const code = `
+      const res = new Response('Not found', { status: 404 });
+      return res.status
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe(404);
+  });
+
+  it('should consume response body as text', async () => {
+    const code = `
+      const res = new Response('Hello World');
+      const text = await res.text();
+      return text
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('Hello World');
+  });
+
+  it('should consume response body as JSON', async () => {
+    const code = `
+      const res = new Response('{"message":"Hello"}');
+      const json = await res.json();
+      return json
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toEqual({ message: 'Hello' });
+  });
+
+  it('should create Response with custom headers', async () => {
+    const code = `
+      const res = new Response('data', {
+        headers: { 'Content-Type': 'text/plain', 'X-Custom': 'value' }
+      });
+      return {
+        contentType: res.headers.get('Content-Type'),
+        custom: res.headers.get('X-Custom')
+      }
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result.contentType).toBe('text/plain');
+    expect(result.result.custom).toBe('value');
+  });
+
+  it('should support has() method on headers', async () => {
+    const code = `
+      const res = new Response('data', {
+        headers: { 'Content-Type': 'text/plain' }
+      });
+      return res.headers.has('Content-Type')
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe(true);
+  });
+
+  it('should support entries() method on headers', async () => {
+    const code = `
+      const res = new Response('data', {
+        headers: { 'content-type': 'text/plain', 'x-custom': 'value' }
+      });
+      const entries = res.headers.entries();
+      return entries
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result.length).toBeGreaterThanOrEqual(2);
+    // Check that our headers are present (Headers normalizes to lowercase)
+    const entries = result.result;
+    const hasContentType = entries.some(
+      (e: string[]) => e[0].toLowerCase() === 'content-type' && e[1] === 'text/plain'
+    );
+    const hasCustom = entries.some(
+      (e: string[]) => e[0].toLowerCase() === 'x-custom' && e[1] === 'value'
+    );
+    expect(hasContentType).toBe(true);
+    expect(hasCustom).toBe(true);
+  });
+
+  it('should support ok property based on status', async () => {
+    const code = `
+      const okRes = new Response('good', { status: 200 });
+      const notOkRes = new Response('bad', { status: 404 });
+      return { ok: okRes.ok, notOk: notOkRes.ok }
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result.ok).toBe(true);
+    expect(result.result.notOk).toBe(false);
+  });
+
+  it('should support custom statusText', async () => {
+    const code = `
+      const res = new Response('Error', { status: 500, statusText: 'Internal Server Error' });
+      return res.statusText
+    `;
+
+    const result = await executeWithAsyncHost(code, {});
+
+    expect(result.success).toBe(true);
+    expect(result.result).toBe('Internal Server Error');
+  });
+});

package/src/sandbox/bridges/response.ts

@@ -0,0 +1,123 @@
+/**
+ * Response API bridge - Provides Response constructor for sandbox
+ *
+ * Allows creating Response objects manually, useful for:
+ * - Consuming ReadableStreams with .text(), .json(), .arrayBuffer() methods
+ * - Creating mock responses for testing
+ * - Handlers that need to return Response objects
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import {
+  createResponseObject,
+  setupStreamRegistry,
+  unwrapResult
+} from './shared/index.js';
+
+/**
+ * Install Response constructor in the sandbox
+ */
+export function installResponse(ctx: BridgeContext): void {
+  const { context, logger } = ctx;
+
+  // Create response object context for the factory (includes cleanup handler)
+  const objCtx = setupStreamRegistry(ctx, 'Response');
+
+  // Create host function to create Response
+  {
+    using hostCreateResponse = context.newFunction(
+      '__hostCreateResponse',
+      (bodyHandle?: QuickJSHandle, initHandle?: QuickJSHandle) => {
+        // Parse body argument
+        let body: BodyInit | null = null;
+        if (bodyHandle) {
+          const bodyValue = context.dump(bodyHandle);
+          // Check if it's a ReadableStream (has a _streamId property)
+          if (bodyValue && typeof bodyValue === 'object' && typeof bodyValue._streamId === 'number') {
+            const stream = objCtx.registry.hostStreams.get(bodyValue._streamId);
+            if (!stream) {
+              throw new Error(`Invalid stream ID: ${bodyValue._streamId}. Stream may have been consumed or cleaned up.`);
+            }
+            body = stream;
+          } else if (
+            bodyValue &&
+            typeof bodyValue === 'object' &&
+            'byteLength' in bodyValue &&
+            'buffer' in bodyValue &&
+            typeof (bodyValue as any).byteLength === 'number' &&
+            (bodyValue as any).byteLength >= 0
+          ) {
+            // It's a Uint8Array or ArrayBufferView - cast to BodyInit
+            body = bodyValue as BodyInit;
+          } else {
+            body = bodyValue as BodyInit;
+          }
+        }
+
+        // Parse init argument
+        let init: ResponseInit = {};
+        if (initHandle) {
+          try {
+            init = context.dump(initHandle) || {};
+          } catch {
+            // Invalid init object, use defaults
+          }
+        }
+
+        // Create host Response
+        const hostResponse = new Response(body, init);
+
+        // Create QuickJS Response object using the unified factory
+        return createResponseObject(ctx, { response: hostResponse }, objCtx);
+      }
+    );
+
+    context.setProp(context.global, '__hostCreateResponse', hostCreateResponse);
+  }
+
+  // Define Response class in QuickJS
+  const classCode = `
+		class Response {
+			constructor(body, init) {
+				const response = __hostCreateResponse(body, init);
+				// Copy all properties from the response to this
+				this.status = response.status;
+				this.statusText = response.statusText;
+				this.ok = response.ok;
+				this.url = response.url;
+				this.type = response.type;
+				this.redirected = response.redirected;
+				this.body = response.body;
+				this.headers = response.headers;
+				this.json = response.json.bind(response);
+				this.text = response.text.bind(response);
+				this.arrayBuffer = response.arrayBuffer.bind(response);
+			}
+		}
+	`;
+
+  {
+    using classHandle = unwrapResult(context.evalCode(classCode), context);
+    context.setProp(context.global, 'Response', classHandle);
+
+    // Hide internal helper from sandbox code
+    // NOTE: The sandbox is not a hard security boundary. Internal helpers are hidden via
+    // enumerable: false to prevent accidental access, but can still be called by name if
+    // the sandbox code knows them. This is acceptable because:
+    // 1. The bridges are the primary security boundary, not QuickJS containment
+    // 2. Internal helpers don't expose dangerous capabilities beyond what bridges already provide
+    // 3. For the use case of safely executing LLM-generated code, this is sufficient
+    // See Sandbox.ts for the full security model documentation.
+    const hideResult = context.evalCode(`(function() {
+      try { Object.defineProperty(globalThis, '__hostCreateResponse', { enumerable: false, writable: false, configurable: false }); } catch(e) {}
+    })()`);
+    if (hideResult.error) {
+      hideResult.error.dispose();
+    } else {
+      (hideResult as { value: QuickJSHandle }).value.dispose();
+    }
+  }
+
+  logger?.info?.('[Bridge] Response constructor installed');
+}