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

package/src/server/self-test.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
 
 import { TURN_KINDS } from "../auth-turn/index.js";
+import { SDK_VERSION } from "./sdk-version.js";
 
 import { type Context, Hono } from "hono";
 import { z } from "zod";
@@ -77,11 +77,22 @@ export interface SelfTestResponse {
 	results: SelfTestCaseResult[];
 }
 
+export interface SelfTestCancellationLogEvent {
+	level: "info";
+	event: "self_test_run_cancelled";
+	providerId: string;
+	requestId: string;
+	operationId: string;
+	caseName: string;
+	reason: string;
+}
+
 export type SelfTestOperationInvoke = (args: {
 	operationId: string;
 	input: unknown;
 	connection?: OperationConnection;
 	requestId: string;
+	signal?: AbortSignal;
 }) => Promise<{
 	status: number;
 	data: unknown;
@@ -106,6 +117,9 @@ export type SelfTestAuthFlowInvoke = (args: {
 	externalRef?: string;
 	input?: Record<string, unknown>;
 	context?: Record<string, unknown>;
+	/** Opaque engine state from the previous turn (`engine` in the auth response), sent verbatim. */
+	engine?: { egressLease: string };
+	signal?: AbortSignal;
 }) => Promise<{
 	status: number;
 	body: unknown;
@@ -165,28 +179,10 @@ export interface SelfTestAppOptions {
 	requestBudgetMs?: number;
 	/** Env override for secret collection + budget resolution (tests). */
 	env?: Readonly<Record<string, string | undefined>>;
+	/** Structured server logger; defaults to the same JSON console shape as the provider server. */
+	logger?: (event: SelfTestCancellationLogEvent) => void;
 }
 
-function resolveSdkVersion(): string {
-	try {
-		const packageJsonUrl = new URL("../../package.json", import.meta.url);
-		const parsed: unknown = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
-		if (
-			parsed &&
-			typeof parsed === "object" &&
-			"version" in parsed &&
-			typeof (parsed as { version: unknown }).version === "string"
-		) {
-			return (parsed as { version: string }).version;
-		}
-	} catch {
-		// fall through to unknown
-	}
-	return "unknown";
-}
-
-const SDK_VERSION = resolveSdkVersion();
-
 type AnyHealthCheckSuite = HealthCheckSuite<unknown, unknown>;
 type AnyHealthCheckCase = HealthCheckCase<unknown, unknown>;
 
@@ -231,33 +227,35 @@ export function computeSelfTestPlanDigest(provider: ProviderDefinition): string
 
 /**
  * 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: OperationDefinition): boolean {
-	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: {
 	request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
 }): SelfTestOperationInvoke {
-	return async ({ operationId, input, connection, requestId }) => {
-		const response = await app.request(`/v1/${encodeURIComponent(operationId)}`, {
-			method: "POST",
-			headers: { "content-type": "application/json" },
-			body: JSON.stringify({
-				requestId,
-				input: input ?? {},
-				...(connection ? { connection } : {}),
+	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({
+					requestId,
+					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: unknown = text;
 		try {
@@ -277,22 +275,75 @@ export function createSelfTestInvoke(app: {
 	};
 }
 
+async function cancelSelfTestResponse(response: Response): Promise<void> {
+	await response.body?.cancel().catch(() => undefined);
+}
+
+function selfTestAbortReason(reason: unknown, sensitiveValues: readonly string[]): string {
+	const text =
+		reason instanceof Error
+			? reason.message || reason.name
+			: reason === undefined
+				? "aborted"
+				: String(reason);
+	return redactSelfTestText(text, sensitiveValues);
+}
+
+function logSelfTestCancellation(
+	provider: ProviderDefinition,
+	options: SelfTestAppOptions,
+	requestId: string,
+	selected: SelectedCase,
+	signal: AbortSignal,
+	sensitiveValues: readonly string[],
+): void {
+	const event: SelfTestCancellationLogEvent = {
+		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: {
 	request: (input: string, requestInit?: RequestInit) => Response | Promise<Response>;
 }): SelfTestAuthFlowInvoke {
-	return async ({ route, requestId, flowId, connectionId, externalRef, input, context }) => {
+	return async ({
+		route,
+		requestId,
+		flowId,
+		connectionId,
+		externalRef,
+		input,
+		context,
+		engine,
+		signal,
+	}) => {
 		const response = await app.request(`/auth/${route}`, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify({
 				requestId,
 				flowId,
+				// Engine ceremony leases are scoped to a tenant; the self-test has no
+				// customer tenant, so it presents a fixed one that never collides.
+				tenantId: "self-test",
 				...(connectionId ? { connectionId } : {}),
 				...(externalRef ? { externalRef } : {}),
 				...(input ? { input } : {}),
 				...(context ? { context } : {}),
+				...(engine ? { engine } : {}),
 			}),
+			...(signal ? { signal } : {}),
 		});
 		const text = await response.text();
 		let body: unknown = text;
@@ -312,17 +363,32 @@ class SelfTestCaseTimeoutError extends Error {
 	}
 }
 
-async function withCaseTimeout<T>(run: () => Promise<T>, timeoutMs: number): Promise<T> {
+async function withCaseTimeout<T>(
+	run: () => Promise<T>,
+	timeoutMs: number,
+	controller: AbortController,
+): Promise<T> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
+	let onAbort: (() => void) | undefined;
 	try {
 		return await Promise.race([
 			run(),
 			new Promise<never>((_, reject) => {
-				timer = setTimeout(() => reject(new SelfTestCaseTimeoutError(timeoutMs)), timeoutMs);
+				timer = setTimeout(() => {
+					const error = new SelfTestCaseTimeoutError(timeoutMs);
+					controller.abort(error);
+					reject(error);
+				}, timeoutMs);
+			}),
+			new Promise<never>((_, 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);
 	}
 }
 
@@ -471,6 +537,7 @@ type ParsedAuthFlowTurn =
 			ok: true;
 			turn: { kind: string; data?: unknown; expectedInput?: unknown };
 			contextPatch?: Record<string, unknown>;
+			engine?: { egressLease: string };
 	  }
 	| { ok: false; code: string; message: string; httpStatus: number };
 
@@ -499,6 +566,7 @@ function parseAuthFlowResponse(result: { status: number; body: unknown }): Parse
 		};
 	}
 	const contextPatch = objectProperty(result.body, "contextPatch");
+	const egressLease = objectProperty(objectProperty(result.body, "engine"), "egressLease");
 	return {
 		ok: true,
 		turn: {
@@ -509,6 +577,7 @@ function parseAuthFlowResponse(result: { status: number; body: unknown }): Parse
 		...(contextPatch && typeof contextPatch === "object" && !Array.isArray(contextPatch)
 			? { contextPatch: contextPatch as Record<string, unknown> }
 			: {}),
+		...(typeof egressLease === "string" && egressLease ? { engine: { egressLease } } : {}),
 	};
 }
 
@@ -595,6 +664,7 @@ async function materializeFlowCredential(
 		isAbandoned?: () => boolean;
 		connectionId?: string;
 		externalRef?: string;
+		signal?: AbortSignal;
 	} = {},
 ): Promise<
 	| { credential: Record<string, string> }
@@ -621,6 +691,7 @@ async function materializeFlowCredential(
 			flowId,
 			...(options.connectionId ? { connectionId: options.connectionId } : {}),
 			...(options.externalRef ? { externalRef: options.externalRef } : {}),
+			...(options.signal ? { signal: options.signal } : {}),
 		}),
 	);
 	if (!started.ok) {
@@ -696,6 +767,10 @@ async function materializeFlowCredential(
 				...(options.externalRef ? { externalRef: options.externalRef } : {}),
 				input: submitInputs,
 				...(Object.keys(flowContext).length > 0 ? { context: flowContext } : {}),
+				// The ceremony egress lease is engine state, not flow context: carry it the
+				// way the gateway does so the continue turn stays on the start turn's egress.
+				...(started.engine ? { engine: started.engine } : {}),
+				...(options.signal ? { signal: options.signal } : {}),
 			}),
 		);
 		if (!continued.ok) {
@@ -756,7 +831,7 @@ async function resolveSelfTestConnection(
 	execution: SelfTestExecutionContext,
 	operationId: string,
 	suite: AnyHealthCheckSuite,
-	options: { forceLogin?: boolean; isAbandoned?: () => boolean } = {},
+	options: { forceLogin?: boolean; isAbandoned?: () => boolean; signal?: AbortSignal } = {},
 ): Promise<SelfTestConnectionResolution> {
 	if (!suite.requiresConnection) return { kind: "connection" };
 	const inputs = execution.credentials ?? {};
@@ -861,6 +936,7 @@ async function resolveSelfTestConnection(
 		...(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
@@ -879,10 +955,9 @@ async function resolveSelfTestConnection(
 		}
 		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",
@@ -913,6 +988,7 @@ async function executeSelfTestCase(
 	operationId: string,
 	suite: AnyHealthCheckSuite,
 	healthCase: AnyHealthCheckCase,
+	caseController: AbortController,
 ): Promise<SelfTestCaseResult> {
 	const { provider, invoke } = execution;
 	// execution.sensitiveValues may grow while the case runs (flow-issued
@@ -926,6 +1002,8 @@ async function executeSelfTestCase(
 	const caseDeadlineAtMs = performance.now() + timeoutMs;
 	const remainingCaseTimeoutMs = () =>
 		Math.max(1, Math.ceil(caseDeadlineAtMs - performance.now()));
+	const runWithCaseTimeout = <T>(run: () => Promise<T>, remainingMs: number) =>
+		withCaseTimeout(run, remainingMs, caseController);
 
 	const beginCase = () => {
 		const startedAt = new Date().toISOString();
@@ -959,16 +1037,17 @@ async function executeSelfTestCase(
 	}
 
 	const resolveConnection = async (forceLogin: boolean): Promise<SelfTestConnectionResolution> => {
-		// 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(
+			return await runWithCaseTimeout(
 				() =>
 					resolveSelfTestConnection(execution, operationId, suite, {
 						forceLogin,
 						isAbandoned: () => abandoned,
+						signal: caseController.signal,
 					}),
 				remainingCaseTimeoutMs(),
 			);
@@ -1012,7 +1091,12 @@ async function executeSelfTestCase(
 		// 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({
@@ -1033,6 +1117,7 @@ async function executeSelfTestCase(
 										input: gatewayInput,
 										connection,
 										requestId: `${execution.requestId}-prepare-${randomUUID()}`,
+										signal: caseController.signal,
 									});
 									if (executed.status === 401 || executed.status === 403) {
 										prepareAuthStatus = executed.status;
@@ -1053,6 +1138,7 @@ async function executeSelfTestCase(
 					input: preparedInput,
 					connection,
 					requestId: `${execution.requestId}-${randomUUID()}`,
+					signal: caseController.signal,
 				});
 				const durationMs = performance.now() - startedAtMs;
 
@@ -1383,47 +1469,77 @@ export function createSelfTestApp(provider: ProviderDefinition, options: SelfTes
 			};
 			const deadline = performance.now() + requestBudgetMs;
 			const results: SelfTestCaseResult[] = [];
+			const runSignal = c.req.raw.signal;
+			let interruptedCase: SelectedCase | undefined;
 			// 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;
-				}
-				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;
+				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;
+					}
+				} 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;