@ricsam/isolate-fetch 0.1.1 → 0.1.3

package/dist/types/isolate.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Global Type Definitions for @ricsam/isolate-fetch
+ *
+ * These types define the globals injected by setupFetch() into an isolated-vm context.
+ * Use these types to typecheck user code that will run inside the V8 isolate.
+ *
+ * @example
+ * // Typecheck isolate code with serve()
+ * type WebSocketData = { id: number; connectedAt: number };
+ *
+ * serve({
+ *   fetch(request, server) {
+ *     if (request.url.includes("/ws")) {
+ *       // server.upgrade knows data should be WebSocketData
+ *       server.upgrade(request, { data: { id: 123, connectedAt: Date.now() } });
+ *       return new Response(null, { status: 101 });
+ *     }
+ *     return new Response("Hello!");
+ *   },
+ *   websocket: {
+ *     // Type hint - specifies the type of ws.data
+ *     data: {} as WebSocketData,
+ *     message(ws, message) {
+ *       // ws.data is typed as WebSocketData
+ *       console.log("User", ws.data.id, "says:", message);
+ *       ws.send("Echo: " + message);
+ *     }
+ *   }
+ * });
+ */
+
+export {};
+
+declare global {
+  // ============================================
+  // Standard Fetch API (from lib.dom)
+  // ============================================
+
+  /**
+   * Headers class for HTTP headers manipulation.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Headers
+   */
+  const Headers: typeof globalThis.Headers;
+
+  /**
+   * Request class for HTTP requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Request
+   */
+  const Request: typeof globalThis.Request;
+
+  /**
+   * Response class for HTTP responses.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Response
+   */
+  const Response: typeof globalThis.Response;
+
+  /**
+   * AbortController for cancelling fetch requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+   */
+  const AbortController: typeof globalThis.AbortController;
+
+  /**
+   * AbortSignal for listening to abort events.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+   */
+  const AbortSignal: typeof globalThis.AbortSignal;
+
+  /**
+   * FormData for constructing form data.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/FormData
+   */
+  const FormData: typeof globalThis.FormData;
+
+  /**
+   * Fetch function for making HTTP requests.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  function fetch(
+    input: RequestInfo | URL,
+    init?: RequestInit
+  ): Promise<Response>;
+
+  // ============================================
+  // Isolate-specific: serve() API
+  // ============================================
+
+  /**
+   * Server interface for handling WebSocket upgrades within serve() handlers.
+   *
+   * @typeParam T - The type of data associated with WebSocket connections
+   */
+  interface Server<T = unknown> {
+    /**
+     * Upgrade an HTTP request to a WebSocket connection.
+     *
+     * @param request - The incoming HTTP request to upgrade
+     * @param options - Optional data to associate with the WebSocket connection
+     * @returns true if upgrade will proceed, false otherwise
+     *
+     * @example
+     * serve({
+     *   fetch(request, server) {
+     *     if (server.upgrade(request, { data: { userId: 123 } })) {
+     *       return new Response(null, { status: 101 });
+     *     }
+     *     return new Response("Upgrade failed", { status: 400 });
+     *   }
+     * });
+     */
+    upgrade(request: Request, options?: { data?: T }): boolean;
+  }
+
+  /**
+   * ServerWebSocket interface for WebSocket connections within serve() handlers.
+   *
+   * @typeParam T - The type of data associated with this WebSocket connection
+   */
+  interface ServerWebSocket<T = unknown> {
+    /**
+     * User data associated with this connection.
+     * Set via `server.upgrade(request, { data: ... })`.
+     */
+    readonly data: T;
+
+    /**
+     * Send a message to the client.
+     *
+     * @param message - The message to send (string, ArrayBuffer, or Uint8Array)
+     */
+    send(message: string | ArrayBuffer | Uint8Array): void;
+
+    /**
+     * Close the WebSocket connection.
+     *
+     * @param code - Optional close code (default: 1000)
+     * @param reason - Optional close reason
+     */
+    close(code?: number, reason?: string): void;
+
+    /**
+     * WebSocket ready state.
+     * - 0: CONNECTING
+     * - 1: OPEN
+     * - 2: CLOSING
+     * - 3: CLOSED
+     */
+    readonly readyState: number;
+  }
+
+  /**
+   * Options for the serve() function.
+   *
+   * @typeParam T - The type of data associated with WebSocket connections
+   */
+  interface ServeOptions<T = unknown> {
+    /**
+     * Handler for HTTP requests.
+     *
+     * @param request - The incoming HTTP request
+     * @param server - Server interface for WebSocket upgrades
+     * @returns Response or Promise resolving to Response
+     */
+    fetch(request: Request, server: Server<T>): Response | Promise<Response>;
+
+    /**
+     * WebSocket event handlers.
+     */
+    websocket?: {
+      /**
+       * Type hint for WebSocket data. The value is not used at runtime.
+       * Specifies the type of `ws.data` for all handlers and `server.upgrade()`.
+       *
+       * @example
+       * websocket: {
+       *   data: {} as { userId: string },
+       *   message(ws, message) {
+       *     // ws.data.userId is typed as string
+       *   }
+       * }
+       */
+      data?: T;
+
+      /**
+       * Called when a WebSocket connection is opened.
+       *
+       * @param ws - The WebSocket connection
+       */
+      open?(ws: ServerWebSocket<T>): void | Promise<void>;
+
+      /**
+       * Called when a message is received.
+       *
+       * @param ws - The WebSocket connection
+       * @param message - The received message (string or ArrayBuffer)
+       */
+      message?(
+        ws: ServerWebSocket<T>,
+        message: string | ArrayBuffer
+      ): void | Promise<void>;
+
+      /**
+       * Called when the connection is closed.
+       *
+       * @param ws - The WebSocket connection
+       * @param code - The close code
+       * @param reason - The close reason
+       */
+      close?(
+        ws: ServerWebSocket<T>,
+        code: number,
+        reason: string
+      ): void | Promise<void>;
+
+      /**
+       * Called when an error occurs.
+       *
+       * @param ws - The WebSocket connection
+       * @param error - The error that occurred
+       */
+      error?(ws: ServerWebSocket<T>, error: Error): void | Promise<void>;
+    };
+  }
+
+  /**
+   * Register an HTTP server handler in the isolate.
+   *
+   * Only one serve() handler can be active at a time.
+   * Calling serve() again replaces the previous handler.
+   *
+   * @param options - Server configuration including fetch handler and optional WebSocket handlers
+   *
+   * @example
+   * type WsData = { connectedAt: number };
+   *
+   * serve({
+   *   fetch(request, server) {
+   *     const url = new URL(request.url);
+   *
+   *     if (url.pathname === "/ws") {
+   *       if (server.upgrade(request, { data: { connectedAt: Date.now() } })) {
+   *         return new Response(null, { status: 101 });
+   *       }
+   *     }
+   *
+   *     if (url.pathname === "/api/hello") {
+   *       return Response.json({ message: "Hello!" });
+   *     }
+   *
+   *     return new Response("Not Found", { status: 404 });
+   *   },
+   *   websocket: {
+   *     data: {} as WsData,
+   *     open(ws) {
+   *       console.log("Connected at:", ws.data.connectedAt);
+   *     },
+   *     message(ws, message) {
+   *       ws.send("Echo: " + message);
+   *     },
+   *     close(ws, code, reason) {
+   *       console.log("Closed:", code, reason);
+   *     }
+   *   }
+   * });
+   */
+  function serve<T = unknown>(options: ServeOptions<T>): void;
+}

package/dist/types/stream-state.d.ts

@@ -0,0 +1,61 @@
+import ivm from "isolated-vm";
+export interface StreamState {
+    /** Buffered chunks waiting to be read */
+    queue: Uint8Array[];
+    /** Total bytes in queue (for backpressure) */
+    queueSize: number;
+    /** Stream has been closed (no more data) */
+    closed: boolean;
+    /** Stream encountered an error */
+    errored: boolean;
+    /** The error value if errored */
+    errorValue: unknown;
+    /** A pull is waiting for data */
+    pullWaiting: boolean;
+    /** Resolve function for waiting pull */
+    pullResolve: ((chunk: Uint8Array | null) => void) | null;
+    /** Reject function for waiting pull */
+    pullReject: ((error: unknown) => void) | null;
+}
+export interface StreamStateRegistry {
+    /** Create a new stream and return its ID */
+    create(): number;
+    /** Get stream state by ID */
+    get(streamId: number): StreamState | undefined;
+    /** Push a chunk to the stream's queue */
+    push(streamId: number, chunk: Uint8Array): boolean;
+    /** Pull a chunk from the stream (returns Promise that resolves when data available) */
+    pull(streamId: number): Promise<{
+        value: Uint8Array;
+        done: false;
+    } | {
+        done: true;
+    }>;
+    /** Close the stream (no more data) */
+    close(streamId: number): void;
+    /** Error the stream */
+    error(streamId: number, errorValue: unknown): void;
+    /** Check if stream queue is above high-water mark */
+    isQueueFull(streamId: number): boolean;
+    /** Delete stream state (cleanup) */
+    delete(streamId: number): void;
+    /** Clear all streams (context cleanup) */
+    clear(): void;
+}
+/** Maximum bytes to buffer before backpressure kicks in */
+export declare const HIGH_WATER_MARK: number;
+/** Maximum number of chunks in queue */
+export declare const MAX_QUEUE_CHUNKS = 16;
+export declare function createStreamStateRegistry(): StreamStateRegistry;
+export declare function getStreamRegistryForContext(context: ivm.Context): StreamStateRegistry;
+export declare function clearStreamRegistryForContext(context: ivm.Context): void;
+/**
+ * Start reading from a native ReadableStream and push to host queue.
+ * Respects backpressure by pausing when queue is full.
+ *
+ * @param nativeStream The native ReadableStream to read from
+ * @param streamId The stream ID in the registry
+ * @param registry The stream state registry
+ * @returns Async cleanup function to cancel the reader
+ */
+export declare function startNativeStreamReader(nativeStream: ReadableStream<Uint8Array>, streamId: number, registry: StreamStateRegistry): () => Promise<void>;

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@ricsam/isolate-fetch",
-  "version": "0.1.1",
-  "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "version": "0.1.3",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.ts",
-      "types": "./src/index.ts"
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
+    },
+    "./isolate": {
+      "types": "./dist/types/isolate.d.ts"
     }
   },
   "scripts": {
@@ -19,12 +22,37 @@
     "@ricsam/isolate-core": "*",
     "isolated-vm": "^6"
   },
-  "devDependencies": {
-    "@ricsam/isolate-test-utils": "*",
-    "@types/node": "^24",
-    "typescript": "^5"
-  },
   "peerDependencies": {
     "isolated-vm": "^6"
-  }
-}
+  },
+  "author": "Richard Samuelsson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/isolate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/isolate/issues"
+  },
+  "homepage": "https://github.com/ricsam/isolate#readme",
+  "keywords": [
+    "isolated-vm",
+    "sandbox",
+    "javascript",
+    "runtime",
+    "fetch",
+    "filesystem",
+    "streams",
+    "v8",
+    "isolate"
+  ],
+  "description": "Fetch API implementation for isolated-vm V8 sandbox",
+  "module": "./dist/mjs/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}

package/CHANGELOG.md

@@ -1,9 +0,0 @@
-# @ricsam/isolate-fetch
-
-## 0.1.1
-
-### Patch Changes
-
-- initial release
-- Updated dependencies
-  - @ricsam/isolate-core@0.1.1

package/src/debug-delayed.test.ts

@@ -1,89 +0,0 @@
-import { test, describe, beforeEach, afterEach, it } from "node:test";
-import assert from "node:assert";
-import ivm from "isolated-vm";
-import {
-  setupFetch,
-  clearAllInstanceState,
-  type FetchHandle,
-} from "./index.ts";
-import { setupTimers, type TimersHandle } from "@ricsam/isolate-timers";
-import { setupConsole } from "@ricsam/isolate-console";
-import { clearStreamRegistryForContext } from "./stream-state.ts";
-
-describe("Debug Delayed Streaming", () => {
-  it("delayed streaming response with setTimeout", { timeout: 10000 }, async () => {
-    const isolate = new ivm.Isolate();
-    const context = await isolate.createContext();
-    clearAllInstanceState();
-
-    const logs: string[] = [];
-    await setupConsole(context, {
-      onLog: (level, ...args) => {
-        logs.push(`[${level}] ${args.join(' ')}`);
-        console.log(`[ISOLATE] ${args.join(' ')}`);
-      }
-    });
-
-    const timersHandle = await setupTimers(context);
-    const fetchHandle = await setupFetch(context);
-
-    try {
-      context.evalSync(`
-        console.log('Setting up serve');
-        serve({
-          async fetch(request) {
-            console.log('Fetch handler called');
-            let count = 0;
-            const stream = new ReadableStream({
-              async pull(controller) {
-                console.log('pull() called, count =', count);
-                if (count < 3) {
-                  console.log('Starting setTimeout');
-                  await new Promise(r => setTimeout(r, 10));
-                  console.log('setTimeout resolved');
-                  const data = "delayed" + count;
-                  console.log('Enqueuing:', data);
-                  controller.enqueue(new TextEncoder().encode(data));
-                  count++;
-                  console.log('Enqueued, returning');
-                } else {
-                  console.log('Closing stream');
-                  controller.close();
-                }
-              }
-            });
-            console.log('Creating Response');
-            const response = new Response(stream);
-            console.log('Response created, returning');
-            return response;
-          }
-        });
-        console.log('Serve registered');
-      `);
-
-      console.log('Calling dispatchRequest');
-      const response = await fetchHandle.dispatchRequest(
-        new Request("http://test/"),
-        {
-          tick: async () => {
-            // Advance virtual time by 50ms each tick to process timers
-            await timersHandle.tick(50);
-          }
-        }
-      );
-
-      console.log('Got response, status:', response.status);
-      console.log('Calling response.text()');
-
-      const text = await response.text();
-      console.log('Got text:', text);
-      assert.strictEqual(text, "delayed0delayed1delayed2");
-    } finally {
-      fetchHandle.dispose();
-      timersHandle.dispose();
-      clearStreamRegistryForContext(context);
-      context.release();
-      isolate.dispose();
-    }
-  });
-});

package/src/debug-streaming.test.ts

@@ -1,81 +0,0 @@
-import { test, describe, beforeEach, afterEach, it } from "node:test";
-import assert from "node:assert";
-import ivm from "isolated-vm";
-import {
-  setupFetch,
-  clearAllInstanceState,
-  type FetchHandle,
-} from "./index.ts";
-import { setupTimers, type TimersHandle } from "@ricsam/isolate-timers";
-import { setupConsole } from "@ricsam/isolate-console";
-import { clearStreamRegistryForContext } from "./stream-state.ts";
-
-describe("Debug Streaming", () => {
-  it("debug pull-based stream", { timeout: 5000 }, async () => {
-    const isolate = new ivm.Isolate();
-    const context = await isolate.createContext();
-    clearAllInstanceState();
-
-    const logs: string[] = [];
-    await setupConsole(context, {
-      onLog: (level, ...args) => {
-        logs.push(`[${level}] ${args.join(' ')}`);
-        console.log(`[ISOLATE] ${args.join(' ')}`);
-      }
-    });
-
-    const timersHandle = await setupTimers(context);
-    const fetchHandle = await setupFetch(context);
-
-    try {
-      context.evalSync(`
-        console.log('Setting up serve');
-        serve({
-          async fetch(request) {
-            console.log('Fetch handler called');
-            let count = 0;
-            const stream = new ReadableStream({
-              pull(controller) {
-                console.log('pull() called, count =', count);
-                if (count < 3) {
-                  const data = "chunk" + count;
-                  console.log('Enqueuing:', data);
-                  controller.enqueue(new TextEncoder().encode(data));
-                  count++;
-                } else {
-                  console.log('Closing stream');
-                  controller.close();
-                }
-              }
-            });
-            console.log('Creating Response');
-            const response = new Response(stream);
-            console.log('Response created, returning');
-            return response;
-          }
-        });
-        console.log('Serve registered');
-      `);
-
-      console.log('Calling dispatchRequest');
-      const response = await fetchHandle.dispatchRequest(
-        new Request("http://test/"),
-        { tick: () => timersHandle.tick() }
-      );
-
-      console.log('Got response, status:', response.status);
-      console.log('Response body:', response.body);
-      console.log('Calling response.text()');
-
-      const text = await response.text();
-      console.log('Got text:', text);
-      assert.strictEqual(text, "chunk0chunk1chunk2");
-    } finally {
-      fetchHandle.dispose();
-      timersHandle.dispose();
-      clearStreamRegistryForContext(context);
-      context.release();
-      isolate.dispose();
-    }
-  });
-});