@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/dist/server/self-test.js

@@ -0,0 +1,555 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { Hono } from "hono";
+import { z } from "zod";
+import { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens";
+import { collectSelfTestSensitiveValues, redactSelfTestText } from "./self-test-redaction";
+import { DEFAULT_SELF_TEST_PORT, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, verifySelfTestAuthorization, } from "./self-test-token";
+export const SELF_TEST_SCHEMA_VERSION = 1;
+export const SELF_TEST_PATH = "/internal/health/self-test";
+export const SELF_TEST_HEALTHZ_PATH = "/healthz";
+/** Overall wall-clock budget for one self-test request (all selected cases). */
+export const PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV = "APIFUSE__PROVIDER_RUNTIME__SELF_TEST_REQUEST_BUDGET_MS";
+export const DEFAULT_SELF_TEST_REQUEST_BUDGET_MS = 120_000;
+const DEFAULT_CASE_TIMEOUT_MS = 30_000;
+const SELF_TEST_BUSY_RETRY_AFTER_MS = 1_000;
+export const SelfTestRequestSchema = z.object({
+    schemaVersion: z.number().int(),
+    requestId: z.string().min(1),
+    /** Single-case form (one case per request): both fields required together. */
+    operationId: z.string().min(1).optional(),
+    caseName: z.string().min(1).optional(),
+    /** Batch form: optional selectors; omitted = every declared case. */
+    operations: z.array(z.string().min(1)).optional(),
+    caseNames: z.array(z.string().min(1)).optional(),
+    /** Per-case timeout override; case/suite/provider defaults apply otherwise. */
+    timeoutMs: z.number().int().min(1).max(600_000).optional(),
+    /** Credential material for requiresConnection cases; never persisted. */
+    credentials: z.object({ inputs: z.record(z.string(), z.string()) }).optional(),
+});
+function resolveSdkVersion() {
+    try {
+        const packageJsonUrl = new URL("../../package.json", import.meta.url);
+        const parsed = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+        if (parsed &&
+            typeof parsed === "object" &&
+            "version" in parsed &&
+            typeof parsed.version === "string") {
+            return parsed.version;
+        }
+    }
+    catch {
+        // fall through to unknown
+    }
+    return "unknown";
+}
+const SDK_VERSION = resolveSdkVersion();
+function healthCheckSuite(operation) {
+    return operation.healthCheck;
+}
+/**
+ * Stable sha256 over the provider's declared health plan (operations, case
+ * names, timeouts) so the scheduler can detect plan/image skew by comparing
+ * the manifest planDigest against the pod-reported one.
+ */
+export function computeSelfTestPlanDigest(provider) {
+    const plan = Object.keys(provider.operations)
+        .sort()
+        .flatMap((operationId) => {
+        const operation = provider.operations[operationId];
+        const suite = operation ? healthCheckSuite(operation) : undefined;
+        if (!suite)
+            return [];
+        return [
+            {
+                operationId,
+                interval: suite.interval,
+                timeoutMs: suite.timeoutMs ?? null,
+                requiresConnection: suite.requiresConnection ?? false,
+                cases: suite.cases.map((healthCase) => ({
+                    name: healthCase.name,
+                    timeoutMs: healthCase.timeoutMs ?? null,
+                    degradedThresholdMs: healthCase.degradedThresholdMs ?? null,
+                    expectedStatus: healthCase.expectedStatus ?? "ok",
+                })),
+            },
+        ];
+    });
+    const canonical = JSON.stringify({
+        schemaVersion: SELF_TEST_SCHEMA_VERSION,
+        providerId: provider.id,
+        plan,
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * 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.
+ */
+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";
+}
+/** 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)}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                requestId,
+                input: input ?? {},
+                ...(connection ? { connection } : {}),
+            }),
+        });
+        const text = await response.text();
+        let body = text;
+        try {
+            body = text.length > 0 ? JSON.parse(text) : undefined;
+        }
+        catch {
+            // non-JSON transports keep the raw text as data
+        }
+        if (response.ok && body && typeof body === "object" && !Array.isArray(body) && "data" in body) {
+            const envelope = body;
+            return {
+                status: response.status,
+                data: envelope.data,
+                ...(envelope.meta ? { meta: envelope.meta } : {}),
+            };
+        }
+        return { status: response.status, data: body };
+    };
+}
+class SelfTestCaseTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Self-test case timed out after ${timeoutMs}ms`);
+        this.name = "SelfTestCaseTimeoutError";
+    }
+}
+async function withCaseTimeout(run, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            run(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new SelfTestCaseTimeoutError(timeoutMs)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function objectProperty(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+        if (entryKey === key)
+            return entryValue;
+    }
+    return undefined;
+}
+function upstreamErrorCode(body) {
+    const error = objectProperty(body, "error");
+    const code = objectProperty(error, "code");
+    return typeof code === "string" ? code : undefined;
+}
+function upstreamErrorMessage(body) {
+    const error = objectProperty(body, "error");
+    const message = objectProperty(error, "message");
+    return typeof message === "string" ? message : undefined;
+}
+function resolveCaseTimeoutMs(execution, suite, healthCase) {
+    const providerDefault = (execution.provider.healthProbe ?? execution.provider.healthMonitor)
+        ?.defaultProbeTimeoutMs;
+    return (execution.requestTimeoutMs ??
+        healthCase.timeoutMs ??
+        suite.timeoutMs ??
+        providerDefault ??
+        DEFAULT_CASE_TIMEOUT_MS);
+}
+function buildSelfTestConnection(execution, operationId, suite) {
+    if (!suite.requiresConnection)
+        return {};
+    const inputs = execution.credentials ?? {};
+    const declaredFields = Object.keys((execution.provider.healthProbe ?? execution.provider.healthMonitor)?.credentialInputs ?? {});
+    for (const field of declaredFields) {
+        if (!inputs[field]) {
+            return { skipReason: `credential_missing:${field}` };
+        }
+    }
+    if (declaredFields.length === 0 && Object.keys(inputs).length === 0) {
+        return { skipReason: "credential_missing:credentials" };
+    }
+    return {
+        connection: {
+            id: `self-test-${execution.requestId}`,
+            mode: "credentials",
+            secrets: { ...inputs },
+            metadata: { purpose: "provider-self-test", operationId },
+            externalRef: `${execution.provider.id}-${operationId}-self-test`,
+        },
+    };
+}
+async function executeSelfTestCase(execution, operationId, suite, healthCase) {
+    const { provider, invoke, sensitiveValues } = execution;
+    const redact = (text) => redactSelfTestText(text, sensitiveValues);
+    const startedAt = new Date().toISOString();
+    const startedAtMs = performance.now();
+    const finish = (partial) => ({
+        operationId,
+        caseName: healthCase.name,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        responseTimeMs: partial.responseTimeMs ?? Math.max(0, Math.round(performance.now() - startedAtMs)),
+        ...partial,
+    });
+    const defaultLabel = redact(healthCase.description ?? healthCase.name);
+    if (healthCase.enabled && healthCase.enabled() === false) {
+        return finish({
+            status: "skipped",
+            label: defaultLabel,
+            skipReason: "disabled",
+        });
+    }
+    const connectionResolution = buildSelfTestConnection(execution, operationId, suite);
+    if ("skipReason" in connectionResolution) {
+        return finish({
+            status: "skipped",
+            label: defaultLabel,
+            skipReason: connectionResolution.skipReason,
+        });
+    }
+    const connection = connectionResolution.connection;
+    const timeoutMs = resolveCaseTimeoutMs(execution, suite, healthCase);
+    try {
+        return await withCaseTimeout(async () => {
+            const resolvedInput = resolveHealthCheckInputDateTokens(healthCase.input);
+            const preparedInput = healthCase.prepareInput
+                ? await healthCase.prepareInput({
+                    providerId: provider.id,
+                    operationId,
+                    input: resolvedInput,
+                    ...(connection ? { connectionId: connection.id } : {}),
+                    gateway: {
+                        execute: async (foreignProviderId, gatewayOperationId, gatewayInput) => {
+                            if (foreignProviderId !== provider.id) {
+                                throw new Error(`Self-test prepareInput may only invoke provider "${provider.id}" operations (requested "${foreignProviderId}").`);
+                            }
+                            const startedGatewayMs = performance.now();
+                            const executed = await invoke({
+                                operationId: gatewayOperationId,
+                                input: gatewayInput,
+                                connection,
+                                requestId: `${execution.requestId}-prepare-${randomUUID()}`,
+                            });
+                            return {
+                                status: executed.status,
+                                duration: performance.now() - startedGatewayMs,
+                                data: executed.data,
+                                meta: executed.meta,
+                            };
+                        },
+                    },
+                })
+                : resolvedInput;
+            const executed = await invoke({
+                operationId,
+                input: preparedInput,
+                connection,
+                requestId: `${execution.requestId}-${randomUUID()}`,
+            });
+            const durationMs = performance.now() - startedAtMs;
+            if (executed.status < 200 || executed.status >= 300) {
+                return finish({
+                    status: "failed",
+                    label: defaultLabel,
+                    httpStatus: executed.status,
+                    error: {
+                        code: upstreamErrorCode(executed.data) ?? "operation_failed",
+                        message: redact(upstreamErrorMessage(executed.data) ??
+                            `Operation invocation failed with status ${executed.status}`),
+                    },
+                });
+            }
+            const assertionContext = {
+                status: executed.status,
+                data: executed.data,
+                durationMs,
+                ...(executed.meta ? { meta: executed.meta } : {}),
+            };
+            let assertionResult;
+            try {
+                assertionResult = await healthCase.assertions(assertionContext);
+            }
+            catch (assertionError) {
+                return finish({
+                    status: "failed",
+                    label: defaultLabel,
+                    httpStatus: executed.status,
+                    assertion: {
+                        passed: false,
+                        message: redact(assertionError instanceof Error ? assertionError.message : String(assertionError)),
+                    },
+                });
+            }
+            const statusValue = objectProperty(assertionResult, "status");
+            const overrideStatus = statusValue === "ok" || statusValue === "degraded" ? statusValue : undefined;
+            const labelValue = objectProperty(assertionResult, "label");
+            const overrideLabel = typeof labelValue === "string" ? redact(labelValue) : undefined;
+            return finish({
+                status: overrideStatus ?? "ok",
+                label: overrideLabel ?? defaultLabel,
+                httpStatus: executed.status,
+                assertion: { passed: true },
+            });
+        }, timeoutMs);
+    }
+    catch (error) {
+        if (error instanceof SelfTestCaseTimeoutError) {
+            return finish({
+                status: "error",
+                label: defaultLabel,
+                error: { code: "self_test_timeout", message: redact(error.message) },
+            });
+        }
+        return finish({
+            status: "error",
+            label: defaultLabel,
+            error: {
+                code: "self_test_execution_error",
+                message: redact(error instanceof Error ? error.message : String(error)),
+            },
+        });
+    }
+}
+function selectCases(provider, request) {
+    const singleCase = request.operationId !== undefined && request.caseName !== undefined;
+    if (singleCase) {
+        const operationId = request.operationId;
+        const operation = provider.operations[operationId];
+        const suite = operation ? healthCheckSuite(operation) : undefined;
+        const healthCase = suite?.cases.find((candidate) => candidate.name === request.caseName);
+        if (!operation || !suite || !healthCase) {
+            return {
+                errorStatus: 422,
+                errorCode: "case_not_found",
+                errorMessage: `Case "${request.caseName}" not found for operation "${operationId}".`,
+            };
+        }
+        if (!isSelfTestReadOnlyOperation(operation)) {
+            return {
+                errorStatus: 403,
+                errorCode: "operation_not_read_only",
+                errorMessage: `Operation "${operationId}" is not classified read-only; self-test refuses to execute it.`,
+            };
+        }
+        return { cases: [{ operationId, operation, suite, healthCase }] };
+    }
+    const operationFilter = request.operations ? new Set(request.operations) : undefined;
+    const caseNameFilter = request.caseNames ? new Set(request.caseNames) : undefined;
+    if (operationFilter) {
+        for (const operationId of operationFilter) {
+            const operation = provider.operations[operationId];
+            if (!operation || !healthCheckSuite(operation)) {
+                return {
+                    errorStatus: 422,
+                    errorCode: "case_not_found",
+                    errorMessage: `Operation "${operationId}" has no declared healthCheck cases.`,
+                };
+            }
+        }
+    }
+    const cases = [];
+    for (const operationId of Object.keys(provider.operations).sort()) {
+        if (operationFilter && !operationFilter.has(operationId))
+            continue;
+        const operation = provider.operations[operationId];
+        const suite = operation ? healthCheckSuite(operation) : undefined;
+        if (!operation || !suite)
+            continue;
+        for (const healthCase of suite.cases) {
+            if (caseNameFilter && !caseNameFilter.has(healthCase.name))
+                continue;
+            cases.push({ operationId, operation, suite, healthCase });
+        }
+    }
+    if (cases.length === 0) {
+        return {
+            errorStatus: 422,
+            errorCode: "case_not_found",
+            errorMessage: "No declared healthCheck cases matched the selection.",
+        };
+    }
+    return { cases };
+}
+function resolveRequestBudgetMs(options) {
+    if (options.requestBudgetMs !== undefined)
+        return options.requestBudgetMs;
+    const env = options.env ?? process.env;
+    const raw = env[PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV];
+    const parsed = raw === undefined ? Number.NaN : Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_SELF_TEST_REQUEST_BUDGET_MS;
+}
+export function resolveSelfTestPort(env = process.env) {
+    const raw = env[PROVIDER_RUNTIME_SELF_TEST_PORT_ENV];
+    const parsed = raw === undefined ? Number.NaN : Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65_535
+        ? parsed
+        : DEFAULT_SELF_TEST_PORT;
+}
+/**
+ * Builds the internal self-test Hono app. This app is served on a SEPARATE
+ * listener (default :3001) that the tenant-facing gateway never dials; when no
+ * master secret is resolvable the self-test route responds 404 (safe default
+ * off) while `GET /healthz` stays available for liveness.
+ */
+export function createSelfTestApp(provider, options) {
+    const app = new Hono();
+    const planDigest = computeSelfTestPlanDigest(provider);
+    const requestBudgetMs = resolveRequestBudgetMs(options);
+    let busy = false;
+    app.notFound((c) => c.json({ error: { code: "not_found", message: "Not found" } }, 404));
+    app.get(SELF_TEST_HEALTHZ_PATH, (c) => c.json({ ok: true }));
+    const handleSelfTest = async (c) => {
+        if (!options.secrets) {
+            return c.json({ error: { code: "not_found", message: "Not found" } }, 404);
+        }
+        const authorized = verifySelfTestAuthorization(c.req.raw.headers.get("authorization") ?? undefined, provider.id, options.secrets);
+        if (!authorized) {
+            return c.json({ error: { code: "unauthorized", message: "Unauthorized" } }, 401);
+        }
+        const rawBody = await c.req.raw
+            .clone()
+            .json()
+            .catch(() => undefined);
+        const schemaVersion = objectProperty(rawBody, "schemaVersion");
+        if (schemaVersion !== SELF_TEST_SCHEMA_VERSION) {
+            return c.json({
+                error: {
+                    code: "unsupported_schema_version",
+                    message: `Unsupported self-test schemaVersion; supported: [${SELF_TEST_SCHEMA_VERSION}].`,
+                    supported: [SELF_TEST_SCHEMA_VERSION],
+                },
+            }, 400);
+        }
+        const parsed = SelfTestRequestSchema.safeParse(rawBody);
+        if (!parsed.success) {
+            return c.json({
+                error: {
+                    code: "invalid_request",
+                    message: "Invalid self-test request body",
+                },
+            }, 400);
+        }
+        const request = parsed.data;
+        if ((request.operationId === undefined) !== (request.caseName === undefined)) {
+            return c.json({
+                error: {
+                    code: "invalid_request",
+                    message: "operationId and caseName must be provided together for single-case requests.",
+                },
+            }, 400);
+        }
+        const selection = selectCases(provider, request);
+        if ("errorStatus" in selection) {
+            return c.json({
+                error: {
+                    code: selection.errorCode,
+                    message: selection.errorMessage,
+                },
+            }, selection.errorStatus);
+        }
+        if (busy) {
+            return c.json({
+                error: {
+                    code: "self_test_busy",
+                    message: "A self-test request is already executing.",
+                },
+                retryAfterMs: SELF_TEST_BUSY_RETRY_AFTER_MS,
+            }, 409);
+        }
+        busy = true;
+        try {
+            const execution = {
+                provider,
+                invoke: options.invoke,
+                requestId: request.requestId,
+                credentials: request.credentials?.inputs,
+                requestTimeoutMs: request.timeoutMs,
+                sensitiveValues: collectSelfTestSensitiveValues(provider, {
+                    env: options.env,
+                    credentialInputs: request.credentials?.inputs,
+                }),
+            };
+            const deadline = performance.now() + requestBudgetMs;
+            const results = [];
+            // 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;
+                }
+                results.push(await executeSelfTestCase(execution, selected.operationId, selected.suite, selected.healthCase));
+            }
+            const singleCase = request.operationId !== undefined && request.caseName !== undefined;
+            const response = {
+                schemaVersion: SELF_TEST_SCHEMA_VERSION,
+                providerId: provider.id,
+                sdkVersion: SDK_VERSION,
+                planDigest,
+                ...(singleCase && results[0] ? { result: results[0] } : {}),
+                results,
+            };
+            return c.json(response, 200);
+        }
+        finally {
+            busy = false;
+        }
+    };
+    app.post(SELF_TEST_PATH, handleSelfTest);
+    // Transitional alias so schedulers can address the endpoint by its short
+    // path; the canonical path is /internal/health/self-test.
+    app.post("/self-test", handleSelfTest);
+    return app;
+}

package/dist/server/serve.d.ts

@@ -59,6 +59,12 @@ export declare function createServerApp(provider: ProviderDefinition, options?:
 export interface ServeOptions extends ProviderServerOptions {
     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(provider: ProviderDefinition, options?: ServeOptions): Promise<void>;
 export {};