yxorp 0.2.0 → 0.2.2

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",
@@ -341,7 +315,15 @@ Here's a complete config showing all features in action:
 
 ---
 
-## Script Hot-Reload
+## Hot-Reload
+
+### Config
+
+Yxorp watches its config file at runtime. **Save the file — changes take effect on the next request.** No restart needed.
+
+This works for all config fields: mock rules, rewrite rules, remote rules, static rules, and headers. The proxy server keeps running and the new config is applied immediately.
+
+### Scripts
 
 Mock and rewrite scripts are reloaded on every request — **just save the file and the next request uses the new code**. No need to restart Yxorp.
 

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");
@@ -12,48 +12,90 @@ const rewrite_rules_matcher_service_1 = require("./services/rules-matchers/rewri
 const mock_rules_matcher_service_1 = require("./services/rules-matchers/mock-rules-matcher.service");
 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;
 let config;
 try {
     const resolved = (0, config_resolver_1.resolveConfig)(process.cwd(), process.argv);
     configDir = resolved.configDir;
+    configPath = resolved.configPath;
     config = resolved.config;
 }
 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);
 }
-const proxyOptions = {
-    target: config.target,
-    changeOrigin: true,
-    followRedirects: true,
-    secure: false,
-    ws: true,
-    selfHandleResponse: true,
-};
-if (config.proxyHeaders) {
-    proxyOptions.headers = config.proxyHeaders;
+function buildProxyConfig(cfg) {
+    const proxyOptions = {
+        target: cfg.target,
+        changeOrigin: true,
+        followRedirects: true,
+        secure: false,
+        ws: true,
+        selfHandleResponse: true,
+    };
+    if (cfg.proxyHeaders) {
+        proxyOptions.headers = cfg.proxyHeaders;
+    }
+    return { ...cfg, proxyOptions };
 }
-const proxyConfig = {
-    ...config,
-    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();
-appConfig.set(proxyConfig);
+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 ---
+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 ---
+let shuttingDown = false;
+function shutdown(signal) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    logger.info(`Received ${signal}, shutting down...`);
+    configWatcher.close();
+    server.close(() => {
+        process.exit(0);
+    });
+}
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));

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;
@@ -28,7 +29,7 @@ class MockMiddleware {
                         res.setHeader('content-type', 'application/json');
                     }
                 }
-                this.logger.info(`mock         ${res.statusCode || 200} ${req.method} ${req.url}`);
+                this.logger.info(`mock         ${res.statusCode || 200} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
                 return;
             }
             if ('file' in mockRule) {
@@ -40,7 +41,7 @@ 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();

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,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`);
+            }
         }
         catch (e) {
             this.logger.error(e);

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.logger.info(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
                 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.logger.info(`rewrite       ${proxyRes.statusCode} ${req.method} ${req.url} ${(0, request_timing_1.elapsedMs)(req)}ms`);
                 next();
                 return;
             }

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];
@@ -59,7 +56,7 @@ class StaticMiddleware {
             }
             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);

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,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyCliOverrides = void 0;
+function getArgValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    return index !== -1 && index + 1 < argv.length ? argv[index + 1] : 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-resolver.d.ts

@@ -1,6 +1,7 @@
 import { ConfigFile } from '../types/yxorp-config';
 export interface ResolvedConfig {
     configDir: string;
+    configPath: string;
     config: ConfigFile;
 }
 export declare function resolveConfig(cwd: string, argv: string[]): ResolvedConfig;

package/dist/services/config-resolver.js

@@ -20,6 +20,7 @@ function resolveConfig(cwd, argv) {
         }
         return {
             configDir: path_1.default.dirname(resolved),
+            configPath: resolved,
             config: JSON.parse(fs_1.default.readFileSync(resolved, 'utf-8')),
         };
     }
@@ -28,6 +29,7 @@ function resolveConfig(cwd, argv) {
     if (fs_1.default.existsSync(rootConfig)) {
         return {
             configDir: cwd,
+            configPath: rootConfig,
             config: JSON.parse(fs_1.default.readFileSync(rootConfig, 'utf-8')),
         };
     }
@@ -36,6 +38,7 @@ function resolveConfig(cwd, argv) {
     if (fs_1.default.existsSync(dotConfig)) {
         return {
             configDir: dotDir,
+            configPath: dotConfig,
             config: JSON.parse(fs_1.default.readFileSync(dotConfig, 'utf-8')),
         };
     }

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

@@ -0,0 +1,9 @@
+/**
+ * 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).
+ */
+export declare function validateConfig(config: any): string[];

package/dist/services/config-validator.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateConfig = void 0;
+const RULE_ARRAYS = ['remoteRules', 'staticRules', 'mockRules', 'rewriteRules'];
+/**
+ * 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).
+ */
+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) ||
+        (typeof proxyPort === 'string' && proxyPort.trim() !== '' && Number.isInteger(Number(proxyPort)));
+    if (!isValidPort) {
+        errors.push('"proxyPort" is required and must be a number or numeric string (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])) {
+            errors.push(`"${key}" must be an array`);
+        }
+    }
+    return errors;
+}
+exports.validateConfig = validateConfig;

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

@@ -0,0 +1,4 @@
+/// <reference types="node" />
+import fs from 'fs';
+import { ConfigFile } from '../types/yxorp-config';
+export declare function watchConfig(configPath: string, onReload: (config: ConfigFile) => void, onError: (err: unknown) => void): fs.FSWatcher;

package/dist/services/config-watcher.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchConfig = void 0;
+const fs_1 = __importDefault(require("fs"));
+function watchConfig(configPath, onReload, onError) {
+    let debounceTimer = null;
+    return fs_1.default.watch(configPath, () => {
+        if (debounceTimer)
+            return;
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            try {
+                const raw = fs_1.default.readFileSync(configPath, 'utf-8');
+                if (!raw.trim())
+                    return;
+                onReload(JSON.parse(raw));
+            }
+            catch (e) {
+                onError(e);
+            }
+        }, 100);
+    });
+}
+exports.watchConfig = watchConfig;

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

@@ -9,6 +9,7 @@ class HttpServer {
     constructor(pipeline) {
         this.pipeline = pipeline;
         this.server = http_1.default.createServer((req, res) => {
+            req.startTime = Date.now();
             this.pipeline.execute(req, res);
         });
         this.use = this.pipeline.use.bind(this.pipeline);

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.0",
+  "version": "0.2.2",
   "description": "A local reverse proxy for rewriting, mocking, and debugging API responses.",
   "files": [
     "dist/",