@zintrust/core 0.1.28 → 0.1.30

package/src/boot/Application.js

@@ -0,0 +1,351 @@
+/**
+ * Application - Framework core entry point
+ * Handles application lifecycle, booting, and environment
+ */
+import { appConfig, cacheConfig, databaseConfig, queueConfig, storageConfig } from '../config/index.js';
+import { ServiceContainer } from '../container/ServiceContainer.js';
+import { StartupHealthChecks } from '../health/StartupHealthChecks.js';
+import { MiddlewareStack } from '../middleware/MiddlewareStack.js';
+import broadcastConfig from '../config/broadcast.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 { Router } from '../routes/Router.js';
+import * as path from '../node-singletons/path.js';
+import { pathToFileURL } from '../node-singletons/url.js';
+import { StartupConfigFile, StartupConfigFileRegistry } from '../runtime/StartupConfigFileRegistry.js';
+const ShutdownManager = Object.freeze({
+    create() {
+        const hooks = [];
+        return Object.freeze({
+            add(hook) {
+                hooks.push(hook);
+            },
+            async run() {
+                for (const hook of hooks) {
+                    // eslint-disable-next-line no-await-in-loop
+                    await hook();
+                }
+            },
+        });
+    },
+});
+const resolveBasePath = (basePath) => {
+    if (typeof basePath === 'string')
+        return basePath;
+    if (typeof process !== 'undefined' && typeof process.cwd === 'function')
+        return process.cwd();
+    return '';
+};
+const makeJoinFromBase = (resolvedBasePath) => (subPath) => {
+    return resolvedBasePath.length > 0 ? `${resolvedBasePath}/${subPath}` : subPath;
+};
+const registerCorePaths = (container, resolvedBasePath, joinFromBase) => {
+    container.singleton('paths', {
+        base: resolvedBasePath,
+        app: joinFromBase('app'),
+        config: joinFromBase('config'),
+        database: joinFromBase('database'),
+        routes: joinFromBase('routes'),
+        tests: joinFromBase('tests'),
+    });
+};
+const registerCoreInstances = (params) => {
+    params.container.singleton('env', params.environment);
+    params.container.singleton('router', params.router);
+    params.container.singleton('middleware', params.middlewareStack);
+    params.container.singleton('container', params.container);
+    params.container.singleton('shutdownManager', params.shutdownManager);
+};
+const registerFrameworkShutdownHooks = (shutdownManager) => {
+    // Register framework-level shutdown hooks for long-lived resources
+    // ConnectionManager may not be initialized; shutdownIfInitialized is safe
+    // Use dynamic import without top-level await to avoid transforming the module into an async module
+    import('../orm/ConnectionManager.js')
+        .then((mod) => {
+        shutdownManager.add(async () => mod.ConnectionManager.shutdownIfInitialized());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../orm/Database.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.resetDatabase());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../cache/Cache.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.Cache.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    // Flush file logging streams
+    import('../config/FileLogWriter.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.FileLogWriter.flush());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../tools/broadcast/BroadcastRegistry.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.BroadcastRegistry.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../tools/storage/StorageDiskRegistry.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.StorageDiskRegistry.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../tools/notification/NotificationChannelRegistry.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.NotificationChannelRegistry.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../tools/mail/MailDriverRegistry.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.MailDriverRegistry.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../tools/queue/Queue.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.Queue.reset());
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    import('../../packages/workers/src/index.js')
+        .then((mod) => {
+        shutdownManager.add(async () => mod.WorkerShutdown.shutdown({ signal: 'APP_SHUTDOWN', timeout: 5000, forceExit: false }));
+    })
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+};
+const tryImportRoutesFromAppBase = async (resolvedBasePath) => {
+    if (resolvedBasePath === '')
+        return undefined;
+    const candidates = [
+        // Dev (tsx)
+        path.join(resolvedBasePath, 'routes', 'api.ts'),
+        // Production build output
+        path.join(resolvedBasePath, 'dist', 'routes', 'api.js'),
+        // Fallback (in case someone transpiles without /dist)
+        path.join(resolvedBasePath, 'routes', 'api.js'),
+    ];
+    for (const candidate of candidates) {
+        try {
+            const url = pathToFileURL(candidate).href;
+            // eslint-disable-next-line no-await-in-loop
+            return (await import(url));
+        }
+        catch {
+            // keep trying
+        }
+    }
+    return undefined;
+};
+const registerRoutes = async (resolvedBasePath, router) => {
+    try {
+        const mod = await tryImportRoutesFromAppBase(resolvedBasePath);
+        if (typeof mod?.registerRoutes === 'function') {
+            mod.registerRoutes(router);
+        }
+        else {
+            const { registerRoutes: registerFrameworkRoutes } = await import('../../routes/api.js');
+            registerFrameworkRoutes(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);
+    }
+};
+const initializeArtifactDirectories = async (resolvedBasePath) => {
+    if (resolvedBasePath === '')
+        return;
+    if (typeof process === '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 tryImportOptional = async (modulePath) => {
+    try {
+        return (await import(modulePath));
+    }
+    catch {
+        return undefined;
+    }
+};
+const isCompiledJsModule = () => {
+    // When running from dist, this module is compiled to .js and Node ESM resolution
+    // requires explicit file extensions for relative imports.
+    return import.meta.url.endsWith('.js');
+};
+const dbLoader = async () => {
+    const db = await tryImportOptional(isCompiledJsModule()
+        ? '../orm/DatabaseRuntimeRegistration.js'
+        : '../orm/DatabaseRuntimeRegistration');
+    db?.registerDatabasesFromRuntimeConfig?.(databaseConfig);
+};
+const queuesLoader = async () => {
+    const queues = await tryImportOptional(isCompiledJsModule()
+        ? '../tools/queue/QueueRuntimeRegistration.js'
+        : '../tools/queue/QueueRuntimeRegistration');
+    queues?.registerQueuesFromRuntimeConfig?.(queueConfig);
+};
+const cachesLoader = async () => {
+    const caches = await tryImportOptional(isCompiledJsModule()
+        ? '../cache/CacheRuntimeRegistration.js'
+        : '../cache/CacheRuntimeRegistration');
+    caches?.registerCachesFromRuntimeConfig?.(cacheConfig);
+};
+const registerFromRuntimeConfig = async () => {
+    await dbLoader();
+    await queuesLoader();
+    await cachesLoader();
+    const broadcasters = await tryImportOptional(isCompiledJsModule()
+        ? '../tools/broadcast/BroadcastRuntimeRegistration.js'
+        : '../tools/broadcast/BroadcastRuntimeRegistration');
+    broadcasters?.registerBroadcastersFromRuntimeConfig?.({
+        default: broadcastConfig.default,
+        drivers: broadcastConfig.drivers,
+    });
+    const disks = await tryImportOptional(isCompiledJsModule()
+        ? '../tools/storage/StorageRuntimeRegistration.js'
+        : '../tools/storage/StorageRuntimeRegistration');
+    disks?.registerDisksFromRuntimeConfig?.(storageConfig);
+    const notifications = await tryImportOptional(isCompiledJsModule()
+        ? '../tools/notification/NotificationRuntimeRegistration.js'
+        : '../tools/notification/NotificationRuntimeRegistration');
+    notifications?.registerNotificationChannelsFromRuntimeConfig?.({
+        default: notificationConfig.default,
+        drivers: notificationConfig.drivers,
+    });
+};
+const createLifecycle = (params) => {
+    const boot = async () => {
+        if (params.getBooted())
+            return;
+        Logger.info(`🚀 Booting ZinTrust Application in ${params.environment} mode...`);
+        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 registerRoutes(params.resolvedBasePath, 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 };
+};
+/**
+ * Application Factory
+ */
+export const Application = Object.freeze({
+    /**
+     * Create a new application instance
+     */
+    create(basePath) {
+        const resolvedBasePath = resolveBasePath(basePath);
+        const joinFromBase = makeJoinFromBase(resolvedBasePath);
+        const environment = appConfig.environment;
+        const container = ServiceContainer.create();
+        const router = Router.createRouter();
+        const middlewareStack = MiddlewareStack.create();
+        const shutdownManager = ShutdownManager.create();
+        let booted = false;
+        registerCorePaths(container, resolvedBasePath, joinFromBase);
+        registerCoreInstances({ container, environment, router, middlewareStack, shutdownManager });
+        registerFrameworkShutdownHooks(shutdownManager);
+        const { boot, shutdown } = createLifecycle({
+            environment,
+            resolvedBasePath,
+            router,
+            shutdownManager,
+            getBooted: () => booted,
+            setBooted: (value) => {
+                booted = value;
+            },
+        });
+        return {
+            boot,
+            shutdown,
+            isBooted: () => booted,
+            isDevelopment: () => appConfig.isDevelopment(),
+            isProduction: () => appConfig.isProduction(),
+            isTesting: () => appConfig.isTesting(),
+            getEnvironment: () => environment,
+            getRouter: () => router,
+            getContainer: () => container,
+            getMiddlewareStack: () => middlewareStack,
+            getBasePath: () => resolvedBasePath,
+        };
+    },
+});
+export default Application;

package/src/boot/Server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server - HTTP Server implementation
+ * Uses Node.js built-in HTTP server with no external dependencies
+ */
+import type { IApplication } from './Application';
+import type { IKernel } from '../http/Kernel';
+import * as http from '../node-singletons/http';
+export interface IServer {
+    listen(): Promise<void>;
+    close(): Promise<void>;
+    getHttpServer(): http.Server;
+}
+/**
+ * Server - HTTP Server implementation
+ * Refactored to Functional Object pattern
+ */
+export declare const Server: Readonly<{
+    /**
+     * Create a new server instance
+     */
+    create(app: IApplication, port?: number, host?: string, kernel?: IKernel | null): IServer;
+}>;
+export default Server;
+//# sourceMappingURL=Server.d.ts.map

package/src/boot/Server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../../src/boot/Server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAOtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAG9C,MAAM,WAAW,OAAO;IACtB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,aAAa,IAAI,IAAI,CAAC,MAAM,CAAC;CAC9B;AA2DD;;;GAGG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;gBACS,YAAY,SAAS,MAAM,SAAS,MAAM,WAAU,OAAO,GAAG,IAAI,GAAU,OAAO;EA4D/F,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/src/boot/Server.js

@@ -0,0 +1,117 @@
+/**
+ * Server - HTTP Server implementation
+ * Uses Node.js built-in HTTP server with no external dependencies
+ */
+import { appConfig } from '../config/app.js';
+import { HTTP_HEADERS } from '../config/constants.js';
+import { Logger } from '../config/logger.js';
+import { ServiceContainer } from '../container/ServiceContainer.js';
+import { ErrorRouting } from '../routes/error.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { Kernel } from '../http/Kernel.js';
+import { Request } from '../http/Request.js';
+import { Response } from '../http/Response.js';
+import * as http from '../node-singletons/http.js';
+/**
+ * Set security headers on response
+ */
+const getContentSecurityPolicyForPath = () => {
+    // Default CSP for the API/framework
+    return ("default-src 'self'; " +
+        "script-src 'self' 'unsafe-inline'; " +
+        "style-src 'self' 'unsafe-inline'; " +
+        "img-src 'self' data:; " +
+        "font-src 'self';");
+};
+const setSecurityHeaders = (res) => {
+    res.setHeader(HTTP_HEADERS.X_POWERED_BY, 'ZinTrust');
+    res.setHeader(HTTP_HEADERS.X_CONTENT_TYPE_OPTIONS, 'nosniff');
+    res.setHeader(HTTP_HEADERS.X_FRAME_OPTIONS, 'DENY');
+    res.setHeader(HTTP_HEADERS.X_XSS_PROTECTION, '1; mode=block');
+    res.setHeader(HTTP_HEADERS.REFERRER_POLICY, 'strict-origin-when-cross-origin');
+    res.setHeader(HTTP_HEADERS.CONTENT_SECURITY_POLICY, getContentSecurityPolicyForPath());
+};
+const handleRequest = async (params, req, res) => {
+    let request;
+    let response;
+    try {
+        setSecurityHeaders(res);
+        if (!req) {
+            throw ErrorFactory.createConnectionError('Request object is missing');
+        }
+        const kernel = params.getKernel();
+        request = Request.create(req);
+        response = Response.create(res);
+        // Delegate request lifecycle to Kernel (routing + middleware + handler execution).
+        await kernel.handleRequest(request, response);
+    }
+    catch (error) {
+        ErrorFactory.createTryCatchError('Server error:', error);
+        // Prefer wrapper-based error handling when available.
+        if (request !== undefined && response !== undefined) {
+            ErrorRouting.handleInternalServerErrorWithWrappers(request, response, error);
+            return;
+        }
+        ErrorRouting.handleInternalServerErrorRaw(res);
+    }
+};
+/**
+ * Server - HTTP Server implementation
+ * Refactored to Functional Object pattern
+ */
+export const Server = Object.freeze({
+    /**
+     * Create a new server instance
+     */
+    create(app, port, host, kernel = null) {
+        const serverPort = port ?? appConfig.port;
+        const serverHost = host ?? appConfig.host;
+        let kernelInstance = kernel;
+        const getKernel = () => {
+            if (kernelInstance !== null)
+                return kernelInstance;
+            const anyApp = app;
+            const container = typeof anyApp.getContainer === 'function'
+                ? anyApp.getContainer()
+                : ServiceContainer.create();
+            kernelInstance = Kernel.create(app.getRouter(), container);
+            return kernelInstance;
+        };
+        const httpServer = http.createServer(async (req, res) => handleRequest({ getKernel }, req, res));
+        const sockets = new Set();
+        httpServer.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.on('close', () => sockets.delete(socket));
+        });
+        return {
+            async listen() {
+                return new Promise((resolve) => {
+                    httpServer.listen(serverPort, serverHost, () => {
+                        resolve();
+                    });
+                });
+            },
+            async close() {
+                return new Promise((resolve) => {
+                    httpServer.close(() => {
+                        Logger.info('ZinTrust server stopped');
+                        resolve();
+                    });
+                    // Ensure keep-alive / hanging connections don't block shutdown
+                    for (const socket of sockets) {
+                        try {
+                            socket.destroy();
+                        }
+                        catch {
+                            // best-effort
+                        }
+                    }
+                });
+            },
+            getHttpServer() {
+                return httpServer;
+            },
+        };
+    },
+});
+export default Server;

package/src/boot/bootstrap.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Application Bootstrap
+ * Entry point for running the ZinTrust server
+ * Sealed namespace for immutability
+ */
+export {};
+//# sourceMappingURL=bootstrap.d.ts.map

package/src/boot/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../../src/boot/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}