jiren 1.5.0 → 1.6.0

package/components/client.ts

@@ -62,7 +62,7 @@ export interface JirenClientOptions<
   performanceMode?: boolean;
 }
 
-/** Helper to extract keys from Target Config */
+// Helper to extract keys from Target Config
 export type ExtractTargetKeys<
   T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
 > = T extends readonly TargetUrlConfig[]
@@ -71,7 +71,6 @@ export type ExtractTargetKeys<
   ? keyof T
   : never;
 
-/** Type-safe URL accessor - maps keys to UrlEndpoint objects */
 export type UrlAccessor<
   T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
 > = {
@@ -79,23 +78,7 @@ export type UrlAccessor<
 };
 
 /**
- * Helper function to define target URLs with type inference.
- * This eliminates the need for 'as const'.
- *
- * @example
- * ```typescript
- * const client = new JirenClient({
- *   targets: defineUrls([
- *     { key: "google", url: "https://google.com" },
- *   ])
- * });
- * // OR
- * const client = new JirenClient({
- *   targets: {
- *      google: "https://google.com"
- *   }
- * });
- * ```
+ * Helper to define target URLs with type inference.
  */
 export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   urls: T
@@ -103,11 +86,22 @@ export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   return urls;
 }
 
+// FinalizationRegistry for automatic cleanup when client is garbage collected
+const clientRegistry = new FinalizationRegistry<number>((ptrValue) => {
+  // Note: We store the pointer as a number since FinalizationRegistry can't hold Pointer directly
+  try {
+    lib.symbols.zclient_free(ptrValue as any);
+  } catch {
+    // Ignore errors during cleanup
+  }
+});
+
 export class JirenClient<
   T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
     | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
-> {
+> implements Disposable
+{
   private ptr: Pointer | null;
   private urlMap: Map<string, string> = new Map();
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
@@ -123,9 +117,9 @@ export class JirenClient<
   private targetsComplete: Set<string> = new Set();
   private performanceMode: boolean = false;
 
-  // Pre-computed headers (avoid per-request overhead)
+  // Pre-computed headers
   private readonly defaultHeadersStr: string;
-  private readonly defaultHeadersBuffer: Buffer; // Cached buffer
+  private readonly defaultHeadersBuffer: Buffer;
   private readonly defaultHeaders: Record<string, string> = {
     "user-agent":
       "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
@@ -144,7 +138,7 @@ export class JirenClient<
     "upgrade-insecure-requests": "1",
   };
 
-  // Pre-computed method buffers (avoid per-request allocation)
+  // Pre-computed method buffers
   private readonly methodBuffers: Record<string, Buffer> = {
     GET: Buffer.from("GET\0"),
     POST: Buffer.from("POST\0"),
@@ -155,7 +149,7 @@ export class JirenClient<
     OPTIONS: Buffer.from("OPTIONS\0"),
   };
 
-  // Reusable TextDecoder (avoid per-response allocation)
+  // Reusable TextDecoder
   private readonly decoder = new TextDecoder();
 
   /** Type-safe URL accessor for warmed-up URLs */
@@ -170,7 +164,10 @@ export class JirenClient<
     this.ptr = lib.symbols.zclient_new();
     if (!this.ptr) throw new Error("Failed to create native client instance");
 
-    // Pre-compute default headers string (avoid per-request overhead)
+    // Register for automatic cleanup when this client is garbage collected
+    clientRegistry.register(this, this.ptr as unknown as number, this);
+
+    // Pre-computed default headers string
     const orderedKeys = [
       "sec-ch-ua",
       "sec-ch-ua-mobile",
@@ -647,15 +644,30 @@ export class JirenClient<
 
   /**
    * Free the native client resources.
-   * Must be called when the client is no longer needed.
+   * Note: This is called automatically when the client is garbage collected,
+   * or you can use the `using` keyword for automatic cleanup in a scope.
    */
   public close(): void {
     if (this.ptr) {
+      // Unregister from FinalizationRegistry since we're manually closing
+      clientRegistry.unregister(this);
       lib.symbols.zclient_free(this.ptr);
       this.ptr = null;
     }
   }
 
+  /**
+   * Dispose method for the `using` keyword (ECMAScript Explicit Resource Management)
+   * @example
+   * ```typescript
+   * using client = new JirenClient({ targets: [...] });
+   * // client is automatically closed when the scope ends
+   * ```
+   */
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
   /**
    * Register interceptors dynamically.
    * @param interceptors - Interceptor configuration to add
@@ -1111,9 +1123,19 @@ export class JirenClient<
       if (bodyLen > 0 && bodyPtr) {
         buffer = toArrayBuffer(bodyPtr, 0, bodyLen).slice(0);
 
-        // Handle GZIP decompression
+        // Handle GZIP decompression - check content-encoding header first
+        const contentEncoding =
+          headersObj instanceof NativeHeaders
+            ? headersObj.get("content-encoding")?.toLowerCase()
+            : (headersObj as Record<string, string>)[
+                "content-encoding"
+              ]?.toLowerCase();
+
         const bufferView = new Uint8Array(buffer);
+
+        // Only attempt gzip if content-encoding is gzip AND magic bytes match
         if (
+          contentEncoding === "gzip" &&
           bufferView.length >= 2 &&
           bufferView[0] === 0x1f &&
           bufferView[1] === 0x8b
@@ -1124,8 +1146,8 @@ export class JirenClient<
               decompressed.byteOffset,
               decompressed.byteOffset + decompressed.byteLength
             );
-          } catch (e) {
-            console.warn("[Jiren] gzip decompression failed:", e);
+          } catch {
+            // Silently ignore decompression failures - data may already be decompressed
           }
         }
       }

package/components/metrics.ts

@@ -1,7 +1,4 @@
-/**
- * Metrics & Observability System for Jiren HTTP Client
- * Tracks performance, cache efficiency, errors, and request statistics
- */
+// Metrics & Observability System
 
 export interface EndpointMetrics {
   endpoint: string;

package/components/native-node.ts

@@ -1,5 +1,6 @@
 import koffi from "koffi";
 import path from "path";
+import fs from "fs";
 import { fileURLToPath } from "url";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -14,9 +15,12 @@ if (platform === "darwin") {
   suffix = "dll";
 }
 
-// Resolve library path relative to this module
-// native.ts uses join(import.meta.dir, `../lib/libhttpclient.${suffix}`)
-const libPath = path.join(__dirname, `../lib/libhttpclient.${suffix}`);
+// Resolve library path (source or dist)
+let libPath = path.join(__dirname, `../lib/libhttpclient.${suffix}`);
+if (!fs.existsSync(libPath)) {
+  // Try two levels up (for dist/components/ -> lib/)
+  libPath = path.join(__dirname, `../../lib/libhttpclient.${suffix}`);
+}
 
 // Load the library
 // koffi.load returns an object where we can register functions

package/components/native.ts

@@ -124,6 +124,35 @@ export const ffiDef = {
     returns: FFIType.u64,
   },
 
+  // =========================================================================
+  // MULTIPLEXING API
+  // =========================================================================
+
+  zclient_request_batch: {
+    args: [
+      FFIType.ptr, // client
+      FFIType.ptr, // requests array (ZBatchRequest*)
+      FFIType.u64, // request_count
+    ],
+    returns: FFIType.ptr, // ZBatchResult*
+  },
+  zclient_batch_result_free: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  zbatch_response_status: {
+    args: [FFIType.ptr, FFIType.u64], // result, index
+    returns: FFIType.u16,
+  },
+  zbatch_response_body: {
+    args: [FFIType.ptr, FFIType.u64], // result, index
+    returns: FFIType.ptr,
+  },
+  zbatch_response_body_len: {
+    args: [FFIType.ptr, FFIType.u64], // result, index
+    returns: FFIType.u64,
+  },
+
   // =========================================================================
   // CACHE FFI
   // =========================================================================

package/components/persistent-worker.ts

@@ -0,0 +1,73 @@
+// Persistent subprocess worker - stays alive and processes multiple requests
+import { CString, type Pointer } from "bun:ffi";
+import { lib } from "./native";
+
+// Create client immediately
+const ptr: Pointer | null = lib.symbols.zclient_new();
+if (!ptr) {
+  console.error("ERROR: Failed to create client");
+  process.exit(1);
+}
+
+// Enable benchmark mode
+lib.symbols.zclient_set_benchmark_mode(ptr, true);
+
+// Read requests from stdin line by line
+const decoder = new TextDecoder();
+
+process.stdin.on("data", async (chunk: Buffer) => {
+  const lines = decoder.decode(chunk).trim().split("\n");
+
+  for (const line of lines) {
+    if (!line) continue;
+
+    try {
+      const { id, url, method = "GET" } = JSON.parse(line);
+
+      if (url === "PREFETCH") {
+        // Prefetch warmup
+        console.log(JSON.stringify({ id, type: "prefetch_done" }));
+        continue;
+      }
+
+      if (url === "QUIT") {
+        lib.symbols.zclient_free(ptr);
+        process.exit(0);
+      }
+
+      const methodBuffer = Buffer.from(method + "\0");
+      const urlBuffer = Buffer.from(url + "\0");
+
+      const respPtr = lib.symbols.zclient_request_full(
+        ptr,
+        methodBuffer,
+        urlBuffer,
+        null,
+        null,
+        5,
+        false
+      );
+
+      if (!respPtr) {
+        console.log(
+          JSON.stringify({ id, success: false, error: "Request failed" })
+        );
+        continue;
+      }
+
+      const status = lib.symbols.zfull_response_status(respPtr);
+      const bodyLen = Number(lib.symbols.zfull_response_body_len(respPtr));
+
+      lib.symbols.zclient_response_full_free(respPtr);
+
+      console.log(JSON.stringify({ id, success: true, status, bodyLen }));
+    } catch (err: any) {
+      console.log(
+        JSON.stringify({ id: 0, success: false, error: err.message })
+      );
+    }
+  }
+});
+
+// Signal ready
+console.log(JSON.stringify({ type: "ready" }));

package/components/subprocess-worker.ts

@@ -0,0 +1,65 @@
+// Worker subprocess - runs in isolated process to avoid library conflicts
+import { CString, type Pointer } from "bun:ffi";
+import { lib } from "./native";
+
+// Get request from stdin
+const decoder = new TextDecoder();
+let inputBuffer = "";
+
+// Create client immediately since we're in a separate process
+const ptr: Pointer | null = lib.symbols.zclient_new();
+if (!ptr) {
+  console.error(
+    JSON.stringify({ success: false, error: "Failed to create client" })
+  );
+  process.exit(1);
+}
+
+// Enable benchmark mode
+lib.symbols.zclient_set_benchmark_mode(ptr, true);
+
+// Read request from argv
+const url = process.argv[2];
+const method = process.argv[3] || "GET";
+
+if (!url) {
+  console.error(JSON.stringify({ success: false, error: "No URL provided" }));
+  process.exit(1);
+}
+
+try {
+  const methodBuffer = Buffer.from(method + "\0");
+  const urlBuffer = Buffer.from(url + "\0");
+
+  const respPtr = lib.symbols.zclient_request_full(
+    ptr,
+    methodBuffer,
+    urlBuffer,
+    null,
+    null,
+    5,
+    false
+  );
+
+  if (!respPtr) throw new Error("Native request failed");
+
+  const status = lib.symbols.zfull_response_status(respPtr);
+  const bodyLen = Number(lib.symbols.zfull_response_body_len(respPtr));
+  const bodyPtr = lib.symbols.zfull_response_body(respPtr);
+
+  let bodyString = "";
+  if (bodyLen > 0 && bodyPtr) {
+    bodyString = new CString(bodyPtr).toString();
+  }
+
+  lib.symbols.zclient_response_full_free(respPtr);
+  lib.symbols.zclient_free(ptr);
+
+  console.log(
+    JSON.stringify({ success: true, status, bodyLen: bodyString.length })
+  );
+} catch (err: any) {
+  console.log(JSON.stringify({ success: false, error: err.message }));
+  lib.symbols.zclient_free(ptr);
+  process.exit(1);
+}

package/components/worker-pool.ts

@@ -0,0 +1,169 @@
+import { Worker } from "worker_threads";
+import { join } from "path";
+import type { RequestOptions } from "./types";
+
+interface WorkerTask {
+  id: number;
+  url: string;
+  options: RequestOptions;
+  resolve: (value: any) => void;
+  reject: (error: any) => void;
+}
+
+interface WorkerWrapper {
+  worker: Worker;
+  busy: boolean;
+  taskQueue: WorkerTask[];
+}
+
+/**
+ * WorkerPool manages a pool of worker threads for parallel HTTP requests.
+ * Each worker has its own native client instance, allowing true parallel execution.
+ */
+export class WorkerPool {
+  private workers: WorkerWrapper[] = [];
+  private taskId = 0;
+  private pendingTasks = new Map<number, WorkerTask>();
+  private ready: Promise<void>;
+  private closed = false;
+
+  constructor(poolSize: number = 4) {
+    const workerPath = join(import.meta.dir, "worker.ts");
+
+    const readyPromises: Promise<void>[] = [];
+
+    for (let i = 0; i < poolSize; i++) {
+      const worker = new Worker(workerPath);
+      const wrapper: WorkerWrapper = {
+        worker,
+        busy: false,
+        taskQueue: [],
+      };
+
+      worker.on("message", (msg: any) => {
+        if (msg.type === "prefetch_done") {
+          return;
+        }
+
+        const task = this.pendingTasks.get(msg.id);
+        if (task) {
+          this.pendingTasks.delete(msg.id);
+          wrapper.busy = false;
+
+          if (msg.success) {
+            task.resolve(msg.response);
+          } else {
+            task.reject(new Error(msg.error));
+          }
+
+          // Process next task in queue
+          this.processQueue(wrapper);
+        }
+      });
+
+      worker.on("error", (err) => {
+        console.error("Worker error:", err);
+      });
+
+      this.workers.push(wrapper);
+    }
+
+    this.ready = Promise.resolve();
+  }
+
+  /**
+   * Wait for the pool to be ready
+   */
+  async waitReady(): Promise<void> {
+    return this.ready;
+  }
+
+  /**
+   * Submit a request to the worker pool
+   */
+  async request(url: string, options: RequestOptions = {}): Promise<any> {
+    if (this.closed) {
+      throw new Error("Worker pool is closed");
+    }
+
+    return new Promise((resolve, reject) => {
+      const task: WorkerTask = {
+        id: this.taskId++,
+        url,
+        options,
+        resolve,
+        reject,
+      };
+
+      // Find the least busy worker
+      if (this.workers.length === 0) {
+        throw new Error("Worker pool has no workers");
+      }
+      let leastBusy = this.workers[0]!;
+      for (const w of this.workers) {
+        if (!w.busy && w.taskQueue.length === 0) {
+          leastBusy = w;
+          break;
+        }
+        if (w.taskQueue.length < leastBusy.taskQueue.length) {
+          leastBusy = w;
+        }
+      }
+
+      leastBusy.taskQueue.push(task);
+      this.processQueue(leastBusy);
+    });
+  }
+
+  private processQueue(wrapper: WorkerWrapper): void {
+    if (wrapper.busy || wrapper.taskQueue.length === 0) {
+      return;
+    }
+
+    const task = wrapper.taskQueue.shift()!;
+    wrapper.busy = true;
+    this.pendingTasks.set(task.id, task);
+
+    wrapper.worker.postMessage({
+      id: task.id,
+      url: task.url,
+      options: task.options,
+    });
+  }
+
+  /**
+   * Pre-warm connections for a list of URLs across all workers
+   */
+  async prefetch(urls: string[]): Promise<void> {
+    const promises = this.workers.map(
+      (w) =>
+        new Promise<void>((resolve) => {
+          const handler = (msg: any) => {
+            if (msg.type === "prefetch_done") {
+              w.worker.off("message", handler);
+              resolve();
+            }
+          };
+          w.worker.on("message", handler);
+          w.worker.postMessage({ type: "prefetch", url: urls });
+        })
+    );
+    await Promise.all(promises);
+  }
+
+  /**
+   * Close all workers
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+    const closePromises = this.workers.map(
+      (w) =>
+        new Promise<void>((resolve) => {
+          w.worker.once("exit", () => resolve());
+          w.worker.postMessage({ type: "close" });
+        })
+    );
+    await Promise.all(closePromises);
+    this.workers = [];
+  }
+}

package/components/worker.ts

@@ -1,13 +1,22 @@
 import { parentPort } from "worker_threads";
 import { CString, type Pointer } from "bun:ffi";
 import { lib } from "./native";
-import type { RequestOptions } from "../types";
+import type { RequestOptions } from "./types";
 
-// Each worker has its own isolated native client
-let ptr: Pointer | null = lib.symbols.zclient_new();
+// LAZY INITIALIZATION: Don't create client until first request
+// This avoids race conditions with library loading
+let ptr: Pointer | null = null;
 
-if (!ptr) {
-  throw new Error("Failed to create native client instance in worker");
+function ensureClient(): Pointer {
+  if (!ptr) {
+    ptr = lib.symbols.zclient_new();
+    if (!ptr) {
+      throw new Error("Failed to create native client instance in worker");
+    }
+    // Enable benchmark mode for consistent performance
+    lib.symbols.zclient_set_benchmark_mode(ptr, true);
+  }
+  return ptr;
 }
 
 // Handle cleanup
@@ -37,20 +46,27 @@ if (parentPort) {
       }
 
       if (msg.type === "prefetch") {
-        if (!ptr) return;
-        const urls = msg.url as unknown as string[]; // hack: url field used for string[]
-        for (const url of urls) {
-          const urlBuffer = Buffer.from(url + "\0");
-          lib.symbols.zclient_prefetch(ptr, urlBuffer);
+        try {
+          const client = ensureClient();
+          const urls = msg.url as unknown as string[];
+          for (const url of urls) {
+            const urlBuffer = Buffer.from(url + "\0");
+            lib.symbols.zclient_prefetch(client, urlBuffer);
+          }
+          parentPort?.postMessage({ type: "prefetch_done" });
+        } catch (err: any) {
+          parentPort?.postMessage({
+            type: "prefetch_done",
+            error: err.message,
+          });
         }
-        parentPort?.postMessage({ type: "prefetch_done" });
         return;
       }
 
       const { id, url, options } = msg;
 
       try {
-        if (!ptr) throw new Error("Worker client is closed");
+        const client = ensureClient();
 
         const method = options.method || "GET";
         const methodBuffer = Buffer.from(method + "\0");
@@ -78,8 +94,9 @@ if (parentPort) {
         const maxRedirects = options.maxRedirects ?? 5;
         const antibot = options.antibot ?? false;
 
-        const respPtr = lib.symbols.zclient_request(
-          ptr,
+        // Use the full request API for complete response
+        const respPtr = lib.symbols.zclient_request_full(
+          client,
           methodBuffer,
           urlBuffer,
           headersBuffer,
@@ -88,16 +105,15 @@ if (parentPort) {
           antibot
         );
 
-        // Parse Response
         if (!respPtr) throw new Error("Native request failed");
 
-        const status = lib.symbols.zclient_response_status(respPtr);
-        const bodyLen = Number(lib.symbols.zclient_response_body_len(respPtr));
-        const bodyPtr = lib.symbols.zclient_response_body(respPtr);
+        const status = lib.symbols.zfull_response_status(respPtr);
+        const bodyLen = Number(lib.symbols.zfull_response_body_len(respPtr));
+        const bodyPtr = lib.symbols.zfull_response_body(respPtr);
         const headersLen = Number(
-          lib.symbols.zclient_response_headers_len(respPtr)
+          lib.symbols.zfull_response_headers_len(respPtr)
         );
-        const headersPtr = lib.symbols.zclient_response_headers(respPtr);
+        const headersRawPtr = lib.symbols.zfull_response_headers(respPtr);
 
         let bodyString = "";
         if (bodyLen > 0 && bodyPtr) {
@@ -105,8 +121,8 @@ if (parentPort) {
         }
 
         const headers: Record<string, string> = {};
-        if (headersLen > 0 && headersPtr) {
-          const headersStr = new CString(headersPtr).toString();
+        if (headersLen > 0 && headersRawPtr) {
+          const headersStr = new CString(headersRawPtr).toString();
           const lines = headersStr.split("\r\n");
           for (const line of lines) {
             if (!line) continue;
@@ -119,7 +135,7 @@ if (parentPort) {
           }
         }
 
-        lib.symbols.zclient_response_free(respPtr);
+        lib.symbols.zclient_response_full_free(respPtr);
 
         parentPort?.postMessage({
           id,