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

package/dist/server/runtime-diagnostics.js

@@ -0,0 +1,360 @@
+import { readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { SDK_VERSION } from "./sdk-version.js";
+/**
+ * Internal runtime diagnostics route on the provider's primary listener, next
+ * to `/health` and `/readyz`. It answers one JSON report that tells an idle
+ * process that still burns CPU apart from a busy one without `exec`: process
+ * CPU sampled over a short window, memory, the Node event-loop and
+ * active-resource APIs, and on Linux the per-thread CPU and file-descriptor
+ * picture from `/proc/self`.
+ *
+ * Read-only and secret-free. It shares the boundary of `/health` and `/readyz`:
+ * the generated provider NetworkPolicy admits only the gateway on this port and
+ * the gateway dials canonical operation paths only, so a tenant cannot reach
+ * it; operators use `kubectl port-forward`.
+ */
+export const RUNTIME_DIAGNOSTICS_ROUTE = "/__apifuse/diagnostics/runtime";
+export const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION = 1;
+/** Query parameter naming the sampling window; clamped, never rejected. */
+export const RUNTIME_DIAGNOSTICS_WINDOW_QUERY = "windowMs";
+export const DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS = 250;
+export const MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS = 50;
+export const MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS = 5_000;
+/**
+ * Linux USER_HZ. The unit of `utime`/`stime` in `/proc` stat files is an ABI
+ * constant (100 Hz) independent of the kernel's CONFIG_HZ.
+ */
+export const PROCFS_CLOCK_TICKS_PER_SECOND = 100;
+export const DEFAULT_PROCFS_SELF_ROOT = "/proc/self";
+const defaultClock = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export function normalizeRuntimeDiagnosticsWindowMs(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS;
+    return Math.min(MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, Math.max(MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, Math.trunc(value)));
+}
+/** Parses the `windowMs` query value; anything unparsable falls back to the default. */
+export function resolveRuntimeDiagnosticsWindowMs(raw) {
+    if (raw === undefined || raw === null || raw.trim() === "") {
+        return DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return normalizeRuntimeDiagnosticsWindowMs(Number.isNaN(parsed) ? undefined : parsed);
+}
+export async function collectRuntimeDiagnostics(input) {
+    const clock = input.clock ?? defaultClock;
+    const procfsRoot = input.procfsRoot ?? DEFAULT_PROCFS_SELF_ROOT;
+    const requestedMs = normalizeRuntimeDiagnosticsWindowMs(input.windowMs);
+    // Two nested brackets. The procfs scans are synchronous work on the main
+    // thread, so the process-level CPU bracket starts after the first scan and
+    // closes before the second one: the scans' own CPU never lands inside it.
+    // The thread bracket encloses the scans and divides their tick deltas by
+    // its own elapsed time, so the scan cost is attributed over the interval it
+    // actually spans instead of inflating a short window.
+    const threadsStartedAt = clock.now();
+    const threadsStart = sampleThreads(procfsRoot);
+    const cpuStart = process.cpuUsage();
+    const eventLoopStart = sampleEventLoopUtilization();
+    const startedAt = clock.now();
+    await clock.sleep(requestedMs);
+    const observedMs = Math.max(0, clock.now() - startedAt);
+    const cpuWindow = process.cpuUsage(cpuStart);
+    const eventLoopEnd = sampleEventLoopUtilization();
+    const threadsEnd = sampleThreads(procfsRoot);
+    const threadsObservedMs = Math.max(0, clock.now() - threadsStartedAt);
+    const fileDescriptors = sampleFileDescriptors(procfsRoot);
+    const cpuLifetime = process.cpuUsage();
+    const uptimeSeconds = process.uptime();
+    const sampledAt = new Date().toISOString();
+    const memory = process.memoryUsage();
+    const activeResources = sampleActiveResources();
+    return {
+        schemaVersion: RUNTIME_DIAGNOSTICS_SCHEMA_VERSION,
+        provider: { id: input.provider.id, version: input.provider.version },
+        sdkVersion: SDK_VERSION,
+        runtime: {
+            bunVersion: process.versions.bun ?? null,
+            nodeCompatVersion: process.versions.node,
+            platform: process.platform,
+            arch: process.arch,
+            pid: process.pid,
+        },
+        sampledAt,
+        uptimeSeconds,
+        window: { requestedMs, observedMs },
+        cpu: {
+            lifetime: {
+                userMicros: cpuLifetime.user,
+                systemMicros: cpuLifetime.system,
+                averageCores: coresFromMicros(cpuLifetime.user + cpuLifetime.system, uptimeSeconds * 1000),
+            },
+            window: {
+                userMicros: cpuWindow.user,
+                systemMicros: cpuWindow.system,
+                userCores: coresFromMicros(cpuWindow.user, observedMs),
+                systemCores: coresFromMicros(cpuWindow.system, observedMs),
+                totalCores: coresFromMicros(cpuWindow.user + cpuWindow.system, observedMs),
+            },
+        },
+        memory: {
+            rss: memory.rss,
+            heapTotal: memory.heapTotal,
+            heapUsed: memory.heapUsed,
+            external: memory.external,
+            arrayBuffers: memory.arrayBuffers,
+        },
+        eventLoop: {
+            reported: eventLoopEnd.idle + eventLoopEnd.active > 0,
+            lifetime: eventLoopEnd,
+            window: eventLoopUtilizationDelta(eventLoopEnd, eventLoopStart),
+        },
+        activeResources,
+        procfs: threadsEnd === null || fileDescriptors === null
+            ? null
+            : {
+                clockTicksPerSecond: PROCFS_CLOCK_TICKS_PER_SECOND,
+                observedMs: threadsObservedMs,
+                threads: summarizeThreads(threadsStart, threadsEnd, threadsObservedMs),
+                fileDescriptors,
+            },
+    };
+}
+function coresFromMicros(micros, elapsedMs) {
+    if (!(elapsedMs > 0))
+        return 0;
+    return micros / 1000 / elapsedMs;
+}
+function sampleEventLoopUtilization() {
+    const eventLoopUtilization = performance.eventLoopUtilization;
+    if (typeof eventLoopUtilization !== "function")
+        return { idle: 0, active: 0, utilization: 0 };
+    try {
+        const sample = eventLoopUtilization.call(performance);
+        return {
+            idle: numberProperty(sample, "idle"),
+            active: numberProperty(sample, "active"),
+            utilization: numberProperty(sample, "utilization"),
+        };
+    }
+    catch {
+        return { idle: 0, active: 0, utilization: 0 };
+    }
+}
+function eventLoopUtilizationDelta(end, start) {
+    const idle = Math.max(0, end.idle - start.idle);
+    const active = Math.max(0, end.active - start.active);
+    const total = idle + active;
+    return { idle, active, utilization: total > 0 ? active / total : 0 };
+}
+function sampleActiveResources() {
+    const getActiveResourcesInfo = process.getActiveResourcesInfo;
+    let types = [];
+    if (typeof getActiveResourcesInfo === "function") {
+        try {
+            const listed = getActiveResourcesInfo.call(process);
+            if (Array.isArray(listed)) {
+                types = listed.filter((entry) => typeof entry === "string");
+            }
+        }
+        catch {
+            types = [];
+        }
+    }
+    const byType = {};
+    for (const type of types)
+        byType[type] = (byType[type] ?? 0) + 1;
+    return { reported: types.length > 0, total: types.length, byType };
+}
+function numberProperty(value, key) {
+    if (value === null || typeof value !== "object")
+        return 0;
+    const candidate = value[key];
+    return typeof candidate === "number" && Number.isFinite(candidate) ? candidate : 0;
+}
+function sampleThreads(root) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, "task"));
+    }
+    catch {
+        return null;
+    }
+    const samples = new Map();
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const sample = sampleThread(join(root, "task", entry), Number.parseInt(entry, 10));
+        if (sample)
+            samples.set(sample.tid, sample);
+    }
+    return samples;
+}
+function sampleThread(taskDir, tid) {
+    let stat;
+    try {
+        stat = readFileSync(join(taskDir, "stat"), "utf8");
+    }
+    catch {
+        // The thread exited between the directory listing and this read.
+        return null;
+    }
+    const open = stat.indexOf("(");
+    const close = stat.lastIndexOf(")");
+    if (open < 0 || close < open)
+        return null;
+    const fields = stat
+        .slice(close + 2)
+        .trimEnd()
+        .split(" ");
+    const userTicks = Number.parseInt(fields[11] ?? "", 10);
+    const systemTicks = Number.parseInt(fields[12] ?? "", 10);
+    if (!Number.isFinite(userTicks) || !Number.isFinite(systemTicks))
+        return null;
+    const switches = readContextSwitches(join(taskDir, "status"));
+    return {
+        tid,
+        name: stat.slice(open + 1, close),
+        state: fields[0] ?? "?",
+        userTicks,
+        systemTicks,
+        voluntary: switches.voluntary,
+        nonvoluntary: switches.nonvoluntary,
+        waitChannel: readWaitChannel(join(taskDir, "wchan")),
+    };
+}
+function readContextSwitches(statusPath) {
+    let voluntary = 0;
+    let nonvoluntary = 0;
+    let status;
+    try {
+        status = readFileSync(statusPath, "utf8");
+    }
+    catch {
+        return { voluntary, nonvoluntary };
+    }
+    for (const line of status.split("\n")) {
+        const separator = line.indexOf(":");
+        if (separator < 0)
+            continue;
+        const key = line.slice(0, separator);
+        if (key !== "voluntary_ctxt_switches" && key !== "nonvoluntary_ctxt_switches")
+            continue;
+        const parsed = Number.parseInt(line.slice(separator + 1).trim(), 10);
+        if (!Number.isFinite(parsed))
+            continue;
+        if (key === "voluntary_ctxt_switches")
+            voluntary = parsed;
+        else
+            nonvoluntary = parsed;
+    }
+    return { voluntary, nonvoluntary };
+}
+function readWaitChannel(wchanPath) {
+    try {
+        const value = readFileSync(wchanPath, "utf8").trim();
+        return value === "" ? null : value;
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeThreads(start, end, observedMs) {
+    const byName = {};
+    const items = [];
+    for (const sample of end.values()) {
+        byName[sample.name] = (byName[sample.name] ?? 0) + 1;
+        const baseline = start?.get(sample.tid);
+        let window = null;
+        if (baseline) {
+            const userTicks = Math.max(0, sample.userTicks - baseline.userTicks);
+            const systemTicks = Math.max(0, sample.systemTicks - baseline.systemTicks);
+            window = {
+                userTicks,
+                systemTicks,
+                cores: coresFromTicks(userTicks + systemTicks, observedMs),
+                contextSwitches: {
+                    voluntary: Math.max(0, sample.voluntary - baseline.voluntary),
+                    nonvoluntary: Math.max(0, sample.nonvoluntary - baseline.nonvoluntary),
+                },
+            };
+        }
+        items.push({
+            tid: sample.tid,
+            name: sample.name,
+            state: sample.state,
+            waitChannel: sample.waitChannel,
+            lifetime: { userTicks: sample.userTicks, systemTicks: sample.systemTicks },
+            window,
+        });
+    }
+    items.sort(compareThreads);
+    return { total: items.length, byName, items };
+}
+function coresFromTicks(ticks, elapsedMs) {
+    if (!(elapsedMs > 0))
+        return 0;
+    return ((ticks / PROCFS_CLOCK_TICKS_PER_SECOND) * 1000) / elapsedMs;
+}
+function compareThreads(left, right) {
+    const leftCores = left.window?.cores ?? -1;
+    const rightCores = right.window?.cores ?? -1;
+    if (leftCores !== rightCores)
+        return rightCores - leftCores;
+    const leftLifetime = left.lifetime.userTicks + left.lifetime.systemTicks;
+    const rightLifetime = right.lifetime.userTicks + right.lifetime.systemTicks;
+    if (leftLifetime !== rightLifetime)
+        return rightLifetime - leftLifetime;
+    return left.tid - right.tid;
+}
+function sampleFileDescriptors(root) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, "fd"));
+    }
+    catch {
+        return null;
+    }
+    const byKind = {
+        socket: 0,
+        eventpoll: 0,
+        timerfd: 0,
+        eventfd: 0,
+        pipe: 0,
+        file: 0,
+        other: 0,
+    };
+    let total = 0;
+    for (const entry of entries) {
+        let target;
+        try {
+            target = readlinkSync(join(root, "fd", entry));
+        }
+        catch {
+            // Closed between the listing and the readlink (the listing's own
+            // directory handle always lands here).
+            continue;
+        }
+        byKind[classifyFileDescriptor(target)] += 1;
+        total += 1;
+    }
+    return { total, byKind };
+}
+function classifyFileDescriptor(target) {
+    if (target.startsWith("socket:"))
+        return "socket";
+    if (target === "anon_inode:[eventpoll]")
+        return "eventpoll";
+    if (target === "anon_inode:[timerfd]")
+        return "timerfd";
+    if (target === "anon_inode:[eventfd]")
+        return "eventfd";
+    if (target.startsWith("pipe:"))
+        return "pipe";
+    if (target.startsWith("/"))
+        return "file";
+    return "other";
+}

package/dist/server/sdk-version.d.ts

@@ -0,0 +1,3 @@
+/** Published @apifuse/provider-sdk version, read from the package manifest; "unknown" when unreadable. */
+export declare function resolveSdkVersion(): string;
+export declare const SDK_VERSION: string;

package/dist/server/sdk-version.js

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+/** Published @apifuse/provider-sdk version, read from the package manifest; "unknown" when unreadable. */
+export 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";
+}
+export const SDK_VERSION = resolveSdkVersion();

package/dist/server/self-test-input-tokens.d.ts

@@ -1 +1,2 @@
-export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date): unknown;
+export type InputDateTokenCalendar = "KST" | "UTC";
+export declare function resolveHealthCheckInputDateTokens(value: unknown, now?: Date, calendar?: InputDateTokenCalendar): unknown;

package/dist/server/self-test-input-tokens.js

@@ -1,20 +1,20 @@
 /**
- * Relative-KST date token resolution for health-check case inputs, ported from
- * the monorepo health-monitor (`apps/health-monitor/src/lib/health-check-input.ts`)
- * so provider self-tests resolve durable probe inputs identically.
+ * Relative date-token resolution for health-check case inputs and fixture
+ * requests. The calendar defaults to KST; callers that need UTC must opt in
+ * explicitly so UTC and KST do not silently disagree from 15:00–23:59 UTC.
  *
- * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead, KST).
+ * Supported token: `+<days>d` or `+<days>d:YYYYMMDD` (1..365 days ahead).
  */
-const RELATIVE_KST_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
-function dateFromKstDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD") {
-    const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
-    const date = new Date(Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead));
+const RELATIVE_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
+function dateFromDaysAhead(daysAhead, now = new Date(), format = "YYYY-MM-DD", calendar = "KST") {
+    const calendarNow = new Date(now.getTime() + (calendar === "KST" ? 9 * 60 * 60 * 1000 : 0));
+    const date = new Date(Date.UTC(calendarNow.getUTCFullYear(), calendarNow.getUTCMonth(), calendarNow.getUTCDate() + daysAhead));
     const isoDate = date.toISOString().slice(0, 10);
     return format === "YYYYMMDD" ? isoDate.replace(/-/g, "") : isoDate;
 }
-export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
+export function resolveHealthCheckInputDateTokens(value, now = new Date(), calendar = "KST") {
     if (typeof value === "string") {
-        const relative = value.match(RELATIVE_KST_DATE_TOKEN);
+        const relative = value.match(RELATIVE_DATE_TOKEN);
         if (!relative)
             return value;
         const daysAhead = Number(relative[1]);
@@ -22,16 +22,20 @@ export function resolveHealthCheckInputDateTokens(value, now = new Date()) {
             return value;
         }
         const format = relative[2]?.toUpperCase() === "YYYYMMDD" ? "YYYYMMDD" : "YYYY-MM-DD";
-        return dateFromKstDaysAhead(daysAhead, now, format);
+        return dateFromDaysAhead(daysAhead, now, format, calendar);
     }
     if (Array.isArray(value)) {
-        return value.map((entry) => resolveHealthCheckInputDateTokens(entry, now));
+        const resolved = value.map((entry) => resolveHealthCheckInputDateTokens(entry, now, calendar));
+        return resolved.some((entry, index) => entry !== value[index]) ? resolved : value;
     }
     if (value && typeof value === "object") {
-        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        const resolved = Object.fromEntries(Object.entries(value).map(([key, entry]) => [
             key,
-            resolveHealthCheckInputDateTokens(entry, now),
+            resolveHealthCheckInputDateTokens(entry, now, calendar),
         ]));
+        return Object.entries(resolved).some(([key, entry]) => entry !== Reflect.get(value, key))
+            ? resolved
+            : value;
     }
     return value;
 }

package/dist/server/self-test-redaction.js

@@ -1,4 +1,4 @@
-import { PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, } from "./self-test-token.js";
+import { collectDiagnosticSensitiveValues, SELF_TEST_SENSITIVE_SOURCE_KINDS, } from "./sensitive-values.js";
 export const SELF_TEST_REDACTED_PLACEHOLDER = "[REDACTED]";
 /** Maximum length of any string echoed in a self-test response. */
 export const SELF_TEST_MAX_TEXT_LENGTH = 300;
@@ -16,37 +16,12 @@ const HEADER_SHAPED_SECRETS = [
  * credential inputs.
  */
 export function collectSelfTestSensitiveValues(provider, options = {}) {
-    const env = options.env ?? process.env;
-    const envNames = new Set([
-        PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV,
-        PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV,
-    ]);
-    for (const secret of provider.secrets ?? []) {
-        envNames.add(secret.name);
-    }
-    const healthProbe = provider.healthProbe ?? provider.healthMonitor;
-    for (const name of healthProbe?.requiredSecrets ?? []) {
-        envNames.add(name);
-    }
-    for (const name of Object.values(healthProbe?.credentialInputs ?? {})) {
-        envNames.add(name);
-    }
-    const values = new Set();
-    for (const name of envNames) {
-        const value = env[name];
-        if (typeof value === "string" && value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
-            values.add(value);
-        }
-    }
-    for (const value of Object.values(options.credentialInputs ?? {})) {
-        if (value.length >= MIN_SENSITIVE_VALUE_LENGTH) {
-            values.add(value);
-        }
-    }
-    return [...values];
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return collectDiagnosticSensitiveValues(provider, {
+        ...options,
+        sourceKinds: SELF_TEST_SENSITIVE_SOURCE_KINDS,
+        minimumLength: MIN_SENSITIVE_VALUE_LENGTH,
+        includeResolvedEnvVariants: false,
+    });
 }
 /**
  * Scrubs known secret values and header-shaped credentials from a string and
@@ -58,7 +33,7 @@ export function redactSelfTestText(text, sensitiveValues, maxLength = SELF_TEST_
     for (const value of sensitiveValues) {
         if (value.length < MIN_SENSITIVE_VALUE_LENGTH)
             continue;
-        redacted = redacted.replace(new RegExp(escapeRegExp(value), "g"), SELF_TEST_REDACTED_PLACEHOLDER);
+        redacted = redacted.replaceAll(value, SELF_TEST_REDACTED_PLACEHOLDER);
     }
     for (const pattern of HEADER_SHAPED_SECRETS) {
         redacted = redacted.replace(pattern, (_match, prefix) => `${prefix}${SELF_TEST_REDACTED_PLACEHOLDER}`);

package/dist/server/self-test.d.ts

@@ -51,11 +51,21 @@ export interface SelfTestResponse {
     result?: SelfTestCaseResult;
     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;
@@ -78,6 +88,11 @@ 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;
@@ -112,6 +127,8 @@ 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;
 }
 /**
  * Stable sha256 over the provider's declared health plan (operations, case
@@ -121,9 +138,7 @@ export interface SelfTestAppOptions {
 export declare 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 declare function isSelfTestReadOnlyOperation(operation: OperationDefinition): boolean;
 /** Binds the self-test executor to a tenant app's /v1 pipeline in-process. */