jiren 1.4.0 → 1.5.0

package/components/client.ts

@@ -1,15 +1,23 @@
 import { CString, toArrayBuffer, type Pointer } from "bun:ffi";
 import { lib } from "./native";
 import { ResponseCache } from "./cache";
+import { MetricsCollector, type RequestMetric } from "./metrics";
 import type {
   RequestOptions,
   JirenResponse,
   JirenResponseBody,
-  WarmupUrlConfig,
+  TargetUrlConfig,
   UrlRequestOptions,
   UrlEndpoint,
   CacheConfig,
   RetryConfig,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
+  MetricsAPI,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -27,29 +35,37 @@ 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<
-  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) */
-  warmup?: string[] | T;
+  /** Target URLs to pre-connect on client creation */
+  targets?: string[] | T;
 
   /** Enable benchmark mode (Force HTTP/2, disable probing) */
   benchmark?: boolean;
 
   /** Global retry configuration */
   retry?: number | RetryConfig;
+
+  /** Request/response interceptors */
+  interceptors?: Interceptors;
+
+  /** Performance mode: disable metrics, skip cache checks for non-cached endpoints (default: true) */
+  performanceMode?: boolean;
 }
 
-/** Helper to extract keys from Warmup Config */
-export type ExtractWarmupKeys<
-  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
-> = T extends readonly WarmupUrlConfig[]
+/** Helper to extract keys from Target Config */
+export type ExtractTargetKeys<
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
+> = T extends readonly TargetUrlConfig[]
   ? T[number]["key"]
   : T extends Record<string, UrlConfig>
   ? keyof T
@@ -57,76 +73,151 @@ 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;
+  [K in ExtractTargetKeys<T>]: UrlEndpoint;
 };
 
 /**
- * Helper function to define warmup URLs with type inference.
+ * Helper function to define target URLs with type inference.
  * This eliminates the need for 'as const'.
  *
  * @example
  * ```typescript
  * const client = new JirenClient({
- *   warmup: defineUrls([
+ *   targets: defineUrls([
  *     { key: "google", url: "https://google.com" },
  *   ])
  * });
  * // OR
  * const client = new JirenClient({
- *   warmup: {
+ *   targets: {
  *      google: "https://google.com"
  *   }
  * });
  * ```
  */
-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: Pointer | null;
   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 targetsPromise: Promise<void> | null = null;
+  private targetsComplete: Set<string> = new Set();
+  private performanceMode: boolean = false;
+
+  // Pre-computed headers (avoid per-request overhead)
+  private readonly defaultHeadersStr: string;
+  private readonly defaultHeadersBuffer: Buffer; // Cached 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",
+    accept:
+      "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+    "accept-encoding": "gzip",
+    "accept-language": "en-US,en;q=0.9",
+    "sec-ch-ua":
+      '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": '"macOS"',
+    "sec-fetch-dest": "document",
+    "sec-fetch-mode": "navigate",
+    "sec-fetch-site": "none",
+    "sec-fetch-user": "?1",
+    "upgrade-insecure-requests": "1",
+  };
+
+  // Pre-computed method buffers (avoid per-request allocation)
+  private readonly methodBuffers: Record<string, Buffer> = {
+    GET: Buffer.from("GET\0"),
+    POST: Buffer.from("POST\0"),
+    PUT: Buffer.from("PUT\0"),
+    PATCH: Buffer.from("PATCH\0"),
+    DELETE: Buffer.from("DELETE\0"),
+    HEAD: Buffer.from("HEAD\0"),
+    OPTIONS: Buffer.from("OPTIONS\0"),
+  };
+
+  // Reusable TextDecoder (avoid per-response allocation)
+  private readonly decoder = new TextDecoder();
 
   /** Type-safe URL accessor for warmed-up URLs */
   public readonly url: UrlAccessor<T>;
 
+  // Metrics collector
+  private metricsCollector: MetricsCollector;
+  /** Public metrics API */
+  public readonly metrics: MetricsAPI;
+
   constructor(options?: JirenClientOptions<T>) {
     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)
+    const orderedKeys = [
+      "sec-ch-ua",
+      "sec-ch-ua-mobile",
+      "sec-ch-ua-platform",
+      "upgrade-insecure-requests",
+      "user-agent",
+      "accept",
+      "sec-fetch-site",
+      "sec-fetch-mode",
+      "sec-fetch-user",
+      "sec-fetch-dest",
+      "accept-encoding",
+      "accept-language",
+    ];
+    this.defaultHeadersStr = orderedKeys
+      .map((k) => `${k}: ${this.defaultHeaders[k]}`)
+      .join("\r\n");
+    // Cache the Buffer to avoid per-request allocation
+    this.defaultHeadersBuffer = Buffer.from(this.defaultHeadersStr + "\0");
+
     // Initialize cache
     this.cache = new ResponseCache(100);
 
+    // Initialize metrics
+    this.metricsCollector = new MetricsCollector();
+    this.metrics = this.metricsCollector;
+
+    // Performance mode (default: true for maximum speed, set false to enable metrics)
+    this.performanceMode = options?.performanceMode ?? true;
+
     // Enable benchmark mode if requested
     if (options?.benchmark) {
       lib.symbols.zclient_set_benchmark_mode(this.ptr, true);
     }
 
-    // Process warmup URLs
-    if (options?.warmup) {
+    // Process target URLs
+    if (options?.targets) {
       const urls: string[] = [];
-      const warmup = options.warmup;
+      const targets = options.targets;
 
-      if (Array.isArray(warmup)) {
-        for (const item of warmup) {
+      if (Array.isArray(targets)) {
+        for (const item of targets) {
           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);
 
@@ -138,11 +229,19 @@ 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 {
         // Record<string, UrlConfig>
-        for (const [key, urlConfig] of Object.entries(warmup)) {
+        for (const [key, urlConfig] of Object.entries(targets) as [
+          string,
+          UrlConfig
+        ][]) {
           if (typeof urlConfig === "string") {
             // Simple string URL
             urls.push(urlConfig);
@@ -160,12 +259,32 @@ export class JirenClient<
                   : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
               this.cacheConfig.set(key, cacheConfig);
             }
+
+            // Store antibot config
+            if (urlConfig.antibot) {
+              this.antibotConfig.set(key, true);
+            }
           }
         }
       }
 
       if (urls.length > 0) {
-        this.warmup(urls);
+        // Lazy pre-connect in background (always - it's faster)
+        this.targetsPromise = this.preconnect(urls).then(() => {
+          urls.forEach((url) => this.targetsComplete.add(url));
+          this.targetsPromise = null; // Clear when done to skip future checks
+        });
+      }
+
+      // 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 +298,34 @@ 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 pre-connection to complete.
+   * Only needed if you want to ensure targets are ready before making requests.
+   */
+  public async waitForTargets(): Promise<void> {
+    if (this.targetsPromise) await this.targetsPromise;
+  }
+
+  /**
+   * @deprecated Use waitForTargets() instead
+   */
+  public async waitForWarmup(): Promise<void> {
+    return this.waitForTargets();
+  }
+
   /**
    * Creates a proxy-based URL accessor for type-safe access to warmed-up URLs.
    */
@@ -213,13 +354,55 @@ export class JirenClient<
           get: async <R = any>(
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            // Wait for targets to complete if still pending
+            if (self.targetsPromise) {
+              await self.targetsPromise;
+            }
+
             // Check if caching is enabled for this URL
             const cacheConfig = self.cacheConfig.get(prop);
 
+            // Check if antibot is enabled for this URL (from targets config or per-request)
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+
+            // === FAST PATH: Skip overhead when no cache and performance mode ===
+            if (!cacheConfig?.enabled && self.performanceMode) {
+              return self.request<R>("GET", buildUrl(options?.path), null, {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: useAntibot,
+              });
+            }
+
+            // === SLOW PATH: Full features (cache, metrics, dedupe) ===
+            const startTime = performance.now();
+
+            // Try L1 cache first
             if (cacheConfig?.enabled) {
-              // Try to get from cache
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) {
+                const responseTimeMs = performance.now() - startTime;
+
+                // Check which cache layer hit (L1 in memory is very fast ~0.001-0.1ms, L2 disk is ~1-5ms)
+                const cacheLayer = responseTimeMs < 0.5 ? "l1" : "l2";
+
+                // Record cache hit metric (skip in performance mode)
+                if (!self.performanceMode) {
+                  self.metricsCollector.recordRequest(prop, {
+                    startTime,
+                    responseTimeMs,
+                    status: cached.status,
+                    success: cached.ok,
+                    bytesSent: 0,
+                    bytesReceived: 0,
+                    cacheHit: true,
+                    cacheLayer,
+                    dedupeHit: false,
+                  });
+                }
+
                 return cached as any;
               }
             }
@@ -232,7 +415,28 @@ export class JirenClient<
 
             // Check if there is already an identical request in flight
             if (self.inflightRequests.has(dedupKey)) {
-              return self.inflightRequests.get(dedupKey);
+              const dedupeStart = performance.now();
+              const result = await self.inflightRequests.get(dedupKey);
+              const responseTimeMs = performance.now() - dedupeStart;
+
+              // Record deduplication hit (skip in performance mode)
+              if (!self.performanceMode) {
+                self.metricsCollector.recordRequest(prop, {
+                  startTime: dedupeStart,
+                  responseTimeMs,
+                  status:
+                    typeof result === "object" && "status" in result
+                      ? result.status
+                      : 200,
+                  success: true,
+                  bytesSent: 0,
+                  bytesReceived: 0,
+                  cacheHit: false,
+                  dedupeHit: true,
+                });
+              }
+
+              return result;
             }
 
             // Create the request promise
@@ -247,7 +451,7 @@ export class JirenClient<
                     headers: options?.headers,
                     maxRedirects: options?.maxRedirects,
                     responseType: options?.responseType,
-                    antibot: options?.antibot,
+                    antibot: useAntibot,
                   }
                 );
 
@@ -266,7 +470,50 @@ export class JirenClient<
                   );
                 }
 
+                const responseTimeMs = performance.now() - startTime;
+
+                // Record request metric (skip in performance mode)
+                if (!self.performanceMode) {
+                  self.metricsCollector.recordRequest(prop, {
+                    startTime,
+                    responseTimeMs,
+                    status:
+                      typeof response === "object" && "status" in response
+                        ? response.status
+                        : 200,
+                    success:
+                      typeof response === "object" && "ok" in response
+                        ? response.ok
+                        : true,
+                    bytesSent: options?.body
+                      ? JSON.stringify(options.body).length
+                      : 0,
+                    bytesReceived: 0,
+                    cacheHit: false,
+                    dedupeHit: false,
+                  });
+                }
+
                 return response;
+              } catch (error) {
+                // Record failed request (skip in performance mode)
+                if (!self.performanceMode) {
+                  const responseTimeMs = performance.now() - startTime;
+                  self.metricsCollector.recordRequest(prop, {
+                    startTime,
+                    responseTimeMs,
+                    status: 0,
+                    success: false,
+                    bytesSent: 0,
+                    bytesReceived: 0,
+                    cacheHit: false,
+                    dedupeHit: false,
+                    error:
+                      error instanceof Error ? error.message : String(error),
+                  });
+                }
+
+                throw error;
               } finally {
                 // Remove from inflight map when done (success or failure)
                 self.inflightRequests.delete(dedupKey);
@@ -410,14 +657,28 @@ export class JirenClient<
   }
 
   /**
-   * Warm up connections to URLs (DNS resolve + QUIC handshake) in parallel.
+   * 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;
+  }
+
+  /**
+   * Pre-connect to URLs (DNS resolve + QUIC handshake) in parallel.
    * Call this early (e.g., at app startup) so subsequent requests are fast.
-   * @param urls - List of URLs to warm up
+   * @param urls - List of URLs to pre-connect to
    */
-  public async warmup(urls: string[]): Promise<void> {
+  public async preconnect(urls: string[]): Promise<void> {
     if (!this.ptr) throw new Error("Client is closed");
 
-    // Warm up all URLs in parallel for faster startup
+    // Pre-connect to all URLs in parallel for faster startup
     await Promise.all(
       urls.map(
         (url) =>
@@ -431,10 +692,17 @@ export class JirenClient<
   }
 
   /**
-   * @deprecated Use warmup() instead
+   * @deprecated Use preconnect() instead
+   */
+  public async warmup(urls: string[]): Promise<void> {
+    return this.preconnect(urls);
+  }
+
+  /**
+   * @deprecated Use preconnect() instead
    */
   public prefetch(urls: string[]): void {
-    this.warmup(urls);
+    this.preconnect(urls);
   }
 
   /**
@@ -510,7 +778,22 @@ export class JirenClient<
       }
     }
 
-    const methodBuffer = Buffer.from(method + "\0");
+    // Run interceptors only if any are registered
+    let ctx: InterceptorRequestContext = { method, url, headers, body };
+    if (this.requestInterceptors.length > 0) {
+      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;
+    }
+
+    // Use pre-computed method buffer or create one for custom methods
+    const methodBuffer =
+      this.methodBuffers[method] || Buffer.from(method + "\0");
     const urlBuffer = Buffer.from(url + "\0");
 
     let bodyBuffer: Buffer | null = null;
@@ -518,63 +801,51 @@ export class JirenClient<
       bodyBuffer = Buffer.from(body + "\0");
     }
 
-    let headersBuffer: Buffer | null = null;
-    const 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",
-      accept:
-        "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
-      "accept-encoding": "gzip",
-      "accept-language": "en-US,en;q=0.9",
-      "sec-ch-ua":
-        '"Not_A Brand";v="8", "Chromium";v="120", "Google Chrome";v="120"',
-      "sec-ch-ua-mobile": "?0",
-      "sec-ch-ua-platform": '"macOS"',
-      "sec-fetch-dest": "document",
-      "sec-fetch-mode": "navigate",
-      "sec-fetch-site": "none",
-      "sec-fetch-user": "?1",
-      "upgrade-insecure-requests": "1",
-    };
-
-    const finalHeaders = { ...defaultHeaders, ...headers };
-
-    // Enforce Chrome header order
-    const orderedHeaders: Record<string, string> = {};
-    const keys = [
-      "sec-ch-ua",
-      "sec-ch-ua-mobile",
-      "sec-ch-ua-platform",
-      "upgrade-insecure-requests",
-      "user-agent",
-      "accept",
-      "sec-fetch-site",
-      "sec-fetch-mode",
-      "sec-fetch-user",
-      "sec-fetch-dest",
-      "accept-encoding",
-      "accept-language",
-    ];
-
-    // Add priority headers in order
-    for (const key of keys) {
-      if (finalHeaders[key]) {
-        orderedHeaders[key] = finalHeaders[key];
-        delete finalHeaders[key];
+    let headersBuffer: Buffer;
+    const hasCustomHeaders = Object.keys(headers).length > 0;
+
+    if (hasCustomHeaders) {
+      // Merge custom headers with defaults (slow path)
+      const finalHeaders = { ...this.defaultHeaders, ...headers };
+
+      // Enforce Chrome header order
+      const orderedHeaders: Record<string, string> = {};
+      const keys = [
+        "sec-ch-ua",
+        "sec-ch-ua-mobile",
+        "sec-ch-ua-platform",
+        "upgrade-insecure-requests",
+        "user-agent",
+        "accept",
+        "sec-fetch-site",
+        "sec-fetch-mode",
+        "sec-fetch-user",
+        "sec-fetch-dest",
+        "accept-encoding",
+        "accept-language",
+      ];
+
+      // Add priority headers in order
+      for (const key of keys) {
+        if (finalHeaders[key]) {
+          orderedHeaders[key] = finalHeaders[key];
+          delete finalHeaders[key];
+        }
       }
-    }
 
-    // Add remaining custom headers
-    for (const [key, value] of Object.entries(finalHeaders)) {
-      orderedHeaders[key] = value;
-    }
+      // Add remaining custom headers
+      for (const [key, value] of Object.entries(finalHeaders)) {
+        orderedHeaders[key] = value;
+      }
 
-    const headerStr = Object.entries(orderedHeaders)
-      .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
-      .join("\r\n");
+      const headerStr = Object.entries(orderedHeaders)
+        .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
+        .join("\r\n");
 
-    if (headerStr.length > 0) {
       headersBuffer = Buffer.from(headerStr + "\0");
+    } else {
+      // Fast path: use pre-computed headers buffer (no allocation!)
+      headersBuffer = this.defaultHeadersBuffer;
     }
 
     // Determine retry configuration
@@ -603,7 +874,8 @@ export class JirenClient<
     while (attempts < maxAttempts) {
       attempts++;
       try {
-        const respPtr = lib.symbols.zclient_request(
+        // Use optimized single-call API (reduces 5 FFI calls to 1)
+        const respPtr = lib.symbols.zclient_request_full(
           this.ptr,
           methodBuffer,
           urlBuffer,
@@ -617,7 +889,20 @@ export class JirenClient<
           throw new Error("Native request failed (returned null pointer)");
         }
 
-        const response = this.parseResponse<T>(respPtr, url);
+        const response = this.parseResponseFull<T>(respPtr, url);
+
+        // Run response interceptors only if any registered
+        let finalResponse = response;
+        if (this.responseInterceptors.length > 0) {
+          let responseCtx: InterceptorResponseContext<T> = {
+            request: ctx,
+            response,
+          };
+          for (const interceptor of this.responseInterceptors) {
+            responseCtx = await interceptor(responseCtx);
+          }
+          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)
@@ -626,15 +911,21 @@ 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 only if any registered
+        if (this.errorInterceptors.length > 0) {
+          for (const interceptor of this.errorInterceptors) {
+            await interceptor(err as Error, ctx);
+          }
+        }
         lastError = err;
         if (attempts < maxAttempts) {
           // Wait before retrying
@@ -697,6 +988,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);
+
+        // 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;
@@ -725,11 +1037,11 @@ export class JirenClient<
         },
         text: async () => {
           consumeBody();
-          return new TextDecoder().decode(buffer);
+          return this.decoder.decode(buffer);
         },
         json: async <R = T>(): Promise<R> => {
           consumeBody();
-          const text = new TextDecoder().decode(buffer);
+          const text = this.decoder.decode(buffer);
           return JSON.parse(text);
         },
       };
@@ -754,6 +1066,119 @@ export class JirenClient<
     }
   }
 
+  /**
+   * Optimized response parser using ZFullResponse struct (single FFI call got all data)
+   */
+  private parseResponseFull<T = any>(
+    respPtr: Pointer | null,
+    url: string
+  ): JirenResponse<T> {
+    if (!respPtr)
+      throw new Error("Native request failed (returned null pointer)");
+
+    try {
+      // Use FFI accessor functions (avoids BigInt-to-Pointer conversion issues)
+      const status = lib.symbols.zfull_response_status(respPtr);
+      const bodyPtr = lib.symbols.zfull_response_body(respPtr);
+      const bodyLen = Number(lib.symbols.zfull_response_body_len(respPtr));
+      const headersPtr = lib.symbols.zfull_response_headers(respPtr);
+      const headersLen = Number(
+        lib.symbols.zfull_response_headers_len(respPtr)
+      );
+
+      let headersObj: Record<string, string> | NativeHeaders = {};
+      if (headersLen > 0 && headersPtr) {
+        const rawSrc = toArrayBuffer(headersPtr, 0, headersLen);
+        const raw = new Uint8Array(rawSrc.slice(0));
+        headersObj = new NativeHeaders(raw);
+      }
+
+      // Simplified proxy for performance mode
+      const headersProxy = this.performanceMode
+        ? (headersObj as Record<string, string>)
+        : (new Proxy(headersObj instanceof NativeHeaders ? headersObj : {}, {
+            get(target, prop) {
+              if (target instanceof NativeHeaders && typeof prop === "string") {
+                if (prop === "toJSON") return () => target.toJSON();
+                const val = target.get(prop);
+                if (val !== null) return val;
+              }
+              return Reflect.get(target, prop);
+            },
+          }) as unknown as Record<string, string>);
+
+      let buffer: ArrayBuffer | Buffer = new ArrayBuffer(0);
+      if (bodyLen > 0 && bodyPtr) {
+        buffer = toArrayBuffer(bodyPtr, 0, bodyLen).slice(0);
+
+        // Handle GZIP decompression
+        const bufferView = new Uint8Array(buffer);
+        if (
+          bufferView.length >= 2 &&
+          bufferView[0] === 0x1f &&
+          bufferView[1] === 0x8b
+        ) {
+          try {
+            const decompressed = Bun.gunzipSync(bufferView);
+            buffer = decompressed.buffer.slice(
+              decompressed.byteOffset,
+              decompressed.byteOffset + decompressed.byteLength
+            );
+          } catch (e) {
+            console.warn("[Jiren] gzip decompression failed:", e);
+          }
+        }
+      }
+
+      let bodyUsed = false;
+      const consumeBody = () => {
+        bodyUsed = true;
+      };
+
+      const bodyObj: JirenResponseBody<T> = {
+        bodyUsed: false,
+        arrayBuffer: async () => {
+          consumeBody();
+          if (Buffer.isBuffer(buffer)) {
+            const buf = buffer as Buffer;
+            return buf.buffer.slice(
+              buf.byteOffset,
+              buf.byteOffset + buf.byteLength
+            ) as ArrayBuffer;
+          }
+          return buffer as ArrayBuffer;
+        },
+        blob: async () => {
+          consumeBody();
+          return new Blob([buffer]);
+        },
+        text: async () => {
+          consumeBody();
+          return this.decoder.decode(buffer);
+        },
+        json: async <R = T>(): Promise<R> => {
+          consumeBody();
+          return JSON.parse(this.decoder.decode(buffer));
+        },
+      };
+
+      Object.defineProperty(bodyObj, "bodyUsed", { get: () => bodyUsed });
+
+      return {
+        url,
+        status,
+        statusText: STATUS_TEXT[status] || "",
+        headers: headersProxy,
+        ok: status >= 200 && status < 300,
+        redirected: false,
+        type: "basic",
+        body: bodyObj,
+      } as JirenResponse<T>;
+    } finally {
+      lib.symbols.zclient_response_full_free(respPtr);
+    }
+  }
+
   /**
    * Helper to prepare body and headers for requests.
    * Handles JSON stringification and Content-Type header.