Study/server/ai/providers/http.ts
Elijah 25bc03ea75
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 29s
Fourth revision: OpenRouter, live tool stages, Explain layout, share sections
- Interactive blocks are encouraged by default; Explain gets a reduced library
  and never writes practice questions.
- Assistant tool steps breathe while running, show live stages from generation
  and the Python check, and read in the past tense when done.
- The assistant asks before searching the web when class materials do not
  cover a question; clarifying questions list every class's exams and never
  ask about format (always NCLEX).
- Explain opens beside the question from 900px wide, moving the question left
  while open and back on the next one.
- Generate dialog drops the practice set/exam switch (presets cover it) and the
  Generate buttons lose their icon.
- Python check notes are green when every check passed, applied fixes neutral.
- Share pages group by exam, then Quizzes, Flashcards, Notes, Class Materials,
  hiding empty groups; the class page uses the same order. "Documents" is now
  "Class Materials".
- OpenRouter provider replaces the Ollama type; migration 6 turns Ollama
  connections into OpenAI-compatible ones at /v1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 21:54:39 -07:00

519 lines
20 KiB
TypeScript

/**
* 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 | null | undefined> = []): 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", "OpenRouter"). */
provider: string;
/** Values that must never appear in an error (API key, custom header values). */
secrets?: Array<string | null | undefined>;
}
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<string, string>;
/** 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<HttpResponse> {
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<string, string> = { ...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<void> {
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<T = unknown>(url: string, opts: HttpOptions): Promise<T> {
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<Uint8Array>, opts: SSEOptions = {}): AsyncGenerator<SSEMessage> {
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<Uint8Array>,
opts: SSEOptions,
): Promise<Awaited<ReturnType<ReadableStreamDefaultReader<Uint8Array>['read']>>> {
if (!opts.idleTimeoutMs) return reader.read();
let timer: ReturnType<typeof setTimeout> | undefined;
const idle = new Promise<never>((_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<SSEMessage>;
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<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v);
}
function hasHeader(headers: Record<string, string>, 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;
}
}