yxorp 0.2.2 → 0.2.4

package/README.md

@@ -264,6 +264,14 @@ For more advanced patterns, see the [path-to-regexp documentation](https://githu
 
 ---
 
+### A Note on Script Security
+
+Mock and rewrite scripts (`"script": "./path/to/file.js"`) are loaded with Node's `require()` and run with the same privileges as Yxorp itself — full filesystem, network, and process access, with no sandboxing.
+
+Only point Yxorp at config files (and the scripts they reference) that you trust, the same way you'd treat any other local Node script. Don't load a config from an untrusted source.
+
+---
+
 ## Full Example
 
 Here's a complete config showing all features in action:

package/dist/index.js

@@ -86,6 +86,7 @@ const configWatcher = (0, config_watcher_1.watchConfig)(configPath, (newConfig)
     logger.info('Config reloaded');
 }, (e) => logger.error(`Config reload failed: ${e.message || e}`));
 // --- Graceful shutdown ---
+const SHUTDOWN_TIMEOUT_MS = 5000;
 let shuttingDown = false;
 function shutdown(signal) {
     if (shuttingDown)
@@ -93,7 +94,17 @@ function shutdown(signal) {
     shuttingDown = true;
     logger.info(`Received ${signal}, shutting down...`);
     configWatcher.close();
+    // server.close()'s callback only fires once every open connection is
+    // closed — keep-alive HTTP sockets and proxied WebSocket connections
+    // (proxyOptions has `ws: true`) can keep it pending indefinitely. Force
+    // an exit after a grace period so a stuck connection can't hang the process.
+    const forceExitTimer = setTimeout(() => {
+        logger.error(`Graceful shutdown timed out after ${SHUTDOWN_TIMEOUT_MS}ms — forcing exit`);
+        process.exit(1);
+    }, SHUTDOWN_TIMEOUT_MS);
+    forceExitTimer.unref();
     server.close(() => {
+        clearTimeout(forceExitTimer);
         process.exit(0);
     });
 }

package/dist/middleware/bootstrap.middleware.d.ts

@@ -1,14 +1,15 @@
-import { IncomingMessage } from 'http';
+/// <reference types="node" />
+import { IncomingMessage, ServerResponse } from 'http';
 import { Middleware } from '../services/pipeline.service';
 import { RewriteRulesMatcher } from '../services/rules-matchers/rewrite-rules-matcher.service';
 import { MockRulesMatcher } from '../services/rules-matchers/mock-rules-matcher.service';
 import { LoggerService } from '../services/logger.service';
-export declare class BootstrapMiddleware implements Middleware<[req: IncomingMessage, res: any]> {
+export declare class BootstrapMiddleware implements Middleware<[req: IncomingMessage, res: ServerResponse]> {
     private rewriteRulesMatcher;
     private mockRulesMatcher;
     private logger;
     constructor(rewriteRulesMatcher: RewriteRulesMatcher, mockRulesMatcher: MockRulesMatcher, logger: LoggerService);
-    use(req: IncomingMessage, _res: any, next: () => void): void;
+    use(req: IncomingMessage, _res: ServerResponse, next: () => void): void;
     private setRewriteRule;
     private setMockRule;
     private setQueryParams;

package/dist/middleware/bootstrap.middleware.js

@@ -27,26 +27,22 @@ class BootstrapMiddleware {
         if (!req.url || !req.method) {
             return;
         }
-        const rewriteRule = this.rewriteRulesMatcher.match(req.url, req.method);
-        if (rewriteRule) {
-            req.rewriteRule = rewriteRule;
-            const rewriteRuleParams = this.rewriteRulesMatcher.params(req.url, rewriteRule);
-            if (rewriteRuleParams) {
-                req.rewriteRuleParams = rewriteRuleParams || {};
-            }
+        // matchWithParams() finds the rule and decodes its path params in a single
+        // pass — match() + params() back to back would compile/run path-to-regexp twice.
+        const matched = this.rewriteRulesMatcher.matchWithParams(req.url, req.method);
+        if (matched) {
+            req.rewriteRule = matched.rule;
+            req.rewriteRuleParams = matched.params || {};
         }
     }
     setMockRule(req) {
         if (!req.url || !req.method) {
             return;
         }
-        const mockRule = this.mockRulesMatcher.match(req.url, req.method);
-        if (mockRule) {
-            req.mockRule = mockRule;
-            const mockRuleParams = this.mockRulesMatcher.params(req.url, mockRule);
-            if (mockRuleParams) {
-                req.mockRuleParams = mockRuleParams || {};
-            }
+        const matched = this.mockRulesMatcher.matchWithParams(req.url, req.method);
+        if (matched) {
+            req.mockRule = matched.rule;
+            req.mockRuleParams = matched.params || {};
         }
     }
     setQueryParams(req) {

package/dist/middleware/mock.middleware.js

@@ -7,7 +7,7 @@ exports.MockMiddleware = void 0;
 const mime_1 = __importDefault(require("mime"));
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const request_timing_1 = require("../utils/request-timing");
+const access_log_1 = require("../utils/access-log");
 class MockMiddleware {
     constructor(logger) {
         this.logger = logger;
@@ -23,13 +23,22 @@ class MockMiddleware {
                 const fullPath = path_1.default.resolve(mockRule.script);
                 delete require.cache[require.resolve(fullPath)];
                 const handler = require(fullPath);
-                if (typeof handler === 'function') {
-                    await handler(req, res);
-                    if (!res.headersSent) {
-                        res.setHeader('content-type', 'application/json');
-                    }
+                if (typeof handler !== 'function') {
+                    // A script that doesn't export a function (e.g. `exports.handler = ...`
+                    // instead of `module.exports = ...`) would otherwise leave the request
+                    // hanging forever — respond with a clear error instead.
+                    res.statusCode = 500;
+                    res.setHeader('content-type', 'application/json');
+                    res.end(JSON.stringify({ error: `Mock script "${mockRule.script}" does not export a function` }));
+                    this.logger.error(`Mock script "${fullPath}" does not export a function (module.exports = (req, res) => {...})`);
+                    this.logger.info((0, access_log_1.formatAccessLog)('mock', res.statusCode, req));
+                    return;
                 }
-                this.logger.info(`mock         ${res.statusCode || 200} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                await handler(req, res);
+                if (!res.headersSent) {
+                    res.setHeader('content-type', 'application/json');
+                }
+                this.logger.info((0, access_log_1.formatAccessLog)('mock', res.statusCode || 200, req));
                 return;
             }
             if ('file' in mockRule) {
@@ -41,13 +50,23 @@ class MockMiddleware {
                 }
                 res.setHeader('content-length', file.length);
                 res.end(file);
-                this.logger.info(`mock         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                this.logger.info((0, access_log_1.formatAccessLog)('mock', res.statusCode, req));
                 return;
             }
             next();
         }
         catch (e) {
             this.logger.error(e);
+            // If the script handler already wrote (part of) a response before throwing,
+            // calling next() would send the request into ProxyMiddleware/httpProxy.web,
+            // which would try to write to an already-finished response.
+            if (res.headersSent) {
+                this.logger.info((0, access_log_1.formatAccessLog)('mock', res.statusCode, req));
+                if (!res.writableEnded) {
+                    res.end();
+                }
+                return;
+            }
             next();
         }
     }

package/dist/middleware/proxy.middleware.js

@@ -11,16 +11,33 @@ class ProxyMiddleware {
     use(req, res) {
         const url = req.url || '';
         const proxyOptions = this.config.get().proxyOptions;
-        const remoteRule = this.remoteRulesMatcher.match(url);
-        const target = remoteRule
-            ? this.remoteRulesMatcher.toPath(url, remoteRule)
-            : undefined;
+        let target;
+        try {
+            const remoteRule = this.remoteRulesMatcher.match(url);
+            target = remoteRule
+                ? this.remoteRulesMatcher.toPath(url, remoteRule)
+                : undefined;
+        }
+        catch (e) {
+            // A malformed `remoteRules[].path` pattern would otherwise throw
+            // synchronously here on every request — fall back to the default target.
+            this.logger.error(e);
+        }
         const options = {
             ...proxyOptions,
             prependPath: !target,
             target: target || proxyOptions.target,
         };
-        this.httpProxy.web(req, res, options).catch((error) => this.logger.error(error));
+        this.httpProxy.web(req, res, options).catch((error) => {
+            // httpxy rejects web()'s promise when the proxy has no 'error' listener
+            // (e.g. target ECONNREFUSED/DNS failure) — without this, the client
+            // would otherwise hang forever waiting for a response that never comes.
+            this.logger.error(error);
+            if (!res.headersSent) {
+                res.statusCode = 502;
+                res.end();
+            }
+        });
     }
 }
 exports.ProxyMiddleware = ProxyMiddleware;

package/dist/middleware/proxyRes.middleware.js

@@ -1,16 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProxyResMiddleware = void 0;
-const request_timing_1 = require("../utils/request-timing");
+const access_log_1 = require("../utils/access-log");
+const headers_1 = require("../utils/headers");
 class ProxyResMiddleware {
     constructor(logger) {
         this.logger = logger;
     }
     use(proxyRes, req, res) {
         try {
-            // Skip transfer-encoding since we reconstruct the body with known length
+            // Hop-by-hop headers (incl. transfer-encoding, since we reconstruct the
+            // body with a known length) must not be forwarded to the client.
             for (let key in proxyRes.headers) {
-                if (key === 'transfer-encoding')
+                if ((0, headers_1.isHopByHopHeader)(key, proxyRes.headers))
                     continue;
                 res.setHeader(key, proxyRes.headers[key]);
             }
@@ -20,10 +22,11 @@ class ProxyResMiddleware {
             res.removeHeader('content-length');
             res.setHeader('content-length', response.length);
             res.end(response);
-            // RewriteMiddleware already logs rewritten responses — log here only for plain pass-through,
-            // so every proxied request gets exactly one log line.
-            if (!req.rewriteRule) {
-                this.logger.info(`proxy         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+            // RewriteMiddleware already logs rewritten responses (success AND failure —
+            // it sets req.rewriteLogged in both cases) — log here only for plain
+            // pass-through, so every proxied request gets exactly one log line.
+            if (!req.rewriteLogged) {
+                this.logger.info((0, access_log_1.formatAccessLog)('proxy', res.statusCode, req));
             }
         }
         catch (e) {

package/dist/middleware/rawBody.middleware.d.ts

@@ -1,6 +1,9 @@
 /// <reference types="node" />
 import { IncomingMessage, ServerResponse } from 'http';
 import { Middleware } from '../services/pipeline.service';
+import { LoggerService } from '../services/logger.service';
 export declare class RawBodyMiddleware implements Middleware<[proxyRes: IncomingMessage, req: IncomingMessage, res: ServerResponse]> {
-    use(proxyRes: IncomingMessage, _req: IncomingMessage, _res: ServerResponse, next: () => void): Promise<void>;
+    private logger;
+    constructor(logger: LoggerService);
+    use(proxyRes: IncomingMessage, _req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void>;
 }

package/dist/middleware/rawBody.middleware.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RawBodyMiddleware = void 0;
 class RawBodyMiddleware {
-    use(proxyRes, _req, _res, next) {
-        return new Promise((resolve, reject) => {
+    constructor(logger) {
+        this.logger = logger;
+    }
+    use(proxyRes, _req, res, next) {
+        return new Promise((resolve) => {
             const body = [];
             proxyRes.on('data', (chunk) => {
                 body.push(chunk);
@@ -14,9 +17,17 @@ class RawBodyMiddleware {
                 resolve();
             });
             proxyRes.on('error', (err) => {
-                proxyRes.rawBody = Buffer.concat(body);
-                next();
-                reject(err);
+                // The upstream response stream broke mid-flight — the body we have is
+                // incomplete/unreliable. Don't continue through Rewrite/ProxyRes with
+                // it (that could produce a broken-but-200-looking response); send a
+                // clean error response instead and resolve cleanly so this doesn't
+                // surface as an unhandled rejection racing with a normal response.
+                this.logger.error(err);
+                if (!res.headersSent) {
+                    res.statusCode = 502;
+                    res.end();
+                }
+                resolve();
             });
         });
     }

package/dist/middleware/rewrite.middleware.d.ts

@@ -6,4 +6,11 @@ export declare class RewriteMiddleware implements Middleware<[proxyRes: Incoming
     private logger;
     constructor(logger: LoggerService);
     use(proxyRes: IncomingMessage, req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void>;
+    /**
+     * Logs the access line for a rewritten response and marks the request as
+     * logged, so ProxyResMiddleware (which would otherwise also log plain
+     * pass-through responses) knows to stay silent — including on the error path
+     * above, where the rewrite itself failed but the response still went out.
+     */
+    private logRewrite;
 }

package/dist/middleware/rewrite.middleware.js

@@ -7,7 +7,7 @@ exports.RewriteMiddleware = void 0;
 const http_encoding_1 = require("http-encoding");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const request_timing_1 = require("../utils/request-timing");
+const access_log_1 = require("../utils/access-log");
 class RewriteMiddleware {
     constructor(logger) {
         this.logger = logger;
@@ -30,7 +30,7 @@ class RewriteMiddleware {
                     const rewritedResponse = await handler(encodedResponse, proxyRes, req, res);
                     proxyRes.rawBody = await (0, http_encoding_1.encodeBuffer)(rewritedResponse, encoding);
                 }
-                this.logger.info(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                this.logRewrite(req, proxyRes);
                 next();
                 return;
             }
@@ -40,7 +40,7 @@ class RewriteMiddleware {
                 if (rewriteRule.statusCode) {
                     proxyRes.statusCode = rewriteRule.statusCode;
                 }
-                this.logger.info(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                this.logRewrite(req, proxyRes);
                 next();
                 return;
             }
@@ -48,8 +48,21 @@ class RewriteMiddleware {
         }
         catch (e) {
             this.logger.error(e);
+            // Even on failure the response still goes out via ProxyResMiddleware —
+            // make sure the request still gets exactly one access-log line.
+            this.logRewrite(req, proxyRes);
             next();
         }
     }
+    /**
+     * Logs the access line for a rewritten response and marks the request as
+     * logged, so ProxyResMiddleware (which would otherwise also log plain
+     * pass-through responses) knows to stay silent — including on the error path
+     * above, where the rewrite itself failed but the response still went out.
+     */
+    logRewrite(req, proxyRes) {
+        req.rewriteLogged = true;
+        this.logger.info((0, access_log_1.formatAccessLog)('rewrite', proxyRes.statusCode, req));
+    }
 }
 exports.RewriteMiddleware = RewriteMiddleware;

package/dist/middleware/static.middleware.d.ts

@@ -8,5 +8,27 @@ export declare class StaticMiddleware implements Middleware<[req: IncomingMessag
     private logger;
     constructor(config: Config, logger: LoggerService);
     use(req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void>;
-    private readdir;
+    /**
+     * Resolves a request URL path to an actual file on disk under the rule's
+     * directory — without enumerating the whole directory tree on every request
+     * (the previous implementation did a full recursive `readdir` per request,
+     * the most expensive thing on this hot path).
+     *
+     * Fast path: build the candidate path directly from the URL and `fs.stat`
+     * it — this covers the overwhelming majority of requests (correct case,
+     * matches exactly) with zero directory listings.
+     *
+     * Fallback (only when the fast path misses AND `caseInsensitive` is set):
+     * walk down the path segment by segment, listing only the relevant
+     * directory at each level and matching case-insensitively — far cheaper
+     * than enumerating the entire tree just to find one file.
+     */
+    private resolveFile;
+    /**
+     * Confirms `filePath` is a regular file AND, after resolving symlinks on
+     * both sides, still lives inside `directory` — a symlink placed under
+     * `directory` that points outside it must not be served.
+     */
+    private isFile;
+    private findCaseInsensitive;
 }

package/dist/middleware/static.middleware.js

@@ -7,7 +7,7 @@ exports.StaticMiddleware = void 0;
 const path_1 = __importDefault(require("path"));
 const promises_1 = __importDefault(require("fs/promises"));
 const mime_1 = __importDefault(require("mime"));
-const request_timing_1 = require("../utils/request-timing");
+const access_log_1 = require("../utils/access-log");
 class StaticMiddleware {
     constructor(config, logger) {
         this.config = config;
@@ -25,58 +25,102 @@ class StaticMiddleware {
                 next();
                 return;
             }
-            const pathToDirectory = path_1.default.resolve(currentStaticRule.directory);
-            const dirents = await this.readdir(pathToDirectory);
-            const filePath = dirents
-                .filter(dirent => !dirent.isDirectory())
-                .map(dirent => ({
-                urlPath: path_1.default.join(currentStaticRule.path, path_1.default.join(dirent.path, dirent.name).replace(pathToDirectory, '')).replace(/\\/g, '/'),
-                path: path_1.default.join(dirent.path, dirent.name).replace(/\\/g, '/'),
-            }))
-                .filter(dirent => {
-                const pathname = path_1.default.extname(urlPath)
-                    ? urlPath
-                    : path_1.default.join(urlPath, currentStaticRule.directoryIndex || '').replace(/\\/g, '/');
-                if (currentStaticRule.caseInsensitive) {
-                    return dirent.urlPath.toLocaleLowerCase() === pathname.toLowerCase();
-                }
-                else {
-                    return dirent.urlPath === pathname;
-                }
-            })
-                .map(dirent => dirent.path)[0];
+            const filePath = await this.resolveFile(currentStaticRule, urlPath);
             if (!filePath) {
                 next();
                 return;
             }
-            const file = await promises_1.default.readFile(path_1.default.resolve(filePath));
-            const mimeType = mime_1.default.getType(path_1.default.resolve(filePath));
+            const file = await promises_1.default.readFile(filePath);
+            const mimeType = mime_1.default.getType(filePath);
             if (mimeType) {
                 res.setHeader('content-type', mimeType);
             }
             res.setHeader('content-length', file.length);
             res.end(file);
-            this.logger.info(`static        ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+            this.logger.info((0, access_log_1.formatAccessLog)('static', res.statusCode, req));
         }
         catch (e) {
             this.logger.error(e);
             next();
         }
     }
-    async readdir(pathname, subpathname) {
-        const files = [];
-        const fullpath = path_1.default.join(pathname, subpathname || '');
-        const dirents = await promises_1.default.readdir(fullpath, {
-            withFileTypes: true,
-        });
-        for (let dirent of dirents) {
-            dirent.path = fullpath;
-            files.push(dirent);
-            if (dirent.isDirectory()) {
-                files.push(...await this.readdir(fullpath, dirent.name));
+    /**
+     * Resolves a request URL path to an actual file on disk under the rule's
+     * directory — without enumerating the whole directory tree on every request
+     * (the previous implementation did a full recursive `readdir` per request,
+     * the most expensive thing on this hot path).
+     *
+     * Fast path: build the candidate path directly from the URL and `fs.stat`
+     * it — this covers the overwhelming majority of requests (correct case,
+     * matches exactly) with zero directory listings.
+     *
+     * Fallback (only when the fast path misses AND `caseInsensitive` is set):
+     * walk down the path segment by segment, listing only the relevant
+     * directory at each level and matching case-insensitively — far cheaper
+     * than enumerating the entire tree just to find one file.
+     */
+    async resolveFile(rule, urlPath) {
+        const directory = path_1.default.resolve(rule.directory);
+        const relativeUrlPath = urlPath.slice(rule.path.length);
+        const pathname = path_1.default.extname(relativeUrlPath)
+            ? relativeUrlPath
+            : path_1.default.join(relativeUrlPath, rule.directoryIndex || '');
+        const segments = pathname.split(/[\\/]+/).filter(Boolean);
+        // Defense in depth — `new URL()` already normalizes `..` segments out of
+        // urlPath, but reject anything that could still escape `directory`.
+        if (segments.includes('..')) {
+            return undefined;
+        }
+        if (segments.length === 0) {
+            return undefined;
+        }
+        const exactPath = path_1.default.join(directory, ...segments);
+        if (await this.isFile(exactPath, directory)) {
+            return exactPath;
+        }
+        if (!rule.caseInsensitive) {
+            return undefined;
+        }
+        let current = directory;
+        for (const segment of segments) {
+            const match = await this.findCaseInsensitive(current, segment);
+            if (!match) {
+                return undefined;
             }
+            current = path_1.default.join(current, match);
+        }
+        return (await this.isFile(current, directory)) ? current : undefined;
+    }
+    /**
+     * Confirms `filePath` is a regular file AND, after resolving symlinks on
+     * both sides, still lives inside `directory` — a symlink placed under
+     * `directory` that points outside it must not be served.
+     */
+    async isFile(filePath, directory) {
+        try {
+            const stats = await promises_1.default.stat(filePath);
+            if (!stats.isFile()) {
+                return false;
+            }
+            const [realFile, realDirectory] = await Promise.all([
+                promises_1.default.realpath(filePath),
+                promises_1.default.realpath(directory),
+            ]);
+            const relative = path_1.default.relative(realDirectory, realFile);
+            return !relative.startsWith('..') && !path_1.default.isAbsolute(relative);
+        }
+        catch {
+            return false;
+        }
+    }
+    async findCaseInsensitive(directory, name) {
+        try {
+            const entries = await promises_1.default.readdir(directory);
+            return entries.find(entry => entry.toLowerCase() === name.toLowerCase());
+        }
+        catch {
+            return undefined;
         }
-        return files;
     }
 }
 exports.StaticMiddleware = StaticMiddleware;

package/dist/services/cli-overrides.js

@@ -1,9 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyCliOverrides = void 0;
+/**
+ * Reads a flag's value from argv, supporting both `--flag value` and
+ * `--flag=value` forms. For the space-separated form, a following token that
+ * itself looks like a flag (starts with `--`) is NOT treated as this flag's
+ * value — `--port --target http://x` should leave `--port` unset rather than
+ * swallowing `--target` as its value.
+ */
 function getArgValue(argv, flag) {
-    const index = argv.indexOf(flag);
-    return index !== -1 && index + 1 < argv.length ? argv[index + 1] : undefined;
+    const prefix = `${flag}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith(prefix)) {
+            return arg.slice(prefix.length);
+        }
+        if (arg === flag) {
+            const next = argv[i + 1];
+            return next !== undefined && !next.startsWith('--') ? next : undefined;
+        }
+    }
+    return undefined;
 }
 /**
  * Applies `--port`/`--target` CLI flags on top of a resolved config, without

package/dist/services/config-validator.d.ts

@@ -4,6 +4,7 @@
  *
  * Intentionally permissive — it only checks the shape of fields that would
  * otherwise cause confusing crashes deeper in the pipeline (e.g. a missing
- * `target` blowing up inside httpxy with an opaque stack trace).
+ * `target` blowing up inside httpxy with an opaque stack trace, or a bad
+ * `path` pattern throwing synchronously inside path-to-regexp's `match()`).
  */
 export declare function validateConfig(config: any): string[];

package/dist/services/config-validator.js

@@ -1,14 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateConfig = void 0;
+const path_to_regexp_1 = require("path-to-regexp");
 const RULE_ARRAYS = ['remoteRules', 'staticRules', 'mockRules', 'rewriteRules'];
+const MAX_PORT = 65535;
 /**
  * Validates a parsed config object and returns a list of human-readable
  * error messages. An empty array means the config is valid.
  *
  * Intentionally permissive — it only checks the shape of fields that would
  * otherwise cause confusing crashes deeper in the pipeline (e.g. a missing
- * `target` blowing up inside httpxy with an opaque stack trace).
+ * `target` blowing up inside httpxy with an opaque stack trace, or a bad
+ * `path` pattern throwing synchronously inside path-to-regexp's `match()`).
  */
 function validateConfig(config) {
     const errors = [];
@@ -19,20 +22,95 @@ function validateConfig(config) {
         errors.push('"target" is required and must be a non-empty string (e.g. "https://api.example.com")');
     }
     const { proxyPort } = config;
-    const isValidPort = (typeof proxyPort === 'number' && Number.isInteger(proxyPort) && proxyPort >= 0) ||
-        (typeof proxyPort === 'string' && proxyPort.trim() !== '' && Number.isInteger(Number(proxyPort)));
+    const isValidPort = (typeof proxyPort === 'number' && Number.isInteger(proxyPort) && proxyPort >= 0 && proxyPort <= MAX_PORT) ||
+        (typeof proxyPort === 'string' && proxyPort.trim() !== '' && Number.isInteger(Number(proxyPort)) && Number(proxyPort) >= 0 && Number(proxyPort) <= MAX_PORT);
     if (!isValidPort) {
-        errors.push('"proxyPort" is required and must be a number or numeric string (e.g. 3000)');
+        errors.push(`"proxyPort" is required and must be a number or numeric string between 0 and ${MAX_PORT} (e.g. 3000)`);
     }
     if (config.proxyHeaders !== undefined &&
         (typeof config.proxyHeaders !== 'object' || config.proxyHeaders === null || Array.isArray(config.proxyHeaders))) {
         errors.push('"proxyHeaders" must be an object of string key-value pairs');
     }
     for (const key of RULE_ARRAYS) {
-        if (config[key] !== undefined && !Array.isArray(config[key])) {
+        const rules = config[key];
+        if (rules === undefined) {
+            continue;
+        }
+        if (!Array.isArray(rules)) {
             errors.push(`"${key}" must be an array`);
+            continue;
         }
+        rules.forEach((rule, index) => {
+            errors.push(...validateRule(key, rule, index));
+        });
     }
     return errors;
 }
 exports.validateConfig = validateConfig;
+function validateRule(key, rule, index) {
+    const errors = [];
+    const label = `"${key}[${index}]"`;
+    if (!rule || typeof rule !== 'object' || Array.isArray(rule)) {
+        return [`${label} must be an object`];
+    }
+    if (typeof rule.path !== 'string' || !rule.path.trim()) {
+        errors.push(`${label} is missing a non-empty "path" string`);
+    }
+    else {
+        const pathError = validatePathPattern(rule.path);
+        if (pathError) {
+            errors.push(`${label} has an invalid "path" pattern: ${pathError}`);
+        }
+    }
+    switch (key) {
+        case 'remoteRules':
+            if (typeof rule.target !== 'string' || !rule.target.trim()) {
+                errors.push(`${label} is missing a non-empty "target" string`);
+            }
+            break;
+        case 'staticRules':
+            if (typeof rule.directory !== 'string' || !rule.directory.trim()) {
+                errors.push(`${label} is missing a non-empty "directory" string`);
+            }
+            break;
+        case 'mockRules':
+        case 'rewriteRules':
+            if (typeof rule.method !== 'string' || !rule.method.trim()) {
+                errors.push(`${label} is missing a non-empty "method" string`);
+            }
+            errors.push(...validateFileOrScriptRule(label, rule));
+            break;
+    }
+    return errors;
+}
+function validateFileOrScriptRule(label, rule) {
+    const hasFile = 'file' in rule;
+    const hasScript = 'script' in rule;
+    if (hasFile && hasScript) {
+        return [`${label} must declare only one of "file" or "script", not both`];
+    }
+    if (!hasFile && !hasScript) {
+        return [`${label} must declare either "file" or "script"`];
+    }
+    if (hasFile && (typeof rule.file !== 'string' || !rule.file.trim())) {
+        return [`${label} has a "file" that must be a non-empty string`];
+    }
+    if (hasScript && (typeof rule.script !== 'string' || !rule.script.trim())) {
+        return [`${label} has a "script" that must be a non-empty string`];
+    }
+    return [];
+}
+/**
+ * Compiles a path-to-regexp pattern to catch malformed patterns at
+ * config-load/reload time, before they reach the rule matchers (where they'd
+ * otherwise throw synchronously on every matching request).
+ */
+function validatePathPattern(path) {
+    try {
+        (0, path_to_regexp_1.match)(path);
+        return undefined;
+    }
+    catch (e) {
+        return (e === null || e === void 0 ? void 0 : e.message) || String(e);
+    }
+}

package/dist/services/config-watcher.js

@@ -5,9 +5,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.watchConfig = void 0;
 const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 function watchConfig(configPath, onReload, onError) {
+    const dir = path_1.default.dirname(configPath);
+    const filename = path_1.default.basename(configPath);
     let debounceTimer = null;
-    return fs_1.default.watch(configPath, () => {
+    // Watch the parent directory rather than the file itself — editors that
+    // save via atomic rename (vim, etc.) replace the inode, after which
+    // fs.watch on the old file path stops firing.
+    return fs_1.default.watch(dir, (_eventType, changedFile) => {
+        if (changedFile && changedFile !== filename)
+            return;
         if (debounceTimer)
             return;
         debounceTimer = setTimeout(() => {

package/dist/services/config.service.d.ts

@@ -1,6 +1,6 @@
 import { YxorpConfig } from '../types/yxorp-config';
 export declare class Config {
-    private config;
+    private config?;
     set(config: YxorpConfig): void;
     get(): YxorpConfig;
 }

package/dist/services/config.service.js

@@ -6,6 +6,9 @@ class Config {
         this.config = config;
     }
     get() {
+        if (!this.config) {
+            throw new Error('Config has not been initialized — call set() before get()');
+        }
         return this.config;
     }
 }

package/dist/services/http-proxy.service.d.ts

@@ -2,13 +2,14 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { IncomingMessage, ServerResponse } from 'http';
+import { ProxyServer } from 'httpxy';
 import { Pipeline } from './pipeline.service';
 export declare class HttpProxy {
     private pipeline;
-    readonly on: (...args: any[]) => any;
+    readonly on: ProxyServer<IncomingMessage, ServerResponse>['on'];
     private proxy;
     constructor(pipeline: Pipeline<[proxyRes: IncomingMessage, req: IncomingMessage, res: ServerResponse]>);
     execute: (args_0: IncomingMessage, args_1: IncomingMessage, args_2: ServerResponse<IncomingMessage>) => Promise<void>;
-    web(req: IncomingMessage, res: ServerResponse, options?: Record<string, any>): any;
-    ws(req: IncomingMessage, socket: any, options: Record<string, any>, head?: Buffer): any;
+    web(req: IncomingMessage, res: ServerResponse, options?: Record<string, any>): Promise<void>;
+    ws(req: IncomingMessage, socket: any, options: Record<string, any>, head?: Buffer): Promise<void>;
 }

package/dist/services/http-server.service.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="node" />
 import { IncomingMessage, Server, ServerResponse } from 'http';
 import { Pipeline } from './pipeline.service';
+import { LoggerService } from './logger.service';
 export declare class HttpServer {
     private pipeline;
+    private logger;
     readonly use: Pipeline<[IncomingMessage, ServerResponse]>['use'];
     readonly on: Server['on'];
     readonly addListener: Server['addListener'];
@@ -11,5 +13,5 @@ export declare class HttpServer {
     readonly close: Server['close'];
     readonly address: Server['address'];
     private readonly server;
-    constructor(pipeline: Pipeline<[req: IncomingMessage, res: ServerResponse]>);
+    constructor(pipeline: Pipeline<[req: IncomingMessage, res: ServerResponse]>, logger: LoggerService);
 }

package/dist/services/http-server.service.js

@@ -6,11 +6,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpServer = void 0;
 const http_1 = __importDefault(require("http"));
 class HttpServer {
-    constructor(pipeline) {
+    constructor(pipeline, logger) {
         this.pipeline = pipeline;
+        this.logger = logger;
         this.server = http_1.default.createServer((req, res) => {
             req.startTime = Date.now();
-            this.pipeline.execute(req, res);
+            // pipeline.execute() is async — an uncaught rejection here (e.g. a
+            // synchronous throw deep in a middleware) would otherwise become an
+            // unhandled promise rejection and can crash the whole process.
+            this.pipeline.execute(req, res).catch((e) => {
+                this.logger.error(e);
+                if (!res.headersSent) {
+                    res.statusCode = 502;
+                    res.end();
+                }
+            });
         });
         this.use = this.pipeline.use.bind(this.pipeline);
         this.on = this.server.on.bind(this.server);

package/dist/services/rules-matchers/method-path-rules-matcher.d.ts

@@ -0,0 +1,27 @@
+export interface MethodPathRule {
+    method: string;
+    path: string;
+    disable?: boolean;
+}
+/**
+ * Shared base for matchers that pick a rule by HTTP method + URL path
+ * (MockRulesMatcher, RewriteRulesMatcher) — both used to be byte-for-byte
+ * identical aside from the rule type. Subclasses only need to provide the
+ * list of candidate rules.
+ */
+export declare abstract class MethodPathRulesMatcher<T extends MethodPathRule> {
+    protected abstract getRules(): T[];
+    match(url: string, method: string): T | undefined;
+    params(url: string, rule: T): Record<string, string> | undefined;
+    /**
+     * Finds the matching rule and its path params in a single pass — avoids
+     * compiling/running the path-to-regexp matcher twice (once via `match()`,
+     * again via `params()`) for the same url+rule, as BootstrapMiddleware does.
+     */
+    matchWithParams(url: string, method: string): {
+        rule: T;
+        params: Record<string, string>;
+    } | undefined;
+    private find;
+    private matchPath;
+}

package/dist/services/rules-matchers/method-path-rules-matcher.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MethodPathRulesMatcher = void 0;
+const path_to_regexp_1 = require("path-to-regexp");
+/**
+ * Shared base for matchers that pick a rule by HTTP method + URL path
+ * (MockRulesMatcher, RewriteRulesMatcher) — both used to be byte-for-byte
+ * identical aside from the rule type. Subclasses only need to provide the
+ * list of candidate rules.
+ */
+class MethodPathRulesMatcher {
+    match(url, method) {
+        var _a;
+        return (_a = this.find(url, method)) === null || _a === void 0 ? void 0 : _a.rule;
+    }
+    params(url, rule) {
+        var _a;
+        return (_a = this.matchPath(rule.path, url)) === null || _a === void 0 ? void 0 : _a.params;
+    }
+    /**
+     * Finds the matching rule and its path params in a single pass — avoids
+     * compiling/running the path-to-regexp matcher twice (once via `match()`,
+     * again via `params()`) for the same url+rule, as BootstrapMiddleware does.
+     */
+    matchWithParams(url, method) {
+        const found = this.find(url, method);
+        return found ? { rule: found.rule, params: found.matchResult.params } : undefined;
+    }
+    find(url, method) {
+        for (const rule of this.getRules()) {
+            if (rule.disable) {
+                continue;
+            }
+            if (rule.method.toLowerCase() !== method.toLowerCase()) {
+                continue;
+            }
+            const matchResult = this.matchPath(rule.path, url);
+            if (matchResult) {
+                return { rule, matchResult };
+            }
+        }
+    }
+    matchPath(path, url) {
+        const matchResult = (0, path_to_regexp_1.match)(path, {
+            decode: decodeURIComponent,
+        })(url);
+        return matchResult || undefined;
+    }
+}
+exports.MethodPathRulesMatcher = MethodPathRulesMatcher;

package/dist/services/rules-matchers/mock-rules-matcher.service.d.ts

@@ -1,8 +1,8 @@
 import { Config } from '../config.service';
 import { MockRule } from '../../types/yxorp-config';
-export declare class MockRulesMatcher {
+import { MethodPathRulesMatcher } from './method-path-rules-matcher';
+export declare class MockRulesMatcher extends MethodPathRulesMatcher<MockRule> {
     private config;
     constructor(config: Config);
-    match(url: string, method: string): MockRule | undefined;
-    params(url: string, mockRule: MockRule): Object | undefined;
+    protected getRules(): MockRule[];
 }

package/dist/services/rules-matchers/mock-rules-matcher.service.js

@@ -1,35 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MockRulesMatcher = void 0;
-const path_to_regexp_1 = require("path-to-regexp");
-class MockRulesMatcher {
+const method_path_rules_matcher_1 = require("./method-path-rules-matcher");
+class MockRulesMatcher extends method_path_rules_matcher_1.MethodPathRulesMatcher {
     constructor(config) {
+        super();
         this.config = config;
     }
-    match(url, method) {
-        const mockRules = this.config.get().mockRules || [];
-        for (let mockRule of mockRules) {
-            if (mockRule.disable) {
-                continue;
-            }
-            if (mockRule.method.toLowerCase() !== method.toLowerCase()) {
-                continue;
-            }
-            const matchResult = (0, path_to_regexp_1.match)(mockRule.path, {
-                decode: decodeURIComponent,
-            })(url);
-            if (matchResult) {
-                return mockRule;
-            }
-        }
-    }
-    params(url, mockRule) {
-        const matchResult = (0, path_to_regexp_1.match)(mockRule.path, {
-            decode: decodeURIComponent,
-        })(url);
-        if (matchResult) {
-            return matchResult.params;
-        }
+    getRules() {
+        return this.config.get().mockRules || [];
     }
 }
 exports.MockRulesMatcher = MockRulesMatcher;

package/dist/services/rules-matchers/rewrite-rules-matcher.service.d.ts

@@ -1,8 +1,8 @@
 import { Config } from '../config.service';
 import { RewriteRule } from '../../types/yxorp-config';
-export declare class RewriteRulesMatcher {
+import { MethodPathRulesMatcher } from './method-path-rules-matcher';
+export declare class RewriteRulesMatcher extends MethodPathRulesMatcher<RewriteRule> {
     private config;
     constructor(config: Config);
-    match(url: string, method: string): RewriteRule | undefined;
-    params(url: string, rewriteRule: RewriteRule): Object | undefined;
+    protected getRules(): RewriteRule[];
 }

package/dist/services/rules-matchers/rewrite-rules-matcher.service.js

@@ -1,35 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RewriteRulesMatcher = void 0;
-const path_to_regexp_1 = require("path-to-regexp");
-class RewriteRulesMatcher {
+const method_path_rules_matcher_1 = require("./method-path-rules-matcher");
+class RewriteRulesMatcher extends method_path_rules_matcher_1.MethodPathRulesMatcher {
     constructor(config) {
+        super();
         this.config = config;
     }
-    match(url, method) {
-        const rewriteRules = this.config.get().rewriteRules || [];
-        for (let rewriteRule of rewriteRules) {
-            if (rewriteRule.disable) {
-                continue;
-            }
-            if (rewriteRule.method.toLowerCase() !== method.toLowerCase()) {
-                continue;
-            }
-            const matchResult = (0, path_to_regexp_1.match)(rewriteRule.path, {
-                decode: decodeURIComponent,
-            })(url);
-            if (matchResult) {
-                return rewriteRule;
-            }
-        }
-    }
-    params(url, rewriteRule) {
-        const matchResult = (0, path_to_regexp_1.match)(rewriteRule.path, {
-            decode: decodeURIComponent,
-        })(url);
-        if (matchResult) {
-            return matchResult.params;
-        }
+    getRules() {
+        return this.config.get().rewriteRules || [];
     }
 }
 exports.RewriteRulesMatcher = RewriteRulesMatcher;

package/dist/services/yxorp-server.service.js

@@ -14,26 +14,43 @@ const static_middleware_1 = require("../middleware/static.middleware");
 function createServer(config, logger, rewriteRulesMatcher, mockRulesMatcher, remoteRulesMatcher) {
     // 1. Proxy pipeline (outgoing responses) — no deps on proxy/server
     const proxyPipeline = new pipeline_service_1.Pipeline();
-    proxyPipeline.use(new rawBody_middleware_1.RawBodyMiddleware(), new rewrite_middleware_1.RewriteMiddleware(logger), new proxyRes_middleware_1.ProxyResMiddleware(logger));
+    proxyPipeline.use(new rawBody_middleware_1.RawBodyMiddleware(logger), new rewrite_middleware_1.RewriteMiddleware(logger), new proxyRes_middleware_1.ProxyResMiddleware(logger));
     // 2. HttpProxy wraps the proxy pipeline
     const proxy = new http_proxy_service_1.HttpProxy(proxyPipeline);
     // 3. Server pipeline (incoming requests)
     const serverPipeline = new pipeline_service_1.Pipeline();
     serverPipeline.use(new static_middleware_1.StaticMiddleware(config, logger), new bootstrap_middleware_1.BootstrapMiddleware(rewriteRulesMatcher, mockRulesMatcher, logger), new mock_middleware_1.MockMiddleware(logger), new proxy_middleware_1.ProxyMiddleware(proxy, remoteRulesMatcher, config, logger));
     // 4. HttpServer wraps the server pipeline
-    const server = new http_server_service_1.HttpServer(serverPipeline);
+    const server = new http_server_service_1.HttpServer(serverPipeline, logger);
     // 5. Attach proxy pipeline to proxyRes event
-    proxy.on('proxyRes', ((proxyRes, req, res) => {
-        proxy.execute(proxyRes, req, res);
-    }));
+    proxy.on('proxyRes', (proxyRes, req, res) => {
+        // proxy.execute() is async — an uncaught rejection here would otherwise
+        // become an unhandled promise rejection and can crash the whole process,
+        // leaving the client hanging with no response.
+        proxy.execute(proxyRes, req, res).catch((e) => {
+            logger.error(e);
+            if (!res.headersSent) {
+                res.statusCode = 502;
+                res.end();
+            }
+        });
+    });
     // 6. WebSocket upgrade handling
     server.addListener('upgrade', (req, socket, head) => {
         const url = req.url || '';
         const proxyOptions = config.get().proxyOptions;
-        const remoteRule = remoteRulesMatcher.match(url, true);
-        const target = remoteRule
-            ? remoteRulesMatcher.toPath(url, remoteRule)
-            : undefined;
+        let target;
+        try {
+            const remoteRule = remoteRulesMatcher.match(url, true);
+            target = remoteRule
+                ? remoteRulesMatcher.toPath(url, remoteRule)
+                : undefined;
+        }
+        catch (e) {
+            // A malformed `remoteRules[].path` pattern would otherwise throw
+            // synchronously here on every upgrade — fall back to the default target.
+            logger.error(e);
+        }
         const options = {
             ...proxyOptions,
             prependPath: !target,

package/dist/utils/access-log.d.ts

@@ -0,0 +1,7 @@
+import { IncomingMessage } from 'http';
+/**
+ * Formats a single access-log line with the label column padded to a fixed
+ * width so entries from different middlewares (mock, rewrite, proxy,
+ * static) line up in the log output.
+ */
+export declare function formatAccessLog(label: string, statusCode: number | string | undefined, req: IncomingMessage): string;

package/dist/utils/access-log.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAccessLog = void 0;
+const request_timing_1 = require("./request-timing");
+const LABEL_WIDTH = 8;
+/**
+ * Formats a single access-log line with the label column padded to a fixed
+ * width so entries from different middlewares (mock, rewrite, proxy,
+ * static) line up in the log output.
+ */
+function formatAccessLog(label, statusCode, req) {
+    return `${label.padEnd(LABEL_WIDTH)}${statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`;
+}
+exports.formatAccessLog = formatAccessLog;

package/dist/utils/headers.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="node" />
+import { IncomingHttpHeaders } from 'http';
+/**
+ * RFC 2616 §13.5.1 hop-by-hop headers must not be forwarded between a proxy
+ * and its client — plus any header dynamically named in the `Connection`
+ * header's value.
+ */
+export declare function isHopByHopHeader(name: string, headers: IncomingHttpHeaders): boolean;

package/dist/utils/headers.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHopByHopHeader = void 0;
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+/**
+ * RFC 2616 §13.5.1 hop-by-hop headers must not be forwarded between a proxy
+ * and its client — plus any header dynamically named in the `Connection`
+ * header's value.
+ */
+function isHopByHopHeader(name, headers) {
+    const lower = name.toLowerCase();
+    if (HOP_BY_HOP_HEADERS.has(lower)) {
+        return true;
+    }
+    const connection = headers.connection;
+    if (connection) {
+        const named = (Array.isArray(connection) ? connection.join(',') : connection)
+            .split(',')
+            .map((value) => value.trim().toLowerCase());
+        if (named.includes(lower)) {
+            return true;
+        }
+    }
+    return false;
+}
+exports.isHopByHopHeader = isHopByHopHeader;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yxorp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A local reverse proxy for rewriting, mocking, and debugging API responses.",
   "files": [
     "dist/",
@@ -27,7 +27,6 @@
     "mime": "^3.0.0",
     "path-to-regexp": "^8.4.2",
     "qs": "^6.15.2",
-    "tslib": "^2.8.1",
     "winston": "^3.19.0"
   },
   "devDependencies": {