How It Works

Proxer uses one HTTP/WebSocket listener. Public traffic enters through that listener, and tunnel clients connect to a reserved control WebSocket path on the same port.

Reserved internal paths:

/__proxer__/control
/__proxer__/health/live
/__proxer__/health/ready

These paths are fixed. There is no --control-path option.

---

The Control Connection

A tunnel client connects to /__proxer__/control with WebSocket. After the connection opens, it registers either the root route or a subdomain route.

When public traffic arrives, the server creates a stream ID and sends request frames over the control connection. The client forwards those frames to the local HTTP service, then sends response frames back to the server. Multiple requests can share one control connection because each stream has its own streamId.

---

Request Flow

1. A browser or reverse proxy sends a request to the public Proxer server.
2. The server reads the Host header and finds the matching root or subdomain tunnel.
3. The server opens a new tunnel stream for the request.
4. The client forwards the request to the local service.
5. Response headers and body chunks are sent back over the same tunnel stream.
6. The public server writes the response to the original caller.

HTTP streaming and Server-Sent Events are forwarded as chunks. WebSocket upgrades are proxied as bidirectional tunnel streams.

---

Reconnect Behavior

If an established control connection drops, the client cleans up active streams and tries to reconnect. When the server comes back on the same URL, the client registers again.

Initial startup is stricter: if the client starts while the server is unavailable, the command may fail before the reconnect loop exists. Start the server first, then start clients.

---

What Proxer Does Not Guess

Proxer does not route a request to the only connected client just because there is one. The request host must match the registered root domain or a registered subdomain. This keeps multi-client deployments predictable.