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

package/dist/runtime/stt.js

@@ -1,4 +1,5 @@
 import { ProviderError, TransportError, ValidationError } from "../errors.js";
+import { createTimeoutController, isTimeoutLikeError } from "./timeout.js";
 export const APIFUSE__STT__BACKEND_ENV = "APIFUSE__STT__BACKEND";
 export const APIFUSE__STT__MODEL_ENV = "APIFUSE__STT__MODEL";
 export const CLOUDFLARE_ACCOUNT_ID_ENV = "APIFUSE__CLOUDFLARE__ACCOUNT_ID";
@@ -112,12 +113,6 @@ function warnOrThrowUnsupportedOption(request, message) {
 function normalizeCloudflareLanguage(language) {
     return language?.split("-")[0]?.toLowerCase();
 }
-function isTimeoutLikeError(error) {
-    return (error instanceof Error &&
-        (error.name === "AbortError" ||
-            error.name === "TimeoutError" ||
-            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
-}
 function toSttTransportError(error) {
     if (error instanceof TransportError)
         return error;
@@ -134,12 +129,6 @@ function toSttTransportError(error) {
         cause: error instanceof Error ? error : undefined,
     });
 }
-function createTimeoutController(signalTimeoutMs) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-    timeout.unref?.();
-    return { controller, clear: () => clearTimeout(timeout) };
-}
 function toCloudflareInput(request) {
     const prompt = resolveSttPrompt(request);
     const input = {

package/dist/runtime/timeout.d.ts

@@ -0,0 +1,5 @@
+export declare function isTimeoutLikeError(error: unknown): error is Error;
+export declare function createTimeoutController(signalTimeoutMs: number): {
+    controller: AbortController;
+    clear: () => void;
+};

package/dist/runtime/timeout.js

@@ -0,0 +1,12 @@
+export function isTimeoutLikeError(error) {
+    return (error instanceof Error &&
+        (error.name === "AbortError" ||
+            error.name === "TimeoutError" ||
+            /\b(timed out|timeout|deadline exceeded)\b/i.test(error.message)));
+}
+export function createTimeoutController(signalTimeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+    timeout.unref?.();
+    return { controller, clear: () => clearTimeout(timeout) };
+}

package/dist/runtime/trace-config.d.ts

@@ -0,0 +1,12 @@
+import type { TraceConfig } from "../types.js";
+/** SDK-owned environment variable names for server trace output. */
+export declare const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export declare const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export declare function resolveTraceConfigFromEnv(env?: EnvLike): TraceConfig | undefined;
+export {};

package/dist/runtime/trace-config.js

@@ -0,0 +1,62 @@
+/** SDK-owned environment variable names for server trace output. */
+export const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+const TRACE_EXPORTER_LOOKUP = {
+    console: true,
+    json: true,
+    otlp: true,
+    none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+const emittedWarnings = new Set();
+function warnOnce(key, message) {
+    if (emittedWarnings.has(key))
+        return;
+    emittedWarnings.add(key);
+    console.warn(message);
+}
+function parseEnabled(raw) {
+    if (raw === undefined)
+        return undefined;
+    switch (raw.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+            return true;
+        case "0":
+        case "false":
+        case "no":
+        case "off":
+            return false;
+        default:
+            warnOnce(APIFUSE__TRACE__ENABLED, "[apifuse] Invalid APIFUSE__TRACE__ENABLED; falling back to disabled tracing.");
+            return false;
+    }
+}
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export function resolveTraceConfigFromEnv(env = process.env) {
+    const enabledRaw = env[APIFUSE__TRACE__ENABLED];
+    const exporterRaw = env[APIFUSE__TRACE__EXPORTER];
+    if (enabledRaw === undefined && exporterRaw === undefined) {
+        return undefined;
+    }
+    const enabled = parseEnabled(enabledRaw);
+    const normalizedExporter = exporterRaw?.trim().toLowerCase();
+    const exporter = TRACE_EXPORTERS.has(normalizedExporter)
+        ? normalizedExporter
+        : exporterRaw === undefined
+            ? undefined
+            : "none";
+    if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
+        warnOnce(APIFUSE__TRACE__EXPORTER, `[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}"; supported exporters are "console", "json", "otlp", and "none"; falling back to exporter "none".`);
+    }
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(exporter !== undefined ? { exporter } : {}),
+    };
+}

package/dist/runtime/trace.d.ts

@@ -10,6 +10,11 @@ export interface CreateTraceContextOptions {
     onSpan?: (span: Span) => void;
     exportOptions?: OTLPExportOptions;
     resourceAttributes?: Record<string, string>;
+    /**
+     * Applied to a detached copy of each span immediately before OTLP export; never touches
+     * getSpans() or onSpan. Returning nothing (or throwing) drops that export batch.
+     */
+    sanitizeSpanForExport?: (span: Span) => Span | undefined;
 }
 type SpanHookOptions<T> = {
     attributes?: Record<string, unknown>;

package/dist/runtime/trace.js

@@ -52,6 +52,17 @@ function insertCompletedSpan(completed, entry, maxSpans) {
         completed.splice(0, completed.length - maxSpans);
     }
 }
+/** Hands the hook a copy whose attributes are detached from the recorded span; a hook that returns nothing fails closed. */
+function prepareSpanForExport(span, sanitize) {
+    const copy = { ...span, attributes: { ...span.attributes } };
+    if (!sanitize)
+        return copy;
+    const sanitized = sanitize(copy);
+    if (!sanitized || typeof sanitized !== "object") {
+        throw new Error("sanitizeSpanForExport returned no span");
+    }
+    return sanitized;
+}
 export function getTraceRecorder(trace) {
     return trace[TRACE_RECORDER] ?? null;
 }
@@ -60,14 +71,40 @@ export function createTraceContext(options = {}) {
     const completed = [];
     const activeSpanStorage = new AsyncLocalStorage();
     let sequence = 0;
-    let traceContext;
+    // Export configuration (which can carry collector credentials) stays in this closure;
+    // the context object handed to provider code never exposes it.
+    const exportOptions = options.exportOptions;
+    const exportResourceAttributes = options.resourceAttributes
+        ? { ...options.resourceAttributes }
+        : undefined;
+    // One trace id per context so every export batch of this request shares it and
+    // two processes can never mint the same id.
+    const exportTraceId = crypto.randomUUID().replace(/-/g, "");
+    let exportScheduled = false;
+    // One pending batch per context: roots completing before the flush share it, and a span is
+    // handed to the exporter exactly once, so later roots never re-send earlier spans.
     const scheduleExport = () => {
-        if (!traceContext._exportOptions) {
+        if (!exportOptions || exportScheduled) {
             return;
         }
-        const spans = completed.map((entry) => ({ ...entry.span }));
+        exportScheduled = true;
         setImmediate(() => {
-            void exportSpansOTLP(spans, traceContext._exportOptions, traceContext._resourceAttributes);
+            exportScheduled = false;
+            const pending = completed.filter((entry) => !entry.exported);
+            for (const entry of pending)
+                entry.exported = true;
+            if (pending.length === 0)
+                return;
+            // Sanitization runs off the request path; a faulty sanitizer drops the batch, never the request.
+            let spans;
+            try {
+                spans = pending.map((entry) => prepareSpanForExport(entry.span, options.sanitizeSpanForExport));
+            }
+            catch {
+                console.warn("[apifuse] OTLP export skipped; span sanitization failed.");
+                return;
+            }
+            void exportSpansOTLP(spans, exportOptions, exportResourceAttributes, exportTraceId);
         });
     };
     const recorder = {
@@ -101,7 +138,7 @@ export function createTraceContext(options = {}) {
                     ...(error ? { error } : {}),
                     ...(pendingSpan.parentId ? { parentId: pendingSpan.parentId } : {}),
                 };
-                insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span }, maxSpans);
+                insertCompletedSpan(completed, { sequence: pendingSpan.sequence, span, exported: false }, maxSpans);
                 options.onSpan?.(span);
                 if (!pendingSpan.parentId) {
                     scheduleExport();
@@ -123,17 +160,13 @@ export function createTraceContext(options = {}) {
             });
         },
     };
-    traceContext = {
+    const traceContext = {
         span(name, fn) {
             return recorder.runSpan(name, fn);
         },
         getSpans() {
             return completed.map((entry) => ({ ...entry.span }));
         },
-        ...(options.exportOptions ? { _exportOptions: options.exportOptions } : {}),
-        ...(options.resourceAttributes
-            ? { _resourceAttributes: { ...options.resourceAttributes } }
-            : {}),
         [TRACE_RECORDER]: recorder,
     };
     return traceContext;

package/dist/serve.d.ts

@@ -1 +1 @@
-export { createServerApp, type ServeOptions, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, type ServeOptions, serve, } from "./server/serve.js";

package/dist/serve.js

@@ -1 +1 @@
-export { createServerApp, serve } from "./server/serve.js";
+export { createServerApp, createServerAppAsync, serve, } from "./server/serve.js";

package/dist/server/error-observability.d.ts

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/error-observability.js

@@ -0,0 +1 @@
+export { safeProviderErrorObservability } from "../error-observability.js";

package/dist/server/index.d.ts

@@ -1,6 +1,9 @@
-export { createServerApp, type ServeOptions, serve } from "./serve.js";
+export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
+export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, type SelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export type { AuthFlowRequest, AuthFlowResponse, AuthFlowSuccessResponse, ConnectionMode, OperationConnection, OperationErrorResponse, OperationRequest, OperationResponse, OperationSuccessResponse, } from "./types.js";

package/dist/server/index.js

@@ -1,6 +1,6 @@
-export { createServerApp, serve } from "./serve.js";
+export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, SelfTestRequestSchema, } from "./self-test.js";
-export { resolveHealthCheckInputDateTokens } from "./self-test-input-tokens.js";
+export { resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";
 export { collectSelfTestSensitiveValues, redactSelfTestText, SELF_TEST_MAX_TEXT_LENGTH, SELF_TEST_REDACTED_PLACEHOLDER, } from "./self-test-redaction.js";
 export { DEFAULT_SELF_TEST_PORT, deriveSelfTestToken, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_ENV, PROVIDER_RUNTIME_SELF_TEST_MASTER_SECRET_PREVIOUS_ENV, PROVIDER_RUNTIME_SELF_TEST_PORT_ENV, resolveSelfTestMasterSecrets, verifySelfTestAuthorization, } from "./self-test-token.js";
 export { AuthFlowRequestSchema, AuthFlowSuccessResponseSchema, ConnectionModeSchema, ErrorEnvelopeSchema, OperationConnectionSchema, OperationErrorResponseSchema, OperationRequestSchema, OperationSuccessResponseSchema, } from "./types.js";

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.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,7 @@ export type SelfTestAuthFlowInvoke = (args: {
     externalRef?: string;
     input?: Record<string, unknown>;
     context?: Record<string, unknown>;
+    signal?: AbortSignal;
 }) => Promise<{
     status: number;
     body: unknown;
@@ -112,6 +123,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 +134,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. */