@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/stateful/session-key.ts

@@ -0,0 +1,111 @@
+declare const SESSION_KEY_BRAND: unique symbol;
+
+/** Canonical, opaque identity for a stateful provider session. */
+export type SessionKey = string & { readonly [SESSION_KEY_BRAND]: "SessionKey" };
+
+export interface SessionKeyParts {
+	readonly providerId: string;
+	readonly serviceAccountId: string;
+	readonly connectionId: string;
+	/** Optional extra session axes (e.g. device, mailbox, persona). Defaults to none. */
+	readonly dimensions?: Readonly<Record<string, string>>;
+}
+
+const PREFIX = "stateful:v1";
+const REQUIRED_DIMENSIONS = ["providerId", "serviceAccountId", "connectionId"] as const;
+const REQUIRED_DIMENSION_SET = new Set<string>(REQUIRED_DIMENSIONS);
+
+export function buildSessionKey(parts: SessionKeyParts): SessionKey {
+	validateRequiredPart(parts.providerId, "providerId");
+	validateRequiredPart(parts.serviceAccountId, "serviceAccountId");
+	validateRequiredPart(parts.connectionId, "connectionId");
+
+	const dimensions = Object.entries(parts.dimensions ?? {}).sort(([left], [right]) =>
+		left < right ? -1 : left > right ? 1 : 0,
+	);
+	for (const [name, value] of dimensions) {
+		validateDimension(name, value);
+	}
+
+	const segments: Array<readonly [string, string]> = [
+		["providerId", parts.providerId],
+		["serviceAccountId", parts.serviceAccountId],
+		["connectionId", parts.connectionId],
+		...dimensions,
+	];
+	return `${PREFIX}/${segments
+		.map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`)
+		.join("/")}` as SessionKey;
+}
+
+export function parseSessionKey(key: string): SessionKeyParts {
+	const prefix = `${PREFIX}/`;
+	if (!key.startsWith(prefix)) {
+		throw new Error(`Invalid session key: expected canonical prefix "${PREFIX}".`);
+	}
+
+	const parsed = new Map<string, string>();
+	for (const segment of key.slice(prefix.length).split("/")) {
+		const separator = segment.indexOf("=");
+		if (separator <= 0) {
+			throw new Error(`Invalid session key segment "${segment}"; expected name=value.`);
+		}
+		const name = decodeSegment(segment.slice(0, separator), "dimension name");
+		const value = decodeSegment(segment.slice(separator + 1), `dimension "${name}"`);
+		if (parsed.has(name)) {
+			throw new Error(`Invalid session key: duplicate dimension "${name}".`);
+		}
+		if (name.trim().length === 0) {
+			throw new Error("Invalid session key: dimension name must not be empty.");
+		}
+		if (value.trim().length === 0) {
+			throw new Error(`Invalid session key: dimension "${name}" must not be empty.`);
+		}
+		parsed.set(name, value);
+	}
+
+	for (const required of REQUIRED_DIMENSIONS) {
+		if (!parsed.has(required)) {
+			throw new Error(`Invalid session key: missing required dimension "${required}".`);
+		}
+	}
+
+	const dimensions: Record<string, string> = {};
+	for (const [name, value] of parsed) {
+		if (!REQUIRED_DIMENSION_SET.has(name)) dimensions[name] = value;
+	}
+	return {
+		providerId: parsed.get("providerId") as string,
+		serviceAccountId: parsed.get("serviceAccountId") as string,
+		connectionId: parsed.get("connectionId") as string,
+		dimensions,
+	};
+}
+
+function validateRequiredPart(value: string, name: string): void {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error(`Cannot build session key: required dimension "${name}" is missing or empty.`);
+	}
+}
+
+function validateDimension(name: string, value: string): void {
+	if (name.trim().length === 0) {
+		throw new Error("Cannot build session key: extra dimension name must not be empty.");
+	}
+	if (REQUIRED_DIMENSION_SET.has(name)) {
+		throw new Error(
+			`Cannot build session key: extra dimension "${name}" duplicates a required dimension.`,
+		);
+	}
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new Error(`Cannot build session key: extra dimension "${name}" is missing or empty.`);
+	}
+}
+
+function decodeSegment(value: string, label: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		throw new Error(`Invalid session key: ${label} is not valid URI encoding.`);
+	}
+}

package/src/stateful/stateful-provider-adapter-context.ts

@@ -0,0 +1,59 @@
+import type { StatefulProviderSessionContext } from "./stateful-provider-adapter.js";
+import type { StatefulOperationRequest } from "./stateful-provider-session-routing.js";
+import type { ManagedSession, SessionOwnerRecord } from "./stateful-provider-session-runtime.js";
+
+export function makeStatefulProviderSessionContext(
+	providerId: string,
+	owner: SessionOwnerRecord,
+	request: StatefulOperationRequest,
+	signal: AbortSignal,
+): StatefulProviderSessionContext {
+	const ctx: StatefulProviderSessionContext = {
+		sessionKey: owner.sessionKey,
+		providerId,
+		connectionId: request.connectionId,
+		serviceAccountId: request.serviceAccountId,
+		ownerPodId: owner.ownerPodId,
+		ownerEndpoint: owner.ownerEndpoint,
+		ownerStatus: owner.status,
+		generation: owner.generation,
+		signal,
+		requestId: request.requestId,
+		operationId: request.operationId,
+		...(request.runtimeContext !== undefined ? { runtimeContext: request.runtimeContext } : {}),
+	};
+	return withOptionalRequestMetadata(ctx, request);
+}
+
+export function makeStatefulProviderCloseContext<TSession>(
+	providerId: string,
+	session: ManagedSession<TSession>,
+): StatefulProviderSessionContext {
+	const identity = session.identity;
+	return {
+		sessionKey: session.sessionKey,
+		providerId,
+		...(identity
+			? {
+					connectionId: identity.connectionId,
+					serviceAccountId: identity.serviceAccountId,
+					ownerPodId: identity.ownerPodId,
+					ownerEndpoint: identity.ownerEndpoint,
+					ownerStatus: identity.ownerStatus,
+				}
+			: {}),
+		generation: session.generation,
+		signal: new AbortController().signal,
+	};
+}
+
+function withOptionalRequestMetadata(
+	ctx: StatefulProviderSessionContext,
+	request: StatefulOperationRequest,
+): StatefulProviderSessionContext {
+	return {
+		...ctx,
+		...(request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {}),
+		...(request.deadlineAt ? { deadlineAt: request.deadlineAt } : {}),
+	};
+}

package/src/stateful/stateful-provider-adapter-metrics.ts

@@ -0,0 +1,48 @@
+import type { StatefulProviderMetricEmitter } from "./stateful-provider-observability.js";
+import type { StatefulOperationRequest } from "./stateful-provider-session-routing.js";
+import type { SessionOwnerRecord } from "./stateful-provider-session-runtime.js";
+
+export function observeStatefulSessionOperationDuration(input: {
+	readonly metricEmitter: StatefulProviderMetricEmitter;
+	readonly request: StatefulOperationRequest;
+	readonly owner: SessionOwnerRecord;
+	readonly durationMs: number;
+}): void {
+	input.metricEmitter.observe(
+		"apifuse_stateful_provider_session_operation_duration_ms",
+		statefulSessionMetricLabels(input.request, input.owner),
+		Math.max(0, input.durationMs),
+	);
+}
+
+export function emitStatefulSessionInvalidatedMetric(input: {
+	readonly metricEmitter: StatefulProviderMetricEmitter;
+	readonly request: StatefulOperationRequest;
+	readonly owner: SessionOwnerRecord;
+	readonly reason: string;
+}): void {
+	input.metricEmitter.increment(
+		"apifuse_stateful_provider_session_invalidations_total",
+		statefulSessionMetricLabels(input.request, input.owner, {
+			redactedErrorCode: input.reason,
+		}),
+	);
+}
+
+function statefulSessionMetricLabels(
+	request: StatefulOperationRequest,
+	owner: SessionOwnerRecord,
+	extra: { readonly redactedErrorCode?: string } = {},
+) {
+	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,
+		...extra,
+	};
+}