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

package/lib/cjs/adapter-express/micro-api/service-mesh/service-discovery.js

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceDiscovery = void 0;
+/**
+ * ServiceDiscovery - Service discovery for microservices.
+ *
+ * Features:
+ * - Static service registration
+ * - Consul integration
+ * - etcd integration
+ * - Automatic service refresh
+ * - Round-robin load balancing
+ * - Health-based filtering
+ *
+ * @example
+ * ```typescript
+ * // Static service discovery
+ * const discovery = new ServiceDiscovery({ type: "static" });
+ *
+ * discovery.registerService({
+ *     id: "user-service-1",
+ *     name: "user-service",
+ *     host: "user-service",
+ *     port: 3001,
+ *     health: "healthy",
+ *     lastCheck: new Date(),
+ * });
+ *
+ * // Get a healthy instance
+ * const instance = discovery.getService("user-service");
+ * const client = new ServiceClient({
+ *     name: "user-service",
+ *     baseUrl: `http://${instance.host}:${instance.port}`,
+ * });
+ *
+ * // Or with Consul
+ * const discovery = new ServiceDiscovery({
+ *     type: "consul",
+ *     endpoint: "http://consul:8500",
+ * });
+ * await discovery.initialize();
+ * ```
+ */
+class ServiceDiscovery {
+    constructor(config) {
+        this.services = new Map();
+        this.roundRobinIndex = new Map();
+        this.config = {
+            type: config.type,
+            endpoint: config.endpoint ?? "",
+            refreshInterval: config.refreshInterval ?? 30000,
+            debug: config.debug ?? false,
+        };
+    }
+    /**
+     * Initialize the service discovery
+     * For consul/etcd, this starts the refresh loop
+     */
+    async initialize() {
+        if (this.config.type === "static") {
+            // Static configuration - no auto-discovery
+            return;
+        }
+        // Initial refresh
+        await this.refresh();
+        // Start refresh loop
+        if (this.config.refreshInterval > 0) {
+            this.refreshTimer = setInterval(() => this.refresh(), this.config.refreshInterval);
+        }
+    }
+    /**
+     * Register a service instance (for static mode)
+     * @param service - Service instance to register
+     */
+    registerService(service) {
+        const instances = this.services.get(service.name) || [];
+        // Check if instance already exists
+        const existingIndex = instances.findIndex((i) => i.id === service.id);
+        if (existingIndex >= 0) {
+            instances[existingIndex] = service;
+        }
+        else {
+            instances.push(service);
+        }
+        this.services.set(service.name, instances);
+        if (this.config.debug) {
+            console.log(`[ServiceDiscovery] Registered ${service.name} (${service.id})`);
+        }
+    }
+    /**
+     * Deregister a service instance
+     * @param serviceName - Service name
+     * @param instanceId - Instance ID to remove
+     */
+    deregisterService(serviceName, instanceId) {
+        const instances = this.services.get(serviceName);
+        if (!instances)
+            return;
+        const filtered = instances.filter((i) => i.id !== instanceId);
+        this.services.set(serviceName, filtered);
+        if (this.config.debug) {
+            console.log(`[ServiceDiscovery] Deregistered ${serviceName} (${instanceId})`);
+        }
+    }
+    /**
+     * Get a healthy instance of a service (round-robin)
+     * @param name - Service name
+     * @returns A healthy service instance or null
+     */
+    getService(name) {
+        const instances = this.services.get(name);
+        if (!instances || instances.length === 0) {
+            return null;
+        }
+        // Filter to healthy instances only
+        const healthy = instances.filter((i) => i.health === "healthy");
+        if (healthy.length === 0) {
+            return null;
+        }
+        // Round-robin selection
+        const currentIndex = this.roundRobinIndex.get(name) ?? 0;
+        const instance = healthy[currentIndex % healthy.length];
+        this.roundRobinIndex.set(name, currentIndex + 1);
+        return instance;
+    }
+    /**
+     * Get all instances of a service
+     * @param name - Service name
+     * @param healthyOnly - Only return healthy instances (default: true)
+     */
+    getServiceInstances(name, healthyOnly = true) {
+        const instances = this.services.get(name) || [];
+        if (healthyOnly) {
+            return instances.filter((i) => i.health === "healthy");
+        }
+        return instances;
+    }
+    /**
+     * Get all registered services
+     */
+    getAllServices() {
+        return new Map(this.services);
+    }
+    /**
+     * List all registered service names
+     */
+    listServices() {
+        return Array.from(this.services.keys());
+    }
+    /**
+     * Update health status of a service instance
+     * @param serviceName - Service name
+     * @param instanceId - Instance ID
+     * @param health - New health status
+     */
+    updateHealth(serviceName, instanceId, health) {
+        const instances = this.services.get(serviceName);
+        if (!instances)
+            return false;
+        const instance = instances.find((i) => i.id === instanceId);
+        if (!instance)
+            return false;
+        instance.health = health;
+        instance.lastCheck = new Date();
+        if (this.config.debug) {
+            console.log(`[ServiceDiscovery] Updated ${serviceName} (${instanceId}) health to ${health}`);
+        }
+        return true;
+    }
+    /**
+     * Get service statistics
+     */
+    getStats() {
+        const stats = {};
+        for (const [name, instances] of this.services) {
+            stats[name] = {
+                total: instances.length,
+                healthy: instances.filter((i) => i.health === "healthy").length,
+                unhealthy: instances.filter((i) => i.health === "unhealthy").length,
+            };
+        }
+        return stats;
+    }
+    /**
+     * Stop the service discovery
+     */
+    stop() {
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = undefined;
+        }
+    }
+    /**
+     * Refresh service list from discovery backend
+     */
+    async refresh() {
+        try {
+            if (this.config.type === "consul") {
+                await this.refreshFromConsul();
+            }
+            else if (this.config.type === "etcd") {
+                await this.refreshFromEtcd();
+            }
+        }
+        catch (error) {
+            console.error("[ServiceDiscovery] Refresh failed:", error);
+        }
+    }
+    /**
+     * Refresh from Consul
+     */
+    async refreshFromConsul() {
+        if (!this.config.endpoint) {
+            throw new Error("Consul endpoint not configured");
+        }
+        try {
+            // Get list of services
+            const servicesResponse = await fetch(`${this.config.endpoint}/v1/catalog/services`);
+            const services = await servicesResponse.json();
+            // Get instances for each service
+            for (const serviceName of Object.keys(services)) {
+                const instances = await this.getConsulInstances(serviceName);
+                this.services.set(serviceName, instances);
+            }
+            if (this.config.debug) {
+                console.log(`[ServiceDiscovery] Refreshed ${this.services.size} services from Consul`);
+            }
+        }
+        catch (error) {
+            console.error("[ServiceDiscovery] Consul refresh failed:", error);
+            throw error;
+        }
+    }
+    /**
+     * Get instances from Consul for a specific service
+     */
+    async getConsulInstances(serviceName) {
+        const response = await fetch(`${this.config.endpoint}/v1/health/service/${serviceName}?passing=true`);
+        const data = (await response.json());
+        return data.map((entry) => ({
+            id: entry.Service.ID,
+            name: entry.Service.Service,
+            host: entry.Service.Address || entry.Node.Address,
+            port: entry.Service.Port,
+            metadata: entry.Service.Meta,
+            health: "healthy",
+            lastCheck: new Date(),
+        }));
+    }
+    /**
+     * Refresh from etcd
+     */
+    async refreshFromEtcd() {
+        if (!this.config.endpoint) {
+            throw new Error("etcd endpoint not configured");
+        }
+        // etcd v3 API implementation
+        console.log("[ServiceDiscovery] etcd integration requires etcd3 client library");
+    }
+}
+exports.ServiceDiscovery = ServiceDiscovery;

package/lib/cjs/adapter-express/middleware/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * @file middleware/index.ts
+ * @description Exports for ExpressoTS middleware
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./request-logging.middleware.js"), exports);

package/lib/cjs/adapter-express/middleware/request-logging.middleware.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * @file request-logging.middleware.ts
+ * @description HTTP request/response logging middleware with context enrichment
+ * @module @expressots/adapter-express
+ *
+ * Features:
+ * - Request ID generation/extraction
+ * - Request/response timing
+ * - Slow request detection
+ * - Configurable verbosity levels
+ * - Body logging with redaction support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultRequestLoggingConfig = getDefaultRequestLoggingConfig;
+exports.createRequestLoggingMiddleware = createRequestLoggingMiddleware;
+exports.requestIdMiddleware = requestIdMiddleware;
+const core_1 = require("@expressots/core");
+/**
+ * Default request logging configuration.
+ */
+function getDefaultRequestLoggingConfig() {
+    return {
+        verbosity: "normal",
+        logBody: false,
+        logHeaders: false,
+        logResponseBody: false,
+        slowRequestThreshold: 1000, // 1 second
+        skipPatterns: [/^\/health$/, /^\/ready$/, /^\/live$/, /^\/_health$/],
+        requestIdHeader: "x-request-id",
+        correlationIdHeader: "x-correlation-id",
+        logUserAgent: true,
+        logIp: true,
+    };
+}
+/**
+ * Create request logging middleware.
+ * @param logger - Logger instance to use
+ * @param config - Optional configuration
+ * @returns Express middleware function
+ * @public API
+ */
+function createRequestLoggingMiddleware(logger, config) {
+    const finalConfig = {
+        ...getDefaultRequestLoggingConfig(),
+        ...config,
+    };
+    return (req, res, next) => {
+        // Skip logging for configured patterns
+        if (finalConfig.skipPatterns.some((pattern) => pattern.test(req.path))) {
+            next();
+            return;
+        }
+        // Create HTTP context with custom header names
+        const httpContext = core_1.ContextManager.createHttpContext(req, {
+            requestIdHeader: finalConfig.requestIdHeader,
+            correlationIdHeader: finalConfig.correlationIdHeader,
+        });
+        // Set request/correlation ID headers for downstream services
+        res.setHeader(finalConfig.requestIdHeader, httpContext.requestId);
+        if (httpContext.correlationId) {
+            res.setHeader(finalConfig.correlationIdHeader, httpContext.correlationId);
+        }
+        // Create log context
+        const logContext = {
+            requestId: httpContext.requestId,
+            userId: httpContext.userId,
+            tenantId: httpContext.tenantId,
+            metadata: {
+                method: httpContext.method,
+                path: httpContext.path,
+            },
+        };
+        // Initialize flow tracker (if flow tracking is enabled)
+        const flowConfig = logger.getConfig()?.flow;
+        const flowTracker = (0, core_1.getFlowTracker)(httpContext.requestId, httpContext.method, httpContext.path, flowConfig);
+        // Log request start based on verbosity
+        logRequestStart(logger, httpContext, finalConfig);
+        // Capture response timing
+        const startTime = Date.now();
+        const startMemory = process.memoryUsage().heapUsed;
+        // Store error on request for later retrieval
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        req.__expressotsFlowError = undefined;
+        // Override res.end to capture response
+        const originalEnd = res.end;
+        let endCalled = false;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.end = function (...args) {
+            // Prevent multiple calls
+            if (endCalled) {
+                return originalEnd.apply(this, args);
+            }
+            endCalled = true;
+            const duration = Date.now() - startTime;
+            const memoryDelta = process.memoryUsage().heapUsed - startMemory;
+            // Get error from request if available (set by controllers, guards, or error handlers)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const error = req.__expressotsFlowError;
+            // Finalize flow and get flow data (pass error if available)
+            const flow = flowTracker.finalize(res.statusCode, error);
+            // Log response with flow data
+            logRequestEnd(logger, httpContext, res, duration, memoryDelta, finalConfig, flow);
+            // Cleanup flow tracker
+            (0, core_1.removeFlowTracker)(httpContext.requestId);
+            // Call original end
+            return originalEnd.apply(this, args);
+        };
+        // Wrap next to capture errors passed to next()
+        const wrappedNext = (err) => {
+            if (err) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                req.__expressotsFlowError = err instanceof Error ? err : new Error(String(err));
+            }
+            next(err);
+        };
+        // Also hook into res.status() to capture error status codes
+        // This helps capture errors that Express error handlers set
+        const originalStatus = res.status.bind(res);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        res.status = function (code) {
+            // If status is >= 400 and no error is stored yet, try to get it from Express error handling
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (code >= 400 && !req.__expressotsFlowError) {
+                // Check if there's an error in the response locals (Express error handlers sometimes put it there)
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const errorFromLocals = res.locals?.error;
+                if (errorFromLocals) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    req.__expressotsFlowError =
+                        errorFromLocals instanceof Error ? errorFromLocals : new Error(String(errorFromLocals));
+                }
+            }
+            return originalStatus(code);
+        };
+        // Run the rest of the middleware chain with context
+        core_1.ContextManager.runWithContext(logContext, () => {
+            wrappedNext();
+        });
+    };
+}
+/**
+ * Log request start.
+ */
+function logRequestStart(logger, context, config) {
+    const { verbosity, logHeaders, logUserAgent, logIp } = config;
+    if (verbosity === "minimal") {
+        // Minimal: Just log that request started
+        logger.debug(`→ ${context.method} ${context.path}`, { requestId: context.requestId });
+        return;
+    }
+    // Build log data based on verbosity
+    const logData = {
+        requestId: context.requestId,
+    };
+    if (logIp && context.ip) {
+        logData.ip = context.ip;
+    }
+    if (logUserAgent && context.userAgent) {
+        logData.userAgent =
+            context.userAgent.length > 50
+                ? context.userAgent.substring(0, 50) + "..."
+                : context.userAgent;
+    }
+    if (context.userId) {
+        logData.userId = context.userId;
+    }
+    if (context.tenantId) {
+        logData.tenantId = context.tenantId;
+    }
+    if (verbosity === "detailed" || verbosity === "debug") {
+        if (logHeaders && context.headers) {
+            logData.headers = context.headers;
+        }
+    }
+    logger.info(`→ ${context.method} ${context.path}`, "request", logData);
+}
+/**
+ * Log request end.
+ */
+function logRequestEnd(logger, context, res, duration, memoryDelta, config, flow) {
+    const { verbosity, slowRequestThreshold } = config;
+    const statusCode = res.statusCode;
+    // Determine log level based on status and duration
+    const isSlowRequest = duration >= slowRequestThreshold;
+    const isError = statusCode >= 400;
+    // Build log data
+    const logData = {
+        requestId: context.requestId,
+        status: statusCode,
+        duration: `${duration}ms`,
+    };
+    if (verbosity === "detailed" || verbosity === "debug") {
+        logData.memoryDelta = `${(memoryDelta / 1024).toFixed(1)}KB`;
+    }
+    if (context.userId) {
+        logData.userId = context.userId;
+    }
+    // Format message
+    const statusEmoji = isError ? "✗" : "✓";
+    const message = `← ${context.method} ${context.path} ${statusCode} ${statusEmoji} ${duration}ms`;
+    // Log with appropriate level and include flow data if available
+    if (isError && statusCode >= 500) {
+        logger.error(message, "request", { ...logData, flow });
+    }
+    else if (isError) {
+        logger.warn(message, "request", { ...logData, flow });
+    }
+    else if (isSlowRequest) {
+        logger.warn(`[SLOW] ${message}`, "request", {
+            ...logData,
+            slowRequestThreshold: `${slowRequestThreshold}ms`,
+            flow,
+        });
+    }
+    else if (verbosity !== "minimal") {
+        logger.info(message, "request", { ...logData, flow });
+    }
+    else {
+        // debug only takes 2 args: message and data
+        logger.debug(`[request] ${message}`, { ...logData, flow });
+    }
+}
+/**
+ * Express middleware that assigns a request ID to each request.
+ * Simpler alternative to full request logging.
+ * @param headerName - Header name for request ID (default: x-request-id)
+ * @returns Express middleware
+ * @public API
+ */
+function requestIdMiddleware(headerName = "x-request-id") {
+    return (req, res, next) => {
+        const existingId = req.headers[headerName.toLowerCase()];
+        const requestId = existingId || core_1.ContextManager.generateRequestId();
+        // Set on request for access by other middleware
+        req.requestId = requestId;
+        // Set on response header
+        res.setHeader(headerName, requestId);
+        // Run with context
+        core_1.ContextManager.runWithContext({ requestId }, () => {
+            next();
+        });
+    };
+}

package/lib/cjs/adapter-express/render/engine.js

@@ -4,17 +4,17 @@ exports.setEngineEjs = setEngineEjs;
 exports.setEngineHandlebars = setEngineHandlebars;
 exports.setEnginePug = setEnginePug;
 const core_1 = require("@expressots/core");
-const resolve_render_1 = require("./resolve-render");
-const constants_1 = require("./constants");
+const resolve_render_js_1 = require("./resolve-render.js");
+const constants_js_1 = require("./constants.js");
 /**
  * Set Ejs as the view engine
  * @param {Application} app - The express application
  * @param {EjsOptions} [options=EJS_DEFAULTS] - The ejs options
  */
-async function setEngineEjs(app, options = constants_1.EJS_DEFAULTS) {
-    (0, resolve_render_1.packageResolver)("ejs");
-    app.set("view engine", options.viewEngine || constants_1.EJS_DEFAULTS.viewEngine);
-    app.set("views", options.viewsDir || constants_1.EJS_DEFAULTS.viewsDir);
+async function setEngineEjs(app, options = constants_js_1.EJS_DEFAULTS) {
+    (0, resolve_render_js_1.packageResolver)("ejs");
+    app.set("view engine", options.viewEngine || constants_js_1.EJS_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || constants_js_1.EJS_DEFAULTS.viewsDir);
     if (Array.isArray(options.viewsDir)) {
         options.viewsDir.forEach((dir) => {
             app.set("views", dir);
@@ -32,13 +32,13 @@ async function setEngineEjs(app, options = constants_1.EJS_DEFAULTS) {
  * @param {express.Application} app - The express application
  * @param {HandlebarsOptions} [options=HANDLEBARS_DEFAULTS] - The handlebars options
  */
-async function setEngineHandlebars(app, options = constants_1.HANDLEBARS_DEFAULTS) {
+async function setEngineHandlebars(app, options = constants_js_1.HANDLEBARS_DEFAULTS) {
     const logger = new core_1.Logger();
     try {
-        const hbs = (0, resolve_render_1.packageResolver)("hbs");
-        hbs.registerPartials(options.partialsDir || constants_1.DEFAULT_PARTIALS_DIR);
-        app.set("view engine", options.viewEngine || constants_1.HANDLEBARS_DEFAULTS.viewEngine);
-        app.set("views", options.viewsDir || constants_1.HANDLEBARS_DEFAULTS.viewsDir);
+        const hbs = (0, resolve_render_js_1.packageResolver)("hbs");
+        hbs.registerPartials(options.partialsDir || constants_js_1.DEFAULT_PARTIALS_DIR);
+        app.set("view engine", options.viewEngine || constants_js_1.HANDLEBARS_DEFAULTS.viewEngine);
+        app.set("views", options.viewsDir || constants_js_1.HANDLEBARS_DEFAULTS.viewsDir);
     }
     catch (error) {
         logger.error(error.message, "handlebars-config");
@@ -49,8 +49,8 @@ async function setEngineHandlebars(app, options = constants_1.HANDLEBARS_DEFAULT
  * @param {express.Application} app - The express application
  * @param {PugOptions} [options=PUG_DEFAULTS] - The pug options
  */
-async function setEnginePug(app, options = constants_1.PUG_DEFAULTS) {
-    (0, resolve_render_1.packageResolver)("pug");
-    app.set("view engine", options.viewEngine || constants_1.PUG_DEFAULTS.viewEngine);
-    app.set("views", options.viewsDir || constants_1.PUG_DEFAULTS.viewsDir);
+async function setEnginePug(app, options = constants_js_1.PUG_DEFAULTS) {
+    (0, resolve_render_js_1.packageResolver)("pug");
+    app.set("view engine", options.viewEngine || constants_js_1.PUG_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || constants_js_1.PUG_DEFAULTS.viewsDir);
 }

package/lib/cjs/adapter-express/render/index.js

@@ -1,2 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setEnginePug = exports.setEngineHandlebars = exports.setEngineEjs = void 0;
+var engine_js_1 = require("./engine.js");
+Object.defineProperty(exports, "setEngineEjs", { enumerable: true, get: function () { return engine_js_1.setEngineEjs; } });
+Object.defineProperty(exports, "setEngineHandlebars", { enumerable: true, get: function () { return engine_js_1.setEngineHandlebars; } });
+Object.defineProperty(exports, "setEnginePug", { enumerable: true, get: function () { return engine_js_1.setEnginePug; } });

package/lib/cjs/adapter-express/studio/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rescanStudioRoutes = exports.reportStudioRuntimeInfo = exports.getStudioAgent = exports.isStudioEnabled = exports.stopStudio = exports.initializeStudio = void 0;
+var studio_integration_js_1 = require("./studio-integration.js");
+Object.defineProperty(exports, "initializeStudio", { enumerable: true, get: function () { return studio_integration_js_1.initializeStudio; } });
+Object.defineProperty(exports, "stopStudio", { enumerable: true, get: function () { return studio_integration_js_1.stopStudio; } });
+Object.defineProperty(exports, "isStudioEnabled", { enumerable: true, get: function () { return studio_integration_js_1.isStudioEnabled; } });
+Object.defineProperty(exports, "getStudioAgent", { enumerable: true, get: function () { return studio_integration_js_1.getStudioAgent; } });
+Object.defineProperty(exports, "reportStudioRuntimeInfo", { enumerable: true, get: function () { return studio_integration_js_1.reportStudioRuntimeInfo; } });
+Object.defineProperty(exports, "rescanStudioRoutes", { enumerable: true, get: function () { return studio_integration_js_1.rescanStudioRoutes; } });