jiren 1.4.5 → 1.5.5

package/components/client.ts

@@ -1,11 +1,12 @@
 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,
@@ -16,6 +17,7 @@ import type {
   ErrorInterceptor,
   InterceptorRequestContext,
   InterceptorResponseContext,
+  MetricsAPI,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -40,12 +42,12 @@ export type UrlConfig =
 
 /** 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;
@@ -55,12 +57,15 @@ export interface JirenClientOptions<
 
   /** 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
@@ -68,39 +73,39 @@ 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;
@@ -114,36 +119,105 @@ export class JirenClient<
   private requestInterceptors: RequestInterceptor[] = [];
   private responseInterceptors: ResponseInterceptor[] = [];
   private errorInterceptors: ErrorInterceptor[] = [];
-  private warmupPromise: Promise<void> | null = null;
-  private warmupComplete: Set<string> = new Set();
+  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);
 
@@ -164,7 +238,10 @@ export class JirenClient<
         }
       } 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);
@@ -184,7 +261,7 @@ export class JirenClient<
             }
 
             // Store antibot config
-            if ((urlConfig as { antibot?: boolean }).antibot) {
+            if (urlConfig.antibot) {
               this.antibotConfig.set(key, true);
             }
           }
@@ -192,9 +269,10 @@ export class JirenClient<
       }
 
       if (urls.length > 0) {
-        // Lazy warmup in background (always - it's faster)
-        this.warmupPromise = this.warmup(urls).then(() => {
-          urls.forEach((url) => this.warmupComplete.add(url));
+        // 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
         });
       }
 
@@ -234,11 +312,18 @@ export class JirenClient<
   }
 
   /**
-   * Wait for lazy warmup to complete.
-   * Only needed if using lazyWarmup: true and want to ensure warmup is done.
+   * 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> {
-    if (this.warmupPromise) await this.warmupPromise;
+    return this.waitForTargets();
   }
 
   /**
@@ -269,22 +354,55 @@ 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;
+            // 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 warmup config or per-request)
+            // 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;
               }
             }
@@ -297,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
@@ -331,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);
@@ -489,14 +671,14 @@ export class JirenClient<
   }
 
   /**
-   * Warm up connections to URLs (DNS resolve + QUIC handshake) in parallel.
+   * 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) =>
@@ -510,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);
   }
 
   /**
@@ -589,21 +778,22 @@ export class JirenClient<
       }
     }
 
-    // Build interceptor request context
+    // Run interceptors only if any are registered
     let ctx: InterceptorRequestContext = { method, url, headers, body };
-
-    // Run request interceptors
-    for (const interceptor of this.requestInterceptors) {
-      ctx = await interceptor(ctx);
+    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;
     }
 
-    // Apply interceptor modifications
-    method = ctx.method;
-    url = ctx.url;
-    headers = ctx.headers;
-    body = ctx.body ?? null;
-
-    const methodBuffer = Buffer.from(method + "\0");
+    // 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;
@@ -611,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
@@ -696,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,
@@ -710,17 +889,20 @@ export class JirenClient<
           throw new Error("Native request failed (returned null pointer)");
         }
 
-        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 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;
         }
-        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)
@@ -738,9 +920,11 @@ export class JirenClient<
 
         return finalResponse;
       } catch (err) {
-        // Run error interceptors
-        for (const interceptor of this.errorInterceptors) {
-          await interceptor(err as Error, ctx);
+        // 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) {
@@ -853,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);
         },
       };
@@ -882,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.