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

package/dist/stateful/http-session-owner-registry.js

@@ -0,0 +1,210 @@
+import { z } from "zod";
+import { statefulSignedHeaders } from "../stateful-signing.js";
+import { StatefulControlPlaneError } from "./errors.js";
+import { parseSessionKey } from "./session-key.js";
+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 {
+    ambiguous = true;
+    constructor(input) {
+        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) => {
+    try {
+        parseSessionKey(value);
+        return value;
+    }
+    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 class HttpSessionOwnerRegistry {
+    #baseUrl;
+    #secret;
+    #scope;
+    #fetch;
+    #clock;
+    #requestTimeoutMs;
+    constructor(options) {
+        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, now, signal) {
+        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, signal) {
+        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, signal) {
+        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, signal) {
+        const response = await this.#post("release", {
+            ...this.#scope,
+            ...input,
+        }, signal);
+        return this.#parse(response, "release", ReleaseResponseSchema);
+    }
+    async #post(operation, body, callerSignal) {
+        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(response, operation, schema) {
+        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;
+        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, status, cause) {
+    return new StatefulControlPlaneError({
+        code: "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
+        message: `Stateful control-plane ${operation} returned an invalid response.`,
+        operation,
+        status,
+        cause,
+    });
+}
+function isTimestamp(value) {
+    return Number.isFinite(Date.parse(value));
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Stateful control-plane ${name} must be a positive integer.`);
+    }
+    return value;
+}

package/dist/stateful/index.d.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/dist/stateful/index.js

@@ -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/dist/stateful/provider-event-delivery-failures.d.ts

@@ -0,0 +1,32 @@
+export type ProviderWebhookFailureTotals = {
+    retryingCount: number;
+    failedCount: number;
+    deadLetteredCount: number;
+};
+export declare function failureForStatus(statusCode: number): {
+    readonly statusCode: number;
+    readonly error?: string;
+};
+export declare function failureForError(error: unknown): {
+    readonly statusCode?: number;
+    readonly error: string;
+};
+export declare function countProviderWebhookFailure(totals: ProviderWebhookFailureTotals, status: string): void;
+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 declare const NOOP_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER: {
+    record(): void;
+};
+export declare class RecordingProviderEventDeliveryFailureRecorder implements ProviderEventDeliveryFailureRecorder {
+    readonly failures: ProviderEventDeliveryFailure[];
+    record(failure: ProviderEventDeliveryFailure): void;
+}

package/dist/stateful/provider-event-delivery-failures.js

@@ -0,0 +1,43 @@
+export function failureForStatus(statusCode) {
+    if (statusCode >= 300 && statusCode < 400) {
+        return { statusCode, error: "Webhook redirects are not followed." };
+    }
+    return { statusCode };
+}
+export function failureForError(error) {
+    if (isPublicValidationError(error)) {
+        return { statusCode: 400, error: error.message };
+    }
+    return { error: publicWorkerError(error) };
+}
+export function countProviderWebhookFailure(totals, status) {
+    if (status === "retrying") {
+        totals.retryingCount += 1;
+        return;
+    }
+    if (status === "dead_lettered") {
+        totals.deadLetteredCount += 1;
+        return;
+    }
+    totals.failedCount += 1;
+}
+export const NOOP_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER = {
+    record() { },
+};
+export class RecordingProviderEventDeliveryFailureRecorder {
+    failures = [];
+    record(failure) {
+        this.failures.push(failure);
+    }
+}
+function publicWorkerError(error) {
+    if (isPublicValidationError(error))
+        return error.message;
+    if (error instanceof Error && error.message) {
+        return "Webhook delivery request failed.";
+    }
+    return "Webhook delivery failed.";
+}
+function isPublicValidationError(error) {
+    return error instanceof Error && error.name.endsWith("ValidationError");
+}

package/dist/stateful/provider-event-pipeline-metrics.d.ts

@@ -0,0 +1,46 @@
+import type { ProviderEvent } from "./provider-events.js";
+export declare const PROVIDER_EVENT_METRIC_NAMES: readonly ["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"];
+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 declare const NOOP_PROVIDER_EVENT_METRIC_EMITTER: {
+    increment(): void;
+    observe(): void;
+};
+export declare function providerEventMetricLabels(event: ProviderEvent): {
+    eventId: string;
+    providerId: string;
+    connectionId: string | undefined;
+    serviceAccountId: string | undefined;
+    eventType: string;
+    subjectKind: string | undefined;
+    subjectId: string | undefined;
+    sessionKey: string;
+    generation: number;
+};
+export declare function providerWebhookDeliveryMetricLabels(delivery: {
+    readonly deliveryId: string;
+}): {
+    deliveryId: string;
+};
+export declare function emitProviderWebhookDeliveryFailureMetric(metricEmitter: ProviderEventMetricEmitter, delivery: {
+    readonly deliveryId: string;
+}, status: string): void;
+export declare function providerWebhookDeliveryLatencyMs(delivery: {
+    readonly lastAttemptAt?: string;
+    readonly nextAttemptAt: string;
+}, now: string): number;

package/dist/stateful/provider-event-pipeline-metrics.js

@@ -0,0 +1,48 @@
+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",
+];
+export const NOOP_PROVIDER_EVENT_METRIC_EMITTER = {
+    increment() { },
+    observe() { },
+};
+export function providerEventMetricLabels(event) {
+    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) {
+    return { deliveryId: delivery.deliveryId };
+}
+export function emitProviderWebhookDeliveryFailureMetric(metricEmitter, delivery, status) {
+    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, now) {
+    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/dist/stateful/provider-event-pipeline.d.ts

@@ -0,0 +1,50 @@
+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>;
+}

package/dist/stateful/provider-event-pipeline.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,101 @@
+export type ProviderEventSubject = {
+    /** Provider-defined resource category, for example `message`, `mailbox`, or `browser-context`. */
+    kind: string;
+    id: string;
+};
+export type ProviderEventSession = {
+    /** Canonical logical session identity shared by every stateful provider. */
+    sessionKey: string;
+    /** Ownership generation shared by every stateful provider for stale-event fencing. */
+    generation: number;
+};
+export interface ProviderEvent<TPayload = Record<string, unknown>> {
+    /** Universal stable identity used for transport retries and deduplication. */
+    eventId: string;
+    /** Universal provider namespace needed to route and interpret the event. */
+    providerId: string;
+    /** Optional because mailbox/browser protocols may not expose an API connection identity. */
+    connectionId?: string;
+    /** Optional because not every provider session maps to a platform service account. */
+    serviceAccountId?: string;
+    /** Universal provider-defined event classification. */
+    eventType: string;
+    /** Optional for protocol-level events without a single resource subject. */
+    subject?: ProviderEventSubject;
+    /** Optional when the upstream protocol does not provide an occurrence timestamp. */
+    occurredAt?: string;
+    /** Universal SDK observation time used for ordering and lag measurement. */
+    observedAt: string;
+    /** Universal JSON data envelope; protocols without data use an empty object. */
+    payload: TPayload;
+    /** Universal stateful ownership fence for rejecting events from stale sessions. */
+    session: ProviderEventSession;
+    providerCursor?: string;
+    dedupeKey?: string;
+    rawRef?: string;
+}
+export type ProviderEventIdFactory = () => string;
+export type ProviderEventClock = () => Date;
+export type BuildProviderEventInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<ProviderEvent<TPayload>, "eventId" | "observedAt"> & {
+    eventId?: string;
+    observedAt?: string;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    /** Provider-specific credential key patterns added to the conservative SDK defaults. */
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventListOptions = {
+    providerId?: string;
+    connectionId?: string;
+    eventType?: string;
+    subjectKind?: string;
+    subjectId?: string;
+    afterObservedAt?: string;
+    limit?: number;
+};
+export type ProviderEventAppendResult = {
+    event: ProviderEvent;
+    appended: boolean;
+};
+export interface ProviderEventLog {
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export type ProviderEventEmitterDefaults = {
+    providerId: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session: ProviderEventSession;
+    clock?: ProviderEventClock;
+    idFactory?: ProviderEventIdFactory;
+    maxPayloadBytes?: number;
+    shouldRedactPayload?: boolean;
+    redactionPatterns?: readonly RegExp[];
+};
+export type ProviderEventEmitterInput<TPayload extends Record<string, unknown> = Record<string, unknown>> = Omit<BuildProviderEventInput<TPayload>, "providerId" | "connectionId" | "serviceAccountId" | "session"> & {
+    providerId?: string;
+    connectionId?: string;
+    serviceAccountId?: string;
+    session?: ProviderEventSession;
+};
+export declare class ProviderEventValidationError extends Error {
+    constructor(message: string);
+}
+export declare function buildProviderEvent<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: BuildProviderEventInput<TPayload>): ProviderEvent<TPayload>;
+export declare function redactProviderEventPayload<TPayload>(payload: TPayload, extraPatterns?: readonly RegExp[]): TPayload;
+export declare function isStaleProviderEvent(event: ProviderEvent, currentGeneration: number): boolean;
+export declare class InMemoryProviderEventLog implements ProviderEventLog {
+    #private;
+    append(event: ProviderEvent): Promise<ProviderEventAppendResult>;
+    get(eventId: string): Promise<ProviderEvent | null>;
+    list(options?: ProviderEventListOptions): Promise<ProviderEvent[]>;
+}
+export declare class ProviderEventEmitter {
+    #private;
+    constructor(log: ProviderEventLog, defaults: ProviderEventEmitterDefaults);
+    emit<TPayload extends Record<string, unknown> = Record<string, unknown>>(input: ProviderEventEmitterInput<TPayload>): Promise<ProviderEventAppendResult>;
+}
+export declare function randomProviderEventId(): string;