@signal24/dk-server-foundation 26.213.615

package/src/index.ts

@@ -0,0 +1,19 @@
+// servers should *always* use UTC
+process.env.TZ = 'UTC';
+const testDate = new Date();
+if (testDate.getTimezoneOffset() !== 0) {
+    throw new Error('Please restart the process with the TZ environment variable set to UTC');
+}
+
+export * from './app';
+export { isDevelopment, isTest } from './app/const';
+export * from './auth';
+export * from './database';
+export * from './health';
+export * from './helpers';
+export * from './http';
+export * from './services';
+export * from './srpc';
+export * from './telemetry';
+export * from './testing';
+export * from './types';

package/src/services/cli/invoke.ts

@@ -0,0 +1,39 @@
+import { cli } from '@deepkit/app';
+import { InjectorError } from '@deepkit/injector';
+import { DatabaseRegistry } from '@deepkit/orm';
+import { ReflectionClass } from '@deepkit/type';
+
+import { getAppModule, getOrCreateInjectorForModule, r } from '../../app/resolver';
+import { getProviderTree } from '../../helpers/framework/injection';
+
+@cli.controller('provider:invoke', {
+    description: 'Invoke a function in any registered provider'
+})
+export class ProviderInvokeCommand {
+    constructor() {}
+
+    async execute(providerName: string, methodName: string, argsJson?: string) {
+        const providers = getProviderTree(getAppModule());
+        const provider = providers.find(p => p.name === providerName);
+
+        if (!provider) {
+            throw new InjectorError(`Provider ${providerName} not found.`);
+        }
+
+        const resolved = getOrCreateInjectorForModule(provider.module).get(provider.provide);
+        const resolvedType = ReflectionClass.from(resolved);
+        if (!resolvedType.hasMethod(methodName)) {
+            throw new InjectorError(`Provider ${providerName} does not have method ${methodName}.`);
+        }
+
+        const args = argsJson ? JSON.parse(argsJson) : [];
+
+        // DK lazily starts the database registry, but we don't have any calls that
+        // would cause that. without the registry, the application shutdown hook to
+        // disconect from the database is never executed. thus, we'll invoke this manually.
+        r(DatabaseRegistry).init();
+
+        // eslint-disable-next-line prefer-spread, @typescript-eslint/no-explicit-any
+        return resolved[methodName].apply(resolved, args as any);
+    }
+}

package/src/services/cli/repl.ts

@@ -0,0 +1,67 @@
+import { cli } from '@deepkit/app';
+import { DatabaseRegistry } from '@deepkit/orm';
+import * as repl from 'repl';
+
+import { getAppModule, getOrCreateInjectorForModule, r } from '../../app/resolver';
+import { getProviderTree } from '../../helpers/framework/injection';
+
+@cli.controller('repl', {
+    description: 'Start a REPL'
+})
+export class ReplCommand {
+    constructor() {}
+
+    async execute() {
+        // DK lazily starts the database registry, but we don't have any calls that
+        // would cause that. without the registry, the application shutdown hook to
+        // disconect from the database is never executed. thus, we'll invoke this manually.
+        const databaseRegistry = r(DatabaseRegistry);
+        databaseRegistry.init();
+
+        const providers = getProviderTree(getAppModule());
+
+        const classProvider = {};
+        const instanceProvider = {};
+
+        for (const provider of providers) {
+            if (!(provider.name in classProvider)) {
+                Object.defineProperty(classProvider, provider.name, {
+                    get() {
+                        return provider.provide;
+                    }
+                });
+            }
+
+            if (!(provider.name in instanceProvider)) {
+                Object.defineProperty(instanceProvider, provider.name, {
+                    get() {
+                        const injector = getOrCreateInjectorForModule(provider.module);
+                        return injector.get(provider.provide);
+                    }
+                });
+            }
+        }
+
+        for (const database of databaseRegistry.getDatabases()) {
+            for (const entity of database.entityRegistry.all()) {
+                Object.defineProperty(instanceProvider, entity.type.typeName!, {
+                    get() {
+                        return entity.getClassType();
+                    }
+                });
+            }
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).$ = classProvider;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (global as any).$$ = instanceProvider;
+
+        return new Promise<void>(resolve => {
+            const replServer = repl.start();
+            replServer.on('exit', () => {
+                resolve();
+            });
+        });
+    }
+}

package/src/services/cli.ts

@@ -0,0 +1,74 @@
+import { EventDispatcher } from '@deepkit/event';
+import { ApplicationServer, onServerMainBootstrapDone, onServerShutdown } from '@deepkit/framework';
+import { HttpRouterRegistry } from '@deepkit/http';
+
+import { r } from '../app/resolver';
+import { globalState } from '../app/state';
+import { HealthcheckController } from '../health/healthcheck.controller';
+import { MetricsController } from '../telemetry/otel/metrics.controller';
+
+export abstract class CliServiceCommand {
+    private eventDispatcher = r(EventDispatcher);
+    private appServer = r(ApplicationServer);
+    private routerRegistry = r(HttpRouterRegistry);
+    protected shouldRun = true;
+    public stop: () => void = () => {};
+
+    async execute() {
+        // note that we're a CLI service to prevent non-CLI side effects
+        globalState.isCliService = true;
+
+        // disable workers
+        this.appServer.config.workers = 0;
+
+        // remove all controllers except health-related ones
+        const routes = this.routerRegistry.getRoutes();
+        for (let i = 0; i < routes.length; i++) {
+            const route = routes[i];
+            if (route.action.type === 'controller') {
+                if (route.action.controller === HealthcheckController || route.action.controller === MetricsController) {
+                    continue;
+                }
+            }
+            routes.splice(i, 1);
+            i--;
+        }
+
+        // start the application server. tell it to wait for signals, but don't want for it to return,
+        // as when listening to stop signals, it won't return until the server shuts down. instead, we
+        // can listen to the onServerMainBootstrapDone event to actually wait for the server to start
+        const onServerMainBootstrapDonePromise = new Promise<void>(resolve => {
+            this.eventDispatcher.listen(onServerMainBootstrapDone, () => resolve());
+        });
+        this.appServer.start(true);
+        await onServerMainBootstrapDonePromise;
+
+        // prepare stop
+        const hasRunService = this.runService !== CliServiceCommand.prototype.runService;
+        const stopPromise = new Promise<void>(resolve => {
+            const handleStop = () => {
+                this.shouldRun = false;
+                resolve();
+            };
+            this.eventDispatcher.listen(onServerShutdown, handleStop);
+            this.stop = handleStop;
+        });
+
+        // start our CLI service
+        await this.startService();
+
+        // wait for stop signal
+        if (hasRunService) {
+            await this.runService();
+        } else {
+            await stopPromise;
+        }
+
+        // process shutdown
+        await this.shutdownService();
+    }
+
+    protected async startService(): Promise<void> {}
+    protected async runService(): Promise<void> {}
+    protected async shutdownService(): Promise<void> {}
+}

package/src/services/index.ts

@@ -0,0 +1,6 @@
+export * from './cli';
+export * from './leader';
+export * from './logger';
+export * from './mail';
+export * from './mesh';
+export * from './worker';

package/src/services/leader.ts

@@ -0,0 +1,201 @@
+import { uuid } from '@deepkit/type';
+import { memoize } from 'lodash';
+
+import { getAppConfig } from '../app/resolver';
+import { getPackageName } from '../helpers/io/package';
+import { createRedis } from '../helpers/redis/redis';
+import { createLogger } from './logger';
+
+const ACQUIRE_SCRIPT = `
+if redis.call("exists", KEYS[1]) == 1 then
+    return 0
+end
+redis.call("set", KEYS[1], ARGV[1], "px", ARGV[2])
+return 1
+`;
+
+const RENEW_SCRIPT = `
+if redis.call("get", KEYS[1]) ~= ARGV[1] then
+    return 0
+end
+redis.call("pexpire", KEYS[1], ARGV[2])
+return 1
+`;
+
+const RELEASE_SCRIPT = `
+if redis.call("get", KEYS[1]) ~= ARGV[1] then
+    return 0
+end
+redis.call("del", KEYS[1])
+return 1
+`;
+
+type LeaderRedisClient = ReturnType<typeof createRedis>['client'] & {
+    ACQUIRE: (key: string, value: string, ttl: number) => Promise<number>;
+    RENEW: (key: string, value: string, ttl: number) => Promise<number>;
+    RELEASE: (key: string, value: string) => Promise<number>;
+};
+
+const getRedisClient = memoize((): LeaderRedisClient => {
+    const { client } = createRedis('MUTEX');
+    client.defineCommand('ACQUIRE', { lua: ACQUIRE_SCRIPT, numberOfKeys: 1 });
+    client.defineCommand('RENEW', { lua: RENEW_SCRIPT, numberOfKeys: 1 });
+    client.defineCommand('RELEASE', { lua: RELEASE_SCRIPT, numberOfKeys: 1 });
+    return client as LeaderRedisClient;
+});
+
+type LeaderCallback = () => void | Promise<void>;
+
+export interface LeaderServiceOptions {
+    ttlMs?: number;
+    renewalIntervalMs?: number;
+    retryDelayMs?: number;
+}
+
+export class LeaderService {
+    private lockId = uuid();
+    private key: string;
+    private _isLeader = false;
+    private running = false;
+    private renewTimer: ReturnType<typeof setInterval> | null = null;
+    private retryTimer: ReturnType<typeof setTimeout> | null = null;
+
+    private becameLeaderCallback: LeaderCallback | null = null;
+    private lostLeaderCallback: LeaderCallback | null = null;
+
+    private ttlMs: number;
+    private renewalIntervalMs: number;
+    private retryDelayMs: number;
+
+    private logger = createLogger(this);
+
+    constructor(key: string, options?: LeaderServiceOptions) {
+        const config = getAppConfig();
+        const prefix = config.MUTEX_REDIS_PREFIX ?? config.REDIS_PREFIX ?? getPackageName() ?? 'app';
+        this.key = `${prefix}:leader:${key}`;
+        this.ttlMs = options?.ttlMs ?? 30000;
+        this.renewalIntervalMs = options?.renewalIntervalMs ?? 10000;
+        this.retryDelayMs = options?.retryDelayMs ?? 5000;
+    }
+
+    get isLeader(): boolean {
+        return this._isLeader;
+    }
+
+    setBecameLeaderCallback(callback: LeaderCallback): void {
+        this.becameLeaderCallback = callback;
+    }
+
+    setLostLeaderCallback(callback: LeaderCallback): void {
+        this.lostLeaderCallback = callback;
+    }
+
+    start(): void {
+        if (this.running) {
+            throw new Error('LeaderService is already running');
+        }
+
+        this.running = true;
+        this.logger.info('starting leader election', { key: this.key });
+        this.tryAcquire();
+    }
+
+    async stop(): Promise<void> {
+        this.running = false;
+
+        if (this.renewTimer) {
+            clearInterval(this.renewTimer);
+            this.renewTimer = null;
+        }
+
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+
+        if (this._isLeader) {
+            try {
+                await getRedisClient().RELEASE(this.key, this.lockId);
+            } catch (err) {
+                this.logger.warn('failed to release leader lock during stop', { err });
+            }
+            this._isLeader = false;
+        }
+    }
+
+    private async tryAcquire(): Promise<void> {
+        if (!this.running) return;
+
+        try {
+            const result = await getRedisClient().ACQUIRE(this.key, this.lockId, this.ttlMs);
+
+            if (result === 1) {
+                // If stop() was called while ACQUIRE was in-flight, release immediately
+                if (!this.running) {
+                    try {
+                        await getRedisClient().RELEASE(this.key, this.lockId);
+                    } catch {
+                        // ignore — lock will expire via TTL
+                    }
+                    return;
+                }
+
+                this._isLeader = true;
+                this.logger.info('became leader', { key: this.key });
+                this.startRenewal();
+                try {
+                    await this.becameLeaderCallback?.();
+                } catch (err) {
+                    this.logger.warn('becameLeader callback error', { err });
+                }
+                return;
+            }
+        } catch (err) {
+            this.logger.warn('error during leader acquisition', { err });
+        }
+
+        if (this.running) {
+            this.retryTimer = setTimeout(() => this.tryAcquire(), this.retryDelayMs);
+        }
+    }
+
+    private startRenewal(): void {
+        this.renewTimer = setInterval(async () => {
+            if (!this.running) return;
+
+            try {
+                const result = await getRedisClient().RENEW(this.key, this.lockId, this.ttlMs);
+                if (result === 0) {
+                    this.handleLostLeadership();
+                }
+            } catch (err) {
+                this.logger.warn('error during leader renewal', { err });
+                this.handleLostLeadership();
+            }
+        }, this.renewalIntervalMs);
+    }
+
+    private handleLostLeadership(): void {
+        if (!this._isLeader) return;
+
+        this._isLeader = false;
+        this.logger.info('lost leadership', { key: this.key });
+
+        if (this.renewTimer) {
+            clearInterval(this.renewTimer);
+            this.renewTimer = null;
+        }
+
+        Promise.resolve()
+            .then(() => this.lostLeaderCallback?.())
+            .catch(err => {
+                this.logger.warn('lostLeader callback error', { err });
+            });
+
+        this.lockId = uuid();
+
+        if (this.running) {
+            this.retryTimer = setTimeout(() => this.tryAcquire(), this.retryDelayMs);
+        }
+    }
+}

package/src/services/logger.ts

@@ -0,0 +1,258 @@
+import { ClassType } from '@deepkit/core';
+import { DefaultFormatter, LogData, Logger, LoggerFormatter, LoggerLevel } from '@deepkit/logger';
+import { DatabaseError } from '@deepkit/orm';
+import { AxiosError, isAxiosError } from 'axios';
+import debug from 'debug';
+import { pino, stdTimeFunctions } from 'pino';
+
+import { isDevFeatureEnabled } from '../app/config';
+import { isDevelopment, isTest } from '../app/const';
+import { DecoratedError, getContext, isError, reportError, withContextData } from '../helpers';
+import { r } from '../app/resolver';
+
+export const shouldUsePinoPretty = isDevFeatureEnabled(process.env.ENABLE_PINO_PRETTY);
+export const shouldUseSingleLine = isDevFeatureEnabled(process.env.ENABLE_PINO_SINGLE_LINE);
+export const LoggerContextProps: string[] = ['http', 'job'];
+export const LoggerContextSymbol = Symbol('LoggerContext');
+
+const PinoSeverityMap = {
+    [LoggerLevel.none]: 'DEFAULT',
+    [LoggerLevel.alert]: 'ALERT',
+    [LoggerLevel.error]: 'ERROR',
+    [LoggerLevel.warning]: 'WARNING',
+    [LoggerLevel.log]: 'NOTICE',
+    [LoggerLevel.info]: 'INFO',
+    [LoggerLevel.debug]: 'DEBUG',
+    [LoggerLevel.debug2]: 'DEBUG'
+} as const;
+type Severity = (typeof PinoSeverityMap)[keyof typeof PinoSeverityMap];
+const InvertedPinoSeverityMap: Record<Severity, number> = {
+    DEFAULT: LoggerLevel.none,
+    ALERT: LoggerLevel.alert,
+    ERROR: LoggerLevel.error,
+    WARNING: LoggerLevel.warning,
+    NOTICE: LoggerLevel.log,
+    INFO: LoggerLevel.info,
+    DEBUG: LoggerLevel.debug
+} as const;
+
+const logStream = shouldUsePinoPretty
+    ? (() => {
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          const PinoPretty = require('pino-pretty');
+          return PinoPretty.default({
+              colorize: true,
+              singleLine: shouldUseSingleLine,
+              messageFormat: '\x1b[35m{scope} \x1b[36m{message}',
+              ignore: 'scope',
+              level: process.env.LOG_LEVEL || (process.env.NODE_ENV === 'production' ? 'info' : 'debug'),
+              levelFirst: true,
+              levelKey: 'severity',
+              customLevels: Object.entries(InvertedPinoSeverityMap)
+                  .map(([severity, level]) => `${severity}:${level}`)
+                  .join(','),
+              messageKey: 'message',
+              customColors: 'alert:bgRed,error:red,warning:yellow,notice:green,info:blue,debug:gray,default:white',
+              sync: isTest
+          });
+      })()
+    : undefined;
+
+export const pinoLogger = pino(
+    {
+        formatters: {
+            level: label => ({ severity: label }),
+            bindings: isDevelopment ? () => ({ pid: process.pid }) : () => ({})
+        },
+        timestamp: stdTimeFunctions.isoTime,
+        messageKey: 'message',
+        customLevels: InvertedPinoSeverityMap,
+        useOnlyCustomLevels: true,
+        level: 'DEFAULT'
+    },
+    logStream
+);
+
+export class ExtendedLogger extends Logger {
+    protected scopeData?: LogData;
+
+    addFormatter(formatter: LoggerFormatter): void {
+        // - the server:start command injects DefaultFormatter after logger is instantiated
+        // - the message that's transformed by DefaultFormatter is not used by the default JSON transport
+        // - the color remover only removes colors from the prop the JSON transport *isn't* using
+        // so don't allow the default formatter to be added, then use our custom JSON formatter
+        // to read the original message prop after the color has been stripped
+        if (formatter instanceof DefaultFormatter) {
+            return;
+        }
+
+        super.addFormatter(formatter);
+    }
+
+    scoped(shortName: string, data?: LogData): ExtendedLogger {
+        const name = this.scope.length ? `${this.scope}:${shortName}` : shortName;
+
+        // If data is provided, always create a new instance to avoid sharing scopeData
+        // between different callers (e.g., different SIP dialogs with different callIds)
+        if (data) {
+            const scoped = new ExtendedLogger(this.transporter, this.formatter, name);
+            scoped.level = this.level;
+            // Inherit parent's scopeData and merge with provided data
+            scoped.scopeData = { ...this.scopeData, ...data };
+            return scoped;
+        }
+
+        // For bare scoped loggers (no data), use caching
+        if (!this.scopes[name]) {
+            const scoped = new ExtendedLogger(this.transporter, this.formatter, name);
+            scoped.level = this.level;
+            if (this.scopeData) {
+                scoped.scopeData = { ...this.scopeData };
+            }
+            this.scopes[name] = scoped;
+        }
+
+        return this.scopes[name] as ExtendedLogger;
+    }
+
+    // the first parameter can be a string or an object
+    // if the first parameter is a string, the second can be an object
+    // any funkier configurations than that, and we start stuffing indexed args onto the data object
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    protected send(messages: any[], level: LoggerLevel, data?: LogData) {
+        let err = isError(messages[0]) ? messages.shift() : isError(messages[1]) ? messages.splice(1, 1).shift() : undefined;
+        const message = typeof messages[0] === 'string' ? messages.shift() : '';
+        if (messages.length === 1 && typeof messages[0] === 'object') {
+            data = Object.assign(data ?? {}, messages[0]);
+        } else if (messages.length) {
+            data = data || {};
+            messages.forEach((msg, idx) => {
+                data![`arg${idx}`] = msg;
+            });
+        } else {
+            data = undefined;
+        }
+
+        if (!err && data && 'err' in data) {
+            err = data.err;
+            delete data.err;
+        }
+
+        if (this.scopeData) {
+            data = Object.assign(data ?? {}, this.scopeData);
+        }
+
+        const strippedMessage = this.stripColors(message);
+
+        // clean up errors that are too large and don't provide value to us
+        if (err instanceof DatabaseError) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            delete (err as any).entity;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            delete (err as any).classSchema;
+        } else if (isAxiosError(err)) {
+            err = transformAxiosError(err);
+        }
+
+        pinoLogger[PinoSeverityMap[level]](
+            {
+                ...(err && { err }),
+                ...(this.scope && { scope: this.scope }),
+                ...data,
+                ...this.getContextProps()
+            },
+            strippedMessage
+        );
+
+        if (err || level === LoggerLevel.alert || level === LoggerLevel.error) {
+            this.handleError(level, strippedMessage, err, data);
+        }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    debug(...message: any[]): void {
+        if (!debug(this.scope).enabled) return;
+        this.send(message, LoggerLevel.debug);
+    }
+
+    getContextProps() {
+        const context = getContext();
+        if (!context) return;
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const entries: [string, any][] = [];
+        for (const prop of LoggerContextProps) {
+            if (context[prop]) {
+                entries.push([prop, context[prop]]);
+            }
+        }
+        if (context[LoggerContextSymbol]) {
+            for (const [key, value] of Object.entries(context[LoggerContextSymbol])) {
+                entries.push([key, value]);
+            }
+        }
+        if (!entries.length) return;
+
+        return Object.fromEntries(entries);
+    }
+
+    stripColors(message: string) {
+        return message.includes('<') ? message.replace(/<(\/)?([a-zA-Z]+)>/g, '') : message;
+    }
+
+    setScopeData(data?: LogData) {
+        this.scopeData = data;
+        return this;
+    }
+
+    handleError(level: LoggerLevel, message: string | undefined, err: Error | undefined, data: LogData | undefined): void {
+        const resolvedErr = message && message !== 'Controller error' ? new Error(message) : (err ?? new Error('Unknown error'));
+        (resolvedErr as DecoratedError).cause = resolvedErr !== err ? err : undefined;
+        reportError(level, resolvedErr, {
+            data,
+            scope: this.scope || undefined,
+            scopeData: this.scopeData,
+            ...this.getContextProps()
+        });
+    }
+}
+
+export function createLogger(subject: string | InstanceType<ClassType>, defaultData?: LogData) {
+    const name = typeof subject === 'string' ? subject : subject.constructor.name;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return r<ExtendedLogger>(Logger as any)
+        .scoped(name)
+        .setScopeData(defaultData);
+}
+
+export function withLoggerContext<T>(data: LogData, fn: () => Promise<T>): Promise<T> {
+    const existingContext = getContext();
+    return withContextData(
+        {
+            [LoggerContextSymbol]: {
+                ...existingContext?.[LoggerContextSymbol],
+                ...data
+            }
+        },
+        fn
+    );
+}
+
+function transformAxiosError(err: AxiosError) {
+    return {
+        code: err.code,
+        message: err.message,
+        stack: err.stack,
+        request: {
+            url: err.config?.url,
+            method: err.config?.method,
+            headers: err.config?.headers,
+            data: err.config?.data
+        },
+        response: {
+            status: err.response?.status,
+            headers: err.response?.headers,
+            data: err.response?.data
+        }
+    };
+}