jiren 1.2.5 → 1.2.7

package/components/client-node-native.ts

@@ -0,0 +1,655 @@
+import { nativeLib as lib } from "./native-node";
+import { ResponseCache } from "./cache";
+import koffi from "koffi";
+import zlib from "zlib";
+import type {
+  RequestOptions,
+  JirenResponse,
+  JirenResponseBody,
+  WarmupUrlConfig,
+  UrlRequestOptions,
+  UrlEndpoint,
+  CacheConfig,
+} from "./types";
+
+const STATUS_TEXT: Record<number, string> = {
+  200: "OK",
+  201: "Created",
+  204: "No Content",
+  301: "Moved Permanently",
+  302: "Found",
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+};
+
+/** URL configuration with optional cache */
+export type UrlConfig = string | { url: string; cache?: boolean | CacheConfig };
+
+/** Options for JirenClient constructor */
+export interface JirenClientOptions<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, UrlConfig>
+> {
+  /** URLs to warmup on client creation (pre-connect + handshake) */
+  warmup?: string[] | T;
+
+  /** Enable benchmark mode (Force HTTP/2, disable probing) */
+  benchmark?: boolean;
+}
+
+/** Helper to extract keys from Warmup Config */
+export type ExtractWarmupKeys<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
+> = T extends readonly WarmupUrlConfig[]
+  ? T[number]["key"]
+  : T extends Record<string, UrlConfig>
+  ? keyof T
+  : never;
+
+/** Type-safe URL accessor - maps keys to UrlEndpoint objects */
+export type UrlAccessor<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig>
+> = {
+  [K in ExtractWarmupKeys<T>]: UrlEndpoint;
+};
+
+/**
+ * Helper function to define warmup URLs with type inference.
+ */
+export function defineUrls<const T extends readonly WarmupUrlConfig[]>(
+  urls: T
+): T {
+  return urls;
+}
+
+export class JirenClient<
+  T extends readonly WarmupUrlConfig[] | Record<string, UrlConfig> =
+    | readonly WarmupUrlConfig[]
+    | Record<string, UrlConfig>
+> {
+  private ptr: any = null; // Koffi pointer (Buffer or External)
+  private urlMap: Map<string, string> = new Map();
+  private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
+    new Map();
+  private cache: ResponseCache;
+
+  /** Type-safe URL accessor for warmed-up URLs */
+  public readonly url: UrlAccessor<T>;
+
+  constructor(options?: JirenClientOptions<T>) {
+    this.ptr = lib.symbols.zclient_new();
+    if (!this.ptr) throw new Error("Failed to create native client instance");
+
+    // Initialize cache
+    this.cache = new ResponseCache(100);
+
+    // Enable benchmark mode if requested
+    if (options?.benchmark) {
+      lib.symbols.zclient_set_benchmark_mode(this.ptr, true);
+    }
+
+    // Process warmup URLs
+    if (options?.warmup) {
+      const urls: string[] = [];
+      const warmup = options.warmup;
+
+      if (Array.isArray(warmup)) {
+        for (const item of warmup) {
+          if (typeof item === "string") {
+            urls.push(item);
+          } else {
+            // WarmupUrlConfig with key and optional cache
+            const config = item as WarmupUrlConfig;
+            urls.push(config.url);
+            this.urlMap.set(config.key, config.url);
+
+            // Store cache config
+            if (config.cache) {
+              const cacheConfig =
+                typeof config.cache === "boolean"
+                  ? { enabled: true, ttl: 60000 }
+                  : { enabled: true, ttl: config.cache.ttl || 60000 };
+              this.cacheConfig.set(config.key, cacheConfig);
+            }
+          }
+        }
+      } else {
+        // Record<string, UrlConfig>
+        for (const [key, urlConfig] of Object.entries(warmup)) {
+          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"
+                  ? { enabled: true, ttl: 60000 }
+                  : { enabled: true, ttl: urlConfig.cache.ttl || 60000 };
+              this.cacheConfig.set(key, cacheConfig);
+            }
+          }
+        }
+      }
+
+      if (urls.length > 0) {
+        this.warmup(urls);
+      }
+    }
+
+    // Create proxy for type-safe URL access
+    this.url = this.createUrlAccessor();
+  }
+
+  /**
+   * Creates a proxy-based URL accessor for type-safe access.
+   */
+  private createUrlAccessor(): UrlAccessor<T> {
+    const self = this;
+
+    return new Proxy({} as UrlAccessor<T>, {
+      get(_target, prop: string) {
+        const baseUrl = self.urlMap.get(prop);
+        if (!baseUrl) {
+          throw new Error(
+            `URL key "${prop}" not found. Available keys: ${Array.from(
+              self.urlMap.keys()
+            ).join(", ")}`
+          );
+        }
+
+        const buildUrl = (path?: string) =>
+          path
+            ? `${baseUrl.replace(/\/$/, "")}/${path.replace(/^\//, "")}`
+            : baseUrl;
+
+        return {
+          get: async <R = any>(
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const cacheConfig = self.cacheConfig.get(prop);
+
+            if (cacheConfig?.enabled) {
+              const cached = self.cache.get(baseUrl, options?.path, options);
+              if (cached) {
+                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: options?.antibot,
+              }
+            );
+
+            if (
+              cacheConfig?.enabled &&
+              typeof response === "object" &&
+              "status" in response
+            ) {
+              self.cache.set(
+                baseUrl,
+                response as JirenResponse,
+                cacheConfig.ttl,
+                options?.path,
+                options
+              );
+            }
+
+            return response;
+          },
+
+          post: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "POST",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          put: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PUT",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          patch: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "PATCH",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          delete: async <R = any>(
+            body?: string | null,
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self.request<R>(
+              "DELETE",
+              buildUrl(options?.path),
+              body || null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+              }
+            );
+          },
+
+          head: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("HEAD", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+
+          options: async (
+            options?: UrlRequestOptions
+          ): Promise<JirenResponse<any>> => {
+            return self.request("OPTIONS", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+            });
+          },
+
+          prefetch: async (options?: UrlRequestOptions): Promise<void> => {
+            self.cache.clear(baseUrl);
+            const cacheConfig = self.cacheConfig.get(prop);
+            if (cacheConfig?.enabled) {
+              await self.request("GET", buildUrl(options?.path), null, {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                antibot: options?.antibot,
+              });
+            }
+          },
+        } as UrlEndpoint;
+      },
+    });
+  }
+
+  public close(): void {
+    if (this.ptr) {
+      lib.symbols.zclient_free(this.ptr);
+      this.ptr = null;
+    }
+  }
+
+  public async warmup(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.
+            resolve();
+          })
+      )
+    );
+  }
+
+  /**
+   * @deprecated Use warmup() instead
+   */
+  public prefetch(urls: string[]): void {
+    this.warmup(urls);
+  }
+
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "json" }
+  ): Promise<T>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "text" }
+  ): Promise<string>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "arraybuffer" }
+  ): Promise<ArrayBuffer>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "blob" }
+  ): Promise<Blob>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions
+  ): Promise<JirenResponse<T>>;
+  public async request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions | Record<string, string> | null
+  ): Promise<JirenResponse<T> | T | string | ArrayBuffer | Blob> {
+    if (!this.ptr) throw new Error("Client is closed");
+
+    // Normalize options
+    let headers: Record<string, string> = {};
+    let maxRedirects = 5;
+    let responseType: RequestOptions["responseType"] | undefined;
+    let antibot = false;
+
+    if (options) {
+      if (
+        "maxRedirects" in options ||
+        "headers" in options ||
+        "responseType" in options ||
+        "method" in options ||
+        "timeout" in options ||
+        "antibot" in options
+      ) {
+        const opts = options as RequestOptions;
+        if (opts.headers) headers = opts.headers;
+        if (opts.maxRedirects !== undefined) maxRedirects = opts.maxRedirects;
+        if (opts.responseType) responseType = opts.responseType;
+        if (opts.antibot !== undefined) antibot = opts.antibot;
+      } else {
+        headers = options as Record<string, string>;
+      }
+    }
+
+    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];
+      }
+    }
+    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");
+
+    // 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.
+
+    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);
+
+    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 response;
+  }
+
+  private parseResponse<T = any>(respPtr: any, url: string): JirenResponse<T> {
+    if (!respPtr)
+      throw new Error("Native request failed (returned null pointer)");
+
+    try {
+      const status = lib.symbols.zclient_response_status(respPtr);
+      const len = Number(lib.symbols.zclient_response_body_len(respPtr));
+      const bodyPtr = lib.symbols.zclient_response_body(respPtr);
+
+      const headersLen = Number(
+        lib.symbols.zclient_response_headers_len(respPtr)
+      );
+      let headersObj: Record<string, string> | NativeHeaders = {};
+
+      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)
+          );
+          headersObj = new NativeHeaders(raw);
+        }
+      }
+
+      const headersProxy = 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: Buffer = Buffer.alloc(0);
+      if (len > 0 && bodyPtr) {
+        // Copy body content
+        buffer = Buffer.from(koffi.decode(bodyPtr, "uint8_t", len));
+
+        // Handle GZIP compression
+        const contentEncoding = headersProxy["content-encoding"]?.toLowerCase();
+
+        // DEBUG LOGS
+        if (len > 0) {
+          console.log(`[Jiren] Body len: ${len}, Encoding: ${contentEncoding}`);
+          if (buffer.length > 2) {
+            console.log(
+              `[Jiren] Bytes: 0x${buffer[0]?.toString(
+                16
+              )} 0x${buffer[1]?.toString(16)} 0x${buffer[2]?.toString(16)}`
+            );
+          }
+        }
+
+        if (
+          contentEncoding === "gzip" ||
+          (buffer.length > 2 && buffer[0] === 0x1f && buffer[1] === 0x8b)
+        ) {
+          try {
+            console.log("[Jiren] Attempting gunzip...");
+            buffer = zlib.gunzipSync(buffer);
+            console.log("[Jiren] Gunzip success!");
+          } catch (e) {
+            console.warn("Failed to gunzip response body:", e);
+          }
+        }
+      }
+
+      let bodyUsed = false;
+      const consumeBody = () => {
+        bodyUsed = true;
+      };
+
+      const bodyObj: JirenResponseBody<T> = {
+        bodyUsed: false,
+        arrayBuffer: async () => {
+          consumeBody();
+          return buffer.buffer.slice(
+            buffer.byteOffset,
+            buffer.byteOffset + buffer.byteLength
+          ) as ArrayBuffer;
+        },
+        blob: async () => {
+          consumeBody();
+          return new Blob([buffer as any]);
+        },
+        text: async () => {
+          consumeBody();
+          return buffer.toString("utf-8");
+        },
+        json: async <R = T>(): Promise<R> => {
+          consumeBody();
+          return JSON.parse(buffer.toString("utf-8"));
+        },
+      };
+
+      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_free(respPtr);
+    }
+  }
+}
+
+class NativeHeaders {
+  private raw: Buffer;
+  private len: number;
+  private cache = new Map<string, string>();
+  private parsed = false;
+
+  constructor(raw: Buffer) {
+    this.raw = raw;
+    this.len = raw.length;
+  }
+
+  private ensureParsed() {
+    if (this.parsed) return;
+    try {
+      const text = this.raw.toString("utf-8");
+      const lines = text.split("\r\n");
+      for (const line of lines) {
+        if (!line) continue;
+        const colon = line.indexOf(":");
+        if (colon === -1) continue;
+        const key = line.substring(0, colon).trim().toLowerCase();
+        const val = line.substring(colon + 1).trim();
+        this.cache.set(key, val);
+      }
+    } catch (e) {
+      // Ignore parsing errors
+    }
+    this.parsed = true;
+  }
+
+  get(name: string): string | null {
+    const target = name.toLowerCase();
+    this.ensureParsed();
+    return this.cache.get(target) || null;
+  }
+
+  toJSON(): Record<string, string> {
+    this.ensureParsed();
+    return Object.fromEntries(this.cache);
+  }
+}

package/components/client.ts

@@ -9,6 +9,7 @@ import type {
   UrlRequestOptions,
   UrlEndpoint,
   CacheConfig,
+  RetryConfig,
 } from "./types";
 
 const STATUS_TEXT: Record<number, string> = {
@@ -40,6 +41,9 @@ export interface JirenClientOptions<
 
   /** Enable benchmark mode (Force HTTP/2, disable probing) */
   benchmark?: boolean;
+
+  /** Global retry configuration */
+  retry?: number | RetryConfig;
 }
 
 /** Helper to extract keys from Warmup Config */
@@ -93,6 +97,8 @@ export class JirenClient<
   private cacheConfig: Map<string, { enabled: boolean; ttl: number }> =
     new Map();
   private cache: ResponseCache;
+  private inflightRequests: Map<string, Promise<any>> = new Map();
+  private globalRetry?: RetryConfig;
 
   /** Type-safe URL accessor for warmed-up URLs */
   public readonly url: UrlAccessor<T>;
@@ -165,6 +171,18 @@ 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;
+    }
+  }
+
+  private async waitFor(ms: number) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
   /**
@@ -206,47 +224,74 @@ export class JirenClient<
               }
             }
 
-            // Make the request
-            const response = await self.request<R>(
-              "GET",
-              buildUrl(options?.path),
-              null,
-              {
-                headers: options?.headers,
-                maxRedirects: options?.maxRedirects,
-                responseType: options?.responseType,
-                antibot: options?.antibot,
-              }
-            );
+            // ** Deduplication Logic **
+            // Create a unique key for this request based on URL and critical options
+            const dedupKey = `GET:${buildUrl(options?.path)}:${JSON.stringify(
+              options?.headers || {}
+            )}`;
 
-            // Store in cache if enabled
-            if (
-              cacheConfig?.enabled &&
-              typeof response === "object" &&
-              "status" in response
-            ) {
-              self.cache.set(
-                baseUrl,
-                response as JirenResponse,
-                cacheConfig.ttl,
-                options?.path,
-                options
-              );
+            // Check if there is already an identical request in flight
+            if (self.inflightRequests.has(dedupKey)) {
+              return self.inflightRequests.get(dedupKey);
             }
 
-            return response;
+            // Create the request promise
+            const requestPromise = (async () => {
+              try {
+                // Make the request
+                const response = await self.request<R>(
+                  "GET",
+                  buildUrl(options?.path),
+                  null,
+                  {
+                    headers: options?.headers,
+                    maxRedirects: options?.maxRedirects,
+                    responseType: options?.responseType,
+                    antibot: options?.antibot,
+                  }
+                );
+
+                // Store in cache if enabled
+                if (
+                  cacheConfig?.enabled &&
+                  typeof response === "object" &&
+                  "status" in response
+                ) {
+                  self.cache.set(
+                    baseUrl,
+                    response as JirenResponse,
+                    cacheConfig.ttl,
+                    options?.path,
+                    options
+                  );
+                }
+
+                return response;
+              } finally {
+                // Remove from inflight map when done (success or failure)
+                self.inflightRequests.delete(dedupKey);
+              }
+            })();
+
+            // Store the promise in the map
+            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,
               }
@@ -254,15 +299,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,
               }
@@ -270,15 +318,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,
               }
@@ -286,15 +337,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,
               }
@@ -523,27 +577,74 @@ export class JirenClient<
       headersBuffer = Buffer.from(headerStr + "\0");
     }
 
-    const respPtr = lib.symbols.zclient_request(
-      this.ptr,
-      methodBuffer,
-      urlBuffer,
-      headersBuffer,
-      bodyBuffer,
-      maxRedirects,
-      antibot
-    );
+    // Determine retry configuration
+    let retryConfig = this.globalRetry;
+    // Check if options is RequestOptions (has 'retry' property and is not just a header map)
+    // We already normalized this earlier, but let's be safe.
+    // If it has 'responseType', 'method', etc., it's RequestOptions.
+    // Simpler: Just check if 'retry' is number or object.
+    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;
+      }
+    }
 
-    const response = this.parseResponse<T>(respPtr, url);
+    let attempts = 0;
+    // Default to 1 attempt (0 retries) if no config
+    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,
+          methodBuffer,
+          urlBuffer,
+          headersBuffer,
+          bodyBuffer,
+          maxRedirects,
+          antibot
+        );
+
+        if (!respPtr) {
+          throw new Error("Native request failed (returned null pointer)");
+        }
 
-    // Auto-parse if requested
-    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();
+        const response = this.parseResponse<T>(respPtr, url);
+
+        // Optional: Retry on specific status codes (e.g., 500, 502, 503, 504)
+        // For now, we only retry on actual exceptions/network failures (null ptr)
+        // or if we decide to throw on 5xx here.
+        // Let's stick to "Network Failure" retries for now as per plan.
+
+        // Auto-parse if requested
+        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 response;
+      } catch (err) {
+        lastError = err;
+        if (attempts < maxAttempts) {
+          // Wait before retrying
+          await this.waitFor(currentDelay);
+          currentDelay *= backoff;
+        }
+      }
     }
 
-    return response;
+    throw lastError || new Error("Request failed after retries");
   }
 
   private parseResponse<T = any>(
@@ -652,6 +753,35 @@ export class JirenClient<
       lib.symbols.zclient_response_free(respPtr);
     }
   }
+
+  /**
+   * Helper to prepare body and headers for requests.
+   * Handles JSON stringification and Content-Type header.
+   */
+  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);
+        // Add Content-Type if not present (case-insensitive check)
+        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 {

package/components/index.ts

@@ -18,6 +18,8 @@ export type {
   WarmupUrlConfig,
   UrlRequestOptions,
   UrlEndpoint,
+  JirenResponse,
+  JirenResponseBody,
 } from "./types";
 
 // Remove broken exports

package/components/native-node.ts

@@ -0,0 +1,93 @@
+import koffi from "koffi";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Determine library extension based on platform
+const platform = process.platform;
+let suffix = "so";
+if (platform === "darwin") {
+  suffix = "dylib";
+} else if (platform === "win32") {
+  suffix = "dll";
+}
+
+// Resolve library path relative to this module
+// native.ts uses join(import.meta.dir, `../lib/libhttpclient.${suffix}`)
+const libPath = path.join(__dirname, `../lib/libhttpclient.${suffix}`);
+
+// Load the library
+// koffi.load returns an object where we can register functions
+const lib = koffi.load(libPath);
+
+// Define types if needed
+// koffi handles void* as 'void*' or 'ptr'
+
+export const symbols = {
+  zclient_new: lib.func("zclient_new", "void *", []),
+  zclient_free: lib.func("zclient_free", "void", ["void *"]),
+  zclient_get: lib.func("zclient_get", "void *", ["void *", "const char *"]),
+  zclient_post: lib.func("zclient_post", "void *", [
+    "void *",
+    "const char *",
+    "const char *",
+  ]),
+  zclient_request: lib.func("zclient_request", "void *", [
+    "void *", // ptr
+    "const char *", // method
+    "const char *", // url
+    "const char *", // headers
+    "const char *", // body
+    "uint8_t", // max_redirects
+    "bool", // antibot
+  ]),
+  zclient_prefetch: lib.func("zclient_prefetch", "void", [
+    "void *",
+    "const char *",
+  ]),
+  zclient_response_status: lib.func("zclient_response_status", "uint16_t", [
+    "void *",
+  ]),
+  zclient_response_body: lib.func("zclient_response_body", "void *", [
+    "void *",
+  ]),
+  zclient_response_body_len: lib.func("zclient_response_body_len", "uint64_t", [
+    "void *",
+  ]),
+  zclient_response_headers: lib.func("zclient_response_headers", "void *", [
+    "void *",
+  ]),
+  zclient_response_headers_len: lib.func(
+    "zclient_response_headers_len",
+    "uint64_t",
+    ["void *"]
+  ),
+  zclient_response_parse_header_offsets: lib.func(
+    "zclient_response_parse_header_offsets",
+    "void *",
+    ["void *"]
+  ),
+  zclient_header_offsets_free: lib.func("zclient_header_offsets_free", "void", [
+    "void *",
+  ]),
+  z_find_header_value: lib.func("z_find_header_value", "void *", [
+    "void *", // raw headers ptr
+    "uint64_t", // len
+    "const char *", // key
+  ]),
+  zclient_header_value_free: lib.func("zclient_header_value_free", "void", [
+    "void *",
+  ]),
+  zclient_response_free: lib.func("zclient_response_free", "void", ["void *"]),
+  zclient_set_benchmark_mode: lib.func("zclient_set_benchmark_mode", "void", [
+    "void *",
+    "bool",
+  ]),
+};
+
+// Export a wrapper that matches structure of bun:ffi lib
+export const nativeLib = {
+  symbols,
+};

package/components/types.ts

@@ -108,18 +108,32 @@ export interface CacheConfig {
   maxSize?: number;
 }
 
+/** Configuration for automatic request retries */
+export interface RetryConfig {
+  /** Number of retry attempts (default: 0) */
+  count?: number;
+  /** Initial delay in milliseconds before first retry (default: 100) */
+  delay?: number;
+  /** Backoff multiplier for subsequent retries (2 = double delay each time) (default: 2) */
+  backoff?: number;
+}
+
 /** Options for URL endpoint requests */
 export interface UrlRequestOptions {
   /** Request headers */
   headers?: Record<string, string>;
   /** Path to append to the base URL */
   path?: string;
+  /** Request body (for POST, PUT, PATCH, DELETE) - Auto-stringifies objects */
+  body?: string | object | null;
   /** Maximum number of redirects to follow */
   maxRedirects?: number;
   /** Automatically parse response body */
   responseType?: "json" | "text" | "arraybuffer" | "blob";
   /** Enable anti-bot protection (using curl-impersonate) */
   antibot?: boolean;
+  /** Retry configuration for this request */
+  retry?: number | RetryConfig;
 }
 
 /** Interface for a URL endpoint with HTTP method helpers */
@@ -134,42 +148,26 @@ export interface UrlEndpoint {
   ): Promise<string>;
 
   /** POST request */
+  post<T = any>(options?: UrlRequestOptions): Promise<JirenResponse<T>>;
   post<T = any>(
-    body?: string | null,
-    options?: UrlRequestOptions
-  ): Promise<JirenResponse<T>>;
-  post<T = any>(
-    body?: string | null,
     options?: UrlRequestOptions & { responseType: "json" }
   ): Promise<T>;
 
   /** PUT request */
+  put<T = any>(options?: UrlRequestOptions): Promise<JirenResponse<T>>;
   put<T = any>(
-    body?: string | null,
-    options?: UrlRequestOptions
-  ): Promise<JirenResponse<T>>;
-  put<T = any>(
-    body?: string | null,
     options?: UrlRequestOptions & { responseType: "json" }
   ): Promise<T>;
 
   /** PATCH request */
+  patch<T = any>(options?: UrlRequestOptions): Promise<JirenResponse<T>>;
   patch<T = any>(
-    body?: string | null,
-    options?: UrlRequestOptions
-  ): Promise<JirenResponse<T>>;
-  patch<T = any>(
-    body?: string | null,
     options?: UrlRequestOptions & { responseType: "json" }
   ): Promise<T>;
 
   /** DELETE request */
+  delete<T = any>(options?: UrlRequestOptions): Promise<JirenResponse<T>>;
   delete<T = any>(
-    body?: string | null,
-    options?: UrlRequestOptions
-  ): Promise<JirenResponse<T>>;
-  delete<T = any>(
-    body?: string | null,
     options?: UrlRequestOptions & { responseType: "json" }
   ): Promise<T>;
 

package/index-node.ts

@@ -12,7 +12,7 @@ export {
   JirenClient,
   type JirenClientOptions,
   type UrlAccessor,
-} from "./components/client-node";
+} from "./components/client-node-native";
 
 // Types
 export * from "./types";

package/index.ts

@@ -23,7 +23,11 @@
  */
 
 // Main client
-export { JirenClient } from "./components";
+export {
+  JirenClient,
+  type JirenResponse,
+  type JirenResponseBody,
+} from "./components";
 
 // Types
 export * from "./types";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiren",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "author": "",
   "main": "index.ts",
   "module": "index.ts",
@@ -47,5 +47,8 @@
       "default": "./index-node.ts"
     },
     "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "koffi": "^2.14.1"
   }
 }