@ricsam/isolate-client 0.0.1 → 0.1.1

package/README.md

@@ -1,45 +1,114 @@
 # @ricsam/isolate-client
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/isolate-client`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Client library for connecting to the isolate daemon. Works with **any JavaScript runtime** (Node.js, Bun, Deno) since it only requires standard socket APIs.
+
+```bash
+npm add @ricsam/isolate-client
+```
+
+**Features:**
+- Connect via Unix socket or TCP
+- Create and manage remote runtimes
+- Execute code in isolated V8 contexts
+- Dispatch HTTP requests to isolate handlers
+- Bidirectional callbacks (console, fetch, fs)
+- Test environment and Playwright support
+
+**Basic Usage:**
+
+```typescript
+import { connect } from "@ricsam/isolate-client";
+
+// Connect to daemon
+const client = await connect({
+  socket: "/tmp/isolate-daemon.sock",
+  // Or TCP: host: "127.0.0.1", port: 47891
+});
+
+// Create a runtime with callbacks
+const runtime = await client.createRuntime({
+  memoryLimit: 128,
+  console: {
+    log: (...args) => console.log("[isolate]", ...args),
+    error: (...args) => console.error("[isolate]", ...args),
+  },
+  fetch: async (request) => fetch(request),
+  fs: {
+    readFile: async (path) => Bun.file(path).arrayBuffer(),
+    writeFile: async (path, data) => Bun.write(path, data),
+    stat: async (path) => {
+      const stat = await Bun.file(path).stat();
+      return { isFile: true, isDirectory: false, size: stat.size };
+    },
+  },
+});
+
+// Execute code
+await runtime.eval(`console.log("Hello from isolate!")`);
+
+// Set up HTTP handler and dispatch requests
+await runtime.eval(`
+  serve({
+    fetch(request) {
+      return Response.json({ message: "Hello!" });
+    }
+  });
+`);
+
+const response = await runtime.dispatchRequest(
+  new Request("http://localhost/api")
+);
+console.log(await response.json()); // { message: "Hello!" }
+
+// Cleanup
+await runtime.dispose();
+await client.close();
+```
+
+**Test Environment:**
+
+```typescript
+// Setup test framework in isolate
+await runtime.setupTestEnvironment();
+
+// Define tests
+await runtime.eval(`
+  describe("math", () => {
+    it("adds numbers", () => {
+      expect(1 + 1).toBe(2);
+    });
+  });
+`);
+
+// Run tests
+const results = await runtime.runTests();
+console.log(`${results.passed}/${results.total} passed`);
+```
+
+**Playwright Integration:**
+
+```typescript
+// Setup Playwright (daemon launches browser)
+await runtime.setupPlaywright({
+  browserType: "chromium",
+  headless: true,
+  onConsoleLog: (log) => console.log("[browser]", log),
+});
+
+// Define browser tests
+await runtime.eval(`
+  test("homepage loads", async () => {
+    await page.goto("https://example.com");
+    await expect(page.getByText("Example Domain")).toBeVisible();
+  });
+`);
+
+// Run tests
+const results = await runtime.runPlaywrightTests();
+console.log(`${results.passed}/${results.total} passed`);
+
+// Get collected data
+const data = await runtime.getCollectedData();
+console.log("Console logs:", data.consoleLogs);
+console.log("Network requests:", data.networkRequests);
+```

package/dist/cjs/connection.cjs

@@ -0,0 +1,504 @@
+// @bun @bun-cjs
+(function(exports, require, module, __filename, __dirname) {var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// packages/isolate-client/src/connection.ts
+var exports_connection = {};
+__export(exports_connection, {
+  connect: () => connect
+});
+module.exports = __toCommonJS(exports_connection);
+var import_node_net = require("net");
+var import_isolate_protocol = require("@ricsam/isolate-protocol");
+var DEFAULT_TIMEOUT = 30000;
+async function connect(options = {}) {
+  const socket = await createSocket(options);
+  const state = {
+    socket,
+    pendingRequests: new Map,
+    callbacks: new Map,
+    nextRequestId: 1,
+    nextCallbackId: 1,
+    connected: true,
+    playwrightEventHandlers: new Map
+  };
+  const parser = import_isolate_protocol.createFrameParser();
+  socket.on("data", (data) => {
+    try {
+      for (const frame of parser.feed(new Uint8Array(data))) {
+        handleMessage(frame.message, state);
+      }
+    } catch (err) {
+      console.error("Error parsing frame:", err);
+    }
+  });
+  socket.on("close", () => {
+    state.connected = false;
+    for (const [, pending] of state.pendingRequests) {
+      pending.reject(new Error("Connection closed"));
+    }
+    state.pendingRequests.clear();
+  });
+  socket.on("error", (err) => {
+    console.error("Socket error:", err);
+  });
+  return {
+    createRuntime: (runtimeOptions) => createRuntime(state, runtimeOptions),
+    close: async () => {
+      state.connected = false;
+      socket.destroy();
+    },
+    isConnected: () => state.connected
+  };
+}
+function createSocket(options) {
+  return new Promise((resolve, reject) => {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    let socket;
+    const onError = (err) => {
+      reject(err);
+    };
+    const onConnect = () => {
+      socket.removeListener("error", onError);
+      resolve(socket);
+    };
+    if (options.socket) {
+      socket = import_node_net.connect(options.socket, onConnect);
+    } else {
+      socket = import_node_net.connect(options.port ?? 47891, options.host ?? "127.0.0.1", onConnect);
+    }
+    socket.on("error", onError);
+    const timeoutId = setTimeout(() => {
+      socket.destroy();
+      reject(new Error("Connection timeout"));
+    }, timeout);
+    socket.once("connect", () => {
+      clearTimeout(timeoutId);
+    });
+  });
+}
+function handleMessage(message, state) {
+  switch (message.type) {
+    case import_isolate_protocol.MessageType.RESPONSE_OK: {
+      const response = message;
+      const pending = state.pendingRequests.get(response.requestId);
+      if (pending) {
+        state.pendingRequests.delete(response.requestId);
+        if (pending.timeoutId)
+          clearTimeout(pending.timeoutId);
+        pending.resolve(response.data);
+      }
+      break;
+    }
+    case import_isolate_protocol.MessageType.RESPONSE_ERROR: {
+      const response = message;
+      const pending = state.pendingRequests.get(response.requestId);
+      if (pending) {
+        state.pendingRequests.delete(response.requestId);
+        if (pending.timeoutId)
+          clearTimeout(pending.timeoutId);
+        const error = new Error(response.message);
+        if (response.details) {
+          error.name = response.details.name;
+          if (response.details.stack) {
+            error.stack = response.details.stack;
+          }
+        }
+        pending.reject(error);
+      }
+      break;
+    }
+    case import_isolate_protocol.MessageType.CALLBACK_INVOKE: {
+      const invoke = message;
+      handleCallbackInvoke(invoke, state);
+      break;
+    }
+    case import_isolate_protocol.MessageType.PONG:
+      break;
+    case import_isolate_protocol.MessageType.PLAYWRIGHT_EVENT: {
+      const event = message;
+      const handler = state.playwrightEventHandlers.get(event.isolateId);
+      if (handler) {
+        switch (event.eventType) {
+          case "consoleLog":
+            handler.onConsoleLog?.(event.payload);
+            break;
+          case "networkRequest":
+            handler.onNetworkRequest?.(event.payload);
+            break;
+          case "networkResponse":
+            handler.onNetworkResponse?.(event.payload);
+            break;
+        }
+      }
+      break;
+    }
+    default:
+      console.warn(`Unexpected message type: ${message.type}`);
+  }
+}
+async function handleCallbackInvoke(invoke, state) {
+  const callback = state.callbacks.get(invoke.callbackId);
+  const response = {
+    type: import_isolate_protocol.MessageType.CALLBACK_RESPONSE,
+    requestId: invoke.requestId
+  };
+  if (!callback) {
+    response.error = {
+      name: "Error",
+      message: `Unknown callback: ${invoke.callbackId}`
+    };
+  } else {
+    try {
+      const result = await callback(...invoke.args);
+      response.result = result;
+    } catch (err) {
+      const error = err;
+      response.error = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      };
+    }
+  }
+  sendMessage(state.socket, response);
+}
+function sendMessage(socket, message) {
+  const frame = import_isolate_protocol.buildFrame(message);
+  socket.write(frame);
+}
+function sendRequest(state, message, timeout = DEFAULT_TIMEOUT) {
+  return new Promise((resolve, reject) => {
+    if (!state.connected) {
+      reject(new Error("Not connected"));
+      return;
+    }
+    const requestId = message.requestId;
+    const timeoutId = setTimeout(() => {
+      state.pendingRequests.delete(requestId);
+      reject(new Error("Request timeout"));
+    }, timeout);
+    state.pendingRequests.set(requestId, {
+      resolve,
+      reject,
+      timeoutId
+    });
+    sendMessage(state.socket, message);
+  });
+}
+async function createRuntime(state, options = {}) {
+  const callbacks = {};
+  if (options.console) {
+    callbacks.console = registerConsoleCallbacks(state, options.console);
+  }
+  if (options.fetch) {
+    callbacks.fetch = registerFetchCallback(state, options.fetch);
+  }
+  if (options.fs) {
+    callbacks.fs = registerFsCallbacks(state, options.fs);
+  }
+  const requestId = state.nextRequestId++;
+  const request = {
+    type: import_isolate_protocol.MessageType.CREATE_RUNTIME,
+    requestId,
+    options: {
+      memoryLimit: options.memoryLimit,
+      callbacks
+    }
+  };
+  const result = await sendRequest(state, request);
+  const isolateId = result.isolateId;
+  return {
+    isolateId,
+    eval: async (code, filename) => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.EVAL,
+        requestId: reqId,
+        isolateId,
+        code,
+        filename
+      };
+      const res = await sendRequest(state, req);
+      return res.value;
+    },
+    dispatchRequest: async (request2, dispatchOptions) => {
+      const reqId = state.nextRequestId++;
+      const serialized = await serializeRequest(request2);
+      const req = {
+        type: import_isolate_protocol.MessageType.DISPATCH_REQUEST,
+        requestId: reqId,
+        isolateId,
+        request: serialized,
+        options: dispatchOptions
+      };
+      const res = await sendRequest(state, req, dispatchOptions?.timeout ?? DEFAULT_TIMEOUT);
+      return deserializeResponse(res.response);
+    },
+    tick: async (ms) => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.TICK,
+        requestId: reqId,
+        isolateId,
+        ms
+      };
+      await sendRequest(state, req);
+    },
+    setupTestEnvironment: async () => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.SETUP_TEST_ENV,
+        requestId: reqId,
+        isolateId
+      };
+      await sendRequest(state, req);
+    },
+    runTests: async (timeout) => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.RUN_TESTS,
+        requestId: reqId,
+        isolateId,
+        timeout
+      };
+      return sendRequest(state, req, timeout ?? DEFAULT_TIMEOUT);
+    },
+    setupPlaywright: async (playwrightOptions) => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.SETUP_PLAYWRIGHT,
+        requestId: reqId,
+        isolateId,
+        options: {
+          browserType: playwrightOptions?.browserType,
+          headless: playwrightOptions?.headless,
+          baseURL: playwrightOptions?.baseURL
+        }
+      };
+      if (playwrightOptions?.onConsoleLog || playwrightOptions?.onNetworkRequest || playwrightOptions?.onNetworkResponse) {
+        state.playwrightEventHandlers.set(isolateId, {
+          onConsoleLog: playwrightOptions.onConsoleLog,
+          onNetworkRequest: playwrightOptions.onNetworkRequest,
+          onNetworkResponse: playwrightOptions.onNetworkResponse
+        });
+      }
+      await sendRequest(state, req);
+    },
+    runPlaywrightTests: async (timeout) => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.RUN_PLAYWRIGHT_TESTS,
+        requestId: reqId,
+        isolateId,
+        timeout
+      };
+      return sendRequest(state, req, timeout ?? DEFAULT_TIMEOUT);
+    },
+    resetPlaywrightTests: async () => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.RESET_PLAYWRIGHT_TESTS,
+        requestId: reqId,
+        isolateId
+      };
+      await sendRequest(state, req);
+    },
+    getCollectedData: async () => {
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.GET_COLLECTED_DATA,
+        requestId: reqId,
+        isolateId
+      };
+      return sendRequest(state, req);
+    },
+    dispose: async () => {
+      state.playwrightEventHandlers.delete(isolateId);
+      const reqId = state.nextRequestId++;
+      const req = {
+        type: import_isolate_protocol.MessageType.DISPOSE_RUNTIME,
+        requestId: reqId,
+        isolateId
+      };
+      await sendRequest(state, req);
+    }
+  };
+}
+function registerConsoleCallbacks(state, callbacks) {
+  const registrations = {};
+  const register = (name, fn) => {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, (_level, ...args) => {
+      fn(...args);
+    });
+    registrations[name] = { callbackId, name, async: false };
+  };
+  if (callbacks.log)
+    register("log", callbacks.log);
+  if (callbacks.warn)
+    register("warn", callbacks.warn);
+  if (callbacks.error)
+    register("error", callbacks.error);
+  if (callbacks.info)
+    register("info", callbacks.info);
+  if (callbacks.debug)
+    register("debug", callbacks.debug);
+  if (callbacks.dir)
+    register("dir", callbacks.dir);
+  return registrations;
+}
+function registerFetchCallback(state, callback) {
+  const callbackId = state.nextCallbackId++;
+  state.callbacks.set(callbackId, async (serialized) => {
+    const request = deserializeRequest(serialized);
+    const response = await callback(request);
+    return serializeResponse(response);
+  });
+  return { callbackId, name: "fetch", async: true };
+}
+function registerFsCallbacks(state, callbacks) {
+  const registrations = {};
+  if (callbacks.readFile) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path) => {
+      const result = await callbacks.readFile(path);
+      return new Uint8Array(result);
+    });
+    registrations.readFile = { callbackId, name: "readFile", async: true };
+  }
+  if (callbacks.writeFile) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path, data) => {
+      let buffer;
+      if (data instanceof Uint8Array) {
+        buffer = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+      } else if (Array.isArray(data)) {
+        buffer = new Uint8Array(data).buffer;
+      } else if (data instanceof ArrayBuffer) {
+        buffer = data;
+      } else {
+        buffer = new ArrayBuffer(0);
+      }
+      await callbacks.writeFile(path, buffer);
+    });
+    registrations.writeFile = { callbackId, name: "writeFile", async: true };
+  }
+  if (callbacks.unlink) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path) => {
+      await callbacks.unlink(path);
+    });
+    registrations.unlink = { callbackId, name: "unlink", async: true };
+  }
+  if (callbacks.readdir) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path) => {
+      return callbacks.readdir(path);
+    });
+    registrations.readdir = { callbackId, name: "readdir", async: true };
+  }
+  if (callbacks.mkdir) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path, options) => {
+      await callbacks.mkdir(path, options);
+    });
+    registrations.mkdir = { callbackId, name: "mkdir", async: true };
+  }
+  if (callbacks.rmdir) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path) => {
+      await callbacks.rmdir(path);
+    });
+    registrations.rmdir = { callbackId, name: "rmdir", async: true };
+  }
+  if (callbacks.stat) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (path) => {
+      return callbacks.stat(path);
+    });
+    registrations.stat = { callbackId, name: "stat", async: true };
+  }
+  if (callbacks.rename) {
+    const callbackId = state.nextCallbackId++;
+    state.callbacks.set(callbackId, async (from, to) => {
+      await callbacks.rename(from, to);
+    });
+    registrations.rename = { callbackId, name: "rename", async: true };
+  }
+  return registrations;
+}
+async function serializeRequest(request) {
+  const headers = [];
+  request.headers.forEach((value, key) => {
+    headers.push([key, value]);
+  });
+  let body = null;
+  if (request.body) {
+    body = new Uint8Array(await request.arrayBuffer());
+  }
+  return {
+    method: request.method,
+    url: request.url,
+    headers,
+    body
+  };
+}
+async function serializeResponse(response) {
+  const headers = [];
+  response.headers.forEach((value, key) => {
+    headers.push([key, value]);
+  });
+  let body = null;
+  if (response.body) {
+    body = new Uint8Array(await response.arrayBuffer());
+  }
+  return {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+    body
+  };
+}
+function deserializeRequest(data) {
+  return new Request(data.url, {
+    method: data.method,
+    headers: data.headers,
+    body: data.body
+  });
+}
+function deserializeResponse(data) {
+  return new Response(data.body, {
+    status: data.status,
+    statusText: data.statusText,
+    headers: data.headers
+  });
+}
+})
+
+//# debugId=AC520FAF0080FE0764756E2164756E21