@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/proxy-telemetry.ts

@@ -1,48 +1,155 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyUserAgentSource,
+	ProxyVendorFailoverTelemetryEvent,
+	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
+import {
+	closedEnum,
+	RequestTelemetry,
+	type ClosedEnum,
+	type TelemetryContributor,
+} from "./request-telemetry.js";
+import { createTraceContext } from "./trace.js";
 
-export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
-
-type ProviderTelemetryHeader = {
-	v: 1;
-	proxy?: {
-		provider: "smartproxy";
-		cacheStatus: ProxyCacheStatus;
-		cacheHit: boolean;
-		resolutionMs: number;
-		allocatorMs?: number;
-		allocatorStatus?: number;
-		allocatorBodyClass?: SmartproxyAllocatorBodyClass;
-		allocatorAttempts?: number;
-		lockWaitMs?: number;
-		redisReadMs?: number;
-		redisWriteMs?: number;
-		poolAgeMs?: number;
-		poolExpiresInMs?: number;
-		attempts: number;
-		refreshes?: number;
-		attemptSamples?: CompactProxyAttemptSample[];
-	};
+export { PROVIDER_TELEMETRY_HEADER } from "./request-telemetry.js";
+
+declare const PROXY_HASH: unique symbol;
+/** Bounded hexadecimal host hash used in proxy attempt samples. */
+export type ProxyHash = ClosedEnum<string> & { readonly [PROXY_HASH]: true };
+
+export type ProxyTelemetryResolvedPayload = {
+	kind: "resolved";
+	provider: ProxyVendorName;
+	userAgentSource?: ProxyUserAgentSource;
+	protocol?: ProxyProtocol;
+	cacheStatus: ProxyCacheStatus;
+	cacheHit: boolean;
+	resolutionMs: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts: number;
+	refreshes?: number;
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: string;
+		o: ProxyAttemptTelemetryEvent["outcome"];
+		c?: string;
+		s?: number;
+		d?: number;
+	}[];
+	/** Distinct vendors attempted across the resolution chain, in order seen. */
+	vendors?: ProxyVendorName[];
+	/** Cross-vendor failover events (bounded). */
+	failovers?: {
+		v: ProxyVendorName;
+		nx?: ProxyVendorName;
+		p: ProxyVendorFailoverTelemetryEvent["phase"];
+		r: ProxyVendorFailoverTelemetryEvent["reason"];
+		a?: number;
+	}[];
 };
 
-type CompactProxyAttemptSample = {
-	n: number;
-	a: number;
-	i?: number;
-	h?: string;
-	o: "ok" | "error";
-	c?: string;
-	s?: number;
-	d?: number;
+export type ProxyTelemetryUnresolvedPayload = {
+	kind: "unresolved";
+	/** Distinct vendors that failed resolution or recorded a failover, in order seen. */
+	vendors: ProxyVendorName[];
+	cacheStatus?: ProxyCacheStatus;
+	cacheHit?: boolean;
+	resolutionMs?: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts?: number;
+	refreshes?: number;
+	failovers?: {
+		v: ProxyVendorName;
+		nx?: ProxyVendorName;
+		p: ProxyVendorFailoverTelemetryEvent["phase"];
+		r: ProxyVendorFailoverTelemetryEvent["reason"];
+		a?: number;
+	}[];
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: string;
+		o: ProxyAttemptTelemetryEvent["outcome"];
+		c?: string;
+		s?: number;
+		d?: number;
+	}[];
+};
+
+export type ProxyTelemetryLogPayload =
+	| ProxyTelemetryResolvedPayload
+	| ProxyTelemetryUnresolvedPayload;
+
+/** Concrete gateway-safe projection of the unchanged proxy sibling. */
+export type ProxyTelemetryHeaderPayload = {
+	kind: ClosedEnum<"resolved" | "unresolved">;
+	provider?: ClosedEnum<ProxyVendorName>;
+	userAgentSource?: ClosedEnum<ProxyUserAgentSource>;
+	protocol?: ClosedEnum<ProxyProtocol>;
+	cacheStatus?: ClosedEnum<ProxyCacheStatus>;
+	cacheHit?: boolean;
+	resolutionMs?: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: ClosedEnum<SmartproxyAllocatorBodyClass>;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts?: number;
+	refreshes?: number;
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: ProxyHash;
+		o: ClosedEnum<ProxyAttemptTelemetryEvent["outcome"]>;
+		c?: ClosedEnum<string>;
+		s?: number;
+		d?: number;
+	}[];
+	vendors?: ClosedEnum<ProxyVendorName>[];
+	failovers?: {
+		v: ClosedEnum<ProxyVendorName>;
+		nx?: ClosedEnum<ProxyVendorName>;
+		p: ClosedEnum<ProxyVendorFailoverTelemetryEvent["phase"]>;
+		r: ClosedEnum<ProxyVendorFailoverTelemetryEvent["reason"]>;
+		a?: number;
+	}[];
 };
 
-const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
+const MAX_RETAINED_PROXY_RESOLUTIONS = 64;
+const PROXY_HEADER_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+const PROXY_HEADER_HASH = /^[0-9a-f]{1,16}$/;
 
 const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
 	disabled: 0,
@@ -69,17 +176,52 @@ function worseStatus(left: ProxyCacheStatus, right: ProxyCacheStatus): ProxyCach
 	return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
 
-function encodeBase64Url(value: string): string {
-	return Buffer.from(value, "utf8").toString("base64url");
+function aggregateResolution(
+	acc: ProxyResolutionTelemetryEvent,
+	event: ProxyResolutionTelemetryEvent,
+): ProxyResolutionTelemetryEvent {
+	return {
+		provider: event.provider,
+		userAgentSource: event.userAgentSource ?? acc.userAgentSource,
+		cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+		cacheHit: acc.cacheHit && event.cacheHit,
+		resolutionMs: acc.resolutionMs + event.resolutionMs,
+		allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+		allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+		allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+		allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
+		lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+		redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+		redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+		poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+		poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
+		attempts: acc.attempts + event.attempts,
+		refreshes: sumOptional(acc.refreshes, event.refreshes),
+	};
 }
 
-export class ProxyTelemetryCollector implements ProxyTelemetrySink {
+export class ProxyTelemetryCollector
+	implements
+		ProxyTelemetrySink,
+		TelemetryContributor<ProxyTelemetryLogPayload, ProxyTelemetryHeaderPayload>
+{
+	readonly key = "proxy" as const;
 	#events: ProxyResolutionTelemetryEvent[] = [];
+	#resolutionCount = 0;
+	#aggregateResolution: ProxyResolutionTelemetryEvent | undefined;
+	#lastSuccessfulResolution: ProxyResolutionTelemetryEvent | undefined;
+	#vendors: ProxyVendorName[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
+	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
+	#unresolvedVendors: ProxyVendorName[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
-		this.#events.push({
-			provider: "smartproxy",
+		const outcome = event.outcome === "error" ? "error" : "ok";
+		const normalized: ProxyResolutionTelemetryEvent = {
+			provider: event.provider,
+			outcome,
+			...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
+			...(event.protocol ? { protocol: event.protocol } : {}),
 			cacheStatus: event.cacheStatus,
 			cacheHit: event.cacheHit,
 			resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
@@ -109,13 +251,47 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			attempts: Math.max(1, Math.floor(event.attempts || 1)),
 			refreshes:
 				event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
+		};
+		this.#resolutionCount += 1;
+		if (this.#events.length < MAX_RETAINED_PROXY_RESOLUTIONS) this.#events.push(normalized);
+		this.#aggregateResolution = this.#aggregateResolution
+			? aggregateResolution(this.#aggregateResolution, normalized)
+			: normalized;
+		if (outcome === "ok") this.#lastSuccessfulResolution = normalized;
+		if (!this.#vendors.includes(event.provider)) this.#vendors.push(event.provider);
+		if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
+			this.#unresolvedVendors.push(event.provider);
+		}
+	}
+
+	/** Number of raw resolution events retained for bounded-history verification. */
+	get retainedResolutionEventCount(): number {
+		return this.#events.length;
+	}
+
+	/** Total resolutions included in the incremental aggregate. */
+	get resolutionEventCount(): number {
+		return this.#resolutionCount;
+	}
+
+	recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void {
+		if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES) return;
+		this.#failovers.push({
+			vendor: event.vendor,
+			...(event.nextVendor ? { nextVendor: event.nextVendor } : {}),
+			phase: event.phase,
+			reason: event.reason,
+			...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
 		});
+		if (!this.#unresolvedVendors.includes(event.vendor)) {
+			this.#unresolvedVendors.push(event.vendor);
+		}
 	}
 
 	recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void {
 		if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES) return;
 		this.#attempts.push({
-			provider: "smartproxy",
+			provider: event.provider,
 			attempt: Math.max(1, Math.floor(event.attempt || 1)),
 			...(event.poolIndex === undefined
 				? {}
@@ -130,75 +306,154 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		});
 	}
 
-	toHeaderValue(): string | undefined {
-		const [first, ...rest] = this.#events;
-		if (!first) return undefined;
-
-		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
-			(acc, event) => ({
-				provider: "smartproxy",
-				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
-				cacheHit: acc.cacheHit && event.cacheHit,
-				resolutionMs: acc.resolutionMs + event.resolutionMs,
-				allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
-				allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
-				allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
-				allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
-				lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
-				redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
-				redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
-				poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
-				poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
-				attempts: acc.attempts + event.attempts,
-				refreshes: sumOptional(acc.refreshes, event.refreshes),
-			}),
-			first,
-		);
-		const payload: ProviderTelemetryHeader = {
-			v: 1,
-			proxy: {
-				provider: "smartproxy",
-				cacheStatus: aggregate.cacheStatus,
-				cacheHit: aggregate.cacheHit,
-				resolutionMs: aggregate.resolutionMs,
-				...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
-				...(aggregate.allocatorStatus !== undefined
-					? { allocatorStatus: aggregate.allocatorStatus }
-					: {}),
-				...(aggregate.allocatorBodyClass !== undefined
-					? { allocatorBodyClass: aggregate.allocatorBodyClass }
-					: {}),
-				...(aggregate.allocatorAttempts !== undefined
-					? { allocatorAttempts: aggregate.allocatorAttempts }
-					: {}),
-				...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
-				...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
-				...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
-				...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
-				...(aggregate.poolExpiresInMs !== undefined
-					? { poolExpiresInMs: aggregate.poolExpiresInMs }
-					: {}),
-				attempts: aggregate.attempts,
-				...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
-				...(this.#attempts.length > 0
+	toLogPayload(): ProxyTelemetryLogPayload | undefined {
+		const aggregate = this.#aggregateResolution;
+		const attemptSamples = this.#attempts.map((attempt, index) => ({
+			n: index + 1,
+			a: attempt.attempt,
+			...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
+			...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+			o: attempt.outcome,
+			...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+			...(attempt.status === undefined ? {} : { s: attempt.status }),
+			...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+		}));
+		const failovers = this.#failovers.map((failover) => ({
+			v: failover.vendor,
+			...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+			p: failover.phase,
+			r: failover.reason,
+			...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+		}));
+
+		if (!this.#lastSuccessfulResolution) {
+			if (!aggregate && failovers.length === 0) return undefined;
+			return {
+				kind: "unresolved",
+				vendors: [...this.#unresolvedVendors],
+				...(aggregate
 					? {
-							attemptSamples: this.#attempts.map((attempt, index) => ({
-								n: index + 1,
-								a: attempt.attempt,
-								...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
-								...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
-								o: attempt.outcome,
-								...(attempt.errorCode ? { c: attempt.errorCode } : {}),
-								...(attempt.status === undefined ? {} : { s: attempt.status }),
-								...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
-							})),
+							cacheStatus: aggregate.cacheStatus,
+							cacheHit: aggregate.cacheHit,
+							resolutionMs: aggregate.resolutionMs,
+							...(aggregate.allocatorMs !== undefined
+								? { allocatorMs: aggregate.allocatorMs }
+								: {}),
+							...(aggregate.allocatorStatus !== undefined
+								? { allocatorStatus: aggregate.allocatorStatus }
+								: {}),
+							...(aggregate.allocatorBodyClass !== undefined
+								? { allocatorBodyClass: aggregate.allocatorBodyClass }
+								: {}),
+							...(aggregate.allocatorAttempts !== undefined
+								? { allocatorAttempts: aggregate.allocatorAttempts }
+								: {}),
+							...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+							...(aggregate.redisReadMs !== undefined
+								? { redisReadMs: aggregate.redisReadMs }
+								: {}),
+							...(aggregate.redisWriteMs !== undefined
+								? { redisWriteMs: aggregate.redisWriteMs }
+								: {}),
+							...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
+							...(aggregate.poolExpiresInMs !== undefined
+								? { poolExpiresInMs: aggregate.poolExpiresInMs }
+								: {}),
+							attempts: aggregate.attempts,
+							...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
 						}
 					: {}),
-			},
+				...(failovers.length > 0 ? { failovers } : {}),
+				...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+			};
+		}
+
+		// The serving vendor/protocol is the last successful resolution.
+		if (!aggregate) return undefined;
+		const serving = this.#lastSuccessfulResolution;
+		return {
+			kind: "resolved",
+			provider: serving.provider,
+			...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
+			...(serving.protocol ? { protocol: serving.protocol } : {}),
+			cacheStatus: aggregate.cacheStatus,
+			cacheHit: aggregate.cacheHit,
+			resolutionMs: aggregate.resolutionMs,
+			...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
+			...(aggregate.allocatorStatus !== undefined
+				? { allocatorStatus: aggregate.allocatorStatus }
+				: {}),
+			...(aggregate.allocatorBodyClass !== undefined
+				? { allocatorBodyClass: aggregate.allocatorBodyClass }
+				: {}),
+			...(aggregate.allocatorAttempts !== undefined
+				? { allocatorAttempts: aggregate.allocatorAttempts }
+				: {}),
+			...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+			...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
+			...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
+			...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
+			...(aggregate.poolExpiresInMs !== undefined
+				? { poolExpiresInMs: aggregate.poolExpiresInMs }
+				: {}),
+			attempts: aggregate.attempts,
+			...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+			...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+			...(this.#vendors.length > 1 ? { vendors: [...this.#vendors] } : {}),
+			...(failovers.length > 0 ? { failovers } : {}),
 		};
+	}
+
+	toHeaderPayload(log: ProxyTelemetryLogPayload): ProxyTelemetryHeaderPayload {
+		const attemptSamples = log.attemptSamples?.map((sample) => ({
+			n: sample.n,
+			a: sample.a,
+			...(sample.i === undefined ? {} : { i: sample.i }),
+			...(sample.h && PROXY_HEADER_HASH.test(sample.h)
+				? { h: closedEnum(sample.h) as ProxyHash }
+				: {}),
+			o: closedEnum(sample.o),
+			...(sample.c && PROXY_HEADER_TOKEN.test(sample.c) ? { c: closedEnum(sample.c) } : {}),
+			...(sample.s === undefined ? {} : { s: sample.s }),
+			...(sample.d === undefined ? {} : { d: sample.d }),
+		}));
+		const failovers = log.failovers?.map((failover) => ({
+			...failover,
+			v: closedEnum(failover.v),
+			...(failover.nx ? { nx: closedEnum(failover.nx) } : {}),
+			p: closedEnum(failover.p),
+			r: closedEnum(failover.r),
+		}));
+		if (log.kind === "resolved") {
+			return {
+				...log,
+				kind: closedEnum(log.kind),
+				provider: closedEnum(log.provider),
+				...(log.userAgentSource ? { userAgentSource: closedEnum(log.userAgentSource) } : {}),
+				...(log.protocol ? { protocol: closedEnum(log.protocol) } : {}),
+				cacheStatus: closedEnum(log.cacheStatus),
+				...(log.allocatorBodyClass
+					? { allocatorBodyClass: closedEnum(log.allocatorBodyClass) }
+					: {}),
+				...(attemptSamples ? { attemptSamples } : {}),
+				...(log.vendors ? { vendors: log.vendors.map((vendor) => closedEnum(vendor)) } : {}),
+				...(failovers ? { failovers } : {}),
+			} as ProxyTelemetryHeaderPayload;
+		}
+		return {
+			...log,
+			kind: closedEnum(log.kind),
+			vendors: log.vendors.map((vendor) => closedEnum(vendor)),
+			...(log.cacheStatus ? { cacheStatus: closedEnum(log.cacheStatus) } : {}),
+			...(log.allocatorBodyClass ? { allocatorBodyClass: closedEnum(log.allocatorBodyClass) } : {}),
+			...(failovers ? { failovers } : {}),
+			...(attemptSamples ? { attemptSamples } : {}),
+		} as ProxyTelemetryHeaderPayload;
+	}
 
-		const encoded = encodeBase64Url(JSON.stringify(payload));
-		if (encoded.length > MAX_HEADER_BYTES) return undefined;
-		return encoded;
+	toHeaderValue(): string | undefined {
+		const telemetry = new RequestTelemetry(createTraceContext());
+		telemetry.register(this);
+		return telemetry.toHeaderValue();
 	}
 }

package/src/runtime/redirect-hop-headers.ts

@@ -0,0 +1,71 @@
+import { getPublicSuffix } from "tough-cookie";
+
+/**
+ * Request-body header names a redirect drops when it changes the method
+ * (Fetch "request-body-header name").
+ */
+const REDIRECT_BODY_HEADERS: ReadonlySet<string> = new Set([
+	"content-encoding",
+	"content-language",
+	"content-location",
+	"content-type",
+]);
+
+/**
+ * Credentials a redirect never carries to another origin. Fetch removes
+ * `Authorization` on a cross-origin redirect; `Proxy-Authorization` is a
+ * credential of the same kind.
+ */
+const CROSS_ORIGIN_CREDENTIAL_HEADERS: ReadonlySet<string> = new Set([
+	"authorization",
+	"proxy-authorization",
+]);
+
+/** One redirect hop: the URL the headers were sent to, and the next request. */
+export interface RedirectHop {
+	readonly from: string;
+	readonly to: string;
+	readonly methodChanged: boolean;
+}
+
+/**
+ * Schemeful site (HTML "same site"): scheme plus registrable domain from the
+ * public suffix list, or the bare host when there is none (an IP address or
+ * a single-label host).
+ */
+function schemefulSite(url: URL): string {
+	const host = url.hostname;
+	const registrable = getPublicSuffix(host, { allowSpecialUseDomain: true, ignoreError: true });
+	return `${url.protocol}//${registrable ?? host}`;
+}
+
+/**
+ * The caller headers the next redirect hop carries, derived from the headers
+ * the previous hop sent. Both stealth redirect walkers compute every hop's
+ * headers here, so the rules hold on every path:
+ *
+ * - a method change drops the request-body headers;
+ * - a cross-origin hop drops `Authorization` and `Proxy-Authorization`;
+ * - a cross-site hop drops an explicit `Cookie`, after which the session
+ *   cookie jar supplies cookies by its own domain rules, as a browser does.
+ *
+ * A header dropped on one hop stays dropped for the rest of the chain.
+ */
+export function redirectHopHeaders<T>(
+	hop: RedirectHop,
+	headers: Readonly<Record<string, T>>,
+): Record<string, T> {
+	const from = new URL(hop.from);
+	const to = new URL(hop.to);
+	const crossOrigin = from.origin !== to.origin;
+	const crossSite = schemefulSite(from) !== schemefulSite(to);
+	return Object.fromEntries(
+		Object.entries(headers).filter(([name]) => {
+			const lower = name.toLowerCase();
+			if (hop.methodChanged && REDIRECT_BODY_HEADERS.has(lower)) return false;
+			if (crossOrigin && CROSS_ORIGIN_CREDENTIAL_HEADERS.has(lower)) return false;
+			if (crossSite && lower === "cookie") return false;
+			return true;
+		}),
+	);
+}