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

package/dist/server/self-test.js

@@ -115,25 +115,15 @@ export function computeSelfTestPlanDigest(provider) {
 }
 /**
  * Fail-closed read-only classification: an operation may self-test only when
- * its own metadata marks it read-only (annotations.readOnly or
- * toolRouter.riskClass "read") and nothing marks it side-effecting. Unclassified
- * operations are refused so the endpoint cannot become a mutation oracle.
+ * its authored safety source of truth classifies it as read-only.
  */
 export function isSelfTestReadOnlyOperation(operation) {
-    const annotations = operation.annotations;
-    if (annotations?.readOnly === false)
-        return false;
-    if (annotations?.destructive === true)
-        return false;
-    const riskClass = operation.toolRouter?.riskClass;
-    if (riskClass !== undefined && riskClass !== "read")
-        return false;
-    return annotations?.readOnly === true || riskClass === "read";
+    return operation.riskClass === "read";
 }
 /** Binds the self-test executor to a tenant app's /v1 pipeline in-process. */
 export function createSelfTestInvoke(app) {
-    return async ({ operationId, input, connection, requestId }) => {
-        const response = await app.request(`/v1/${encodeURIComponent(operationId)}`, {
+    return async ({ operationId, input, connection, requestId, signal }) => {
+        const responsePromise = Promise.resolve(app.request(`/v1/${encodeURIComponent(operationId)}`, {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({
@@ -141,7 +131,14 @@ export function createSelfTestInvoke(app) {
                 input: input ?? {},
                 ...(connection ? { connection } : {}),
             }),
-        });
+            ...(signal ? { signal } : {}),
+        }));
+        const response = await responsePromise;
+        if (signal?.aborted) {
+            await cancelSelfTestResponse(response);
+            signal.throwIfAborted();
+        }
+        // An abort after body consumption starts may let response.text() finish.
         const text = await response.text();
         let body = text;
         try {
@@ -161,9 +158,36 @@ export function createSelfTestInvoke(app) {
         return { status: response.status, data: body };
     };
 }
+async function cancelSelfTestResponse(response) {
+    await response.body?.cancel().catch(() => undefined);
+}
+function selfTestAbortReason(reason, sensitiveValues) {
+    const text = reason instanceof Error
+        ? reason.message || reason.name
+        : reason === undefined
+            ? "aborted"
+            : String(reason);
+    return redactSelfTestText(text, sensitiveValues);
+}
+function logSelfTestCancellation(provider, options, requestId, selected, signal, sensitiveValues) {
+    const event = {
+        level: "info",
+        event: "self_test_run_cancelled",
+        providerId: provider.id,
+        requestId,
+        operationId: selected.operationId,
+        caseName: selected.healthCase.name,
+        reason: selfTestAbortReason(signal.reason, sensitiveValues),
+    };
+    if (options.logger) {
+        options.logger(event);
+        return;
+    }
+    console.log(JSON.stringify(event));
+}
 /** Binds the self-test auth-flow driver to a tenant app's /auth pipeline in-process. */
 export function createSelfTestAuthFlowInvoke(app) {
-    return async ({ route, requestId, flowId, connectionId, externalRef, input, context }) => {
+    return async ({ route, requestId, flowId, connectionId, externalRef, input, context, signal, }) => {
         const response = await app.request(`/auth/${route}`, {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -175,6 +199,7 @@ export function createSelfTestAuthFlowInvoke(app) {
                 ...(input ? { input } : {}),
                 ...(context ? { context } : {}),
             }),
+            ...(signal ? { signal } : {}),
         });
         const text = await response.text();
         let body = text;
@@ -193,19 +218,32 @@ class SelfTestCaseTimeoutError extends Error {
         this.name = "SelfTestCaseTimeoutError";
     }
 }
-async function withCaseTimeout(run, timeoutMs) {
+async function withCaseTimeout(run, timeoutMs, controller) {
     let timer;
+    let onAbort;
     try {
         return await Promise.race([
             run(),
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new SelfTestCaseTimeoutError(timeoutMs)), timeoutMs);
+                timer = setTimeout(() => {
+                    const error = new SelfTestCaseTimeoutError(timeoutMs);
+                    controller.abort(error);
+                    reject(error);
+                }, timeoutMs);
+            }),
+            new Promise((_, reject) => {
+                onAbort = () => reject(controller.signal.reason);
+                controller.signal.addEventListener("abort", onAbort, { once: true });
+                if (controller.signal.aborted)
+                    onAbort();
             }),
         ]);
     }
     finally {
         if (timer !== undefined)
             clearTimeout(timer);
+        if (onAbort)
+            controller.signal.removeEventListener("abort", onAbort);
     }
 }
 function objectProperty(value, key) {
@@ -389,6 +427,7 @@ async function materializeFlowCredential(execution, inputs, options = {}) {
         flowId,
         ...(options.connectionId ? { connectionId: options.connectionId } : {}),
         ...(options.externalRef ? { externalRef: options.externalRef } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
     }));
     if (!started.ok) {
         return { kind: "flow_error", code: started.code, message: started.message };
@@ -460,6 +499,7 @@ async function materializeFlowCredential(execution, inputs, options = {}) {
             ...(options.externalRef ? { externalRef: options.externalRef } : {}),
             input: submitInputs,
             ...(Object.keys(flowContext).length > 0 ? { context: flowContext } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
         }));
         if (!continued.ok) {
             // Providers built with defineCredentialsAuth cannot return a retry
@@ -613,6 +653,7 @@ async function resolveSelfTestConnection(execution, operationId, suite, options
         ...(options.isAbandoned !== undefined ? { isAbandoned: options.isAbandoned } : {}),
         connectionId,
         externalRef: `${execution.provider.id}-${operationId}-self-test`,
+        ...(options.signal ? { signal: options.signal } : {}),
     });
     if (!("credential" in materialized)) {
         // Only the multi-turn SKIP is negative-cached. Flow ERRORS
@@ -632,10 +673,9 @@ async function resolveSelfTestConnection(execution, operationId, suite, options
         }
         return materialized;
     }
-    // A flow that outlived the case deadline still completes here (the timeout
-    // only races the promise, it cannot cancel it). The case already reported
-    // self_test_timeout — caching this credential would let the next probe
-    // reuse a login whose latency just failed the case, hiding the failure.
+    // Abort is cooperative: a flow may still complete after the case deadline
+    // if provider code ignores the signal. Never cache that late credential or
+    // let the next probe hide the timed-out login.
     if (options.isAbandoned?.() === true) {
         return {
             kind: "flow_error",
@@ -659,7 +699,7 @@ async function resolveSelfTestConnection(execution, operationId, suite, options
 function isAuthFailureCaseResult(result) {
     return result.status === "failed" && (result.httpStatus === 401 || result.httpStatus === 403);
 }
-async function executeSelfTestCase(execution, operationId, suite, healthCase) {
+async function executeSelfTestCase(execution, operationId, suite, healthCase, caseController) {
     const { provider, invoke } = execution;
     // execution.sensitiveValues may grow while the case runs (flow-issued
     // secrets); redact always reads the live array.
@@ -671,6 +711,7 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase) {
     // a 30s case must never take ~4×30s across its stages.
     const caseDeadlineAtMs = performance.now() + timeoutMs;
     const remainingCaseTimeoutMs = () => Math.max(1, Math.ceil(caseDeadlineAtMs - performance.now()));
+    const runWithCaseTimeout = (run, remainingMs) => withCaseTimeout(run, remainingMs, caseController);
     const beginCase = () => {
         const startedAt = new Date().toISOString();
         const startedAtMs = performance.now();
@@ -695,14 +736,15 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase) {
         });
     }
     const resolveConnection = async (forceLogin) => {
-        // The timeout only races the flow promise — it cannot cancel it. Once
-        // the deadline fires, the still-running resolution is marked abandoned
-        // so its late completion cannot write the session cache.
+        // The deadline aborts the in-process flow request. Keep the abandonment
+        // guard as a backstop for provider code that ignores cancellation so a
+        // late completion still cannot write the session cache.
         let abandoned = false;
         try {
-            return await withCaseTimeout(() => resolveSelfTestConnection(execution, operationId, suite, {
+            return await runWithCaseTimeout(() => resolveSelfTestConnection(execution, operationId, suite, {
                 forceLogin,
                 isAbandoned: () => abandoned,
+                signal: caseController.signal,
             }), remainingCaseTimeoutMs());
         }
         catch (error) {
@@ -739,7 +781,10 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase) {
         // operation attempt, or a slow login reads as a fast healthy case.
         const { startedAtMs, finish } = caseScope;
         try {
-            return await withCaseTimeout(async () => {
+            return await runWithCaseTimeout(async () => {
+                if (healthCase.assertions === undefined) {
+                    throw new Error(`Self-test cannot execute declarative health-check case "${healthCase.name}"; run its scenario through the health monitor.`);
+                }
                 const resolvedInput = resolveHealthCheckInputDateTokens(healthCase.input);
                 const preparedInput = healthCase.prepareInput
                     ? await healthCase.prepareInput({
@@ -758,6 +803,7 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase) {
                                     input: gatewayInput,
                                     connection,
                                     requestId: `${execution.requestId}-prepare-${randomUUID()}`,
+                                    signal: caseController.signal,
                                 });
                                 if (executed.status === 401 || executed.status === 403) {
                                     prepareAuthStatus = executed.status;
@@ -777,6 +823,7 @@ async function executeSelfTestCase(execution, operationId, suite, healthCase) {
                     input: preparedInput,
                     connection,
                     requestId: `${execution.requestId}-${randomUUID()}`,
+                    signal: caseController.signal,
                 });
                 const durationMs = performance.now() - startedAtMs;
                 if (executed.status < 200 || executed.status >= 300) {
@@ -1054,41 +1101,65 @@ export function createSelfTestApp(provider, options) {
             };
             const deadline = performance.now() + requestBudgetMs;
             const results = [];
+            const runSignal = c.req.raw.signal;
+            let interruptedCase;
             // Sequential execution (parallelism 1): self-tests run on serving pods
             // and must never compete with themselves for upstream quota.
             for (const selected of selection.cases) {
-                if (performance.now() >= deadline) {
-                    const now = new Date().toISOString();
-                    results.push({
-                        operationId: selected.operationId,
-                        caseName: selected.healthCase.name,
-                        status: "skipped",
-                        label: selected.healthCase.name,
-                        responseTimeMs: 0,
-                        skipReason: "budget_exhausted",
-                        startedAt: now,
-                        finishedAt: now,
-                    });
-                    continue;
+                const caseController = new AbortController();
+                const abortFromRun = () => caseController.abort(runSignal.reason);
+                runSignal.addEventListener("abort", abortFromRun, { once: true });
+                if (runSignal.aborted)
+                    abortFromRun();
+                try {
+                    if (runSignal.aborted) {
+                        interruptedCase = selected;
+                        break;
+                    }
+                    if (performance.now() >= deadline) {
+                        const now = new Date().toISOString();
+                        results.push({
+                            operationId: selected.operationId,
+                            caseName: selected.healthCase.name,
+                            status: "skipped",
+                            label: selected.healthCase.name,
+                            responseTimeMs: 0,
+                            skipReason: "budget_exhausted",
+                            startedAt: now,
+                            finishedAt: now,
+                        });
+                        continue;
+                    }
+                    if (!isSelfTestReadOnlyOperation(selected.operation)) {
+                        const now = new Date().toISOString();
+                        results.push({
+                            operationId: selected.operationId,
+                            caseName: selected.healthCase.name,
+                            status: "error",
+                            label: selected.healthCase.name,
+                            responseTimeMs: 0,
+                            error: {
+                                code: "operation_not_read_only",
+                                message: `Operation "${selected.operationId}" is not classified read-only; self-test refuses to execute it.`,
+                            },
+                            startedAt: now,
+                            finishedAt: now,
+                        });
+                        continue;
+                    }
+                    results.push(await executeSelfTestCase(execution, selected.operationId, selected.suite, selected.healthCase, caseController));
+                    if (runSignal.aborted) {
+                        interruptedCase = selected;
+                        break;
+                    }
                 }
-                if (!isSelfTestReadOnlyOperation(selected.operation)) {
-                    const now = new Date().toISOString();
-                    results.push({
-                        operationId: selected.operationId,
-                        caseName: selected.healthCase.name,
-                        status: "error",
-                        label: selected.healthCase.name,
-                        responseTimeMs: 0,
-                        error: {
-                            code: "operation_not_read_only",
-                            message: `Operation "${selected.operationId}" is not classified read-only; self-test refuses to execute it.`,
-                        },
-                        startedAt: now,
-                        finishedAt: now,
-                    });
-                    continue;
+                finally {
+                    runSignal.removeEventListener("abort", abortFromRun);
+                    caseController.abort();
                 }
-                results.push(await executeSelfTestCase(execution, selected.operationId, selected.suite, selected.healthCase));
+            }
+            if (interruptedCase) {
+                logSelfTestCancellation(provider, options, request.requestId, interruptedCase, runSignal, execution.sensitiveValues);
             }
             const singleCase = request.operationId !== undefined && request.caseName !== undefined;
             const response = {

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

@@ -0,0 +1,230 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { type ProviderEngine } from "../engine.js";
+import { type ProviderErrorObservability } from "../errors.js";
+import { type ProviderErrorCategory } from "../observability.js";
+import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
+import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
+import type { SelfTestCancellationLogEvent } from "./self-test.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>;
+        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;
+    status: number;
+    proxy?: ProxyTelemetryLogPayload;
+};
+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[];
+    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[];
+} | {
+    level: "info";
+    event: "provider_choice_token";
+    providerId: string;
+    purpose: string;
+    operation: "parse" | "consume";
+    format: "word" | "legacy";
+    outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
+    consumeMode: "never" | "on-parse" | "explicit";
+    consumed: boolean;
+    replay: boolean;
+} | {
+    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;
+} | 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;
+    /** 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. */
+    resolver?: ResolverContext;
+    /** 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 {};