@liquidmetal-ai/precip 1.0.0

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

@@ -0,0 +1,229 @@
+/**
+ * Tests for Actor Bridge
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { z } from 'zod';
+import { executeWithAsyncHost } from '../test-helper.js';
+import { installActor } from './actor.js';
+import type { ActorMountInfo } from '../../types.js';
+
+describe('Actor Bridge', () => {
+  // Mock actor stub
+  const createMockActorStub = () => ({
+    getState: vi.fn().mockResolvedValue({ loggedIn: true, userId: 'user-123' }),
+    updatePrefs: vi.fn().mockResolvedValue({ success: true }),
+    clearSession: vi.fn().mockResolvedValue({ success: true })
+  });
+
+  // Mock actor namespace
+  const createMockActorNamespace = (stub: ReturnType<typeof createMockActorStub>) => ({
+    idFromName: vi.fn().mockImplementation((name: string) => ({
+      toString: () => name,
+      equals: () => false,
+      name
+    })),
+    get: vi.fn().mockReturnValue(stub)
+  });
+
+  const createActorMountInfo = (stub: ReturnType<typeof createMockActorStub>): ActorMountInfo => ({
+    name: 'session',
+    type: 'actor',
+    resource: createMockActorNamespace(stub) as any,
+    description: 'Per-user session state',
+    methods: {
+      getState: {
+        description: 'Get current session state',
+        params: z.tuple([]),
+        returns: z.object({
+          loggedIn: z.boolean(),
+          userId: z.string().optional()
+        })
+      },
+      updatePrefs: {
+        description: 'Update user preferences',
+        params: z.tuple([z.object({
+          theme: z.enum(['light', 'dark']).optional(),
+          notifications: z.boolean().optional()
+        }).describe('prefs')]),
+        returns: z.object({ success: z.boolean() })
+      },
+      clearSession: {
+        description: 'Clear session data',
+        params: z.tuple([]),
+        returns: z.object({ success: z.boolean() })
+      }
+    }
+  });
+
+  it('should call actor method with correct arguments', async () => {
+    const mockStub = createMockActorStub();
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			const session = await actor('/session', 'user-123');
+			const state = await session.getState();
+			return state;
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result).toEqual({ loggedIn: true, userId: 'user-123' });
+    expect(mockStub.getState).toHaveBeenCalledTimes(1);
+  });
+
+  it('should pass parameters to actor method', async () => {
+    const mockStub = createMockActorStub();
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			const session = await actor('/session', 'user-456');
+			const result = await session.updatePrefs({ theme: 'dark' });
+			return result;
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result).toEqual({ success: true });
+    expect(mockStub.updatePrefs).toHaveBeenCalledWith({ theme: 'dark' });
+  });
+
+  it('should validate params against schema', async () => {
+    const mockStub = createMockActorStub();
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			const session = await actor('/session', 'user-789');
+			try {
+				// Pass invalid theme value
+				const result = await session.updatePrefs({ theme: 'invalid-theme' });
+				return { error: false, result };
+			} catch (e) {
+				return { error: true, message: e.message || String(e) };
+			}
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('Invalid');
+  });
+
+  it('should return error for unknown mount', async () => {
+    const mockStub = createMockActorStub();
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			try {
+				const unknown = await actor('/nonexistent', 'test');
+				return { error: false };
+			} catch (e) {
+				return { error: true, message: e.message || String(e) };
+			}
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('not found');
+  });
+
+  it('should cache actor stubs', async () => {
+    const mockStub = createMockActorStub();
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			// Get the same actor twice
+			const session1 = await actor('/session', 'user-same');
+			const session2 = await actor('/session', 'user-same');
+			
+			// Call methods on both
+			await session1.getState();
+			await session2.getState();
+			
+			return { called: true };
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    // The namespace.get should only be called once due to caching
+    // Note: Due to how the current implementation works, this may be called twice
+    // since we're creating new stub handles. This test documents the current behavior.
+    expect(mockStub.getState).toHaveBeenCalledTimes(2);
+  });
+
+  it('should handle actor method errors', async () => {
+    const mockStub = createMockActorStub();
+    mockStub.clearSession.mockRejectedValue(new Error('Session already cleared'));
+    const mountInfo = createActorMountInfo(mockStub);
+    const actorMounts = new Map<string, ActorMountInfo>([['session', mountInfo]]);
+
+    const code = `
+			const session = await actor('/session', 'user-error');
+			try {
+				await session.clearSession();
+				return { error: false };
+			} catch (e) {
+				return { error: true, message: e.message || String(e) };
+			}
+		`;
+
+    const result = await executeWithAsyncHost(
+      code,
+      {},
+      {
+        timeoutMs: 5000,
+        bridgeInstallers: [ctx => installActor(ctx, actorMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('already cleared');
+  });
+});

package/src/sandbox/bridges/actor.ts

@@ -0,0 +1,195 @@
+/**
+ * Actor Bridge - Provides actor(path, instanceId) with schema-based method stubs
+ *
+ * Usage in sandbox:
+ *   const session = await actor('/sessions', 'user-123');
+ *   const state = await session.getState();
+ *   await session.updatePrefs({ theme: 'dark' });
+ *
+ * Features:
+ * - Explicit methods generated from Zod schemas
+ * - Stub caching per actor instance
+ * - Parameter validation against schema
+ * - ReadableStream return handling
+ */
+
+import type { QuickJSHandle } from 'quickjs-emscripten-core';
+import type { BridgeContext } from './types.js';
+import type { ActorMountInfo, ActorMethodSchema } from '../../types.js';
+import type { Actor, ActorStub } from '@liquidmetal-ai/raindrop-framework';
+import { convertToHandle } from './utils.js';
+import {
+  createStreamCleanupHandler,
+  createIdCounter,
+  nextId,
+  type StreamRegistry,
+  withTrackedPromise,
+  createReaderHandle,
+  parseMountPath
+} from './shared/index.js';
+
+/**
+ * Install actor API in the sandbox
+ */
+export function installActor(ctx: BridgeContext, actorMounts: Map<string, ActorMountInfo>): void {
+  const { context, logger, cleanupHandlers } = ctx;
+
+  // Cache for host actor stubs: "mountName:instanceName" → hostStub
+  const hostStubCache = new Map<string, ActorStub<Actor<unknown>>>();
+
+  // Stream registry for any streaming returns
+  const registry: StreamRegistry = {
+    hostStreams: new Map<number, ReadableStream>(),
+    hostReaders: new Map<number, ReadableStreamDefaultReader>()
+  };
+  const streamIdCounter = createIdCounter();
+  const readerIdCounter = createIdCounter();
+
+  // Register cleanup handlers
+  cleanupHandlers.push(() => {
+    hostStubCache.clear();
+    logger?.info?.('[Actor Bridge] Cleaned up host stub cache');
+  });
+
+  cleanupHandlers.push(createStreamCleanupHandler(registry, 'Actor', logger));
+
+  // actor(path, instanceId) → stub with methods
+  {
+    using actorFunction = context.newFunction(
+      'actor',
+      (pathHandle: QuickJSHandle, nameHandle: QuickJSHandle) => {
+        // Validate inputs — QuickJS converts host exceptions thrown in
+        // newFunction callbacks into sandbox-visible thrown errors
+        const path = context.dump(pathHandle);
+        if (typeof path !== 'string') {
+          throw new Error('actor() first argument must be a string path');
+        }
+        const instanceName = context.dump(nameHandle);
+        if (typeof instanceName !== 'string') {
+          throw new Error('actor() second argument must be a string instance name');
+        }
+
+        // Parse the path to get mount
+        const { mount } = parseMountPath(path, actorMounts, 'Actor');
+
+        const cacheKey = `${mount.name}:${instanceName}`;
+
+        // Get or create the host stub (cached)
+        let hostStub = hostStubCache.get(cacheKey);
+        if (!hostStub) {
+          const id = mount.resource.idFromName(instanceName);
+          hostStub = mount.resource.get(id);
+          hostStubCache.set(cacheKey, hostStub);
+        }
+
+        // Always create a new sandbox stub handle
+        // (QuickJS handles can't be reused after being returned)
+        return createActorStub(ctx, hostStub, mount.methods, registry, {
+          streamIdCounter,
+          readerIdCounter
+        });
+      }
+    );
+
+    context.setProp(context.global, 'actor', actorFunction);
+  }
+
+  logger?.info?.(`[Actor Bridge] Installed with ${actorMounts.size} mount(s)`);
+}
+
+/**
+ * Create a sandbox stub object with methods defined by the schema
+ */
+function createActorStub(
+  ctx: BridgeContext,
+  hostStub: ActorStub<Actor<unknown>>,
+  methods: Record<string, ActorMethodSchema>,
+  registry: StreamRegistry,
+  counters: { streamIdCounter: { value: number }; readerIdCounter: { value: number } }
+): QuickJSHandle {
+  const { context, logger } = ctx;
+
+  const stubHandle = context.newObject();
+
+  // Create a method for each schema-defined method
+  for (const [methodName, schema] of Object.entries(methods)) {
+    using methodHandle = context.newFunction(methodName, (...args: QuickJSHandle[]) => {
+      // Dump all arguments from the sandbox
+      const jsArgs = args.map(arg => context.dump(arg));
+
+      // Validate the argument tuple against the schema
+      const parseResult = schema.params.safeParse(jsArgs);
+
+      // If validation fails, reject immediately
+      if (!parseResult.success) {
+        const errorMessage = `Invalid params for ${methodName}: ${parseResult.error.message}`;
+        return withTrackedPromise(ctx, async (deferred) => {
+          using errHandle = context.newString(errorMessage);
+          deferred.reject(errHandle);
+          ctx.runtime.executePendingJobs();
+        });
+      }
+
+      return withTrackedPromise(ctx, async (deferred) => {
+        // Call the actual actor method
+        const result = await (hostStub as any)[methodName](...parseResult.data);
+
+        // Handle ReadableStream specially
+        if (result instanceof ReadableStream) {
+          using streamHandle = createStreamHandle(ctx, result, registry, counters);
+          deferred.resolve(streamHandle);
+        } else {
+          // Validate return type (optional, just for safety)
+          const returnResult = schema.returns.safeParse(result);
+          if (!returnResult.success) {
+            logger?.warn?.(
+              `[Actor Bridge] Return type mismatch for ${methodName}: ${returnResult.error.message}`
+            );
+          }
+
+          using resultHandle = convertToHandle(context, result);
+          deferred.resolve(resultHandle);
+        }
+
+        ctx.runtime.executePendingJobs();
+      });
+    });
+
+    context.setProp(stubHandle, methodName, methodHandle);
+  }
+
+  return stubHandle;
+}
+
+/**
+ * Create a ReadableStream handle for streaming returns
+ */
+function createStreamHandle(
+  ctx: BridgeContext,
+  stream: ReadableStream,
+  registry: StreamRegistry,
+  counters: { streamIdCounter: { value: number }; readerIdCounter: { value: number } }
+): QuickJSHandle {
+  const { context } = ctx;
+
+  const streamId = nextId(counters.streamIdCounter);
+  registry.hostStreams.set(streamId, stream);
+
+  const streamHandle = context.newObject();
+
+  // Add getReader() method
+  {
+    using getReaderMethod = context.newFunction('getReader', () => {
+      const reader = stream.getReader();
+      const readerId = nextId(counters.readerIdCounter);
+      registry.hostReaders.set(readerId, reader);
+
+      return createReaderHandle(ctx, reader, () => {
+        registry.hostReaders.delete(readerId);
+      });
+    });
+    context.setProp(streamHandle, 'getReader', getReaderMethod);
+  }
+
+  return streamHandle;
+}