jiren 1.4.0 → 1.5.0

package/components/cache.ts

@@ -1,8 +1,36 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  readdirSync,
+  statSync,
+} from "fs";
 import { gzipSync, gunzipSync } from "zlib";
 import { createHash } from "crypto";
 import { join } from "path";
-import type { JirenResponse } from "./types";
+import type { JirenResponse, JirenResponseBody } from "./types";
+
+/**
+ * Serializable cache entry - stores raw body data for reconstruction
+ */
+interface SerializableCacheEntry {
+  // Store serializable parts of response
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  url: string;
+  ok: boolean;
+  redirected: boolean;
+  type: "basic" | "cors" | "default" | "error" | "opaque" | "opaqueredirect";
+  // Store raw body as base64 string (for binary compatibility)
+  bodyData: string;
+  bodyIsText: boolean;
+  // Cache metadata
+  timestamp: number;
+  ttl: number;
+}
 
 interface CacheEntry {
   response: JirenResponse;
@@ -10,12 +38,224 @@ interface CacheEntry {
   ttl: number;
 }
 
+/**
+ * Reconstruct body methods from raw data
+ */
+function reconstructBody(bodyData: string, isText: boolean): JirenResponseBody {
+  let buffer: ArrayBuffer;
+
+  if (isText) {
+    // Text data stored directly
+    const encoder = new TextEncoder();
+    buffer = encoder.encode(bodyData).buffer as ArrayBuffer;
+  } else {
+    // Binary data stored as base64
+    const binaryString = atob(bodyData);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    buffer = bytes.buffer as ArrayBuffer;
+  }
+
+  return {
+    bodyUsed: false,
+    text: async () => {
+      if (isText) return bodyData;
+      const decoder = new TextDecoder();
+      return decoder.decode(buffer);
+    },
+    json: async () => {
+      const text = isText ? bodyData : new TextDecoder().decode(buffer);
+      return JSON.parse(text);
+    },
+    arrayBuffer: async () => buffer,
+    blob: async () => new Blob([buffer]),
+  };
+}
+
+/**
+ * L1 In-Memory LRU Cache Node
+ */
+interface LRUNode {
+  key: string;
+  entry: CacheEntry;
+  prev: LRUNode | null;
+  next: LRUNode | null;
+}
+
+/**
+ * L1 In-Memory LRU Cache
+ * Provides ~0.001ms access time (vs ~5ms for disk)
+ */
+class L1MemoryCache {
+  private capacity: number;
+  private cache: Map<string, LRUNode> = new Map();
+  private head: LRUNode | null = null; // Most recently used
+  private tail: LRUNode | null = null; // Least recently used
+
+  // Stats
+  public hits = 0;
+  public misses = 0;
+
+  constructor(capacity = 100) {
+    this.capacity = capacity;
+  }
+
+  /**
+   * Get from L1 cache (O(1) lookup + LRU update)
+   */
+  get(key: string): CacheEntry | null {
+    const node = this.cache.get(key);
+    if (!node) {
+      this.misses++;
+      return null;
+    }
+
+    // Check if expired
+    const now = Date.now();
+    if (now - node.entry.timestamp > node.entry.ttl) {
+      this.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    // Move to front (most recently used)
+    this.moveToFront(node);
+    this.hits++;
+    return node.entry;
+  }
+
+  /**
+   * Set in L1 cache with LRU eviction
+   */
+  set(key: string, entry: CacheEntry): void {
+    // If key exists, update and move to front
+    const existing = this.cache.get(key);
+    if (existing) {
+      existing.entry = entry;
+      this.moveToFront(existing);
+      return;
+    }
+
+    // Create new node
+    const node: LRUNode = {
+      key,
+      entry,
+      prev: null,
+      next: this.head,
+    };
+
+    // Add to front
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    if (!this.tail) {
+      this.tail = node;
+    }
+
+    this.cache.set(key, node);
+
+    // Evict LRU if over capacity
+    if (this.cache.size > this.capacity) {
+      this.evictLRU();
+    }
+  }
+
+  /**
+   * Delete from L1 cache
+   */
+  delete(key: string): void {
+    const node = this.cache.get(key);
+    if (!node) return;
+
+    this.removeNode(node);
+    this.cache.delete(key);
+  }
+
+  /**
+   * Clear all L1 cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.head = null;
+    this.tail = null;
+  }
+
+  /**
+   * Get L1 cache stats
+   */
+  stats() {
+    return {
+      size: this.cache.size,
+      capacity: this.capacity,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate:
+        this.hits + this.misses > 0
+          ? ((this.hits / (this.hits + this.misses)) * 100).toFixed(2) + "%"
+          : "0%",
+    };
+  }
+
+  private moveToFront(node: LRUNode): void {
+    if (node === this.head) return; // Already at front
+
+    this.removeNode(node);
+
+    // Add to front
+    node.prev = null;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    if (!this.tail) {
+      this.tail = node;
+    }
+  }
+
+  private removeNode(node: LRUNode): void {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+  }
+
+  private evictLRU(): void {
+    if (!this.tail) return;
+
+    const key = this.tail.key;
+    this.removeNode(this.tail);
+    this.cache.delete(key);
+  }
+}
+
+/**
+ * Two-Tier Response Cache
+ *
+ * L1: In-Memory LRU Cache (~0.001ms access) - hot data
+ * L2: Disk Cache with gzip (~5ms access) - persistence
+ *
+ * Read path:  L1 → L2 → Network
+ * Write path: L1 + L2 (write-through)
+ */
 export class ResponseCache {
+  private l1: L1MemoryCache;
   private cacheDir: string;
-  private maxSize: number;
+  private maxDiskSize: number;
 
-  constructor(maxSize = 100, cacheDir = ".cache/jiren") {
-    this.maxSize = maxSize;
+  constructor(l1Capacity = 100, cacheDir = ".cache/jiren", maxDiskSize = 100) {
+    this.l1 = new L1MemoryCache(l1Capacity);
+    this.maxDiskSize = maxDiskSize;
     this.cacheDir = cacheDir;
 
     // Create cache directory if it doesn't exist
@@ -45,10 +285,58 @@ export class ResponseCache {
   }
 
   /**
-   * Get cached response if valid
+   * Preload L2 disk cache entry into L1 memory cache.
+   * Call this during initialization to ensure first request hits L1.
+   * @param url - Base URL to preload
+   * @param path - Optional path
+   * @param options - Optional request options
+   * @returns true if entry was preloaded, false if not found/expired
+   */
+  preloadL1(url: string, path?: string, options?: any): boolean {
+    const key = this.generateKey(url, path, options);
+
+    // Check if already in L1
+    if (this.l1.get(key)) {
+      return true;
+    }
+
+    // Try to load from L2 disk
+    const l2Entry = this.getFromDisk(key);
+    if (l2Entry) {
+      this.l1.set(key, l2Entry);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get cached response - checks L1 first, then L2
    */
   get(url: string, path?: string, options?: any): JirenResponse | null {
     const key = this.generateKey(url, path, options);
+
+    // L1: Check in-memory cache first (~0.001ms)
+    const l1Entry = this.l1.get(key);
+    if (l1Entry) {
+      return l1Entry.response;
+    }
+
+    // L2: Check disk cache (~5ms)
+    const l2Entry = this.getFromDisk(key);
+    if (l2Entry) {
+      // Promote to L1 for faster future access
+      this.l1.set(key, l2Entry);
+      return l2Entry.response;
+    }
+
+    return null;
+  }
+
+  /**
+   * Get from L2 disk cache
+   */
+  private getFromDisk(key: string): CacheEntry | null {
     const filePath = this.getCacheFilePath(key);
 
     if (!existsSync(filePath)) return null;
@@ -60,30 +348,46 @@ export class ResponseCache {
       // Decompress
       const decompressed = gunzipSync(compressed);
       const data = decompressed.toString("utf-8");
-      const entry: CacheEntry = JSON.parse(data);
+      const serialized: SerializableCacheEntry = JSON.parse(data);
 
       // Check if expired
       const now = Date.now();
-      if (now - entry.timestamp > entry.ttl) {
+      if (now - serialized.timestamp > serialized.ttl) {
         // Delete expired cache file
         try {
-          require("fs").unlinkSync(filePath);
+          unlinkSync(filePath);
         } catch {}
         return null;
       }
 
-      return entry.response;
+      // Reconstruct the response with working body methods
+      const response: JirenResponse = {
+        status: serialized.status,
+        statusText: serialized.statusText,
+        headers: serialized.headers,
+        url: serialized.url,
+        ok: serialized.ok,
+        redirected: serialized.redirected,
+        type: serialized.type || "default",
+        body: reconstructBody(serialized.bodyData, serialized.bodyIsText),
+      };
+
+      return {
+        response,
+        timestamp: serialized.timestamp,
+        ttl: serialized.ttl,
+      };
     } catch (error) {
       // Invalid cache file, delete it
       try {
-        require("fs").unlinkSync(filePath);
+        unlinkSync(filePath);
       } catch {}
       return null;
     }
   }
 
   /**
-   * Store response in cache as compressed JSON file
+   * Store response in both L1 and L2 (write-through)
    */
   set(
     url: string,
@@ -93,7 +397,6 @@ export class ResponseCache {
     options?: any
   ): void {
     const key = this.generateKey(url, path, options);
-    const filePath = this.getCacheFilePath(key);
 
     const entry: CacheEntry = {
       response,
@@ -101,9 +404,59 @@ export class ResponseCache {
       ttl,
     };
 
+    // L1: Store in memory (~0.001ms)
+    this.l1.set(key, entry);
+
+    // L2: Store on disk (async-ish, for persistence)
+    this.setToDisk(key, entry);
+  }
+
+  /**
+   * Write to L2 disk cache
+   */
+  private async setToDisk(key: string, entry: CacheEntry): Promise<void> {
+    const filePath = this.getCacheFilePath(key);
+
     try {
+      // Extract body text for serialization
+      let bodyData: string;
+      let bodyIsText = true;
+
+      try {
+        bodyData = await entry.response.body.text();
+      } catch {
+        // If text fails, try arrayBuffer and convert to base64
+        try {
+          const buffer = await entry.response.body.arrayBuffer();
+          const bytes = new Uint8Array(buffer);
+          let binary = "";
+          for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]!);
+          }
+          bodyData = btoa(binary);
+          bodyIsText = false;
+        } catch {
+          bodyData = "";
+        }
+      }
+
+      // Create serializable entry
+      const serialized: SerializableCacheEntry = {
+        status: entry.response.status,
+        statusText: entry.response.statusText,
+        headers: entry.response.headers as Record<string, string>,
+        url: entry.response.url,
+        ok: entry.response.ok,
+        redirected: entry.response.redirected,
+        type: entry.response.type || "default",
+        bodyData,
+        bodyIsText,
+        timestamp: entry.timestamp,
+        ttl: entry.ttl,
+      };
+
       // Convert to JSON
-      const json = JSON.stringify(entry);
+      const json = JSON.stringify(serialized);
 
       // Compress with gzip
       const compressed = gzipSync(json);
@@ -120,26 +473,29 @@ export class ResponseCache {
    * Clear cache for a specific URL or all
    */
   clear(url?: string): void {
+    // Clear L1
+    this.l1.clear();
+
+    // Clear L2
     if (url) {
       // Clear all cache files for this URL
       // This is approximate since we hash the keys
       // For now, just clear all to be safe
-      this.clearAll();
+      this.clearAllDisk();
     } else {
-      this.clearAll();
+      this.clearAllDisk();
     }
   }
 
   /**
-   * Clear all cache files
+   * Clear all L2 disk cache files
    */
-  private clearAll(): void {
+  private clearAllDisk(): void {
     try {
-      const fs = require("fs");
-      const files = fs.readdirSync(this.cacheDir);
+      const files = readdirSync(this.cacheDir);
       for (const file of files) {
         if (file.endsWith(".json.gz")) {
-          fs.unlinkSync(join(this.cacheDir, file));
+          unlinkSync(join(this.cacheDir, file));
         }
       }
     } catch (error) {
@@ -148,34 +504,35 @@ export class ResponseCache {
   }
 
   /**
-   * Get cache statistics
+   * Get combined cache statistics
    */
   stats() {
+    const l1Stats = this.l1.stats();
+
+    // L2 disk stats
+    let diskSize = 0;
+    let diskFiles = 0;
+    let totalDiskBytes = 0;
+
     try {
-      const fs = require("fs");
-      const files = fs.readdirSync(this.cacheDir);
+      const files = readdirSync(this.cacheDir);
       const cacheFiles = files.filter((f: string) => f.endsWith(".json.gz"));
+      diskFiles = cacheFiles.length;
 
-      // Calculate total size
-      let totalSize = 0;
       for (const file of cacheFiles) {
-        const stats = fs.statSync(join(this.cacheDir, file));
-        totalSize += stats.size;
+        const stats = statSync(join(this.cacheDir, file));
+        totalDiskBytes += stats.size;
       }
+    } catch {}
 
-      return {
-        size: cacheFiles.length,
-        maxSize: this.maxSize,
-        cacheDir: this.cacheDir,
-        totalSizeKB: (totalSize / 1024).toFixed(2),
-      };
-    } catch {
-      return {
-        size: 0,
-        maxSize: this.maxSize,
+    return {
+      l1: l1Stats,
+      l2: {
+        size: diskFiles,
+        maxSize: this.maxDiskSize,
         cacheDir: this.cacheDir,
-        totalSizeKB: "0",
-      };
-    }
+        totalSizeKB: (totalDiskBytes / 1024).toFixed(2),
+      },
+    };
   }
 }

package/components/client-node-native.ts

@@ -6,7 +6,7 @@ import type {
   RequestOptions,
   JirenResponse,
   JirenResponseBody,
-  WarmupUrlConfig,
+  TargetUrlConfig,
   UrlRequestOptions,
   UrlEndpoint,
   CacheConfig,
@@ -32,8 +32,8 @@ export type UrlConfig = string | { url: string; cache?: boolean | CacheConfig };
 
 /** Options for JirenClient constructor */
 export interface JirenClientOptions<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
-    | readonly WarmupUrlConfig[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
+    | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
 > {
   /** URLs to warmup on client creation (pre-connect + handshake) */
@@ -45,8 +45,8 @@ export interface JirenClientOptions<
 
 /** Helper to extract keys from Warmup Config */
 export type ExtractWarmupKeys<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
-> = T extends readonly WarmupUrlConfig[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
+> = T extends readonly TargetUrlConfig[]
   ? T[number]["key"]
   : T extends Record<string, UrlConfig>
   ? keyof T
@@ -54,7 +54,7 @@ export type ExtractWarmupKeys<
 
 /** Type-safe URL accessor - maps keys to UrlEndpoint objects */
 export type UrlAccessor<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
 > = {
   [K in ExtractWarmupKeys<T>]: UrlEndpoint;
 };
@@ -62,21 +62,22 @@ export type UrlAccessor<
 /**
  * Helper function to define warmup URLs with type inference.
  */
-export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
+export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   urls: T
 ): T {
   return urls;
 }
 
 export class JirenClient<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
-    | readonly WarmupUrlConfig[]
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
+    | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
 > {
   private ptr: any = null; // Koffi pointer (Buffer or External)
   private urlMap: Map<string, string> = new Map();
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
     new Map();
+  private antibotConfig: Map<string, boolean> = new Map();
   private cache: ResponseCache;
 
   /** Type-safe URL accessor for warmed-up URLs */
@@ -104,8 +105,8 @@ export class JirenClient<
           if (typeof item === "string") {
             urls.push(item);
           } else {
-            // WarmupUrlConfig with key and optional cache
-            const config = item as WarmupUrlConfig;
+            // TargetUrlConfig with key and optional cache
+            const config = item as TargetUrlConfig;
             urls.push(config.url);
             this.urlMap.set(config.key, config.url);
 
@@ -117,6 +118,11 @@ export class JirenClient<
                   : { enabled: true, ttl: config.cache.ttl || 60000 };
               this.cacheConfig.set(config.key, cacheConfig);
             }
+
+            // Store antibot config
+            if (config.antibot) {
+              this.antibotConfig.set(config.key, true);
+            }
           }
         }
       } else {
@@ -139,6 +145,11 @@ export class JirenClient<
                   : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
               this.cacheConfig.set(key, cacheConfig);
             }
+
+            // Store antibot config
+            if ((urlConfig as { antibot?: boolean }).antibot) {
+              this.antibotConfig.set(key, true);
+            }
           }
         }
       }
@@ -146,12 +157,30 @@ export class JirenClient<
       if (urls.length > 0) {
         this.warmup(urls);
       }
+
+      // Preload L2 disk cache entries into L1 memory for cached endpoints
+      // This ensures user's first request hits L1 (~0.001ms) instead of L2 (~5ms)
+      for (const [key, config] of this.cacheConfig.entries()) {
+        if (config.enabled) {
+          const url = this.urlMap.get(key);
+          if (url) {
+            this.cache.preloadL1(url);
+          }
+        }
+      }
     }
 
     // Create proxy for type-safe URL access
     this.url = this.createUrlAccessor();
   }
 
+  /**
+   * Wait for warmup to complete
+   */
+  public async waitForWarmup(): Promise<void> {
+    // Native warmup is synchronous, so this is effectively a no-op
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access.
    */
@@ -180,6 +209,10 @@ export class JirenClient<
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
             const cacheConfig = self.cacheConfig.get(prop);
 
+            // Check if antibot is enabled for this URL (from warmup config or per-request)
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+
             if (cacheConfig?.enabled) {
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) {
@@ -195,7 +228,7 @@ export class JirenClient<
                 headers: options?.headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
-                antibot: options?.antibot,
+                antibot: useAntibot,
               }
             );