How karthikpro/node-router works
Purpose and Runtime
This is a Node.js reverse-proxy server that loads JSON route definitions at runtime and applies configuration changes without restart. It runs on Node.js 16.20.2+ and defaults to port 9000, overridable through PORT. The main executable and HTTP composition point is server.js; package scripts and dependencies are defined in package.json.
HTTP Entry Points
The server exposes operational and UI endpoints:
• Dashboard: /, rendered from views/index.ejs
• Documentation: /documentation, rendered from views/documentation.ejs
• Health endpoint: /health
• Fallback/not-found rendering: views/404.ejs
All unmatched proxied traffic is evaluated against the dynamically loaded route configuration.
Route Configuration Boundary
Route definitions are JSON documents placed under routes/, such as routes/test.json. Each file defines a URL context and backend target plus optional request transformations and policies. The routes/ directory is both the operator-facing control plane and the reload boundary: filesystem changes cause the active routing configuration to refresh.
Dynamic Routing and Proxy Stage
server.js loads route JSON definitions, maps incoming request paths to a configured urlContext, and forwards matching traffic to the configured backend. Before forwarding, it can remove a client-facing prefix (removePrefix) and prepend a backend-facing prefix (addPrefix). This separates public gateway paths from upstream service paths.
Per-Route Policy Stage
Each route may carry behavior applied at the proxy boundary:
• CORS settings, such as allowed origins and methods.
• Security headers, using Helmet-backed options such as frameguard and XSS filtering.
• Request logging.
• Upstream timeout settings, with path patterns exempted through ignoreTimeout.
These policies belong to route configuration rather than application code, allowing per-upstream behavior without redeployment.
External Dependencies and Infrastructure
The process depends on reachable backend HTTP services named by route configuration (for example, backend-server:8080 in the documented schema). It uses the local filesystem as configuration infrastructure and EJS templates for the built-in operator UI. Dependency versions and runtime libraries are locked by package-lock.json.
Key Repository Paths
• Runtime server and proxy orchestration: server.js
• Package/runtime contract: package.json
• Live route configuration directory: routes/
• Example route definition: routes/test.json
• Operator-facing views: views/index.ejs, views/documentation.ejs, views/404.ejs
Main entry points: server.js HTTP listener · test.json Example route · package.json Package contract · package-lock.json Dependency lock
Components 14
Proxy Runtime
- Package contract · Defines scripts, dependencies, and Node runtime requirements.
package.json - Dependency lock
package-lock.json - Proxy server · Composes HTTP endpoints, route loading, policies, and proxying.
server.js - HTTP listener · Listens on port 9000 by default or PORT.
server.js - Route loader · Loads route documents into the active routing table.
server.js - Dynamic route matcher · Matches request paths against configured urlContext values.
server.js - Path transformation · Applies removePrefix and addPrefix before forwarding.
server.js - Per-route policies · Applies CORS, Helmet headers, logging, and timeout rules.
server.js
Route Control Plane
- Live route definitions · Filesystem changes reload the active routing configuration.
- Example route · Defines a URL context, backend, transformations, and policies.
routes/test.json
Operator UI
- Dashboard view
views/index.ejs - Documentation view
views/documentation.ejs - Not-found view
views/404.ejs
Other components
- Backend HTTP services · Targets named by each route backend, such as backend-server:8080.
Connections 17
- Package contract → Proxy server: runs
- Dependency lock → Package contract: locks dependencies for
- Proxy server → HTTP listener: creates
- Proxy server → Route loader: loads configuration
- Live route definitions → Example route: contains
- Live route definitions → Route loader: reloads on changes
- Route loader → Dynamic route matcher: supplies active routes
- HTTP listener → Dashboard view: GET / renders
- HTTP listener → Documentation view: GET /documentation renders
- HTTP listener → Not-found view: fallback renders
- HTTP listener → Dynamic route matcher: unmatched proxy traffic
- Dynamic route matcher → Path transformation: matching route
- Path transformation → Per-route policies: rewritten request
- Per-route policies → Backend HTTP services: forwards with route policy
- Example route → Dynamic route matcher: urlContext and backend
- Example route → Path transformation: prefix rules
- Example route → Per-route policies: policy settings