@apifuse/provider-sdk 2.2.0-beta.13 → 2.2.0-beta.15

package/src/runtime/stealth.ts

@@ -50,6 +50,11 @@ import {
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
 } from "./proxy-retry-policy.js";
+import {
+	evaluateRedirectHop,
+	isRedirectStatus,
+	resolveRedirectUrl,
+} from "./redirects.js";
 import {
 	isSensitiveKey,
 	redactSensitiveError,
@@ -731,16 +736,6 @@ function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	}
 }
 
-function isRedirectStatus(status: number): boolean {
-	return [301, 302, 303, 307, 308].includes(status);
-}
-
-function nextRedirectMethod(status: number, method: StealthMethod): StealthMethod {
-	if (status === 303 && method !== "HEAD") return "GET";
-	if ((status === 301 || status === 302) && method === "POST") return "GET";
-	return method;
-}
-
 function locationHeader(headers: Record<string, string>): string | undefined {
 	for (const [name, value] of Object.entries(headers)) {
 		if (name.toLowerCase() === "location") return value;
@@ -1256,7 +1251,7 @@ function createSessionFetcher(
 					const redactedLocation = location ? redactRedirectUrl(location) : undefined;
 					let nextUrl: string | undefined;
 					try {
-						nextUrl = location ? new URL(location, responseUrl).toString() : undefined;
+						nextUrl = resolveRedirectUrl(location, responseUrl);
 					} catch (error) {
 						throw redactSensitiveError(error, [...sensitiveValues], location, redactedLocation);
 					}
@@ -1297,51 +1292,29 @@ function createSessionFetcher(
 							throw sanitizedError;
 						}
 					}
-					if (shouldStop) {
-						return {
-							final: response,
-							hops,
-							reason: "stopped",
-							cookies: cookieJar.snapshot(),
-							cookieStore: cookieJar.serialize(),
-						};
-					}
-
-					if (!nextUrl) {
-						return {
-							final: response,
-							hops,
-							reason: "missing_location",
-							cookies: cookieJar.snapshot(),
-							cookieStore: cookieJar.serialize(),
-						};
-					}
-
-					if (hops.length > maxHops) {
+					const decision = evaluateRedirectHop({
+						status: response.status,
+						method,
+						nextUrl,
+						shouldStop,
+						redirectCount: hops.length,
+						maxHops,
+						visitedRequests,
+					});
+					if (decision.kind === "stop") {
 						return {
 							final: response,
 							hops,
-							reason: "max_hops",
+							reason: decision.reason,
 							cookies: cookieJar.snapshot(),
 							cookieStore: cookieJar.serialize(),
 						};
 					}
-
-					const nextMethod = nextRedirectMethod(response.status, method);
-					if (nextMethod !== method) {
+					if (decision.nextMethod !== method) {
 						body = undefined;
 					}
-					if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
-						return {
-							final: response,
-							hops,
-							reason: "loop",
-							cookies: cookieJar.snapshot(),
-							cookieStore: cookieJar.serialize(),
-						};
-					}
-					method = nextMethod;
-					currentUrl = nextUrl;
+					method = decision.nextMethod;
+					currentUrl = decision.nextUrl;
 				}
 
 				if (!response) {

package/src/server/index.ts

@@ -1,5 +1,7 @@
 export {
 	createServerApp,
+	ERROR_OBSERVABILITY_HEADER,
+	type ErrorObservabilityDetails,
 	type ProviderServerCloseOptions,
 	type ProviderServerHandle,
 	type ProviderServerLogEvent,

package/src/server/serve.ts

@@ -9,6 +9,7 @@ import {
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
+	isValidationError,
 	ProviderError,
 } from "../errors.js";
 import {
@@ -35,6 +36,7 @@ import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import { createNativeNetworkClient } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
@@ -81,6 +83,7 @@ import type {
 	OperationSseTransport,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderProxyPolicy,
 	ProviderRuntimeState,
 	ProviderStreamEvent,
 	StealthClient,
@@ -108,6 +111,14 @@ import {
 
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+	category: ProviderErrorCategory;
+	taxonomyVersion: string;
+	retryable: boolean;
+	upstreamStatus?: number;
+};
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"] as const;
 const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
@@ -278,6 +289,13 @@ function resolveOperationConnectionId(request: OperationRequest): string | undef
 	return request.connection?.id ?? request.connectionId;
 }
 
+function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
+	if (typeof provider.proxy === "object") return provider.proxy;
+	if (provider.proxy === true) return { mode: "optional" };
+	if (provider.proxy === false) return { mode: "disabled" };
+	return undefined;
+}
+
 function createProviderContext(
 	provider: ProviderDefinition,
 	request: OperationRequest,
@@ -344,6 +362,17 @@ function createProviderContext(
 						engine: provider.browser?.engine,
 					})
 				: createBrowserStub(),
+		...(provider.native
+			? {
+					native: {
+						network: createNativeNetworkClient({
+							egress: provider.native.network,
+							proxyPolicy: resolveNativeProxyPolicy(provider),
+							affinityKey: proxyClientOptions.affinityKey,
+						}),
+					},
+				}
+			: {}),
 		trace: createTraceContext(),
 		auth: createAuthStub(),
 		stt: options.stt ?? createSttClientFromEnv(provider.stt),
@@ -446,6 +475,17 @@ function createAuthFlowContext(
 					? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
 					: createStealthClient(stealthBaseUrl, stealthClientOptions)
 				: createStealthStub(),
+			...(provider.native
+				? {
+						native: {
+							network: createNativeNetworkClient({
+								egress: provider.native.network,
+								proxyPolicy: resolveNativeProxyPolicy(provider),
+								affinityKey: proxyClientOptions.affinityKey,
+							}),
+						},
+					}
+				: {}),
 			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
 			credential,
 			context: flowContextStore.context,
@@ -486,6 +526,7 @@ export type ProviderServerLogEvent =
 			errorCategory?: ProviderErrorCategory;
 			taxonomyVersion?: string;
 			retryable?: boolean;
+			signal?: "unregistered_provider_error_code";
 			issues?: Array<{ path: string; code: string; message: string }>;
 	  })
 	| {
@@ -604,26 +645,28 @@ function zodDetails(error: z.ZodError): Array<{
 }
 
 function toErrorResponse(error: unknown, requestId?: string): OperationErrorResponse {
+	const observability = errorObservabilityDetails(error);
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return {
 			error: {
 				code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
 				message: "Stateful forwarding deadline expired.",
 				...(requestId ? { requestId } : {}),
-				details: { retryable: false },
+				retryable: observability.retryable,
 			},
 		};
 	}
 
 	if (isProviderError(error)) {
-		const details = publicProviderErrorDetails(error);
+		const details = error.details;
 		return {
 			error: {
 				code: error.code ?? "provider_error",
 				message: publicProviderErrorMessage(error),
 				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
 				...(error.fix ? { fix: error.fix } : {}),
-				...(details ? { details } : {}),
+				...(details !== undefined ? { details } : {}),
 			},
 		};
 	}
@@ -634,6 +677,7 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 				code: "invalid_request",
 				message: "Invalid request body",
 				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
 				details: zodDetails(error),
 			},
 		};
@@ -650,6 +694,7 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 			code: "internal_error",
 			message: "Internal error",
 			...(requestId ? { requestId } : {}),
+			retryable: observability.retryable,
 			details: {
 				retryable: false,
 				category: "internal_error",
@@ -659,42 +704,12 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 	};
 }
 
-function publicProviderErrorDetails(error: ProviderError): unknown {
-	const providerDetails = error.details;
-	const observabilityDetails = providerObservabilityDetails(error);
-
-	if (providerDetails === undefined) {
-		return observabilityDetails;
-	}
-	if (observabilityDetails === undefined) {
-		return providerDetails;
-	}
-	if (isPlainRecord(providerDetails) && isPlainRecord(observabilityDetails)) {
-		return { ...providerDetails, ...observabilityDetails };
-	}
-	return {
-		provider: providerDetails,
-		observability: observabilityDetails,
-	};
-}
-
-function isPlainRecord(value: unknown): value is Record<string, unknown> {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 // Accepts `unknown` so the branded guards narrow cleanly from the top: the
 // subtype error classes are structurally compatible with ProviderError, so
 // narrowing from a ProviderError-typed value would collapse the negative branch
 // to `never`. Narrowing from unknown avoids that while still recognizing errors
 // from a duplicate SDK module instance.
-function providerObservabilityDetails(error: unknown):
-	| {
-			category: ProviderErrorCategory;
-			taxonomyVersion: string;
-			retryable: boolean;
-			upstreamStatus?: number;
-	  }
-	| undefined {
+function providerObservabilityDetails(error: unknown): ErrorObservabilityDetails | undefined {
 	// Session-expiry surfaces the credential_expired category + the opt-in
 	// retryable signal so Gateway/Credential Service can refresh and re-drive the
 	// operation (see design.md §4.3 D3). Without this branch the auth error would
@@ -751,6 +766,54 @@ function providerObservabilityDetails(error: unknown):
 	};
 }
 
+function errorObservabilityDetails(error: unknown): ErrorObservabilityDetails {
+	const providerDetails = providerObservabilityDetails(error);
+	if (providerDetails) return providerDetails;
+
+	if (error instanceof z.ZodError || isValidationError(error)) {
+		return {
+			category:
+				isProviderError(error) && error.options?.category
+					? error.options.category
+					: "input_validation",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+		};
+	}
+
+	if (error instanceof StatefulRoutingDeadlineError) {
+		return {
+			category: "timeout",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: false,
+		};
+	}
+
+	if (isProviderError(error)) {
+		return {
+			category: error.options?.category ?? "provider_error",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
+
+	return {
+		category: "internal_error",
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable: false,
+	};
+}
+
+function responseWithErrorObservability(response: Response, error: unknown): Response {
+	const headers = new Headers(response.headers);
+	headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}
+
 function publicProviderErrorMessage(error: ProviderError): string {
 	if (isTransportError(error)) {
 		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
@@ -782,11 +845,6 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 	if (error instanceof StatefulRoutingDeadlineError) {
 		return 504;
 	}
-
-	if (isTransportError(error)) {
-		return error.code === "transport_timeout" ? 504 : 502;
-	}
-
 	if (isProviderError(error)) {
 		switch (error.code) {
 			case "AUTH_REQUIRED":
@@ -812,13 +870,96 @@ function toStatusCode(error: unknown): 400 | 401 | 404 | 429 | 500 | 502 | 503 |
 			case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
 				return 503;
 		}
+		if (isTransportError(error)) {
+			return error.code === "transport_timeout" ? 504 : 502;
+		}
+		if (isValidationError(error)) {
+			return error.options?.category === "output_validation" ? 500 : 400;
+		}
 
-		return 400;
+		return 500;
 	}
 
 	return 500;
 }
 
+// Codes emitted by SDK-owned paths must never be attributed to provider
+// authors by the unregistered-code signal, even when their intentional status
+// is 500. Provider-authored codes not in this registry retain the signal.
+const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
+	"AUTH_PROMPT_UNAVAILABLE",
+	"BROWSER_CDP_POOL_REQUIRED",
+	"BROWSER_RUNTIME_UNSUPPORTED",
+	"STEALTH_RUNTIME_UNSUPPORTED",
+	"SSE_EVENT_UNDECLARED",
+	"STREAM_EVENT_TOO_LARGE",
+	"STREAM_CHUNK_TOO_LARGE",
+	"SSE_RESULT_UNSUPPORTED",
+	"STREAM_RESULT_UNSUPPORTED",
+	"AUTH_FLOW_NOT_CONFIGURED",
+	"refresh_not_supported",
+	"RUNTIME_UNSUPPORTED",
+	"PROVIDER_STATE_UNSUPPORTED",
+	"CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+	"CHOICE_STATE_PAYLOAD_TOO_LARGE",
+	"CHOICE_STATE_UNAVAILABLE",
+	"CHOICE_CONTEXT_REQUIRED",
+	"unsupported_stealth_cookie_store_version",
+	"provider_secret_error",
+	"credential_key_error",
+	"credential_mode_error",
+	"flow_expired",
+	"turn_validation_error",
+	"context_access_error",
+	"UNSUPPORTED_STT_OPTION",
+	"INVALID_STT_AUDIO",
+	"STT_AUDIO_TOO_LARGE",
+	"STT_UPSTREAM_FAILED",
+	"INVALID_STT_VERIFICATION_CODE_OPTIONS",
+	"NO_CODE_FOUND",
+	"AMBIGUOUS_CODE",
+	"retry_invalid_policy",
+	"retry_unsafe_method",
+	"stealth_cookie_store_serialize_failed",
+	"response_too_large",
+	"transport_stream_unavailable",
+	"transport_invalid_method",
+	"http_transport_override_unsupported",
+	"http_redirect_policy_invalid",
+	"http_redirect_stopped",
+	"http_redirect_max_hops",
+	"http_redirect_missing_location",
+	"http_redirect_loop",
+	"transport_invalid_url",
+	"retry_exhausted",
+	"auth_abort_unsafe_data",
+	"credentials_auth_missing_credential_keys",
+	"credentials_auth_missing_credential",
+	"credentials_auth_invalid_login_result",
+	"credentials_auth_unknown_challenge",
+	"credentials_auth_unknown_pending_challenge",
+	"STATEFUL_FORWARDING_NOT_CONFIGURED",
+	"STATEFUL_FORWARDING_SIGNATURE_MISSING",
+	"STATEFUL_FORWARDING_NONCE_INVALID",
+	"STATEFUL_FORWARDING_TIMESTAMP_INVALID",
+	"STATEFUL_FORWARDING_SIGNATURE_INVALID",
+	"STATEFUL_FORWARDING_REPLAY_DETECTED",
+	"STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+	"STATEFUL_FORWARDING_ENVELOPE_INVALID",
+	"STATEFUL_FORWARDING_PROVIDER_MISMATCH",
+	"STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+	"STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+	"STATEFUL_FORWARDING_REQUEST_FAILED",
+	"STATEFUL_FORWARDING_CONTEXT_MISSING",
+	"STATEFUL_FORWARDING_BAD_RESPONSE",
+	"STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+	"STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+	"STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+	"STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+	"STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+	"STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+]);
+
 function extractRequestId(raw: unknown): string | undefined {
 	if (!raw || typeof raw !== "object") {
 		return undefined;
@@ -847,7 +988,13 @@ function logProviderError(
 				: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
-	const details = isProviderError(error) ? providerObservabilityDetails(error) : undefined;
+	const details = errorObservabilityDetails(error);
+	const isUnregisteredProviderErrorCode =
+		status === 500 &&
+		isProviderError(error) &&
+		!isValidationError(error) &&
+		typeof error.code === "string" &&
+		!SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
 	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
 	emit({
 		level: status >= 500 ? "error" : "warn",
@@ -861,15 +1008,12 @@ function logProviderError(
 		code,
 		errorClass,
 		message,
-		...(isTransportError(error) && error.upstreamStatus
-			? { upstreamStatus: error.upstreamStatus }
-			: {}),
-		...(details
-			? {
-					errorCategory: details.category,
-					taxonomyVersion: details.taxonomyVersion,
-					retryable: details.retryable,
-				}
+		...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+		errorCategory: details.category,
+		taxonomyVersion: details.taxonomyVersion,
+		retryable: details.retryable,
+		...(isUnregisteredProviderErrorCode
+			? { signal: "unregistered_provider_error_code" as const }
 			: {}),
 		...(error instanceof z.ZodError ? { issues: zodDetails(error) } : {}),
 	});
@@ -1614,17 +1758,10 @@ export function createServerApp(
 		});
 	}
 
-	app.notFound((c) =>
-		c.json(
-			{
-				error: {
-					code: "not_found",
-					message: "Not found",
-				},
-			},
-			404,
-		),
-	);
+	app.notFound((c) => {
+		const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+		return responseWithErrorObservability(c.json(toErrorResponse(error), 404), error);
+	});
 
 	app.get("/health", (c) =>
 		c.json({
@@ -1786,7 +1923,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1850,7 +1990,10 @@ export function createServerApp(
 			);
 			const telemetryHeader = proxyTelemetry.toHeaderValue();
 			if (telemetryHeader) c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1887,7 +2030,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1924,7 +2070,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1961,7 +2110,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -1998,7 +2150,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 
@@ -2035,7 +2190,10 @@ export function createServerApp(
 				status,
 				finishRequestCost(requestCost),
 			);
-			return c.json(toErrorResponse(error, requestId), status);
+			return responseWithErrorObservability(
+				c.json(toErrorResponse(error, requestId), status),
+				error,
+			);
 		}
 	});
 

package/src/server/types.ts

@@ -26,6 +26,7 @@ export const ErrorEnvelopeSchema = z.object({
 	code: z.string(),
 	message: z.string(),
 	requestId: z.string().optional(),
+	retryable: z.boolean(),
 	fix: z.string().optional(),
 	details: z.unknown().optional(),
 });

package/src/stateful/stateful-provider-owner-forwarder.ts

@@ -35,6 +35,14 @@ type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promi
 
 const MAX_FORWARDED_HEADERS = 32;
 const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+	error: OperationErrorResponseSchema.shape.error.extend({
+		retryable: z.boolean().optional().default(false),
+	}),
+});
 const SENSITIVE_HEADER_NAMES = new Set([
 	"authorization",
 	"cookie",
@@ -253,7 +261,7 @@ async function parseForwardedResponse(response: Response): Promise<StatefulOpera
 		return { output: success.data.data };
 	}
 
-	const error = OperationErrorResponseSchema.safeParse(body);
+	const error = ForwardedOperationErrorResponseSchema.safeParse(body);
 	if (error.success) {
 		throw new StatefulOwnerForwardingError({
 			code: error.data.error.code,