@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/storage.ts

@@ -0,0 +1,421 @@
+/**
+ * Storage bridge - Provides unified read/write/list/remove with Response-like objects
+ *
+ * Works with Bucket, SmartBucket (extends Bucket), KvCache, and ActorStorage.
+ * All storage types share the same four operations: read, write, list, remove.
+ *
+ * read() returns a Response-like object:
+ * - .text() / .json() / .arrayBuffer() for convenience
+ * - .body.getReader() for streaming (buckets only)
+ * - .size, .key, .uploaded metadata (buckets only)
+ *
+ * write() accepts optional type-specific options:
+ * - KV: { ttl, expiration, metadata }
+ * - Bucket: { contentType, customMetadata }
+ * - ActorStorage: (none — values stored as-is)
+ *
+ * list() accepts optional type-specific options:
+ * - Common: { prefix, limit }
+ * - Bucket: { delimiter, startAfter }
+ * - ActorStorage: { start, end, startAfter, reverse, limit }
+ *
+ * remove() deletes a key or file.
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import type { Bucket, KvCache, ActorStorage } from '@liquidmetal-ai/raindrop-framework';
+import {
+  withTrackedPromiseResult,
+  withTrackedPromiseValue,
+  createResponseObject,
+  setupStreamRegistry,
+  parseMountPath,
+  createListResult
+} from './shared/index.js';
+
+export interface StorageMountInfo {
+  name: string;
+  type: 'bucket' | 'smartbucket' | 'kv' | 'actor-storage';
+  resource: Bucket | KvCache | ActorStorage;
+  mode?: 'ro' | 'rw'; // Default: 'ro' (read-only)
+}
+
+/**
+ * Convert a string to a ReadableStream<Uint8Array> so KV values
+ * go through the same createResponseObject path as bucket objects.
+ */
+function stringToStream(value: string): ReadableStream<Uint8Array> {
+  const encoded = new TextEncoder().encode(value);
+  return bytesToStream(encoded);
+}
+
+/**
+ * Wrap a Uint8Array (or ArrayBuffer-backed value) in a single-chunk ReadableStream.
+ * Used for actor-storage values which are stored as raw bytes.
+ */
+function bytesToStream(data: Uint8Array | ArrayBuffer): ReadableStream<Uint8Array> {
+  const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    }
+  });
+}
+
+/**
+ * Install storage API in the sandbox (read, write, list, remove)
+ */
+export function installStorage(
+  ctx: BridgeContext,
+  storageMounts: Map<string, StorageMountInfo>
+): void {
+  const { context, logger } = ctx;
+
+  // Create response object context for the factory (includes cleanup handler)
+  const objCtx = setupStreamRegistry(ctx, 'Storage');
+
+  // ================================================================
+  // read(path) - Returns Response-like object
+  //
+  // All types return the same shape via createResponseObject:
+  //   .body (ReadableStream), .text(), .json(), .arrayBuffer()
+  //   .status, .ok, .headers, .key
+  // Buckets additionally have: .size, .uploaded
+  // KV additionally has: .metadata (if set)
+  // ================================================================
+  const readMethod = context.newFunction('read', (pathHandle: QuickJSHandle) => {
+    const path = context.dump(pathHandle) as string;
+
+    return withTrackedPromiseResult(ctx, async () => {
+      const { mount, resourcePath } = parseMountPath(path, storageMounts, 'Storage');
+
+      if (mount.type === 'kv') {
+        // KV read - use getWithMetadata for expiration/metadata
+        const kv = mount.resource as KvCache;
+        const result = await kv.getWithMetadata(resourcePath);
+
+        if (result.value === null) {
+          throw new Error(`Resource not found: ${path}`);
+        }
+
+        const valueStr = result.value as string;
+        const body = stringToStream(valueStr);
+        const metadata: Record<string, string | number> = { key: path };
+        if (result.metadata !== null && result.metadata !== undefined) {
+          metadata.metadata =
+            typeof result.metadata === 'string'
+              ? result.metadata
+              : JSON.stringify(result.metadata);
+        }
+
+        return createResponseObject(
+          ctx,
+          {
+            responseInit: {
+              status: 200,
+              statusText: 'OK',
+              ok: true,
+              url: path,
+              type: 'default',
+              redirected: false,
+              headers: new Headers()
+            },
+            body,
+            metadata
+          },
+          objCtx
+        );
+      } else if (mount.type === 'actor-storage') {
+        // ActorStorage read - stored as Uint8Array bytes
+        const storage = mount.resource as ActorStorage;
+        const value = await storage.get<Uint8Array>(resourcePath);
+
+        if (value === undefined) {
+          throw new Error(`Resource not found: ${path}`);
+        }
+
+        const body = bytesToStream(value);
+
+        return createResponseObject(
+          ctx,
+          {
+            responseInit: {
+              status: 200,
+              statusText: 'OK',
+              ok: true,
+              url: path,
+              type: 'default',
+              redirected: false,
+              headers: new Headers()
+            },
+            body,
+            metadata: { key: path }
+          },
+          objCtx
+        );
+      } else {
+        // Bucket read - with streaming support
+        const bucket = mount.resource as Bucket;
+        const obj = await bucket.get(resourcePath);
+
+        if (!obj) {
+          throw new Error(`Resource not found: ${path}`);
+        }
+
+        // Create headers object with content-type
+        const headers = new Headers();
+        if (obj.httpMetadata?.contentType) {
+          headers.set('content-type', obj.httpMetadata.contentType);
+        }
+
+        // Create Response-like object with bridged stream
+        return createResponseObject(
+          ctx,
+          {
+            responseInit: {
+              status: 200,
+              statusText: 'OK',
+              ok: true,
+              url: path,
+              type: 'default',
+              redirected: false,
+              headers
+            },
+            body: obj.body,
+            metadata: {
+              key: path,
+              size: obj.size,
+              uploaded: obj.uploaded.toISOString()
+            }
+          },
+          objCtx
+        );
+      }
+    });
+  });
+  context.setProp(context.global, 'read', readMethod);
+  readMethod.dispose();
+
+  // ================================================================
+  // write(path, content, options?) - Write file, KV entry, or actor state
+  //
+  // Options (type-specific):
+  //   KV:     { ttl: number, expiration: number, metadata: any }
+  //   Bucket: { contentType: string, customMetadata: Record<string, string> }
+  //   ActorStorage: (none)
+  // ================================================================
+  const writeMethod = context.newFunction(
+    'write',
+    (pathHandle: QuickJSHandle, contentHandle: QuickJSHandle, optionsHandle?: QuickJSHandle) => {
+      const path = context.dump(pathHandle) as string;
+      const content = context.dump(contentHandle);
+      const options = optionsHandle
+        ? (context.dump(optionsHandle) as Record<string, any> | null)
+        : null;
+
+      return withTrackedPromiseValue(ctx, async () => {
+        const { mount, resourcePath } = parseMountPath(path, storageMounts, 'Storage');
+
+        // Check if mount allows writes (default is read-only)
+        if (mount.mode !== 'rw') {
+          throw new Error(`Cannot write to read-only mount: /${mount.name}`);
+        }
+
+        if (mount.type === 'kv') {
+          const kv = mount.resource as KvCache;
+          const kvOptions: Record<string, any> = {};
+          if (options?.ttl !== undefined) {
+            kvOptions.expirationTtl = options.ttl;
+          }
+          if (options?.expiration !== undefined) {
+            kvOptions.expiration = options.expiration;
+          }
+          if (options?.metadata !== undefined) {
+            kvOptions.metadata = options.metadata;
+          }
+          const value = typeof content === 'string' ? content : JSON.stringify(content);
+          await kv.put(
+            resourcePath,
+            value,
+            Object.keys(kvOptions).length > 0 ? kvOptions : undefined
+          );
+        } else if (mount.type === 'actor-storage') {
+          const storage = mount.resource as ActorStorage;
+          // Store as Uint8Array bytes, same as what a bucket stores
+          const value = typeof content === 'string' ? content : JSON.stringify(content);
+          const bytes = new TextEncoder().encode(value);
+          await storage.put(resourcePath, bytes);
+        } else {
+          const bucket = mount.resource as Bucket;
+          const bucketOptions: Record<string, any> = {};
+          if (options?.contentType) {
+            bucketOptions.httpMetadata = { contentType: options.contentType };
+          }
+          if (options?.customMetadata) {
+            bucketOptions.customMetadata = options.customMetadata;
+          }
+          const value = typeof content === 'string' ? content : JSON.stringify(content);
+          await bucket.put(
+            resourcePath,
+            value,
+            Object.keys(bucketOptions).length > 0 ? bucketOptions : undefined
+          );
+        }
+
+        // Return success as a plain value
+        return { success: true };
+      });
+    }
+  );
+  context.setProp(context.global, 'write', writeMethod);
+  writeMethod.dispose();
+
+  // ================================================================
+  // list(path, options?) - List files or keys
+  //
+  // Options (type-specific):
+  //   Common:       { prefix: string, limit: number }
+  //   Bucket:       { delimiter: string, startAfter: string }
+  //   ActorStorage: { start: string, end: string, startAfter: string, reverse: boolean }
+  //
+  // Note: prefix is also extracted from the path itself (everything after the mount name).
+  // If options.prefix is also provided, it is appended to the path-based prefix.
+  // ================================================================
+  const listMethod = context.newFunction(
+    'list',
+    (pathHandle: QuickJSHandle, optionsHandle?: QuickJSHandle) => {
+      const path = context.dump(pathHandle) as string;
+      const options = optionsHandle
+        ? (context.dump(optionsHandle) as Record<string, any> | null)
+        : null;
+
+      return withTrackedPromiseResult(ctx, async () => {
+        const { mount, resourcePath } = parseMountPath(path, storageMounts, 'Storage');
+
+        if (mount.type === 'kv') {
+          const kv = mount.resource as KvCache;
+          // Build prefix: use resourcePath as base, append options.prefix if provided
+          let prefix: string | undefined = resourcePath || undefined;
+          if (options?.prefix !== undefined) {
+            prefix = (prefix || '') + options.prefix;
+          }
+          const listed = await kv.list({
+            prefix,
+            limit: options?.limit,
+            cursor: options?.cursor
+          });
+
+          // Build files array - include cursor/complete for pagination
+          const files = listed.keys.map((key: any) => ({
+            key: key.name,
+            expiration: key.expiration
+          }));
+
+          // Build additional properties for pagination
+          const additionalProps: Record<string, QuickJSHandle> = {};
+          if (!listed.list_complete && listed.cursor) {
+            additionalProps.cursor = context.newString(listed.cursor);
+          }
+          additionalProps.list_complete = listed.list_complete ? context.true.dup() : context.false.dup();
+
+          return createListResult(context, mount.name, files, additionalProps);
+        } else if (mount.type === 'actor-storage') {
+          const storage = mount.resource as ActorStorage;
+          const listOptions: Record<string, any> = {};
+
+          // Use resourcePath as prefix if present
+          if (resourcePath) {
+            listOptions.prefix = resourcePath;
+          }
+          // Options can override/supplement
+          if (options?.prefix !== undefined) {
+            listOptions.prefix = (listOptions.prefix || '') + options.prefix;
+          }
+          if (options?.start !== undefined) listOptions.start = options.start;
+          if (options?.end !== undefined) listOptions.end = options.end;
+          if (options?.startAfter !== undefined) listOptions.startAfter = options.startAfter;
+          if (options?.reverse !== undefined) listOptions.reverse = options.reverse;
+          if (options?.limit !== undefined) listOptions.limit = options.limit;
+
+          const entries = await storage.list(
+            Object.keys(listOptions).length > 0 ? listOptions : undefined
+          );
+
+          // Build files array
+          const files = Array.from(entries).map(([key]) => ({ key }));
+
+          return createListResult(context, mount.name, files);
+        } else {
+          const bucket = mount.resource as Bucket;
+          const bucketOptions: Record<string, any> = {
+            limit: options?.limit || 1000
+          };
+          if (resourcePath) {
+            bucketOptions.prefix = resourcePath;
+          }
+          if (options?.prefix !== undefined) {
+            bucketOptions.prefix = (bucketOptions.prefix || '') + options.prefix;
+          }
+          if (options?.delimiter !== undefined) bucketOptions.delimiter = options.delimiter;
+          if (options?.startAfter !== undefined) bucketOptions.startAfter = options.startAfter;
+
+          const listed = await bucket.list(bucketOptions);
+
+          // Build files array
+          const files = listed.objects.map(obj => ({
+            key: obj.key,
+            size: obj.size,
+            uploaded: obj.uploaded
+          }));
+
+          // Build additional properties for pagination
+          const additionalProps: Record<string, QuickJSHandle> = {};
+          if (listed.truncated && listed.cursor) {
+            additionalProps.cursor = context.newString(listed.cursor);
+          }
+          additionalProps.truncated = listed.truncated ? context.true.dup() : context.false.dup();
+
+          return createListResult(context, mount.name, files, additionalProps);
+        }
+      });
+    }
+  );
+  context.setProp(context.global, 'list', listMethod);
+  listMethod.dispose();
+
+  // ================================================================
+  // remove(path) - Delete file or key
+  // ================================================================
+  const removeMethod = context.newFunction('remove', (pathHandle: QuickJSHandle) => {
+    const path = context.dump(pathHandle) as string;
+
+    return withTrackedPromiseValue(ctx, async () => {
+      const { mount, resourcePath } = parseMountPath(path, storageMounts, 'Storage');
+
+      // Check if mount allows writes (default is read-only)
+      if (mount.mode !== 'rw') {
+        throw new Error(`Cannot delete from read-only mount: /${mount.name}`);
+      }
+
+      if (mount.type === 'kv') {
+        const kv = mount.resource as KvCache;
+        await kv.delete(resourcePath);
+      } else if (mount.type === 'actor-storage') {
+        const storage = mount.resource as ActorStorage;
+        await storage.delete(resourcePath);
+      } else {
+        const bucket = mount.resource as Bucket;
+        await bucket.delete(resourcePath);
+      }
+
+      // Return success as a plain value
+      return { success: true };
+    });
+  });
+  context.setProp(context.global, 'remove', removeMethod);
+  removeMethod.dispose();
+
+  logger?.info?.('[Bridge] storage installed (read, write, list, remove)');
+}

package/src/sandbox/bridges/text-decoder.ts

@@ -0,0 +1,190 @@
+/**
+ * TextDecoder bridge - Decodes Uint8Array to strings with streaming support
+ *
+ * OPTIMIZATION: Uses context.getArrayBuffer() for efficient binary transfer
+ * instead of context.dump() which is extremely slow for large arrays.
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import { defineClass } from './utils.js';
+
+/**
+ * Install TextDecoder in the sandbox
+ * Bridges to runtime's native TextDecoder with stateful instance tracking
+ */
+export function installTextDecoder(ctx: BridgeContext): void {
+  const { context, logger, cleanupHandlers } = ctx;
+
+  // Store decoder instances by ID to maintain state across calls
+  const decoderInstances = new Map<number, TextDecoder>();
+  let decoderIdCounter = 0;
+
+  // Register cleanup handler to prevent memory leak
+  cleanupHandlers.push(() => {
+    const count = decoderInstances.size;
+    decoderInstances.clear();
+    if (count > 0) {
+      logger?.info?.(`[TextDecoder] Cleaned up ${count} decoder instances`);
+    }
+  });
+
+  // Host function to create a decoder and return its ID
+  {
+    using hostCreateDecoder = context.newFunction(
+      '__hostCreateDecoder',
+      (labelHandle?, optionsHandle?) => {
+        try {
+          const label = labelHandle ? context.dump(labelHandle) : 'utf-8';
+          const options = optionsHandle ? context.dump(optionsHandle) : {};
+
+          // Create the runtime's TextDecoder instance and store it
+          const decoder = new TextDecoder(typeof label === 'string' ? label : 'utf-8', options);
+          const decoderId = ++decoderIdCounter;
+          decoderInstances.set(decoderId, decoder);
+
+          // Return an object with the decoder ID and encoding
+          const resultHandle = context.newObject();
+          {
+            using idHandle = context.newNumber(decoderId);
+            context.setProp(resultHandle, 'id', idHandle);
+          }
+          {
+            using encodingHandle = context.newString(decoder.encoding);
+            context.setProp(resultHandle, 'encoding', encodingHandle);
+          }
+
+          return resultHandle;
+        } catch (e) {
+          return context.newError(e instanceof Error ? e.message : String(e));
+        }
+      }
+    );
+
+    context.setProp(context.global, '__hostCreateDecoder', hostCreateDecoder);
+  }
+
+  // Host function to decode - uses getArrayBuffer for efficient transfer
+  {
+    using hostDecode = context.newFunction(
+      '__hostDecode',
+      (
+        decoderIdHandle: QuickJSHandle,
+        bufferHandle?: QuickJSHandle,
+        byteOffsetHandle?: QuickJSHandle,
+        byteLengthHandle?: QuickJSHandle,
+        streamHandle?: QuickJSHandle
+      ) => {
+        try {
+          const decoderId = context.dump(decoderIdHandle) as number;
+
+          const decoder = decoderInstances.get(decoderId);
+          if (!decoder) {
+            return context.newError('TextDecoder instance not found');
+          }
+
+          // If no buffer provided, this is a final flush call
+          if (!bufferHandle) {
+            const text = decoder.decode();
+            return context.newString(text);
+          }
+
+          // Get stream option
+          const stream = streamHandle ? context.dump(streamHandle) === true : false;
+
+          // Use getArrayBuffer for efficient binary transfer (avoids slow dump())
+          const arrayBufferResult = context.getArrayBuffer(bufferHandle);
+          if (!arrayBufferResult) {
+            return context.newError(
+              'Failed to extract ArrayBuffer from input. Input must be an ArrayBuffer or TypedArray.'
+            );
+          }
+
+          try {
+            // arrayBufferResult.value is a Uint8Array view of the ArrayBuffer
+            let uint8Array = arrayBufferResult.value;
+
+            // Apply byte offset and length if this was a typed array view
+            const byteOffset = byteOffsetHandle ? (context.dump(byteOffsetHandle) as number) : 0;
+            const byteLength = byteLengthHandle
+              ? (context.dump(byteLengthHandle) as number)
+              : uint8Array.length;
+
+            // If we have offset/length that differ from the full buffer, create a view
+            if (byteOffset !== 0 || byteLength !== uint8Array.length) {
+              uint8Array = new Uint8Array(uint8Array.buffer, byteOffset, byteLength);
+            }
+
+            // Decode synchronously, then dispose the WASM-backed buffer
+            // (safe because decode() is synchronous and completes before dispose)
+            const text = decoder.decode(uint8Array, { stream });
+            return context.newString(text);
+          } finally {
+            arrayBufferResult.dispose();
+          }
+        } catch (e) {
+          logger?.error?.('TextDecoder.decode error', { error: e });
+          return context.newError(e instanceof Error ? e.message : String(e));
+        }
+      }
+    );
+
+    context.setProp(context.global, '__hostDecode', hostDecode);
+  }
+
+  // Define TextDecoder class in QuickJS
+  const classCode = `
+		class TextDecoder {
+			constructor(label, options) {
+				const result = __hostCreateDecoder(label, options);
+				this.__decoderId = result.id;
+				this.encoding = result.encoding;
+			}
+			
+			decode(input, options) {
+				if (input === undefined || input === null) {
+					return __hostDecode(this.__decoderId);
+				}
+				
+				let buffer, byteOffset, byteLength;
+				
+				if (input instanceof ArrayBuffer) {
+					buffer = input;
+					byteOffset = 0;
+					byteLength = input.byteLength;
+				} else if (ArrayBuffer.isView(input)) {
+					buffer = input.buffer;
+					byteOffset = input.byteOffset;
+					byteLength = input.byteLength;
+				} else {
+					throw new TypeError('input must be a BufferSource');
+				}
+				
+				const stream = options && options.stream === true;
+				return __hostDecode(this.__decoderId, buffer, byteOffset, byteLength, stream);
+			}
+		}
+	`;
+
+  const classHandle = defineClass(ctx, classCode, 'TextDecoder');
+  if (classHandle) {
+    using handle = classHandle;
+    context.setProp(context.global, 'TextDecoder', handle);
+
+    // Clean up internal globals — make non-enumerable/writable to hide from sandbox
+    // NOTE: The sandbox is not a hard security boundary. Internal helpers are hidden via
+    // enumerable: false but can still be called by name. This is acceptable because the bridges
+    // are the primary security boundary, not QuickJS containment. See Sandbox.ts for details.
+    const hideResult = context.evalCode(`(function() {
+      try { Object.defineProperty(globalThis, '__hostCreateDecoder', { enumerable: false, writable: false, configurable: false }); } catch(e) {}
+      try { Object.defineProperty(globalThis, '__hostDecode', { enumerable: false, writable: false, configurable: false }); } catch(e) {}
+    })()`);
+    if (hideResult.error) {
+      hideResult.error.dispose();
+    } else {
+      (hideResult as { value: QuickJSHandle }).value.dispose();
+    }
+
+    logger?.info?.('[Bridge] TextDecoder installed (optimized with getArrayBuffer)');
+  }
+}