@zyno-io/dk-server-foundation 26.216.430

package/src/helpers/redis/mutex.ts

@@ -0,0 +1,260 @@
+import { uuid } from '@deepkit/type';
+import { createHash } from 'crypto';
+import { memoize } from 'lodash';
+
+import { getAppConfig } from '../../app/resolver';
+import { withSpan } from '../../telemetry';
+import { ConcretePrimitive } from '../../types';
+import { getPackageName } from '../io/package';
+import { sleepMs } from '../utils/date';
+import { createRedis } from './redis';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type MutexFn<R = any> = (didWait: boolean) => Promise<R>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type MutexKey = ConcretePrimitive | InstanceType<any>;
+
+const getMutexHelpers = memoize(() => {
+    const appConfig = getAppConfig();
+
+    if (appConfig.MUTEX_MODE === 'local') {
+        return {
+            prepareKey: (k: string) => k,
+            exec: localMutexExec
+        };
+    }
+
+    const prefix = appConfig.MUTEX_REDIS_PREFIX ?? appConfig.REDIS_PREFIX ?? getPackageName() ?? 'app';
+    return {
+        prepareKey: (k: string) => `${prefix}:${k}`,
+        exec: redisMutexExec
+    };
+});
+
+interface IMutexOptions<T> {
+    key: MutexKey | MutexKey[];
+    fn: MutexFn<T>;
+    retryCount?: number;
+    retryDelay?: number;
+    renewInterval?: number;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const DefaultMutexOptions: Partial<IMutexOptions<any>> = {
+    retryCount: 30,
+    retryDelay: 1000,
+    renewInterval: 1000
+};
+
+export class MutexAcquisitionError extends Error {
+    constructor(message?: string) {
+        super(message ?? 'Failed to acquire mutex within timeout');
+        this.name = 'MutexAcquisitionError';
+    }
+}
+
+export function withMutex<T>(options: IMutexOptions<T>): Promise<T> {
+    const flattenedKey = flattenMutexKey(options.key);
+    const helpers = getMutexHelpers();
+    const preparedKey = helpers.prepareKey(flattenedKey);
+    return withSpan('mutex:requested', { key: flattenedKey }, () =>
+        helpers.exec({
+            ...DefaultMutexOptions,
+            ...options,
+            key: preparedKey,
+            fn: (didWait: boolean) => withSpan('mutex:held', () => options.fn(didWait))
+        })
+    );
+}
+
+export function withMutexes<T>(options: Omit<IMutexOptions<T>, 'key'> & { keys: IMutexOptions<T>['key'][] }): Promise<T> {
+    const currentKey = options.keys[0];
+    const remainingKeys = options.keys.slice(1);
+
+    let didAnyWait = false;
+    return withMutex({
+        ...options,
+        key: currentKey,
+        fn: didWait => {
+            didAnyWait = didAnyWait || didWait;
+            return remainingKeys.length ? withMutexes({ ...options, keys: remainingKeys }) : options.fn(didAnyWait);
+        }
+    });
+}
+
+/**
+ * Local Mutex
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const localMutexes = new Map<string, Promise<any>>();
+async function localMutexExec<T>(options: IMutexOptions<T>): Promise<T> {
+    const hasMutex = localMutexes.has(options.key);
+
+    if (localMutexes.has(options.key)) {
+        // eslint-disable-next-line no-async-promise-executor
+        await new Promise<void>(async (resolve, reject) => {
+            let hasTimedOut = false;
+
+            const timeout = setTimeout(() => {
+                hasTimedOut = true;
+                reject(new MutexAcquisitionError());
+            }, options.retryDelay! * options.retryCount!);
+
+            while (localMutexes.has(options.key)) {
+                try {
+                    await localMutexes.get(options.key);
+                } catch {
+                    /**/
+                }
+            }
+
+            if (hasTimedOut) return;
+            clearTimeout(timeout);
+
+            resolve();
+        });
+    }
+
+    const promise = new Promise<T>((resolve, reject) => {
+        options
+            .fn(hasMutex)
+            .then(resolve)
+            .catch(reject)
+            .finally(() => {
+                localMutexes.delete(options.key);
+            });
+    });
+    localMutexes.set(options.key, promise);
+    return promise;
+}
+
+/**
+ * Redis Mutex
+ */
+
+// Redis scripts:
+// ACQUIRE [key] [value] [ttl]
+// RENEW [key] [value] [ttl]
+// RELEASE [key] [value]
+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
+`;
+
+const getMutexRedisClient = memoize(() => {
+    const { client } = createRedis('MUTEX');
+    return client;
+});
+
+const getRedisClient = memoize(() => {
+    const redisClient = getMutexRedisClient();
+    redisClient.defineCommand('ACQUIRE', {
+        lua: ACQUIRE_SCRIPT,
+        numberOfKeys: 1
+    });
+    redisClient.defineCommand('RENEW', {
+        lua: RENEW_SCRIPT,
+        numberOfKeys: 1
+    });
+    redisClient.defineCommand('RELEASE', {
+        lua: RELEASE_SCRIPT,
+        numberOfKeys: 1
+    });
+    return redisClient as typeof redisClient & {
+        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>;
+    };
+});
+
+async function redisMutexExec<T>(options: IMutexOptions<T>): Promise<T> {
+    const lockId = uuid();
+    const redisClient = getRedisClient();
+
+    const lockTtl = options.renewInterval! * 3;
+    const deadlineMs = Date.now() + options.retryCount! * options.retryDelay!;
+    let attempts = 0;
+
+    do {
+        attempts++;
+        const result = await redisClient.ACQUIRE(options.key, lockId, lockTtl);
+        if (result === 0) {
+            await sleepMs(options.retryDelay!);
+            continue;
+        }
+
+        return new Promise<T>((resolve, reject) => {
+            const interval = setInterval(() => {
+                redisClient
+                    .RENEW(options.key, lockId, lockTtl)
+                    .then(result => {
+                        if (result === 0) throw new MutexAcquisitionError('Key missing or value mismatch');
+                    })
+                    .catch(err => {
+                        reject(new MutexAcquisitionError(`Failed to renew mutex ${options.key} ${lockId}: ${String(err)}`));
+                    });
+            }, options.renewInterval! / 2);
+
+            options
+                .fn(attempts > 1)
+                .then(resolve)
+                .catch(reject)
+                .finally(() => {
+                    clearInterval(interval);
+                    redisClient
+                        .RELEASE(options.key, lockId)
+                        .then(result => {
+                            if (result === 0) throw new MutexAcquisitionError('Key missing or value mismatch');
+                        })
+                        .catch(err => {
+                            console.warn(`Failed to release mutex ${options.key} ${lockId}`, err);
+                        });
+                });
+        });
+    } while (Date.now() < deadlineMs);
+
+    throw new MutexAcquisitionError();
+}
+
+/**
+ * Helpers
+ */
+
+export function flattenMutexKey(key: MutexKey | MutexKey[]): string {
+    if (Array.isArray(key)) {
+        return key.map(k => flattenMutexKey(k)).join(':');
+    }
+
+    if (typeof key === 'object') {
+        if ('name' in key) {
+            return key.name;
+        }
+
+        if ('constructor' in key) {
+            return key.constructor.name;
+        }
+
+        const jsonKey = JSON.stringify(key);
+        const objectKey = jsonKey.length === 2 ? String(key) : jsonKey;
+        return createHash('md5').update(objectKey).digest('hex');
+    }
+
+    return String(key);
+}

package/src/helpers/redis/redis.ts

@@ -0,0 +1,60 @@
+import RedisClient, { RedisOptions } from 'ioredis';
+
+import { getAppConfig } from '../../app/resolver';
+import { getPackageName } from '../io/package';
+
+export function createRedisOptions(configPrefix?: string): { options: RedisOptions; prefix: string } {
+    const config = { ...getAppConfig() };
+
+    if (configPrefix) {
+        for (const key in config) {
+            if (key.startsWith(`${configPrefix}_REDIS_`)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (config as any)[key.substring(configPrefix.length + 1)] = (config as any)[key];
+            }
+        }
+    }
+
+    const prefix = config.REDIS_PREFIX ?? getPackageName() ?? 'app';
+
+    if (config.REDIS_SENTINEL_HOST) {
+        const options: RedisOptions = {
+            sentinels: [
+                {
+                    host: config.REDIS_SENTINEL_HOST,
+                    port: config.REDIS_SENTINEL_PORT
+                }
+            ],
+            name: config.REDIS_SENTINEL_NAME
+        };
+        return { options, prefix };
+    }
+
+    if (config.REDIS_HOST) {
+        const options: RedisOptions = { host: config.REDIS_HOST, port: config.REDIS_PORT };
+        return { options, prefix };
+    }
+
+    throw new Error('REDIS_HOST or REDIS_SENTINEL_HOST must be configured');
+}
+
+const allClients = new Set<RedisClient>();
+
+export function createRedis(configPrefix?: string): {
+    client: RedisClient;
+    prefix: string;
+} {
+    const { options, prefix } = createRedisOptions(configPrefix);
+    const client = new RedisClient(options);
+    allClients.add(client);
+    client.on('end', () => allClients.delete(client));
+    return { client, prefix };
+}
+
+export async function disconnectAllRedis(): Promise<void> {
+    const clients = [...allClients];
+    allClients.clear();
+    await Promise.all(clients.map(c => c.quit().catch(() => {})));
+}
+
+// todo: register Redis instances with healthcheck controller

package/src/helpers/security/crypto.ts

@@ -0,0 +1,133 @@
+import { randomBytes as nativeRandomBytes } from 'crypto';
+import * as crypto from 'crypto';
+import { promisify } from 'util';
+
+import { getAppConfig } from '../../app/resolver';
+
+const nativeAsyncRandomBytes = promisify(nativeRandomBytes);
+
+// TODO: slice long requests into multiple async requests as not to block the thread for too long
+
+export async function randomBytes(length: number, shouldReturnHex?: never): Promise<Buffer>;
+export async function randomBytes(length: number, shouldReturnHex: true): Promise<string>;
+export async function randomBytes(length: number, shouldReturnHex?: true | never): Promise<Buffer | string> {
+    const bytes = await nativeAsyncRandomBytes(length);
+    return shouldReturnHex ? bytes.toString('hex') : bytes;
+}
+
+export function randomBytesSync(length: number, shouldReturnHex?: never): Buffer;
+export function randomBytesSync(length: number, shouldReturnHex: true): string;
+export function randomBytesSync(length: number, shouldReturnHex?: true | never): Buffer | string {
+    const bytes = nativeRandomBytes(length);
+    return shouldReturnHex ? bytes.toString('hex') : bytes;
+}
+
+export const PrintableCharacters = Array.from({ length: 127 - 32 }, (_, i) => String.fromCharCode(i + 32)).join('');
+export const AlphanumericCharacters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+export const UpperCaseAlphanumericCharacters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+export const NumericCharacters = '0123456789';
+export async function randomString(length: number, source: string = PrintableCharacters): Promise<string> {
+    const reference = await randomBytes(length);
+    const result = Array.from({ length });
+    for (let i = 0; i < length; i++) {
+        result[i] = source[reference[i] % source.length];
+    }
+    return result.join('');
+}
+export function randomStringSync(length: number, source: string = PrintableCharacters): string {
+    const reference = randomBytesSync(length);
+    const result = Array.from({ length });
+    for (let i = 0; i < length; i++) {
+        result[i] = source[reference[i] % source.length];
+    }
+    return result.join('');
+}
+
+export class Crypto {
+    static encrypt(data: string): string;
+    static encrypt(data: Buffer): Buffer;
+    static encrypt(data: string | Buffer): string | Buffer {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return this.getInstance().encrypt(data as any);
+    }
+
+    static decrypt(data: string): string;
+    static decrypt(data: Buffer): Buffer;
+    static decrypt(data: string | Buffer): string | Buffer {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return this.getInstance().decrypt(data as any);
+    }
+
+    private static instance: Crypto;
+    private static getInstance() {
+        if (!this.instance) {
+            this.instance = new Crypto();
+        }
+        return this.instance;
+    }
+
+    private key: Buffer;
+    private ivLength: number;
+    constructor() {
+        const appConfig = getAppConfig();
+        if (!appConfig.CRYPTO_SECRET) {
+            throw new Error('CRYPTO_SECRET is not set in application configuration');
+        }
+        if (appConfig.CRYPTO_SECRET.length === 64 && /^[0-9a-f]+$/i.test(appConfig.CRYPTO_SECRET)) {
+            this.key = Buffer.from(appConfig.CRYPTO_SECRET, 'hex');
+        } else if (appConfig.CRYPTO_SECRET.length !== 32) {
+            throw new Error('CRYPTO_SECRET must be 32 bytes (or 64 hex characters)');
+        } else {
+            this.key = Buffer.from(appConfig.CRYPTO_SECRET);
+        }
+        this.ivLength = appConfig.CRYPTO_IV_LENGTH;
+    }
+
+    encrypt(data: string): string;
+    encrypt(data: Buffer): Buffer;
+    encrypt(data: string | Buffer): string | Buffer {
+        // Check if the input is a Buffer
+        const isBuffer = Buffer.isBuffer(data);
+
+        // Convert to a buffer if it's a string
+        if (!isBuffer) {
+            data = Buffer.from(data as string);
+        }
+
+        // Generate a random initialization vector
+        const iv = crypto.randomBytes(this.ivLength);
+        const cipher = crypto.createCipheriv('aes-256-gcm', this.key, iv);
+
+        // Encrypt the data
+        const encryptedData = Buffer.concat([cipher.update(data), cipher.final()]);
+
+        // Concatenate iv, encrypted data, and authentication tag into a single Buffer
+        const outputData = Buffer.concat([iv, encryptedData, cipher.getAuthTag()]);
+
+        // Return the data encoded as base64 if input was a string, else return as Buffer
+        return isBuffer ? outputData : outputData.toString('base64');
+    }
+
+    decrypt(data: string): string;
+    decrypt(data: Buffer): Buffer;
+    decrypt(data: string | Buffer): string | Buffer {
+        // Check if the input is a Buffer
+        const isBuffer = Buffer.isBuffer(data);
+
+        // Convert to Buffer if it's a string
+        const dataBuf = isBuffer ? data : Buffer.from(data, 'base64');
+
+        // Split the input into iv, encrypted data, and authentication tag
+        const iv = dataBuf.subarray(0, this.ivLength);
+        const authTag = dataBuf.subarray(dataBuf.length - 16);
+        const encryptedData = dataBuf.subarray(this.ivLength, dataBuf.length - 16);
+
+        // Decrypt the data
+        const decipher = crypto.createDecipheriv('aes-256-gcm', this.key, iv);
+        decipher.setAuthTag(authTag);
+        const decryptedData = Buffer.concat([decipher.update(encryptedData), decipher.final()]);
+
+        // Return the decrypted data as a string if the input was a string, else return as Buffer
+        return isBuffer ? decryptedData : decryptedData.toString('utf8');
+    }
+}

package/src/helpers/security/validation.ts

@@ -0,0 +1,16 @@
+import { HttpBadRequestError } from '@deepkit/http';
+import { ReceiveType, validate, ValidationError } from '@deepkit/type';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function validateOrThrow<T>(data: any, type?: ReceiveType<T>): data is T {
+    const errors = validate<T>(data, type);
+    if (errors.length) throw new ValidationError(errors);
+    return true;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function assertInput(value: any, field?: string): asserts value {
+    if (value === undefined || value === null) {
+        throw new HttpBadRequestError(field ? `${field} is required` : 'missing parameters');
+    }
+}

package/src/helpers/utils/date.ts

@@ -0,0 +1,13 @@
+import { format } from 'date-fns';
+
+export function extractDate(date: Date): string {
+    return format(date, 'yyyy-MM-dd');
+}
+
+export function sleepMs(ms: number) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export function sleepSecs(secs: number) {
+    return sleepMs(secs * 1000);
+}

package/src/helpers/utils/error.ts

@@ -0,0 +1,155 @@
+import { LoggerLevel } from '@deepkit/logger';
+import * as Sentry from '@sentry/node';
+import { compact, omit, pick } from 'lodash';
+import { isNativeError } from 'util/types';
+
+import { getAppConfig } from '../../app/resolver';
+import { getTraceContext } from '../../telemetry';
+import { isSentryInstalled } from '../../telemetry/sentry';
+import { ArrowFunctionNoArgs, VoidFunction } from '../../types';
+
+export const SentryLiftKeysToTagsFromLoggerContext = [];
+
+export interface DecoratedError extends Error {
+    cause?: Error;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    context?: Record<string, any>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isError(e: any): e is Error {
+    return e instanceof Error || isNativeError(e);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getErrorMessage(e: any): string {
+    return isError(e) ? e.message : String(e);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function toError(e: any, cause?: any): Error {
+    const baseError = isError(e) ? e : new Error(String(e));
+    if (cause) {
+        (baseError as DecoratedError).cause = toError(cause);
+    }
+    return baseError;
+}
+
+export function tryOrErrorSync<T extends ArrowFunctionNoArgs>(fn: T): ReturnType<T> | Error {
+    try {
+        return fn();
+    } catch (e) {
+        return toError(e);
+    }
+}
+
+export async function tryOrError<T extends ArrowFunctionNoArgs>(fn: T): Promise<ReturnType<T> | Error> {
+    try {
+        return await fn();
+    } catch (e) {
+        return toError(e);
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function tryWithReject<T extends (reject: VoidFunction) => Promise<any>>(fn: T): Promise<ReturnType<T>> {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise(async (resolve, reject) => {
+        try {
+            resolve(await fn(reject));
+        } catch (e) {
+            reject(e);
+        }
+    });
+}
+
+export interface IErrorContext {
+    scope?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    scopeData?: Record<string, any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    loggerContext?: Record<string, any>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    data?: Record<string, any>;
+}
+const errorHandlerState: { reporter?: (level: LoggerLevel, err: Error, context: IErrorContext) => void } = {};
+export function setGlobalErrorReporter(reporter: (label: LoggerLevel, err: Error, context: IErrorContext) => void) {
+    errorHandlerState.reporter = reporter;
+}
+export function reportError(level: LoggerLevel, err: Error, context: IErrorContext) {
+    if (errorHandlerState.reporter) {
+        errorHandlerState.reporter(level, err, context);
+    }
+    if (isSentryInstalled()) {
+        const tags = context.loggerContext ? pick(context.loggerContext, SentryLiftKeysToTagsFromLoggerContext) : {};
+        const Details = {
+            ...context,
+            loggerContext: omit(context.loggerContext, SentryLiftKeysToTagsFromLoggerContext)
+        };
+        Sentry.captureException(err, {
+            tags,
+            extra: { Details },
+            level: level === LoggerLevel.alert ? 'fatal' : level === LoggerLevel.warning ? 'warning' : 'error'
+        });
+    }
+    if (level === LoggerLevel.alert) {
+        sendSlackAlertNotification(err, context);
+    }
+}
+
+async function sendSlackAlertNotification(err: DecoratedError, context: IErrorContext) {
+    try {
+        const traceContext = getTraceContext();
+        const url = getAppConfig().ALERTS_SLACK_WEBHOOK_URL;
+        if (!url) return;
+
+        await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                text: compact([`:rotating_light: *${err.message}*`, err.cause && `cause: ${err.cause.message}`]).join('\n'),
+                attachments: [
+                    {
+                        color: 'danger',
+                        fields: compact([
+                            context.scope && {
+                                title: 'Scope',
+                                value: context.scope,
+                                short: true
+                            },
+                            traceContext && {
+                                title: 'Trace ID',
+                                value: traceContext.traceId,
+                                short: true
+                            },
+                            context.data && {
+                                title: 'Alert Data',
+                                value: JSON.stringify(context.data, null, 2),
+                                short: false
+                            },
+                            err.context && {
+                                title: 'Error Context',
+                                value: JSON.stringify(err.context, null, 2),
+                                short: false
+                            },
+                            context.scopeData && {
+                                title: 'Scope Data',
+                                value: JSON.stringify(context.scopeData, null, 2),
+                                short: false
+                            },
+                            context.loggerContext && {
+                                title: 'Logger Context',
+                                value: JSON.stringify(context.loggerContext, null, 2),
+                                short: false
+                            }
+                        ])
+                    }
+                ]
+            })
+        });
+    } catch (err) {
+        console.error('Failed to send slack alert notification', err);
+    }
+}

package/src/helpers/utils/jsx.ts

@@ -0,0 +1,8 @@
+import { InjectorContext } from '@deepkit/injector';
+import { ElementStruct, render } from '@deepkit/template';
+
+import { resolve } from '../../app/resolver';
+
+export async function jsxToHtml(jsx: ElementStruct) {
+    return render(resolve(InjectorContext).getRootInjector(), jsx) as Promise<string>;
+}

package/src/helpers/utils/uuid.ts

@@ -0,0 +1,8 @@
+import { uuidv7, V7Generator } from 'uuidv7';
+
+export const uuid7 = uuidv7;
+
+const v7Generator = new V7Generator();
+export const uuid7FromDate = (date: Date) => {
+    return v7Generator.generateOrResetCore(date.getTime(), 10_000).toString();
+};