@expressots/adapter-express 4.0.0-preview.1 → 4.0.0-preview.3

package/lib/esm/adapter-express/application-express.js

@@ -17,7 +17,7 @@ import { HttpStatusCodeMiddleware } from "./express-utils/http-status-middleware
 import { InversifyExpressServer } from "./express-utils/inversify-express-server.js";
 import { setEngineEjs, setEngineHandlebars, setEnginePug } from "./render/engine.js";
 import { getControllersFromMetadata, getControllersFromContainer, getControllerMethodMetadata, getControllerMetadata, } from "./express-utils/utils.js";
-import { initializeStudio, stopStudio, isStudioEnabled, reportStudioRuntimeInfo, } from "./studio/index.js";
+import { initializeStudio, stopStudio, isStudioEnabled, reportStudioRuntimeInfo, rescanStudioRoutes, } from "./studio/index.js";
 /**
  * The AppExpress class provides methods for configuring and running an Express application.
  * @class AppExpress
@@ -63,23 +63,26 @@ export class AppExpress {
     portRetryAttempts = 10;
     /** Delay between port retry attempts (ms) */
     portRetryDelay = 500;
-    // Log buffering for banner-first display
-    // IMPORTANT: All these properties must be declared BEFORE initBuffering!
+    // Log buffering for banner-first display.
+    //
+    // Buffering is **opt-in** and is activated either by:
+    //   1. Constructing an `AppExpress` instance (the constructor calls
+    //      `startLogBuffering()`), or
+    //   2. The framework calling `AppExpress.startLogBuffering()` explicitly
+    //      from `bootstrap()` so logs emitted during container/module setup
+    //      are captured before the AppExpress instance even exists.
+    //
+    // Importing `@expressots/adapter-express` does NOT touch stdio. Test
+    // harnesses, type-only consumers, and tooling that imports the module
+    // without ever booting an app will see normal `process.stdout` /
+    // `console.*` behavior. `micro()` calls `disableBuffering()` on entry
+    // because it does not use the banner system.
     static originalStdoutWrite = null;
     static originalStderrWrite = null;
     static logBuffer = [];
     static isBuffering = false;
-    static bufferingInitialized = false;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static originalGlobalConsole = null;
-    // Initialize buffering when AppExpress class is loaded (before any instances are created)
-    // This ensures ALL logs are buffered from the very beginning for the full template.
-    // The micro() function explicitly disables this buffering since it doesn't use the banner system.
-    // This MUST be declared AFTER all the static properties it uses!
-    static initBuffering = (() => {
-        AppExpress.startLogBuffering();
-        return true;
-    })();
     /**
      * Disable log buffering. Called by micro() to restore normal console output
      * since micro API doesn't use the banner system.
@@ -91,9 +94,15 @@ export class AppExpress {
         AppExpress.logBuffer = [];
     }
     /**
-     * Start buffering all console output.
-     * This captures both console.log and direct process.stdout.write calls.
-     * @private
+     * Start buffering all console output for the banner-first display flow.
+     * Captures both `console.*` and direct `process.stdout.write` / `process.stderr.write`
+     * calls so they can be flushed in the correct order after the banner displays.
+     *
+     * Idempotent: calling this multiple times is safe.
+     *
+     * @public API — called by `bootstrap()` so logs emitted during container
+     * setup are captured before the `AppExpress` instance exists. Also called
+     * automatically inside the constructor as a safety net.
      */
     static startLogBuffering() {
         if (AppExpress.isBuffering)
@@ -199,8 +208,11 @@ export class AppExpress {
         }
     }
     constructor() {
-        // Buffering is already started via static initialization (initBuffering)
-        // This ensures ALL logs are captured from the very beginning
+        // Activate banner-first log buffering on first AppExpress construction.
+        // Idempotent — bootstrap() typically called this earlier so logs emitted
+        // during container/module setup were already buffered. micro() never
+        // reaches this constructor; it explicitly disables buffering itself.
+        AppExpress.startLogBuffering();
         this.globalConfiguration();
     }
     /**
@@ -280,24 +292,43 @@ export class AppExpress {
      * @internal
      */
     async handleExit(signal) {
-        // 1. Stop Studio Agent if running
-        await stopStudio();
-        // 2. Execute lifecycle shutdown hooks on all IShutdown providers
+        // Helper: race any drain against a hard cap. We never want a
+        // misbehaving cleanup hook (OTel exporter, slow DB driver, user
+        // shutdown promise that never resolves) to hold the whole exit
+        // chain. Each phase gets its own bound — total fits inside the
+        // outer `setShutdownTimeout` watchdog.
+        const withTimeout = async (p, ms) => {
+            const value = Promise.resolve(p).then(() => { });
+            const timer = new Promise((resolve) => setTimeout(resolve, ms).unref());
+            await Promise.race([value, timer]);
+        };
+        // 1. Stop Studio Agent if running. We cap this at 1.5s — the agent
+        //    itself caps its websocket drain at 500ms and OpenTelemetry at
+        //    500ms, but auto-instrumentations can leave handles around so
+        //    the wrapper close still occasionally drags. 1.5s is plenty.
+        await withTimeout(stopStudio(), 1500);
+        // 2. Execute lifecycle shutdown hooks on all IShutdown providers.
+        //    Capped at the user-configured shutdown timeout (default 5s).
         if (this.lifecycleRegistry) {
-            await this.lifecycleRegistry.executeShutdown(signal);
+            await withTimeout(this.lifecycleRegistry.executeShutdown(signal), this.shutdownTimeout);
         }
-        // 3. Call user's serverShutdown hook
-        await this.handleSyncOrAsync(this.serverShutdown(signal));
-        // 4. Gracefully close the HTTP server with connection force-close
+        // 3. Call user's serverShutdown hook (also capped).
+        await withTimeout(this.handleSyncOrAsync(this.serverShutdown(signal)), this.shutdownTimeout);
+        // 4. Gracefully close the HTTP server with aggressive connection
+        //    teardown. Order matters: we destroy *all* tracked connections
+        //    immediately (not just idle ones) before calling `close()`,
+        //    because otherwise an active keep-alive request would hold the
+        //    `close` callback open until either its keep-alive timer
+        //    expires (~5s) or the inner `forceCloseTimeout` fires. Killing
+        //    connections up-front lets `close` resolve in the next tick.
         if (this.serverInstance) {
             await new Promise((resolve) => {
-                // Set a timeout to force-destroy connections if graceful shutdown takes too long
                 const forceCloseTimeout = setTimeout(() => {
                     console.log(`⚠️  Force-closing ${this.activeConnections.size} active connections after ${this.shutdownTimeout}ms timeout`);
                     this.destroyAllConnections();
                     resolve();
                 }, this.shutdownTimeout);
-                // Try graceful close first
+                forceCloseTimeout.unref();
                 this.serverInstance.close((err) => {
                     clearTimeout(forceCloseTimeout);
                     if (err) {
@@ -306,12 +337,17 @@ export class AppExpress {
                     }
                     resolve();
                 });
-                // Immediately destroy idle connections (keep-alive connections with no pending requests)
-                // This speeds up shutdown significantly
-                this.serverInstance.closeIdleConnections?.();
+                // Aggressively kill keep-alive sockets so `close` actually
+                // resolves promptly. `closeAllConnections` is Node 18.2+; older
+                // versions silently no-op via the optional-call.
+                try {
+                    this.serverInstance.closeAllConnections?.();
+                }
+                catch {
+                    // best-effort — destroy our tracked set as a fallback
+                }
+                this.destroyAllConnections();
             });
-            // Clear all remaining connections
-            this.destroyAllConnections();
         }
     }
     /**
@@ -623,7 +659,16 @@ export class AppExpress {
                     interceptorCount: this.lastApplicationMetrics?.interceptors,
                     middlewareCount: this.lastApplicationMetrics?.middleware,
                     runtimeItems: this.collectStudioRuntimeItems(),
+                    middlewarePreset: this.collectMiddlewarePresetInfo(),
                 });
+                // Re-scan routes now that `InversifyExpressServer.build()` has
+                // populated the Express `_router` stack. The agent's first scan
+                // happens before controllers are bound (Studio middleware ships
+                // ahead of route registration so it can capture every request),
+                // so without this rescan newly-added or never-bound controllers
+                // never appear in the Studio Routes / Architecture views.
+                // Fire-and-forget; the Studio Agent broadcasts the result over WS.
+                void rescanStudioRoutes();
                 // Setup signal handlers for graceful shutdown
                 // Supported signals:
                 // - SIGTERM: Standard termination (Kubernetes, Docker, process managers)
@@ -651,17 +696,64 @@ export class AppExpress {
                             return;
                         }
                         this.isShuttingDown = true;
-                        // Use console.log for shutdown messages - synchronous and guaranteed to write before exit
-                        console.log(`\n📡 Signal ${signal} received, initiating graceful shutdown...`);
-                        // Execute shutdown hooks and exit
+                        // Emit the shutdown notice through the framework Logger so it
+                        // matches the standard "[ExpressoTS] … INFO [context] …" output.
+                        // The leading newline keeps it off the terminal's "^C" echo line.
+                        process.stdout.write("\n");
+                        this.logger.info(`Signal ${signal} received, initiating graceful shutdown...`, "adapter-express");
+                        // Hard overall cap on the graceful shutdown. `handleExit` chains
+                        // several `await`s — Studio agent stop, lifecycle shutdown
+                        // hooks, the user's `serverShutdown`, and finally
+                        // `serverInstance.close`. If any of those hang (an unresponsive
+                        // OpenTelemetry exporter, a pending DB transaction, a slow
+                        // user hook, an HTTP keep-alive socket the OS hasn't reaped
+                        // yet), the host process otherwise sits in
+                        // "📡 Signal SIGINT received, initiating graceful shutdown…"
+                        // for minutes. Capping the whole pipeline keeps the developer
+                        // ergonomics tight (Ctrl+C is interactive — they want their
+                        // prompt back now) while still allowing fast hooks to run to
+                        // completion.
+                        //
+                        // We expose the cap so apps with legitimately long drains
+                        // (e.g. flushing a 50k-message queue) can opt into a longer
+                        // timeout via `setShutdownTimeout`.
+                        const overallCap = this.shutdownTimeout + 3000;
+                        let forced = false;
+                        const overallTimer = setTimeout(() => {
+                            forced = true;
+                            console.warn(`⚠️  Graceful shutdown exceeded ${overallCap}ms; ` +
+                                `force-exiting. If this happens routinely, raise ` +
+                                `\`setShutdownTimeout\` or audit your IShutdown hooks.`);
+                            this.destroyAllConnections();
+                            process.exit(0);
+                        }, overallCap);
+                        // Don't let the watchdog timer keep the event loop alive on
+                        // its own; if everything else releases the loop it's fine
+                        // for `process.exit(0)` to fire from `handleExit` cleanly.
+                        overallTimer.unref();
                         this.handleExit(signal)
                             .then(() => {
-                            console.log("✅ Graceful shutdown completed");
-                            process.exit(0);
+                            if (forced)
+                                return;
+                            clearTimeout(overallTimer);
+                            this.logger.info("Graceful shutdown completed", "adapter-express");
+                            // Flush stdout before exiting. Writing an empty chunk with a
+                            // callback guarantees the log line above is fully drained to
+                            // the terminal (the callback only fires after prior queued
+                            // writes complete), so the message can't appear after the
+                            // shell has already redrawn its prompt.
+                            process.stdout.write("", () => {
+                                process.exit(0);
+                            });
                         })
                             .catch((error) => {
-                            console.error(`❌ Error during shutdown: ${error.message}`);
-                            process.exit(1);
+                            if (forced)
+                                return;
+                            clearTimeout(overallTimer);
+                            this.logger.error(`Error during shutdown: ${error.message}`, "adapter-express");
+                            process.stderr.write("", () => {
+                                process.exit(1);
+                            });
                         });
                     };
                     // Store handler for later removal and register it
@@ -1161,21 +1253,236 @@ export class AppExpress {
                     });
                 }
             }
-            // Bail out if both lists are empty — nothing useful to forward.
-            if (providers.length === 0 && interceptors.length === 0) {
+            const middleware = this.collectMiddlewarePipelineItems();
+            const middlewareBindings = this.collectMiddlewareBindings();
+            if (providers.length === 0 &&
+                interceptors.length === 0 &&
+                !middleware &&
+                !middlewareBindings) {
+                return undefined;
+            }
+            return { providers, interceptors, middleware, middlewareBindings };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Harvest controller- and route-scoped middleware bindings from
+     * Reflect metadata. Each entry describes a single edge the Studio
+     * architecture map should draw, e.g. "AuthMiddleware → UserController
+     * (route POST /users/:id)".
+     *
+     * The middleware values stored on `ControllerMetadata.middleware` are
+     * a polymorphic union (class, function, registered name, conditional
+     * config, …). We normalise each to a display name; entries we can't
+     * name (anonymous arrow functions, plain object configs without a
+     * `name` field) are omitted. The agent's static scan picks up the
+     * remaining named cases via decorator parsing — between the two
+     * sources Studio sees a complete graph for the common patterns.
+     */
+    collectMiddlewareBindings() {
+        try {
+            const controllers = getControllersFromMetadata();
+            if (!controllers || controllers.length === 0)
                 return undefined;
+            const out = [];
+            const nameOf = (value) => {
+                if (value == null)
+                    return null;
+                if (typeof value === "string")
+                    return value;
+                if (typeof value === "symbol") {
+                    const desc = value.description;
+                    return desc && desc.length > 0 ? desc : null;
+                }
+                if (typeof value === "function") {
+                    const fnName = value.name;
+                    return typeof fnName === "string" && fnName.length > 0 ? fnName : null;
+                }
+                if (typeof value === "object") {
+                    const candidate = value.name;
+                    if (typeof candidate === "string" && candidate.length > 0) {
+                        return candidate;
+                    }
+                    const ctorName = value.constructor?.name;
+                    if (typeof ctorName === "string" && ctorName.length > 0 && ctorName !== "Object") {
+                        return ctorName;
+                    }
+                }
+                return null;
+            };
+            for (const controllerTarget of controllers) {
+                const controllerCtor = controllerTarget;
+                const controllerName = controllerCtor.name;
+                if (typeof controllerName !== "string" || controllerName.length === 0) {
+                    continue;
+                }
+                const ctrlMeta = getControllerMetadata(controllerCtor);
+                if (ctrlMeta?.middleware && Array.isArray(ctrlMeta.middleware)) {
+                    for (const mw of ctrlMeta.middleware) {
+                        const middlewareName = nameOf(mw);
+                        if (!middlewareName)
+                            continue;
+                        out.push({
+                            middlewareName,
+                            scope: "controller",
+                            controllerName,
+                        });
+                    }
+                }
+                const methodMeta = getControllerMethodMetadata(controllerCtor);
+                if (Array.isArray(methodMeta)) {
+                    const basePath = ctrlMeta?.path ?? "";
+                    for (const route of methodMeta) {
+                        if (!route?.middleware || !Array.isArray(route.middleware))
+                            continue;
+                        const httpMethod = typeof route.method === "string" ? route.method.toUpperCase() : undefined;
+                        const fullPath = this.joinRoutePath(basePath, route.path);
+                        for (const mw of route.middleware) {
+                            const middlewareName = nameOf(mw);
+                            if (!middlewareName)
+                                continue;
+                            out.push({
+                                middlewareName,
+                                scope: "route",
+                                controllerName,
+                                controllerMethod: typeof route.key === "string" ? route.key : undefined,
+                                httpMethod,
+                                routePath: fullPath,
+                            });
+                        }
+                    }
+                }
             }
-            return { providers, interceptors };
+            return out.length > 0 ? out : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Combine a controller's base path with a route path, normalising
+     * leading/trailing slashes. Mirrors the simpler logic Studio uses to
+     * build `RouteInfo.path` so the bindings line up with route entries.
+     */
+    joinRoutePath(basePath, routePath) {
+        const base = basePath?.startsWith("/") ? basePath : `/${basePath ?? ""}`;
+        if (!routePath || routePath === "/" || routePath === "")
+            return base || "/";
+        const tail = routePath.startsWith("/") ? routePath : `/${routePath}`;
+        return (base + tail).replace(/\/+/g, "/");
+    }
+    /**
+     * Collect the ordered middleware pipeline from the Middleware service
+     * for forwarding to Studio. Uses feature-detection so older core
+     * versions that lack `getPipelineInfo()` won't break.
+     */
+    collectMiddlewarePipelineItems() {
+        try {
+            const mw = this.Middleware;
+            const getPipelineInfo = mw.getPipelineInfo;
+            if (typeof getPipelineInfo !== "function")
+                return undefined;
+            const info = getPipelineInfo.call(mw);
+            if (!info || !info.entries || info.entries.length === 0)
+                return undefined;
+            return info.entries.map((e) => ({
+                name: e.name,
+                category: e.category,
+                type: e.type,
+                order: e.order,
+                path: e.path !== "Global" ? e.path : undefined,
+            }));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Build the middleware preset info snapshot for Studio. Reads the
+     * last applied preset from the Middleware service and transforms it
+     * into the shape Studio expects.
+     */
+    collectMiddlewarePresetInfo() {
+        try {
+            const mw = this.Middleware;
+            const getPreset = mw.getLastAppliedPreset;
+            if (typeof getPreset !== "function")
+                return undefined;
+            const preset = getPreset.call(mw);
+            if (!preset)
+                return undefined;
+            const cfg = preset.config;
+            const parse = cfg.parse && typeof cfg.parse === "object"
+                ? {
+                    json: cfg.parse.json && typeof cfg.parse.json === "object"
+                        ? { limit: cfg.parse.json.limit }
+                        : undefined,
+                    urlencoded: cfg.parse.urlencoded && typeof cfg.parse.urlencoded === "object"
+                        ? {
+                            limit: cfg.parse.urlencoded.limit,
+                            extended: cfg.parse.urlencoded.extended,
+                        }
+                        : undefined,
+                    cookies: !!cfg.parse.cookies,
+                }
+                : cfg.parse
+                    ? { json: { limit: "100kb" }, cookies: false }
+                    : undefined;
+            let security;
+            if (typeof cfg.security === "string") {
+                security = resolveSecurityTierForStudio(cfg.security);
+            }
+            else if (cfg.security && typeof cfg.security === "object") {
+                const sec = cfg.security;
+                security = {
+                    helmet: sec.headers !== false,
+                    cors: sec.cors && typeof sec.cors === "object"
+                        ? sec.cors
+                        : sec.cors !== false
+                            ? { origin: true }
+                            : undefined,
+                    rateLimit: sec.rateLimit && typeof sec.rateLimit === "object"
+                        ? sec.rateLimit
+                        : sec.rateLimit
+                            ? { windowMs: 60000, max: 100 }
+                            : false,
+                };
+            }
+            const compress = cfg.compress
+                ? {
+                    enabled: true,
+                    level: typeof cfg.compress === "object" ? cfg.compress.level : undefined,
+                }
+                : { enabled: false };
+            const logger = cfg.logger
+                ? {
+                    enabled: true,
+                    implementation: typeof cfg.logger === "object" ? cfg.logger.implementation : "auto",
+                }
+                : { enabled: false };
+            return {
+                name: preset.name,
+                hasOverrides: preset.hasOverrides,
+                parse,
+                security,
+                compress,
+                logger,
+            };
         }
         catch {
-            // Metadata reads should never break boot. Status page just falls
-            // back to its static-scan list.
             return undefined;
         }
     }
     /**
      * Display middleware startup logs after the banner.
-     * This makes startup logging transparent to the user - no need for manual code in postServerInitialization().
+     *
+     * Warnings (e.g. missing optional packages like `helmet`) are always surfaced
+     * so the developer can act on them. Informational entries (e.g. "Security
+     * configured", "Applied preset: api") are demoted to `debug` since the
+     * dashboard already shows the active middleware count; set `LOG_LEVEL=DEBUG`
+     * to see the full breakdown.
      * @private
      */
     displayMiddlewareStartupLogs() {
@@ -1190,7 +1497,7 @@ export class AppExpress {
                 this.logger.warn(log.message, "middleware");
             }
             else {
-                this.logger.info(log.message, "middleware");
+                this.logger.withContext("middleware").debug(log.message);
             }
         });
         this.Middleware.clearStartupLogs();
@@ -1267,7 +1574,7 @@ export class AppExpress {
             };
             // Display banner
             this.bannerGenerator.display(this.port, this.environment || "development", finalAppInfo, metrics, features, {
-                "Global Prefix": this.globalPrefix || "/",
+                Prefix: this.globalPrefix || "/",
                 "Node Version": process.version,
                 Platform: process.platform,
             }, bannerData);
@@ -1298,3 +1605,52 @@ export class AppExpress {
         }
     }
 }
+/**
+ * Resolve a named security tier string into the display-friendly shape
+ * expected by the Studio Middleware card. Mirrors the defaults applied
+ * by `Middleware.getSecurityPreset()` in `@expressots/core`.
+ */
+function resolveSecurityTierForStudio(tier) {
+    switch (tier) {
+        case "api":
+            return {
+                tier,
+                helmet: true,
+                cors: {
+                    origin: true,
+                    credentials: true,
+                    methods: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                    allowedHeaders: ["Content-Type", "Authorization", "X-Requested-With"],
+                },
+                rateLimit: { windowMs: 60000, max: 100 },
+            };
+        case "strict":
+            return {
+                tier,
+                helmet: true,
+                cors: { origin: false },
+                rateLimit: { windowMs: 60000, max: 50 },
+            };
+        case "relaxed":
+            return {
+                tier,
+                helmet: true,
+                cors: { origin: true },
+                rateLimit: false,
+            };
+        case "minimal":
+            return {
+                tier,
+                helmet: false,
+                rateLimit: false,
+            };
+        case "standard":
+        default:
+            return {
+                tier,
+                helmet: true,
+                cors: { origin: true },
+                rateLimit: false,
+            };
+    }
+}