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

package/lib/cjs/adapter-express/micro-api/gateway/circuit-breaker.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = void 0;
+/**
+ * CircuitBreaker - Protect against cascading failures in distributed systems.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Requests fail immediately without calling the service
+ * - HALF_OPEN: Limited requests pass through to test if service recovered
+ *
+ * @example
+ * ```typescript
+ * const circuitBreaker = new CircuitBreaker({
+ *     failureThreshold: 5,
+ *     timeout: 60000,
+ * });
+ *
+ * app.Route.get("/external-api", async (req, res) => {
+ *     try {
+ *         const result = await circuitBreaker.execute(async () => {
+ *             return await fetch("https://external-api.com/data");
+ *         });
+ *         res.json(await result.json());
+ *     } catch (error) {
+ *         if (error.message === "Circuit breaker is OPEN") {
+ *             res.status(503).json({ error: "Service temporarily unavailable" });
+ *         } else {
+ *             res.status(500).json({ error: error.message });
+ *         }
+ *     }
+ * });
+ * ```
+ */
+class CircuitBreaker {
+    constructor(config) {
+        this.state = "CLOSED";
+        this.failures = 0;
+        this.successes = 0;
+        this.totalSuccesses = 0;
+        this.totalCalls = 0;
+        this.recentFailures = [];
+        this.config = {
+            failureThreshold: config?.failureThreshold ?? 5,
+            successThreshold: config?.successThreshold ?? 2,
+            timeout: config?.timeout ?? 60000,
+            monitoringPeriod: config?.monitoringPeriod ?? 10000,
+        };
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     * @param fn - Function to execute
+     * @throws Error if circuit is open
+     */
+    async execute(fn) {
+        this.totalCalls++;
+        // Check if circuit is open
+        if (this.state === "OPEN") {
+            // Check if timeout has passed
+            if (this.shouldAttemptReset()) {
+                this.state = "HALF_OPEN";
+                this.successes = 0;
+            }
+            else {
+                throw new Error("Circuit breaker is OPEN");
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats() {
+        return {
+            state: this.state,
+            failures: this.failures,
+            successes: this.totalSuccesses,
+            totalCalls: this.totalCalls,
+            lastFailure: this.lastFailure,
+            lastSuccess: this.lastSuccess,
+            openedAt: this.openedAt,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker
+     */
+    reset() {
+        this.state = "CLOSED";
+        this.failures = 0;
+        this.successes = 0;
+        this.totalSuccesses = 0;
+        this.recentFailures = [];
+        this.openedAt = undefined;
+    }
+    /**
+     * Manually open the circuit
+     */
+    open() {
+        this.state = "OPEN";
+        this.openedAt = new Date();
+    }
+    /**
+     * Handle successful call
+     */
+    onSuccess() {
+        this.totalSuccesses++;
+        this.lastSuccess = new Date();
+        if (this.state === "HALF_OPEN") {
+            this.successes++;
+            if (this.successes >= this.config.successThreshold) {
+                this.state = "CLOSED";
+                this.failures = 0;
+                this.recentFailures = [];
+                this.openedAt = undefined;
+            }
+        }
+        else if (this.state === "CLOSED") {
+            // Clear old failures outside monitoring period
+            this.cleanupRecentFailures();
+        }
+    }
+    /**
+     * Handle failed call
+     */
+    onFailure() {
+        this.failures++;
+        this.lastFailure = new Date();
+        this.recentFailures.push(this.lastFailure);
+        if (this.state === "HALF_OPEN") {
+            // Any failure in half-open state reopens the circuit
+            this.state = "OPEN";
+            this.openedAt = new Date();
+            this.successes = 0;
+        }
+        else if (this.state === "CLOSED") {
+            this.cleanupRecentFailures();
+            // Check if we've hit the failure threshold
+            if (this.recentFailures.length >= this.config.failureThreshold) {
+                this.state = "OPEN";
+                this.openedAt = new Date();
+            }
+        }
+    }
+    /**
+     * Check if timeout has passed and we should try to reset
+     */
+    shouldAttemptReset() {
+        if (!this.openedAt)
+            return true;
+        return Date.now() - this.openedAt.getTime() >= this.config.timeout;
+    }
+    /**
+     * Remove failures outside the monitoring period
+     */
+    cleanupRecentFailures() {
+        const cutoff = Date.now() - this.config.monitoringPeriod;
+        this.recentFailures = this.recentFailures.filter((date) => date.getTime() > cutoff);
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;

package/lib/cjs/adapter-express/micro-api/gateway/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * API Gateway Utilities for ExpressoTS Micro Template
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProxy = exports.ServiceProxy = exports.CircuitBreaker = void 0;
+var circuit_breaker_js_1 = require("./circuit-breaker.js");
+Object.defineProperty(exports, "CircuitBreaker", { enumerable: true, get: function () { return circuit_breaker_js_1.CircuitBreaker; } });
+var service_proxy_js_1 = require("./service-proxy.js");
+Object.defineProperty(exports, "ServiceProxy", { enumerable: true, get: function () { return service_proxy_js_1.ServiceProxy; } });
+Object.defineProperty(exports, "createProxy", { enumerable: true, get: function () { return service_proxy_js_1.createProxy; } });

package/lib/cjs/adapter-express/micro-api/gateway/service-proxy.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceProxy = void 0;
+exports.createProxy = createProxy;
+const circuit_breaker_js_1 = require("./circuit-breaker.js");
+/**
+ * ServiceProxy - Proxy requests to other microservices.
+ *
+ * Features:
+ * - Automatic request forwarding
+ * - Path rewriting
+ * - Custom headers
+ * - Request timeout
+ * - Retry support
+ * - Optional circuit breaker integration
+ *
+ * @example
+ * ```typescript
+ * // Proxy to user service
+ * const userProxy = createProxy({
+ *     target: "http://user-service:3001",
+ *     pathRewrite: (path) => path.replace("/api/users", ""),
+ *     timeout: 5000,
+ *     retries: 3,
+ *     circuitBreaker: true,
+ * });
+ *
+ * app.Route.get("/api/users/*", userProxy.handler());
+ * app.Route.post("/api/users/*", userProxy.handler());
+ * ```
+ */
+class ServiceProxy {
+    constructor(config) {
+        this.config = {
+            target: config.target,
+            timeout: config.timeout ?? 30000,
+            retries: config.retries ?? 0,
+            headers: config.headers ?? {},
+            pathRewrite: config.pathRewrite ?? ((path) => path),
+            debug: config.debug ?? false,
+        };
+        // Initialize circuit breaker if enabled
+        if (config.circuitBreaker) {
+            const cbConfig = typeof config.circuitBreaker === "object" ? config.circuitBreaker : undefined;
+            this.config.circuitBreaker = new circuit_breaker_js_1.CircuitBreaker(cbConfig);
+        }
+    }
+    /**
+     * Create an Express handler for proxying requests
+     */
+    handler() {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        return async (req, res, _next) => {
+            try {
+                const result = await this.proxyRequest(req);
+                // Copy status and headers
+                res.status(result.status);
+                result.headers.forEach((value, key) => {
+                    // Skip certain headers
+                    if (!["content-encoding", "transfer-encoding"].includes(key.toLowerCase())) {
+                        res.setHeader(key, value);
+                    }
+                });
+                // Send body
+                const body = await result.text();
+                res.send(body);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                if (this.config.debug) {
+                    console.error(`[Proxy] Error:`, errorMessage);
+                }
+                if (errorMessage === "Circuit breaker is OPEN") {
+                    res.status(503).json({
+                        error: "Service temporarily unavailable",
+                        service: this.config.target,
+                    });
+                }
+                else if (error instanceof Error && error.name === "AbortError") {
+                    res.status(504).json({
+                        error: "Gateway timeout",
+                        service: this.config.target,
+                    });
+                }
+                else {
+                    res.status(502).json({
+                        error: "Bad gateway",
+                        message: errorMessage,
+                        service: this.config.target,
+                    });
+                }
+            }
+        };
+    }
+    /**
+     * Proxy a request to the target service
+     */
+    async proxyRequest(req) {
+        const execute = async () => {
+            return await this.executeWithRetry(req);
+        };
+        if (this.config.circuitBreaker) {
+            return await this.config.circuitBreaker.execute(execute);
+        }
+        return await execute();
+    }
+    /**
+     * Execute request with retry logic
+     */
+    async executeWithRetry(req, attempt = 0) {
+        try {
+            return await this.executeRequest(req);
+        }
+        catch (error) {
+            if (attempt < this.config.retries) {
+                // Exponential backoff
+                await this.delay(Math.pow(2, attempt) * 100);
+                return await this.executeWithRetry(req, attempt + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Execute a single request
+     */
+    async executeRequest(req) {
+        // Rewrite path if configured
+        const path = this.config.pathRewrite(req.path);
+        const url = new URL(path, this.config.target);
+        // Copy query parameters
+        Object.entries(req.query).forEach(([key, value]) => {
+            if (typeof value === "string") {
+                url.searchParams.append(key, value);
+            }
+        });
+        // Build headers
+        const headers = {
+            ...this.extractHeaders(req),
+            ...this.config.headers,
+        };
+        // Build request options
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        const requestInit = {
+            method: req.method,
+            headers,
+            signal: controller.signal,
+        };
+        // Add body for non-GET requests
+        if (req.method !== "GET" && req.method !== "HEAD" && req.body) {
+            requestInit.body = JSON.stringify(req.body);
+            headers["content-type"] = "application/json";
+        }
+        if (this.config.debug) {
+            console.log(`[Proxy] ${req.method} ${url.toString()}`);
+        }
+        try {
+            const response = await fetch(url.toString(), requestInit);
+            clearTimeout(timeoutId);
+            // Cast to ProxyResponse to avoid conflict with Express Response type
+            return response;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            throw error;
+        }
+    }
+    /**
+     * Extract relevant headers from incoming request
+     */
+    extractHeaders(req) {
+        const headers = {};
+        const forwardHeaders = [
+            "authorization",
+            "content-type",
+            "accept",
+            "user-agent",
+            "x-request-id",
+            "x-trace-id",
+            "x-span-id",
+            "x-correlation-id",
+        ];
+        forwardHeaders.forEach((header) => {
+            const value = req.headers[header];
+            if (typeof value === "string") {
+                headers[header] = value;
+            }
+        });
+        // Add X-Forwarded headers
+        headers["x-forwarded-for"] = req.ip || req.socket.remoteAddress || "unknown";
+        headers["x-forwarded-host"] = req.headers.host || "";
+        headers["x-forwarded-proto"] = req.protocol;
+        return headers;
+    }
+    /**
+     * Delay helper
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get circuit breaker stats (if enabled)
+     */
+    getCircuitBreakerStats() {
+        return this.config.circuitBreaker?.getStats();
+    }
+}
+exports.ServiceProxy = ServiceProxy;
+/**
+ * Create a new service proxy
+ */
+function createProxy(config) {
+    return new ServiceProxy(config);
+}

package/lib/cjs/adapter-express/micro-api/index.js

@@ -1,5 +1,29 @@
 "use strict";
+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 });
-exports.createMicroAPI = void 0;
-var application_express_micro_1 = require("./application-express-micro");
-Object.defineProperty(exports, "createMicroAPI", { enumerable: true, get: function () { return application_express_micro_1.createMicroAPI; } });
+exports.createMicroAPI = exports.micro = void 0;
+// Primary API - pure simplicity
+var micro_js_1 = require("./micro.js");
+Object.defineProperty(exports, "micro", { enumerable: true, get: function () { return micro_js_1.micro; } });
+// Advanced features - import separately when needed
+__exportStar(require("./gateway/index.js"), exports); // CircuitBreaker, ServiceProxy
+__exportStar(require("./service-mesh/index.js"), exports); // ServiceDiscovery, ServiceClient
+__exportStar(require("./serverless/index.js"), exports); // Lambda, Cloudflare, Vercel adapters
+__exportStar(require("./queue/index.js"), exports); // RabbitMQ consumer
+// Legacy API - deprecated, will be removed in v6
+/** @deprecated Use micro() instead */
+var application_express_micro_js_1 = require("./application-express-micro.js");
+Object.defineProperty(exports, "createMicroAPI", { enumerable: true, get: function () { return application_express_micro_js_1.createMicroAPI; } });

package/lib/cjs/adapter-express/micro-api/micro.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.micro = micro;
+const core_1 = require("@expressots/core");
+const express_1 = __importDefault(require("express"));
+const application_express_js_1 = require("../application-express.js");
+/**
+ * Create a new micro API instance
+ *
+ * @example
+ * ```typescript
+ * const app = micro();
+ * app.get("/", () => "Hello World");
+ * app.listen(3000);
+ * ```
+ *
+ * @param config - Optional configuration
+ * @returns MicroApp instance
+ * @public API
+ */
+function micro(config) {
+    // Disable the log buffering from AppExpress since micro() doesn't use the banner system
+    // This restores normal console output for micro API users
+    application_express_js_1.AppExpress.disableBuffering();
+    const app = (0, express_1.default)();
+    const logger = new core_1.Logger();
+    const console = new core_1.Console();
+    const globalPrefix = config?.globalPrefix?.replace(/\/$/, "") || "";
+    let httpServer;
+    let errorHandler = null;
+    // Auto-enable JSON parsing by default
+    if (config?.autoParseJson !== false) {
+        app.use(express_1.default.json());
+        app.use(express_1.default.urlencoded({ extended: true }));
+    }
+    /**
+     * Wrap handler to auto-send return values
+     */
+    const wrapHandler = (handler) => {
+        return async (req, res, next) => {
+            try {
+                const result = await handler(req, res, next);
+                // If response already sent, don't send again
+                if (res.headersSent) {
+                    return;
+                }
+                // Auto-send return values
+                if (result !== undefined) {
+                    if (typeof result === "string") {
+                        res.send(result);
+                    }
+                    else {
+                        res.json(result);
+                    }
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    };
+    /**
+     * Register a route with Express-style middleware ordering
+     */
+    const route = (method, path, ...handlers) => {
+        const fullPath = `${globalPrefix}${path.startsWith("/") ? path : `/${path}`}`;
+        const handler = handlers.pop();
+        const middleware = handlers;
+        app[method](fullPath, ...middleware, wrapHandler(handler));
+        logger.info(`Route ${method.toUpperCase()} '${fullPath}' registered`, "micro");
+        // Register in the suggestions engine so 404s can produce "Did you mean ...?"
+        try {
+            (0, core_1.getRouteRegistry)().register(method.toUpperCase(), fullPath, fullPath);
+        }
+        catch {
+            // Suggestions registry is optional; never fail registration because of it.
+        }
+        return microApp;
+    };
+    /**
+     * Install a catch-all 404 fallback that mirrors the behavior of the full
+     * inversify-express-server: log "Did you mean ...?" via the framework Logger
+     * and respond with a structured RFC-7807-style JSON body.
+     *
+     * Skipped entirely when the suggestion engine is disabled (the env-aware
+     * default disables it in NODE_ENV=production).
+     */
+    const installNotFoundHandler = () => {
+        app.use((req, res, next) => {
+            if (res.headersSent) {
+                return next();
+            }
+            const suggestionsConfig = (0, core_1.getDefaultSuggestionsConfig)();
+            if (!suggestionsConfig.enabled) {
+                return next();
+            }
+            const requestedPath = req.originalUrl || req.url;
+            const requestedMethod = req.method;
+            const hints = (0, core_1.getErrorHints)(new Error(`Route '${requestedMethod} ${requestedPath}' not found`), {
+                path: requestedPath,
+                method: requestedMethod,
+                statusCode: 404,
+            }, suggestionsConfig);
+            if (hints.length > 0) {
+                try {
+                    const formatted = (0, core_1.formatSuggestions)(hints);
+                    if (formatted) {
+                        logger.warn(`Route not found: ${requestedMethod} ${requestedPath}${formatted}`, "router-404");
+                    }
+                }
+                catch {
+                    // best-effort logging
+                }
+            }
+            const routeSuggestion = hints.find((hint) => hint.type === "route");
+            const actionHint = hints.find((hint) => hint.type === "hint");
+            const body = {
+                type: "https://expressots.dev/errors/not-found",
+                title: "Route Not Found",
+                status: 404,
+                detail: `Route '${requestedMethod} ${requestedPath}' does not exist`,
+                instance: requestedPath,
+                timestamp: new Date().toISOString(),
+            };
+            if (routeSuggestion?.routes && routeSuggestion.routes.length > 0) {
+                body.suggestions = routeSuggestion.routes.map((suggestion) => ({
+                    method: suggestion.route.method,
+                    path: suggestion.route.fullPath || suggestion.route.path,
+                    similarity: Math.round(suggestion.similarity * 100),
+                    reason: suggestion.reason,
+                }));
+            }
+            else if (actionHint?.actions && actionHint.actions.length > 0) {
+                body.actions = actionHint.actions;
+            }
+            res.status(404).type("application/json").send(JSON.stringify(body));
+        });
+    };
+    /**
+     * Handle server shutdown gracefully
+     */
+    const handleExit = () => {
+        logger.info("Server shutting down", "micro");
+        process.exit(0);
+    };
+    const microApp = {
+        get: (path, ...handlers) => route("get", path, ...handlers),
+        post: (path, ...handlers) => route("post", path, ...handlers),
+        put: (path, ...handlers) => route("put", path, ...handlers),
+        patch: (path, ...handlers) => route("patch", path, ...handlers),
+        delete: (path, ...handlers) => route("delete", path, ...handlers),
+        use(...args) {
+            if (typeof args[0] === "string") {
+                app.use(args[0], ...args.slice(1));
+            }
+            else {
+                app.use(...args);
+            }
+            return microApp;
+        },
+        setErrorHandler(handler) {
+            errorHandler = handler;
+            return microApp;
+        },
+        async listen(port, appInfo) {
+            const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
+            // Install the 404 fallback before the user error handler so unmatched
+            // routes get suggestions instead of falling through to the default
+            // Express HTML or - worse - to a regular middleware that arity-confused
+            // its way into running on every request.
+            installNotFoundHandler();
+            // Apply error handler last. Wrap it in a 4-arity function so that
+            // Express recognizes it as an error-handling middleware regardless of
+            // whether the user wrote `(err, req, res)` or `(err, req, res, next)`.
+            // Without this wrapper, Express would treat a 3-arg user handler as a
+            // regular middleware and run it on every request, which both swallows
+            // 404s and crashes when the user calls `res.status(...)` (positional
+            // `res` would actually be Express's `next`).
+            if (errorHandler) {
+                const userHandler = errorHandler;
+                const wrappedErrorHandler = (err, req, res, next) => userHandler(err, req, res, next);
+                app.use(wrappedErrorHandler);
+            }
+            return new Promise((resolve, reject) => {
+                httpServer = app.listen(normalizedPort, async () => {
+                    const address = httpServer.address();
+                    const actualPort = typeof address === "object" && address?.port ? address.port : normalizedPort;
+                    if (config?.showBanner !== false) {
+                        await console.messageServer(actualPort, "development", {
+                            appName: appInfo?.appName || "ExpressoTS Micro",
+                            appVersion: appInfo?.appVersion || "1.0.0",
+                        });
+                    }
+                    // Handle graceful shutdown
+                    ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
+                        process.on(signal, handleExit);
+                    });
+                    resolve();
+                });
+                httpServer.on("error", (error) => {
+                    logger.error(`Server error: ${error.message}`, "micro");
+                    reject(error);
+                });
+            });
+        },
+        getHttpServer() {
+            return httpServer;
+        },
+        getApp() {
+            return app;
+        },
+    };
+    return microApp;
+}

package/lib/cjs/adapter-express/micro-api/queue/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Queue Integration for ExpressoTS Micro Template
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RabbitMQConsumer = void 0;
+var rabbitmq_consumer_js_1 = require("./rabbitmq-consumer.js");
+Object.defineProperty(exports, "RabbitMQConsumer", { enumerable: true, get: function () { return rabbitmq_consumer_js_1.RabbitMQConsumer; } });

package/lib/cjs/adapter-express/micro-api/queue/queue.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });