jiren 3.3.0 → 3.5.0

package/components/client-node-fetch.ts

@@ -0,0 +1,953 @@
+import { MetricsCollector } from "./metrics.js";
+import type {
+  RequestOptions,
+  JirenResponse,
+  JirenResponseBody,
+  TargetUrlConfig,
+  UrlRequestOptions,
+  UrlEndpoint,
+  RetryConfig,
+  Interceptors,
+  RequestInterceptor,
+  ResponseInterceptor,
+  ErrorInterceptor,
+  InterceptorRequestContext,
+  InterceptorResponseContext,
+  MetricsAPI,
+  ProgressRequestOptions,
+  UrlConfig,
+  JirenClientOptions,
+  UrlAccessor,
+} from "./types.js";
+
+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",
+};
+
+const RAW_BODY = Symbol("jiren.raw.body");
+let didWarnFallback = false;
+
+interface InternalResponse<T = any> extends JirenResponse<T> {
+  [RAW_BODY]: Buffer;
+}
+
+interface CachedResponse {
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  url: string;
+  ok: boolean;
+  redirected: boolean;
+  type: "basic" | "cors" | "default" | "error" | "opaque" | "opaqueredirect";
+  body: Buffer;
+  expiresAt: number;
+}
+
+export function defineUrls<const T extends readonly TargetUrlConfig[]>(
+  urls: T,
+): T {
+  return urls;
+}
+
+export class JirenClient<
+  T extends readonly TargetUrlConfig[] | Record<string, UrlConfig> =
+    | readonly TargetUrlConfig[]
+    | Record<string, UrlConfig>,
+> implements Disposable {
+  private closed = false;
+  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 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 = false;
+  private useDefaultHeaders = true;
+  private cacheStore: Map<string, CachedResponse> = new Map();
+
+  private readonly defaultHeaders: Record<string, string> = {
+    "user-agent":
+      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) 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": '"Windows"',
+    "sec-fetch-dest": "document",
+    "sec-fetch-mode": "navigate",
+    "sec-fetch-site": "none",
+    "sec-fetch-user": "?1",
+    "upgrade-insecure-requests": "1",
+  };
+
+  public readonly url: UrlAccessor<T>;
+
+  private metricsCollector: MetricsCollector;
+  public readonly metrics: MetricsAPI;
+
+  constructor(options?: JirenClientOptions<T>) {
+    if (!didWarnFallback) {
+      didWarnFallback = true;
+      console.warn(
+        "[Jiren] Using fetch fallback mode (reduced performance/features).",
+      );
+    }
+
+    this.metricsCollector = new MetricsCollector();
+    this.metrics = this.metricsCollector;
+
+    this.performanceMode = options?.performanceMode ?? false;
+    this.useDefaultHeaders = options?.defaultHeaders ?? true;
+
+    const targets = options?.urls;
+    if (targets) {
+      const urls: string[] = [];
+
+      if (Array.isArray(targets)) {
+        for (const item of targets) {
+          if (typeof item === "string") {
+            urls.push(item);
+          } else {
+            const config = item as TargetUrlConfig;
+            urls.push(config.url);
+            this.urlMap.set(config.key, config.url);
+
+            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);
+            }
+
+            if (config.antibot) {
+              this.antibotConfig.set(config.key, true);
+            }
+          }
+        }
+      } else {
+        for (const [key, urlConfig] of Object.entries(targets) as [
+          string,
+          UrlConfig,
+        ][]) {
+          if (typeof urlConfig === "string") {
+            urls.push(urlConfig);
+            this.urlMap.set(key, urlConfig);
+          } else {
+            urls.push(urlConfig.url);
+            this.urlMap.set(key, urlConfig.url);
+
+            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 (urlConfig.antibot) {
+              this.antibotConfig.set(key, true);
+            }
+          }
+        }
+      }
+
+      if (urls.length > 0 && options?.preconnect !== false) {
+        this.targetsPromise = this.preconnect(urls).then(() => {
+          urls.forEach((url) => this.targetsComplete.add(url));
+          this.targetsPromise = null;
+        });
+      }
+    }
+
+    this.url = this.createUrlAccessor();
+
+    if (options?.retry) {
+      this.globalRetry =
+        typeof options.retry === "number"
+          ? { count: options.retry, delay: 100, backoff: 2 }
+          : options.retry;
+    }
+
+    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));
+  }
+
+  public async waitForTargets(): Promise<void> {
+    if (this.targetsPromise) await this.targetsPromise;
+  }
+
+  public async waitForWarmup(): Promise<void> {
+    return this.waitForTargets();
+  }
+
+  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> => {
+            if (self.targetsPromise) {
+              await self.targetsPromise;
+            }
+
+            const cacheConfig = self.cacheConfig.get(prop);
+            const useAntibot =
+              options?.antibot ?? self.antibotConfig.get(prop) ?? false;
+            const url = buildUrl(options?.path);
+            const requestKey = self.getRequestKey(
+              "GET",
+              url,
+              options?.headers,
+              null,
+            );
+
+            if (cacheConfig?.enabled) {
+              const cached = self.getCachedResponse(requestKey);
+              if (cached) return cached as JirenResponse<R>;
+            }
+
+            if (self.inflightRequests.has(requestKey)) {
+              return self.inflightRequests.get(requestKey)!;
+            }
+
+            const startTime = performance.now();
+            const requestPromise = (async () => {
+              try {
+                const response = await self._request<R>("GET", url, null, {
+                  headers: options?.headers,
+                  maxRedirects: options?.maxRedirects,
+                  responseType: options?.responseType,
+                  antibot: useAntibot,
+                  timeout: options?.timeout,
+                  retry: options?.retry,
+                });
+
+                if (
+                  cacheConfig?.enabled &&
+                  self.isJirenResponse(response) &&
+                  !options?.responseType
+                ) {
+                  self.setCachedResponse(requestKey, response, cacheConfig.ttl);
+                }
+
+                if (!self.performanceMode && self.isJirenResponse(response)) {
+                  const raw = response[RAW_BODY];
+                  self.metricsCollector.recordRequest(prop, {
+                    startTime,
+                    responseTimeMs: performance.now() - startTime,
+                    status: response.status,
+                    success: response.ok,
+                    bytesSent: 0,
+                    bytesReceived: raw.length,
+                    cacheHit: false,
+                    dedupeHit: false,
+                  });
+                }
+
+                return response;
+              } catch (error) {
+                if (!self.performanceMode) {
+                  self.metricsCollector.recordRequest(prop, {
+                    startTime,
+                    responseTimeMs: performance.now() - startTime,
+                    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(requestKey);
+              }
+            })();
+
+            self.inflightRequests.set(requestKey, requestPromise);
+            return requestPromise;
+          },
+
+          post: async <R = any>(
+            body?: any,
+            options?: UrlRequestOptions & { responseType?: "json" },
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers: preparedHeaders, serializedBody } =
+              self.prepareBody(body, options?.headers);
+            return self._request<R>(
+              "POST",
+              buildUrl(options?.path),
+              serializedBody,
+              {
+                headers: preparedHeaders,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+                timeout: options?.timeout,
+                retry: options?.retry,
+              },
+            );
+          },
+
+          put: async <R = any>(
+            body?: any,
+            options?: UrlRequestOptions & { responseType?: "json" },
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers: preparedHeaders, serializedBody } =
+              self.prepareBody(body, options?.headers);
+            return self._request<R>(
+              "PUT",
+              buildUrl(options?.path),
+              serializedBody,
+              {
+                headers: preparedHeaders,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+                timeout: options?.timeout,
+                retry: options?.retry,
+              },
+            );
+          },
+
+          patch: async <R = any>(
+            body?: any,
+            options?: UrlRequestOptions & { responseType?: "json" },
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers: preparedHeaders, serializedBody } =
+              self.prepareBody(body, options?.headers);
+            return self._request<R>(
+              "PATCH",
+              buildUrl(options?.path),
+              serializedBody,
+              {
+                headers: preparedHeaders,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+                timeout: options?.timeout,
+                retry: options?.retry,
+              },
+            );
+          },
+
+          delete: async <R = any>(
+            options?: UrlRequestOptions & { responseType?: "json" },
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            const { headers: preparedHeaders, serializedBody } =
+              self.prepareBody(options?.body, options?.headers);
+            return self._request<R>(
+              "DELETE",
+              buildUrl(options?.path),
+              serializedBody,
+              {
+                headers: preparedHeaders,
+                maxRedirects: options?.maxRedirects,
+                responseType: options?.responseType,
+                antibot: options?.antibot,
+                timeout: options?.timeout,
+                retry: options?.retry,
+              },
+            );
+          },
+
+          head: async (
+            options?: UrlRequestOptions,
+          ): Promise<JirenResponse<any>> => {
+            return self._request("HEAD", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+              timeout: options?.timeout,
+              retry: options?.retry,
+            });
+          },
+
+          options: async (
+            options?: UrlRequestOptions,
+          ): Promise<JirenResponse<any>> => {
+            return self._request("OPTIONS", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+              timeout: options?.timeout,
+              retry: options?.retry,
+            });
+          },
+
+          trace: async <R = any>(
+            options?: UrlRequestOptions,
+          ): Promise<JirenResponse<R> | R | string | ArrayBuffer | Blob> => {
+            return self._request<R>("TRACE", buildUrl(options?.path), null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+              timeout: options?.timeout,
+              retry: options?.retry,
+            });
+          },
+
+          prefetch: async (options?: UrlRequestOptions): Promise<void> => {
+            const targetUrl = buildUrl(options?.path);
+            for (const key of self.cacheStore.keys()) {
+              if (key.includes(targetUrl)) {
+                self.cacheStore.delete(key);
+              }
+            }
+            await self._request("GET", targetUrl, null, {
+              headers: options?.headers,
+              maxRedirects: options?.maxRedirects,
+              antibot: options?.antibot,
+              timeout: options?.timeout,
+              retry: options?.retry,
+            });
+          },
+
+          download: async <R = any>(
+            options?: ProgressRequestOptions,
+          ): Promise<JirenResponse<R>> => {
+            const response = (await self._request<R>(
+              "GET",
+              buildUrl(options?.path),
+              null,
+              { headers: options?.headers },
+            )) as InternalResponse<R>;
+
+            const total = response[RAW_BODY].length;
+            options?.onDownloadProgress?.({
+              loaded: total,
+              total,
+              percent: 100,
+              speed: 0,
+              eta: 0,
+            });
+
+            return self.cloneResponse(response);
+          },
+
+          upload: async <R = any>(
+            options?: ProgressRequestOptions & {
+              method?: "POST" | "PUT" | "PATCH";
+              body?: string | object | null;
+            },
+          ): Promise<JirenResponse<R>> => {
+            const method = options?.method || "POST";
+            const { headers: preparedHeaders, serializedBody } = self.prepareBody(
+              options?.body,
+              options?.headers,
+            );
+            const total = serializedBody
+              ? Buffer.byteLength(serializedBody, "utf-8")
+              : 0;
+
+            if (options?.onUploadProgress) {
+              options.onUploadProgress({
+                loaded: 0,
+                total,
+                percent: 0,
+                speed: 0,
+                eta: 0,
+              });
+            }
+
+            const response = (await self._request<R>(
+              method,
+              buildUrl(options?.path),
+              serializedBody,
+              { headers: preparedHeaders },
+            )) as InternalResponse<R>;
+
+            if (options?.onUploadProgress) {
+              options.onUploadProgress({
+                loaded: total,
+                total,
+                percent: 100,
+                speed: 0,
+                eta: 0,
+              });
+            }
+
+            return self.cloneResponse(response);
+          },
+
+          getJsonFields: async <R = any>(
+            fields: string[],
+            options?: UrlRequestOptions,
+          ): Promise<R> => {
+            const json = await self._request<Record<string, unknown>>(
+              "GET",
+              buildUrl(options?.path),
+              null,
+              {
+                headers: options?.headers,
+                maxRedirects: options?.maxRedirects,
+                timeout: options?.timeout,
+                responseType: "json",
+              },
+            );
+
+            const result: Record<string, unknown> = {};
+            for (const field of fields) {
+              result[field] = json?.[field];
+            }
+            return result as R;
+          },
+        } as UrlEndpoint;
+      },
+    });
+  }
+
+  public close(): void {
+    this.closed = true;
+    this.inflightRequests.clear();
+    this.cacheStore.clear();
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  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;
+  }
+
+  public async preconnect(urls: string[]): Promise<void> {
+    urls.forEach((url) => this.targetsComplete.add(url));
+  }
+
+  public async warmup(urls: string[]): Promise<void> {
+    return this.preconnect(urls);
+  }
+
+  public prefetch(urls: string[]): void {
+    void this.preconnect(urls);
+  }
+
+  protected async _request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "json" },
+  ): Promise<T>;
+  protected async _request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "text" },
+  ): Promise<string>;
+  protected async _request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "arraybuffer" },
+  ): Promise<ArrayBuffer>;
+  protected async _request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions & { responseType: "blob" },
+  ): Promise<Blob>;
+  protected async _request<T = any>(
+    method: string,
+    url: string,
+    body?: string | null,
+    options?: RequestOptions,
+  ): Promise<JirenResponse<T>>;
+  protected 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.closed) throw new Error("Client is closed");
+
+    let headers: Record<string, string> = {};
+    let responseType: RequestOptions["responseType"] | undefined;
+    let timeout: number | undefined;
+
+    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.responseType) responseType = opts.responseType;
+        if (opts.timeout !== undefined) timeout = opts.timeout;
+      } else {
+        headers = options as Record<string, string>;
+      }
+    }
+
+    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;
+    }
+
+    let retryConfig = this.globalRetry;
+    if (options && typeof options === "object" && "retry" in options) {
+      const userRetry = options?.retry;
+      if (typeof userRetry === "number") {
+        retryConfig = { count: userRetry, delay: 100, backoff: 2 };
+      } else if (typeof userRetry === "object") {
+        retryConfig = userRetry;
+      }
+    }
+
+    const finalHeaders = this.buildHeaders(headers);
+    let attempts = 0;
+    const maxAttempts = (retryConfig?.count || 0) + 1;
+    let currentDelay = retryConfig?.delay || 100;
+    const backoff = retryConfig?.backoff || 2;
+    let lastError: unknown;
+
+    while (attempts < maxAttempts) {
+      attempts++;
+      try {
+        const controller =
+          timeout && timeout > 0 ? new AbortController() : undefined;
+        let timeoutId: NodeJS.Timeout | undefined;
+
+        if (controller && timeout && timeout > 0) {
+          timeoutId = setTimeout(() => controller.abort(), timeout);
+        }
+
+        try {
+          const response = await fetch(url, {
+            method,
+            headers: finalHeaders,
+            body: body || undefined,
+            redirect: "follow",
+            signal: controller?.signal,
+          });
+
+          const raw = Buffer.from(await response.arrayBuffer());
+          const parsed = this.createResponse<T>(url, response, raw);
+
+          let finalResponse = parsed;
+          if (this.responseInterceptors.length > 0) {
+            let responseCtx: InterceptorResponseContext<T> = {
+              request: ctx,
+              response: parsed,
+            };
+            for (const interceptor of this.responseInterceptors) {
+              responseCtx = await interceptor(responseCtx);
+            }
+            finalResponse = responseCtx.response as InternalResponse<T>;
+          }
+
+          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();
+
+          return finalResponse;
+        } catch (error) {
+          if ((error as Error).name === "AbortError" && timeout) {
+            const timeoutError = new Error(`Request timeout after ${timeout}ms`);
+            timeoutError.name = "TimeoutError";
+            throw timeoutError;
+          }
+          throw error;
+        } finally {
+          if (timeoutId) clearTimeout(timeoutId);
+        }
+      } catch (err) {
+        if (this.errorInterceptors.length > 0) {
+          for (const interceptor of this.errorInterceptors) {
+            await interceptor(err as Error, ctx);
+          }
+        }
+        lastError = err;
+
+        if ((err as Error).name === "TimeoutError") {
+          throw err;
+        }
+
+        if (attempts < maxAttempts) {
+          await this.waitFor(currentDelay);
+          currentDelay *= backoff;
+        }
+      }
+    }
+
+    throw lastError || new Error("Request failed after retries");
+  }
+
+  private createResponse<T>(
+    url: string,
+    response: Response,
+    buffer: Buffer,
+  ): InternalResponse<T> {
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+
+    let bodyUsed = false;
+    const bodyObj: JirenResponseBody<T> = {
+      bodyUsed: false,
+      arrayBuffer: async () => {
+        bodyUsed = true;
+        return buffer.buffer.slice(
+          buffer.byteOffset,
+          buffer.byteOffset + buffer.byteLength,
+        ) as ArrayBuffer;
+      },
+      blob: async () => {
+        bodyUsed = true;
+        return new Blob([buffer]);
+      },
+      text: async () => {
+        bodyUsed = true;
+        return buffer.toString("utf-8");
+      },
+      json: async <R = T>(): Promise<R> => {
+        bodyUsed = true;
+        return JSON.parse(buffer.toString("utf-8"));
+      },
+    };
+
+    Object.defineProperty(bodyObj, "bodyUsed", {
+      get: () => bodyUsed,
+    });
+
+    const jirenResponse: InternalResponse<T> = {
+      url,
+      status: response.status,
+      statusText: response.statusText || STATUS_TEXT[response.status] || "",
+      headers,
+      ok: response.ok,
+      redirected: response.redirected,
+      type: response.type || "basic",
+      body: bodyObj,
+      [RAW_BODY]: buffer,
+    };
+
+    return jirenResponse;
+  }
+
+  private cloneResponse<T>(response: InternalResponse<T>): JirenResponse<T> {
+    const clone = this.createBufferedResponse<T>(
+      response.url,
+      response.status,
+      response.statusText,
+      response.headers,
+      response.ok,
+      response.redirected,
+      response.type,
+      response[RAW_BODY],
+    );
+    return clone;
+  }
+
+  private createBufferedResponse<T>(
+    url: string,
+    status: number,
+    statusText: string,
+    headers: Record<string, string>,
+    ok: boolean,
+    redirected: boolean,
+    type: "basic" | "cors" | "default" | "error" | "opaque" | "opaqueredirect",
+    buffer: Buffer,
+  ): InternalResponse<T> {
+    let bodyUsed = false;
+    const bodyObj: JirenResponseBody<T> = {
+      bodyUsed: false,
+      arrayBuffer: async () => {
+        bodyUsed = true;
+        return buffer.buffer.slice(
+          buffer.byteOffset,
+          buffer.byteOffset + buffer.byteLength,
+        ) as ArrayBuffer;
+      },
+      blob: async () => {
+        bodyUsed = true;
+        return new Blob([buffer]);
+      },
+      text: async () => {
+        bodyUsed = true;
+        return buffer.toString("utf-8");
+      },
+      json: async <R = T>(): Promise<R> => {
+        bodyUsed = true;
+        return JSON.parse(buffer.toString("utf-8"));
+      },
+    };
+
+    Object.defineProperty(bodyObj, "bodyUsed", {
+      get: () => bodyUsed,
+    });
+
+    return {
+      url,
+      status,
+      statusText,
+      headers: { ...headers },
+      ok,
+      redirected,
+      type,
+      body: bodyObj,
+      [RAW_BODY]: Buffer.from(buffer),
+    };
+  }
+
+  private isJirenResponse(value: unknown): value is InternalResponse<any> {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      "status" in value &&
+      "body" in value
+    );
+  }
+
+  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 };
+  }
+
+  private buildHeaders(
+    userHeaders: Record<string, string>,
+  ): Record<string, string> {
+    if (!this.useDefaultHeaders) {
+      return { ...userHeaders };
+    }
+
+    const normalized: Record<string, string> = {};
+    for (const [key, value] of Object.entries(this.defaultHeaders)) {
+      normalized[key.toLowerCase()] = value;
+    }
+    for (const [key, value] of Object.entries(userHeaders)) {
+      normalized[key.toLowerCase()] = value;
+    }
+    return normalized;
+  }
+
+  private getRequestKey(
+    method: string,
+    url: string,
+    headers?: Record<string, string>,
+    body?: string | null,
+  ): string {
+    return `${method}:${url}:${JSON.stringify(headers || {})}:${body || ""}`;
+  }
+
+  private getCachedResponse(key: string): JirenResponse | null {
+    const cached = this.cacheStore.get(key);
+    if (!cached) return null;
+    if (Date.now() > cached.expiresAt) {
+      this.cacheStore.delete(key);
+      return null;
+    }
+
+    return this.createBufferedResponse(
+      cached.url,
+      cached.status,
+      cached.statusText,
+      cached.headers,
+      cached.ok,
+      cached.redirected,
+      cached.type,
+      cached.body,
+    );
+  }
+
+  private setCachedResponse(
+    key: string,
+    response: InternalResponse,
+    ttl: number,
+  ): void {
+    this.cacheStore.set(key, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: { ...response.headers },
+      url: response.url,
+      ok: response.ok,
+      redirected: response.redirected,
+      type: response.type,
+      body: Buffer.from(response[RAW_BODY]),
+      expiresAt: Date.now() + ttl,
+    });
+  }
+}