@apifuse/provider-sdk 2.2.0-beta.67 → 2.2.0-beta.69

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 }),
+	};
+}

package/src/testing/run.ts

@@ -10,6 +10,7 @@ import { createTestHandleContext } from "../runtime/handle.js";
  */
 const STANDARD_TEST_CONNECTION_ID = "standard-test-connection";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
+import { assertCallerHeadersSupported } from "../runtime/stealth-owned-headers.js";
 import { createUnsupportedOcrClient } from "../runtime/ocr.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
 import {
@@ -356,8 +357,19 @@ function createUpstreamContext(
 		options?: unknown,
 	): Promise<HttpResponse> =>
 		toHttpResponse(await dispatch({ transport: "http", method, url, body, options }));
-	const stealthCall = async (url: string, options?: { method?: string; body?: unknown }) =>
-		toStealthResponse(
+	// The production transport rejects owned headers (User-Agent, Sec-Fetch-*,
+	// sec-ch-ua*, ...) before any byte is sent; the fake applies the same
+	// function, so a provider test fails exactly where production would.
+	const stealthCall = async (
+		url: string,
+		options?: {
+			method?: string;
+			body?: unknown;
+			headers?: Readonly<Record<string, string | readonly string[] | undefined>>;
+		},
+	) => {
+		assertCallerHeadersSupported(options?.headers ?? {});
+		return toStealthResponse(
 			await dispatch({
 				transport: "stealth",
 				method: options?.method?.toUpperCase() ?? "GET",
@@ -367,6 +379,7 @@ function createUpstreamContext(
 			}),
 			url,
 		);
+	};
 
 	const createBrowserPage = (): BrowserPage => {
 		let currentUrl = "about:blank";

package/src/trace-sanitization.ts

@@ -52,7 +52,7 @@ export function sanitizeTraceAttributes(
 				const valueRedactor =
 					typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
 						? diagnosticStructuredRedactor(redact)
-						: diagnosticAttributeRedactor(key, redact);
+						: diagnosticAttributeRedactor(key, redact, value);
 				const sanitizedValue = keyChanged
 					? redactedKey === REDACTION_FAILED
 						? REDACTION_FAILED

package/src/types.ts

@@ -1414,7 +1414,23 @@ export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolic
 	headers?: Record<string, string | string[]>;
 	method?: HttpMethod;
 	body?: string | Buffer;
+	/**
+	 * Defaults to `"follow"`. Every followed hop drops the request-body headers
+	 * when the method changes, `Authorization` and `Proxy-Authorization` when it
+	 * leaves the current origin, and an explicit `Cookie` when it leaves the
+	 * current site (scheme plus registrable domain); after that the session
+	 * cookie jar supplies cookies for the new site.
+	 */
 	redirect?: "follow" | "manual" | "error";
+	/**
+	 * Opt-in same-origin redirect enforcement, the ctx.http `redirectPolicy`
+	 * for the stealth transport. A redirect whose target leaves the initial
+	 * origin, exceeds `maxHops` (at most 10, the stealth redirect limit),
+	 * loops, or has no usable `Location` throws `HttpRedirectError` before any
+	 * request is sent to that target. Requires the default
+	 * `redirect: "follow"`.
+	 */
+	redirectPolicy?: HttpRedirectPolicy;
 	/**
 	 * Maximum decoded response-body bytes to buffer. When set, the stealth
 	 * transport aborts the response and throws `response_too_large` if the
@@ -1440,13 +1456,21 @@ export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolic
 		 * replacement for hand-set `Sec-Fetch-*` headers, which the transport
 		 * rejects; it drives `Sec-Fetch-Mode`/`Dest`/`User`, `Accept`, `Priority`,
 		 * and `Upgrade-Insecure-Requests`.
+		 *
+		 * `form-post` is an HTML `<form method="post">` submission: a navigation
+		 * (`navigate`/`document`, the document `Accept`, `Upgrade-Insecure-Requests`)
+		 * that carries a body, in the header order Chrome uses for it, with
+		 * `Cache-Control: max-age=0` and the caller's `Content-Type`, `Origin` and
+		 * `Referer` in place. It is never inferred, since a form submission and a
+		 * script `fetch()` POST look the same to the transport.
 		 */
-		requestClass?: "navigation" | "xhr" | "post";
+		requestClass?: "navigation" | "form-post" | "xhr" | "post";
 		/**
-		 * Whether a `navigation` request carries a user gesture and therefore
-		 * `Sec-Fetch-User: ?1` (default `true`). Set `false` for script-driven
-		 * navigations such as `location.replace`, which Chrome sends without it.
-		 * Ignored for the `xhr` and `post` request classes.
+		 * Whether a `navigation` or `form-post` request carries a user gesture and
+		 * therefore `Sec-Fetch-User: ?1` (default `true`). Set `false` for
+		 * script-driven navigations such as `location.replace` or
+		 * `form.submit()`, which Chrome sends without it. Ignored for the `xhr` and
+		 * `post` request classes.
 		 */
 		userActivation?: boolean;
 		/**
@@ -1551,7 +1575,7 @@ export interface StealthRedirectHop {
 }
 
 export interface StealthRedirectRunOptions
-	extends Omit<StealthFetchOptions, "redirect"> {
+	extends Omit<StealthFetchOptions, "redirect" | "redirectPolicy"> {
 	url: string;
 	maxHops?: number;
 	stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;