@zyno-io/dk-server-foundation 26.216.430

package/src/http/workflow.ts

@@ -0,0 +1,167 @@
+import { asyncOperation } from '@deepkit/core';
+import { eventDispatcher } from '@deepkit/event';
+import { HttpBadRequestError, HttpError, HttpRequest, HttpRouter, httpWorkflow, JSONResponse } from '@deepkit/http';
+import { LoggerInterface } from '@deepkit/logger';
+import { ValidationError } from '@deepkit/type';
+
+import { DecoratedError } from '../helpers';
+import { setSpanAttributes } from '../telemetry/otel/helpers';
+
+export class HttpWorkflowListenerOptions {
+    logRequestBodyOnError: boolean = process.env.NODE_ENV !== 'production';
+}
+
+export class HttpWorkflowListener {
+    constructor(
+        protected router: HttpRouter,
+        protected logger: LoggerInterface,
+        protected options: HttpWorkflowListenerOptions
+    ) {}
+
+    // this is a copy of the default onRoute, with the timeouts removed, because
+    // we sometimes use middleware to easily express various security requirements, and allowing a timeout
+    // during a time of delayed response due to any number of factors (such as DB load) is a security risk
+    // having a priority of 99 and dispatching a "next" ensures the default handler doesn't do anything
+    @eventDispatcher.listen(httpWorkflow.onRoute, 99)
+    async onRouteOverride(event: typeof httpWorkflow.onRoute.event) {
+        if (event.sent) return;
+        if (event.hasNext()) return;
+
+        try {
+            const resolved = this.router.resolveRequest(event.request);
+            if (resolved) {
+                event.request.uploadedFiles = resolved.uploadedFiles;
+
+                if (resolved.middlewares) {
+                    const middlewares = resolved.middlewares(event.injectorContext);
+                    if (middlewares.length) {
+                        await asyncOperation(async (resolve, reject) => {
+                            function finish() {
+                                resolve(undefined);
+                            }
+
+                            event.response.once('finish', finish);
+                            let i = -1;
+
+                            async function next() {
+                                i++;
+                                if (i >= middlewares.length) {
+                                    event.response.off('finish', finish);
+                                    resolve(undefined);
+                                    return;
+                                }
+
+                                try {
+                                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                    await middlewares[i].fn(event.request, event.response, (error?: any) => {
+                                        if (error) {
+                                            event.response.off('finish', finish);
+                                            reject(error);
+                                        } else {
+                                            next();
+                                        }
+                                    });
+                                } catch (error) {
+                                    reject(error);
+                                }
+                            }
+
+                            await next();
+                        });
+                    }
+                }
+
+                event.routeFound(resolved.routeConfig, resolved.parameters);
+            }
+        } catch (error) {
+            this.logger.error('Could not resolve request', error);
+            event.notFound();
+        }
+    }
+
+    // the default behavior for parameter resolver and controllers encountering HttpError
+    // is to return a JSONResponse with the error message in the "message" field. we want to use
+    // the "error" field, so override them both here
+    @eventDispatcher.listen(httpWorkflow.onParametersFailed)
+    onParametersFailed(event: typeof httpWorkflow.onParametersFailed.event) {
+        if (event.error instanceof ValidationError) {
+            this.logger.warn('Request parameters error', {
+                type: 'validation',
+                err: event.error.message,
+                requestBody: this.getRequestBodyForErrorLogging(event.request)
+            });
+
+            // JSON parse errors should be treated as 400s
+        } else if (event.error instanceof SyntaxError && event.error.message.includes('JSON')) {
+            this.logger.warn('Request parameters error ', { type: 'json', requestBody: this.getRequestBodyForErrorLogging(event.request) });
+            event.error = new HttpBadRequestError('Failed to parse JSON');
+
+            // all other errors should include the request body as error context
+        } else if (!(event.error instanceof HttpError)) {
+            this.decorateErrorWithRequest(event.error, event.request);
+        }
+
+        return this.handleHttpErrorFromEvent(event);
+    }
+
+    @eventDispatcher.listen(httpWorkflow.onControllerError)
+    onControllerError(event: typeof httpWorkflow.onControllerError.event) {
+        // ValidationErrors should only render as HTTP 400 when it's in the query or body, which is handled by
+        // parameters processing. validation errors within the controller body are internal errors and should be treated
+        // as 500s
+        if (event.error instanceof ValidationError) {
+            const originalError = event.error;
+            event.error = new Error('Validation failure within controller');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (event.error as any).cause = originalError;
+        }
+
+        if (event.sent && event.response.statusCode < 400) {
+            if (event.response.chunkedEncoding) {
+                event.response.write('\n\nINTERNAL SERVER ERROR\n\n', () => {
+                    event.response.destroy();
+                });
+            } else {
+                // not safe to write more data if we're not using chunked encoding
+                event.response.destroy();
+            }
+            this.logger.error('Controller error after response sent', event.error);
+            return;
+        }
+
+        this.handleHttpErrorFromEvent(event);
+
+        if (!event.sent) {
+            this.decorateErrorWithRequest(event.error, event.request);
+        }
+    }
+
+    private handleHttpErrorFromEvent(event: typeof httpWorkflow.onParametersFailed.event | typeof httpWorkflow.onControllerError.event) {
+        if (event.error instanceof HttpError) {
+            setSpanAttributes({ 'error.message': event.error.message });
+            this.logger.warn('Request processing error', { 'error.message': event.error.message });
+            event.stopImmediatePropagation();
+            event.send(
+                new JSONResponse(
+                    {
+                        error: event.error.message
+                    },
+                    event.error.httpCode
+                ).disableAutoSerializing()
+            );
+        }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private decorateErrorWithRequest(error: any, request: HttpRequest) {
+        (error as DecoratedError).context = {
+            ...(error as DecoratedError).context,
+            requestBody: this.getRequestBodyForErrorLogging(request)
+        };
+    }
+
+    private getRequestBodyForErrorLogging(request: HttpRequest) {
+        if (!this.options.logRequestBodyOnError) return undefined;
+        return request.body?.toString().slice(0, 4096);
+    }
+}

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-context.ts

@@ -0,0 +1,63 @@
+import { DatabaseRegistry } from '@deepkit/orm';
+
+import { getAppModule, getOrCreateInjectorForModule, r } from '../../app/resolver';
+import { getProviderTree } from '../../helpers/framework/injection';
+
+export interface ReplContext {
+    /** Class providers (access via $.ClassName) */
+    classProvider: Record<string, unknown>;
+    /** Instance providers (access via $$.InstanceName) — lazily resolved from DI */
+    instanceProvider: Record<string, unknown>;
+}
+
+/**
+ * Build the REPL context with `$` (class providers) and `$$` (instance providers + entity classes).
+ * Also sets `global.$` and `global.$$` for use in eval contexts.
+ */
+export function buildReplContext(): ReplContext {
+    const databaseRegistry = r(DatabaseRegistry);
+    databaseRegistry.init();
+
+    const providers = getProviderTree(getAppModule());
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const classProvider: any = {};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const instanceProvider: any = {};
+
+    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 { classProvider, instanceProvider };
+}

package/src/services/cli/repl.ts

@@ -0,0 +1,22 @@
+import { cli } from '@deepkit/app';
+import * as repl from 'repl';
+
+import { buildReplContext } from './repl-context';
+
+@cli.controller('repl', {
+    description: 'Start a REPL'
+})
+export class ReplCommand {
+    constructor() {}
+
+    async execute() {
+        buildReplContext();
+
+        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);
+        }
+    }
+}