@apifuse/provider-sdk 2.2.0-beta.4 → 2.2.0-beta.40

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,77 @@
+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<Exclude<NonNullable<TraceConfig["exporter"]>, "otlp">, true> = {
+	console: true,
+	json: 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}" (OTLP is unsupported for server output); supported exporters are "console", "json", and "none"; falling back to exporter "none".`,
+		);
+	}
+
+	return {
+		...(enabled !== undefined ? { enabled } : {}),
+		...(exporter !== undefined ? { exporter } : {}),
+	};
+}

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/index.ts

@@ -1,16 +1,48 @@
-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 ProviderServerLogEvent,
+	type ProviderServerLogger,
+	type ProviderServerOperationExecutor,
+	type ProviderServerOperationExecutorInput,
+	type ProviderServerOptions,
+	type ProviderServerStatefulForwardEnvelope,
+	type ServeOptions,
+	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,
 	type SelfTestAppOptions,
+	type SelfTestAuthFlowInvoke,
+	type SelfTestAuthFlowRoute,
 	type SelfTestCaseResult,
 	type SelfTestCaseStatus,
 	type SelfTestOperationInvoke,
@@ -18,7 +50,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;
 }