@apifuse/provider-sdk 2.2.0-beta.55 → 2.2.0-beta.56

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.56
+
+- Release candidate for main commit 390167b3f51488be0beba25a1ea5eb425d3bf839.
+
 ## 2.2.0-beta.55
 
 - Release candidate for main commit 1c495af089940a4c666e6baf58dc0dd577771a40.

package/bin/apifuse-pack-types.ts

@@ -292,6 +292,115 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-telemetry-header-vendor.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry headers reject an unbranded vendor string",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { vendor: string }> = {",
+			'\tkey: "resolver",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ vendor: "free-text" }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-host.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry headers reject an unbranded host string",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { host: string }> = {",
+			'\tkey: "http",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ host: "x.example" }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-tenant-vendor.ts",
+		expectedCode: "TS2322",
+		description: "tenant-neutral projections reject vendor identities",
+		source: [
+			'import type { TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			'export const bad: TenantNeutral<{ vendorUsed: "smartproxy" }> = { vendorUsed: "smartproxy" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-any.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry projections reject any-valued properties",
+		source: [
+			'import type { GatewayIngestible } from "@apifuse/provider-sdk";',
+			"",
+			'export const bad: GatewayIngestible<{ x: any }> = { x: "free-text" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-header-union-array.ts",
+		expectedCode: "TS2322",
+		description: "gateway telemetry projections reject arrays mixing numbers and strings",
+		source: [
+			'import type { TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"const bad: TelemetryContributor<{}, { values: (number | string)[] }> = {",
+			'\tkey: "resolver",',
+			"\ttoLogPayload: () => ({}),",
+			'\ttoHeaderPayload: () => ({ values: [1, "free prose"] }),',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-opaque-identity.ts",
+		expectedCode: "TS2322",
+		description: "tenant opaque array brands are not accepted outside the cache keys property",
+		source: [
+			'import type { TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			"type LocalOpaque = string[] & { readonly __tenantOpaqueCacheKeys: true };",
+			"declare const opaque: LocalOpaque;",
+			"export const bad: TenantNeutral<{ identity: LocalOpaque }> = { identity: opaque };",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-telemetry-meta-vendor.ts",
+		expectedCode: "TS2322",
+		description: "success metadata rejects tenant-visible vendor identity keys",
+		source: [
+			'import { closedEnum, type ClosedEnum, type TenantNeutral } from "@apifuse/provider-sdk";',
+			"",
+			'type Meta = { cached: boolean; detail: { vendorUsed: ClosedEnum<"smartproxy"> } };',
+			'export const bad: TenantNeutral<Meta> = { cached: false, detail: { vendorUsed: closedEnum("smartproxy") } };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-proxy-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "proxy telemetry contributor satisfies the public contributor contract",
+		source: [
+			'import { closedEnum, type ClosedEnum, type GatewayIngestible, type ProxyTelemetryHeaderPayload, type ProxyTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const proxy: TelemetryContributor<ProxyTelemetryLogPayload, ProxyTelemetryHeaderPayload> = {",
+			'\tkey: "proxy",',
+			'\ttoLogPayload: () => ({ kind: "unresolved", vendors: [] }),',
+			'\ttoHeaderPayload: () => ({ kind: closedEnum("unresolved"), vendors: [] }),',
+			"};",
+			'type Values = { values: ClosedEnum<"a" | "b">[] };',
+			'export const values: GatewayIngestible<Values> = { values: [closedEnum("a"), closedEnum("b")] };',
+			"",
+		].join("\n"),
+	},
 ] as const;
 
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));
@@ -513,6 +622,15 @@ function assertNegativeControlFails(consumerDir: string): void {
 			],
 			{ cwd: consumerDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
 		);
+		if (negativeControl.expectedCode === "") {
+			if (result.status !== 0) {
+				throw new Error(
+					`Positive control "${negativeControl.description}" failed to compile:\n${result.stdout}\n${result.stderr}`,
+				);
+			}
+			console.log(`Positive control accepted: ${negativeControl.description}`);
+			continue;
+		}
 		if (result.status === 0) {
 			throw new Error(
 				'Negative control "' +
@@ -528,6 +646,9 @@ function assertNegativeControlFails(consumerDir: string): void {
 				`Negative control "${negativeControl.description}" (${negativeControl.filename}) failed for an unexpected reason (wanted ${negativeControl.expectedCode}):\n${output}`,
 			);
 		}
+		console.log(
+			`Negative control rejected (${negativeControl.expectedCode}): ${negativeControl.description}`,
+		);
 	}
 }
 

package/dist/index.d.ts

@@ -32,7 +32,8 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
-export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "./runtime/proxy-telemetry.js";
+export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "./runtime/proxy-telemetry.js";
+export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "./runtime/request-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";

package/dist/index.js

@@ -26,6 +26,7 @@ export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdle
 export { generateInsights } from "./runtime/insights.js";
 export { wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export { RequestTelemetry, closedEnum, } from "./runtime/request-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "./runtime/secrets.js";

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

@@ -1,5 +1,11 @@
 import type { ProxyAttemptTelemetryEvent, ProxyCacheStatus, ProxyProtocol, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyUserAgentSource, ProxyVendorFailoverTelemetryEvent, ProxyVendorName, SmartproxyAllocatorBodyClass } from "../config/loader.js";
-export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+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;
@@ -77,11 +83,56 @@ export type ProxyTelemetryUnresolvedPayload = {
     }[];
 };
 export type ProxyTelemetryLogPayload = ProxyTelemetryResolvedPayload | ProxyTelemetryUnresolvedPayload;
-export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
+/** 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,7 +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,
@@ -23,17 +27,39 @@ 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) {
         const outcome = event.outcome === "error" ? "error" : "ok";
-        this.#events.push({
+        const normalized = {
             provider: event.provider,
             outcome,
             ...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
@@ -58,11 +84,29 @@ 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;
@@ -96,8 +140,7 @@ export class ProxyTelemetryCollector {
         });
     }
     toLogPayload() {
-        const [first, ...rest] = this.#events;
-        const okEvents = this.#events.filter((event) => event.outcome !== "error");
+        const aggregate = this.#aggregateResolution;
         const attemptSamples = this.#attempts.map((attempt, index) => ({
             n: index + 1,
             a: attempt.attempt,
@@ -115,31 +158,9 @@ export class ProxyTelemetryCollector {
             r: failover.reason,
             ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
         }));
-        if (okEvents.length === 0) {
-            if (!first && failovers.length === 0)
+        if (!this.#lastSuccessfulResolution) {
+            if (!aggregate && failovers.length === 0)
                 return undefined;
-            const failureEvents = this.#events.filter((event) => event.outcome === "error");
-            const [firstFailure, ...remainingFailures] = failureEvents;
-            const aggregate = firstFailure
-                ? remainingFailures.reduce((acc, event) => ({
-                    provider: event.provider,
-                    outcome: "error",
-                    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),
-                }), firstFailure)
-                : undefined;
             return {
                 kind: "unresolved",
                 vendors: [...this.#unresolvedVendors],
@@ -180,30 +201,9 @@ export class ProxyTelemetryCollector {
             };
         }
         // The serving vendor/protocol is the last successful resolution.
-        const serving = okEvents[okEvents.length - 1] ?? first;
-        const vendors = [];
-        for (const event of this.#events) {
-            if (!vendors.includes(event.provider))
-                vendors.push(event.provider);
-        }
-        const aggregate = rest.reduce((acc, event) => ({
-            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),
-        }), first);
+        if (!aggregate)
+            return undefined;
+        const serving = this.#lastSuccessfulResolution;
         return {
             kind: "resolved",
             provider: serving.provider,
@@ -232,18 +232,59 @@ export class ProxyTelemetryCollector {
             attempts: aggregate.attempts,
             ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
             ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
-            ...(vendors.length > 1 ? { vendors } : {}),
+            ...(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 proxy = this.toLogPayload();
-        if (!proxy)
-            return undefined;
-        const payload = { v: 1, proxy };
-        const encoded = encodeBase64Url(JSON.stringify(payload));
-        if (encoded.length > MAX_HEADER_BYTES)
-            return undefined;
-        return encoded;
+        const telemetry = new RequestTelemetry(createTraceContext());
+        telemetry.register(this);
+        return telemetry.toHeaderValue();
     }
 }

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

@@ -0,0 +1,70 @@
+import type { ProxyTelemetrySink } from "../config/loader.js";
+import type { ProxyTelemetryLogPayload } from "./proxy-telemetry.js";
+import type { Span, TraceContext } from "./trace.js";
+export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+export type TelemetryKey = "proxy" | "resolver" | "http" | "stealth" | "native" | "browser" | "ocr" | "stt" | "cache" | "state" | "events";
+declare const CLOSED_ENUM: unique symbol;
+/** A string from an SDK-declared, closed observability taxonomy. */
+export type ClosedEnum<T extends string> = T & {
+    readonly [CLOSED_ENUM]: true;
+};
+/** Brands a value from an SDK-declared closed string union without changing it. */
+export declare function closedEnum<T extends string>(value: T): ClosedEnum<T>;
+/** Explicit exemption for the existing implementation-shaped cache key list. */
+export type TenantOpaqueKeys = string[] & {
+    readonly __tenantOpaqueCacheKeys: true;
+};
+/** Names the deliberate tenant cache-key exemption without changing its wire value. */
+export declare function tenantOpaqueKeys(value: string[]): TenantOpaqueKeys;
+/**
+ * Compile-time projection for the gateway ingestion contract. Plain strings,
+ * URLs, hostnames, free text, unknown values, and escape-hatch properties reduce to `never`.
+ */
+export type GatewayIngestible<T> = 0 extends 1 & T ? never : T extends object ? keyof T extends never ? never : {
+    [K in keyof T]: 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [readonly (infer U)[]] ? 0 extends 1 & U ? never : unknown extends U ? never : [U] extends [
+        number | boolean | ClosedEnum<string> | GatewayIngestible<U>
+    ] ? T[K] : never : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [GatewayIngestible<NonNullable<T[K]>>] ? T[K] : never : never;
+} : never;
+/** Compile-time projection for tenant-visible, identity-neutral metadata. */
+export type TenantNeutral<T> = 0 extends 1 & T ? never : T extends object ? {
+    [K in keyof T]: K extends `vendor${string}` | "provider" | "engine" | "model" | `${string}Host` ? never : 0 extends 1 & T[K] ? never : unknown extends T[K] ? never : [NonNullable<T[K]>] extends [
+        string[] & {
+            readonly __tenantOpaqueCacheKeys: true;
+        }
+    ] ? K extends "keys" ? T[K] : never : [NonNullable<T[K]>] extends [number | boolean | ClosedEnum<string>] ? T[K] : [NonNullable<T[K]>] extends [object] ? [NonNullable<T[K]>] extends [TenantNeutral<NonNullable<T[K]>>] ? T[K] : never : never;
+} : never;
+export interface SpanIndex {
+    readonly spans: readonly Span[];
+    readonly byName: ReadonlyMap<string, readonly Span[]>;
+    count(name: string): number;
+    durationMs(name: string): number;
+}
+export interface TelemetryContributor<Log extends object, Header extends object> {
+    readonly key: TelemetryKey;
+    toLogPayload(spans: SpanIndex): Log | undefined;
+    toHeaderPayload(log: Log): 0 extends 1 & Header ? never : [Header] extends [GatewayIngestible<Header>] ? Header | undefined : never;
+}
+export type RequestTelemetryLogPayload = {
+    proxy?: ProxyTelemetryLogPayload;
+} & Partial<Record<Exclude<TelemetryKey, "proxy">, object>>;
+/**
+ * Bounded structural defence in depth against casts and accidental free text.
+ * Closed-enum brands are erased at runtime; the type-level guard is the contract,
+ * while this check only enforces safe token shapes and collection bounds.
+ */
+export declare function isGatewayIngestible(value: unknown): boolean;
+/** One finalisation owner for every request-scoped telemetry contributor. */
+export declare class RequestTelemetry {
+    #private;
+    readonly trace: TraceContext;
+    readonly contributors: Readonly<Partial<Record<TelemetryKey, {
+        readonly key: TelemetryKey;
+        toLogPayload(spans: SpanIndex): object | undefined;
+    }>>>;
+    constructor(trace: TraceContext);
+    register<Log extends object, Header extends object>(contributor: TelemetryContributor<Log, Header> & (0 extends 1 & Log ? never : 0 extends 1 & Header ? never : [Header] extends [GatewayIngestible<Header>] ? unknown : never)): void;
+    get proxy(): ProxyTelemetrySink | undefined;
+    toLogPayload(): RequestTelemetryLogPayload | undefined;
+    toHeaderValue(): string | undefined;
+}
+export {};