@apifuse/provider-sdk 2.2.0-beta.20 → 2.2.0-beta.21

package/src/runtime/state.ts

@@ -17,6 +17,93 @@ import {
 
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
 const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+const LEGACY_INDEX_SCAN_COUNT = 256;
+const LEGACY_INDEX_SCAN_MAX_PAGES = 8;
+const SET_WITH_QUOTA_SCRIPT = `
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local expires_at = tonumber(ARGV[3])
+local index_ttl = tonumber(ARGV[4])
+local envelope = ARGV[5]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = redis.call("EXISTS", KEYS[1])
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+
+const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
+local current = redis.call("GET", KEYS[1])
+local current_version = 0
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if not ok or type(decoded) ~= "table" or type(decoded.version) ~= "number" then
+		return {-2, current}
+	end
+	current_version = decoded.version
+end
+if current_version ~= tonumber(ARGV[1]) then
+	return {-1, current or false}
+end
+
+local now = tonumber(ARGV[2])
+local max_entries = tonumber(ARGV[3])
+local expires_at = tonumber(ARGV[4])
+local index_ttl = tonumber(ARGV[5])
+local envelope = ARGV[6]
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = current and 1 or 0
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+
+const DELETE_WITH_INDEX_SCRIPT = `
+redis.call("DEL", KEYS[1])
+redis.call("ZREM", KEYS[2], KEYS[1])
+return 1
+`;
+
+// Older SDKs wrote only the value key. Every operation that depends on the
+// namespace index advances a bounded SCAN cursor and lazily imports active
+// legacy envelopes into the new ZSET. The cursor is
+// deliberately cyclic rather than permanently "complete": an old pod may
+// still write an unindexed key during a rolling deploy. Each list/write call
+// does a fixed amount of migration work; Redis KEYS and unbounded scans remain
+// forbidden.
+const BACKFILL_LEGACY_INDEX_SCRIPT = `
+local now = tonumber(ARGV[1])
+local index_ttl = tonumber(ARGV[2])
+local next_cursor = ARGV[3]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", now)
+for i = 4, #ARGV, 3 do
+	local key = ARGV[i]
+	local expected = ARGV[i + 1]
+	local expires_at = tonumber(ARGV[i + 2])
+	if redis.call("GET", key) == expected then
+		redis.call("ZADD", KEYS[1], "NX", expires_at, key)
+	end
+end
+if redis.call("EXISTS", KEYS[1]) == 1 then
+	redis.call("PEXPIRE", KEYS[1], index_ttl)
+end
+redis.call("SET", KEYS[2], next_cursor, "PX", index_ttl)
+return redis.call("ZCARD", KEYS[1])
+`;
 
 type RedisProviderRuntimeStateOptions = {
 	readonly redisUrl: string;
@@ -87,6 +174,10 @@ function publicStateKey(
 	return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
 }
 
+function redisGlobLiteral(value: string): string {
+	return value.replace(/[\\*?\[\]]/g, "\\$&");
+}
+
 function parseStateDurationMs(ttl: StateWriteOptions["ttl"]): number {
 	const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
 	if (!match) return 3_600_000;
@@ -171,13 +262,91 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		return providerStateKey(this.providerId, this.namespaceName, key);
 	}
 
-	private prefix(): string {
+	private indexKey(): string {
+		// Keep bookkeeping outside the caller-owned keyspace. A provider may use
+		// any state key (including "__index"), so a suffix inside the namespace
+		// could turn the ZSET into a string and break every subsequent write.
+		const namespaceIdentity = Buffer.from(
+			providerStatePrefix(this.providerId, this.namespaceName),
+			"utf8",
+		).toString("base64url");
+		return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
+	}
+
+	private legacyScanCursorKey(): string {
+		return `${this.indexKey()}:legacy-scan-cursor`;
+	}
+
+	private legacyPrefix(): string {
 		return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
 	}
 
-	private async activeKeys(): Promise<string[]> {
+	private async backfillLegacyIndex(): Promise<void> {
 		await requireRedisReady(this.backend.redis);
-		return await withRequiredRedis(() => this.backend.redis.keys(`${this.prefix()}*`));
+		const cursorKey = this.legacyScanCursorKey();
+		let cursor =
+			(await withRequiredRedis(() => this.backend.redis.get(cursorKey))) ?? "0";
+		const pattern = `${redisGlobLiteral(this.legacyPrefix())}*`;
+		const indexTtlMs = parseStateDurationMs(this.options.maxTtl);
+
+		for (let page = 0; page < LEGACY_INDEX_SCAN_MAX_PAGES; page += 1) {
+			const [nextCursor, keys] = await withRequiredRedis(() =>
+				this.backend.redis.scan(
+					cursor,
+					"MATCH",
+					pattern,
+					"COUNT",
+					LEGACY_INDEX_SCAN_COUNT,
+				),
+			);
+			const rawValues =
+				keys.length > 0
+					? await withRequiredRedis(() => this.backend.redis.mget(keys))
+					: [];
+			const now = Date.now();
+			const activeLegacyArgs: string[] = [];
+			for (const [index, raw] of rawValues.entries()) {
+				const key = keys[index];
+				if (!key || !raw) continue;
+				const envelope = envelopeFromJson(
+					publicStateKey(this.providerId, this.namespaceName, key),
+					raw,
+				);
+				const expiresAtMs = envelope ? Date.parse(envelope.expiresAt) : Number.NaN;
+				if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now) continue;
+				activeLegacyArgs.push(key, raw, String(expiresAtMs));
+			}
+			await withRequiredRedis(() =>
+				this.backend.redis.eval(
+					BACKFILL_LEGACY_INDEX_SCRIPT,
+					2,
+					this.indexKey(),
+					cursorKey,
+					String(now),
+					String(indexTtlMs),
+					nextCursor,
+					...activeLegacyArgs,
+				),
+			);
+			cursor = nextCursor;
+			if (cursor === "0") break;
+		}
+	}
+
+	private async indexedKeys(limit: number): Promise<string[]> {
+		await requireRedisReady(this.backend.redis);
+		const now = Date.now();
+		return await withRequiredRedis(async () => {
+			await this.backend.redis.zremrangebyscore(this.indexKey(), "-inf", now);
+			return await this.backend.redis.zrangebyscore(
+				this.indexKey(),
+				now + 1,
+				"+inf",
+				"LIMIT",
+				0,
+				limit,
+			);
+		});
 	}
 
 	private enforceValueSize(value: unknown): void {
@@ -189,23 +358,41 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		}
 	}
 
-	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) {
+	private quotaExceeded(): UnsupportedProviderStateError {
+		return new UnsupportedProviderStateError(
+			`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`,
+		);
+	}
+
+	private writeTiming(ttl: StateWriteOptions["ttl"]): {
+		expiresAt: string;
+		expiresAtMs: number;
+		indexTtlMs: number;
+	} {
+		const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+		const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+		if (ttlMs > maxTtlMs) {
 			throw new UnsupportedProviderStateError(
-				`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`,
+				`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`,
 			);
 		}
+		const expiresAtMs = Date.now() + ttlMs;
+		return {
+			expiresAt: new Date(expiresAtMs).toISOString(),
+			expiresAtMs,
+			indexTtlMs: maxTtlMs,
+		};
 	}
 
 	async list<T>(options?: { limit?: number; prefix?: string }): Promise<StateValue<T>[]> {
-		const keys = (await this.activeKeys()).filter((key) => {
+		const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+		if (requestedLimit === 0) return [];
+		await this.backfillLegacyIndex();
+		const keys = (await this.indexedKeys(this.options.maxEntries)).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));
+		const limited = keys.slice(0, requestedLimit);
 		if (limited.length === 0) return [];
 		const values = await withRequiredRedis(() => this.backend.redis.mget(limited));
 		return values.flatMap((raw, index) => {
@@ -224,22 +411,34 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 
 	async set<T>(key: string, value: T, options?: StateWriteOptions): Promise<StateValue<T>> {
 		this.enforceValueSize(value);
-		await this.enforceMaxEntries(key);
+		await this.backfillLegacyIndex();
 		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),
+		const timing = this.writeTiming(options?.ttl);
+		const envelope = redisEnvelope(value, version, createdAt, timing.expiresAt);
+		await requireRedisReady(this.backend.redis);
+		const result = await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				SET_WITH_QUOTA_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+				String(Date.now()),
+				String(this.options.maxEntries),
+				String(timing.expiresAtMs),
+				String(timing.indexTtlMs),
+				JSON.stringify(envelope),
+			),
 		);
+		if (!Array.isArray(result) || Number(result[0]) !== 1) {
+			throw this.quotaExceeded();
+		}
 		return {
 			key,
 			value,
 			version,
-			expiresAt,
+			expiresAt: timing.expiresAt,
 			createdAt,
 			updatedAt: envelope.updatedAt,
 		};
@@ -263,16 +462,64 @@ class RedisProviderStateNamespace implements ProviderStateNamespace {
 		options?: StateWriteOptions,
 	): Promise<StateCasResult<T>> {
 		this.enforceValueSize(value);
+		await this.backfillLegacyIndex();
 		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) };
+		const createdAt = current?.createdAt ?? new Date().toISOString();
+		const timing = this.writeTiming(options?.ttl);
+		const envelope = redisEnvelope(
+			value,
+			expectedVersion + 1,
+			createdAt,
+			timing.expiresAt,
+		);
+		await requireRedisReady(this.backend.redis);
+		const result = await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				COMPARE_AND_SET_WITH_QUOTA_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+				String(expectedVersion),
+				String(Date.now()),
+				String(this.options.maxEntries),
+				String(timing.expiresAtMs),
+				String(timing.indexTtlMs),
+				JSON.stringify(envelope),
+			),
+		);
+		if (Array.isArray(result) && Number(result[0]) === 0) {
+			throw this.quotaExceeded();
+		}
+		if (!Array.isArray(result) || Number(result[0]) !== 1) {
+			const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+			return { ok: false, current: envelopeFromJson(key, rawCurrent) };
+		}
+		return {
+			ok: true,
+			value: {
+				key,
+				value,
+				version: envelope.version,
+				expiresAt: timing.expiresAt,
+				createdAt,
+				updatedAt: envelope.updatedAt,
+			},
+		};
 	}
 
 	async delete(key: string): Promise<void> {
 		await requireRedisReady(this.backend.redis);
-		await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+		await withRequiredRedis(() =>
+			this.backend.redis.eval(
+				DELETE_WITH_INDEX_SCRIPT,
+				2,
+				this.redisKey(key),
+				this.indexKey(),
+			),
+		);
 	}
 
 	async increment(
@@ -358,6 +605,31 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 
 	constructor(private readonly options: StateNamespaceOptions) {}
 
+	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 enforceWritePolicy(key: string, value: unknown, ttl: StateWriteOptions["ttl"]): void {
+		this.enforceValueSize(value);
+		const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+		const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+		if (ttlMs > maxTtlMs) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`,
+			);
+		}
+		if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+			throw new UnsupportedProviderStateError(
+				`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`,
+			);
+		}
+	}
+
 	private pruneExpired(nowMs = Date.now()): void {
 		for (const [key, row] of this.values.entries()) {
 			if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -381,6 +653,7 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 
 	async set<T>(key: string, value: T, options?: StateWriteOptions): Promise<StateValue<T>> {
 		this.pruneExpired();
+		this.enforceWritePolicy(key, value, options?.ttl);
 		const now = new Date().toISOString();
 		const current = this.values.get(key);
 		const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
@@ -407,14 +680,30 @@ class MemoryProviderStateNamespace implements ProviderStateNamespace {
 	}
 
 	async compareAndSet<T>(
-		_key: string,
-		_expectedVersion: number,
-		_value: T,
-		_options?: StateWriteOptions,
+		key: string,
+		expectedVersion: number,
+		value: T,
+		options?: StateWriteOptions,
 	): Promise<StateCasResult<T>> {
-		throw new UnsupportedProviderStateError(
-			"In-memory provider runtime state does not support compareAndSet",
-		);
+		this.pruneExpired();
+		const current = this.values.get(key) as StateValue<T> | undefined;
+		if ((current?.version ?? 0) !== expectedVersion) {
+			return { ok: false, current: current ?? null };
+		}
+		this.enforceWritePolicy(key, value, options?.ttl);
+		const now = new Date().toISOString();
+		const stored = {
+			key,
+			value,
+			version: expectedVersion + 1,
+			expiresAt: resolveMemoryStateExpiresAt(
+				options?.ttl ?? this.options.defaultTtl,
+			),
+			createdAt: current?.createdAt ?? now,
+			updatedAt: now,
+		} satisfies StateValue<T>;
+		this.values.set(key, stored);
+		return { ok: true, value: stored };
 	}
 
 	async delete(key: string): Promise<void> {

package/src/server/serve.ts

@@ -478,6 +478,7 @@ function createAuthFlowContext(
 
 	return {
 		context: {
+			flowId: request.flowId,
 			connectionId: request.connectionId,
 			externalRef: request.externalRef,
 			tenantId: request.tenantId ?? "",
@@ -502,7 +503,12 @@ function createAuthFlowContext(
 						},
 					}
 				: {}),
-			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+			env: createEnvContext([
+				...(provider.secrets?.map((secret) => secret.name) ?? []),
+				...(provider.auth?.mode === "oauth2_proxied"
+					? ["APIFUSE__AUTH_PROXY__URL"]
+					: []),
+			]),
 			credential,
 			context: flowContextStore.context,
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
@@ -531,7 +537,7 @@ export type ProviderServerLogEvent =
 	| (ProviderServerLogEventBase & {
 			level: "info";
 			event: "provider_request_completed";
-	  })
+		})
 	| (ProviderServerLogEventBase & {
 			level: "warn" | "error";
 			event: "provider_request_failed";
@@ -545,13 +551,13 @@ export type ProviderServerLogEvent =
 			signal?: "unregistered_provider_error_code";
 			signalFix?: string;
 			issues?: Array<{ path: string; code: string; message: string }>;
-	  })
+		})
 	| {
 			level: "warn";
 			event: "provider_secrets_missing";
 			providerId: string;
 			missingSecrets: string[];
-	  }
+		}
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";
@@ -562,7 +568,7 @@ export type ProviderServerLogEvent =
 			resource: "browser" | "stealth";
 			errorClass: string;
 			message: string;
-	  }
+		}
 	| {
 			level: "error";
 			event: "provider_shutdown_hook_failed";
@@ -570,7 +576,7 @@ export type ProviderServerLogEvent =
 			hookIndex: number;
 			errorClass: string;
 			message: string;
-	  };
+		};
 
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 
@@ -599,14 +605,14 @@ export type ProviderServerOptions = {
 	 * @example
 	 * ```ts
 	 * await serve(provider, {
-	 *   shutdown: {
-	 *     hooks: [
-	 *       async () => { await emitter.flush(); },
-	 *       async () => { await sessionManager.closeAll("server-shutdown"); },
-	 *       async () => { await lease.release(); },
-	 *       async () => { await router.close(); },
-	 *     ],
-	 *   },
+	 *	 shutdown: {
+	 *		 hooks: [
+	 *			 async () => { await emitter.flush(); },
+	 *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+	 *			 async () => { await lease.release(); },
+	 *			 async () => { await router.close(); },
+	 *		 ],
+	 *	 },
 	 * });
 	 * ```
 	 */

package/src/server/types.ts

@@ -3,7 +3,13 @@ import { PROVIDER_ERROR_SOURCES } from "../observability.js";
 
 import { HttpRetryPreset } from "../types.js";
 
-export const ConnectionModeSchema = z.enum(["oauth2", "credentials", "platform-managed", "none"]);
+export const ConnectionModeSchema = z.enum([
+	"oauth2",
+	"oauth2_proxied",
+	"credentials",
+	"platform-managed",
+	"none",
+]);
 
 export const OperationConnectionSchema = z.object({
 	id: z.string(),

package/src/testing/run.ts

@@ -29,7 +29,13 @@ import type {
 // A single lowercase segment (no hyphen) is a valid id, so the trailing group
 // is optional (`*`), matching providers like `kakaomap`, `kstartup`, `triple`.
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
+const VALID_AUTH_MODES = [
+	"none",
+	"platform-managed",
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] as const;
 const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 const snapshotCaptureStates = new WeakMap<
 	ProviderContext,
@@ -754,7 +760,7 @@ function formatJsonDiff(current: unknown, expected: unknown): string {
 
 		if (currentLine === expectedLine) {
 			if (currentLine !== undefined) {
-				lines.push(`  ${currentLine}`);
+				lines.push(`	${currentLine}`);
 			}
 			continue;
 		}