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

package/dist/stateful/stateful-provider-adapter.js

@@ -0,0 +1,287 @@
+import { makeStatefulProviderCloseContext, makeStatefulProviderSessionContext, } from "./stateful-provider-adapter-context.js";
+import { emitStatefulSessionInvalidatedMetric, observeStatefulSessionOperationDuration, } from "./stateful-provider-adapter-metrics.js";
+import { NOOP_STATEFUL_PROVIDER_METRIC_EMITTER, } from "./stateful-provider-observability.js";
+import { PodLocalSessionPool } from "./stateful-provider-session-runtime.js";
+export class StatefulSessionInvalidatedError extends Error {
+    name = "StatefulSessionInvalidatedError";
+    reason;
+    retryable;
+    constructor(message, options) {
+        super(message);
+        this.reason = options.reason;
+        this.retryable = options.retryable ?? false;
+    }
+}
+const STATEFUL_SESSION_ESTABLISHMENT_FAILURE = Symbol.for("@apifuse/provider-sdk/stateful/session-establishment-failure@1");
+function markStatefulSessionEstablishmentFailure(error) {
+    if ((typeof error === "object" && error !== null) || typeof error === "function") {
+        try {
+            Object.defineProperty(error, STATEFUL_SESSION_ESTABLISHMENT_FAILURE, {
+                value: true,
+                enumerable: false,
+            });
+            return error;
+        }
+        catch { }
+    }
+    const wrapped = new Error("Stateful session establishment failed.", { cause: error });
+    Object.defineProperty(wrapped, STATEFUL_SESSION_ESTABLISHMENT_FAILURE, { value: true });
+    return wrapped;
+}
+export class StatefulProviderSessionManager {
+    #adapter;
+    #pool;
+    #checkpointStore;
+    #eventPublisher;
+    #clock;
+    #metricEmitter;
+    #eventDisposers = new Map();
+    #eventOwnerFences = new Map();
+    #parallelLimiters = new Map();
+    constructor(options) {
+        validateAdapterConfiguration(options);
+        this.#adapter = options.adapter;
+        this.#checkpointStore = options.checkpointStore;
+        this.#eventPublisher = options.eventPublisher;
+        this.#clock = options.clock ?? (() => new Date());
+        this.#metricEmitter = options.metricEmitter ?? NOOP_STATEFUL_PROVIDER_METRIC_EMITTER;
+        this.#pool = new PodLocalSessionPool(options.poolPolicy, (session, reason) => this.closeManagedSession(session, reason));
+    }
+    async invoke(owner, request, signal, validateOwnership) {
+        const startedAt = this.#clock().getTime();
+        const run = async () => {
+            const managedSession = await this.getOrCreate(owner, request, signal, validateOwnership);
+            const validatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+            const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            try {
+                const result = await this.#adapter.invoke(ctx, managedSession.value, request);
+                this.observeDuration(request, owner, startedAt);
+                return result;
+            }
+            catch (error) {
+                if (!(error instanceof StatefulSessionInvalidatedError))
+                    throw error;
+                emitStatefulSessionInvalidatedMetric({
+                    metricEmitter: this.#metricEmitter,
+                    request,
+                    owner,
+                    reason: error.reason,
+                });
+                await this.#pool.invalidate(owner.sessionKey, error.reason);
+                if (!error.retryable || this.#adapter.policy.reconnect === "unsupported")
+                    throw error;
+                const reconnected = await this.getOrCreate(owner, request, signal, validateOwnership);
+                const revalidatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+                const reconnectedCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, revalidatedOwner, request, signal);
+                const result = await this.#adapter.invoke(reconnectedCtx, reconnected.value, request);
+                this.observeDuration(request, owner, startedAt);
+                return result;
+            }
+        };
+        return this.schedule(owner.sessionKey, run);
+    }
+    executeLocal(request, owner, signal, validateOwnership) {
+        return this.invoke(owner, request, signal, validateOwnership);
+    }
+    async health(owner, request, signal, validateOwnership) {
+        if (!this.#adapter.health) {
+            throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" has no health hook.`);
+        }
+        return this.schedule(owner.sessionKey, async () => {
+            const session = await this.getOrCreate(owner, request, signal, validateOwnership);
+            const validatedOwner = await this.validatePooledOwnership(owner, request.sessionKey, signal, validateOwnership);
+            return this.#adapter.health?.(makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal), session.value);
+        });
+    }
+    async reconcileWrite(owner, request, ledgerEntry, signal, validateOwnership) {
+        if (!this.#adapter.reconcileWrite) {
+            throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" does not support write reconciliation.`);
+        }
+        return this.schedule(owner.sessionKey, async () => {
+            const restoreCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, owner, request, signal);
+            const sharedState = this.#adapter.restore
+                ? await this.#adapter.restore(restoreCtx)
+                : undefined;
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            return this.#adapter.reconcileWrite?.(ctx, ledgerEntry, sharedState);
+        });
+    }
+    closeAll(reason) {
+        return this.#pool.closeAll(reason);
+    }
+    async getOrCreate(owner, request, signal, validateOwnership) {
+        return this.#pool.getOrCreate(owner.sessionKey, owner.generation, () => this.connect(owner, request, signal, validateOwnership), this.#clock(), managedSessionIdentity(owner, request));
+    }
+    async connect(owner, request, signal, validateOwnership) {
+        const ctx = makeStatefulProviderSessionContext(this.#adapter.providerId, owner, request, signal);
+        let session;
+        let connected = false;
+        try {
+            const sharedState = this.#adapter.restore ? await this.#adapter.restore(ctx) : undefined;
+            session = await this.#adapter.connect(ctx, sharedState);
+            connected = true;
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            const validatedCtx = makeStatefulProviderSessionContext(this.#adapter.providerId, validatedOwner, request, signal);
+            this.refreshEventOwnerFence(validatedOwner, request.sessionKey);
+            if (!this.#adapter.subscribe || !this.#eventPublisher)
+                return session;
+            const identityKey = sessionIdentityKey(owner.sessionKey, owner.generation);
+            const disposer = await this.#adapter.subscribe(validatedCtx, session, (event) => {
+                const ownerFence = this.#eventOwnerFences.get(identityKey);
+                if (!ownerFence)
+                    return;
+                this.#eventPublisher?.publish(event, { ownerFence });
+            });
+            if (typeof disposer !== "function") {
+                throw new Error(`Stateful provider adapter "${this.#adapter.providerId}" subscribe hook must return a disposer.`);
+            }
+            this.#eventDisposers.set(identityKey, disposer);
+            return session;
+        }
+        catch (error) {
+            this.#eventOwnerFences.delete(sessionIdentityKey(owner.sessionKey, owner.generation));
+            let establishmentError = error;
+            if (connected) {
+                try {
+                    await this.#adapter.close(ctx, session, "session-establishment-failed");
+                }
+                catch (closeError) {
+                    establishmentError = new AggregateError([error, closeError], "Stateful session establishment and cleanup both failed.");
+                }
+            }
+            throw markStatefulSessionEstablishmentFailure(establishmentError);
+        }
+    }
+    async validatePooledOwnership(owner, sessionKey, signal, validateOwnership) {
+        try {
+            const validatedOwner = validateOwnership ? await validateOwnership(owner, signal) : owner;
+            this.refreshEventOwnerFence(validatedOwner, sessionKey);
+            return validatedOwner;
+        }
+        catch (error) {
+            await this.#pool
+                .invalidate(owner.sessionKey, "ownership-validation-failed")
+                .catch(() => undefined);
+            throw markStatefulSessionEstablishmentFailure(error);
+        }
+    }
+    refreshEventOwnerFence(owner, sessionKey) {
+        this.#eventOwnerFences.set(sessionIdentityKey(owner.sessionKey, owner.generation), {
+            sessionKey,
+            generation: owner.generation,
+            ownerPodId: owner.ownerPodId,
+            ownerEndpoint: owner.ownerEndpoint,
+        });
+    }
+    async closeManagedSession(session, reason) {
+        const ctx = makeStatefulProviderCloseContext(this.#adapter.providerId, session);
+        const errors = [];
+        const disposerKey = sessionIdentityKey(session.sessionKey, session.generation);
+        const disposer = this.#eventDisposers.get(disposerKey);
+        this.#eventDisposers.delete(disposerKey);
+        this.#eventOwnerFences.delete(disposerKey);
+        if (disposer) {
+            try {
+                await disposer();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (this.#adapter.snapshot && this.#checkpointStore) {
+            try {
+                const state = await this.#adapter.snapshot(ctx, session.value);
+                if (state !== undefined)
+                    await this.#checkpointStore(ctx, state);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        try {
+            await this.#adapter.close(ctx, session.value, reason);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, "Stateful session cleanup failed in multiple hooks.");
+        }
+    }
+    observeDuration(request, owner, startedAt) {
+        observeStatefulSessionOperationDuration({
+            metricEmitter: this.#metricEmitter,
+            request,
+            owner,
+            durationMs: this.#clock().getTime() - startedAt,
+        });
+    }
+    async runLimited(sessionKey, maxInFlight, run) {
+        const limiter = this.#parallelLimiters.get(sessionKey) ?? { active: 0, waiting: [] };
+        this.#parallelLimiters.set(sessionKey, limiter);
+        if (limiter.active >= maxInFlight) {
+            await new Promise((resolve) => limiter.waiting.push(resolve));
+        }
+        limiter.active += 1;
+        try {
+            return await run();
+        }
+        finally {
+            limiter.active -= 1;
+            limiter.waiting.shift()?.();
+            if (limiter.active === 0 && limiter.waiting.length === 0) {
+                this.#parallelLimiters.delete(sessionKey);
+            }
+        }
+    }
+    schedule(sessionKey, run) {
+        const concurrency = this.#adapter.policy.concurrency;
+        if (concurrency.mode === "serialize")
+            return this.#pool.runExclusive(sessionKey, run);
+        if (concurrency.maxInFlight === undefined)
+            return run();
+        return this.runLimited(sessionKey, concurrency.maxInFlight, run);
+    }
+}
+function validateAdapterConfiguration(options) {
+    const adapter = options.adapter;
+    if (!adapter.policy?.concurrency || !adapter.policy.reconnect) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" requires concurrency and reconnect policies.`);
+    }
+    const concurrency = adapter.policy.concurrency;
+    if (concurrency.mode !== "serialize" && concurrency.mode !== "parallel") {
+        throw new Error('Stateful concurrency policy mode must be "serialize" or "parallel".');
+    }
+    if (concurrency.mode === "serialize" && "maxInFlight" in concurrency) {
+        throw new Error("Stateful serialize concurrency must not declare maxInFlight.");
+    }
+    if (concurrency.mode === "parallel" &&
+        concurrency.maxInFlight !== undefined &&
+        (!Number.isInteger(concurrency.maxInFlight) || concurrency.maxInFlight <= 0)) {
+        throw new Error("Stateful parallel concurrency maxInFlight must be a positive integer.");
+    }
+    if (!["resume", "recreate", "unsupported"].includes(adapter.policy.reconnect)) {
+        throw new Error('Stateful reconnect policy must be "resume", "recreate", or "unsupported".');
+    }
+    if (Boolean(adapter.snapshot) !== Boolean(options.checkpointStore)) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" snapshot and session-manager checkpointStore must be configured together.`);
+    }
+    if (Boolean(adapter.subscribe) !== Boolean(options.eventPublisher)) {
+        throw new Error(`Stateful provider adapter "${adapter.providerId}" subscribe and session-manager eventPublisher must be configured together.`);
+    }
+}
+function managedSessionIdentity(owner, request) {
+    return {
+        connectionId: request.connectionId,
+        serviceAccountId: request.serviceAccountId,
+        ownerPodId: owner.ownerPodId,
+        ownerEndpoint: owner.ownerEndpoint,
+        ownerStatus: owner.status,
+    };
+}
+function sessionIdentityKey(sessionKey, generation) {
+    return `${sessionKey}\u001f${generation}`;
+}

package/dist/stateful/stateful-provider-observability.d.ts

@@ -0,0 +1,62 @@
+export declare const STATEFUL_PROVIDER_METRIC_NAMES: readonly ["apifuse_stateful_provider_session_owner_acquire_total", "apifuse_stateful_provider_session_owner_renew_total", "apifuse_stateful_provider_session_owner_release_total", "apifuse_stateful_provider_session_owner_conflict_total", "apifuse_stateful_provider_session_owner_fencing_stale_total", "apifuse_stateful_provider_active_sessions", "apifuse_stateful_provider_lru_evictions_total", "apifuse_stateful_provider_session_invalidations_total", "apifuse_stateful_provider_session_operation_queue_depth", "apifuse_stateful_provider_session_operation_queue_wait_ms", "apifuse_stateful_provider_session_operation_duration_ms", "apifuse_stateful_provider_routing_forward_total", "apifuse_stateful_provider_routing_local_total", "apifuse_stateful_provider_routing_reacquire_total", "apifuse_stateful_provider_routing_deadline_expired_total", "apifuse_stateful_provider_event_append_total", "apifuse_stateful_provider_event_dedupe_total", "apifuse_stateful_provider_event_drop_total", "apifuse_stateful_provider_event_lag_ms", "apifuse_stateful_provider_webhook_enqueue_total", "apifuse_stateful_provider_webhook_fanout_recovered_total", "apifuse_stateful_provider_webhook_delivered_total", "apifuse_stateful_provider_webhook_retry_total", "apifuse_stateful_provider_webhook_dead_letter_total", "apifuse_stateful_provider_webhook_canceled_total", "apifuse_stateful_provider_webhook_replay_total", "apifuse_stateful_provider_webhook_latency_ms", "apifuse_stateful_provider_write_ledger_ambiguous_total", "apifuse_stateful_provider_write_ledger_reconciled_total", "apifuse_stateful_provider_write_ledger_failed_total"];
+export type StatefulProviderMetricName = (typeof STATEFUL_PROVIDER_METRIC_NAMES)[number];
+export declare const STATEFUL_PROVIDER_LOG_FIELDS: readonly ["requestId", "eventId", "deliveryId", "providerId", "connectionId", "serviceAccountId", "operationId", "sessionKeyHash", "ownerPodId", "generation", "leaseExpiresAt", "capacityClass", "queueDepth", "eventType", "subjectKind", "subjectId", "retryCount", "ledgerState", "healthStatus", "redactedErrorCode"];
+export type StatefulProviderLogField = (typeof STATEFUL_PROVIDER_LOG_FIELDS)[number];
+export declare const STATEFUL_PROVIDER_AUTOSCALING_SIGNALS: readonly ["active_sessions", "session_queue_depth", "session_queue_wait_ms", "reconnect_rate", "provider_event_lag_ms", "webhook_outbox_depth", "webhook_due_retry_depth", "memory_pressure", "file_descriptor_pressure", "socket_pressure"];
+export type StatefulProviderAutoscalingSignal = (typeof STATEFUL_PROVIDER_AUTOSCALING_SIGNALS)[number];
+export declare const STATEFUL_PROVIDER_HEALTH_DIMENSIONS: readonly ["registry_connectivity", "owner_lease_freshness", "pool_capacity", "upstream_auth_validity", "push_loop_lag", "event_append_lag", "webhook_backlog"];
+export type StatefulProviderHealthDimension = (typeof STATEFUL_PROVIDER_HEALTH_DIMENSIONS)[number];
+export declare const STATEFUL_PROVIDER_ROLLOUT_STATES: readonly ["disabled", "tenant_allowlist", "connection_allowlist", "shadow", "canary", "production", "rollback"];
+export type StatefulProviderRolloutState = (typeof STATEFUL_PROVIDER_ROLLOUT_STATES)[number];
+export interface StatefulProviderMetricLabelInput {
+    readonly requestId?: string;
+    readonly eventId?: string;
+    readonly deliveryId?: string;
+    readonly providerId?: string;
+    readonly connectionId?: string;
+    readonly serviceAccountId?: string;
+    readonly operationId?: string;
+    readonly sessionKey?: string;
+    readonly sessionKeyHash?: string;
+    readonly ownerPodId?: string;
+    readonly generation?: number | string;
+    readonly leaseExpiresAt?: string;
+    readonly capacityClass?: string;
+    readonly queueDepth?: number | string;
+    readonly eventType?: string;
+    readonly subjectKind?: string;
+    readonly subjectId?: string;
+    readonly retryCount?: number | string;
+    readonly ledgerState?: string;
+    readonly healthStatus?: string;
+    readonly redactedErrorCode?: string;
+}
+export type StatefulProviderMetricLabels = Partial<Record<StatefulProviderLogField, string>>;
+export interface StatefulProviderMetricEmitter {
+    increment(name: StatefulProviderMetricName, labels?: StatefulProviderMetricLabelInput, value?: number): void;
+    gauge(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+    observe(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+}
+export type StatefulProviderRecordedMetric = {
+    readonly kind: "increment" | "gauge" | "observe";
+    readonly name: StatefulProviderMetricName;
+    readonly labels: StatefulProviderMetricLabels;
+    readonly value: number;
+};
+export declare const NOOP_STATEFUL_PROVIDER_METRIC_EMITTER: {
+    increment(): void;
+    gauge(): void;
+    observe(): void;
+};
+export declare class RecordingStatefulProviderMetricEmitter implements StatefulProviderMetricEmitter {
+    readonly metrics: StatefulProviderRecordedMetric[];
+    increment(name: StatefulProviderMetricName, labels?: StatefulProviderMetricLabelInput, value?: number): void;
+    gauge(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+    observe(name: StatefulProviderMetricName, labels: StatefulProviderMetricLabelInput, value: number): void;
+}
+export declare function isStatefulProviderMetricName(value: unknown): value is StatefulProviderMetricName;
+export declare function isStatefulProviderLogField(value: unknown): value is StatefulProviderLogField;
+export declare function isStatefulProviderAutoscalingSignal(value: unknown): value is StatefulProviderAutoscalingSignal;
+export declare function sanitizeSessionKeyForLog(sessionKey: string): string;
+export declare function statefulProviderMetricLabels(input: StatefulProviderMetricLabelInput): StatefulProviderMetricLabels;
+export declare function assertNoRawSessionKeyInLabels(labels: Record<string, string | number | boolean | null | undefined>, rawSessionKey: string): void;

package/dist/stateful/stateful-provider-observability.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+export const STATEFUL_PROVIDER_METRIC_NAMES = [
+    "apifuse_stateful_provider_session_owner_acquire_total",
+    "apifuse_stateful_provider_session_owner_renew_total",
+    "apifuse_stateful_provider_session_owner_release_total",
+    "apifuse_stateful_provider_session_owner_conflict_total",
+    "apifuse_stateful_provider_session_owner_fencing_stale_total",
+    "apifuse_stateful_provider_active_sessions",
+    "apifuse_stateful_provider_lru_evictions_total",
+    "apifuse_stateful_provider_session_invalidations_total",
+    "apifuse_stateful_provider_session_operation_queue_depth",
+    "apifuse_stateful_provider_session_operation_queue_wait_ms",
+    "apifuse_stateful_provider_session_operation_duration_ms",
+    "apifuse_stateful_provider_routing_forward_total",
+    "apifuse_stateful_provider_routing_local_total",
+    "apifuse_stateful_provider_routing_reacquire_total",
+    "apifuse_stateful_provider_routing_deadline_expired_total",
+    "apifuse_stateful_provider_event_append_total",
+    "apifuse_stateful_provider_event_dedupe_total",
+    "apifuse_stateful_provider_event_drop_total",
+    "apifuse_stateful_provider_event_lag_ms",
+    "apifuse_stateful_provider_webhook_enqueue_total",
+    "apifuse_stateful_provider_webhook_fanout_recovered_total",
+    "apifuse_stateful_provider_webhook_delivered_total",
+    "apifuse_stateful_provider_webhook_retry_total",
+    "apifuse_stateful_provider_webhook_dead_letter_total",
+    "apifuse_stateful_provider_webhook_canceled_total",
+    "apifuse_stateful_provider_webhook_replay_total",
+    "apifuse_stateful_provider_webhook_latency_ms",
+    "apifuse_stateful_provider_write_ledger_ambiguous_total",
+    "apifuse_stateful_provider_write_ledger_reconciled_total",
+    "apifuse_stateful_provider_write_ledger_failed_total",
+];
+export const STATEFUL_PROVIDER_LOG_FIELDS = [
+    "requestId",
+    "eventId",
+    "deliveryId",
+    "providerId",
+    "connectionId",
+    "serviceAccountId",
+    "operationId",
+    "sessionKeyHash",
+    "ownerPodId",
+    "generation",
+    "leaseExpiresAt",
+    "capacityClass",
+    "queueDepth",
+    "eventType",
+    "subjectKind",
+    "subjectId",
+    "retryCount",
+    "ledgerState",
+    "healthStatus",
+    "redactedErrorCode",
+];
+export const STATEFUL_PROVIDER_AUTOSCALING_SIGNALS = [
+    "active_sessions",
+    "session_queue_depth",
+    "session_queue_wait_ms",
+    "reconnect_rate",
+    "provider_event_lag_ms",
+    "webhook_outbox_depth",
+    "webhook_due_retry_depth",
+    "memory_pressure",
+    "file_descriptor_pressure",
+    "socket_pressure",
+];
+export const STATEFUL_PROVIDER_HEALTH_DIMENSIONS = [
+    "registry_connectivity",
+    "owner_lease_freshness",
+    "pool_capacity",
+    "upstream_auth_validity",
+    "push_loop_lag",
+    "event_append_lag",
+    "webhook_backlog",
+];
+export const STATEFUL_PROVIDER_ROLLOUT_STATES = [
+    "disabled",
+    "tenant_allowlist",
+    "connection_allowlist",
+    "shadow",
+    "canary",
+    "production",
+    "rollback",
+];
+const METRIC_NAME_SET = new Set(STATEFUL_PROVIDER_METRIC_NAMES);
+const LOG_FIELD_SET = new Set(STATEFUL_PROVIDER_LOG_FIELDS);
+const AUTOSCALING_SIGNAL_SET = new Set(STATEFUL_PROVIDER_AUTOSCALING_SIGNALS);
+export const NOOP_STATEFUL_PROVIDER_METRIC_EMITTER = {
+    increment() { },
+    gauge() { },
+    observe() { },
+};
+export class RecordingStatefulProviderMetricEmitter {
+    metrics = [];
+    increment(name, labels = {}, value = 1) {
+        this.metrics.push({
+            kind: "increment",
+            name,
+            labels: statefulProviderMetricLabels(labels),
+            value,
+        });
+    }
+    gauge(name, labels, value) {
+        this.metrics.push({
+            kind: "gauge",
+            name,
+            labels: statefulProviderMetricLabels(labels),
+            value,
+        });
+    }
+    observe(name, labels, value) {
+        this.metrics.push({
+            kind: "observe",
+            name,
+            labels: statefulProviderMetricLabels(labels),
+            value,
+        });
+    }
+}
+export function isStatefulProviderMetricName(value) {
+    return typeof value === "string" && METRIC_NAME_SET.has(value);
+}
+export function isStatefulProviderLogField(value) {
+    return typeof value === "string" && LOG_FIELD_SET.has(value);
+}
+export function isStatefulProviderAutoscalingSignal(value) {
+    return typeof value === "string" && AUTOSCALING_SIGNAL_SET.has(value);
+}
+export function sanitizeSessionKeyForLog(sessionKey) {
+    return `session_sha256:${createHash("sha256").update(sessionKey).digest("hex")}`;
+}
+export function statefulProviderMetricLabels(input) {
+    const labels = {};
+    for (const field of STATEFUL_PROVIDER_LOG_FIELDS) {
+        if (field === "sessionKeyHash")
+            continue;
+        const value = input[field];
+        if (value !== undefined) {
+            labels[field] = String(value);
+        }
+    }
+    const sessionKeyHash = input.sessionKeyHash ??
+        (input.sessionKey ? sanitizeSessionKeyForLog(input.sessionKey) : undefined);
+    if (sessionKeyHash) {
+        labels.sessionKeyHash = sessionKeyHash;
+    }
+    if (input.sessionKey) {
+        assertNoRawSessionKeyInLabels(labels, input.sessionKey);
+    }
+    return labels;
+}
+export function assertNoRawSessionKeyInLabels(labels, rawSessionKey) {
+    if (!rawSessionKey)
+        return;
+    for (const [key, value] of Object.entries(labels)) {
+        if (String(value ?? "").includes(rawSessionKey)) {
+            throw new Error(`Stateful provider metric label "${key}" contains a raw session key.`);
+        }
+    }
+}

package/dist/stateful/stateful-provider-owner-forwarder.d.ts

@@ -0,0 +1,41 @@
+import type { ProviderServerStatefulForwardEnvelope } from "../server/serve.js";
+import type { StatefulOperationRequest, StatefulOperationResult, StatefulOwnerForwarder } from "./stateful-provider-session-routing.js";
+import type { SessionOwnerRecord, SessionOwnerRegistry } from "./stateful-provider-session-runtime.js";
+export declare const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
+export declare const STATEFUL_FORWARDING_SIGNATURE_HEADER = "x-apifuse-stateful-signature";
+export declare const STATEFUL_FORWARDING_TIMESTAMP_HEADER = "x-apifuse-stateful-timestamp";
+export declare const STATEFUL_FORWARDING_NONCE_HEADER = "x-apifuse-stateful-nonce";
+export declare const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
+export interface StatefulOwnerForwarderOptions {
+    readonly currentPodId: string;
+    readonly secret: string;
+    readonly fetch?: FetchTransport;
+    readonly clock?: () => Date;
+}
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** Builds the standard fail-closed owner-currentness check for serve(). */
+export declare function createStatefulOwnerFenceValidator(registry: SessionOwnerRegistry): (fence: Pick<ProviderServerStatefulForwardEnvelope, "sessionKey" | "ownerPodId" | "generation">, signal: AbortSignal) => Promise<boolean>;
+export declare class StatefulOwnerForwardingError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    constructor(input: {
+        readonly code: string;
+        readonly message: string;
+        readonly status?: number;
+        readonly cause?: unknown;
+    });
+}
+export declare class HttpStatefulOwnerForwarder implements StatefulOwnerForwarder {
+    #private;
+    constructor(options: StatefulOwnerForwarderOptions);
+    forward(owner: SessionOwnerRecord, request: StatefulOperationRequest, signal: AbortSignal): Promise<StatefulOperationResult>;
+}
+export declare function signStatefulForwardingBody(input: {
+    readonly secret: string;
+    readonly timestamp: string;
+    readonly rawBody: string;
+    readonly method: string;
+    readonly path: string;
+    readonly nonce: string;
+}): string;
+export {};