exisjs 0.4.2 → 0.4.4

package/dist/server/app.js

@@ -35,31 +35,68 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.activeAppInstance = exports.app = exports.App = void 0;
 exports.getActiveApp = getActiveApp;
-const node_http_1 = require("node:http");
-const node_https_1 = require("node:https");
-const node_http2_1 = require("node:http2");
 const ws_1 = require("ws");
-const node_url_1 = require("node:url");
-const validator_1 = require("../utils/validator");
-const request_1 = require("./request");
-const response_1 = require("./response");
-const context_1 = require("./context");
 const router_1 = require("../router/router");
 const middleware_1 = require("../middleware/middleware");
 const errors_1 = require("../utils/errors");
 const server_1 = require("../websocket/server");
-const socket_1 = require("../websocket/socket");
 const config_1 = require("../utils/config");
 const logger_1 = require("../utils/logger");
 const hot_reload_1 = require("./hot-reload");
-const dev_error_overlay_1 = require("./dev-error-overlay");
-const uws_adapter_1 = require("./uws-adapter");
-const client_1 = require("../queue/client");
-const worker_1 = require("../queue/worker");
-const scheduler_1 = require("../cron/scheduler");
 const container_1 = require("../di/container");
+const bootstrapper_1 = require("./bootstrapper");
+const ws_orchestrator_1 = require("./ws-orchestrator");
+const plugin_manager_1 = require("./plugin-manager");
+const route_scanner_1 = require("./route-scanner");
+const queue_manager_1 = require("./queue-manager");
+const request_handler_1 = require("./request-handler");
+const controller_registrar_1 = require("./controller-registrar");
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 class App {
+    get server() {
+        return this.bootstrapper.getServer();
+    }
+    get redirectServer() {
+        return this.bootstrapper.redirectServer;
+    }
+    get onStartHook() {
+        return this.pluginManager.onStartHook;
+    }
+    set onStartHook(cb) {
+        this.pluginManager.onStartHook = cb;
+    }
+    get onCloseHook() {
+        return this.pluginManager.onCloseHook;
+    }
+    set onCloseHook(cb) {
+        this.pluginManager.onCloseHook = cb;
+    }
+    // ─── Lifecycle Hooks Registry ───────────────────────────────────────────────
+    get hooks() {
+        return this.pluginManager.hooks;
+    }
+    // ─── Queue ──────────────────────────────────────────────────────────────────
+    get apiDir() {
+        return this.routeScanner.apiDir;
+    }
+    set apiDir(val) {
+        this.routeScanner.apiDir = val;
+    }
+    get _queueClient() {
+        return this.queueManager._queueClient;
+    }
+    get _queueWorker() {
+        return this.queueManager._queueWorker;
+    }
+    get _cronScheduler() {
+        return this.queueManager._cronScheduler;
+    }
+    get _pendingQueueJobs() {
+        return this.queueManager._pendingQueueJobs;
+    }
+    set _pendingQueueJobs(v) {
+        this.queueManager._pendingQueueJobs = v;
+    }
     get queueClient() {
         return this._queueClient;
     }
@@ -67,64 +104,40 @@ class App {
         return this._queueWorker;
     }
     constructor(options = {}) {
-        this.redirectServer = null;
-        this.apiDir = null;
         this.globalMiddleware = [];
         this.errorHandlers = [];
         this._configured = false;
         this._routesMounted = false;
         this._loggerCreated = false;
-        this.registeredPlugins = new Map();
-        this.routeMap = new Map();
         this.hotReloader = null;
-        this.lazyRoutes = new Map();
         this.wsServer = new server_1.ExisWebSocketServer();
         this.rawWsServer = new ws_1.WebSocketServer({ noServer: true });
         // ─── uWebSockets.js Backend ──────────────────────────────────────────────────
         this._useUws = false;
         this._uwsApp = null;
         this._uwsListenToken = null;
-        // ─── Lifecycle Hooks Registry ───────────────────────────────────────────────
-        this.hooks = {
-            ready: [],
-            close: [],
-            request: [],
-            response: [],
-            error: [],
-            route: [],
-        };
         // ─── Dataloaders Registry ───────────────────────────────────────────────────
         this._dataloaders = new Map();
         this.explicitOptions = {};
         // ─── Dependency Injection ───────────────────────────────────────────────────
         this.container = new container_1.Container();
-        // ─── Queue ──────────────────────────────────────────────────────────────────
-        this._queueClient = null;
-        this._queueWorker = null;
-        this._cronScheduler = null;
-        this._pendingQueueJobs = [];
+        // WebSocket Upgrade logic has been moved to WsOrchestrator
         this.shutdownHooks = [];
-        // ─── App Initialization ────────────────────────────────────────────────────────
+        // ─── App Initialization ───────────────────────────────────────────────────────
         this._configLoaded = false;
         this.explicitOptions = options;
         this.options = (0, config_1.mergeConfig)(config_1.defaultConfig, options);
         this.router = new router_1.Router();
         this.ensureLogger();
-        // Queue setup is now deferred to app.create() when the config is loaded
+        this.pluginManager = new plugin_manager_1.PluginManager(this);
+        this.wsOrchestrator = new ws_orchestrator_1.WsOrchestrator(this);
+        this.bootstrapper = new bootstrapper_1.ServerBootstrapper(this);
+        this.routeScanner = new route_scanner_1.RouteScanner(this);
+        this.queueManager = new queue_manager_1.QueueManager(this);
+        this.requestHandler = new request_handler_1.RequestHandler(this);
+        this.controllerRegistrar = new controller_registrar_1.ControllerRegistrar(this);
         if (this.options.queue) {
-            this._initQueue(this.options.queue);
-        }
-        // Auto-detect uWebSockets.js backend
-        if (options.server === 'uws' ||
-            (options.server !== 'node' &&
-                (0, uws_adapter_1.isUwsAvailable)() &&
-                this.options.env !== 'test')) {
-            this._useUws = true;
-            // Don't init Node server — we'll create the uWS app at listen() time
-        }
-        else {
-            this._useUws = false;
-            this.server = this._initServer();
+            this.queueManager._initQueue(this.options.queue);
         }
     }
     ensureLogger() {
@@ -137,58 +150,30 @@ class App {
         }
         this.log = (0, logger_1.createLogger)(loggerOptions);
     }
-    _initServer() {
-        let server;
-        if (this.options.ssl) {
-            if (this.options.http2 !== false) {
-                server = (0, node_http2_1.createSecureServer)({ allowHTTP1: true, ...this.options.ssl }, this.handle.bind(this));
-            }
-            else {
-                server = (0, node_https_1.createServer)(this.options.ssl, this.handle.bind(this));
-            }
-        }
-        else {
-            server = (0, node_http_1.createServer)(this.handle.bind(this));
-        }
-        server.on('upgrade', this._handleUpgrade.bind(this));
-        const keepAlive = this.options.keepAlive;
-        if (keepAlive) {
-            const kaConfig = keepAlive === true ? {} : keepAlive;
-            if ('keepAliveTimeout' in server)
-                server.keepAliveTimeout = kaConfig.timeoutMs ?? 5000;
-            if ('headersTimeout' in server)
-                server.headersTimeout = kaConfig.headersTimeoutMs ?? 60000;
-            if (kaConfig.maxRequests !== undefined &&
-                'maxRequestsPerSocket' in server) {
-                ;
-                server.maxRequestsPerSocket = kaConfig.maxRequests;
-            }
-        }
-        return server;
-    }
+    // _initServer logic has been moved to ServerBootstrapper
     // ─── Lifecycle Hooks Registration ───────────────────────────────────────────
     onReady(cb) {
-        this.hooks.ready.push(cb);
+        this.pluginManager.onReady(cb);
         return this;
     }
     onClose(cb) {
-        this.hooks.close.push(cb);
+        this.pluginManager.onClose(cb);
         return this;
     }
     onRequest(cb) {
-        this.hooks.request.push(cb);
+        this.pluginManager.onRequest(cb);
         return this;
     }
     onResponse(cb) {
-        this.hooks.response.push(cb);
+        this.pluginManager.onResponse(cb);
         return this;
     }
     onError(cb) {
-        this.hooks.error.push(cb);
+        this.pluginManager.onError(cb);
         return this;
     }
     onRoute(cb) {
-        this.hooks.route.push(cb);
+        this.pluginManager.onRoute(cb);
         return this;
     }
     // ─── Dataloaders ────────────────────────────────────────────────────────────
@@ -205,108 +190,10 @@ class App {
     }
     // ─── Plugin System ──────────────────────────────────────────────────────────
     hasPlugin(name) {
-        return this.registeredPlugins.has(name);
+        return this.pluginManager.hasPlugin(name);
     }
     async register(pluginOrInstance, legacyOptions) {
-        let plugin;
-        let options;
-        if ('plugin' in pluginOrInstance && !('register' in pluginOrInstance)) {
-            plugin = pluginOrInstance.plugin;
-            options = pluginOrInstance.options;
-        }
-        else {
-            plugin = pluginOrInstance;
-            options = legacyOptions;
-        }
-        if (this.registeredPlugins.has(plugin.name)) {
-            throw new Error(`Plugin '${plugin.name}' is already registered`);
-        }
-        if (plugin.dependencies) {
-            for (const dep of plugin.dependencies) {
-                if (!this.registeredPlugins.has(dep)) {
-                    throw new Error(`Plugin '${plugin.name}' requires dependency '${dep}' which is not registered`);
-                }
-            }
-        }
-        // eslint-disable-next-line @typescript-eslint/no-this-alias
-        let targetApp = this;
-        let pluginRouter;
-        if (plugin.encapsulate !== false) {
-            pluginRouter = new router_1.Router();
-            // Create a proxy that intercepts route and middleware registrations
-            targetApp = new Proxy(this, {
-                get(target, prop, receiver) {
-                    if ([
-                        'get',
-                        'post',
-                        'put',
-                        'patch',
-                        'delete',
-                        'httpOptions',
-                        'head',
-                        'all',
-                        'ws',
-                        'query',
-                        'connect',
-                        'trace',
-                    ].includes(prop)) {
-                        return (path, ...handlers) => {
-                            const routerMethod = prop === 'httpOptions' ? 'options' : prop;
-                            pluginRouter[routerMethod](path, ...handlers);
-                            return receiver;
-                        };
-                    }
-                    if (prop === 'use') {
-                        return (...handlers) => {
-                            for (const h of handlers) {
-                                if (h.length === 4) {
-                                    // error handlers stay global for now, or we could scope them
-                                    target.use(h);
-                                }
-                                else {
-                                    pluginRouter.use(h);
-                                }
-                            }
-                            return receiver;
-                        };
-                    }
-                    // Encapsulate lifecycle hooks by converting them to scoped middleware!
-                    if (['onRequest', 'onResponse'].includes(prop)) {
-                        return (cb) => {
-                            if (prop === 'onRequest') {
-                                pluginRouter.use(async (req, res, next) => {
-                                    try {
-                                        await cb(req, res);
-                                        next();
-                                    }
-                                    catch (err) {
-                                        next(err);
-                                    }
-                                });
-                            }
-                            else if (prop === 'onResponse') {
-                                pluginRouter.use((req, res, next) => {
-                                    res.raw.on('finish', () => {
-                                        cb(req, res).catch(() => {
-                                            /* ignore */
-                                        });
-                                    });
-                                    next();
-                                });
-                            }
-                            return receiver;
-                        };
-                    }
-                    const value = Reflect.get(target, prop, receiver);
-                    return typeof value === 'function' ? value.bind(target) : value;
-                },
-            });
-        }
-        await plugin.register(targetApp, options);
-        if (pluginRouter) {
-            this.mount('/', pluginRouter);
-        }
-        this.registeredPlugins.set(plugin.name, plugin);
+        await this.pluginManager.register(pluginOrInstance, legacyOptions);
         return this;
     }
     // ─── Middleware ─────────────────────────────────────────────────────────────
@@ -407,340 +294,7 @@ class App {
     }
     // ─── Class-Based Controllers Registration ──────────────────────────────────
     registerControllers(controllers, basePath = '', prefixMiddlewares = []) {
-        const ROUTE_REGISTRY = Symbol.for('exisjs:routes');
-        const CONTROLLER_PREFIX = Symbol.for('exisjs:controller_prefix');
-        const CONTROLLER_HOST = Symbol.for('exisjs:controller_host');
-        const MIDDLEWARE_REGISTRY = Symbol.for('exisjs:middlewares');
-        const ROUTE_METADATA = Symbol.for('exisjs:route_metadata');
-        const LIFECYCLE_METADATA = Symbol.for('exisjs:lifecycle_metadata');
-        const PARAM_METADATA = Symbol.for('exisjs:param_metadata');
-        for (const ControllerClass of controllers) {
-            const prefix = ControllerClass.prototype[CONTROLLER_PREFIX] || '';
-            const host = ControllerClass.prototype[CONTROLLER_HOST];
-            const routes = ControllerClass.prototype[ROUTE_REGISTRY] || [];
-            const classMiddlewares = [
-                ...(Array.isArray(ControllerClass.prototype[MIDDLEWARE_REGISTRY])
-                    ? ControllerClass.prototype[MIDDLEWARE_REGISTRY]
-                    : ControllerClass.prototype[MIDDLEWARE_REGISTRY]?._classMiddlewares ||
-                        []),
-            ];
-            const methodMiddlewares = (!Array.isArray(ControllerClass.prototype[MIDDLEWARE_REGISTRY])
-                ? ControllerClass.prototype[MIDDLEWARE_REGISTRY]
-                : {}) || {};
-            const routeMetadataMap = ControllerClass.prototype[ROUTE_METADATA] || {};
-            const lifecycleMetadataMap = ControllerClass.prototype[LIFECYCLE_METADATA] || {};
-            const paramMetadataMap = ControllerClass.prototype[PARAM_METADATA] || {};
-            for (const route of routes) {
-                const method = route.method.toLowerCase();
-                const executeCore = async (req, res, next, streamOrSocket) => {
-                    let instance = this.container.resolve(ControllerClass);
-                    if (!instance) {
-                        // Auto-instantiate if not provided via DI
-                        instance = new ControllerClass();
-                        this.container.provide(ControllerClass, { useValue: instance });
-                    }
-                    try {
-                        // 0. Enforce Route Permissions (Role Authorization)
-                        const routeMetadata = routeMetadataMap[route.handlerName] || {};
-                        const permissions = routeMetadata.permissions;
-                        if (permissions && permissions.length > 0) {
-                            const userPerms = req.user?.permissions || (req.user?.role ? [req.user.role] : []);
-                            const hasPermission = permissions.some((p) => userPerms.includes(p));
-                            if (!hasPermission) {
-                                if (res) {
-                                    res.status(403).json({
-                                        success: false,
-                                        error: {
-                                            code: 'FORBIDDEN',
-                                            message: 'Insufficient permissions to access this resource',
-                                        },
-                                    });
-                                }
-                                return;
-                            }
-                        }
-                        // 1. Run Guards
-                        const routeLifecycle = lifecycleMetadataMap[route.handlerName] || {};
-                        const guards = routeLifecycle.guards || [];
-                        for (const guard of guards) {
-                            let allowed = false;
-                            if (typeof guard === 'function') {
-                                if (guard.prototype &&
-                                    typeof guard.prototype.canActivate === 'function') {
-                                    let guardInstance = this.container.resolve(guard);
-                                    if (!guardInstance) {
-                                        guardInstance = new guard();
-                                    }
-                                    allowed = await guardInstance.canActivate(req);
-                                }
-                                else {
-                                    allowed = await guard(req);
-                                }
-                            }
-                            if (!allowed) {
-                                if (res) {
-                                    res.status(403).json({
-                                        success: false,
-                                        error: { code: 'FORBIDDEN', message: 'Forbidden by Guard' },
-                                    });
-                                }
-                                return;
-                            }
-                        }
-                        // 2. Resolve parameters
-                        const paramMetadata = paramMetadataMap[route.handlerName] || [];
-                        const args = [];
-                        if (paramMetadata.length === 0) {
-                            if (method === 'ws' || method === 'sse') {
-                                args.push(req, streamOrSocket);
-                            }
-                            else {
-                                args.push(req, res, next);
-                            }
-                        }
-                        else {
-                            for (const param of paramMetadata) {
-                                if (!param) {
-                                    args.push(undefined);
-                                    continue;
-                                }
-                                let rawArg;
-                                switch (param.type) {
-                                    case 'req':
-                                        rawArg = req;
-                                        break;
-                                    case 'res':
-                                        rawArg = res;
-                                        break;
-                                    case 'body':
-                                        if (req.body === undefined &&
-                                            ['POST', 'PUT', 'PATCH'].includes(req.method)) {
-                                            const contentType = req.headers['content-type'] || '';
-                                            if (contentType.includes('json')) {
-                                                await req.json().catch(() => {
-                                                    /* noop */
-                                                });
-                                            }
-                                            else if (contentType.includes('form')) {
-                                                await req.formData().catch(() => {
-                                                    /* noop */
-                                                });
-                                            }
-                                        }
-                                        rawArg = req.body;
-                                        break;
-                                    case 'param':
-                                        rawArg = param.name ? req.params[param.name] : req.params;
-                                        break;
-                                    case 'query':
-                                        rawArg = param.name ? req.query[param.name] : req.query;
-                                        break;
-                                    case 'header':
-                                        rawArg = param.name
-                                            ? req.headers[param.name.toLowerCase()]
-                                            : req.headers;
-                                        break;
-                                    case 'session':
-                                        rawArg = req.session;
-                                        break;
-                                    case 'next':
-                                        rawArg = next;
-                                        break;
-                                    case 'host':
-                                        rawArg = param.name
-                                            ? req.params[param.name]
-                                            : req.hostname;
-                                        break;
-                                    case 'socket':
-                                    case 'stream':
-                                        rawArg = streamOrSocket;
-                                        break;
-                                    case 'ip':
-                                        rawArg = req.ip;
-                                        break;
-                                    case 'uploadedFile':
-                                    case 'uploadedFiles':
-                                        if (req.body === undefined &&
-                                            ['POST', 'PUT', 'PATCH'].includes(req.method)) {
-                                            await req.formData().catch(() => {
-                                                /* noop */
-                                            });
-                                        }
-                                        if (req.files) {
-                                            const isMulti = param.type === 'uploadedFiles';
-                                            let files = [];
-                                            if (param.name) {
-                                                files = req.files.filter((f) => f.fieldname === param.name);
-                                            }
-                                            else {
-                                                files = req.files;
-                                            }
-                                            rawArg = isMulti ? files : files[0];
-                                        }
-                                        break;
-                                    default:
-                                        rawArg = undefined;
-                                }
-                                if (param.pipes && param.pipes.length > 0) {
-                                    for (const pipe of param.pipes) {
-                                        if (typeof pipe === 'function' &&
-                                            pipe.prototype?.transform) {
-                                            let pipeInstance = this.container.resolve(pipe);
-                                            if (!pipeInstance)
-                                                pipeInstance = new pipe();
-                                            rawArg = await pipeInstance.transform(rawArg, {
-                                                type: param.type,
-                                                name: param.name,
-                                            });
-                                        }
-                                        else if (typeof pipe === 'object' &&
-                                            typeof pipe.parse === 'function') {
-                                            rawArg = await pipe.parse(rawArg);
-                                        }
-                                        else if (typeof pipe === 'object' &&
-                                            typeof pipe.transform === 'function') {
-                                            rawArg = await pipe.transform(rawArg, {
-                                                type: param.type,
-                                                name: param.name,
-                                            });
-                                        }
-                                        else if (typeof pipe === 'function') {
-                                            rawArg = await pipe(rawArg);
-                                        }
-                                    }
-                                }
-                                args.push(rawArg);
-                            }
-                        }
-                        // 3. Execute Custom Interceptors
-                        const interceptors = routeLifecycle.interceptors || [];
-                        for (const interceptor of interceptors) {
-                            if (typeof interceptor === 'function') {
-                                if (interceptor.prototype &&
-                                    typeof interceptor.prototype.intercept === 'function') {
-                                    let interceptorInstance = this.container.resolve(interceptor);
-                                    if (!interceptorInstance) {
-                                        interceptorInstance = new interceptor();
-                                    }
-                                    await interceptorInstance.intercept(req, res);
-                                }
-                                else {
-                                    await interceptor(req, res);
-                                }
-                            }
-                        }
-                        // 4. Invoke the method
-                        const result = await instance[route.handlerName](...args);
-                        if (res && !res.headersSent) {
-                            const routeMeta = routeMetadataMap[route.handlerName] || {};
-                            if (routeMeta.redirect) {
-                                res.redirect(routeMeta.redirect.url, routeMeta.redirect.statusCode);
-                                return;
-                            }
-                            // Apply custom headers
-                            if (routeMeta.headers) {
-                                for (const [name, val] of Object.entries(routeMeta.headers)) {
-                                    res.setHeader(name, val);
-                                }
-                            }
-                            // Apply custom HTTP Code
-                            if (routeMeta.httpCode) {
-                                res.status(routeMeta.httpCode);
-                            }
-                            if (result !== undefined) {
-                                res.json(result);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        let handled = false;
-                        const routeLifecycle = lifecycleMetadataMap[route.handlerName] || {};
-                        const filters = routeLifecycle.filters || [];
-                        for (const filter of filters) {
-                            if (typeof filter === 'function' && filter.prototype?.catch) {
-                                let filterInstance = this.container.resolve(filter);
-                                if (!filterInstance)
-                                    filterInstance = new filter();
-                                await filterInstance.catch(err, { req, res });
-                                handled = true;
-                                break;
-                            }
-                            else if (typeof filter === 'object' &&
-                                typeof filter.catch === 'function') {
-                                await filter.catch(err, { req, res });
-                                handled = true;
-                                break;
-                            }
-                        }
-                        if (!handled) {
-                            if (next)
-                                next(err);
-                            else
-                                console.error(`[Exis ${method.toUpperCase()} Error]`, err);
-                        }
-                    }
-                };
-                let finalHandler;
-                if (method === 'ws' || method === 'sse') {
-                    finalHandler = async (streamOrSocket, rawReq) => {
-                        await executeCore(rawReq, undefined, undefined, streamOrSocket);
-                    };
-                }
-                else {
-                    finalHandler = async (req, res, next) => {
-                        await executeCore(req, res, next);
-                    };
-                }
-                const fullPath = (basePath + prefix + route.path).replace(/\/+/g, '/') || '/';
-                const routeSpecificMiddlewares = methodMiddlewares[route.handlerName] || [];
-                const allMiddlewares = [
-                    ...prefixMiddlewares,
-                    ...classMiddlewares,
-                    ...routeSpecificMiddlewares,
-                ];
-                const routeMeta = routeMetadataMap[route.handlerName] || {};
-                const finalHost = routeMeta.hosts || host;
-                let schema = route.schema;
-                const paramMetadata = paramMetadataMap[route.handlerName] || [];
-                let extractedBodySchema = undefined;
-                let extractedQuerySchema = undefined;
-                for (const param of paramMetadata) {
-                    if (!param)
-                        continue;
-                    if (param.type === 'body') {
-                        const bodyPipe = param.pipes?.find((p) => p && typeof p.parse === 'function');
-                        if (bodyPipe)
-                            extractedBodySchema = bodyPipe;
-                    }
-                    if (param.type === 'query') {
-                        const queryPipe = param.pipes?.find((p) => p && typeof p.parse === 'function');
-                        if (queryPipe)
-                            extractedQuerySchema = queryPipe;
-                    }
-                }
-                const extractedResponseSchema = routeMeta.responseSchema;
-                if (schema ||
-                    finalHost ||
-                    extractedBodySchema ||
-                    extractedQuerySchema ||
-                    extractedResponseSchema) {
-                    schema = schema || {};
-                    if (finalHost)
-                        schema.host = finalHost;
-                    if (extractedBodySchema && !schema.body)
-                        schema.body = extractedBodySchema;
-                    if (extractedQuerySchema && !schema.query)
-                        schema.query = extractedQuerySchema;
-                    if (extractedResponseSchema && !schema.response)
-                        schema.response = extractedResponseSchema;
-                    this.router[method](fullPath, ...allMiddlewares, schema, finalHandler);
-                }
-                else {
-                    ;
-                    this.router[method](fullPath, ...allMiddlewares, finalHandler);
-                }
-            }
-        }
+        this.controllerRegistrar.registerControllers(controllers, basePath, prefixMiddlewares);
         return this;
     }
     // ─── Dependency Injection ───────────────────────────────────────────────────
@@ -788,681 +342,32 @@ class App {
             this.errorHandlers.push((0, errors_1.createErrorHandler)(this.options.env === 'development'));
         }
     }
-    getCompiledPipeline() {
-        if (this._compiledPipeline)
-            return this._compiledPipeline;
-        this.applyBuiltins();
-        this._compiledPipeline = [
-            ...this.globalMiddleware,
-            (req, res, next) => this.router.handle(req, res, next),
-            middleware_1.notFound,
-        ];
-        return this._compiledPipeline;
-    }
-    // ─── Web Standard Fetch (Edge Runtime) & Inject ──────────────────────────────
     async fetch(request, env, ctx) {
-        if (!this._routesMounted) {
-            if (typeof this.create === 'function')
-                await this.create();
-            if (typeof this.onStartHook === 'function')
-                await this.onStartHook(this);
-        }
-        const { handleFetch } = await Promise.resolve().then(() => __importStar(require('../adapters/fetch')));
-        return handleFetch(this, request, env, ctx);
+        return this.requestHandler.fetch(request, env, ctx);
     }
     async inject(options) {
-        const method = (options.method || 'GET').toUpperCase();
-        const url = options.url.startsWith('http')
-            ? options.url
-            : `http://localhost${options.url}`;
-        const headers = new Headers();
-        if (options.headers) {
-            for (const [k, v] of Object.entries(options.headers)) {
-                headers.set(k, v);
-            }
-        }
-        let bodyStr;
-        if (options.body) {
-            bodyStr =
-                typeof options.body === 'string'
-                    ? options.body
-                    : JSON.stringify(options.body);
-            if (!headers.has('content-type') && typeof options.body !== 'string') {
-                headers.set('content-type', 'application/json');
-            }
-        }
-        const req = new Request(url, {
-            method,
-            headers,
-            body: ['GET', 'HEAD', 'OPTIONS'].includes(method) ? undefined : bodyStr,
-        });
-        const fetchRes = await this.fetch(req);
-        const resText = await fetchRes.text();
-        let parsedBody = resText;
-        try {
-            parsedBody = JSON.parse(resText);
-        }
-        catch {
-            // ignore
-        }
-        const resHeaders = {};
-        fetchRes.headers.forEach((v, k) => {
-            resHeaders[k] = v;
-        });
-        return {
-            status: fetchRes.status,
-            headers: resHeaders,
-            body: parsedBody,
-            text: resText,
-        };
+        return this.requestHandler.inject(options);
     }
     // ─── Private Internal Pipeline Handler ─────────────────────────────────────────────────────
-    _executeWithContext(req, res, execution) {
-        const store = {
-            state: {},
-            afterCallbacks: [],
-            req: req,
-            res: res,
-            app: this,
-            diCache: new Map(),
-        };
-        res.raw.on('finish', () => {
-            for (const cb of store.afterCallbacks) {
-                try {
-                    const promise = cb();
-                    if (promise instanceof Promise) {
-                        promise.catch((err) => {
-                            this.log.error({ err }, 'Error in after() background task');
-                        });
-                    }
-                }
-                catch (err) {
-                    this.log.error({ err }, 'Error in after() background task');
-                }
-            }
-        });
-        context_1.executionContext.run(store, execution);
+    getCompiledPipeline() {
+        return this.requestHandler.getCompiledPipeline();
     }
     handle(rawReq, rawRes) {
-        const res = new response_1.ExisResponse(rawRes);
-        const req = new request_1.ExisRequest(rawReq, res, this.options.trustProxy, this.options.bodyLimit);
-        res.req = req;
-        res.etagEnabled = this.options.etag === true;
-        req.log = this.log;
-        req._dataloaderFns = this._dataloaders;
-        this._executeWithContext(req, res, () => {
-            if (this.hooks.request.length === 0 && this.hooks.response.length === 0) {
-                (0, router_1.runHandlers)(this.getCompiledPipeline(), req, res, (err) => {
-                    if (err) {
-                        this._runErrorHandlers(err, req, res).catch((e) => {
-                            this.log.error({ err: e }, 'Error in error handler');
-                        });
-                    }
-                });
-                return;
-            }
-            this._handleWithHooks(req, res, rawRes);
-        });
+        this.requestHandler.handle(rawReq, rawRes);
     }
     /**
      * Handle a request from the uWebSockets.js backend.
      * Uses the same middleware pipeline as Node HTTP but with uWS shims.
      */
     handleUws(shimReq, shimRes) {
-        // Wrap uWS shims in ExisRequest/ExisResponse using type coercion
-        // The shims implement the same interface that ExisRequest/ExisResponse expect
-        const res = new response_1.ExisResponse(shimRes);
-        const req = new request_1.ExisRequest(shimReq, res, this.options.trustProxy, this.options.bodyLimit);
-        res.req = req;
-        res.etagEnabled = this.options.etag === true;
-        req.log = this.log;
-        req._dataloaderFns = this._dataloaders;
-        this._executeWithContext(req, res, () => {
-            if (this.hooks.request.length === 0 && this.hooks.response.length === 0) {
-                (0, router_1.runHandlers)(this.getCompiledPipeline(), req, res, (err) => {
-                    if (err) {
-                        this._runErrorHandlers(err, req, res).catch((e) => {
-                            this.log.error({ err: e }, 'Error in error handler');
-                        });
-                    }
-                });
-                return;
-            }
-            this._handleWithHooks(req, res, shimRes);
-        });
-    }
-    async _handleWithHooks(req, res, rawRes) {
-        // ─── onRequest Hook ───
-        if (this.hooks.request.length > 0) {
-            // eslint-disable-next-line @typescript-eslint/prefer-for-of
-            for (let i = 0; i < this.hooks.request.length; i++) {
-                await this.hooks.request[i](req, res);
-            }
-        }
-        if (res.headersSent)
-            return;
-        // ─── onResponse Hook ───
-        if (this.hooks.response.length > 0) {
-            rawRes.on('finish', () => {
-                // eslint-disable-next-line @typescript-eslint/prefer-for-of
-                for (let i = 0; i < this.hooks.response.length; i++) {
-                    Promise.resolve(this.hooks.response[i](req, res)).catch((err) => {
-                        this.log.error({ err }, 'Error in onResponse hook');
-                    });
-                }
-            });
-        }
-        (0, router_1.runHandlers)(this.getCompiledPipeline(), req, res, (err) => {
-            if (err) {
-                this._runErrorHandlers(err, req, res).catch((e) => {
-                    this.log.error({ err: e }, 'Error in error handler');
-                });
-            }
-        });
-    }
-    async _runErrorHandlers(err, req, res) {
-        // ─── onError Hook ───
-        if (this.hooks.error.length > 0) {
-            // eslint-disable-next-line @typescript-eslint/prefer-for-of
-            for (let i = 0; i < this.hooks.error.length; i++) {
-                await this.hooks.error[i](err, req, res);
-            }
-        }
-        if (res.headersSent)
-            return;
-        for (const handler of this.errorHandlers) {
-            let handled = false;
-            await handler(err, req, res, () => {
-                handled = true;
-            });
-            if (!handled || res.headersSent)
-                return;
-        }
-        // fallback if no error handler ran
-        const defaultHandler = (0, errors_1.createErrorHandler)(this.options.env === 'development');
-        await defaultHandler(err, req, res, () => {
-            /* noop */
-        });
-    }
-    // ─── WebSocket Upgrade Handler ───────────────────────────────────────────────
-    async _handleUpgrade(rawReq, socket, head) {
-        this.applyBuiltins();
-        // Match route
-        const reqPath = (rawReq.url || '').split('?')[0];
-        const matched = this.router.match('WS', reqPath);
-        if (!matched) {
-            socket.write('HTTP/1.1 404 Not Found\\r\\n\\r\\n');
-            socket.destroy();
-            return;
-        }
-        // Create a dummy ServerResponse so standard HTTP middleware can run and reject if needed
-        const rawRes = new node_http_1.ServerResponse(rawReq);
-        rawRes.assignSocket(socket);
-        const res = new response_1.ExisResponse(rawRes);
-        const originalMethod = rawReq.method;
-        const req = new request_1.ExisRequest(rawReq, res, this.options.trustProxy, this.options.bodyLimit);
-        res.req = req;
-        req.method = 'WS';
-        req.params = matched.params;
-        req.log = this.log;
-        // Build the middleware pipeline specifically for this WebSocket route
-        const pipeline = [
-            ...this.globalMiddleware,
-            async (req, res, next) => {
-                // Exclude the last handler which is the actual WsHandler wrapper
-                const routeHandlers = matched.route.handlers.slice(0, -1);
-                (0, router_1.runHandlers)(routeHandlers, req, res, (err) => {
-                    if (err)
-                        return next(err);
-                    next();
-                });
-            },
-        ];
-        await (0, router_1.runHandlers)(pipeline, req, res, async (err) => {
-            if (err) {
-                this.log.error({ err }, 'Error during WebSocket upgrade middleware');
-                socket.write('HTTP/1.1 500 Internal Server Error\\r\\n\\r\\n');
-                socket.destroy();
-                return;
-            }
-            if (res.headersSent) {
-                // A middleware intercepted and sent an HTTP response (e.g. 401 Unauthorized)
-                socket.destroy();
-                return;
-            }
-            // Restore original HTTP method (usually 'GET') so the `ws` package doesn't reject with 405
-            rawReq.method = originalMethod;
-            // Middleware passed, perform upgrade
-            this.rawWsServer.handleUpgrade(rawReq, socket, head, (ws) => {
-                const exisWs = new socket_1.ExisWebSocket(ws, req, this.wsServer);
-                this.wsServer.track(exisWs);
-                req.ws = exisWs;
-                const finalHandler = matched.route.handlers[matched.route.handlers.length - 1];
-                Promise.resolve(finalHandler(req, res, () => {
-                    /* noop */
-                })).catch((err) => {
-                    this.log.error({ err }, 'Error in WebSocket handler');
-                    ws.close(1011, 'Internal Server Error');
-                });
-            });
-        });
+        this.requestHandler.handleUws(shimReq, shimRes);
     }
-    /**
-     * WebSocket Upgrade Handler for uWebSockets.js
-     * Runs the middleware pipeline and if successful, upgrades the connection.
-     */
-    async handleUwsUpgrade(shimReq, uwsRes, context) {
-        this.applyBuiltins();
-        const reqPath = (shimReq.url || '').split('?')[0];
-        const matched = this.router.match('WS', reqPath);
-        if (!matched) {
-            // 404
-            uwsRes.cork(() => {
-                uwsRes.writeStatus('404 Not Found');
-                uwsRes.end();
-            });
-            return;
-        }
-        let isAborted = false;
-        uwsRes.onAborted(() => {
-            isAborted = true;
-        });
-        const shimRes = new uws_adapter_1.UwsServerResponse(uwsRes);
-        const res = new response_1.ExisResponse(shimRes);
-        const req = new request_1.ExisRequest(shimReq, res, this.options.trustProxy, this.options.bodyLimit);
-        res.req = req;
-        req.method = 'WS';
-        req.params = matched.params;
-        req.log = this.log;
-        const pipeline = [
-            ...this.globalMiddleware,
-            async (req, res, next) => {
-                const routeHandlers = matched.route.handlers.slice(0, -1);
-                (0, router_1.runHandlers)(routeHandlers, req, res, (err) => {
-                    if (err)
-                        return next(err);
-                    next();
-                });
-            },
-        ];
-        this._executeWithContext(req, res, () => {
-            (0, router_1.runHandlers)(pipeline, req, res, async (err) => {
-                if (isAborted)
-                    return;
-                if (err) {
-                    this.log.error({ err }, 'Error during uWS WebSocket upgrade middleware');
-                    uwsRes.cork(() => {
-                        uwsRes.writeStatus('500 Internal Server Error');
-                        uwsRes.end();
-                    });
-                    return;
-                }
-                if (res.headersSent) {
-                    return; // Middleware sent an HTTP response
-                }
-                // We need to fetch headers directly from the shimReq.headers
-                const secWebSocketKey = shimReq.headers['sec-websocket-key'] || '';
-                const secWebSocketProtocol = shimReq.headers['sec-websocket-protocol'] || '';
-                const secWebSocketExtensions = shimReq.headers['sec-websocket-extensions'] || '';
-                // Prepare user data for the upgraded websocket
-                const userData = {
-                    req,
-                    res,
-                    exisWs: new socket_1.ExisWebSocket(null, req, this.wsServer), // the raw will be set to shim in open()
-                    finalHandler: matched.route.handlers[matched.route.handlers.length - 1],
-                };
-                this.wsServer.track(userData.exisWs);
-                req.ws = userData.exisWs;
-                uwsRes.cork(() => {
-                    uwsRes.upgrade(userData, secWebSocketKey, secWebSocketProtocol, secWebSocketExtensions, context);
-                });
-                Promise.resolve(userData.finalHandler(req, res, () => {
-                    /* noop */
-                })).catch((e) => {
-                    this.log.error({ err: e }, 'Error in uWS WebSocket handler');
-                });
-            });
-        });
+    getErrorHandlers() {
+        return this.errorHandlers;
     }
     // ─── Listen ───────────────────────────────────────────────────────────────────
-    listen(portOrOptions, callback) {
-        if (process.env.EXIS_CLI_MODE === '1') {
-            return undefined;
-        }
-        this.applyBuiltins();
-        let port;
-        let host;
-        let onListen;
-        if (typeof portOrOptions === 'number') {
-            port = portOrOptions;
-            host = this.options.host;
-            onListen = callback ? () => callback() : undefined;
-        }
-        else if (typeof portOrOptions === 'object') {
-            if (portOrOptions.ssl) {
-                this.options.ssl = portOrOptions.ssl;
-                // Re-initialize server if ssl is passed during listen
-                this.server = this._initServer();
-            }
-            if (portOrOptions.redirectHttp !== undefined) {
-                this.options.redirectHttp = portOrOptions.redirectHttp;
-            }
-            port = portOrOptions.port ?? this.options.port;
-            host = portOrOptions.host ?? this.options.host;
-            onListen = portOrOptions.onListen;
-        }
-        else {
-            port = this.options.port;
-            host = this.options.host;
-        }
-        // Auto HTTP -> HTTPS redirect server (only for Node HTTP backend)
-        // ─── uWebSockets.js listen path ───
-        if (this._useUws) {
-            this._uwsApp = (0, uws_adapter_1.createUwsApp)(this.handleUws.bind(this), this.handleUwsUpgrade.bind(this), this.options.ssl);
-            this._uwsApp.listen(port, host, async (token) => {
-                if (!token) {
-                    this.log.error(`Failed to listen on ${host}:${port} (uWS)`);
-                    return;
-                }
-                this._uwsListenToken = token;
-                const address = { port, host };
-                if (this.hotReloader) {
-                    this.hotReloader.stop();
-                }
-                if (onListen) {
-                    onListen(address);
-                }
-                else {
-                    if (!process.env.__EXIS_DEV_SERVER && !process.env.__EXIS_CLI) {
-                        const url = `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`;
-                        this.log.info({ url, env: this.options.env, backend: 'uws' }, `Server running at ${url} (uWebSockets.js)`);
-                    }
-                }
-                if (this.options.env === 'production') {
-                    const handleShutdown = async () => {
-                        this.log.info('Received shutdown signal (SIGTERM/SIGINT)');
-                        try {
-                            await this.close();
-                            process.exit(0);
-                        }
-                        catch (err) {
-                            this.log.error({ err }, 'Error during graceful shutdown');
-                            process.exit(1);
-                        }
-                    };
-                    process.once('SIGTERM', handleShutdown);
-                    process.once('SIGINT', handleShutdown);
-                }
-                // ─── onReady Hook ───
-                for (const hook of this.hooks.ready) {
-                    await hook();
-                }
-                if (callback)
-                    callback();
-            });
-            // Return a minimal server-like object for compatibility
-            return this.server;
-        }
-        // ─── Node HTTP listen path ───
-        // Auto HTTP -> HTTPS redirect server
-        if (this.options.ssl &&
-            this.options.redirectHttp !== undefined &&
-            this.options.redirectHttp !== false) {
-            const redirectPort = typeof this.options.redirectHttp === 'number'
-                ? this.options.redirectHttp
-                : 80;
-            this.redirectServer = (0, node_http_1.createServer)((req, res) => {
-                const targetHost = req.headers.host?.split(':')[0] || host;
-                const actualPort = port === 0
-                    ? this.server.address()?.port ||
-                        port
-                    : port;
-                const targetPort = actualPort === 443 ? '' : `:${actualPort}`;
-                res.writeHead(301, {
-                    Location: `https://${targetHost}${targetPort}${req.url || '/'}`,
-                });
-                res.end();
-            });
-            this.redirectServer.listen(redirectPort, host, () => {
-                this.log.info(`Redirect server listening on port ${redirectPort} -> HTTPS port ${port}`);
-            });
-        }
-        this.server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                console.error(`\n\x1b[31m✗ Port ${port} is already in use.\x1b[0m`);
-                console.error(`  Try killing the process or use a different port in exis.config.ts\n`);
-                process.exit(1);
-            }
-            else {
-                this.log.error({ err }, 'Failed to start server');
-                process.exit(1);
-            }
-        });
-        this.server.listen(port, host, async () => {
-            const address = { port, host };
-            if (this.options.env === 'production') {
-                const handleShutdown = async () => {
-                    this.log.info('Received shutdown signal (SIGTERM/SIGINT)');
-                    try {
-                        await this.close();
-                        process.exit(0);
-                    }
-                    catch (err) {
-                        this.log.error({ err }, 'Error during graceful shutdown');
-                        process.exit(1);
-                    }
-                };
-                process.once('SIGTERM', handleShutdown);
-                process.once('SIGINT', handleShutdown);
-            }
-            // ─── onReady Hook ───
-            for (const hook of this.hooks.ready) {
-                await hook();
-            }
-            // Start queue worker if initialized
-            if (this._queueWorker) {
-                await this._queueWorker.start();
-            }
-            if (onListen) {
-                onListen(address);
-            }
-            else {
-                if (!process.env.__EXIS_DEV_SERVER && !process.env.__EXIS_CLI) {
-                    const url = `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`;
-                    this.log.info({ url, env: this.options.env }, `Server running at ${url}`);
-                }
-            }
-            if (callback)
-                callback();
-        });
-        return this.server;
-    }
-    // ─── Banner ───────────────────────────────────────────────────────────────────
-    async _printStartupBanner() {
-        const port = this.options.port ?? 3000;
-        const host = this.options.host ?? 'localhost';
-        const c = {
-            cyan: '\x1b[36m',
-            green: '\x1b[32m',
-            gray: '\x1b[90m',
-            dim: '\x1b[2m',
-            bold: '\x1b[1m',
-            reset: '\x1b[0m',
-            magenta: '\x1b[35m',
-            bgMagenta: '\x1b[45m',
-            white: '\x1b[37m',
-            primary: '\x1b[38;2;160;70;255m',
-            blue: '\x1b[38;2;41;169;206m',
-        };
-        let fwVersion = '0.0.0';
-        try {
-            const fs = await Promise.resolve().then(() => __importStar(require('node:fs')));
-            const path = await Promise.resolve().then(() => __importStar(require('node:path')));
-            const pkgPath = path.join(__dirname, '../../package.json');
-            fwVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
-        }
-        catch {
-            /* ignore */
-        }
-        const displayHost = host === '0.0.0.0' || host === '127.0.0.1' ? 'localhost' : host;
-        let localIp = '<YOUR_IP>';
-        try {
-            const os = await Promise.resolve().then(() => __importStar(require('node:os')));
-            const nets = os.networkInterfaces();
-            for (const name of Object.keys(nets)) {
-                for (const net of nets[name] || []) {
-                    if (net.family === 'IPv4' && !net.internal) {
-                        localIp = net.address;
-                        break;
-                    }
-                }
-                if (localIp !== '<YOUR_IP>')
-                    break;
-            }
-        }
-        catch {
-            /* ignore */
-        }
-        const networkHost = host === '0.0.0.0'
-            ? `http://${localIp}:${port}`
-            : 'use --host 0.0.0.0 to expose';
-        const readyMs = 125;
-        const displayEnv = this.options.env || process.env.NODE_ENV || 'development';
-        const workerCount = process.env.__EXIS_CLUSTER_WORKERS;
-        const cluster = await Promise.resolve().then(() => __importStar(require('node:cluster')));
-        // In cluster mode, ONLY let Worker #1 print the banner so we don't spam the console 12 times
-        if (cluster.default.isWorker && cluster.default.worker?.id !== 1) {
-            return;
-        }
-        console.log(`\n  ${c.primary}${c.bold}EXIS v${fwVersion}${c.reset}  ready in ${c.bold}${readyMs} ms${c.reset}\n`);
-        console.log(`  ${c.white}➜${c.reset}  ${c.bold}Local:${c.reset}   ${c.blue}http://${displayHost}:${port}/${c.reset}`);
-        console.log(`  ${c.white}➜${c.reset}  ${c.dim}Network:${c.reset} ${c.blue}${networkHost}/${c.reset}`);
-        console.log(`  ${c.white}➜${c.reset}  ${c.dim}Environ:${c.reset} ${c.green}${displayEnv}${c.reset}`);
-        if (workerCount && Number(workerCount) > 1) {
-            console.log(`  ${c.white}➜${c.reset}  ${c.dim}Workers:${c.reset} ${c.magenta}${workerCount}${c.reset}`);
-        }
-        console.log(`  ${c.white}➜${c.reset}  press ${c.bold}h + enter${c.reset} ${c.dim}to show help${c.reset}\n`);
-    }
-    // ─── Graceful Shutdown ────────────────────────────────────────────────────────
-    onShutdown(hook) {
-        this.shutdownHooks.push(hook);
-        return this;
-    }
-    close(timeout = 5000) {
-        return new Promise((resolve, reject) => {
-            this.log.info('Initiating graceful shutdown');
-            let finishCalled = false;
-            const finish = async () => {
-                if (finishCalled)
-                    return;
-                finishCalled = true;
-                try {
-                    for (const hook of this.shutdownHooks) {
-                        await hook();
-                    }
-                    // Also execute onClose hooks
-                    for (const hook of this.hooks.close) {
-                        await hook();
-                    }
-                    if (this.onCloseHook) {
-                        await this.onCloseHook(this);
-                    }
-                    if (this._cronScheduler) {
-                        this._cronScheduler.stop();
-                    }
-                    if (this._queueWorker) {
-                        await this._queueWorker.stop();
-                    }
-                    if (this._queueClient) {
-                        await this._queueClient.close();
-                    }
-                    if (this.hotReloader) {
-                        await this.hotReloader.stop();
-                    }
-                    this.log.info('Graceful shutdown completed');
-                    resolve();
-                }
-                catch (err) {
-                    this.log.error({ err }, 'Error executing shutdown hooks');
-                    reject(err);
-                }
-            };
-            if (!this._useUws && (!this.server || !this.server.listening)) {
-                finish();
-                return;
-            }
-            if (this._useUws && !this._uwsListenToken) {
-                finish();
-                return;
-            }
-            // Close idle keep-alive connections immediately
-            if (!this._useUws &&
-                this.server &&
-                'closeIdleConnections' in this.server) {
-                ;
-                this.server.closeIdleConnections?.();
-            }
-            // Set timeout to force close active connections
-            const timer = setTimeout(() => {
-                this.log.warn(`Shutdown timeout of ${timeout}ms exceeded, forcefully terminating active connections`);
-                if (!this._useUws &&
-                    this.server &&
-                    'closeAllConnections' in this.server) {
-                    ;
-                    this.server.closeAllConnections?.();
-                }
-                finish(); // Ensure finish is called on timeout
-            }, timeout);
-            const cleanupAndFinish = async () => {
-                clearTimeout(timer);
-                await finish();
-            };
-            this.wsServer.close();
-            for (const client of this.rawWsServer.clients) {
-                client.terminate();
-            }
-            this.rawWsServer.close();
-            if (this.redirectServer) {
-                this.redirectServer.close();
-            }
-            if (this._useUws && this._uwsApp) {
-                this._uwsApp.close(this._uwsListenToken);
-                this._uwsListenToken = null;
-                cleanupAndFinish();
-            }
-            else {
-                this.server.close((err) => {
-                    if (err)
-                        reject(err);
-                    else
-                        cleanupAndFinish();
-                });
-            }
-        });
-    }
-    // ─── Expose internals ─────────────────────────────────────────────────────────
-    getRouter() {
-        return this.router;
-    }
-    async loadAllRoutes() {
-        for (const [filePath, entry] of this.lazyRoutes.entries()) {
-            if (!entry.loaded) {
-                entry.loaded = true;
-                this.router.removeRoutesBySource('lazy:' + filePath);
-                const routePath = this.routeMap.get(filePath);
-                if (routePath) {
-                    try {
-                        await this.mountRouteFile(filePath, routePath);
-                    }
-                    catch (e) {
-                        this.log.error({ err: e, file: filePath }, 'Failed to eager-load route');
-                    }
-                }
-            }
-        }
-    }
     getServer() {
-        return this.server;
+        return this.bootstrapper.getServer();
     }
     getConfig() {
         return this.options;
@@ -1481,6 +386,16 @@ class App {
             this._loggerCreated = false;
             this.ensureLogger();
             this._configLoaded = true;
+            if (this.options.env === 'development') {
+                const { getAvailablePort } = await Promise.resolve().then(() => __importStar(require('../utils/port')));
+                const requestedPort = this.options.port || 3000;
+                const host = this.options.host || '0.0.0.0';
+                const availablePort = await getAvailablePort(requestedPort, host);
+                if (availablePort !== requestedPort) {
+                    this.log.info(`Port ${requestedPort} is in use, using ${availablePort} instead.`);
+                }
+                this.options.port = availablePort;
+            }
             if ((process.env.__EXIS_DEV_SERVER || process.env.__EXIS_CLI) &&
                 !process.env.__EXIS_REPL &&
                 !process.env.__EXIS_TEST) {
@@ -1488,910 +403,71 @@ class App {
             }
         }
         // Initialize Queue after config is loaded
-        if (this.options.queue && !this._queueClient) {
-            this._initQueue(this.options.queue);
+        if (this.options.queue && !this.queueManager._queueClient) {
+            this.queueManager._initQueue(this.options.queue);
         }
         // Flush any pending jobs that were registered before config was loaded
-        if (this._pendingQueueJobs.length > 0) {
-            if (!this._queueWorker) {
+        if (this.queueManager._pendingQueueJobs.length > 0) {
+            if (!this.queueManager._queueWorker) {
                 if (this.options.queue?.enableWorkers !== false) {
                     throw new Error('Queue worker is not initialized. Please configure ExisConfig.queue first.');
                 }
             }
             else {
-                for (const job of this._pendingQueueJobs) {
-                    this._queueWorker.registerJob(job);
-                    if (this._cronScheduler && job.cron) {
-                        this._cronScheduler.registerJob(job);
+                for (const job of this.queueManager._pendingQueueJobs) {
+                    this.queueManager._queueWorker.registerJob(job);
+                    if (this.queueManager._cronScheduler && job.cron) {
+                        this.queueManager._cronScheduler.registerJob(job);
                     }
                 }
             }
-            this._pendingQueueJobs = [];
+            this.queueManager._pendingQueueJobs = [];
         }
         if (this._routesMounted)
             return this;
         // Automatically scan and mount file-based routes and jobs
-        await this.autoMountRoutes(root);
-        await this.autoMountJobs(root);
+        await this.routeScanner.autoMountRoutes(root);
+        await this.routeScanner.autoMountJobs(root);
         this._routesMounted = true;
         // Start Hot Route Reloading in dev mode
-        if (this.options.env === 'development' && this._allApiDirs) {
+        if (this.options.env === 'development' &&
+            this.routeScanner._allApiDirs) {
             this.hotReloader = new hot_reload_1.HotReloader({
-                apiDirs: this._allApiDirs,
+                apiDirs: this.routeScanner._allApiDirs,
                 router: this.router,
-                routeMap: this.routeMap,
-                mountRoute: (filePath, routePath) => this.mountRouteFile(filePath, routePath),
+                routeMap: this.routeScanner.routeMap,
+                mountRoute: (filePath, routePath) => this.routeScanner.mountRouteFile(filePath, routePath),
             });
             await this.hotReloader.start();
         }
         return this;
     }
-    // ─── Auto-Mount File-Based Routes ─────────────────────────────────────────────
-    async autoMountRoutes(root) {
-        const fs = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
-        const path = await Promise.resolve().then(() => __importStar(require('node:path')));
-        const isProd = process.env.NODE_ENV === 'production';
-        const isDev = this.options.env === 'development';
-        // Try to load the pre-built manifest first (O(1) boot)
-        const manifestPath = path.join(root, '.exis', 'routes-manifest.js');
-        try {
-            const stat = await fs.stat(manifestPath);
-            if (stat.isFile()) {
-                let url = (0, node_url_1.pathToFileURL)(manifestPath).href;
-                if (!isProd)
-                    url += '?t=' + Date.now(); // cache bust for dev
-                let mod;
-                if (process.env.VITEST || process.env.NODE_ENV === 'test') {
-                    mod = await Promise.resolve(`${url}`).then(s => __importStar(require(s)));
-                }
-                else {
-                    const dynamicImport = new Function('specifier', 'return import(specifier)');
-                    mod = await dynamicImport(url);
-                }
-                const manifest = mod.manifest;
-                if (Array.isArray(manifest)) {
-                    for (const entry of manifest) {
-                        const { routePath, module: routeMod, filePath } = entry;
-                        const normalizedPath = path.resolve(root, filePath);
-                        this.routeMap.set(normalizedPath, routePath);
-                        const CONTROLLER_PREFIX = Symbol.for('exisjs:controller_prefix');
-                        const isClassController = (obj) => obj &&
-                            obj.prototype &&
-                            obj.prototype[CONTROLLER_PREFIX] !== undefined;
-                        const unwrappedMod = routeMod.default && routeMod.default.default
-                            ? routeMod.default.default
-                            : routeMod.default
-                                ? routeMod.default
-                                : routeMod;
-                        const functionalControllerObj = unwrappedMod && unwrappedMod.__isController ? unwrappedMod : null;
-                        const routerInstance = routeMod.router || routeMod.default || routeMod;
-                        if (functionalControllerObj) {
-                            const router = this.compileFunctionalController(functionalControllerObj);
-                            this.mountRouteWithSource(routePath, router, normalizedPath);
-                        }
-                        else if (isClassController(routerInstance)) {
-                            this.registerControllers([routerInstance], routePath);
-                        }
-                        else {
-                            this.mountRouteWithSource(routePath, routerInstance, normalizedPath);
-                        }
-                    }
-                    // Skip the filesystem scan completely!
-                    return;
-                }
-            }
-        }
-        catch (err) {
-            if (err.code !== 'ENOENT') {
-                console.warn('exisjs: Failed to load routes manifest:', err.message);
-            }
-            // Fall back to scanning the filesystem
-        }
-        const searchDirs = isProd
-            ? [
-                path.join(root, '.exis', 'server', 'src', 'http'),
-                path.join(root, '.exis', 'server', 'http'),
-                path.join(root, 'dist', 'src', 'http'),
-                path.join(root, 'dist', 'http'),
-                path.join(root, 'src', 'http'),
-                path.join(root, 'http'),
-            ]
-            : [path.join(root, 'src', 'http'), path.join(root, 'http')];
-        const appDirs = [];
-        for (const dir of searchDirs) {
-            try {
-                const stat = await fs.stat(dir);
-                if (stat.isDirectory()) {
-                    const baseName = path.basename(path.dirname(dir)) === 'src' ? 'src/http' : 'http';
-                    const alreadyHasCompiledOrRawForThisBase = appDirs.some((existing) => {
-                        const existingBase = path.basename(path.dirname(existing)) === 'src'
-                            ? 'src/http'
-                            : 'http';
-                        return existingBase === baseName;
-                    });
-                    if (!alreadyHasCompiledOrRawForThisBase) {
-                        appDirs.push(dir);
-                    }
-                }
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        if (appDirs.length === 0)
-            return;
-        this.apiDir = appDirs[0] // keep property name for backwards compatibility
-        ;
-        this._allApiDirs = appDirs;
-        const cc = {
-            green: '\x1b[32m',
-            cyan: '\x1b[36m',
-            gray: '\x1b[90m',
-            reset: '\x1b[0m',
-        };
-        for (const appDir of appDirs) {
-            const routes = await this.scanDirectory(appDir);
-            for (const { filePath, routePath } of routes) {
-                if (filePath.endsWith('route.ts') || filePath.endsWith('route.js')) {
-                    const normalized = path.resolve(filePath);
-                    this.routeMap.set(normalized, routePath);
-                    if (isDev) {
-                        const lazyKey = normalized;
-                        this.lazyRoutes.set(lazyKey, {
-                            filePath: normalized,
-                            loaded: false,
-                        });
-                        const lazyHandler = async (req, res, next) => {
-                            const entry = this.lazyRoutes.get(lazyKey);
-                            if (entry && !entry.loaded) {
-                                entry.loaded = true;
-                                this.router.removeRoutesBySource('lazy:' + lazyKey);
-                                try {
-                                    await this.mountRouteFile(normalized, routePath);
-                                    const relative = path
-                                        .relative(process.cwd(), normalized)
-                                        .replace(/\\/g, '/');
-                                    console.log(` ${cc.green}✓${cc.reset} Lazy loaded ${cc.cyan}${relative}${cc.reset}`);
-                                }
-                                catch (err) {
-                                    (0, dev_error_overlay_1.formatDevError)(err, normalized);
-                                    return;
-                                }
-                                await this.router.handle(req, res, next);
-                            }
-                            else {
-                                next?.();
-                            }
-                        };
-                        const lazyRouter = new router_1.Router();
-                        lazyRouter.all(routePath, lazyHandler);
-                        lazyRouter.all(routePath + '/*path', lazyHandler);
-                        for (const r of lazyRouter.getRoutes()) {
-                            r.sourceFile = 'lazy:' + lazyKey;
-                            this.router.addRawRoute(r);
-                        }
-                    }
-                    else {
-                        try {
-                            await this.mountRouteFile(normalized, routePath);
-                        }
-                        catch (err) {
-                            this.log.error({ err, file: filePath }, `Failed to load route file: ${filePath}`);
-                        }
-                    }
-                }
-            }
-        }
-    }
-    // ─── Route File Mounting (shared by autoMount and HotReloader) ──────────────
-    // ─── Auto-Mount File-Based Jobs ──────────────────────────────────────────────
-    async autoMountJobs(root) {
-        if (!this._queueWorker)
-            return;
-        const fs = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
-        const path = await Promise.resolve().then(() => __importStar(require('node:path')));
-        const isProd = process.env.NODE_ENV === 'production';
-        const searchDirs = isProd
-            ? [
-                path.join(root, '.exis', 'server', 'src', 'jobs'),
-                path.join(root, '.exis', 'server', 'jobs'),
-                path.join(root, 'dist', 'src', 'jobs'),
-                path.join(root, 'dist', 'jobs'),
-                path.join(root, 'src', 'jobs'),
-                path.join(root, 'jobs'),
-            ]
-            : [path.join(root, 'src', 'jobs'), path.join(root, 'jobs')];
-        let jobsDir = '';
-        for (const dir of searchDirs) {
-            try {
-                const stat = await fs.stat(dir);
-                if (stat.isDirectory()) {
-                    jobsDir = dir;
-                    break;
-                }
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        if (!jobsDir)
-            return;
-        try {
-            const entries = await fs.readdir(jobsDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (entry.isFile() &&
-                    (entry.name.endsWith('.ts') || entry.name.endsWith('.js'))) {
-                    const filePath = path.join(jobsDir, entry.name);
-                    const name = entry.name.replace(/\.(ts|js)$/, '');
-                    try {
-                        // Load the definition directly (no compilation needed here just to get the schema)
-                        const mod = await Promise.resolve(`${filePath}`).then(s => __importStar(require(s)));
-                        const jobDef = mod.default || mod;
-                        if (jobDef) {
-                            const def = {
-                                name: jobDef.name || name,
-                                filePath, // Attach filePath for Thread Pool execution
-                                cron: jobDef.cron,
-                                schema: jobDef.schema,
-                                defaultOptions: jobDef.defaultOptions,
-                            };
-                            this._queueWorker.registerJob(def);
-                            if (this._cronScheduler && jobDef.cron) {
-                                this._cronScheduler.registerJob(def);
-                            }
-                            this.log.info(`Registered background job: ${name}`);
-                        }
-                    }
-                    catch (err) {
-                        this.log.error(`Failed to load job file ${filePath}: ${err}`);
-                    }
-                }
-            }
-        }
-        catch {
-            // Ignore if jobs directory does not exist
-        }
-    }
-    async mountRouteFile(filePath, routePath) {
-        let mod;
-        try {
-            const url = process.env.VITEST || process.env.NODE_ENV === 'test'
-                ? (0, node_url_1.pathToFileURL)(filePath).href
-                : (0, node_url_1.pathToFileURL)(filePath).href + '?t=' + Date.now();
-            if (process.env.VITEST || process.env.NODE_ENV === 'test') {
-                mod = await Promise.resolve(`${url}`).then(s => __importStar(require(s)));
-            }
-            else {
-                const dynamicImport = new Function('specifier', 'return import(specifier)');
-                mod = await dynamicImport(url);
-            }
-        }
-        catch {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            mod = require(filePath);
-        }
-        const path = await Promise.resolve().then(() => __importStar(require('node:path')));
-        const fs = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
-        const dirname = path.dirname(filePath);
-        const apiDir = this.apiDir || dirname;
-        const normDirname = path.resolve(dirname).replace(/\\/g, '/').toLowerCase();
-        const normApiDir = path.resolve(apiDir).replace(/\\/g, '/').toLowerCase();
-        const segments = normDirname.startsWith(normApiDir)
-            ? normDirname.slice(normApiDir.length).split('/').filter(Boolean)
-            : [];
-        const allMiddlewares = [];
-        const allFilters = [];
-        const allGuards = [];
-        const allInterceptors = [];
-        let allMetadata = {};
-        let allCors = undefined;
-        let allHeaders = {};
-        const activeGateways = [];
-        const dirsToCheck = [apiDir];
-        let tempDir = apiDir;
-        for (const segment of segments) {
-            tempDir = path.join(tempDir, segment);
-            dirsToCheck.push(tempDir);
-        }
-        for (const dir of dirsToCheck) {
-            try {
-                const gwPathJs = path.join(dir, 'gateway.js');
-                const gwPathTs = path.join(dir, 'gateway.ts');
-                let targetGw = '';
-                if (await fs.stat(gwPathTs).catch(() => null))
-                    targetGw = gwPathTs;
-                else if (await fs.stat(gwPathJs).catch(() => null))
-                    targetGw = gwPathJs;
-                if (targetGw) {
-                    activeGateways.push(targetGw);
-                    const gwUrl = process.env.VITEST || process.env.NODE_ENV === 'test'
-                        ? (0, node_url_1.pathToFileURL)(targetGw).href
-                        : (0, node_url_1.pathToFileURL)(targetGw).href + '?t=' + Date.now();
-                    let gwMod;
-                    try {
-                        if (process.env.VITEST || process.env.NODE_ENV === 'test') {
-                            gwMod = await Promise.resolve(`${gwUrl}`).then(s => __importStar(require(s)));
-                        }
-                        else {
-                            const dynamicImportGw = new Function('specifier', 'return import(specifier)');
-                            gwMod = await dynamicImportGw(gwUrl);
-                        }
-                    }
-                    catch {
-                        // eslint-disable-next-line @typescript-eslint/no-require-imports
-                        gwMod = require(targetGw);
-                    }
-                    const gwConfig = gwMod && gwMod.default && gwMod.default.default
-                        ? gwMod.default.default
-                        : gwMod && gwMod.default
-                            ? gwMod.default
-                            : gwMod;
-                    if (gwConfig) {
-                        const isExcluded = (reqPath, reqMethod) => {
-                            if (!gwConfig.exclude)
-                                return false;
-                            for (const rule of gwConfig.exclude) {
-                                if (typeof rule === 'string') {
-                                    if (rule.endsWith('/*')) {
-                                        if (reqPath.startsWith(rule.slice(0, -2)))
-                                            return true;
-                                    }
-                                    else if (reqPath === rule)
-                                        return true;
-                                }
-                                else {
-                                    const pathMatch = rule.path.endsWith('/*')
-                                        ? reqPath.startsWith(rule.path.slice(0, -2))
-                                        : reqPath === rule.path;
-                                    if (pathMatch) {
-                                        if (!rule.methods ||
-                                            rule.methods.includes(reqMethod))
-                                            return true;
-                                    }
-                                }
-                            }
-                            return false;
-                        };
-                        if (gwConfig.middleware) {
-                            const wrapped = gwConfig.middleware.map((m) => (req, res, next) => isExcluded(req.path, req.method) ? next() : m(req, res, next));
-                            allMiddlewares.push(...wrapped);
-                        }
-                        if (gwConfig.filters) {
-                            const wrapped = gwConfig.filters.map((f) => (err, req, res, next) => isExcluded(req.path, req.method)
-                                ? next(err)
-                                : f.prototype && f.prototype.catch
-                                    ? new f().catch(err, req, res, next)
-                                    : f(err, req, res, next));
-                            allFilters.push(...wrapped);
-                        }
-                        if (gwConfig.guards) {
-                            const wrapped = gwConfig.guards.map((g) => {
-                                return async (req) => {
-                                    if (isExcluded(req.path, req.method))
-                                        return true;
-                                    return typeof g === 'function'
-                                        ? g.prototype?.canActivate
-                                            ? new g().canActivate(req)
-                                            : g(req)
-                                        : g.canActivate(req);
-                                };
-                            });
-                            allGuards.push(...wrapped);
-                        }
-                        if (gwConfig.interceptors) {
-                            const wrapped = gwConfig.interceptors.map((i) => {
-                                return async (req, res) => {
-                                    if (isExcluded(req.path, req.method))
-                                        return;
-                                    return typeof i === 'function'
-                                        ? i.prototype?.intercept
-                                            ? new i().intercept(req, res)
-                                            : i(req, res)
-                                        : i.intercept(req, res);
-                                };
-                            });
-                            allInterceptors.push(...wrapped);
-                        }
-                        if (gwConfig.timeout !== undefined) {
-                            const baseTimeout = gwConfig.timeout;
-                            const timeoutMiddleware = (req, res, next) => {
-                                if (isExcluded(req.path, req.method))
-                                    return next();
-                                const ms = typeof baseTimeout === 'function'
-                                    ? baseTimeout(req)
-                                    : baseTimeout;
-                                if (ms) {
-                                    req.timeoutTimer = setTimeout(() => {
-                                        if (!res.headersSent) {
-                                            res.status(408).json({
-                                                success: false,
-                                                error: {
-                                                    code: 'REQUEST_TIMEOUT',
-                                                    message: 'Request Timeout',
-                                                },
-                                            });
-                                        }
-                                    }, ms);
-                                    res.raw.on('finish', () => clearTimeout(req.timeoutTimer));
-                                }
-                                next();
-                            };
-                            allMiddlewares.push(timeoutMiddleware);
-                        }
-                        if (gwConfig.metadata) {
-                            allMetadata = { ...allMetadata, ...gwConfig.metadata };
-                        }
-                        if (gwConfig.cors !== undefined)
-                            allCors = gwConfig.cors;
-                        if (gwConfig.headers)
-                            allHeaders = { ...allHeaders, ...gwConfig.headers };
-                        if (gwConfig.plugins) {
-                            for (const plugin of gwConfig.plugins) {
-                                await this.register(plugin);
-                            }
-                        }
-                        if (gwConfig.imports) {
-                            for (const mod of gwConfig.imports) {
-                                const name = 'plugin' in mod ? mod.plugin.name : mod.name;
-                                if (!this.hasPlugin(name)) {
-                                    await this.register(mod);
-                                }
-                            }
-                        }
-                        if (gwConfig.providers) {
-                            for (const [token, providerConfig] of gwConfig.providers) {
-                                this.provide(token, providerConfig);
-                            }
-                        }
-                    }
-                }
-            }
-            catch {
-                /* ignore */
-            }
-        }
-        const currentMod = mod && mod.default && mod.default.default
-            ? mod.default.default
-            : mod && mod.default
-                ? mod.default
-                : mod;
-        const isControllerObj = currentMod && currentMod.__isController === true;
-        const routeConfig = {
-            ...(isControllerObj ? currentMod : {}),
-            ...(mod.config || {}),
-        };
-        // Fallback to global app.options.cors if neither gateway nor route specify it
-        if (routeConfig.cors !== undefined)
-            allCors = routeConfig.cors;
-        else if (allCors === undefined && this.options.cors !== undefined)
-            allCors = this.options.cors;
-        if (routeConfig.middleware)
-            allMiddlewares.push(...(Array.isArray(routeConfig.middleware)
-                ? routeConfig.middleware
-                : [routeConfig.middleware]));
-        if (routeConfig.headers)
-            allHeaders = { ...allHeaders, ...routeConfig.headers };
-        if (routeConfig.plugins) {
-            for (const plugin of routeConfig.plugins) {
-                await this.register(plugin);
-            }
-        }
-        // Pass gateway features to controllers via metadata if necessary
-        const combinedFilters = [
-            ...allFilters,
-            ...(routeConfig.filters
-                ? Array.isArray(routeConfig.filters)
-                    ? routeConfig.filters
-                    : [routeConfig.filters]
-                : []),
-        ];
-        const combinedGuards = [
-            ...allGuards,
-            ...(routeConfig.guards
-                ? Array.isArray(routeConfig.guards)
-                    ? routeConfig.guards
-                    : [routeConfig.guards]
-                : []),
-        ];
-        const combinedInterceptors = [
-            ...allInterceptors,
-            ...(routeConfig.interceptors
-                ? Array.isArray(routeConfig.interceptors)
-                    ? routeConfig.interceptors
-                    : [routeConfig.interceptors]
-                : []),
-        ];
-        // Inject into the default export if it's a functional controller
-        if (mod.default && typeof mod.default === 'object') {
-            try {
-                if (!mod.default.filters)
-                    mod.default.filters = [];
-                mod.default.filters.push(...combinedFilters);
-                if (!mod.default.guards)
-                    mod.default.guards = [];
-                mod.default.guards.push(...combinedGuards);
-                if (!mod.default.interceptors)
-                    mod.default.interceptors = [];
-                mod.default.interceptors.push(...combinedInterceptors);
-                if (!mod.default.metadata)
-                    mod.default.metadata = {};
-                Object.assign(mod.default.metadata, {
-                    ...allMetadata,
-                    ...(routeConfig.metadata || {}),
-                });
-            }
-            catch {
-                // If mod.default is frozen, ignore
-            }
-        }
-        const prefixMiddlewares = [];
-        if (this.options.debugRouting) {
-            const pathLib = await Promise.resolve().then(() => __importStar(require('node:path')));
-            const relFile = pathLib
-                .relative(process.cwd(), filePath)
-                .replace(/\\/g, '/');
-            const gwStr = activeGateways.length > 0
-                ? activeGateways
-                    .map((g) => pathLib.relative(process.cwd(), g).replace(/\\/g, '/'))
-                    .join(' -> ') + ' -> '
-                : '';
-            prefixMiddlewares.push((req, res, next) => {
-                this.log.debug(`[Request] ${req.method} ${req.path} -> ${gwStr}${relFile}`);
-                next();
-            });
-        }
-        if (allCors !== undefined) {
-            if (allCors === true)
-                prefixMiddlewares.push((0, middleware_1.cors)({}));
-            else if (allCors !== false)
-                prefixMiddlewares.push((0, middleware_1.cors)(allCors));
-        }
-        if (Object.keys(allHeaders).length > 0) {
-            prefixMiddlewares.push((req, res, next) => {
-                for (const [k, v] of Object.entries(allHeaders))
-                    res.setHeader(k, v);
-                next();
-            });
-        }
-        prefixMiddlewares.push(...allMiddlewares);
-        const isRouter = (obj) => obj && 'handle' in obj && 'get' in obj;
-        const CONTROLLER_PREFIX = Symbol.for('exisjs:controller_prefix');
-        const isController = (obj) => obj && obj.prototype && obj.prototype[CONTROLLER_PREFIX] !== undefined;
-        const unwrappedMod = mod && mod.default && mod.default.default
-            ? mod.default.default
-            : mod && mod.default
-                ? mod.default
-                : mod;
-        const functionalControllerObj = unwrappedMod && unwrappedMod.__isController ? unwrappedMod : null;
-        if (functionalControllerObj) {
-            // ─── THE NEW PERFECT FUNCTIONAL CONTROLLER ───
-            const compiledRouter = this.compileFunctionalController(functionalControllerObj);
-            this.mountRouteWithSource(routePath, compiledRouter, filePath, prefixMiddlewares);
-        }
-        else if (mod.router && isRouter(mod.router)) {
-            this.mountRouteWithSource(routePath, mod.router, filePath, prefixMiddlewares);
-        }
-        else if (unwrappedMod && isController(unwrappedMod)) {
-            this.registerControllers([unwrappedMod], routePath, prefixMiddlewares);
-        }
-        else if (unwrappedMod && isRouter(unwrappedMod)) {
-            this.mountRouteWithSource(routePath, unwrappedMod, filePath, prefixMiddlewares);
-        }
-        else if (isRouter(mod)) {
-            this.mountRouteWithSource(routePath, mod, filePath, prefixMiddlewares);
-        }
-        else {
-            this.log.warn(`\n[WARN] Route file \x1b[36m${filePath}\x1b[0m does not export a recognized router or controller.\n`);
-        }
+    // ─── Listen ───────────────────────────────────────────────────────────────────
+    listen(portOrOptions, callback) {
+        return this.bootstrapper.listen(portOrOptions, callback);
     }
-    compileFunctionalController(config) {
-        const router = new router_1.Router();
-        const fileMiddleware = [];
-        if (config.cors) {
-            fileMiddleware.push(config.cors === true ? (0, middleware_1.cors)({}) : (0, middleware_1.cors)(config.cors));
-        }
-        if (config.middleware) {
-            fileMiddleware.push(...(Array.isArray(config.middleware)
-                ? config.middleware
-                : [config.middleware]));
-        }
-        const { onError, onResponse } = config;
-        for (const [key, routeConfig] of Object.entries(config)) {
-            if ([
-                'cors',
-                'middleware',
-                'onError',
-                'onResponse',
-                '__isController',
-            ].includes(key))
-                continue;
-            const rc = routeConfig;
-            if (!rc || !rc.method || !rc.path || !rc.handle)
-                continue;
-            const routeMiddlewares = [...fileMiddleware];
-            if (rc.cors) {
-                routeMiddlewares.push(rc.cors === true ? (0, middleware_1.cors)({}) : (0, middleware_1.cors)(rc.cors));
-            }
-            if (rc.middleware) {
-                routeMiddlewares.push(...(Array.isArray(rc.middleware) ? rc.middleware : [rc.middleware]));
-            }
-            // ─── SUPER HANDLER WRAPPER ───
-            const superHandler = async (req, res, next) => {
-                if (onResponse) {
-                    res.raw.on('finish', () => onResponse(req, res));
-                }
-                try {
-                    // 0. Enforce Route Permissions (Role Authorization)
-                    if (rc.permissions && rc.permissions.length > 0) {
-                        if (!req.user) {
-                            res.status(401).json({
-                                success: false,
-                                error: {
-                                    code: 'UNAUTHORIZED',
-                                    message: 'Unauthorized: User not found on request',
-                                },
-                            });
-                            return;
-                        }
-                        const userPerms = req.user.permissions || req.user.roles || req.user.role || [];
-                        const permsArray = Array.isArray(userPerms)
-                            ? userPerms
-                            : [userPerms];
-                        const hasPerm = rc.permissions.every((p) => permsArray.includes(p));
-                        if (!hasPerm) {
-                            res.status(403).json({
-                                success: false,
-                                error: {
-                                    code: 'FORBIDDEN',
-                                    message: 'Forbidden: Insufficient permissions',
-                                },
-                            });
-                            return;
-                        }
-                    }
-                    // 1. Run Guards
-                    const routeGuards = [...(config.guards || []), ...(rc.guards || [])];
-                    for (const guard of routeGuards) {
-                        const allowed = await (typeof guard === 'function'
-                            ? guard.prototype?.canActivate
-                                ? new guard().canActivate(req)
-                                : guard(req)
-                            : guard.canActivate(req));
-                        if (!allowed) {
-                            if (res && !res.headersSent) {
-                                res.status(403).json({
-                                    success: false,
-                                    error: { code: 'FORBIDDEN', message: 'Forbidden by Guard' },
-                                });
-                            }
-                            return;
-                        }
-                    }
-                    // Build Context
-                    const ctx = {
-                        body: req.body,
-                        query: req.query,
-                        params: req.params,
-                        headers: req.headers,
-                        req,
-                        res,
-                        app: this,
-                        socket: req.ws,
-                        state: context_1.executionContext.getStore()?.state || {},
-                        ...req, // Spread req to allow access to user, session, etc.
-                    };
-                    const result = await rc.handle(ctx);
-                    // 2. Run Interceptors
-                    const routeInterceptors = [
-                        ...(config.interceptors || []),
-                        ...(rc.interceptors || []),
-                    ];
-                    for (const interceptor of routeInterceptors) {
-                        await (typeof interceptor === 'function'
-                            ? interceptor.prototype?.intercept
-                                ? new interceptor().intercept(req, res)
-                                : interceptor(req, res)
-                            : interceptor.intercept(req, res));
-                    }
-                    if (result !== undefined && !res.headersSent) {
-                        if (typeof result === 'object' && result !== null) {
-                            res.json(result);
-                        }
-                        else {
-                            res.send(String(result));
-                        }
-                    }
-                }
-                catch (err) {
-                    if (onError) {
-                        try {
-                            await onError(err, req, res);
-                        }
-                        catch (hookErr) {
-                            next(hookErr);
-                        }
-                    }
-                    else {
-                        next(err); // Hands off to ExisJS global error handler (which handles HttpErrors automatically!)
-                    }
-                }
-            };
-            // Mount to router
-            const method = rc.method.toLowerCase();
-            const schema = {};
-            const isValidatorOrPipe = (v) => v.parse ||
-                v.transform ||
-                (typeof v === 'function' && v.prototype?.transform);
-            if (rc.body) {
-                schema.body = isValidatorOrPipe(rc.body) ? rc.body : validator_1.v.object(rc.body);
-            }
-            if (rc.query) {
-                schema.query = isValidatorOrPipe(rc.query)
-                    ? rc.query
-                    : validator_1.v.object(rc.query);
-            }
-            if (rc.params) {
-                schema.params = isValidatorOrPipe(rc.params)
-                    ? rc.params
-                    : validator_1.v.object(rc.params);
-            }
-            if (rc.host) {
-                schema.host = rc.host;
-            }
-            const combinedFilters = [
-                ...(config.filters
-                    ? Array.isArray(config.filters)
-                        ? config.filters
-                        : [config.filters]
-                    : []),
-                ...(rc.filters
-                    ? Array.isArray(rc.filters)
-                        ? rc.filters
-                        : [rc.filters]
-                    : []),
-            ];
-            if (combinedFilters.length > 0) {
-                schema.filters = combinedFilters;
-            }
-            const combinedMetadata = {
-                ...(config.metadata || {}),
-                ...(rc.metadata || {}),
-            };
-            if (Object.keys(combinedMetadata).length > 0) {
-                schema.metadata = combinedMetadata;
-            }
-            if (method === 'sse') {
-                const sseHandler = async (stream, rawReq) => {
-                    try {
-                        const ctx = {
-                            body: rawReq.body,
-                            query: rawReq.query,
-                            params: rawReq.params,
-                            headers: rawReq.headers,
-                            req: rawReq,
-                            res: undefined, // Res is not available in standard SSE after handshake
-                            app: this,
-                            stream,
-                            ...rawReq,
-                        };
-                        await rc.handle(ctx);
-                    }
-                    catch (err) {
-                        if (onError) {
-                            await onError(err, rawReq, {});
-                        }
-                        else {
-                            console.error('[Exis SSE Error]', err);
-                        }
-                    }
-                };
-                router.sse(rc.path, ...routeMiddlewares, sseHandler);
-            }
-            else {
-                if (Object.keys(schema).length > 0) {
-                    ;
-                    router[method](rc.path, ...routeMiddlewares, schema, superHandler);
-                }
-                else {
-                    ;
-                    router[method](rc.path, ...routeMiddlewares, superHandler);
-                }
-            }
-        }
-        return router;
+    // ─── Banner ───────────────────────────────────────────────────────────────────
+    async _printStartupBanner() {
+        return this.bootstrapper.printStartupBanner();
     }
-    mountRouteWithSource(prefix, subRouter, sourceFile, prefixMiddlewares = []) {
-        for (const route of subRouter.getRoutes()) {
-            const fullPath = (prefix + route.path).replace(/\/+/g, '/');
-            const r = { ...route, path: fullPath, sourceFile };
-            if (prefixMiddlewares.length > 0) {
-                r.handlers = [...prefixMiddlewares, ...r.handlers];
-            }
-            this.router.addRawRoute(r);
-            if (this.hooks.route.length > 0) {
-                // eslint-disable-next-line @typescript-eslint/prefer-for-of
-                for (let i = 0; i < this.hooks.route.length; i++) {
-                    this.hooks.route[i]({ method: route.method, path: fullPath });
-                }
-            }
-        }
+    // ─── Graceful Shutdown ────────────────────────────────────────────────────────
+    onShutdown(hook) {
+        this.bootstrapper.onShutdown(hook);
         return this;
     }
-    async scanDirectory(dir, baseRoute = '/') {
-        const fs = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
-        const path = await Promise.resolve().then(() => __importStar(require('node:path')));
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        const results = [];
-        for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                let segment = entry.name;
-                if (segment.startsWith('(') && segment.endsWith(')')) {
-                    const subResults = await this.scanDirectory(fullPath, baseRoute);
-                    results.push(...subResults);
-                    continue;
-                }
-                if (segment.startsWith('[...') && segment.endsWith(']')) {
-                    segment = '*' + segment.slice(4, -1);
-                }
-                else {
-                    segment = segment.replace(/\[(.*?)\]/g, ':$1');
-                }
-                const nextBase = baseRoute === '/' ? `/${segment}` : `${baseRoute}/${segment}`;
-                const subResults = await this.scanDirectory(fullPath, nextBase);
-                results.push(...subResults);
-            }
-            else {
-                results.push({ filePath: fullPath, routePath: baseRoute });
-            }
-        }
-        return results;
+    close(timeout = 5000) {
+        return this.bootstrapper.close(timeout);
+    }
+    // ─── Expose internals ─────────────────────────────────────────────────────────
+    getRouter() {
+        return this.router;
     }
     // ─── Queues ─────────────────────────────────────────────────────────────────
-    /**
-     * Registers a background job worker handler.
-     */
     queue(name, handler, options) {
-        if (!this._queueWorker) {
-            if (this.options.queue?.enableWorkers === false) {
-                // workers disabled explicitly, gracefully skip registering
-                return;
-            }
-            // Worker not initialized yet (e.g. config loading is pending), buffer the job
-            this._pendingQueueJobs.push({
-                name,
-                handler: handler,
-                ...options,
-            });
-            return;
-        }
-        this._queueWorker.registerJob({
-            name,
-            handler: handler,
-            ...options,
-        });
+        return this.queueManager.queue(name, handler, options);
     }
-    /**
-     * Enqueues a payload for background processing.
-     */
     async enqueue(name, payload, opts) {
-        if (!this._queueClient) {
-            throw new Error(`Queue is not initialized. Please configure ExisConfig.queue first.`);
-        }
-        return this._queueClient.enqueue(name, payload, opts);
-    }
-    _initQueue(qConfig) {
-        if (!this._queueClient) {
-            this._queueClient = new client_1.ExisQueue(qConfig);
-        }
-        const enableWorkers = qConfig.enableWorkers ?? true;
-        if (enableWorkers && !this._queueWorker) {
-            this._queueWorker = new worker_1.ExisWorker(qConfig, this.log, this._queueClient.getDriver());
-            this._queueWorker.start();
-            const redisClient = this._queueWorker.redis || null;
-            this._cronScheduler = new scheduler_1.CronScheduler(this._queueWorker, redisClient, this.log);
-            this._cronScheduler.start();
-        }
+        return this.queueManager.enqueue(name, payload, opts);
     }
 }
 exports.App = App;