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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.57
+
+- Release candidate for main commit 4087dafdeab771eb91691884ce7315b8c399f863.
+
+## 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/cli/migrate-operation-declaration.d.ts

@@ -45,6 +45,7 @@ export type OperationDeclarationRepositoryResult = {
     readonly providerRoot: string;
     readonly changedFiles: readonly string[];
     readonly operationCount: number;
+    readonly notes: readonly OperationDeclarationNote[];
     readonly sidecar?: string;
     readonly localeTodoCount: number;
 } | {
@@ -53,9 +54,15 @@ export type OperationDeclarationRepositoryResult = {
     readonly refusals: readonly OperationDeclarationRefusal[];
     /** Operations that were independently migratable before repository-atomic refusal. */
     readonly operationCount: number;
+    readonly notes: readonly OperationDeclarationNote[];
     readonly changedFiles: readonly string[];
     readonly localeTodoCount: number;
 };
+export type OperationDeclarationNote = {
+    readonly code: "runtime_composed_registry";
+    readonly path: string;
+    readonly initializer: string;
+};
 /** Run the file transform repository-wide, committing writes only if every file is provable. */
 export declare function migrateOperationDeclarationRepository(providerRootInput: string, options?: {
     readonly check?: boolean;

package/dist/cli/migrate-operation-declaration.js

@@ -68,7 +68,8 @@ function migrateOperationDeclarationInternal(sourceText, fileName, options, cont
     }
     const constObjects = collectModuleConstObjects(source);
     const constArrays = collectModuleConstArrays(source);
-    const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds, context.operationSites, context.excludedBindings);
+    const discovery = discoverOperationSites(source, fileName, constObjects, options.operationIds, context.operationSites, context.excludedBindings, context.runtimeComposedInitializers);
+    context.recordDiscoveredSites?.(discovery.discoveredCount);
     if (discovery.refusals.length > 0) {
         return { status: "refused", refusals: discovery.refusals };
     }
@@ -599,14 +600,15 @@ function replaceExampleLocaleMember(member, newName, localeKey, source) {
         text: `${newName}: ${JSON.stringify(localeKey)}`,
     };
 }
-function discoverOperationSites(source, fileName, constObjects, operationIds, operationSites, excludedBindings) {
+function discoverOperationSites(source, fileName, constObjects, operationIds, operationSites, excludedBindings, runtimeComposedInitializers) {
     const sitesByStart = new Map();
+    const discoveredStarts = new Set();
     const localIds = new Map(operationIds ?? []);
     const localExcludedBindings = new Set(excludedBindings ?? []);
     const refusals = [];
     const operationFactories = collectSimpleOperationFactories(source);
     const factoryCallIds = new Map();
-    for (const map of collectOperationsMaps(source, constObjects, fileName, refusals)) {
+    for (const map of collectOperationsMaps(source, constObjects, fileName, refusals, runtimeComposedInitializers)) {
         for (const property of map.properties) {
             if (ts.isSpreadAssignment(property))
                 continue;
@@ -680,12 +682,15 @@ function discoverOperationSites(source, fileName, constObjects, operationIds, op
         if (ts.isCallExpression(node) && isOperationHelperCall(node)) {
             const argument = operationArgument(node);
             const bindingName = enclosingBindingName(node);
+            const unwrappedArgument = unwrapExpression(argument);
+            if (unwrappedArgument !== undefined && ts.isObjectLiteralExpression(unwrappedArgument)) {
+                discoveredStarts.add(unwrappedArgument.getStart(source));
+            }
             if (bindingName !== undefined && localExcludedBindings.has(bindingName))
                 return;
             const operationKey = (bindingName === undefined ? undefined : localIds.get(bindingName)) ??
                 bindingName ??
                 "<anonymous>";
-            const unwrappedArgument = unwrapExpression(argument);
             if (unwrappedArgument === undefined || !ts.isObjectLiteralExpression(unwrappedArgument)) {
                 refusals.push(refusal(fileName, operationKey, "non_literal", "Operation helper argument must be an object literal."));
             }
@@ -711,8 +716,11 @@ function discoverOperationSites(source, fileName, constObjects, operationIds, op
         ts.forEachChild(node, visit);
     };
     visit(source);
+    for (const start of sitesByStart.keys())
+        discoveredStarts.add(start);
     return {
         sites: [...sitesByStart.values()].sort((left, right) => left.object.getStart(source) - right.object.getStart(source)),
+        discoveredCount: discoveredStarts.size,
         refusals,
     };
 }
@@ -741,7 +749,7 @@ function collectSimpleOperationFactories(source) {
     }
     return factories;
 }
-function collectOperationsMaps(source, constObjects, fileName, refusals) {
+function collectOperationsMaps(source, constObjects, fileName, refusals, runtimeComposedInitializers) {
     const maps = new Map();
     const inspect = (expression, label) => {
         const unwrapped = unwrapExpression(expression);
@@ -758,6 +766,8 @@ function collectOperationsMaps(source, constObjects, fileName, refusals) {
             return;
         }
         if (ts.isCallExpression(unwrapped)) {
+            if (runtimeComposedInitializers?.has(expression.getStart(source)) === true)
+                return;
             refusals.push(refusal(fileName, label, "factory_composed_operations", "The operations map is produced by a factory call and cannot be statically enumerated."));
         }
     };
@@ -1274,6 +1284,7 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
     const todos = [];
     const refusals = [...repositoryIndex.refusals];
     let operationCount = 0;
+    let repositoryDiscoveredCount = 0;
     for (const sourcePath of sourceFiles) {
         const relativePath = slash(relative(providerRoot, sourcePath));
         const result = migrateOperationDeclarationInternal(readFileSync(sourcePath, "utf8"), relativePath, {
@@ -1283,6 +1294,10 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
             operationSites: repositoryIndex.operationSites.get(sourcePath),
             excludedBindings: repositoryIndex.excludedBindings.get(sourcePath),
             staticObjectResolver: repositoryIndex.staticObjectResolverFor(sourcePath),
+            runtimeComposedInitializers: repositoryIndex.runtimeComposedInitializers.get(sourcePath),
+            recordDiscoveredSites: (count) => {
+                repositoryDiscoveredCount += count;
+            },
         });
         if (result.status === "refused") {
             refusals.push(...result.refusals);
@@ -1295,7 +1310,18 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
             todos.push(...result.localeTodos);
         }
     }
-    if (repositoryIndex.declarations.length > 0 && repositoryIndex.discoveredCount === 0) {
+    const notes = repositoryDiscoveredCount === 0
+        ? []
+        : repositoryIndex.declarations.flatMap((declaration) => declaration.runtimeInitializer === undefined
+            ? []
+            : [
+                {
+                    code: "runtime_composed_registry",
+                    path: slash(relative(providerRoot, declaration.path)),
+                    initializer: declaration.runtimeInitializer,
+                },
+            ]);
+    if (repositoryIndex.declarations.length > 0 && repositoryDiscoveredCount === 0) {
         for (const declaration of repositoryIndex.declarations) {
             refusals.push(refusal(slash(relative(providerRoot, declaration.path)), "<operations>", "no_operations_discovered", `Provider construct ${declaration.construct} declares operations via unresolved initializer ${JSON.stringify(declaration.initializer.getText(declaration.initializer.getSourceFile()))}, but repository-wide discovery found zero operation sites.`));
         }
@@ -1309,6 +1335,7 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
             providerRoot,
             refusals,
             operationCount,
+            notes,
             changedFiles,
             localeTodoCount: todos.length,
         };
@@ -1322,6 +1349,7 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
             providerRoot,
             changedFiles: [],
             operationCount,
+            notes,
             localeTodoCount: 0,
         };
     }
@@ -1338,6 +1366,7 @@ export function migrateOperationDeclarationRepository(providerRootInput, options
         providerRoot,
         changedFiles,
         operationCount,
+        notes,
         sidecar,
         localeTodoCount: todos.length,
     };
@@ -1489,12 +1518,12 @@ function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
     const operationIds = buildOperationIdIndex(sourceFiles);
     const operationSites = new Map();
     const excludedBindings = new Map();
+    const runtimeComposedInitializers = new Map();
     const refusals = [];
     const declarations = [];
     const indexedProviderProperties = new Set();
     const factoryIds = new Map();
     const bindingCandidates = new Map();
-    let discoveredCount = 0;
     const relativePath = (path) => slash(relative(providerRoot, path));
     const resolutionRefusal = (path, operationKey, detail) => {
         refusals.push(refusal(relativePath(path), operationKey, "non_literal", detail));
@@ -1749,7 +1778,6 @@ function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
         }
         sites.set(start, operationId);
         operationSites.set(path, sites);
-        discoveredCount += 1;
     };
     const classifyEntry = (entry) => {
         const resolved = resolveLocatedExpression(entry.value, new Set());
@@ -1793,7 +1821,6 @@ function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
             };
             factory.ids.add(entry.operationId);
             factoryIds.set(key, factory);
-            discoveredCount += 1;
             return;
         }
         resolutionRefusal(resolved.value.path, entry.operationId, `Operation initializer ${JSON.stringify(expression.getText(resolved.value.source))} is not a raw object, operation helper, or simple same-file factory call.`);
@@ -1803,10 +1830,23 @@ function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
         if (indexedProviderProperties.has(key))
             return;
         indexedProviderProperties.add(key);
-        declarations.push({ path, construct, initializer: node.initializer });
+        const resolvedInitializer = resolveLocatedExpression({ path, source, expression: node.initializer }, new Set());
+        let runtimeInitializer;
+        if (resolvedInitializer.status === "resolved") {
+            const resolvedExpression = unwrapExpression(resolvedInitializer.value.expression);
+            if (resolvedExpression !== undefined && ts.isCallExpression(resolvedExpression)) {
+                runtimeInitializer = resolvedExpression.getText(resolvedInitializer.value.source);
+                const initializers = runtimeComposedInitializers.get(path) ?? new Set();
+                initializers.add(node.initializer.getStart(source));
+                runtimeComposedInitializers.set(path, initializers);
+            }
+        }
+        declarations.push({ path, construct, initializer: node.initializer, runtimeInitializer });
         const flattened = flattenRegistry({ path, source, expression: node.initializer }, new Set());
         if ("detail" in flattened) {
-            resolutionRefusal(path, "<operations>", flattened.detail);
+            if (runtimeInitializer === undefined) {
+                resolutionRefusal(path, "<operations>", flattened.detail);
+            }
         }
         else {
             for (const entry of flattened.entries.values())
@@ -1919,9 +1959,9 @@ function buildRepositoryOperationIndex(sourceFiles, providerRoot) {
         operationIds,
         operationSites,
         excludedBindings,
+        runtimeComposedInitializers,
         refusals,
         declarations,
-        discoveredCount,
         staticObjectResolverFor: (currentPath) => (expression, source) => resolveStaticObject(expression, sources.has(source.fileName) ? source.fileName : currentPath),
     };
 }

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;
 }