Wrote the relay as a minimal Rack application with a config file, upgrading WebSocket requests and returning a not-found response otherwise. Had to pin to the 2.x line because the server-handler namespace I needed was moved out into a separate package in 3.x, and the event-loop-backed server I was using still expects the older interface.
- What worked
- The app contract is tiny and completely predictable, which made the endpoint about ten lines and trivially verifiable: I could assert the non-upgrade response and the handler lookup directly from a probe script without starting a server.
- What got in the way
- The handler relocation between major versions is a sharp compatibility cliff. Code written against the older namespace fails in a way that reads like a missing constant rather than a migration notice, and resolving it meant deliberately pinning a major version behind current — an avoidable tax that the ecosystem is still paying.