Relationships
#4804 The workspace router: forward /w/<name>/ to that workspace's serve
Opened by zack · 11/16/2026· Shipped 11/16/2026
Issue 6 of 18 in the execution plan of design/surfaces/serve-workspaces.md. One PR. No dependencies.
Problem
swamp serve host holds one listener for many serves. It needs a router that sends each request to the right child and gets out of the way: streaming, WebSockets and every credential have to pass through unchanged, because each serve authenticates its own callers.
The local dashboard's hub also forwards /w/<name>/… (src/serve/local/workspace_hub.ts), but only a fixed list of reads to a read-only child. This router is new code with the same path shape.
Change
Add the workspace router in src/serve/host/. It takes a lookup from workspace name to port and state, so it needs no supervisor and can be built and tested on its own.
- Prefix match. A path that starts with
/w/<name>/goes to that workspace with the prefix removed. Every other path goes to the root unchanged, or answers 404 when there is no root. The/w/prefix belongs to the host, so a route the root defines under/w/is never reached. - HTTP. Bodies are streamed in both directions and never buffered, so SSE and the worker data plane pass through.
- WebSocket. Relayed frame by frame between the caller's socket and one the router opens to the child. The query, subprotocols,
Originand cookies are carried over. - Headers.
Authorization, cookies andOriginpass through untouched. The router adds no credential. HTTP is forwarded overnode:http, because Deno'sfetchsends a streamed body chunked and drops itsContent-Length, which the v3 datastore's chunk upload requires;node:httpkeeps bothContent-LengthandHost. A WebSocket is opened with Deno's client, which setsHostfrom the URL, so a child reads the public host fromX-Forwarded-Hostthere. - Forwarding headers. The router overwrites
X-Forwarded-Forwith the caller's address,X-Forwarded-Hostwith the caller'sHost, andX-Forwarded-Protowith the listener's protocol, so a caller cannot supply its own. Serve readsX-Forwarded-Prototo choose the dashboard session cookie'sSecureflag and its expected origin, so the router terminating TLS must send it. A router told it is itself behind a proxy passes on what that proxy reports. - Errors. A workspace that is not running answers 503 with its state. An unknown name answers 404.
The hop from the router to a child is plain loopback TCP.
Done when
An integration test runs the router in-process in front of port-0 serve stand-ins and covers:
- a request and its reply
- a streamed body in each direction, and a streamed upload that keeps its
Content-Length - SSE
- a WebSocket, with subprotocol,
Originand cookies carried over - a 503 for a stopped workspace, naming its state
- a 404 for an unknown name
- forwarding headers sent by the caller are replaced, not passed on
- a child sees the caller's public host and protocol in
X-Forwarded-HostandX-Forwarded-Proto - a path outside
/w/reaches the root unchanged, and answers 404 with no root
Out of scope
- TLS and the listener itself.
swamp serve hostowns those, issue 7 in the plan. - The fitness rule that keeps
src/serve/host/from importing the model, vault and datastore registries. It lands with issue 7.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.