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

package/src/stateful/http-session-owner-registry.ts

@@ -0,0 +1,306 @@
+import { z } from "zod";
+
+import { statefulSignedHeaders } from "../stateful-signing.js";
+import { StatefulControlPlaneError, type StatefulControlPlaneOperation } from "./errors.js";
+import { parseSessionKey, type SessionKey } from "./session-key.js";
+import type {
+	AcquireSessionOwnerInput,
+	AcquireSessionOwnerResult,
+	ReleaseSessionOwnerInput,
+	RenewSessionOwnerInput,
+	SessionOwnerRecord,
+	SessionOwnerRegistry,
+} from "./stateful-provider-session-runtime.js";
+
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type SessionOwnerScope = {
+	readonly serviceAccountId: string;
+	readonly providerId: string;
+	readonly connectionId?: string;
+};
+
+export type HttpSessionOwnerRegistryOptions = {
+	readonly baseUrl: string;
+	readonly secret: string;
+	readonly scope?: SessionOwnerScope;
+	readonly fetch?: FetchTransport;
+	readonly clock?: () => Date;
+	readonly requestTimeoutMs?: number;
+};
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * A mutating registry request failed after it may have reached the control plane. Callers must
+ * resolve the session owner and reconcile instead of blindly retrying the mutation.
+ */
+export class AmbiguousRegistryOperationError extends StatefulControlPlaneError {
+	readonly ambiguous = true;
+
+	constructor(input: {
+		readonly operation: Exclude<StatefulControlPlaneOperation, "resolve">;
+		readonly message: string;
+		readonly cause: unknown;
+	}) {
+		super({
+			code: "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
+			message: input.message,
+			operation: input.operation,
+			cause: input.cause,
+		});
+		this.name = "AmbiguousRegistryOperationError";
+	}
+}
+
+const SessionKeySchema = z
+	.string()
+	.min(1)
+	.transform((value, context): SessionKey => {
+		try {
+			parseSessionKey(value);
+			return value as SessionKey;
+		} catch (error) {
+			context.addIssue({
+				code: "custom",
+				message: error instanceof Error ? error.message : "Invalid canonical session key.",
+			});
+			return z.NEVER;
+		}
+	});
+
+const OwnerRecordSchema = z.object({
+	sessionKey: SessionKeySchema,
+	ownerPodId: z.string().min(1),
+	ownerEndpoint: z.string().min(1),
+	generation: z.number().int().positive(),
+	leaseExpiresAt: z.string().refine(isTimestamp),
+	status: z.enum(["acquiring", "connected", "draining", "expired"]),
+	lastUsedAt: z.string().refine(isTimestamp),
+});
+
+const AcquireResultSchema = z.object({
+	record: OwnerRecordSchema,
+	acquired: z.boolean(),
+});
+
+const ResolveResponseSchema = z.union([
+	OwnerRecordSchema,
+	z.object({ record: OwnerRecordSchema }).transform((value) => value.record),
+	z.object({ data: OwnerRecordSchema }).transform((value) => value.data),
+]);
+
+const AcquireResponseSchema = z.union([
+	AcquireResultSchema,
+	z.object({ data: AcquireResultSchema }).transform((value) => value.data),
+]);
+
+const RenewResponseSchema = z.union([
+	OwnerRecordSchema.nullable(),
+	z.object({ record: OwnerRecordSchema.nullable() }).transform((value) => value.record),
+	z.object({ data: OwnerRecordSchema.nullable() }).transform((value) => value.data),
+]);
+
+const ReleaseResponseSchema = z.union([
+	z.boolean(),
+	z.object({ released: z.boolean() }).transform((value) => value.released),
+	z.object({ data: z.boolean() }).transform((value) => value.data),
+]);
+
+export type HttpSessionOwnerRecord = Omit<SessionOwnerRecord, "sessionKey"> & {
+	readonly sessionKey: SessionKey;
+};
+
+export type HttpAcquireSessionOwnerResult = Omit<AcquireSessionOwnerResult, "record"> & {
+	readonly record: HttpSessionOwnerRecord;
+};
+
+export class HttpSessionOwnerRegistry implements SessionOwnerRegistry {
+	readonly #baseUrl: string;
+	readonly #secret: string;
+	readonly #scope?: SessionOwnerScope;
+	readonly #fetch: FetchTransport;
+	readonly #clock: () => Date;
+	readonly #requestTimeoutMs: number;
+
+	constructor(options: HttpSessionOwnerRegistryOptions) {
+		if (options.baseUrl.trim().length === 0) {
+			throw new Error("Stateful control-plane baseUrl is required.");
+		}
+		if (options.secret.trim().length === 0) {
+			throw new Error("Stateful control-plane secret is required.");
+		}
+		this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.#secret = options.secret;
+		this.#scope = options.scope;
+		this.#fetch = options.fetch ?? globalThis.fetch;
+		this.#clock = options.clock ?? (() => new Date());
+		this.#requestTimeoutMs = positiveInteger(
+			options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+			"requestTimeoutMs",
+		);
+	}
+
+	async resolve(
+		sessionKey: SessionKey,
+		now?: Date,
+		signal?: AbortSignal,
+	): Promise<HttpSessionOwnerRecord | null> {
+		const response = await this.#post(
+			"resolve",
+			{
+				...this.#scope,
+				sessionKey,
+				...(now ? { now: now.toISOString() } : {}),
+			},
+			signal,
+		);
+		if (response.status === 404) return null;
+		return this.#parse(response, "resolve", ResolveResponseSchema);
+	}
+
+	async acquire(
+		input: AcquireSessionOwnerInput,
+		signal?: AbortSignal,
+	): Promise<HttpAcquireSessionOwnerResult> {
+		const response = await this.#post(
+			"acquire",
+			{
+				...this.#scope,
+				...input,
+				...(input.now ? { now: input.now.toISOString() } : {}),
+			},
+			signal,
+		);
+		return this.#parse(response, "acquire", AcquireResponseSchema);
+	}
+
+	async renew(
+		input: RenewSessionOwnerInput,
+		signal?: AbortSignal,
+	): Promise<HttpSessionOwnerRecord | null> {
+		const response = await this.#post(
+			"renew",
+			{
+				...this.#scope,
+				...input,
+				...(input.now ? { now: input.now.toISOString() } : {}),
+			},
+			signal,
+		);
+		return this.#parse(response, "renew", RenewResponseSchema);
+	}
+
+	async release(input: ReleaseSessionOwnerInput, signal?: AbortSignal): Promise<boolean> {
+		const response = await this.#post(
+			"release",
+			{
+				...this.#scope,
+				...input,
+			},
+			signal,
+		);
+		return this.#parse(response, "release", ReleaseResponseSchema);
+	}
+
+	async #post(
+		operation: StatefulControlPlaneOperation,
+		body: unknown,
+		callerSignal?: AbortSignal,
+	): Promise<Response> {
+		callerSignal?.throwIfAborted();
+		const rawBody = JSON.stringify(body);
+		const timestamp = this.#clock().toISOString();
+		const path = `/v1/stateful/sessions/owners/${operation}`;
+		const timeoutSignal = AbortSignal.timeout(this.#requestTimeoutMs);
+		const signal = AbortSignal.any(callerSignal ? [callerSignal, timeoutSignal] : [timeoutSignal]);
+		try {
+			return await this.#fetch(`${this.#baseUrl}${path}`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					...statefulSignedHeaders({
+						secret: this.#secret,
+						timestamp,
+						rawBody,
+						method: "POST",
+						path,
+					}),
+				},
+				body: rawBody,
+				signal,
+			});
+		} catch (cause) {
+			const timedOut = timeoutSignal.aborted && !callerSignal?.aborted;
+			if (operation !== "resolve") {
+				throw new AmbiguousRegistryOperationError({
+					operation,
+					message: timedOut
+						? `Stateful control-plane ${operation} timed out after ${this.#requestTimeoutMs}ms; resolve the session owner and reconcile before retrying.`
+						: `Stateful control-plane ${operation} request failed after it may have committed; resolve the session owner and reconcile before retrying.`,
+					cause,
+				});
+			}
+			throw new StatefulControlPlaneError({
+				code: "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
+				message: timedOut
+					? `Stateful control-plane resolve timed out after ${this.#requestTimeoutMs}ms; retry resolve or check control-plane availability.`
+					: "Stateful control-plane resolve request failed.",
+				operation,
+				cause,
+			});
+		}
+	}
+
+	async #parse<T>(
+		response: Response,
+		operation: StatefulControlPlaneOperation,
+		schema: z.ZodType<T>,
+	): Promise<T> {
+		if (!response.ok) {
+			throw new StatefulControlPlaneError({
+				code: "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
+				message: `Stateful control-plane ${operation} returned status ${response.status}.`,
+				operation,
+				status: response.status,
+			});
+		}
+		const rawBody = await response.text();
+		let body: unknown;
+		try {
+			body = JSON.parse(rawBody);
+		} catch (cause) {
+			throw invalidResponse(operation, response.status, cause);
+		}
+		const parsed = schema.safeParse(body);
+		if (!parsed.success) {
+			throw invalidResponse(operation, response.status, parsed.error);
+		}
+		return parsed.data;
+	}
+}
+
+function invalidResponse(
+	operation: StatefulControlPlaneOperation,
+	status: number,
+	cause: unknown,
+): StatefulControlPlaneError {
+	return new StatefulControlPlaneError({
+		code: "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+		message: `Stateful control-plane ${operation} returned an invalid response.`,
+		operation,
+		status,
+		cause,
+	});
+}
+
+function isTimestamp(value: string): boolean {
+	return Number.isFinite(Date.parse(value));
+}
+
+function positiveInteger(value: number, name: string): number {
+	if (!Number.isInteger(value) || value <= 0) {
+		throw new Error(`Stateful control-plane ${name} must be a positive integer.`);
+	}
+	return value;
+}

package/src/stateful/index.ts

@@ -0,0 +1,18 @@
+export * from "../stateful-signing.js";
+export * from "./errors.js";
+export * from "./http-provider-event-emitter.js";
+export * from "./http-session-owner-registry.js";
+export * from "./provider-event-delivery-failures.js";
+export * from "./provider-event-pipeline-metrics.js";
+export * from "./provider-event-pipeline.js";
+export * from "./provider-events.js";
+export * from "./session-key.js";
+export * from "./stateful-provider-adapter-context.js";
+export * from "./stateful-provider-adapter-metrics.js";
+export * from "./stateful-provider-adapter.js";
+export * from "./stateful-provider-observability.js";
+export * from "./stateful-provider-owner-forwarder.js";
+export * from "./stateful-provider-runtime-context.js";
+export * from "./stateful-provider-runtime-executor.js";
+export * from "./stateful-provider-session-routing.js";
+export * from "./stateful-provider-session-runtime.js";

package/src/stateful/provider-event-delivery-failures.ts

@@ -0,0 +1,80 @@
+export type ProviderWebhookFailureTotals = {
+	retryingCount: number;
+	failedCount: number;
+	deadLetteredCount: number;
+};
+
+export function failureForStatus(statusCode: number): {
+	readonly statusCode: number;
+	readonly error?: string;
+} {
+	if (statusCode >= 300 && statusCode < 400) {
+		return { statusCode, error: "Webhook redirects are not followed." };
+	}
+	return { statusCode };
+}
+
+export function failureForError(error: unknown): {
+	readonly statusCode?: number;
+	readonly error: string;
+} {
+	if (isPublicValidationError(error)) {
+		return { statusCode: 400, error: error.message };
+	}
+	return { error: publicWorkerError(error) };
+}
+
+export function countProviderWebhookFailure(
+	totals: ProviderWebhookFailureTotals,
+	status: string,
+): void {
+	if (status === "retrying") {
+		totals.retryingCount += 1;
+		return;
+	}
+	if (status === "dead_lettered") {
+		totals.deadLetteredCount += 1;
+		return;
+	}
+	totals.failedCount += 1;
+}
+
+export type ProviderEventDeliveryFailureReason = "buffer_overflow" | "attempts_exhausted";
+
+export type ProviderEventDeliveryFailure = {
+	readonly eventId: string;
+	readonly reason: ProviderEventDeliveryFailureReason;
+	readonly attempts: number;
+	readonly failedAt: string;
+	readonly error?: string;
+};
+
+export interface ProviderEventDeliveryFailureRecorder {
+	record(failure: ProviderEventDeliveryFailure): void | Promise<void>;
+}
+
+export const NOOP_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER = {
+	record() {},
+} satisfies ProviderEventDeliveryFailureRecorder;
+
+export class RecordingProviderEventDeliveryFailureRecorder
+	implements ProviderEventDeliveryFailureRecorder
+{
+	readonly failures: ProviderEventDeliveryFailure[] = [];
+
+	record(failure: ProviderEventDeliveryFailure): void {
+		this.failures.push(failure);
+	}
+}
+
+function publicWorkerError(error: unknown): string {
+	if (isPublicValidationError(error)) return error.message;
+	if (error instanceof Error && error.message) {
+		return "Webhook delivery request failed.";
+	}
+	return "Webhook delivery failed.";
+}
+
+function isPublicValidationError(error: unknown): error is Error {
+	return error instanceof Error && error.name.endsWith("ValidationError");
+}

package/src/stateful/provider-event-pipeline-metrics.ts

@@ -0,0 +1,95 @@
+import type { ProviderEvent } from "./provider-events.js";
+
+export const PROVIDER_EVENT_METRIC_NAMES = [
+	"apifuse_stateful_provider_event_append_total",
+	"apifuse_stateful_provider_event_dedupe_total",
+	"apifuse_stateful_provider_event_drop_total",
+	"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_latency_ms",
+] as const;
+
+export type ProviderEventMetricName = (typeof PROVIDER_EVENT_METRIC_NAMES)[number];
+
+export type ProviderEventMetricLabelInput = {
+	readonly eventId?: string;
+	readonly deliveryId?: string;
+	readonly providerId?: string;
+	readonly connectionId?: string;
+	readonly serviceAccountId?: string;
+	readonly eventType?: string;
+	readonly subjectKind?: string;
+	readonly subjectId?: string;
+	readonly sessionKey?: string;
+	readonly generation?: number | string;
+};
+
+export interface ProviderEventMetricEmitter {
+	increment(
+		name: ProviderEventMetricName,
+		labels?: ProviderEventMetricLabelInput,
+		value?: number,
+	): void;
+	observe(
+		name: ProviderEventMetricName,
+		labels: ProviderEventMetricLabelInput,
+		value: number,
+	): void;
+}
+
+export const NOOP_PROVIDER_EVENT_METRIC_EMITTER = {
+	increment() {},
+	observe() {},
+} satisfies ProviderEventMetricEmitter;
+
+export function providerEventMetricLabels(event: ProviderEvent) {
+	return {
+		eventId: event.eventId,
+		providerId: event.providerId,
+		connectionId: event.connectionId,
+		serviceAccountId: event.serviceAccountId,
+		eventType: event.eventType,
+		subjectKind: event.subject?.kind,
+		subjectId: event.subject?.id,
+		sessionKey: event.session.sessionKey,
+		generation: event.session.generation,
+	};
+}
+
+export function providerWebhookDeliveryMetricLabels(delivery: { readonly deliveryId: string }) {
+	return { deliveryId: delivery.deliveryId };
+}
+
+export function emitProviderWebhookDeliveryFailureMetric(
+	metricEmitter: ProviderEventMetricEmitter,
+	delivery: { readonly deliveryId: string },
+	status: string,
+): void {
+	if (status === "retrying") {
+		metricEmitter.increment(
+			"apifuse_stateful_provider_webhook_retry_total",
+			providerWebhookDeliveryMetricLabels(delivery),
+		);
+		return;
+	}
+	if (status === "dead_lettered") {
+		metricEmitter.increment(
+			"apifuse_stateful_provider_webhook_dead_letter_total",
+			providerWebhookDeliveryMetricLabels(delivery),
+		);
+	}
+}
+
+export function providerWebhookDeliveryLatencyMs(
+	delivery: { readonly lastAttemptAt?: string; readonly nextAttemptAt: string },
+	now: string,
+): number {
+	const startedAt = Date.parse(delivery.lastAttemptAt ?? delivery.nextAttemptAt);
+	const completedAt = Date.parse(now);
+	if (!Number.isFinite(startedAt) || !Number.isFinite(completedAt)) return 0;
+	return Math.max(0, completedAt - startedAt);
+}

package/src/stateful/provider-event-pipeline.ts

@@ -0,0 +1,61 @@
+import type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+import type { SessionKey } from "./session-key.js";
+
+export type { ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+
+export type ProviderEventOwnerFence = {
+	readonly ownerPodId: string;
+	readonly ownerEndpoint: string;
+	readonly sessionKey: SessionKey;
+	readonly generation: number;
+};
+
+export type ProviderEventPublishOptions = {
+	/** Required ownership proof forwarded to the durable platform write boundary. */
+	readonly ownerFence: ProviderEventOwnerFence;
+	/** Overrides the transport idempotency key; defaults to the event id. */
+	readonly idempotencyKey?: string;
+};
+
+export type PublishAck = {
+	/** Whether this event was accepted into the pod-local retry buffer. */
+	readonly accepted: boolean;
+	/** Number of events currently held in the pod-local retry buffer. */
+	readonly queued: number;
+};
+
+/** Fire-and-forget publication from a provider pod into the platform ingest boundary. */
+export interface ProviderEventPublisher {
+	publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+}
+
+export type AppendProviderEventAndEnqueueWebhooksResult = {
+	readonly appended: boolean;
+	readonly appendedCount: number;
+	readonly matchedSubscriptionCount: number;
+	readonly enqueuedCount: number;
+	readonly recoveredFanoutCount?: number;
+	readonly fenced?: boolean;
+};
+
+export type ProviderEventPipelineAppendOptions = {
+	readonly now?: string;
+	readonly idFactory?: () => string;
+	readonly metricEmitter?: ProviderEventMetricEmitter;
+	readonly beforeAppend?: () => Promise<boolean> | boolean;
+	readonly ownerFence?: ProviderEventOwnerFence;
+};
+
+/**
+ * Durable append-and-fanout contract implemented on the platform side.
+ *
+ * Provider-pod code must depend on ProviderEventPublisher, never ProviderEventPipeline: a pod-local
+ * publisher cannot truthfully report a durable append or downstream webhook fanout.
+ */
+export interface ProviderEventPipeline {
+	appendAndFanout(
+		event: ProviderEvent,
+		options?: ProviderEventPipelineAppendOptions,
+	): Promise<AppendProviderEventAndEnqueueWebhooksResult>;
+}