@apifuse/provider-sdk 2.2.0-beta.10 → 2.2.0-beta.11

package/dist/stateful/http-provider-event-emitter.js

@@ -0,0 +1,237 @@
+import { statefulSignedHeaders } from "../stateful-signing.js";
+import { NOOP_PROVIDER_EVENT_METRIC_EMITTER, providerEventMetricLabels, } from "./provider-event-pipeline-metrics.js";
+const DEFAULT_MAX_BUFFERED_EVENTS = 1_000;
+const DEFAULT_RETRY_BASE_MS = 500;
+const DEFAULT_RETRY_MAX_MS = 30_000;
+const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_JITTER_RATIO = 0.2;
+const CONSOLE_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER = {
+    record(failure) {
+        console.error(JSON.stringify({
+            event: "provider_event_delivery_failed",
+            eventId: failure.eventId,
+            reason: failure.reason,
+            attempts: failure.attempts,
+        }));
+    },
+};
+/**
+ * Provider-pod HTTP publication with a bounded best-effort delivery guarantee and at-least-once
+ * transport retries. This is not durable at-least-once delivery: buffered events can be lost if
+ * the process is killed. Graceful shutdown should drain the in-memory buffer with flush().
+ */
+export class HttpProviderEventEmitter {
+    #baseUrl;
+    #secret;
+    #fetch;
+    #clock;
+    #random;
+    #metricEmitter;
+    #failureRecorder;
+    #maxBufferedEvents;
+    #retryBaseMs;
+    #retryMaxMs;
+    #maxAttempts;
+    #jitterRatio;
+    #queue = [];
+    #drainPromise;
+    #deliveredCount = 0;
+    #failedCount = 0;
+    constructor(options) {
+        if (options.baseUrl.trim().length === 0) {
+            throw new Error("Provider event ingest baseUrl is required.");
+        }
+        if (options.secret.trim().length === 0) {
+            throw new Error("Provider event ingest secret is required.");
+        }
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#secret = options.secret;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#clock = options.clock ?? (() => new Date());
+        this.#random = options.random ?? Math.random;
+        this.#metricEmitter = options.metricEmitter ?? NOOP_PROVIDER_EVENT_METRIC_EMITTER;
+        this.#failureRecorder =
+            options.failureRecorder ?? CONSOLE_PROVIDER_EVENT_DELIVERY_FAILURE_RECORDER;
+        this.#maxBufferedEvents = positiveInteger(options.maxBufferedEvents ?? DEFAULT_MAX_BUFFERED_EVENTS, "maxBufferedEvents");
+        this.#retryBaseMs = nonnegativeFinite(options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS, "retryBaseMs");
+        this.#retryMaxMs = nonnegativeFinite(options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS, "retryMaxMs");
+        this.#maxAttempts = positiveInteger(options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS, "maxAttempts");
+        this.#jitterRatio = boundedRatio(options.jitterRatio ?? DEFAULT_JITTER_RATIO, "jitterRatio");
+        if (this.#retryMaxMs < this.#retryBaseMs) {
+            throw new Error("Provider event retryMaxMs must be greater than or equal to retryBaseMs.");
+        }
+    }
+    publish(event, options) {
+        const accepted = this.#enqueue(event, options);
+        return { accepted, queued: this.#queue.length };
+    }
+    pendingCount() {
+        return this.#queue.length;
+    }
+    async flush(timeoutMs = 30_000) {
+        nonnegativeFinite(timeoutMs, "flush timeout");
+        this.#ensureDrain();
+        if (this.#queue.length === 0 || timeoutMs === 0)
+            return this.#flushReport();
+        let timeout;
+        const timedOut = new Promise((resolve) => {
+            timeout = setTimeout(resolve, timeoutMs);
+        });
+        await Promise.race([this.#drainPromise ?? Promise.resolve(), timedOut]);
+        if (timeout)
+            clearTimeout(timeout);
+        return this.#flushReport();
+    }
+    #flushReport() {
+        return {
+            delivered: this.#deliveredCount,
+            failed: this.#failedCount,
+            pending: this.#queue.length,
+        };
+    }
+    #enqueue(event, options) {
+        let rawBody;
+        try {
+            rawBody = JSON.stringify({
+                ...event,
+                ownerFence: options.ownerFence,
+            });
+        }
+        catch (error) {
+            this.#recordFailure(event, "attempts_exhausted", 0, error);
+            return false;
+        }
+        if (this.#queue.length >= this.#maxBufferedEvents) {
+            const oldest = this.#queue.shift();
+            if (oldest) {
+                oldest.dropped = true;
+                oldest.abortController?.abort();
+                this.#recordFailure(oldest.event, "buffer_overflow", oldest.attempts);
+            }
+        }
+        this.#queue.push({
+            event,
+            rawBody,
+            idempotencyKey: options.idempotencyKey ?? event.eventId,
+            attempts: 0,
+            dropped: false,
+        });
+        this.#ensureDrain();
+        return true;
+    }
+    #ensureDrain() {
+        if (this.#drainPromise || this.#queue.length === 0)
+            return;
+        this.#drainPromise = Promise.resolve()
+            .then(() => this.#drain())
+            .finally(() => {
+            this.#drainPromise = undefined;
+            if (this.#queue.length > 0)
+                this.#ensureDrain();
+        });
+    }
+    async #drain() {
+        while (this.#queue.length > 0) {
+            const current = this.#queue[0];
+            if (!current)
+                return;
+            current.attempts += 1;
+            const delivered = await this.#send(current);
+            if (current.dropped)
+                continue;
+            if (delivered) {
+                if (this.#queue[0] === current)
+                    this.#queue.shift();
+                this.#deliveredCount += 1;
+                continue;
+            }
+            if (current.attempts >= this.#maxAttempts) {
+                if (this.#queue[0] === current)
+                    this.#queue.shift();
+                this.#recordFailure(current.event, "attempts_exhausted", current.attempts);
+                continue;
+            }
+            await delay(this.#retryDelay(current.attempts));
+        }
+    }
+    async #send(buffered) {
+        const timestamp = this.#clock().toISOString();
+        const path = "/v1/stateful/events";
+        const abortController = new AbortController();
+        buffered.abortController = abortController;
+        try {
+            const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-apifuse-event-id": buffered.idempotencyKey,
+                    ...statefulSignedHeaders({
+                        secret: this.#secret,
+                        timestamp,
+                        rawBody: buffered.rawBody,
+                        method: "POST",
+                        path,
+                    }),
+                },
+                body: buffered.rawBody,
+                signal: abortController.signal,
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (buffered.abortController === abortController) {
+                buffered.abortController = undefined;
+            }
+        }
+    }
+    #retryDelay(attempts) {
+        const exponential = Math.min(this.#retryMaxMs, this.#retryBaseMs * 2 ** Math.max(0, attempts - 1));
+        const jitter = 1 + (this.#random() * 2 - 1) * this.#jitterRatio;
+        return Math.max(0, Math.round(exponential * jitter));
+    }
+    #recordFailure(event, reason, attempts, error) {
+        this.#failedCount += 1;
+        this.#incrementDropMetric(event);
+        try {
+            const recorded = this.#failureRecorder.record({
+                eventId: event.eventId,
+                reason,
+                attempts,
+                failedAt: this.#clock().toISOString(),
+                ...(error ? { error: "Provider event could not be serialized." } : {}),
+            });
+            void Promise.resolve(recorded).catch(() => { });
+        }
+        catch { }
+    }
+    #incrementDropMetric(event, emitter = this.#metricEmitter) {
+        try {
+            emitter.increment("apifuse_stateful_provider_event_drop_total", providerEventMetricLabels(event));
+        }
+        catch { }
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`Provider event ${name} must be a positive integer.`);
+    }
+    return value;
+}
+function nonnegativeFinite(value, name) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`Provider event ${name} must be a non-negative finite number.`);
+    }
+    return value;
+}
+function boundedRatio(value, name) {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`Provider event ${name} must be between 0 and 1.`);
+    }
+    return value;
+}

package/dist/stateful/http-session-owner-registry.d.ts

@@ -0,0 +1,44 @@
+import { StatefulControlPlaneError, type StatefulControlPlaneOperation } from "./errors.js";
+import { 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;
+};
+/**
+ * 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 declare class AmbiguousRegistryOperationError extends StatefulControlPlaneError {
+    readonly ambiguous = true;
+    constructor(input: {
+        readonly operation: Exclude<StatefulControlPlaneOperation, "resolve">;
+        readonly message: string;
+        readonly cause: unknown;
+    });
+}
+export type HttpSessionOwnerRecord = Omit<SessionOwnerRecord, "sessionKey"> & {
+    readonly sessionKey: SessionKey;
+};
+export type HttpAcquireSessionOwnerResult = Omit<AcquireSessionOwnerResult, "record"> & {
+    readonly record: HttpSessionOwnerRecord;
+};
+export declare class HttpSessionOwnerRegistry implements SessionOwnerRegistry {
+    #private;
+    constructor(options: HttpSessionOwnerRegistryOptions);
+    resolve(sessionKey: SessionKey, now?: Date, signal?: AbortSignal): Promise<HttpSessionOwnerRecord | null>;
+    acquire(input: AcquireSessionOwnerInput, signal?: AbortSignal): Promise<HttpAcquireSessionOwnerResult>;
+    renew(input: RenewSessionOwnerInput, signal?: AbortSignal): Promise<HttpSessionOwnerRecord | null>;
+    release(input: ReleaseSessionOwnerInput, signal?: AbortSignal): Promise<boolean>;
+}
+export {};

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;