yxorp 0.1.5 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2023 Kirill Suntsov
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2023-2026 Kirill Suntsov <suntsov.kirill@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,81 +1,369 @@
-# Yxorp
-This is a simple CLI reverse proxy utility for rewriting or mocking API data. It is in early development and may contain many bugs 😊
-
-## Installation
-```
-npm i -g yxorp
-```
-## Usage
-Just run yxopr in folder which contains yxopr.json
-
-## Config
-Simple yxorp.json example:
-```json
-{
-  "#": "The site that will be proxied"
-  "target": "http://example.com/",
-  "proxyPort": 3002,
-  "#": "Makes static path with files in directory",
-  "staticRules": [
-    {
-      "path": "/some-path-on-server",
-      "directory": "./some-path-with-static-files",
-      "disable": false
-    }
-  ],
-  "#": "Scripts may be using for set some data for mock scripts",
-  "scripts": [
-    "./scripts/some-data.js"
-  ],
-  "#": "For matching paths in mockRules and rewriteRules uses https://www.npmjs.com/package/path-to-regex",
-  "#": "This rules uses to modify API data",
-  "mockRules": [
-    {
-      "method": "GET",
-      "path": "/api/example-one(.*)",
-      "script": "./mock/api/example-one.js",
-      "disable": false
-    }, {
-      "method": "GET",
-      "path": "/api/example-two(.*)",
-      "file": "./mock/api/example-two.json",
-      "statusCode": 200,
-      "disable": false
-    }
-  ]
-  "rewriteRules": [
-    {
-      "method": "GET",
-      "path": "/api/example-one(.*)",
-      "script": "./rewrite/api/example-one.js",
-      "disable": false
-    }, {
-      "method": "GET",
-      "path": "/api/example-two(.*)",
-      "file": "./rewrite/api/example-two.json",
-      "statusCode": 200,
-      "disable": false
-    }
-  ]
-}
-```
-
-## Mock script example
-```javascript
-var data = {
-  error: "some error",
-};
-
-res.statusCode = 500;
-res.end(Buffer.from(JSON.stringify(data)));
-```
-
-## Rewrite script example
-```javascript
-const data = JSON.parse(body.toString());
-
-data.modify = 'from js 123';
-
-result = Buffer.from(JSON.stringify(data));
-
-```
+# Yxorp
+
+**Yxorp** is a local reverse proxy for rewriting, mocking, and debugging API responses. Think of it as a lightweight Swiss Army knife for HTTP(S) traffic — useful when you're developing a frontend against an API that's not quite ready, needs some data tweaking, or just returns the wrong thing.
+
+It sits between your app and a target server, and you get to decide what happens to every request and response.
+
+---
+
+## Installation
+
+```bash
+npm i -g yxorp
+```
+
+---
+
+## Quick Start
+
+**1. Create a config file** — `yxorp.json` in your project root:
+
+```json
+{
+  "target": "https://api.example.com",
+  "proxyPort": 3000
+}
+```
+
+**2. Run it:**
+
+```bash
+yxorp
+```
+
+That's it. Yxorp starts on `http://localhost:3000` and proxies everything to `https://api.example.com`. Open your app, point it at `http://localhost:3000`, and watch the traffic flow.
+
+Now the fun part — start adding rules.
+
+---
+
+## Config Resolution
+
+Yxorp looks for its config in this order:
+
+| Priority | Location | Example |
+|----------|----------|---------|
+| 1 | `--config <path>` flag | `yxorp --config ./proxy/settings.json` |
+| 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:
+
+```
+my-project/
+  .yxorp/
+    settings.json
+    mock/
+      users.js
+    static/
+      logo.svg
+```
+
+---
+
+## Config Reference
+
+### `target` (required)
+
+The upstream server everything proxies to by default.
+
+```json
+"target": "https://api.example.com"
+```
+
+### `proxyPort` (required)
+
+Port for the local proxy server.
+
+```json
+"proxyPort": 8080
+```
+
+### `proxyHeaders`
+
+Extra HTTP headers to send with every proxied request to the target server. Useful when the target rejects requests with a missing or unexpected `User-Agent`, `Origin`, or custom header.
+
+```json
+{
+  "target": "https://api.example.com",
+  "proxyPort": 3000,
+  "proxyHeaders": {
+    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+    "origin": "https://example.com"
+  }
+}
+```
+
+---
+
+### `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.
+
+#### By file — respond with a JSON file:
+
+```json
+{
+  "method": "GET",
+  "path": "/api/users/:id",
+  "file": "./mock/user.json",
+  "statusCode": 200
+}
+```
+
+#### By script — dynamic response logic:
+
+```json
+{
+  "method": "POST",
+  "path": "/api/users",
+  "script": "./mock/create-user.js"
+}
+```
+
+The script receives `req` and `res` and does whatever it wants:
+
+```javascript
+// ./mock/create-user.js
+module.exports = (req, res) => {
+  res.statusCode = 201;
+  res.setHeader('content-type', 'application/json');
+  res.end(JSON.stringify({ id: 42, status: 'created' }));
+};
+```
+
+**Hot-reload is built-in** — edit the script file and the next request picks up changes automatically. No restart needed.
+
+#### Disable a rule:
+
+```json
+{
+  "method": "GET",
+  "path": "/api/users/:id",
+  "file": "./mock/user.json",
+  "disable": true
+}
+```
+
+Disabled rules are skipped, and the request passes through to the next matching middleware (rewrite, then proxy).
+
+---
+
+### Rewrite Rules (`rewriteRules`)
+
+Let the request reach the target, then **modify the response** before it gets back to your app.
+
+#### By file — replace the entire response body:
+
+```json
+{
+  "method": "GET",
+  "path": "/api/users/:id",
+  "file": "./rewrite/user-override.json",
+  "statusCode": 200
+}
+```
+
+#### By script — transform the response body:
+
+```json
+{
+  "method": "GET",
+  "path": "/api/users/:id",
+  "script": "./rewrite/user.js"
+}
+```
+
+The script receives the decoded response body, the proxy response, the original request, and the outgoing response:
+
+```javascript
+// ./rewrite/user.js
+module.exports = (body, proxyRes, req, res) => {
+  const data = JSON.parse(body.toString());
+  data.processedBy = 'yxorp';
+  return Buffer.from(JSON.stringify(data));
+};
+```
+
+Whatever you return becomes the new response body.
+
+---
+
+### Remote Rules (`remoteRules`)
+
+Route specific paths to a **different target server** instead of the default one:
+
+```json
+{
+  "remoteRules": [
+    {
+      "path": "/api/legacy/:rest",
+      "target": "http://localhost:4000",
+      "ws": false
+    }
+  ]
+}
+```
+
+The `ws` option enables WebSocket proxying for that route.
+
+---
+
+### Static Rules (`staticRules`)
+
+Serve local files as if they were on the remote server:
+
+```json
+{
+  "staticRules": [
+    {
+      "path": "/assets",
+      "directory": "./static-files"
+    }
+  ]
+}
+```
+
+Requests to `http://localhost:3000/assets/logo.svg` will serve `./static-files/logo.svg` directly, without hitting the target.
+
+Options:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `path` | string | URL path prefix to match |
+| `directory` | string | Local directory to serve files from |
+| `caseInsensitive` | boolean | Ignore filename case when matching |
+| `directoryIndex` | string | Default file for directory requests (e.g. `index.html`) |
+| `disable` | boolean | Skip this rule |
+
+---
+
+### Path Matching
+
+All rules use `path-to-regexp` v8 for URL matching — the same library used by Express, Koa, and many other frameworks.
+
+| Pattern | Matches | `params` |
+|---------|---------|----------|
+| `/api/users` | `/api/users` exactly | `{}` |
+| `/api/users/:id` | `/api/users/42`, `/api/users/abc` | `{ id: '42' }` |
+| `/api/users/:id/photos` | `/api/users/42/photos` | `{ id: '42' }` |
+
+For more advanced patterns, see the [path-to-regexp documentation](https://github.com/pillarjs/path-to-regexp).
+
+---
+
+## Full Example
+
+Here's a complete config showing all features in action:
+
+```json
+{
+  "target": "https://api.example.com",
+  "proxyPort": 3000,
+
+  "scripts": [
+    "./scripts/globals.js"
+  ],
+
+  "staticRules": [
+    {
+      "path": "/assets",
+      "directory": "./static",
+      "directoryIndex": "index.html",
+      "caseInsensitive": true
+    }
+  ],
+
+  "remoteRules": [
+    {
+      "path": "/api/v1",
+      "target": "http://localhost:4000"
+    }
+  ],
+
+  "mockRules": [
+    {
+      "method": "GET",
+      "path": "/api/users/:id",
+      "file": "./mock/users.json",
+      "statusCode": 200
+    },
+    {
+      "method": "POST",
+      "path": "/api/users",
+      "script": "./mock/create-user.js"
+    }
+  ],
+
+  "rewriteRules": [
+    {
+      "method": "GET",
+      "path": "/api/products/:id",
+      "script": "./rewrite/product.js"
+    }
+  ]
+}
+```
+
+---
+
+## Script Hot-Reload
+
+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.
+
+This is especially handy during development when you're iterating on API response shapes.
+
+---
+
+## Development
+
+```bash
+# Clone and run in dev mode (with auto-reload)
+npm start
+
+# Run tests (integration tests spin up real servers)
+npm test
+
+# Build for production
+npm run build
+```
+
+---
+
+## Why "Yxorp"?
+
+Spell it backwards.

package/bin/yxorp.js

@@ -1,22 +1,13 @@
-#!/usr/bin/env node
-
-var path = require('path');
-var nodemon = require('nodemon');
-var nodemonDefaults = require('nodemon/lib/config/defaults');
-
-var pathToTsNode = path.normalize(__dirname + './../node_modules/.bin/ts-node');
-var filepath = path.normalize(__dirname + './../src/index.ts')
-
-nodemonDefaults.execMap.ts = pathToTsNode;
-
-nodemon({
-  script: filepath,
-  watch: ['yxorp.json']
-});
-
-nodemon.on('quit', function () {
-  console.log('Yxopr has quit');
-  process.exit();
-}).on('restart', function (files) {
-  console.log('Yxopr restarts...');
-});
+#!/usr/bin/env node
+
+try {
+  require('../dist/index.js');
+} catch (e) {
+  if (e.code === 'MODULE_NOT_FOUND') {
+    console.error(
+      'Yxorp is not built. Run `npm run build` first, or use `npm start` for development.'
+    );
+    process.exit(1);
+  }
+  throw e;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const config_service_1 = require("./services/config.service");
+const logger_service_1 = require("./services/logger.service");
+const remote_rules_matcher_service_1 = require("./services/rules-matchers/remote-rules-matcher.service");
+const rewrite_rules_matcher_service_1 = require("./services/rules-matchers/rewrite-rules-matcher.service");
+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");
+// --- Config resolution ---
+let configDir;
+let config;
+try {
+    const resolved = (0, config_resolver_1.resolveConfig)(process.cwd(), process.argv);
+    configDir = resolved.configDir;
+    config = resolved.config;
+}
+catch (e) {
+    console.error(e.message || e);
+    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;
+}
+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);
+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);
+listen(config.proxyPort, () => {
+    console.log(`Yxorp server started successfully on http://localhost:${config.proxyPort}`);
+});

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

@@ -0,0 +1,15 @@
+import { IncomingMessage } 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]> {
+    private rewriteRulesMatcher;
+    private mockRulesMatcher;
+    private logger;
+    constructor(rewriteRulesMatcher: RewriteRulesMatcher, mockRulesMatcher: MockRulesMatcher, logger: LoggerService);
+    use(req: IncomingMessage, _res: any, next: () => void): void;
+    private setRewriteRule;
+    private setMockRule;
+    private setQueryParams;
+}

package/dist/middleware/bootstrap.middleware.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BootstrapMiddleware = void 0;
+const qs_1 = __importDefault(require("qs"));
+class BootstrapMiddleware {
+    constructor(rewriteRulesMatcher, mockRulesMatcher, logger) {
+        this.rewriteRulesMatcher = rewriteRulesMatcher;
+        this.mockRulesMatcher = mockRulesMatcher;
+        this.logger = logger;
+    }
+    use(req, _res, next) {
+        try {
+            this.setRewriteRule(req);
+            this.setMockRule(req);
+            this.setQueryParams(req);
+            next();
+        }
+        catch (e) {
+            this.logger.error(e);
+            next();
+        }
+    }
+    setRewriteRule(req) {
+        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 || {};
+            }
+        }
+    }
+    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 || {};
+            }
+        }
+    }
+    setQueryParams(req) {
+        if (!req.url) {
+            return;
+        }
+        const url = new URL(req.url, 'http://fake.com');
+        const query = qs_1.default.parse(url.search, {
+            ignoreQueryPrefix: true,
+        });
+        req.query = query;
+    }
+}
+exports.BootstrapMiddleware = BootstrapMiddleware;

package/dist/middleware/mock.middleware.d.ts

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