/** * Shared HTTP plumbing for provider adapters: a fetch wrapper with timeouts, * an SSE parser over Web Streams, and one place that turns provider failures * into `AIError`s. Uses only global `fetch` — no SDKs. * * Security rule for this whole folder: an API key must never reach an error * message, a log line or a thrown value. Everything user-visible that contains * provider text goes through `scrubSecrets` first. */ import { AIError, type AIErrorCode } from '../types.ts'; /* ------------------------------------------------------------------ */ /* Secret scrubbing */ /* ------------------------------------------------------------------ */ const KEY_PATTERNS: RegExp[] = [ /\bsk-[A-Za-z0-9_-]{8,}/g, // OpenAI / Anthropic / OpenRouter style /\bAIza[0-9A-Za-z_-]{16,}/g, // Google API keys /\bgsk_[A-Za-z0-9]{8,}/g, // Groq /(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, /([?&](?:key|api_key|apikey|access_token)=)[^&\s"']+/gi, ]; /** Removes known secrets (and anything that looks like an API key) from provider text. */ export function scrubSecrets(text: string, secrets: Array = []): string { let out = text; for (const s of secrets) { if (s && s.length >= 4) out = out.split(s).join('[redacted]'); } for (const re of KEY_PATTERNS) { out = out.replace(re, (_m, prefix?: unknown) => (typeof prefix === 'string' ? `${prefix}[redacted]` : '[redacted]')); } return out; } function clip(text: string, max = 800): string { const t = text.trim(); return t.length > max ? `${t.slice(0, max)}…` : t; } /* ------------------------------------------------------------------ */ /* Error mapping */ /* ------------------------------------------------------------------ */ export interface ErrorContext { /** Human provider label used in messages ("OpenAI", "Ollama"). */ provider: string; /** Values that must never appear in an error (API key, custom header values). */ secrets?: Array; } interface ProviderErrorFields { message: string; type: string; code: string; /** Whole body as text, used for keyword matching (quota ids, reasons, ...). */ raw: string; } /** Pulls message/type/code out of the error envelopes used by the providers we talk to. */ export function extractProviderError(body: unknown): ProviderErrorFields { let node: unknown = body; if (typeof node === 'string') { const text = node; try { node = JSON.parse(text); } catch { return { message: text.trim().startsWith('<') ? '' : text.trim(), type: '', code: '', raw: text }; } } const raw = safeStringify(node); // Gemini sometimes wraps the error object in an array. if (Array.isArray(node)) node = node[0]; if (!isRecord(node)) return { message: '', type: '', code: '', raw }; const err = node.error ?? node; // Ollama: {"error": "model 'x' not found"} if (typeof err === 'string') return { message: err, type: '', code: '', raw }; if (!isRecord(err)) return { message: '', type: '', code: '', raw }; const message = typeof err.message === 'string' ? err.message : typeof node.message === 'string' ? node.message : ''; // OpenAI: error.type + error.code; Anthropic: error.type; Gemini: error.status (+ numeric code). const type = [err.type, err.status].filter((v): v is string => typeof v === 'string').join(' '); const code = typeof err.code === 'string' ? err.code : ''; return { message, type, code, raw }; } const CONTEXT_RE = /context[_ ]length|context[_ ]window|maximum context|max(?:imum)? (?:input )?tokens? (?:limit|allowed)|too many (?:input )?tokens|prompt is too long|input is too long|input token count|exceeds? the (?:model'?s? )?(?:maximum|max)[^.]{0,40}tokens|reduce the length|request[_ ]too[_ ]large|exceed_context_size|n_ctx/i; const QUOTA_RE = /insufficient[_ ]quota|billing|credit balance|exceeded your current quota|out of credits|insufficient (?:credits|funds|balance)|payment required|spend(?:ing)? limit/i; const AUTH_RE = /invalid[_ ]api[_ ]key|incorrect api key|api key not valid|api_key_invalid|authentication[_ ]error|invalid x-api-key|unauthorized|no auth credentials/i; const FILTER_RE = /content[_ ]filter|content[_ ]policy|content management policy|safety system|responsible ai/i; function classify(status: number | undefined, f: ProviderErrorFields): AIErrorCode { const hay = `${f.type} ${f.code} ${f.message}`; const s = status ?? 0; // Provider error names win over the status code: they are also all we have // for errors delivered inside an already-open (HTTP 200) stream. if (/authentication_error|invalid_api_key|permission_error|PERMISSION_DENIED|UNAUTHENTICATED/.test(hay)) return 'auth'; if (/insufficient_quota|billing_error/.test(hay)) return 'quota'; if (/context_length_exceeded|request_too_large/.test(hay)) return 'context_length'; if (/overloaded_error|server_error|api_error|UNAVAILABLE|INTERNAL\b/.test(`${f.type} ${f.code}`)) return 'server'; if (s === 401 || s === 403) return 'auth'; if (s === 402) return 'quota'; if (s === 429 || /rate_limit|RESOURCE_EXHAUSTED/.test(hay)) { // Gemini words every 429 as "exceeded your current quota"; its details say // whether it is a per-minute limit (retry soon) or a daily/billing cap. if (/PerMinute|retryDelay|RetryInfo/.test(f.raw) && !/PerDay/.test(f.raw)) return 'rate_limit'; return QUOTA_RE.test(hay) || /PerDay/.test(f.raw) ? 'quota' : 'rate_limit'; } if (s === 404 || /not_found_error|model_not_found|NOT_FOUND/.test(hay)) return 'not_found'; if (s === 408 || s === 504 || /DEADLINE_EXCEEDED/.test(hay)) return 'timeout'; if (s === 413) return 'context_length'; if (s >= 500) return 'server'; // Remaining 4xx (and status-less stream errors). if (AUTH_RE.test(hay)) return 'auth'; // Gemini answers a bad key with 400 INVALID_ARGUMENT if (CONTEXT_RE.test(hay)) return 'context_length'; if (QUOTA_RE.test(hay)) return 'quota'; // Anthropic: 400 "credit balance is too low" if (FILTER_RE.test(hay)) return 'content_filter'; if (s === 0 && !f.message) return 'server'; return 'bad_request'; } function friendlyMessage(code: AIErrorCode, provider: string): string { switch (code) { case 'auth': return `${provider} rejected the API key.`; case 'rate_limit': return `${provider} is rate limiting requests. Try again in a moment.`; case 'quota': return `${provider} reports that the account is out of quota or credit.`; case 'context_length': return `The conversation is too long for this ${provider} model.`; case 'not_found': return `${provider} could not find that model or endpoint.`; case 'content_filter': return `${provider} blocked the request with its content filter.`; case 'server': return `${provider} is having trouble right now. Try again shortly.`; case 'timeout': return `${provider} took too long to respond.`; case 'bad_request': return `${provider} rejected the request.`; default: return `${provider} returned an error.`; } } /** * The single place that maps "HTTP status + provider error body" to an AIError. * Pass `status: undefined` for errors that arrive as events inside a stream. */ export function errorFromProvider(ctx: ErrorContext, status: number | undefined, body: unknown): AIError { const fields = extractProviderError(body); const code = classify(status, fields); const detail = fields.message || (status ? `HTTP ${status}` : ''); return new AIError(code, friendlyMessage(code, ctx.provider), { status, providerMessage: detail ? clip(scrubSecrets(detail, ctx.secrets)) : undefined, }); } /** Maps anything thrown by `fetch` / a body read to an AIError. */ export function errorFromThrown(ctx: ErrorContext, err: unknown, abortReason?: 'timeout' | 'aborted' | null): AIError { if (err instanceof AIError) return err; const name = isRecord(err) && typeof err.name === 'string' ? err.name : ''; if (abortReason === 'timeout' || name === 'TimeoutError') { return new AIError('timeout', friendlyMessage('timeout', ctx.provider), { cause: err }); } if (abortReason === 'aborted' || name === 'AbortError') { return new AIError('aborted', 'The request was cancelled.', { cause: err }); } // undici reports DNS/connection failures as TypeError("fetch failed") with the real reason in `cause`. const cause = isRecord(err) && isRecord(err.cause) ? err.cause : undefined; const parts = [ cause && typeof cause.code === 'string' ? cause.code : '', cause && typeof cause.message === 'string' ? cause.message : '', err instanceof Error ? err.message : String(err), ].filter(Boolean); return new AIError('network', `Could not reach ${ctx.provider}. Check the address and your connection.`, { providerMessage: clip(scrubSecrets(parts.join(': '), ctx.secrets)), cause: err, }); } /* ------------------------------------------------------------------ */ /* fetch with timeouts */ /* ------------------------------------------------------------------ */ export interface HttpOptions extends ErrorContext { method?: 'GET' | 'POST'; headers?: Record; /** Serialised as JSON when present. */ body?: unknown; signal?: AbortSignal; /** Time allowed until response headers arrive (default 60s). */ firstByteTimeoutMs?: number; /** Hard cap on the whole exchange (default 30 min — streams are long). */ totalTimeoutMs?: number; } export interface HttpResponse { response: Response; ctx: ErrorContext; /** Abort the exchange from our side (used by the idle watchdog). */ abort(reason: 'timeout' | 'aborted'): void; abortReason(): 'timeout' | 'aborted' | null; /** Clears timers/listeners. Safe to call more than once. */ cleanup(): void; } export const DEFAULT_FIRST_BYTE_TIMEOUT_MS = 60_000; export const DEFAULT_TOTAL_TIMEOUT_MS = 30 * 60_000; /** Longest silence tolerated inside an open stream before we give up. */ export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000; /** * Sends a request and resolves once headers are in. Does NOT check `response.ok` * (callers decide; see `ensureOk`). Throws AIError for abort/timeout/network. */ export async function httpRequest(url: string, opts: HttpOptions): Promise { const ctx: ErrorContext = { provider: opts.provider, secrets: opts.secrets }; if (opts.signal?.aborted) throw new AIError('aborted', 'The request was cancelled.'); const controller = new AbortController(); let reason: 'timeout' | 'aborted' | null = null; const abort = (r: 'timeout' | 'aborted') => { if (reason) return; reason = r; controller.abort(); }; const onUserAbort = () => abort('aborted'); opts.signal?.addEventListener('abort', onUserAbort, { once: true }); const firstByte = setTimeout(() => abort('timeout'), opts.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS); const total = setTimeout(() => abort('timeout'), opts.totalTimeoutMs ?? DEFAULT_TOTAL_TIMEOUT_MS); let cleaned = false; const cleanup = () => { if (cleaned) return; cleaned = true; clearTimeout(firstByte); clearTimeout(total); opts.signal?.removeEventListener('abort', onUserAbort); }; const headers: Record = { ...opts.headers }; let body: string | undefined; if (opts.body !== undefined) { body = JSON.stringify(opts.body); if (!hasHeader(headers, 'content-type')) headers['Content-Type'] = 'application/json'; } try { const response = await fetch(url, { method: opts.method ?? (body === undefined ? 'GET' : 'POST'), headers, body, signal: controller.signal, }); clearTimeout(firstByte); return { response, ctx, abort, abortReason: () => reason, cleanup }; } catch (err) { cleanup(); throw errorFromThrown(ctx, err, reason); } } /** Reads the body of a failed response and throws the mapped AIError. Returns normally when `ok`. */ export async function ensureOk(http: HttpResponse): Promise { if (http.response.ok) return; let text = ''; try { text = await http.response.text(); } catch { /* body unreadable — the status code alone still maps to something useful */ } finally { http.cleanup(); } throw errorFromProvider(http.ctx, http.response.status, text); } /** Request + status check + JSON parse, for non-streaming calls such as model discovery. */ export async function requestJson(url: string, opts: HttpOptions): Promise { const http = await httpRequest(url, opts); await ensureOk(http); try { const text = await http.response.text(); try { return JSON.parse(text) as T; } catch { throw new AIError('invalid_response', `${opts.provider} sent a response that was not valid JSON.`, { providerMessage: clip(scrubSecrets(text, opts.secrets), 300), }); } } catch (err) { throw errorFromThrown(http.ctx, err, http.abortReason()); } finally { http.cleanup(); } } /* ------------------------------------------------------------------ */ /* Server-sent events */ /* ------------------------------------------------------------------ */ export interface SSEMessage { /** Value of the `event:` field, when the server sent one. */ event?: string; /** All `data:` lines of the event joined with "\n". */ data: string; } export interface SSEOptions { /** Abort when no bytes arrive for this long. */ idleTimeoutMs?: number; onIdle?: () => void; } /** * Parses a text/event-stream body. Handles `\n`, `\r\n` and bare `\r` line * endings (also when split across chunks), multi-line `data:`, comment lines, * a UTF-8 BOM, and a final event that is not followed by a blank line. * Iteration ends at end-of-stream or at the OpenAI-style `data: [DONE]` sentinel. */ export async function* parseSSE(stream: ReadableStream, opts: SSEOptions = {}): AsyncGenerator { const reader = stream.getReader(); const decoder = new TextDecoder('utf-8'); let buffer = ''; let dataLines: string[] = []; let eventName: string | undefined; let sawCR = false; // previous chunk ended in "\r": swallow a leading "\n" let first = true; const takeLine = (line: string): SSEMessage | 'done' | null => { if (line === '') { // Blank line dispatches the event. if (dataLines.length === 0) { eventName = undefined; return null; } const msg: SSEMessage = { data: dataLines.join('\n') }; if (eventName !== undefined) msg.event = eventName; dataLines = []; eventName = undefined; return msg.data === '[DONE]' ? 'done' : msg; } if (line.startsWith(':')) return null; // comment / keep-alive const colon = line.indexOf(':'); const field = colon === -1 ? line : line.slice(0, colon); let value = colon === -1 ? '' : line.slice(colon + 1); if (value.startsWith(' ')) value = value.slice(1); if (field === 'data') dataLines.push(value); else if (field === 'event') eventName = value; // `id` and `retry` are irrelevant for one-shot completions. return null; }; try { for (;;) { const { done, value } = await readWithIdle(reader, opts); if (done) break; let chunk = decoder.decode(value, { stream: true }); if (first && chunk.length > 0) { first = false; if (chunk.charCodeAt(0) === 0xfeff) chunk = chunk.slice(1); } if (sawCR && chunk.startsWith('\n')) chunk = chunk.slice(1); if (chunk.length > 0) sawCR = chunk.endsWith('\r'); buffer += chunk; let start = 0; for (;;) { const idx = indexOfLineEnd(buffer, start); if (idx === -1) break; const line = buffer.slice(start, idx); start = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? idx + 2 : idx + 1; const out = takeLine(line); if (out === 'done') return; if (out) yield out; } buffer = buffer.slice(start); } // Flush: tolerate a last line / last event without the terminating newline(s). buffer += decoder.decode(); if (buffer.length > 0) { const out = takeLine(buffer); if (out === 'done') return; if (out) yield out; } const tail = takeLine(''); if (tail && tail !== 'done') yield tail; } finally { try { await reader.cancel(); } catch { /* already closed or errored */ } } } function indexOfLineEnd(s: string, from: number): number { for (let i = from; i < s.length; i++) { const c = s.charCodeAt(i); if (c === 10 || c === 13) return i; } return -1; } async function readWithIdle( reader: ReadableStreamDefaultReader, opts: SSEOptions, ): Promise['read']>>> { if (!opts.idleTimeoutMs) return reader.read(); let timer: ReturnType | undefined; const idle = new Promise((_resolve, reject) => { timer = setTimeout(() => { opts.onIdle?.(); const err = new Error('stream idle timeout'); err.name = 'TimeoutError'; reject(err); }, opts.idleTimeoutMs); }); try { return await Promise.race([reader.read(), idle]); } finally { clearTimeout(timer); } } /** * Iterates the SSE events of an open response, translating read failures * (dropped connection, abort, idle timeout) into AIErrors and always releasing * the request's timers. `data` is JSON-parsed; unparseable events are skipped. */ export async function* sseJson(http: HttpResponse, idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS): AsyncGenerator<{ event?: string; data: unknown }> { const body = http.response.body; if (!body) { http.cleanup(); throw new AIError('invalid_response', `${http.ctx.provider} returned an empty response.`); } const events = parseSSE(body, { idleTimeoutMs, onIdle: () => http.abort('timeout') }); try { for (;;) { let next: IteratorResult; try { next = await events.next(); } catch (err) { throw errorFromThrown(http.ctx, err, http.abortReason()); } if (next.done) return; let data: unknown; try { data = JSON.parse(next.value.data); } catch { continue; // keep-alives such as OpenRouter's ": OPENROUTER PROCESSING" variants, or junk } yield next.value.event !== undefined ? { event: next.value.event, data } : { data }; } } finally { await events.return(undefined).catch(() => undefined); http.cleanup(); } } /* ------------------------------------------------------------------ */ /* Small shared utilities */ /* ------------------------------------------------------------------ */ export function isRecord(v: unknown): v is Record { return typeof v === 'object' && v !== null && !Array.isArray(v); } function hasHeader(headers: Record, name: string): boolean { const n = name.toLowerCase(); return Object.keys(headers).some((k) => k.toLowerCase() === n); } function safeStringify(v: unknown): string { try { return JSON.stringify(v) ?? ''; } catch { return ''; } } /** Trims whitespace and trailing slashes from a base URL. */ export function trimBaseUrl(url: string): string { return url.trim().replace(/\/+$/, ''); } /** Host part of a URL for user-facing messages; never includes credentials or query. */ export function hostOf(url: string): string { try { return new URL(url).host; } catch { return url; } } /** True for loopback / private-network hosts, where a local model server may need minutes to load a model. */ export function isLocalUrl(url: string): boolean { try { const h = new URL(url).hostname.replace(/^\[|\]$/g, ''); return ( h === 'localhost' || h === '::1' || h.endsWith('.local') || h.endsWith('.internal') || /^127\./.test(h) || /^10\./.test(h) || /^192\.168\./.test(h) || /^172\.(1[6-9]|2\d|3[01])\./.test(h) || h === 'host.docker.internal' ); } catch { return false; } }