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

package/dist/runtime/request-telemetry.js

@@ -0,0 +1,228 @@
+import { PROVIDER_OBSERVABILITY_TAXONOMY_VERSION } from "../observability.js";
+export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+/** Brands a value from an SDK-declared closed string union without changing it. */
+export function closedEnum(value) {
+    return value;
+}
+/** Names the deliberate tenant cache-key exemption without changing its wire value. */
+export function tenantOpaqueKeys(value) {
+    return value;
+}
+const MAX_HEADER_BYTES = 4_096;
+const MAX_INGESTIBLE_ARRAY_LENGTH = 64;
+const MAX_INGESTIBLE_OBJECT_KEYS = 32;
+const MAX_INGESTIBLE_DEPTH = 4;
+const INGESTIBLE_TOKEN = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/;
+const HEADER_PRIORITY = [
+    "proxy",
+    "resolver",
+    "native",
+    "http",
+    "stealth",
+    "browser",
+    "ocr",
+    "stt",
+    "cache",
+    "state",
+];
+const warnedInvalidKeys = new Set();
+function createSpanIndex(trace) {
+    const spans = trace.getSpans().slice();
+    const mutableByName = new Map();
+    for (const span of spans) {
+        const named = mutableByName.get(span.name);
+        if (named)
+            named.push(span);
+        else
+            mutableByName.set(span.name, [span]);
+    }
+    const byName = new Map(mutableByName);
+    return {
+        spans,
+        byName,
+        count(name) {
+            return byName.get(name)?.length ?? 0;
+        },
+        durationMs(name) {
+            return (byName.get(name) ?? []).reduce((total, span) => total + span.duration_ms, 0);
+        },
+    };
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * 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 function isGatewayIngestible(value) {
+    const ancestors = new Set();
+    const visit = (candidate, depth) => {
+        if (typeof candidate === "number")
+            return Number.isFinite(candidate);
+        if (typeof candidate === "boolean")
+            return true;
+        if (typeof candidate === "string")
+            return INGESTIBLE_TOKEN.test(candidate);
+        if (candidate === null || typeof candidate !== "object")
+            return false;
+        if (depth >= MAX_INGESTIBLE_DEPTH || ancestors.has(candidate))
+            return false;
+        if (Array.isArray(candidate)) {
+            if (candidate.length > MAX_INGESTIBLE_ARRAY_LENGTH)
+                return false;
+            ancestors.add(candidate);
+            const valid = candidate.every((item, index) => Object.hasOwn(candidate, index) && visit(item, depth + 1));
+            ancestors.delete(candidate);
+            return valid;
+        }
+        if (!isPlainRecord(candidate))
+            return false;
+        const keys = Object.keys(candidate);
+        if (keys.length > MAX_INGESTIBLE_OBJECT_KEYS)
+            return false;
+        ancestors.add(candidate);
+        const valid = keys.every((key) => visit(candidate[key], depth + 1));
+        ancestors.delete(candidate);
+        return valid;
+    };
+    try {
+        return visit(value, 0);
+    }
+    catch {
+        return false;
+    }
+}
+function encodeEnvelope(envelope) {
+    return Buffer.from(JSON.stringify(envelope), "utf8").toString("base64url");
+}
+function warnInvalidSibling(key) {
+    if (warnedInvalidKeys.has(key))
+        return;
+    warnedInvalidKeys.add(key);
+    try {
+        console.warn(`[provider-sdk] Dropped invalid telemetry sibling "${key}"; contributors must return serializable log objects and bounded gateway-safe header values.`);
+    }
+    catch {
+        // A host-provided console must not let telemetry fail the request path.
+    }
+}
+function isProxySink(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    try {
+        return typeof Reflect.get(value, "recordProxyResolution") === "function";
+    }
+    catch {
+        return false;
+    }
+}
+/** One finalisation owner for every request-scoped telemetry contributor. */
+export class RequestTelemetry {
+    trace;
+    contributors;
+    #registered = {};
+    #exposed = {};
+    #proxy;
+    constructor(trace) {
+        this.trace = trace;
+        this.contributors = this.#exposed;
+    }
+    register(contributor) {
+        if (this.#registered[contributor.key]) {
+            throw new TypeError(`Telemetry contributor "${contributor.key}" is already registered.`);
+        }
+        const registered = {
+            key: contributor.key,
+            toLogPayload: (spans) => contributor.toLogPayload(spans),
+            toHeaderPayload: (log) => contributor.toHeaderPayload(log),
+        };
+        this.#registered[contributor.key] = registered;
+        this.#exposed[contributor.key] = contributor;
+        if (contributor.key === "proxy" && isProxySink(contributor))
+            this.#proxy = contributor;
+    }
+    get proxy() {
+        return this.#proxy;
+    }
+    toLogPayload() {
+        const spans = createSpanIndex(this.trace);
+        const payload = {};
+        for (const key of Object.keys(this.#registered)) {
+            const contributor = this.#registered[key];
+            if (!contributor)
+                continue;
+            try {
+                const sibling = contributor.toLogPayload(spans);
+                if (sibling === undefined)
+                    continue;
+                JSON.stringify(sibling);
+                payload[key] = sibling;
+            }
+            catch {
+                warnInvalidSibling(key);
+            }
+        }
+        return Object.keys(payload).length > 0 ? payload : undefined;
+    }
+    toHeaderValue() {
+        const spans = createSpanIndex(this.trace);
+        const siblings = {};
+        for (const key of HEADER_PRIORITY) {
+            const contributor = this.#registered[key];
+            if (!contributor)
+                continue;
+            try {
+                const log = contributor.toLogPayload(spans);
+                if (log === undefined)
+                    continue;
+                const projected = contributor.toHeaderPayload(log);
+                if (projected === undefined)
+                    continue;
+                if (!isGatewayIngestible(projected)) {
+                    warnInvalidSibling(key);
+                    continue;
+                }
+                const serialized = JSON.stringify(projected);
+                const decoded = JSON.parse(serialized);
+                if (!isGatewayIngestible(decoded) || !isPlainRecord(decoded)) {
+                    warnInvalidSibling(key);
+                    continue;
+                }
+                siblings[key] = decoded;
+            }
+            catch {
+                warnInvalidSibling(key);
+            }
+        }
+        if (Object.keys(siblings).length === 0)
+            return undefined;
+        // Gateway uses permissive json.Unmarshal (unknown keys are ignored) but
+        // requires v === 1. The observability taxonomy is additive and independent.
+        const envelope = {
+            v: 1,
+            taxonomy: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            ...siblings,
+        };
+        let encoded = encodeEnvelope(envelope);
+        if (encoded.length <= MAX_HEADER_BYTES)
+            return encoded;
+        for (let index = HEADER_PRIORITY.length - 1; index >= 0; index -= 1) {
+            const key = HEADER_PRIORITY[index];
+            if (!key || !(key in envelope))
+                continue;
+            delete envelope[key];
+            if (!HEADER_PRIORITY.some((candidate) => candidate in envelope))
+                return undefined;
+            envelope.truncated = true;
+            encoded = encodeEnvelope(envelope);
+            if (encoded.length <= MAX_HEADER_BYTES)
+                return encoded;
+        }
+        return undefined;
+    }
+}

package/dist/server/index.d.ts

@@ -1,5 +1,7 @@
 export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.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 type { Span, TraceContext } from "../runtime/trace.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";

package/dist/server/index.js

@@ -1,3 +1,4 @@
+export { RequestTelemetry, closedEnum, } from "../runtime/request-telemetry.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
 export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/serve-implementation.js

@@ -26,6 +26,7 @@ import { getProviderBaseUrl } from "../runtime/provider.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
+import { closedEnum, RequestTelemetry, tenantOpaqueKeys, } from "../runtime/request-telemetry.js";
 import { createUnsupportedResolverClient, } from "../runtime/resolver-shared.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
@@ -75,6 +76,16 @@ function providerErrorCode(error) {
 }
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
+const RETRY_LAST_ERROR_CODES = [
+    "transport_cancelled",
+    "transport_timeout",
+    "transport_network_error",
+    "upstream_http_error",
+    "other",
+];
+function tenantRetryLastErrorCode(value) {
+    return RETRY_LAST_ERROR_CODES.find((candidate) => candidate === value) ?? "other";
+}
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
 const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
 const DEFAULT_STATEFUL_FORWARDING_MAX_SKEW_MS = 5 * 60_000;
@@ -409,7 +420,7 @@ function createProviderContext(provider, request, operationId, options, state =
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
         affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
-        telemetry: scope.proxyTelemetry,
+        telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
@@ -417,7 +428,7 @@ function createProviderContext(provider, request, operationId, options, state =
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
-        telemetry: scope.proxyTelemetry,
+        telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
         ...(signal ? { signal } : {}),
         ...(provider.stealth ? { stealth: provider.stealth } : {}),
@@ -564,14 +575,14 @@ function createAuthFlowContext(provider, request, options, state, scope, signal)
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
         affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
-        telemetry: scope.proxyTelemetry,
+        telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
-        telemetry: scope.proxyTelemetry,
+        telemetry: scope.telemetry.proxy,
         engineCredentials: engineProxyCredentials,
         ...(signal ? { signal } : {}),
         ...(provider.stealth ? { stealth: provider.stealth } : {}),
@@ -1014,7 +1025,7 @@ function providerErrorCauseChain(error) {
     }
     return frames.length > 0 ? frames : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode, proxyTelemetry, observabilityDetails, correlation = {}) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode, telemetry, observabilityDetails, correlation = {}) {
     const providerCode = isProviderError(error) ? providerErrorCode(error) : undefined;
     const code = isProviderError(error)
         ? (providerCode ?? "provider_error")
@@ -1033,7 +1044,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         typeof providerCode === "string" &&
         !SDK_OWNED_PROVIDER_ERROR_CODES.has(providerCode) &&
         declaredErrorCode === undefined;
-    const proxy = proxyTelemetry?.toLogPayload();
+    const telemetryPayload = telemetry?.toLogPayload();
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     // The logger is caller-supplied and may mutate the event synchronously.
     // Give it an independent snapshot so those mutations cannot corrupt the
@@ -1058,7 +1069,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
             : {}),
         status,
         ...cost,
-        ...(proxy ? { proxy } : {}),
+        ...(telemetryPayload ?? {}),
         code,
         errorClass,
         message,
@@ -1093,8 +1104,8 @@ function logProviderCleanupError(logger, provider, kind, operationId, requestId,
         message,
     });
 }
-function logProviderSuccess(logger, provider, kind, route, requestId, status, cost, proxyTelemetry, correlation = {}) {
-    const proxy = proxyTelemetry?.toLogPayload();
+function logProviderSuccess(logger, provider, kind, route, requestId, status, cost, telemetry, correlation = {}) {
+    const telemetryPayload = telemetry?.toLogPayload();
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: "info",
@@ -1113,7 +1124,7 @@ function logProviderSuccess(logger, provider, kind, route, requestId, status, co
             : {}),
         status,
         ...cost,
-        ...(proxy ? { proxy } : {}),
+        ...(telemetryPayload ?? {}),
     });
 }
 const STREAM_CLEANUP_TIMEOUT_MS = 100;
@@ -1165,7 +1176,6 @@ function requestTraceId(headers, requestId) {
 function createRequestScope(input) {
     const requestCost = startRequestCost();
     const traceConfig = resolveTraceConfigFromEnv();
-    const proxyTelemetry = new ProxyTelemetryCollector();
     const details = {
         route: input.route,
         requestId: input.requestId,
@@ -1188,6 +1198,9 @@ function createRequestScope(input) {
             ...(initialTraceId ? { traceId: initialTraceId } : {}),
         })
         : createTraceContext();
+    const proxyCollector = new ProxyTelemetryCollector();
+    const telemetry = new RequestTelemetry(trace);
+    telemetry.register(proxyCollector);
     let rootRunner = (fn) => fn();
     let resolveRoot;
     const rootTerminal = new Promise((resolve) => {
@@ -1233,7 +1246,7 @@ function createRequestScope(input) {
         await Promise.all(streamCleanups.map(runCleanupEntry));
     };
     const headerSnapshot = (error) => {
-        const providerTelemetryHeader = proxyTelemetry.toHeaderValue();
+        const providerTelemetryHeader = telemetry.toHeaderValue();
         const declaredErrorCode = error === undefined ? undefined : input.declaredErrorCode?.(error);
         const errorObservability = error === undefined ? undefined : errorObservabilityDetails(error, declaredErrorCode);
         return {
@@ -1261,7 +1274,7 @@ function createRequestScope(input) {
     };
     const scope = {
         trace,
-        proxyTelemetry,
+        telemetry,
         enrich(enrichment) {
             if (terminalOutcome)
                 return;
@@ -1334,10 +1347,10 @@ function createRequestScope(input) {
                 const cost = finishRequestCost(requestCost);
                 try {
                     if (error === undefined) {
-                        logProviderSuccess(input.logger, input.provider, input.kind, details.route, details.requestId, status, cost, proxyTelemetry, details.correlation);
+                        logProviderSuccess(input.logger, input.provider, input.kind, details.route, details.requestId, status, cost, telemetry, details.correlation);
                     }
                     else {
-                        logProviderError(input.logger, input.provider, input.kind, details.route, details.requestId, error, status, cost, declaredErrorCode, proxyTelemetry, finishedResult.errorObservability, details.correlation);
+                        logProviderError(input.logger, input.provider, input.kind, details.route, details.requestId, error, status, cost, declaredErrorCode, telemetry, finishedResult.errorObservability, details.correlation);
                     }
                 }
                 catch {
@@ -1407,18 +1420,43 @@ function toJsonSuccessResponse(result, ctx) {
     }
     const cacheMeta = ctx && "cache" in ctx ? ctx.cache.responseMeta() : undefined;
     const retryMeta = ctx ? retryResponseMeta.get(ctx) : undefined;
+    const cache = cacheMeta
+        ? {
+            hit: cacheMeta.hit,
+            stale: cacheMeta.stale,
+            // TODO(owner): keep or remove implementation-shaped cache keys from tenant meta.
+            keys: tenantOpaqueKeys(cacheMeta.keys),
+            ...(cacheMeta.source ? { source: closedEnum(cacheMeta.source) } : {}),
+        }
+        : undefined;
+    const retry = retryMeta
+        ? {
+            attempts: retryMeta.attempts,
+            retries: retryMeta.retries,
+            ...(retryMeta.preset ? { preset: closedEnum(retryMeta.preset) } : {}),
+            transport: closedEnum(retryMeta.transport),
+            ...(retryMeta.lastErrorCode
+                ? {
+                    lastErrorCode: closedEnum(tenantRetryLastErrorCode(retryMeta.lastErrorCode)),
+                }
+                : {}),
+            ...(retryMeta.lastStatus ? { lastStatus: retryMeta.lastStatus } : {}),
+        }
+        : undefined;
     const meta = cacheMeta || retryMeta
         ? {
-            ...(cacheMeta
+            ...(cache
                 ? {
-                    cached: cacheMeta.hit,
-                    stale: cacheMeta.stale,
-                    cache: cacheMeta,
+                    cached: cache.hit,
+                    stale: cache.stale,
+                    cache,
                 }
                 : {}),
-            ...(retryMeta ? { retry: retryMeta } : {}),
+            ...(retry ? { retry } : {}),
         }
         : undefined;
+    const _neutralMeta = meta;
+    void _neutralMeta;
     return {
         data: result,
         ...(meta ? { meta } : {}),

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.55",
+	"version": "2.2.0-beta.56",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/index.ts

@@ -181,10 +181,23 @@ export {
 export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.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,