@apifuse/provider-sdk 2.2.0-beta.10 → 2.2.0-beta.12

package/src/stateful/stateful-provider-session-runtime.ts

@@ -0,0 +1,403 @@
+import type { SessionKey } from "./session-key.js";
+
+/** @deprecated Use SessionKey from session-key.ts. */
+export type StatefulProviderSessionKey = SessionKey;
+export type SessionOwnerStatus = "acquiring" | "connected" | "draining" | "expired";
+
+export interface SessionOwnerRecord {
+	/** Runtime-decoded key; registry inputs use the opaque SessionKey type. */
+	readonly sessionKey: string;
+	readonly ownerPodId: string;
+	readonly ownerEndpoint: string;
+	readonly generation: number;
+	readonly leaseExpiresAt: string;
+	readonly status: SessionOwnerStatus;
+	readonly lastUsedAt: string;
+}
+
+export interface AcquireSessionOwnerInput {
+	readonly sessionKey: SessionKey;
+	readonly ownerPodId: string;
+	readonly ownerEndpoint: string;
+	readonly leaseDurationMs: number;
+	readonly status?: Exclude<SessionOwnerStatus, "expired">;
+	readonly now?: Date;
+}
+
+export interface AcquireSessionOwnerResult {
+	readonly record: SessionOwnerRecord;
+	readonly acquired: boolean;
+}
+
+export interface RenewSessionOwnerInput {
+	readonly sessionKey: SessionKey;
+	readonly ownerPodId: string;
+	readonly generation: number;
+	readonly leaseDurationMs: number;
+	readonly status?: Exclude<SessionOwnerStatus, "expired">;
+	readonly now?: Date;
+}
+
+export interface ReleaseSessionOwnerInput {
+	readonly sessionKey: SessionKey;
+	readonly ownerPodId: string;
+	readonly generation: number;
+}
+
+/**
+ * A session-owner registry is a fencing authority. Generations MUST be positive integers and
+ * strictly increase for each successful takeover of a session key, including after expiry or
+ * release. Implementations must retain a high-water mark (a tombstone) for at least the registry's
+ * lifetime; generation values must never be reused.
+ */
+export interface SessionOwnerRegistry {
+	resolve(
+		sessionKey: SessionKey,
+		now?: Date,
+		signal?: AbortSignal,
+	): Promise<SessionOwnerRecord | null>;
+	acquire(
+		input: AcquireSessionOwnerInput,
+		signal?: AbortSignal,
+	): Promise<AcquireSessionOwnerResult>;
+	renew(input: RenewSessionOwnerInput, signal?: AbortSignal): Promise<SessionOwnerRecord | null>;
+	release(input: ReleaseSessionOwnerInput, signal?: AbortSignal): Promise<boolean>;
+}
+
+export interface SessionPoolPolicy {
+	readonly maxSessions: number;
+	/** Disable idle eviction for connection-owned listeners with `"unlimited"`. */
+	readonly idleTimeoutMs: number | "unlimited";
+	/** Disable age-based recycling for expensive healthy sessions with `"unlimited"`. */
+	readonly maxLifetimeMs: number | "unlimited";
+}
+
+export interface ManagedSessionIdentity {
+	readonly connectionId: string;
+	readonly serviceAccountId: string;
+	readonly ownerPodId: string;
+	readonly ownerEndpoint: string;
+	readonly ownerStatus: SessionOwnerStatus;
+}
+
+export interface ManagedSession<T> {
+	readonly sessionKey: string;
+	readonly generation: number;
+	readonly value: T;
+	readonly createdAt: string;
+	readonly lastUsedAt: string;
+	readonly identity?: ManagedSessionIdentity;
+}
+
+type SessionFactory<T> = () => T | Promise<T>;
+type SessionCloseHook<T> = (session: ManagedSession<T>, reason: string) => void | Promise<void>;
+export class InMemorySessionOwnerRegistry implements SessionOwnerRegistry {
+	readonly #owners = new Map<SessionKey, SessionOwnerRecord>();
+	readonly #generationHighWater = new Map<SessionKey, number>();
+
+	async resolve(
+		sessionKey: SessionKey,
+		now: Date = new Date(),
+		signal?: AbortSignal,
+	): Promise<SessionOwnerRecord | null> {
+		signal?.throwIfAborted();
+		const current = this.#owners.get(sessionKey);
+		if (!current || isLeaseExpired(current, now)) return null;
+		validateGeneration(current.generation);
+		return current;
+	}
+
+	async acquire(
+		input: AcquireSessionOwnerInput,
+		signal?: AbortSignal,
+	): Promise<AcquireSessionOwnerResult> {
+		signal?.throwIfAborted();
+		validateLeaseDuration(input.leaseDurationMs);
+		const now = input.now ?? new Date();
+		const current = this.#owners.get(input.sessionKey);
+		if (current && !isLeaseExpired(current, now)) {
+			validateGeneration(current.generation);
+			if (current.ownerPodId !== input.ownerPodId) {
+				return { record: current, acquired: false };
+			}
+			const record = makeOwnerRecord(input, current.generation, now);
+			this.#owners.set(input.sessionKey, record);
+			return { record, acquired: true };
+		}
+
+		const generation =
+			Math.max(current?.generation ?? 0, this.#generationHighWater.get(input.sessionKey) ?? 0) + 1;
+		const record = makeOwnerRecord(input, generation, now);
+		this.#owners.set(input.sessionKey, record);
+		this.#generationHighWater.set(input.sessionKey, generation);
+		return { record, acquired: true };
+	}
+
+	async renew(
+		input: RenewSessionOwnerInput,
+		signal?: AbortSignal,
+	): Promise<SessionOwnerRecord | null> {
+		signal?.throwIfAborted();
+		validateGeneration(input.generation);
+		validateLeaseDuration(input.leaseDurationMs);
+		const now = input.now ?? new Date();
+		const current = this.#owners.get(input.sessionKey);
+		if (
+			!current ||
+			current.ownerPodId !== input.ownerPodId ||
+			current.generation !== input.generation ||
+			isLeaseExpired(current, now)
+		) {
+			return null;
+		}
+
+		const record: SessionOwnerRecord = {
+			...current,
+			leaseExpiresAt: addMs(now, input.leaseDurationMs).toISOString(),
+			status: input.status ?? current.status,
+			lastUsedAt: now.toISOString(),
+		};
+		this.#owners.set(input.sessionKey, record);
+		return record;
+	}
+
+	async release(input: ReleaseSessionOwnerInput, signal?: AbortSignal): Promise<boolean> {
+		signal?.throwIfAborted();
+		validateGeneration(input.generation);
+		const current = this.#owners.get(input.sessionKey);
+		if (
+			!current ||
+			current.ownerPodId !== input.ownerPodId ||
+			current.generation !== input.generation
+		) {
+			return false;
+		}
+		this.#generationHighWater.set(
+			input.sessionKey,
+			Math.max(this.#generationHighWater.get(input.sessionKey) ?? 0, current.generation),
+		);
+		this.#owners.delete(input.sessionKey);
+		return true;
+	}
+}
+
+export class PodLocalSessionPool<T> {
+	readonly #sessions = new Map<string, ManagedSession<T>>();
+	readonly #queues = new Map<string, Promise<void>>();
+	readonly #creates = new Map<string, Promise<ManagedSession<T>>>();
+	#closed = false;
+
+	constructor(
+		private readonly policy: SessionPoolPolicy,
+		private readonly closeSession: SessionCloseHook<T>,
+	) {
+		validatePoolPolicy(policy);
+	}
+
+	async getOrCreate(
+		sessionKey: string,
+		generation: number,
+		factory: SessionFactory<T>,
+		now: Date = new Date(),
+		identity?: ManagedSessionIdentity,
+	): Promise<ManagedSession<T>> {
+		validateGeneration(generation);
+		this.assertOpen(sessionKey);
+		const existingCreate = this.#creates.get(sessionKey);
+		if (existingCreate) {
+			try {
+				await existingCreate;
+			} catch {}
+			this.assertOpen(sessionKey);
+		}
+		const create = this.getOrCreateUnlocked(sessionKey, generation, factory, now, identity);
+		this.#creates.set(sessionKey, create);
+		try {
+			const session = await create;
+			this.assertOpen(sessionKey);
+			return session;
+		} finally {
+			if (this.#creates.get(sessionKey) === create) this.#creates.delete(sessionKey);
+		}
+	}
+
+	private async getOrCreateUnlocked(
+		sessionKey: string,
+		generation: number,
+		factory: SessionFactory<T>,
+		now: Date,
+		identity?: ManagedSessionIdentity,
+	): Promise<ManagedSession<T>> {
+		await this.evictExpired(now);
+
+		const current = this.#sessions.get(sessionKey);
+		if (current && current.generation === generation) {
+			const touched = { ...current, lastUsedAt: now.toISOString() };
+			this.#sessions.delete(sessionKey);
+			this.#sessions.set(sessionKey, touched);
+			return touched;
+		}
+		if (current) await this.closeOne(sessionKey, "generation-changed");
+
+		const session: ManagedSession<T> = {
+			sessionKey,
+			generation,
+			value: await factory(),
+			createdAt: now.toISOString(),
+			lastUsedAt: now.toISOString(),
+			...(identity ? { identity } : {}),
+		};
+		this.#sessions.set(sessionKey, session);
+		await this.evictOverCapacity();
+		return session;
+	}
+
+	async closeAll(reason: string): Promise<void> {
+		this.#closed = true;
+		const errors: unknown[] = [];
+		await Promise.all(
+			[...this.#creates.values()].map(async (create) => {
+				let session: ManagedSession<T>;
+				try {
+					session = await create;
+				} catch {
+					return;
+				}
+				try {
+					await this.closeOne(session.sessionKey, reason);
+				} catch (error) {
+					errors.push(error);
+				}
+			}),
+		);
+		for (const sessionKey of [...this.#sessions.keys()]) {
+			try {
+				await this.closeOne(sessionKey, reason);
+			} catch (error) {
+				errors.push(error);
+			}
+		}
+		if (errors.length > 0) {
+			throw new AggregateError(errors, `Failed to close ${errors.length} stateful session(s).`);
+		}
+	}
+
+	async invalidate(sessionKey: string, reason: string): Promise<void> {
+		await this.closeOne(sessionKey, reason);
+	}
+
+	async runExclusive<R>(sessionKey: string, task: () => R | Promise<R>): Promise<R> {
+		const previous = this.#queues.get(sessionKey) ?? Promise.resolve();
+		const next = previous.then(task, task);
+		const settled = next.then(
+			() => undefined,
+			() => undefined,
+		);
+		this.#queues.set(sessionKey, settled);
+		await settled.finally(() => {
+			if (this.#queues.get(sessionKey) === settled) {
+				this.#queues.delete(sessionKey);
+			}
+		});
+		return next;
+	}
+
+	private async evictExpired(now: Date): Promise<void> {
+		for (const [sessionKey, session] of this.#sessions) {
+			if (isSessionExpired(session, this.policy, now)) {
+				await this.closeOne(sessionKey, "expired");
+			}
+		}
+	}
+
+	private async evictOverCapacity(): Promise<void> {
+		while (this.#sessions.size > this.policy.maxSessions) {
+			const lruKey = this.#sessions.keys().next().value;
+			if (lruKey === undefined) return;
+			await this.closeOne(lruKey, "capacity");
+		}
+	}
+
+	private async closeOne(sessionKey: string, reason: string): Promise<void> {
+		const session = this.#sessions.get(sessionKey);
+		if (!session) return;
+		this.#sessions.delete(sessionKey);
+		await this.closeSession(session, reason);
+	}
+
+	private assertOpen(sessionKey: string): void {
+		if (!this.#closed) return;
+		throw new Error(
+			`Pod-local session pool is closed; cannot get or create session "${sessionKey}".`,
+		);
+	}
+}
+
+function makeOwnerRecord(
+	input: AcquireSessionOwnerInput,
+	generation: number,
+	now: Date,
+): SessionOwnerRecord {
+	validateGeneration(generation);
+	return {
+		sessionKey: input.sessionKey,
+		ownerPodId: input.ownerPodId,
+		ownerEndpoint: input.ownerEndpoint,
+		generation,
+		leaseExpiresAt: addMs(now, input.leaseDurationMs).toISOString(),
+		status: input.status ?? "acquiring",
+		lastUsedAt: now.toISOString(),
+	};
+}
+
+function isLeaseExpired(record: SessionOwnerRecord, now: Date): boolean {
+	return Date.parse(record.leaseExpiresAt) <= now.getTime();
+}
+
+function isSessionExpired<T>(
+	session: ManagedSession<T>,
+	policy: SessionPoolPolicy,
+	now: Date,
+): boolean {
+	const nowMs = now.getTime();
+	return (
+		(policy.idleTimeoutMs !== "unlimited" &&
+			nowMs - Date.parse(session.lastUsedAt) >= policy.idleTimeoutMs) ||
+		(policy.maxLifetimeMs !== "unlimited" &&
+			nowMs - Date.parse(session.createdAt) >= policy.maxLifetimeMs)
+	);
+}
+
+function validateLeaseDuration(leaseDurationMs: number): void {
+	if (!Number.isFinite(leaseDurationMs) || leaseDurationMs <= 0) {
+		throw new Error("Session owner leaseDurationMs must be a positive finite number.");
+	}
+}
+
+function validateGeneration(generation: number): void {
+	if (!Number.isInteger(generation) || generation <= 0) {
+		throw new Error("Session owner generation must be a positive integer.");
+	}
+}
+
+function validatePoolPolicy(policy: SessionPoolPolicy): void {
+	if (!Number.isInteger(policy.maxSessions) || policy.maxSessions <= 0) {
+		throw new Error("Session pool maxSessions must be a positive integer.");
+	}
+	if (
+		policy.idleTimeoutMs !== "unlimited" &&
+		(!Number.isFinite(policy.idleTimeoutMs) || policy.idleTimeoutMs <= 0)
+	) {
+		throw new Error('Session pool idleTimeoutMs must be a positive finite number or "unlimited".');
+	}
+	if (
+		policy.maxLifetimeMs !== "unlimited" &&
+		(!Number.isFinite(policy.maxLifetimeMs) || policy.maxLifetimeMs <= 0)
+	) {
+		throw new Error('Session pool maxLifetimeMs must be a positive finite number or "unlimited".');
+	}
+}
+
+function addMs(date: Date, ms: number): Date {
+	return new Date(date.getTime() + ms);
+}

package/src/stateful-signing.ts

@@ -0,0 +1,46 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+export const STATEFUL_SIGNATURE_HEADER = "x-apifuse-stateful-signature";
+export const STATEFUL_TIMESTAMP_HEADER = "x-apifuse-stateful-timestamp";
+export const STATEFUL_NONCE_HEADER = "x-apifuse-stateful-nonce";
+
+export type StatefulSigningInput = {
+	readonly secret: string;
+	readonly timestamp: string;
+	readonly rawBody: string;
+	readonly method: string;
+	readonly path: string;
+	readonly nonce: string;
+};
+
+export function signStatefulRequestBody(input: StatefulSigningInput): string {
+	return `v1=${createHmac("sha256", input.secret)
+		.update(
+			`v1:${input.method.toUpperCase()}:${input.path}:${input.timestamp}:${input.nonce}.${input.rawBody}`,
+		)
+		.digest("hex")}`;
+}
+
+export function verifyStatefulRequestSignature(
+	input: StatefulSigningInput & { readonly signature: string },
+): boolean {
+	return safeEqualAscii(input.signature, signStatefulRequestBody(input));
+}
+
+export function statefulSignedHeaders(
+	input: Omit<StatefulSigningInput, "nonce"> & { readonly nonce?: string },
+): Record<string, string> {
+	const nonce = input.nonce ?? randomUUID();
+	return {
+		[STATEFUL_SIGNATURE_HEADER]: signStatefulRequestBody({ ...input, nonce }),
+		[STATEFUL_TIMESTAMP_HEADER]: input.timestamp,
+		[STATEFUL_NONCE_HEADER]: nonce,
+	};
+}
+
+function safeEqualAscii(actual: string, expected: string): boolean {
+	const actualBytes = Buffer.from(actual);
+	const expectedBytes = Buffer.from(expected);
+	if (actualBytes.byteLength !== expectedBytes.byteLength) return false;
+	return timingSafeEqual(actualBytes, expectedBytes);
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { SerializedCookieJar } from "tough-cookie";
 
 import type { infer as ZodInfer, ZodType } from "zod";
 
@@ -1051,18 +1052,45 @@ export interface StealthFetchOptions extends RequestOptions {
 }
 
 export interface CookieJar {
-	get(name: string): string | undefined;
-	getAll(): Record<string, string>;
-	toString(): string;
-	find?(predicate: (cookie: string) => boolean): string | undefined;
+	/** URL-less reads use the jar's response URL or session base URL. */
+	get(name: string, url?: string): string | undefined;
+	getAll(url?: string): Record<string, string>;
+	toString(url?: string): string;
+	find?(predicate: (cookie: string) => boolean, url?: string): string | undefined;
+}
+
+/**
+ * Version 1 of the JSON-safe, attribute-preserving stealth cookie store.
+ * The nested jar is tough-cookie's serialized form and retains cookie origin,
+ * Path, Secure, expiry, host-only, and other RFC attributes.
+ */
+export interface StealthCookieStoreV1 {
+	readonly version: 1;
+	readonly jar: SerializedCookieJar;
 }
 
+/** Cookie persistence formats understood by this SDK version. */
+export type StealthCookieStore = StealthCookieStoreV1;
+
 export interface StealthSessionCookies extends CookieJar {
-	has(name: string): boolean;
-	setFromCookieStrings(cookieStrings: readonly string[]): void;
-	toHeader(): string;
+	has(name: string, url?: string): boolean;
+	/** URL-less writes are scoped to the session base URL. */
+	setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+	toHeader(url?: string): string;
+	/**
+	 * Returns every cookie as a flat name/value map, collapsing duplicate names.
+	 * @deprecated Use serialize() for lossless, attribute-preserving persistence.
+	 */
 	snapshot(): Record<string, string>;
+	/**
+	 * Restores flat values as host-only, Path=/ cookies on the session base URL.
+	 * @deprecated Use deserialize() with state produced by serialize().
+	 */
 	restore(cookies: Record<string, string>): void;
+	/** Returns a versioned, JSON-safe, attribute-preserving representation of every cookie. */
+	serialize(): StealthCookieStoreV1;
+	/** Replaces the jar with a previously serialized, attribute-preserving cookie store. */
+	deserialize(state: StealthCookieStore): void;
 	clear(): void;
 }
 
@@ -1108,7 +1136,13 @@ export interface StealthRedirectRunResult {
 	final: StealthResponse;
 	hops: StealthRedirectHop[];
 	reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+	/**
+	 * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
+	 * @deprecated Use cookieStore for lossless persistence.
+	 */
 	cookies: Record<string, string>;
+	/** Versioned, attribute-preserving cookie state accumulated across the redirect chain. */
+	cookieStore: StealthCookieStoreV1;
 }
 
 export interface StealthSession {