webspresso 0.0.97 → 0.0.98

package/src/server.js

@@ -6,6 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const zlib = require('zlib');
 const { AsyncLocalStorage } = require('async_hooks');
 const express = require('express');
 const helmet = require('helmet');
@@ -17,6 +18,9 @@ const { mountClientRuntime } = require('./client-runtime/mount');
 const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages, detectLocale, loadI18n, createTranslator } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
+const { createDevReloadHub } = require('./dev-reload');
+const { createDevBundler } = require('./bundle');
+const { registerClearHook } = require('./njk-frontmatter');
 const { createPluginManager } = require('./plugin-manager');
 const { createServiceRegistry } = require('./services');
 const { scanRoutes } = require('./discovery/scan-routes');
@@ -25,6 +29,12 @@ const { mountDiscoveredRoutes } = require('./routing/mount-discovered-routes');
 const { discoverModuleDetails } = require('./modules/module-discovery');
 const { ShutdownManager, NodeHttpAdapter } = require('../core/shutdown');
 const { createCompressionMiddleware } = require('../core/compression');
+const {
+  createDevProfilerMiddleware,
+  attachProfilerToKnex,
+  formatDevBanner,
+  printDevBanner,
+} = require('./dev');
 const {
   WebspressoError,
   HttpError,
@@ -40,6 +50,35 @@ const {
 // Async storage for tracking template render call stacks (circular extends guard)
 const renderStackStorage = new AsyncLocalStorage();
 
+/**
+ * Fast hardware-accelerated Weak ETag generator using native zlib.crc32
+ * Up to 13x faster than Express default SHA-1, zero external dependencies.
+ * Compliant with RFC 7232 Section 2.3 (Weak Entity Tag).
+ * Format: W/"<len-hex>-<crc32-hex>"
+ *
+ * @param {Buffer|string} body - Response body
+ * @param {string} [encoding] - String encoding if body is string
+ * @returns {string} RFC 7232 formatted Weak ETag
+ */
+function fastETag(body, encoding) {
+  if (!body || body.length === 0) {
+    return 'W/"0-0"';
+  }
+  const buf = Buffer.isBuffer(body) ? body : Buffer.from(body, encoding || 'utf8');
+  if (buf.length === 0) {
+    return 'W/"0-0"';
+  }
+  if (typeof zlib.crc32 === 'function') {
+    return `W/"${buf.length.toString(16)}-${zlib.crc32(buf).toString(16)}"`;
+  }
+  // Graceful fallback for environments without zlib.crc32
+  let h1 = 0x811c9dc5;
+  for (let i = 0; i < buf.length; i++) {
+    h1 = Math.imul(h1 ^ buf[i], 0x01000193);
+  }
+  return `W/"${buf.length.toString(16)}-${(h1 >>> 0).toString(16)}"`;
+}
+
 /**
  * Configure Nunjucks environment with circular extends guard and loader protection
  * @param {string|string[]} templateDirs - Template directory paths
@@ -52,14 +91,21 @@ function configureSafeNunjucks(templateDirs, options = {}) {
   const origRender = env.render.bind(env);
   const origRenderString = env.renderString.bind(env);
 
+  // Production template cache to bypass loader traversal when caching is active
+  const productionTemplateCache = (!options.noCache) ? new Map() : null;
+  if (productionTemplateCache) {
+    registerClearHook(() => productionTemplateCache.clear());
+  }
+
   function wrapTemplateRoot(tmpl, name) {
     if (!tmpl || tmpl._safeWrapped) return;
     tmpl._safeWrapped = true;
     const origRoot = tmpl.rootRenderFunc;
     if (typeof origRoot !== 'function') return;
 
+    const normalizedName = String(name || tmpl.path || 'anonymous');
+
     tmpl.rootRenderFunc = function(e, context, frame, runtime, renderCb) {
-      const normalizedName = String(name || tmpl.path || 'anonymous');
       const store = renderStackStorage.getStore();
       if (store) {
         store.stack.push(normalizedName);
@@ -69,8 +115,12 @@ function configureSafeNunjucks(templateDirs, options = {}) {
         if (!finished) {
           finished = true;
           if (store) {
-            const idx = store.stack.lastIndexOf(normalizedName);
-            if (idx !== -1) store.stack.splice(idx, 1);
+            if (store.stack[store.stack.length - 1] === normalizedName) {
+              store.stack.pop();
+            } else {
+              const idx = store.stack.lastIndexOf(normalizedName);
+              if (idx !== -1) store.stack.splice(idx, 1);
+            }
           }
         }
         renderCb(err, out);
@@ -79,8 +129,12 @@ function configureSafeNunjucks(templateDirs, options = {}) {
         return origRoot.call(this, e, context, frame, runtime, done);
       } catch (ex) {
         if (store) {
-          const idx = store.stack.lastIndexOf(normalizedName);
-          if (idx !== -1) store.stack.splice(idx, 1);
+          if (store.stack[store.stack.length - 1] === normalizedName) {
+            store.stack.pop();
+          } else {
+            const idx = store.stack.lastIndexOf(normalizedName);
+            if (idx !== -1) store.stack.splice(idx, 1);
+          }
         }
         throw ex;
       }
@@ -108,17 +162,28 @@ function configureSafeNunjucks(templateDirs, options = {}) {
       }
     }
 
+    if (!cb && !parentName && productionTemplateCache && typeof name === 'string') {
+      const cached = productionTemplateCache.get(name);
+      if (cached) return cached;
+    }
+
     const wrappedCb = typeof cb === 'function' ? function(err, tmpl) {
-      if (tmpl) {
+      if (tmpl && !tmpl._safeWrapped) {
         wrapTemplateRoot(tmpl, name);
       }
+      if (productionTemplateCache && tmpl && !err && typeof name === 'string' && !parentName) {
+        productionTemplateCache.set(name, tmpl);
+      }
       cb(err, tmpl);
     } : undefined;
 
     const res = origGetTemplate(name, eagerCompile, parentName, ignoreMissing, wrappedCb);
-    if (res) {
+    if (res && !res._safeWrapped) {
       wrapTemplateRoot(res, name);
     }
+    if (productionTemplateCache && res && typeof name === 'string' && !parentName) {
+      productionTemplateCache.set(name, res);
+    }
     return res;
   };
 
@@ -407,7 +472,13 @@ function createApp(options = {}) {
     timeout: timeoutConfig = '30s',
     auth: authManager = null,
     setupRoutes,
+    dev: devOpts = {},
   } = options;
+
+  // Auto-instrument Knex queries for dev profiler
+  if (options.db && options.db.knex) {
+    attachProfilerToKnex(options.db.knex);
+  }
   
   if (!initialPagesDir && !options.pages && !options.api && !options.modules && !options.routes && !options.rootDir) {
     throw new Error('pagesDir is required');
@@ -433,8 +504,11 @@ function createApp(options = {}) {
   const pluginManager = createPluginManager();
   
   // Configure asset manager
+  const projectBase = publicDir ? path.dirname(path.resolve(publicDir)) : process.cwd();
   configureAssets({
     publicDir: publicDir || 'public',
+    srcDir: options.srcDir || path.join(projectBase, 'src'),
+    pagesDir: pagesDir || 'pages',
     ...assetsConfig
   });
   
@@ -495,16 +569,33 @@ function createApp(options = {}) {
   const app = express();
   app.serviceRegistry = serviceRegistry;
 
-  // Correlation Request ID middleware
+  // Unified Request Context & Lifecycle Initializer middleware
+  const { renderStream } = require('../core/ssr/stream');
   app.use((req, res, next) => {
+    // 1. Request draining check during graceful shutdown
+    if (shutdownManager.isShuttingDown) {
+      res.set('Connection', 'close');
+      if (!res.headersSent) {
+        if (preferJsonErrorResponse(req)) {
+          return res.status(503).json({ error: 'Service Unavailable', message: 'Server is shutting down', status: 503 });
+        }
+        return res.status(503).send('Server is shutting down');
+      }
+      res.on('finish', () => {
+        try {
+          if (req.socket && !req.socket.destroyed) {
+            req.socket.end();
+          }
+        } catch (e) {}
+      });
+    }
+
+    // 2. Correlation Request ID
     const reqId = (req.headers && req.headers['x-request-id']) ? req.headers['x-request-id'] : crypto.randomUUID();
     req.id = reqId;
     res.setHeader('X-Request-Id', reqId);
-    next();
-  });
 
-  // Request context & services caller middleware
-  app.use((req, res, next) => {
+    // 3. Request DB, Services, and Context
     if (options.db) {
       req.db = options.db;
     }
@@ -518,29 +609,40 @@ function createApp(options = {}) {
     };
     req.service = (name, input, opts) =>
       serviceRegistry.call(name, input, req.context, opts);
-    next();
-  });
 
-  // SSR Streaming Response Helper
-  const { renderStream } = require('../core/ssr/stream');
-  app.use((req, res, next) => {
+    // 4. SSR Streaming Response Helper
     res.renderStream = (templatePath, context = {}, renderOptions = {}) => {
       return renderStream(res, templatePath, context, {
         env: nunjucksEnv,
         ...renderOptions,
       });
     };
+
     next();
   });
 
   // Async handler wrapper helper for automatic promise rejection handling
   function wrapAsync(fn) {
     if (typeof fn !== 'function') return fn;
+    if (fn._isWrappedAsync) return fn;
+    let wrapped;
     if (fn.length === 4) {
-      return function(err, req, res, next) {
+      wrapped = function(err, req, res, next) {
         try {
           const ret = fn.call(this, err, req, res, next);
-          if (ret && typeof ret.catch === 'function') {
+          if (ret && ret.then) {
+            ret.catch(next);
+          }
+          return ret;
+        } catch (syncErr) {
+          return next(syncErr);
+        }
+      };
+    } else {
+      wrapped = function(req, res, next) {
+        try {
+          const ret = fn.call(this, req, res, next);
+          if (ret && ret.then) {
             ret.catch(next);
           }
           return ret;
@@ -549,51 +651,243 @@ function createApp(options = {}) {
         }
       };
     }
-    return function(req, res, next) {
+    wrapped._isWrappedAsync = true;
+    return wrapped;
+  }
+
+  function dispatchFastPath(handlers, req, res, next) {
+    let idx = 0;
+    function runNext(err) {
+      if (err) return next(err);
+      if (idx >= handlers.length) return next();
+      const fn = handlers[idx++];
       try {
-        const ret = fn.call(this, req, res, next);
-        if (ret && typeof ret.catch === 'function') {
-          ret.catch(next);
+        const ret = fn(req, res, runNext);
+        if (ret && typeof ret.then === 'function') {
+          ret.catch(runNext);
         }
-        return ret;
-      } catch (syncErr) {
-        return next(syncErr);
+      } catch (e) {
+        runNext(e);
       }
+    }
+    runNext();
+  }
+
+  const fastPathStaticByMethod = {
+    GET: new Map(),
+    POST: new Map(),
+    PUT: new Map(),
+    DELETE: new Map(),
+    PATCH: new Map(),
+    HEAD: new Map(),
+    OPTIONS: new Map(),
+  };
+  const fastPathStaticMap = new Map();
+  app.fastPathStaticMap = fastPathStaticMap;
+  app.fastPathStaticByMethod = fastPathStaticByMethod;
+
+  // Dynamic route registration list and LRU lookup cache
+  const dynamicRouteList = [];
+  const dynamicRouteMap = new Map();
+  const dynamicRouteLookupCache = new Map();
+  const prefixMiddlewares = [];
+  const MAX_DYNAMIC_CACHE_SIZE = 2000;
+  const NOT_FOUND_SENTINEL = Symbol('NOT_FOUND');
+
+  app.dynamicRouteList = dynamicRouteList;
+  app.dynamicRouteLookupCache = dynamicRouteLookupCache;
+
+  function getDynamicCache(key) {
+    const val = dynamicRouteLookupCache.get(key);
+    if (!val) return undefined;
+    dynamicRouteLookupCache.delete(key);
+    dynamicRouteLookupCache.set(key, val);
+    return val;
+  }
+
+  function setDynamicCache(key, val) {
+    if (dynamicRouteLookupCache.size >= MAX_DYNAMIC_CACHE_SIZE) {
+      const oldestKey = dynamicRouteLookupCache.keys().next().value;
+      dynamicRouteLookupCache.delete(oldestKey);
+    }
+    dynamicRouteLookupCache.set(key, val);
+  }
+
+  function extractRouteParams(paramNames, match) {
+    const params = {};
+    for (let i = 0; i < paramNames.length; i++) {
+      const val = match[i + 1];
+      if (val !== undefined) {
+        try {
+          params[paramNames[i]] = decodeURIComponent(val);
+        } catch (_) {
+          params[paramNames[i]] = val;
+        }
+      }
+    }
+    return params;
+  }
+
+  function compileRoutePattern(pattern) {
+    if (typeof pattern !== 'string') return null;
+    if (pattern === '*' || pattern === '/*' || pattern === '') return null;
+    if (pattern.includes('(') || pattern.includes(')')) return null;
+
+    const paramNames = [];
+    const parts = pattern.split('/');
+    let regexStr = '^';
+    let hasWildcard = false;
+
+    for (let i = 1; i < parts.length; i++) {
+      const part = parts[i];
+      if (!part) continue;
+      regexStr += '\\/';
+      if (part.startsWith(':')) {
+        const isOptional = part.endsWith('?');
+        const name = isOptional ? part.slice(1, -1) : part.slice(1);
+        paramNames.push(name);
+        regexStr += isOptional ? '([^/]+)?' : '([^/]+)';
+      } else if (part.startsWith('*')) {
+        const name = part.slice(1) || '0';
+        paramNames.push(name);
+        regexStr += '(.*)';
+        hasWildcard = true;
+      } else {
+        regexStr += part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      }
+    }
+
+    if (regexStr === '^') {
+      regexStr = '^\\/?$';
+    } else {
+      regexStr += '\\/?$';
+    }
+
+    return {
+      pattern,
+      regex: new RegExp(regexStr),
+      paramNames,
+      hasWildcard,
     };
   }
 
-  // Wrap routing methods on app to catch uncaught async errors
+  // Wrap routing methods on app to catch uncaught async errors and register fast-path static and dynamic routes
   const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'all'];
   for (const method of HTTP_METHODS) {
     const origMethod = app[method];
     if (typeof origMethod === 'function') {
       app[method] = function(path, ...handlers) {
+        if (handlers.length === 0) {
+          return origMethod.call(this, path);
+        }
         const wrappedHandlers = handlers.flat().map((h) => wrapAsync(h));
+
+        const normPath = (typeof path === 'string' && path.length > 1 && path.endsWith('/'))
+          ? path.slice(0, -1)
+          : path;
+
+        // Fast-path static registration for literal string paths without dynamic parameters or regex
+        if (
+          typeof normPath === 'string' &&
+          normPath.length > 0 &&
+          !normPath.includes(':') &&
+          !normPath.includes('*') &&
+          !normPath.includes('(') &&
+          !normPath.includes(')') &&
+          !normPath.includes('?')
+        ) {
+          const uMethod = method.toUpperCase();
+          const routeInfo = { path: normPath, methods: { [method.toLowerCase()]: true } };
+          const registerStatic = (m) => {
+            const key = `${m} ${normPath}`;
+            let methodMap = fastPathStaticByMethod[m];
+            if (!methodMap) {
+              methodMap = new Map();
+              fastPathStaticByMethod[m] = methodMap;
+            }
+            const existing = methodMap.get(normPath);
+            if (existing) {
+              existing.handlers.push(...wrappedHandlers);
+            } else {
+              const entry = {
+                path: normPath,
+                handlers: [...wrappedHandlers],
+                routeInfo,
+              };
+              methodMap.set(normPath, entry);
+              fastPathStaticMap.set(key, entry);
+            }
+          };
+
+          if (uMethod === 'ALL') {
+            for (const m of ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']) {
+              registerStatic(m);
+            }
+          } else {
+            registerStatic(uMethod);
+          }
+          dynamicRouteLookupCache.clear();
+        } else if (
+          typeof path === 'string' &&
+          path.length > 0 &&
+          (path.includes(':') || path.includes('*')) &&
+          path !== '*' &&
+          path !== '/*' &&
+          !path.includes('(') &&
+          !path.includes(')')
+        ) {
+          const compiled = compileRoutePattern(path);
+          if (compiled) {
+            const uMethod = method.toUpperCase();
+            const routeInfo = { path, methods: { [method.toLowerCase()]: true } };
+            const registerDynamic = (m) => {
+              const key = `${m} ${path}`;
+              const existing = dynamicRouteMap.get(key);
+              if (existing) {
+                existing.handlers.push(...wrappedHandlers);
+              } else {
+                const entry = {
+                  method: m,
+                  path,
+                  compiled,
+                  handlers: [...wrappedHandlers],
+                  routeInfo,
+                };
+                dynamicRouteMap.set(key, entry);
+                dynamicRouteList.push(entry);
+              }
+            };
+
+            if (uMethod === 'ALL') {
+              for (const m of ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']) {
+                registerDynamic(m);
+              }
+            } else {
+              registerDynamic(uMethod);
+            }
+            dynamicRouteLookupCache.clear();
+          }
+        }
+
         return origMethod.call(this, path, ...wrappedHandlers);
       };
     }
   }
 
-  // Request draining check during graceful shutdown (zero overhead during normal operation)
-  app.use((req, res, next) => {
-    if (shutdownManager.isShuttingDown) {
-      res.set('Connection', 'close');
-      if (!res.headersSent) {
-        if (preferJsonErrorResponse(req)) {
-          return res.status(503).json({ error: 'Service Unavailable', message: 'Server is shutting down', status: 503 });
-        }
-        return res.status(503).send('Server is shutting down');
-      }
-      res.on('finish', () => {
-        try {
-          if (req.socket && !req.socket.destroyed) {
-            req.socket.end();
-          }
-        } catch (e) {}
+  // Wrap app.use to track path-prefixed middlewares for fast-path dispatcher execution
+  const origAppUse = app.use.bind(app);
+  app.use = function(pathOrHandler, ...handlers) {
+    if (typeof pathOrHandler === 'string' && handlers.length > 0) {
+      const normPrefix = (pathOrHandler.length > 1 && pathOrHandler.endsWith('/'))
+        ? pathOrHandler.slice(0, -1)
+        : pathOrHandler;
+      prefixMiddlewares.push({
+        prefix: normPrefix,
+        handlers: handlers.flat().map((h) => wrapAsync(h)),
       });
     }
-    next();
-  });
+    return origAppUse(pathOrHandler, ...handlers);
+  };
   
   // Security headers with Helmet
   if (helmetConfig !== false) {
@@ -638,7 +932,63 @@ function createApp(options = {}) {
       }
     }
     
-    app.use(helmet(finalConfig));
+    const helmetMw = helmet(finalConfig);
+
+    // Check if configuration uses purely static directives (no per-request dynamic functions)
+    let isDynamicCsp = false;
+    if (finalConfig.contentSecurityPolicy && finalConfig.contentSecurityPolicy.directives) {
+      for (const val of Object.values(finalConfig.contentSecurityPolicy.directives)) {
+        if (typeof val === 'function') {
+          isDynamicCsp = true;
+          break;
+        }
+        if (Array.isArray(val) && val.some((item) => typeof item === 'function')) {
+          isDynamicCsp = true;
+          break;
+        }
+      }
+    }
+
+    if (!isDynamicCsp) {
+      const staticHeaders = {};
+      let removePoweredBy = false;
+      const dummyRes = {
+        setHeader(name, value) {
+          staticHeaders[name] = value;
+        },
+        removeHeader(name) {
+          if (name && name.toLowerCase() === 'x-powered-by') {
+            removePoweredBy = true;
+          }
+        },
+      };
+
+      try {
+        helmetMw({ headers: {} }, dummyRes, () => {});
+      } catch (_) {
+        // Fallback to standard helmet middleware if mock invocation fails
+      }
+
+      const headerEntries = Object.entries(staticHeaders);
+      if (headerEntries.length > 0) {
+        if (removePoweredBy) {
+          app.disable('x-powered-by');
+        }
+        app.use((req, res, next) => {
+          for (let i = 0; i < headerEntries.length; i++) {
+            res.setHeader(headerEntries[i][0], headerEntries[i][1]);
+          }
+          if (removePoweredBy) {
+            res.removeHeader('X-Powered-By');
+          }
+          next();
+        });
+      } else {
+        app.use(helmetMw);
+      }
+    } else {
+      app.use(helmetMw);
+    }
   }
 
   // HTTP Response Compression
@@ -668,23 +1018,34 @@ function createApp(options = {}) {
   // Ensure extended query parser for nested filter/sort query parameters (?filter[field]=val)
   app.set('query parser', 'extended');
   
+  // Fast hardware-accelerated Weak ETag (CRC32 + Hex length) as default
+  // Configurable via options.etag or options.server.etag
+  const etagSetting = options.etag !== undefined
+    ? options.etag
+    : (options.server?.etag !== undefined ? options.server.etag : 'fast');
+
+  if (etagSetting === false || etagSetting === null) {
+    app.set('etag', false);
+  } else if (etagSetting === 'fast' || etagSetting === true) {
+    app.set('etag', fastETag);
+  } else {
+    app.set('etag', etagSetting);
+  }
+  
   // JSON body parser for API routes
   app.use(express.json());
   app.use(express.urlencoded({ extended: true }));
   
   // Ensure default empty object for body on mutating requests if not populated
+  // and halt processing if request has timed out (after body parsers)
   app.use((req, res, next) => {
+    if (timeoutConfig !== false && req.timedout) return;
     if (req.body === undefined && (req.method === 'POST' || req.method === 'PUT' || req.method === 'PATCH')) {
       req.body = {};
     }
     next();
   });
   
-  // Halt processing if request has timed out (after body parsers)
-  if (timeoutConfig !== false) {
-    app.use(haltOnTimedout);
-  }
-  
   // Authentication middleware (if auth manager provided)
   let authMiddleware = null;
   if (authManager) {
@@ -713,18 +1074,70 @@ function createApp(options = {}) {
 
   mountClientRuntime(app, clientRuntime);
 
+  // Development Hot / Live Reload Hub (SSE & CSS hot swap & Template Live Reload)
+  const devReloadOption = options.devReload;
+  const isDevReloadExplicit = devReloadOption === true || (typeof devReloadOption === 'object' && devReloadOption.enabled === true);
+  const isDevReloadDisabled = devReloadOption === false || (typeof devReloadOption === 'object' && devReloadOption.enabled === false);
+  const devReloadEnabled = isDevReloadExplicit || (!isDevReloadDisabled && isDev && !isTest);
+
+  const devReloadHub = createDevReloadHub({
+    app,
+    publicDir,
+    pagesDir,
+    viewsDir,
+    options: typeof devReloadOption === 'object' ? devReloadOption : {},
+    enabled: devReloadEnabled,
+    logger: logging ? console : null,
+  });
+
+  if (devReloadHub) {
+    app.devReloadHub = devReloadHub;
+    app.broadcastDevReload = (type, payload) => devReloadHub.broadcast(type, payload);
+    if (shutdownManager) {
+      shutdownManager.registerDisposer('devReload', () => devReloadHub.close());
+    }
+  }
+
+  // Client-side JS incremental bundler (esbuild context() API)
+  const bundleOption = options.bundle;
+  const isBundleExplicit = bundleOption === true || (typeof bundleOption === 'object' && bundleOption.enabled !== false);
+  const isBundleDisabled = bundleOption === false;
+
+  if (isBundleExplicit && !isBundleDisabled) {
+    const bundlerOpts = typeof bundleOption === 'object' ? { ...bundleOption } : {};
+    if (!bundlerOpts.cwd) bundlerOpts.cwd = rootDir;
+    const devBundler = createDevBundler(bundlerOpts, devReloadHub);
+    app.devBundler = devBundler;
+
+    if (devBundler.isAvailable() && bundlerOpts.watch !== false && isDev && !isTest) {
+      devBundler.startWatch().catch((err) => {
+        if (logging) console.error('[Webspresso Bundler] Watch error:', err.message);
+      });
+    }
+
+    if (shutdownManager) {
+      shutdownManager.registerDisposer('devBundler', () => devBundler.dispose());
+    }
+  }
+
   // Configure Nunjucks with viewsDir priority and circular extension guard
   const templateDirs = [viewsDir, pagesDir].filter(Boolean);
   if (templateDirs.length === 0) {
     templateDirs.push(path.join(rootDir, 'pages'));
   }
   
+  const nunjucksOpts = options.nunjucks || {};
   const nunjucksEnv = configureSafeNunjucks(templateDirs, {
     autoescape: true,
     express: app,
     watch: isDev && !isTest,
-    noCache: isDev || isTest
+    noCache: nunjucksOpts.noCache ?? (isDev || isTest),
+    ...nunjucksOpts,
   });
+
+  if (devReloadHub && typeof devReloadHub.attachNunjucks === 'function') {
+    devReloadHub.attachNunjucks(nunjucksEnv);
+  }
   
   // Add custom Nunjucks filters
   nunjucksEnv.addFilter('json', (obj) => {
@@ -794,16 +1207,18 @@ function createApp(options = {}) {
   const pluginContext = { app, nunjucksEnv, options, middlewares, shutdownManager };
   pluginManager.registerSync(plugins, pluginContext);
   
-  // Request logging middleware
+  // Request logging & query profiling middleware
   if (logging) {
-    app.use((req, res, next) => {
-      const start = Date.now();
-      res.on('finish', () => {
-        const duration = Date.now() - start;
-        console.log(`${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
-      });
-      next();
+    const profilerMiddleware = createDevProfilerMiddleware({
+      db: options.db ?? null,
+      logger: options.logger || console,
+      detectNPlusOne: devOpts.nPlusOne !== false,
+      thresholdNPlusOne: devOpts.nPlusOneThreshold ?? 4,
+      slowQueryMs: devOpts.slowQueryMs ?? 50,
+      verbose: devOpts.verbose ?? false,
+      colors: devOpts.colors !== false,
     });
+    app.use(profilerMiddleware);
   }
   
   // 1. Scan and compile discovered routes (src/pages, src/api, modules/*)
@@ -827,6 +1242,86 @@ function createApp(options = {}) {
     console.log('\nMounting routes:');
   }
 
+  // Fast-Path Static & Dynamic Route Dispatcher ($O(1) direct static & dynamic LRU lookup)
+  // Eliminates Express linear layer regex matching (matchLayer) for static, dynamic, and 404 routes
+  app.use(function fastPathDispatcher(req, res, next) {
+    const rawPath = req.path || (req.url ? req.url.split('?')[0] : '/');
+    const pathname = rawPath.length > 1 && rawPath.endsWith('/') ? rawPath.slice(0, -1) : rawPath;
+    const method = req.method ? req.method.toUpperCase() : 'GET';
+
+    function getHandlersWithMiddlewares(routeHandlers) {
+      if (prefixMiddlewares.length === 0) return routeHandlers;
+      const applicable = [];
+      for (let i = 0; i < prefixMiddlewares.length; i++) {
+        const pm = prefixMiddlewares[i];
+        if (pathname === pm.prefix || pathname.startsWith(pm.prefix + '/')) {
+          applicable.push(...pm.handlers);
+        }
+      }
+      return applicable.length > 0 ? [...applicable, ...routeHandlers] : routeHandlers;
+    }
+
+    // 1. Static fast-path ($O(1) partitioned by method - zero string concat)
+    const methodMap = fastPathStaticByMethod[method];
+    let entry = methodMap ? methodMap.get(pathname) : undefined;
+    if (!entry && method === 'HEAD') {
+      entry = fastPathStaticByMethod.GET ? fastPathStaticByMethod.GET.get(pathname) : undefined;
+    }
+    if (entry) {
+      if (!req.params) req.params = {};
+      req.route = entry.routeInfo;
+      return dispatchFastPath(getHandlersWithMiddlewares(entry.handlers), req, res, next);
+    }
+
+    // 2. Dynamic route fast-path with LRU caching
+    if (dynamicRouteList.length > 0) {
+      const cacheKey = `${method} ${pathname}`;
+      const cached = getDynamicCache(cacheKey);
+
+      if (cached === NOT_FOUND_SENTINEL) {
+        return next();
+      }
+
+      if (cached) {
+        req.params = Object.assign({}, cached.params);
+        req.route = cached.entry.routeInfo;
+        return dispatchFastPath(getHandlersWithMiddlewares(cached.entry.handlers), req, res, next);
+      }
+
+      if (method === 'HEAD') {
+        const cachedGet = getDynamicCache(`GET ${pathname}`);
+        if (cachedGet && cachedGet !== NOT_FOUND_SENTINEL) {
+          req.params = Object.assign({}, cachedGet.params);
+          req.route = cachedGet.entry.routeInfo;
+          return dispatchFastPath(getHandlersWithMiddlewares(cachedGet.entry.handlers), req, res, next);
+        }
+      }
+
+      // Linear pattern scan over registered dynamic routes (only once per unique pathname)
+      for (let i = 0; i < dynamicRouteList.length; i++) {
+        const entry = dynamicRouteList[i];
+        if (entry.method !== method && !(method === 'HEAD' && entry.method === 'GET')) {
+          continue;
+        }
+
+        const match = pathname.match(entry.compiled.regex);
+        if (match) {
+          const params = extractRouteParams(entry.compiled.paramNames, match);
+          setDynamicCache(cacheKey, { entry, params });
+
+          req.params = Object.assign({}, params);
+          req.route = entry.routeInfo;
+          return dispatchFastPath(getHandlersWithMiddlewares(entry.handlers), req, res, next);
+        }
+      }
+
+      // Memoize as not found so subsequent requests for this path bypass regex scanning
+      setDynamicCache(cacheKey, NOT_FOUND_SENTINEL);
+    }
+
+    next();
+  });
+
   // Mount discovered routes
   const { routeMetadata: discoveredMeta, registerDynamicDiscoveredRoutes } = mountDiscoveredRoutes(app, routeTable, {
     nunjucks: nunjucksEnv,
@@ -969,7 +1464,7 @@ function createApp(options = {}) {
       : null;
 
   // 404 handler
-  app.use(async (req, res) => {
+  const notFoundHandler = async (req, res) => {
     res.status(404);
     const ctx = createErrorContext(req);
     
@@ -1015,7 +1510,8 @@ function createApp(options = {}) {
     } else {
       res.json({ error: 'Not Found', status: 404 });
     }
-  });
+  };
+  app.use(notFoundHandler);
   
   let customErrorHandler = null;
   app.setErrorHandler = function(handler) {
@@ -1163,6 +1659,25 @@ function createApp(options = {}) {
   app.listen = function(...args) {
     const server = origListen(...args);
     app.server = server;
+
+    // HTTP Server Socket Tuning: prevent 502 race conditions behind Cloudflare / Nginx / AWS ALB
+    // Node.js defaults keepAliveTimeout to 5s, whereas Cloudflare/ALB default to 60s idle keep-alive.
+    // Note: Node requires headersTimeout > keepAliveTimeout.
+    const serverOpts = options.server || {};
+    const keepAliveTimeout = serverOpts.keepAliveTimeout != null
+      ? serverOpts.keepAliveTimeout
+      : 65000;
+    const headersTimeout = serverOpts.headersTimeout != null
+      ? serverOpts.headersTimeout
+      : Math.max(keepAliveTimeout + 1000, 66000);
+
+    if (typeof server.keepAliveTimeout === 'number') {
+      server.keepAliveTimeout = keepAliveTimeout;
+    }
+    if (typeof server.headersTimeout === 'number') {
+      server.headersTimeout = headersTimeout;
+    }
+
     const adapter = new NodeHttpAdapter(server);
     shutdownManager.registerAdapter(adapter);
 
@@ -1170,11 +1685,62 @@ function createApp(options = {}) {
       shutdownManager.enableShutdownHooks();
     }
 
+    // Development startup banner
+    const shouldShowBanner =
+      devOpts.banner !== false &&
+      options.banner !== false &&
+      isDev &&
+      !isTest;
+
+    if (shouldShowBanner) {
+      server.once('listening', () => {
+        printDevBanner({
+          app,
+          server,
+          routeTable,
+          options,
+          db: options.db ?? null,
+          serviceRegistry,
+          pluginManager,
+          logger: options.logger || console,
+          showRouteTable: devOpts.routeTable !== false && options.routeTable !== false,
+        });
+      });
+    }
+
     return server;
   };
+
+  app.printDevBanner = function(opts = {}) {
+    printDevBanner({
+      app,
+      server: app.server,
+      routeTable,
+      options,
+      db: options.db ?? null,
+      serviceRegistry,
+      pluginManager,
+      logger: options.logger || console,
+      showRouteTable: true,
+      ...opts,
+    });
+  };
+
+  app.formatDevBanner = function(opts = {}) {
+    return formatDevBanner({
+      app,
+      server: app.server,
+      routeTable,
+      options,
+      db: options.db ?? null,
+      serviceRegistry,
+      pluginManager,
+      ...opts,
+    });
+  };
   
   return { app, nunjucksEnv, pluginManager, authMiddleware, shutdownManager };
 }
 
 // Export for use as library
-module.exports = { createApp };
+module.exports = { createApp, fastETag };