jiren 1.3.1 → 1.4.5

package/components/client-node-native.ts

@@ -77,6 +77,7 @@ export class JirenClient<
   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 */
@@ -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,10 +209,14 @@ 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) {
-                return self.rehydrateResponse(cached);
+                return cached as any;
               }
             }
 
@@ -195,7 +228,7 @@ export class JirenClient<
                 headers: options?.headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
-                antibot: options?.antibot,
+                antibot: useAntibot,
               }
             );
 
@@ -535,39 +568,42 @@ export class JirenClient<
         // Copy body content
         buffer = Buffer.from(koffi.decode(bodyPtr, "uint8_t", len));
 
-        // Handle GZIP compression
+        // Handle GZIP compression - search for magic bytes in first 16 bytes
+        // (handles chunked encoding or other framing that may add prefix bytes)
         const contentEncoding = headersProxy["content-encoding"]?.toLowerCase();
+        let gzipOffset = -1;
 
-        if (
-          contentEncoding === "gzip" ||
-          (buffer.length > 2 && buffer[0] === 0x1f && buffer[1] === 0x8b)
-        ) {
+        // Search for gzip magic bytes (0x1f 0x8b) in first 16 bytes
+        for (let i = 0; i < Math.min(16, buffer.length - 1); i++) {
+          if (buffer[i] === 0x1f && buffer[i + 1] === 0x8b) {
+            gzipOffset = i;
+            break;
+          }
+        }
+
+        if (contentEncoding === "gzip" || gzipOffset >= 0) {
           try {
-            console.log("[Jiren] Attempting gunzip...");
-            buffer = zlib.gunzipSync(buffer);
-            console.log("[Jiren] Gunzip success!");
+            // If we found gzip at an offset, slice from there
+            const gzipData = gzipOffset > 0 ? buffer.slice(gzipOffset) : buffer;
+            console.log(
+              `[Jiren] Decompressing gzip (offset: ${
+                gzipOffset >= 0 ? gzipOffset : 0
+              }, size: ${gzipData.length})`
+            );
+            buffer = zlib.gunzipSync(gzipData);
           } catch (e) {
             console.warn("Failed to gunzip response body:", e);
           }
         }
       }
 
-      // Convert to base64 for caching persistence
-      let base64Data = "";
-      try {
-        base64Data = buffer.toString("base64");
-      } catch (e) {
-        // Should not happen
-      }
-
       let bodyUsed = false;
       const consumeBody = () => {
         bodyUsed = true;
       };
 
-      const bodyObj: JirenResponseBody<T> & { _raw?: string } = {
+      const bodyObj: JirenResponseBody<T> = {
         bodyUsed: false,
-        _raw: base64Data,
         arrayBuffer: async () => {
           consumeBody();
           return buffer.buffer.slice(
@@ -607,63 +643,6 @@ export class JirenClient<
       lib.symbols.zclient_response_free(respPtr);
     }
   }
-
-  /**
-   * Rehydrates a cached response object by restoring the body interface methods.
-   * This is necessary because JSON serialization strips functions.
-   */
-  private rehydrateResponse(cached: any): JirenResponse {
-    // If it already has methods, return as is
-    if (typeof cached.body.text === "function") return cached;
-
-    // Retrieve raw data
-    const rawData = cached.body._raw;
-    let buffer: Buffer;
-
-    if (rawData) {
-      buffer = Buffer.from(rawData, "base64");
-    } else {
-      buffer = Buffer.from("");
-    }
-
-    let bodyUsed = cached.body.bodyUsed || false;
-    const consumeBody = () => {
-      bodyUsed = true;
-    };
-
-    const bodyObj: JirenResponseBody = {
-      _raw: rawData, // Keep it for re-caching if needed
-      bodyUsed,
-      arrayBuffer: async () => {
-        consumeBody();
-        return buffer.buffer.slice(
-          buffer.byteOffset,
-          buffer.byteOffset + buffer.byteLength
-        ) as ArrayBuffer;
-      },
-      blob: async () => {
-        consumeBody();
-        return new Blob([buffer as any]);
-      },
-      text: async () => {
-        consumeBody();
-        return buffer.toString("utf-8");
-      },
-      json: async <R = any>(): Promise<R> => {
-        consumeBody();
-        return JSON.parse(buffer.toString("utf-8"));
-      },
-    } as any;
-
-    Object.defineProperty(bodyObj, "bodyUsed", {
-      get: () => bodyUsed,
-    });
-
-    return {
-      ...cached,
-      body: bodyObj,
-    };
-  }
 }
 
 class NativeHeaders {

package/components/client-node.ts

@@ -58,6 +58,7 @@ export class JirenClient<
   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 */
@@ -90,6 +91,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 {
@@ -112,6 +118,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);
+            }
           }
         }
       }
@@ -119,12 +130,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 (no-op for fetch client)
+   */
+  public async waitForWarmup(): Promise<void> {
+    // No-op - fetch client warmup is fire-and-forget
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access.
    */
@@ -153,6 +182,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) return cached as any;
@@ -166,7 +199,7 @@ export class JirenClient<
                 headers: options?.headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
-                antibot: options?.antibot,
+                antibot: useAntibot,
               }
             );
 

package/components/client.ts

@@ -10,6 +10,12 @@ import type {
   UrlEndpoint,
   CacheConfig,
   RetryConfig,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -27,8 +33,10 @@ const STATUS_TEXT: Record<number, string> = {
   503: "Service Unavailable",
 };
 
-/** URL configuration with optional cache */
-export type UrlConfig = string | { url: string; cache?: boolean | CacheConfig };
+/** URL configuration with optional cache and antibot */
+export type UrlConfig =
+  | string
+  | { url: string; cache?: boolean | CacheConfig; antibot?: boolean };
 
 /** Options for JirenClient constructor */
 export interface JirenClientOptions<
@@ -44,6 +52,9 @@ export interface JirenClientOptions<
 
   /** Global retry configuration */
   retry?: number | RetryConfig;
+
+  /** Request/response interceptors */
+  interceptors?: Interceptors;
 }
 
 /** Helper to extract keys from Warmup Config */
@@ -96,9 +107,15 @@ export class JirenClient<
   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;
   private inflightRequests: Map<string, Promise<any>> = new Map();
   private globalRetry?: RetryConfig;
+  private requestInterceptors: RequestInterceptor[] = [];
+  private responseInterceptors: ResponseInterceptor[] = [];
+  private errorInterceptors: ErrorInterceptor[] = [];
+  private warmupPromise: Promise<void> | null = null;
+  private warmupComplete: Set<string> = new Set();
 
   /** Type-safe URL accessor for warmed-up URLs */
   public readonly url: UrlAccessor<T>;
@@ -138,6 +155,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 {
@@ -160,12 +182,31 @@ 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);
+            }
           }
         }
       }
 
       if (urls.length > 0) {
-        this.warmup(urls);
+        // Lazy warmup in background (always - it's faster)
+        this.warmupPromise = this.warmup(urls).then(() => {
+          urls.forEach((url) => this.warmupComplete.add(url));
+        });
+      }
+
+      // 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);
+          }
+        }
       }
     }
 
@@ -179,12 +220,27 @@ export class JirenClient<
           ? { count: options.retry, delay: 100, backoff: 2 }
           : options.retry;
     }
+
+    // Initialize interceptors
+    if (options?.interceptors) {
+      this.requestInterceptors = options.interceptors.request || [];
+      this.responseInterceptors = options.interceptors.response || [];
+      this.errorInterceptors = options.interceptors.error || [];
+    }
   }
 
   private async waitFor(ms: number) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  /**
+   * Wait for lazy warmup to complete.
+   * Only needed if using lazyWarmup: true and want to ensure warmup is done.
+   */
+  public async waitForWarmup(): Promise<void> {
+    if (this.warmupPromise) await this.warmupPromise;
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access to warmed-up URLs.
    */
@@ -213,14 +269,23 @@ export class JirenClient<
           get: async <R = any>(
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            // Wait for warmup to complete if not yet done
+            if (self.warmupPromise && !self.warmupComplete.has(baseUrl)) {
+              await self.warmupPromise;
+            }
+
             // Check if caching is enabled for this URL
             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) {
               // Try to get from cache
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) {
-                return self.rehydrateResponse(cached);
+                return cached as any;
               }
             }
 
@@ -247,7 +312,7 @@ export class JirenClient<
                     headers: options?.headers,
                     maxRedirects: options?.maxRedirects,
                     responseType: options?.responseType,
-                    antibot: options?.antibot,
+                    antibot: useAntibot,
                   }
                 );
 
@@ -409,6 +474,20 @@ export class JirenClient<
     }
   }
 
+  /**
+   * Register interceptors dynamically.
+   * @param interceptors - Interceptor configuration to add
+   * @returns this for chaining
+   */
+  public use(interceptors: Interceptors): this {
+    if (interceptors.request)
+      this.requestInterceptors.push(...interceptors.request);
+    if (interceptors.response)
+      this.responseInterceptors.push(...interceptors.response);
+    if (interceptors.error) this.errorInterceptors.push(...interceptors.error);
+    return this;
+  }
+
   /**
    * Warm up connections to URLs (DNS resolve + QUIC handshake) in parallel.
    * Call this early (e.g., at app startup) so subsequent requests are fast.
@@ -510,6 +589,20 @@ export class JirenClient<
       }
     }
 
+    // Build interceptor request context
+    let ctx: InterceptorRequestContext = { method, url, headers, body };
+
+    // Run request interceptors
+    for (const interceptor of this.requestInterceptors) {
+      ctx = await interceptor(ctx);
+    }
+
+    // Apply interceptor modifications
+    method = ctx.method;
+    url = ctx.url;
+    headers = ctx.headers;
+    body = ctx.body ?? null;
+
     const methodBuffer = Buffer.from(method + "\0");
     const urlBuffer = Buffer.from(url + "\0");
 
@@ -619,6 +712,16 @@ export class JirenClient<
 
         const response = this.parseResponse<T>(respPtr, url);
 
+        // Run response interceptors
+        let responseCtx: InterceptorResponseContext<T> = {
+          request: ctx,
+          response,
+        };
+        for (const interceptor of this.responseInterceptors) {
+          responseCtx = await interceptor(responseCtx);
+        }
+        const finalResponse = responseCtx.response;
+
         // Optional: Retry on specific status codes (e.g., 500, 502, 503, 504)
         // For now, we only retry on actual exceptions/network failures (null ptr)
         // or if we decide to throw on 5xx here.
@@ -626,15 +729,19 @@ export class JirenClient<
 
         // Auto-parse if requested
         if (responseType) {
-          if (responseType === "json") return response.body.json();
-          if (responseType === "text") return response.body.text();
+          if (responseType === "json") return finalResponse.body.json();
+          if (responseType === "text") return finalResponse.body.text();
           if (responseType === "arraybuffer")
-            return response.body.arrayBuffer();
-          if (responseType === "blob") return response.body.blob();
+            return finalResponse.body.arrayBuffer();
+          if (responseType === "blob") return finalResponse.body.blob();
         }
 
-        return response;
+        return finalResponse;
       } catch (err) {
+        // Run error interceptors
+        for (const interceptor of this.errorInterceptors) {
+          await interceptor(err as Error, ctx);
+        }
         lastError = err;
         if (attempts < maxAttempts) {
           // Wait before retrying
@@ -697,14 +804,27 @@ export class JirenClient<
       if (len > 0 && bodyPtr) {
         // Create a copy of the buffer because the native response is freed immediately after
         buffer = toArrayBuffer(bodyPtr, 0, len).slice(0);
-      }
 
-      // Convert to base64 for caching persistence
-      let base64Data = "";
-      try {
-        base64Data = Buffer.from(buffer).toString("base64");
-      } catch (e) {
-        // Should not happen for valid buffer
+        // Handle GZIP decompression if needed
+        const bufferView = new Uint8Array(buffer);
+        // Check for gzip magic bytes (0x1f 0x8b)
+        if (
+          bufferView.length >= 2 &&
+          bufferView[0] === 0x1f &&
+          bufferView[1] === 0x8b
+        ) {
+          try {
+            // Use Bun's built-in gzip decompression
+            const decompressed = Bun.gunzipSync(bufferView);
+            buffer = decompressed.buffer.slice(
+              decompressed.byteOffset,
+              decompressed.byteOffset + decompressed.byteLength
+            );
+          } catch (e) {
+            // Decompression failed, keep original buffer
+            console.warn("[Jiren] gzip decompression failed:", e);
+          }
+        }
       }
 
       let bodyUsed = false;
@@ -714,9 +834,8 @@ export class JirenClient<
         bodyUsed = true;
       };
 
-      const bodyObj: JirenResponseBody<T> & { _raw?: string } = {
+      const bodyObj: JirenResponseBody<T> = {
         bodyUsed: false,
-        _raw: base64Data,
         arrayBuffer: async () => {
           consumeBody();
           if (Buffer.isBuffer(buffer)) {
@@ -791,64 +910,6 @@ export class JirenClient<
 
     return { headers, serializedBody };
   }
-
-  /**
-   * Rehydrates a cached response object by restoring the body interface methods.
-   * This is necessary because JSON serialization strips functions.
-   */
-  private rehydrateResponse(cached: any): JirenResponse {
-    // If it already has methods, return as is
-    if (typeof cached.body.text === "function") return cached;
-
-    // Retrieve raw data
-    const rawData = cached.body._raw;
-    let buffer: Buffer;
-
-    if (rawData) {
-      buffer = Buffer.from(rawData, "base64");
-    } else {
-      buffer = Buffer.from("");
-    }
-
-    let bodyUsed = cached.body.bodyUsed || false;
-    const consumeBody = () => {
-      bodyUsed = true;
-    };
-
-    const bodyObj: JirenResponseBody = {
-      _raw: rawData, // Keep it for re-caching if needed
-      bodyUsed,
-      arrayBuffer: async () => {
-        consumeBody();
-        return buffer.buffer.slice(
-          buffer.byteOffset,
-          buffer.byteOffset + buffer.byteLength
-        ) as ArrayBuffer;
-      },
-      blob: async () => {
-        consumeBody();
-        return new Blob([buffer]);
-      },
-      text: async () => {
-        consumeBody();
-        return new TextDecoder().decode(buffer);
-      },
-      json: async <R = any>(): Promise<R> => {
-        consumeBody();
-        const text = new TextDecoder().decode(buffer);
-        return JSON.parse(text);
-      },
-    } as any;
-
-    Object.defineProperty(bodyObj, "bodyUsed", {
-      get: () => bodyUsed,
-    });
-
-    return {
-      ...cached,
-      body: bodyObj,
-    };
-  }
 }
 
 class NativeHeaders {

package/components/index.ts

@@ -20,6 +20,12 @@ export type {
   UrlEndpoint,
   JirenResponse,
   JirenResponseBody,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
 } from "./types";
 
 // Remove broken exports