override-proxy

Pluggable local development server that serves rule-based HTTP and WebSocket overrides first, then proxies unmatched traffic to upstream targets.

Key features:

• Override-first: if a rule matches, respond immediately; otherwise proxy.
• Multi-server, route-scoped config with root and subdirectory routes.
• Inline HTTP and WebSocket rules through config imports.
• Raw WebSocket direct proxy or bridge mode with bidirectional message actions.
• CLI entry with config discovery, serve, validate, and legacy fallback.
• Layered environment loading via dotenvx (.env.local then .env.default).

Documentation

| Document | Purpose | | ------------------------------------------------------------------------ | -------------------------------------------------- | | README.md | User guide and overview (you are here) | | AGENTS.md | Detailed guide for AI agents | | docs/TOOLS.md | Development commands and verification workflow | | docs/ARCHITECTURE.md | Visual diagrams and code location index | | docs/design/config.md | Config model for multi-server routing | | docs/design/websocket.md | WebSocket proxy and rule semantics | | docs/design/cli.md | CLI behavior | | docs/design/implementation-plan.md | Ordered implementation checklist | | docs/EXAMPLES.md | Copy-paste examples for common scenarios | | docs/PATTERNS.md | Best practices and common pitfalls | | docs/DOC-WRITING-GUIDE.md | Documentation writing standards (for contributors) | | skills/override-proxy/SKILL.md | Codex skill for agent-assisted usage |

Development Tools

The workflow is config-driven: import rule values in config, validate the config, then run focused tests or the built CLI. See docs/TOOLS.md for the current command list.

Codex Skill

This repository includes an installable Codex skill at skills/override-proxy. Install it from this GitHub repository with the skill-installer workflow by using repo crescendolab-open/override-proxy and path skills/override-proxy.

The skill guides agents toward a project-local devDependency setup, then helps them author configs or rules with the same commands the repository will use.

Quick Start

Install it in your app or mock workspace:

pnpm install -D @crescendolab/override-proxy

Create override-proxy.config.ts:

import { defineConfig, rule } from "@crescendolab/override-proxy";

const Ping = rule("GET", "/__ping", (_req, res) => {
  res.json({ ok: true, source: "override-proxy" });
});

export default defineConfig({
  servers: [
    {
      port: 4000,
      routes: [
        {
          path: "/",
          target: "https://pokeapi.co/api/v2/",
          http: { rules: [Ping] },
        },
      ],
    },
  ],
});

Validate and serve:

pnpm exec override-proxy validate
pnpm exec override-proxy serve
curl http://localhost:4000/__ping

For repeatable team usage, add package scripts in the consuming project:

{
  "scripts": {
    "proxy:validate": "override-proxy validate",
    "proxy:serve": "override-proxy serve"
  }
}

Then run pnpm run proxy:validate and pnpm run proxy:serve.

Repository Development

From this source checkout:

pnpm install
pnpm dev

pnpm dev runs the CLI serve path through nodemon.

Validate a config file without listening:

pnpm exec tsx cli.ts validate
pnpm exec tsx cli.ts validate --config ./override-proxy.config.ts

Build the standalone package entrypoints:

pnpm run build
node dist/cli.js validate

Release workflow:

pnpm changeset

Every user-facing change should include a changeset. After changes land on main, the Release workflow uses Changesets to open a version PR. Merging that version PR publishes to npm through pnpm release; the repository must provide an NPM_TOKEN secret for publishing.

Environment Variables

Load order (first wins, no overwrite): .env.local → .env.default

Sample .env.default (do not put secrets here):

PROXY_TARGET=https://pokeapi.co/api/v2/
PORT=4000
# CORS_ORIGINS=http://localhost:3000,https://your-app.local

| Name | Description | Default | | ------------ | ----------------------------------------------- | ---------------------------- | | PROXY_TARGET | Upstream target when no rule matches | https://pokeapi.co/api/v2/ | | PORT | Preferred port (auto-increments if busy) | 4000 | | CORS_ORIGINS | Allowed origins (comma list, empty = allow all) | (empty) |

Put secrets only in .env.local (ignored by git). .env.default is committed and should remain non-sensitive.

CLI And Config Files

The CLI command defaults to serve. In this source checkout, run it through tsx:

pnpm exec tsx cli.ts
pnpm exec tsx cli.ts serve --config ./override-proxy.config.ts
pnpm exec tsx cli.ts validate --config ./override-proxy.config.ts

After pnpm run build, the package exposes override-proxy from ./dist/cli.js. Installed package usage should go through the consuming project's local dependency:

pnpm exec override-proxy
pnpm exec override-proxy serve --config ./override-proxy.config.ts
pnpm exec override-proxy validate --config ./override-proxy.config.ts

When consuming the built or installed package, config files can import helpers from @crescendolab/override-proxy. In this source checkout before building, import from local source files such as ./config.js.

Default config discovery checks the current working directory for:

1. override-proxy.local.config.ts
2. override-proxy.local.config.mts
3. override-proxy.local.config.js
4. override-proxy.local.config.mjs
5. override-proxy.config.local.ts
6. override-proxy.config.local.mts
7. override-proxy.config.local.js
8. override-proxy.config.local.mjs
9. override-proxy.config.ts
10. override-proxy.config.mts
11. override-proxy.config.js
12. override-proxy.config.mjs

Local config names are ignored by the repository's default .gitignore.

If no config file exists, override-proxy runs in legacy proxy mode using PROXY_TARGET, PORT, and CORS_ORIGINS.

Example multi-route config:

import { defineConfig } from "./config.js";
import { ApiUser } from "./rules/api-user.js";
import { RootFallback } from "./rules/root-fallback.js";

export default defineConfig({
  servers: [
    {
      name: "main",
      host: "127.0.0.1",
      port: 4000,
      routes: [
        {
          name: "api",
          path: "/api",
          target: "https://api.example.com",
          http: {
            rules: [ApiUser],
          },
          rewrite: { stripPrefix: true },
        },
        {
          name: "root",
          path: "/",
          target: "https://www.example.com",
          http: {
            rules: [RootFallback],
          },
        },
      ],
    },
  ],
});

Routes are matched by pathname with priority, longest segment-aware prefix, declaration order, and root fallback.

Config exports can be objects, factories, or async factories:

import { readFile } from "node:fs/promises";
import { LocalRule } from "./rules/local.js";

export default defineConfig(async () => {
  const fixture = JSON.parse(await readFile("./fixtures/user.json", "utf8"));

  return {
    servers: [
      {
        routes: [{ path: "/", http: { rules: [LocalRule(fixture)] } }],
      },
    ],
  };
});

Rule System

Rules are ordinary JavaScript values attached to config. Put them inline or import them from any module; config may be an object, function, or async function, so filesystem reads and other setup belong in userland config code.

Interface:

interface OverrideRule {
  name?: string;
  enabled?: boolean; // default true
  methods: [Method, ...Method[]]; // non-empty, uppercase
  test(req: Request): boolean;
  handler(
    req: Request,
    res: Response,
    next: NextFunction,
  ): void | Promise<void>;
}

Helper creation styles:

1. Overload form:

rule(method: Method | readonly Method[], path: string | RegExp, handler, options?)

1. Config object form:

rule({ path?: string|RegExp, test?: (req)=>boolean, methods?: readonly Method[], name?, enabled?, handler })

Constraints:

• Provide either path or test (if both given, test augments path match logic you control).
• If methods omitted in config form it defaults to ["GET"].
• First matching enabled rule short-circuits.

Authoring patterns:

1. export const SomeRule = rule(...) and import it from config.
2. Export arrays for scenario packs, then spread them into http.rules or ws.rules.
3. Use name when logs need a stable display value; otherwise the helper derives one from path when possible.

WebSocket Rules

WebSocket support targets raw WebSocket traffic. It does not implement Socket.IO protocol semantics.

Route config supports three modes:

| Mode | Behavior | | -------- | ------------------------------------------------------------------------ | | direct | Transparent WebSocket proxy using the upstream target | | bridge | Accept client socket, optionally connect upstream, and run message rules | | mock | Accept client socket without opening an upstream connection |

For WebSocket routes, set ws.target to the upstream origin or base path. The client request path is appended after route rewrites, and bridge mode forwards the client query string to the upstream URL.

Bridge and mock message rules use wsRule():

import { wsRule } from "../../utils.js";

export const PatchChatMessage = wsRule({
  test: (ctx) =>
    ctx.direction === "client" && ctx.jsonObject?.["type"] === "message",
  handler: (ctx) => {
    ctx.emitToClient({ type: "proxy:seen" });
    return ctx.forward({
      ...ctx.jsonObject,
      patchedByProxy: true,
    });
  },
});

Each message context includes raw, text, json, jsonObject, direction, route metadata, request headers, and action helpers. Supported actions are forward, skip, emitToClient, emitToUpstream, close, and fail.

Use wsConnectionRule() when the proxy should send messages without waiting for client or upstream traffic, such as welcome events, heartbeat pings, or server-push mocks:

import { wsConnectionRule } from "../../utils.js";

export const Heartbeat = wsConnectionRule({
  onConnect: (ctx) => {
    ctx.client.send({ type: "proxy:ready" });

    ctx.every(30_000, () => {
      ctx.client.send({ type: "proxy:ping", at: Date.now() });
    });
  },
});

The connection context exposes typed client and optional upstream peers with send, close, and readyState. Advanced rules can use ctx.raw.client / ctx.raw.upstream for the underlying ws sockets. Timers registered with ctx.every() and disposers returned from onConnect() are cleaned up when the connection closes.

Examples

4.1 Simple path

import { rule } from "../utils.js";
export default rule({
  name: "ping",
  path: "/__ping",
  methods: ["GET"],
  handler: (_req, res) => res.json({ ok: true, t: Date.now() }),
});

4.2 RegExp capture

import { rule } from "../utils.js";
export default rule({
  name: "user-detail",
  path: /^\/api\/users\/(\d+)$/,
  methods: ["GET"],
  handler: (req, res) => {
    const match = /^\/api\/users\/(\d+)$/.exec(req.path);
    if (!match) {
      res.status(404).json({ error: "not_found" });
      return;
    }
    const [, id] = match;
    res.json({ id, name: `User ${id}`, from: "override" });
  },
});

4.3 Custom test

import { rule } from "../utils.js";
export const rules = [
  rule({
    name: "feature-core",
    test: (req) =>
      req.method === "GET" &&
      req.path === "/feature-controls" &&
      req.query["only"] === "core",
    handler: (_req, res) =>
      res.json({ features: ["core-a", "core-b"], ts: Date.now() }),
  }),
];

4.4 Disabled rule

export default rule({
  name: "temp-off",
  path: "/disabled",
  enabled: false,
  handler: (_r, res) => res.json({ off: true }),
});

Built-in Endpoints

| Path | Method | Description | | ------------- | ------ | ------------------------------------- | | /__env | GET | Legacy non-sensitive environment info | | /__override | GET | Config-mode server and route snapshot | | * | ANY | Route-specific proxy fallback |

Route CORS settings apply to route traffic, not built-in control endpoints.

Logging pattern: [id] -> METHOD path / match ruleName / completion line with status & source.

Development Workflow

1. Add or edit rule modules.
2. Import the active rules from override-proxy.config.ts.
3. Run pnpm exec tsx cli.ts validate.
4. Start with pnpm dev and send requests to validate behavior.

Change upstream: set PROXY_TARGET in .env.local
Restrict CORS: CORS_ORIGINS=http://localhost:3000,https://dev.example.com

Project Structure

.
├─ cli.ts
├─ index.ts
├─ config.ts
├─ server-runtime.ts
├─ http-app.ts
├─ ws-direct-proxy.ts
├─ ws-bridge.ts
├─ main.ts
├─ utils.ts
├─ tests/
├─ .env.default
├─ package.json
├─ tsconfig.json
├─ tsconfig.build.json
└─ nodemon.json

Common Scenarios

• Simulate latency: await new Promise(r => setTimeout(r, 800));
• Conditional override: test: (req)=> req.path === "/api/users" && req.headers["x-mock-mode"] === "1"
• Header trigger: test: (req)=> req.headers["x-mock-mode"] === "1"
• WebSocket mock event: ctx.emitToClient({ type: "proxy:ready" }); return ctx.skip();

Security Notes

• Keep secrets only in .env.local.
• Remove or protect /__env if exposing externally.
• Rules execute arbitrary code: review sources.
• Avoid exposing this service directly to the public Internet.

Extension Ideas

| Feature | Description | | ----------------------- | -------------------------------- | | /__rules | List rules + status + hit counts | | Runtime toggle | Enable/disable via PATCH | | Hot replace | chokidar-based in-process swap | | Fault / delay injection | Simulate 4xx/5xx/timeout | | Stats | hit count / last hit timestamp | | Priority control | Explicit rule ordering |

Rule Organization & Archival

You can still keep rule modules under rules/, but runtime does not scan that directory. Config decides exactly which rule values are active.

11.1 Group Related Rules

• Group by feature / domain / scenario using either subfolders and/or multi-export files.
• Import the packs you want in override-proxy.config.ts.

11.2 Disable Single Rule

To temporarily disable a single rule without deleting it, add enabled: false to the rule configuration:

export const UserDetail = rule({
  methods: ['GET'],
  path: /^\/api\/users\/\d+$/,
  enabled: false,
  handler: (req, res) => res.json({ ... })
});

The rule remains in config but won't match requests.

11.3 Disable an Entire Group

Remove that pack from the config array, or branch inside an async config factory:

const rules = process.env["MOCK_PACK"] === "checkout" ? checkoutRules : [];

11.4 Shareable by Design

• Committed config and rule modules are instantly shared—teammates restart and get the same overrides.
• Avoid secrets / PII in responses. Use env vars or synthetic placeholders if needed.
• Scenario-oriented packs let you prepare multiple demo states and enable exactly one by config import or factory branch.

11.5 Personal / WIP Rules

• For scratch work you do not want committed, use override-proxy.local.config.ts and keep it git-ignored.

11.6 Naming Guidance

• Module names: concise, kebab-case domain or scenario (billing-refunds, chat-surge-test).
• Rule name (shown in logs): stable identifier (PascalCase or kebab-case) reflecting purpose.

11.7 Quick Lifecycle Table

| Action | Steps | | ------------------- | ------------------------------------- | | Add feature pack | Create module, import rules in config | | Disable single rule | Add enabled: false to rule config | | Disable rule group | Remove pack from config or branch env | | Share | Push config/rule modules and restart |

11.8 Why Inline over Runtime Scanning?

Inline config keeps runtime simple and makes TypeScript point directly at missing imports, wrong rule shapes, and dead code.

Comparison with MSW

override-proxy and MSW both solve API interception/mocking but sit at different layers: this project is a standalone reverse proxy that applies override rules first and transparently forwards the rest; MSW runs inside your runtime (Service Worker in the browser or a Node process). They are often complementary (team‑wide shared partial overrides via override-proxy; fully deterministic isolated tests & Storybook via MSW).

| Aspect | override-proxy | MSW | When to favor override-proxy | When to favor MSW | | ------------------------ | ---------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------- | | Deployment form | Standalone Node reverse proxy | In-process (Service Worker / Node) | Need one shared layer for Web, Mobile, backend scripts | Only JS app/tests, want zero base URL changes | | Override strategy | First matching rule short-circuits, rest passthrough | All requests potentially intercepted; passthrough needs opting in | Partial mock + keep real behavior for the rest | Fully controlled, offline, deterministic data | | Upstream realism | Unmatched hits real upstream (reduced mock drift) | All data must be defined/generative | Want to reduce divergence between mock and prod | Want fully stable replayable fixtures | | Team sharing | Point base URL; everyone instantly uses same overrides | Must add handlers per repo | Fast alignment “what’s overridden today” | Single codebase control is enough | | Client languages | Any (JS, iOS, Android, backend) via HTTP | Primarily JavaScript ecosystems | Multi-language integration workflows | Pure JS/UI workflows | | Logging & observability | Centralized request log (latency, status, source, rule) | Distributed per environment | Need mixed real+mock traffic insight | Local test verbosity sufficient | | CORS / network semantics | Real browser/network semantics preserved | Simulated inside SW/Node | Need to validate real cookies/CORS/TLS | Network realism not required | | Adoption cost | Run one process + point base URL | Install lib + configure handlers in each env | Want zero code intrusion | Prefer inline mocks in tests | | Extensibility surface | Natural spot for caching, record/replay, fault/latency injection | Built-in REST/GraphQL/WebSocket already | Need proxy aggregation / caching | Need protocol breadth immediately | | Non-JS test integration | Any stack via HTTP | Requires JS runtime | Mixed polyglot E2E | JS-only test matrix |

Key strengths of this project

1. Override‑first with transparent passthrough: author only what you need to change; everything else stays real, reducing maintenance & data drift.
2. Cross‑client sharing: any device or language adopts overrides by switching a base URL (or system proxy).
3. Low intrusion: no library embedded in the app—easy to adopt or discard.
4. Real network conditions: genuine CORS, cookies, caching, TLS; good for integration sanity checks.
5. Flexible rules: an override is just an Express handler—inject latency, errors, dynamic data, conditional passthrough.
6. Layered env loading: safe defaults in .env.default, secrets in .env.local (git‑ignored).
7. Evolution friendly: ideal anchor point for future record & replay, metrics, runtime toggles, chaos/fault injection, priority control.
8. Short learning curve: minimal API (defineConfig() + rule() / wsRule()); experienced Node/Express users are productive immediately.

Typical combined workflow with MSW

• Day-to-day team development: run override-proxy for shared partial overrides + live upstream behavior.
• Test / CI: use MSW for 100% deterministic, offline, fast tests.
• Demo / Storybook: point at override-proxy for realistic hybrid data; fall back to MSW when full offline determinism needed.

Summary: override-proxy is a shared, real-network, partial-override layer; MSW is an in-process, fully controllable interception layer. They complement rather than exclude each other.

Architecture & Flow (Mermaid)

flowchart LR
  subgraph Client
    A[Request]
  end
  A --> B[override-proxy]
  B -->|rule match| C[Override handler]
  B -->|no match| U[(Upstream API)]
  C --> R[Response]
  U --> R
  R --> A
  %% Behaviors: dynamic JSON, latency, error injection
  classDef proxy fill:#0d6efd,stroke:#084298,stroke-width:1px,color:#fff;
  class B proxy;

Complementary Usage with MSW

sequenceDiagram
  participant DevApp as Frontend App
  participant OP as override-proxy
  participant Up as Upstream API
  participant MSW as MSW (test env)

  Note over DevApp,OP: Local dev (shared partial overrides)
  DevApp->>OP: GET /api/items
  OP->>OP: Match rule?
  alt Rule matches
    OP-->>DevApp: Mocked JSON
  else No match
    OP->>Up: Forward request
    Up-->>OP: Real response
    OP-->>DevApp: Real JSON
  end
  Note over DevApp,MSW: Test/CI (fully mocked)
  DevApp->>MSW: GET /api/items
  MSW-->>DevApp: Deterministic mocked JSON

License

Apache License 2.0 © 2025 Crescendo Lab. See LICENSE for full text.

Author: Crescendo Lab — 2025

Need extras (rule listing, runtime toggles, latency/error injection)? Open an issue or ask.