@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/dist/stateful/stateful-provider-session-routing.js

@@ -0,0 +1,345 @@
+import { StatefulRoutingDeadlineError } from "./errors.js";
+import { NOOP_STATEFUL_PROVIDER_METRIC_EMITTER, } from "./stateful-provider-observability.js";
+export { forwardingContextFromStatefulRuntimeContext, isStatefulOperationRuntimeContext, providerContextFromStatefulRuntimeContext, statefulForwardingContextFromProviderRequest, withStatefulLocalProviderContext, } from "./stateful-provider-runtime-context.js";
+export { StatefulRoutingDeadlineError } from "./errors.js";
+export class StatefulRoutingOwnershipError extends Error {
+    requestId;
+    sessionKey;
+    constructor(requestId, sessionKey, message) {
+        super(message);
+        this.name = "StatefulRoutingOwnershipError";
+        this.requestId = requestId;
+        this.sessionKey = sessionKey;
+    }
+}
+const STATEFUL_SESSION_ESTABLISHMENT_FAILURE = Symbol.for("@apifuse/provider-sdk/stateful/session-establishment-failure@1");
+function isStatefulSessionEstablishmentFailure(error) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function")
+        return false;
+    return (Object.getOwnPropertyDescriptor(error, STATEFUL_SESSION_ESTABLISHMENT_FAILURE)?.value === true);
+}
+export class StatefulSessionRouter {
+    #currentPod;
+    #registry;
+    #forwarder;
+    #executor;
+    #leaseDurationMs;
+    #leaseRenewIntervalMs;
+    #clock;
+    #metricEmitter;
+    #managedLeases = new Map();
+    #latestLocalAttempts = new Map();
+    #establishmentQueues = new Map();
+    #nextLocalAttempt = 0;
+    constructor(options) {
+        validateRouterLeaseDuration(options.leaseDurationMs);
+        const renewalFraction = options.leaseRenewalFraction ?? 1 / 3;
+        validateLeaseRenewalFraction(renewalFraction);
+        this.#currentPod = options.currentPod;
+        this.#registry = options.registry;
+        this.#forwarder = options.forwarder;
+        this.#executor = options.executor;
+        this.#leaseDurationMs = options.leaseDurationMs;
+        this.#leaseRenewIntervalMs = Math.max(1, Math.floor(options.leaseDurationMs * renewalFraction));
+        this.#clock = options.clock ?? (() => new Date());
+        this.#metricEmitter = options.metricEmitter ?? NOOP_STATEFUL_PROVIDER_METRIC_EMITTER;
+    }
+    async route(request) {
+        const now = this.#clock();
+        if (isExpiredDeadline(request, now)) {
+            this.#metricEmitter.increment("apifuse_stateful_provider_routing_deadline_expired_total", {
+                requestId: request.requestId,
+                providerId: request.providerId,
+                connectionId: request.connectionId,
+                serviceAccountId: request.serviceAccountId,
+                operationId: request.operationId,
+                sessionKey: request.sessionKey,
+                redactedErrorCode: "deadline_expired",
+            });
+            throw new StatefulRoutingDeadlineError(request.requestId, request.deadlineAt);
+        }
+        const deadlineSignal = makeDeadlineSignal(request, now);
+        try {
+            const route = await this.runEstablishmentTask(request.sessionKey, async () => {
+                const resolved = await this.#registry.resolve(request.sessionKey, now, deadlineSignal.signal);
+                if (resolved) {
+                    validateOwnerGeneration(resolved);
+                    return this.prepareRouteToOwner(request, resolved, deadlineSignal.signal);
+                }
+                const acquired = await this.#registry.acquire({
+                    sessionKey: request.sessionKey,
+                    ownerPodId: this.#currentPod.podId,
+                    ownerEndpoint: this.#currentPod.endpoint,
+                    leaseDurationMs: this.#leaseDurationMs,
+                    status: "acquiring",
+                    now,
+                }, deadlineSignal.signal);
+                validateOwnerGeneration(acquired.record);
+                this.#metricEmitter.increment("apifuse_stateful_provider_routing_reacquire_total", metricLabels(request, acquired.record));
+                return this.prepareRouteToOwner(request, acquired.record, deadlineSignal.signal);
+            });
+            return await this.routeToOwner(request, route, deadlineSignal);
+        }
+        finally {
+            deadlineSignal.cleanup();
+        }
+    }
+    async release() {
+        const sessionKeys = new Set([
+            ...this.#managedLeases.keys(),
+            ...this.#latestLocalAttempts.keys(),
+        ]);
+        await Promise.all([...sessionKeys].map((key) => this.releaseSession(key)));
+    }
+    async releaseSession(sessionKey) {
+        return this.runEstablishmentTask(sessionKey, async () => {
+            try {
+                const managed = this.#managedLeases.get(sessionKey);
+                if (!managed)
+                    return false;
+                this.stopManagedLease(managed);
+                this.#managedLeases.delete(sessionKey);
+                return await this.#registry.release({
+                    sessionKey,
+                    ownerPodId: managed.record.ownerPodId,
+                    generation: managed.record.generation,
+                });
+            }
+            finally {
+                this.#latestLocalAttempts.delete(sessionKey);
+            }
+        });
+    }
+    /** @internal Test-only visibility into local-attempt lifecycle cleanup. */
+    get latestLocalAttemptCountForTesting() {
+        return this.#latestLocalAttempts.size;
+    }
+    async prepareRouteToOwner(request, owner, signal) {
+        if (owner.sessionKey !== request.sessionKey) {
+            throw new StatefulRoutingOwnershipError(request.requestId, request.sessionKey, "Resolved stateful session owner does not match request session key.");
+        }
+        if (owner.ownerPodId !== this.#currentPod.podId) {
+            this.forgetManagedLease(request.sessionKey);
+            this.#metricEmitter.increment("apifuse_stateful_provider_routing_forward_total", metricLabels(request, owner));
+            return { owner };
+        }
+        const localAttempt = ++this.#nextLocalAttempt;
+        this.#latestLocalAttempts.set(request.sessionKey, localAttempt);
+        try {
+            const validatedOwner = await this.validateLocalOwnership(request, owner, signal, false);
+            this.ensureManagedLease(request.sessionKey, validatedOwner);
+            this.#metricEmitter.increment("apifuse_stateful_provider_routing_local_total", metricLabels(request, validatedOwner));
+            return { owner: validatedOwner, localAttempt };
+        }
+        catch (error) {
+            if (this.#latestLocalAttempts.get(request.sessionKey) === localAttempt) {
+                this.#latestLocalAttempts.delete(request.sessionKey);
+            }
+            throw error;
+        }
+    }
+    async routeToOwner(request, route, deadlineSignal) {
+        const { owner, localAttempt } = route;
+        if (localAttempt !== undefined) {
+            try {
+                return await this.#executor.executeLocal(request, owner, deadlineSignal.signal, (expected, signal) => this.runEstablishmentTask(request.sessionKey, () => this.validateLocalOwnership(request, expected, signal, true)));
+            }
+            catch (error) {
+                if (isStatefulSessionEstablishmentFailure(error)) {
+                    await this.releaseFailedEstablishment(request.sessionKey, owner, localAttempt);
+                }
+                throw error;
+            }
+        }
+        return this.#forwarder.forward(owner, request, deadlineSignal.signal);
+    }
+    ensureManagedLease(sessionKey, owner) {
+        const current = this.#managedLeases.get(sessionKey);
+        if (current &&
+            current.record.ownerPodId === owner.ownerPodId &&
+            current.record.generation === owner.generation) {
+            current.record = owner;
+            return;
+        }
+        if (current)
+            this.stopManagedLease(current);
+        const managed = { sessionKey, record: owner };
+        this.#managedLeases.set(sessionKey, managed);
+        this.scheduleRenewal(managed);
+    }
+    scheduleRenewal(managed) {
+        managed.timer = setTimeout(() => void this.renewManagedLease(managed), this.#leaseRenewIntervalMs);
+        managed.timer.unref?.();
+    }
+    async renewManagedLease(managed) {
+        if (this.#managedLeases.get(managed.sessionKey) !== managed)
+            return;
+        try {
+            const renewed = await this.#registry.renew({
+                sessionKey: managed.sessionKey,
+                ownerPodId: managed.record.ownerPodId,
+                generation: managed.record.generation,
+                leaseDurationMs: this.#leaseDurationMs,
+                now: this.#clock(),
+            });
+            if (!renewed) {
+                this.forgetManagedLease(managed.sessionKey);
+                return;
+            }
+            validateOwnerGeneration(renewed);
+            managed.record = renewed;
+        }
+        catch {
+            // A transient control-plane failure is retried on the next renewal interval.
+        }
+        finally {
+            if (this.#managedLeases.get(managed.sessionKey) === managed) {
+                this.scheduleRenewal(managed);
+            }
+        }
+    }
+    async validateLocalOwnership(request, expected, signal, markConnected) {
+        const resolved = await this.#registry.resolve(request.sessionKey, this.#clock(), signal);
+        if (!sameOwner(resolved, expected)) {
+            this.forgetManagedLease(request.sessionKey);
+            throw ownershipChanged(request);
+        }
+        if (!markConnected)
+            return resolved;
+        const connected = await this.#registry.renew({
+            sessionKey: request.sessionKey,
+            ownerPodId: resolved.ownerPodId,
+            generation: resolved.generation,
+            leaseDurationMs: this.#leaseDurationMs,
+            status: "connected",
+            now: this.#clock(),
+        }, signal);
+        if (!sameOwner(connected, expected)) {
+            this.forgetManagedLease(request.sessionKey);
+            throw ownershipChanged(request);
+        }
+        validateOwnerGeneration(connected);
+        this.ensureManagedLease(request.sessionKey, connected);
+        return connected;
+    }
+    forgetManagedLease(sessionKey) {
+        this.#latestLocalAttempts.delete(sessionKey);
+        const managed = this.#managedLeases.get(sessionKey);
+        if (!managed)
+            return;
+        this.stopManagedLease(managed);
+        this.#managedLeases.delete(sessionKey);
+    }
+    async releaseFailedEstablishment(sessionKey, owner, localAttempt) {
+        await this.runEstablishmentTask(sessionKey, async () => {
+            if (this.#latestLocalAttempts.get(sessionKey) !== localAttempt)
+                return;
+            try {
+                const managed = this.#managedLeases.get(sessionKey);
+                if (managed &&
+                    managed.record.ownerPodId === owner.ownerPodId &&
+                    managed.record.generation === owner.generation) {
+                    this.stopManagedLease(managed);
+                    this.#managedLeases.delete(sessionKey);
+                }
+                try {
+                    await this.#registry.release({
+                        sessionKey,
+                        ownerPodId: owner.ownerPodId,
+                        generation: owner.generation,
+                    });
+                }
+                catch (error) {
+                    try {
+                        console.error(JSON.stringify({
+                            event: "stateful_session_establishment_lease_release_failed",
+                            sessionKey: owner.sessionKey,
+                            ownerPodId: owner.ownerPodId,
+                            generation: owner.generation,
+                            errorClass: error instanceof Error ? error.name : "UnknownError",
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            finally {
+                if (this.#latestLocalAttempts.get(sessionKey) === localAttempt) {
+                    this.#latestLocalAttempts.delete(sessionKey);
+                }
+            }
+        });
+    }
+    async runEstablishmentTask(sessionKey, task) {
+        const previous = this.#establishmentQueues.get(sessionKey) ?? Promise.resolve();
+        const next = previous.then(task, task);
+        const settled = next.then(() => undefined, () => undefined);
+        this.#establishmentQueues.set(sessionKey, settled);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.#establishmentQueues.get(sessionKey) === settled) {
+                this.#establishmentQueues.delete(sessionKey);
+            }
+        }
+    }
+    stopManagedLease(managed) {
+        if (managed.timer)
+            clearTimeout(managed.timer);
+        managed.timer = undefined;
+    }
+}
+function metricLabels(request, owner) {
+    return {
+        requestId: request.requestId,
+        providerId: request.providerId,
+        connectionId: request.connectionId,
+        serviceAccountId: request.serviceAccountId,
+        operationId: request.operationId,
+        sessionKey: request.sessionKey,
+        ownerPodId: owner.ownerPodId,
+        generation: owner.generation,
+    };
+}
+function validateRouterLeaseDuration(leaseDurationMs) {
+    if (!Number.isFinite(leaseDurationMs) || leaseDurationMs <= 0) {
+        throw new Error("Stateful session router leaseDurationMs must be a positive finite number.");
+    }
+}
+function validateLeaseRenewalFraction(fraction) {
+    if (!Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
+        throw new Error("Stateful session router leaseRenewalFraction must be greater than 0 and less than 1.");
+    }
+}
+function validateOwnerGeneration(owner) {
+    if (!Number.isInteger(owner.generation) || owner.generation <= 0) {
+        throw new Error("Stateful session owner generation must be a positive integer.");
+    }
+}
+function sameOwner(actual, expected) {
+    return (actual !== null &&
+        actual.sessionKey === expected.sessionKey &&
+        actual.ownerPodId === expected.ownerPodId &&
+        actual.generation === expected.generation);
+}
+function ownershipChanged(request) {
+    return new StatefulRoutingOwnershipError(request.requestId, request.sessionKey, "Stateful session ownership changed before the local provider invocation.");
+}
+function isExpiredDeadline(request, now) {
+    if (!request.deadlineAt)
+        return false;
+    const deadlineMs = Date.parse(request.deadlineAt);
+    return !Number.isFinite(deadlineMs) || deadlineMs <= now.getTime();
+}
+function makeDeadlineSignal(request, now) {
+    const controller = new AbortController();
+    if (!request.deadlineAt) {
+        return { signal: controller.signal, cleanup: () => { } };
+    }
+    const delayMs = Date.parse(request.deadlineAt) - now.getTime();
+    const timer = setTimeout(() => controller.abort(), delayMs);
+    return {
+        signal: controller.signal,
+        cleanup: () => clearTimeout(timer),
+    };
+}

package/dist/stateful/stateful-provider-session-runtime.d.ts

@@ -0,0 +1,98 @@
+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 declare class InMemorySessionOwnerRegistry implements SessionOwnerRegistry {
+    #private;
+    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 declare class PodLocalSessionPool<T> {
+    #private;
+    private readonly policy;
+    private readonly closeSession;
+    constructor(policy: SessionPoolPolicy, closeSession: SessionCloseHook<T>);
+    getOrCreate(sessionKey: string, generation: number, factory: SessionFactory<T>, now?: Date, identity?: ManagedSessionIdentity): Promise<ManagedSession<T>>;
+    private getOrCreateUnlocked;
+    closeAll(reason: string): Promise<void>;
+    invalidate(sessionKey: string, reason: string): Promise<void>;
+    runExclusive<R>(sessionKey: string, task: () => R | Promise<R>): Promise<R>;
+    private evictExpired;
+    private evictOverCapacity;
+    private closeOne;
+    private assertOpen;
+}
+export {};

package/dist/stateful/stateful-provider-session-runtime.js

@@ -0,0 +1,245 @@
+export class InMemorySessionOwnerRegistry {
+    #owners = new Map();
+    #generationHighWater = new Map();
+    async resolve(sessionKey, now = new Date(), signal) {
+        signal?.throwIfAborted();
+        const current = this.#owners.get(sessionKey);
+        if (!current || isLeaseExpired(current, now))
+            return null;
+        validateGeneration(current.generation);
+        return current;
+    }
+    async acquire(input, signal) {
+        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, signal) {
+        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 = {
+            ...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, signal) {
+        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 {
+    policy;
+    closeSession;
+    #sessions = new Map();
+    #queues = new Map();
+    #creates = new Map();
+    #closed = false;
+    constructor(policy, closeSession) {
+        this.policy = policy;
+        this.closeSession = closeSession;
+        validatePoolPolicy(policy);
+    }
+    async getOrCreate(sessionKey, generation, factory, now = new Date(), identity) {
+        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);
+        }
+    }
+    async getOrCreateUnlocked(sessionKey, generation, factory, now, identity) {
+        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 = {
+            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) {
+        this.#closed = true;
+        const errors = [];
+        await Promise.all([...this.#creates.values()].map(async (create) => {
+            let session;
+            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, reason) {
+        await this.closeOne(sessionKey, reason);
+    }
+    async runExclusive(sessionKey, task) {
+        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;
+    }
+    async evictExpired(now) {
+        for (const [sessionKey, session] of this.#sessions) {
+            if (isSessionExpired(session, this.policy, now)) {
+                await this.closeOne(sessionKey, "expired");
+            }
+        }
+    }
+    async evictOverCapacity() {
+        while (this.#sessions.size > this.policy.maxSessions) {
+            const lruKey = this.#sessions.keys().next().value;
+            if (lruKey === undefined)
+                return;
+            await this.closeOne(lruKey, "capacity");
+        }
+    }
+    async closeOne(sessionKey, reason) {
+        const session = this.#sessions.get(sessionKey);
+        if (!session)
+            return;
+        this.#sessions.delete(sessionKey);
+        await this.closeSession(session, reason);
+    }
+    assertOpen(sessionKey) {
+        if (!this.#closed)
+            return;
+        throw new Error(`Pod-local session pool is closed; cannot get or create session "${sessionKey}".`);
+    }
+}
+function makeOwnerRecord(input, generation, now) {
+    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, now) {
+    return Date.parse(record.leaseExpiresAt) <= now.getTime();
+}
+function isSessionExpired(session, policy, now) {
+    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) {
+    if (!Number.isFinite(leaseDurationMs) || leaseDurationMs <= 0) {
+        throw new Error("Session owner leaseDurationMs must be a positive finite number.");
+    }
+}
+function validateGeneration(generation) {
+    if (!Number.isInteger(generation) || generation <= 0) {
+        throw new Error("Session owner generation must be a positive integer.");
+    }
+}
+function validatePoolPolicy(policy) {
+    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, ms) {
+    return new Date(date.getTime() + ms);
+}