@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/shared/response-object.ts

@@ -0,0 +1,280 @@
+/**
+ * Unified Response object factory for QuickJS bridges
+ * Used by fetch(), Response constructor, and bucket.get()
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import { isFail } from 'quickjs-emscripten-core';
+import type { BridgeContext } from '../types.js';
+import { createStreamObject } from '../readable-stream.js';
+import { createHeadersObject } from './headers.js';
+import { attachBodyMethods } from './body-methods.js';
+import { nextId } from './cleanup.js';
+import { parseJsonInContext } from './json-helpers.js';
+import {
+  withTrackedPromiseResult,
+  withTrackedPromiseValue
+} from './promise-helper.js';
+
+/**
+ * Options for creating a Response object in the sandbox
+ */
+export interface ResponseObjectOptions {
+  /** The actual host Response to bridge (for fetch, Response constructor) */
+  response?: Response;
+  /** For objects without a real Response (e.g., bucket) - provide init values */
+  responseInit?: {
+    status: number;
+    statusText?: string;
+    ok: boolean;
+    url?: string;
+    type?: ResponseType;
+    redirected?: boolean;
+    headers?: Headers;
+  };
+  /** ReadableStream body (for bucket objects or custom Response) */
+  body?: ReadableStream<Uint8Array>;
+  /** Extra metadata to set on the response (e.g., bucket-specific: key, size, uploaded) */
+  metadata?: Record<string, string | number>;
+}
+
+/**
+ * Registry context containing ID counters and host object maps
+ */
+export interface ResponseObjectContext {
+  registry: {
+    hostResponses: Map<number, Response>;
+    hostStreams: Map<number, ReadableStream>;
+    hostReaders: Map<number, ReadableStreamDefaultReader>;
+  };
+  responseIdCounter: { value: number };
+  streamIdCounter: { value: number };
+  readerIdCounter: { value: number };
+}
+
+/**
+ * Install a dynamic `bodyUsed` getter on a response handle.
+ * Falls back to a static property if defineProperty fails.
+ */
+function installBodyUsedGetter(
+  context: BridgeContext['context'],
+  responseHandle: QuickJSHandle,
+  getterFn: QuickJSHandle
+): void {
+  {
+    using fn = getterFn;
+    context.setProp(responseHandle, '__getBodyUsed', fn);
+  }
+
+  const defineBodyUsed = context.evalCode(`(function(obj) {
+		var fn = obj.__getBodyUsed;
+		Object.defineProperty(obj, 'bodyUsed', {
+			get: function() { return fn(); },
+			enumerable: true,
+			configurable: true
+		});
+		delete obj.__getBodyUsed;
+		return obj;
+	})`);
+  if (isFail(defineBodyUsed)) {
+    // Fallback: set static property
+    defineBodyUsed.error.dispose();
+    context.setProp(responseHandle, 'bodyUsed', context.false);
+  } else {
+    using defineFunc = defineBodyUsed.value;
+    const applyResult = context.callFunction(defineFunc, context.undefined, responseHandle);
+    if (isFail(applyResult)) {
+      applyResult.error.dispose();
+      context.setProp(responseHandle, 'bodyUsed', context.false);
+    } else {
+      applyResult.value.dispose();
+    }
+  }
+}
+
+/**
+ * Attach body consumption methods that create a Response from the stream.
+ * Used by bucket.get() which provides a bare ReadableStream.
+ *
+ * This is different from attachBodyMethods() which uses an existing Response object.
+ * Refactored to use withTrackedPromise* helpers to eliminate manual deferred boilerplate.
+ */
+export function attachStreamBodyMethods(
+  ctx: BridgeContext,
+  responseHandle: QuickJSHandle,
+  bodyStream: ReadableStream<Uint8Array>
+): void {
+  const { context, tracker } = ctx;
+
+  // Track body consumption state - streams can only be consumed once
+  let bodyUsed = false;
+
+  // Helper to check and mark body as used, returning a host Response or null
+  const consumeBody = (): Response | null => {
+    if (bodyUsed) return null;
+    bodyUsed = true;
+    return new Response(bodyStream);
+  };
+
+  // Helper to reject with "already consumed" error
+  const rejectConsumed = (): QuickJSHandle => {
+    const deferred = context.newPromise();
+    tracker.deferredPromises.add(deferred);
+    using errHandle = context.newString('Body has already been consumed');
+    deferred.reject(errHandle);
+    tracker.deferredPromises.delete(deferred);
+    return deferred.handle;
+  };
+
+  // Expose bodyUsed as a dynamic getter
+  installBodyUsedGetter(
+    context,
+    responseHandle,
+    context.newFunction('__getBodyUsed', () => bodyUsed ? context.true : context.false)
+  );
+
+  // text() - consumes the body stream
+  {
+    using textMethod = context.newFunction('text', () => {
+      const response = consumeBody();
+      if (!response) return rejectConsumed();
+      return withTrackedPromiseValue(ctx, () => response.text());
+    });
+    context.setProp(responseHandle, 'text', textMethod);
+  }
+
+  // json() - consumes the body stream
+  {
+    using jsonMethod = context.newFunction('json', () => {
+      const response = consumeBody();
+      if (!response) return rejectConsumed();
+      return withTrackedPromiseResult(ctx, async () => {
+        const data = await response.json();
+        return parseJsonInContext(context, JSON.stringify(data));
+      });
+    });
+    context.setProp(responseHandle, 'json', jsonMethod);
+  }
+
+  // arrayBuffer() - consumes the body stream
+  {
+    using arrayBufferMethod = context.newFunction('arrayBuffer', () => {
+      const response = consumeBody();
+      if (!response) return rejectConsumed();
+      return withTrackedPromiseResult(ctx, async () => {
+        const buffer = await response.arrayBuffer();
+        return context.newArrayBuffer(buffer);
+      });
+    });
+    context.setProp(responseHandle, 'arrayBuffer', arrayBufferMethod);
+  }
+}
+
+/**
+ * Creates a bridged Response object in QuickJS.
+ * Unified factory used by fetch, Response constructor, and bucket.get().
+ */
+export function createResponseObject(
+  ctx: BridgeContext,
+  opts: ResponseObjectOptions,
+  objCtx: ResponseObjectContext
+): QuickJSHandle {
+  const { context } = ctx;
+  const { registry, responseIdCounter, streamIdCounter, readerIdCounter } = objCtx;
+
+  const responseHandle = context.newObject();
+
+  // Determine source - real Response or init object
+  const response = opts.response;
+  const init = opts.responseInit ?? {
+    status: response?.status ?? 200,
+    statusText: response?.statusText ?? '',
+    ok: response?.ok ?? true,
+    url: response?.url ?? '',
+    type: response?.type ?? 'default',
+    redirected: response?.redirected ?? false,
+    headers: response?.headers
+  };
+  const bodyStream = opts.body ?? response?.body ?? null;
+
+  // Set standard Response properties
+  {
+    using statusHandle = context.newNumber(init.status);
+    context.setProp(responseHandle, 'status', statusHandle);
+  }
+
+  {
+    using statusTextHandle = context.newString(init.statusText || '');
+    context.setProp(responseHandle, 'statusText', statusTextHandle);
+  }
+
+  context.setProp(responseHandle, 'ok', init.ok ? context.true : context.false);
+
+  {
+    using urlHandle = context.newString(init.url || '');
+    context.setProp(responseHandle, 'url', urlHandle);
+  }
+
+  {
+    using typeHandle = context.newString(init.type || 'default');
+    context.setProp(responseHandle, 'type', typeHandle);
+  }
+
+  context.setProp(responseHandle, 'redirected', init.redirected ? context.true : context.false);
+
+  // Extra metadata (for bucket responses: key, size, uploaded)
+  if (opts.metadata) {
+    for (const [key, value] of Object.entries(opts.metadata)) {
+      using handle = typeof value === 'number'
+        ? context.newNumber(value)
+        : context.newString(String(value));
+      context.setProp(responseHandle, key, handle);
+    }
+  }
+
+  // Bridge body stream
+  if (bodyStream) {
+    const streamId = nextId(streamIdCounter);
+    registry.hostStreams.set(streamId, bodyStream);
+    using streamHandle = createStreamObject(
+      ctx,
+      bodyStream,
+      streamId,
+      registry.hostReaders,
+      readerIdCounter
+    );
+    context.setProp(responseHandle, 'body', streamHandle);
+  } else {
+    context.setProp(responseHandle, 'body', context.null);
+  }
+
+  // Headers
+  {
+    using headersHandle = createHeadersObject(ctx, init.headers);
+    context.setProp(responseHandle, 'headers', headersHandle);
+  }
+
+  // Body methods - attach based on what we have
+  if (response) {
+    // We have a real Response - use the original body methods
+    const responseId = nextId(responseIdCounter);
+    registry.hostResponses.set(responseId, response);
+    attachBodyMethods(ctx, responseHandle, responseId, registry.hostResponses);
+
+    // Expose bodyUsed as a dynamic getter backed by the host Response
+    installBodyUsedGetter(
+      context,
+      responseHandle,
+      context.newFunction('__getBodyUsed', () => response.bodyUsed ? context.true : context.false)
+    );
+  } else if (bodyStream) {
+    // We have a bare stream (bucket case) - create Response wrappers
+    // (attachStreamBodyMethods sets up bodyUsed getter internally)
+    attachStreamBodyMethods(ctx, responseHandle, bodyStream);
+  } else {
+    // No body - bodyUsed is always true (no body to consume)
+    context.setProp(responseHandle, 'bodyUsed', context.true);
+  }
+
+  return responseHandle;
+}

package/src/sandbox/bridges/shared/result-builder.ts

@@ -0,0 +1,130 @@
+/**
+ * Result object builder utilities for QuickJS bridges
+ *
+ * Provides helpers for building common result objects like:
+ * - List results with files arrays and counts
+ * - Success/result objects
+ * - Response metadata objects
+ */
+
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten-core';
+import { Scope } from 'quickjs-emscripten-core';
+
+/**
+ * File entry for list results
+ */
+export interface FileEntry {
+  key: string;
+  size?: number;
+  uploaded?: Date;
+  expiration?: number;
+}
+
+/**
+ * Build a list result object with files array and count
+ *
+ * @param context - QuickJS context
+ * @param mountName - Name of the mount for prefixing keys
+ * @param files - Array of file entries
+ * @param additionalProps - Additional properties to add to result (e.g., truncated)
+ * @returns QuickJS handle to the result object
+ */
+export function createListResult(
+  context: QuickJSContext,
+  mountName: string,
+  files: FileEntry[],
+  additionalProps?: Record<string, QuickJSHandle>
+): QuickJSHandle {
+  const resultHandle = context.newObject();
+
+  {
+    using filesArray = context.newArray();
+
+    files.forEach((file, index) => {
+      // Scope per iteration — auto-disposes fileHandle and all property handles
+      Scope.withScope((scope) => {
+        const fileHandle = scope.manage(context.newObject());
+
+        const keyHandle = scope.manage(context.newString(`/${mountName}/${file.key}`));
+        context.setProp(fileHandle, 'key', keyHandle);
+
+        if (file.size !== undefined) {
+          const sizeHandle = scope.manage(context.newNumber(file.size));
+          context.setProp(fileHandle, 'size', sizeHandle);
+        }
+
+        if (file.uploaded) {
+          const uploadedHandle = scope.manage(context.newString(file.uploaded.toISOString()));
+          context.setProp(fileHandle, 'uploaded', uploadedHandle);
+        }
+
+        if (file.expiration !== undefined) {
+          const expHandle = scope.manage(context.newNumber(file.expiration));
+          context.setProp(fileHandle, 'expiration', expHandle);
+        }
+
+        context.setProp(filesArray, index, fileHandle);
+      });
+    });
+
+    context.setProp(resultHandle, 'files', filesArray);
+  }
+
+  {
+    using countHandle = context.newNumber(files.length);
+    context.setProp(resultHandle, 'count', countHandle);
+  }
+
+  // Add any additional properties
+  if (additionalProps) {
+    for (const [key, valueHandle] of Object.entries(additionalProps)) {
+      context.setProp(resultHandle, key, valueHandle);
+      // Don't dispose - caller retains ownership
+    }
+  }
+
+  return resultHandle;
+}
+
+/**
+ * Build a success result object
+ */
+export function createSuccessResult(context: QuickJSContext): QuickJSHandle {
+  const resultHandle = context.newObject();
+  context.setProp(resultHandle, 'success', context.true);
+  return resultHandle;
+}
+
+/**
+ * Build a success result with a key property
+ */
+export function createSuccessResultWithKey(
+  context: QuickJSContext,
+  key: string
+): QuickJSHandle {
+  const resultHandle = context.newObject();
+  {
+    using keyHandle = context.newString(key);
+    context.setProp(resultHandle, 'key', keyHandle);
+  }
+  context.setProp(resultHandle, 'success', context.true);
+  return resultHandle;
+}
+
+/**
+ * Build a success result with custom metadata
+ */
+export function createSuccessResultWithMetadata(
+  context: QuickJSContext,
+  metadata: Record<string, string | number>
+): QuickJSHandle {
+  const resultHandle = context.newObject();
+
+  for (const [key, value] of Object.entries(metadata)) {
+    using handle = typeof value === 'number' ? context.newNumber(value) : context.newString(value);
+    context.setProp(resultHandle, key, handle);
+  }
+
+  context.setProp(resultHandle, 'success', context.true);
+  return resultHandle;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Scope helpers and result-unwrapping utilities for QuickJS bridges.
+ *
+ * Provides:
+ * - unwrapResult: Disposes error and throws (or returns value) from VmCallResult/evalCode
+ */
+
+import type { QuickJSContext, QuickJSHandle, VmCallResult } from 'quickjs-emscripten-core';
+import { isFail } from 'quickjs-emscripten-core';
+
+/**
+ * Safely stringify a value, handling circular references and other edge cases.
+ */
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Unwrap a VmCallResult (from evalCode or callFunction).
+ * On success: returns the value handle (caller must dispose).
+ * On failure: disposes the error handle and throws an Error.
+ */
+export function unwrapResult(result: VmCallResult<QuickJSHandle>, context?: QuickJSContext): QuickJSHandle {
+  if (isFail(result)) {
+    let message: string;
+    if (context) {
+      try {
+        const error = context.dump(result.error);
+        message = typeof error === 'string' ? error : safeStringify(error);
+      } catch {
+        message = 'Unknown error';
+      }
+    } else {
+      message = 'QuickJS evaluation failed';
+    }
+    result.error.dispose();
+    throw new Error(message);
+  }
+  return result.value;
+}

package/src/sandbox/bridges/shared/stream-reader.ts

@@ -0,0 +1,90 @@
+/**
+ * Stream reader factory for QuickJS bridges
+ *
+ * Creates reader objects with read(), cancel(), and releaseLock() methods.
+ * Eliminates ~100 lines of duplicated reader creation code across actor and readable-stream bridges.
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from '../types.js';
+import {
+  withTrackedPromiseResult,
+  withTrackedPromiseValue
+} from './promise-helper.js';
+
+/**
+ * Create a reader handle with standard reader methods
+ *
+ * @param ctx - Bridge context
+ * @param reader - The host reader
+ * @param onRelease - Optional callback when releaseLock is called
+ * @returns QuickJS handle to the reader object
+ */
+export function createReaderHandle(
+  ctx: BridgeContext,
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  onRelease?: () => void
+): QuickJSHandle {
+  const { context, logger } = ctx;
+  const readerHandle = context.newObject();
+
+  // Create read() method
+  {
+    using readMethod = context.newFunction('read', () => {
+      return withTrackedPromiseResult(ctx, async () => {
+        const { done, value } = await reader.read();
+
+        const resultHandle = context.newObject();
+
+        context.setProp(resultHandle, 'done', done ? context.true : context.false);
+
+        if (value) {
+          // Use slice to handle Uint8Array views into larger ArrayBuffers (e.g. Node.js Buffer)
+          const buf =
+            value.byteOffset === 0 && value.byteLength === value.buffer.byteLength
+              ? value.buffer
+              : value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+          using valueHandle = context.newArrayBuffer(buf);
+          context.setProp(resultHandle, 'value', valueHandle);
+        } else {
+          context.setProp(resultHandle, 'value', context.undefined);
+        }
+
+        return resultHandle;
+      });
+    });
+    context.setProp(readerHandle, 'read', readMethod);
+  }
+
+  // Create cancel() method
+  {
+    using cancelMethod = context.newFunction('cancel', () => {
+      return withTrackedPromiseValue(ctx, async () => {
+        await reader.cancel();
+        if (onRelease) {
+          onRelease();
+        }
+        return undefined;
+      });
+    });
+    context.setProp(readerHandle, 'cancel', cancelMethod);
+  }
+
+  // Create releaseLock() method
+  {
+    using releaseLockMethod = context.newFunction('releaseLock', () => {
+      try {
+        reader.releaseLock();
+        if (onRelease) {
+          onRelease();
+        }
+      } catch (e) {
+        logger?.warn?.(`releaseLock failed: ${e}`);
+      }
+      return context.undefined;
+    });
+    context.setProp(readerHandle, 'releaseLock', releaseLockMethod);
+  }
+
+  return readerHandle;
+}