@derian-cordoba/api-gateway 1.0.0

package/.env.example

@@ -0,0 +1,32 @@
+# ── Server ───────────────────────────────────────────────────────────────────
+# Port the gateway listens on. GATEWAY_PORT takes priority over PORT.
+GATEWAY_PORT=3000
+
+# Optional URL prefix mounted before all gateway routes.
+# Example: GATEWAY_PREFIX=/api/v1  →  routes become /api/v1/<baseURL>
+GATEWAY_PREFIX=
+
+# ── Logging ──────────────────────────────────────────────────────────────────
+# Log level: trace | debug | info | warn | error | fatal
+LOG_LEVEL=info
+
+# Set to "production" to disable pino-pretty and emit newline-delimited JSON.
+NODE_ENV=development
+
+# ── CORS ─────────────────────────────────────────────────────────────────────
+# Comma-separated list of allowed origins. Use * to allow all origins.
+CORS_ORIGINS=*
+
+# Comma-separated list of allowed HTTP methods.
+CORS_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
+
+# Comma-separated list of allowed request headers.
+CORS_HEADERS=Content-Type,Authorization
+
+# ── Routes ───────────────────────────────────────────────────────────────────
+# Path to the JSON file that defines proxy routes (relative to process cwd).
+ROUTES_FILE_PATH=routes.json
+
+# Inline route definitions as a JSON array (merged with ROUTES_FILE_PATH).
+# Example: ROUTES=[{"baseURL":"/svc","proxy":{"target":"http://localhost:4000","changeOrigin":true}}]
+ROUTES=

package/README.md

@@ -0,0 +1,382 @@
+# API Gateway
+
+A generic, configuration-driven HTTP API gateway. Routes incoming requests to upstream services via a JSON config file or environment variable, with per-route rate limiting, request validation, structured logging, and full security headers out of the box.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Getting Started](#getting-started)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+  - [Route Configuration](#route-configuration)
+- [Running the Gateway](#running-the-gateway)
+- [Health Check](#health-check)
+- [Project Structure](#project-structure)
+- [Example Project](#example-project)
+- [Architecture](#architecture)
+
+---
+
+## Features
+
+- **Configuration-driven routing** — define proxy routes in a JSON file, an environment variable, or both; changes take effect on restart with zero code changes
+- **Per-route rate limiting** — each route can declare its own `max` requests / `windowMs` window, enforced by `express-rate-limit`
+- **Startup validation** — route config is validated with Zod at boot time; the process exits with a descriptive error rather than silently misbehaving
+- **Structured logging** — `pino` + `pino-http` emit newline-delimited JSON in production and human-readable output (via `pino-pretty`) in development
+- **Security headers** — full `helmet` defaults applied to every response (`CSP`, `HSTS`, `X-Frame-Options`, `X-Content-Type-Options`, etc.)
+- **Configurable CORS** — origins, methods, and allowed headers controlled via environment variables
+- **Health check endpoint** — `GET /health` returns uptime, version, and timestamp; always available regardless of configured routes
+- **Optional URL prefix** — mount all routes under a shared prefix (e.g. `/api/v1`) via `GATEWAY_PREFIX`
+- **Body forwarding** — JSON bodies on `POST`, `PUT`, and `PATCH` requests are correctly forwarded to upstreams (`fixRequestBody`)
+- **Graceful shutdown** — `SIGINT` and `uncaughtException` handlers stop the server cleanly before exiting
+
+---
+
+## Requirements
+
+- Node.js 18+
+- pnpm 10+
+
+---
+
+## Getting Started
+
+```bash
+# 1. Clone and install
+git clone <repo-url>
+cd api-gateway
+pnpm install
+
+# 2. Create your env file
+cp .env.example .env
+
+# 3. Create a routes config (see Route Configuration below)
+cp examples/basic/routes.json routes.json   # or write your own
+
+# 4. Start in development mode (hot-reload)
+pnpm dev
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Copy `.env.example` to `.env` and edit as needed.
+
+#### Server
+
+| Variable | Default | Description |
+|---|---|---|
+| `GATEWAY_PORT` | `3000` | Port the gateway listens on. Takes priority over `PORT`. |
+| `PORT` | `3000` | Fallback port when `GATEWAY_PORT` is not set. |
+| `GATEWAY_PREFIX` | _(none)_ | Optional path prefix for all routes. Example: `/api/v1` makes proxy routes reachable at `/api/v1/<baseURL>` and the health check at `/api/v1/health`. |
+
+#### Logging
+
+| Variable | Default | Description |
+|---|---|---|
+| `NODE_ENV` | `development` | Set to `production` to disable `pino-pretty` and emit newline-delimited JSON. |
+| `LOG_LEVEL` | `info` | Pino log level: `trace` · `debug` · `info` · `warn` · `error` · `fatal`. |
+
+#### CORS
+
+| Variable | Default | Description |
+|---|---|---|
+| `CORS_ORIGINS` | `*` | Comma-separated list of allowed origins. Use `*` to allow all. |
+| `CORS_METHODS` | `GET,POST,PUT,DELETE,PATCH,OPTIONS` | Comma-separated list of allowed HTTP methods. |
+| `CORS_HEADERS` | `Content-Type,Authorization` | Comma-separated list of allowed request headers. |
+
+#### Routes
+
+| Variable | Default | Description |
+|---|---|---|
+| `ROUTES_FILE_PATH` | `routes.json` | Path to the JSON route config file, relative to `process.cwd()`. |
+| `ROUTES` | _(none)_ | Inline route definitions as a JSON array. Merged with `ROUTES_FILE_PATH`. Useful for containerised deployments where injecting a file is inconvenient. |
+
+---
+
+### Route Configuration
+
+Routes are defined as a JSON array. Each entry is a **Gateway** object:
+
+```ts
+{
+  baseURL:    string     // required — path prefix to match, must start with "/"
+  proxy:      Proxy      // required — upstream proxy settings
+  rateLimit?: RateLimit  // optional — per-route rate limiting
+}
+```
+
+#### `Proxy`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `target` | `string` | ✅ | Target upstream URL (must be a valid URL). |
+| `changeOrigin` | `boolean` | — | Rewrite the `Host` header to the target origin. |
+| `pathRewrite` | `{ [pattern]: replacement }` | — | Regex path rewrite rules applied before forwarding. |
+| `headers` | `{ [name]: value }` | — | Extra headers added to every forwarded request. |
+| `isSecure` | `boolean` | — | Verify the upstream TLS certificate. |
+| `method` | `string` | — | Override the HTTP method forwarded to the upstream. |
+| `timeout` | `number` | — | Proxy request timeout in milliseconds. |
+
+#### `RateLimit`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `max` | `number` | ✅ | Maximum number of requests allowed per window. |
+| `windowMs` | `number` | ✅ | Time window in milliseconds. |
+| `statusCode` | `number` | — | HTTP status returned when the limit is exceeded (default: `429`). |
+| `message` | `string` | — | Response message when the limit is exceeded (default: `"Too many requests"`). |
+
+Responses include standard `RateLimit-*` headers (RFC draft-8).
+
+#### Example `routes.json`
+
+```json
+[
+  {
+    "baseURL": "/users",
+    "proxy": {
+      "target": "http://users-service:3001",
+      "changeOrigin": true,
+      "pathRewrite": { "^/users": "" }
+    },
+    "rateLimit": {
+      "max": 100,
+      "windowMs": 60000,
+      "statusCode": 429,
+      "message": "Too many requests. Please try again in a minute."
+    }
+  },
+  {
+    "baseURL": "/orders",
+    "proxy": {
+      "target": "http://orders-service:3002",
+      "changeOrigin": true,
+      "pathRewrite": { "^/orders": "" },
+      "headers": {
+        "X-Internal-Source": "api-gateway"
+      },
+      "timeout": 5000
+    }
+  }
+]
+```
+
+Config is validated with [Zod](https://zod.dev) at startup. If any route is invalid the process exits immediately with a detailed per-field error message.
+
+Routes are loaded from two sources and **merged**:
+
+1. `ROUTES_FILE_PATH` — JSON file on disk (missing file is a warning, not an error)
+2. `ROUTES` — JSON array in an environment variable
+
+---
+
+## Running the Gateway
+
+### Development (hot-reload)
+
+```bash
+pnpm dev
+```
+
+Uses `ts-node-dev` to transpile on the fly and restart on file changes. Logs are pretty-printed via `pino-pretty`.
+
+### Production
+
+```bash
+# Compile TypeScript
+pnpm build
+
+# Run the compiled output
+pnpm start
+```
+
+In production (`NODE_ENV=production`) logs are emitted as newline-delimited JSON suitable for log aggregators (Datadog, Loki, CloudWatch, etc.).
+
+---
+
+## Health Check
+
+The gateway exposes a built-in health check endpoint that is always available, independent of the configured proxy routes.
+
+```
+GET /health
+```
+
+If `GATEWAY_PREFIX` is set, the endpoint is available at `<GATEWAY_PREFIX>/health`.
+
+**Response `200 OK`:**
+
+```json
+{
+  "status": "ok",
+  "uptime": 42,
+  "version": "1.0.0",
+  "timestamp": "2026-06-18T00:00:00.000Z"
+}
+```
+
+| Field | Description |
+|---|---|
+| `status` | Always `"ok"` when the process is alive. |
+| `uptime` | Seconds since the gateway process started. |
+| `version` | Value of `npm_package_version` (set automatically by npm/pnpm). |
+| `timestamp` | ISO 8601 timestamp of the response. |
+
+---
+
+## Project Structure
+
+```
+src/apps/api-gateway/
+├── index.ts                  # Entry point — bootstraps the app, registers process signals
+├── App.ts                    # Thin lifecycle wrapper (start / stop)
+├── Server.ts                 # HTTP server creation and prefix mounting
+├── logger.ts                 # Pino logger singleton
+│
+├── config/
+│   ├── app-env.ts            # Aggregates all config modules into a single AppEnv object
+│   ├── env/config.ts         # NODE_ENV → isDev flag
+│   ├── gateway/config.ts     # GATEWAY_PORT, GATEWAY_PREFIX
+│   ├── cors/config.ts        # CORS_ORIGINS, CORS_METHODS, CORS_HEADERS
+│   └── routes/config.ts      # ROUTES_FILE_PATH
+│
+├── routes/
+│   ├── Router.ts             # Middleware pipeline (logging → security → CORS → body → proxy → errors)
+│   ├── ProxyManager.ts       # Reads, validates, and registers proxy routes
+│   ├── RouteValidator.ts     # Zod schemas for Gateway / Proxy / RateLimit types
+│   └── HealthRouter.ts       # GET /health handler
+│
+└── types/
+    ├── gateway.d.ts          # Gateway type
+    ├── proxy.d.ts            # Proxy type
+    └── rate-limit.d.ts       # RateLimit type
+```
+
+---
+
+## Example Project
+
+`examples/basic/` contains a self-contained demo with two mock upstream services and a pre-built gateway config.
+
+### What's included
+
+| File | Description |
+|---|---|
+| `routes.json` | Gateway config with two routes (`/users`, `/products`) each with rate limiting and path rewriting |
+| `.env` | Gateway environment for the example |
+| `upstream-users.js` | Mock Users service on port `4001` |
+| `upstream-products.js` | Mock Products service on port `4002` |
+| `run.sh` | Starts all three processes and stops them together on Ctrl+C |
+
+### Running the example
+
+```bash
+pnpm example
+```
+
+This copies `examples/basic/.env` to the project root and starts all three services. Once running:
+
+| Endpoint | Description |
+|---|---|
+| `http://localhost:3000/health` | Gateway health check |
+| `http://localhost:3000/users` | Proxied to Users service |
+| `http://localhost:3000/products` | Proxied to Products service |
+
+### Users service endpoints (`/users`)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/users` | List all users |
+| `GET` | `/users/:id` | Get a user by ID |
+| `POST` | `/users` | Create a user (body: `{ name, email }`) |
+| `DELETE` | `/users/:id` | Delete a user by ID |
+
+### Products service endpoints (`/products`)
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/products` | List all products |
+| `GET` | `/products/:id` | Get a product by ID |
+| `POST` | `/products` | Create a product (body: `{ name, price }`) |
+| `PATCH` | `/products/:id/stock` | Adjust stock (body: `{ quantity: number }`) |
+
+### Example requests
+
+```bash
+# List users
+curl http://localhost:3000/users
+
+# Create a user
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice", "email": "alice@example.com"}'
+
+# Get a product
+curl http://localhost:3000/products/1
+
+# Update product stock
+curl -X PATCH http://localhost:3000/products/1/stock \
+  -H "Content-Type: application/json" \
+  -d '{"quantity": 25}'
+```
+
+---
+
+## Architecture
+
+### Request lifecycle
+
+```
+Client
+  │
+  ▼
+Express app
+  │
+  ├─ pino-http          structured request/response logging
+  ├─ helmet             security headers (CSP, HSTS, X-Frame-Options, …)
+  ├─ cors               configurable origin / method / header policy
+  ├─ express.json       body parsing
+  ├─ compression        gzip response compression
+  │
+  ├─ GET /health        health check — short-circuits here
+  │
+  ├─ express-rate-limit per-route request throttling (applied per baseURL)
+  ├─ http-proxy-middleware  proxies request to upstream, forwards body
+  │
+  └─ error handler      catches unhandled errors → 500 JSON response
+```
+
+### Startup sequence
+
+```
+index.ts
+  │
+  ├─ dotenv.config()           load .env before any module reads process.env
+  ├─ new App()
+  │    └─ new Server()
+  │         ├─ appEnv resolved  config modules read from process.env
+  │         └─ new Router()
+  │
+  └─ app.start()
+       ├─ router.init()          async: reads routes file, validates, registers middleware
+       └─ httpServer.listen()    starts accepting connections only after routes are ready
+```
+
+### Route loading
+
+Routes are loaded from two sources at startup and merged into a single array before validation:
+
+```
+ROUTES_FILE_PATH (JSON file)  ──┐
+                                ├──► merge ──► Zod validation ──► register proxy routes
+ROUTES (env var JSON array)   ──┘
+```
+
+If either source is missing or contains invalid JSON it is skipped with a warning. If the merged result fails Zod validation, the process exits with a descriptive error.

package/dist/src/apps/api-gateway/App.d.ts

@@ -0,0 +1,12 @@
+export declare class App {
+    private readonly server;
+    constructor();
+    /**
+     * Start the HTTP server
+     */
+    start(): Promise<void>;
+    /**
+     * Configure security headers using Helmet
+     */
+    stop(): Promise<void>;
+}

package/dist/src/apps/api-gateway/App.js

@@ -0,0 +1,35 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.App = void 0;
+const Server_1 = require("./Server");
+class App {
+    constructor() {
+        this.server = new Server_1.Server();
+    }
+    /**
+     * Start the HTTP server
+     */
+    start() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.server.start();
+        });
+    }
+    /**
+     * Configure security headers using Helmet
+     */
+    stop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return yield this.server.stop();
+        });
+    }
+}
+exports.App = App;

package/dist/src/apps/api-gateway/Server.d.ts

@@ -0,0 +1,27 @@
+import { type Express } from "express";
+export declare class Server {
+    private readonly app;
+    private readonly router;
+    private readonly httpServer;
+    private readonly port;
+    private readonly prefix;
+    constructor();
+    /**
+     * Register all middleware and proxy routes without opening a port.
+     * Call this before start() or use it directly in tests with getApp().
+     */
+    init(): Promise<void>;
+    /**
+     * Returns the underlying Express application.
+     * Useful for integration tests via supertest without binding to a port.
+     */
+    getApp(): Express;
+    /**
+     * Initialise routes then start the HTTP server.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the HTTP server gracefully
+     */
+    stop(): Promise<void>;
+}

package/dist/src/apps/api-gateway/Server.js

@@ -0,0 +1,79 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Server = void 0;
+const express_1 = __importDefault(require("express"));
+const http_1 = require("http");
+const Router_1 = require("./routes/Router");
+const app_env_1 = require("./config/app-env");
+const logger_1 = require("./logger");
+class Server {
+    constructor() {
+        this.port = app_env_1.appEnv.gateway.port;
+        this.prefix = app_env_1.appEnv.gateway.prefix;
+        this.router = new Router_1.Router();
+        this.app = (0, express_1.default)();
+        this.httpServer = (0, http_1.createServer)(this.app);
+    }
+    /**
+     * Register all middleware and proxy routes without opening a port.
+     * Call this before start() or use it directly in tests with getApp().
+     */
+    init() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.router.init();
+            this.app.use(this.prefix, this.router.getRouter());
+        });
+    }
+    /**
+     * Returns the underlying Express application.
+     * Useful for integration tests via supertest without binding to a port.
+     */
+    getApp() {
+        return this.app;
+    }
+    /**
+     * Initialise routes then start the HTTP server.
+     */
+    start() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.init();
+            return new Promise((resolve) => {
+                this.httpServer.listen(this.port, () => {
+                    logger_1.logger.info(`Gateway started on port ${this.port} (prefix: ${this.prefix})`);
+                    resolve();
+                });
+            });
+        });
+    }
+    /**
+     * Stop the HTTP server gracefully
+     */
+    stop() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve) => {
+                this.httpServer.close((error) => {
+                    if (error) {
+                        logger_1.logger.warn({ err: error }, "Error while stopping server");
+                    }
+                    else {
+                        logger_1.logger.info("Gateway stopped");
+                    }
+                    resolve();
+                });
+            });
+        });
+    }
+}
+exports.Server = Server;

package/dist/src/apps/api-gateway/config/app-env.d.ts

@@ -0,0 +1,11 @@
+import { type GatewayConfig } from "./gateway/config";
+import { type CorsConfig } from "./cors/config";
+import { type RoutesConfig } from "./routes/config";
+import { type EnvConfig } from "./env/config";
+export type AppEnv = {
+    env: EnvConfig;
+    gateway: GatewayConfig;
+    cors: CorsConfig;
+    routes: RoutesConfig;
+};
+export declare const appEnv: AppEnv;

package/dist/src/apps/api-gateway/config/app-env.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appEnv = void 0;
+const config_1 = require("./gateway/config");
+const config_2 = require("./cors/config");
+const config_3 = require("./routes/config");
+const config_4 = require("./env/config");
+exports.appEnv = {
+    env: config_4.envConfig,
+    gateway: config_1.gatewayConfig,
+    cors: config_2.corsConfig,
+    routes: config_3.routesConfig,
+};

package/dist/src/apps/api-gateway/config/cors/config.d.ts

@@ -0,0 +1,6 @@
+export type CorsConfig = {
+    origins: string | string[];
+    methods: string[];
+    allowedHeaders: string[];
+};
+export declare const corsConfig: CorsConfig;

package/dist/src/apps/api-gateway/config/cors/config.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.corsConfig = void 0;
+const { CORS_ORIGINS, CORS_METHODS, CORS_HEADERS } = process.env;
+exports.corsConfig = {
+    origins: (CORS_ORIGINS === null || CORS_ORIGINS === void 0 ? void 0 : CORS_ORIGINS.split(",").map((origin) => origin.trim())) || "*",
+    methods: CORS_METHODS
+        ? CORS_METHODS.split(",").map((method) => method.trim())
+        : ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+    allowedHeaders: CORS_HEADERS
+        ? CORS_HEADERS.split(",").map((header) => header.trim())
+        : ["Content-Type", "Authorization"],
+};

package/dist/src/apps/api-gateway/config/env/config.d.ts

@@ -0,0 +1,4 @@
+export type EnvConfig = {
+    isDev: boolean;
+};
+export declare const envConfig: EnvConfig;

package/dist/src/apps/api-gateway/config/env/config.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envConfig = void 0;
+exports.envConfig = {
+    isDev: process.env.NODE_ENV !== "production",
+};

package/dist/src/apps/api-gateway/config/gateway/config.d.ts

@@ -0,0 +1,9 @@
+export type GatewayConfig = {
+    prefix: string;
+    port: number;
+};
+export declare const DEFAULT_PORT: number;
+export declare const gatewayConfig: {
+    readonly prefix: string;
+    readonly port: number;
+};

package/dist/src/apps/api-gateway/config/gateway/config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatewayConfig = exports.DEFAULT_PORT = void 0;
+const { GATEWAY_PREFIX, GATEWAY_PORT, PORT } = process.env;
+exports.DEFAULT_PORT = 3000;
+exports.gatewayConfig = {
+    prefix: GATEWAY_PREFIX || '/',
+    port: Number(GATEWAY_PORT || PORT) || exports.DEFAULT_PORT,
+};

package/dist/src/apps/api-gateway/config/routes/config.d.ts

@@ -0,0 +1,4 @@
+export type RoutesConfig = {
+    filePath: string;
+};
+export declare const routesConfig: RoutesConfig;

package/dist/src/apps/api-gateway/config/routes/config.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routesConfig = void 0;
+exports.routesConfig = {
+    filePath: process.env.ROUTES_FILE_PATH || "routes.json",
+};

package/dist/src/apps/api-gateway/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/apps/api-gateway/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dotenv_1 = require("dotenv");
+(0, dotenv_1.config)();
+const App_1 = require("./App");
+const logger_1 = require("./logger");
+function handleError(error) {
+    logger_1.logger.error({ err: error }, "Fatal startup error");
+    process.exit(1);
+}
+/**
+ * Bootstrap the application.
+ *
+ * This function creates a new instance of the App class and starts it.
+ *
+ * @returns {void}
+ */
+function bootstrap() {
+    const app = new App_1.App();
+    app.start().catch(handleError);
+    // Handle process termination signals
+    process.on("SIGINT", () => __awaiter(this, void 0, void 0, function* () {
+        yield app.stop();
+        process.exit(0);
+    }));
+    process.on("uncaughtException", (error) => __awaiter(this, void 0, void 0, function* () {
+        logger_1.logger.error({ err: error }, "uncaughtException");
+        try {
+            yield app.stop();
+        }
+        catch (_a) {
+            // ignore stop errors during crash shutdown
+        }
+        process.exit(1);
+    }));
+}
+bootstrap();

package/dist/src/apps/api-gateway/logger.d.ts

@@ -0,0 +1,2 @@
+import pino from "pino";
+export declare const logger: pino.Logger<never, boolean>;

package/dist/src/apps/api-gateway/logger.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const pino_1 = __importDefault(require("pino"));
+const app_env_1 = require("./config/app-env");
+exports.logger = (0, pino_1.default)(Object.assign({ level: process.env.LOG_LEVEL || "info" }, (app_env_1.appEnv.env.isDev && {
+    transport: {
+        target: "pino-pretty",
+        options: {
+            colorize: true,
+            ignore: "pid,hostname",
+            translateTime: "SYS:HH:MM:ss",
+        },
+    },
+})));

package/dist/src/apps/api-gateway/routes/HealthRouter.d.ts

@@ -0,0 +1,2 @@
+import { Router as ExpressRouter } from "express";
+export declare function createHealthRouter(): ExpressRouter;

package/dist/src/apps/api-gateway/routes/HealthRouter.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthRouter = createHealthRouter;
+const express_1 = require("express");
+const http_status_codes_1 = require("http-status-codes");
+const startTime = Date.now();
+function createHealthRouter() {
+    const router = (0, express_1.Router)();
+    router.get("/health", (_req, res) => {
+        res.status(http_status_codes_1.StatusCodes.OK).json({
+            status: "ok",
+            uptime: Math.floor((Date.now() - startTime) / 1000),
+            version: process.env.npm_package_version || "unknown",
+            timestamp: new Date().toISOString(),
+        });
+    });
+    return router;
+}

package/dist/src/apps/api-gateway/routes/ProxyManager.d.ts

@@ -0,0 +1,13 @@
+import type { Router } from "express";
+export declare class ProxyManager {
+    private readonly router;
+    private readonly filePath;
+    constructor(router: Router);
+    /**
+     * Register all proxy routes in the application
+     */
+    registerProxyRoutes(): Promise<void>;
+    private readRoutes;
+    private readFileRoutes;
+    private readEnvRoutes;
+}

package/dist/src/apps/api-gateway/routes/ProxyManager.js

@@ -0,0 +1,97 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyManager = void 0;
+const http_proxy_middleware_1 = require("http-proxy-middleware");
+const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
+const http_status_codes_1 = require("http-status-codes");
+const promises_1 = require("node:fs/promises");
+const RouteValidator_1 = require("./RouteValidator");
+const logger_1 = require("../logger");
+const app_env_1 = require("../config/app-env");
+class ProxyManager {
+    constructor(router) {
+        this.router = router;
+        this.filePath = app_env_1.appEnv.routes.filePath;
+    }
+    /**
+     * Register all proxy routes in the application
+     */
+    registerProxyRoutes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const routes = yield this.readRoutes();
+            if (routes.length === 0) {
+                logger_1.logger.warn("No proxy routes configured");
+                return;
+            }
+            routes.forEach((route) => {
+                var _a, _b;
+                // Apply per-route rate limiting when configured
+                if (route.rateLimit) {
+                    this.router.use(route.baseURL, (0, express_rate_limit_1.default)({
+                        windowMs: route.rateLimit.windowMs,
+                        limit: route.rateLimit.max,
+                        statusCode: (_a = route.rateLimit.statusCode) !== null && _a !== void 0 ? _a : http_status_codes_1.StatusCodes.TOO_MANY_REQUESTS,
+                        message: (_b = route.rateLimit.message) !== null && _b !== void 0 ? _b : "Too many requests",
+                        standardHeaders: true,
+                        legacyHeaders: false,
+                    }));
+                }
+                this.router.use(route.baseURL, (0, http_proxy_middleware_1.createProxyMiddleware)(Object.assign(Object.assign({}, route.proxy), { on: {
+                        // Re-stream the body that express.json() already consumed so the
+                        // upstream receives the request body correctly on POST/PUT/PATCH.
+                        proxyReq: http_proxy_middleware_1.fixRequestBody,
+                    } })));
+                logger_1.logger.info({ baseURL: route.baseURL, target: route.proxy.target }, "Registered proxy route");
+            });
+        });
+    }
+    readRoutes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fileRoutes = yield this.readFileRoutes();
+            const envRoutes = this.readEnvRoutes();
+            const merged = [...fileRoutes, ...envRoutes];
+            return (0, RouteValidator_1.validateRoutes)(merged);
+        });
+    }
+    readFileRoutes() {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const content = yield (0, promises_1.readFile)(this.filePath, "utf-8");
+                return JSON.parse(content);
+            }
+            catch (error) {
+                if (error.code === "ENOENT") {
+                    logger_1.logger.debug({ filePath: this.filePath }, "Routes file not found, skipping");
+                    return [];
+                }
+                logger_1.logger.error({ err: error, filePath: this.filePath }, "Failed to read routes file");
+                return [];
+            }
+        });
+    }
+    readEnvRoutes() {
+        const raw = process.env.ROUTES;
+        if (!raw)
+            return [];
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            logger_1.logger.error({ err: error }, "Failed to parse ROUTES env var as JSON, skipping");
+            return [];
+        }
+    }
+}
+exports.ProxyManager = ProxyManager;

package/dist/src/apps/api-gateway/routes/RouteValidator.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { Gateway } from "../types/gateway";
+export declare const GatewaysSchema: z.ZodArray<z.ZodObject<{
+    baseURL: z.ZodString;
+    proxy: z.ZodObject<{
+        target: z.ZodURL;
+        isSecure: z.ZodOptional<z.ZodBoolean>;
+        changeOrigin: z.ZodOptional<z.ZodBoolean>;
+        pathRewrite: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        method: z.ZodOptional<z.ZodString>;
+        timeout: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    rateLimit: z.ZodOptional<z.ZodObject<{
+        max: z.ZodNumber;
+        windowMs: z.ZodNumber;
+        statusCode: z.ZodOptional<z.ZodNumber>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare function validateRoutes(data: unknown): Gateway[];

package/dist/src/apps/api-gateway/routes/RouteValidator.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GatewaysSchema = void 0;
+exports.validateRoutes = validateRoutes;
+const zod_1 = require("zod");
+const ProxySchema = zod_1.z.object({
+    target: zod_1.z.url("Proxy target must be a valid URL"),
+    isSecure: zod_1.z.boolean().optional(),
+    changeOrigin: zod_1.z.boolean().optional(),
+    pathRewrite: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    headers: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    method: zod_1.z.string().optional(),
+    timeout: zod_1.z.number().positive("Proxy timeout must be a positive number").optional(),
+});
+const RateLimitSchema = zod_1.z.object({
+    max: zod_1.z.number().positive("Rate limit max must be a positive number"),
+    windowMs: zod_1.z.number().positive("Rate limit windowMs must be a positive number"),
+    statusCode: zod_1.z.number().optional(),
+    message: zod_1.z.string().optional(),
+});
+const GatewaySchema = zod_1.z.object({
+    baseURL: zod_1.z.string().startsWith("/", "baseURL must start with /"),
+    proxy: ProxySchema,
+    rateLimit: RateLimitSchema.optional(),
+});
+exports.GatewaysSchema = zod_1.z.array(GatewaySchema);
+function validateRoutes(data) {
+    const result = exports.GatewaysSchema.safeParse(data);
+    if (!result.success) {
+        const formatted = result.error.issues
+            .map((issue) => `  [${issue.path.join(".")}] ${issue.message}`)
+            .join("\n");
+        throw new Error(`Invalid route configuration:\n${formatted}`);
+    }
+    return result.data;
+}

package/dist/src/apps/api-gateway/routes/Router.d.ts

@@ -0,0 +1,18 @@
+import { Router as ExpressRouter } from "express";
+export declare class Router {
+    private readonly router;
+    constructor();
+    /**
+     * Get the router instance for the application
+     */
+    getRouter(): ExpressRouter;
+    /**
+     * Initialise all middleware and routes. Must be awaited before the HTTP
+     * server starts listening so that proxy routes are registered in time.
+     */
+    init(): Promise<void>;
+    private configureCors;
+    private configureBodyParser;
+    private configureProxyManager;
+    private configureErrorHandler;
+}

package/dist/src/apps/api-gateway/routes/Router.js

@@ -0,0 +1,120 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Router = void 0;
+const express_1 = __importStar(require("express"));
+const http_status_codes_1 = require("http-status-codes");
+const cors_1 = __importDefault(require("cors"));
+const compression_1 = __importDefault(require("compression"));
+const helmet_1 = __importDefault(require("helmet"));
+const pino_http_1 = __importDefault(require("pino-http"));
+const ProxyManager_1 = require("./ProxyManager");
+const HealthRouter_1 = require("./HealthRouter");
+const app_env_1 = require("../config/app-env");
+const logger_1 = require("../logger");
+class Router {
+    constructor() {
+        this.router = (0, express_1.Router)();
+    }
+    /**
+     * Get the router instance for the application
+     */
+    getRouter() {
+        return this.router;
+    }
+    /**
+     * Initialise all middleware and routes. Must be awaited before the HTTP
+     * server starts listening so that proxy routes are registered in time.
+     */
+    init() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Structured HTTP request logging
+            this.router.use((0, pino_http_1.default)({ logger: logger_1.logger }));
+            // Security headers (full helmet defaults)
+            this.router.use((0, helmet_1.default)());
+            // Configurable CORS
+            this.configureCors();
+            // Body parsing + gzip compression
+            this.configureBodyParser();
+            // Health check
+            this.router.use((0, HealthRouter_1.createHealthRouter)());
+            // Proxy routes (async — reads config file / env var)
+            yield this.configureProxyManager();
+            // Error handler must be registered last
+            this.configureErrorHandler();
+        });
+    }
+    configureCors() {
+        const { origins, methods, allowedHeaders } = app_env_1.appEnv.cors;
+        this.router.use((0, cors_1.default)({
+            origin: origins,
+            methods,
+            allowedHeaders,
+        }));
+    }
+    configureBodyParser() {
+        this.router.use(express_1.default.json());
+        this.router.use(express_1.default.urlencoded({ extended: true }));
+        this.router.use((0, compression_1.default)());
+    }
+    configureProxyManager() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const proxyManager = new ProxyManager_1.ProxyManager(this.router);
+            yield proxyManager.registerProxyRoutes();
+        });
+    }
+    configureErrorHandler() {
+        this.router.use((error, _req, res, _next) => {
+            logger_1.logger.error({ err: error }, "Unhandled error");
+            res.status(http_status_codes_1.StatusCodes.INTERNAL_SERVER_ERROR).json({
+                error: "Internal Server Error",
+                message: error.message,
+            });
+        });
+    }
+}
+exports.Router = Router;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@derian-cordoba/api-gateway",
+  "version": "1.0.0",
+  "description": "A generic, configuration-driven HTTP API gateway with per-route rate limiting, structured logging, and security headers",
+  "main": "./dist/src/apps/api-gateway/index.js",
+  "types": "./dist/src/apps/api-gateway/index.d.ts",
+  "bin": {
+    "api-gateway": "./dist/src/apps/api-gateway/index.js"
+  },
+  "files": [
+    "dist/",
+    ".env.example",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=10.0.0"
+  },
+  "keywords": [
+    "api-gateway",
+    "gateway",
+    "proxy",
+    "reverse-proxy",
+    "express",
+    "rate-limiting",
+    "typescript",
+    "nodejs"
+  ],
+  "author": "derian-cordoba",
+  "license": "MIT",
+  "packageManager": "pnpm@10.6.5",
+  "scripts": {
+    "dev": "NODE_ENV=development ts-node-dev --ignore-watch node_modules --respawn --transpile-only src/apps/api-gateway/index.ts",
+    "build": "rm -rf ./dist && tsc -p tsconfig.prod.json",
+    "postbuild": "chmod +x dist/src/apps/api-gateway/index.js",
+    "start": "node dist/src/apps/api-gateway/index.js",
+    "prepare": "pnpm build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "example": "bash examples/basic/run.sh"
+  },
+  "devDependencies": {
+    "@types/compression": "^1.8.0",
+    "@types/cors": "^2.8.18",
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.15.21",
+    "@types/supertest": "^7.2.0",
+    "pino-pretty": "^13.1.3",
+    "supertest": "^7.2.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "compression": "^1.8.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.5.0",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.2",
+    "helmet": "^8.1.0",
+    "http-proxy-middleware": "^3.0.5",
+    "http-status-codes": "^2.3.0",
+    "pino": "^10.3.1",
+    "pino-http": "^11.0.0",
+    "zod": "^4.4.3"
+  },
+  "overrides": {
+    "rimraf": "^6.0.1"
+  }
+}