@zyno-io/dk-server-foundation 26.216.430

package/src/telemetry/otel/index.ts

@@ -0,0 +1,150 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+import { BullMQInstrumentation } from '@jenniferplusplus/opentelemetry-instrumentation-bullmq';
+import { AttributeValue, diag, DiagConsoleLogger, DiagLogLevel, metrics, trace } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Instrumentation, registerInstrumentations } from '@opentelemetry/instrumentation';
+import { DnsInstrumentation } from '@opentelemetry/instrumentation-dns';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { IORedisInstrumentation } from '@opentelemetry/instrumentation-ioredis';
+import { UndiciInstrumentation, UndiciRequest } from '@opentelemetry/instrumentation-undici';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { MeterProvider, MetricReader, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { BatchSpanProcessor, NodeTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { IncomingMessage, RequestOptions } from 'http';
+import OtelNodeMetrics from 'opentelemetry-node-metrics';
+import { hostname } from 'os';
+
+import { isDevelopment } from '../../app/const';
+import { getPackageJson } from '../../helpers/io/package';
+import { getTraceContext, OtelState, withSpan } from './helpers';
+import { MariaDBInstrumentation } from './MariaDBInstrumentation';
+
+type IHttpAttributeHook = (request: IncomingMessage) => Record<string, AttributeValue>;
+
+export interface IOtelOptions {
+    instrumentations?: Instrumentation[];
+    httpIncomingRequestAttributeHook?: IHttpAttributeHook;
+    /** Enable the /metrics endpoint. */
+    enableMetricsEndpoint?: boolean;
+}
+
+export function init(options?: IOtelOptions) {
+    const shouldInstallTraces = !!(process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+    const shouldPushMetrics = !!(process.env.OTEL_EXPORTER_OTLP_METRICS_ENDPOINT ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+
+    const metricsEndpointEnv = process.env.OTEL_METRICS_ENDPOINT_ENABLED;
+    const metricsEndpointExplicitlyEnabled = metricsEndpointEnv === 'true' || metricsEndpointEnv === '1' || options?.enableMetricsEndpoint === true;
+    const metricsEndpointExplicitlyDisabled =
+        metricsEndpointEnv === 'false' || metricsEndpointEnv === '0' || options?.enableMetricsEndpoint === false;
+    let shouldEnableMetricsEndpoint: boolean | undefined = metricsEndpointExplicitlyEnabled
+        ? true
+        : metricsEndpointExplicitlyDisabled
+          ? false
+          : undefined;
+
+    if (shouldPushMetrics) {
+        shouldEnableMetricsEndpoint ??= true;
+    }
+
+    const shouldInstallMetrics = shouldPushMetrics || !!shouldEnableMetricsEndpoint;
+
+    if (!shouldInstallTraces && !shouldInstallMetrics) {
+        console.log('OTEL_EXPORTER_* not configured. Not installing OpenTelemetry.');
+        return;
+    }
+
+    if (process.env.OTEL_DEBUG) {
+        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
+    }
+
+    const pkgJson = getPackageJson();
+    const resource = resourceFromAttributes({
+        'service.name': pkgJson?.name ?? 'unk',
+        'service.version': pkgJson?.version ?? 'unk',
+        'deployment.environment': process.env.APP_ENV,
+        'host.name': hostname(),
+        'process.pid': process.pid
+    });
+
+    registerInstrumentations({
+        instrumentations: [
+            new HttpInstrumentation({
+                startIncomingSpanHook: options?.httpIncomingRequestAttributeHook,
+                ignoreIncomingRequestHook: (request: IncomingMessage) => request.url === '/healthz' || request.url === '/metrics',
+                ignoreOutgoingRequestHook: (request: RequestOptions) => !!request.host?.match(/sentry\./)
+            }),
+            new UndiciInstrumentation({
+                ignoreRequestHook: (request: UndiciRequest) => /(\/healthz|\/metrics|sentry\.)/.test(request.path)
+            }),
+            new DnsInstrumentation(),
+            new IORedisInstrumentation(),
+            new BullMQInstrumentation(),
+            new MariaDBInstrumentation(),
+            ...(options?.instrumentations ?? [])
+        ]
+    });
+
+    installDkSqlTracer();
+
+    if (shouldInstallTraces) {
+        const exporter = new OTLPTraceExporter();
+        const spanProcessor = isDevelopment ? new SimpleSpanProcessor(exporter) : new BatchSpanProcessor(exporter);
+        const tracerProvider = new NodeTracerProvider({ resource, spanProcessors: [spanProcessor] });
+        tracerProvider.register();
+        trace.setGlobalTracerProvider(tracerProvider);
+
+        OtelState.tracer = tracerProvider.getTracer('default');
+
+        const { setHttpContextResolver } = require('../../http');
+        setHttpContextResolver(() => ({
+            traceId: getTraceContext()?.traceId
+        }));
+
+        const { LoggerContextProps } = require('../../services');
+        LoggerContextProps.push('traceId');
+    }
+
+    if (shouldInstallMetrics) {
+        const readers: MetricReader[] = [];
+
+        if (shouldPushMetrics) {
+            const otlpExporter = new OTLPMetricExporter();
+            readers.push(
+                new PeriodicExportingMetricReader({
+                    exporter: otlpExporter,
+                    exportIntervalMillis: 10_000
+                })
+            );
+        }
+
+        if (shouldEnableMetricsEndpoint) {
+            const prometheusExporter = new PrometheusExporter({ preventServerStart: true });
+            readers.push(prometheusExporter as unknown as MetricReader);
+            OtelState.prometheusExporter = prometheusExporter;
+        }
+
+        const meterProvider = new MeterProvider({
+            resource,
+            readers
+        });
+        metrics.setGlobalMeterProvider(meterProvider);
+        OtelNodeMetrics(meterProvider);
+    }
+
+    console.log('OpenTelemetry installed.');
+}
+
+function installDkSqlTracer() {
+    if (require.cache[require.resolve('mariadb')]) {
+        throw new Error('mariadb was loaded prior to SQL instrumentation injection. Please correct dependency load order.');
+    }
+
+    const { Database } = require('@deepkit/orm');
+    const originalTransaction = Database.prototype.transaction;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    Database.prototype.transaction = function <T>(callback: (session: any) => Promise<T>): Promise<T> {
+        return withSpan('sql.transaction', () => originalTransaction.call(this, callback));
+    };
+}

package/src/telemetry/otel/metrics.controller.ts

@@ -0,0 +1,50 @@
+import { http, HttpRequest, Response } from '@deepkit/http';
+
+import { AnyResponse } from '../../http';
+import { OtelState } from './helpers';
+
+function isPrivateLanIp(ip: string): boolean {
+    // Handle IPv6-mapped IPv4 addresses (::ffff:x.x.x.x)
+    if (ip.startsWith('::ffff:')) {
+        ip = ip.slice(7);
+    }
+
+    // IPv4 private ranges
+    if (ip.startsWith('10.')) return true; // 10.0.0.0/8
+    if (/^172\.(1[6-9]|2[0-9]|3[0-1])\./.test(ip)) return true; // 172.16.0.0/12
+    if (ip.startsWith('192.168.')) return true; // 192.168.0.0/16
+    if (ip.startsWith('127.')) return true; // 127.0.0.0/8 (localhost)
+
+    // IPv6 private ranges
+    if (ip === '::1') return true; // localhost
+    if (/^f[cd][0-9a-f]{2}:/i.test(ip)) return true; // fc00::/7 (unique local)
+    if (/^fe80:/i.test(ip)) return true; // fe80::/10 (link-local)
+
+    return false;
+}
+
+@http.controller('/metrics')
+export class MetricsController {
+    @http.GET()
+    async getMetrics(request: HttpRequest): AnyResponse {
+        const ip = request.getRemoteAddress();
+        if (!isPrivateLanIp(ip)) {
+            return new Response('Forbidden', 'text/plain', 403);
+        }
+
+        if (!OtelState.prometheusExporter) {
+            return new Response('Metrics not available', 'text/plain', 503);
+        }
+
+        const exporter = OtelState.prometheusExporter;
+        const { resourceMetrics, errors } = await exporter.collect();
+
+        if (errors.length) {
+            console.error('PrometheusExporter: metrics collection errors', ...errors);
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = (exporter as any)._serializer.serialize(resourceMetrics);
+        return new Response(body, 'text/plain', 200);
+    }
+}

package/src/telemetry/sentry.ts

@@ -0,0 +1,58 @@
+import * as Sentry from '@sentry/node';
+
+import { getPackageJson } from '../helpers';
+import { getTraceContext, isTracingInstalled } from './otel/helpers';
+
+const SentryState = {
+    installed: false
+};
+export function isSentryInstalled() {
+    return SentryState.installed;
+}
+
+// eslint-disable-next-line eslint-plugin-import/namespace
+export interface ISentryOptions extends Sentry.NodeOptions {
+    dsn: string;
+}
+
+export function installSentry(options: ISentryOptions) {
+    const { dsn, ...sentryOptions } = options;
+    const pkgJson = getPackageJson();
+
+    Sentry.init({
+        dsn: dsn,
+        environment: process.env.APP_ENV,
+        maxBreadcrumbs: 0,
+        release: pkgJson?.name?.replace(/^@.+?\//, '') + '@' + pkgJson?.version,
+        skipOpenTelemetrySetup: true,
+        integrations: integrations =>
+            integrations.filter(integration => {
+                return !['Http', 'NodeFetch'].includes(integration.name);
+            }),
+        ...sentryOptions
+    });
+
+    if (isTracingInstalled()) {
+        Sentry.addEventProcessor(event => {
+            const spanCtx = getTraceContext();
+            if (spanCtx) {
+                event.contexts = {
+                    ...event.contexts,
+                    trace: {
+                        trace_id: spanCtx.traceId,
+                        span_id: spanCtx.spanId
+                    }
+                };
+            }
+            return event;
+        });
+    }
+
+    SentryState.installed = true;
+}
+
+export async function flushSentry() {
+    if (isSentryInstalled()) {
+        await Sentry.flush(5);
+    }
+}

package/src/testing/expect.ts

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import _ from 'lodash';
+
+const ASYMMETRIC_MATCHER = Symbol.for('asymmetricMatcher');
+
+interface AsymmetricMatcher {
+    [ASYMMETRIC_MATCHER]: true;
+    check(value: unknown): boolean;
+    toString(): string;
+}
+
+function isAsymmetricMatcher(value: unknown): value is AsymmetricMatcher {
+    return typeof value === 'object' && value !== null && ASYMMETRIC_MATCHER in value;
+}
+
+function deepMatch(actual: unknown, expected: unknown): boolean {
+    if (isAsymmetricMatcher(expected)) {
+        return expected.check(actual);
+    }
+
+    if (expected === null || expected === undefined) {
+        return actual === expected;
+    }
+
+    if (typeof expected !== 'object') {
+        return _.isEqual(actual, expected);
+    }
+
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual)) return false;
+        if (actual.length !== expected.length) return false;
+        return expected.every((exp, i) => deepMatch(actual[i], exp));
+    }
+
+    if (typeof actual !== 'object' || actual === null) return false;
+
+    for (const key of Object.keys(expected as Record<string, unknown>)) {
+        if (!deepMatch((actual as Record<string, unknown>)[key], (expected as Record<string, unknown>)[key])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const PRIMITIVE_TYPE_MAP = new Map<any, string>([
+    [Number, 'number'],
+    [String, 'string'],
+    [Boolean, 'boolean'],
+    [BigInt, 'bigint'],
+    [Symbol, 'symbol']
+]);
+
+export function matchesObject(actual: unknown, expected: unknown): void {
+    if (!deepMatch(actual, expected)) {
+        assert.fail(
+            `Expected object to match:\n` + `  Expected: ${JSON.stringify(expected, null, 2)}\n` + `  Actual:   ${JSON.stringify(actual, null, 2)}`
+        );
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function anyOf(Type: new (...args: any[]) => any): AsymmetricMatcher {
+    const primitiveType = PRIMITIVE_TYPE_MAP.get(Type);
+    return {
+        [ASYMMETRIC_MATCHER]: true,
+        check(value: unknown) {
+            if (primitiveType) return typeof value === primitiveType;
+            return value instanceof Type;
+        },
+        toString() {
+            return `any(${Type.name})`;
+        }
+    };
+}
+
+export function arrayContaining(expected: unknown[]): AsymmetricMatcher {
+    return {
+        [ASYMMETRIC_MATCHER]: true,
+        check(value: unknown) {
+            if (!Array.isArray(value)) return false;
+            return expected.every(exp => value.some(v => deepMatch(v, exp)));
+        },
+        toString() {
+            return `arrayContaining(${JSON.stringify(expected)})`;
+        }
+    };
+}
+
+export function stringContaining(expected: string): AsymmetricMatcher {
+    return {
+        [ASYMMETRIC_MATCHER]: true,
+        check(value: unknown) {
+            return typeof value === 'string' && value.includes(expected);
+        },
+        toString() {
+            return `stringContaining(${JSON.stringify(expected)})`;
+        }
+    };
+}
+
+export function objectContaining(expected: Record<string, unknown>): AsymmetricMatcher {
+    return {
+        [ASYMMETRIC_MATCHER]: true,
+        check(value: unknown) {
+            if (typeof value !== 'object' || value === null) return false;
+            return deepMatch(value, expected);
+        },
+        toString() {
+            return `objectContaining(${JSON.stringify(expected)})`;
+        }
+    };
+}
+
+export function anything(): AsymmetricMatcher {
+    return {
+        [ASYMMETRIC_MATCHER]: true,
+        check() {
+            return true;
+        },
+        toString() {
+            return 'anything()';
+        }
+    };
+}
+
+/**
+ * Assert that a mock was called with the given arguments at least once.
+ * Works with node:test mock.fn() and mock.method() return values.
+ */
+export function assertCalledWith(mockFn: { mock: { calls: { arguments: unknown[] }[] } }, ...expectedArgs: unknown[]): void {
+    const calls = mockFn.mock.calls;
+    const match = calls.some(call => {
+        if (call.arguments.length !== expectedArgs.length) return false;
+        return expectedArgs.every((exp, i) => deepMatch(call.arguments[i], exp));
+    });
+    if (!match) {
+        assert.fail(
+            `Expected mock to have been called with:\n` +
+                `  Expected: ${JSON.stringify(expectedArgs, null, 2)}\n` +
+                `  Actual calls: ${JSON.stringify(
+                    calls.map(c => c.arguments),
+                    null,
+                    2
+                )}`
+        );
+    }
+}

package/src/testing/fixtures.ts

@@ -0,0 +1,62 @@
+import { ActiveRecordClassType } from '@deepkit/orm';
+import { isNonUndefined } from '@deepkit/sql';
+import { ReflectionKind, resolveRuntimeType, Type, TypeProperty } from '@deepkit/type';
+
+import { createPersistedEntity, NewEntityFields } from '../database';
+
+export type StringifiedDates<T> = {
+    [K in keyof T]: NonNullable<T[K]> extends Date ? string : T[K];
+};
+type IDefinedMock<T> = T & {
+    [SchemaSymbol]: ActiveRecordClassType;
+};
+
+export type TestFields<T extends ActiveRecordClassType> = StringifiedDates<NewEntityFields<InstanceType<T>>>;
+export type MockData<T extends ActiveRecordClassType> = IDefinedMock<TestFields<T>>;
+
+const SchemaSymbol = Symbol('Schema');
+export const defineEntityFixtures = <T extends ActiveRecordClassType, K extends PropertyKey>(
+    cls: T,
+    data: { [P in K]: TestFields<T> }
+): { [P in K]: MockData<T> } => {
+    for (const key in data) {
+        Object.defineProperty(data[key], SchemaSymbol, { enumerable: false, value: cls });
+    }
+    return data as { [P in K]: MockData<T> };
+};
+
+const isDate = (t: Type) => t.kind === ReflectionKind.class && t.classType.name === 'Date';
+export function prepareEntityFixtures<T extends ActiveRecordClassType>(entity: T, data: NewEntityFields<InstanceType<T>>) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: any = { ...data };
+    const type = resolveRuntimeType(entity);
+    if (type.kind === ReflectionKind.class) {
+        const props = type.types.filter(t => t.kind === ReflectionKind.property) as TypeProperty[];
+        const dateProps = props
+            .filter(p => {
+                if (p.type.kind === ReflectionKind.class) {
+                    return isDate(p.type);
+                } else if (p.type.kind === ReflectionKind.union) {
+                    return p.type.types.filter(isNonUndefined).every(isDate);
+                }
+            })
+            .map(p => p.name);
+
+        for (const prop of dateProps) {
+            if (typeof result[prop] === 'string') {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                result[prop] = new Date((data as any)[prop]);
+            }
+        }
+    }
+    return result;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function loadEntityFixtures(entities: IDefinedMock<any>[]) {
+    // todo: group by type & inject in bulk per type
+    for (const entity of entities) {
+        const data = prepareEntityFixtures(entity[SchemaSymbol], entity);
+        await createPersistedEntity(entity[SchemaSymbol], data);
+    }
+}