@zintrust/core 0.1.40 → 0.1.42

package/src/boot/registry/registerRoute.js

@@ -0,0 +1,96 @@
+import { appConfig } from '../../config/index.js';
+import Logger from '../../config/logger.js';
+import * as path from '../../node-singletons/path.js';
+import { pathToFileURL } from '../../node-singletons/url.js';
+import { detectRuntime } from '../../runtime/detectRuntime.js';
+const isCloudflare = detectRuntime().isCloudflare;
+export const isCompiledJsModule = () => {
+    // When running from dist, this module is compiled to .js and Node ESM resolution
+    // requires explicit file extensions for relative imports.
+    const metaUrl = typeof import.meta?.url === 'string' ? import.meta.url : '';
+    return metaUrl.endsWith('.js');
+};
+export const tryImportOptional = async (modulePath) => {
+    try {
+        return (await import(modulePath));
+    }
+    catch {
+        return undefined;
+    }
+};
+export const tryImportOptionalR = async (modulePath) => {
+    try {
+        return (await import(modulePath));
+    }
+    catch (error) {
+        Logger.error(`Error importing module ${modulePath}:`, error);
+        return undefined;
+    }
+};
+const tryImportRoutesFromAppBase = async (resolvedBasePath) => {
+    if (resolvedBasePath === '')
+        return undefined;
+    const routeCandidates = appConfig.isDevelopment()
+        ? [
+            path.join(resolvedBasePath, 'routes', 'api.ts'),
+            path.join(resolvedBasePath, 'routes', 'api.js'),
+        ]
+        : [
+            path.join(resolvedBasePath, 'routes', 'api.js'),
+            path.join(resolvedBasePath, 'dist', 'routes', 'api.js'),
+            path.join(resolvedBasePath, 'routes', 'api.ts'),
+            path.join(resolvedBasePath, 'dist', 'routes', 'api.ts'),
+        ];
+    for (const routePath of routeCandidates) {
+        try {
+            const url = pathToFileURL(routePath).href;
+            // eslint-disable-next-line no-await-in-loop
+            return (await import(url));
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return undefined;
+};
+const registerAppRoutes = async (resolvedBasePath, router) => {
+    const mod = await tryImportRoutesFromAppBase(resolvedBasePath);
+    if (mod && typeof mod.registerRoutes === 'function') {
+        mod.registerRoutes(router);
+    }
+};
+const registerFrameworkRoutes = async (resolvedBasePath, router) => {
+    const frameworkRoutes = await tryImportRoutesFromAppBase(resolvedBasePath);
+    if (frameworkRoutes && typeof frameworkRoutes.registerRoutes === 'function') {
+        frameworkRoutes.registerRoutes(router);
+    }
+};
+const registerGlobalRoutes = (router) => {
+    const globalRoutes = globalThis.__zintrustRoutes;
+    if (globalRoutes && typeof globalRoutes.registerRoutes === 'function') {
+        globalRoutes.registerRoutes(router);
+    }
+    else {
+        Logger.warn('No app routes found and framework routes are unavailable. Ensure routes/api.ts exists in the project.');
+    }
+};
+export const registerMasterRoutes = async (resolvedBasePath, router) => {
+    try {
+        if (isCloudflare) {
+            registerGlobalRoutes(router);
+        }
+        if (!isCloudflare) {
+            await registerAppRoutes(resolvedBasePath, router);
+        }
+        if (router.routes.length === 0) {
+            await registerFrameworkRoutes(resolvedBasePath, router);
+        }
+        // Always register core framework routes (health, metrics, doc) after app routes
+        // This ensures app can override but core routes always exist
+        const { registerCoreRoutes } = await import('../../routes/CoreRoutes.js');
+        registerCoreRoutes(router);
+    }
+    catch (error) {
+        Logger.error('Failed to register routes:', error);
+    }
+};

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

@@ -0,0 +1,15 @@
+import type { IShutdownManager } from './type';
+import type { IRouter } from '../../index.js';
+export declare const registerFrameworkShutdownHooks: (shutdownManager: IShutdownManager) => void;
+export declare const createLifecycle: (params: {
+    environment: string;
+    resolvedBasePath: string;
+    router: IRouter;
+    shutdownManager: IShutdownManager;
+    getBooted: () => boolean;
+    setBooted: (value: boolean) => void;
+}) => {
+    boot: () => Promise<void>;
+    shutdown: () => Promise<void>;
+};
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/runtime.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAOvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AA+I9C,eAAO,MAAM,8BAA8B,GAAI,iBAAiB,gBAAgB,KAAG,IA4BlF,CAAC;AAyLF,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;CAuE7D,CAAC"}

package/src/boot/registry/runtime.js

@@ -0,0 +1,364 @@
+import * as RuntimeConfig from '../../config/index.js';
+import { StartupHealthChecks } from '../../health/StartupHealthChecks.js';
+import { loadQueueMonitorModule, loadWorkersModule } from '../../runtime/WorkersModule.js';
+import { registerCachesFromRuntimeConfig } from '../../cache/CacheRuntimeRegistration.js';
+import broadcastConfig from '../../config/broadcast.js';
+import { Cloudflare } from '../../config/cloudflare.js';
+import { FeatureFlags } from '../../config/features.js';
+import { Logger } from '../../config/logger.js';
+import notificationConfig from '../../config/notification.js';
+import { StartupConfigValidator } from '../../config/StartupConfigValidator.js';
+import { existsSync } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+import { pathToFileURL } from '../../node-singletons/url.js';
+import { registerDatabasesFromRuntimeConfig } from '../../orm/DatabaseRuntimeRegistration.js';
+import { registerMasterRoutes, tryImportOptional } from './registerRoute.js';
+import { registerWorkerShutdownHook } from './worker.js';
+import { StartupConfigFile, StartupConfigFileRegistry } from '../../runtime/StartupConfigFileRegistry.js';
+import { registerBroadcastersFromRuntimeConfig } from '../../tools/broadcast/BroadcastRuntimeRegistration.js';
+import { registerNotificationChannelsFromRuntimeConfig } from '../../tools/notification/NotificationRuntimeRegistration.js';
+import { registerQueuesFromRuntimeConfig } from '../../tools/queue/QueueRuntimeRegistration.js';
+import { registerDisksFromRuntimeConfig } from '../../tools/storage/StorageRuntimeRegistration.js';
+const loadRuntimeQueueConfig = async () => {
+    try {
+        const modulePath = '@runtime-config/queue';
+        const loaded = (await import(modulePath));
+        return loaded.default ?? queueConfig ?? undefined;
+    }
+    catch {
+        return queueConfig ?? undefined;
+    }
+};
+const readRuntimeConfig = (key, fallback) => {
+    try {
+        const value = RuntimeConfig[key];
+        return (value ?? fallback);
+    }
+    catch {
+        return fallback;
+    }
+};
+const appConfig = readRuntimeConfig('appConfig', { port: 7777, dockerWorker: false });
+const cacheConfig = readRuntimeConfig('cacheConfig', RuntimeConfig.cacheConfig);
+const databaseConfig = readRuntimeConfig('databaseConfig', {
+    default: 'sqlite',
+    connections: {},
+});
+const queueConfig = readRuntimeConfig('queueConfig', RuntimeConfig.queueConfig);
+const storageConfig = readRuntimeConfig('storageConfig', RuntimeConfig.storageConfig);
+// eslint-disable-next-line @typescript-eslint/require-await
+const dbLoader = async () => {
+    registerDatabasesFromRuntimeConfig(databaseConfig);
+};
+const queuesLoader = async () => {
+    await registerQueuesFromRuntimeConfig(queueConfig);
+};
+// eslint-disable-next-line @typescript-eslint/require-await
+const cachesLoader = async () => {
+    registerCachesFromRuntimeConfig(cacheConfig);
+};
+const registerFromRuntimeConfig = async () => {
+    await dbLoader();
+    await queuesLoader();
+    await cachesLoader();
+    registerBroadcastersFromRuntimeConfig({
+        default: broadcastConfig.default,
+        drivers: broadcastConfig.drivers,
+    });
+    registerDisksFromRuntimeConfig(storageConfig);
+    registerNotificationChannelsFromRuntimeConfig({
+        default: notificationConfig.default,
+        drivers: notificationConfig.drivers,
+    });
+};
+/**
+ * Helper: Register ConnectionManager shutdown hook
+ */
+const registerConnectionManagerHook = (shutdownManager) => {
+    shutdownManager.add(async () => {
+        try {
+            const mod = await import('../../orm/ConnectionManager.js');
+            await mod.ConnectionManager.shutdownIfInitialized();
+        }
+        catch {
+            /* ignore import failures in restrictive runtimes */
+        }
+    });
+};
+/**
+ * Helper: Register Database reset hook
+ */
+const registerDatabaseResetHook = (shutdownManager) => {
+    shutdownManager.add(async () => {
+        try {
+            const mod = await import('../../orm/Database.js');
+            mod.resetDatabase();
+        }
+        catch {
+            /* ignore import failures in restrictive runtimes */
+        }
+    });
+};
+/**
+ * Helper: Register generic reset hook for modules with reset() method
+ */
+const registerResetHook = (shutdownManager, modulePath, exportName) => {
+    shutdownManager.add(async () => {
+        try {
+            const mod = (await import(modulePath));
+            const resetModule = mod[exportName];
+            if (resetModule?.reset) {
+                resetModule.reset();
+            }
+        }
+        catch {
+            /* ignore import failures in restrictive runtimes */
+        }
+    });
+};
+/**
+ * Helper: Register FileLogWriter flush hook
+ */
+const registerFileLogFlushHook = (shutdownManager) => {
+    shutdownManager.add(async () => {
+        try {
+            const mod = await import('../../config/FileLogWriter.js');
+            mod.FileLogWriter.flush();
+        }
+        catch {
+            /* ignore import failures in restrictive runtimes */
+        }
+    });
+};
+export const registerFrameworkShutdownHooks = (shutdownManager) => {
+    // Register framework-level shutdown hooks for long-lived resources
+    registerConnectionManagerHook(shutdownManager);
+    // Ensure worker management system is asked to shutdown BEFORE databases are reset
+    registerWorkerShutdownHook(shutdownManager);
+    // Database and cache reset
+    registerDatabaseResetHook(shutdownManager);
+    registerResetHook(shutdownManager, '@cache/Cache', 'Cache');
+    // File logging
+    registerFileLogFlushHook(shutdownManager);
+    // Registry resets
+    registerResetHook(shutdownManager, '@broadcast/BroadcastRegistry', 'BroadcastRegistry');
+    registerResetHook(shutdownManager, '@storage/StorageDiskRegistry', 'StorageDiskRegistry');
+    registerResetHook(shutdownManager, '@notification/NotificationChannelRegistry', 'NotificationChannelRegistry');
+    registerResetHook(shutdownManager, '@mail/MailDriverRegistry', 'MailDriverRegistry');
+    registerResetHook(shutdownManager, '@tools/queue/Queue', 'Queue');
+};
+const initializeArtifactDirectories = async (resolvedBasePath) => {
+    if (resolvedBasePath === '')
+        return;
+    if (typeof process === 'undefined')
+        return;
+    const globalAny = globalThis;
+    if (globalAny.CF !== undefined)
+        return;
+    if (typeof globalAny.WebSocketPair === 'function')
+        return;
+    if (globalAny.caches !== undefined)
+        return;
+    let nodeFs;
+    try {
+        nodeFs = await import('../../node-singletons/fs.js');
+    }
+    catch {
+        return;
+    }
+    const dirs = ['logs', 'storage', 'tmp'];
+    for (const dir of dirs) {
+        const fullPath = path.join(resolvedBasePath, dir);
+        try {
+            if (!nodeFs.existsSync(fullPath)) {
+                nodeFs.mkdirSync(fullPath, { recursive: true });
+                Logger.info(`✓ Created directory: ${dir}`);
+            }
+        }
+        catch (error) {
+            Logger.warn(`Failed to create ${dir} directory`, error);
+        }
+    }
+};
+const extractRedisConfigFromQueueConfig = () => {
+    const redisConfig = queueConfig.drivers?.redis ?? {};
+    const redisHost = typeof redisConfig['host'] === 'string' ? redisConfig['host'] : '127.0.0.1';
+    const redisPort = typeof redisConfig['port'] === 'number' && Number.isFinite(redisConfig['port'])
+        ? redisConfig['port']
+        : 6379;
+    const redisPassword = typeof redisConfig['password'] === 'string' ? redisConfig['password'] : '';
+    const redisDb = typeof redisConfig['database'] === 'number' && Number.isFinite(redisConfig['database'])
+        ? redisConfig['database']
+        : 0;
+    return {
+        host: redisHost,
+        port: redisPort,
+        password: redisPassword,
+        db: redisDb,
+    };
+};
+const loadAndValidateQueueMonitorModule = async () => {
+    let workersModule;
+    try {
+        workersModule = (await loadQueueMonitorModule());
+    }
+    catch (error) {
+        Logger.warn('Failed to load Queue Monitor module', error);
+        return null;
+    }
+    if (!workersModule || !('QueueMonitor' in workersModule)) {
+        Logger.warn('Queue Monitor module not available');
+        return null;
+    }
+    const queueMonitorModule = workersModule;
+    const { QueueMonitor } = queueMonitorModule;
+    if (QueueMonitor === undefined || typeof QueueMonitor.create !== 'function') {
+        Logger.warn('Queue Monitor module does not expose QueueMonitor.create');
+        return null;
+    }
+    return queueMonitorModule;
+};
+const initializeQueueMonitor = async (router) => {
+    const runQueueConfig = await loadRuntimeQueueConfig();
+    const monitorConfig = runQueueConfig?.monitor;
+    if (monitorConfig === undefined) {
+        return;
+    }
+    if (monitorConfig.enabled === false) {
+        return;
+    }
+    const queueMonitorModule = await loadAndValidateQueueMonitorModule();
+    if (queueMonitorModule === null) {
+        Logger.debug('Queue Monitor is enabled in configuration but module failed to load or is invalid. Skipping Queue Monitor initialization.');
+        return;
+    }
+    const redisConfig = extractRedisConfigFromQueueConfig();
+    const { QueueMonitor } = queueMonitorModule;
+    const monitor = QueueMonitor.create({
+        ...monitorConfig,
+        redis: redisConfig,
+    });
+    try {
+        monitor.registerRoutes(router);
+    }
+    catch (error) {
+        Logger.error('Failed to register Queue Monitor routes', error);
+    }
+    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`);
+};
+const initializeWorkers = async (router) => {
+    const workers = await loadWorkersModule();
+    if (workers?.WorkerInit !== undefined && typeof workers.registerWorkerRoutes === 'function') {
+        workers.registerWorkerRoutes(router, undefined, { middleware: undefined });
+    }
+};
+const resolveLocalQueueRedisEntry = () => {
+    if (typeof process === 'undefined' || typeof process.cwd !== 'function')
+        return null;
+    const cwd = process.cwd();
+    if (cwd.trim() === '')
+        return null;
+    const localEntry = path.join(cwd, 'dist', 'packages', 'queue-redis', 'src', 'index.js');
+    return existsSync(localEntry) ? localEntry : null;
+};
+const loadQueueHttpGatewayModule = async () => {
+    try {
+        return (await import('@zintrust/queue-redis'));
+    }
+    catch {
+        const localEntry = resolveLocalQueueRedisEntry();
+        if (localEntry === null)
+            return undefined;
+        const url = pathToFileURL(localEntry).href;
+        return (await import(url));
+    }
+};
+const initializeQueueHttpGateway = async (router) => {
+    try {
+        const module = await loadQueueHttpGatewayModule();
+        if (module === undefined) {
+            Logger.warn('Queue HTTP gateway module is unavailable (@zintrust/queue-redis not found)');
+            return;
+        }
+        if (module.QueueHttpGateway === undefined ||
+            typeof module.QueueHttpGateway.create !== 'function') {
+            Logger.warn('Queue HTTP gateway module does not expose QueueHttpGateway.create');
+            return;
+        }
+        module.QueueHttpGateway.create().registerRoutes(router);
+        Logger.info('Queue HTTP gateway route registered at /api/_sys/queue/rpc');
+    }
+    catch (error) {
+        Logger.warn('Failed to register Queue HTTP gateway routes', error);
+    }
+};
+const initializeScheduleHttpGateway = async (router) => {
+    try {
+        const { ScheduleHttpGateway } = await import('../../scheduler/ScheduleHttpGateway.js');
+        ScheduleHttpGateway.create().registerRoutes(router);
+        Logger.info('Schedule HTTP gateway route registered at /api/_sys/schedule/rpc');
+    }
+    catch (error) {
+        Logger.warn('Failed to register Schedule HTTP gateway routes', error);
+    }
+};
+export const createLifecycle = (params) => {
+    const boot = async () => {
+        if (params.getBooted())
+            return;
+        Logger.info(`🚀 Booting ZinTrust Application in ${params.environment} mode...`);
+        if (params.environment === 'development') {
+            // Clear config registry cache to ensure fresh config loading in watch mode
+            // This fixes the issue where config/middleware.ts changes are ignored in watch mode
+            StartupConfigFileRegistry.clear();
+        }
+        StartupConfigValidator.assertValid();
+        // Preload project-owned config overrides that must be available synchronously.
+        await StartupConfigFileRegistry.preload([
+            StartupConfigFile.Middleware,
+            StartupConfigFile.Cache,
+            StartupConfigFile.Database,
+            StartupConfigFile.Queue,
+            StartupConfigFile.Storage,
+            StartupConfigFile.Mail,
+            StartupConfigFile.Broadcast,
+            StartupConfigFile.Notification,
+        ]);
+        FeatureFlags.initialize();
+        await StartupHealthChecks.assertHealthy();
+        await registerFromRuntimeConfig();
+        await initializeArtifactDirectories(params.resolvedBasePath);
+        await registerMasterRoutes(params.resolvedBasePath, params.router);
+        if (Cloudflare.getWorkersEnv() === null && appConfig.dockerWorker === false) {
+            await initializeWorkers(params.router);
+            await initializeQueueMonitor(params.router);
+            await initializeQueueHttpGateway(params.router);
+            await initializeScheduleHttpGateway(params.router);
+        }
+        // Register service providers
+        // Bootstrap services
+        Logger.info('✅ Application booted successfully');
+        params.setBooted(true);
+    };
+    const shutdown = async () => {
+        Logger.info('🛑 Shutting down application...');
+        try {
+            await params.shutdownManager.run();
+        }
+        catch (error) {
+            Logger.error('Shutdown hook failed:', error);
+        }
+        // Ensure FileLogWriter.flush is attempted even if dynamic registration failed.
+        try {
+            const fileLogWriter = await tryImportOptional('@config/FileLogWriter');
+            fileLogWriter?.FileLogWriter?.flush?.();
+        }
+        catch {
+            /* best-effort */
+        }
+        params.setBooted(false);
+        Logger.info('✅ Application shut down successfully');
+    };
+    return { boot, shutdown };
+};

package/src/boot/registry/type.d.ts

@@ -0,0 +1,25 @@
+import type { IMiddlewareStack } from '../../middleware';
+import type { IServiceContainer } from '../../container/ServiceContainer';
+import type { IRouter } from '../../routes/Router';
+export interface IApplication {
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+    isBooted(): boolean;
+    isDevelopment(): boolean;
+    isProduction(): boolean;
+    isTesting(): boolean;
+    getEnvironment(): string;
+    getRouter(): IRouter;
+    getContainer(): IServiceContainer;
+    getMiddlewareStack(): IMiddlewareStack;
+    getBasePath(): string;
+}
+export type RoutesModule = {
+    registerRoutes?: (r: IRouter) => void;
+};
+export type ShutdownHook = () => void | Promise<void>;
+export interface IShutdownManager {
+    add(hook: ShutdownHook): void;
+    run(): Promise<void>;
+}
+//# sourceMappingURL=type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../../../src/boot/registry/type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,IAAI,OAAO,CAAC;IACpB,aAAa,IAAI,OAAO,CAAC;IACzB,YAAY,IAAI,OAAO,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC;IACrB,cAAc,IAAI,MAAM,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IACvC,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB"}

package/src/boot/registry/type.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+import type { IShutdownManager } from './type';
+/**
+ * Helper: Register Worker management system shutdown hook
+ */
+export declare const registerWorkerShutdownHook: (shutdownManager: IShutdownManager) => Promise<void>;
+//# sourceMappingURL=worker.d.ts.map

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

@@ -0,0 +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"}

package/src/boot/registry/worker.js

@@ -0,0 +1,35 @@
+import { appConfig } from '../../config/app.js';
+import { Env } from '../../config/env.js';
+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 ||
+        appConfig.dockerWorker === true) {
+        return Promise.resolve(); // NOSONAR - Skip worker shutdown hook registration
+    }
+    // Ensure worker management system is asked to shutdown BEFORE databases are reset.
+    // This prevents workers from trying to access DB connections that have already
+    // been closed by subsequent shutdown hooks.
+    shutdownManager.add(async () => {
+        try {
+            const mod = (await loadWorkersModule());
+            const isShuttingDown = typeof mod.WorkerShutdown.isShuttingDown === 'function'
+                ? mod.WorkerShutdown.isShuttingDown()
+                : (mod.WorkerShutdown.getShutdownState?.().isShuttingDown ?? false);
+            const completedAt = mod.WorkerShutdown.getShutdownState?.().completedAt ?? null;
+            if (isShuttingDown || completedAt !== null)
+                return;
+            await mod.WorkerShutdown.shutdown({
+                signal: 'APP_SHUTDOWN',
+                timeout: 5000,
+                forceExit: false,
+            });
+        }
+        catch {
+            /* ignore import failures in restrictive runtimes */
+        }
+    });
+    return Promise.resolve(); // NOSONAR
+};

package/src/cache/drivers/KVRemoteDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KVRemoteDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/KVRemoteDriver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsBtD,eAAO,MAAM,cAAc;cACf,WAAW;EAiErB,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"KVRemoteDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/KVRemoteDriver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAiCtD,eAAO,MAAM,cAAc;cACf,WAAW;EAkErB,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/cache/drivers/KVRemoteDriver.js

@@ -6,13 +6,25 @@
 import { RemoteSignedJson } from '../../common/RemoteSignedJson.js';
 import { Env } from '../../config/env.js';
 import { Logger } from '../../config/logger.js';
+const resolveSigningPrefix = (baseUrl) => {
+    try {
+        const parsed = new URL(baseUrl);
+        const path = parsed.pathname.endsWith('/') ? parsed.pathname.slice(0, -1) : parsed.pathname;
+        if (path === '' || path === '/')
+            return undefined;
+        return path;
+    }
+    catch {
+        return undefined;
+    }
+};
 const normalizeNamespace = (defaultNamespace) => defaultNamespace.trim() === '' ? undefined : defaultNamespace;
 export const KVRemoteDriver = Object.freeze({
     create() {
         const settings = {
             baseUrl: Env.get('KV_REMOTE_URL'),
             keyId: Env.get('KV_REMOTE_KEY_ID'),
-            secret: Env.get('KV_REMOTE_SECRET'),
+            secret: Env.get('KV_REMOTE_SECRET', Env.APP_KEY),
             defaultNamespace: Env.get('KV_REMOTE_NAMESPACE'),
             timeoutMs: Env.getInt('ZT_PROXY_TIMEOUT_MS', Env.REQUEST_TIMEOUT),
         };
@@ -21,6 +33,7 @@ export const KVRemoteDriver = Object.freeze({
             keyId: settings.keyId,
             secret: settings.secret,
             timeoutMs: settings.timeoutMs,
+            signaturePathPrefixToStrip: resolveSigningPrefix(settings.baseUrl),
             missingUrlMessage: 'KV remote proxy URL is missing (KV_REMOTE_URL)',
             missingCredentialsMessage: 'KV remote signing credentials are missing (KV_REMOTE_KEY_ID / KV_REMOTE_SECRET)',
             messages: {

package/src/cli/CLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA0CH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AA2MD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}
+{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AAuPD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}