Node.js API Gateway (Elysia Version)

A minimal yet production-minded API Gateway built with Node.js 22, Elysia.js, and TypeScript.

This project demonstrates how to build a reverse proxy / API gateway with authentication, rate limiting, request transformation, observability, and a built-in dashboard — all in a single-file server with zero frontend build tooling.

Designed as a pet-project, learning reference, and interview-ready infrastructure example.

---

Features

Core Gateway Capabilities

• Reverse Proxy

  • Proxies incoming HTTP requests to an upstream API
  • Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE)
  • Preserves request method, path, and payload
  • Gracefully handles JSON and non-JSON responses

• Authentication Middleware

  • Token-based authorization (Authorization: Bearer <token>)
  • Centralized auth enforcement for all proxied routes
  • Easy to replace with JWT, OAuth, or API keys

• Rate Limiting

  • Per-IP in-memory rate limiting
  • Sliding time window (per minute)
  • Standard rate-limit response headers:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • X-RateLimit-Reset

• Request Transformation

  • Gateway-level request mutation
  • Automatic payload injection for non-GET requests
  • Demonstrates how gateways enrich or normalize traffic

---

Built-in Dashboard (SPA)

• Served directly by the backend (no build step)
• Tailwind CSS via CDN
• Features:
  • Method selector (GET / POST)
  • Path-based proxy testing
  • JSON body editor
  • Live response viewer
  • Error handling & validation
• Ideal for manual testing and demos

---

cURL Generator

The dashboard automatically generates a ready-to-use curl command for every request.

Features:

• Reflects the selected HTTP method, path, headers, and body
• Includes the active authorization token
• Updates in real time as the request is edited
• One-click copy to clipboard

This allows seamless transition from UI testing to terminal or CI usage.

---

Observability & Health

• Health Check Endpoint

  • /health
  • Includes uptime and gateway status

• Runtime Logging

  • Clean, structured startup logs
  • Clear route visibility

---

Technology Stack

• Node.js >= 22
• Elysia.js 1.4.x
• @elysiajs/node
• @elysiajs/html
• TypeScript 5.x
• Tailwind CSS (CDN)
• Native fetch (Node 22)

No frontend frameworks.
No bundlers.
No build pipeline required.

---

Project Structure

nodejs-api-gateway-elysia/
├── server.ts        # Entire gateway + dashboard in one file
├── package.json
└── README.md

---

Installation & Running Locally

1. Clone the repository

git clone https://github.com/smart-developer1791/nodejs-api-gateway-elysia
cd nodejs-api-gateway-elysia

2. Install dependencies

npm install

3. Run in development mode

npm run dev

4. Open the dashboard

http://localhost:8080

---

Configuration

Variable	Description	Default
PORT	HTTP server port	8080
RATE_LIMIT	Requests per IP per minute	20
TARGET_API	Upstream API base URL	https://jsonplaceholder.typicode.com
AUTH_TOKEN	Static bearer token	Bearer secret-token

⚠️ For production, authentication secrets must be moved to environment variables.

---

Endpoints

Path	Method	Description
/	GET	Gateway dashboard (SPA)
/proxy/*	ANY	Proxied upstream request
/health	GET	Health check

---

Proxy Usage Examples

GET request

curl -X GET \
  -H "Authorization: Bearer secret-token" \
  http://localhost:8080/proxy/posts/1

POST request

curl -X POST \
  -H "Authorization: Bearer secret-token" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello","body":"World","userId":1}' \
  http://localhost:8080/proxy/posts

The gateway will automatically inject:

{
  "gatewayInjected": true
}

---

Health Check

curl http://localhost:8080/health

Example response:

{
  "status": "ok",
  "uptime": 151.9083812,
  "timestamp": "2025-12-27T19:47:14.144Z"
}

---

Rate Limiting Behavior

• Max 20 requests per minute per IP
• On limit exceeded:
  • HTTP 429 Too Many Requests
  • JSON error response
• Rate-limit headers included on every proxied response

---

Rate Limit Error Example

When the rate limit is exceeded, the gateway responds with HTTP 429 and a structured JSON payload:

{
  "error": "Rate limit exceeded",
  "message": "Maximum 20 requests per minute",
  "retryAfter": 53
}

---

Design Notes

• This gateway is intentionally minimal
• Focuses on:
  • correctness
  • readability
  • real-world patterns
• Uses in-memory storage for simplicity
• Designed to be extended, not scaled as-is

---

Production Considerations

If adapting this gateway for production:

• Replace in-memory rate limit store with Redis
• Use JWT or OAuth instead of static tokens
• Add request/response timeouts
• Add structured logging
• Add retry & circuit breaker logic
• Add metrics export (Prometheus)

---

Future Improvements

• Redis-backed rate limiting
• JWT authentication
• WebSocket live metrics
• Request/response logging
• OpenAPI / Swagger support
• Plugin-based middleware system
• Multiple upstream services with routing rules

---

Purpose

This project is intentionally built as:

• a reference implementation of an API Gateway using Elysia.js

---

Deploy in 10 seconds