@zintrust/core 1.5.3 → 1.5.5

package/src/cli/utils/spawn.js

@@ -4,6 +4,36 @@ import { spawn } from '../../node-singletons/child-process.js';
 import { existsSync } from '../../node-singletons/fs.js';
 import * as path from '../../node-singletons/path.js';
 import { fileURLToPath } from '../../node-singletons/url.js';
+const CLI_SPAWN_TRACE_ENV_KEYS = ['CLI_SPAWN_TRACE', 'ZIN_SPAWN_TRACE'];
+const getCliSpawnTracePid = () => {
+    if (typeof process === 'undefined')
+        return undefined;
+    return process.pid;
+};
+const isCliSpawnTraceEnabled = () => {
+    if (typeof process === 'undefined')
+        return false;
+    return CLI_SPAWN_TRACE_ENV_KEYS.some((key) => {
+        const raw = process.env[key];
+        if (typeof raw !== 'string')
+            return false;
+        const normalized = raw.trim().toLowerCase();
+        return (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on');
+    });
+};
+const writeCliSpawnTrace = (label, details = {}) => {
+    if (!isCliSpawnTraceEnabled())
+        return;
+    const line = JSON.stringify({
+        trace: 'cli-spawn',
+        label,
+        pid: getCliSpawnTracePid(),
+        details,
+    });
+    if (typeof process !== 'undefined' && typeof process.stderr?.write === 'function') {
+        process.stderr.write(`${line}\n`);
+    }
+};
 const getExitCode = (exitCode, signal) => {
     if (typeof exitCode === 'number')
         return exitCode;
@@ -45,60 +75,299 @@ const buildCommandNotFoundMessage = (command) => {
     }
     return `Error: '${command}' not found on PATH.`;
 };
+const waitForChildExit = async (child, onExit) => {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let childResult = {
+            exitCode: null,
+            signal: null,
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            writeCliSpawnTrace('spawn.wait.finish', {
+                childPid: child.pid,
+                exitCode: childResult.exitCode,
+                signal: childResult.signal,
+            });
+            child.off?.('exit', onExitEvent);
+            child.off?.('close', onCloseEvent);
+            onExit();
+            resolve(childResult);
+        };
+        const onExitEvent = (code, signal) => {
+            writeCliSpawnTrace('spawn.child.exit', {
+                childPid: child.pid,
+                exitCode: code,
+                signal,
+            });
+            childResult = { exitCode: code, signal };
+        };
+        const onCloseEvent = (code, signal) => {
+            writeCliSpawnTrace('spawn.child.close', {
+                childPid: child.pid,
+                exitCode: code,
+                signal,
+            });
+            childResult = {
+                exitCode: childResult.exitCode ?? code,
+                signal: childResult.signal ?? signal,
+            };
+            finish();
+        };
+        child.once('error', (error) => {
+            writeCliSpawnTrace('spawn.child.error', {
+                childPid: child.pid,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            reject(error);
+        });
+        child.once('exit', onExitEvent);
+        child.once('close', onCloseEvent);
+    });
+};
+const resolveSignalHandling = (input) => {
+    const forwardSignals = typeof input.forwardSignals === 'boolean' ? input.forwardSignals : !process.stdin.isTTY;
+    const ttySignalForwardDelayMs = process.stdin.isTTY === true && forwardSignals === false
+        ? Math.max(0, input.ttySignalForwardDelayMs ?? 0)
+        : 0;
+    return {
+        forwardSignals,
+        ttySignalForwardDelayMs,
+    };
+};
+const spawnChildProcess = (input) => {
+    writeCliSpawnTrace('spawn.child.start', {
+        command: input.command,
+        args: input.args,
+        cwd: input.cwd,
+        shell: input.shell,
+    });
+    const child = spawn(input.command, input.args, {
+        cwd: input.cwd,
+        env: input.env,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        shell: input.shell,
+    });
+    child.stdout?.on('data', (chunk) => {
+        writeCliSpawnTrace('spawn.child.stdout.data', {
+            childPid: child.pid,
+            bytes: typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length,
+        });
+        process.stdout.write(chunk);
+    });
+    child.stdout?.on('end', () => {
+        writeCliSpawnTrace('spawn.child.stdout.end', {
+            childPid: child.pid,
+        });
+    });
+    child.stdout?.on('close', () => {
+        writeCliSpawnTrace('spawn.child.stdout.close', {
+            childPid: child.pid,
+        });
+    });
+    child.stderr?.on('data', (chunk) => {
+        writeCliSpawnTrace('spawn.child.stderr.data', {
+            childPid: child.pid,
+            bytes: typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length,
+        });
+        process.stderr.write(chunk);
+    });
+    child.stderr?.on('end', () => {
+        writeCliSpawnTrace('spawn.child.stderr.end', {
+            childPid: child.pid,
+        });
+    });
+    child.stderr?.on('close', () => {
+        writeCliSpawnTrace('spawn.child.stderr.close', {
+            childPid: child.pid,
+        });
+    });
+    writeCliSpawnTrace('spawn.child.started', {
+        childPid: child.pid,
+        command: input.command,
+    });
+    return child;
+};
+const createForwardSignal = (input) => {
+    return (signal) => {
+        writeCliSpawnTrace('spawn.signal.forward.attempt', {
+            childPid: input.child.pid,
+            signal,
+        });
+        try {
+            input.child.kill(signal);
+            writeCliSpawnTrace('spawn.signal.forward.complete', {
+                childPid: input.child.pid,
+                signal,
+            });
+        }
+        catch (error) {
+            writeCliSpawnTrace('spawn.signal.forward.failed', {
+                childPid: input.child.pid,
+                signal,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            const wrapped = ErrorFactory.createTryCatchError('Failed to forward signal to child process', error);
+            try {
+                process.stderr.write(`${String(wrapped.message)}\n`);
+            }
+            catch {
+                // ignore
+            }
+            throw wrapped;
+        }
+    };
+};
+const createSignalHandlers = (input) => {
+    const onSigint = () => {
+        writeCliSpawnTrace('spawn.signal.received', {
+            signal: 'SIGINT',
+            forwardSignals: input.forwardSignals,
+        });
+        if (input.forwardSignals) {
+            input.forwardSignal('SIGINT');
+            return;
+        }
+        input.delayedSignalForwarder.schedule('SIGINT');
+    };
+    const onSigterm = () => {
+        writeCliSpawnTrace('spawn.signal.received', {
+            signal: 'SIGTERM',
+            forwardSignals: input.forwardSignals,
+        });
+        if (input.forwardSignals) {
+            input.forwardSignal('SIGTERM');
+            return;
+        }
+        input.delayedSignalForwarder.schedule('SIGTERM');
+    };
+    return { onSigint, onSigterm };
+};
+const createDelayedSignalForwarder = (input) => {
+    let delayedSignalTimer;
+    let escalationTimer;
+    const clearEscalation = () => {
+        if (escalationTimer === undefined)
+            return;
+        clearTimeout(escalationTimer);
+        escalationTimer = undefined;
+    };
+    const clear = () => {
+        if (delayedSignalTimer !== undefined) {
+            clearTimeout(delayedSignalTimer);
+            delayedSignalTimer = undefined;
+        }
+        clearEscalation();
+        writeCliSpawnTrace('spawn.signal.delay.clear');
+    };
+    const scheduleEscalation = (signal) => {
+        if (escalationTimer !== undefined || input.isChildClosed())
+            return;
+        const nextSignal = signal === 'SIGINT' ? 'SIGTERM' : signal;
+        const escalationDelayMs = Math.max(250, Math.min(1000, input.ttySignalForwardDelayMs));
+        escalationTimer = globalThis.setTimeout(() => {
+            escalationTimer = undefined;
+            if (input.isChildClosed())
+                return;
+            try {
+                writeCliSpawnTrace('spawn.signal.escalation.fire', {
+                    signal: nextSignal,
+                });
+                input.forwardSignal(nextSignal);
+            }
+            catch {
+                // best-effort fallback for interactive watch processes
+            }
+        }, escalationDelayMs);
+        escalationTimer.unref?.();
+    };
+    const schedule = (signal) => {
+        if (input.ttySignalForwardDelayMs <= 0 ||
+            delayedSignalTimer !== undefined ||
+            input.isChildClosed()) {
+            return;
+        }
+        delayedSignalTimer = globalThis.setTimeout(() => {
+            delayedSignalTimer = undefined;
+            if (input.isChildClosed())
+                return;
+            try {
+                writeCliSpawnTrace('spawn.signal.delay.fire', {
+                    signal,
+                });
+                input.forwardSignal(signal);
+                scheduleEscalation(signal);
+            }
+            catch {
+                // best-effort fallback for interactive watch processes
+            }
+        }, input.ttySignalForwardDelayMs);
+        writeCliSpawnTrace('spawn.signal.delay.schedule', {
+            signal,
+            delayMs: input.ttySignalForwardDelayMs,
+        });
+        delayedSignalTimer.unref?.();
+    };
+    return { clear, schedule };
+};
 export const SpawnUtil = Object.freeze({
     async spawnAndWait(input) {
         const cwd = input.cwd ?? process.cwd();
         const resolvedCommand = input.shell === true ? input.command : resolveLocalBin(input.command, cwd);
-        const child = spawn(resolvedCommand, input.args, {
+        const signalHandling = resolveSignalHandling(input);
+        writeCliSpawnTrace('spawn.and-wait.start', {
+            command: resolvedCommand,
+            args: input.args,
+            cwd,
+            shell: input.shell === true,
+            forwardSignals: signalHandling.forwardSignals,
+            ttySignalForwardDelayMs: signalHandling.ttySignalForwardDelayMs,
+        });
+        const child = spawnChildProcess({
+            command: resolvedCommand,
+            args: input.args,
             cwd,
             env: input.env ?? appConfig.getSafeEnv(),
-            stdio: 'inherit',
             shell: input.shell === true,
         });
         // In interactive shells, the foreground process group already receives SIGINT
         // (and often SIGTERM) so forwarding can cause duplicates. `tsx watch` is
         // especially sensitive here and can print "Previous process hasn't exited yet. Force killing...".
-        const forwardSignals = typeof input.forwardSignals === 'boolean' ? input.forwardSignals : !process.stdin.isTTY;
-        const forwardSignal = (signal) => {
-            try {
-                child.kill(signal);
-            }
-            catch (error) {
-                const wrapped = ErrorFactory.createTryCatchError('Failed to forward signal to child process', error);
-                // Best-effort logging; then rethrow (tests/assertions rely on this behavior).
-                try {
-                    process.stderr.write(`${String(wrapped.message)}\n`);
-                }
-                catch {
-                    // ignore
-                }
-                throw wrapped;
-            }
-        };
-        const onSigint = () => {
-            if (forwardSignals) {
-                forwardSignal('SIGINT');
-            }
-            // If not forwarding, handle to prevent the parent from exiting before the child
-            // finishes its graceful shutdown (child receives SIGINT directly in TTY).
-        };
-        const onSigterm = () => {
-            if (forwardSignals) {
-                forwardSignal('SIGTERM');
-            }
-            // Same rationale as SIGINT: keep parent alive while waiting for child to exit.
-        };
+        const forwardSignals = signalHandling.forwardSignals;
+        const ttySignalForwardDelayMs = signalHandling.ttySignalForwardDelayMs;
+        let childClosed = false;
+        const forwardSignal = createForwardSignal({ child });
+        const delayedSignalForwarder = createDelayedSignalForwarder({
+            ttySignalForwardDelayMs,
+            isChildClosed: () => childClosed,
+            forwardSignal,
+        });
+        const { onSigint, onSigterm } = createSignalHandlers({
+            forwardSignals,
+            delayedSignalForwarder,
+            forwardSignal,
+        });
         process.on('SIGINT', onSigint);
         process.on('SIGTERM', onSigterm);
+        writeCliSpawnTrace('spawn.signal.handlers.registered', {
+            childPid: child.pid,
+        });
         try {
-            const result = await new Promise((resolve, reject) => {
-                child.once('error', (error) => {
-                    reject(error);
-                });
-                child.once('close', (code, signal) => {
-                    resolve({ exitCode: code, signal });
+            const result = await waitForChildExit(child, () => {
+                childClosed = true;
+                delayedSignalForwarder.clear();
+                writeCliSpawnTrace('spawn.child.mark-closed', {
+                    childPid: child.pid,
                 });
             });
+            writeCliSpawnTrace('spawn.and-wait.result', {
+                childPid: child.pid,
+                exitCode: result.exitCode,
+                signal: result.signal,
+                normalizedExitCode: getExitCode(result.exitCode, result.signal),
+            });
             return getExitCode(result.exitCode, result.signal);
         }
         catch (error) {
@@ -109,8 +378,12 @@ export const SpawnUtil = Object.freeze({
             throw ErrorFactory.createTryCatchError('Failed to spawn child process', error);
         }
         finally {
+            delayedSignalForwarder.clear();
             process.off('SIGINT', onSigint);
             process.off('SIGTERM', onSigterm);
+            writeCliSpawnTrace('spawn.signal.handlers.removed', {
+                childPid: child.pid,
+            });
         }
     },
 });

package/src/config/index.d.ts

@@ -12,13 +12,13 @@ export { notificationConfig, type NotificationConfig } from './notification';
 export { queueConfig, type QueueConfig } from './queue';
 export { securityConfig } from './security';
 export { storageConfig, type StorageConfig } from './storage';
+export type { MiddlewareConfigType } from './type';
 export { createRedisConnection } from './workers';
 /**
  * Combined configuration object
  * Sealed namespace for immutability
  */
 export declare const config: Readonly<{
-    readonly middleware: import("./type").MiddlewareConfigType;
     readonly app: Readonly<{
         readonly name: string;
         readonly prefix: string;
@@ -211,6 +211,7 @@ export declare const config: Readonly<{
             readonly namespace: string;
         };
     }>;
+    readonly middleware: import("./type").MiddlewareConfigType;
     readonly cache: {
         default: string;
         drivers: import("./type").CacheConfigInput["drivers"];

package/src/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;8BAkC0f,CAAC;;;;;;;;;;;;;;;;;;;;2EA9C3e,CAAA;;;;;;;;;;;;;;;;;;;;8BAD2B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+C8X,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EAHnb,CAAC;AAEZ,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACnF,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;8BAkCgc,CAAC;;;;;;;;;;;;;;;;;;;;iFA/Cjb,CAAA;;;;;;;;;;;;;;;;;;;;8BAD2B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgDoU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;EAHzX,CAAC;AAEZ,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}

package/src/config/index.js

@@ -28,9 +28,6 @@ export { createRedisConnection } from './workers.js';
  * Sealed namespace for immutability
  */
 export const config = Object.freeze({
-    get middleware() {
-        return middlewareConfig;
-    },
     get app() {
         return appConfig;
     },
@@ -52,6 +49,9 @@ export const config = Object.freeze({
     get microservices() {
         return microservicesConfig;
     },
+    get middleware() {
+        return middlewareConfig;
+    },
     get cache() {
         return cacheConfig;
     },

package/src/config/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/config/queue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGhG,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC;IACzC,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH,CAAC,CAAC;AA+EH;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAO,kBA4DnC,CAAC;AAgDH,QAAA,MAAM,iBAAiB,QAAO;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,CAAC,YAAY,EAAE,sBAAsB,KAAK,kBAAkB,CAAC,eAAe,CAAC,CAAC;IACzF,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CAuEH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAqB/D,eAAO,MAAM,WAAW,EAAE,WAYxB,CAAC"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../src/config/queue.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,KAAK,EAAE,sBAAsB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAyChG,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC;IACzC,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH,CAAC,CAAC;AA+EH;;GAEG;AACH,eAAO,MAAM,iBAAiB,QAAO,kBA4DnC,CAAC;AAgDH,QAAA,MAAM,iBAAiB,QAAO;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,SAAS,EAAE,CAAC,YAAY,EAAE,sBAAsB,KAAK,kBAAkB,CAAC,eAAe,CAAC,CAAC;IACzF,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnF,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAClC,WAAW,EAAE,OAAO,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,CAAC;CAuEH,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAqB/D,eAAO,MAAM,WAAW,EAAE,WAYxB,CAAC"}

package/src/config/queue.js

@@ -6,10 +6,39 @@
 import { Cloudflare } from './cloudflare.js';
 import { Env } from './env.js';
 import { Logger } from './logger.js';
-import { isKnownMiddlewareName, middlewareConfig } from './middleware.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
 import { ZintrustLang } from '../lang/lang.js';
 import { StartupConfigFile, StartupConfigFileRegistry } from '../runtime/StartupConfigFileRegistry.js';
+const StaticMiddlewareKeys = Object.freeze({
+    log: true,
+    error: true,
+    security: true,
+    rateLimit: true,
+    sanitizeBody: true,
+    fillRateLimit: true,
+    authRateLimit: true,
+    userMutationRateLimit: true,
+    csrf: true,
+    auth: true,
+    jwt: true,
+    bulletproof: true,
+    validateLogin: true,
+    validateRegister: true,
+    validateUserStore: true,
+    validateUserUpdate: true,
+    validateUserFill: true,
+});
+const isKnownQueueMonitorMiddlewareName = (value) => {
+    return (Object.hasOwn(StaticMiddlewareKeys, value) || /^rateLimit:\d+:\d+(?:\.\d+)?$/.test(value.trim()));
+};
+const getConfiguredQueueMonitorRouteKeys = () => {
+    const middlewareOverrides = StartupConfigFileRegistry.get(StartupConfigFile.Middleware) ?? {};
+    const routeConfig = middlewareOverrides.route;
+    if (typeof routeConfig !== 'object' || routeConfig === null || Array.isArray(routeConfig)) {
+        return new Set();
+    }
+    return new Set(Object.keys(routeConfig));
+};
 const getQueueDriver = (driverConfig) => {
     const driverName = driverConfig.default;
     return driverConfig.drivers[driverName];
@@ -124,9 +153,9 @@ const createBaseMonitor = () => {
         .map((m) => m.trim())
         .filter((m) => m.length > 0);
     if (enabled && middleware.length > 0) {
-        const knownKeys = new Set(Object.keys(middlewareConfig.route ?? {}));
+        const knownKeys = getConfiguredQueueMonitorRouteKeys();
         const unknownKeys = middleware.filter((name) => {
-            return !knownKeys.has(name) && !isKnownMiddlewareName(name);
+            return !knownKeys.has(name) && !isKnownQueueMonitorMiddlewareName(name);
         });
         if (unknownKeys.length > 0) {
             Logger.error('Unknown QUEUE_MONITOR_MIDDLEWARE keys configured', {

package/src/helper/ShutdownTrace.d.ts

@@ -0,0 +1,9 @@
+type ShutdownTraceDetails = Record<string, unknown>;
+export declare const ShutdownTrace: Readonly<{
+    isEnabled: () => boolean;
+    log: (label: string, details?: ShutdownTraceDetails) => void;
+    logHandles: (label: string, details?: ShutdownTraceDetails) => void;
+    logBullMQWorker: (label: string, worker: unknown, details?: ShutdownTraceDetails) => void;
+}>;
+export {};
+//# sourceMappingURL=ShutdownTrace.d.ts.map

package/src/helper/ShutdownTrace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShutdownTrace.d.ts","sourceRoot":"","sources":["../../../src/helper/ShutdownTrace.ts"],"names":[],"mappings":"AAKA,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwMpD,eAAO,MAAM,aAAa;qBAlLJ,OAAO;iBAwFT,MAAM,YAAW,oBAAoB,KAAQ,IAAI;wBAY1C,MAAM,YAAW,oBAAoB,KAAQ,IAAI;6BA6CnE,MAAM,UACL,OAAO,YACN,oBAAoB,KAC5B,IAAI;EAmCL,CAAC"}

package/src/helper/ShutdownTrace.js

@@ -0,0 +1,165 @@
+const TRACE_ENV_KEYS = ['SHUTDOWN_TRACE', 'DEBUG_SHUTDOWN_TRACE', 'WORKER_SHUTDOWN_TRACE'];
+const MAX_HANDLE_DETAILS = 20;
+const writeLine = (line) => {
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess?.stderr && typeof nodeProcess.stderr.write === 'function') {
+        nodeProcess.stderr.write(`${line}\n`);
+        return;
+    }
+    if (typeof console !== 'undefined' && typeof console.info === 'function') {
+        console.info(line);
+    }
+};
+const getNodeProcess = () => {
+    if (typeof process === 'undefined')
+        return null;
+    return process;
+};
+const isEnabled = () => {
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess === null)
+        return false;
+    return TRACE_ENV_KEYS.some((key) => {
+        const raw = nodeProcess.env[key];
+        if (typeof raw !== 'string')
+            return false;
+        const normalized = raw.trim().toLowerCase();
+        return (normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on');
+    });
+};
+const getConstructorName = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return typeof value;
+    const constructorValue = value.constructor;
+    return typeof constructorValue?.name === 'string' ? constructorValue.name : 'Unknown';
+};
+const hasFunction = (value, key) => {
+    return (typeof value === 'object' &&
+        value !== null &&
+        key in value &&
+        typeof value[key] === 'function');
+};
+const getOptionalValue = (value, key) => {
+    if (typeof value !== 'object' || value === null || !(key in value))
+        return undefined;
+    return value[key];
+};
+const summarizeHandle = (handle) => {
+    const constructorName = getConstructorName(handle);
+    const summary = {
+        type: constructorName,
+    };
+    const fd = getOptionalValue(handle, 'fd');
+    if (typeof fd === 'number') {
+        summary['fd'] = fd;
+    }
+    const localPort = getOptionalValue(handle, 'localPort');
+    if (typeof localPort === 'number') {
+        summary['localPort'] = localPort;
+    }
+    const remotePort = getOptionalValue(handle, 'remotePort');
+    if (typeof remotePort === 'number') {
+        summary['remotePort'] = remotePort;
+    }
+    const repeat = getOptionalValue(handle, '_repeat');
+    if (typeof repeat === 'number') {
+        summary['repeatMs'] = repeat;
+    }
+    const destroyed = getOptionalValue(handle, 'destroyed');
+    if (typeof destroyed === 'boolean') {
+        summary['destroyed'] = destroyed;
+    }
+    if (hasFunction(handle, 'hasRef')) {
+        try {
+            summary['hasRef'] = handle.hasRef();
+        }
+        catch {
+            summary['hasRef'] = 'error';
+        }
+    }
+    return summary;
+};
+const countTypes = (items) => {
+    return items.reduce((counts, item) => {
+        const type = getConstructorName(item);
+        counts[type] = (counts[type] ?? 0) + 1;
+        return counts;
+    }, {});
+};
+const log = (label, details = {}) => {
+    if (!isEnabled())
+        return;
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details,
+    }));
+};
+const logHandles = (label, details = {}) => {
+    if (!isEnabled())
+        return;
+    const nodeProcess = getNodeProcess();
+    if (nodeProcess === null) {
+        writeLine(JSON.stringify({
+            level: 'info',
+            trace: 'shutdown',
+            label,
+            details: {
+                ...details,
+                available: false,
+                reason: 'process unavailable',
+            },
+        }));
+        return;
+    }
+    const handles = typeof nodeProcess._getActiveHandles === 'function' ? nodeProcess._getActiveHandles() : [];
+    const requests = typeof nodeProcess._getActiveRequests === 'function' ? nodeProcess._getActiveRequests() : [];
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details: {
+            ...details,
+            available: true,
+            handleCount: handles.length,
+            requestCount: requests.length,
+            handleTypes: countTypes(handles),
+            requestTypes: countTypes(requests),
+            handles: handles.slice(0, MAX_HANDLE_DETAILS).map((handle) => summarizeHandle(handle)),
+            requests: requests.slice(0, MAX_HANDLE_DETAILS).map((request) => summarizeHandle(request)),
+        },
+    }));
+};
+const logBullMQWorker = (label, worker, details = {}) => {
+    if (!isEnabled())
+        return;
+    const name = getOptionalValue(worker, 'name');
+    const opts = getOptionalValue(worker, 'opts');
+    const connection = getOptionalValue(opts, 'connection');
+    const prefix = getOptionalValue(opts, 'prefix');
+    const concurrency = getOptionalValue(opts, 'concurrency');
+    const autorun = getOptionalValue(opts, 'autorun');
+    const closing = getOptionalValue(worker, 'closing');
+    writeLine(JSON.stringify({
+        level: 'info',
+        trace: 'shutdown',
+        label,
+        details: {
+            ...details,
+            workerType: getConstructorName(worker),
+            queueName: typeof name === 'string' ? name : undefined,
+            prefix: typeof prefix === 'string' ? prefix : undefined,
+            concurrency: typeof concurrency === 'number' ? concurrency : undefined,
+            autorun: typeof autorun === 'boolean' ? autorun : undefined,
+            connectionType: getConstructorName(connection),
+            closingState: closing === undefined ? 'idle' : getConstructorName(closing),
+        },
+    }));
+};
+export const ShutdownTrace = Object.freeze({
+    isEnabled,
+    log,
+    logHandles,
+    logBullMQWorker,
+});