@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/dist/server/types.d.ts

@@ -1,17 +1,19 @@
 import { z } from "zod";
 export declare const ConnectionModeSchema: z.ZodEnum<{
-    credentials: "credentials";
     none: "none";
+    credentials: "credentials";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
+    oauth2_proxied: "oauth2_proxied";
 }>;
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
     mode: z.ZodEnum<{
-        credentials: "credentials";
         none: "none";
+        credentials: "credentials";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
+        oauth2_proxied: "oauth2_proxied";
     }>;
     secrets: z.ZodRecord<z.ZodString, z.ZodString>;
     scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -25,10 +27,11 @@ export declare const OperationRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -42,6 +45,13 @@ export declare const ErrorEnvelopeSchema: z.ZodObject<{
     code: z.ZodString;
     message: z.ZodString;
     requestId: z.ZodOptional<z.ZodString>;
+    retryable: z.ZodBoolean;
+    source: z.ZodOptional<z.ZodEnum<{
+        client: "client";
+        upstream_rule: "upstream_rule";
+        upstream_failure: "upstream_failure";
+        apifuse: "apifuse";
+    }>>;
     fix: z.ZodOptional<z.ZodString>;
     details: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
@@ -55,21 +65,21 @@ export declare const OperationSuccessResponseSchema: z.ZodObject<{
             stale: z.ZodBoolean;
             keys: z.ZodArray<z.ZodString>;
             source: z.ZodOptional<z.ZodEnum<{
-                loader: "loader";
-                memory: "memory";
                 mixed: "mixed";
                 redis: "redis";
+                memory: "memory";
+                loader: "loader";
             }>>;
         }, z.core.$strip>>;
         retry: z.ZodOptional<z.ZodObject<{
             attempts: z.ZodNumber;
             retries: z.ZodNumber;
             preset: z.ZodOptional<z.ZodEnum<{
-                aggressive_read: "aggressive_read";
                 off: "off";
-                rate_limit_aware: "rate_limit_aware";
-                safe_read: "safe_read";
                 transport_transient: "transport_transient";
+                safe_read: "safe_read";
+                aggressive_read: "aggressive_read";
+                rate_limit_aware: "rate_limit_aware";
             }>>;
             transport: z.ZodEnum<{
                 native: "native";
@@ -84,6 +94,13 @@ export declare const OperationErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
@@ -101,10 +118,11 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            credentials: "credentials";
             none: "none";
+            credentials: "credentials";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
+            oauth2_proxied: "oauth2_proxied";
         }>;
         secrets: z.ZodRecord<z.ZodString, z.ZodString>;
         scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -121,6 +139,13 @@ export declare const AuthFlowErrorResponseSchema: z.ZodObject<{
         code: z.ZodString;
         message: z.ZodString;
         requestId: z.ZodOptional<z.ZodString>;
+        retryable: z.ZodBoolean;
+        source: z.ZodOptional<z.ZodEnum<{
+            client: "client";
+            upstream_rule: "upstream_rule";
+            upstream_failure: "upstream_failure";
+            apifuse: "apifuse";
+        }>>;
         fix: z.ZodOptional<z.ZodString>;
         details: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;

package/dist/server/types.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
-import { HttpRetryPreset } from "../types";
+import { PROVIDER_ERROR_SOURCES } from "../observability.js";
+import { HttpRetryPreset } from "../types.js";
 export const ConnectionModeSchema = z.enum([
     "oauth2",
+    "oauth2_proxied",
     "credentials",
     "platform-managed",
     "none",
@@ -26,6 +28,11 @@ export const ErrorEnvelopeSchema = z.object({
     code: z.string(),
     message: z.string(),
     requestId: z.string().optional(),
+    retryable: z.boolean(),
+    // Who stopped the request (honest-provider-error-contract); optional so
+    // older peers (stateful forwarding owners) remain parseable. Derived from
+    // the PROVIDER_ERROR_SOURCES registry so the enum cannot drift.
+    source: z.enum(PROVIDER_ERROR_SOURCES).optional(),
     fix: z.string().optional(),
     details: z.unknown().optional(),
 });

package/dist/stateful/errors.d.ts

@@ -0,0 +1,19 @@
+export type StatefulControlPlaneOperation = "resolve" | "acquire" | "renew" | "release";
+export declare class StatefulRoutingDeadlineError extends Error {
+    readonly requestId: string;
+    readonly deadlineAt: string;
+    constructor(requestId: string, deadlineAt: string);
+}
+export declare class StatefulControlPlaneError extends Error {
+    readonly code: string;
+    readonly operation: StatefulControlPlaneOperation;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(input: {
+        readonly code: string;
+        readonly message: string;
+        readonly operation: StatefulControlPlaneOperation;
+        readonly status?: number;
+        readonly cause?: unknown;
+    });
+}

package/dist/stateful/errors.js

@@ -0,0 +1,24 @@
+export class StatefulRoutingDeadlineError extends Error {
+    requestId;
+    deadlineAt;
+    constructor(requestId, deadlineAt) {
+        super(`Stateful operation request ${requestId} deadline has expired.`);
+        this.name = "StatefulRoutingDeadlineError";
+        this.requestId = requestId;
+        this.deadlineAt = deadlineAt;
+    }
+}
+export class StatefulControlPlaneError extends Error {
+    code;
+    operation;
+    status;
+    cause;
+    constructor(input) {
+        super(input.message);
+        this.name = "StatefulControlPlaneError";
+        this.code = input.code;
+        this.operation = input.operation;
+        this.status = input.status;
+        this.cause = input.cause;
+    }
+}

package/dist/stateful/http-provider-event-emitter.d.ts

@@ -0,0 +1,40 @@
+import type { ProviderEventDeliveryFailureRecorder } from "./provider-event-delivery-failures.js";
+import type { ProviderEventPublisher, ProviderEventPublishOptions, PublishAck } from "./provider-event-pipeline.js";
+import { type ProviderEventMetricEmitter } from "./provider-event-pipeline-metrics.js";
+import type { ProviderEvent } from "./provider-events.js";
+type FetchTransport = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export type HttpProviderEventEmitterOptions = {
+    readonly baseUrl: string;
+    readonly secret: string;
+    readonly fetch?: FetchTransport;
+    readonly clock?: () => Date;
+    readonly random?: () => number;
+    readonly metricEmitter?: ProviderEventMetricEmitter;
+    readonly failureRecorder?: ProviderEventDeliveryFailureRecorder;
+    readonly maxBufferedEvents?: number;
+    readonly retryBaseMs?: number;
+    readonly retryMaxMs?: number;
+    readonly maxAttempts?: number;
+    readonly jitterRatio?: number;
+};
+export type ProviderEventFlushReport = {
+    /** Events delivered during this emitter's lifetime. */
+    readonly delivered: number;
+    /** Events permanently dropped during this emitter's lifetime. */
+    readonly failed: number;
+    /** Events still buffered when flush returned. */
+    readonly pending: number;
+};
+/**
+ * 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 declare class HttpProviderEventEmitter implements ProviderEventPublisher {
+    #private;
+    constructor(options: HttpProviderEventEmitterOptions);
+    publish(event: ProviderEvent, options: ProviderEventPublishOptions): PublishAck;
+    pendingCount(): number;
+    flush(timeoutMs?: number): Promise<ProviderEventFlushReport>;
+}
+export {};

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 {};