switchyard: tell Switchyard the app's route.go paths and workers (#102101)
### About this stack
These PRs let Switchyard, the experimental Go server in front of
self-hosted `next start` (`__NEXT_EXPERIMENTAL_SWITCHYARD=1`, #101695
and #102035), send `route.go` requests straight to their Go worker
instead of through Node. Switchyard goes direct only when Node would
have passed the request to the worker unchanged, so clients get the same
response either way; everything else keeps going to Node. Each PR adds
one kind of request that can go direct. The stack splits #101981 for
review.
1. **→ This PR:** **Skeleton** (#102101): Node tells Switchyard which
exact paths are route.go handlers, and which route.go workers are
running. Every request still goes to Node.
2. **Happy path** (#102102): requests to exact route.go paths go
straight to the worker, with any headers, built exactly as Node would
build them.
3. **Query strings** (#102103): requests with a query that Node would
pass on unchanged.
4. **Dynamic segments and catch-alls** (#102113): `/go/users/[id]`,
`[...path]` and `[[...path]]`, matched in the router's order.
5. **basePath** (#102114): apps that set a `basePath`.
6. **Request bodies** (#102115): POST and PUT with a body, including
answers sent before the upload ends.
7. **Early Hints** (#102116): 103 responses are dropped, as Node drops
them.
8. **Compression** (#102117): apps with `compress` on (the default),
compressed the way Node does, so browser requests can go direct.
9. **Worker threads** (#102118): each route.go worker runs Go code on at
most 4 threads by default.
10. **Trailers and the response-header limit** (#102119): trailer values
are dropped and Node's limit on a worker's response headers applies, as
through Node.
11. **Hop-by-hop response headers** (#102120): the worker's
`Keep-Alive`, `Proxy-Authenticate` and similar headers reach the client,
as through Node.
### What?
Under `next start` with Switchyard on, Node now tells Switchyard about
the app's `route.go` routes. Switchyard stores what it hears but still
sends every request to Node; the next PR starts using it.
- **The route table.** Once the router has loaded the app, Node sends
whether the app can use the direct path at all, and if so which exact
paths are `route.go` routes and which ones Node answers itself (pages,
public files, `/_next/`).
- **Workers.** Node keeps starting and owning `route.go` workers. It now
also reports each one when it's ready, and again when it exits or is
retired.
`DEBUG=next:switchyard` shows both. Without Switchyard, nothing changes:
the table module is only loaded when Switchyard asks for it.
### Why?
To send a `route.go` request to its worker directly, Switchyard needs to
know which paths are `route.go` routes and where their workers listen.
Node already has both: the router's startup data (`fsChecker`) and
`NativeRouteManager`. This PR passes them on instead of having
Switchyard work them out again.
### How?
- `switchyard-route-table.ts` builds the table from the router's data.
An app that uses anything Node runs before routing (`proxy.ts`,
rewrites, redirects, `next.config` headers, i18n, instrumentation) gets
a table with only a `reason`. Apps with a `basePath` or `compress` on
(the default) also get a reason for now; later PRs in the stack remove
those.
- Node writes JSON lines to Switchyard's stdin (`control.go`): `table`,
then `worker` and `gone` as workers start and stop. The table is sent
once the router has loaded, after Switchyard is already accepting
requests, so `next start` reports ready as early as before.
- Switchyard replaces its state whole on each message, so a request
reads either the old state or the new one. `routing.Load` reads the
table in the `routing` package, which imports no network code (a test
enforces that) so other hosts can share it.
### Verification
- `go test -race ./...` in `packages/next/src/server/switchyard`:
loading tables, reading control messages, and applying table, worker and
gone messages.
- `test/unit/switchyard-route-table.test.ts`: each reason an app gets no
direct routes, and the exact-path table.
- `pnpm typescript`.
- With `__NEXT_EXPERIMENTAL_SWITCHYARD` off and on:
`test/production/app-dir/switchyard/switchyard.test.ts` and
`switchyard-process.test.ts`, 52 of 53 both ways. The other is "keeps
external callers out of loopback-only API routes", which connects to the
machine's own network address and fails locally with Switchyard off too;
CI runs it.
<!-- NEXT_JS_LLM -->
🤖 Generated with [Claude Code](https://claude.com/claude-code)