@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/search.ts

@@ -0,0 +1,264 @@
+/**
+ * Search bridge - Provides search/chunkSearch with pagination support
+ *
+ * Returns result objects with:
+ * - .results - current page results
+ * - .hasMore - boolean
+ * - .nextPage() - returns next page (same shape)
+ * - async iterator - for await (const r of results)
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import { isFail } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import type { SmartBucket } from '@liquidmetal-ai/raindrop-framework';
+import { withTrackedPromiseResult, parseMountPath } from './shared/index.js';
+
+export interface SearchMountInfo {
+  name: string;
+  smartbucket: SmartBucket;
+}
+
+/**
+ * Build a single search result item handle. Uses Scope for per-item cleanup.
+ */
+function createSearchResultItem(
+  context: BridgeContext['context'],
+  r: any
+): QuickJSHandle {
+  const itemHandle = context.newObject();
+
+  if (r.text) {
+    using textHandle = context.newString(r.text);
+    context.setProp(itemHandle, 'text', textHandle);
+  }
+  if (r.source) {
+    using sourceHandle = context.newString(r.source);
+    context.setProp(itemHandle, 'source', sourceHandle);
+  }
+  if (r.score !== undefined) {
+    using scoreHandle = context.newNumber(r.score);
+    context.setProp(itemHandle, 'score', scoreHandle);
+  }
+  if (r.chunkSignature) {
+    using chunkHandle = context.newString(r.chunkSignature);
+    context.setProp(itemHandle, 'chunkSignature', chunkHandle);
+  }
+
+  return itemHandle;
+}
+
+/**
+ * Build a results array handle from search results.
+ */
+function createResultsArray(
+  context: BridgeContext['context'],
+  results: any[]
+): QuickJSHandle {
+  const resultsArray = context.newArray();
+  results.forEach((r, index) => {
+    using itemHandle = createSearchResultItem(context, r);
+    context.setProp(resultsArray, index, itemHandle);
+  });
+  return resultsArray;
+}
+
+/**
+ * Install search API in the sandbox
+ */
+export function installSearch(
+  ctx: BridgeContext,
+  searchMounts: Map<string, SearchMountInfo>
+): void {
+  const { context, logger } = ctx;
+
+  /**
+   * Create a search results object with pagination support
+   */
+  function createSearchResultsHandle(
+    results: any[],
+    hasMore: boolean,
+    pagination: { total: number; page: number; pageSize: number },
+    smartbucket: SmartBucket,
+    requestId: string
+  ): QuickJSHandle {
+    const resultHandle = context.newObject();
+
+    // .results array
+    {
+      using resultsArray = createResultsArray(context, results);
+      context.setProp(resultHandle, 'results', resultsArray);
+    }
+
+    // .hasMore boolean
+    context.setProp(resultHandle, 'hasMore', hasMore ? context.true : context.false);
+
+    // .total, .page, .pageSize for info
+    {
+      using totalHandle = context.newNumber(pagination.total);
+      context.setProp(resultHandle, 'total', totalHandle);
+    }
+    {
+      using pageHandle = context.newNumber(pagination.page);
+      context.setProp(resultHandle, 'page', pageHandle);
+    }
+    {
+      using pageSizeHandle = context.newNumber(pagination.pageSize);
+      context.setProp(resultHandle, 'pageSize', pageSizeHandle);
+    }
+
+    // .nextPage() method - captures requestId in closure
+    {
+      using nextPageMethod = context.newFunction('nextPage', () => {
+        if (!hasMore) {
+          // No more pages - return empty results
+          return withTrackedPromiseResult(ctx, async () => {
+            return createSearchResultsHandle(
+              [],
+              false,
+              { total: pagination.total, page: pagination.page + 1, pageSize: pagination.pageSize },
+              smartbucket,
+              requestId
+            );
+          });
+        }
+
+        return withTrackedPromiseResult(ctx, async () => {
+          const nextPage = pagination.page + 1;
+          const result = await smartbucket.getPaginatedResults({
+            requestId,
+            page: nextPage
+          });
+
+          return createSearchResultsHandle(
+            result.results,
+            result.pagination.hasMore,
+            {
+              total: result.pagination.total,
+              page: result.pagination.page,
+              pageSize: result.pagination.pageSize
+            },
+            smartbucket,
+            requestId
+          );
+        });
+      });
+      context.setProp(resultHandle, 'nextPage', nextPageMethod);
+    }
+
+    // Symbol.asyncIterator for "for await" support
+    // We define the iterator entirely in QuickJS so there are no captured host handles
+    // that could be disposed before the iterator is used.
+    const asyncIteratorSetupCode = `
+			(function(resultsObj) {
+				resultsObj[Symbol.asyncIterator] = function() {
+					return {
+						currentResults: resultsObj.results.slice(),
+						currentIndex: 0,
+						resultsObj: resultsObj,
+						async next() {
+							// If we have results in current page, yield them
+							if (this.currentIndex < this.currentResults.length) {
+								return { value: this.currentResults[this.currentIndex++], done: false };
+							}
+							// Try to get next page
+							if (this.resultsObj.hasMore) {
+								this.resultsObj = await this.resultsObj.nextPage();
+								this.currentResults = this.resultsObj.results.slice();
+								this.currentIndex = 0;
+								if (this.currentResults.length > 0) {
+									return { value: this.currentResults[this.currentIndex++], done: false };
+								}
+							}
+							// No more results
+							return { done: true };
+						}
+					};
+				};
+			})
+		`;
+
+    const setupFnResult = context.evalCode(asyncIteratorSetupCode);
+    if (isFail(setupFnResult)) {
+      logger?.warn?.('[Search Bridge] Failed to create async iterator setup');
+      setupFnResult.error.dispose();
+    } else {
+      using setupFn = setupFnResult.value;
+      const callResult = context.callFunction(setupFn, context.undefined, resultHandle);
+      if (isFail(callResult)) {
+        logger?.warn?.('[Search Bridge] Failed to apply async iterator');
+        callResult.error.dispose();
+      } else {
+        callResult.value.dispose();
+      }
+    }
+
+    return resultHandle;
+  }
+
+  // search(path, query) - Semantic search with pagination
+  {
+    using searchMethod = context.newFunction(
+      'search',
+      (pathHandle: QuickJSHandle, queryHandle: QuickJSHandle) => {
+        const path = context.dump(pathHandle) as string;
+        const query = context.dump(queryHandle) as string;
+
+        return withTrackedPromiseResult(ctx, async () => {
+          const { mount } = parseMountPath(path, searchMounts, 'Search');
+          const requestId = `search-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+          const result = await mount.smartbucket.search({
+            input: query,
+            requestId
+          });
+
+          return createSearchResultsHandle(
+            result.results,
+            result.pagination.hasMore,
+            {
+              total: result.pagination.total,
+              page: result.pagination.page,
+              pageSize: result.pagination.pageSize
+            },
+            mount.smartbucket,
+            requestId
+          );
+        });
+      }
+    );
+    context.setProp(context.global, 'search', searchMethod);
+  }
+
+  // chunkSearch(path, query) - RAG chunk search (no pagination)
+  {
+    using chunkSearchMethod = context.newFunction(
+      'chunkSearch',
+      (pathHandle: QuickJSHandle, queryHandle: QuickJSHandle) => {
+        const path = context.dump(pathHandle) as string;
+        const query = context.dump(queryHandle) as string;
+
+        return withTrackedPromiseResult(ctx, async () => {
+          const { mount } = parseMountPath(path, searchMounts, 'Search');
+          const requestId = `chunk-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+
+          const result = await mount.smartbucket.chunkSearch({
+            input: query,
+            requestId
+          });
+
+          // Build results using the shared helper
+          const resultHandle = context.newObject();
+          {
+            using resultsArray = createResultsArray(context, result.results);
+            context.setProp(resultHandle, 'results', resultsArray);
+          }
+          return resultHandle;
+        });
+      }
+    );
+    context.setProp(context.global, 'chunkSearch', chunkSearchMethod);
+  }
+
+  logger?.info?.(`[Search Bridge] Installed with ${searchMounts.size} SmartBucket mount(s)`);
+}

package/src/sandbox/bridges/shared/body-methods.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared body consumption methods (json, text, arrayBuffer) for Response-like objects
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from '../types.js';
+import { withTrackedPromiseResult, withTrackedPromiseValue } from './promise-helper.js';
+import { parseJsonInContext } from './json-helpers.js';
+
+/**
+ * Create a body consumption method (json, text, or arrayBuffer)
+ *
+ * @param ctx - Bridge context
+ * @param methodName - 'json', 'text', or 'arrayBuffer'
+ * @param responseId - ID of the response in the registry
+ * @param responseRegistry - Map of response IDs to Response objects
+ */
+export function createBodyMethod(
+  ctx: BridgeContext,
+  methodName: 'json' | 'text' | 'arrayBuffer',
+  responseId: number,
+  responseRegistry: Map<number, Response>
+): QuickJSHandle {
+  const { context, tracker } = ctx;
+
+  return context.newFunction(methodName, () => {
+    const response = responseRegistry.get(responseId);
+
+    if (!response) {
+      const deferred = context.newPromise();
+      tracker.deferredPromises.add(deferred);
+      using errHandle = context.newString('Response not found or already consumed');
+      deferred.reject(errHandle);
+      tracker.deferredPromises.delete(deferred);
+      return deferred.handle;
+    }
+
+    // Check if body was already used (host Response tracks this)
+    if (response.bodyUsed) {
+      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;
+    }
+
+    if (methodName === 'text') {
+      return withTrackedPromiseValue(ctx, async () => {
+        return await response.text();
+      });
+    } else if (methodName === 'arrayBuffer') {
+      return withTrackedPromiseResult(ctx, async () => {
+        const buffer = await response.arrayBuffer();
+        return ctx.context.newArrayBuffer(buffer);
+      });
+    } else {
+      // json
+      return withTrackedPromiseResult(ctx, async () => {
+        const data = await response.json();
+        const jsonStr = JSON.stringify(data);
+        return parseJsonInContext(context, jsonStr);
+      });
+    }
+  });
+}
+
+/**
+ * Attach all body methods (json, text, arrayBuffer) to a response handle
+ */
+export function attachBodyMethods(
+  ctx: BridgeContext,
+  responseHandle: QuickJSHandle,
+  responseId: number,
+  responseRegistry: Map<number, Response>
+): void {
+  const { context } = ctx;
+
+  {
+    using jsonMethod = createBodyMethod(ctx, 'json', responseId, responseRegistry);
+    context.setProp(responseHandle, 'json', jsonMethod);
+  }
+
+  {
+    using textMethod = createBodyMethod(ctx, 'text', responseId, responseRegistry);
+    context.setProp(responseHandle, 'text', textMethod);
+  }
+
+  {
+    using arrayBufferMethod = createBodyMethod(ctx, 'arrayBuffer', responseId, responseRegistry);
+    context.setProp(responseHandle, 'arrayBuffer', arrayBufferMethod);
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Shared cleanup utilities for stream-based bridges
+ */
+
+import type { Logger } from '../../../types.js';
+
+/**
+ * Registry of host objects that need cleanup
+ */
+export interface StreamRegistry {
+  hostResponses?: Map<number, Response>;
+  hostStreams: Map<number, ReadableStream>;
+  hostReaders: Map<number, ReadableStreamDefaultReader>;
+}
+
+/**
+ * Create a cleanup handler for stream-based bridges.
+ *
+ * The cleanup order is important:
+ * 1. Release readers FIRST - streams can't be cancelled while locked
+ * 2. Cancel streams - this settles any pending read promises
+ * 3. Wait for cancellation to complete (with timeout)
+ * 4. Clear all maps
+ *
+ * @param registry - Registry containing Maps of host objects
+ * @param bridgeName - Name for logging (e.g., 'Fetch', 'Response', 'Bucket')
+ * @param logger - Optional logger
+ */
+export function createStreamCleanupHandler(
+  registry: StreamRegistry,
+  bridgeName: string,
+  logger?: Logger,
+  cleanupTimeoutMs: number = 5000
+): () => Promise<void> {
+  return async () => {
+    logger?.info?.(`[${bridgeName}] Cleanup: aborting all active streams and readers`);
+
+    const pendingOperations: Promise<unknown>[] = [];
+
+    // STEP 1: Release readers FIRST before cancelling streams
+    // Streams cannot be cancelled while a reader has the lock
+    const readersToRelease = Array.from(registry.hostReaders.entries());
+    for (const [id, reader] of readersToRelease) {
+      try {
+        reader.releaseLock();
+        logger?.info?.(`[${bridgeName}] Released reader lock for reader ${id}`);
+      } catch (e) {
+        // Reader might already be released, ignore error
+        logger?.info?.(`[${bridgeName}] Reader ${id} already released or not locked: ${e}`);
+      }
+    }
+
+    // STEP 2: Cancel all streams (after readers are released)
+    const streamsToCancel = Array.from(registry.hostStreams.entries());
+    for (const [id, stream] of streamsToCancel) {
+      try {
+        const cancelPromise = stream.cancel('Sandbox cleanup').catch(() => {
+          // Ignore errors from cancellation
+        });
+        pendingOperations.push(cancelPromise);
+        logger?.info?.(`[${bridgeName}] Cancelled stream ${id}`);
+      } catch (e) {
+        // Stream might be cancelled or closed already
+        logger?.info?.(`[${bridgeName}] Stream ${id} already cancelled or closed: ${e}`);
+      }
+    }
+
+    // STEP 3: Wait for all stream cancellation promises to settle WITH TIMEOUT
+    // This prevents stream cleanup from blocking disposal indefinitely
+    if (pendingOperations.length > 0) {
+      logger?.info?.(
+        `[${bridgeName}] Waiting for ${pendingOperations.length} stream operations to settle (with timeout)`
+      );
+
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const timeout = new Promise(resolve => {
+          timer = setTimeout(resolve, cleanupTimeoutMs);
+        });
+        await Promise.race([Promise.allSettled(pendingOperations), timeout]);
+        logger?.info?.(`[${bridgeName}] Stream cleanup completed`);
+      } catch (e) {
+        logger?.warn?.(`[${bridgeName}] Stream cleanup timeout or error: ${e}`);
+      } finally {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+        }
+      }
+    }
+
+    // STEP 4: Clear all registries AFTER operations have settled
+    registry.hostReaders.clear();
+    registry.hostStreams.clear();
+    if (registry.hostResponses) {
+      registry.hostResponses.clear();
+    }
+  };
+}
+
+/**
+ * Counter factory for generating unique IDs
+ */
+export function createIdCounter(): { value: number } {
+  return { value: 0 };
+}
+
+/**
+ * Get next ID from counter
+ */
+export function nextId(counter: { value: number }): number {
+  return ++counter.value;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Shared value conversion utility for QuickJS bridges
+ *
+ * Single source of truth for converting JavaScript values to QuickJS handles.
+ * Used by both utils.ts (createSyncBridge/createAsyncBridge) and promise-helper.ts.
+ */
+
+import type { QuickJSContext, QuickJSHandle } from 'quickjs-emscripten-core';
+import { getJsonParse } from './json-helpers.js';
+
+/**
+ * Safely extract the relevant portion of a Uint8Array's backing ArrayBuffer.
+ * Handles the case where a Uint8Array is a view into a larger ArrayBuffer
+ * (common with Node.js Buffer).
+ */
+function safeArrayBuffer(uint8Array: Uint8Array): ArrayBuffer {
+  if (uint8Array.byteOffset === 0 && uint8Array.byteLength === uint8Array.buffer.byteLength) {
+    return uint8Array.buffer as ArrayBuffer;
+  }
+  return uint8Array.buffer.slice(
+    uint8Array.byteOffset,
+    uint8Array.byteOffset + uint8Array.byteLength
+  ) as ArrayBuffer;
+}
+
+/**
+ * Convert JavaScript values to QuickJS handles.
+ *
+ * IMPORTANT: Returns duplicated handles for singleton values (undefined, null, true, false)
+ * so that callers can always safely call .dispose() on the returned handle.
+ */
+export function convertToHandle(context: QuickJSContext, value: any): QuickJSHandle {
+  if (value === undefined) {
+    return context.undefined.dup();
+  } else if (value === null) {
+    return context.null.dup();
+  } else if (typeof value === 'number') {
+    return context.newNumber(value);
+  } else if (typeof value === 'string') {
+    return context.newString(value);
+  } else if (typeof value === 'boolean') {
+    return value ? context.true.dup() : context.false.dup();
+  } else if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    const uint8Array = value instanceof Uint8Array ? value : new Uint8Array(value);
+    return context.newArrayBuffer(safeArrayBuffer(uint8Array));
+  } else if (Array.isArray(value)) {
+    const arr = context.newArray();
+    for (let i = 0; i < value.length; i++) {
+      const elemHandle = convertToHandle(context, value[i]);
+      context.setProp(arr, i, elemHandle);
+      elemHandle.dispose();
+    }
+    return arr;
+  } else if (typeof value === 'object') {
+    try {
+      const jsonStr = JSON.stringify(value);
+      const jsonParse = getJsonParse(context);
+      const jsonStrHandle = context.newString(jsonStr);
+      const result = context.callFunction(jsonParse, context.undefined, jsonStrHandle);
+      jsonStrHandle.dispose();
+      jsonParse.dispose();
+
+      if (result.error) {
+        result.error.dispose();
+        throw new Error('Failed to convert object via JSON.parse');
+      }
+      return (result as { value: QuickJSHandle }).value;
+    } catch (e) {
+      throw new Error(
+        'Failed to convert object: ' + (e instanceof Error ? e.message : String(e))
+      );
+    }
+  } else {
+    return context.newString(String(value));
+  }
+}