@chidchanun/bcp 0.2.6 → 0.2.7

package/packages/server/src/observability.ts

@@ -0,0 +1,1258 @@
+import type {
+    MiddlewarePipelineHandler,
+} from "./middleware.js";
+
+export type MetricLabelValue =
+    | string
+    | number
+    | boolean;
+
+export type MetricLabels =
+    Readonly<Record<
+        string,
+        MetricLabelValue
+    >>;
+
+export interface MetricDefinitionOptions {
+    help?: string;
+    labelNames?: readonly string[];
+}
+
+export interface HistogramOptions
+extends MetricDefinitionOptions {
+    buckets?: readonly number[];
+}
+
+export interface CounterMetric {
+    readonly name: string;
+    inc(
+        value?: number,
+        labels?: MetricLabels
+    ): void;
+}
+
+export interface GaugeMetric {
+    readonly name: string;
+    set(
+        value: number,
+        labels?: MetricLabels
+    ): void;
+    inc(
+        value?: number,
+        labels?: MetricLabels
+    ): void;
+    dec(
+        value?: number,
+        labels?: MetricLabels
+    ): void;
+}
+
+export interface HistogramMetric {
+    readonly name: string;
+    observe(
+        value: number,
+        labels?: MetricLabels
+    ): void;
+}
+
+export interface MetricsRegistry {
+    counter(
+        name: string,
+        options?: MetricDefinitionOptions
+    ): CounterMetric;
+    gauge(
+        name: string,
+        options?: MetricDefinitionOptions
+    ): GaugeMetric;
+    histogram(
+        name: string,
+        options?: HistogramOptions
+    ): HistogramMetric;
+    metrics(): string;
+    reset(): void;
+}
+
+export interface RequestMetricsOptions {
+    prefix?: string;
+    includeMethod?: boolean;
+    includeStatus?: boolean;
+}
+
+export type HealthCheckResult =
+    | boolean
+    | {
+        ok: boolean;
+        detail?: string;
+    };
+
+export type HealthCheck =
+    () =>
+        | HealthCheckResult
+        | Promise<HealthCheckResult>;
+
+export interface HealthCheckOptions {
+    timeoutMs?: number;
+}
+
+export interface HealthCheckReportItem {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+    detail?: string;
+}
+
+export interface HealthReport {
+    ok: boolean;
+    status: "healthy" | "unhealthy";
+    checkedAt: string;
+    checks: HealthCheckReportItem[];
+}
+
+export interface HealthRegistry {
+    register(
+        name: string,
+        check: HealthCheck,
+        options?: HealthCheckOptions
+    ): () => void;
+    run(): Promise<HealthReport>;
+    response(): Promise<Response>;
+    clear(): void;
+}
+
+interface MetricSeries {
+    labels: Record<string, string>;
+    value: number;
+}
+
+interface HistogramSeries {
+    labels: Record<string, string>;
+    count: number;
+    sum: number;
+    buckets: number[];
+}
+
+interface CounterDefinition {
+    type: "counter";
+    name: string;
+    help: string;
+    labelNames: string[];
+    series: Map<string, MetricSeries>;
+}
+
+interface GaugeDefinition {
+    type: "gauge";
+    name: string;
+    help: string;
+    labelNames: string[];
+    series: Map<string, MetricSeries>;
+}
+
+interface HistogramDefinition {
+    type: "histogram";
+    name: string;
+    help: string;
+    labelNames: string[];
+    buckets: number[];
+    series: Map<string, HistogramSeries>;
+}
+
+type MetricDefinition =
+    | CounterDefinition
+    | GaugeDefinition
+    | HistogramDefinition;
+
+const DEFAULT_HISTOGRAM_BUCKETS = [
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1,
+    2.5,
+    5,
+    10,
+];
+
+export function createMetricsRegistry(): MetricsRegistry {
+    const definitions =
+        new Map<string, MetricDefinition>();
+
+    return {
+        counter(
+            name,
+            options = {}
+        ) {
+            const definition =
+                getOrCreateSimpleDefinition(
+                    definitions,
+                    "counter",
+                    name,
+                    options
+                );
+
+            return {
+                name: definition.name,
+                inc(
+                    value = 1,
+                    labels = {}
+                ) {
+                    assertFiniteNumber(
+                        value,
+                        "counter increment"
+                    );
+
+                    if (value < 0) {
+                        throw new TypeError(
+                            "BCP Observability: counters cannot be decreased."
+                        );
+                    }
+
+                    const series =
+                        getSimpleSeries(
+                            definition,
+                            labels
+                        );
+                    series.value += value;
+                },
+            };
+        },
+        gauge(
+            name,
+            options = {}
+        ) {
+            const definition =
+                getOrCreateSimpleDefinition(
+                    definitions,
+                    "gauge",
+                    name,
+                    options
+                );
+
+            const read = (
+                labels: MetricLabels
+            ) =>
+                getSimpleSeries(
+                    definition,
+                    labels
+                );
+
+            return {
+                name: definition.name,
+                set(
+                    value,
+                    labels = {}
+                ) {
+                    assertFiniteNumber(
+                        value,
+                        "gauge value"
+                    );
+                    read(labels).value =
+                        value;
+                },
+                inc(
+                    value = 1,
+                    labels = {}
+                ) {
+                    assertFiniteNumber(
+                        value,
+                        "gauge increment"
+                    );
+                    read(labels).value +=
+                        value;
+                },
+                dec(
+                    value = 1,
+                    labels = {}
+                ) {
+                    assertFiniteNumber(
+                        value,
+                        "gauge decrement"
+                    );
+                    read(labels).value -=
+                        value;
+                },
+            };
+        },
+        histogram(
+            name,
+            options = {}
+        ) {
+            const metricName =
+                normalizeMetricName(
+                    name
+                );
+            const labelNames =
+                normalizeLabelNames(
+                    options.labelNames
+                );
+            const buckets =
+                normalizeBuckets(
+                    options.buckets
+                );
+            const existing =
+                definitions.get(
+                    metricName
+                );
+            let definition:
+                HistogramDefinition;
+
+            if (existing) {
+                assertCompatibleDefinition(
+                    existing,
+                    "histogram",
+                    labelNames
+                );
+
+                if (
+                    existing.type !==
+                    "histogram" ||
+                    !sameNumbers(
+                        existing.buckets,
+                        buckets
+                    )
+                ) {
+                    throw new Error(
+                        `BCP Observability: metric ${metricName} was already registered with different histogram buckets.`
+                    );
+                }
+
+                definition = existing;
+            } else {
+                definition = {
+                    type: "histogram",
+                    name: metricName,
+                    help:
+                        normalizeHelp(
+                            options.help,
+                            metricName
+                        ),
+                    labelNames,
+                    buckets,
+                    series:
+                        new Map(),
+                };
+                definitions.set(
+                    metricName,
+                    definition
+                );
+            }
+
+            return {
+                name: definition.name,
+                observe(
+                    value,
+                    labels = {}
+                ) {
+                    assertFiniteNumber(
+                        value,
+                        "histogram observation"
+                    );
+                    const normalizedLabels =
+                        normalizeLabels(
+                            definition.labelNames,
+                            labels
+                        );
+                    const key =
+                        serializeLabels(
+                            definition.labelNames,
+                            normalizedLabels
+                        );
+                    let series =
+                        definition.series.get(
+                            key
+                        );
+
+                    if (!series) {
+                        series = {
+                            labels:
+                                normalizedLabels,
+                            count: 0,
+                            sum: 0,
+                            buckets:
+                                definition.buckets.map(
+                                    () => 0
+                                ),
+                        };
+                        definition.series.set(
+                            key,
+                            series
+                        );
+                    }
+
+                    series.count += 1;
+                    series.sum += value;
+
+                    for (
+                        let index = 0;
+                        index < definition.buckets.length;
+                        index++
+                    ) {
+                        if (
+                            value <=
+                            definition.buckets[index]
+                        ) {
+                            series.buckets[index] += 1;
+                        }
+                    }
+                },
+            };
+        },
+        metrics() {
+            return renderMetrics(
+                definitions
+            );
+        },
+        reset() {
+            for (
+                const definition
+                of definitions.values()
+            ) {
+                definition.series.clear();
+            }
+        },
+    };
+}
+
+export function createRequestMetricsMiddleware(
+    registry: MetricsRegistry,
+    options:
+        RequestMetricsOptions = {}
+): MiddlewarePipelineHandler {
+    const prefix =
+        normalizePrefix(
+            options.prefix
+        );
+    const labelNames:
+        string[] = [];
+
+    if (
+        options.includeMethod !==
+        false
+    ) {
+        labelNames.push(
+            "method"
+        );
+    }
+
+    if (
+        options.includeStatus !==
+        false
+    ) {
+        labelNames.push(
+            "status"
+        );
+    }
+
+    const requests =
+        registry.counter(
+            `${prefix}http_requests_total`,
+            {
+                help:
+                    "Total HTTP requests observed by BCP middleware.",
+                labelNames,
+            }
+        );
+    const duration =
+        registry.histogram(
+            `${prefix}http_request_duration_seconds`,
+            {
+                help:
+                    "HTTP request duration observed by BCP middleware.",
+                labelNames,
+            }
+        );
+
+    return async (
+        request,
+        next
+    ) => {
+        const startedAt =
+            process.hrtime.bigint();
+        let status = 500;
+
+        try {
+            const response =
+                await next();
+            status =
+                response.status;
+            return response;
+        } finally {
+            const elapsed =
+                Number(
+                    process.hrtime.bigint() -
+                    startedAt
+                ) /
+                1_000_000_000;
+            const labels:
+                Record<string, string> = {};
+
+            if (
+                options.includeMethod !==
+                false
+            ) {
+                labels.method =
+                    request.method
+                        .toUpperCase();
+            }
+
+            if (
+                options.includeStatus !==
+                false
+            ) {
+                labels.status =
+                    String(status);
+            }
+
+            requests.inc(
+                1,
+                labels
+            );
+            duration.observe(
+                elapsed,
+                labels
+            );
+        }
+    };
+}
+
+export function createMetricsResponse(
+    registry: MetricsRegistry
+): Response {
+    return new Response(
+        registry.metrics(),
+        {
+            status: 200,
+            headers: {
+                "content-type":
+                    "text/plain; version=0.0.4; charset=utf-8",
+                "cache-control":
+                    "no-store",
+            },
+        }
+    );
+}
+
+export function createHealthRegistry(): HealthRegistry {
+    const checks =
+        new Map<
+            string,
+            {
+                check: HealthCheck;
+                timeoutMs: number;
+            }
+        >();
+
+    return {
+        register(
+            name,
+            check,
+            options = {}
+        ) {
+            const normalizedName =
+                normalizeHealthCheckName(
+                    name
+                );
+            const timeoutMs =
+                normalizeHealthTimeout(
+                    options.timeoutMs
+                );
+
+            if (
+                checks.has(
+                    normalizedName
+                )
+            ) {
+                throw new Error(
+                    `BCP Observability: health check ${normalizedName} is already registered.`
+                );
+            }
+
+            checks.set(
+                normalizedName,
+                {
+                    check,
+                    timeoutMs,
+                }
+            );
+
+            return () => {
+                checks.delete(
+                    normalizedName
+                );
+            };
+        },
+        async run() {
+            const results =
+                await Promise.all(
+                    Array.from(
+                        checks.entries()
+                    ).map(
+                        async ([
+                            name,
+                            definition,
+                        ]) =>
+                            runHealthCheck(
+                                name,
+                                definition.check,
+                                definition.timeoutMs
+                            )
+                    )
+                );
+            const ok =
+                results.every(
+                    item =>
+                        item.ok
+                );
+
+            return {
+                ok,
+                status:
+                    ok
+                        ? "healthy"
+                        : "unhealthy",
+                checkedAt:
+                    new Date()
+                        .toISOString(),
+                checks:
+                    results,
+            };
+        },
+        async response() {
+            const report =
+                await this.run();
+
+            return Response.json(
+                report,
+                {
+                    status:
+                        report.ok
+                            ? 200
+                            : 503,
+                    headers: {
+                        "cache-control":
+                            "no-store",
+                    },
+                }
+            );
+        },
+        clear() {
+            checks.clear();
+        },
+    };
+}
+
+function getOrCreateSimpleDefinition(
+    definitions:
+        Map<string, MetricDefinition>,
+    type: "counter" | "gauge",
+    name: string,
+    options: MetricDefinitionOptions
+): CounterDefinition | GaugeDefinition {
+    const metricName =
+        normalizeMetricName(
+            name
+        );
+    const labelNames =
+        normalizeLabelNames(
+            options.labelNames
+        );
+    const existing =
+        definitions.get(
+            metricName
+        );
+
+    if (existing) {
+        assertCompatibleDefinition(
+            existing,
+            type,
+            labelNames
+        );
+
+        return existing as
+            CounterDefinition |
+            GaugeDefinition;
+    }
+
+    const definition:
+        CounterDefinition |
+        GaugeDefinition = {
+            type,
+            name: metricName,
+            help:
+                normalizeHelp(
+                    options.help,
+                    metricName
+                ),
+            labelNames,
+            series:
+                new Map(),
+        };
+
+    definitions.set(
+        metricName,
+        definition
+    );
+
+    return definition;
+}
+
+function getSimpleSeries(
+    definition:
+        CounterDefinition |
+        GaugeDefinition,
+    labels: MetricLabels
+): MetricSeries {
+    const normalizedLabels =
+        normalizeLabels(
+            definition.labelNames,
+            labels
+        );
+    const key =
+        serializeLabels(
+            definition.labelNames,
+            normalizedLabels
+        );
+    let series =
+        definition.series.get(
+            key
+        );
+
+    if (!series) {
+        series = {
+            labels:
+                normalizedLabels,
+            value: 0,
+        };
+        definition.series.set(
+            key,
+            series
+        );
+    }
+
+    return series;
+}
+
+function renderMetrics(
+    definitions:
+        Map<string, MetricDefinition>
+): string {
+    const lines:
+        string[] = [];
+
+    for (
+        const definition
+        of Array.from(
+            definitions.values()
+        ).sort(
+            (left, right) =>
+                left.name.localeCompare(
+                    right.name
+                )
+        )
+    ) {
+        lines.push(
+            `# HELP ${definition.name} ${escapeHelp(definition.help)}`,
+            `# TYPE ${definition.name} ${definition.type}`
+        );
+
+        if (
+            definition.type ===
+            "histogram"
+        ) {
+            for (
+                const series
+                of definition.series.values()
+            ) {
+                for (
+                    let index = 0;
+                    index < definition.buckets.length;
+                    index++
+                ) {
+                    lines.push(
+                        `${definition.name}_bucket${renderLabels({
+                            ...series.labels,
+                            le: String(
+                                definition.buckets[index]
+                            ),
+                        })} ${series.buckets[index]}`
+                    );
+                }
+
+                lines.push(
+                    `${definition.name}_bucket${renderLabels({
+                        ...series.labels,
+                        le: "+Inf",
+                    })} ${series.count}`,
+                    `${definition.name}_sum${renderLabels(series.labels)} ${series.sum}`,
+                    `${definition.name}_count${renderLabels(series.labels)} ${series.count}`
+                );
+            }
+        } else {
+            for (
+                const series
+                of definition.series.values()
+            ) {
+                lines.push(
+                    `${definition.name}${renderLabels(series.labels)} ${series.value}`
+                );
+            }
+        }
+    }
+
+    return lines.length > 0
+        ? `${lines.join("\n")}\n`
+        : "";
+}
+
+async function runHealthCheck(
+    name: string,
+    check: HealthCheck,
+    timeoutMs: number
+): Promise<HealthCheckReportItem> {
+    const startedAt =
+        performance.now();
+
+    try {
+        const result =
+            await withTimeout(
+                Promise.resolve()
+                    .then(
+                        check
+                    ),
+                timeoutMs
+            );
+        const normalized =
+            typeof result ===
+            "boolean"
+                ? {
+                    ok: result,
+                }
+                : result;
+
+        return {
+            name,
+            ok:
+                normalized.ok ===
+                true,
+            durationMs:
+                elapsedMilliseconds(
+                    startedAt
+                ),
+            ...(normalized.detail
+                ? {
+                    detail:
+                        normalized.detail,
+                }
+                : {}),
+        };
+    } catch (error) {
+        return {
+            name,
+            ok: false,
+            durationMs:
+                elapsedMilliseconds(
+                    startedAt
+                ),
+            detail:
+                error instanceof Error
+                    ? error.message
+                    : "Health check failed.",
+        };
+    }
+}
+
+function withTimeout<T>(
+    promise: Promise<T>,
+    timeoutMs: number
+): Promise<T> {
+    return new Promise<T>(
+        (
+            resolve,
+            reject
+        ) => {
+            const timeout =
+                setTimeout(
+                    () =>
+                        reject(
+                            new Error(
+                                `Health check timed out after ${timeoutMs}ms.`
+                            )
+                        ),
+                    timeoutMs
+                );
+
+            timeout.unref?.();
+
+            promise.then(
+                value => {
+                    clearTimeout(
+                        timeout
+                    );
+                    resolve(value);
+                },
+                error => {
+                    clearTimeout(
+                        timeout
+                    );
+                    reject(error);
+                }
+            );
+        }
+    );
+}
+
+function normalizeMetricName(
+    value: string
+): string {
+    const name =
+        value.trim();
+
+    if (
+        !/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(
+            name
+        )
+    ) {
+        throw new TypeError(
+            `BCP Observability: invalid metric name \"${value}\".`
+        );
+    }
+
+    return name;
+}
+
+function normalizeLabelNames(
+    values:
+        readonly string[] |
+        undefined
+): string[] {
+    const names =
+        Array.from(
+            new Set(
+                (
+                    values ??
+                    []
+                ).map(
+                    value =>
+                        value.trim()
+                )
+            )
+        );
+
+    for (
+        const name
+        of names
+    ) {
+        if (
+            !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(
+                name
+            ) ||
+            name === "le"
+        ) {
+            throw new TypeError(
+                `BCP Observability: invalid metric label name \"${name}\".`
+            );
+        }
+    }
+
+    return names;
+}
+
+function normalizeLabels(
+    labelNames: readonly string[],
+    labels: MetricLabels
+): Record<string, string> {
+    const received =
+        Object.keys(
+            labels
+        ).sort();
+    const expected =
+        [
+            ...labelNames,
+        ].sort();
+
+    if (
+        received.length !==
+            expected.length ||
+        received.some(
+            (
+                name,
+                index
+            ) =>
+                name !==
+                expected[index]
+        )
+    ) {
+        throw new TypeError(
+            `BCP Observability: metric labels must match [${labelNames.join(", ")}].`
+        );
+    }
+
+    return Object.fromEntries(
+        labelNames.map(
+            name => [
+                name,
+                String(
+                    labels[name]
+                ),
+            ]
+        )
+    );
+}
+
+function serializeLabels(
+    labelNames: readonly string[],
+    labels: Record<string, string>
+): string {
+    return labelNames
+        .map(
+            name =>
+                `${name}=${labels[name]}`
+        )
+        .join("\u0000");
+}
+
+function renderLabels(
+    labels: Record<string, string>
+): string {
+    const entries =
+        Object.entries(
+            labels
+        );
+
+    if (
+        entries.length === 0
+    ) {
+        return "";
+    }
+
+    return `{${entries.map(
+        ([
+            name,
+            value,
+        ]) =>
+            `${name}=\"${escapeLabelValue(value)}\"`
+    ).join(",")}}`;
+}
+
+function normalizeBuckets(
+    values:
+        readonly number[] |
+        undefined
+): number[] {
+    const buckets =
+        [
+            ...(
+                values ??
+                DEFAULT_HISTOGRAM_BUCKETS
+            ),
+        ].sort(
+            (
+                left,
+                right
+            ) =>
+                left - right
+        );
+
+    if (
+        buckets.length === 0 ||
+        buckets.some(
+            value =>
+                !Number.isFinite(
+                    value
+                )
+        )
+    ) {
+        throw new TypeError(
+            "BCP Observability: histogram buckets must contain finite numbers."
+        );
+    }
+
+    return Array.from(
+        new Set(
+            buckets
+        )
+    );
+}
+
+function assertCompatibleDefinition(
+    existing: MetricDefinition,
+    expectedType:
+        MetricDefinition["type"],
+    labelNames: readonly string[]
+): void {
+    if (
+        existing.type !==
+            expectedType ||
+        !sameStrings(
+            existing.labelNames,
+            labelNames
+        )
+    ) {
+        throw new Error(
+            `BCP Observability: metric ${existing.name} was already registered with a different definition.`
+        );
+    }
+}
+
+function normalizeHelp(
+    value: string | undefined,
+    fallback: string
+): string {
+    return value?.trim() ||
+        fallback;
+}
+
+function normalizePrefix(
+    value: string | undefined
+): string {
+    if (!value) {
+        return "bcp_";
+    }
+
+    const prefix =
+        value.trim();
+
+    if (
+        !/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(
+            prefix
+        )
+    ) {
+        throw new TypeError(
+            "BCP Observability: metrics prefix is invalid."
+        );
+    }
+
+    return prefix.endsWith("_")
+        ? prefix
+        : `${prefix}_`;
+}
+
+function normalizeHealthCheckName(
+    value: string
+): string {
+    const name =
+        value.trim();
+
+    if (!name) {
+        throw new TypeError(
+            "BCP Observability: health check name must not be empty."
+        );
+    }
+
+    return name;
+}
+
+function normalizeHealthTimeout(
+    value: number | undefined
+): number {
+    const timeoutMs =
+        value ?? 5_000;
+
+    if (
+        !Number.isFinite(
+            timeoutMs
+        ) ||
+        timeoutMs <= 0
+    ) {
+        throw new TypeError(
+            "BCP Observability: health check timeout must be a positive finite number of milliseconds."
+        );
+    }
+
+    return Math.floor(
+        timeoutMs
+    );
+}
+
+function assertFiniteNumber(
+    value: number,
+    label: string
+): void {
+    if (
+        !Number.isFinite(
+            value
+        )
+    ) {
+        throw new TypeError(
+            `BCP Observability: ${label} must be a finite number.`
+        );
+    }
+}
+
+function sameStrings(
+    left: readonly string[],
+    right: readonly string[]
+): boolean {
+    return left.length ===
+        right.length &&
+        left.every(
+            (
+                value,
+                index
+            ) =>
+                value ===
+                right[index]
+        );
+}
+
+function sameNumbers(
+    left: readonly number[],
+    right: readonly number[]
+): boolean {
+    return left.length ===
+        right.length &&
+        left.every(
+            (
+                value,
+                index
+            ) =>
+                value ===
+                right[index]
+        );
+}
+
+function escapeHelp(
+    value: string
+): string {
+    return value
+        .replaceAll(
+            "\\",
+            "\\\\"
+        )
+        .replaceAll(
+            "\n",
+            "\\n"
+        );
+}
+
+function escapeLabelValue(
+    value: string
+): string {
+    return value
+        .replaceAll(
+            "\\",
+            "\\\\"
+        )
+        .replaceAll(
+            "\"",
+            "\\\""
+        )
+        .replaceAll(
+            "\n",
+            "\\n"
+        );
+}
+
+function elapsedMilliseconds(
+    startedAt: number
+): number {
+    return Math.round(
+        (
+            performance.now() -
+            startedAt
+        ) * 1000
+    ) /
+        1000;
+}