mesh

Local dev proxy. Named services instead of ports. Failure injection without mocks.

app.test   → :3000
api.test   → :4000
admin.test → :5000

No more :3000, :4000, :5000 open in different tabs. No more mixing them up.

Install

npm install -g @avelor/mesh

Requires Node.js 18+. For HTTPS, install mkcert.

Usage

mesh init         # create mesh.yml in current directory
mesh start        # start proxy in background (will prompt for sudo)
mesh status       # show running services
mesh stop         # stop the proxy
mesh route        # start in foreground (useful for debugging)

mesh start runs on :80 and :443 (if mkcert is available), writes the hostname entries to /etc/hosts, and cleans them up automatically on stop.

mesh.yml

services:
  app: 3000
  api: 4000
  admin: 5000

That's enough to get started. Services are available at app.test, api.test, admin.test.

Failure rules

Test how your app handles errors — no mocks, no code changes.

services:
  app: 3000
  api: 4000

rules:
  api:
    - path: /payments
      method: POST
      status: 503
      body:
        error: Payment service unavailable
        retryAfter: 30
      rate: 30
    - path: /auth/login
      status: 401
      rate: 20
    - path: /slow-endpoint
      delay: 2000
      rate: 100
    - path: /flaky
      status: 500
      delay: 800
      rate: 25

| Field | Description | |----------|---------------------------------------------------------------| | path | Request path prefix to match | | method | HTTP method to match (GET, POST, PUT, PATCH, DELETE…) | | status | HTTP status code to return (400, 401, 500, etc.) | | body | Response body — object (sent as JSON) or string (plain text) | | delay | Milliseconds to wait before responding | | rate | Percentage of matching requests to affect (1–100) |

status and delay can be combined: wait N ms, then fail with that status. Without body, the default is { "error": "<status text>", "injected": true }.

Subdomains

Multiple names can point to the same port:

services:
  app: 3000
  tenant1.app: 3000
  tenant2.app: 3000
  api: 4000

Rules apply per name, so tenant1.app and tenant2.app can have different failure scenarios.

HTTPS

If mkcert is installed, mesh route automatically generates a locally-trusted certificate for all your .test domains and serves them over HTTPS. Port :80 redirects to :443.

# macOS
brew install mkcert

# Linux
apt install mkcert

If mkcert is not found, mesh falls back to HTTP only.

Generated certificates are stored in .mesh/ (added to .gitignore by mesh init).

Examples

See examples/basic and examples/multi for working setups with a frontend and API server.

# terminal 1
cd examples/basic
node api.js

# terminal 2
cd examples/basic
node app.js

# terminal 3 (from examples/basic)
mesh route

Then open https://app.test.

How it works

mesh route runs a local HTTP/HTTPS proxy on 127.0.0.1. Incoming requests are matched by hostname, forwarded to the configured port, and optionally intercepted by failure rules before reaching the target service.

/etc/hosts entries are written on start and removed on exit (SIGINT / SIGTERM).

License

MIT