@j0hanz/superfetch 2.0.1 → 2.1.0

package/dist/fetch.js

@@ -0,0 +1,910 @@
+import { randomUUID } from 'node:crypto';
+import diagnosticsChannel from 'node:diagnostics_channel';
+import dns from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+import os from 'node:os';
+import { performance } from 'node:perf_hooks';
+import { Agent } from 'undici';
+import { config } from './config.js';
+import { createErrorWithCode, FetchError, isSystemError } from './errors.js';
+import { getOperationId, getRequestId, logDebug, logError, logWarn, redactUrl, } from './observability.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function buildIpv4(parts) {
+    return parts.join('.');
+}
+function buildIpv6(parts) {
+    return parts.map(String).join(':');
+}
+const BLOCK_LIST = new BlockList();
+const IPV6_ZERO = buildIpv6([0, 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_LOOPBACK = buildIpv6([0, 0, 0, 0, 0, 0, 0, 1]);
+const IPV6_64_FF9B = buildIpv6(['64', 'ff9b', 0, 0, 0, 0, 0, 0]);
+const IPV6_64_FF9B_1 = buildIpv6(['64', 'ff9b', 1, 0, 0, 0, 0, 0]);
+const IPV6_2001 = buildIpv6(['2001', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_2002 = buildIpv6(['2002', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FC00 = buildIpv6(['fc00', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FE80 = buildIpv6(['fe80', 0, 0, 0, 0, 0, 0, 0]);
+const IPV6_FF00 = buildIpv6(['ff00', 0, 0, 0, 0, 0, 0, 0]);
+const BLOCKED_IPV4_SUBNETS = [
+    { subnet: buildIpv4([0, 0, 0, 0]), prefix: 8 },
+    { subnet: buildIpv4([10, 0, 0, 0]), prefix: 8 },
+    { subnet: buildIpv4([100, 64, 0, 0]), prefix: 10 },
+    { subnet: buildIpv4([127, 0, 0, 0]), prefix: 8 },
+    { subnet: buildIpv4([169, 254, 0, 0]), prefix: 16 },
+    { subnet: buildIpv4([172, 16, 0, 0]), prefix: 12 },
+    { subnet: buildIpv4([192, 168, 0, 0]), prefix: 16 },
+    { subnet: buildIpv4([224, 0, 0, 0]), prefix: 4 },
+    { subnet: buildIpv4([240, 0, 0, 0]), prefix: 4 },
+];
+const BLOCKED_IPV6_SUBNETS = [
+    { subnet: IPV6_ZERO, prefix: 128 },
+    { subnet: IPV6_LOOPBACK, prefix: 128 },
+    { subnet: IPV6_64_FF9B, prefix: 96 },
+    { subnet: IPV6_64_FF9B_1, prefix: 48 },
+    { subnet: IPV6_2001, prefix: 32 },
+    { subnet: IPV6_2002, prefix: 16 },
+    { subnet: IPV6_FC00, prefix: 7 },
+    { subnet: IPV6_FE80, prefix: 10 },
+    { subnet: IPV6_FF00, prefix: 8 },
+];
+for (const entry of BLOCKED_IPV4_SUBNETS) {
+    BLOCK_LIST.addSubnet(entry.subnet, entry.prefix, 'ipv4');
+}
+for (const entry of BLOCKED_IPV6_SUBNETS) {
+    BLOCK_LIST.addSubnet(entry.subnet, entry.prefix, 'ipv6');
+}
+function matchesBlockedIpPatterns(resolvedIp) {
+    for (const pattern of config.security.blockedIpPatterns) {
+        if (pattern.test(resolvedIp)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function isBlockedIp(ip) {
+    if (config.security.blockedHosts.has(ip)) {
+        return true;
+    }
+    const ipType = resolveIpType(ip);
+    if (!ipType)
+        return false;
+    const normalizedIp = ip.toLowerCase();
+    if (isBlockedByList(normalizedIp, ipType))
+        return true;
+    return matchesBlockedIpPatterns(normalizedIp);
+}
+function resolveIpType(ip) {
+    const ipType = isIP(ip);
+    return ipType === 4 || ipType === 6 ? ipType : null;
+}
+function isBlockedByList(ip, ipType) {
+    if (ipType === 4) {
+        return BLOCK_LIST.check(ip, 'ipv4');
+    }
+    return BLOCK_LIST.check(ip, 'ipv6');
+}
+export function normalizeUrl(urlString) {
+    const trimmedUrl = requireTrimmedUrl(urlString);
+    assertUrlLength(trimmedUrl);
+    const url = parseUrl(trimmedUrl);
+    assertHttpProtocol(url);
+    assertNoCredentials(url);
+    const hostname = normalizeHostname(url);
+    assertHostnameAllowed(hostname);
+    // Canonicalize hostname to avoid trailing-dot variants and keep url.href consistent.
+    url.hostname = hostname;
+    return { normalizedUrl: url.href, hostname };
+}
+export function validateAndNormalizeUrl(urlString) {
+    return normalizeUrl(urlString).normalizedUrl;
+}
+const VALIDATION_ERROR_CODE = 'VALIDATION_ERROR';
+function createValidationError(message) {
+    return createErrorWithCode(message, VALIDATION_ERROR_CODE);
+}
+function requireTrimmedUrl(urlString) {
+    if (!urlString || typeof urlString !== 'string') {
+        throw createValidationError('URL is required');
+    }
+    const trimmedUrl = urlString.trim();
+    if (!trimmedUrl) {
+        throw createValidationError('URL cannot be empty');
+    }
+    return trimmedUrl;
+}
+function assertUrlLength(url) {
+    if (url.length <= config.constants.maxUrlLength)
+        return;
+    throw createValidationError(`URL exceeds maximum length of ${config.constants.maxUrlLength} characters`);
+}
+function parseUrl(urlString) {
+    if (!URL.canParse(urlString)) {
+        throw createValidationError('Invalid URL format');
+    }
+    return new URL(urlString);
+}
+function assertHttpProtocol(url) {
+    if (url.protocol === 'http:' || url.protocol === 'https:')
+        return;
+    throw createValidationError(`Invalid protocol: ${url.protocol}. Only http: and https: are allowed`);
+}
+function assertNoCredentials(url) {
+    if (!url.username && !url.password)
+        return;
+    throw createValidationError('URLs with embedded credentials are not allowed');
+}
+function normalizeHostname(url) {
+    let hostname = url.hostname.toLowerCase();
+    while (hostname.endsWith('.')) {
+        hostname = hostname.slice(0, -1);
+    }
+    if (!hostname) {
+        throw createValidationError('URL must have a valid hostname');
+    }
+    return hostname;
+}
+const BLOCKED_HOST_SUFFIXES = ['.local', '.internal'];
+function assertHostnameAllowed(hostname) {
+    assertNotBlockedHost(hostname);
+    assertNotBlockedIp(hostname);
+    assertNotBlockedHostnameSuffix(hostname);
+}
+function assertNotBlockedHost(hostname) {
+    if (!config.security.blockedHosts.has(hostname))
+        return;
+    throw createValidationError(`Blocked host: ${hostname}. Internal hosts are not allowed`);
+}
+function assertNotBlockedIp(hostname) {
+    if (!isBlockedIp(hostname))
+        return;
+    throw createValidationError(`Blocked IP range: ${hostname}. Private IPs are not allowed`);
+}
+function assertNotBlockedHostnameSuffix(hostname) {
+    if (!matchesBlockedSuffix(hostname))
+        return;
+    throw createValidationError(`Blocked hostname pattern: ${hostname}. Internal domain suffixes are not allowed`);
+}
+function matchesBlockedSuffix(hostname) {
+    return BLOCKED_HOST_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
+}
+const GITHUB_BLOB_RULE = {
+    name: 'github',
+    pattern: /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/i,
+    transform: (match) => {
+        const owner = match[1] ?? '';
+        const repo = match[2] ?? '';
+        const branch = match[3] ?? '';
+        const path = match[4] ?? '';
+        return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+    },
+};
+const GITHUB_GIST_RULE = {
+    name: 'github-gist',
+    pattern: /^https?:\/\/gist\.github\.com\/([^/]+)\/([a-f0-9]+)(?:#file-(.+)|\/raw\/([^/]+))?$/i,
+    transform: (match) => {
+        const user = match[1] ?? '';
+        const gistId = match[2] ?? '';
+        const hashFile = match[3];
+        const rawFile = match[4];
+        const filename = rawFile ?? hashFile?.replace(/-/g, '.');
+        const filePath = filename ? `/${filename}` : '';
+        return `https://gist.githubusercontent.com/${user}/${gistId}/raw${filePath}`;
+    },
+};
+const GITLAB_BLOB_RULE = {
+    name: 'gitlab',
+    pattern: /^(https?:\/\/(?:[^/]+\.)?gitlab\.com\/[^/]+\/[^/]+)\/-\/blob\/([^/]+)\/(.+)$/i,
+    transform: (match) => {
+        const baseUrl = match[1] ?? '';
+        const branch = match[2] ?? '';
+        const path = match[3] ?? '';
+        return `${baseUrl}/-/raw/${branch}/${path}`;
+    },
+};
+const BITBUCKET_SRC_RULE = {
+    name: 'bitbucket',
+    pattern: /^(https?:\/\/(?:www\.)?bitbucket\.org\/[^/]+\/[^/]+)\/src\/([^/]+)\/(.+)$/i,
+    transform: (match) => {
+        const baseUrl = match[1] ?? '';
+        const branch = match[2] ?? '';
+        const path = match[3] ?? '';
+        return `${baseUrl}/raw/${branch}/${path}`;
+    },
+};
+const TRANSFORM_RULES = [
+    GITHUB_BLOB_RULE,
+    GITHUB_GIST_RULE,
+    GITLAB_BLOB_RULE,
+    BITBUCKET_SRC_RULE,
+];
+function isRawUrl(url) {
+    const lowerUrl = url.toLowerCase();
+    return (lowerUrl.includes('raw.githubusercontent.com') ||
+        lowerUrl.includes('gist.githubusercontent.com') ||
+        lowerUrl.includes('/-/raw/') ||
+        /bitbucket\.org\/[^/]+\/[^/]+\/raw\//.test(lowerUrl));
+}
+function getUrlWithoutParams(url) {
+    const hashIndex = url.indexOf('#');
+    const queryIndex = url.indexOf('?');
+    let endIndex = url.length;
+    if (queryIndex !== -1) {
+        if (hashIndex !== -1) {
+            endIndex = Math.min(queryIndex, hashIndex);
+        }
+        else {
+            endIndex = queryIndex;
+        }
+    }
+    else if (hashIndex !== -1) {
+        endIndex = hashIndex;
+    }
+    const hash = hashIndex !== -1 ? url.slice(hashIndex) : '';
+    return {
+        base: url.slice(0, endIndex),
+        hash,
+    };
+}
+function resolveUrlToMatch(rule, base, hash) {
+    if (rule.name !== 'github-gist')
+        return base;
+    if (!hash.startsWith('#file-'))
+        return base;
+    return base + hash;
+}
+function applyTransformRules(base, hash) {
+    for (const rule of TRANSFORM_RULES) {
+        const urlToMatch = resolveUrlToMatch(rule, base, hash);
+        const match = rule.pattern.exec(urlToMatch);
+        if (match) {
+            return { url: rule.transform(match), platform: rule.name };
+        }
+    }
+    return null;
+}
+export function transformToRawUrl(url) {
+    if (!url)
+        return { url, transformed: false };
+    if (isRawUrl(url)) {
+        return { url, transformed: false };
+    }
+    const { base, hash } = getUrlWithoutParams(url);
+    const result = applyTransformRules(base, hash);
+    if (!result)
+        return { url, transformed: false };
+    logDebug('URL transformed to raw content URL', {
+        platform: result.platform,
+        original: url.substring(0, 100),
+        transformed: result.url.substring(0, 100),
+    });
+    return {
+        url: result.url,
+        transformed: true,
+        platform: result.platform,
+    };
+}
+const RAW_TEXT_EXTENSIONS = new Set([
+    '.md',
+    '.markdown',
+    '.txt',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.toml',
+    '.xml',
+    '.csv',
+    '.rst',
+    '.adoc',
+    '.org',
+]);
+export function isRawTextContentUrl(url) {
+    if (!url)
+        return false;
+    if (isRawUrl(url))
+        return true;
+    const { base } = getUrlWithoutParams(url);
+    const lowerBase = base.toLowerCase();
+    return hasKnownRawTextExtension(lowerBase);
+}
+function hasKnownRawTextExtension(urlBaseLower) {
+    for (const ext of RAW_TEXT_EXTENSIONS) {
+        if (urlBaseLower.endsWith(ext))
+            return true;
+    }
+    return false;
+}
+const DNS_LOOKUP_TIMEOUT_MS = 5000;
+function normalizeLookupResults(addresses, family) {
+    if (Array.isArray(addresses)) {
+        return addresses;
+    }
+    return [{ address: addresses, family: family ?? 4 }];
+}
+function findBlockedIpError(list, hostname) {
+    for (const addr of list) {
+        const ip = typeof addr === 'string' ? addr : addr.address;
+        if (!isBlockedIp(ip)) {
+            continue;
+        }
+        return createErrorWithCode(`Blocked IP detected for ${hostname}`, 'EBLOCKED');
+    }
+    return null;
+}
+function findInvalidFamilyError(list, hostname) {
+    for (const addr of list) {
+        const family = typeof addr === 'string' ? 0 : addr.family;
+        if (family === 4 || family === 6)
+            continue;
+        return createErrorWithCode(`Invalid address family returned for ${hostname}`, 'EINVAL');
+    }
+    return null;
+}
+function createNoDnsResultsError(hostname) {
+    return createErrorWithCode(`No DNS results returned for ${hostname}`, 'ENODATA');
+}
+function createEmptySelection(hostname) {
+    return {
+        error: createNoDnsResultsError(hostname),
+        fallback: [],
+        address: [],
+    };
+}
+function selectLookupResult(list, useAll, hostname) {
+    if (list.length === 0)
+        return createEmptySelection(hostname);
+    if (useAll)
+        return { address: list, fallback: list };
+    const first = list.at(0);
+    if (!first)
+        return createEmptySelection(hostname);
+    return {
+        address: first.address,
+        family: first.family,
+        fallback: list,
+    };
+}
+function findLookupError(list, hostname) {
+    return (findInvalidFamilyError(list, hostname) ?? findBlockedIpError(list, hostname));
+}
+function handleLookupResult(error, addresses, hostname, resolvedFamily, useAll, callback) {
+    if (error) {
+        callback(error, addresses);
+        return;
+    }
+    const list = normalizeLookupResults(addresses, resolvedFamily);
+    const lookupError = findLookupError(list, hostname);
+    if (lookupError) {
+        callback(lookupError, list);
+        return;
+    }
+    const selection = selectLookupResult(list, useAll, hostname);
+    if (selection.error) {
+        callback(selection.error, selection.fallback);
+        return;
+    }
+    callback(null, selection.address, selection.family);
+}
+function resolveDns(hostname, options, callback) {
+    const { normalizedOptions, useAll, resolvedFamily } = buildLookupContext(options);
+    const lookupOptions = buildLookupOptions(normalizedOptions);
+    const timeout = createLookupTimeout(hostname, callback);
+    const safeCallback = wrapLookupCallback(callback, timeout);
+    dns.lookup(hostname, lookupOptions, createLookupCallback(hostname, resolvedFamily, useAll, safeCallback));
+}
+function normalizeLookupOptions(options) {
+    return typeof options === 'number' ? { family: options } : options;
+}
+function buildLookupContext(options) {
+    const normalizedOptions = normalizeLookupOptions(options);
+    return {
+        normalizedOptions,
+        useAll: Boolean(normalizedOptions.all),
+        resolvedFamily: resolveFamily(normalizedOptions.family),
+    };
+}
+const DEFAULT_DNS_ORDER = 'verbatim';
+function resolveResultOrder(options) {
+    if (options.order)
+        return options.order;
+    const legacyVerbatim = getLegacyVerbatim(options);
+    if (legacyVerbatim !== undefined) {
+        return legacyVerbatim ? 'verbatim' : 'ipv4first';
+    }
+    return DEFAULT_DNS_ORDER;
+}
+function getLegacyVerbatim(options) {
+    if (isRecord(options)) {
+        const { verbatim } = options;
+        return typeof verbatim === 'boolean' ? verbatim : undefined;
+    }
+    return undefined;
+}
+function buildLookupOptions(normalizedOptions) {
+    return {
+        family: normalizedOptions.family,
+        hints: normalizedOptions.hints,
+        all: true,
+        order: resolveResultOrder(normalizedOptions),
+    };
+}
+function createLookupCallback(hostname, resolvedFamily, useAll, callback) {
+    return (err, addresses) => {
+        handleLookupResult(err, addresses, hostname, resolvedFamily, useAll, callback);
+    };
+}
+function resolveFamily(family) {
+    if (family === 'IPv4')
+        return 4;
+    if (family === 'IPv6')
+        return 6;
+    return family;
+}
+function createLookupTimeout(hostname, callback) {
+    let done = false;
+    const timer = setTimeout(() => {
+        if (done)
+            return;
+        done = true;
+        callback(createErrorWithCode(`DNS lookup timed out for ${hostname}`, 'ETIMEOUT'), []);
+    }, DNS_LOOKUP_TIMEOUT_MS);
+    timer.unref();
+    return {
+        isDone: () => done,
+        markDone: () => {
+            done = true;
+            clearTimeout(timer);
+        },
+    };
+}
+function wrapLookupCallback(callback, timeout) {
+    return (err, address, family) => {
+        if (timeout.isDone())
+            return;
+        timeout.markDone();
+        callback(err, address, family);
+    };
+}
+function getAgentOptions() {
+    const cpuCount = os.availableParallelism();
+    return {
+        keepAliveTimeout: 60000,
+        connections: Math.max(cpuCount * 2, 25),
+        pipelining: 1,
+        connect: { lookup: resolveDns },
+    };
+}
+export const dispatcher = new Agent(getAgentOptions());
+export function destroyAgents() {
+    void dispatcher.close();
+}
+function parseRetryAfter(header) {
+    if (!header)
+        return 60;
+    const parsed = parseInt(header, 10);
+    return Number.isNaN(parsed) ? 60 : parsed;
+}
+function createCanceledError(url) {
+    return new FetchError('Request was canceled', url, 499, {
+        reason: 'aborted',
+    });
+}
+function createTimeoutError(url, timeoutMs) {
+    return new FetchError(`Request timeout after ${timeoutMs}ms`, url, 504, {
+        timeout: timeoutMs,
+    });
+}
+function createRateLimitError(url, headerValue) {
+    const retryAfter = parseRetryAfter(headerValue);
+    return new FetchError('Too many requests', url, 429, { retryAfter });
+}
+function createHttpError(url, status, statusText) {
+    return new FetchError(`HTTP ${status}: ${statusText}`, url, status);
+}
+function createNetworkError(url, message) {
+    const details = message ? { message } : undefined;
+    return new FetchError(`Network error: Could not reach ${url}`, url, undefined, details ?? {});
+}
+function createUnknownError(url, message) {
+    return new FetchError(message, url);
+}
+function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === 'AbortError' || error.name === 'TimeoutError'));
+}
+function isTimeoutError(error) {
+    return error instanceof Error && error.name === 'TimeoutError';
+}
+function getRequestUrl(record) {
+    const value = record.requestUrl;
+    return typeof value === 'string' ? value : null;
+}
+function resolveErrorUrl(error, fallback) {
+    if (error instanceof FetchError)
+        return error.url;
+    if (!isRecord(error))
+        return fallback;
+    const requestUrl = getRequestUrl(error);
+    if (requestUrl)
+        return requestUrl;
+    return fallback;
+}
+function mapFetchError(error, fallbackUrl, timeoutMs) {
+    if (error instanceof FetchError)
+        return error;
+    const url = resolveErrorUrl(error, fallbackUrl);
+    if (isAbortError(error)) {
+        if (isTimeoutError(error)) {
+            return createTimeoutError(url, timeoutMs);
+        }
+        return createCanceledError(url);
+    }
+    if (error instanceof Error) {
+        return createNetworkError(url, error.message);
+    }
+    return createUnknownError(url, 'Unexpected error');
+}
+const fetchChannel = diagnosticsChannel.channel('superfetch.fetch');
+function publishFetchEvent(event) {
+    if (!fetchChannel.hasSubscribers)
+        return;
+    try {
+        fetchChannel.publish(event);
+    }
+    catch {
+        // Avoid crashing the publisher if a subscriber throws.
+    }
+}
+export function startFetchTelemetry(url, method) {
+    const safeUrl = redactUrl(url);
+    const contextRequestId = getRequestId();
+    const operationId = getOperationId();
+    const context = {
+        requestId: randomUUID(),
+        startTime: performance.now(),
+        url: safeUrl,
+        method: method.toUpperCase(),
+        ...(contextRequestId ? { contextRequestId } : {}),
+        ...(operationId ? { operationId } : {}),
+    };
+    publishFetchEvent({
+        v: 1,
+        type: 'start',
+        requestId: context.requestId,
+        method: context.method,
+        url: context.url,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+    });
+    logDebug('HTTP Request', {
+        requestId: context.requestId,
+        method: context.method,
+        url: context.url,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+    });
+    return context;
+}
+export function recordFetchResponse(context, response, contentSize) {
+    const duration = performance.now() - context.startTime;
+    const durationLabel = `${Math.round(duration)}ms`;
+    publishFetchEvent({
+        v: 1,
+        type: 'end',
+        requestId: context.requestId,
+        status: response.status,
+        duration,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+    });
+    const contentType = response.headers.get('content-type');
+    const contentLength = response.headers.get('content-length') ??
+        (contentSize === undefined ? undefined : String(contentSize));
+    logDebug('HTTP Response', {
+        requestId: context.requestId,
+        status: response.status,
+        url: context.url,
+        duration: durationLabel,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+        ...(contentType ? { contentType } : {}),
+        ...(contentLength ? { size: contentLength } : {}),
+    });
+    if (duration > 5000) {
+        logWarn('Slow HTTP request detected', {
+            requestId: context.requestId,
+            url: context.url,
+            duration: durationLabel,
+            ...(context.contextRequestId
+                ? { contextRequestId: context.contextRequestId }
+                : {}),
+            ...(context.operationId ? { operationId: context.operationId } : {}),
+        });
+    }
+}
+export function recordFetchError(context, error, status) {
+    const duration = performance.now() - context.startTime;
+    const err = error instanceof Error ? error : new Error(String(error));
+    const event = {
+        v: 1,
+        type: 'error',
+        requestId: context.requestId,
+        url: context.url,
+        error: err.message,
+        duration,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+    };
+    const code = isSystemError(err) ? err.code : undefined;
+    if (code !== undefined) {
+        event.code = code;
+    }
+    if (status !== undefined) {
+        event.status = status;
+    }
+    publishFetchEvent(event);
+    const log = status === 429 ? logWarn : logError;
+    log('HTTP Request Error', {
+        requestId: context.requestId,
+        url: context.url,
+        status,
+        code,
+        error: err.message,
+        ...(context.contextRequestId
+            ? { contextRequestId: context.contextRequestId }
+            : {}),
+        ...(context.operationId ? { operationId: context.operationId } : {}),
+    });
+}
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function isRedirectStatus(status) {
+    return REDIRECT_STATUSES.has(status);
+}
+function cancelResponseBody(response) {
+    const cancelPromise = response.body?.cancel();
+    if (cancelPromise) {
+        cancelPromise.catch(() => {
+            // Best-effort cancellation; ignore failures.
+        });
+    }
+}
+async function performFetchCycle(currentUrl, init, redirectLimit, redirectCount) {
+    const response = await fetch(currentUrl, { ...init, redirect: 'manual' });
+    if (!isRedirectStatus(response.status)) {
+        return { response };
+    }
+    assertRedirectWithinLimit(response, currentUrl, redirectLimit, redirectCount);
+    const location = getRedirectLocation(response, currentUrl);
+    cancelResponseBody(response);
+    return {
+        response,
+        nextUrl: resolveRedirectTarget(currentUrl, location),
+    };
+}
+function assertRedirectWithinLimit(response, currentUrl, redirectLimit, redirectCount) {
+    if (redirectCount < redirectLimit)
+        return;
+    cancelResponseBody(response);
+    throw new FetchError('Too many redirects', currentUrl);
+}
+function getRedirectLocation(response, currentUrl) {
+    const location = response.headers.get('location');
+    if (location)
+        return location;
+    cancelResponseBody(response);
+    throw new FetchError('Redirect response missing Location header', currentUrl);
+}
+function annotateRedirectError(error, url) {
+    if (!isRecord(error))
+        return;
+    error.requestUrl = url;
+}
+function resolveRedirectTarget(baseUrl, location) {
+    if (!URL.canParse(location, baseUrl)) {
+        throw createErrorWithCode('Invalid redirect target', 'EBADREDIRECT');
+    }
+    const resolved = new URL(location, baseUrl);
+    if (resolved.username || resolved.password) {
+        throw createErrorWithCode('Redirect target includes credentials', 'EBADREDIRECT');
+    }
+    return validateAndNormalizeUrl(resolved.href);
+}
+export async function fetchWithRedirects(url, init, maxRedirects) {
+    let currentUrl = url;
+    const redirectLimit = Math.max(0, maxRedirects);
+    for (let redirectCount = 0; redirectCount <= redirectLimit; redirectCount += 1) {
+        const { response, nextUrl } = await performFetchCycleSafely(currentUrl, init, redirectLimit, redirectCount);
+        if (!nextUrl) {
+            return { response, url: currentUrl };
+        }
+        currentUrl = nextUrl;
+    }
+    throw new FetchError('Too many redirects', currentUrl);
+}
+async function performFetchCycleSafely(currentUrl, init, redirectLimit, redirectCount) {
+    try {
+        return await performFetchCycle(currentUrl, init, redirectLimit, redirectCount);
+    }
+    catch (error) {
+        annotateRedirectError(error, currentUrl);
+        throw error;
+    }
+}
+function assertContentLengthWithinLimit(response, url, maxBytes) {
+    const contentLengthHeader = response.headers.get('content-length');
+    if (!contentLengthHeader)
+        return;
+    const contentLength = Number.parseInt(contentLengthHeader, 10);
+    if (Number.isNaN(contentLength) || contentLength <= maxBytes) {
+        return;
+    }
+    cancelResponseBody(response);
+    throw new FetchError(`Response exceeds maximum size of ${maxBytes} bytes`, url);
+}
+function createReadState() {
+    return {
+        decoder: new TextDecoder(),
+        parts: [],
+        total: 0,
+    };
+}
+function appendChunk(state, chunk, maxBytes, url) {
+    state.total += chunk.byteLength;
+    if (state.total > maxBytes) {
+        throw new FetchError(`Response exceeds maximum size of ${maxBytes} bytes`, url);
+    }
+    const decoded = state.decoder.decode(chunk, { stream: true });
+    if (decoded)
+        state.parts.push(decoded);
+}
+function finalizeRead(state) {
+    const decoded = state.decoder.decode();
+    if (decoded)
+        state.parts.push(decoded);
+}
+function createAbortError(url) {
+    return new FetchError('Request was aborted during response read', url, 499, {
+        reason: 'aborted',
+    });
+}
+async function cancelReaderQuietly(reader) {
+    try {
+        await reader.cancel();
+    }
+    catch {
+        // Ignore cancel errors; we're already failing this read.
+    }
+}
+async function throwIfAborted(signal, url, reader) {
+    if (!signal?.aborted)
+        return;
+    await cancelReaderQuietly(reader);
+    throw createAbortError(url);
+}
+async function handleReadFailure(error, signal, url, reader) {
+    const aborted = signal?.aborted ?? false;
+    await cancelReaderQuietly(reader);
+    if (aborted) {
+        throw createAbortError(url);
+    }
+    throw error;
+}
+async function readAllChunks(reader, state, url, maxBytes, signal) {
+    await throwIfAborted(signal, url, reader);
+    let result = await reader.read();
+    while (!result.done) {
+        appendChunk(state, result.value, maxBytes, url);
+        await throwIfAborted(signal, url, reader);
+        result = await reader.read();
+    }
+}
+async function readStreamWithLimit(stream, url, maxBytes, signal) {
+    const state = createReadState();
+    const reader = stream.getReader();
+    try {
+        await readAllChunks(reader, state, url, maxBytes, signal);
+    }
+    catch (error) {
+        await handleReadFailure(error, signal, url, reader);
+    }
+    finally {
+        reader.releaseLock();
+    }
+    finalizeRead(state);
+    return { text: state.parts.join(''), size: state.total };
+}
+export async function readResponseText(response, url, maxBytes, signal) {
+    assertContentLengthWithinLimit(response, url, maxBytes);
+    if (!response.body) {
+        const text = await response.text();
+        const size = Buffer.byteLength(text);
+        if (size > maxBytes) {
+            throw new FetchError(`Response exceeds maximum size of ${maxBytes} bytes`, url);
+        }
+        return { text, size };
+    }
+    return readStreamWithLimit(response.body, url, maxBytes, signal);
+}
+const DEFAULT_HEADERS = {
+    'User-Agent': config.fetcher.userAgent,
+    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+    'Accept-Language': 'en-US,en;q=0.5',
+    'Accept-Encoding': 'gzip, deflate, br',
+    Connection: 'keep-alive',
+};
+function buildHeaders() {
+    return { ...DEFAULT_HEADERS };
+}
+function buildRequestSignal(timeoutMs, external) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (!external)
+        return timeoutSignal;
+    return AbortSignal.any([external, timeoutSignal]);
+}
+function buildRequestInit(headers, signal) {
+    return {
+        method: 'GET',
+        headers,
+        signal,
+        dispatcher,
+    };
+}
+function resolveResponseError(response, finalUrl) {
+    return (resolveRateLimitError(response, finalUrl) ??
+        resolveHttpError(response, finalUrl));
+}
+function resolveRateLimitError(response, finalUrl) {
+    return response.status === 429
+        ? createRateLimitError(finalUrl, response.headers.get('retry-after'))
+        : null;
+}
+function resolveHttpError(response, finalUrl) {
+    return response.ok
+        ? null
+        : createHttpError(finalUrl, response.status, response.statusText);
+}
+async function handleFetchResponse(response, finalUrl, telemetry, signal) {
+    const responseError = resolveResponseError(response, finalUrl);
+    if (responseError) {
+        cancelResponseBody(response);
+        throw responseError;
+    }
+    const { text, size } = await readResponseText(response, finalUrl, config.fetcher.maxContentLength, signal);
+    recordFetchResponse(telemetry, response, size);
+    return text;
+}
+async function fetchWithTelemetry(normalizedUrl, requestInit, timeoutMs) {
+    const telemetry = startFetchTelemetry(normalizedUrl, 'GET');
+    try {
+        return await fetchAndHandle(normalizedUrl, requestInit, telemetry);
+    }
+    catch (error) {
+        const mapped = mapFetchError(error, normalizedUrl, timeoutMs);
+        telemetry.url = mapped.url;
+        recordFetchError(telemetry, mapped, mapped.statusCode);
+        throw mapped;
+    }
+}
+async function fetchAndHandle(normalizedUrl, requestInit, telemetry) {
+    const { response, url: finalUrl } = await fetchWithRedirects(normalizedUrl, requestInit, config.fetcher.maxRedirects);
+    telemetry.url = finalUrl;
+    return handleFetchResponse(response, finalUrl, telemetry, requestInit.signal ?? undefined);
+}
+export async function fetchNormalizedUrl(normalizedUrl, options) {
+    const timeoutMs = config.fetcher.timeout;
+    const headers = buildHeaders();
+    const signal = buildRequestSignal(timeoutMs, options?.signal);
+    const requestInit = buildRequestInit(headers, signal);
+    return fetchWithTelemetry(normalizedUrl, requestInit, timeoutMs);
+}