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

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

@@ -0,0 +1,161 @@
+import { Console, Logger, Middleware } from "@expressots/core";
+import express from "express";
+import { IOC } from "./application-express-micro-container.js";
+import { Route } from "./application-express-micro-route.js";
+class AppExpressMicro {
+    logger = new Logger();
+    app;
+    httpServer;
+    port;
+    environment;
+    container;
+    globalPrefix = "/";
+    middlewareManager;
+    routeManager;
+    /**
+     * Handle the exit of the server
+     * @private
+     */
+    handleExit() {
+        this.logger.info("Server shutting down.", "MicroAPI");
+        process.exit(0);
+    }
+    /**
+     * Configure the middleware for the application
+     * @private
+     */
+    configureMiddleware() {
+        const sortedMiddlewarePipeline = this.middlewareManager.getMiddlewarePipeline();
+        const pipeline = sortedMiddlewarePipeline.map((entry) => entry.middleware);
+        for (const entry of pipeline) {
+            if (typeof entry === "function") {
+                this.app.use(entry);
+            }
+            else if (entry.middlewares) {
+                const { path, middlewares } = entry;
+                for (const mid of middlewares) {
+                    if (path) {
+                        this.app.use(path, mid);
+                    }
+                    else {
+                        this.app.use(mid);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Set the global route prefix
+     * @param prefix - The global route prefix
+     * @public API
+     */
+    setGlobalRoutePrefix(prefix) {
+        this.globalPrefix = prefix;
+    }
+    /**
+     * Get the Middleware instance
+     * @returns IMiddleware
+     * @public API
+     */
+    get Middleware() {
+        return this.middlewareManager;
+    }
+    /**
+     * Get the Route instance
+     * @returns IRoute
+     * @public API
+     */
+    get Route() {
+        return this.routeManager;
+    }
+    /**
+     * Get the Container instance
+     * @returns IIOC
+     * @public API
+     */
+    get Container() {
+        return this.container;
+    }
+    /**
+     * Get the Express HTTP Server instance
+     * @returns express.Application
+     * @public API
+     */
+    getHttpServer() {
+        return this.httpServer;
+    }
+    /**
+     * Create a new instance of the Express Micro API adapter
+     * @param config - Configuration options
+     * @returns ICreateMicroAPI
+     * @public API
+     */
+    create(config) {
+        this.app = express();
+        this.routeManager = new Route(this.app);
+        this.container = new IOC(config?.containerOptions);
+        this.middlewareManager = new Middleware();
+        this.environment = "development";
+        return this;
+    }
+    /**
+     * Build the Web Server Micro API
+     * @returns IWebServerMicroAPI
+     * @public API
+     */
+    build() {
+        this.routeManager.setGlobalRoutePrefix(this.globalPrefix);
+        return this;
+    }
+    /**
+     * Listen for incoming requests
+     * @param port - The port to listen on
+     * @param appInfo - Information about the application
+     * @public API
+     */
+    async listen(port, appInfo) {
+        const logger = new Logger();
+        const console = new Console();
+        const normalizedPort = typeof port === "string" ? parseInt(port, 10) : port;
+        this.configureMiddleware();
+        this.routeManager.applyRoutes();
+        if (this.Middleware.getErrorHandler()) {
+            this.app.use(this.Middleware.getErrorHandler());
+        }
+        return new Promise((resolve, reject) => {
+            this.httpServer = this.app.listen(normalizedPort, async () => {
+                const address = this.httpServer.address();
+                if (typeof address === "object" && address?.port) {
+                    this.port = address.port;
+                }
+                else {
+                    this.port = normalizedPort;
+                }
+                // Display startup message using Console class
+                await console.messageServer(this.port, this.environment, {
+                    appName: appInfo?.appName || "ExpressoTS Micro",
+                    appVersion: appInfo?.appVersion || "1.0.0",
+                });
+                ["SIGTERM", "SIGHUP", "SIGBREAK", "SIGQUIT", "SIGINT"].forEach((signal) => {
+                    process.on(signal, this.handleExit.bind(this));
+                });
+                resolve();
+            });
+            this.httpServer.on("error", (error) => {
+                logger.error(`Error starting server: ${error.message}`, "MicroAPI");
+                reject(error);
+            });
+        });
+    }
+}
+/**
+ * Create a new instance of the Express Micro API adapter
+ * @param config - Configuration options
+ * @returns ICreateMicroAPI
+ * @public API
+ */
+export function createMicroAPI(config) {
+    const microAPI = new AppExpressMicro();
+    const create = microAPI.create.bind(microAPI);
+    return create(config);
+}

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

@@ -0,0 +1,174 @@
+/**
+ * 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 });
+ *         }
+ *     }
+ * });
+ * ```
+ */
+export class CircuitBreaker {
+    state = "CLOSED";
+    failures = 0;
+    successes = 0;
+    totalSuccesses = 0;
+    totalCalls = 0;
+    lastFailure;
+    lastSuccess;
+    openedAt;
+    recentFailures = [];
+    config;
+    constructor(config) {
+        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);
+    }
+}

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

@@ -0,0 +1,5 @@
+/**
+ * API Gateway Utilities for ExpressoTS Micro Template
+ */
+export { CircuitBreaker, } from "./circuit-breaker.js";
+export { ServiceProxy, createProxy } from "./service-proxy.js";

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

@@ -0,0 +1,210 @@
+import { CircuitBreaker } from "./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());
+ * ```
+ */
+export class ServiceProxy {
+    config;
+    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 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();
+    }
+}
+/**
+ * Create a new service proxy
+ */
+export function createProxy(config) {
+    return new ServiceProxy(config);
+}

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

@@ -0,0 +1,10 @@
+// Primary API - pure simplicity
+export { micro } from "./micro.js";
+// Advanced features - import separately when needed
+export * from "./gateway/index.js"; // CircuitBreaker, ServiceProxy
+export * from "./service-mesh/index.js"; // ServiceDiscovery, ServiceClient
+export * from "./serverless/index.js"; // Lambda, Cloudflare, Vercel adapters
+export * from "./queue/index.js"; // RabbitMQ consumer
+// Legacy API - deprecated, will be removed in v6
+/** @deprecated Use micro() instead */
+export { createMicroAPI } from "./application-express-micro.js";