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

package/dist/runtime/proxy-nodemaven.js

@@ -0,0 +1,147 @@
+import { readDiagnosticEnv } from "./diagnostic-env.js";
+import { createHash, randomBytes } from "node:crypto";
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL = "http";
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS = {
+    http: { min: 8080, max: 9080 },
+    socks5: { min: 1080, max: 2080 },
+};
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+export function hasNodemavenCredentials() {
+    return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+function readNodemavenUsername() {
+    return readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)?.trim() || undefined;
+}
+function readNodemavenPassword() {
+    return readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)?.trim() || undefined;
+}
+function resolveNodemavenFilter(value) {
+    const raw = value?.trim().toLowerCase();
+    if (!raw)
+        return DEFAULT_NODEMAVEN_FILTER;
+    if (!NODEMAVEN_FILTERS.has(raw)) {
+        throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+    }
+    return raw;
+}
+export function nodemavenPoolSize(policy) {
+    return Math.min(NODEMAVEN_MAX_POOL_SIZE, Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)));
+}
+export function nodemavenLifetimeMinutes(policy) {
+    const configured = policy.session?.lifetimeMinutes;
+    if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+        return NODEMAVEN_MAX_LIFETIME_MINUTES;
+    }
+    return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(policy, now = Date.now()) {
+    const lifetimeMs = nodemavenLifetimeMinutes(policy) * 60_000;
+    const refreshEpoch = Math.floor(now / lifetimeMs);
+    return {
+        refreshEpoch,
+        expiresAt: new Date((refreshEpoch + 1) * lifetimeMs).toISOString(),
+    };
+}
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value) {
+    if (!value)
+        return undefined;
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "");
+    return slug || undefined;
+}
+function isStickyAffinity(policy) {
+    return (policy.session?.affinity ?? "request") !== "request";
+}
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(policy, affinityKey, poolIndex, refreshEpoch) {
+    if (!isStickyAffinity(policy) || !affinityKey) {
+        return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+    }
+    const digest = createHash("sha256")
+        .update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+        .digest("hex");
+    // hex digits are a subset of the allowed [a-z0-9] sid charset.
+    return digest.slice(0, SID_LENGTH);
+}
+function selectPort(protocol, sid, poolIndex) {
+    const { min, max } = NODEMAVEN_PORTS[protocol];
+    const span = max - min + 1;
+    const hashInt = Number.parseInt(createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8), 16);
+    return min + (hashInt % span);
+}
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input) {
+    const username = input.credentials.username.trim();
+    const password = input.credentials.password.trim();
+    if (!username || !password) {
+        throw new Error(`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`);
+    }
+    const filter = resolveNodemavenFilter(input.credentials.filter);
+    const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+    const port = selectPort(input.protocol, sid, input.poolIndex);
+    const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+    const sticky = isStickyAffinity(input.policy);
+    const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+    const region = slugifyGeo(input.policy.geo?.subdivision);
+    const city = slugifyGeo(input.policy.geo?.city);
+    const tokens = [username];
+    if (country)
+        tokens.push("country", country);
+    if (region)
+        tokens.push("region", region);
+    if (city)
+        tokens.push("city", city);
+    tokens.push("sid", sid);
+    tokens.push("filter", filter);
+    tokens.push("ipv4", "true");
+    const proxyUsername = tokens.join("-");
+    // Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+    const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+    return {
+        url,
+        protocol: input.protocol,
+        sticky,
+        sessionId: sid,
+        ...(sticky
+            ? {
+                expiresAt: input.expiresAt ??
+                    new Date((input.now ?? Date.now()) + lifetimeMinutes * 60_000).toISOString(),
+            }
+            : {}),
+        diagnostics: {
+            vendor: "nodemaven",
+            protocol: input.protocol,
+            sticky,
+            filter,
+            lifetimeMinutes,
+            ...(country ? { country } : {}),
+        },
+    };
+}

package/dist/runtime/proxy-retry-policy.d.ts

@@ -21,7 +21,10 @@ export declare function normalizeProxyTransportRetryOptions(retry: RequestOption
     label?: RetryPolicyLabel;
 }): NormalizedProxyTransportRetryOptions | undefined;
 export declare function validateUnsafeProxyTransportRetryMethods(options: NormalizedProxyTransportRetryOptions, label?: RetryPolicyLabel): void;
-export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions): boolean;
+export declare function isProxyTransportRetryMethod(method: HttpMethod | string, options: NormalizedProxyTransportRetryOptions, request?: {
+    readonly body?: unknown;
+    readonly headers?: Readonly<Record<string, string | readonly string[] | undefined>>;
+}): boolean;
 export declare function shouldRetryProxyTransportError(error: unknown, options: NormalizedProxyTransportRetryOptions): boolean;
 export declare function shouldRetryProxyTransportAttempt(input: {
     error: unknown;

package/dist/runtime/proxy-retry-policy.js

@@ -1,5 +1,6 @@
 import { ProviderError, TransportError } from "../errors.js";
 import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types.js";
+import { isSensitiveKey } from "./request-options.js";
 export const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
 export const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES = [
     "transport_network_error",
@@ -250,10 +251,18 @@ export function validateUnsafeProxyTransportRetryMethods(options, label = "Proxy
         return;
     throw new ProviderError(`${label} retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
 }
-export function isProxyTransportRetryMethod(method, options) {
-    return options.methods
+export function isProxyTransportRetryMethod(method, options, request) {
+    const methodAllowed = options.methods
         .map((allowedMethod) => allowedMethod.toUpperCase())
         .includes(method.toUpperCase());
+    if (!methodAllowed || request === undefined)
+        return methodAllowed;
+    if (request.body !== undefined)
+        return false;
+    return !Object.keys(request.headers ?? {}).some((name) => {
+        const normalized = name.toLowerCase();
+        return normalized === "cookie" || normalized === "proxy-authorization" || isSensitiveKey(name);
+    });
 }
 export function shouldRetryProxyTransportError(error, options) {
     const code = retryErrorCode(error);

package/dist/runtime/proxy-telemetry.d.ts

@@ -1,8 +1,138 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader.js";
-export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
-export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
+import type { ProxyAttemptTelemetryEvent, ProxyCacheStatus, ProxyProtocol, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyUserAgentSource, ProxyVendorFailoverTelemetryEvent, ProxyVendorName, SmartproxyAllocatorBodyClass } from "../config/loader.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+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;
+    }[];
+};
+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;
+    }[];
+};
+export declare class ProxyTelemetryCollector implements ProxyTelemetrySink, TelemetryContributor<ProxyTelemetryLogPayload, ProxyTelemetryHeaderPayload> {
     #private;
+    readonly key: "proxy";
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    /** Number of raw resolution events retained for bounded-history verification. */
+    get retainedResolutionEventCount(): number;
+    /** Total resolutions included in the incremental aggregate. */
+    get resolutionEventCount(): number;
+    recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
+    toLogPayload(): ProxyTelemetryLogPayload | undefined;
+    toHeaderPayload(log: ProxyTelemetryLogPayload): ProxyTelemetryHeaderPayload;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -1,6 +1,11 @@
-export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
-const MAX_HEADER_BYTES = 4_096;
+import { closedEnum, RequestTelemetry, } from "./request-telemetry.js";
+import { createTraceContext } from "./trace.js";
+export { PROVIDER_TELEMETRY_HEADER } from "./request-telemetry.js";
 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 = {
     disabled: 0,
     memory_hit: 1,
@@ -22,15 +27,43 @@ function maxOptional(left, right) {
 function worseStatus(left, right) {
     return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
-function encodeBase64Url(value) {
-    return Buffer.from(value, "utf8").toString("base64url");
+function aggregateResolution(acc, event) {
+    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 {
+    key = "proxy";
     #events = [];
+    #resolutionCount = 0;
+    #aggregateResolution;
+    #lastSuccessfulResolution;
+    #vendors = [];
     #attempts = [];
+    #failovers = [];
+    #unresolvedVendors = [];
     recordProxyResolution(event) {
-        this.#events.push({
-            provider: "smartproxy",
+        const outcome = event.outcome === "error" ? "error" : "ok";
+        const normalized = {
+            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)),
@@ -51,13 +84,48 @@ export class ProxyTelemetryCollector {
                 : Math.max(0, Math.floor(event.poolExpiresInMs)),
             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() {
+        return this.#events.length;
+    }
+    /** Total resolutions included in the incremental aggregate. */
+    get resolutionEventCount() {
+        return this.#resolutionCount;
+    }
+    recordProxyVendorFailover(event) {
+        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) {
         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
                 ? {}
@@ -71,72 +139,152 @@ export class ProxyTelemetryCollector {
                 : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
         });
     }
-    toHeaderValue() {
-        const [first, ...rest] = this.#events;
-        if (!first)
-            return undefined;
-        const aggregate = rest.reduce((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 = {
-            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() {
+        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 } : {}),
                     }
                     : {}),
-            },
-        };
-        const encoded = encodeBase64Url(JSON.stringify(payload));
-        if (encoded.length > MAX_HEADER_BYTES)
+                ...(failovers.length > 0 ? { failovers } : {}),
+                ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+            };
+        }
+        // The serving vendor/protocol is the last successful resolution.
+        if (!aggregate)
             return undefined;
-        return encoded;
+        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) {
+        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) }
+                : {}),
+            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 } : {}),
+            };
+        }
+        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 } : {}),
+        };
+    }
+    toHeaderValue() {
+        const telemetry = new RequestTelemetry(createTraceContext());
+        telemetry.register(this);
+        return telemetry.toHeaderValue();
     }
 }