@signal24/dk-server-foundation 26.213.615

package/src/helpers/data/transformer.ts

@@ -0,0 +1,54 @@
+import { pick } from 'lodash';
+
+import { asyncMap } from './array';
+
+export class Transformer<I> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private executor?: (input: I[]) => any[] | Promise<any[]>;
+
+    static create<I>(input: I[]): Transformer<I> {
+        return new Transformer(input);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(private input: I[] | Transformer<any>) {}
+
+    apply<O>(fn: (input: I[]) => O[] | Promise<O[]>, shouldApply = true): Transformer<O> {
+        this.executor = shouldApply ? fn : input => input;
+        return new Transformer<O>(this);
+    }
+
+    applyEach<O>(fn: (input: I) => O, shouldApply = true): Transformer<O> {
+        return this.apply(arr => arr.map(fn), shouldApply);
+    }
+
+    applyEachAsync<O>(fn: (input: I) => Promise<O>, shouldApply = true): Transformer<O> {
+        return this.apply(arr => asyncMap(arr, fn), shouldApply);
+    }
+
+    narrow<K extends (keyof I)[]>(...keys: K): Transformer<Pick<I, K[number]>> {
+        return this.apply(input => {
+            return input.map(i => {
+                return pick(i, ...keys) as Pick<I, K[number]>;
+            });
+        });
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async execute(): Promise<any[]> {
+        if (!this.executor) {
+            throw new Error('No executor defined');
+        }
+
+        const input = await this.get();
+        return this.executor(input);
+    }
+
+    async get(): Promise<I[]> {
+        if (this.input instanceof Transformer) {
+            return await this.input.execute();
+        } else {
+            return this.input;
+        }
+    }
+}

package/src/helpers/framework/decorators.ts

@@ -0,0 +1,27 @@
+import { ClassType } from '@deepkit/core';
+
+export function createSymbolAttachmentClassDecorator(aSymbol: symbol) {
+    return (): ClassDecorator => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (target: any) => {
+            target[aSymbol] = aSymbol;
+            return target;
+        };
+    };
+}
+
+const DecoratorRegistry = new Map<symbol, ClassType[]>();
+export function createRegistryClassDecorator(aSymbol: symbol) {
+    return (): ClassDecorator => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (target: any) => {
+            const classes = DecoratorRegistry.get(aSymbol) ?? [];
+            classes.push(target);
+            DecoratorRegistry.set(aSymbol, classes);
+            return target;
+        };
+    };
+}
+export function getRegisteredClasses<T extends ClassType>(aSymbol: symbol): T[] {
+    return (DecoratorRegistry.get(aSymbol) as T[]) ?? [];
+}

package/src/helpers/framework/event.ts

@@ -0,0 +1,11 @@
+import { ClassType } from '@deepkit/core';
+import { eventClass, eventDispatcher } from '@deepkit/event';
+
+export function applyParentEventHandlers(target: ClassType) {
+    const parent = Object.getPrototypeOf(target);
+    const config = eventClass._fetch(parent);
+    config?.listeners.forEach(listener => {
+        eventDispatcher.listen(listener.eventToken, listener.order)(target.prototype, listener.methodName);
+    });
+    return target;
+}

package/src/helpers/framework/injection.ts

@@ -0,0 +1,47 @@
+import { getClassName, isClass } from '@deepkit/core';
+import { InjectorModule, isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider } from '@deepkit/injector';
+import { compact } from 'lodash';
+
+export function getProviderTree(module: InjectorModule) {
+    const result = compact(
+        module.providers.map(p => {
+            if (isClass(p)) {
+                const name = getProviderName(p);
+                if (name) {
+                    return {
+                        name,
+                        module,
+                        provide: p
+                    };
+                }
+            } else if (isValueProvider(p) || isClassProvider(p) || isExistingProvider(p) || isFactoryProvider(p)) {
+                if (p.scope) return null;
+
+                const name = getProviderName(p.provide);
+                if (name) {
+                    return {
+                        name,
+                        module,
+                        provide: p.provide
+                    };
+                }
+            }
+            return null;
+        })
+    );
+
+    for (const anImport of module.imports) {
+        result.push(...getProviderTree(anImport));
+    }
+
+    return result;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getProviderName(p: any) {
+    if (typeof p === 'string') {
+        return p;
+    }
+    const className = getClassName(p);
+    return className !== 'undefined' && className !== 'anonymous class' ? className : null;
+}

package/src/helpers/index.ts

@@ -0,0 +1,34 @@
+// Data manipulation
+export * from './data/array';
+export * from './data/objects';
+export * from './data/serialization';
+export * from './data/transformer';
+
+// Async & concurrency
+export * from './async/context';
+export * from './async/process';
+export * from './async/promise';
+
+// Redis-based features
+export * from './redis/broadcast';
+export * from './redis/cache';
+export * from './redis/mutex';
+export * from './redis/redis';
+
+// I/O operations
+export * from './io/package';
+export * from './io/stream';
+
+// Security & cryptography
+export * from './security/crypto';
+export * from './security/validation';
+
+// Framework helpers
+export * from './framework/event';
+export * from './framework/injection';
+
+// Utilities
+export * from './utils/date';
+export * from './utils/error';
+export * from './utils/jsx';
+export * from './utils/uuid';

package/src/helpers/io/package.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'fs';
+import { memoize } from 'lodash';
+import { join } from 'path';
+import { cwd } from 'process';
+import type { PackageJson } from 'type-fest';
+
+export const getPackageJson: () => PackageJson | undefined = memoize(() => {
+    try {
+        const pkgJsonStr = readFileSync(join(cwd(), 'package.json'), 'utf8');
+        const pkgJson = JSON.parse(pkgJsonStr);
+        return pkgJson;
+        // eslint-disable-next-line unused-imports/no-unused-vars
+    } catch (err) {
+        return undefined;
+    }
+});
+
+export function getPackageVersion() {
+    const pkgJson = getPackageJson();
+    return pkgJson?.version;
+}
+
+export function getPackageName() {
+    const pkgJson = getPackageJson();
+    return pkgJson?.name;
+}

package/src/helpers/io/stream.ts

@@ -0,0 +1,79 @@
+import { unlink } from 'fs/promises';
+import { Readable, Writable } from 'stream';
+
+export class PipeError extends Error {
+    constructor(
+        public readonly cause: Error,
+        public readonly side: 'input' | 'output'
+    ) {
+        super(cause.message);
+    }
+}
+
+export function safePipe(input: Readable, output: Writable) {
+    return new Promise<void>((resolve, reject) => {
+        input.on('close', () => {
+            if (!input.readableEnded) {
+                if (!output.destroyed) output.destroy();
+                reject(new PipeError(new Error('Input stream aborted'), 'input'));
+            }
+        });
+        input.on('error', err => {
+            if (!output.destroyed) output.destroy();
+            reject(new PipeError(err, 'input'));
+        });
+
+        output.on('close', () => {
+            if (!output.writableEnded) {
+                if (!input.destroyed) input.destroy();
+                reject(new PipeError(new Error('Output stream aborted'), 'output'));
+            }
+        });
+        output.on('error', err => {
+            if (!input.destroyed) input.destroy();
+            reject(new PipeError(err, 'output'));
+        });
+
+        output.on('finish', () => {
+            resolve();
+        });
+        input.pipe(output);
+    });
+}
+
+class ResourceTracker {
+    files: string[] = [];
+    streams: (Readable | Writable)[] = [];
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(private reject: (err: any) => void) {}
+
+    addStream(stream: Readable | Writable) {
+        stream.on('error', this.reject);
+        this.streams.push(stream);
+    }
+
+    addFile(file: string) {
+        this.files.push(file);
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function withResourceCleanup<T>(fn: (tracker: ResourceTracker) => Promise<T>, onError?: (err: any) => void) {
+    return new Promise<T>((resolve, reject) => {
+        const tracker = new ResourceTracker(reject);
+        fn(tracker)
+            .then(resolve, err => {
+                onError?.(err);
+                reject(err);
+            })
+            .finally(() => {
+                tracker.files.forEach(file => {
+                    unlink(file).catch(() => {});
+                });
+                tracker.streams.forEach(stream => {
+                    if (!stream.destroyed) stream.destroy();
+                });
+            });
+    });
+}

package/src/helpers/redis/broadcast.ts

@@ -0,0 +1,94 @@
+import { Logger, LoggerInterface } from '@deepkit/logger';
+import { ReceiveType } from '@deepkit/type';
+import { memoize } from 'lodash';
+import { hostname } from 'os';
+
+import { r } from '../../app/resolver';
+import { createRedis } from './redis';
+
+const getSharedBroadcastChannel = memoize(() => {
+    const logger = r(Logger).scoped('Broadcast');
+    const { prefix, client: publishClient } = createRedis('BROADCAST');
+    const { client: subscribeClient } = createRedis('BROADCAST');
+
+    const channel = `${prefix}:broadcast`;
+    const localInstanceKey = `${hostname()}/${process.pid}`;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const listeners = new Map<string, Set<(message: any) => void>>();
+
+    subscribeClient.subscribe(channel);
+    subscribeClient.on('message', (_, message) => {
+        try {
+            const { instanceKey, eventName, data } = JSON.parse(message);
+            if (instanceKey === localInstanceKey) return;
+            const listenersForEvent = listeners.get(eventName);
+            if (!listenersForEvent) return;
+            for (const listener of listenersForEvent) {
+                try {
+                    listener(data);
+                } catch (err) {
+                    logger.error(`Failed to handle broadcast message`, err, { eventName });
+                }
+            }
+        } catch (err) {
+            logger.error('Failed to parse broadcast message', err, message);
+        }
+    });
+
+    return {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        subscribe: (eventName: string, fn: (data: any) => void) => {
+            const listenersForEvent = listeners.get(eventName) ?? new Set();
+            listenersForEvent.add(fn);
+            listeners.set(eventName, listenersForEvent);
+        },
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        publish: (eventName: string, data: any) => {
+            publishClient.publish(channel, JSON.stringify({ instanceKey: localInstanceKey, eventName, data }));
+        }
+    };
+});
+
+export function createBroadcastChannel<T>(eventName: string, _type?: ReceiveType<T>) {
+    const channel = getSharedBroadcastChannel();
+
+    return {
+        subscribe: (fn: (data: T) => void) => {
+            channel.subscribe(eventName, data => {
+                // todo: figure out type validation
+                // assert<T>(data, undefined, type);
+                fn(data);
+            });
+        },
+
+        publish: (data: T) => {
+            channel.publish(eventName, data);
+        }
+    };
+}
+
+interface IDistributedMethodParent {
+    logger: LoggerInterface;
+}
+export function createDistributedMethod<T>(parent: IDistributedMethodParent, name: string, fn: (data: T) => Promise<void>, type?: ReceiveType<T>) {
+    const channel = createBroadcastChannel(name, type);
+
+    const wrappedFn = async (data: T) => {
+        try {
+            await fn(data);
+        } catch (err) {
+            parent.logger.error(`Error executing ${name} distributed method`, err);
+        }
+    };
+
+    // invoke locally when remotely requested
+    channel.subscribe(wrappedFn);
+
+    // publish & invoke locally when locally executed
+    return (data: T) => {
+        channel.publish(data);
+        return wrappedFn(data);
+    };
+}

package/src/helpers/redis/cache.ts

@@ -0,0 +1,28 @@
+import { memoize } from 'lodash';
+
+import { createRedis } from './redis';
+
+const getRedis = memoize(() => createRedis('CACHE'));
+
+export class Cache {
+    static async get(key: string): Promise<string | null> {
+        const { client, prefix } = getRedis();
+        return client.get(`${prefix}:cache:${key}`);
+    }
+
+    static async set(key: string, value: string, ttl = 60): Promise<void> {
+        const { client, prefix } = getRedis();
+        await client.set(`${prefix}:cache:${key}`, value, 'EX', ttl);
+    }
+
+    static async getObj<T>(key: string): Promise<T | null> {
+        const { client, prefix } = getRedis();
+        const value = await client.get(`${prefix}:cache:${key}`);
+        return value ? JSON.parse(value) : null;
+    }
+
+    static async setObj<T>(key: string, value: T, ttl = 60): Promise<void> {
+        const { client, prefix } = getRedis();
+        await client.set(`${prefix}:cache:${key}`, JSON.stringify(value), 'EX', ttl);
+    }
+}

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);
+}