@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.6

package/src/runtime/executor.ts

@@ -1,4 +1,4 @@
-import { ProviderError } from "../errors";
+import { ProviderError, SessionExpiredError } from "../errors";
 import { parseSchema } from "../schema";
 import type { ProviderContext, ProviderDefinition } from "../types";
 
@@ -51,7 +51,24 @@ export async function executeOperation(
 			Promise.resolve(operation.handler(ctx, validatedInput)),
 		);
 
-	const result = await execute();
+	let result: unknown;
+	try {
+		result = await execute();
+	} catch (error) {
+		// Session expiry is renewed by Credential Service via the /auth/refresh
+		// route, NOT in-process here: this executor cannot mutate ctx.credential,
+		// so an in-process retry would just repeat the call with the same stale
+		// credential (and risk repeating partial side-effects). Instead we surface
+		// the expiry so Credential Service refreshes and re-drives the operation
+		// with a fresh credential. `retryOnAuthRefresh` declares that this
+		// operation is safe to re-drive after refresh, which we signal by marking
+		// the surfaced error retryable; non-idempotent operations (the default)
+		// stay non-retryable so they are not auto-re-driven. See design.md §4.3 D3.
+		if (error instanceof SessionExpiredError && operation.retryOnAuthRefresh) {
+			throw new SessionExpiredError(error.message, { retryable: true });
+		}
+		throw error;
+	}
 
 	if (isStreamingOperation(provider, operationId)) {
 		return result;

package/src/runtime/redis.ts

@@ -0,0 +1,116 @@
+import Redis from "ioredis";
+
+export type ProviderRedisClient = Redis;
+
+export type ProviderRedisClientOptions = {
+	readonly redisUrl: string;
+	readonly timeoutMs: number;
+	readonly onError: () => void;
+};
+
+type RedisTimeoutOptions<T> = {
+	readonly timeoutMs: number;
+	readonly onTimeout: () => T;
+	readonly onError?: (error: unknown) => T;
+};
+
+export function createProviderRedisClient(
+	options: ProviderRedisClientOptions,
+): ProviderRedisClient {
+	const redis = new Redis(options.redisUrl, {
+		connectTimeout: options.timeoutMs,
+		enableOfflineQueue: false,
+		lazyConnect: true,
+		maxRetriesPerRequest: 0,
+		retryStrategy: () => null,
+	});
+	redis.on("error", options.onError);
+	return redis;
+}
+
+export async function withRedisTimeout<T>(
+	operation: () => Promise<T>,
+	options: RedisTimeoutOptions<T>,
+): Promise<T> {
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	try {
+		const timeout = new Promise<T>((resolve, reject) => {
+			timeoutId = setTimeout(() => {
+				try {
+					resolve(options.onTimeout());
+				} catch (error) {
+					reject(error);
+				}
+			}, options.timeoutMs);
+		});
+		const operationResult = options.onError
+			? operation().catch(options.onError)
+			: operation();
+		return await Promise.race([operationResult, timeout]);
+	} finally {
+		if (timeoutId) clearTimeout(timeoutId);
+	}
+}
+
+export function redisStatus(redis: ProviderRedisClient): string {
+	return redis.status;
+}
+
+async function waitForRedisReady(
+	redis: ProviderRedisClient,
+	timeoutMs: number,
+): Promise<boolean> {
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+	let settled = false;
+
+	return await new Promise<boolean>((resolve) => {
+		const cleanup = () => {
+			if (timeoutId) clearTimeout(timeoutId);
+			redis.off("ready", onReady);
+			redis.off("close", onUnavailable);
+			redis.off("end", onUnavailable);
+			redis.off("error", onUnavailable);
+		};
+		const finish = (ready: boolean) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(ready);
+		};
+		const onReady = () => finish(true);
+		const onUnavailable = () => finish(false);
+
+		timeoutId = setTimeout(
+			() => finish(redisStatus(redis) === "ready"),
+			timeoutMs,
+		);
+		redis.once("ready", onReady);
+		redis.once("close", onUnavailable);
+		redis.once("end", onUnavailable);
+		redis.once("error", onUnavailable);
+	});
+}
+
+export async function ensureRedisReady(
+	redis: ProviderRedisClient,
+	timeoutMs: number,
+): Promise<boolean> {
+	if (redisStatus(redis) === "ready") return true;
+
+	if (redisStatus(redis) === "wait" || redisStatus(redis) === "end") {
+		const connected = await withRedisTimeout(
+			async () => {
+				await redis.connect();
+				return true;
+			},
+			{
+				timeoutMs,
+				onTimeout: () => false,
+				onError: () => false,
+			},
+		);
+		return connected && redisStatus(redis) === "ready";
+	}
+
+	return await waitForRedisReady(redis, timeoutMs);
+}

package/src/runtime/state.ts

@@ -1,3 +1,4 @@
+import { providerStateRedisUrlFromEnv } from "../config/loader";
 import { ProviderError } from "../errors";
 import type {
 	ProviderRuntimeState,
@@ -7,6 +8,340 @@ import type {
 	StateValue,
 	StateWriteOptions,
 } from "../types";
+import {
+	createProviderRedisClient,
+	ensureRedisReady,
+	type ProviderRedisClient,
+	withRedisTimeout,
+} from "./redis";
+
+const DEFAULT_REDIS_TIMEOUT_MS = 250;
+const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+
+type RedisProviderRuntimeStateOptions = {
+	readonly redisUrl: string;
+	readonly providerId?: string;
+};
+
+type RedisStateEnvelope = {
+	readonly value: unknown;
+	readonly version: number;
+	readonly expiresAt: string;
+	readonly createdAt: string;
+	readonly updatedAt: string;
+};
+
+type RedisBackend = {
+	readonly redis: ProviderRedisClient;
+};
+
+const redisBackends = new Map<string, RedisBackend>();
+
+function getRedisBackend(redisUrl: string): RedisBackend {
+	const existing = redisBackends.get(redisUrl);
+	if (existing) return existing;
+	const redis = createProviderRedisClient({
+		redisUrl,
+		timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
+		onError: () => {
+			// Runtime state operations fail closed at their call sites. Avoid noisy
+			// unhandled Redis errors from background reconnect attempts.
+		},
+	});
+	const backend = { redis };
+	redisBackends.set(redisUrl, backend);
+	return backend;
+}
+
+async function withRequiredRedis<T>(operation: () => Promise<T>): Promise<T> {
+	return await withRedisTimeout(operation, {
+		timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
+		onTimeout: () => {
+			throw new UnsupportedProviderStateError(
+				"Provider runtime state Redis timed out",
+			);
+		},
+		onError: () => {
+			throw new UnsupportedProviderStateError(
+				"Provider runtime state Redis is unavailable",
+			);
+		},
+	});
+}
+
+async function requireRedisReady(redis: ProviderRedisClient): Promise<void> {
+	if (await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS)) return;
+	throw new UnsupportedProviderStateError(
+		"Provider runtime state Redis is unavailable",
+	);
+}
+
+function providerStatePrefix(
+	providerId: string | undefined,
+	namespace: string,
+): string {
+	return `${REDIS_STATE_PREFIX}:${providerId ?? "default"}:${namespace}`;
+}
+
+function providerStateKey(
+	providerId: string | undefined,
+	namespace: string,
+	key: string,
+): string {
+	return `${providerStatePrefix(providerId, namespace)}:${key}`;
+}
+
+function publicStateKey(
+	providerId: string | undefined,
+	namespace: string,
+	redisKey: string,
+): string {
+	const prefix = `${providerStatePrefix(providerId, namespace)}:`;
+	return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
+}
+
+function parseStateDurationMs(ttl: StateWriteOptions["ttl"]): number {
+	const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
+	if (!match) return 3_600_000;
+	const amount = Number(match[1]);
+	const unit = match[2];
+	const multiplier =
+		unit === "ms"
+			? 1
+			: unit === "s"
+				? 1_000
+				: unit === "m"
+					? 60_000
+					: unit === "h"
+						? 3_600_000
+						: 86_400_000;
+	return Math.max(1, amount * multiplier);
+}
+
+function resolveExpiresAt(ttl: StateWriteOptions["ttl"]): string {
+	return new Date(Date.now() + parseStateDurationMs(ttl)).toISOString();
+}
+
+function envelopeFromJson(
+	key: string,
+	raw: string | null,
+	// biome-ignore lint/suspicious/noExplicitAny: state envelopes deserialize caller-owned generic values.
+): StateValue<any> | null {
+	if (!raw) return null;
+	const parsed: unknown = JSON.parse(raw);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return null;
+	}
+	const record: Record<string, unknown> = Object.fromEntries(
+		Object.entries(parsed),
+	);
+	if (
+		typeof record.version !== "number" ||
+		typeof record.expiresAt !== "string" ||
+		typeof record.createdAt !== "string" ||
+		typeof record.updatedAt !== "string" ||
+		!("value" in record)
+	) {
+		return null;
+	}
+	return {
+		key,
+		value: record.value,
+		version: record.version,
+		expiresAt: record.expiresAt,
+		createdAt: record.createdAt,
+		updatedAt: record.updatedAt,
+	};
+}
+
+function redisEnvelope(
+	value: unknown,
+	version: number,
+	createdAt: string,
+	expiresAt: string,
+): RedisStateEnvelope {
+	const updatedAt = new Date().toISOString();
+	return { value, version, expiresAt, createdAt, updatedAt };
+}
+
+class RedisProviderStateNamespace implements ProviderStateNamespace {
+	constructor(
+		private readonly backend: RedisBackend,
+		private readonly providerId: string | undefined,
+		private readonly namespaceName: string,
+		private readonly options: StateNamespaceOptions,
+	) {}
+
+	private redisKey(key: string): string {
+		return providerStateKey(this.providerId, this.namespaceName, key);
+	}
+
+	private prefix(): string {
+		return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
+	}
+
+	private async activeKeys(): Promise<string[]> {
+		await requireRedisReady(this.backend.redis);
+		return await withRequiredRedis(() =>
+			this.backend.redis.keys(`${this.prefix()}*`),
+		);
+	}
+
+	private enforceValueSize(value: unknown): void {
+		const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+		if (bytes > this.options.maxValueBytes) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`,
+			);
+		}
+	}
+
+	private async enforceMaxEntries(key: string): Promise<void> {
+		const keys = await this.activeKeys();
+		const redisKey = this.redisKey(key);
+		const otherKeys = keys.filter((candidate) => candidate !== redisKey);
+		if (otherKeys.length >= this.options.maxEntries) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`,
+			);
+		}
+	}
+
+	async list<T>(options?: {
+		limit?: number;
+		prefix?: string;
+	}): Promise<StateValue<T>[]> {
+		const keys = (await this.activeKeys()).filter((key) => {
+			const publicKey = publicStateKey(
+				this.providerId,
+				this.namespaceName,
+				key,
+			);
+			return options?.prefix ? publicKey.startsWith(options.prefix) : true;
+		});
+		const limited = keys.slice(0, Math.max(0, options?.limit ?? keys.length));
+		if (limited.length === 0) return [];
+		const values = await withRequiredRedis(() =>
+			this.backend.redis.mget(limited),
+		);
+		return values.flatMap((raw, index) => {
+			const key = limited[index];
+			if (!key) return [];
+			const value = envelopeFromJson(
+				publicStateKey(this.providerId, this.namespaceName, key),
+				raw,
+			);
+			return value ? [value] : [];
+		});
+	}
+
+	async get<T>(key: string): Promise<StateValue<T> | null> {
+		await requireRedisReady(this.backend.redis);
+		const raw = await withRequiredRedis(() =>
+			this.backend.redis.get(this.redisKey(key)),
+		);
+		return envelopeFromJson(key, raw);
+	}
+
+	async set<T>(
+		key: string,
+		value: T,
+		options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		this.enforceValueSize(value);
+		await this.enforceMaxEntries(key);
+		const current = await this.get<T>(key);
+		const createdAt = current?.createdAt ?? new Date().toISOString();
+		const version = (current?.version ?? 0) + 1;
+		const ttl = options?.ttl ?? this.options.defaultTtl;
+		const ttlMs = parseStateDurationMs(ttl);
+		const expiresAt = resolveExpiresAt(ttl);
+		const envelope = redisEnvelope(value, version, createdAt, expiresAt);
+		await withRequiredRedis(() =>
+			this.backend.redis.set(
+				this.redisKey(key),
+				JSON.stringify(envelope),
+				"PX",
+				ttlMs,
+			),
+		);
+		return {
+			key,
+			value,
+			version,
+			expiresAt,
+			createdAt,
+			updatedAt: envelope.updatedAt,
+		};
+	}
+
+	async patch<T extends Record<string, unknown>>(
+		key: string,
+		partial: Partial<T>,
+		options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		const current = (await this.get<Record<string, unknown>>(key))?.value ?? {};
+		// biome-ignore lint/suspicious/noExplicitAny: patch preserves the caller-provided generic state shape.
+		const merged: any = { ...current, ...partial };
+		return await this.set<T>(key, merged, options);
+	}
+
+	async compareAndSet<T>(
+		key: string,
+		expectedVersion: number,
+		value: T,
+		options?: StateWriteOptions,
+	): Promise<StateCasResult<T>> {
+		this.enforceValueSize(value);
+		const current = await this.get<T>(key);
+		if ((current?.version ?? 0) !== expectedVersion) {
+			return { ok: false, current };
+		}
+		return { ok: true, value: await this.set(key, value, options) };
+	}
+
+	async delete(key: string): Promise<void> {
+		await requireRedisReady(this.backend.redis);
+		await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+	}
+
+	async increment(
+		key: string,
+		field: string,
+		delta = 1,
+		options?: StateWriteOptions,
+	): Promise<StateValue<Record<string, unknown>>> {
+		const current = (await this.get<Record<string, unknown>>(key))?.value ?? {};
+		const previous = typeof current[field] === "number" ? current[field] : 0;
+		return await this.set(
+			key,
+			{ ...current, [field]: previous + delta },
+			options,
+		);
+	}
+}
+
+class RedisProviderRuntimeState implements ProviderRuntimeState {
+	readonly backend: RedisBackend;
+	readonly providerId?: string;
+
+	constructor(options: RedisProviderRuntimeStateOptions) {
+		this.backend = getRedisBackend(options.redisUrl);
+		this.providerId = options.providerId;
+	}
+
+	namespace(
+		name: string,
+		options: StateNamespaceOptions,
+	): ProviderStateNamespace {
+		return new RedisProviderStateNamespace(
+			this.backend,
+			this.providerId,
+			name,
+			options,
+		);
+	}
+}
 
 export class UnsupportedProviderStateError extends ProviderError {
 	constructor(
@@ -71,6 +406,158 @@ class UnsupportedProviderRuntimeState implements ProviderRuntimeState {
 	}
 }
 
+class MemoryProviderStateNamespace implements ProviderStateNamespace {
+	// biome-ignore lint/suspicious/noExplicitAny: in-memory state stores heterogeneous generic values by key.
+	readonly values = new Map<string, StateValue<any>>();
+
+	constructor(private readonly options: StateNamespaceOptions) {}
+
+	private pruneExpired(nowMs = Date.now()): void {
+		for (const [key, row] of this.values.entries()) {
+			if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
+				this.values.delete(key);
+			}
+		}
+	}
+
+	async list<T>(_options?: {
+		limit?: number;
+		prefix?: string;
+	}): Promise<StateValue<T>[]> {
+		this.pruneExpired();
+		const rows = Array.from(this.values.values()).filter((value) =>
+			_options?.prefix ? value.key.startsWith(_options.prefix) : true,
+		);
+		return rows.slice(0, _options?.limit);
+	}
+
+	async get<T>(key: string): Promise<StateValue<T> | null> {
+		this.pruneExpired();
+		return this.values.get(key) ?? null;
+	}
+
+	async set<T>(
+		key: string,
+		value: T,
+		options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		this.pruneExpired();
+		const now = new Date().toISOString();
+		const current = this.values.get(key);
+		const expiresAt = resolveMemoryStateExpiresAt(
+			options?.ttl ?? this.options.defaultTtl,
+		);
+		const row = {
+			key,
+			value,
+			version: (current?.version ?? 0) + 1,
+			expiresAt,
+			createdAt: current?.createdAt ?? now,
+			updatedAt: now,
+		} satisfies StateValue<T>;
+		this.values.set(key, row);
+		return row;
+	}
+
+	async patch<T extends Record<string, unknown>>(
+		_key: string,
+		_partial: Partial<T>,
+		_options?: StateWriteOptions,
+	): Promise<StateValue<T>> {
+		throw new UnsupportedProviderStateError(
+			"In-memory provider runtime state does not support patch",
+		);
+	}
+
+	async compareAndSet<T>(
+		_key: string,
+		_expectedVersion: number,
+		_value: T,
+		_options?: StateWriteOptions,
+	): Promise<StateCasResult<T>> {
+		throw new UnsupportedProviderStateError(
+			"In-memory provider runtime state does not support compareAndSet",
+		);
+	}
+
+	async delete(key: string): Promise<void> {
+		this.values.delete(key);
+	}
+
+	async increment(
+		_key: string,
+		_field: string,
+		_delta = 1,
+		_options?: StateWriteOptions,
+	): Promise<StateValue<Record<string, unknown>>> {
+		throw new UnsupportedProviderStateError(
+			"In-memory provider runtime state does not support increment",
+		);
+	}
+}
+
+class MemoryProviderRuntimeState implements ProviderRuntimeState {
+	readonly namespaces = new Map<string, MemoryProviderStateNamespace>();
+
+	namespace(
+		name: string,
+		_options: StateNamespaceOptions,
+	): ProviderStateNamespace {
+		const existing = this.namespaces.get(name);
+		if (existing) return existing;
+		const created = new MemoryProviderStateNamespace(_options);
+		this.namespaces.set(name, created);
+		return created;
+	}
+}
+
+function resolveMemoryStateExpiresAt(ttl: StateWriteOptions["ttl"]): string {
+	const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
+	if (!match) return new Date(Date.now() + 3_600_000).toISOString();
+	const amount = Number(match[1]);
+	const unit = match[2];
+	const multiplier =
+		unit === "ms"
+			? 1
+			: unit === "s"
+				? 1_000
+				: unit === "m"
+					? 60_000
+					: unit === "h"
+						? 3_600_000
+						: 86_400_000;
+	return new Date(Date.now() + amount * multiplier).toISOString();
+}
+
+export function createRedisProviderRuntimeState(
+	options: RedisProviderRuntimeStateOptions,
+): ProviderRuntimeState {
+	return new RedisProviderRuntimeState(options);
+}
+
+export function createProviderRuntimeStateFromEnv(
+	options: {
+		readonly providerId?: string;
+		readonly allowMemoryFallback?: boolean;
+	} = {},
+): ProviderRuntimeState {
+	const redisUrl = providerStateRedisUrlFromEnv();
+	if (redisUrl) {
+		return createRedisProviderRuntimeState({
+			redisUrl,
+			providerId: options.providerId,
+		});
+	}
+	if (options.allowMemoryFallback === true) {
+		return new MemoryProviderRuntimeState();
+	}
+	return createUnsupportedProviderRuntimeState();
+}
+
+export function createMemoryProviderRuntimeState(): ProviderRuntimeState {
+	return new MemoryProviderRuntimeState();
+}
+
 export function createUnsupportedProviderRuntimeState(): ProviderRuntimeState {
 	return new UnsupportedProviderRuntimeState();
 }

package/src/runtime/stealth.ts

@@ -776,12 +776,19 @@ function createSessionFetcher(
 		options?: StealthFetchOptions,
 		proxyAttempt?: number,
 	): Promise<ResolvedAttemptProxy> {
+		const rawProxyAttemptOffset = options?.proxyAttemptOffset ?? 0;
+		const proxyAttemptOffset = Number.isFinite(rawProxyAttemptOffset)
+			? Math.max(0, Math.floor(rawProxyAttemptOffset))
+			: 0;
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
 			upstream: clientOptions.upstream,
 			apifuseConfig: clientOptions.apifuseConfig,
 			affinityKey: clientOptions.affinityKey,
-			proxyAttempt,
+			proxyAttempt:
+				proxyAttempt === undefined
+					? proxyAttemptOffset
+					: proxyAttemptOffset + proxyAttempt,
 			telemetry: clientOptions.telemetry,
 		});