@apifuse/provider-sdk 2.2.0-beta.66 → 2.2.0-beta.68

package/src/server/serve-implementation.ts

@@ -29,6 +29,7 @@ import { SDK_VERSION } from "./sdk-version.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { providerErrorStackFrames } from "./error-stack-frames.js";
 import {
+	registeredUpstreamErrorCategory,
 	SDK_OWNED_PROVIDER_ERROR_CODES,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
 	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
@@ -106,7 +107,7 @@ import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import type * as NativeNetworkRuntimeModule from "../runtime/native-network.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { bindOcrTelemetry, OcrTelemetryCollector } from "../runtime/ocr-telemetry.js";
-import { getProviderBaseUrl } from "../runtime/provider.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../runtime/provider.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
@@ -216,6 +217,10 @@ import type {
 } from "../types.js";
 import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
+import {
+	type ProviderStateBackendLogEvent,
+	providerStateBackendLogEvent,
+} from "./state-backend-report.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import {
 	collectStaticDiagnosticSensitiveValues,
@@ -635,15 +640,6 @@ function bindResolverSignalWithoutRuntime(
 	return boundResolver;
 }
 
-function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined {
-	const baseUrl = getProviderBaseUrl(provider);
-	if (baseUrl) {
-		return baseUrl;
-	}
-	const firstHost = provider.allowedHosts?.[0];
-	return firstHost ? `https://${firstHost}` : undefined;
-}
-
 function getProviderStealthProfile(provider: ProviderDefinition) {
 	return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
@@ -1476,6 +1472,7 @@ export type ProviderServerLogEvent =
 			 */
 			warnings?: readonly string[];
 	  }
+	| ProviderStateBackendLogEvent
 	| SelfTestCancellationLogEvent;
 
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
@@ -1607,8 +1604,9 @@ function zodDetails(
 // (credential_unavailable) usually means a caller credential problem, an
 // internal stateful-routing deadline is APIFuse-owned despite its timeout
 // category, and the built-in upstream failure families keep their upstream
-// attribution even when the author left the category at the provider_error
-// default.
+// attribution even under an explicit non-upstream category. An unset category
+// needs no override: a registered upstream code already carries its category
+// (SDK_UPSTREAM_ERROR_CODE_REGISTRY), and the source follows from it.
 function publicErrorSource(error: unknown, category: ProviderErrorCategory): ProviderErrorSource {
 	if (error instanceof StatefulRoutingDeadlineError) return "apifuse";
 	if (isProviderError(error)) {
@@ -1931,6 +1929,24 @@ function providerObservabilityDetails(
 	};
 }
 
+// The category a `ProviderError` (validation errors included) gets when its
+// author set none, ahead of the branch's own default: an operation-declared
+// rejection status (409/410/422) → upstream_rejected, then the registered
+// upstream code's category (UPSTREAM_SCHEMA_ERROR → upstream_schema_drift,
+// NOT_FOUND → upstream_http, ...). `undefined` leaves the branch default.
+function derivedErrorCategory(
+	error: unknown,
+	declaredStatus: unknown,
+): ProviderErrorCategory | undefined {
+	if (
+		isEmittableErrorStatus(declaredStatus) &&
+		categoryForStatus(declaredStatus) === "upstream_rejected"
+	) {
+		return "upstream_rejected";
+	}
+	return registeredUpstreamErrorCategory(providerErrorCode(error));
+}
+
 function classifiedErrorObservabilityDetails(
 	error: unknown,
 	declaredErrorCode?: OperationErrorCode,
@@ -1945,12 +1961,10 @@ function classifiedErrorObservabilityDetails(
 		return {
 			category: providerCategory
 				? providerCategory
-				: isEmittableErrorStatus(declaredStatus) &&
-						categoryForStatus(declaredStatus) === "upstream_rejected"
-					? "upstream_rejected"
-					: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+				: (derivedErrorCategory(error, declaredStatus) ??
+					(isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
 						? "provider_error"
-						: "input_validation",
+						: "input_validation")),
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: isProviderError(error)
 				? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
@@ -1967,19 +1981,13 @@ function classifiedErrorObservabilityDetails(
 	}
 
 	if (isProviderError(error)) {
-		// Deterministic upstream refusals default to the rejection category:
-		// the UPSTREAM_REJECTED family and any operation-declared rejection
-		// status (409/410/422) classify as upstream_rejected unless the
-		// author set an explicit category.
-		const declaredStatus = effectiveDeclaration?.status;
-		const rejectionDefault =
-			providerErrorCode(error) === "UPSTREAM_REJECTED" ||
-			(isEmittableErrorStatus(declaredStatus) &&
-				categoryForStatus(declaredStatus) === "upstream_rejected")
-				? ("upstream_rejected" as const)
-				: ("provider_error" as const);
+		// Retryability does not follow the derived category: it stays
+		// instance ?? declared ?? false below.
 		return {
-			category: providerErrorOption(error, "category") ?? rejectionDefault,
+			category:
+				providerErrorOption(error, "category") ??
+				derivedErrorCategory(error, effectiveDeclaration?.status) ??
+				"provider_error",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable:
 				providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
@@ -3755,7 +3763,13 @@ function createServerAppWithCapabilityModules(
 	}
 
 	app.notFound((c) => {
-		const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+		// An unknown route is not an upstream answer: the explicit category keeps
+		// the registered not_found code from attributing it to an upstream.
+		const error = new ProviderError("Not found", {
+			code: "not_found",
+			category: "provider_error",
+			retryable: false,
+		});
 		const observabilityDetails = errorObservabilityDetails(error);
 		return responseWithErrorObservability(
 			c.json(
@@ -4354,6 +4368,18 @@ export async function serve<TContext extends Partial<ProviderContext> = Provider
 			!isUnavailableProviderEngine(engineSelection.engine),
 		),
 	);
+	// Same contract for the stores: one line per process boot naming the state
+	// and cache backends this pod resolved, so "which Redis is this provider's
+	// state actually on" is a log grep instead of an inference from the
+	// Deployment spec (apifuse#2302).
+	logger(
+		providerStateBackendLogEvent({
+			providerId: provider.id,
+			sdkVersion: SDK_VERSION,
+			injectedState: options.state !== undefined,
+			allowMemoryFallback: options.allowMemoryStateFallback === true,
+		}),
+	);
 
 	const servers: BunServerHandle[] = [];
 	try {

package/src/server/state-backend-report.ts

@@ -0,0 +1,185 @@
+import {
+	providerCacheRedisResolutionFromEnv,
+	type ProviderRedisUrlResolution,
+	providerStateRedisResolutionFromEnv,
+} from "../config/loader.js";
+
+/**
+ * What a provider store resolved to at boot.
+ *
+ * `endpoint` is deliberately host and port only: the URL can carry a password
+ * (`redis://:secret@host:6379`), and the diagnostic inventory already treats
+ * those credential components — and only those — as sensitive
+ * (`collectDiagnosticSensitiveValues`, `urlCredentialComponents(url, {
+ * includePathAndQuery: false })`). A URL that does not parse contributes no
+ * endpoint at all rather than a redacted-looking fragment of itself.
+ */
+export type ProviderStoreBackendReport = {
+	/**
+	 * `redis` when a URL resolved, `memory` for the in-process fallback,
+	 * `unsupported` when state has no backend and every call fails closed,
+	 * `injected` when the host handed the server a store object.
+	 */
+	readonly backend: "redis" | "memory" | "unsupported" | "injected";
+	/** Env name that supplied the Redis URL. Present only for `redis`. */
+	readonly envName?: string;
+	/**
+	 * `host:port` of the resolved Redis. Never includes credentials, path or
+	 * query. Absent when the URL does not parse, or when its query carries an
+	 * ioredis option that moves the endpoint (`path`, `port`, `host`, `family`)
+	 * so the authority is not where the client connects — see
+	 * `state_redis_url_ambiguous_endpoint`.
+	 */
+	readonly endpoint?: string;
+	/** URL scheme, e.g. `redis` or `rediss`. Present only for `redis`. */
+	readonly scheme?: string;
+	/** True when the URL came from a shared fallback env rather than the store's own. */
+	readonly fallback?: boolean;
+};
+
+/**
+ * One line per process boot naming the stores the provider resolved. Without
+ * it, a provider silently riding the cache Redis for its state is
+ * indistinguishable from one on a durable instance, from outside the pod and
+ * from the pod's own logs (apifuse#2302, the reason apifuse#2144 could only be
+ * verified by inference from the Deployment spec).
+ */
+export type ProviderStateBackendLogEvent = {
+	/** `warn` when a warning was raised, otherwise `info`. */
+	readonly level: "info" | "warn";
+	readonly event: "provider_state_backend";
+	readonly providerId: string;
+	readonly state: ProviderStoreBackendReport;
+	readonly cache: ProviderStoreBackendReport;
+	readonly sdkVersion: string;
+	/**
+	 * Non-fatal findings, e.g. `state_redis_url_fallback` (the state store is
+	 * sharing an instance provisioned for something else),
+	 * `state_redis_url_unparsed`, or `state_redis_url_ambiguous_endpoint` (the
+	 * URL's query carries an ioredis option that moves the endpoint, so the
+	 * authority is not reported as the endpoint). Absent when the resolution
+	 * was unambiguous.
+	 */
+	readonly warnings?: readonly string[];
+};
+
+/**
+ * Whether ioredis' own URL parsing would move the endpoint away from the
+ * authority this function can see. `createProviderRedisClient` hands the raw
+ * URL to `new Redis(url, …)`, and `parseURL` ends with
+ * `defaults(result, queryOptions)` — lodash `defaults`, so a query key only
+ * applies where the authority supplied nothing:
+ *
+ * - `path` is never derived from the authority of a `redis://` URL (that
+ *   pathname is the db index), so `?path=` always applies — and
+ *   `StandaloneConnector` connects to `options.path` INSTEAD of host/port.
+ *   The client is then on a Unix socket the authority says nothing about.
+ * - `port` applies only when the URL carries no explicit port.
+ * - `host` never applies here: we return early unless `parsed.hostname` is
+ *   set, so `result.host` is always already populated.
+ * - `family` selects an address family; it does not move `host:port`.
+ *
+ * Verified against the pinned ioredis 5.11.1. In those cases the endpoint is
+ * WITHHELD and the ambiguity named, rather than reported as the authority — a
+ * diagnostic whose whole job is to answer "which Redis is this provider on"
+ * must not answer it wrongly. The query is never echoed: it can carry a
+ * password, which is why `endpoint` is host-and-port only to begin with.
+ */
+function queryMovesEndpoint(parsed: URL): boolean {
+	if (parsed.searchParams.has("path")) return true;
+	return parsed.searchParams.has("port") && parsed.port === "";
+}
+
+function redisEndpoint(url: string): {
+	endpoint?: string;
+	scheme?: string;
+	ambiguous?: boolean;
+} {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {};
+	}
+	// No authority means this is not the `redis://host:port` shape at all (e.g.
+	// a bare `host:port`, which parses as a scheme). Report nothing rather than
+	// a fragment of a string whose parts we have not identified.
+	if (!parsed.hostname) return {};
+	const scheme = parsed.protocol.replace(/:$/, "");
+	if (queryMovesEndpoint(parsed)) return { scheme, ambiguous: true };
+	return {
+		scheme,
+		endpoint: parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname,
+	};
+}
+
+function redisReport(resolution: ProviderRedisUrlResolution): {
+	report: ProviderStoreBackendReport;
+	parsed: boolean;
+	ambiguous: boolean;
+} {
+	const { endpoint, scheme, ambiguous } = redisEndpoint(resolution.url);
+	return {
+		parsed: endpoint !== undefined || ambiguous === true,
+		ambiguous: ambiguous === true,
+		report: {
+			backend: "redis",
+			envName: resolution.envName,
+			...(endpoint === undefined ? {} : { endpoint }),
+			...(scheme === undefined ? {} : { scheme }),
+			...(resolution.fallback ? { fallback: true } : {}),
+		},
+	};
+}
+
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export function providerStateBackendLogEvent(input: {
+	readonly providerId: string;
+	readonly sdkVersion: string;
+	/** The host passed an explicit state store, so no env resolution happened. */
+	readonly injectedState: boolean;
+	/** Mirrors `createProviderRuntimeStateFromEnv({ allowMemoryFallback })`. */
+	readonly allowMemoryFallback: boolean;
+}): ProviderStateBackendLogEvent {
+	const warnings: string[] = [];
+	let state: ProviderStoreBackendReport;
+	if (input.injectedState) {
+		state = { backend: "injected" };
+	} else {
+		const resolution = providerStateRedisResolutionFromEnv();
+		if (resolution) {
+			const { report, parsed, ambiguous } = redisReport(resolution);
+			state = report;
+			if (!parsed) warnings.push("state_redis_url_unparsed");
+			if (ambiguous) warnings.push("state_redis_url_ambiguous_endpoint");
+			if (resolution.fallback) warnings.push("state_redis_url_fallback");
+		} else {
+			state = { backend: input.allowMemoryFallback ? "memory" : "unsupported" };
+		}
+	}
+
+	const cacheResolution = providerCacheRedisResolutionFromEnv();
+	let cache: ProviderStoreBackendReport;
+	if (cacheResolution) {
+		const { report, parsed, ambiguous } = redisReport(cacheResolution);
+		cache = report;
+		if (!parsed) warnings.push("cache_redis_url_unparsed");
+		if (ambiguous) warnings.push("cache_redis_url_ambiguous_endpoint");
+	} else {
+		cache = { backend: "memory" };
+	}
+
+	return {
+		level: warnings.length > 0 ? "warn" : "info",
+		event: "provider_state_backend",
+		providerId: input.providerId,
+		state,
+		cache,
+		sdkVersion: input.sdkVersion,
+		...(warnings.length === 0 ? {} : { warnings }),
+	};
+}