Add a fallback handler for routes that cannot be enumerated #5
2026-07-28
docs: document fallback routing for both listeners
New "Routes that cannot be enumerated" section, linked from both listener sections since the hook and its precedence are identical on each. Also records the HTTP/3 query-strip change and why a fallback has to be a constructor argument on the ListenerAsync* wrappers.
test(http): replay one fallback route table over both listeners
The point of the feature is that a URL means the same thing over either protocol, so the test states it that way: one route map plus one fallback, registered with ListenerHTTP1 and ListenerHTTP, asked the same eight questions, asserting identical answers. Covers exact routes beating the fallback, query strings still routing to the bare path, the fallback seeing the full target including the query, the fallback choosing its own status (404 and 303), a throwing fallback becoming a 500, and an unset fallback still producing the listener's own synthetic 404. Verified against a broken build both ways: dropping the fallback lookup fails 9 checks, dropping the query-strip fails 2.
feat(http): give ListenerHTTP the same fallback and query-strip routing
ListenerHTTP1's docs promise the same route map shape as ListenerHTTP so a handler can be registered with both and served over either protocol. That only holds if the dispatch rule is the same on both, so mirror it here: exact `:path`, then the query-stripped path, then `fallback`, then the synthetic 404. The query-strip half is a behaviour change on this listener. `/thing?x=1` previously 404'd even with `/thing` registered, while HTTP/1.1 routed it — the asymmetry the shared route map was supposed to avoid. It also matters for `fallback`: without it a query string would divert a registered path to the fallback over HTTP/3 but not over HTTP/1.1. `fallback` covers `routes` only. An unmatched WebTransport CONNECT is still a 404 — a WT handler takes a session, not a request, so there is nothing sensible to hand it. MakeBidiHandler now reads the maps off `self` instead of taking them as pointer parameters. `self` was already captured and unused, and this mirrors how ListenerHTTP1 reaches its own state through Impl::owner.
feat(http1): dispatch unmatched paths to an optional fallback handler
The route map only answers paths that are known when the listener is built. A route with an unbounded segment — /shop/<slug>, /order/<token>, /posts/<id> — cannot be pre-registered: the token space is unbounded and the product set changes while the server runs. Every such request became a synthetic 404 that the application never got to see. Add one optional member, called for anything `routes` missed, with the full target still in request.path. Precedence is exact path, then the query-stripped path, then fallback, then the 404 as before, so a default-constructed listener behaves byte-identically and no call site changes. A hook rather than a pattern syntax: consumers that already have a router — one shared between a wasm frontend and the server, so a URL cannot mean different things to a crawler and to the app — keep using it, and there is no second route table to disagree with the first. PathWithoutQuery moves out of this file into :HTTP as an exported PathWithoutQueryHTTP, since ListenerHTTP now needs the same split and a fallback handler almost always does too. ListenerAsyncHTTP1 starts accepting inside its constructor, so assigning `listener.fallback` afterwards would race the accept loop; it gets a constructor overload that installs the fallback before the thread starts.