@lopatnov/express-reverse-proxy 5.0.5 → 5.0.7

package/README.md

@@ -269,14 +269,14 @@ If `server-config.json` already exists, the command asks before overwriting.
 
 Manage the PM2 process cluster. Action defaults to `start` when omitted.
 
-| Action    | Description                                            |
-| --------- | ------------------------------------------------------ |
-| `start`   | Start the cluster (default when action is omitted)     |
-| `stop`    | Stop all cluster instances                             |
-| `restart` | Restart all cluster instances                          |
-| `status`  | Show PM2 process status table                          |
-| `logs`    | Stream the last 200 log lines                          |
-| `monitor` | Open the PM2 real-time monitor                         |
+| Action    | Description                                        |
+| --------- | -------------------------------------------------- |
+| `start`   | Start the cluster (default when action is omitted) |
+| `stop`    | Stop all cluster instances                         |
+| `restart` | Restart all cluster instances                      |
+| `status`  | Show PM2 process status table                      |
+| `logs`    | Stream the last 200 log lines                      |
+| `monitor` | Open the PM2 real-time monitor                     |
 
 ```shell
 express-reverse-proxy --cluster              # same as --cluster start
@@ -325,10 +325,10 @@ Add a `$schema` reference to your config file to get property autocomplete, desc
 
 ### Environment variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `8000` | Overrides the port when it is not set in the config file |
-| `NODE_ENV` | — | Passed through to PM2 env profiles (`env` / `env_development`) |
+| Variable   | Default | Description                                                    |
+| ---------- | ------- | -------------------------------------------------------------- |
+| `PORT`     | `8000`  | Overrides the port when it is not set in the config file       |
+| `NODE_ENV` | —       | Passed through to PM2 env profiles (`env` / `env_development`) |
 
 ### port
 
@@ -383,10 +383,10 @@ Watches the `folders` directories for file changes and automatically reloads con
 
 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 |
+| Endpoint                        | Description                          |
+| ------------------------------- | ------------------------------------ |
+| `GET /__hot-reload__`           | SSE stream — browsers subscribe here |
+| `GET /__hot-reload__/client.js` | Ready-to-use client script           |
 
 #### Connecting the client
 
@@ -399,7 +399,7 @@ The server exposes two endpoints when hot reload is enabled:
 **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';
+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.
@@ -446,11 +446,11 @@ Permanently or temporarily redirect URL paths to new destinations. Redirects are
 }
 ```
 
-| Field    | Default | Description                                              |
-| -------- | ------- | -------------------------------------------------------- |
-| `from`   | —       | Source URL path *(array form only, required)*            |
-| `to`     | —       | Destination path or full URL *(required)*                |
-| `status` | `301`   | HTTP redirect status: `301`, `302`, `307`, or `308`      |
+| Field    | Default | Description                                         |
+| -------- | ------- | --------------------------------------------------- |
+| `from`   | —       | Source URL path _(array form only, required)_       |
+| `to`     | —       | Destination path or full URL _(required)_           |
+| `status` | `301`   | HTTP redirect status: `301`, `302`, `307`, or `308` |
 
 > `301` — Moved Permanently. `302` — Found (temporary). Use `301` for permanent URL changes and `302` for temporary ones.
 
@@ -538,7 +538,11 @@ Forward requests to a back-end server. Supports three forms:
 ```json
 {
   "proxy": {
-    "/api": ["http://backend1:3000", "http://backend2:3000", "http://backend3:3000"]
+    "/api": [
+      "http://backend1:3000",
+      "http://backend2:3000",
+      "http://backend3:3000"
+    ]
   }
 }
 ```
@@ -629,8 +633,8 @@ Enable HTTPS on a port by adding an `ssl` object to any site config for that por
 | ---------- | --------- | -------------------------------------------------------- |
 | `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 |
-| `redirect` | `integer` | *(optional)* HTTP port to redirect (301) to HTTPS        |
+| `ca`       | `string`  | _(optional)_ Path to the CA bundle for client validation |
+| `redirect` | `integer` | _(optional)_ HTTP port to redirect (301) to HTTPS        |
 
 Paths are resolved **relative to the config file**, not the current working directory.
 
@@ -780,11 +784,11 @@ Limit the number of requests a client can make in a time window. Responds with `
 }
 ```
 
-| Option      | Default  | Description                                      |
-| ----------- | -------- | ------------------------------------------------ |
-| `windowMs`  | `60000`  | Time window in milliseconds                      |
-| `limit`     | `5`      | Maximum requests per client per window           |
-| `message`   | built-in | Response body when limit is exceeded             |
+| Option     | Default  | Description                            |
+| ---------- | -------- | -------------------------------------- |
+| `windowMs` | `60000`  | Time window in milliseconds            |
+| `limit`    | `5`      | Maximum requests per client per window |
+| `message`  | built-in | Response body when limit is exceeded   |
 
 See [express-rate-limit docs](https://express-rate-limit.mintlify.app/reference/configuration) for all options.
 
@@ -805,11 +809,11 @@ Protect the site with HTTP Basic Authentication. All requests must include valid
 }
 ```
 
-| Option      | Default | Description                                                  |
-| ----------- | ------- | ------------------------------------------------------------ |
-| `users`     | —       | Object mapping username → password *(required)*              |
+| Option      | Default | Description                                                    |
+| ----------- | ------- | -------------------------------------------------------------- |
+| `users`     | —       | Object mapping username → password _(required)_                |
 | `challenge` | `false` | Send `WWW-Authenticate` header to trigger browser login dialog |
-| `realm`     | —       | Realm string shown in the browser login dialog               |
+| `realm`     | —       | Realm string shown in the browser login dialog                 |
 
 See [express-basic-auth docs](https://github.com/LionC/express-basic-auth#options) for all options.
 
@@ -841,8 +845,8 @@ Custom path:
 }
 ```
 
-| Option | Default        | Description                      |
-| ------ | -------------- | -------------------------------- |
+| Option | Default         | Description                     |
+| ------ | --------------- | ------------------------------- |
 | `path` | `"/__health__"` | URL path of the health endpoint |
 
 > The health check endpoint is placed before rate limiting and basic auth — it is always publicly accessible regardless of other authentication settings.
@@ -867,12 +871,12 @@ Execute server-side scripts using the CGI (Common Gateway Interface) protocol. W
 }
 ```
 
-| Option         | Default                               | Description                                                          |
-| -------------- | ------------------------------------- | -------------------------------------------------------------------- |
-| `path`         | `"/cgi-bin"`                          | URL prefix that triggers CGI dispatch                                |
-| `dir`          | `"./cgi-bin"`                         | Local directory containing scripts (resolved relative to config file)|
-| `extensions`   | `[".cgi", ".pl", ".py", ".sh"]`       | File extensions treated as executable CGI scripts                    |
-| `interpreters` | `{}`                                  | Map of file extension → interpreter command                          |
+| Option         | Default                         | Description                                                           |
+| -------------- | ------------------------------- | --------------------------------------------------------------------- |
+| `path`         | `"/cgi-bin"`                    | URL prefix that triggers CGI dispatch                                 |
+| `dir`          | `"./cgi-bin"`                   | Local directory containing scripts (resolved relative to config file) |
+| `extensions`   | `[".cgi", ".pl", ".py", ".sh"]` | File extensions treated as executable CGI scripts                     |
+| `interpreters` | `{}`                            | Map of file extension → interpreter command                           |
 
 Shorthand — point directly to the script directory (all defaults apply):
 
@@ -884,18 +888,18 @@ Shorthand — point directly to the script directory (all defaults apply):
 
 CGI environment variables set for every request:
 
-| Variable          | Value                                                    |
-| ----------------- | -------------------------------------------------------- |
-| `REQUEST_METHOD`  | HTTP method (`GET`, `POST`, …)                           |
-| `QUERY_STRING`    | URL query string (without `?`)                           |
-| `CONTENT_TYPE`    | `Content-Type` request header                            |
-| `CONTENT_LENGTH`  | `Content-Length` request header                          |
-| `SCRIPT_FILENAME` | Absolute path to the script file                         |
-| `SCRIPT_NAME`     | URL path to the script (e.g. `/cgi-bin/hello.py`)        |
-| `SERVER_NAME`     | Requested hostname                                       |
-| `SERVER_PORT`     | Server listen port                                       |
-| `REMOTE_ADDR`     | Client IP address                                        |
-| `HTTP_*`          | All request headers (e.g. `HTTP_ACCEPT`, `HTTP_HOST`)    |
+| Variable          | Value                                                 |
+| ----------------- | ----------------------------------------------------- |
+| `REQUEST_METHOD`  | HTTP method (`GET`, `POST`, …)                        |
+| `QUERY_STRING`    | URL query string (without `?`)                        |
+| `CONTENT_TYPE`    | `Content-Type` request header                         |
+| `CONTENT_LENGTH`  | `Content-Length` request header                       |
+| `SCRIPT_FILENAME` | Absolute path to the script file                      |
+| `SCRIPT_NAME`     | URL path to the script (e.g. `/cgi-bin/hello.py`)     |
+| `SERVER_NAME`     | Requested hostname                                    |
+| `SERVER_PORT`     | Server listen port                                    |
+| `REMOTE_ADDR`     | Client IP address                                     |
+| `HTTP_*`          | All request headers (e.g. `HTTP_ACCEPT`, `HTTP_HOST`) |
 
 A minimal Python example (`cgi-bin/hello.py`):
 
@@ -960,39 +964,52 @@ Shorthand — directory only (all defaults apply):
 }
 ```
 
-| Option          | Default        | Description                                                              |
-| --------------- | -------------- | ------------------------------------------------------------------------ |
-| `path`          | `"/upload"`    | URL prefix for the upload endpoint                                       |
-| `dir`           | `"./uploads"`  | Save directory (resolved relative to the config file)                    |
-| `maxFileSize`   | none           | Maximum file size in bytes; responds with `413` when exceeded            |
-| `maxFiles`      | none           | Maximum number of files per request; responds with `400` when exceeded   |
-| `allowedTypes`  | none           | MIME type whitelist; responds with `400` when the type is not in the list|
-| `fieldName`     | any field      | Accept only files uploaded in this specific form field                   |
+| Option         | Default       | Description                                                               |
+| -------------- | ------------- | ------------------------------------------------------------------------- |
+| `path`         | `"/upload"`   | URL prefix for the upload endpoint                                        |
+| `dir`          | `"./uploads"` | Save directory (resolved relative to the config file)                     |
+| `maxFileSize`  | none          | Maximum file size in bytes; responds with `413` when exceeded             |
+| `maxFiles`     | none          | Maximum number of files per request; responds with `400` when exceeded    |
+| `allowedTypes` | none          | MIME type whitelist; responds with `400` when the type is not in the list |
+| `fieldName`    | any field     | Accept only files uploaded in this specific form field                    |
 
 **Array form** — multiple upload endpoints on the same site:
 
 ```json
 {
   "upload": [
-    { "path": "/photos", "dir": "./photos", "allowedTypes": ["image/jpeg", "image/png"] },
-    { "path": "/docs",   "dir": "./documents", "allowedTypes": ["application/pdf"], "maxFileSize": 5242880 }
+    {
+      "path": "/photos",
+      "dir": "./photos",
+      "allowedTypes": ["image/jpeg", "image/png"]
+    },
+    {
+      "path": "/docs",
+      "dir": "./documents",
+      "allowedTypes": ["application/pdf"],
+      "maxFileSize": 5242880
+    }
   ]
 }
 ```
 
 **HTTP interface:**
 
-| Method | URL              | Description                              |
-| ------ | ---------------- | ---------------------------------------- |
-| `POST` | `<path>`         | Upload files via `multipart/form-data`   |
-| `GET`  | `<path>/<name>`  | Retrieve a previously uploaded file      |
+| Method | URL             | Description                            |
+| ------ | --------------- | -------------------------------------- |
+| `POST` | `<path>`        | Upload files via `multipart/form-data` |
+| `GET`  | `<path>/<name>` | Retrieve a previously uploaded file    |
 
 `POST` success response (`200`):
 
 ```json
 {
   "files": [
-    { "file": "photo-1700000000000-123456789.jpg", "size": 45678, "originalName": "photo.jpg" }
+    {
+      "file": "photo-1700000000000-123456789.jpg",
+      "size": 45678,
+      "originalName": "photo.jpg"
+    }
   ]
 }
 ```
@@ -1186,9 +1203,9 @@ Redirect old URLs to new ones after a site restructure, without breaking existin
 {
   "port": 8080,
   "redirects": [
-    { "from": "/about.html",    "to": "/about",       "status": 301 },
-    { "from": "/products.html", "to": "/products",    "status": 301 },
-    { "from": "/blog/:slug",    "to": "/posts/:slug", "status": 301 }
+    { "from": "/about.html", "to": "/about", "status": 301 },
+    { "from": "/products.html", "to": "/products", "status": 301 },
+    { "from": "/blog/:slug", "to": "/posts/:slug", "status": 301 }
   ],
   "folders": "./public"
 }
@@ -1199,7 +1216,7 @@ Or as an object map for simple path-to-path redirects:
 ```json
 {
   "redirects": {
-    "/old-home":  "/",
+    "/old-home": "/",
     "/old-about": "/about",
     "/legacy-api": "https://api.example.com"
   }
@@ -1386,14 +1403,14 @@ express-reverse-proxy --cluster start --cluster-config ./my-ecosystem.config.cjs
 
 Run via npm scripts:
 
-| Script                  | Description                                                        |
-| ----------------------- | ------------------------------------------------------------------ |
-| `npm run pm2-start`     | Start cluster (max CPU cores); reads `server-config.json` from cwd |
-| `npm run pm2-restart`   | Restart all instances                                              |
-| `npm run pm2-stop`      | Stop all instances                                                 |
-| `npm run pm2-status`    | Show process status                                                |
-| `npm run pm2-logs`      | Show last 200 log lines                                            |
-| `npm run pm2-monitor`   | Open real-time monitor                                             |
+| Script                | Description                                                        |
+| --------------------- | ------------------------------------------------------------------ |
+| `npm run pm2-start`   | Start cluster (max CPU cores); reads `server-config.json` from cwd |
+| `npm run pm2-restart` | Restart all instances                                              |
+| `npm run pm2-stop`    | Stop all instances                                                 |
+| `npm run pm2-status`  | Show process status                                                |
+| `npm run pm2-logs`    | Show last 200 log lines                                            |
+| `npm run pm2-monitor` | Open real-time monitor                                             |
 
 Or use the CLI directly:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lopatnov/express-reverse-proxy",
   "email": "oleksandr@lopatnov.cv.ua",
-  "version": "5.0.5",
+  "version": "5.0.7",
   "description": "Node.js CLI tool to serve static front-end files with a reverse proxy for back-end APIs",
   "type": "module",
   "author": "lopatnov",
@@ -75,7 +75,7 @@
     "express": "^5.2.1",
     "express-basic-auth": "^1.2.1",
     "express-http-proxy": "^2.1.2",
-    "express-rate-limit": "^8.3.0",
+    "express-rate-limit": "^8.3.2",
     "helmet": "^8.1.0",
     "morgan": "^1.10.1",
     "multer": "^2.1.1",
@@ -84,7 +84,7 @@
     "serve-favicon": "^2.5.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
-    "cypress": "^15.11.0"
+    "@biomejs/biome": "^2.4.11",
+    "cypress": "^15.13.1"
   }
 }

package/server.js

@@ -69,7 +69,7 @@ function exitError(msg, code = -1) {
 }
 
 function parseArguments(args) {
-  const argsNames = args.map((a) => a.name);
+  const argsNames = new Set(args.map((a) => a.name));
   return args.reduce((res, arg) => {
     const argIndex = process.argv.indexOf(arg.name);
     if (argIndex > -1) {
@@ -77,10 +77,7 @@ function parseArguments(args) {
       if (arg.subArgs) {
         arg.subArgs.forEach((subArg, index) => {
           const subArgIndex = argIndex + index + 1;
-          if (
-            process.argv.length <= subArgIndex ||
-            argsNames.indexOf(process.argv[subArgIndex]) > -1
-          ) {
+          if (process.argv.length <= subArgIndex || argsNames.has(process.argv[subArgIndex])) {
             exitError(`Invalid argument ${arg.name}. Missing <${subArg}>.`, 16);
           }
           res[arg.name].args.push(process.argv[subArgIndex]);
@@ -99,10 +96,10 @@ function help(app, args) {
 
   args.forEach((arg) => {
     const tabIndentLength = 3;
-    const tabIndent = Array(tabIndentLength).fill('\t').join('');
-    const argTabIndent = Array(tabIndentLength - Math.trunc(arg.name.length / 4))
-      .fill('\t')
-      .join('');
+    const tabIndent = '\t'.repeat(tabIndentLength);
+    const argTabIndent = '\t'.repeat(
+      Math.max(1, tabIndentLength - Math.trunc(arg.name.length / 4)),
+    );
     console.log(`\t\x1b[1m${arg.name}\x1b[0m${argTabIndent}${arg.description}`);
     if (arg.subArgs) {
       const subArgs = arg.subArgs.map((subArg) => `<${subArg}>`).join(' ');
@@ -174,7 +171,7 @@ if (serverArgs['--init']) {
   if (proxyPath) proxyTarget = (await rl.question(`Proxy target for ${proxyPath}: `)).trim();
   const hotReload = (await rl.question('Hot reload? [y/N]: ')).trim().toLowerCase() === 'y';
   rl.close();
-  const cfg = { port: parseInt(port, 10), folders: folder };
+  const cfg = { port: Number.parseInt(port, 10), folders: folder };
   if (proxyPath && proxyTarget) cfg.proxy = { [proxyPath]: proxyTarget };
   if (hotReload) cfg.hotReload = true;
   fs.writeFileSync(configOut, `${JSON.stringify(cfg, null, 2)}\n`);
@@ -194,7 +191,14 @@ const configDir = path.dirname(path.resolve(configFile));
 const DEFAULT_CONFIG = { port: 8000, folders: '.' };
 
 let rawConfig;
-if (!fs.existsSync(configFile)) {
+if (fs.existsSync(configFile)) {
+  console.log(`[config] ${configFile}`);
+  try {
+    rawConfig = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch (err) {
+    exitError(`Failed to parse "${configFile}": ${err.message}`, 1);
+  }
+} else {
   if (serverArgs['--config']) {
     exitError(`Configuration file not found: "${configFile}"`, 404);
   }
@@ -202,13 +206,6 @@ if (!fs.existsSync(configFile)) {
     `\x1b[33m[config] "${configFile}" not found — using defaults (port: 8000, folders: ".")\x1b[0m`,
   );
   rawConfig = DEFAULT_CONFIG;
-} else {
-  console.log(`[config] ${configFile}`);
-  try {
-    rawConfig = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  } catch (err) {
-    exitError(`Failed to parse "${configFile}": ${err.message}`, 1);
-  }
 }
 
 const configs = Array.isArray(rawConfig) ? rawConfig : [rawConfig];
@@ -216,7 +213,7 @@ const configs = Array.isArray(rawConfig) ? rawConfig : [rawConfig];
 // Validate: same host on same port is an error; same host on different ports is OK
 const seen = new Set();
 configs.forEach((c) => {
-  const p = parseInt(c.port || process.env.PORT || 8000, 10);
+  const p = Number.parseInt(c.port || process.env.PORT || 8000, 10);
   if (p < 1 || p > 65535) exitError(`Invalid port: ${p}`, 1);
   const key = `${p}:${c.host || '*'}`;
   if (seen.has(key)) {
@@ -228,7 +225,7 @@ configs.forEach((c) => {
 // Group configs by port
 const configsByPort = new Map();
 configs.forEach((c) => {
-  const p = parseInt(c.port || process.env.PORT || 8000, 10);
+  const p = Number.parseInt(c.port || process.env.PORT || 8000, 10);
   if (!configsByPort.has(p)) configsByPort.set(p, []);
   configsByPort.get(p).push(c);
 });
@@ -319,7 +316,15 @@ function addMappedProxy(router, port, localRootPath, pathPairs) {
 
 function addProxies(router, port, localRootPath, proxies) {
   proxies.forEach((proxyUrl) => {
-    addRemoteProxy(router, port, localRootPath, proxyUrl);
+    if (
+      Array.isArray(proxyUrl) &&
+      proxyUrl.length > 0 &&
+      proxyUrl.every((i) => typeof i === 'string')
+    ) {
+      addRemoteProxy(router, port, localRootPath, proxyUrl);
+    } else {
+      addProxy(router, port, localRootPath, proxyUrl);
+    }
   });
 }
 
@@ -333,6 +338,275 @@ function addProxy(router, port, localRootPath, remoteProxy) {
   }
 }
 
+function configureLogging(router, siteConfig, configDir) {
+  if (siteConfig.logging === false) return;
+  const lc = siteConfig.logging;
+  if (typeof lc === 'object' && lc.file) {
+    const stream = fs.createWriteStream(path.resolve(configDir, lc.file), { flags: 'a' });
+    router.use(morgan(lc.format || 'combined', { stream }));
+  } else {
+    router.use(morgan((typeof lc === 'object' ? lc.format : null) || 'dev'));
+  }
+}
+
+function toOpts(val) {
+  return typeof val === 'object' ? val : {};
+}
+
+function configureMiddleware(router, siteConfig) {
+  if (siteConfig.responseTime) router.use(responseTime(toOpts(siteConfig.responseTime)));
+  if (siteConfig.cors) router.use(cors(toOpts(siteConfig.cors)));
+  if (siteConfig.compression) router.use(compression(toOpts(siteConfig.compression)));
+  if (siteConfig.helmet) router.use(helmet(toOpts(siteConfig.helmet)));
+  if (siteConfig.favicon) router.use(favicon(path.resolve(configDir, siteConfig.favicon)));
+  if (siteConfig.healthCheck) {
+    const hcPath =
+      (typeof siteConfig.healthCheck === 'object' && siteConfig.healthCheck.path) || '/__health__';
+    router.get(hcPath, (_req, res) => {
+      res.json({ status: 'ok', uptime: process.uptime(), timestamp: new Date().toISOString() });
+    });
+  }
+  if (siteConfig.rateLimit) router.use(rateLimit(toOpts(siteConfig.rateLimit)));
+  if (siteConfig.basicAuth) router.use(basicAuth(toOpts(siteConfig.basicAuth)));
+  if (siteConfig.headers) {
+    router.use((_req, res, next) => {
+      for (const h of Object.keys(siteConfig.headers)) res.setHeader(h, siteConfig.headers[h]);
+      next();
+    });
+  }
+}
+
+function setupRedirects(router, redirects) {
+  if (Array.isArray(redirects)) {
+    for (const r of redirects) {
+      router.all(r.from, (_req, res) => res.redirect(r.status || 301, r.to));
+    }
+  } else {
+    for (const [from, to] of Object.entries(redirects)) {
+      const dest = typeof to === 'string' ? to : to.to;
+      const status = typeof to === 'object' ? to.status || 301 : 301;
+      router.all(from, (_req, res) => res.redirect(status, dest));
+    }
+  }
+}
+
+function buildCgiEnv(req, scriptPath, cgiUrlPath, p) {
+  const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+  const env = {
+    ...process.env,
+    GATEWAY_INTERFACE: 'CGI/1.1',
+    SERVER_PROTOCOL: 'HTTP/1.1',
+    SERVER_SOFTWARE: 'express-reverse-proxy',
+    REQUEST_METHOD: req.method.toUpperCase(),
+    SCRIPT_FILENAME: scriptPath,
+    SCRIPT_NAME: cgiUrlPath + req.path,
+    PATH_INFO: '',
+    QUERY_STRING: url.search ? url.search.slice(1) : '',
+    REMOTE_ADDR: req.ip || '127.0.0.1',
+    CONTENT_TYPE: req.headers['content-type'] || '',
+    CONTENT_LENGTH: req.headers['content-length'] || '0',
+    SERVER_NAME: req.hostname || 'localhost',
+    SERVER_PORT: String(p),
+  };
+  for (const [k, v] of Object.entries(req.headers)) {
+    env[`HTTP_${k.toUpperCase().replaceAll('-', '_')}`] = Array.isArray(v) ? v.join(', ') : v;
+  }
+  return env;
+}
+
+function applyCgiHeaders(rawHeaders, res) {
+  let statusCode = 200;
+  for (const line of rawHeaders.split(/\r?\n/)) {
+    const colon = line.indexOf(':');
+    if (colon === -1) continue;
+    const name = line.substring(0, colon).trim();
+    const value = line.substring(colon + 1).trim();
+    if (name.toLowerCase() === 'status') {
+      statusCode = Number.parseInt(value, 10) || 200;
+    } else {
+      res.setHeader(name, value);
+    }
+  }
+  return statusCode;
+}
+
+function setupCgi(router, siteConfig, p, configDir) {
+  if (!siteConfig.cgi) return;
+  const cgiRaw = siteConfig.cgi;
+  const cgiConfigs = Array.isArray(cgiRaw)
+    ? cgiRaw
+    : [typeof cgiRaw === 'string' ? { dir: cgiRaw } : cgiRaw];
+
+  for (const cgiConfig of cgiConfigs) {
+    const cgiUrlPath = cgiConfig.path || '/cgi-bin';
+    const cgiDirResolved = path.resolve(configDir, cgiConfig.dir || './cgi-bin');
+    const cgiExts = new Set(cgiConfig.extensions || ['.cgi', '.pl', '.py', '.sh']);
+    const interps = cgiConfig.interpreters || {};
+
+    router.use(cgiUrlPath, (req, res, next) => {
+      const scriptPath = path.resolve(path.join(cgiDirResolved, req.path));
+      if (!scriptPath.startsWith(cgiDirResolved + path.sep)) return next();
+
+      const ext = path.extname(scriptPath);
+      if (!cgiExts.has(ext)) return next();
+      let scriptStat;
+      try {
+        scriptStat = fs.lstatSync(scriptPath);
+      } catch {
+        return next();
+      }
+      if (!scriptStat.isFile() || scriptStat.isSymbolicLink()) return next();
+
+      const env = buildCgiEnv(req, scriptPath, cgiUrlPath, p);
+      const interpreter = interps[ext];
+      const command = interpreter || scriptPath;
+      const args = interpreter ? [scriptPath] : [];
+      const child = spawn(command, args, { env, cwd: path.dirname(scriptPath), shell: false });
+
+      child.stdin.on('error', (_err) => {});
+      req.pipe(child.stdin);
+
+      res.on('drain', () => child.stdout.resume());
+
+      let headersParsed = false;
+      let rawBuf = '';
+      child.stdout.on('data', (chunk) => {
+        if (headersParsed) {
+          if (!res.write(chunk)) child.stdout.pause();
+        } else {
+          rawBuf += chunk.toString('binary');
+          if (rawBuf.length > 65536) {
+            child.stdout.destroy();
+            child.kill();
+            res.status(500).send('CGI headers too large');
+            return;
+          }
+          const m = /\r?\n\r?\n/.exec(rawBuf);
+          if (m) {
+            const rawHeaders = rawBuf.substring(0, m.index);
+            const bodyStart = Buffer.from(rawBuf.substring(m.index + m[0].length), 'binary');
+            headersParsed = true;
+            res.status(applyCgiHeaders(rawHeaders, res));
+            if (bodyStart.length && !res.write(bodyStart)) child.stdout.pause();
+          }
+        }
+      });
+      child.stdout.on('end', () => {
+        if (headersParsed) {
+          res.end();
+        } else if (!res.headersSent) {
+          res.status(500).send('CGI script produced no output');
+        }
+      });
+      child.stderr.on('data', (data) => console.error(`[cgi] ${scriptPath}: ${data}`));
+      child.on('error', (err) => {
+        console.error(`[cgi] spawn error for ${scriptPath}: ${err.message}`);
+        if (!res.headersSent) res.status(500).send(`CGI error: ${err.message}`);
+      });
+      console.log(`[cgi] ${req.method} ${cgiUrlPath}${req.path} → ${scriptPath}`);
+    });
+  }
+}
+
+function buildFileFilter(allowedTypes) {
+  if (!allowedTypes) return undefined;
+  return (_req, file, cb) => {
+    if (allowedTypes.has(file.mimetype)) cb(null, true);
+    else cb(Object.assign(new Error(`File type not allowed: ${file.mimetype}`), { status: 400 }));
+  };
+}
+
+function handleUploadResponse(req, res) {
+  if (!req.files?.length) return res.status(400).json({ error: 'No files uploaded' });
+  res.json({
+    files: req.files.map((f) => ({ file: f.filename, size: f.size, originalName: f.originalname })),
+  });
+}
+
+function setupUpload(router, siteConfig, configDir) {
+  if (!siteConfig.upload) return;
+  const uploadRaw = siteConfig.upload;
+  const uploadConfigs = Array.isArray(uploadRaw)
+    ? uploadRaw
+    : [typeof uploadRaw === 'string' ? { dir: uploadRaw } : uploadRaw];
+
+  for (const uploadConfig of uploadConfigs) {
+    const uploadUrlPath = uploadConfig.path || '/upload';
+    const uploadDir = path.resolve(configDir, uploadConfig.dir || './uploads');
+    const allowedTypes = uploadConfig.allowedTypes ? new Set(uploadConfig.allowedTypes) : null;
+
+    fs.mkdirSync(uploadDir, { recursive: true });
+
+    const storage = multer.diskStorage({
+      destination: uploadDir,
+      filename: (_req, file, cb) => {
+        const ext = path.extname(file.originalname);
+        const base =
+          path.basename(file.originalname, ext).replaceAll(/[^a-zA-Z0-9_.-]/g, '_') || 'file';
+        cb(null, `${base}-${Date.now()}-${Math.round(Math.random() * 1e9)}${ext}`);
+      },
+    });
+
+    const limits = {};
+    if (uploadConfig.maxFileSize) limits.fileSize = uploadConfig.maxFileSize;
+    if (uploadConfig.maxFiles) limits.files = uploadConfig.maxFiles;
+
+    const uploader = multer({ storage, limits, fileFilter: buildFileFilter(allowedTypes) });
+    const multerMiddleware = uploadConfig.fieldName
+      ? uploader.array(uploadConfig.fieldName)
+      : uploader.any();
+
+    router.post(uploadUrlPath, multerMiddleware, handleUploadResponse);
+    router.use(uploadUrlPath, express.static(uploadDir));
+    console.log(`[upload] POST ${uploadUrlPath} → ${uploadDir}`);
+  }
+}
+
+function setupHotReload(app, portConfigs, p) {
+  const hotReloadEnabled = portConfigs.some((c) => c.hotReload === true);
+  if (!hotReloadEnabled) return;
+
+  const hotReloadClientJs = fs.readFileSync(path.join(__dirname, 'hot-reload-client.js'), 'utf8');
+  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.send(hotReloadClientJs);
+  });
+
+  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)) {
+      const onChange = () => {
+        clearTimeout(reloadTimer);
+        reloadTimer = setTimeout(() => {
+          for (const client of sseClients) client.write('data: reload\n\n');
+        }, 100);
+      };
+      try {
+        fs.watch(absPath, { recursive: true }, onChange);
+      } catch {
+        console.warn(
+          `[hot-reload] recursive watch not supported on this platform, falling back for ${absPath}`,
+        );
+        fs.watch(absPath, onChange);
+      }
+    }
+  }
+  console.log(`[hot-reload] watching ${watchPaths.length} folder(s) on port ${p}`);
+}
+
 function unhandled(res, acceptConfig) {
   const headers = (acceptConfig.headers && Object.keys(acceptConfig.headers)) || [];
   for (const header of headers) res.setHeader(header, acceptConfig.headers[header]);
@@ -358,42 +632,7 @@ const servers = [];
 
 configsByPort.forEach((portConfigs, p) => {
   const app = express();
-  // 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}`);
-  }
+  setupHotReload(app, portConfigs, p);
 
   // Specific hosts first, catch-all last
   const sorted = [
@@ -404,254 +643,32 @@ configsByPort.forEach((portConfigs, p) => {
   sorted.forEach((siteConfig) => {
     const siteHost = siteConfig.host || '*';
     const router = express.Router();
-
     console.log(`[host] ${siteHost} → :${p}`);
-
-    if (siteConfig.logging !== false) {
-      const lc = siteConfig.logging;
-      if (typeof lc === 'object' && lc.file) {
-        const stream = fs.createWriteStream(path.resolve(configDir, lc.file), { flags: 'a' });
-        router.use(morgan(lc.format || 'combined', { stream }));
-      } else {
-        router.use(morgan((typeof lc === 'object' ? lc.format : null) || 'dev'));
-      }
-    }
-
-    if (siteConfig.responseTime) {
-      const opts = typeof siteConfig.responseTime === 'object' ? siteConfig.responseTime : {};
-      router.use(responseTime(opts));
-    }
-
-    if (siteConfig.cors) {
-      const opts = typeof siteConfig.cors === 'object' ? siteConfig.cors : {};
-      router.use(cors(opts));
-    }
-
-    if (siteConfig.compression) {
-      const opts = typeof siteConfig.compression === 'object' ? siteConfig.compression : {};
-      router.use(compression(opts));
-    }
-
-    if (siteConfig.helmet) {
-      const opts = typeof siteConfig.helmet === 'object' ? siteConfig.helmet : {};
-      router.use(helmet(opts));
-    }
-
-    if (siteConfig.favicon) {
-      router.use(favicon(path.resolve(configDir, siteConfig.favicon)));
-    }
-
-    if (siteConfig.healthCheck) {
-      const hcPath =
-        (typeof siteConfig.healthCheck === 'object' && siteConfig.healthCheck.path) ||
-        '/__health__';
-      router.get(hcPath, (_req, res) => {
-        res.json({ status: 'ok', uptime: process.uptime(), timestamp: new Date().toISOString() });
-      });
-    }
-
-    if (siteConfig.rateLimit) {
-      const opts = typeof siteConfig.rateLimit === 'object' ? siteConfig.rateLimit : {};
-      router.use(rateLimit(opts));
-    }
-
-    if (siteConfig.basicAuth) {
-      const opts = typeof siteConfig.basicAuth === 'object' ? siteConfig.basicAuth : {};
-      router.use(basicAuth(opts));
-    }
-
-    if (siteConfig.headers) {
-      router.use((_req, res, next) => {
-        for (const h of Object.keys(siteConfig.headers)) res.setHeader(h, siteConfig.headers[h]);
-        next();
-      });
-    }
-
-    if (siteConfig.redirects) {
-      const redirects = siteConfig.redirects;
-      if (Array.isArray(redirects)) {
-        for (const r of redirects) {
-          router.all(r.from, (_req, res) => res.redirect(r.status || 301, r.to));
-        }
-      } else {
-        for (const [from, to] of Object.entries(redirects)) {
-          const dest = typeof to === 'string' ? to : to.to;
-          const status = typeof to === 'object' ? to.status || 301 : 301;
-          router.all(from, (_req, res) => res.redirect(status, dest));
-        }
-      }
-    }
-
-    if (siteConfig.folders) {
-      addStaticFolder(router, p, null, siteConfig.folders);
-    }
-
-    if (siteConfig.cgi) {
-      const cgiRaw = siteConfig.cgi;
-      const cgiConfigs = Array.isArray(cgiRaw)
-        ? cgiRaw
-        : [typeof cgiRaw === 'string' ? { dir: cgiRaw } : cgiRaw];
-
-      for (const cgiConfig of cgiConfigs) {
-        const cgiUrlPath = cgiConfig.path || '/cgi-bin';
-        const cgiDirResolved = path.resolve(configDir, cgiConfig.dir || './cgi-bin');
-        const cgiExts = new Set(cgiConfig.extensions || ['.cgi', '.pl', '.py', '.sh']);
-        const interps = cgiConfig.interpreters || {};
-
-        router.use(cgiUrlPath, (req, res, next) => {
-          const scriptPath = path.resolve(path.join(cgiDirResolved, req.path));
-          if (!scriptPath.startsWith(cgiDirResolved + path.sep)) return next();
-
-          const ext = path.extname(scriptPath);
-          if (!cgiExts.has(ext) || !fs.existsSync(scriptPath)) return next();
-
-          const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
-          const env = {
-            ...process.env,
-            GATEWAY_INTERFACE: 'CGI/1.1',
-            SERVER_PROTOCOL: 'HTTP/1.1',
-            SERVER_SOFTWARE: 'express-reverse-proxy',
-            REQUEST_METHOD: req.method.toUpperCase(),
-            SCRIPT_FILENAME: scriptPath,
-            SCRIPT_NAME: cgiUrlPath + req.path,
-            PATH_INFO: '',
-            QUERY_STRING: url.search ? url.search.slice(1) : '',
-            REMOTE_ADDR: req.ip || '127.0.0.1',
-            CONTENT_TYPE: req.headers['content-type'] || '',
-            CONTENT_LENGTH: req.headers['content-length'] || '0',
-            SERVER_NAME: req.hostname || 'localhost',
-            SERVER_PORT: String(p),
-          };
-          for (const [k, v] of Object.entries(req.headers)) {
-            env[`HTTP_${k.toUpperCase().replace(/-/g, '_')}`] = Array.isArray(v) ? v.join(', ') : v;
-          }
-
-          const interpreter = interps[ext];
-          const command = interpreter || scriptPath;
-          const args = interpreter ? [scriptPath] : [];
-          const child = spawn(command, args, { env, cwd: path.dirname(scriptPath) });
-
-          child.stdin.on('error', (_err) => {});
-          req.pipe(child.stdin);
-
-          let headersParsed = false;
-          let rawBuf = '';
-          child.stdout.on('data', (chunk) => {
-            if (!headersParsed) {
-              rawBuf += chunk.toString('binary');
-              const m = /\r?\n\r?\n/.exec(rawBuf);
-              if (m) {
-                const rawHeaders = rawBuf.substring(0, m.index);
-                const bodyStart = Buffer.from(rawBuf.substring(m.index + m[0].length), 'binary');
-                headersParsed = true;
-                let statusCode = 200;
-                for (const line of rawHeaders.split(/\r?\n/)) {
-                  const colon = line.indexOf(':');
-                  if (colon === -1) continue;
-                  const name = line.substring(0, colon).trim();
-                  const value = line.substring(colon + 1).trim();
-                  if (name.toLowerCase() === 'status') {
-                    statusCode = Number.parseInt(value, 10) || 200;
-                  } else {
-                    res.setHeader(name, value);
-                  }
-                }
-                res.status(statusCode);
-                if (bodyStart.length) res.write(bodyStart);
-              }
-            } else {
-              res.write(chunk);
-            }
-          });
-          child.stdout.on('end', () => {
-            if (!headersParsed) res.status(500).send('CGI script produced no output');
-            else res.end();
-          });
-          child.stderr.on('data', (data) => console.error(`[cgi] ${scriptPath}: ${data}`));
-          child.on('error', (err) => {
-            console.error(`[cgi] spawn error for ${scriptPath}: ${err.message}`);
-            if (!res.headersSent) res.status(500).send(`CGI error: ${err.message}`);
-          });
-          console.log(`[cgi] ${req.method} ${cgiUrlPath}${req.path} → ${scriptPath}`);
-        });
-      }
-    }
-
-    if (siteConfig.upload) {
-      const uploadRaw = siteConfig.upload;
-      const uploadConfigs = Array.isArray(uploadRaw)
-        ? uploadRaw
-        : [typeof uploadRaw === 'string' ? { dir: uploadRaw } : uploadRaw];
-
-      for (const uploadConfig of uploadConfigs) {
-        const uploadUrlPath = uploadConfig.path || '/upload';
-        const uploadDir = path.resolve(configDir, uploadConfig.dir || './uploads');
-        const allowedTypes = uploadConfig.allowedTypes ? new Set(uploadConfig.allowedTypes) : null;
-
-        fs.mkdirSync(uploadDir, { recursive: true });
-
-        const storage = multer.diskStorage({
-          destination: uploadDir,
-          filename: (_req, file, cb) => {
-            const ext = path.extname(file.originalname);
-            const base = path.basename(file.originalname, ext).replace(/[^a-zA-Z0-9_.-]/g, '_');
-            cb(null, `${base}-${Date.now()}-${Math.round(Math.random() * 1e9)}${ext}`);
-          },
-        });
-
-        const fileFilter = allowedTypes
-          ? (_req, file, cb) => {
-              if (allowedTypes.has(file.mimetype)) cb(null, true);
-              else
-                cb(
-                  Object.assign(new Error(`File type not allowed: ${file.mimetype}`), {
-                    status: 400,
-                  }),
-                );
-            }
-          : undefined;
-
-        const limits = {};
-        if (uploadConfig.maxFileSize) limits.fileSize = uploadConfig.maxFileSize;
-        if (uploadConfig.maxFiles) limits.files = uploadConfig.maxFiles;
-
-        const uploader = multer({ storage, limits, fileFilter });
-        const multerMiddleware = uploadConfig.fieldName
-          ? uploader.array(uploadConfig.fieldName)
-          : uploader.any();
-
-        router.post(uploadUrlPath, multerMiddleware, (req, res) => {
-          if (!req.files?.length) return res.status(400).json({ error: 'No files uploaded' });
-          res.json({
-            files: req.files.map((f) => ({
-              file: f.filename,
-              size: f.size,
-              originalName: f.originalname,
-            })),
-          });
-        });
-
-        router.use(uploadUrlPath, express.static(uploadDir));
-        console.log(`[upload] POST ${uploadUrlPath} → ${uploadDir}`);
-      }
-    }
-
-    if (siteConfig.proxy) {
-      addProxy(router, p, null, siteConfig.proxy);
-    }
-
+    configureLogging(router, siteConfig, configDir);
+    configureMiddleware(router, siteConfig);
+    if (siteConfig.redirects) setupRedirects(router, siteConfig.redirects);
+    if (siteConfig.folders) addStaticFolder(router, p, null, siteConfig.folders);
+    setupCgi(router, siteConfig, p, configDir);
+    setupUpload(router, siteConfig, configDir);
+    if (siteConfig.proxy) addProxy(router, p, null, siteConfig.proxy);
     if (siteConfig.unhandled) {
-      router.use((req, res, _next) => {
-        Object.keys(siteConfig.unhandled).forEach((acceptName) => {
+      router.use((req, res, next) => {
+        const entries = Object.entries(siteConfig.unhandled);
+        for (const [acceptName, acceptConfig] of entries) {
+          if (acceptName && acceptName !== '*' && acceptName !== '**' && req.accepts(acceptName)) {
+            unhandled(res, acceptConfig);
+            return;
+          }
+        }
+        for (const [acceptName, acceptConfig] of entries) {
           if (!acceptName || acceptName === '*' || acceptName === '**') {
-            unhandled(res, siteConfig.unhandled[acceptName]);
-          } else if (req.accepts(acceptName)) {
-            unhandled(res, siteConfig.unhandled[acceptName]);
+            unhandled(res, acceptConfig);
+            return;
           }
-        });
+        }
+        next();
       });
     }
-
     if (siteHost === '*') {
       app.use(router);
     } else {