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

package/dist/stateful/stateful-provider-owner-forwarder.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { OperationErrorResponseSchema, OperationSuccessResponseSchema, } from "../server/index.js";
+import { signStatefulRequestBody, statefulSignedHeaders } from "../stateful-signing.js";
+import { forwardingContextFromStatefulRuntimeContext } from "./stateful-provider-session-routing.js";
+export const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
+export const STATEFUL_FORWARDING_SIGNATURE_HEADER = "x-apifuse-stateful-signature";
+export const STATEFUL_FORWARDING_TIMESTAMP_HEADER = "x-apifuse-stateful-timestamp";
+export const STATEFUL_FORWARDING_NONCE_HEADER = "x-apifuse-stateful-nonce";
+export const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
+const MAX_FORWARDED_HEADERS = 32;
+const MAX_FORWARDED_HEADER_BYTES = 8 * 1024;
+// Inbound compatibility boundary for rolling deploys: older owner pods omit
+// top-level retryable. Emitted responses remain strict via
+// OperationErrorResponseSchema.
+const ForwardedOperationErrorResponseSchema = OperationErrorResponseSchema.extend({
+    error: OperationErrorResponseSchema.shape.error.extend({
+        retryable: z.boolean().optional().default(false),
+    }),
+});
+const SENSITIVE_HEADER_NAMES = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    STATEFUL_FORWARDING_SIGNATURE_HEADER,
+    STATEFUL_FORWARDING_TIMESTAMP_HEADER,
+    STATEFUL_FORWARDING_NONCE_HEADER,
+    STATEFUL_FORWARDING_SOURCE_POD_HEADER,
+]);
+/** Builds the standard fail-closed owner-currentness check for serve(). */
+export function createStatefulOwnerFenceValidator(registry) {
+    return async (fence, signal) => {
+        const current = await registry.resolve(fence.sessionKey, undefined, signal);
+        return (current !== null &&
+            current.sessionKey === fence.sessionKey &&
+            current.ownerPodId === fence.ownerPodId &&
+            current.generation === fence.generation);
+    };
+}
+export class StatefulOwnerForwardingError extends Error {
+    code;
+    status;
+    constructor(input) {
+        super(input.message, input.cause === undefined ? undefined : { cause: input.cause });
+        this.name = "StatefulOwnerForwardingError";
+        this.code = input.code;
+        this.status = input.status;
+    }
+}
+export class HttpStatefulOwnerForwarder {
+    #currentPodId;
+    #secret;
+    #fetch;
+    #clock;
+    constructor(options) {
+        if (options.secret.trim().length === 0) {
+            throw new Error("Stateful owner forwarding secret is required.");
+        }
+        this.#currentPodId = options.currentPodId;
+        this.#secret = options.secret;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#clock = options.clock ?? (() => new Date());
+    }
+    async forward(owner, request, signal) {
+        assertNoRequestScopedFiles(request.input);
+        const forwardedAt = this.#clock().toISOString();
+        const envelope = buildForwardingEnvelope({
+            owner,
+            request,
+            sourcePodId: this.#currentPodId,
+            forwardedAt,
+        });
+        const rawBody = JSON.stringify(envelope);
+        let response;
+        try {
+            const target = new URL(`${owner.ownerEndpoint.replace(/\/+$/, "")}${STATEFUL_INTERNAL_OPERATIONS_ROUTE}`);
+            response = await this.#fetch(target, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...statefulSignedHeaders({
+                        secret: this.#secret,
+                        timestamp: forwardedAt,
+                        rawBody,
+                        method: "POST",
+                        path: STATEFUL_INTERNAL_OPERATIONS_ROUTE,
+                    }),
+                    [STATEFUL_FORWARDING_SOURCE_POD_HEADER]: this.#currentPodId,
+                },
+                body: rawBody,
+                signal,
+            });
+        }
+        catch (cause) {
+            throw new StatefulOwnerForwardingError({
+                code: "STATEFUL_FORWARDING_REQUEST_FAILED",
+                message: "Stateful owner forwarding request failed before a response was received.",
+                cause,
+            });
+        }
+        return parseForwardedResponse(response);
+    }
+}
+export function signStatefulForwardingBody(input) {
+    return signStatefulRequestBody(input);
+}
+function assertNoRequestScopedFiles(input) {
+    if (!containsRequestScopedFile(input))
+        return;
+    throw new StatefulOwnerForwardingError({
+        code: "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
+        message: "Request-scoped files cannot be forwarded to a remote stateful owner. Use staged upload once available so the forwarding envelope carries only durable file_ref values, or route the request to the owner-local provider process.",
+    });
+}
+function containsRequestScopedFile(value) {
+    if (isRequestScopedFileRef(value))
+        return true;
+    if (Array.isArray(value))
+        return value.some((item) => containsRequestScopedFile(item));
+    if (!value || typeof value !== "object")
+        return false;
+    return Object.values(value).some((item) => containsRequestScopedFile(item));
+}
+function isRequestScopedFileRef(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = Object.fromEntries(Object.entries(value));
+    return record.type === "request_file" && typeof record.id === "string";
+}
+function buildForwardingEnvelope(input) {
+    const metadata = forwardedMetadata(input.request);
+    return {
+        requestId: input.request.requestId,
+        providerId: input.request.providerId,
+        operationId: input.request.operationId,
+        sessionKey: input.request.sessionKey,
+        connectionId: input.request.connectionId,
+        serviceAccountId: input.request.serviceAccountId,
+        ...(input.request.idempotencyKey ? { idempotencyKey: input.request.idempotencyKey } : {}),
+        ...(input.request.deadlineAt !== undefined ? { deadlineAt: input.request.deadlineAt } : {}),
+        sourcePodId: input.sourcePodId,
+        forwardedAt: input.forwardedAt,
+        ownerPodId: input.owner.ownerPodId,
+        generation: input.owner.generation,
+        operationRequest: {
+            requestId: input.request.requestId,
+            input: input.request.input,
+            connection: metadata.connection,
+            headers: sanitizeForwardedHeaders(metadata.headers),
+            ...(metadata.trace ? { trace: metadata.trace } : {}),
+        },
+    };
+}
+function forwardedMetadata(request) {
+    const forwardingContext = forwardingContextFromStatefulRuntimeContext(request.runtimeContext);
+    if (!forwardingContext) {
+        throw new StatefulOwnerForwardingError({
+            code: "STATEFUL_FORWARDING_CONTEXT_MISSING",
+            message: "Stateful operation forwarding requires request context metadata.",
+        });
+    }
+    const operationRequest = forwardingContext.operationRequest;
+    const connection = OperationConnectionSchema.parse(operationRequest?.connection);
+    return {
+        connection,
+        ...(operationRequest?.headers ? { headers: operationRequest.headers } : {}),
+        ...(operationRequest?.trace ? { trace: operationRequest.trace } : {}),
+    };
+}
+function sanitizeForwardedHeaders(headers) {
+    if (!headers)
+        return {};
+    const forwarded = {};
+    let totalBytes = 0;
+    for (const [name, value] of Object.entries(headers)) {
+        const normalized = name.toLowerCase();
+        if (SENSITIVE_HEADER_NAMES.has(normalized))
+            continue;
+        const nextBytes = Buffer.byteLength(name) + Buffer.byteLength(value);
+        if (Object.keys(forwarded).length >= MAX_FORWARDED_HEADERS ||
+            totalBytes + nextBytes > MAX_FORWARDED_HEADER_BYTES) {
+            break;
+        }
+        forwarded[name] = value;
+        totalBytes += nextBytes;
+    }
+    return forwarded;
+}
+async function parseForwardedResponse(response) {
+    const body = await response.json().catch(() => undefined);
+    const success = OperationSuccessResponseSchema.safeParse(body);
+    if (response.ok && success.success) {
+        return { output: success.data.data };
+    }
+    const error = ForwardedOperationErrorResponseSchema.safeParse(body);
+    if (error.success) {
+        throw new StatefulOwnerForwardingError({
+            code: error.data.error.code,
+            message: error.data.error.message,
+            status: response.status,
+        });
+    }
+    throw new StatefulOwnerForwardingError({
+        code: "STATEFUL_FORWARDING_BAD_RESPONSE",
+        message: `Stateful owner returned an invalid response with status ${response.status}.`,
+        status: response.status,
+    });
+}
+const OperationConnectionSchema = z.object({
+    id: z.string(),
+    mode: z.enum(["oauth2", "credentials", "platform-managed", "none"]),
+    secrets: z.record(z.string(), z.string()),
+    scopes: z.array(z.string()).optional(),
+    metadata: z.record(z.string(), z.unknown()),
+    externalRef: z.string(),
+});

package/dist/stateful/stateful-provider-runtime-context.d.ts

@@ -0,0 +1,32 @@
+export interface StatefulLocalRuntimeContext {
+    readonly providerContext?: unknown;
+}
+export interface StatefulForwardingRuntimeContext {
+    readonly operationRequest?: {
+        readonly requestId: string;
+        readonly connection?: unknown;
+        readonly headers?: Record<string, string>;
+        readonly trace?: Record<string, string>;
+    };
+}
+export interface StatefulOperationRuntimeContext {
+    readonly local?: StatefulLocalRuntimeContext;
+    readonly forwarding?: StatefulForwardingRuntimeContext;
+}
+/**
+ * Attaches provider-process-only context for local execution. This value must
+ * never be serialized into owner-forwarding envelopes.
+ */
+export declare function withStatefulLocalProviderContext(providerContext: unknown, forwarding?: StatefulForwardingRuntimeContext): StatefulOperationRuntimeContext;
+/**
+ * Copies only operation metadata that is safe to serialize across owner pods.
+ */
+export declare function statefulForwardingContextFromProviderRequest(request: {
+    readonly requestId: string;
+    readonly connection?: unknown;
+    readonly headers?: Record<string, string>;
+    readonly trace?: Record<string, string>;
+}): StatefulForwardingRuntimeContext;
+export declare function isStatefulOperationRuntimeContext(value: unknown): value is StatefulOperationRuntimeContext;
+export declare function providerContextFromStatefulRuntimeContext(value: unknown): unknown;
+export declare function forwardingContextFromStatefulRuntimeContext(value: unknown): StatefulForwardingRuntimeContext | undefined;

package/dist/stateful/stateful-provider-runtime-context.js

@@ -0,0 +1,60 @@
+/**
+ * Attaches provider-process-only context for local execution. This value must
+ * never be serialized into owner-forwarding envelopes.
+ */
+export function withStatefulLocalProviderContext(providerContext, forwarding) {
+    return {
+        local: { providerContext },
+        ...(forwarding ? { forwarding } : {}),
+    };
+}
+/**
+ * Copies only operation metadata that is safe to serialize across owner pods.
+ */
+export function statefulForwardingContextFromProviderRequest(request) {
+    return {
+        operationRequest: {
+            requestId: request.requestId,
+            ...(request.connection !== undefined ? { connection: request.connection } : {}),
+            ...(request.headers ? { headers: request.headers } : {}),
+            ...(request.trace ? { trace: request.trace } : {}),
+        },
+    };
+}
+export function isStatefulOperationRuntimeContext(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return ("local" in value ||
+        "forwarding" in value ||
+        "operationRequest" in value ||
+        "providerContext" in value);
+}
+export function providerContextFromStatefulRuntimeContext(value) {
+    if (!isStatefulOperationRuntimeContext(value))
+        return undefined;
+    if ("local" in value)
+        return value.local?.providerContext;
+    // Backward-compatible read for pre-split runtimeContext objects. New code
+    // should always use `withStatefulLocalProviderContext` instead.
+    if ("providerContext" in value)
+        return value.providerContext;
+    return undefined;
+}
+export function forwardingContextFromStatefulRuntimeContext(value) {
+    if (!isStatefulOperationRuntimeContext(value))
+        return undefined;
+    if ("forwarding" in value)
+        return value.forwarding;
+    if ("operationRequest" in value) {
+        const operationRequest = value.operationRequest;
+        if (isForwardingOperationRequest(operationRequest)) {
+            return { operationRequest };
+        }
+    }
+    return undefined;
+}
+function isForwardingOperationRequest(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    return "requestId" in value && typeof value.requestId === "string";
+}

package/dist/stateful/stateful-provider-runtime-executor.d.ts

@@ -0,0 +1,34 @@
+import type { SessionKey } from "./session-key.js";
+import type { StatefulProviderMetricEmitter } from "./stateful-provider-observability.js";
+import { type StatefulOperationExecutor, type StatefulOperationRequest, type StatefulOperationResult, type StatefulOwnerForwarder, type StatefulOwnerPod } from "./stateful-provider-session-routing.js";
+import type { SessionOwnerRegistry } from "./stateful-provider-session-runtime.js";
+export interface StatefulProviderInvocationMetadata<TInput = unknown> {
+    readonly requestId: string;
+    readonly sessionKey: SessionKey;
+    readonly providerId: string;
+    readonly operationId: string;
+    readonly connectionId: string;
+    readonly serviceAccountId: string;
+    readonly input: TInput;
+    readonly idempotencyKey?: string;
+    readonly deadlineAt?: string;
+    readonly runtimeContext?: unknown;
+}
+export interface StatefulProviderRuntimeExecutorOptions {
+    readonly currentPod: StatefulOwnerPod;
+    readonly registry: SessionOwnerRegistry;
+    readonly forwarder: StatefulOwnerForwarder;
+    readonly executor: StatefulOperationExecutor;
+    readonly leaseDurationMs: number;
+    readonly leaseRenewalFraction?: number;
+    readonly clock?: () => Date;
+    readonly metricEmitter?: StatefulProviderMetricEmitter;
+}
+export declare class StatefulProviderRuntimeExecutor {
+    #private;
+    constructor(options: StatefulProviderRuntimeExecutorOptions);
+    invoke(request: StatefulOperationRequest): Promise<StatefulOperationResult>;
+    release(): Promise<void>;
+    releaseSession(sessionKey: SessionKey): Promise<boolean>;
+}
+export declare function buildStatefulOperationRequest<TInput>(metadata: StatefulProviderInvocationMetadata<TInput>): StatefulOperationRequest<TInput>;

package/dist/stateful/stateful-provider-runtime-executor.js

@@ -0,0 +1,52 @@
+import { StatefulSessionRouter, } from "./stateful-provider-session-routing.js";
+export class StatefulProviderRuntimeExecutor {
+    #router;
+    constructor(options) {
+        this.#router = new StatefulSessionRouter({
+            currentPod: options.currentPod,
+            registry: options.registry,
+            forwarder: options.forwarder,
+            executor: options.executor,
+            leaseDurationMs: options.leaseDurationMs,
+            ...(options.leaseRenewalFraction !== undefined
+                ? { leaseRenewalFraction: options.leaseRenewalFraction }
+                : {}),
+            ...(options.clock ? { clock: options.clock } : {}),
+            ...(options.metricEmitter ? { metricEmitter: options.metricEmitter } : {}),
+        });
+    }
+    invoke(request) {
+        return this.#router.route(request);
+    }
+    release() {
+        return this.#router.release();
+    }
+    releaseSession(sessionKey) {
+        return this.#router.releaseSession(sessionKey);
+    }
+}
+export function buildStatefulOperationRequest(metadata) {
+    requireNonEmpty(metadata.requestId, "requestId");
+    requireNonEmpty(metadata.sessionKey, "sessionKey");
+    requireNonEmpty(metadata.providerId, "providerId");
+    requireNonEmpty(metadata.operationId, "operationId");
+    requireNonEmpty(metadata.connectionId, "connectionId");
+    requireNonEmpty(metadata.serviceAccountId, "serviceAccountId");
+    return {
+        requestId: metadata.requestId,
+        sessionKey: metadata.sessionKey,
+        providerId: metadata.providerId,
+        operationId: metadata.operationId,
+        connectionId: metadata.connectionId,
+        serviceAccountId: metadata.serviceAccountId,
+        input: metadata.input,
+        ...(metadata.idempotencyKey ? { idempotencyKey: metadata.idempotencyKey } : {}),
+        ...(metadata.deadlineAt ? { deadlineAt: metadata.deadlineAt } : {}),
+        ...(metadata.runtimeContext !== undefined ? { runtimeContext: metadata.runtimeContext } : {}),
+    };
+}
+function requireNonEmpty(value, field) {
+    if (value.trim().length === 0) {
+        throw new Error(`Stateful provider invocation ${field} is required.`);
+    }
+}

package/dist/stateful/stateful-provider-session-routing.d.ts

@@ -0,0 +1,67 @@
+import type { SessionKey } from "./session-key.js";
+import { type StatefulProviderMetricEmitter } from "./stateful-provider-observability.js";
+import type { SessionOwnerRecord, SessionOwnerRegistry, SessionOwnerStatus } from "./stateful-provider-session-runtime.js";
+export { forwardingContextFromStatefulRuntimeContext, isStatefulOperationRuntimeContext, providerContextFromStatefulRuntimeContext, type StatefulForwardingRuntimeContext, type StatefulLocalRuntimeContext, type StatefulOperationRuntimeContext, statefulForwardingContextFromProviderRequest, withStatefulLocalProviderContext, } from "./stateful-provider-runtime-context.js";
+export interface StatefulOperationRequest<TInput = unknown> {
+    readonly requestId: string;
+    readonly sessionKey: SessionKey;
+    readonly providerId: string;
+    readonly operationId: string;
+    readonly connectionId: string;
+    readonly serviceAccountId: string;
+    readonly input: TInput;
+    readonly idempotencyKey?: string;
+    readonly deadlineAt?: string;
+    readonly runtimeContext?: unknown;
+}
+export interface StatefulOperationResult<TOutput = unknown> {
+    readonly output: TOutput;
+}
+export interface StatefulOwnerPod {
+    readonly podId: string;
+    readonly endpoint: string;
+}
+export interface StatefulOperationExecutor<_TSession = unknown> {
+    executeLocal(request: StatefulOperationRequest, owner: SessionOwnerRecord, signal: AbortSignal, validateOwnership?: StatefulOwnershipValidator): Promise<StatefulOperationResult>;
+}
+export type StatefulOwnershipValidator = (owner: SessionOwnerRecord, signal: AbortSignal) => Promise<SessionOwnerRecord>;
+export interface StatefulOwnerForwarder {
+    forward(owner: SessionOwnerRecord, request: StatefulOperationRequest, signal: AbortSignal): Promise<StatefulOperationResult>;
+}
+export interface StatefulSessionRouterOptions {
+    readonly currentPod: StatefulOwnerPod;
+    readonly registry: SessionOwnerRegistry;
+    readonly forwarder: StatefulOwnerForwarder;
+    readonly executor: StatefulOperationExecutor;
+    readonly leaseDurationMs: number;
+    readonly leaseRenewalFraction?: number;
+    /** @deprecated Acquired sessions always begin in the acquiring state. */
+    readonly ownerStatus?: Exclude<SessionOwnerStatus, "expired">;
+    readonly clock?: () => Date;
+    readonly metricEmitter?: StatefulProviderMetricEmitter;
+}
+export { StatefulRoutingDeadlineError } from "./errors.js";
+export declare class StatefulRoutingOwnershipError extends Error {
+    readonly requestId: string;
+    readonly sessionKey: SessionKey;
+    constructor(requestId: string, sessionKey: SessionKey, message: string);
+}
+export declare class StatefulSessionRouter {
+    #private;
+    constructor(options: StatefulSessionRouterOptions);
+    route<TInput = unknown>(request: StatefulOperationRequest<TInput>): Promise<StatefulOperationResult>;
+    release(): Promise<void>;
+    releaseSession(sessionKey: SessionKey): Promise<boolean>;
+    /** @internal Test-only visibility into local-attempt lifecycle cleanup. */
+    get latestLocalAttemptCountForTesting(): number;
+    private prepareRouteToOwner;
+    private routeToOwner;
+    private ensureManagedLease;
+    private scheduleRenewal;
+    private renewManagedLease;
+    private validateLocalOwnership;
+    private forgetManagedLease;
+    private releaseFailedEstablishment;
+    private runEstablishmentTask;
+    private stopManagedLease;
+}