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

package/src/runtime/stt.ts

@@ -14,6 +14,7 @@ import type {
 	VerificationCodeCandidateSource,
 	VerificationCodeExtractionResult,
 } from "../types.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";
@@ -169,15 +170,6 @@ function normalizeCloudflareLanguage(language: Bcp47Locale | undefined): string
 	return language?.split("-")[0]?.toLowerCase();
 }
 
-function isTimeoutLikeError(error: unknown): error is 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: unknown): TransportError {
 	if (error instanceof TransportError) return error;
 	if (isTimeoutLikeError(error)) {
@@ -194,16 +186,6 @@ function toSttTransportError(error: unknown): TransportError {
 	});
 }
 
-function createTimeoutController(signalTimeoutMs: number): {
-	controller: AbortController;
-	clear: () => void;
-} {
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
-	timeout.unref?.();
-	return { controller, clear: () => clearTimeout(timeout) };
-}
-
 function toCloudflareInput(request: SttTranscribeRequest): Record<string, unknown> {
 	const prompt = resolveSttPrompt(request);
 	const input: Record<string, unknown> = {

package/src/runtime/timeout.ts

@@ -0,0 +1,18 @@
+export function isTimeoutLikeError(error: unknown): error is 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: number): {
+	controller: AbortController;
+	clear: () => void;
+} {
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), signalTimeoutMs);
+	timeout.unref?.();
+	return { controller, clear: () => clearTimeout(timeout) };
+}

package/src/runtime/trace-config.ts

@@ -0,0 +1,78 @@
+import type { TraceConfig } from "../types.js";
+
+/** 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";
+
+type EnvLike = Record<string, string | undefined>;
+
+const TRACE_EXPORTER_LOOKUP: Record<NonNullable<TraceConfig["exporter"]>, true> = {
+	console: true,
+	json: true,
+	otlp: true,
+	none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+
+const emittedWarnings = new Set<string>();
+
+function warnOnce(key: string, message: string): void {
+	if (emittedWarnings.has(key)) return;
+	emittedWarnings.add(key);
+	console.warn(message);
+}
+
+function parseEnabled(raw: string | undefined): boolean | undefined {
+	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: EnvLike = process.env): TraceConfig | undefined {
+	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 as NonNullable<TraceConfig["exporter"]>)
+		? (normalizedExporter as NonNullable<TraceConfig["exporter"]>)
+		: 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/src/runtime/trace.ts

@@ -21,6 +21,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> = {
@@ -41,6 +46,8 @@ type PendingSpan = {
 type CompletedSpanEntry = {
 	sequence: number;
 	span: Span;
+	/** Set once the span has been handed to the exporter so no batch re-sends it. */
+	exported: boolean;
 };
 
 export interface TraceRecorder {
@@ -51,8 +58,6 @@ export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-re
 
 type InternalTraceContext = TraceContext & {
 	[TRACE_RECORDER]: TraceRecorder;
-	_exportOptions?: OTLPExportOptions;
-	_resourceAttributes?: Record<string, string>;
 };
 
 function buildOTLPExportOptions(config?: TraceConfig): OTLPExportOptions | undefined {
@@ -124,6 +129,20 @@ function insertCompletedSpan(
 	}
 }
 
+/** Hands the hook a copy whose attributes are detached from the recorded span; a hook that returns nothing fails closed. */
+function prepareSpanForExport(
+	span: Span,
+	sanitize: CreateTraceContextOptions["sanitizeSpanForExport"],
+): Span {
+	const copy: Span = { ...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: BaseTraceContext): TraceRecorder | null {
 	return (trace as Partial<InternalTraceContext>)[TRACE_RECORDER] ?? null;
 }
@@ -133,20 +152,41 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 	const completed: CompletedSpanEntry[] = [];
 	const activeSpanStorage = new AsyncLocalStorage<PendingSpan | undefined>();
 	let sequence = 0;
-	let traceContext!: InternalTraceContext;
-
+	// 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;
 		}
+		exportScheduled = true;
 
-		const spans = completed.map((entry) => ({ ...entry.span }));
 		setImmediate(() => {
-			void exportSpansOTLP(
-				spans,
-				traceContext._exportOptions as OTLPExportOptions,
-				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: Span[];
+			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);
 		});
 	};
 
@@ -189,7 +229,11 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 					...(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) {
@@ -213,17 +257,13 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 		},
 	};
 
-	traceContext = {
+	const traceContext: InternalTraceContext = {
 		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,
 	};
 

package/src/serve.ts

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

package/src/server/error-observability.ts

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

package/src/server/index.ts

@@ -1,4 +1,33 @@
-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,
@@ -23,7 +52,10 @@ export {
 	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,

package/src/server/self-test-input-tokens.ts

@@ -1,46 +1,61 @@
 /**
- * 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;
+const RELATIVE_DATE_TOKEN = /^\+(\d{1,3})d(?::(YYYYMMDD))?$/i;
 
-function dateFromKstDaysAhead(
+export type InputDateTokenCalendar = "KST" | "UTC";
+
+function dateFromDaysAhead(
 	daysAhead: number,
 	now = new Date(),
 	format: "YYYY-MM-DD" | "YYYYMMDD" = "YYYY-MM-DD",
+	calendar: InputDateTokenCalendar = "KST",
 ): string {
-	const kstNow = new Date(now.getTime() + 9 * 60 * 60 * 1000);
+	const calendarNow = new Date(now.getTime() + (calendar === "KST" ? 9 * 60 * 60 * 1000 : 0));
 	const date = new Date(
-		Date.UTC(kstNow.getUTCFullYear(), kstNow.getUTCMonth(), kstNow.getUTCDate() + daysAhead),
+		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: unknown, now = new Date()): unknown {
+export function resolveHealthCheckInputDateTokens(
+	value: unknown,
+	now = new Date(),
+	calendar: InputDateTokenCalendar = "KST",
+): unknown {
 	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]);
 		if (!Number.isInteger(daysAhead) || daysAhead < 1 || daysAhead > 365) {
 			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(
+		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;
 }