@macss/modular-api 0.1.0 → 0.3.0

package/dist/core/logger/logger.js

@@ -0,0 +1,132 @@
+"use strict";
+// ============================================================
+// core/logger/logger.ts
+// LogLevel enum, ModularLogger interface, RequestScopedLogger.
+// Mirror of logger.dart — RFC 5424, JSON to stdout, zero deps.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestScopedLogger = exports.LogLevel = void 0;
+/**
+ * RFC 5424 log levels in descending severity order.
+ *
+ * Filtering rule: if configured `logLevel = X`, only messages with
+ * `value <= X` are emitted. Higher values produce total silence.
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["emergency"] = 0] = "emergency";
+    LogLevel[LogLevel["alert"] = 1] = "alert";
+    LogLevel[LogLevel["critical"] = 2] = "critical";
+    LogLevel[LogLevel["error"] = 3] = "error";
+    LogLevel[LogLevel["warning"] = 4] = "warning";
+    LogLevel[LogLevel["notice"] = 5] = "notice";
+    LogLevel[LogLevel["info"] = 6] = "info";
+    LogLevel[LogLevel["debug"] = 7] = "debug";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+/** Human-readable name for each LogLevel value. */
+const LEVEL_NAME = {
+    [LogLevel.emergency]: 'emergency',
+    [LogLevel.alert]: 'alert',
+    [LogLevel.critical]: 'critical',
+    [LogLevel.error]: 'error',
+    [LogLevel.warning]: 'warning',
+    [LogLevel.notice]: 'notice',
+    [LogLevel.info]: 'info',
+    [LogLevel.debug]: 'debug',
+};
+/**
+ * Per-request logger that carries `traceId` and respects `logLevel` filtering.
+ *
+ * Created by `loggingMiddleware` for each incoming HTTP request and injected
+ * into the UseCase via the `logger` property.
+ *
+ * Accepts an optional `writeFn` for output — defaults to `console.log`.
+ * In tests, pass a capturing function to inspect output without side-effects.
+ */
+class RequestScopedLogger {
+    constructor(traceId, logLevel, serviceName, writeFn = (line) => process.stdout.write(line + '\n')) {
+        this.traceId = traceId;
+        this.logLevel = logLevel;
+        this.serviceName = serviceName;
+        this.writeFn = writeFn;
+    }
+    // ─── Public API (8 RFC 5424 levels) ──────────────────────────────
+    emergency(msg, fields) {
+        this.log(LogLevel.emergency, msg, { fields });
+    }
+    alert(msg, fields) {
+        this.log(LogLevel.alert, msg, { fields });
+    }
+    critical(msg, fields) {
+        this.log(LogLevel.critical, msg, { fields });
+    }
+    error(msg, fields) {
+        this.log(LogLevel.error, msg, { fields });
+    }
+    warning(msg, fields) {
+        this.log(LogLevel.warning, msg, { fields });
+    }
+    notice(msg, fields) {
+        this.log(LogLevel.notice, msg, { fields });
+    }
+    info(msg, fields) {
+        this.log(LogLevel.info, msg, { fields });
+    }
+    debug(msg, fields) {
+        this.log(LogLevel.debug, msg, { fields });
+    }
+    // ─── Framework-internal: request/response logging ────────────────
+    /** Emits a "request received" log at `info` level. */
+    logRequest(opts) {
+        this.log(LogLevel.info, 'request received', {
+            extra: { method: opts.method, route: opts.route },
+        });
+    }
+    /** Emits a "request completed" log at the level determined by `statusCode`. */
+    logResponse(opts) {
+        this.log(RequestScopedLogger.levelForStatus(opts.statusCode), 'request completed', {
+            extra: {
+                method: opts.method,
+                route: opts.route,
+                status: opts.statusCode,
+                duration_ms: opts.durationMs,
+            },
+        });
+    }
+    /** Emits an "unhandled exception" log at `error` level. No stack trace. */
+    logUnhandledException(opts) {
+        this.log(LogLevel.error, 'unhandled exception', {
+            extra: { route: opts.route, status: 500 },
+        });
+    }
+    // ─── Internal ────────────────────────────────────────────────────
+    log(level, msg, opts = {}) {
+        // Filtering: only emit if the message level <= configured logLevel.
+        if (level > this.logLevel)
+            return;
+        const entry = {
+            ts: Date.now() / 1000,
+            level: LEVEL_NAME[level],
+            severity: level,
+            msg,
+            service: this.serviceName,
+            trace_id: this.traceId,
+        };
+        if (opts.extra)
+            Object.assign(entry, opts.extra);
+        if (opts.fields)
+            entry['fields'] = opts.fields;
+        this.writeFn(JSON.stringify(entry));
+    }
+    /** Maps HTTP status code → RFC 5424 log level. */
+    static levelForStatus(status) {
+        if (status >= 500)
+            return LogLevel.error;
+        if (status >= 400)
+            return LogLevel.warning;
+        if (status >= 200 && status < 400)
+            return LogLevel.info;
+        return LogLevel.notice; // 1xx
+    }
+}
+exports.RequestScopedLogger = RequestScopedLogger;

package/dist/core/logger/logging_middleware.d.ts

@@ -0,0 +1,25 @@
+import type { RequestHandler } from 'express';
+import { LogLevel } from './logger';
+import type { WriteFn } from './logger';
+/** Key used in `res.locals` to propagate the logger to downstream handlers. */
+export declare const LOGGER_LOCALS_KEY = "modularLogger";
+export interface LoggingMiddlewareOptions {
+    logLevel: LogLevel;
+    serviceName: string;
+    excludedRoutes?: string[];
+    /** Override output for testing. Defaults to stdout. */
+    writeFn?: WriteFn;
+}
+/**
+ * Creates an Express middleware that:
+ *
+ * 1. Reads or generates a `trace_id` (from `X-Request-ID` header).
+ * 2. Creates a {@link RequestScopedLogger} scoped to the current request.
+ * 3. Emits a `"request received"` log at `info` level.
+ * 4. Passes the logger via `res.locals` for downstream handlers.
+ * 5. Emits a `"request completed"` log (level based on status code).
+ * 6. Returns the `X-Request-ID` header in the response.
+ *
+ * Requests whose path matches `excludedRoutes` are passed through silently.
+ */
+export declare function loggingMiddleware(opts: LoggingMiddlewareOptions): RequestHandler;

package/dist/core/logger/logging_middleware.js

@@ -0,0 +1,60 @@
+"use strict";
+// ============================================================
+// core/logger/logging_middleware.ts
+// Express middleware — trace_id, structured JSON logs.
+// Mirror of logging_middleware.dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOGGER_LOCALS_KEY = void 0;
+exports.loggingMiddleware = loggingMiddleware;
+const node_crypto_1 = require("node:crypto");
+const logger_1 = require("./logger");
+/** Key used in `res.locals` to propagate the logger to downstream handlers. */
+exports.LOGGER_LOCALS_KEY = 'modularLogger';
+/**
+ * Creates an Express middleware that:
+ *
+ * 1. Reads or generates a `trace_id` (from `X-Request-ID` header).
+ * 2. Creates a {@link RequestScopedLogger} scoped to the current request.
+ * 3. Emits a `"request received"` log at `info` level.
+ * 4. Passes the logger via `res.locals` for downstream handlers.
+ * 5. Emits a `"request completed"` log (level based on status code).
+ * 6. Returns the `X-Request-ID` header in the response.
+ *
+ * Requests whose path matches `excludedRoutes` are passed through silently.
+ */
+function loggingMiddleware(opts) {
+    const excludedSet = new Set(opts.excludedRoutes ?? []);
+    return (req, res, next) => {
+        const path = req.path;
+        // Skip excluded routes (health, metrics, docs).
+        if (excludedSet.has(path)) {
+            return next();
+        }
+        // 1. Resolve trace_id
+        const headerValue = req.headers['x-request-id'];
+        const traceId = typeof headerValue === 'string' && headerValue.length > 0 ? headerValue : (0, node_crypto_1.randomUUID)();
+        // 2. Create per-request logger
+        const logger = new logger_1.RequestScopedLogger(traceId, opts.logLevel, opts.serviceName, opts.writeFn);
+        const method = req.method.toUpperCase();
+        const route = path;
+        // 3. "request received"
+        logger.logRequest({ method, route });
+        // 4. Propagate logger via res.locals
+        res.locals[exports.LOGGER_LOCALS_KEY] = logger;
+        // 5. Attach X-Request-ID to response
+        res.setHeader('X-Request-ID', traceId);
+        // 6. Capture timing and emit response log on finish
+        const startNs = process.hrtime.bigint();
+        res.on('finish', () => {
+            const durationMs = Number(process.hrtime.bigint() - startNs) / 1e6;
+            logger.logResponse({
+                method,
+                route,
+                statusCode: res.statusCode,
+                durationMs,
+            });
+        });
+        next();
+    };
+}

package/dist/core/metrics/metric_registry.d.ts

@@ -0,0 +1,32 @@
+import { Registry, Counter, Gauge, Histogram, type CounterConfiguration, type GaugeConfiguration, type HistogramConfiguration } from 'prom-client';
+/**
+ * Internal registry wrapping prom-client's `Registry`.
+ *
+ * On construction, registers `process_start_time_seconds` as a gauge
+ * set to the current epoch in seconds.
+ */
+export declare class MetricRegistry {
+    readonly registry: Registry;
+    private readonly names;
+    constructor();
+    createCounter<T extends string = string>(config: Pick<CounterConfiguration<T>, 'name' | 'help' | 'labelNames'>): Counter<T>;
+    createGauge<T extends string = string>(config: Pick<GaugeConfiguration<T>, 'name' | 'help' | 'labelNames'>): Gauge<T>;
+    createHistogram<T extends string = string>(config: Pick<HistogramConfiguration<T>, 'name' | 'help' | 'labelNames' | 'buckets'>): Histogram<T>;
+    /** Serializes all metrics to Prometheus text exposition format. */
+    serialize(): Promise<string>;
+    /** Content type for the Prometheus text format. */
+    get contentType(): string;
+    private assertUnique;
+}
+/**
+ * Public API for users to register custom metrics.
+ * Validates names and rejects reserved prefixes before delegating.
+ */
+export declare class MetricsRegistrar {
+    private readonly registry;
+    constructor(registry: MetricRegistry);
+    createCounter<T extends string = string>(config: Pick<CounterConfiguration<T>, 'name' | 'help' | 'labelNames'>): Counter<T>;
+    createGauge<T extends string = string>(config: Pick<GaugeConfiguration<T>, 'name' | 'help' | 'labelNames'>): Gauge<T>;
+    createHistogram<T extends string = string>(config: Pick<HistogramConfiguration<T>, 'name' | 'help' | 'labelNames' | 'buckets'>): Histogram<T>;
+    private validate;
+}

package/dist/core/metrics/metric_registry.js

@@ -0,0 +1,104 @@
+"use strict";
+// ============================================================
+// core/metrics/metric_registry.ts
+// Wraps prom-client with a two-layer API:
+//   MetricRegistry — internal, manages prom-client Registry
+//   MetricsRegistrar — public, validates names before delegating
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsRegistrar = exports.MetricRegistry = void 0;
+const prom_client_1 = require("prom-client");
+/** Prometheus metric name regex. */
+const VALID_NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+function assertValidName(name) {
+    if (!name || !VALID_NAME.test(name)) {
+        throw new Error(`Invalid metric name "${name}": must match [a-zA-Z_:][a-zA-Z0-9_:]*`);
+    }
+}
+// ── MetricRegistry (internal) ─────────────────────────────────────────
+/**
+ * Internal registry wrapping prom-client's `Registry`.
+ *
+ * On construction, registers `process_start_time_seconds` as a gauge
+ * set to the current epoch in seconds.
+ */
+class MetricRegistry {
+    constructor() {
+        this.names = new Set();
+        this.registry = new prom_client_1.Registry();
+        // Auto-register process_start_time_seconds.
+        const startTime = this.createGauge({
+            name: 'process_start_time_seconds',
+            help: 'Start time of the process since unix epoch in seconds.',
+        });
+        startTime.set(Date.now() / 1000);
+    }
+    createCounter(config) {
+        this.assertUnique(config.name);
+        const counter = new prom_client_1.Counter({
+            ...config,
+            registers: [this.registry],
+        });
+        return counter;
+    }
+    createGauge(config) {
+        this.assertUnique(config.name);
+        const gauge = new prom_client_1.Gauge({
+            ...config,
+            registers: [this.registry],
+        });
+        return gauge;
+    }
+    createHistogram(config) {
+        this.assertUnique(config.name);
+        const histogram = new prom_client_1.Histogram({
+            ...config,
+            registers: [this.registry],
+        });
+        return histogram;
+    }
+    /** Serializes all metrics to Prometheus text exposition format. */
+    async serialize() {
+        return this.registry.metrics();
+    }
+    /** Content type for the Prometheus text format. */
+    get contentType() {
+        return this.registry.contentType;
+    }
+    assertUnique(name) {
+        if (this.names.has(name)) {
+            throw new Error(`Metric "${name}" is already registered.`);
+        }
+        this.names.add(name);
+    }
+}
+exports.MetricRegistry = MetricRegistry;
+// ── MetricsRegistrar (public) ─────────────────────────────────────────
+/**
+ * Public API for users to register custom metrics.
+ * Validates names and rejects reserved prefixes before delegating.
+ */
+class MetricsRegistrar {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    createCounter(config) {
+        this.validate(config.name);
+        return this.registry.createCounter(config);
+    }
+    createGauge(config) {
+        this.validate(config.name);
+        return this.registry.createGauge(config);
+    }
+    createHistogram(config) {
+        this.validate(config.name);
+        return this.registry.createHistogram(config);
+    }
+    validate(name) {
+        assertValidName(name);
+        if (name.startsWith('__')) {
+            throw new Error(`Metric name "${name}" uses reserved prefix "__".`);
+        }
+    }
+}
+exports.MetricsRegistrar = MetricsRegistrar;

package/dist/core/metrics/metrics_middleware.d.ts

@@ -0,0 +1,24 @@
+import type { RequestHandler } from 'express';
+import type { Counter, Gauge, Histogram } from 'prom-client';
+import type { MetricRegistry } from './metric_registry';
+export interface MetricsMiddlewareOptions {
+    requestsTotal: Counter<'method' | 'route' | 'status_code'>;
+    requestsInFlight: Gauge;
+    requestDuration: Histogram<'method' | 'route' | 'status_code'>;
+    excludedRoutes: string[];
+    registeredPaths: string[];
+}
+/**
+ * Creates an Express middleware that instruments HTTP requests.
+ *
+ * Records:
+ * - `requestsTotal` — counter with labels: method, route, status_code
+ * - `requestsInFlight` — gauge (inc on entry, dec on finish)
+ * - `requestDuration` — histogram with labels: method, route, status_code
+ */
+export declare function metricsMiddleware(opts: MetricsMiddlewareOptions): RequestHandler;
+/**
+ * Creates an Express handler that returns Prometheus metrics.
+ * Always returns HTTP 200 with `text/plain; version=0.0.4; charset=utf-8`.
+ */
+export declare function metricsHandler(registry: MetricRegistry): RequestHandler;

package/dist/core/metrics/metrics_middleware.js

@@ -0,0 +1,51 @@
+"use strict";
+// ============================================================
+// core/metrics/metrics_middleware.ts
+// Express middleware + handler for Prometheus metrics.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metricsMiddleware = metricsMiddleware;
+exports.metricsHandler = metricsHandler;
+/**
+ * Creates an Express middleware that instruments HTTP requests.
+ *
+ * Records:
+ * - `requestsTotal` — counter with labels: method, route, status_code
+ * - `requestsInFlight` — gauge (inc on entry, dec on finish)
+ * - `requestDuration` — histogram with labels: method, route, status_code
+ */
+function metricsMiddleware(opts) {
+    const excludedSet = new Set(opts.excludedRoutes);
+    const registeredSet = new Set(opts.registeredPaths);
+    return (req, res, next) => {
+        const path = req.path;
+        // Skip excluded routes.
+        if (excludedSet.has(path)) {
+            return next();
+        }
+        const method = req.method.toUpperCase();
+        const route = registeredSet.has(path) ? path : 'UNMATCHED';
+        opts.requestsInFlight.inc();
+        const startTime = process.hrtime.bigint();
+        res.on('finish', () => {
+            opts.requestsInFlight.dec();
+            const durationNs = Number(process.hrtime.bigint() - startTime);
+            const durationSecs = durationNs / 1e9;
+            const statusCode = res.statusCode.toString();
+            const labels = { method, route, status_code: statusCode };
+            opts.requestsTotal.inc(labels);
+            opts.requestDuration.observe(labels, durationSecs);
+        });
+        next();
+    };
+}
+/**
+ * Creates an Express handler that returns Prometheus metrics.
+ * Always returns HTTP 200 with `text/plain; version=0.0.4; charset=utf-8`.
+ */
+function metricsHandler(registry) {
+    return async (_req, res) => {
+        const body = await registry.serialize();
+        res.status(200).set('Content-Type', 'text/plain; version=0.0.4; charset=utf-8').send(body);
+    };
+}

package/dist/core/modular_api.d.ts

@@ -1,10 +1,31 @@
 import { type RequestHandler } from 'express';
 import { ModuleBuilder } from './module_builder';
+import type { HealthCheck } from './health/health_check';
+import { MetricsRegistrar } from './metrics/metric_registry';
+import { LogLevel } from './logger/logger';
 export interface ModularApiOptions {
     /** Base path prefix for all module routes. Default: '/api' */
     basePath?: string;
     /** API title shown in Swagger UI. Default: 'API' */
     title?: string;
+    /** API version string (e.g. '1.0.0'). Used in health check response. Default: '0.0.0' */
+    version?: string;
+    /**
+     * Release identifier. Defaults to `version-debug`.
+     * Override via `process.env.RELEASE_ID`.
+     */
+    releaseId?: string;
+    /** Opt-in Prometheus metrics endpoint. Default: false */
+    metricsEnabled?: boolean;
+    /** Path for the metrics endpoint. Default: '/metrics' */
+    metricsPath?: string;
+    /** Routes excluded from instrumentation. Default: ['/metrics', '/health', '/docs'] */
+    excludedMetricsRoutes?: string[];
+    /**
+     * Minimum log level for the structured JSON logger.
+     * Default: LogLevel.info (emits emergency..info, suppresses debug).
+     */
+    logLevel?: LogLevel;
 }
 /**
  * Main entry point for modular_api.
@@ -24,7 +45,7 @@ export interface ModularApiOptions {
  * ```
  *
  * Auto-mounted endpoints:
- *   GET /health  → 200 "ok"
+ *   GET /health  → 200/503 application/health+json (IETF draft)
  *   GET /docs    → Swagger UI
  */
 export declare class ModularApi {
@@ -33,7 +54,28 @@ export declare class ModularApi {
     private readonly basePath;
     private readonly title;
     private readonly middlewares;
+    private readonly healthService;
+    private readonly metricsEnabled;
+    private readonly metricsPath;
+    private readonly excludedMetricsRoutes;
+    private readonly metricRegistry?;
+    private readonly _metricsRegistrar?;
+    private readonly httpRequestsTotal?;
+    private readonly httpRequestsInFlight?;
+    private readonly httpRequestDuration?;
+    private readonly logLevel;
+    /** Public accessor for custom-metric registration. Undefined when metrics are disabled. */
+    get metrics(): MetricsRegistrar | undefined;
     constructor(options?: ModularApiOptions);
+    /**
+     * Register a {@link HealthCheck} to be evaluated on `GET /health`.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.addHealthCheck(new DatabaseHealthCheck());
+     * ```
+     */
+    addHealthCheck(check: HealthCheck): this;
     /**
      * Registers a group of use cases under a named module.
      * Returns `this` for method chaining.

package/dist/core/modular_api.js

@@ -13,6 +13,13 @@ const express_1 = __importDefault(require("express"));
 const module_builder_1 = require("./module_builder");
 const openapi_1 = require("../openapi/openapi");
 const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+const health_service_1 = require("./health/health_service");
+const health_handler_1 = require("./health/health_handler");
+const metric_registry_1 = require("./metrics/metric_registry");
+const metrics_middleware_1 = require("./metrics/metrics_middleware");
+const logging_middleware_1 = require("./logger/logging_middleware");
+const logger_1 = require("./logger/logger");
+const registry_1 = require("./registry");
 /**
  * Main entry point for modular_api.
  *
@@ -31,18 +38,61 @@ const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
  * ```
  *
  * Auto-mounted endpoints:
- *   GET /health  → 200 "ok"
+ *   GET /health  → 200/503 application/health+json (IETF draft)
  *   GET /docs    → Swagger UI
  */
 class ModularApi {
+    /** Public accessor for custom-metric registration. Undefined when metrics are disabled. */
+    get metrics() {
+        return this._metricsRegistrar;
+    }
     constructor(options = {}) {
         this.middlewares = [];
         this.basePath = options.basePath ?? '/api';
-        this.title = options.title ?? 'API';
+        this.title = options.title ?? 'Modular API';
+        this.healthService = new health_service_1.HealthService({
+            version: options.version ?? 'x.y.z',
+            releaseId: options.releaseId,
+        });
+        // Metrics setup
+        this.metricsEnabled = options.metricsEnabled ?? false;
+        this.metricsPath = options.metricsPath ?? '/metrics';
+        this.excludedMetricsRoutes = options.excludedMetricsRoutes ?? ['/metrics', '/health', '/docs'];
+        // Logging
+        this.logLevel = options.logLevel ?? logger_1.LogLevel.info;
+        if (this.metricsEnabled) {
+            this.metricRegistry = new metric_registry_1.MetricRegistry();
+            this._metricsRegistrar = new metric_registry_1.MetricsRegistrar(this.metricRegistry);
+            this.httpRequestsTotal = this.metricRegistry.createCounter({
+                name: 'http_requests_total',
+                help: 'Total number of HTTP requests.',
+                labelNames: ['method', 'route', 'status_code'],
+            });
+            this.httpRequestsInFlight = this.metricRegistry.createGauge({
+                name: 'http_requests_in_flight',
+                help: 'Number of HTTP requests currently being processed.',
+            });
+            this.httpRequestDuration = this.metricRegistry.createHistogram({
+                name: 'http_request_duration_seconds',
+                help: 'HTTP request duration in seconds.',
+                labelNames: ['method', 'route', 'status_code'],
+            });
+        }
         this.app = (0, express_1.default)();
         this.app.use(express_1.default.json());
         this.rootRouter = express_1.default.Router();
-        this.app.use(this.rootRouter);
+    }
+    /**
+     * Register a {@link HealthCheck} to be evaluated on `GET /health`.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.addHealthCheck(new DatabaseHealthCheck());
+     * ```
+     */
+    addHealthCheck(check) {
+        this.healthService.addHealthCheck(check);
+        return this;
     }
     /**
      * Registers a group of use cases under a named module.
@@ -88,18 +138,49 @@ class ModularApi {
     serve(options) {
         const { port, host = '0.0.0.0' } = options;
         return new Promise((resolve) => {
+            // Logging middleware FIRST — trace_id + structured JSON logs.
+            const excludedLogRoutes = ['/health', this.metricsPath, '/docs', '/docs/'];
+            this.app.use((0, logging_middleware_1.loggingMiddleware)({
+                logLevel: this.logLevel,
+                serviceName: this.title,
+                excludedRoutes: excludedLogRoutes,
+            }));
+            // Metrics middleware — before user middlewares & routes.
+            // Created here so registeredPaths is populated from apiRegistry.
+            if (this.metricsEnabled &&
+                this.httpRequestsTotal &&
+                this.httpRequestsInFlight &&
+                this.httpRequestDuration) {
+                const registeredPaths = registry_1.apiRegistry.routes.map((r) => r.path);
+                this.app.use((0, metrics_middleware_1.metricsMiddleware)({
+                    requestsTotal: this.httpRequestsTotal,
+                    requestsInFlight: this.httpRequestsInFlight,
+                    requestDuration: this.httpRequestDuration,
+                    excludedRoutes: this.excludedMetricsRoutes,
+                    registeredPaths,
+                }));
+            }
             // Register middlewares before routes
             for (const mw of this.middlewares) {
                 this.app.use(mw);
             }
-            // Health endpoint
-            this.app.get('/health', (_req, res) => res.status(200).send('ok'));
+            // Metrics endpoint (before rootRouter — its own handler).
+            if (this.metricsEnabled && this.metricRegistry) {
+                this.app.get(this.metricsPath, (0, metrics_middleware_1.metricsHandler)(this.metricRegistry));
+            }
+            // Health endpoint — IETF Health Check Response Format
+            this.app.get('/health', (0, health_handler_1.healthHandler)(this.healthService));
+            // Module use case routes.
+            this.app.use(this.rootRouter);
             // Swagger / OpenAPI docs
             const spec = (0, openapi_1.buildOpenApiSpec)({ title: this.title, port });
             this.app.use('/docs', swagger_ui_express_1.default.serve, swagger_ui_express_1.default.setup(spec));
             const server = this.app.listen(port, host, () => {
                 console.log(`Docs  → http://localhost:${port}/docs`);
                 console.log(`Health → http://localhost:${port}/health`);
+                if (this.metricsEnabled) {
+                    console.log(`Metrics → http://localhost:${port}${this.metricsPath}`);
+                }
                 resolve(server);
             });
         });

package/dist/core/usecase.d.ts

@@ -1,3 +1,4 @@
+import type { ModularLogger } from './logger/logger';
 /**
  * **Contract** — use `implements Input`.
  *
@@ -94,6 +95,12 @@ export declare abstract class UseCase<I extends Input, O extends Output> {
     abstract readonly input: I;
     /** Output DTO — set in execute(). */
     abstract output: O;
+    /**
+     * Request-scoped logger injected by the framework's logging middleware.
+     * Available inside `execute()`. Undefined when running without middleware
+     * or in tests that don't provide one.
+     */
+    logger?: ModularLogger;
     /**
      * Synchronous validation.
      * Return a human-readable error string to abort execution with HTTP 400.

package/dist/core/usecase_handler.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCaseHandler = useCaseHandler;
 const use_case_exception_1 = require("./use_case_exception");
+const logging_middleware_1 = require("./logger/logging_middleware");
 const JSON_HEADERS = { 'Content-Type': 'application/json; charset=utf-8' };
 /**
  * Wraps any UseCase factory into an Express RequestHandler.
@@ -33,9 +34,14 @@ function useCaseHandler(factory) {
             // 1. Extract payload
             const data = req.method.toUpperCase() === 'GET' || req.method.toUpperCase() === 'DELETE'
                 ? { ...req.query, ...req.params }
-                : req.body ?? {};
+                : (req.body ?? {});
             // 2. Build use case
             const useCase = factory(data);
+            // 2b. Inject request-scoped logger (if logging middleware is active)
+            const logger = res.locals[logging_middleware_1.LOGGER_LOCALS_KEY];
+            if (logger) {
+                useCase.logger = logger;
+            }
             // 3. Validate
             const validationError = useCase.validate();
             if (validationError !== null) {