merge-port

merge-port

Local reverse proxy. Two upstreams (or many), one listen port. Pure path routing — no containers, no DNS, no TLS termination.

Repo: github.com/anivaryam/merge-port. Binary: merge-port (install via brokit install merge-port, go install, or release tarball).

When to reach for it

• Frontend (5173) + backend (3001) → one URL (e.g. :8080) so cookies, fetches, and WebSockets share an origin.
• Tunnel a single port instead of two.
• Container entrypoint that must serve everything on $PORT.
• Multiple backends behind one origin (/api → 3001, /auth → 3002, / → 3000).

Do NOT use for: TLS termination (put a real LB in front), production load balancing across hosts, sticky sessions, or anything that needs request rewriting beyond prefix-based routing.

Two modes

Simple mode

merge-port --client 5173 --server 3001 --port 8080

• /api/* → server (3001)
• everything else → client (5173)

Repeatable --api-prefix to add more server routes:

merge-port --client 5173 --server 3001 \
  --api-prefix /api --api-prefix /auth --api-prefix /uploads

Route mode

Multiple backends, explicit prefixes:

merge-port --route /api=3001 --route /auth=3002 --route /=3000

Target accepts: bare port (3001), host:port, or full URL (http://admin.local:4000).

Route mode is exclusive with --client/--server/--api-prefix. Pick one form.

Add /=... as catch-all in route mode if you want frontend fallback — without it, unmatched paths return 404.

Routing rule: longest prefix wins. WebSockets pass through transparently (the proxy honours upgrade frames).

Config files

merge-port init                                # writes .merge-port.yaml in cwd
merge-port init --client 5173 --server 3001 --dry-run

Simple mode YAML:

port: 8080
client: 3000
server: 3001
api_prefixes:
  - /api
  - /auth

Route mode YAML:

port: 8080
routes:
  - prefix: /api
    target: "3001"
  - prefix: /
    target: "5173"