jeopi-ai 16.2.13

package/src/utils/proxy.ts

@@ -0,0 +1,240 @@
+import * as net from "node:net";
+import * as tls from "node:tls";
+import * as AIError from "../error";
+import type { FetchImpl } from "../types";
+
+/**
+ * Checks if a host is local or cloud metadata, which should always bypass the proxy
+ * (e.g. localhost, 127/8, ::1, 169.254.169.254, metadata.google.internal).
+ */
+export function isLocalOrMetadataHost(host: string): boolean {
+	const lowerHost = host.toLowerCase();
+
+	// Hostnames: localhost and the cloud metadata service.
+	if (lowerHost === "localhost" || lowerHost.endsWith(".localhost") || lowerHost === "metadata.google.internal") {
+		return true;
+	}
+
+	// Strip IPv6 brackets before numeric checks.
+	const ip = lowerHost.replace(/^\[|\]$/g, "");
+
+	// IPv4 loopback (127/8), unspecified (0/8), RFC1918 private (10/8, 172.16/12,
+	// 192.168/16) and link-local (169.254/16 — covers IMDS 169.254.169.254 and
+	// ECS credentials 169.254.170.2). None are reachable through a remote egress
+	// proxy, and credential/metadata probes must never leak to one.
+	const v4 = ip.match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+	if (v4) {
+		const a = Number(v4[1]);
+		const b = Number(v4[2]);
+		if (a === 127 || a === 10 || a === 0) return true;
+		if (a === 169 && b === 254) return true;
+		if (a === 192 && b === 168) return true;
+		if (a === 172 && b >= 16 && b <= 31) return true;
+		return false;
+	}
+
+	// IPv6 loopback (::1), unspecified (::), link-local (fe80::/10) and
+	// unique-local (fc00::/7 — covers EC2 IPv6 IMDS fd00:ec2::254).
+	if (ip === "::1" || ip === "::") return true;
+	if (/^fe[89ab][0-9a-f]:/.test(ip)) return true;
+	if (/^f[cd][0-9a-f]{2}:/.test(ip)) return true;
+
+	return false;
+}
+
+/**
+ * Check if the url should bypass the proxy due to hard-coded localhost/metadata checks
+ * or custom NO_PROXY/no_proxy environment variables rules.
+ */
+export function shouldBypassProxy(urlObj: URL): boolean {
+	if (isLocalOrMetadataHost(urlObj.hostname)) {
+		return true;
+	}
+
+	const noProxyVal = Bun.env.NO_PROXY || Bun.env.no_proxy;
+	if (!noProxyVal) {
+		return false;
+	}
+
+	const rules = noProxyVal
+		.split(/[,\s]+/)
+		.map(r => r.trim())
+		.filter(Boolean);
+	const targetHost = urlObj.hostname.toLowerCase();
+	const targetPort = urlObj.port || (urlObj.protocol === "https:" ? "443" : "80");
+
+	for (const rule of rules) {
+		if (rule === "*") {
+			return true;
+		}
+
+		let ruleHost = rule.toLowerCase();
+		let rulePort: string | undefined;
+
+		if (ruleHost.includes("]:")) {
+			const lastColon = ruleHost.lastIndexOf(":");
+			rulePort = ruleHost.slice(lastColon + 1);
+			ruleHost = ruleHost.slice(0, lastColon);
+		} else if (!ruleHost.includes("]") && ruleHost.includes(":")) {
+			const lastColon = ruleHost.lastIndexOf(":");
+			rulePort = ruleHost.slice(lastColon + 1);
+			ruleHost = ruleHost.slice(0, lastColon);
+		}
+
+		// Strip IPv6 brackets
+		ruleHost = ruleHost.replace(/^\[|\]$/g, "");
+
+		if (rulePort && rulePort !== targetPort) {
+			continue;
+		}
+
+		// Match host part
+		if (ruleHost.startsWith(".")) {
+			const suffix = ruleHost;
+			const cleanRule = ruleHost.slice(1);
+			if (targetHost === cleanRule || targetHost.endsWith(suffix)) {
+				return true;
+			}
+		} else {
+			if (targetHost === ruleHost || targetHost.endsWith(`.${ruleHost}`)) {
+				return true;
+			}
+		}
+	}
+
+	return false;
+}
+
+const proxyCache = new Map<string, string | undefined>();
+
+/** Test seam: clears the provider proxy cache. */
+export function __resetProxyCache(): void {
+	proxyCache.clear();
+}
+
+/**
+ * Normalizes provider id (e.g. github-copilot -> PI_PROXY_GITHUB_COPILOT) and looks it up.
+ * If not found, falls back to PI_PROXY. Results are memoized because env values are static
+ * for the lifetime of the process and this function is called for every outgoing request.
+ */
+export function getProxyForProvider(provider: string): string | undefined {
+	if (proxyCache.has(provider)) {
+		return proxyCache.get(provider);
+	}
+
+	const normalized = provider.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+	const envKey = `PI_PROXY_${normalized}`;
+	const value = Bun.env[envKey] || Bun.env.PI_PROXY;
+	proxyCache.set(provider, value);
+	return value;
+}
+
+/**
+ * Wraps a fetch implementation to inject proxy options for non-local hosts.
+ */
+export function wrapFetchForProxy(fetchImpl: FetchImpl, provider: string): FetchImpl {
+	const proxyUrl = getProxyForProvider(provider);
+	if (!proxyUrl) {
+		return fetchImpl;
+	}
+
+	const wrapped = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+		const urlStr = input instanceof Request ? input.url : input.toString();
+		let urlObj: URL;
+		try {
+			urlObj = new URL(urlStr);
+		} catch {
+			// Fallback to calling fetch unmodified if URL is unparseable
+			return fetchImpl(input, init);
+		}
+
+		if (shouldBypassProxy(urlObj)) {
+			return fetchImpl(input, init);
+		}
+
+		const mergedInit = { ...(init ?? {}), proxy: proxyUrl };
+		return fetchImpl(input, mergedInit);
+	};
+
+	if (fetchImpl.preconnect) {
+		wrapped.preconnect = fetchImpl.preconnect;
+	}
+	return wrapped;
+}
+
+/**
+ * Tunnel a socket connection through an HTTP CONNECT proxy.
+ * This is used specifically to wrap Node's `http2.connect(baseUrl, { createConnection })` for Cursor.
+ */
+export async function connectProxiedSocket(proxyUrlStr: string, targetUrlStr: string): Promise<tls.TLSSocket> {
+	const proxyUrl = new URL(proxyUrlStr);
+	const targetUrl = new URL(targetUrlStr);
+
+	const useProxySsl = proxyUrl.protocol === "https:";
+	const proxyPort = proxyUrl.port ? parseInt(proxyUrl.port, 10) : useProxySsl ? 443 : 80;
+	const proxyHost = proxyUrl.hostname;
+
+	const targetPort = targetUrl.port ? parseInt(targetUrl.port, 10) : 443;
+	const targetHost = targetUrl.hostname;
+
+	const { promise, resolve, reject } = Promise.withResolvers<tls.TLSSocket>();
+
+	let rawSocket: net.Socket;
+	if (useProxySsl) {
+		rawSocket = tls.connect({
+			host: proxyHost,
+			port: proxyPort,
+		});
+	} else {
+		rawSocket = net.connect({
+			host: proxyHost,
+			port: proxyPort,
+		});
+	}
+
+	rawSocket.once("error", reject);
+
+	const readyEvent = useProxySsl ? "secureConnect" : "connect";
+	rawSocket.once(readyEvent, () => {
+		let connectReq = `CONNECT ${targetHost}:${targetPort} HTTP/1.1\r\n` + `Host: ${targetHost}:${targetPort}\r\n`;
+
+		if (proxyUrl.username || proxyUrl.password) {
+			const creds = Buffer.from(
+				`${decodeURIComponent(proxyUrl.username)}:${decodeURIComponent(proxyUrl.password)}`,
+			).toString("base64");
+			connectReq += `Proxy-Authorization: Basic ${creds}\r\n`;
+		}
+		connectReq += "\r\n";
+
+		rawSocket.write(connectReq);
+
+		let responseData = "";
+		const onData = (chunk: Buffer) => {
+			responseData += chunk.toString("binary");
+			if (responseData.includes("\r\n\r\n")) {
+				rawSocket.off("data", onData);
+				rawSocket.off("error", reject);
+
+				const firstLine = responseData.split("\r\n")[0];
+				if (firstLine.includes(" 200 ")) {
+					const tlsSocket = tls.connect({
+						socket: rawSocket,
+						servername: targetHost,
+						ALPNProtocols: ["h2"],
+					});
+
+					tlsSocket.once("secureConnect", () => {
+						resolve(tlsSocket);
+					});
+					tlsSocket.once("error", reject);
+				} else {
+					rawSocket.destroy();
+					reject(new AIError.ValidationError(`Proxy tunnel failed: ${firstLine}`));
+				}
+			}
+		};
+		rawSocket.on("data", onData);
+	});
+
+	return promise;
+}

package/src/utils/request-debug.ts

@@ -0,0 +1,351 @@
+import { Buffer } from "node:buffer";
+import * as fs from "node:fs/promises";
+import type { FetchImpl } from "../types";
+
+const REQUEST_DEBUG_ENV = "PI_REQ_DEBUG";
+const DEBUG_FETCH_MARKER = Symbol("omp.requestDebugFetch");
+const textEncoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+let nextSessionId = 1;
+
+type DebugFetch = FetchImpl & { [DEBUG_FETCH_MARKER]?: true };
+type RequestBodyInit = NonNullable<RequestInit["body"]>;
+
+type RequestDebugBody = { body: unknown } | { bodyText: string } | { bodyBase64: string } | { bodyUnavailable: string };
+
+export type RequestDebugHeaders = Headers | Record<string, string | string[] | number | undefined | null> | undefined;
+
+export interface RequestDebugPayload {
+	method: string;
+	url: string;
+	headers?: RequestDebugHeaders;
+	body?: unknown;
+	bodyText?: string;
+	bodyBase64?: string;
+	bodyUnavailable?: string;
+	protocol?: string;
+}
+
+interface ReservedRequestDebugFile {
+	id: number;
+	requestPath: string;
+	responsePath: string;
+	handle: fs.FileHandle;
+	overwrite: boolean;
+}
+
+export interface RequestDebugResponseLog {
+	write(chunk: Uint8Array | string): void;
+	close(): Promise<void>;
+}
+
+export interface RequestDebugSession {
+	readonly id: number;
+	readonly requestPath: string;
+	readonly responsePath: string;
+	openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog>;
+	wrapResponse(response: Response): Promise<Response>;
+}
+
+function isRequestDebugEnvEnabled(): boolean {
+	return Bun.env[REQUEST_DEBUG_ENV] === "1";
+}
+
+export function isRequestDebugEnabled(): boolean {
+	return isRequestDebugEnvEnabled();
+}
+
+export function wrapFetchForRequestDebug(fetchImpl: FetchImpl): FetchImpl {
+	if (!isRequestDebugEnabled()) return fetchImpl;
+	const maybeWrapped = fetchImpl as DebugFetch;
+	if (maybeWrapped[DEBUG_FETCH_MARKER]) return fetchImpl;
+
+	const wrapped = Object.assign(
+		async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+			if (!isRequestDebugEnabled()) return fetchImpl(input, init);
+			const session = await createFetchRequestDebugSession(input, init);
+			const response = await fetchImpl(input, init);
+			return session.wrapResponse(response);
+		},
+		fetchImpl.preconnect ? { preconnect: fetchImpl.preconnect } : {},
+		{ [DEBUG_FETCH_MARKER]: true as const },
+	);
+	return wrapped;
+}
+
+export function withRequestDebugFetch<T extends { fetch?: FetchImpl } | undefined>(options: T): T {
+	if (!isRequestDebugEnabled()) return options;
+	const fetchImpl = options?.fetch ?? (globalThis.fetch as FetchImpl);
+	const wrapped = wrapFetchForRequestDebug(fetchImpl);
+	return { ...(options ?? {}), fetch: wrapped } as T;
+}
+
+export async function createRequestDebugSession(payload: RequestDebugPayload): Promise<RequestDebugSession> {
+	const { id, requestPath, responsePath, handle, overwrite } = await reserveRequestDebugFile();
+	const requestDump: Record<string, unknown> = {
+		id,
+		protocol: payload.protocol ?? "http",
+		method: payload.method,
+		url: payload.url,
+	};
+	const headers = headersToRecord(payload.headers);
+	if (headers) requestDump.headers = headers;
+	if (payload.body !== undefined) requestDump.body = payload.body;
+	if (payload.bodyText !== undefined) requestDump.bodyText = payload.bodyText;
+	if (payload.bodyBase64 !== undefined) requestDump.bodyBase64 = payload.bodyBase64;
+	if (payload.bodyUnavailable !== undefined) requestDump.bodyUnavailable = payload.bodyUnavailable;
+
+	try {
+		await handle.writeFile(`${JSON.stringify(requestDump, null, 2)}\n`, "utf8");
+	} finally {
+		await handle.close();
+	}
+
+	return new FileRequestDebugSession(id, requestPath, responsePath, overwrite);
+}
+
+async function createFetchRequestDebugSession(
+	input: string | URL | Request,
+	init: RequestInit | undefined,
+): Promise<RequestDebugSession> {
+	const headers = resolveRequestHeaders(input, init);
+	const body = await snapshotRequestBody(input, init, headers.get("content-type"));
+	return createRequestDebugSession({
+		method: resolveRequestMethod(input, init),
+		url: resolveRequestUrl(input),
+		headers,
+		...body,
+	});
+}
+
+class FileRequestDebugSession implements RequestDebugSession {
+	readonly id: number;
+	readonly requestPath: string;
+	readonly responsePath: string;
+	readonly #overwriteResponseLog: boolean;
+
+	constructor(id: number, requestPath: string, responsePath: string, overwriteResponseLog: boolean) {
+		this.id = id;
+		this.requestPath = requestPath;
+		this.responsePath = responsePath;
+		this.#overwriteResponseLog = overwriteResponseLog;
+	}
+
+	async openResponseLog(statusLine: string, headers?: RequestDebugHeaders): Promise<RequestDebugResponseLog> {
+		const handle = await fs.open(this.responsePath, this.#overwriteResponseLog ? "w" : "wx");
+		const headerBlock = formatResponseHeaderBlock(statusLine, headers);
+		await handle.write(textEncoder.encode(headerBlock));
+		return new FileRequestDebugResponseLog(handle);
+	}
+
+	async wrapResponse(response: Response): Promise<Response> {
+		const log = await this.openResponseLog(`HTTP ${response.status} ${response.statusText}`.trim(), response.headers);
+		if (!response.body) {
+			await log.close();
+			return response;
+		}
+
+		const reader = response.body.getReader();
+		const teed = new ReadableStream<Uint8Array>({
+			async pull(controller) {
+				try {
+					const { done, value } = await reader.read();
+					if (done) {
+						await log.close();
+						controller.close();
+						return;
+					}
+					log.write(value);
+					controller.enqueue(value);
+				} catch (error) {
+					await log.close().catch(() => undefined);
+					controller.error(error);
+				}
+			},
+			async cancel(reason) {
+				try {
+					await reader.cancel(reason);
+				} finally {
+					await log.close();
+				}
+			},
+		});
+
+		const wrapped = new Response(teed, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers,
+		});
+		copyResponseMetadata(wrapped, response);
+		return wrapped;
+	}
+}
+
+class FileRequestDebugResponseLog implements RequestDebugResponseLog {
+	#handle: fs.FileHandle | undefined;
+	#pending: Promise<void> = Promise.resolve();
+	#closed: Promise<void> | undefined;
+
+	constructor(handle: fs.FileHandle) {
+		this.#handle = handle;
+	}
+
+	write(chunk: Uint8Array | string): void {
+		const handle = this.#handle;
+		if (!handle) return;
+		const bytes = typeof chunk === "string" ? textEncoder.encode(chunk) : chunk.slice();
+		this.#pending = this.#pending.then(async () => {
+			await handle.write(bytes);
+		});
+	}
+
+	close(): Promise<void> {
+		if (this.#closed) return this.#closed;
+		const handle = this.#handle;
+		if (!handle) return Promise.resolve();
+		this.#handle = undefined;
+		this.#closed = (async () => {
+			try {
+				await this.#pending;
+			} finally {
+				await handle.close();
+			}
+		})();
+		return this.#closed;
+	}
+}
+
+function copyResponseMetadata(target: Response, source: Response): void {
+	const sourceUrl = source.url;
+	if (!sourceUrl) return;
+	try {
+		Object.defineProperty(target, "url", { value: sourceUrl, configurable: true });
+	} catch {
+		// Some runtimes may expose Response.url as non-configurable. The body
+		// capture remains correct; callers that need url already tolerate the
+		// platform default on other response wrappers in this package.
+	}
+}
+
+async function reserveRequestDebugFile(): Promise<ReservedRequestDebugFile> {
+	for (;;) {
+		const id = nextSessionId++;
+		const requestPath = `rr-session-${id}.json`;
+		try {
+			const handle = await fs.open(requestPath, "wx");
+			return { id, requestPath, responsePath: `rr-session-${id}.res.log`, handle, overwrite: false };
+		} catch (error) {
+			if (isFileExistsError(error)) continue;
+			throw error;
+		}
+	}
+}
+
+function resolveRequestMethod(input: string | URL | Request, init: RequestInit | undefined): string {
+	return (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+}
+
+function resolveRequestUrl(input: string | URL | Request): string {
+	return input instanceof Request ? input.url : input.toString();
+}
+
+function resolveRequestHeaders(input: string | URL | Request, init: RequestInit | undefined): Headers {
+	if (init?.headers) return new Headers(init.headers);
+	return input instanceof Request ? new Headers(input.headers) : new Headers();
+}
+
+async function snapshotRequestBody(
+	input: string | URL | Request,
+	init: RequestInit | undefined,
+	contentType: string | null,
+): Promise<RequestDebugBody | undefined> {
+	if (init?.body !== undefined && init.body !== null) return snapshotBodyInit(init.body, contentType);
+	if (input instanceof Request && input.body) {
+		return snapshotBytes(new Uint8Array(await input.clone().arrayBuffer()), contentType);
+	}
+	return undefined;
+}
+
+async function snapshotBodyInit(body: RequestBodyInit, contentType: string | null): Promise<RequestDebugBody> {
+	if (typeof body === "string") return snapshotText(body, contentType);
+	if (body instanceof URLSearchParams) return { bodyText: body.toString() };
+	if (body instanceof FormData) return { bodyUnavailable: "FormData" };
+	if (body instanceof Blob) return snapshotBytes(new Uint8Array(await body.arrayBuffer()), body.type || contentType);
+	if (body instanceof ArrayBuffer) return snapshotBytes(new Uint8Array(body), contentType);
+	if (ArrayBuffer.isView(body)) {
+		return snapshotBytes(new Uint8Array(body.buffer, body.byteOffset, body.byteLength), contentType);
+	}
+	if (body instanceof ReadableStream) return { bodyUnavailable: "ReadableStream" };
+	return { bodyText: String(body) };
+}
+
+function snapshotBytes(bytes: Uint8Array, contentType: string | null): RequestDebugBody {
+	try {
+		return snapshotText(utf8Decoder.decode(bytes), contentType);
+	} catch {
+		return { bodyBase64: Buffer.from(bytes).toString("base64") };
+	}
+}
+
+function snapshotText(text: string, contentType: string | null): RequestDebugBody {
+	if (isJsonContentType(contentType) || looksLikeJson(text)) {
+		try {
+			return { body: JSON.parse(text) };
+		} catch {
+			// Fall through to bodyText: malformed JSON is still useful as raw text.
+		}
+	}
+	return { bodyText: text };
+}
+
+function isJsonContentType(contentType: string | null): boolean {
+	if (!contentType) return false;
+	const lower = contentType.toLowerCase();
+	return lower.includes("application/json") || lower.includes("+json");
+}
+
+function looksLikeJson(text: string): boolean {
+	const trimmed = text.trimStart();
+	return trimmed.startsWith("{") || trimmed.startsWith("[");
+}
+
+function formatResponseHeaderBlock(statusLine: string, headers?: RequestDebugHeaders): string {
+	const lines = [statusLine];
+	const record = headersToRecord(headers);
+	if (record) {
+		for (const name in record) {
+			const value = record[name];
+			if (Array.isArray(value)) {
+				for (const item of value) lines.push(`${name}: ${item}`);
+			} else {
+				lines.push(`${name}: ${value}`);
+			}
+		}
+	}
+	return `${lines.join("\r\n")}\r\n\r\n`;
+}
+
+function headersToRecord(headers: RequestDebugHeaders): Record<string, string | string[]> | undefined {
+	if (!headers) return undefined;
+	const record: Record<string, string | string[]> = {};
+	let hasHeaders = false;
+	if (headers instanceof Headers) {
+		headers.forEach((value, key) => {
+			hasHeaders = true;
+			record[key] = value;
+		});
+	} else {
+		for (const key in headers) {
+			const value = headers[key];
+			if (value === undefined || value === null) continue;
+			hasHeaders = true;
+			record[key] = Array.isArray(value) ? value.map(String) : String(value);
+		}
+	}
+	return hasHeaders ? record : undefined;
+}
+
+function isFileExistsError(error: unknown): boolean {
+	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "EEXIST";
+}

package/src/utils/retry-after.ts

@@ -0,0 +1,110 @@
+export type HeadersLike = Headers | Record<string, string | undefined> | undefined | null;
+
+const RETRY_AFTER_HINT = "retry-after-ms=";
+
+export function formatErrorMessageWithRetryAfter(error: unknown, headers?: HeadersLike): string {
+	const message = error instanceof Error ? error.message : JSON.stringify(error);
+	if (message.includes(RETRY_AFTER_HINT)) {
+		return message;
+	}
+
+	const retryAfterMs = getRetryAfterMsFromHeaders(headers ?? getHeadersFromError(error));
+	if (retryAfterMs === undefined) {
+		return message;
+	}
+
+	return `${message} ${RETRY_AFTER_HINT}${retryAfterMs}`;
+}
+
+export function getRetryAfterMsFromHeaders(headers: HeadersLike): number | undefined {
+	if (!headers) return undefined;
+
+	const retryAfter = parseRetryAfterHeader(getHeaderValue(headers, "retry-after"));
+	const resetMs = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset-ms"), "ms");
+	const resetSeconds = parseResetHeader(getHeaderValue(headers, "x-ratelimit-reset"), "s");
+
+	const candidates = [retryAfter, resetMs, resetSeconds].filter((value): value is number => value !== undefined);
+	if (candidates.length === 0) return undefined;
+	return Math.max(...candidates);
+}
+
+export function getHeadersFromError(error: unknown): HeadersLike {
+	if (!error || typeof error !== "object") return undefined;
+	const record = error as { headers?: unknown; response?: { headers?: unknown }; cause?: unknown };
+	const direct = extractHeaders(record.headers) ?? extractHeaders(record.response?.headers);
+	if (direct) return direct;
+	if (record.cause) return getHeadersFromError(record.cause);
+	return undefined;
+}
+
+function extractHeaders(value: unknown): HeadersLike {
+	if (!value) return undefined;
+	if (value instanceof Headers) return value;
+	if (typeof value === "object") return value as Record<string, string | undefined>;
+	return undefined;
+}
+
+function getHeaderValue(headers: Headers | Record<string, string | undefined>, name: string): string | undefined {
+	if (headers instanceof Headers) {
+		const value = headers.get(name);
+		return value ?? undefined;
+	}
+
+	const target = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) {
+		if (key.toLowerCase() === target && typeof value === "string") {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+function parseRetryAfterHeader(value: string | undefined): number | undefined {
+	if (!value) return undefined;
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+
+	const numeric = Number(trimmed);
+	if (Number.isFinite(numeric)) {
+		if (numeric <= 0) return undefined;
+		return Math.ceil(numeric * 1000);
+	}
+
+	const dateMs = Date.parse(trimmed);
+	if (!Number.isNaN(dateMs)) {
+		const delay = dateMs - Date.now();
+		return delay > 0 ? Math.ceil(delay) : undefined;
+	}
+
+	return undefined;
+}
+
+function parseResetHeader(value: string | undefined, unit: "ms" | "s"): number | undefined {
+	if (!value) return undefined;
+	const numeric = Number(value);
+	if (!Number.isFinite(numeric) || numeric <= 0) return undefined;
+
+	const nowMs = Date.now();
+	let targetMs: number | undefined;
+
+	if (unit === "ms") {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric);
+		}
+	} else {
+		if (numeric > 1e12) {
+			targetMs = numeric;
+		} else if (numeric > 1e9) {
+			targetMs = numeric * 1000;
+		} else {
+			return Math.ceil(numeric * 1000);
+		}
+	}
+
+	if (targetMs <= nowMs) return undefined;
+	return Math.ceil(targetMs - nowMs);
+}