@signal24/dk-server-foundation 26.213.615

package/src/services/mail/index.ts

@@ -0,0 +1,117 @@
+import { ClassType } from '@deepkit/core';
+import { ScopedLogger } from '@deepkit/logger';
+
+import { BaseAppConfig } from '../../app';
+import { toError } from '../../helpers';
+import { PostmarkProvider } from './postmark';
+import { SmtpProvider } from './smtp';
+
+const senderSuffix = process.env.APP_ENV !== 'production' ? ` (${process.env.APP_ENV}) ` : '';
+const subjectPrefix = process.env.APP_ENV !== 'production' ? `[${process.env.APP_ENV}] ` : '';
+
+export abstract class MailTemplate<T> {
+    constructor(protected data: T) {}
+    abstract subject: string;
+    abstract generateHtml(): string;
+    generateText(): string | void {
+        /** */
+    }
+}
+
+export interface MessageProperties {
+    from?: {
+        name?: string;
+        address: string;
+    };
+    to: {
+        name?: string;
+        address: string;
+    };
+    replyTo?: {
+        name?: string;
+        address: string;
+    };
+    subject: string;
+    message: string;
+    plainMessage?: string;
+    attachments?: {
+        name: string;
+        content: Buffer;
+        contentType: string;
+        cid?: string;
+    }[];
+}
+
+export interface TemplateMessageProperties<T> extends Omit<MessageProperties, 'subject' | 'message' | 'plainMessage'> {
+    template: ClassType<MailTemplate<T>>;
+    data: T;
+}
+
+export interface PreparedMessageProperties extends Omit<MessageProperties, 'to' | 'from' | 'replyTo'> {
+    to: string;
+    from: string;
+    replyTo?: string;
+}
+
+export interface MailProvider {
+    send(message: PreparedMessageProperties): Promise<string>;
+}
+
+export class MailService {
+    provider: MailProvider;
+
+    constructor(
+        private config: BaseAppConfig,
+        private logger: ScopedLogger
+    ) {
+        if (this.config.MAIL_PROVIDER === 'postmark') {
+            this.provider = new PostmarkProvider(this.config, logger);
+        } else if (this.config.MAIL_PROVIDER === 'smtp') {
+            this.provider = new SmtpProvider(this.config, logger);
+        } else {
+            throw new Error('Unsupported mail provider');
+        }
+    }
+
+    async send(params: MessageProperties) {
+        const preparedParams = this.prepare(params);
+        await this.sendPrepared(preparedParams);
+    }
+
+    async sendFromTemplate<T>(params: TemplateMessageProperties<T>) {
+        const preparedParams = this.prepareFromTemplate(params);
+        await this.sendPrepared(preparedParams);
+    }
+
+    prepare(params: MessageProperties): PreparedMessageProperties {
+        const fromName = params.from?.name || this.config.MAIL_FROM_NAME;
+        const fromAddressPrefix = fromName ? `"${fromName}${senderSuffix}" ` : '';
+        const fromAddress = params.from?.address || this.config.MAIL_FROM;
+        const replyToPrefix = params.replyTo?.name ? `"${params.replyTo.name}" ` : '';
+        const toAddressPrefix = params.to.name ? `"${params.to.name}" ` : '';
+        return {
+            ...params,
+            from: `${fromAddressPrefix}<${fromAddress}>`,
+            to: `${toAddressPrefix}<${params.to.address}>`,
+            replyTo: params.replyTo ? `${replyToPrefix}<${params.replyTo.address}>` : undefined,
+            subject: `${subjectPrefix}${params.subject}`
+        };
+    }
+
+    prepareFromTemplate<T>(params: TemplateMessageProperties<T>): PreparedMessageProperties {
+        const tpl = new params.template(params.data);
+        const message = tpl.generateHtml();
+        const plainMessage = tpl.generateText() ?? undefined;
+        return this.prepare({ ...params, message, plainMessage, subject: tpl.subject });
+    }
+
+    async sendPrepared(message: PreparedMessageProperties) {
+        try {
+            const messageId = await this.provider.send(message);
+            this.logger.info('Email sent', { to: message.to, subject: message.subject, messageId });
+        } catch (err) {
+            this.logger.error('Failed to send email', err, { to: message.to, subject: message.subject });
+            throw toError('Failed to send email', err);
+        }
+    }
+}

package/src/services/mail/postmark.ts

@@ -0,0 +1,37 @@
+import { ScopedLogger } from '@deepkit/logger';
+import { ServerClient } from 'postmark';
+
+import { BaseAppConfig } from '../../app';
+import type { MailProvider, PreparedMessageProperties } from '.';
+
+export class PostmarkProvider implements MailProvider {
+    private postmarkClient = new ServerClient(this.config.POSTMARK_SECRET!);
+
+    constructor(
+        private config: BaseAppConfig,
+        private logger: ScopedLogger
+    ) {
+        if (!this.config.POSTMARK_SECRET) {
+            throw new Error('POSTMARK_SECRET is not set');
+        }
+    }
+
+    async send(message: PreparedMessageProperties): Promise<string> {
+        const response = await this.postmarkClient.sendEmail({
+            From: message.from,
+            To: message.to,
+            Subject: message.subject,
+            HtmlBody: message.message,
+            TextBody: message.plainMessage,
+            ReplyTo: message.replyTo,
+            Attachments: message.attachments?.map(attachment => ({
+                Name: attachment.name,
+                Content: attachment.content.toString('base64'),
+                ContentType: attachment.contentType,
+                ContentID: attachment.cid ?? null,
+                ContentLength: attachment.content.length
+            }))
+        });
+        return response.MessageID;
+    }
+}

package/src/services/mail/smtp.ts

@@ -0,0 +1,46 @@
+import { ScopedLogger } from '@deepkit/logger';
+import { createTransport } from 'nodemailer';
+
+import { BaseAppConfig } from '../../app';
+import type { MailProvider, PreparedMessageProperties } from '.';
+
+export class SmtpProvider implements MailProvider {
+    private transporter = createTransport({
+        host: this.config.SMTP_HOST,
+        port: this.config.SMTP_PORT,
+        secure: this.config.SMTP_TLS,
+        auth: this.config.SMTP_USER
+            ? {
+                  user: this.config.SMTP_USER,
+                  pass: this.config.SMTP_PASSWORD_SECRET
+              }
+            : undefined
+    });
+
+    constructor(
+        private config: BaseAppConfig,
+        private logger: ScopedLogger
+    ) {
+        if (!this.config.SMTP_HOST) {
+            throw new Error('SMTP_HOST is not set');
+        }
+    }
+
+    async send(message: PreparedMessageProperties): Promise<string> {
+        const response = await this.transporter.sendMail({
+            from: message.from,
+            to: message.to,
+            subject: message.subject,
+            html: message.message,
+            text: message.plainMessage,
+            replyTo: message.replyTo,
+            attachments: message.attachments?.map(attachment => ({
+                filename: attachment.name,
+                content: attachment.content,
+                contentType: attachment.contentType,
+                cid: attachment.cid
+            }))
+        });
+        return response.messageId;
+    }
+}

package/src/services/mesh.ts

@@ -0,0 +1,508 @@
+import { hostname } from 'os';
+
+import { uuid } from '@deepkit/type';
+import { memoize } from 'lodash';
+
+import { createRedis } from '../helpers/redis/redis';
+import { LeaderService, LeaderServiceOptions } from './leader';
+import { createLogger } from './logger';
+
+// --- Types ---
+
+export type MeshMessageMap = Record<string, { request: unknown; response: unknown }>;
+
+export interface MeshNode {
+    instanceId: number;
+    hostname: string;
+    self: boolean;
+}
+
+export interface MeshServiceOptions {
+    heartbeatIntervalMs?: number;
+    nodeTtlMs?: number;
+    requestTimeoutMs?: number;
+    leaderOptions?: LeaderServiceOptions;
+}
+
+export class MeshRequestTimeoutError extends Error {
+    constructor(instanceId: number, type: string) {
+        super(`Mesh request to instance ${instanceId} timed out (type: ${type})`);
+        this.name = 'MeshRequestTimeoutError';
+    }
+}
+
+export class MeshHandlerError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'MeshHandlerError';
+    }
+}
+
+export class MeshNoHandlerError extends Error {
+    constructor(type: string) {
+        super(`No handler registered for mesh message type: ${type}`);
+        this.name = 'MeshNoHandlerError';
+    }
+}
+
+// --- Constants ---
+
+const NO_HANDLER_ERROR_PREFIX = 'MESH_NO_HANDLER:';
+
+// --- Lua Scripts ---
+
+const HEARTBEAT_SCRIPT = `
+local time = redis.call("time")
+local now_ms = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+redis.call("zadd", KEYS[1], now_ms, ARGV[1])
+return 1
+`;
+
+const CLEANUP_SCRIPT = `
+local time = redis.call("time")
+local now_ms = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+local cutoff = now_ms - tonumber(ARGV[1])
+local expired = redis.call("zrangebyscore", KEYS[1], "-inf", cutoff)
+for i, id in ipairs(expired) do
+    redis.call("zrem", KEYS[1], id)
+    redis.call("hdel", KEYS[2], id)
+end
+return expired
+`;
+
+// --- Redis Client ---
+
+type MeshRedisClient = ReturnType<typeof createRedis>['client'] & {
+    HEARTBEAT: (key: string, instanceId: string) => Promise<number>;
+    CLEANUP: (heartbeatsKey: string, nodesKey: string, ttlMs: string) => Promise<string[]>;
+};
+
+const getMeshRedis = memoize(() => {
+    const { client, prefix } = createRedis('MESH');
+    client.defineCommand('HEARTBEAT', { lua: HEARTBEAT_SCRIPT, numberOfKeys: 1 });
+    client.defineCommand('CLEANUP', { lua: CLEANUP_SCRIPT, numberOfKeys: 2 });
+    return { client: client as MeshRedisClient, prefix };
+});
+
+// --- Channel Message Types ---
+
+interface MeshRequest {
+    requestId: string;
+    senderInstanceId: number;
+    type: string;
+    data: unknown;
+    timeoutMs?: number;
+}
+
+interface MeshResponse {
+    requestId: string;
+    reply: true;
+    data?: unknown;
+    error?: string;
+}
+
+interface MeshHeartbeat {
+    requestId: string;
+    heartbeat: true;
+}
+
+// --- Pending Request ---
+
+interface PendingRequest {
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+    type: string;
+    targetInstanceId: number;
+}
+
+// --- MeshService ---
+
+export class MeshService<T extends MeshMessageMap> {
+    private _instanceId: number = 0;
+    private key: string;
+    private prefix: string = '';
+    private running = false;
+
+    private heartbeatIntervalMs: number;
+    private nodeTtlMs: number;
+    private requestTimeoutMs: number;
+    private leaderOptions?: LeaderServiceOptions;
+
+    private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+    private leaderService: LeaderService | null = null;
+    private subscriberClient: ReturnType<typeof createRedis>['client'] | null = null;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    private handlers = new Map<string, (data: any) => any>();
+    private pendingRequests = new Map<string, PendingRequest>();
+    private activeHandlerIntervals = new Set<ReturnType<typeof setInterval>>();
+    private nodeCleanedUpCallback: ((instanceId: number) => void | Promise<void>) | null = null;
+
+    private logger = createLogger(this);
+
+    constructor(key: string, options?: MeshServiceOptions) {
+        this.key = key;
+        this.heartbeatIntervalMs = options?.heartbeatIntervalMs ?? 5000;
+        this.nodeTtlMs = options?.nodeTtlMs ?? 15000;
+        this.requestTimeoutMs = options?.requestTimeoutMs ?? 10000;
+        this.leaderOptions = options?.leaderOptions;
+    }
+
+    get instanceId(): number {
+        return this._instanceId;
+    }
+
+    registerHandler<K extends keyof T & string>(type: K, handler: (data: T[K]['request']) => T[K]['response'] | Promise<T[K]['response']>): void {
+        this.handlers.set(type, handler);
+    }
+
+    setNodeCleanedUpCallback(cb: (instanceId: number) => void | Promise<void>): void {
+        this.nodeCleanedUpCallback = cb;
+    }
+
+    async getNodes(): Promise<MeshNode[]> {
+        if (!this.running) {
+            throw new Error('MeshService is not running');
+        }
+
+        const { client } = getMeshRedis();
+        const members = await client.zrange(this.heartbeatsKey(), 0, -1);
+        if (members.length === 0) return [];
+
+        const hostnames = await client.hmget(this.nodesKey(), ...members);
+        return members.map((id, i) => ({
+            instanceId: parseInt(id, 10),
+            hostname: hostnames[i] ?? 'unknown',
+            self: parseInt(id, 10) === this._instanceId
+        }));
+    }
+
+    async invoke<K extends keyof T & string>(instanceId: number, type: K, data: T[K]['request']): Promise<T[K]['response']> {
+        if (!this.running) {
+            throw new Error('MeshService is not running');
+        }
+
+        // Local invocation — call handler directly
+        if (instanceId === this._instanceId) {
+            const handler = this.handlers.get(type);
+            if (!handler) throw new MeshNoHandlerError(type);
+            return handler(data);
+        }
+
+        // Remote invocation via pub/sub
+        const requestId = uuid();
+        const channel = this.channelForInstance(instanceId);
+
+        // Serialize before registering pending request to avoid leaked timers on stringify failure
+        const message: MeshRequest = {
+            requestId,
+            senderInstanceId: this._instanceId,
+            type,
+            data,
+            timeoutMs: this.requestTimeoutMs
+        };
+        const payload = JSON.stringify(message);
+
+        return new Promise<T[K]['response']>((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new MeshRequestTimeoutError(instanceId, type));
+            }, this.requestTimeoutMs);
+
+            this.pendingRequests.set(requestId, {
+                resolve: resolve as (value: unknown) => void,
+                reject,
+                timer,
+                type,
+                targetInstanceId: instanceId
+            });
+
+            const { client } = getMeshRedis();
+            client.publish(channel, payload).catch(err => {
+                clearTimeout(timer);
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`Failed to publish mesh request: ${err instanceof Error ? err.message : String(err)}`));
+            });
+        });
+    }
+
+    async start(): Promise<void> {
+        if (this.running) {
+            throw new Error('MeshService is already running');
+        }
+
+        const { client, prefix } = getMeshRedis();
+        this.prefix = prefix;
+
+        // Acquire unique instance ID
+        this._instanceId = await client.incr(this.nextIdKey());
+
+        // Create subscriber and subscribe to own channel
+        const { client: subClient } = createRedis('MESH');
+        this.subscriberClient = subClient;
+
+        try {
+            const channel = this.channelForInstance(this._instanceId);
+            await subClient.subscribe(channel);
+            subClient.on('message', (_channel: string, message: string) => {
+                this.handleMessage(message);
+            });
+
+            // Register heartbeat and node metadata
+            await client.HEARTBEAT(this.heartbeatsKey(), String(this._instanceId));
+            await client.hset(this.nodesKey(), String(this._instanceId), hostname());
+        } catch (err) {
+            // Clean up subscriber on partial init failure
+            try {
+                await subClient.unsubscribe();
+                await subClient.quit();
+            } catch {
+                // ignore cleanup errors
+            }
+            this.subscriberClient = null;
+            throw err;
+        }
+
+        this.running = true;
+
+        // Start heartbeat interval
+        this.heartbeatTimer = setInterval(() => this.doHeartbeat(), this.heartbeatIntervalMs);
+
+        // Start leader service for cleanup duties
+        this.leaderService = new LeaderService(`mesh:${this.key}`, this.leaderOptions);
+        this.leaderService.start();
+
+        this.logger.info('mesh node started', { instanceId: this._instanceId, key: this.key });
+    }
+
+    async stop(): Promise<void> {
+        this.running = false;
+
+        // Stop leader service
+        if (this.leaderService) {
+            await this.leaderService.stop();
+            this.leaderService = null;
+        }
+
+        // Stop heartbeat
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+
+        // Clear all active handler heartbeat intervals
+        for (const interval of this.activeHandlerIntervals) {
+            clearInterval(interval);
+        }
+        this.activeHandlerIntervals.clear();
+
+        // Reject all pending requests
+        for (const [requestId, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('MeshService stopped'));
+            this.pendingRequests.delete(requestId);
+        }
+
+        // Unsubscribe and quit subscriber
+        if (this.subscriberClient) {
+            try {
+                await this.subscriberClient.unsubscribe();
+                await this.subscriberClient.quit();
+            } catch {
+                // ignore errors during cleanup
+            }
+            this.subscriberClient = null;
+        }
+
+        // Remove self from heartbeats and nodes
+        try {
+            const { client } = getMeshRedis();
+            await client.zrem(this.heartbeatsKey(), String(this._instanceId));
+            await client.hdel(this.nodesKey(), String(this._instanceId));
+        } catch {
+            // ignore errors during cleanup
+        }
+
+        this.logger.info('mesh node stopped', { instanceId: this._instanceId, key: this.key });
+    }
+
+    // --- Private ---
+
+    private nextIdKey(): string {
+        return `${this.prefix}:mesh:${this.key}:next_id`;
+    }
+
+    private heartbeatsKey(): string {
+        return `${this.prefix}:mesh:${this.key}:heartbeats`;
+    }
+
+    private nodesKey(): string {
+        return `${this.prefix}:mesh:${this.key}:nodes`;
+    }
+
+    private channelForInstance(instanceId: number): string {
+        return `${this.prefix}:mesh:${this.key}:node:${instanceId}`;
+    }
+
+    private async doHeartbeat(): Promise<void> {
+        if (!this.running) return;
+
+        try {
+            const { client } = getMeshRedis();
+            await client.HEARTBEAT(this.heartbeatsKey(), String(this._instanceId));
+        } catch (err) {
+            this.logger.warn('mesh heartbeat failed', { err });
+        }
+
+        // If leader, run cleanup
+        if (this.leaderService?.isLeader) {
+            await this.doCleanup();
+        }
+    }
+
+    private async doCleanup(): Promise<void> {
+        try {
+            const { client } = getMeshRedis();
+            const expired = await client.CLEANUP(this.heartbeatsKey(), this.nodesKey(), String(this.nodeTtlMs));
+
+            if (expired.length > 0) {
+                this.logger.info('cleaned up expired mesh nodes', { expired });
+
+                for (const idStr of expired) {
+                    const id = parseInt(idStr, 10);
+                    try {
+                        await this.nodeCleanedUpCallback?.(id);
+                    } catch (err) {
+                        this.logger.warn('node cleanup callback error', { err, instanceId: id });
+                    }
+                }
+            }
+        } catch (err) {
+            this.logger.warn('mesh cleanup failed', { err });
+        }
+    }
+
+    private handleMessage(raw: string): void {
+        if (!this.running) return;
+
+        let msg: unknown;
+        try {
+            msg = JSON.parse(raw);
+        } catch (err) {
+            this.logger.warn('failed to parse mesh message', { err, raw });
+            return;
+        }
+
+        if (typeof msg !== 'object' || msg === null) {
+            this.logger.warn('invalid mesh message: not an object', { raw });
+            return;
+        }
+
+        const obj = msg as Record<string, unknown>;
+
+        if ('heartbeat' in obj && obj.heartbeat) {
+            this.handleHeartbeatMessage(obj as unknown as MeshHeartbeat);
+        } else if ('reply' in obj && obj.reply) {
+            this.handleResponseMessage(obj as unknown as MeshResponse);
+        } else {
+            this.handleRequestMessage(obj as unknown as MeshRequest);
+        }
+    }
+
+    private handleHeartbeatMessage(msg: MeshHeartbeat): void {
+        const pending = this.pendingRequests.get(msg.requestId);
+        if (!pending) return;
+
+        // Reset timeout
+        clearTimeout(pending.timer);
+        pending.timer = setTimeout(() => {
+            this.pendingRequests.delete(msg.requestId);
+            pending.reject(new MeshRequestTimeoutError(pending.targetInstanceId, pending.type));
+        }, this.requestTimeoutMs);
+    }
+
+    private handleResponseMessage(msg: MeshResponse): void {
+        const pending = this.pendingRequests.get(msg.requestId);
+        if (!pending) return;
+
+        clearTimeout(pending.timer);
+        this.pendingRequests.delete(msg.requestId);
+
+        if (msg.error !== undefined) {
+            if (typeof msg.error === 'string' && msg.error.startsWith(NO_HANDLER_ERROR_PREFIX)) {
+                pending.reject(new MeshNoHandlerError(msg.error.slice(NO_HANDLER_ERROR_PREFIX.length)));
+            } else {
+                pending.reject(new MeshHandlerError(msg.error));
+            }
+        } else {
+            pending.resolve(msg.data);
+        }
+    }
+
+    private handleRequestMessage(msg: MeshRequest): void {
+        if (!this.running) return;
+
+        if (typeof msg.requestId !== 'string' || typeof msg.senderInstanceId !== 'number' || typeof msg.type !== 'string') {
+            this.logger.warn('invalid mesh request: missing or malformed fields', { msg });
+            return;
+        }
+
+        const handler = this.handlers.get(msg.type);
+        const { client } = getMeshRedis();
+        const senderChannel = this.channelForInstance(msg.senderInstanceId);
+
+        if (!handler) {
+            const response: MeshResponse = {
+                requestId: msg.requestId,
+                reply: true,
+                error: `${NO_HANDLER_ERROR_PREFIX}${msg.type}`
+            };
+            client.publish(senderChannel, JSON.stringify(response)).catch(err => {
+                this.logger.warn('failed to publish no-handler response', { err });
+            });
+            return;
+        }
+
+        // Use the caller's timeout for heartbeat interval (fall back to our own)
+        const effectiveTimeoutMs = msg.timeoutMs ?? this.requestTimeoutMs;
+        const heartbeatInterval = setInterval(() => {
+            const heartbeat: MeshHeartbeat = {
+                requestId: msg.requestId,
+                heartbeat: true
+            };
+            client.publish(senderChannel, JSON.stringify(heartbeat)).catch(err => {
+                this.logger.warn('failed to publish handler heartbeat', { err });
+            });
+        }, effectiveTimeoutMs * 0.75);
+        this.activeHandlerIntervals.add(heartbeatInterval);
+
+        // Execute handler
+        Promise.resolve()
+            .then(() => handler(msg.data))
+            .then(result => {
+                clearInterval(heartbeatInterval);
+                this.activeHandlerIntervals.delete(heartbeatInterval);
+                const response: MeshResponse = {
+                    requestId: msg.requestId,
+                    reply: true,
+                    data: result
+                };
+                client.publish(senderChannel, JSON.stringify(response)).catch(err => {
+                    this.logger.warn('failed to publish handler response', { err });
+                });
+            })
+            .catch(err => {
+                clearInterval(heartbeatInterval);
+                this.activeHandlerIntervals.delete(heartbeatInterval);
+                const response: MeshResponse = {
+                    requestId: msg.requestId,
+                    reply: true,
+                    error: err instanceof Error ? err.message : String(err)
+                };
+                client.publish(senderChannel, JSON.stringify(response)).catch(publishErr => {
+                    this.logger.warn('failed to publish handler error response', { err: publishErr });
+                });
+            });
+    }
+}