DSH plugin web server: route matching and fallback seats
A registered route that 404s usually lost to the fallback seat or to prefix match ordering, not to a typo in the path. DSH plugin's HTTP server matches in a fixed order: exact, longest prefix, fallback. Registration order takes no part in matching — remember that first.
The server serves browsers only
It is neither a capability seam nor part of the agent loop.(source)
dsh-host-webserver is the browser HTTP carrier for the GUI Host: a node:http server (switching to node:https when tls is configured) providing ctx.webServer, a named route registry, optional gzip response compression, an index.html transform callback, and a fallback (handler or resource) a plugin can claim.
It is not part of the agent loop and not a capability seam; the only harness concept involved is the Peer represented by index rendering.
Other plugins register all functional routes, including the /api bridge, plugin bundles, and the HMR event stream. This server serves browsers only: Electron loads built files via file:// and sends fetch requests through an IPC bridge, never through this server.
Route matching: exact, longest prefix, fallback
Registration order carries no meaning; a conflict is a configuration error.(source)
WebRouteKind has two values: exact matches pathname literally; prefix p matches p and p/<anything>. A WebRoute path is absolute with no trailing slash, and its handler owns the full response lifecycle, so it can hold a response open like an SSE stream.
Matching is fixed: consult the exact table, then take the longest matching prefix, then fall through to the registered fallback. Registration order carries no request-facing semantics.
Named routes are disjoint by composition, and every request no named route claims is answered by the fallback seat. That seat has exactly one owner; a second registration throws.
The published web composition claims the seat with dsh-host-frontend-static, a SPA dist server with fixed semantics: Connection authenticates before reading the dist root and configured index HTML; non-index assets stay public; non-GET/HEAD returns 405; traversal outside the dist root returns 403; existing files are served directly; missing or non-file targets return an empty 404; unknown extensions are sent as octet-stream.
resource versus handler
Routes producing side effects or returning private data should be handlers even when answering GET.(source)
A route or fallback may use resource — a function mapping a Fetch Request to a Response — instead of a handler. A WebResource answers HTTP GET and HEAD requests and in-process reads too.
The key difference is the Peer: HTTP GET and HEAD arrive at a resource with no Peer, while readResource(request, peer) reads it in process under the caller's admitted Peer. Reads follow the same match order but reach resources only.
Hence the practical criterion: routes returning owner-private data or performing actions stay handlers even when answering GET. Resources suit public, side-effect-free reads.
Config: address, TLS, compression
The listen address must be a concrete literal; wildcard addresses are rejected at load.(source)
Config fields and defaults:
host— a concrete IPv4 or IPv6 literal of some local interface. A loopback literal keeps the server on this machine; other literals serve that address's network over plaintext HTTP unlesstlsis configured. An unspecified address is rejected at load because it exposes every interface at once.port— the listen port; 0 lets the operating system assign one.tls— certificate chain and private key files, both read once before the listener binds. Unreadable, empty, invalid PEM, or mismatched key and certificate all reject initialization instead of falling back to HTTP; material is never re-read, so replacing certificates needs a reload.compression—'none'or'gzip', defaulting to'none'.compressionLevel— gzip DEFLATE level 0 to 9, defaulting to 1.compressionThresholdBytes— the minimum gzip threshold for a known response length, defaulting to 1024; streams of unknown length also qualify.
The carrier owns no authentication or Origin policy. The shipped dsh web command defaults to loopback and accepts a concrete --host address; a non-loopback plaintext bind warns at startup. Its Connection plugin supplies Host/Origin validation and browser session authentication for every Host API route and stream; the bind address plus --trusted-host decides which browser Host is accepted, and --public-url only changes the announced URL.
Service behavior: listen, register, compress, index injection
A listen failure rejects initialization rather than pretending to start.(source)
WebServer (ctx.webServer) listens immediately on activation; a listen failure such as EADDRINUSE rejects initialization, and the starting process reports the failed fiber.
register(route) adds one named route and returns its disposer. A duplicate (kind, path) throws, because route patterns are a composition-level contract and a conflict is a configuration error.
gzip wraps qualifying socket-based responses inside the server, so handlers keep holding ServerResponse directly while resources hand a Response back for the service to write. Existing content encodings, Cache-Control: no-transform, range responses, SSE, ZIP, and packed .gz Worker images all keep identity responses.
Index injection has two entry points: collectIndexInjections(peer) gathers structured IndexInjection lines through one webserver/index-inject emit for the Peer the page represents, and renderIndex(html, peer) renders them into successful root and configured index responses, then applies raw tapIndex(transform) escape-hatch transforms in registration order. dsh-client-modules answers that event with startup manifest lines.
Read facts from port (including the OS-assigned port when config.port is 0) and protocol (http: or https:) instead of guessing.
Errors, disposal, and output ownership
Teardown must forcibly close connections, or SSE will hang the process.(source)
A request throwing during handling is logged as a warning and answered with 400 (or the socket is destroyed if headers were already sent) and never exits the process. Typical cases: malformed % escapes hitting decodeURIComponent, or a client disconnecting mid-body.
dispose pairs close() with closeAllConnections(), because handlers may hold responses open like SSE and those connections never finish on their own; without a forced close, teardown hangs.
TLS sockets count as connections only after the handshake, so the server tracks both the raw TLS socket and the upgraded socket and destroys both at dispose.
The package never prints output: URL lines belong to the shell. That boundary is often mistaken for "startup failed," when it is only a different output owner.
Verification: register an endpoint
Cover match order, the fallback, and disposal.(source)
- Register an
exact/api/ping, request it, and assert it hits instead of the fallback. - Register a
prefix/assets, request/assets/app.js, and assert it hits; requesting/assetsitself should hit too. - Register both exact
/a/band prefix/a, request/a/b, and assert exact wins. - Request an unclaimed path and assert the fallback answers (404 or index under the static composition).
- Register the same
(kind, path)twice and assert a throw rather than a later registration overwriting. - Open a long-lived SSE connection, call
dispose, and assert the process does not hang andcloseAllConnectionstook effect.
If step 3 hits the prefix, check whether both were declared as prefix — longest-prefix comparison only happens between prefixes.
For the overall client layering, see web client layering; for common disposer problems, see web route disposer.
One line to close: browsers only, exact before prefix, one fallback owner, private data through handlers, wildcard addresses rejected at load, and teardown must force connections closed.
FAQ
Check the fallback seat and matching order. DSH plugin always matches the exact table, then the longest prefix, then the registered fallback; registration order carries no request-facing meaning.
No. DSH plugin's fallback seat has exactly one owner. DSH plugin throws on a second fallback registration, treating the conflict as a composition configuration error.
No. DSH plugin's Electron loads built files through file://. DSH plugin's HTTP server serves browsers only, and Electron fetch requests go through an IPC bridge.
No. DSH plugin reads certificates once before binding the listener. DSH plugin needs a reload to replace them, and an unreadable, empty, or mismatched file rejects initialization rather than falling back to HTTP.
Related Terms
- WebRoute
- WebRoute is a named route with exact or prefix matching, an absolute path, and a handler owning the full response lifecycle.— packages/host/webserver/src/index.ts
- WebResource
- WebResource maps a Fetch Request to a Response; HTTP GET and HEAD reach it without a Peer.— packages/host/webserver/src/index.ts
- readResource
- readResource reads a resource in process under an admitted caller Peer, using the same match order but reaching resources only.— packages/host/webserver/src/index.ts
- collectIndexInjections
- collectIndexInjections gathers structured IndexInjection lines through one webserver/index-inject emit for renderIndex to render.— packages/host/webserver/src/index.ts
Sources
- DeepSeek Harness reference - HTTP server· deepseek-ai
- packages/host/webserver/src/index.ts· deepseek-ai