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

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.54",
+	"version": "2.2.0-beta.56",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-a.ts.txt

@@ -0,0 +1,3 @@
+export const registry = {
+	first: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-b.ts.txt

@@ -0,0 +1,3 @@
+export const registry = {
+	second: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-barrel.ts.txt

@@ -0,0 +1,2 @@
+export * from "./ambiguous-a";
+export * from "./ambiguous-b";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-ambiguous-index.ts.txt

@@ -0,0 +1,3 @@
+import { registry } from "./ambiguous-barrel";
+
+export default buildProvider({ operations: registry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-computed.ts.txt

@@ -0,0 +1,6 @@
+const operationId = "ping";
+const registry = {
+	[operationId]: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
+};
+
+export default buildProvider({ operations: registry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-a.ts.txt

@@ -0,0 +1 @@
+export { registry } from "./cycle-b";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-b.ts.txt

@@ -0,0 +1 @@
+export { registry } from "./cycle-a";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-cycle-index.ts.txt

@@ -0,0 +1,3 @@
+import { registry } from "./cycle-a";
+
+export default buildProvider({ operations: registry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-barrel.ts.txt

@@ -0,0 +1,7 @@
+import { catalogOperations } from "./catalog";
+import { storeOperations } from "./stores";
+
+export const daisoOperations = {
+	...catalogOperations,
+	...storeOperations,
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-catalog.ts.txt

@@ -0,0 +1,19 @@
+import { OPERATION_DOCS } from "./docs";
+
+export const catalogOperations = {
+	"browse-catalog": {
+		docs: { ...OPERATION_DOCS.catalog },
+		descriptionKey: "operations.browseCatalog.description",
+		annotations: { readOnly: true },
+		inputExamples: [{ scenario: "Browse the catalog", input: {} }],
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	},
+	"search-products": {
+		annotations: { readOnly: true },
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	},
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-docs.ts.txt

@@ -0,0 +1,6 @@
+export const OPERATION_DOCS = {
+	catalog: {
+		titleKey: "operations.groupedRead.title",
+		descriptionKey: "operations.groupedRead.description",
+	},
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-index.ts.txt

@@ -0,0 +1,3 @@
+import { daisoOperations } from "./operations";
+
+export default buildProvider({ operations: daisoOperations });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-daiso-stores.ts.txt

@@ -0,0 +1,8 @@
+export const storeOperations = {
+	"search-stores": {
+		annotations: { readOnly: true },
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	},
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-indirect-config.ts.txt

@@ -0,0 +1,5 @@
+import { packageRegistry } from "provider-operation-package";
+
+const config = { operations: packageRegistry };
+
+export default buildProvider(config);

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-nonstatic.ts.txt

@@ -0,0 +1,4 @@
+const first = { ping: pingOperation };
+const second = { pong: pongOperation };
+
+export default buildProvider({ operations: enabled ? first : second });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-package-index.ts.txt

@@ -0,0 +1,3 @@
+import { packageRegistry } from "provider-operation-package";
+
+export default buildProvider({ operations: packageRegistry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-index.ts.txt

@@ -0,0 +1,3 @@
+import { registry } from "./barrel-one.js";
+
+export default buildProvider({ operations: registry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-leaf.ts.txt

@@ -0,0 +1,10 @@
+const leafRegistry = {
+	ping: {
+		annotations: { readOnly: true },
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	},
+};
+
+export const registry = leafRegistry;

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-one.ts.txt

@@ -0,0 +1 @@
+export { registry } from "./barrel-two.js";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-reexport-two.ts.txt

@@ -0,0 +1 @@
+export { registry } from "./leaf";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-barrel.ts.txt

@@ -0,0 +1,2 @@
+export * from "provider-operation-package";
+export * from "./star-leaf";

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-index.ts.txt

@@ -0,0 +1,3 @@
+import { registry } from "./star-barrel";
+
+export default buildProvider({ operations: registry });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/discovery-star-package-leaf.ts.txt

@@ -0,0 +1,3 @@
+export const registry = {
+	ping: { annotations: { readOnly: true }, input: InputSchema, output: OutputSchema, handler },
+};

package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-duplicate-provider.ts.txt

@@ -0,0 +1,11 @@
+function makePingOperation() {
+	return defineOperation<ProviderContext>()({
+		annotations: { readOnly: true },
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	});
+}
+
+export const first = buildProvider({ operations: { ping: makePingOperation() } });
+export default buildProvider({ operations: { ping: makePingOperation() } });

package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-id-unresolved.ts.txt

@@ -0,0 +1,7 @@
+defineOperation<ProviderContext>()({
+	annotations: { readOnly: true },
+	inputExamples: [{ scenario: "Anonymous", input: {} }],
+	input: InputSchema,
+	output: OutputSchema,
+	handler,
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-one-to-many.ts.txt

@@ -0,0 +1,18 @@
+function makeSearchOperation(kind: string) {
+	return defineOperation<ProviderContext>()({
+		annotations: { readOnly: true },
+		inputExamples: [{ scenario: "Search items", input: { kind } }],
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	});
+}
+
+export default buildProvider({
+	operations: {
+		"used-goods-search": makeSearchOperation("used"),
+		"realty-search-listings": makeSearchOperation("realty"),
+		"jobs-search": makeSearchOperation("jobs"),
+		"cars-search": makeSearchOperation("cars"),
+	},
+});

package/src/cli/__tests__/fixtures/migrate-operation-declaration/factory-one-to-one.ts.txt

@@ -0,0 +1,13 @@
+function makeSearchOperation(kind: string) {
+	return defineOperation<ProviderContext>()({
+		annotations: { readOnly: true },
+		inputExamples: [{ scenario: "Search items", input: { kind } }],
+		input: InputSchema,
+		output: OutputSchema,
+		handler,
+	});
+}
+
+export default buildProvider({
+	operations: { "search-items": makeSearchOperation("items") },
+});