@ricsam/isolate-client 0.1.4 → 0.1.6

package/README.md

@@ -18,6 +18,7 @@ npm add @ricsam/isolate-client
 - Module loader for custom ES module resolution
 - Custom functions callable from isolate code
 - Test environment and Playwright support
+- **Namespace-based runtime caching** for performance optimization
 
 ## Basic Usage
 
@@ -69,6 +70,79 @@ await runtime.dispose();
 await client.close();
 ```
 
+## Namespace-Based Runtime Caching
+
+For performance-critical applications, use **namespaces** to cache and reuse runtimes. Namespaced runtimes preserve their V8 isolate, context, and compiled module cache across dispose/create cycles:
+
+```typescript
+import { connect } from "@ricsam/isolate-client";
+
+const client = await connect({ socket: "/tmp/isolate.sock" });
+
+// Create a namespace for a tenant/user/session
+const namespace = client.createNamespace("tenant-123");
+
+// Create a runtime in this namespace
+const runtime = await namespace.createRuntime({
+  memoryLimitMB: 128,
+  moduleLoader: async (name) => loadModule(name),
+});
+
+console.log(runtime.reused); // false - first time
+
+// Import heavy modules (gets compiled and cached)
+await runtime.eval(`
+  import { heavyLibrary } from "@/heavy-module";
+  console.log("Module loaded!");
+`);
+
+// Dispose returns runtime to pool (soft-delete)
+await runtime.dispose();
+
+// Later: reuse the same namespace (same or different connection!)
+const client2 = await connect({ socket: "/tmp/isolate.sock" });
+const namespace2 = client2.createNamespace("tenant-123");
+const runtime2 = await namespace2.createRuntime({ /* options */ });
+
+console.log(runtime2.reused); // true - reused from pool!
+// Module cache preserved - no recompilation needed
+await runtime2.eval(`
+  import { heavyLibrary } from "@/heavy-module";  // instant!
+`);
+```
+
+### Namespace Interface
+
+```typescript
+interface Namespace {
+  /** The namespace ID */
+  readonly id: string;
+  /** Create a runtime in this namespace (cacheable on dispose) */
+  createRuntime(options?: RuntimeOptions): Promise<RemoteRuntime>;
+}
+```
+
+### What's Preserved vs Reset
+
+**Preserved on reuse (performance benefit):**
+- V8 Isolate instance
+- V8 Context
+- Compiled ES module cache
+- Global state and imported modules
+
+**Reset on reuse:**
+- Owner connection (new owner)
+- Callbacks (re-registered from new client)
+- Timers (cleared)
+- Console state (counters, timers, groups reset)
+
+### Behavior Notes
+
+- Non-namespaced runtimes (`client.createRuntime()`) work as before - true disposal
+- Namespaced runtimes are cached on dispose and evicted via LRU when `maxIsolates` limit is reached
+- Cross-client reuse is allowed - any connection can reuse a namespace by ID
+- A namespace can only have one active runtime at a time; creating a second runtime with the same namespace ID while one is active will fail
+
 ## Module Loader
 
 Register a custom module loader to handle dynamic `import()` calls:
@@ -340,7 +414,11 @@ await browser.close();
 ```typescript
 interface RemoteRuntime {
   readonly id: string;
+  /** True if runtime was reused from namespace pool */
+  readonly reused?: boolean;
+
   eval(code: string, filename?: string): Promise<void>;
+  /** Dispose runtime (soft-delete if namespaced, hard delete otherwise) */
   dispose(): Promise<void>;
 
   // Module handles
@@ -351,6 +429,17 @@ interface RemoteRuntime {
   readonly playwright: RemotePlaywrightHandle;
 }
 
+interface DaemonConnection {
+  /** Create a new runtime in the daemon */
+  createRuntime(options?: RuntimeOptions): Promise<RemoteRuntime>;
+  /** Create a namespace for runtime pooling/reuse */
+  createNamespace(id: string): Namespace;
+  /** Close the connection */
+  close(): Promise<void>;
+  /** Check if connected */
+  isConnected(): boolean;
+}
+
 interface RemoteFetchHandle {
   dispatchRequest(request: Request, options?: DispatchOptions): Promise<Response>;
   hasServeHandler(): Promise<boolean>;

package/dist/cjs/connection.cjs

@@ -35,7 +35,7 @@ __export(exports_connection, {
 module.exports = __toCommonJS(exports_connection);
 var import_node_net = require("net");
 var import_isolate_protocol = require("@ricsam/isolate-protocol");
-var import_isolate_playwright = require("@ricsam/isolate-playwright");
+var import_client = require("@ricsam/isolate-playwright/client");
 var DEFAULT_TIMEOUT = 30000;
 var isolateWsCallbacks = new Map;
 async function connect(options = {}) {
@@ -49,7 +49,8 @@ async function connect(options = {}) {
     nextStreamId: 1,
     connected: true,
     streamResponses: new Map,
-    uploadStreams: new Map
+    uploadStreams: new Map,
+    moduleSourceCache: new Map
   };
   const parser = import_isolate_protocol.createFrameParser();
   socket.on("data", (data) => {
@@ -64,15 +65,38 @@ async function connect(options = {}) {
   socket.on("close", () => {
     state.connected = false;
     for (const [, pending] of state.pendingRequests) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId);
+      }
       pending.reject(new Error("Connection closed"));
     }
     state.pendingRequests.clear();
+    for (const [, receiver] of state.streamResponses) {
+      receiver.state = "errored";
+      receiver.error = new Error("Connection closed");
+      const resolvers = receiver.pullResolvers.splice(0);
+      for (const resolver of resolvers) {
+        resolver();
+      }
+    }
+    state.streamResponses.clear();
+    for (const [, session] of state.uploadStreams) {
+      session.state = "closed";
+      if (session.creditResolver) {
+        session.creditResolver();
+      }
+    }
+    state.uploadStreams.clear();
   });
   socket.on("error", (err) => {
     console.error("Socket error:", err);
   });
   return {
     createRuntime: (runtimeOptions) => createRuntime(state, runtimeOptions),
+    createNamespace: (id) => ({
+      id,
+      createRuntime: (runtimeOptions) => createRuntime(state, runtimeOptions, id)
+    }),
     close: async () => {
       state.connected = false;
       socket.destroy();
@@ -173,10 +197,76 @@ function handleMessage(message, state) {
         streamId: msg.streamId,
         requestId: msg.requestId,
         metadata: msg.metadata,
-        chunks: [],
-        totalBytes: 0
+        controller: null,
+        state: "active",
+        pendingChunks: [],
+        pullResolvers: [],
+        controllerFinalized: false
       };
+      const readableStream = new ReadableStream({
+        start(controller) {
+          receiver.controller = controller;
+        },
+        pull(_controller) {
+          if (receiver.controllerFinalized) {
+            return;
+          }
+          while (receiver.pendingChunks.length > 0) {
+            const chunk = receiver.pendingChunks.shift();
+            receiver.controller.enqueue(chunk);
+          }
+          if (receiver.state === "closed") {
+            if (!receiver.controllerFinalized) {
+              receiver.controllerFinalized = true;
+              receiver.controller.close();
+            }
+            return Promise.resolve();
+          }
+          if (receiver.state === "errored") {
+            if (!receiver.controllerFinalized && receiver.error) {
+              receiver.controllerFinalized = true;
+              receiver.controller.error(receiver.error);
+            }
+            return Promise.resolve();
+          }
+          sendMessage(state.socket, {
+            type: import_isolate_protocol.MessageType.STREAM_PULL,
+            streamId: msg.streamId,
+            maxBytes: import_isolate_protocol.STREAM_DEFAULT_CREDIT
+          });
+          return new Promise((resolve) => {
+            receiver.pullResolvers.push(resolve);
+          });
+        },
+        cancel(_reason) {
+          receiver.state = "closed";
+          receiver.controllerFinalized = true;
+          const resolvers = receiver.pullResolvers.splice(0);
+          for (const resolver of resolvers) {
+            resolver();
+          }
+          sendMessage(state.socket, {
+            type: import_isolate_protocol.MessageType.STREAM_ERROR,
+            streamId: msg.streamId,
+            error: "Stream cancelled by consumer"
+          });
+          state.streamResponses.delete(msg.streamId);
+          return new Promise((resolve) => setTimeout(resolve, 0));
+        }
+      });
       state.streamResponses.set(msg.streamId, receiver);
+      const pending = state.pendingRequests.get(msg.requestId);
+      if (pending) {
+        state.pendingRequests.delete(msg.requestId);
+        if (pending.timeoutId)
+          clearTimeout(pending.timeoutId);
+        const response = new Response(readableStream, {
+          status: msg.metadata?.status ?? 200,
+          statusText: msg.metadata?.statusText ?? "OK",
+          headers: msg.metadata?.headers
+        });
+        pending.resolve({ response, __streaming: true });
+      }
       sendMessage(state.socket, {
         type: import_isolate_protocol.MessageType.STREAM_PULL,
         streamId: msg.streamId,
@@ -187,14 +277,14 @@ function handleMessage(message, state) {
     case import_isolate_protocol.MessageType.RESPONSE_STREAM_CHUNK: {
       const msg = message;
       const receiver = state.streamResponses.get(msg.streamId);
-      if (receiver) {
-        receiver.chunks.push(msg.chunk);
-        receiver.totalBytes += msg.chunk.length;
-        sendMessage(state.socket, {
-          type: import_isolate_protocol.MessageType.STREAM_PULL,
-          streamId: msg.streamId,
-          maxBytes: import_isolate_protocol.STREAM_DEFAULT_CREDIT
-        });
+      if (receiver && receiver.state === "active") {
+        if (receiver.pullResolvers.length > 0) {
+          receiver.controller.enqueue(msg.chunk);
+          const resolver = receiver.pullResolvers.shift();
+          resolver();
+        } else {
+          receiver.pendingChunks.push(msg.chunk);
+        }
       }
       break;
     }
@@ -202,20 +292,18 @@ function handleMessage(message, state) {
       const msg = message;
       const receiver = state.streamResponses.get(msg.streamId);
       if (receiver) {
-        const body = concatUint8Arrays(receiver.chunks);
-        const pending = state.pendingRequests.get(receiver.requestId);
-        if (pending) {
-          state.pendingRequests.delete(receiver.requestId);
-          if (pending.timeoutId)
-            clearTimeout(pending.timeoutId);
-          pending.resolve({
-            response: {
-              status: receiver.metadata?.status ?? 200,
-              statusText: receiver.metadata?.statusText ?? "OK",
-              headers: receiver.metadata?.headers ?? [],
-              body
-            }
-          });
+        receiver.state = "closed";
+        while (receiver.pendingChunks.length > 0) {
+          const chunk = receiver.pendingChunks.shift();
+          receiver.controller.enqueue(chunk);
+        }
+        if (!receiver.controllerFinalized) {
+          receiver.controllerFinalized = true;
+          receiver.controller.close();
+        }
+        const resolvers = receiver.pullResolvers.splice(0);
+        for (const resolver of resolvers) {
+          resolver();
         }
         state.streamResponses.delete(msg.streamId);
       }
@@ -242,12 +330,15 @@ function handleMessage(message, state) {
       }
       const receiver = state.streamResponses.get(msg.streamId);
       if (receiver) {
-        const pending = state.pendingRequests.get(receiver.requestId);
-        if (pending) {
-          state.pendingRequests.delete(receiver.requestId);
-          if (pending.timeoutId)
-            clearTimeout(pending.timeoutId);
-          pending.reject(new Error(msg.error));
+        receiver.state = "errored";
+        receiver.error = new Error(msg.error);
+        while (receiver.pendingChunks.length > 0) {
+          const chunk = receiver.pendingChunks.shift();
+          receiver.controller.enqueue(chunk);
+        }
+        const resolvers = receiver.pullResolvers.splice(0);
+        for (const resolver of resolvers) {
+          resolver();
         }
         state.streamResponses.delete(msg.streamId);
       }
@@ -257,16 +348,6 @@ function handleMessage(message, state) {
       console.warn(`Unexpected message type: ${message.type}`);
   }
 }
-function concatUint8Arrays(arrays) {
-  const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const arr of arrays) {
-    result.set(arr, offset);
-    offset += arr.length;
-  }
-  return result;
-}
 async function handleCallbackInvoke(invoke, state) {
   const callback = state.callbacks.get(invoke.callbackId);
   const response = {
@@ -316,7 +397,7 @@ function sendRequest(state, message, timeout = DEFAULT_TIMEOUT) {
     sendMessage(state.socket, message);
   });
 }
-async function createRuntime(state, options = {}) {
+async function createRuntime(state, options = {}, namespaceId) {
   const callbacks = {};
   if (options.console) {
     callbacks.console = registerConsoleCallbacks(state, options.console);
@@ -335,7 +416,7 @@ async function createRuntime(state, options = {}) {
   }
   let playwrightHandler;
   if (options.playwright) {
-    playwrightHandler = import_isolate_playwright.createPlaywrightHandler(options.playwright.page, {
+    playwrightHandler = import_client.createPlaywrightHandler(options.playwright.page, {
       timeout: options.playwright.timeout,
       baseUrl: options.playwright.baseUrl
     });
@@ -439,11 +520,13 @@ async function createRuntime(state, options = {}) {
       memoryLimitMB: options.memoryLimitMB,
       cwd: options.cwd,
       callbacks,
-      testEnvironment: testEnvironmentOption
+      testEnvironment: testEnvironmentOption,
+      namespaceId
     }
   };
   const result = await sendRequest(state, request);
   const isolateId = result.isolateId;
+  const reused = result.reused ?? false;
   const wsCommandCallbacks = new Set;
   isolateWsCallbacks.set(isolateId, wsCommandCallbacks);
   const fetchHandle = {
@@ -458,15 +541,21 @@ async function createRuntime(state, options = {}) {
         request: serializableRequest,
         options: opts
       };
+      const handleResponse = (res) => {
+        if (res.__streaming && res.response instanceof Response) {
+          return res.response;
+        }
+        return deserializeResponse(res.response);
+      };
       if (serialized.bodyStreamId !== undefined && bodyStream) {
         const streamId = serialized.bodyStreamId;
         const responsePromise = sendRequest(state, request2, opts?.timeout ?? DEFAULT_TIMEOUT);
         await sendBodyStream(state, streamId, bodyStream);
         const res = await responsePromise;
-        return deserializeResponse(res.response);
+        return handleResponse(res);
       } else {
         const res = await sendRequest(state, request2, opts?.timeout ?? DEFAULT_TIMEOUT);
-        return deserializeResponse(res.response);
+        return handleResponse(res);
       }
     },
     async getUpgradeRequest() {
@@ -681,6 +770,7 @@ async function createRuntime(state, options = {}) {
   return {
     id: isolateId,
     isolateId,
+    reused,
     fetch: fetchHandle,
     timers: timersHandle,
     console: consoleHandle,
@@ -814,7 +904,14 @@ function registerFsCallbacks(state, callbacks) {
 function registerModuleLoaderCallback(state, callback) {
   const callbackId = state.nextCallbackId++;
   state.callbacks.set(callbackId, async (moduleName) => {
-    return callback(moduleName);
+    const specifier = moduleName;
+    const cached = state.moduleSourceCache.get(specifier);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const source = await callback(specifier);
+    state.moduleSourceCache.set(specifier, source);
+    return source;
   });
   return { callbackId, name: "moduleLoader", type: "async" };
 }
@@ -1141,4 +1238,4 @@ async function sendBodyStream(state, streamId, body) {
 }
 })
 
-//# debugId=7380B90E2B96832A64756E2164756E21
+//# debugId=6FA96113BD7C15F464756E2164756E21