@apifuse/provider-sdk 2.2.0-beta.53 → 2.2.0-beta.55

package/src/runtime/auth-flow.ts

@@ -13,6 +13,7 @@ import type {
 import { createUnsupportedOcrClient } from "./ocr.js";
 import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
+import { createTraceContext } from "./trace.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -66,6 +67,7 @@ export function createFlowContext(options: {
 	initialContext?: Record<string, unknown>;
 	ocr?: OcrContext;
 	stt?: SttContext;
+	trace?: FlowContext["trace"];
 }): FlowContext {
 	return {
 		flowId: options.flowId,
@@ -73,6 +75,7 @@ export function createFlowContext(options: {
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,
 		providerId: options.providerId,
+		trace: options.trace ?? createTraceContext(),
 		http: options.http,
 		state: options.state,
 		stealth: options.stealth,

package/src/runtime/trace.ts

@@ -21,6 +21,8 @@ export interface CreateTraceContextOptions {
 	onSpan?: (span: Span) => void;
 	exportOptions?: OTLPExportOptions;
 	resourceAttributes?: Record<string, string>;
+	/** W3C-compatible 32-character lowercase hexadecimal trace id used for export. */
+	traceId?: 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.
@@ -55,11 +57,33 @@ export interface TraceRecorder {
 }
 
 export const TRACE_RECORDER = Symbol.for("@apifuse/provider-sdk/runtime/trace-recorder");
+const TRACE_EXPORT_METADATA = Symbol.for(
+	"@apifuse/provider-sdk/runtime/trace-export-metadata",
+);
+
+type TraceExportMetadata = {
+	update(input: { traceId?: string; resourceAttributes?: Record<string, string> }): void;
+};
 
 type InternalTraceContext = TraceContext & {
 	[TRACE_RECORDER]: TraceRecorder;
+	[TRACE_EXPORT_METADATA]: TraceExportMetadata;
 };
 
+function assertValidTraceId(traceId: string): void {
+	if (!/^[0-9a-f]{32}$/.test(traceId) || /^0{32}$/.test(traceId)) {
+		throw new TypeError("traceId must be 32 lowercase hexadecimal characters and non-zero");
+	}
+}
+
+/** Updates request metadata before its pending root span completes and exports. */
+export function updateTraceContextExportMetadata(
+	trace: BaseTraceContext,
+	input: { traceId?: string; resourceAttributes?: Record<string, string> },
+): void {
+	(trace as Partial<InternalTraceContext>)[TRACE_EXPORT_METADATA]?.update(input);
+}
+
 function buildOTLPExportOptions(config?: TraceConfig): OTLPExportOptions | undefined {
 	if (config?.exporter !== "otlp") {
 		return undefined;
@@ -148,6 +172,7 @@ export function getTraceRecorder(trace: BaseTraceContext): TraceRecorder | null
 }
 
 export function createTraceContext(options: CreateTraceContextOptions = {}): TraceContext {
+	if (options.traceId !== undefined) assertValidTraceId(options.traceId);
 	const maxSpans = options.maxSpans ?? 1000;
 	const completed: CompletedSpanEntry[] = [];
 	const activeSpanStorage = new AsyncLocalStorage<PendingSpan | undefined>();
@@ -160,7 +185,7 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 		: 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 exportTraceId = options.traceId ?? crypto.randomUUID().replace(/-/g, "");
 	let exportScheduled = false;
 
 	// One pending batch per context: roots completing before the flush share it, and a span is
@@ -265,6 +290,17 @@ export function createTraceContext(options: CreateTraceContextOptions = {}): Tra
 			return completed.map((entry) => ({ ...entry.span }));
 		},
 		[TRACE_RECORDER]: recorder,
+		[TRACE_EXPORT_METADATA]: {
+			update(input) {
+				if (input.traceId !== undefined) {
+					assertValidTraceId(input.traceId);
+					exportTraceId = input.traceId;
+				}
+				if (input.resourceAttributes !== undefined && exportResourceAttributes) {
+					Object.assign(exportResourceAttributes, input.resourceAttributes);
+				}
+			},
+		},
 	};
 
 	return traceContext;