@ricsam/isolate 0.0.1 → 0.1.0

package/dist/types/internal/console/index.d.ts

@@ -0,0 +1,108 @@
+import ivm from "isolated-vm";
+/**
+ * Console entry types for structured console output.
+ * Each entry type captures the specific data needed to render like DevTools.
+ * Output is pre-formatted as stdout strings (like Node.js console) inside the sandbox.
+ */
+export type ConsoleEntry = {
+    type: "output";
+    level: "log" | "warn" | "error" | "info" | "debug";
+    stdout: string;
+    groupDepth: number;
+} | {
+    /** Browser console output (from Playwright page, not sandbox) */
+    type: "browserOutput";
+    level: string;
+    stdout: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    timestamp: number;
+} | {
+    type: "dir";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "table";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "time";
+    label: string;
+    duration: number;
+    groupDepth: number;
+} | {
+    type: "timeLog";
+    label: string;
+    duration: number;
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "count";
+    label: string;
+    count: number;
+    groupDepth: number;
+} | {
+    type: "countReset";
+    label: string;
+    groupDepth: number;
+} | {
+    type: "assert";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "group";
+    label: string;
+    collapsed: boolean;
+    groupDepth: number;
+} | {
+    type: "groupEnd";
+    groupDepth: number;
+} | {
+    type: "clear";
+} | {
+    type: "trace";
+    stdout: string;
+    stack: string;
+    groupDepth: number;
+};
+/**
+ * Console options with a single structured callback.
+ */
+export interface ConsoleOptions {
+    /**
+     * Callback invoked for each console operation.
+     * Receives a structured entry with all data needed to render the output.
+     */
+    onEntry?: (entry: ConsoleEntry) => void;
+}
+/**
+ * Console handle for accessing internal state.
+ */
+export interface ConsoleHandle {
+    dispose(): void;
+    reset(): void;
+    getTimers(): Map<string, number>;
+    getCounters(): Map<string, number>;
+    getGroupDepth(): number;
+}
+/**
+ * Setup console API in an isolated-vm context
+ *
+ * Injects console.log, console.warn, console.error, console.info, console.debug,
+ * console.trace, console.dir, console.table, console.time, console.timeEnd,
+ * console.timeLog, console.count, console.countReset, console.group,
+ * console.groupCollapsed, console.groupEnd, console.clear, console.assert
+ *
+ * @example
+ * const handle = await setupConsole(context, {
+ *   onEntry: (entry) => {
+ *     if (entry.type === 'output') {
+ *       console.log(`[${entry.level}]`, ...entry.args);
+ *     }
+ *   }
+ * });
+ */
+export declare function setupConsole(context: ivm.Context, options?: ConsoleOptions): Promise<ConsoleHandle>;

package/dist/types/internal/console/utils.d.ts

@@ -0,0 +1,27 @@
+import type { ConsoleOptions } from "./index.ts";
+/**
+ * Simple console callback interface for basic usage.
+ */
+export interface SimpleConsoleCallbacks {
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+    info?: (message: string) => void;
+    debug?: (message: string) => void;
+}
+/**
+ * Helper to create ConsoleOptions from simple callbacks.
+ * Routes log-level outputs to the appropriate callback and handles assertions.
+ *
+ * @example
+ * ```typescript
+ * const runtime = await createRuntime({
+ *   console: simpleConsoleHandler({
+ *     log: (msg) => console.log('[sandbox]', msg),
+ *     warn: (msg) => console.warn('[sandbox]', msg),
+ *     error: (msg) => console.error('[sandbox]', msg),
+ *   })
+ * });
+ * ```
+ */
+export declare function simpleConsoleHandler(callbacks: SimpleConsoleCallbacks): ConsoleOptions;

package/dist/types/internal/core/index.d.ts

@@ -0,0 +1,119 @@
+import ivm from "isolated-vm";
+export type { Isolate, Context, Reference } from "isolated-vm";
+/**
+ * Clear all instance state (for testing)
+ */
+export declare function clearAllInstanceState(): void;
+/**
+ * Cleanup all handles created during unmarshalling for a context
+ */
+export declare function cleanupUnmarshaledHandles(context: ivm.Context): void;
+export interface MarshalOptions {
+    maxDepth?: number;
+}
+export interface UnmarshalOptions {
+    maxDepth?: number;
+}
+/**
+ * Marshal a JavaScript value to an isolated-vm Reference.
+ * Converts host values into values that can be used inside the isolate.
+ */
+export declare function marshal(context: ivm.Context, value: unknown, options?: MarshalOptions): ivm.Reference;
+/**
+ * Unmarshal an isolated-vm Reference or value to a JavaScript value.
+ * Converts isolate values back to host values.
+ */
+export declare function unmarshal(context: ivm.Context, value: ivm.Reference | unknown, options?: UnmarshalOptions): unknown;
+/**
+ * Scope for managing reference lifecycle
+ */
+export interface Scope {
+    /**
+     * Track a reference for automatic cleanup when scope exits
+     */
+    manage<T extends ivm.Reference>(ref: T): T;
+    /**
+     * Marshal a value and track the resulting reference
+     */
+    marshal(value: unknown, options?: MarshalOptions): ivm.Reference;
+}
+/**
+ * Execute a synchronous callback with automatic reference cleanup.
+ * All references tracked via scope.manage() will be released when the scope exits.
+ */
+export declare function withScope<T>(context: ivm.Context, callback: (scope: Scope) => T): T;
+/**
+ * Execute an async callback with automatic reference cleanup.
+ * All references tracked via scope.manage() will be released when the scope exits.
+ */
+export declare function withScopeAsync<T>(context: ivm.Context, callback: (scope: Scope) => Promise<T>): Promise<T>;
+/**
+ * Define a synchronous function that can be called from the isolate.
+ * Arguments are automatically unmarshalled, return values are automatically marshalled.
+ */
+export declare function defineFunction(context: ivm.Context, name: string, fn: (...args: unknown[]) => unknown): ivm.Reference;
+/**
+ * Define an async function that can be called from the isolate.
+ * Uses ivm.Reference.apply with promise transfer so isolate code can truly await
+ * host work without blocking the isolate thread.
+ */
+export declare function defineAsyncFunction(context: ivm.Context, name: string, fn: (...args: unknown[]) => Promise<unknown>): ivm.Reference;
+export interface PropertyDescriptor<TState = unknown> {
+    get?: (state: TState) => unknown;
+    set?: (state: TState, value: unknown) => void;
+    value?: unknown;
+    writable?: boolean;
+    enumerable?: boolean;
+    configurable?: boolean;
+}
+export interface ClassDefinition<TState extends object = object> {
+    name: string;
+    construct?: (args: unknown[]) => TState;
+    methods?: Record<string, {
+        fn: (state: TState, ...args: unknown[]) => unknown;
+        async?: boolean;
+    }>;
+    properties?: Record<string, PropertyDescriptor<TState>>;
+    staticMethods?: Record<string, {
+        fn: (...args: unknown[]) => unknown;
+        async?: boolean;
+    }>;
+    staticProperties?: Record<string, unknown>;
+    extends?: string;
+}
+/**
+ * Define a class that can be instantiated in the isolate.
+ * Instance state is stored on the host side, accessed via unique IDs.
+ */
+export declare function defineClass<TState extends object = object>(context: ivm.Context, definition: ClassDefinition<TState>): ivm.Reference;
+export interface SetupCoreOptions {
+    /** Whether to inject TextEncoder/TextDecoder */
+    textEncoding?: boolean;
+    /** Whether to inject URL/URLSearchParams */
+    url?: boolean;
+    /** Whether to inject Blob/File */
+    blob?: boolean;
+    /** Whether to inject Streams */
+    streams?: boolean;
+    /** Whether to inject DOMParser and DOM constructors */
+    domParser?: boolean;
+}
+export interface CoreHandle {
+    dispose(): void;
+}
+/**
+ * Setup core APIs in an isolated-vm context.
+ *
+ * Injects the following globals:
+ * - ReadableStream, WritableStream, TransformStream
+ * - ReadableStreamDefaultReader, WritableStreamDefaultWriter
+ * - Blob
+ * - File
+ * - DOMException
+ * - DOMParser
+ * - Node, Document, DocumentFragment, DocumentType, Element, Attr, Text, Comment
+ * - Event, EventTarget, CustomEvent
+ * - URL, URLSearchParams
+ * - TextEncoder, TextDecoder
+ */
+export declare function setupCore(context: ivm.Context, options?: SetupCoreOptions): Promise<CoreHandle>;

package/dist/types/internal/crypto/index.d.ts

@@ -0,0 +1,18 @@
+import ivm from "isolated-vm";
+export interface CryptoHandle {
+    dispose(): void;
+}
+/**
+ * Setup Web Crypto API in an isolated-vm context
+ *
+ * Provides crypto.getRandomValues and crypto.randomUUID
+ *
+ * @example
+ * const handle = await setupCrypto(context);
+ * await context.eval(`
+ *   const uuid = crypto.randomUUID();
+ *   const array = new Uint8Array(16);
+ *   crypto.getRandomValues(array);
+ * `);
+ */
+export declare function setupCrypto(context: ivm.Context): Promise<CryptoHandle>;

package/dist/types/internal/daemon/callback-fs-handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Callback-based FileSystemHandler adapter.
+ *
+ * Adapts simple client callbacks (readFile, writeFile, etc.) to the
+ * FileSystemHandler interface used by ../fs/index.ts.
+ */
+import type { FileSystemHandler } from "../fs/index.ts";
+import type { ConnectionState, CallbackContext } from "./types.ts";
+interface InvokeClientCallback {
+    (connection: ConnectionState, callbackId: number, args: unknown[], options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+interface CallbackFsHandlerOptions {
+    connection: ConnectionState;
+    callbackContext: CallbackContext;
+    invokeClientCallback: InvokeClientCallback;
+    basePath?: string;
+    getSignal?: () => AbortSignal | undefined;
+}
+/**
+ * Create a FileSystemHandler that invokes client callbacks.
+ *
+ * Maps WHATWG FileSystem API operations to simple POSIX-like callbacks.
+ * Uses callbackContext for dynamic callback ID lookup to support runtime reuse.
+ */
+export declare function createCallbackFileSystemHandler(options: CallbackFsHandlerOptions): FileSystemHandler;
+export {};

package/dist/types/internal/daemon/connection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Connection handling for the isolate daemon.
+ */
+import type { Socket } from "node:net";
+import type { DaemonState } from "./types.ts";
+/**
+ * Handle a new client connection.
+ */
+export declare function handleConnection(socket: Socket, state: DaemonState): void;

package/dist/types/internal/daemon/daemon.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/internal/daemon/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ./index.ts
+ *
+ * Node.js daemon for running isolated-vm runtimes accessible via IPC.
+ */
+import type { DaemonOptions, DaemonHandle, DaemonStats } from "./types.ts";
+export type { DaemonOptions, DaemonHandle, DaemonStats };
+/**
+ * Start the isolate daemon.
+ *
+ * @param options - Daemon configuration options
+ * @returns Handle to control the daemon
+ */
+export declare function startDaemon(options?: DaemonOptions): Promise<DaemonHandle>;

package/dist/types/internal/daemon/runtime-pool.d.ts

@@ -0,0 +1,16 @@
+import type { DaemonState, DaemonStats, IsolateInstance } from "./types.ts";
+export interface RuntimePoolSnapshot {
+    activeIsolates: number;
+    pooledIsolates: number;
+    trackedIsolates: number;
+    activeConnections: number;
+    maxIsolates: number;
+    namespacedIsolates: number;
+    poisonedIsolates: number;
+}
+type RuntimePoolState = Pick<DaemonState, "isolates" | "connections" | "options">;
+export declare function collectRuntimePoolSnapshot(state: RuntimePoolState): RuntimePoolSnapshot;
+export declare function createDaemonStats(state: DaemonState): DaemonStats;
+export declare function formatRuntimePoolSnapshot(snapshot: RuntimePoolSnapshot): string;
+export declare function formatRuntimeLabel(instance: Pick<IsolateInstance, "isolateId" | "namespaceId">): string;
+export {};

package/dist/types/internal/daemon/types.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Internal types for the isolate daemon.
+ */
+import type { Socket } from "node:net";
+import type { RuntimeHandle } from "../runtime/index.ts";
+import type { CallbackRegistration } from "../protocol/index.ts";
+/**
+ * Options for starting the daemon.
+ */
+export interface DaemonOptions {
+    /** Unix socket path (preferred) */
+    socketPath?: string;
+    /** TCP host (fallback) */
+    host?: string;
+    /** TCP port (fallback) */
+    port?: number;
+    /** Maximum number of isolates */
+    maxIsolates?: number;
+    /** Default memory limit for isolates in megabytes */
+    defaultMemoryLimitMB?: number;
+}
+/**
+ * Handle returned by startDaemon.
+ */
+export interface DaemonHandle {
+    /** Close the daemon and all connections */
+    close(): Promise<void>;
+    /** Get daemon statistics */
+    getStats(): DaemonStats;
+    /** Socket path or address the daemon is listening on */
+    address: string;
+}
+/**
+ * Daemon statistics.
+ */
+export interface DaemonStats {
+    /** Currently owned runtimes that are not soft-disposed */
+    activeIsolates: number;
+    /** Soft-disposed namespaced runtimes kept in the reuse pool */
+    pooledIsolates: number;
+    /** Total runtimes tracked by the daemon (counts toward maxIsolates) */
+    trackedIsolates: number;
+    activeConnections: number;
+    totalIsolatesCreated: number;
+    totalRequestsProcessed: number;
+}
+/**
+ * Internal state for a single isolate instance.
+ */
+export interface IsolateInstance {
+    isolateId: string;
+    runtime: RuntimeHandle;
+    ownerConnection: Socket | null;
+    callbacks: Map<number, CallbackRegistration>;
+    createdAt: number;
+    lastActivity: number;
+    runtimeAbortController?: AbortController;
+    /** Functions returned by custom function calls (callable from isolate) */
+    returnedCallbacks?: Map<number, Function>;
+    /** Promises returned by custom function calls (resolvable from isolate) */
+    returnedPromises?: Map<number, Promise<unknown>>;
+    /** Async iterators returned by custom function calls (iterable from isolate) */
+    returnedIterators?: Map<number, AsyncIterator<unknown>>;
+    /** Next ID for daemon-local callback registration (starts at high number to avoid conflicts) */
+    nextLocalCallbackId?: number;
+    /** Namespace ID for pooling/reuse (if set, runtime is cached on dispose) */
+    namespaceId?: string;
+    /** Whether this runtime is soft-deleted (disposed but cached for reuse) */
+    isDisposed: boolean;
+    /** Whether runtime hit unrecoverable module-linking state and must not be reused */
+    isPoisoned: boolean;
+    /** Timestamp when runtime was disposed (for LRU eviction) */
+    disposedAt?: number;
+    /** Mutable context for callbacks - allows updating callback IDs/connection on reuse */
+    callbackContext?: CallbackContext;
+    /** In-flight test run (for result forwarding across reconnections) */
+    pendingTestRun?: {
+        promise: Promise<unknown>;
+    };
+}
+/**
+ * Mutable context for callbacks that can be updated on runtime reuse.
+ * This allows closures to reference current callback IDs instead of captured values.
+ */
+export interface CallbackContext {
+    /** Current connection state (updated on reuse) */
+    connection: ConnectionState | null;
+    /** Console onEntry callback ID */
+    consoleOnEntry?: number;
+    /** Fetch callback ID */
+    fetch?: number;
+    /** Module loader callback ID */
+    moduleLoader?: number;
+    /** testEnvironment.onEvent callback ID */
+    testEnvironmentOnEvent?: number;
+    /** Playwright callback IDs */
+    playwright: {
+        handlerCallbackId?: number;
+        onBrowserConsoleLogCallbackId?: number;
+        onNetworkRequestCallbackId?: number;
+        onNetworkResponseCallbackId?: number;
+    };
+    /** FS callback IDs by name */
+    fs: {
+        readFile?: number;
+        writeFile?: number;
+        stat?: number;
+        readdir?: number;
+        unlink?: number;
+        mkdir?: number;
+        rmdir?: number;
+    };
+    /** Custom function callback IDs by name */
+    custom: Map<string, number>;
+    /** Reconnection promise — set when connection drops, resolved when a new connection arrives */
+    reconnectionPromise?: {
+        promise: Promise<ConnectionState>;
+        resolve: (conn: ConnectionState) => void;
+        reject: (err: Error) => void;
+        timeoutId: ReturnType<typeof setTimeout>;
+    };
+}
+/**
+ * Pending request waiting for response.
+ */
+export interface PendingRequest {
+    resolve: (result: unknown) => void;
+    reject: (error: Error) => void;
+    /** Optional cleanup hook (e.g. remove listeners, clear timeout) */
+    cleanup?: () => void;
+    /** Optional metadata for callback requests */
+    callbackId?: number;
+}
+/**
+ * Stream session for tracking active streams.
+ */
+export interface StreamSession {
+    streamId: number;
+    direction: "upload" | "download";
+    requestId: number;
+    state: "active" | "closing" | "closed";
+    bytesTransferred: number;
+    credit: number;
+    creditResolver?: () => void;
+    cancelReader?: () => void;
+}
+/**
+ * Stream receiver for collecting uploaded stream chunks.
+ */
+export interface StreamReceiver {
+    streamId: number;
+    requestId: number;
+    chunks: Uint8Array[];
+    totalBytes: number;
+    resolve: (body: Uint8Array) => void;
+    reject: (error: Error) => void;
+}
+/**
+ * Callback stream receiver for streaming fetch callback responses.
+ * Receives streamed response body from client for fetch callbacks.
+ */
+export interface CallbackStreamReceiver {
+    streamId: number;
+    requestId: number;
+    metadata: {
+        status: number;
+        statusText: string;
+        headers: [string, string][];
+    };
+    controller: ReadableStreamDefaultController<Uint8Array>;
+    state: "active" | "closed" | "errored";
+    pendingChunks: Uint8Array[];
+    error?: Error;
+    pullResolvers: Array<() => void>;
+    controllerFinalized: boolean;
+}
+/**
+ * Internal state for a client connection.
+ */
+export interface ConnectionState {
+    socket: Socket;
+    isolates: Set<string>;
+    pendingRequests: Map<number, PendingRequest>;
+    pendingCallbacks: Map<number, PendingRequest>;
+    nextRequestId: number;
+    nextCallbackId: number;
+    nextStreamId: number;
+    /** Active download streams (daemon sending to client) */
+    activeStreams: Map<number, StreamSession>;
+    /** Active upload stream receivers (client sending to daemon) */
+    streamReceivers: Map<number, StreamReceiver>;
+    /** Active callback stream receivers (for streaming fetch callback responses) */
+    callbackStreamReceivers: Map<number, CallbackStreamReceiver>;
+    /** Abort controllers for in-flight DISPATCH_REQUEST calls keyed by requestId */
+    dispatchAbortControllers: Map<number, AbortController>;
+    /** Request IDs aborted before DISPATCH_REQUEST was registered */
+    earlyAbortedDispatches: Set<number>;
+}
+/**
+ * Global daemon state.
+ */
+export interface DaemonState {
+    isolates: Map<string, IsolateInstance>;
+    connections: Map<Socket, ConnectionState>;
+    stats: DaemonStats;
+    options: Required<DaemonOptions>;
+    /** Index of namespaced runtimes by namespace ID for fast lookup */
+    namespacedRuntimes: Map<string, IsolateInstance>;
+    /** Track in-flight namespace creations to prevent thundering herd */
+    namespacedCreatesInFlight: Set<string>;
+}

package/dist/types/internal/encoding/index.d.ts

@@ -0,0 +1,21 @@
+import type ivm from "isolated-vm";
+export interface EncodingHandle {
+    dispose(): void;
+}
+/**
+ * Setup encoding APIs in an isolated-vm context
+ *
+ * Injects:
+ * - atob/btoa for Base64 encoding/decoding
+ * - Buffer class for binary data handling (utf8, base64, hex)
+ *
+ * @example
+ * const handle = await setupEncoding(context);
+ * await context.eval(`
+ *   const encoded = btoa("hello");
+ *   const decoded = atob(encoded);
+ *   const buf = Buffer.from("hello");
+ *   const hex = buf.toString("hex");
+ * `);
+ */
+export declare function setupEncoding(context: ivm.Context): Promise<EncodingHandle>;