Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneeszack

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, Origin and cookies are carried over.
  • Headers. Authorization, cookies and Origin pass through untouched. The router adds no credential. HTTP is forwarded over node:http, because Deno's fetch sends a streamed body chunked and drops its Content-Length, which the v3 datastore's chunk upload requires; node:http keeps both Content-Length and Host. A WebSocket is opened with Deno's client, which sets Host from the URL, so a child reads the public host from X-Forwarded-Host there.
  • Forwarding headers. The router overwrites X-Forwarded-For with the caller's address, X-Forwarded-Host with the caller's Host, and X-Forwarded-Proto with the listener's protocol, so a caller cannot supply its own. Serve reads X-Forwarded-Proto to choose the dashboard session cookie's Secure flag 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, Origin and 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-Host and X-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 host owns 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.
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 21 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/16/2026, 10:08:42 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
zack assigned zack11/16/2026, 7:24:14 PM

Sign in to post a ripple.