adaptive-gateway 1.0.5

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 Adejare Omomofe
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# Adaptive Gateway
+
+`adaptive-gateway` is a lightweight Express-compatible gateway middleware with caching, circuit-breaker fallback, and rate limiting.
+
+## Install
+
+```bash
+npm install adaptive-gateway
+```
+
+## Usage
+
+```js
+import express from 'express';
+import gateKeep from 'adaptive-gateway';
+
+const app = express();
+
+app.use(express.json());
+
+app.use('/proxy', gateKeep({
+  target: 'http://localhost:3000',
+  ttl: 300,
+  latencyThreshold: 500,
+  pathRewrite: path => path.replace(/^\/proxy/, ''),
+  breakerOptions: {
+    timeout: 8000,
+    errorThresholdPercentage: 50,
+    resetTimeout: 10000
+  }
+}));
+
+app.listen(4000, () => {
+  console.log('Gateway running on http://localhost:4000');
+});
+```
+
+## Named exports
+
+```js
+import { adaptiveGateway, createGateKeepMiddleware, gateKeep } from 'adaptive-gateway';
+```
+
+- `adaptiveGateway(options)` — gateway wrapper with built-in rate limiting
+- `createGateKeepMiddleware(options)` — reusable middleware factory
+- `gateKeep` — alias for `createGateKeepMiddleware`
+
+## Options
+
+- `target` — backend URL to proxy to
+- `ttl` — cache TTL in seconds
+- `latencyThreshold` — threshold for request caching decisions
+- `pathRewrite` — function to rewrite the incoming request path before proxying
+- `breakerOptions` — opossum circuit breaker configuration
+
+## Notes
+
+This package is designed to be used in an Express app and assumes a Redis client and metrics pipeline are configured in the local project.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "adaptive-gateway",
+  "version": "1.0.5",
+  "description": "Adaptive Express gateway middleware with caching, circuit breaker fallback, and rate limiting.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "nodemon examples/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "express",
+    "gateway",
+    "middleware",
+    "proxy",
+    "cache",
+    "rate-limit",
+    "circuit-breaker"
+  ],
+  "author": "Adejare Omomofe",
+  "license": "ISC",
+  "dependencies": {
+    "axios": "^1.16.0",
+    "express": "^5.2.1",
+    "node-cron": "^4.2.1",
+    "opossum": "^9.0.0",
+    "pg": "^8.20.0",
+    "redis": "^5.12.1"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.14"
+  }
+}

package/src/analytics/cachePolicy.js

@@ -0,0 +1,27 @@
+import { getEndpointStats } from './metricAnalyzer.js';
+import redisClient from '../cache/redisClient.js';
+
+export async function getCacheableEndpoints(latencyThreshold = 100, defaultTtl = 60) {
+    const stats = await getEndpointStats();
+
+    for (const stat of stats) {
+        const highLatency = stat.avgLatency > latencyThreshold;
+        const lowErrorRate = parseFloat(stat.errorRate) < 3;
+        const highTraffic = stat.requestCount > 100;
+
+        if (highLatency && lowErrorRate && highTraffic) {
+            let ttl = defaultTtl;
+            if (stat.avgLatency > latencyThreshold * 2) ttl = defaultTtl * 2;
+            if (stat.avgLatency > latencyThreshold * 3) ttl = defaultTtl * 5;
+            redisClient.set(`cacheable:${stat.endpoint}`, 'true', { EX: ttl });
+        } else {
+            redisClient.del(`cacheable:${stat.endpoint}`);
+        }
+
+        console.log(`Endpoint: ${stat.endpoint}, Avg Latency: ${stat.avgLatency}ms, Error Rate: ${stat.errorRate}%`);
+    }
+
+    return stats
+        .filter(stat => stat.avgLatency > latencyThreshold && parseFloat(stat.errorRate) < 3)
+        .map(stat => stat.endpoint);
+}

package/src/analytics/metricAnalyzer.js

@@ -0,0 +1,18 @@
+import { pool } from "../database/db.js";
+export async function getEndpointStats() {
+    const result = await pool.query(`
+        SELECT endpoint, 
+               COUNT(*) AS total_requests, 
+               AVG(response_time_ms) AS avg_latency, 
+               SUM(CASE WHEN is_error THEN 1 ELSE 0 END) AS error_count
+        FROM metrics
+        GROUP BY endpoint
+        ORDER BY total_requests DESC
+    `);
+    return result.rows.map(row => ({
+        endpoint: row.endpoint,
+        totalRequests: parseInt(row.total_requests, 10),
+        avgLatency: parseFloat(row.avg_latency),
+        errorRate: `${((Number(row.error_count) / parseInt(row.total_requests, 10)) * 100).toFixed(2)}%`
+    }));
+}

package/src/cache/redisClient.js

@@ -0,0 +1,11 @@
+import redis, { createClient } from 'redis';
+
+const client = createClient()
+
+client.on('error', (err) => console.log('Redis Client Error', err));
+
+(async () => {
+    await client.connect();
+})();
+
+export default client;

package/src/database/db.js

@@ -0,0 +1,9 @@
+import { Pool } from 'pg';
+
+export const pool = new Pool({
+    user: 'mac',
+    host: 'localhost',
+    database: 'gateway_metrics',
+    password: '',
+    port: 5432,
+});

package/src/index.js

@@ -0,0 +1,21 @@
+
+import { rateLimit } from './rateLimit/ratelimit.js';
+import { createGateKeepMiddleware } from './services/gateKeep.js';
+
+export const adaptiveGateway = (options) => {
+    const proxyMiddleware = createGateKeepMiddleware({
+        target: options.proxy.target,
+        ttl: options.cache.ttl,
+        latencyThreshold: options.cache.latencyThreshold,
+        pathRewrite: options.proxy.pathRewrite
+    });
+
+    return async function (req, res, next) {
+        rateLimit(req, res, options.rateLimit.max, options.rateLimit.windowMs, async () => {
+            await proxyMiddleware(req, res, next);
+        });
+    };
+};
+
+export { createGateKeepMiddleware };
+export default adaptiveGateway;

package/src/jobs/cachePolicy.js

@@ -0,0 +1,24 @@
+import { getCacheableEndpoints } from '../analytics/cachePolicy.js';
+const CACHE_POLICY_REFRESH_INTERVAL_MS = 15 * 60 * 1000;
+
+export async function recalculateCachePolicy() {
+    console.log('Recalculating cache policy based on analytics data...');
+    // TODO: implement cache policy recalculation logic here using analytics data
+    await getCacheableEndpoints();
+}
+
+export function startCachePolicyRecalculationJob() {
+    console.log('Starting cache policy recalculation job every 15 minutes.');
+    // Run immediately on startup, then every 15 minutes.
+    recalculateCachePolicy().catch(error => {
+        console.error('Failed to run initial cache policy recalculation:', error);
+    });
+
+    setInterval(async () => {
+        try {
+            await recalculateCachePolicy();
+        } catch (error) {
+            console.error('Error during cache policy recalculation:', error);
+        }
+    }, CACHE_POLICY_REFRESH_INTERVAL_MS);
+}

package/src/metrics/recordMetrics.js

@@ -0,0 +1,24 @@
+import { pool } from "../database/db.js";
+
+export async function recordMetrics({ path, method, latency, status, error = false }) {
+    console.log({
+        path: path,
+        method: method,
+        latency: `${latency}ms`,
+        status: status,
+        error: error,
+        timestamp: new Date().toISOString()
+    });
+
+    // try {
+    //     await pool.query(
+    //         `INSERT INTO metrics (endpoint, method, status_code, response_time_ms, is_error)
+    //    VALUES ($1, $2, $3, $4, $5)`,
+    //         [path, method, status, latency, error]
+    //     );
+    // } catch (err) {
+    //     console.error("Failed to insert metrics:", err.message);
+    // }
+
+
+}

package/src/proxy/forwarder.js

@@ -0,0 +1,40 @@
+import axios from "axios";
+import { recordMetrics } from "../metrics/recordMetrics.js";
+import redisClient from "../cache/redisClient.js";
+import { getCacheableEndpoints } from "../analytics/cachePolicy.js";
+
+const TARGET_BACKEND = 'http://localhost:3000';
+
+export async function gateKeep(req, res, path, target = TARGET_BACKEND, ttl, latencyThreshold) {
+    const start = Date.now();
+    try {
+        if (req.method == 'GET' && (await getCacheableEndpoints()).includes(path)) {
+            const cacheKey = `${path}:${JSON.stringify(req.query)}`;
+            const cachedResponse = await redisClient.get(cacheKey);
+            if (cachedResponse) {
+                console.log(`Cache hit for ${cacheKey}`);
+                return res.json(JSON.parse(cachedResponse));
+            }
+            console.log(`Cache miss for ${cacheKey}`);
+        }
+        const response = await axios({
+            method: req.method,
+            url: `${target}${path}`,
+            data: req.body,
+            params: req.query,
+        })
+        const duration = Date.now() - start;
+        await recordMetrics({ path, method: req.method, latency: duration, status: response.status });
+        if (req.method == 'GET' && (await getCacheableEndpoints()).includes(path)) {
+            const cacheKey = `${path}:${JSON.stringify(req.query)}`;
+            await redisClient.set(cacheKey, JSON.stringify(response.data), { EX: ttl });
+        }
+        res.status(response.status).json(response.data);
+
+    } catch (error) {
+        const duration = Date.now() - start;
+        console.error(`Error proxying request to ${path}:`, error.message);
+        await recordMetrics({ path, method: req.method, latency: duration, status: error.response?.status || 'Error', error: true });
+        res.status(error.response?.status || 500).json({ error: 'Internal Server Error' });
+    }
+}

package/src/rateLimit/ratelimit.js

@@ -0,0 +1,32 @@
+const bucket = new Map();
+
+export const rateLimit = (req, res, max, windowMs, next) => {
+    const key = req.ip;
+    const now = Date.now();
+
+    if (!bucket.has(key)) {
+        bucket.set(key, {
+            tokens: max,
+            lastRefill: now
+        });
+    }
+
+    const userBucket = bucket.get(key);
+    const elapsed = now - userBucket.lastRefill;
+    const refillAmount = (elapsed * max) / windowMs;
+
+    if (refillAmount > 0) {
+        userBucket.tokens = Math.min(max, userBucket.tokens + refillAmount);
+        userBucket.lastRefill = now;
+    }
+
+    if (userBucket.tokens >= 1) {
+        userBucket.tokens -= 1;
+        bucket.set(key, userBucket);
+        next();
+    } else {
+        res.status(429).json({
+            error: 'Too Many Requests'
+        });
+    }
+};

package/src/services/gateKeep.js

@@ -0,0 +1,99 @@
+import CircuitBreaker from 'opossum';
+import axios from 'axios';
+import redisClient from '../cache/redisClient.js';
+import { recordMetrics } from '../metrics/recordMetrics.js';
+import { getCacheableEndpoints } from '../analytics/cachePolicy.js';
+
+const DEFAULT_TARGET = 'http://localhost:3000';
+const DEFAULT_TTL = 300;
+const DEFAULT_LATENCY_THRESHOLD = 500;
+const DEFAULT_BREAKER_OPTIONS = {
+    timeout: 8000,
+    errorThresholdPercentage: 50,
+    resetTimeout: 10000
+};
+
+function buildCacheKey(target, path, query) {
+    return `${target}:${path}:${JSON.stringify(query ?? {})}`;
+}
+
+function createBreaker(options) {
+    const breaker = new CircuitBreaker(async (target, path, req) => {
+        const response = await axios({
+            method: req.method,
+            url: `${target}${path}`,
+            data: req.body,
+            params: req.query,
+            validateStatus: status => status < 500
+        });
+
+        if (response.status >= 500) {
+            const error = new Error(`Upstream server error: ${response.status}`);
+            error.response = response;
+            throw error;
+        }
+
+        return response;
+    }, options);
+
+    breaker.fallback(async (target, path, req) => {
+        const cacheKey = buildCacheKey(target, path, req.query);
+        const stale = await redisClient.get(cacheKey);
+        if (stale) {
+            return {
+                status: 200,
+                data: JSON.parse(stale),
+                stale: true
+            };
+        }
+
+        throw new Error('Service unavailable');
+    });
+
+    return breaker;
+}
+
+export function createGateKeepMiddleware({
+    target = DEFAULT_TARGET,
+    ttl = DEFAULT_TTL,
+    latencyThreshold = DEFAULT_LATENCY_THRESHOLD,
+    pathRewrite = path => path,
+    breakerOptions = {}
+} = {}) {
+    const breaker = createBreaker({ ...DEFAULT_BREAKER_OPTIONS, ...breakerOptions });
+
+    return async function gateKeepMiddleware(req, res, next) {
+        const path = pathRewrite(req.path);
+        const cacheKey = buildCacheKey(target, path, req.query);
+        const shouldCache = req.method === 'GET' && (await getCacheableEndpoints(latencyThreshold)).includes(path);
+
+        if (shouldCache) {
+            const cached = await redisClient.get(cacheKey);
+            if (cached) {
+                return res.json(JSON.parse(cached));
+            }
+        }
+
+        const start = Date.now();
+        try {
+            const response = await breaker.fire(target, path, req);
+            const duration = Date.now() - start;
+            await recordMetrics({ path, method: req.method, latency: duration, status: response.status });
+
+            if (shouldCache) {
+                await redisClient.set(cacheKey, JSON.stringify(response.data), { EX: ttl });
+            }
+
+            return res.status(response.status).json(response.data);
+        } catch (error) {
+            const duration = Date.now() - start;
+            await recordMetrics({ path, method: req.method, latency: duration, status: error.response?.status || 503, error: true });
+            return res.status(error.response?.status || 503).json({
+                error: 'Service unavailable',
+                details: error.message
+            });
+        }
+    };
+}
+
+export const gateKeep = createGateKeepMiddleware;