@chidchanun/bcp 0.2.16 → 0.2.17

package/packages/server/src/observability-v3.ts

@@ -0,0 +1,878 @@
+import {
+    AsyncLocalStorage,
+} from "node:async_hooks";
+import {
+    randomBytes,
+    randomUUID,
+} from "node:crypto";
+
+import type {
+    MiddlewareContext,
+    MiddlewareNext,
+    MiddlewarePipelineHandler,
+    MiddlewareRequest,
+} from "./middleware.js";
+
+export type TraceAttributeValue =
+    | string
+    | number
+    | boolean;
+
+export type TraceAttributes =
+    Readonly<Record<string, TraceAttributeValue>>;
+
+export type TraceSpanKind =
+    | "internal"
+    | "server"
+    | "client"
+    | "producer"
+    | "consumer";
+
+export type TraceSpanStatus =
+    | "unset"
+    | "ok"
+    | "error";
+
+export interface TraceContext {
+    traceId: string;
+    spanId: string;
+    traceFlags: string;
+    correlationId: string;
+    tracestate?: string;
+}
+
+export interface TraceCarrier {
+    traceparent: string;
+    correlationId: string;
+    tracestate?: string;
+}
+
+export interface TraceSpanEvent {
+    name: string;
+    timestamp: number;
+    attributes: Record<string, TraceAttributeValue>;
+}
+
+export interface TraceSpanRecord {
+    name: string;
+    kind: TraceSpanKind;
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    traceFlags: string;
+    correlationId: string;
+    tracestate?: string;
+    serviceName?: string;
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    status: TraceSpanStatus;
+    statusMessage?: string;
+    attributes: Record<string, TraceAttributeValue>;
+    events: TraceSpanEvent[];
+}
+
+export interface TraceSpanExporter {
+    export(span: TraceSpanRecord): void | Promise<void>;
+    shutdown?(): void | Promise<void>;
+}
+
+export interface MemoryTraceSpanExporter
+extends TraceSpanExporter {
+    spans(): TraceSpanRecord[];
+    clear(): void;
+}
+
+export interface TraceIdFactory {
+    traceId(): string;
+    spanId(): string;
+    correlationId(): string;
+}
+
+export interface StartTraceSpanOptions {
+    parent?: TraceContext | null;
+    kind?: TraceSpanKind;
+    attributes?: TraceAttributes;
+    startTime?: number;
+}
+
+export interface TraceSpan {
+    readonly name: string;
+    readonly context: TraceContext;
+    readonly parentSpanId: string | undefined;
+    readonly kind: TraceSpanKind;
+    readonly status: TraceSpanStatus;
+    readonly ended: boolean;
+    setAttribute(name: string, value: TraceAttributeValue): void;
+    addEvent(name: string, attributes?: TraceAttributes): void;
+    setStatus(status: TraceSpanStatus, message?: string): void;
+    end(endTime?: number): Promise<TraceSpanRecord>;
+}
+
+export interface TracerOptions {
+    exporter?: TraceSpanExporter;
+    serviceName?: string;
+    now?: () => number;
+    idFactory?: TraceIdFactory;
+    defaultAttributes?: TraceAttributes;
+}
+
+export interface Tracer {
+    startSpan(name: string, options?: StartTraceSpanOptions): TraceSpan;
+    withSpan<T>(
+        name: string,
+        callback: (span: TraceSpan) => T | Promise<T>,
+        options?: StartTraceSpanOptions
+    ): Promise<T>;
+    currentContext(): TraceContext | undefined;
+    runWithContext<T>(context: TraceContext, callback: () => T): T;
+    shutdown(): Promise<void>;
+}
+
+export interface RequestTracingOptions {
+    spanName?: string | ((request: MiddlewareRequest) => string);
+    includeResponseHeaders?: boolean;
+    attributes?:
+        | TraceAttributes
+        | ((request: MiddlewareRequest) => TraceAttributes);
+}
+
+export interface TraceMetricsRegistryLike {
+    counter(
+        name: string,
+        options?: {
+            help?: string;
+            labelNames?: readonly string[];
+        }
+    ): {
+        inc(value?: number, labels?: TraceAttributes): void;
+    };
+    histogram(
+        name: string,
+        options?: {
+            help?: string;
+            labelNames?: readonly string[];
+            buckets?: readonly number[];
+        }
+    ): {
+        observe(value: number, labels?: TraceAttributes): void;
+    };
+}
+
+export interface TraceMetricsOptions {
+    prefix?: string;
+    includeSpanName?: boolean;
+}
+
+const TRACEPARENT_PATTERN =
+    /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+const traceStorage =
+    new AsyncLocalStorage<TraceContext>();
+
+export function createTracer(
+    options: TracerOptions = {}
+): Tracer {
+    const exporter = options.exporter;
+    const now = options.now ?? Date.now;
+    const idFactory =
+        options.idFactory ?? createDefaultTraceIdFactory();
+    const serviceName =
+        normalizeOptionalText(options.serviceName);
+    const defaultAttributes =
+        normalizeAttributes(options.defaultAttributes);
+
+    function startSpan(
+        rawName: string,
+        spanOptions: StartTraceSpanOptions = {}
+    ): TraceSpan {
+        const name = normalizeName(rawName, "span name");
+        const parent =
+            spanOptions.parent === undefined
+                ? currentTraceContext()
+                : spanOptions.parent ?? undefined;
+        const traceId = parent?.traceId ??
+            normalizeTraceId(idFactory.traceId());
+        const spanId =
+            normalizeSpanId(idFactory.spanId());
+        const traceFlags = parent?.traceFlags ?? "01";
+        const correlationId = parent?.correlationId ??
+            normalizeCorrelationId(idFactory.correlationId());
+        const tracestate = parent?.tracestate;
+        const context: TraceContext = {
+            traceId,
+            spanId,
+            traceFlags,
+            correlationId,
+            ...(tracestate ? { tracestate } : {}),
+        };
+        const attributes = {
+            ...defaultAttributes,
+            ...normalizeAttributes(spanOptions.attributes),
+        };
+        const events: TraceSpanEvent[] = [];
+        const startedAt = spanOptions.startTime ?? now();
+        assertTimestamp(startedAt, "span startTime");
+        const kind = spanOptions.kind ?? "internal";
+        let status: TraceSpanStatus = "unset";
+        let statusMessage: string | undefined;
+        let ended = false;
+        let completed: TraceSpanRecord | undefined;
+
+        const span: TraceSpan = {
+            name,
+            context,
+            parentSpanId: parent?.spanId,
+            kind,
+            get status(): TraceSpanStatus {
+                return status;
+            },
+            get ended(): boolean {
+                return ended;
+            },
+            setAttribute(
+                rawAttributeName: string,
+                value: TraceAttributeValue
+            ): void {
+                assertNotEnded();
+                attributes[
+                    normalizeName(rawAttributeName, "attribute name")
+                ] = normalizeAttributeValue(value);
+            },
+            addEvent(
+                rawEventName: string,
+                eventAttributes: TraceAttributes = {}
+            ): void {
+                assertNotEnded();
+                const timestamp = now();
+                assertTimestamp(timestamp, "event timestamp");
+                events.push({
+                    name: normalizeName(rawEventName, "event name"),
+                    timestamp,
+                    attributes: normalizeAttributes(eventAttributes),
+                });
+            },
+            setStatus(
+                nextStatus: TraceSpanStatus,
+                message?: string
+            ): void {
+                assertNotEnded();
+                status = normalizeStatus(nextStatus);
+                statusMessage = normalizeOptionalText(message);
+            },
+            async end(endTime?: number): Promise<TraceSpanRecord> {
+                if (completed) {
+                    return cloneTraceSpanRecord(completed);
+                }
+                const endedAt = endTime ?? now();
+                assertTimestamp(endedAt, "span endTime");
+                if (endedAt < startedAt) {
+                    throw new RangeError(
+                        "BCP Observability: span endTime cannot be earlier than startTime."
+                    );
+                }
+                ended = true;
+                completed = {
+                    name,
+                    kind,
+                    traceId,
+                    spanId,
+                    ...(parent?.spanId
+                        ? { parentSpanId: parent.spanId }
+                        : {}),
+                    traceFlags,
+                    correlationId,
+                    ...(tracestate ? { tracestate } : {}),
+                    ...(serviceName ? { serviceName } : {}),
+                    startedAt,
+                    endedAt,
+                    durationMs: endedAt - startedAt,
+                    status,
+                    ...(statusMessage ? { statusMessage } : {}),
+                    attributes: { ...attributes },
+                    events: events.map(cloneTraceEvent),
+                };
+                try {
+                    await exporter?.export(
+                        cloneTraceSpanRecord(completed)
+                    );
+                } catch {
+                    // Exporters must not break application execution.
+                }
+                return cloneTraceSpanRecord(completed);
+            },
+        };
+
+        return span;
+
+        function assertNotEnded(): void {
+            if (ended) {
+                throw new Error(
+                    `BCP Observability: span "${name}" has already ended.`
+                );
+            }
+        }
+    }
+
+    async function withSpan<T>(
+        name: string,
+        callback: (span: TraceSpan) => T | Promise<T>,
+        spanOptions: StartTraceSpanOptions = {}
+    ): Promise<T> {
+        if (typeof callback !== "function") {
+            throw new TypeError(
+                "BCP Observability: span callback must be a function."
+            );
+        }
+        const span = startSpan(name, spanOptions);
+        return await traceStorage.run(
+            span.context,
+            async (): Promise<T> => {
+                try {
+                    const value = await callback(span);
+                    if (
+                        !span.ended &&
+                        span.status === "unset"
+                    ) {
+                        span.setStatus("ok");
+                    }
+                    return value;
+                } catch (error) {
+                    if (!span.ended) {
+                        span.setStatus(
+                            "error",
+                            error instanceof Error
+                                ? error.message
+                                : "Span callback failed."
+                        );
+                        span.addEvent("exception", {
+                            "exception.type":
+                                error instanceof Error
+                                    ? error.name
+                                    : typeof error,
+                            "exception.message":
+                                error instanceof Error
+                                    ? error.message
+                                    : String(error),
+                        });
+                    }
+                    throw error;
+                } finally {
+                    if (!span.ended) {
+                        await span.end();
+                    }
+                }
+            }
+        );
+    }
+
+    const tracer: Tracer = {
+        startSpan,
+        withSpan,
+        currentContext(): TraceContext | undefined {
+            return currentTraceContext();
+        },
+        runWithContext<T>(
+            context: TraceContext,
+            callback: () => T
+        ): T {
+            return runWithTraceContext(context, callback);
+        },
+        async shutdown(): Promise<void> {
+            await exporter?.shutdown?.();
+        },
+    };
+
+    return tracer;
+}
+
+export function currentTraceContext(): TraceContext | undefined {
+    const current = traceStorage.getStore();
+    return current ? cloneTraceContext(current) : undefined;
+}
+
+export function runWithTraceContext<T>(
+    context: TraceContext,
+    callback: () => T
+): T {
+    if (typeof callback !== "function") {
+        throw new TypeError(
+            "BCP Observability: trace context callback must be a function."
+        );
+    }
+    return traceStorage.run(
+        normalizeTraceContext(context),
+        callback
+    );
+}
+
+export function createTraceCarrier(
+    context: TraceContext | undefined = currentTraceContext()
+): TraceCarrier | undefined {
+    if (!context) {
+        return undefined;
+    }
+    const normalized = normalizeTraceContext(context);
+    return {
+        traceparent: formatTraceparent(normalized),
+        correlationId: normalized.correlationId,
+        ...(normalized.tracestate
+            ? { tracestate: normalized.tracestate }
+            : {}),
+    };
+}
+
+export function runWithTraceCarrier<T>(
+    carrier: TraceCarrier | undefined | null,
+    callback: () => T
+): T {
+    if (!carrier) {
+        return callback();
+    }
+    const context = extractTraceCarrier(carrier);
+    return context
+        ? runWithTraceContext(context, callback)
+        : callback();
+}
+
+export function extractTraceCarrier(
+    carrier:
+        | TraceCarrier
+        | Readonly<Record<string, string | undefined>>
+): TraceContext | null {
+    const traceparent = carrier.traceparent;
+    if (!traceparent) {
+        return null;
+    }
+    const parsed = parseTraceparent(traceparent);
+    if (!parsed) {
+        return null;
+    }
+    const correlationId =
+        typeof carrier.correlationId === "string"
+            ? carrier.correlationId
+            : parsed.traceId;
+    const tracestate =
+        typeof carrier.tracestate === "string"
+            ? normalizeOptionalText(carrier.tracestate)
+            : undefined;
+    return {
+        ...parsed,
+        correlationId: normalizeCorrelationId(correlationId),
+        ...(tracestate ? { tracestate } : {}),
+    };
+}
+
+export function injectTraceHeaders(
+    headers: Headers,
+    context: TraceContext | undefined = currentTraceContext()
+): Headers {
+    if (!(headers instanceof Headers)) {
+        throw new TypeError(
+            "BCP Observability: injectTraceHeaders() requires Headers."
+        );
+    }
+    if (!context) {
+        return headers;
+    }
+    const normalized = normalizeTraceContext(context);
+    headers.set("traceparent", formatTraceparent(normalized));
+    headers.set("x-correlation-id", normalized.correlationId);
+    if (normalized.tracestate) {
+        headers.set("tracestate", normalized.tracestate);
+    } else {
+        headers.delete("tracestate");
+    }
+    return headers;
+}
+
+export function extractTraceHeaders(
+    input: Headers | { readonly headers: Headers }
+): TraceContext | null {
+    const headers =
+        input instanceof Headers
+            ? input
+            : input.headers;
+    if (!(headers instanceof Headers)) {
+        throw new TypeError(
+            "BCP Observability: extractTraceHeaders() requires Headers or a request-like object."
+        );
+    }
+    const parsed = parseTraceparent(headers.get("traceparent"));
+    if (!parsed) {
+        return null;
+    }
+    const correlationId =
+        headers.get("x-correlation-id") ?? parsed.traceId;
+    const tracestate = normalizeOptionalText(
+        headers.get("tracestate") ?? undefined
+    );
+    return {
+        ...parsed,
+        correlationId: normalizeCorrelationId(correlationId),
+        ...(tracestate ? { tracestate } : {}),
+    };
+}
+
+export function formatTraceparent(
+    context: Pick<TraceContext, "traceId" | "spanId" | "traceFlags">
+): string {
+    return [
+        "00",
+        normalizeTraceId(context.traceId),
+        normalizeSpanId(context.spanId),
+        normalizeTraceFlags(context.traceFlags),
+    ].join("-");
+}
+
+export function parseTraceparent(
+    value: string | null | undefined
+): Pick<TraceContext, "traceId" | "spanId" | "traceFlags"> | null {
+    if (!value) {
+        return null;
+    }
+    const match = TRACEPARENT_PATTERN.exec(
+        value.trim().toLowerCase()
+    );
+    if (!match || /^0+$/.test(match[1]) || /^0+$/.test(match[2])) {
+        return null;
+    }
+    return {
+        traceId: match[1],
+        spanId: match[2],
+        traceFlags: match[3],
+    };
+}
+
+export function createRequestTracingMiddleware(
+    tracer: Tracer,
+    options: RequestTracingOptions = {}
+): MiddlewarePipelineHandler {
+    if (!tracer) {
+        throw new TypeError(
+            "BCP Observability: request tracing requires a tracer."
+        );
+    }
+
+    const middleware: MiddlewarePipelineHandler = async (
+        request: MiddlewareRequest,
+        next: MiddlewareNext,
+        _context: MiddlewareContext
+    ): Promise<Response> => {
+        const incoming = extractTraceHeaders(request.headers);
+        const spanName =
+            typeof options.spanName === "function"
+                ? options.spanName(request)
+                : options.spanName ??
+                    `HTTP ${request.method.toUpperCase()}`;
+        const optionAttributes =
+            typeof options.attributes === "function"
+                ? options.attributes(request)
+                : options.attributes ?? {};
+
+        return tracer.withSpan(
+            spanName,
+            async (span: TraceSpan): Promise<Response> => {
+                span.setAttribute(
+                    "http.request.method",
+                    request.method.toUpperCase()
+                );
+                span.setAttribute(
+                    "url.path",
+                    request.nextUrl.pathname
+                );
+                let response: Response;
+                try {
+                    response = await next();
+                    span.setAttribute(
+                        "http.response.status_code",
+                        response.status
+                    );
+                    if (response.status >= 500) {
+                        span.setStatus("error", `HTTP ${response.status}`);
+                    }
+                } catch (error) {
+                    span.setStatus(
+                        "error",
+                        error instanceof Error
+                            ? error.message
+                            : "HTTP request failed."
+                    );
+                    throw error;
+                }
+                return options.includeResponseHeaders === false
+                    ? response
+                    : cloneResponseWithTraceHeaders(
+                        response,
+                        span.context
+                    );
+            },
+            {
+                parent: incoming,
+                kind: "server",
+                attributes: optionAttributes,
+            }
+        );
+    };
+
+    return middleware;
+}
+
+export function createMemoryTraceSpanExporter(): MemoryTraceSpanExporter {
+    const records: TraceSpanRecord[] = [];
+    return {
+        export(span: TraceSpanRecord): void {
+            records.push(cloneTraceSpanRecord(span));
+        },
+        spans(): TraceSpanRecord[] {
+            return records.map(cloneTraceSpanRecord);
+        },
+        clear(): void {
+            records.length = 0;
+        },
+    };
+}
+
+export function createTraceMetricsExporter(
+    registry: TraceMetricsRegistryLike,
+    options: TraceMetricsOptions = {}
+): TraceSpanExporter {
+    const prefix = normalizeMetricPrefix(
+        options.prefix ?? "bcp_trace"
+    );
+    const labelNames = [
+        "kind",
+        "status",
+        ...(options.includeSpanName ? ["span"] : []),
+    ];
+    const spans = registry.counter(
+        `${prefix}_spans_total`,
+        {
+            help: "Completed BCP trace spans.",
+            labelNames,
+        }
+    );
+    const duration = registry.histogram(
+        `${prefix}_span_duration_seconds`,
+        {
+            help: "BCP trace span duration in seconds.",
+            labelNames,
+        }
+    );
+
+    return {
+        export(span: TraceSpanRecord): void {
+            const labels: Record<string, TraceAttributeValue> = {
+                kind: span.kind,
+                status: span.status,
+            };
+            if (options.includeSpanName) {
+                labels.span = span.name;
+            }
+            spans.inc(1, labels);
+            duration.observe(span.durationMs / 1000, labels);
+        },
+    };
+}
+
+export function createCompositeTraceSpanExporter(
+    exporters: readonly TraceSpanExporter[]
+): TraceSpanExporter {
+    const list = [...exporters];
+    return {
+        async export(span: TraceSpanRecord): Promise<void> {
+            for (const exporter of list) {
+                await exporter.export(cloneTraceSpanRecord(span));
+            }
+        },
+        async shutdown(): Promise<void> {
+            for (const exporter of [...list].reverse()) {
+                await exporter.shutdown?.();
+            }
+        },
+    };
+}
+
+export function getTraceLogFields(
+    context: TraceContext | undefined = currentTraceContext()
+): Record<string, string> {
+    if (!context) {
+        return {};
+    }
+    const normalized = normalizeTraceContext(context);
+    return {
+        traceId: normalized.traceId,
+        spanId: normalized.spanId,
+        correlationId: normalized.correlationId,
+    };
+}
+
+function createDefaultTraceIdFactory(): TraceIdFactory {
+    return {
+        traceId(): string {
+            return randomBytes(16).toString("hex");
+        },
+        spanId(): string {
+            return randomBytes(8).toString("hex");
+        },
+        correlationId(): string {
+            return randomUUID();
+        },
+    };
+}
+
+function cloneResponseWithTraceHeaders(
+    response: Response,
+    context: TraceContext
+): Response {
+    const headers = new Headers(response.headers);
+    injectTraceHeaders(headers, context);
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+
+function normalizeTraceContext(context: TraceContext): TraceContext {
+    const tracestate = normalizeOptionalText(context.tracestate);
+    return {
+        traceId: normalizeTraceId(context.traceId),
+        spanId: normalizeSpanId(context.spanId),
+        traceFlags: normalizeTraceFlags(context.traceFlags),
+        correlationId: normalizeCorrelationId(context.correlationId),
+        ...(tracestate ? { tracestate } : {}),
+    };
+}
+
+function cloneTraceContext(context: TraceContext): TraceContext {
+    return { ...context };
+}
+
+function cloneTraceSpanRecord(span: TraceSpanRecord): TraceSpanRecord {
+    return {
+        ...span,
+        attributes: { ...span.attributes },
+        events: span.events.map(cloneTraceEvent),
+    };
+}
+
+function cloneTraceEvent(event: TraceSpanEvent): TraceSpanEvent {
+    return {
+        ...event,
+        attributes: { ...event.attributes },
+    };
+}
+
+function normalizeAttributes(
+    attributes: TraceAttributes | undefined
+): Record<string, TraceAttributeValue> {
+    const normalized: Record<string, TraceAttributeValue> = {};
+    for (const [rawName, value] of Object.entries(attributes ?? {})) {
+        normalized[
+            normalizeName(rawName, "attribute name")
+        ] = normalizeAttributeValue(value);
+    }
+    return normalized;
+}
+
+function normalizeAttributeValue(
+    value: TraceAttributeValue
+): TraceAttributeValue {
+    if (
+        typeof value !== "string" &&
+        typeof value !== "number" &&
+        typeof value !== "boolean"
+    ) {
+        throw new TypeError(
+            "BCP Observability: trace attributes must be string, number or boolean values."
+        );
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new TypeError(
+            "BCP Observability: numeric trace attributes must be finite."
+        );
+    }
+    return value;
+}
+
+function normalizeStatus(status: TraceSpanStatus): TraceSpanStatus {
+    if (status !== "unset" && status !== "ok" && status !== "error") {
+        throw new TypeError(
+            "BCP Observability: invalid span status."
+        );
+    }
+    return status;
+}
+
+function normalizeTraceId(value: string): string {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(normalized) || /^0+$/.test(normalized)) {
+        throw new TypeError(
+            "BCP Observability: traceId must be 32 non-zero hexadecimal characters."
+        );
+    }
+    return normalized;
+}
+
+function normalizeSpanId(value: string): string {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{16}$/.test(normalized) || /^0+$/.test(normalized)) {
+        throw new TypeError(
+            "BCP Observability: spanId must be 16 non-zero hexadecimal characters."
+        );
+    }
+    return normalized;
+}
+
+function normalizeTraceFlags(value: string): string {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{2}$/.test(normalized)) {
+        throw new TypeError(
+            "BCP Observability: traceFlags must be two hexadecimal characters."
+        );
+    }
+    return normalized;
+}
+
+function normalizeCorrelationId(value: string): string {
+    return normalizeName(value, "correlationId");
+}
+
+function normalizeName(value: string, field: string): string {
+    const normalized = String(value ?? "").trim();
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Observability: ${field} must be a non-empty string.`
+        );
+    }
+    return normalized;
+}
+
+function normalizeOptionalText(
+    value: string | undefined
+): string | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized || undefined;
+}
+
+function assertTimestamp(value: number, field: string): void {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Observability: ${field} must be a finite number.`
+        );
+    }
+}
+
+function normalizeMetricPrefix(value: string): string {
+    const normalized = value.trim();
+    if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(normalized)) {
+        throw new TypeError(
+            "BCP Observability: trace metrics prefix contains unsupported characters."
+        );
+    }
+    return normalized;
+}