@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/shared/headers.ts

@@ -0,0 +1,181 @@
+/**
+ * Shared Headers object creation for fetch and Response bridges
+ *
+ * Backed by a host Headers object. Mutation methods (set, append, delete)
+ * update both the host Headers and the direct-access properties on the
+ * QuickJS handle so the two views stay in sync.
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import { Scope, isFail } from 'quickjs-emscripten-core';
+import type { BridgeContext } from '../types.js';
+
+/**
+ * Create a Headers object with full Web API support:
+ * get(), has(), set(), append(), delete(), entries(), forEach(), keys(), values()
+ *
+ * Mutations go through the host Headers object and are synced back to
+ * direct-access properties on the QuickJS handle.
+ */
+export function createHeadersObject(
+  ctx: BridgeContext,
+  headers: Headers | Record<string, string> | undefined
+): QuickJSHandle {
+  const { context } = ctx;
+  const headersHandle = context.newObject();
+
+  if (!headers) {
+    return headersHandle;
+  }
+
+  // Convert to Headers object if it's a plain record
+  const headersObj = headers instanceof Headers ? headers : new Headers(headers);
+
+  // Set header properties for direct access
+  headersObj.forEach((value: string, name: string) => {
+    using valueHandle = context.newString(value);
+    context.setProp(headersHandle, name, valueHandle);
+  });
+
+  // Add get() method
+  {
+    using getMethod = context.newFunction('get', (nameHandle: QuickJSHandle) => {
+      const name = context.dump(nameHandle);
+      const value = headersObj.get(name);
+      if (value === null) {
+        return context.null;
+      }
+      return context.newString(value);
+    });
+    context.setProp(headersHandle, 'get', getMethod);
+  }
+
+  // Add has() method
+  {
+    using hasMethod = context.newFunction('has', (nameHandle: QuickJSHandle) => {
+      const name = context.dump(nameHandle);
+      return headersObj.has(name) ? context.true : context.false;
+    });
+    context.setProp(headersHandle, 'has', hasMethod);
+  }
+
+  // Add set() method - replaces the value for a header
+  {
+    using setMethod = context.newFunction(
+      'set',
+      (nameHandle: QuickJSHandle, valueHandle: QuickJSHandle) => {
+        const name = context.dump(nameHandle) as string;
+        const value = context.dump(valueHandle) as string;
+        headersObj.set(name, value);
+        // Sync the direct-access property
+        using newValueHandle = context.newString(headersObj.get(name)!);
+        context.setProp(headersHandle, name.toLowerCase(), newValueHandle);
+        return context.undefined;
+      }
+    );
+    context.setProp(headersHandle, 'set', setMethod);
+  }
+
+  // Add append() method - appends a value (multi-value headers like Set-Cookie)
+  {
+    using appendMethod = context.newFunction(
+      'append',
+      (nameHandle: QuickJSHandle, valueHandle: QuickJSHandle) => {
+        const name = context.dump(nameHandle) as string;
+        const value = context.dump(valueHandle) as string;
+        headersObj.append(name, value);
+        // Sync the direct-access property (combined value with ", " per spec)
+        const combined = headersObj.get(name.toLowerCase());
+        if (combined !== null) {
+          using combinedHandle = context.newString(combined);
+          context.setProp(headersHandle, name.toLowerCase(), combinedHandle);
+        }
+        return context.undefined;
+      }
+    );
+    context.setProp(headersHandle, 'append', appendMethod);
+  }
+
+  // Add delete() method - removes a header entirely
+  {
+    using deleteMethod = context.newFunction('delete', (nameHandle: QuickJSHandle) => {
+      const name = context.dump(nameHandle) as string;
+      headersObj.delete(name);
+      context.setProp(headersHandle, name.toLowerCase(), context.undefined);
+      return context.undefined;
+    });
+    context.setProp(headersHandle, 'delete', deleteMethod);
+  }
+
+  // Add entries() method that returns an array
+  {
+    using entriesMethod = context.newFunction('entries', () => {
+      const entriesArray = context.newArray();
+      let index = 0;
+      headersObj.forEach((value: string, name: string) => {
+        // Use Scope for per-iteration cleanup of intermediate handles
+        Scope.withScope((scope) => {
+          const tuple = scope.manage(context.newArray());
+          const nameH = scope.manage(context.newString(name));
+          const valueH = scope.manage(context.newString(value));
+          context.setProp(tuple, 0, nameH);
+          context.setProp(tuple, 1, valueH);
+          context.setProp(entriesArray, index, tuple);
+        });
+        index++;
+      });
+      return entriesArray;
+    });
+    context.setProp(headersHandle, 'entries', entriesMethod);
+  }
+
+  // Add forEach() method - commonly used
+  {
+    using forEachMethod = context.newFunction('forEach', (callbackHandle: QuickJSHandle) => {
+      headersObj.forEach((value: string, name: string) => {
+        using valueH = context.newString(value);
+        using nameH = context.newString(name);
+        // Call the callback with (value, name) - matches Headers.forEach signature
+        const callResult = context.callFunction(callbackHandle, context.undefined, valueH, nameH);
+        // Dispose the return value of the callback
+        if (isFail(callResult)) {
+          callResult.error.dispose();
+        } else {
+          callResult.value.dispose();
+        }
+      });
+      return context.undefined;
+    });
+    context.setProp(headersHandle, 'forEach', forEachMethod);
+  }
+
+  // Add keys() method - returns array of header names
+  {
+    using keysMethod = context.newFunction('keys', () => {
+      const keysArray = context.newArray();
+      let index = 0;
+      headersObj.forEach((_: string, name: string) => {
+        using nameHandle = context.newString(name);
+        context.setProp(keysArray, index++, nameHandle);
+      });
+      return keysArray;
+    });
+    context.setProp(headersHandle, 'keys', keysMethod);
+  }
+
+  // Add values() method - returns array of header values
+  {
+    using valuesMethod = context.newFunction('values', () => {
+      const valuesArray = context.newArray();
+      let index = 0;
+      headersObj.forEach((value: string, _: string) => {
+        using valueHandle = context.newString(value);
+        context.setProp(valuesArray, index++, valueHandle);
+      });
+      return valuesArray;
+    });
+    context.setProp(headersHandle, 'values', valuesMethod);
+  }
+
+  return headersHandle;
+}

package/src/sandbox/bridges/shared/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared bridge utilities
+ */
+
+export { convertToHandle } from './convert.js';
+export { unwrapResult } from './scope-helpers.js';
+export { createHeadersObject } from './headers.js';
+export { attachBodyMethods } from './body-methods.js';
+export {
+  createStreamCleanupHandler,
+  createIdCounter,
+  nextId,
+  type StreamRegistry
+} from './cleanup.js';
+export { getJsonParse, parseJsonInContext } from './json-helpers.js';
+export {
+  createResponseObject,
+  attachStreamBodyMethods,
+  type ResponseObjectOptions,
+  type ResponseObjectContext
+} from './response-object.js';
+export {
+  withTrackedPromise,
+  withTrackedPromiseResult,
+  withTrackedPromiseValue
+} from './promise-helper.js';
+export { setupStreamRegistry, setupSimpleStreamRegistry } from './registry-setup.js';
+export { parseMountPath, type ParsedPath } from './path-parser.js';
+export {
+  createListResult,
+  createSuccessResult,
+  createSuccessResultWithKey,
+  createSuccessResultWithMetadata,
+  type FileEntry
+} from './result-builder.js';
+export { createReaderHandle } from './stream-reader.js';

package/src/sandbox/bridges/shared/json-helpers.ts

@@ -0,0 +1,77 @@
+/**
+ * Shared JSON parsing utilities for QuickJS bridges
+ * Provides cached JSON.parse access to avoid repeated evalCode calls
+ */
+
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten-core';
+
+// Internal symbol name for cached JSON.parse on context global
+const JSON_PARSE_CACHE_KEY = '__cachedJsonParse';
+
+/**
+ * Get or create a cached JSON.parse reference for the context.
+ * Returns a handle - caller must dispose.
+ *
+ * This avoids evalCode on every JSON parse operation.
+ * The cached handle is stored on the context's global object, so it's
+ * automatically cleaned up when the context is disposed.
+ */
+export function getJsonParse(context: QuickJSContext): QuickJSHandle {
+  // Check if we already cached JSON.parse on the global
+  const cachedHandle = context.getProp(context.global, JSON_PARSE_CACHE_KEY);
+  const cachedType = context.typeof(cachedHandle);
+
+  if (cachedType === 'function') {
+    // Already cached - return (caller must dispose)
+    return cachedHandle;
+  }
+
+  // Not cached yet - dispose the undefined handle we got
+  cachedHandle.dispose();
+
+  // Get JSON.parse from the context
+  {
+    using jsonHandle = context.getProp(context.global, 'JSON');
+    const jsonParse = context.getProp(jsonHandle, 'parse');
+
+    // Store on global for future calls — use Object.defineProperty to make it
+    // non-enumerable (hidden from Object.keys/for-in) and non-writable
+    // (sandbox code can't tamper with it)
+    context.setProp(context.global, JSON_PARSE_CACHE_KEY, jsonParse);
+    const hideResult = context.evalCode(`
+      try {
+        Object.defineProperty(globalThis, '${JSON_PARSE_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 jsonParse;
+  }
+}
+
+/**
+ * Parse a JSON string in QuickJS context.
+ * Returns the parsed handle or throws on error.
+ * Caller must dispose the returned handle.
+ */
+export function parseJsonInContext(context: QuickJSContext, jsonString: string): QuickJSHandle {
+  using jsonParse = getJsonParse(context);
+  using jsonStrHandle = context.newString(jsonString);
+  const result = context.callFunction(jsonParse, context.undefined, jsonStrHandle);
+
+  if (result.error) {
+    const error = context.dump(result.error);
+    result.error.dispose();
+    throw new Error(`JSON parse failed: ${JSON.stringify(error)}`);
+  }
+
+  return (result as { value: QuickJSHandle }).value;
+}

package/src/sandbox/bridges/shared/path-parser.ts

@@ -0,0 +1,109 @@
+/**
+ * Unified path parser for mount-based paths.
+ *
+ * Handles /mount-name/path/to/resource format consistently across all bridges.
+ * Reduces ~80 lines of duplicated path parsing code.
+ */
+
+/**
+ * Parsed path result containing the mount and resource path
+ */
+export interface ParsedPath<T> {
+  mount: T;
+  resourcePath: string;
+}
+
+/**
+ * Normalize a resource path by resolving `.` and `..` segments.
+ * Rejects any attempt to traverse above the mount root.
+ *
+ * @param resourcePath - The raw resource path (after mount name extraction)
+ * @param fullPath - The original full path (for error messages)
+ * @param mountTypeName - Name for error messages (e.g., "Bucket", "Storage")
+ * @returns Normalized path with no `.` or `..` segments
+ * @throws Error if path attempts to traverse above the mount root
+ */
+function normalizeResourcePath(
+  resourcePath: string,
+  fullPath: string,
+  mountTypeName: string
+): string {
+  const segments = resourcePath.split('/');
+  const normalized: string[] = [];
+
+  for (const segment of segments) {
+    if (segment === '..') {
+      if (normalized.length === 0) {
+        throw new Error(
+          `Invalid ${mountTypeName} path: ${fullPath}. Path traversal beyond mount root is not allowed`
+        );
+      }
+      normalized.pop();
+    } else if (segment !== '.' && segment !== '') {
+      normalized.push(segment);
+    }
+  }
+
+  return normalized.join('/');
+}
+
+/**
+ * Parse a mount-based path like "/mount-name/path/to/resource"
+ *
+ * @param path - The full path to parse
+ * @param mounts - Map of mount name to mount info
+ * @param mountTypeName - Name for error messages (e.g., "Bucket", "Storage")
+ * @param requireResourcePath - Whether the path must have a resource path (default: false)
+ * @returns Parsed path with mount and resource path
+ * @throws Error if path is invalid, mount not found, or path traversal attempted
+ */
+export function parseMountPath<T>(
+  path: string,
+  mounts: Map<string, T>,
+  mountTypeName: string,
+  requireResourcePath: boolean = false
+): ParsedPath<T> {
+  if (!path.startsWith('/')) {
+    throw new Error(`Invalid ${mountTypeName} path: ${path}. Paths must start with /`);
+  }
+
+  const withoutSlash = path.slice(1);
+
+  if (!withoutSlash) {
+    throw new Error(`Invalid ${mountTypeName} path: ${path}. Path must include a mount name`);
+  }
+
+  const slashIndex = withoutSlash.indexOf('/');
+
+  let mountName: string;
+  let resourcePath: string;
+
+  if (slashIndex === -1) {
+    // Just /mount-name with no resource path
+    mountName = withoutSlash;
+    resourcePath = '';
+
+    if (requireResourcePath) {
+      throw new Error(
+        `Invalid ${mountTypeName} path: ${path}. Expected /mount-name/path but got only mount name`
+      );
+    }
+  } else {
+    mountName = withoutSlash.slice(0, slashIndex);
+    resourcePath = normalizeResourcePath(
+      withoutSlash.slice(slashIndex + 1),
+      path,
+      mountTypeName
+    );
+  }
+
+  const mount = mounts.get(mountName);
+  if (!mount) {
+    const available = Array.from(mounts.keys()).join(', ');
+    throw new Error(
+      `${mountTypeName} mount not found: ${mountName}. Available: ${available || 'none'}`
+    );
+  }
+
+  return { mount, resourcePath };
+}

package/src/sandbox/bridges/shared/promise-helper.ts

@@ -0,0 +1,108 @@
+/**
+ * Promise helper utilities for QuickJS bridges
+ *
+ * Eliminates the boilerplate of deferred promises, tracking, and error handling
+ * that's repeated in every async bridge method.
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from '../types.js';
+import { convertToHandle } from './convert.js';
+
+/**
+ * Wraps an async operation with automatic promise tracking and error handling.
+ *
+ * This eliminates 20+ lines of boilerplate from every async bridge method:
+ * - Creates deferred promise
+ * - Adds to tracker
+ * - Runs async function with try/catch
+ * - Handles resolve/reject with proper handle disposal
+ * - Cleans up promise tracking
+ * - Notifies promise tracker
+ *
+ * @param ctx - Bridge context
+ * @param fn - Async function that receives the deferred promise handle
+ * @returns QuickJS handle to the promise
+ */
+export function withTrackedPromise(
+  ctx: BridgeContext,
+  fn: (deferred: any) => Promise<void>
+): QuickJSHandle {
+  const { context, runtime, tracker } = ctx;
+  const deferred = context.newPromise();
+  tracker.deferredPromises.add(deferred);
+
+  const hostPromise = (async () => {
+    try {
+      await fn(deferred);
+    } catch (e: unknown) {
+      // Handle errors by rejecting the deferred promise
+      try {
+        const errHandle = context.newString(e instanceof Error ? e.message : String(e));
+        deferred.reject(errHandle);
+        errHandle.dispose();
+        runtime.executePendingJobs();
+      } catch (rejectError) {
+        // Context is likely disposed — deferred will be cleaned up by sandbox cleanup
+        ctx.logger?.error?.('[Bridge] Failed to reject promise in withTrackedPromise', {
+          originalError: e,
+          rejectError
+        });
+      }
+      // Don't rethrow - we've already handled it by rejecting the deferred promise
+    }
+  })().finally(() => {
+    tracker.pendingPromises.delete(hostPromise);
+    tracker.deferredPromises.delete(deferred);
+  });
+
+  tracker.pendingPromises.add(hostPromise);
+  tracker.notifyNewPromise();
+
+  return deferred.handle;
+}
+
+/**
+ * Simplified version for async operations that return a QuickJS handle.
+ * Automatically resolves the deferred promise with the result handle and disposes it.
+ *
+ * @param ctx - Bridge context
+ * @param fn - Async function that returns a QuickJSHandle to resolve with
+ * @returns QuickJS handle to the promise
+ */
+export function withTrackedPromiseResult(
+  ctx: BridgeContext,
+  fn: () => Promise<QuickJSHandle>
+): QuickJSHandle {
+  return withTrackedPromise(ctx, async (deferred) => {
+    const resultHandle = await fn();
+    deferred.resolve(resultHandle);
+    resultHandle.dispose();
+    ctx.runtime.executePendingJobs();
+  });
+}
+
+/**
+ * Like withTrackedPromiseResult but allows custom handling of the result before resolving.
+ *
+ * @param ctx - Bridge context
+ * @param fn - Async function that returns any value (will be converted to handle)
+ * @returns QuickJS handle to the promise
+ */
+export function withTrackedPromiseValue<T>(
+  ctx: BridgeContext,
+  fn: () => Promise<T>
+): QuickJSHandle {
+  const { context } = ctx;
+
+  return withTrackedPromise(ctx, async (deferred) => {
+    const value = await fn();
+
+    // Convert value to handle using the proper utility
+    const resultHandle = convertToHandle(context, value);
+
+    deferred.resolve(resultHandle);
+    resultHandle.dispose();
+    ctx.runtime.executePendingJobs();
+  });
+}

package/src/sandbox/bridges/shared/registry-setup.ts

@@ -0,0 +1,84 @@
+/**
+ * Registry setup utilities for QuickJS bridges
+ *
+ * Standardizes the initialization of stream registries and response object contexts
+ * across all stream-based bridges.
+ */
+
+import type { BridgeContext } from '../types.js';
+import {
+  createStreamCleanupHandler,
+  createIdCounter,
+  type StreamRegistry
+} from './cleanup.js';
+import type { ResponseObjectContext } from './response-object.js';
+
+/**
+ * Sets up a stream registry with counters, cleanup handler, and response object context.
+ *
+ * This eliminates ~17 lines of repetitive setup code from fetch, response, storage, and bucket bridges.
+ *
+ * @param ctx - Bridge context (cleanupHandlers will be populated)
+ * @param bridgeName - Name for logging and cleanup
+ * @returns ResponseObjectContext containing registry and counters
+ */
+export function setupStreamRegistry(
+  ctx: BridgeContext,
+  bridgeName: string
+): ResponseObjectContext {
+  const registry: StreamRegistry = {
+    hostResponses: new Map<number, Response>(),
+    hostStreams: new Map<number, ReadableStream>(),
+    hostReaders: new Map<number, ReadableStreamDefaultReader>()
+  };
+
+  const responseIdCounter = createIdCounter();
+  const streamIdCounter = createIdCounter();
+  const readerIdCounter = createIdCounter();
+
+  ctx.cleanupHandlers.push(createStreamCleanupHandler(registry, bridgeName, ctx.logger));
+
+  return {
+    registry: {
+      hostResponses: registry.hostResponses!,
+      hostStreams: registry.hostStreams,
+      hostReaders: registry.hostReaders
+    },
+    responseIdCounter,
+    streamIdCounter,
+    readerIdCounter
+  };
+}
+
+/**
+ * Sets up a stream registry without Response tracking.
+ * Used by bridges that only handle streams/readers (like actor, readable-stream).
+ *
+ * @param ctx - Bridge context (cleanupHandlers will be populated)
+ * @param bridgeName - Name for logging and cleanup
+ * @returns Registry and counters for streams/readers
+ */
+export function setupSimpleStreamRegistry(
+  ctx: BridgeContext,
+  bridgeName: string
+): {
+  registry: StreamRegistry;
+  streamIdCounter: { value: number };
+  readerIdCounter: { value: number };
+} {
+  const registry: StreamRegistry = {
+    hostStreams: new Map<number, ReadableStream>(),
+    hostReaders: new Map<number, ReadableStreamDefaultReader>()
+  };
+
+  const streamIdCounter = createIdCounter();
+  const readerIdCounter = createIdCounter();
+
+  ctx.cleanupHandlers.push(createStreamCleanupHandler(registry, bridgeName, ctx.logger));
+
+  return {
+    registry,
+    streamIdCounter,
+    readerIdCounter
+  };
+}