@zintrust/core 0.1.18 → 0.1.20

package/routes/health.js

@@ -0,0 +1,127 @@
+/**
+ * Health Routes
+ * Provides health, liveness, and readiness endpoints.
+ */
+import { appConfig } from '../src/config/index.js';
+import { RuntimeHealthProbes } from '../src/health/RuntimeHealthProbes.js';
+import { Env } from '../src/config/env.js';
+import { Logger } from '../src/config/logger.js';
+import { useDatabase } from '../src/orm/Database.js';
+import { QueryBuilder } from '../src/orm/QueryBuilder.js';
+import { Router } from '../src/routing/Router.js';
+export function registerHealthRoutes(router) {
+    registerHealthRoute(router);
+    registerHealthLiveRoute(router);
+    registerHealthReadyRoute(router);
+}
+function registerHealthRoute(router) {
+    Router.get(router, '/health', async (_req, res) => {
+        const environment = Env.NODE_ENV ?? 'development';
+        try {
+            const db = useDatabase();
+            const maybeIsConnected = db.isConnected;
+            const maybeConnect = db.connect;
+            if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+                if (typeof maybeConnect === 'function') {
+                    await maybeConnect.call(db);
+                }
+            }
+            await QueryBuilder.ping(db);
+            const uptime = typeof process !== 'undefined' && typeof process.uptime === 'function'
+                ? process.uptime()
+                : 0;
+            res.json({
+                status: 'healthy',
+                timestamp: new Date().toISOString(),
+                uptime,
+                database: 'connected',
+                environment,
+            });
+        }
+        catch (error) {
+            Logger.error('Health check failed:', error);
+            const isProd = environment === 'production' || environment === 'prod';
+            res.setStatus(503).json({
+                status: 'unhealthy',
+                timestamp: new Date().toISOString(),
+                database: 'disconnected',
+                error: isProd ? 'Service unavailable' : error.message,
+            });
+        }
+    });
+}
+function registerHealthLiveRoute(router) {
+    Router.get(router, '/health/live', async (_req, res) => {
+        const uptime = typeof process !== 'undefined' && typeof process.uptime === 'function' ? process.uptime() : 0;
+        res.json({
+            status: 'alive',
+            timestamp: new Date().toISOString(),
+            uptime,
+        });
+    });
+}
+function registerHealthReadyRoute(router) {
+    Router.get(router, '/health/ready', async (_req, res) => {
+        const startTime = Date.now();
+        const environment = appConfig.environment;
+        let databaseResponseTime = null;
+        let cacheResponseTime = null;
+        try {
+            const db = useDatabase();
+            const maybeIsConnected = db.isConnected;
+            const maybeConnect = db.connect;
+            if (typeof maybeIsConnected === 'function' && maybeIsConnected.call(db) === false) {
+                if (typeof maybeConnect === 'function') {
+                    await maybeConnect.call(db);
+                }
+            }
+            await QueryBuilder.ping(db);
+            databaseResponseTime = Date.now() - startTime;
+            // Only probe KV at runtime when explicitly configured.
+            cacheResponseTime = await RuntimeHealthProbes.pingKvCache(2000);
+            res.json({
+                status: 'ready',
+                timestamp: new Date().toISOString(),
+                environment,
+                dependencies: {
+                    database: {
+                        status: 'ready',
+                        responseTime: databaseResponseTime,
+                    },
+                    ...(cacheResponseTime === null
+                        ? {}
+                        : {
+                            cache: {
+                                status: 'ready',
+                                responseTime: cacheResponseTime,
+                            },
+                        }),
+                },
+            });
+        }
+        catch (error) {
+            Logger.error('Readiness check failed:', error);
+            const isProd = environment === 'production';
+            const responseTime = Date.now() - startTime;
+            const dependencies = {
+                database: {
+                    status: databaseResponseTime === null ? 'unavailable' : 'ready',
+                    responseTime: databaseResponseTime ?? responseTime,
+                },
+            };
+            if (RuntimeHealthProbes.getCacheDriverName() === 'kv') {
+                dependencies['cache'] = {
+                    status: 'unavailable',
+                    responseTime: cacheResponseTime ?? responseTime,
+                };
+            }
+            res.setStatus(503).json({
+                status: 'not_ready',
+                timestamp: new Date().toISOString(),
+                environment,
+                dependencies,
+                error: isProd ? 'Service unavailable' : error.message,
+            });
+        }
+    });
+}

package/routes/metrics.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Metrics Routes
+ *
+ * Exposes Prometheus metrics when enabled.
+ */
+import { type IRouter } from '../src/routing/Router';
+export declare function registerMetricsRoutes(router: IRouter): void;
+export default registerMetricsRoutes;
+//# sourceMappingURL=metrics.d.ts.map

package/routes/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../routes/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,iBAAiB,CAAC;AAEvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAW3D;AAED,eAAe,qBAAqB,CAAC"}

package/routes/metrics.js

@@ -0,0 +1,20 @@
+/**
+ * Metrics Routes
+ *
+ * Exposes Prometheus metrics when enabled.
+ */
+import { PrometheusMetrics } from '../src/observability/PrometheusMetrics.js';
+import { Env } from '../src/config/env.js';
+import { Router } from '../src/routing/Router.js';
+export function registerMetricsRoutes(router) {
+    if (Env.getBool('METRICS_ENABLED', false) === false)
+        return;
+    const pathFromEnv = Env.get('METRICS_PATH', '/metrics').trim();
+    const path = pathFromEnv === '' ? '/metrics' : pathFromEnv;
+    Router.get(router, path, async (_req, res) => {
+        const { contentType, body } = await PrometheusMetrics.getMetricsText();
+        res.setHeader('Content-Type', contentType);
+        res.send(body);
+    });
+}
+export default registerMetricsRoutes;

package/routes/openapi.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAPI Routes
+ *
+ * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
+ */
+import { type IRouter } from '../src/routing/Router';
+export declare function registerOpenApiRoutes(router: IRouter): void;
+export default registerOpenApiRoutes;
+//# sourceMappingURL=openapi.d.ts.map

package/routes/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../routes/openapi.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,iBAAiB,CAAC;AA2CvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAuC3D;AAED,eAAe,qBAAqB,CAAC"}

package/routes/openapi.js

@@ -0,0 +1,76 @@
+/**
+ * OpenAPI Routes
+ *
+ * Serves a generated OpenAPI spec from the in-memory RouteRegistry.
+ */
+import { OpenApiGenerator } from '../src/openapi/OpenApiGenerator.js';
+import { Env } from '../src/config/env.js';
+import { Router } from '../src/routing/Router.js';
+import { RouteRegistry } from '../src/routing/RouteRegistry.js';
+const getServerUrl = () => {
+    const explicit = Env.BASE_URL;
+    if (explicit.trim() !== '')
+        return explicit;
+    const host = Env.HOST;
+    const port = Env.PORT;
+    if (host.trim() === '' || Number.isNaN(port) || port <= 0)
+        return undefined;
+    return `http://${host}:${port}`;
+};
+const getDocsHtml = (specUrl) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${Env.APP_NAME} API Docs</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      html, body { margin: 0; padding: 0; }
+      #swagger-ui { box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function () {
+        window.ui = SwaggerUIBundle({
+          url: ${JSON.stringify(specUrl)},
+          dom_id: '#swagger-ui',
+          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+          layout: 'BaseLayout'
+        });
+      };
+    </script>
+  </body>
+</html>`;
+export function registerOpenApiRoutes(router) {
+    Router.get(router, '/openapi.json', async (_req, res) => {
+        // Convert readonly to mutable array for OpenApiGenerator
+        const routes = Array.from(RouteRegistry.list());
+        const doc = OpenApiGenerator.generate(routes, {
+            title: Env.APP_NAME,
+            version: Env.get('APP_VERSION', '0.0.0'),
+            serverUrl: getServerUrl(),
+            excludePaths: ['/openapi.json', '/docs'],
+        });
+        res.json(doc);
+    }, {
+        meta: {
+            summary: 'OpenAPI spec',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+    Router.get(router, '/docs', async (_req, res) => {
+        res.html(getDocsHtml('/openapi.json'));
+    }, {
+        meta: {
+            summary: 'Swagger UI',
+            tags: ['Docs'],
+            responseStatus: 200,
+        },
+    });
+}
+export default registerOpenApiRoutes;

package/routes/storage.d.ts

@@ -0,0 +1,4 @@
+import { type IRouter } from '../src/routing/Router';
+export declare function registerStorageRoutes(router: IRouter): void;
+export default registerStorageRoutes;
+//# sourceMappingURL=storage.d.ts.map

package/routes/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../routes/storage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,iBAAiB,CAAC;AAIvD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAiC3D;AAED,eAAe,qBAAqB,CAAC"}

package/routes/storage.js

@@ -0,0 +1,35 @@
+import { HTTP_HEADERS } from '../src/config/constants.js';
+import { Env } from '../src/config/env.js';
+import { Router } from '../src/routing/Router.js';
+import { LocalSignedUrl } from '../src/tools/storage/LocalSignedUrl.js';
+import { Storage } from '../src/tools/storage/index.js';
+export function registerStorageRoutes(router) {
+    Router.get(router, '/storage/download', async (req, res) => {
+        const tokenRaw = req.getQueryParam('token');
+        const token = typeof tokenRaw === 'string' ? tokenRaw : '';
+        if (token.trim() === '') {
+            res.setStatus(400).json({ message: 'Missing token' });
+            return;
+        }
+        const appKey = Env.get('APP_KEY', '');
+        if (appKey.trim() === '') {
+            res.setStatus(500).json({ message: 'Storage signing is not configured' });
+            return;
+        }
+        try {
+            const payload = LocalSignedUrl.verifyToken(token, appKey);
+            // Only local disk is supported by this route.
+            if (payload.disk !== 'local') {
+                res.setStatus(400).json({ message: 'Unsupported disk' });
+                return;
+            }
+            const contents = await Storage.get('local', payload.key);
+            res.setHeader(HTTP_HEADERS.CONTENT_TYPE, 'application/octet-stream');
+            res.setStatus(200).send(contents);
+        }
+        catch {
+            res.setStatus(403).json({ message: 'Invalid or expired token' });
+        }
+    });
+}
+export default registerStorageRoutes;

package/src/boot/Application.d.ts

@@ -2,8 +2,8 @@
  * Application - Framework core entry point
  * Handles application lifecycle, booting, and environment
  */
-import { IServiceContainer } from '../container/ServiceContainer';
-import { IMiddlewareStack } from '../middleware/MiddlewareStack';
+import type { IServiceContainer } from '../container/ServiceContainer';
+import type { IMiddlewareStack } from '../middleware/MiddlewareStack';
 import { type IRouter } from '../routing/Router';
 export interface IApplication {
     boot(): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"Application.d.ts","sourceRoot":"","sources":["../../../src/boot/Application.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAoB,MAAM,8BAA8B,CAAC;AAEnF,OAAO,EAAE,gBAAgB,EAAmB,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AASxD,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;AAsUD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM,GAAG,YAAY;EA0CvC,CAAC;AAEH,eAAe,WAAW,CAAC"}
+{"version":3,"file":"Application.d.ts","sourceRoot":"","sources":["../../../src/boot/Application.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AASxD,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;AAqVD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM,GAAG,YAAY;EA0CvC,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/src/boot/Application.js

@@ -88,6 +88,16 @@ const registerFrameworkShutdownHooks = (shutdownManager) => {
         /* ignore import failures in restrictive runtimes */
     });
     /* c8 ignore stop */
+    // Flush file logging streams
+    import('../config/FileLogWriter.js')
+        .then((mod) => {
+        shutdownManager.add(() => mod.FileLogWriter.flush());
+    })
+        /* c8 ignore start */
+        .catch(() => {
+        /* ignore import failures in restrictive runtimes */
+    });
+    /* c8 ignore stop */
     import('../tools/broadcast/BroadcastRegistry.js')
         .then((mod) => {
         shutdownManager.add(() => mod.BroadcastRegistry.reset());
@@ -162,10 +172,15 @@ const registerRoutes = async (resolvedBasePath, router) => {
         const mod = await tryImportRoutesFromAppBase(resolvedBasePath);
         if (typeof mod?.registerRoutes === 'function') {
             mod.registerRoutes(router);
-            return;
         }
-        const { registerRoutes: registerFrameworkRoutes } = await import('../../routes/api.js');
-        registerFrameworkRoutes(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('../routing/CoreRoutes.js');
+        registerCoreRoutes(router);
     }
     catch (error) {
         Logger.error('Failed to register routes:', error);

package/src/boot/Server.d.ts

@@ -2,7 +2,8 @@
  * Server - HTTP Server implementation
  * Uses Node.js built-in HTTP server with no external dependencies
  */
-import { IApplication } from './Application';
+import type { IApplication } from './Application';
+import type { IKernel } from '../http/Kernel';
 import * as http from '../node-singletons/http';
 export interface IServer {
     listen(): Promise<void>;
@@ -17,7 +18,7 @@ export declare const Server: Readonly<{
     /**
      * Create a new server instance
      */
-    create(app: IApplication, port?: number, host?: string): IServer;
+    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

@@ -1 +1 @@
-{"version":3,"file":"Server.d.ts","sourceRoot":"","sources":["../../../src/boot/Server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AASjD,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAK9C,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;AA6MD;;;GAGG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;gBACS,YAAY,SAAS,MAAM,SAAS,MAAM,GAAG,OAAO;EA4ChE,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"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;AAMtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAM5C,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAI9C,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

@@ -2,194 +2,57 @@
  * Server - HTTP Server implementation
  * Uses Node.js built-in HTTP server with no external dependencies
  */
-import { esmDirname } from '../common/index.js';
 import { appConfig } from '../config/app.js';
-import { HTTP_HEADERS, MIME_TYPES } from '../config/constants.js';
+import { HTTP_HEADERS } from '../config/constants.js';
 import { Logger } from '../config/logger.js';
+import { ServiceContainer } from '../container/ServiceContainer.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 fs from '../node-singletons/fs.js';
 import * as http from '../node-singletons/http.js';
-import * as path from '../node-singletons/path.js';
-import { Router } from '../routing/Router.js';
-const MIME_TYPES_MAP = {
-    '.html': MIME_TYPES.HTML,
-    '.js': MIME_TYPES.JS,
-    '.css': MIME_TYPES.CSS,
-    '.json': MIME_TYPES.JSON,
-    '.png': MIME_TYPES.PNG,
-    '.jpg': MIME_TYPES.JPG,
-    '.gif': MIME_TYPES.GIF,
-    '.svg': MIME_TYPES.SVG,
-    '.wav': MIME_TYPES.WAV,
-    '.mp4': MIME_TYPES.MP4,
-    '.woff': MIME_TYPES.WOFF,
-    '.ttf': MIME_TYPES.TTF,
-    '.eot': MIME_TYPES.EOT,
-    '.otf': MIME_TYPES.OTF,
-    '.wasm': MIME_TYPES.WASM,
-};
-const findPackageRoot = (startDir) => {
-    let current = startDir;
-    for (let i = 0; i < 10; i++) {
-        if (fs.existsSync(path.join(current, 'package.json')))
-            return current;
-        const parent = path.dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return startDir;
-};
-const getFrameworkPublicRoots = () => {
-    const thisDir = esmDirname(import.meta.url);
-    const packageRoot = findPackageRoot(thisDir);
-    return [
-        path.join(packageRoot, 'dist/public'),
-        path.join(packageRoot, 'public'), // Fallback for shipped package
-    ];
-};
-const getDocsPublicRoot = () => {
-    // First try app-local roots (developer app override), then fall back to framework-shipped assets.
-    const appRoots = [path.join(process.cwd(), 'public')];
-    const candidates = [...appRoots, ...getFrameworkPublicRoots()];
-    const hasDocsEntrypoint = (root) => {
-        const directIndex = path.join(root, 'index.html');
-        return fs.existsSync(directIndex);
-    };
-    // Prefer a root that actually contains docs assets.
-    for (const candidate of candidates) {
-        if (fs.existsSync(candidate) && hasDocsEntrypoint(candidate))
-            return candidate;
-    }
-    // Fall back to the first existing directory.
-    for (const candidate of candidates) {
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    return candidates[0];
-};
-/**
- * Map URL path to physical file path
- */
-const mapStaticPath = (urlPath) => {
-    const publicRoot = getDocsPublicRoot();
-    const normalize = (p) => (p.startsWith('/') ? p.slice(1) : p);
-    // /doc acts as a mount for the docs/static site.
-    if (urlPath === '/doc' || urlPath === '/doc/')
-        return publicRoot;
-    if (urlPath.startsWith('/doc/'))
-        return path.join(publicRoot, normalize(urlPath.slice('/doc/'.length)));
-    // Also serve app-local static files from the same public root.
-    return path.join(publicRoot, normalize(urlPath));
-};
-/**
- * Send static file to response
- */
-const sendStaticFile = (filePath, response) => {
-    const ext = path.extname(filePath).toLowerCase();
-    const contentType = MIME_TYPES_MAP[ext] || 'application/octet-stream';
-    const content = fs.readFileSync(filePath);
-    response.setStatus(200);
-    response.setHeader('Content-Type', contentType);
-    response.send(content);
-};
-/**
- * Serve static files from docs-website
- */
-// eslint-disable-next-line @typescript-eslint/require-await
-const serveStatic = async (request, response) => {
-    const urlPath = request.getPath();
-    let filePath = mapStaticPath(urlPath);
-    if (!filePath)
-        return false;
-    try {
-        // If it's a directory, look for index.html
-        if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
-            filePath = path.join(filePath, 'index.html');
-        }
-        // Handle clean URLs (try adding .html)
-        if (!fs.existsSync(filePath) && !path.extname(filePath)) {
-            const htmlPath = `${filePath}.html`;
-            if (fs.existsSync(htmlPath)) {
-                filePath = htmlPath;
-            }
-        }
-        if (fs.existsSync(filePath)) {
-            sendStaticFile(filePath, response);
-            return true;
-        }
-    }
-    catch (error) {
-        ErrorFactory.createTryCatchError(`Error serving static file ${filePath}`, error);
-    }
-    return false;
-};
+import { ErrorRouting } from '../routing/error.js';
 /**
  * Set security headers on response
  */
-const getContentSecurityPolicyForPath = (requestPath) => {
-    // Default CSP for the API/framework.
-    const baseCsp = "default-src 'self'; " +
+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';";
-    // Docs pages intentionally load external assets (Tailwind CDN + Google Fonts).
-    // Keep this relaxation scoped to the docs base path.
-    if (!requestPath.startsWith('/doc'))
-        return baseCsp;
-    return ("default-src 'self'; " +
-        "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://cdn.tailwindcss.com; " +
-        "script-src-elem 'self' 'unsafe-inline' https://cdn.tailwindcss.com; " +
-        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
-        "style-src-elem 'self' 'unsafe-inline' https://fonts.googleapis.com; " +
-        "img-src 'self' data: https:; " +
-        "font-src 'self' data: https://fonts.gstatic.com;");
+        "font-src 'self';");
 };
-const setSecurityHeaders = (res, requestPath) => {
+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(requestPath));
+    res.setHeader(HTTP_HEADERS.CONTENT_SECURITY_POLICY, getContentSecurityPolicyForPath());
 };
-/**
- * Handle incoming HTTP requests
- */
-const handleRequest = async (app, req, res) => {
+const handleRequest = async (params, req, res) => {
+    let request;
+    let response;
     try {
-        // Use the raw URL so docs assets (/doc/assets/...) get the correct CSP.
-        const requestPath = typeof req?.url === 'string' ? req.url : '/';
-        setSecurityHeaders(res, requestPath);
+        setSecurityHeaders(res);
         if (!req) {
             throw ErrorFactory.createConnectionError('Request object is missing');
         }
-        const request = Request.create(req);
-        const response = Response.create(res);
-        // Route the request
-        const router = app.getRouter();
-        const route = Router.match(router, request.getMethod(), request.getPath());
-        if (route === null) {
-            // Try serving static files from docs-website
-            if (await serveStatic(request, response)) {
-                return;
-            }
-            // 404 Not Found
-            response.setStatus(404).json({ message: 'Not Found' });
-        }
-        else {
-            // Handler found, execute route handler
-            request.setParams(route.params);
-            await route.handler(request, response);
-        }
+        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);
-        res.writeHead(500, { [HTTP_HEADERS.CONTENT_TYPE]: MIME_TYPES.JSON });
-        res.end(JSON.stringify({ message: 'Internal Server Error' }));
+        // Prefer wrapper-based error handling when available.
+        if (request !== undefined && response !== undefined) {
+            ErrorRouting.handleInternalServerErrorWithWrappers(request, response, error);
+            return;
+        }
+        ErrorRouting.handleInternalServerErrorRaw(res);
     }
 };
 /**
@@ -200,10 +63,21 @@ export const Server = Object.freeze({
     /**
      * Create a new server instance
      */
-    create(app, port, host) {
+    create(app, port, host, kernel = null) {
         const serverPort = port ?? appConfig.port;
         const serverHost = host ?? appConfig.host;
-        const httpServer = http.createServer(async (req, res) => handleRequest(app, req, res));
+        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);
@@ -220,7 +94,7 @@ export const Server = Object.freeze({
             async close() {
                 return new Promise((resolve) => {
                     httpServer.close(() => {
-                        Logger.info('Zintrust server stopped');
+                        Logger.info('ZinTrust server stopped');
                         resolve();
                     });
                     // Ensure keep-alive / hanging connections don't block shutdown

package/src/boot/bootstrap.js

@@ -126,7 +126,7 @@ const BootstrapFunctions = Object.freeze({
             // Boot application
             await app.boot();
             // Get port and host from environment
-            const port = Env.getInt('PORT', 3000);
+            const port = Env.getInt('PORT', 7777);
             const host = Env.get('HOST', 'localhost');
             // Create and start server
             const server = Server.create(app, port, host);

package/src/cache/Cache.d.ts

@@ -3,7 +3,7 @@
  * Central cache management and driver resolution
  * Sealed namespace pattern - all exports through Cache namespace
  */
-import { CacheDriver } from './CacheDriver';
+import type { CacheDriver } from './CacheDriver';
 type CacheStore = Readonly<{
     get: <T>(key: string) => Promise<T | null>;
     set: <T>(key: string, value: T, ttl?: number) => Promise<void>;