@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/server/serve-implementation.d.ts

@@ -0,0 +1,285 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { type ProviderEngine, type ProviderEngineMode } from "../engine.js";
+import { type ProviderErrorObservability } from "../errors.js";
+import { type ProviderLocaleCatalogMap } from "../i18n/catalog.js";
+import { type ProviderErrorCategory } from "../observability.js";
+import type { HandleTelemetryEvent } from "../handle.js";
+import { type HttpTelemetryLogPayload } from "../runtime/http-telemetry.js";
+import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
+import { type ResolverTelemetryLogPayload } from "../runtime/resolver-telemetry.js";
+import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ProviderRuntimeTarget, ResolverContext, SttContext } from "../types.js";
+import type { SelfTestCancellationLogEvent } from "./self-test.js";
+import { type ProviderStateBackendLogEvent } from "./state-backend-report.js";
+import { type AuthFlowRequest, type OperationRequest } from "./types.js";
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+    category: ProviderErrorCategory;
+    taxonomyVersion: string;
+    retryable: boolean;
+    upstreamStatus?: number;
+    providerObservability?: ProviderErrorObservability;
+};
+export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    providerId: z.ZodString;
+    operationId: z.ZodString;
+    sessionKey: z.ZodString;
+    connectionId: z.ZodString;
+    serviceAccountId: z.ZodString;
+    ownerPodId: z.ZodString;
+    generation: z.ZodNumber;
+    sourcePodId: z.ZodString;
+    forwardedAt: z.ZodString;
+    deadlineAt: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+    operationRequest: z.ZodObject<{
+        requestId: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        connectionId: z.ZodOptional<z.ZodString>;
+        tenantId: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        trace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        connection: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            mode: z.ZodEnum<{
+                credentials: "credentials";
+                none: "none";
+                oauth2: "oauth2";
+                "platform-managed": "platform-managed";
+                oauth2_proxied: "oauth2_proxied";
+            }>;
+            secrets: z.ZodRecord<z.ZodString, z.ZodString>;
+            scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            externalRef: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ProviderServerStatefulForwardEnvelope = Readonly<z.infer<typeof ProviderServerStatefulForwardEnvelopeSchema>>;
+export type ProviderServerStatefulOwnerFence = Readonly<Pick<ProviderServerStatefulForwardEnvelope, "providerId" | "sessionKey" | "ownerPodId" | "generation" | "sourcePodId" | "forwardedAt" | "requestId" | "idempotencyKey">>;
+export type ProviderServerStatefulOwnerFenceValidator = (fence: ProviderServerStatefulOwnerFence, signal: AbortSignal) => boolean | Promise<boolean>;
+export type ProviderServerOperationExecutorInput<TContext extends Partial<ProviderContext> = ProviderContext> = {
+    readonly provider: ProviderDefinition<TContext>;
+    readonly operationId: string;
+    readonly ctx: TContext;
+    readonly request: OperationRequest & {
+        readonly deadlineAt?: string;
+    };
+    readonly signal?: AbortSignal;
+    readonly internalStatefulForward?: ProviderServerStatefulForwardEnvelope;
+};
+export type ProviderServerOperationExecutor<TContext extends Partial<ProviderContext> = ProviderContext> = (input: ProviderServerOperationExecutorInput<TContext>) => Promise<unknown>;
+export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
+export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
+export declare function resolveAuthFlowProxyAffinityKey(provider: ProviderDefinition, request: Pick<AuthFlowRequest, "connection" | "connectionId" | "externalRef" | "tenantId" | "providerId">): string;
+type ProviderRequestCost = {
+    durationMs: number;
+    cpuUserMicros: number;
+    cpuSystemMicros: number;
+    cpuTotalMicros: number;
+};
+type ProviderServerLogEventBase = ProviderRequestCost & {
+    providerId: string;
+    kind: "operation" | "auth";
+    route: string;
+    requestId?: string;
+    connectionId?: string;
+    flowId?: string;
+    tenantId?: string;
+    requestedProviderId?: string;
+    status: number;
+    proxy?: ProxyTelemetryLogPayload;
+    resolver?: ResolverTelemetryLogPayload;
+    http?: HttpTelemetryLogPayload;
+};
+export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
+    level: "info";
+    event: "provider_request_completed";
+}) | (ProviderServerLogEventBase & {
+    level: "warn" | "error";
+    event: "provider_request_failed";
+    code: string;
+    errorClass: string;
+    message: string;
+    upstreamStatus?: number;
+    errorCategory?: ProviderErrorCategory;
+    taxonomyVersion?: string;
+    retryable?: boolean;
+    providerObservability?: ProviderErrorObservability;
+    causeChain?: ProviderErrorCauseFrame[];
+    stack?: string[];
+    signal?: "unregistered_provider_error_code";
+    signalFix?: string;
+    issues?: Array<{
+        path: string;
+        code: string;
+        message: string;
+    }>;
+}) | {
+    level: "warn";
+    event: "provider_secrets_missing";
+    providerId: string;
+    missingSecrets: string[];
+} | {
+    /** Emitted once at boot when `locales/en.json` exists but cannot be read. */
+    level: "warn";
+    event: "provider_locale_catalogs_unavailable";
+    providerId: string;
+    reason: string;
+} | ({
+    level: "info";
+    event: "provider_handle";
+} & HandleTelemetryEvent) | {
+    level: "warn";
+    event: "provider_cleanup_failed";
+    providerId: string;
+    kind: "operation" | "auth";
+    route: string;
+    requestId?: string;
+    resource: "browser" | "stealth";
+    errorClass: string;
+    message: string;
+} | {
+    level: "error";
+    event: "provider_shutdown_hook_failed";
+    providerId: string;
+    hookIndex: number;
+    errorClass: string;
+    message: string;
+} | {
+    /** `warn` when the requested attachment could not be honoured, otherwise `info`. */
+    level: "info" | "warn";
+    event: "provider_engine_mode";
+    providerId: string;
+    /** Resolved attachment; `custom` for an opaque host engine. */
+    mode: ProviderEngineMode | "custom";
+    source: "engine" | "env" | "option" | "default";
+    /** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+    deprecated: boolean;
+    /** False when the engine refuses to attach; `/readyz` reports 503. */
+    attached: boolean;
+    sdkVersion: string;
+    runtimeTarget?: ProviderRuntimeTarget;
+    /**
+     * Non-fatal selection findings, e.g. `invalid_env_value`,
+     * `env_overrode_option`, `engine_object_overrode_requested_mode`,
+     * `engine_env_ignored`. Absent when the selection was unambiguous.
+     */
+    warnings?: readonly string[];
+} | ProviderStateBackendLogEvent | SelfTestCancellationLogEvent;
+export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
+export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
+    logger?: ProviderServerLogger;
+    /** Capability attachment boundary. Defaults to the local in-process engine. */
+    engine?: ProviderEngine;
+    /**
+     * Explicit engine attachment mode. Lowest precedence of the three inputs:
+     * an explicit `engine` object wins, then `APIFUSE__ENGINE__MODE` (the
+     * deployment outranks provider code), then this option, then the in-process
+     * default. Disagreement is never fatal — it is reported on the
+     * `provider_engine_mode` boot event (`env_overrode_option`,
+     * `engine_object_overrode_requested_mode`), which only `serve` emits. A value
+     * that is not a known mode throws `ValidationError`, because unlike the env it
+     * can only come from calling code.
+     */
+    engineMode?: ProviderEngineMode;
+    /** Request-file resolver supplied by the engine host when `files` is declared. */
+    files?: ProviderFilesContext;
+    /** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
+    operationExecutor?: ProviderServerOperationExecutor<TContext>;
+    /** Optional signed internal executor for stateful owner forwarding. */
+    internalOperationExecutor?: ProviderServerOperationExecutor<TContext>;
+    statefulForwarding?: {
+        readonly secret: string;
+        readonly maxSkewMs?: number;
+        readonly replayCacheMaxEntries?: number;
+        /** Required fail-closed check against the SDK/runtime owner registry. */
+        readonly validateOwnerFence: ProviderServerStatefulOwnerFenceValidator;
+    };
+    /** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
+    stt?: SttContext;
+    /** Optional OCR override for tests or custom hosts; local/prod normally resolves from env. */
+    ocr?: OcrContext;
+    /**
+     * Optional resolver override for tests or custom hosts; local/prod normally resolves from env.
+     * SDK chains are reconstructed with each request's telemetry sink. An opaque host
+     * resolver is reported as one custom invocation; its internal vendor work is not exposed.
+     */
+    resolver?: ResolverContext;
+    /**
+     * Pre-loaded provider locale catalogs used to localize auth turns and the
+     * client-facing `message`/`fix` of provider errors.
+     *
+     * Defaults to reading `locales/{en,ko,ja}.json` from the provider directory
+     * once at server construction. Supply this to bundle catalogs instead of
+     * probing the filesystem, or to pin catalogs in tests.
+     */
+    localeCatalogs?: ProviderLocaleCatalogMap;
+    /** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
+    state?: ProviderRuntimeState;
+    /** Allow process-local runtime state only for local development and tests. */
+    allowMemoryStateFallback?: boolean;
+    /**
+     * Graceful process shutdown. Hooks run in declaration order after listeners stop accepting work.
+     *
+     * @example
+     * ```ts
+     * await serve(provider, {
+     *	 shutdown: {
+     *		 hooks: [
+     *			 async () => { await emitter.flush(); },
+     *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+     *			 async () => { await lease.release(); },
+     *			 async () => { await router.close(); },
+     *		 ],
+     *	 },
+     * });
+     * ```
+     */
+    shutdown?: {
+        readonly hooks?: Array<() => Promise<void>>;
+        readonly signals?: boolean | NodeJS.Signals[];
+        readonly timeoutMs?: number;
+    };
+};
+export type ProviderErrorCauseFrame = {
+    errorClass: string;
+    code?: string;
+    message: string;
+    messageLength: number;
+    messageFingerprint: string;
+    providerObservability?: ProviderErrorObservability;
+};
+/**
+ * Primary, cross-runtime app factory. Declared capability ESM is preloaded
+ * asynchronously, so this path works on Bun and every supported Node release.
+ */
+export declare function createServerAppAsync<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ProviderServerOptions<TContext>): Promise<Hono>;
+/**
+ * Synchronous compatibility factory. Standard providers remain synchronous on
+ * every runtime because they load no capability modules. Providers declaring a
+ * capability require Bun or Node >=22.12; older Node releases receive an
+ * actionable error directing them to createServerAppAsync().
+ */
+export declare function createServerApp<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ProviderServerOptions<TContext>): Hono;
+export type ProviderServerCloseOptions = {
+    readonly timeoutMs?: number;
+};
+export type ProviderServerHandle = {
+    readonly port: number;
+    close(options?: ProviderServerCloseOptions): Promise<void>;
+};
+export interface ServeOptions<TContext extends Partial<ProviderContext> = ProviderContext> extends ProviderServerOptions<TContext> {
+    host?: string;
+    port?: number;
+    /**
+     * Port for the internal self-test listener (default 3001 or
+     * APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT). The listener only starts
+     * when APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET is present.
+     */
+    selfTestPort?: number;
+}
+export declare function serve<TContext extends Partial<ProviderContext> = ProviderContext>(provider: ProviderDefinition<TContext>, options?: ServeOptions<TContext>): Promise<ProviderServerHandle>;
+export {};