@zintrust/core 1.5.3 → 1.5.5

package/src/boot/bootstrap.js

@@ -11,6 +11,7 @@ import { Env } from '../config/env.js';
 import { Logger } from '../config/logger.js';
 import { shutdownRedisConnections } from '../config/workers.js';
 import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { ShutdownTrace } from '../helper/ShutdownTrace.js';
 import { ProjectRuntime } from '../runtime/ProjectRuntime.js';
 import { StartupErrorLogging } from '../runtime/StartupErrorLogging.js';
 import { WorkerProjectAutoImports } from '../runtime/WorkerProjectAutoImports.js';
@@ -92,66 +93,130 @@ const withTimeout = async (promise, timeoutMs, label) => {
             globalThis.clearTimeout(timeoutId);
     }
 };
+const shutdownWorkersIfNeeded = async (signal, remainingMs) => {
+    if (appConfig.worker !== true ||
+        (appConfig.detectRuntime() !== 'nodejs' && appConfig.detectRuntime() !== 'lambda') ||
+        appConfig.dockerWorker === true) {
+        return;
+    }
+    try {
+        ShutdownTrace.log('bootstrap.graceful-shutdown.worker-shutdown.start', {
+            signal,
+            remainingMs: remainingMs(),
+        });
+        const workers = await loadWorkersModule();
+        const workerBudgetMs = Math.min(15000, remainingMs());
+        await withTimeout(workers.WorkerShutdown.shutdown({
+            signal,
+            timeout: workerBudgetMs,
+            forceExit: false,
+        }), workerBudgetMs, 'Worker shutdown timed out');
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.worker-shutdown.complete', {
+            workerBudgetMs,
+            remainingMs: remainingMs(),
+        });
+    }
+    catch (error) {
+        Logger.warn('Worker shutdown failed (continuing with app shutdown)', error);
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.worker-shutdown.failed', {
+            remainingMs: remainingMs(),
+        });
+    }
+};
+const shutdownServerIfNeeded = async (remainingMs) => {
+    if (serverInstance === undefined)
+        return;
+    ShutdownTrace.log('bootstrap.graceful-shutdown.server-close.start', {
+        remainingMs: remainingMs(),
+    });
+    await serverInstance.close();
+    ShutdownTrace.logHandles('bootstrap.graceful-shutdown.server-close.complete', {
+        remainingMs: remainingMs(),
+    });
+};
+const shutdownAppIfNeeded = async (remainingMs) => {
+    if (appInstance === undefined)
+        return;
+    try {
+        const appBudgetMs = Math.min(5000, remainingMs());
+        ShutdownTrace.log('bootstrap.graceful-shutdown.app-shutdown.start', {
+            appBudgetMs,
+            remainingMs: remainingMs(),
+        });
+        await withTimeout(appInstance.shutdown(), appBudgetMs, 'App shutdown timed out');
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.app-shutdown.complete', {
+            appBudgetMs,
+            remainingMs: remainingMs(),
+        });
+    }
+    catch (error) {
+        Logger.warn('App shutdown failed or timed out, forcing exit', error);
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.app-shutdown.failed', {
+            remainingMs: remainingMs(),
+        });
+    }
+};
+const shutdownTrackedRedis = async (remainingMs) => {
+    try {
+        const redisBudgetMs = Math.max(250, Math.min(3000, remainingMs()));
+        ShutdownTrace.log('bootstrap.graceful-shutdown.redis-shutdown.start', {
+            redisBudgetMs,
+            remainingMs: remainingMs(),
+        });
+        await withTimeout(shutdownRedisConnections(), redisBudgetMs, 'Redis connection shutdown timed out');
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.redis-shutdown.complete', {
+            redisBudgetMs,
+            remainingMs: remainingMs(),
+        });
+    }
+    catch (error) {
+        Logger.warn('Redis connection shutdown failed (continuing with app shutdown)', error);
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.redis-shutdown.failed', {
+            remainingMs: remainingMs(),
+        });
+    }
+};
+const runGracefulShutdownPhases = async (signal, remainingMs) => {
+    await shutdownWorkersIfNeeded(signal, remainingMs);
+    await shutdownServerIfNeeded(remainingMs);
+    await shutdownAppIfNeeded(remainingMs);
+    await shutdownTrackedRedis(remainingMs);
+    Logger.info('✅ Application shut down successfully');
+    ShutdownTrace.logHandles('bootstrap.graceful-shutdown.complete', {
+        remainingMs: remainingMs(),
+    });
+};
 const gracefulShutdown = async (signal) => {
     if (isShuttingDown)
         return;
     isShuttingDown = true;
-    const shutdownBudgetMs = Env.getInt('SHUTDOWN_TIMEOUT', 1500);
+    const shutdownBudgetMs = Env.getInt('SHUTDOWN_TIMEOUT', 10000);
     const minForceExitMs = shutdownBudgetMs + 250;
     const forceExitMs = Math.max(Env.getInt('SHUTDOWN_FORCE_EXIT_MS', 10000), minForceExitMs);
     const deadlineMs = Date.now() + shutdownBudgetMs;
     const remainingMs = () => Math.max(0, deadlineMs - Date.now());
     Logger.info(`${signal} received, shutting down gracefully...`);
+    ShutdownTrace.logHandles('bootstrap.graceful-shutdown.received', {
+        signal,
+        shutdownBudgetMs,
+        forceExitMs,
+        workerEnabled: appConfig.worker,
+    });
     try {
         const forceExitTimer = globalThis.setTimeout(() => {
             process.exit(0);
         }, forceExitMs);
         // Best-effort: don't keep the process alive just for this timer
         forceExitTimer.unref?.();
-        await withTimeout((async () => {
-            // Shutdown worker management system FIRST (before database closes)
-            if (appConfig.worker === true &&
-                (appConfig.detectRuntime() === 'nodejs' || appConfig.detectRuntime() === 'lambda') &&
-                appConfig.dockerWorker === false) {
-                try {
-                    const workers = await loadWorkersModule();
-                    const workerBudgetMs = Math.min(15000, remainingMs());
-                    await withTimeout(workers.WorkerShutdown.shutdown({
-                        signal,
-                        timeout: workerBudgetMs,
-                        forceExit: false,
-                    }), workerBudgetMs, 'Worker shutdown timed out');
-                }
-                catch (error) {
-                    Logger.warn('Worker shutdown failed (continuing with app shutdown)', error);
-                }
-            }
-            if (serverInstance !== undefined) {
-                await serverInstance.close();
-            }
-            if (appInstance !== undefined) {
-                try {
-                    const appBudgetMs = Math.min(5000, remainingMs());
-                    await withTimeout(appInstance.shutdown(), appBudgetMs, 'App shutdown timed out');
-                }
-                catch (error) {
-                    Logger.warn('App shutdown failed or timed out, forcing exit', error);
-                }
-            }
-            try {
-                const redisBudgetMs = Math.max(250, Math.min(3000, remainingMs()));
-                await withTimeout(shutdownRedisConnections(), redisBudgetMs, 'Redis connection shutdown timed out');
-            }
-            catch (error) {
-                Logger.warn('Redis connection shutdown failed (continuing with app shutdown)', error);
-            }
-            Logger.info('✅ Application shut down successfully');
-        })(), shutdownBudgetMs, 'Graceful shutdown timed out');
+        await withTimeout(runGracefulShutdownPhases(signal, remainingMs), shutdownBudgetMs, 'Graceful shutdown timed out');
         globalThis.clearTimeout(forceExitTimer);
         process.exit(0);
     }
     catch (error) {
         Logger.error('Graceful shutdown failed:', error);
+        ShutdownTrace.logHandles('bootstrap.graceful-shutdown.error', {
+            error: error instanceof Error ? error.message : String(error),
+        });
         process.exit(1);
     }
 };
@@ -283,15 +348,20 @@ const BootstrapFunctions = Object.freeze({
         });
     },
 });
-// Run bootstrap
-await BootstrapFunctions.start().catch((error) => {
+const startBootstrap = async () => {
     try {
-        Logger.error('Failed to bootstrap application:', error);
+        await BootstrapFunctions.start();
+        BootstrapFunctions.setupShutdownHandler();
     }
-    catch {
-        // best-effort logging
+    catch (error) {
+        try {
+            Logger.error('Failed to bootstrap application:', error);
+        }
+        catch {
+            // best-effort logging
+        }
+        process.exit(1);
     }
-    process.exit(1);
-});
-// Handle graceful shutdown
-BootstrapFunctions.setupShutdownHandler();
+};
+// Run bootstrap without parse-time top-level await so Worker bundles can load this module.
+export const bootstrapReady = startBootstrap();

package/src/boot/registry/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/runtime.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AASvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AA+P9C,eAAO,MAAM,8BAA8B,GAAI,iBAAiB,gBAAgB,KAAG,IA6BlF,CAAC;AAwUF,eAAO,MAAM,eAAe,GAAI,QAAQ;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,gBAAgB,CAAC;IAClC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,KAAG;IAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAyF7D,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/runtime.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAUvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAkQ9C,eAAO,MAAM,8BAA8B,GAAI,iBAAiB,gBAAgB,KAAG,IA6BlF,CAAC;AA8UF,eAAO,MAAM,eAAe,GAAI,QAAQ;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,gBAAgB,CAAC;IAClC,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,KAAG;IAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAsH7D,CAAC"}

package/src/boot/registry/runtime.js

@@ -11,7 +11,7 @@ import { Logger } from '../../config/logger.js';
 import notificationConfig from '../../config/notification.js';
 import { StartupConfigValidator } from '../../config/StartupConfigValidator.js';
 import { ErrorFactory } from '../../exceptions/ZintrustError.js';
-import { isNonEmptyString } from '../../helper/index.js';
+import { isNonEmptyString, ShutdownTrace } from '../../helper/index.js';
 import { existsSync } from '../../node-singletons/fs.js';
 import * as path from '../../node-singletons/path.js';
 import { pathToFileURL } from '../../node-singletons/url.js';
@@ -23,6 +23,7 @@ import { SocketFeature } from '../../sockets/SocketRuntime.js';
 import { SocketRuntimeRegistry } from '../../sockets/SocketRuntimeRegistry.js';
 import { registerBroadcastersFromRuntimeConfig } from '../../tools/broadcast/BroadcastRuntimeRegistration.js';
 import { registerNotificationChannelsFromRuntimeConfig } from '../../tools/notification/NotificationRuntimeRegistration.js';
+import { QueueReliabilityOrchestrator } from '../../tools/queue/QueueReliabilityOrchestrator.js';
 import { registerQueuesFromRuntimeConfig } from '../../tools/queue/QueueRuntimeRegistration.js';
 import { registerDisksFromRuntimeConfig } from '../../tools/storage/StorageRuntimeRegistration.js';
 const importFromExistingCandidates = async (moduleCandidates) => {
@@ -332,6 +333,10 @@ const initializeQueueMonitor = async (router) => {
         knownQueues: resolveKnownQueues,
         redis: redisConfig,
     });
+    runtimeQueueMonitor = monitor;
+    ShutdownTrace.logHandles('runtime.queue-monitor.created', {
+        basePath: monitorConfig.basePath ?? '',
+    });
     try {
         monitor.registerRoutes(router);
     }
@@ -341,6 +346,7 @@ const initializeQueueMonitor = async (router) => {
     Logger.info(`Queue Monitor routes registered at http://127.0.0.1:${appConfig.port}${monitorConfig.basePath ?? ''}`);
     Logger.info(`Queue Monitor enqueue endpoint at http://127.0.0.1:${appConfig.port}/test/enqueue`);
 };
+let runtimeQueueMonitor = null;
 const initializeWorkers = async (router) => {
     const workers = await loadWorkersModule({ allowWhenDisabled: true });
     if (workers?.WorkerInit !== undefined && typeof workers.registerWorkerRoutes === 'function') {
@@ -528,7 +534,12 @@ export const createLifecycle = (params) => {
         initializeSockets(params.router);
         await initializeSystemTrace(params.router);
         if (Cloudflare.getWorkersEnv() === null && appConfig.dockerWorker === false) {
-            await initializeWorkers(params.router);
+            if (appConfig.worker === true) {
+                await initializeWorkers(params.router);
+            }
+            else {
+                Logger.info('Skipping worker route registration (WORKER_ENABLED=false).');
+            }
             await initializeQueueMonitor(params.router);
             if (appConfig.worker === true) {
                 await initializeQueueHttpGateway(params.router);
@@ -548,11 +559,34 @@ export const createLifecycle = (params) => {
     };
     const shutdown = async () => {
         Logger.info('🛑 Shutting down application...');
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.start');
+        QueueReliabilityOrchestrator.stop();
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.after-queue-reliability-stop');
+        if (runtimeQueueMonitor !== null && typeof runtimeQueueMonitor.close === 'function') {
+            try {
+                ShutdownTrace.log('runtime.lifecycle.shutdown.queue-monitor-close.start');
+                await runtimeQueueMonitor.close();
+                ShutdownTrace.logHandles('runtime.lifecycle.shutdown.queue-monitor-close.complete');
+            }
+            catch (error) {
+                Logger.warn('Queue Monitor shutdown failed', error);
+                ShutdownTrace.logHandles('runtime.lifecycle.shutdown.queue-monitor-close.failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                runtimeQueueMonitor = null;
+            }
+        }
         try {
             await params.shutdownManager.run();
+            ShutdownTrace.logHandles('runtime.lifecycle.shutdown.after-hooks');
         }
         catch (error) {
             Logger.error('Shutdown hook failed:', error);
+            ShutdownTrace.logHandles('runtime.lifecycle.shutdown.hooks-failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
         }
         // Ensure FileLogWriter.flush is attempted even if dynamic registration failed.
         try {
@@ -563,6 +597,7 @@ export const createLifecycle = (params) => {
             /* best-effort */
         }
         params.setBooted(false);
+        ShutdownTrace.logHandles('runtime.lifecycle.shutdown.complete');
     };
     return { boot, shutdown };
 };

package/src/boot/registry/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,iBAAiB,gBAAgB,KAChC,OAAO,CAAC,IAAI,CA0Cd,CAAC"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/worker.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,GACrC,iBAAiB,gBAAgB,KAChC,OAAO,CAAC,IAAI,CA2Cd,CAAC"}

package/src/boot/registry/worker.js

@@ -5,7 +5,8 @@ import { loadWorkersModule } from '../../runtime/WorkersModule.js';
  * Helper: Register Worker management system shutdown hook
  */
 export const registerWorkerShutdownHook = async (shutdownManager) => {
-    if (Env.getBool('WORKER_SHUTDOWN_ON_APP_EXIT', true) === false ||
+    if (appConfig.worker !== true ||
+        Env.getBool('WORKER_SHUTDOWN_ON_APP_EXIT', true) === false ||
         appConfig.dockerWorker === true) {
         return Promise.resolve(); // NOSONAR - Skip worker shutdown hook registration
     }
@@ -17,7 +18,7 @@ export const registerWorkerShutdownHook = async (shutdownManager) => {
             const mod = (await loadWorkersModule());
             const isShuttingDown = typeof mod.WorkerShutdown.isShuttingDown === 'function'
                 ? mod.WorkerShutdown.isShuttingDown()
-                : mod.WorkerShutdown.getShutdownState?.().isShuttingDown ?? false;
+                : (mod.WorkerShutdown.getShutdownState?.().isShuttingDown ?? false);
             const completedAt = mod.WorkerShutdown.getShutdownState?.().completedAt ?? null;
             if (isShuttingDown || completedAt !== null)
                 return;

package/src/cli/commands/StartCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsgCvF,eAAO,MAAM,YAAY;cACb,YAAY;;mCA18BU,MAAM,KAAG,OAAO;4CAaP,MAAM,KAAG,MAAM;4CA4Bf,MAAM,KAAG,OAAO;sCAetB,MAAM,WAAW,MAAM,KAAG,OAAO;oCAmBnC,MAAM,KAAG,OAAO;;EA06BjD,CAAC"}
+{"version":3,"file":"StartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/StartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAugCvF,eAAO,MAAM,YAAY;cACb,YAAY;;mCA38BU,MAAM,KAAG,OAAO;4CAaP,MAAM,KAAG,MAAM;4CA4Bf,MAAM,KAAG,OAAO;sCAetB,MAAM,WAAW,MAAM,KAAG,OAAO;oCAmBnC,MAAM,KAAG,OAAO;;EA26BjD,CAAC"}

package/src/cli/commands/StartCommand.js

@@ -635,6 +635,7 @@ const executeNodeStart = async (cmd, context, mode, watchEnabled, _port) => {
             command: dev.command,
             args: dev.args,
             forwardSignals: false,
+            ttySignalForwardDelayMs: 1500,
             env: {
                 ...buildStartEnv(context.projectRoot),
                 ZINTRUST_BOOTSTRAP_PREFERENCE: 'source',

package/src/cli/utils/spawn.d.ts

@@ -4,6 +4,7 @@ export interface SpawnAndWaitInput {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     forwardSignals?: boolean;
+    ttySignalForwardDelayMs?: number;
     shell?: boolean;
 }
 export declare const SpawnUtil: Readonly<{

package/src/cli/utils/spawn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/spawn.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAiDD,eAAO,MAAM,SAAS;wBACM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;EAiF7D,CAAC"}
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/cli/utils/spawn.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAyYD,eAAO,MAAM,SAAS;wBACM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;EA8E7D,CAAC"}