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

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; } });