@lopatnov/express-reverse-proxy 2.0.0 → 3.0.0

package/README.md

@@ -218,6 +218,55 @@ The port the server listens on. Defaults to `8000`. Can also be set via the `POR
 }
 ```
 
+### logging
+
+Controls HTTP request logging (Morgan). Enabled by default. Set to `false` to silence per-request log lines — useful in production behind another proxy, or to keep console output clean.
+
+```json
+{
+  "port": 8080,
+  "logging": false,
+  "folders": "www"
+}
+```
+
+### hotReload
+
+Watches the `folders` directories for file changes and automatically reloads connected browser tabs. Uses Server-Sent Events (SSE). Intended for local development only.
+
+```json
+{
+  "port": 8080,
+  "hotReload": true,
+  "folders": "www"
+}
+```
+
+The server exposes two endpoints when hot reload is enabled:
+
+| Endpoint | Description |
+| --------------------------------- | ------------------------------------------ |
+| `GET /__hot-reload__` | SSE stream — browsers subscribe here |
+| `GET /__hot-reload__/client.js` | Ready-to-use client script |
+
+#### Connecting the client
+
+**Option A — plain HTML project**: add a script tag to your page. The file is served directly by the dev server, no installation needed:
+
+```html
+<script src="/__hot-reload__/client.js"></script>
+```
+
+**Option B — bundled project** (Vite, webpack, etc.): import the client module. The bundler resolves it through the package `exports` field:
+
+```js
+import '@lopatnov/express-reverse-proxy/hot-reload-client';
+```
+
+Both options connect to `/__hot-reload__` and call `location.reload()` when a file change is detected. The connection is re-established automatically after 3 seconds if the server restarts.
+
+> **PM2 note:** hot reload works best with a single process (`node server.js`). If using PM2, set `instances: 1` in your ecosystem config — each worker maintains its own file watcher and SSE client list independently.
+
 ### headers
 
 Add headers to every response — useful for CORS in development.
@@ -385,6 +434,34 @@ To use multi-site mode, make the config file an **array** instead of an object.
 >
 > Two entries with the same `host` **and** `port` cause a startup error. The same `host` on different ports is allowed.
 
+### ssl
+
+Enable HTTPS on a port by adding an `ssl` object to any site config for that port. All sites sharing the same port use the same certificate.
+
+| Field  | Type     | Description                                              |
+| ------ | -------- | -------------------------------------------------------- |
+| `key`  | `string` | Path to the private key file (PEM format)                |
+| `cert` | `string` | Path to the certificate file (PEM format)                |
+| `ca`   | `string` | *(optional)* Path to the CA bundle for client validation |
+
+Paths are resolved **relative to the config file**, not the current working directory.
+
+```json
+{
+  "port": 443,
+  "ssl": {
+    "key": "./certs/key.pem",
+    "cert": "./certs/cert.pem"
+  },
+  "folders": "./public",
+  "proxy": {
+    "/api": "http://localhost:4000"
+  }
+}
+```
+
+> All site configs on the same port must either all have `ssl` or none — mixing is a startup error.
+
 ---
 
 ## Configuration Recipes
@@ -422,6 +499,37 @@ Only `/api/*` requests go to the back-end; everything else stays local.
 - `GET /api/users` → proxied to `http://localhost:4000/users`
 - `GET /missing` → 404 Not Found
 
+### HTTPS with a self-signed certificate (local dev)
+
+```shell
+mkdir certs
+openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem \
+  -days 365 -nodes -subj "/CN=localhost"
+```
+
+```json
+{
+  "port": 8443,
+  "ssl": {
+    "key": "./certs/key.pem",
+    "cert": "./certs/cert.pem"
+  },
+  "folders": "www",
+  "proxy": {
+    "/api": "http://localhost:4000"
+  }
+}
+```
+
+Start and open in browser (accept the self-signed cert warning):
+
+```shell
+node server.js --config server-config.json
+# [listen] https://localhost:8443
+```
+
+---
+
 ### CORS headers + rich error responses
 
 ```json
@@ -519,6 +627,56 @@ express-reverse-proxy --cluster status
 express-reverse-proxy --cluster stop
 ```
 
+### Behind a reverse proxy
+
+For production deployments it is common to place a dedicated reverse proxy in front of `express-reverse-proxy` to handle TLS termination, HTTP/2, gzip compression, and rate limiting. In this setup the Node.js server listens on a local port over plain HTTP, while the outer proxy terminates HTTPS connections from the internet:
+
+```
+Internet (HTTPS / HTTP/2)
+        ↓
+  Nginx or Caddy          — TLS, HTTP/2, gzip, rate limiting
+        ↓ HTTP/1.1 (localhost)
+  express-reverse-proxy   — PM2 cluster, routing, static files, API proxy
+        ↓
+  Backend API servers
+```
+
+**No `ssl` config needed** in `server-config.json` when the outer proxy handles TLS.
+
+#### Nginx
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name example.com;
+
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+
+    location / {
+        proxy_pass         http://127.0.0.1:8080;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+Free certificates can be obtained with [Certbot](https://certbot.eff.org/): `certbot --nginx -d example.com`.
+
+#### Caddy
+
+[Caddy](https://caddyserver.com/) provisions and renews Let's Encrypt certificates automatically — no extra tooling needed:
+
+```
+example.com {
+    reverse_proxy 127.0.0.1:8080
+}
+```
+
+Start with `caddy run --config Caddyfile`.
+
 ---
 
 ## Testing

package/ecosystem.config.cjs

@@ -1,24 +1,24 @@
-const path = require('node:path');
-
-module.exports = {
-  apps: [
-    {
-      name: 'express-reverse-proxy',
-      script: path.join(__dirname, 'server.js'),
-      instances: 'max',
-      exec_mode: 'cluster',
-      wait_ready: true,
-      listen_timeout: 30000,
-      kill_timeout: 5000,
-      shutdown_with_message: true,
-      vizion: false, // disable git metadata collection
-      pmx: false, // disable PM2 metrics (avoids wmic ENOENT on Windows 11)
-      env: {
-        NODE_ENV: 'production',
-      },
-      env_development: {
-        NODE_ENV: 'development',
-      },
-    },
-  ],
-};
+const path = require('node:path');
+
+module.exports = {
+  apps: [
+    {
+      name: 'express-reverse-proxy',
+      script: path.join(__dirname, 'server.js'),
+      instances: 'max',
+      exec_mode: 'cluster',
+      wait_ready: true,
+      listen_timeout: 30000,
+      kill_timeout: 5000,
+      shutdown_with_message: true,
+      vizion: false, // disable git metadata collection
+      pmx: false, // disable PM2 metrics (avoids wmic ENOENT on Windows 11)
+      env: {
+        NODE_ENV: 'production',
+      },
+      env_development: {
+        NODE_ENV: 'development',
+      },
+    },
+  ],
+};

package/hot-reload-client.js

@@ -0,0 +1,31 @@
+/**
+ * Hot Reload Client — connect via SSE and reload the page when files change.
+ *
+ * Usage (choose one):
+ *
+ *   <!-- as a plain script tag -->
+ *   <script src="/__hot-reload__/client.js"></script>
+ *
+ *   <!-- as an ES module (bundler resolves via package.json exports) -->
+ *   import '@lopatnov/express-reverse-proxy/hot-reload-client';
+ *
+ * The server must have `"hotReload": true` in its server-config.json.
+ */
+(function hotReloadClient() {
+  var url = '/__hot-reload__';
+
+  function connect() {
+    var es = new EventSource(url);
+
+    es.onmessage = () => {
+      location.reload();
+    };
+
+    es.onerror = () => {
+      es.close();
+      setTimeout(connect, 3000);
+    };
+  }
+
+  connect();
+})();

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@lopatnov/express-reverse-proxy",
   "email": "oleksandr@lopatnov.cv.ua",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Node.js CLI tool to serve static front-end files with a reverse proxy for back-end APIs",
   "type": "module",
   "author": "lopatnov",
   "main": "server.js",
   "exports": {
-    ".": "./server.js"
+    ".": "./server.js",
+    "./hot-reload-client": "./hot-reload-client.js"
   },
   "bin": {
     "express-reverse-proxy": "./server.js"
@@ -57,6 +58,7 @@
   "homepage": "https://lopatnov.github.io/express-reverse-proxy/",
   "files": [
     "server.js",
+    "hot-reload-client.js",
     "ecosystem.config.cjs",
     "README.md",
     "LICENSE"

package/server.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import https from 'node:https';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import express from 'express';
@@ -151,6 +152,7 @@ if (serverArgs['--config']) {
     configFile = path.join(configFile, './server-config.json');
   }
 }
+const configDir = path.dirname(path.resolve(configFile));
 
 const DEFAULT_CONFIG = { port: 8000, folders: '.' };
 
@@ -194,6 +196,21 @@ configs.forEach((c) => {
   configsByPort.get(p).push(c);
 });
 
+// Validate: cannot mix SSL and non-SSL site configs on the same port
+for (const [p, group] of configsByPort) {
+  const sslCount = group.filter((c) => c.ssl).length;
+  if (sslCount > 0 && sslCount < group.length) {
+    exitError(`Port ${p}: cannot mix SSL and non-SSL site configs on the same port.`, 1);
+  }
+}
+
+function collectFolderPaths(folders) {
+  if (typeof folders === 'string') return [folders];
+  if (Array.isArray(folders)) return folders.flatMap(collectFolderPaths);
+  if (folders instanceof Object) return Object.values(folders).flatMap(collectFolderPaths);
+  return [];
+}
+
 function addStaticFolderByName(router, port, urlPath, folder) {
   let folderPath = folder;
   if (!path.isAbsolute(folder)) {
@@ -290,7 +307,47 @@ const servers = [];
 
 configsByPort.forEach((portConfigs, p) => {
   const app = express();
-  app.use(morgan('combined'));
+  const loggingEnabled = portConfigs.every((c) => c.logging !== false);
+  if (loggingEnabled) {
+    app.use(morgan('combined'));
+  }
+
+  // Hot reload via SSE
+  const hotReloadEnabled = portConfigs.some((c) => c.hotReload === true);
+  if (hotReloadEnabled) {
+    const sseClients = new Set();
+    let reloadTimer = null;
+
+    app.get('/__hot-reload__', (req, res) => {
+      res.setHeader('Content-Type', 'text/event-stream');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.setHeader('Connection', 'keep-alive');
+      res.flushHeaders();
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+    });
+
+    app.get('/__hot-reload__/client.js', (_req, res) => {
+      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+      res.sendFile(path.join(__dirname, 'hot-reload-client.js'));
+    });
+
+    const watchPaths = [
+      ...new Set(portConfigs.flatMap((c) => collectFolderPaths(c.folders || []))),
+    ];
+    for (const folder of watchPaths) {
+      const absPath = path.isAbsolute(folder) ? folder : path.join(process.cwd(), folder);
+      if (fs.existsSync(absPath)) {
+        fs.watch(absPath, { recursive: true }, () => {
+          clearTimeout(reloadTimer);
+          reloadTimer = setTimeout(() => {
+            for (const client of sseClients) client.write('data: reload\n\n');
+          }, 100);
+        });
+      }
+    }
+    console.log(`[hot-reload] watching ${watchPaths.length} folder(s) on port ${p}`);
+  }
 
   // Specific hosts first, catch-all last
   const sorted = [
@@ -341,10 +398,31 @@ configsByPort.forEach((portConfigs, p) => {
     }
   });
 
-  const server = app.listen(p, () => {
-    console.log(`[listen] http://localhost:${p}`);
-    if (process.send) process.send('ready');
-  });
+  const sslConfig = portConfigs.find((c) => c.ssl)?.ssl;
+  let server;
+  if (sslConfig) {
+    let sslOptions;
+    try {
+      sslOptions = {
+        key: fs.readFileSync(path.resolve(configDir, sslConfig.key)),
+        cert: fs.readFileSync(path.resolve(configDir, sslConfig.cert)),
+      };
+      if (sslConfig.ca) {
+        sslOptions.ca = fs.readFileSync(path.resolve(configDir, sslConfig.ca));
+      }
+    } catch (err) {
+      exitError(`SSL cert/key error on port ${p}: ${err.message}`, 1);
+    }
+    server = https.createServer(sslOptions, app).listen(p, () => {
+      console.log(`[listen] https://localhost:${p}`);
+      if (process.send) process.send('ready');
+    });
+  } else {
+    server = app.listen(p, () => {
+      console.log(`[listen] http://localhost:${p}`);
+      if (process.send) process.send('ready');
+    });
+  }
   server.on('error', (err) => {
     if (err.code === 'EADDRINUSE') {
       exitError(`Port ${p} is already in use`, 1);