@zyno-io/dk-server-foundation 26.216.430

package/src/srpc/types.ts

@@ -0,0 +1,146 @@
+import type { BinaryReader, BinaryWriter } from '@bufbuild/protobuf/wire';
+import type { ClassType } from '@deepkit/core';
+import { ScopedLogger } from '@deepkit/logger';
+import WebSocket from 'ws';
+
+import type { IByteStreamable } from './SrpcByteStream';
+
+export type RequestKeys<T> = {
+    [K in keyof T]: K extends `${infer _X}Request` ? K : never;
+}[keyof T];
+
+export type ResponseKeys<T> = {
+    [K in keyof T]: K extends `${infer _X}Response` ? K : never;
+}[keyof T];
+
+/**
+ * Extract prefix from Request keys (e.g., 'uEcho' from 'uEchoRequest')
+ */
+export type RequestPrefix<K> = K extends `${infer P}Request` ? P : never;
+
+/**
+ * Extract prefix from Response keys (e.g., 'uEcho' from 'uEchoResponse')
+ */
+export type ResponsePrefix<K> = K extends `${infer P}Response` ? P : never;
+
+/**
+ * Get all valid invoke prefixes where TReq has `${P}Request` and TRes has `${P}Response`.
+ * Excludes string index signatures to prevent overly permissive typing.
+ */
+export type InvokePrefixes<TReq, TRes> = {
+    [K in keyof TReq]: K extends string ? (K extends `${infer P}Request` ? (`${P}Response` extends keyof TRes ? P : never) : never) : never;
+}[keyof TReq];
+
+/**
+ * Get the request data type for a given prefix (for sending requests).
+ */
+export type RequestData<TReq, P extends string> = `${P}Request` extends keyof TReq ? NonNullable<TReq[`${P}Request`]> : never;
+
+/**
+ * Get the response data type for a given prefix.
+ */
+export type ResponseData<TRes, P extends string> = `${P}Response` extends keyof TRes ? NonNullable<TRes[`${P}Response`]> : never;
+
+/**
+ * Get the request data type for a handler (for receiving requests).
+ */
+export type HandlerRequestData<TReq, P extends string> = `${P}Request` extends keyof TReq ? NonNullable<TReq[`${P}Request`]> : never;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type SrpcMeta = Record<string, any>;
+
+export interface BaseMessage {
+    // requestId and reply are optional for framework messages (pingPong, byteStreamOperation)
+    // but required for actual request/response messages
+    requestId?: string;
+    reply?: boolean;
+    error?: string;
+    userError?: boolean;
+    trace?: {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    pingPong?: {};
+    byteStreamOperation?: {
+        streamId: number;
+        write?: { chunk: Uint8Array };
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        finish?: {};
+        destroy?: { error?: string };
+    };
+}
+
+/**
+ * Interface for ts-proto generated message types with encode/decode functions.
+ * This matches the MessageFns interface generated by ts-proto.
+ */
+export interface SrpcMessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+}
+
+export type SrpcDisconnectCause = 'disconnect' | 'duplicate' | 'timeout' | 'badArg';
+
+export interface IQueuedRequest {
+    exp: number;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    resolve: (value: any) => void;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    reject: (err: any) => void;
+}
+
+export class SrpcError extends Error {
+    constructor(
+        public message: string,
+        public isUserError?: boolean
+    ) {
+        super(message);
+    }
+}
+
+////////////////////////////////////////
+// SERVER
+
+export interface ISrpcServerOptions<TClientOutput extends BaseMessage, TServerOutput extends BaseMessage> {
+    logger: ScopedLogger;
+    /** ts-proto generated ClientMessage type with encode/decode */
+    clientMessage: SrpcMessageFns<TClientOutput>;
+    /** ts-proto generated ServerMessage type with encode/decode */
+    serverMessage: SrpcMessageFns<TServerOutput>;
+    wsPath: string;
+    debug?: boolean;
+    /** Controls SRPC log output. 'info' (default) logs normally, 'debug' downgrades to debug level, false suppresses all logs. */
+    logLevel?: 'info' | 'debug' | false;
+}
+
+export interface SrpcStream<T = SrpcMeta> extends IByteStreamable {
+    $ws: WebSocket;
+    $queue: Map<string, IQueuedRequest>;
+    readonly id: string;
+    readonly clientStreamId: string;
+    readonly address: string;
+    readonly clientId: string;
+    readonly appVersion: string;
+    readonly configureTs: number;
+    readonly meta: T;
+    readonly connectedAt: number;
+    lastPingAt: number;
+}
+
+export type SrpcMessageHandlerFn<C, I, O> = (wrappedStream: C, data: I) => Promise<O>;
+export interface ISrpcMessageHandler<C, I, O> {
+    handle: SrpcMessageHandlerFn<C, I, O>;
+}
+export type TSrpcMessageHandlerClass<C, I, O> = ClassType<ISrpcMessageHandler<C, I, O>>;
+export type TSrpcMessageHandlerFnOrClass<C, I, O> = SrpcMessageHandlerFn<C, I, O> | TSrpcMessageHandlerClass<C, I, O>;
+export const isSrpcMessageHandlerClass = <C, I, O>(handler: TSrpcMessageHandlerFnOrClass<C, I, O>): handler is TSrpcMessageHandlerClass<C, I, O> => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return typeof handler === 'function' && typeof (handler as any).prototype?.handle === 'function';
+};
+
+////////////////////////////////////////
+// CLIENT
+
+// todo

package/src/telemetry/index.ts

@@ -0,0 +1 @@
+export * from './otel/helpers';

package/src/telemetry/otel/MariaDBInstrumentation.ts

@@ -0,0 +1,297 @@
+// https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-mysql/src/instrumentation.ts
+
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Attributes, MeterProvider, UpDownCounter } from '@opentelemetry/api';
+import { InstrumentationBase, InstrumentationNodeModuleDefinition, isWrapped } from '@opentelemetry/instrumentation';
+import { AttributeNames } from '@opentelemetry/instrumentation-mysql/build/src/AttributeNames';
+import { MySQLInstrumentationConfig } from '@opentelemetry/instrumentation-mysql/build/src/types';
+import { getDbQueryText, getDbValues, getSpanName } from '@opentelemetry/instrumentation-mysql/build/src/utils';
+import { ATTR_DB_QUERY_TEXT, ATTR_DB_SYSTEM_NAME, DB_SYSTEM_NAME_VALUE_MARIADB } from '@opentelemetry/semantic-conventions';
+import type * as mariadbTypes from 'mariadb';
+
+import { withSpan } from './helpers';
+
+export class MariaDBInstrumentation extends InstrumentationBase {
+    static readonly COMMON_ATTRIBUTES = {
+        [ATTR_DB_SYSTEM_NAME]: DB_SYSTEM_NAME_VALUE_MARIADB
+    };
+    private _connectionsUsage!: UpDownCounter;
+
+    constructor(config?: MySQLInstrumentationConfig) {
+        super('@opentelemetry/instrumentation-mariadb', '0.0.1', config ?? {});
+        this._setMetricInstruments();
+    }
+
+    override setMeterProvider(meterProvider: MeterProvider) {
+        super.setMeterProvider(meterProvider);
+        this._setMetricInstruments();
+    }
+
+    private _setMetricInstruments() {
+        this._connectionsUsage = this.meter.createUpDownCounter(
+            'db.client.connections.usage', //TODO:: use semantic convention
+            {
+                description: 'The number of connections that are currently in state described by the state attribute.',
+                unit: '{connection}'
+            }
+        );
+    }
+
+    protected init() {
+        return [
+            new InstrumentationNodeModuleDefinition(
+                'mariadb',
+                ['3.*'],
+                moduleExports => {
+                    if (isWrapped(moduleExports.createConnection)) {
+                        this._unwrap(moduleExports, 'createConnection');
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this._wrap(moduleExports, 'createConnection', this._patchCreateConnection() as any);
+
+                    if (isWrapped(moduleExports.createPool)) {
+                        this._unwrap(moduleExports, 'createPool');
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this._wrap(moduleExports, 'createPool', this._patchCreatePool() as any);
+
+                    if (isWrapped(moduleExports.createPoolCluster)) {
+                        this._unwrap(moduleExports, 'createPoolCluster');
+                    }
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    this._wrap(moduleExports, 'createPoolCluster', this._patchCreatePoolCluster() as any);
+
+                    return moduleExports;
+                },
+                moduleExports => {
+                    if (moduleExports === undefined) return;
+                    this._unwrap(moduleExports, 'createConnection');
+                    this._unwrap(moduleExports, 'createPool');
+                    this._unwrap(moduleExports, 'createPoolCluster');
+                }
+            )
+        ];
+    }
+
+    // global export function
+    private _patchCreateConnection() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalCreateConnection: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+
+            return function createConnection(_connectionUri: string | mariadbTypes.ConnectionConfig) {
+                // eslint-disable-next-line prefer-rest-params
+                const originalResult = originalCreateConnection(...arguments);
+
+                // This is unwrapped on next call after unpatch
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                thisPlugin._wrap(originalResult, 'query', thisPlugin._patchQuery(originalResult) as any);
+
+                return originalResult;
+            };
+        };
+    }
+
+    // global export function
+    private _patchCreatePool() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalCreatePool: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            return function createPool(_config: string | mariadbTypes.PoolConfig) {
+                // eslint-disable-next-line prefer-rest-params
+                const pool = originalCreatePool(...arguments);
+
+                thisPlugin._wrap(pool, 'query', thisPlugin._patchQuery(pool));
+                thisPlugin._wrap(pool, 'getConnection', thisPlugin._patchGetConnection(pool));
+                thisPlugin._wrap(pool, 'end', thisPlugin._patchPoolEnd(pool));
+                thisPlugin._setPoolcallbacks(pool, thisPlugin, '');
+
+                return pool;
+            };
+        };
+    }
+    private _patchPoolEnd(pool: mariadbTypes.Pool) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalPoolEnd: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            return function end(_callback?: unknown) {
+                const nAll = pool.totalConnections();
+                const nFree = pool.idleConnections();
+                const nUsed = nAll - nFree;
+                const poolName = 'unk'; // todo
+                thisPlugin._connectionsUsage.add(-nUsed, {
+                    state: 'used',
+                    name: poolName
+                });
+                thisPlugin._connectionsUsage.add(-nFree, {
+                    state: 'idle',
+                    name: poolName
+                });
+                // eslint-disable-next-line prefer-rest-params
+                return originalPoolEnd.apply(pool, arguments);
+            };
+        };
+    }
+
+    // global export function
+    private _patchCreatePoolCluster() {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalCreatePoolCluster: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            return function createPool(_config: string | mariadbTypes.PoolConfig) {
+                // eslint-disable-next-line prefer-rest-params
+                const cluster = originalCreatePoolCluster(...arguments);
+
+                // This is unwrapped on next call after unpatch
+                thisPlugin._wrap(cluster, 'getConnection', thisPlugin._patchGetConnection(cluster));
+                thisPlugin._wrap(cluster, 'add', thisPlugin._patchAdd(cluster));
+
+                return cluster;
+            };
+        };
+    }
+    private _patchAdd(cluster: mariadbTypes.PoolCluster) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalAdd: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            return function add(id: string, _config: unknown) {
+                // Unwrap if unpatch has been called
+                if (!thisPlugin['_enabled']) {
+                    thisPlugin._unwrap(cluster, 'add');
+                    // eslint-disable-next-line prefer-rest-params
+                    return originalAdd.apply(cluster, arguments);
+                }
+                // eslint-disable-next-line prefer-rest-params
+                originalAdd.apply(cluster, arguments);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const nodes = cluster['_nodes' as keyof mariadbTypes.PoolCluster] as any;
+                if (nodes) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const nodeId = typeof id === 'object' ? 'CLUSTER::' + (cluster as any)._lastId : String(id);
+
+                    const pool = nodes[nodeId].pool;
+                    thisPlugin._setPoolcallbacks(pool, thisPlugin, id);
+                }
+            };
+        };
+    }
+
+    // method on cluster or pool
+    private _patchGetConnection(pool: mariadbTypes.Pool | mariadbTypes.PoolCluster) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalGetConnection: Function) => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            return async function getConnection() {
+                // Unwrap if unpatch has been called
+                if (!thisPlugin['_enabled']) {
+                    thisPlugin._unwrap(pool, 'getConnection');
+                    // eslint-disable-next-line prefer-rest-params
+                    return originalGetConnection.apply(pool, arguments);
+                }
+
+                // eslint-disable-next-line prefer-rest-params
+                const connection = await originalGetConnection.apply(pool, arguments);
+                if (!isWrapped(connection.query)) {
+                    thisPlugin._wrap(connection, 'query', thisPlugin._patchQuery(connection));
+                }
+
+                return connection;
+            };
+        };
+    }
+
+    private _patchQuery(connection: mariadbTypes.Connection | mariadbTypes.Pool) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        return (originalQuery: Function): mariadbTypes.Connection['query'] => {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const thisPlugin = this;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return function query(query: string, _valuesOrCallback?: any[]) {
+                if (!thisPlugin['_enabled']) {
+                    thisPlugin._unwrap(connection, 'query');
+                    // eslint-disable-next-line prefer-rest-params
+                    return originalQuery.apply(connection, arguments);
+                }
+
+                query = query.trim();
+
+                const spanName = getSpanName(query);
+                const spanAttributes: Attributes = {
+                    ...MariaDBInstrumentation.COMMON_ATTRIBUTES,
+                    [ATTR_DB_QUERY_TEXT]: getDbQueryText(query)
+                };
+
+                const instrumentationConfig: MySQLInstrumentationConfig = thisPlugin.getConfig();
+                if (instrumentationConfig.enhancedDatabaseReporting) {
+                    let values;
+
+                    if (Array.isArray(_valuesOrCallback)) {
+                        values = _valuesOrCallback;
+                        // eslint-disable-next-line prefer-rest-params
+                    } else if (arguments[2]) {
+                        values = [_valuesOrCallback];
+                    }
+
+                    spanAttributes[AttributeNames.MYSQL_VALUES] = getDbValues(query, values);
+                }
+
+                return withSpan(spanName, spanAttributes, () => originalQuery.apply(connection, [query, _valuesOrCallback]));
+            };
+        };
+    }
+
+    private _setPoolcallbacks(pool: mariadbTypes.Pool, thisPlugin: MariaDBInstrumentation, id: string) {
+        //TODO:: use semantic convention
+        const poolName = id || 'unk';
+
+        pool.on('connection', _connection => {
+            thisPlugin._connectionsUsage.add(1, {
+                state: 'idle',
+                name: poolName
+            });
+        });
+
+        pool.on('acquire', _connection => {
+            thisPlugin._connectionsUsage.add(-1, {
+                state: 'idle',
+                name: poolName
+            });
+            thisPlugin._connectionsUsage.add(1, {
+                state: 'used',
+                name: poolName
+            });
+        });
+
+        pool.on('release', _connection => {
+            thisPlugin._connectionsUsage.add(-1, {
+                state: 'used',
+                name: poolName
+            });
+            thisPlugin._connectionsUsage.add(1, {
+                state: 'idle',
+                name: poolName
+            });
+        });
+    }
+}

package/src/telemetry/otel/helpers.ts

@@ -0,0 +1,117 @@
+import { Attributes, ROOT_CONTEXT, Span, SpanKind, SpanStatusCode, trace, Tracer } from '@opentelemetry/api';
+import type { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
+import { isNativeError } from 'util/types';
+
+export const OtelState = {
+    tracer: undefined as Tracer | undefined,
+    prometheusExporter: undefined as PrometheusExporter | undefined,
+
+    get installed() {
+        return OtelState.tracer !== undefined;
+    }
+};
+
+export function isTracingInstalled() {
+    return OtelState.installed;
+}
+
+export function getTracer() {
+    return OtelState.tracer;
+}
+
+export function getActiveSpan() {
+    return trace.getActiveSpan();
+}
+
+export function getTraceContext() {
+    return getActiveSpan()?.spanContext();
+}
+
+export function disableActiveTrace() {
+    const ctx = getTraceContext();
+    if (ctx) {
+        ctx.traceFlags = 0;
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isError(e: any): e is Error {
+    return e instanceof Error || isNativeError(e);
+}
+
+async function runInSpan<T>(span: Span, fn: () => Promise<T>): Promise<T> {
+    try {
+        const result = await fn();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    } catch (err) {
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: isError(err) ? err.message : String(err)
+        });
+        throw err;
+    } finally {
+        span.end();
+    }
+}
+
+type SpanInfo =
+    | {
+          traceId: string;
+          spanId: string;
+          traceFlags?: number;
+      }
+    | { traceparent: string }
+    | undefined;
+
+export function withRemoteSpan<T>(name: string, spanInfo: SpanInfo, attrs: Attributes | undefined, fn: () => Promise<T>): Promise<T> {
+    if (!OtelState.tracer) return fn();
+    if (!spanInfo) return withSpan(name, attrs, fn);
+
+    let traceId: string;
+    let spanId: string;
+    let traceFlags: number | undefined;
+
+    if ('traceparent' in spanInfo) {
+        const parts = spanInfo.traceparent.split('-');
+        traceId = parts[1];
+        spanId = parts[2];
+    } else {
+        traceId = spanInfo.traceId;
+        spanId = spanInfo.spanId;
+        traceFlags = spanInfo.traceFlags;
+    }
+
+    const parentContext = trace.setSpanContext(ROOT_CONTEXT, {
+        traceId,
+        spanId,
+        traceFlags: traceFlags ?? 1 /* sample by default */,
+        isRemote: true
+    });
+    return OtelState.tracer.startActiveSpan(name, { attributes: attrs, kind: SpanKind.SERVER }, parentContext, span => runInSpan(span, fn));
+}
+
+export function withSpan<T>(name: string, fn: () => Promise<T>): Promise<T>;
+export function withSpan<T>(name: string, attrs: Attributes | undefined, fn: () => Promise<T>): Promise<T>;
+export function withSpan<T>(name: string, attrsOrFn: Attributes | (() => T) | undefined, fn?: () => Promise<T>): Promise<T> {
+    const resolvedAttrs = typeof attrsOrFn === 'object' ? attrsOrFn : undefined;
+    const resolvedFn = fn ?? (attrsOrFn as () => Promise<T>);
+
+    if (!OtelState.tracer) return resolvedFn();
+    return OtelState.tracer.startActiveSpan(name, { attributes: resolvedAttrs }, span => runInSpan(span, resolvedFn));
+}
+
+export function withRootSpan<T>(name: string, fn: () => Promise<T>): Promise<T>;
+export function withRootSpan<T>(name: string, attrs: Attributes | undefined, fn: () => Promise<T>): Promise<T>;
+export function withRootSpan<T>(name: string, attrsOrFn: Attributes | (() => T) | undefined, fn?: () => Promise<T>): Promise<T> {
+    const resolvedAttrs = typeof attrsOrFn === 'object' ? attrsOrFn : undefined;
+    const resolvedFn = fn ?? (attrsOrFn as () => Promise<T>);
+
+    if (!OtelState.tracer) return resolvedFn();
+    return OtelState.tracer.startActiveSpan(name, { attributes: resolvedAttrs }, ROOT_CONTEXT, span => runInSpan(span, resolvedFn));
+}
+
+export function setSpanAttributes(attributes: Attributes) {
+    if (!OtelState.installed) return;
+    getActiveSpan()?.setAttributes(attributes);
+}