jiren 1.5.5 → 1.6.5

package/components/client-node-native.ts

@@ -1,5 +1,11 @@
-import { nativeLib as lib } from "./native-node";
-import { ResponseCache } from "./cache";
+import {
+  nativeLib as lib,
+  ZPipelineRequest,
+  ZPipelineResponse,
+  ZPipelineResult,
+} from "./native-node.js";
+import { ResponseCache } from "./cache.js";
+import { MetricsCollector, type RequestMetric } from "./metrics.js";
 import koffi from "koffi";
 import zlib from "zlib";
 import type {
@@ -10,7 +16,15 @@ import type {
   UrlRequestOptions,
   UrlEndpoint,
   CacheConfig,
-} from "./types";
+  RetryConfig,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
+  MetricsAPI,
+} from "./types.js";
 
 const STATUS_TEXT: Record<number, string> = {
   200: "OK",
@@ -27,8 +41,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<
@@ -36,15 +52,27 @@ export interface JirenClientOptions<
     | 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;
+
+  /** Enable default browser emulation headers (default: true) */
+  defaultHeaders?: boolean;
 }
 
-/** Helper to extract keys from Warmup Config */
-export type ExtractWarmupKeys<
+// Helper to extract keys from Target Config
+export type ExtractTargetKeys<
   T extends readonly TargetUrlConfig[] | Record<string, UrlConfig>
 > = T extends readonly TargetUrlConfig[]
   ? T[number]["key"]
@@ -52,15 +80,14 @@ export type ExtractWarmupKeys<
   ? keyof T
   : never;
 
-/** Type-safe URL accessor - maps keys to UrlEndpoint objects */
 export type UrlAccessor<
   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 to define target URLs with type inference.
  */
 export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   urls: T
@@ -68,49 +95,122 @@ export function defineUrls<const T extends readonly TargetUrlConfig[]>(
   return urls;
 }
 
+// Cleanup native resources on GC
+const clientRegistry = new FinalizationRegistry<any>((ptr) => {
+  try {
+    lib.symbols.zclient_free(ptr);
+  } catch {
+    // Ignore cleanup errors
+  }
+});
+
 export class JirenClient<
   T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
     | readonly TargetUrlConfig[]
     | Record<string, UrlConfig>
-> {
-  private ptr: any = null; // Koffi pointer (Buffer or External)
+> implements Disposable
+{
+  private ptr: any = null; // Koffi pointer
   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;
+  private useDefaultHeaders: boolean = true;
+
+  // Pre-computed headers
+  private readonly defaultHeadersStr: string;
+  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",
+  };
 
   /** 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");
 
+    clientRegistry.register(this, this.ptr, this);
+
+    // Pre-computed default headers string
+    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");
+
     // Initialize cache
     this.cache = new ResponseCache(100);
 
+    // Initialize metrics
+    this.metricsCollector = new MetricsCollector();
+    this.metrics = this.metricsCollector;
+
+    // Performance mode (default: true for maximum speed)
+    this.performanceMode = options?.performanceMode ?? true;
+
+    // Default headers (default: true)
+    this.useDefaultHeaders = options?.defaultHeaders ?? 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 {
-            // TargetUrlConfig with key and optional cache
             const config = item as TargetUrlConfig;
             urls.push(config.url);
             this.urlMap.set(config.key, config.url);
 
-            // Store cache config
             if (config.cache) {
               const cacheConfig =
                 typeof config.cache === "boolean"
@@ -119,25 +219,23 @@ export class JirenClient<
               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);
             this.urlMap.set(key, urlConfig);
           } else {
-            // URL config object with cache
             urls.push(urlConfig.url);
             this.urlMap.set(key, urlConfig.url);
 
-            // Store cache config
             if (urlConfig.cache) {
               const cacheConfig =
                 typeof urlConfig.cache === "boolean"
@@ -146,8 +244,7 @@ export class JirenClient<
               this.cacheConfig.set(key, cacheConfig);
             }
 
-            // Store antibot config
-            if ((urlConfig as { antibot?: boolean }).antibot) {
+            if (urlConfig.antibot) {
               this.antibotConfig.set(key, true);
             }
           }
@@ -155,11 +252,13 @@ export class JirenClient<
       }
 
       if (urls.length > 0) {
-        this.warmup(urls);
+        this.targetsPromise = this.preconnect(urls).then(() => {
+          urls.forEach((url) => this.targetsComplete.add(url));
+          this.targetsPromise = null;
+        });
       }
 
-      // 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)
+      // Preload L2 disk cache entries into L1 memory
       for (const [key, config] of this.cacheConfig.entries()) {
         if (config.enabled) {
           const url = this.urlMap.get(key);
@@ -172,13 +271,39 @@ export class JirenClient<
 
     // Create proxy for type-safe URL access
     this.url = this.createUrlAccessor();
+
+    // Store global retry config
+    if (options?.retry) {
+      this.globalRetry =
+        typeof options.retry === "number"
+          ? { 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 warmup to complete
+   * Wait for lazy pre-connection to complete.
+   */
+  public async waitForTargets(): Promise<void> {
+    if (this.targetsPromise) await this.targetsPromise;
+  }
+
+  /**
+   * @deprecated Use waitForTargets() instead
    */
   public async waitForWarmup(): Promise<void> {
-    // Native warmup is synchronous, so this is effectively a no-op
+    return this.waitForTargets();
   }
 
   /**
@@ -207,58 +332,173 @@ export class JirenClient<
           get: async <R = any>(
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
-            const cacheConfig = self.cacheConfig.get(prop);
+            if (self.targetsPromise) {
+              await self.targetsPromise;
+            }
 
-            // Check if antibot is enabled for this URL (from warmup config or per-request)
+            const cacheConfig = self.cacheConfig.get(prop);
             const useAntibot =
               options?.antibot ?? self.antibotConfig.get(prop) ?? false;
 
+            // Fast path: no cache
+            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,
+              });
+            }
+
+            const startTime = performance.now();
+
+            // Try cache
             if (cacheConfig?.enabled) {
               const cached = self.cache.get(baseUrl, options?.path, options);
               if (cached) {
+                const responseTimeMs = performance.now() - startTime;
+                const cacheLayer = responseTimeMs < 0.5 ? "l1" : "l2";
+
+                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;
               }
             }
 
-            const response = await self.request<R>(
-              "GET",
-              buildUrl(options?.path),
-              null,
-              {
-                headers: options?.headers,
-                maxRedirects: options?.maxRedirects,
-                responseType: options?.responseType,
-                antibot: useAntibot,
+            // Deduplication
+            const dedupKey = `GET:${buildUrl(options?.path)}:${JSON.stringify(
+              options?.headers || {}
+            )}`;
+
+            if (self.inflightRequests.has(dedupKey)) {
+              const dedupeStart = performance.now();
+              const result = await self.inflightRequests.get(dedupKey);
+              const responseTimeMs = performance.now() - dedupeStart;
+
+              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,
+                });
               }
-            );
 
-            if (
-              cacheConfig?.enabled &&
-              typeof response === "object" &&
-              "status" in response
-            ) {
-              self.cache.set(
-                baseUrl,
-                response as JirenResponse,
-                cacheConfig.ttl,
-                options?.path,
-                options
-              );
+              return result;
             }
 
-            return response;
+            const requestPromise = (async () => {
+              try {
+                const response = await self.request<R>(
+                  "GET",
+                  buildUrl(options?.path),
+                  null,
+                  {
+                    headers: options?.headers,
+                    maxRedirects: options?.maxRedirects,
+                    responseType: options?.responseType,
+                    antibot: useAntibot,
+                  }
+                );
+
+                if (
+                  cacheConfig?.enabled &&
+                  typeof response === "object" &&
+                  "status" in response
+                ) {
+                  self.cache.set(
+                    baseUrl,
+                    response as JirenResponse,
+                    cacheConfig.ttl,
+                    options?.path,
+                    options
+                  );
+                }
+
+                const responseTimeMs = performance.now() - startTime;
+
+                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) {
+                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 {
+                self.inflightRequests.delete(dedupKey);
+              }
+            })();
+
+            self.inflightRequests.set(dedupKey, requestPromise);
+
+            return requestPromise;
           },
 
           post: async <R = any>(
-            body?: string | null,
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers, serializedBody } = self.prepareBody(
+              options?.body,
+              options?.headers
+            );
             return self.request<R>(
               "POST",
               buildUrl(options?.path),
-              body || null,
+              serializedBody,
               {
-                headers: options?.headers,
+                headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
               }
@@ -266,15 +506,18 @@ export class JirenClient<
           },
 
           put: async <R = any>(
-            body?: string | null,
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers, serializedBody } = self.prepareBody(
+              options?.body,
+              options?.headers
+            );
             return self.request<R>(
               "PUT",
               buildUrl(options?.path),
-              body || null,
+              serializedBody,
               {
-                headers: options?.headers,
+                headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
               }
@@ -282,15 +525,18 @@ export class JirenClient<
           },
 
           patch: async <R = any>(
-            body?: string | null,
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers, serializedBody } = self.prepareBody(
+              options?.body,
+              options?.headers
+            );
             return self.request<R>(
               "PATCH",
               buildUrl(options?.path),
-              body || null,
+              serializedBody,
               {
-                headers: options?.headers,
+                headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
               }
@@ -298,15 +544,18 @@ export class JirenClient<
           },
 
           delete: async <R = any>(
-            body?: string | null,
             options?: UrlRequestOptions
           ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers, serializedBody } = self.prepareBody(
+              options?.body,
+              options?.headers
+            );
             return self.request<R>(
               "DELETE",
               buildUrl(options?.path),
-              body || null,
+              serializedBody,
               {
-                headers: options?.headers,
+                headers,
                 maxRedirects: options?.maxRedirects,
                 responseType: options?.responseType,
               }
@@ -349,24 +598,55 @@ export class JirenClient<
     });
   }
 
+  /**
+   * Free the native client resources.
+   * Note: This is called automatically when the client is garbage collected,
+   * or you can use the `using` keyword for automatic cleanup in a scope.
+   */
   public close(): void {
     if (this.ptr) {
+      // Unregister from FinalizationRegistry since we're manually closing
+      clientRegistry.unregister(this);
       lib.symbols.zclient_free(this.ptr);
       this.ptr = null;
     }
   }
 
-  public async warmup(urls: string[]): Promise<void> {
+  /**
+   * Dispose method for the `using` keyword (ECMAScript Explicit Resource Management)
+   * @example
+   * ```typescript
+   * using client = new JirenClient({ targets: [...] });
+   * // client is automatically closed when the scope ends
+   * ```
+   */
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  /**
+   * Register interceptors dynamically.
+   */
+  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 in parallel.
+   */
+  public async preconnect(urls: string[]): Promise<void> {
     if (!this.ptr) throw new Error("Client is closed");
 
     await Promise.all(
       urls.map(
         (url) =>
           new Promise<void>((resolve) => {
-            const urlBuffer = Buffer.from(url + "\0");
-            lib.symbols.zclient_prefetch(this.ptr, url); // Koffi handles string auto-conversion if type is 'const char*' but Buffer is safer for null termination?
-            // Koffi: "const char *" expects a string or Buffer. String is null-terminated by Koffi.
-            // Using generic string.
+            lib.symbols.zclient_prefetch(this.ptr, url);
             resolve();
           })
       )
@@ -374,10 +654,108 @@ 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);
+  }
+
+  /**
+   * Pre-warm a single URL (establishes connection, caches DNS, TLS session)
+   * Call this before making requests to eliminate first-request latency.
+   */
+  public async prewarm(url: string): Promise<void> {
+    return this.preconnect([url]);
+  }
+
+  /**
+   * Execute multiple requests in a single pipelined batch (100k+ RPS)
+   * All requests must go to the same host.
+   * @param host - The host (e.g., "localhost")
+   * @param port - The port (e.g., 4000)
+   * @param requests - Array of { method, path } objects
+   * @returns Array of response bodies as strings
+   */
+  public batch(
+    host: string,
+    port: number,
+    requests: Array<{ method: string; path: string }>
+  ): string[] {
+    if (!this.ptr) throw new Error("Client is closed");
+    if (requests.length === 0) return [];
+
+    // Encode strings to buffers and create request structs
+    const requestStructs: any[] = [];
+    const buffers: Buffer[] = []; // Keep references to prevent GC
+
+    for (const req of requests) {
+      const methodBuf = Buffer.from(req.method + "\0");
+      const pathBuf = Buffer.from(req.path + "\0");
+      buffers.push(methodBuf, pathBuf);
+
+      requestStructs.push({
+        method_ptr: methodBuf,
+        method_len: req.method.length,
+        path_ptr: pathBuf,
+        path_len: req.path.length,
+      });
+    }
+
+    // Create array of structs
+    const requestArray = koffi.as(
+      requestStructs,
+      koffi.pointer(ZPipelineRequest)
+    );
+
+    // Call native pipelined batch
+    const resultPtr = lib.symbols.zclient_request_batch_http1(
+      this.ptr,
+      host,
+      port,
+      requestArray,
+      requests.length
+    );
+
+    if (!resultPtr) {
+      throw new Error("Batch request failed");
+    }
+
+    // Read result struct
+    const result = koffi.decode(resultPtr, ZPipelineResult);
+    const count = Number(result.count);
+
+    // Read response array
+    const responses: string[] = [];
+    const responseArray = koffi.decode(
+      result.responses,
+      koffi.array(ZPipelineResponse, count)
+    );
+
+    for (let i = 0; i < count; i++) {
+      const resp = responseArray[i];
+      const bodyLen = Number(resp.body_len);
+      if (bodyLen > 0) {
+        const bodyBuf = koffi.decode(
+          resp.body_ptr,
+          koffi.array("uint8_t", bodyLen)
+        );
+        responses.push(Buffer.from(bodyBuf).toString("utf-8"));
+      } else {
+        responses.push("");
+      }
+    }
+
+    // Free native memory
+    lib.symbols.zclient_pipeline_result_free(resultPtr);
+
+    return responses;
   }
 
   public async request<T = any>(
@@ -443,84 +821,133 @@ export class JirenClient<
       }
     }
 
-    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",
-    ];
-
-    for (const key of keys) {
-      if (finalHeaders[key]) {
-        orderedHeaders[key] = finalHeaders[key];
-        delete finalHeaders[key];
+    // Run interceptors
+    let ctx: InterceptorRequestContext = { method, url, headers, body };
+    if (this.requestInterceptors.length > 0) {
+      for (const interceptor of this.requestInterceptors) {
+        ctx = await interceptor(ctx);
       }
+      method = ctx.method;
+      url = ctx.url;
+      headers = ctx.headers;
+      body = ctx.body ?? null;
     }
-    for (const [key, value] of Object.entries(finalHeaders)) {
-      orderedHeaders[key] = value;
+
+    // Prepare headers
+    let headerStr: string;
+    const hasCustomHeaders = Object.keys(headers).length > 0;
+
+    if (hasCustomHeaders) {
+      const finalHeaders = this.useDefaultHeaders
+        ? { ...this.defaultHeaders, ...headers }
+        : headers;
+      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",
+      ];
+
+      for (const key of keys) {
+        if (finalHeaders[key]) {
+          orderedHeaders[key] = finalHeaders[key];
+          delete finalHeaders[key];
+        }
+      }
+
+      for (const [key, value] of Object.entries(finalHeaders)) {
+        orderedHeaders[key] = value;
+      }
+
+      headerStr = Object.entries(orderedHeaders)
+        .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
+        .join("\r\n");
+    } else {
+      headerStr = this.useDefaultHeaders ? this.defaultHeadersStr : "";
     }
 
-    const headerStr = Object.entries(orderedHeaders)
-      .map(([k, v]) => `${k.toLowerCase()}: ${v}`)
-      .join("\r\n");
+    // Retry logic
+    let retryConfig = this.globalRetry;
+    if (options && typeof options === "object" && "retry" in options) {
+      const userRetry = (options as any).retry;
+      if (typeof userRetry === "number") {
+        retryConfig = { count: userRetry, delay: 100, backoff: 2 };
+      } else if (typeof userRetry === "object") {
+        retryConfig = userRetry;
+      }
+    }
 
-    // Koffi auto-converts strings to const char *.
-    // Pass strings directly.
-    // For body and headers, empty string is fine if null.
-    // But native check might expect null pointer?
-    // zclient_request expects const char*. If passed null/undefined, Koffi might pass NULL?
-    // Let's pass null for explicit nulls.
+    let attempts = 0;
+    const maxAttempts = (retryConfig?.count || 0) + 1;
+    let currentDelay = retryConfig?.delay || 100;
+    const backoff = retryConfig?.backoff || 2;
+    let lastError: any;
+
+    while (attempts < maxAttempts) {
+      attempts++;
+      try {
+        const respPtr = lib.symbols.zclient_request(
+          this.ptr,
+          method,
+          url,
+          headerStr.length > 0 ? headerStr : null,
+          body || null,
+          maxRedirects,
+          antibot
+        );
+
+        if (!respPtr) {
+          throw new Error("Native request failed (returned null pointer)");
+        }
 
-    const respPtr = lib.symbols.zclient_request(
-      this.ptr,
-      method,
-      url,
-      headerStr.length > 0 ? headerStr : null,
-      body || null,
-      maxRedirects,
-      antibot
-    );
+        const response = this.parseResponse<T>(respPtr, url);
+
+        // Run response interceptors
+        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 response = this.parseResponse<T>(respPtr, url);
+        if (responseType) {
+          if (responseType === "json") return finalResponse.body.json();
+          if (responseType === "text") return finalResponse.body.text();
+          if (responseType === "arraybuffer")
+            return finalResponse.body.arrayBuffer();
+          if (responseType === "blob") return finalResponse.body.blob();
+        }
 
-    if (responseType) {
-      if (responseType === "json") return response.body.json();
-      if (responseType === "text") return response.body.text();
-      if (responseType === "arraybuffer") return response.body.arrayBuffer();
-      if (responseType === "blob") return response.body.blob();
+        return finalResponse;
+      } catch (err) {
+        if (this.errorInterceptors.length > 0) {
+          for (const interceptor of this.errorInterceptors) {
+            await interceptor(err as Error, ctx);
+          }
+        }
+        lastError = err;
+        if (attempts < maxAttempts) {
+          await this.waitFor(currentDelay);
+          currentDelay *= backoff;
+        }
+      }
     }
 
-    return response;
+    throw lastError || new Error("Request failed after retries");
   }
 
   private parseResponse<T = any>(respPtr: any, url: string): JirenResponse<T> {
@@ -540,8 +967,6 @@ export class JirenClient<
       if (headersLen > 0) {
         const rawHeadersPtr = lib.symbols.zclient_response_headers(respPtr);
         if (rawHeadersPtr) {
-          // Copy headers to JS memory
-          // Koffi decode to buffer: koffi.decode(ptr, "uint8_t", len)
           const raw = Buffer.from(
             koffi.decode(rawHeadersPtr, "uint8_t", headersLen)
           );
@@ -565,15 +990,12 @@ export class JirenClient<
 
       let buffer: Buffer = Buffer.alloc(0);
       if (len > 0 && bodyPtr) {
-        // Copy body content
         buffer = Buffer.from(koffi.decode(bodyPtr, "uint8_t", len));
 
-        // Handle GZIP compression - search for magic bytes in first 16 bytes
-        // (handles chunked encoding or other framing that may add prefix bytes)
+        // Handle GZIP
         const contentEncoding = headersProxy["content-encoding"]?.toLowerCase();
         let gzipOffset = -1;
 
-        // 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;
@@ -583,16 +1005,10 @@ export class JirenClient<
 
         if (contentEncoding === "gzip" || gzipOffset >= 0) {
           try {
-            // 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);
+            // Keep original buffer
           }
         }
       }
@@ -643,6 +1059,33 @@ export class JirenClient<
       lib.symbols.zclient_response_free(respPtr);
     }
   }
+
+  /**
+   * Helper to prepare body and headers for requests.
+   */
+  private prepareBody(
+    body: string | object | null | undefined,
+    userHeaders?: Record<string, string>
+  ): { headers: Record<string, string>; serializedBody: string | null } {
+    let serializedBody: string | null = null;
+    const headers = { ...userHeaders };
+
+    if (body !== null && body !== undefined) {
+      if (typeof body === "object") {
+        serializedBody = JSON.stringify(body);
+        const hasContentType = Object.keys(headers).some(
+          (k) => k.toLowerCase() === "content-type"
+        );
+        if (!hasContentType) {
+          headers["Content-Type"] = "application/json";
+        }
+      } else {
+        serializedBody = String(body);
+      }
+    }
+
+    return { headers, serializedBody };
+  }
 }
 
 class NativeHeaders {