yxorp 0.2.1 → 0.2.3

package/README.md

@@ -47,7 +47,7 @@ Yxorp looks for its config in this order:
 | 2 | `./yxorp.json` | In your project root |
 | 3 | `./.yxorp/settings.json` | Inside a hidden `.yxorp` directory |
 
-When config lives inside `.yxorp/`, all relative paths (scripts, mock files, static directories) are resolved relative to that directory. This keeps things tidy:
+When config lives inside `.yxorp/`, all relative paths (mock files, rewrite files, static directories) are resolved relative to that directory. This keeps things tidy:
 
 ```
 my-project/
@@ -59,6 +59,14 @@ my-project/
       logo.svg
 ```
 
+### CLI overrides
+
+`--port` and `--target` override the corresponding config values without touching the file — handy for one-off runs or scripting:
+
+```bash
+yxorp --port 4000 --target http://localhost:8080
+```
+
 ---
 
 ## Config Reference
@@ -96,40 +104,6 @@ Extra HTTP headers to send with every proxied request to the target server. Usef
 
 ---
 
-### `scripts`
-
-Additional JavaScript files loaded **once at startup**. Use them to set up shared data or helpers for your mock/rewrite scripts.
-
-Why `scripts` and not just `require()` inside each mock file? Because mock scripts are hot-reloaded on every request (their module cache is cleared). Any data they `require()` would also need to be re-imported. Scripts loaded via the `scripts` array sidestep this — they run once at startup and can stash data on `globalThis` for all mock/rewrite scripts to use.
-
-```json
-"scripts": [
-  "./scripts/seed-data.js"
-]
-```
-
-```javascript
-// scripts/seed-data.js — runs once, survives hot-reload
-globalThis.users = [
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' },
-];
-```
-
-```javascript
-// mock/user.js — hot-reloaded on every request, but seed-data is untouched
-module.exports = (req, res) => {
-  const user = globalThis.users.find(u => u.id === Number(req.params.id));
-  res.end(JSON.stringify(user));
-};
-```
-
-As a rule of thumb:
-- **`scripts`** — for data you initialize once (lookup tables, config, seed data)
-- **`require()` inside mock/rewrite files** — for utility helpers you want imported fresh each time
-
----
-
 ### Mock Rules (`mockRules`)
 
 Intercept a matching request **before** it reaches the target and respond immediately. The target server never sees it.
@@ -155,7 +129,7 @@ Intercept a matching request **before** it reaches the target and respond immedi
 }
 ```
 
-The script receives `req` and `res` and does whatever it wants:
+The script receives the raw Node.js `req` (`IncomingMessage`) and `res` (`ServerResponse`) — **just like writing a tiny backend**. There's no magic layered on top: you're fully responsible for setting the status code, headers, and body yourself, exactly as the real target server would.
 
 ```javascript
 // ./mock/create-user.js
@@ -166,6 +140,10 @@ module.exports = (req, res) => {
 };
 ```
 
+If you don't set `res.statusCode`, it defaults to Node's `200`. If you don't call `res.end()`, the response hangs — Yxorp won't do it for you. The only assist it provides: if the script finishes without sending headers, Yxorp sets `content-type: application/json` for you (handy for quick `res.end(JSON.stringify(...))` one-liners).
+
+This mirrors how a real backend works on purpose — mock scripts are meant to **stand in for the target server**, so the same rules apply: you decide what the client receives, down to the last header.
+
 **Hot-reload is built-in** — edit the script file and the next request picks up changes automatically. No restart needed.
 
 #### Disable a rule:
@@ -295,10 +273,6 @@ Here's a complete config showing all features in action:
   "target": "https://api.example.com",
   "proxyPort": 3000,
 
-  "scripts": [
-    "./scripts/globals.js"
-  ],
-
   "staticRules": [
     {
       "path": "/assets",

package/dist/index.js

@@ -2,8 +2,8 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
-var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const config_service_1 = require("./services/config.service");
 const logger_service_1 = require("./services/logger.service");
@@ -13,6 +13,15 @@ const mock_rules_matcher_service_1 = require("./services/rules-matchers/mock-rul
 const yxorp_server_service_1 = require("./services/yxorp-server.service");
 const config_resolver_1 = require("./services/config-resolver");
 const config_watcher_1 = require("./services/config-watcher");
+const config_validator_1 = require("./services/config-validator");
+const cli_overrides_1 = require("./services/cli-overrides");
+// --- Version flag ---
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    const pkgPath = path_1.default.join(__dirname, '../package.json');
+    const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf-8'));
+    console.log(pkg.version);
+    process.exit(0);
+}
 // --- Config resolution ---
 let configDir;
 let configPath;
@@ -27,6 +36,15 @@ catch (e) {
     console.error(e.message || e);
     process.exit(1);
 }
+// --- CLI overrides ---
+// e.g. `yxorp --port 4000 --target http://localhost:8080` — flags win over config values.
+config = (0, cli_overrides_1.applyCliOverrides)(config, process.argv);
+const configErrors = (0, config_validator_1.validateConfig)(config);
+if (configErrors.length) {
+    console.error('Invalid config:');
+    configErrors.forEach(err => console.error(`  - ${err}`));
+    process.exit(1);
+}
 // Change CWD to config directory so relative paths in config work correctly
 if (configDir !== process.cwd()) {
     process.chdir(configDir);
@@ -45,9 +63,6 @@ function buildProxyConfig(cfg) {
     }
     return { ...cfg, proxyOptions };
 }
-(_a = config === null || config === void 0 ? void 0 : config.scripts) === null || _a === void 0 ? void 0 : _a.forEach(script => {
-    require(path_1.default.resolve(script));
-});
 // Manual composition — no DI container
 const logger = new logger_service_1.LoggerService();
 const appConfig = new config_service_1.Config();
@@ -55,12 +70,43 @@ appConfig.set(buildProxyConfig(config));
 const mockRulesMatcher = new mock_rules_matcher_service_1.MockRulesMatcher(appConfig);
 const rewriteRulesMatcher = new rewrite_rules_matcher_service_1.RewriteRulesMatcher(appConfig);
 const remoteRulesMatcher = new remote_rules_matcher_service_1.RemoteRulesMatcher(appConfig);
-const { listen } = (0, yxorp_server_service_1.createServer)(appConfig, logger, rewriteRulesMatcher, mockRulesMatcher, remoteRulesMatcher);
+const { server, listen } = (0, yxorp_server_service_1.createServer)(appConfig, logger, rewriteRulesMatcher, mockRulesMatcher, remoteRulesMatcher);
 listen(config.proxyPort, () => {
     console.log(`Yxorp server started successfully on http://localhost:${config.proxyPort}`);
 });
 // --- Config hot-reload ---
-(0, config_watcher_1.watchConfig)(configPath, (newConfig) => {
+const configWatcher = (0, config_watcher_1.watchConfig)(configPath, (newConfig) => {
+    const errors = (0, config_validator_1.validateConfig)(newConfig);
+    if (errors.length) {
+        logger.error('Config reload skipped — invalid config:');
+        errors.forEach(err => logger.error(`  - ${err}`));
+        return;
+    }
     appConfig.set(buildProxyConfig(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)
+        return;
+    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);
+    });
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));

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,6 +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");
 class MockMiddleware {
     constructor(logger) {
         this.logger = logger;
@@ -22,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(`mock         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                    return;
                 }
-                this.logger.info(`mock         ${res.statusCode || 200} ${req.method} ${req.url}`);
+                await handler(req, res);
+                if (!res.headersSent) {
+                    res.setHeader('content-type', 'application/json');
+                }
+                this.logger.info(`mock         ${res.statusCode || 200} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
                 return;
             }
             if ('file' in mockRule) {
@@ -40,13 +50,23 @@ class MockMiddleware {
                 }
                 res.setHeader('content-length', file.length);
                 res.end(file);
-                this.logger.info(`mock         ${res.statusCode} ${req.method} ${req.url}`);
+                this.logger.info(`mock         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
                 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(`mock         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+                if (!res.writableEnded) {
+                    res.end();
+                }
+                return;
+            }
             next();
         }
     }

package/dist/middleware/proxy.middleware.js

@@ -11,10 +11,18 @@ 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,

package/dist/middleware/proxyRes.middleware.d.ts

@@ -5,5 +5,5 @@ import { LoggerService } from '../services/logger.service';
 export declare class ProxyResMiddleware implements Middleware<[proxyRes: IncomingMessage, req: IncomingMessage, res: ServerResponse]> {
     private logger;
     constructor(logger: LoggerService);
-    use(proxyRes: IncomingMessage, _req: IncomingMessage, res: ServerResponse): void;
+    use(proxyRes: IncomingMessage, req: IncomingMessage, res: ServerResponse): void;
 }

package/dist/middleware/proxyRes.middleware.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProxyResMiddleware = void 0;
+const request_timing_1 = require("../utils/request-timing");
 class ProxyResMiddleware {
     constructor(logger) {
         this.logger = logger;
     }
-    use(proxyRes, _req, res) {
+    use(proxyRes, req, res) {
         try {
             // Skip transfer-encoding since we reconstruct the body with known length
             for (let key in proxyRes.headers) {
@@ -19,6 +20,12 @@ class ProxyResMiddleware {
             res.removeHeader('content-length');
             res.setHeader('content-length', response.length);
             res.end(response);
+            // 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(`proxy         ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+            }
         }
         catch (e) {
             this.logger.error(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,6 +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");
 class RewriteMiddleware {
     constructor(logger) {
         this.logger = logger;
@@ -29,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}`);
+                this.logRewrite(req, proxyRes);
                 next();
                 return;
             }
@@ -39,7 +40,7 @@ class RewriteMiddleware {
                 if (rewriteRule.statusCode) {
                     proxyRes.statusCode = rewriteRule.statusCode;
                 }
-                this.logger.info(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url}`);
+                this.logRewrite(req, proxyRes);
                 next();
                 return;
             }
@@ -47,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(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
+    }
 }
 exports.RewriteMiddleware = RewriteMiddleware;

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

@@ -8,5 +8,22 @@ 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;
+    private isFile;
+    private findCaseInsensitive;
 }

package/dist/middleware/static.middleware.js

@@ -7,6 +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");
 class StaticMiddleware {
     constructor(config, logger) {
         this.config = config;
@@ -17,10 +18,6 @@ class StaticMiddleware {
             const staticRules = this.config.get().staticRules || [];
             const url = new URL(req.url || '', 'http://fake.com');
             const urlPath = url.pathname;
-            if (!staticRules) {
-                next();
-                return;
-            }
             const currentStaticRule = staticRules.filter((staticRule) => {
                 return urlPath.startsWith(staticRule.path);
             })[0];
@@ -28,58 +25,89 @@ 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}`);
+            this.logger.info(`static        ${res.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
         }
         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)) {
+            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)) ? current : undefined;
+    }
+    async isFile(filePath) {
+        try {
+            const stats = await promises_1.default.stat(filePath);
+            return stats.isFile();
+        }
+        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.d.ts

@@ -0,0 +1,7 @@
+import { ConfigFile } from '../types/yxorp-config';
+/**
+ * Applies `--port`/`--target` CLI flags on top of a resolved config, without
+ * touching the config file. CLI flags win over config values. Returns a new
+ * object — the input config is left untouched.
+ */
+export declare function applyCliOverrides(config: ConfigFile, argv: string[]): ConfigFile;

package/dist/services/cli-overrides.js

@@ -0,0 +1,42 @@
+"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 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
+ * touching the config file. CLI flags win over config values. Returns a new
+ * object — the input config is left untouched.
+ */
+function applyCliOverrides(config, argv) {
+    const portOverride = getArgValue(argv, '--port');
+    const targetOverride = getArgValue(argv, '--target');
+    if (portOverride === undefined && targetOverride === undefined) {
+        return config;
+    }
+    return {
+        ...config,
+        ...(portOverride !== undefined ? { proxyPort: portOverride } : {}),
+        ...(targetOverride !== undefined ? { target: targetOverride } : {}),
+    };
+}
+exports.applyCliOverrides = applyCliOverrides;

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

@@ -0,0 +1,10 @@
+/**
+ * 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, 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

@@ -0,0 +1,116 @@
+"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, or a bad
+ * `path` pattern throwing synchronously inside path-to-regexp's `match()`).
+ */
+function validateConfig(config) {
+    const errors = [];
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        return ['Config must be a JSON object'];
+    }
+    if (typeof config.target !== 'string' || !config.target.trim()) {
+        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 && 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 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) {
+        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/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,10 +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) => {
-            this.pipeline.execute(req, res);
+            req.startTime = Date.now();
+            // 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): Object | 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: Object;
+    } | 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.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/types/yxorp-config.d.ts

@@ -4,7 +4,6 @@ export interface YxorpConfig extends ConfigFile {
 export interface ConfigFile {
     target: string;
     proxyPort: string | number;
-    scripts?: string[];
     proxyHeaders?: Record<string, string>;
     remoteRules?: RemoteRule[];
     staticRules?: StaticRule[];

package/dist/utils/request-timing.d.ts

@@ -0,0 +1,6 @@
+import { IncomingMessage } from 'http';
+/**
+ * Milliseconds elapsed since the request started (set by HttpServer on arrival).
+ * Falls back to 0 if startTime wasn't recorded for some reason.
+ */
+export declare function elapsedMs(req: IncomingMessage): number;

package/dist/utils/request-timing.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.elapsedMs = void 0;
+/**
+ * Milliseconds elapsed since the request started (set by HttpServer on arrival).
+ * Falls back to 0 if startTime wasn't recorded for some reason.
+ */
+function elapsedMs(req) {
+    return req.startTime !== undefined ? Date.now() - req.startTime : 0;
+}
+exports.elapsedMs = elapsedMs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yxorp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "A local reverse proxy for rewriting, mocking, and debugging API responses.",
   "files": [
     "dist/",