@expressots/adapter-express 3.0.0-beta.4.2 → 4.0.0-preview.1

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

@@ -0,0 +1,259 @@
+/**
+ * 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();
+ * ```
+ */
+export class ServiceDiscovery {
+    services = new Map();
+    roundRobinIndex = new Map();
+    refreshTimer;
+    config;
+    constructor(config) {
+        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");
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * @file middleware/index.ts
+ * @description Exports for ExpressoTS middleware
+ */
+export * from "./request-logging.middleware.js";

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

@@ -0,0 +1,239 @@
+/**
+ * @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
+ */
+import { ContextManager, getFlowTracker, removeFlowTracker, } from "@expressots/core";
+/**
+ * Default request logging configuration.
+ */
+export 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
+ */
+export 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 = 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 = 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
+            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
+        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
+ */
+export function requestIdMiddleware(headerName = "x-request-id") {
+    return (req, res, next) => {
+        const existingId = req.headers[headerName.toLowerCase()];
+        const requestId = existingId || ContextManager.generateRequestId();
+        // Set on request for access by other middleware
+        req.requestId = requestId;
+        // Set on response header
+        res.setHeader(headerName, requestId);
+        // Run with context
+        ContextManager.runWithContext({ requestId }, () => {
+            next();
+        });
+    };
+}

package/lib/esm/adapter-express/render/constants.js

@@ -0,0 +1,37 @@
+import { join } from "path";
+/**
+ * Ejs defaults
+ * @type {EjsOptions}
+ * @constant
+ * @default
+ */
+export const EJS_DEFAULTS = {
+    viewsDir: join(process.cwd(), "views"),
+    viewEngine: "ejs",
+    serverOptions: {},
+};
+/**
+ * Handlebars defaults
+ * @type {HandlebarsOptions}
+ * @constant
+ * @default
+ */
+export const HANDLEBARS_DEFAULTS = {
+    viewEngine: "hbs",
+    viewsDir: join(process.cwd(), "views"),
+    partialsDir: join(process.cwd(), "views/partials"),
+};
+/**
+ * Default partials directory
+ */
+export const DEFAULT_PARTIALS_DIR = join(process.cwd(), "views/partials");
+/**
+ * Pug defaults
+ * @type {PugOptions}
+ * @constant
+ * @default
+ */
+export const PUG_DEFAULTS = {
+    viewEngine: "pug",
+    viewsDir: join(process.cwd(), "views"),
+};

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

@@ -0,0 +1,51 @@
+import { Logger } from "@expressots/core";
+import { packageResolver } from "./resolve-render.js";
+import { DEFAULT_PARTIALS_DIR, EJS_DEFAULTS, HANDLEBARS_DEFAULTS, PUG_DEFAULTS, } from "./constants.js";
+/**
+ * Set Ejs as the view engine
+ * @param {Application} app - The express application
+ * @param {EjsOptions} [options=EJS_DEFAULTS] - The ejs options
+ */
+export async function setEngineEjs(app, options = EJS_DEFAULTS) {
+    packageResolver("ejs");
+    app.set("view engine", options.viewEngine || EJS_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || EJS_DEFAULTS.viewsDir);
+    if (Array.isArray(options.viewsDir)) {
+        options.viewsDir.forEach((dir) => {
+            app.set("views", dir);
+        });
+    }
+    if (options.serverOptions) {
+        app.locals = {
+            ...app.locals,
+            ...options.serverOptions,
+        };
+    }
+}
+/**
+ * Set Handlebars as the view engine
+ * @param {express.Application} app - The express application
+ * @param {HandlebarsOptions} [options=HANDLEBARS_DEFAULTS] - The handlebars options
+ */
+export async function setEngineHandlebars(app, options = HANDLEBARS_DEFAULTS) {
+    const logger = new Logger();
+    try {
+        const hbs = packageResolver("hbs");
+        hbs.registerPartials(options.partialsDir || DEFAULT_PARTIALS_DIR);
+        app.set("view engine", options.viewEngine || HANDLEBARS_DEFAULTS.viewEngine);
+        app.set("views", options.viewsDir || HANDLEBARS_DEFAULTS.viewsDir);
+    }
+    catch (error) {
+        logger.error(error.message, "handlebars-config");
+    }
+}
+/**
+ * Set Pug as the view engine
+ * @param {express.Application} app - The express application
+ * @param {PugOptions} [options=PUG_DEFAULTS] - The pug options
+ */
+export async function setEnginePug(app, options = PUG_DEFAULTS) {
+    packageResolver("pug");
+    app.set("view engine", options.viewEngine || PUG_DEFAULTS.viewEngine);
+    app.set("views", options.viewsDir || PUG_DEFAULTS.viewsDir);
+}

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

@@ -0,0 +1 @@
+export { setEngineEjs, setEngineHandlebars, setEnginePug } from "./engine.js";

package/lib/esm/adapter-express/render/resolve-render.js

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Logger } from "@expressots/core";
+/**
+ * Resolve package from the current working directory.
+ * @param packageName
+ * @param options
+ * @returns
+ */
+export function packageResolver(packageName, ...options) {
+    const logger = new Logger();
+    try {
+        const hasPackage = require.resolve(packageName, {
+            paths: [process.cwd()],
+        });
+        if (hasPackage) {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const packageResolved = require(hasPackage);
+            if (typeof packageResolved === "function") {
+                return packageResolved(...options);
+            }
+            if (packageResolved.default && typeof packageResolved.default === "function") {
+                return packageResolved.default(...options);
+            }
+            return packageResolved;
+        }
+    }
+    catch (error) {
+        logger.warn(`Package [${packageName}] not installed. Please install it using your package manager.`, "package-resolver");
+    }
+}

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

@@ -0,0 +1 @@
+export { initializeStudio, stopStudio, isStudioEnabled, getStudioAgent, reportStudioRuntimeInfo, } from "./studio-integration.js";