Explore application-typed handshake rejection codes - #403
Merged
Conversation
wernst
approved these changes
Aug 25, 2026
Mayank808
added a commit
that referenced
this pull request
Aug 25, 2026
## Why River 0.221.0 includes the new application-typed handshake rejection code API from #403. ## What changed Bumps the `@replit/river` package version from 0.220.1 to 0.221.0. This prepares the package metadata for the next minor npm release. ## Versioning - [ ] Breaking protocol change - [ ] Breaking ts/js API change
2 tasks
Armster15
added a commit
that referenced
this pull request
Sep 2, 2026
## Why River already stores WebSocket upgrade headers in `connection.extras`, but server handshake validation cannot read them. A downstream gateway authenticates a session cookie during WebSocket upgrade and needs to pass the verified identity to `validate`. ## What changed Server handshake validation now accepts one optional argument: ```ts validate(metadata, previousMetadata, from, connectionExtras) ``` River passes the extras from the current connection at both validation sites: - The initial handshake receives the extras for the new socket. - A same-socket rehandshake receives the original extras for that socket. - A reconnect creates a new socket, so its handshake receives the new socket extras. `WebSocketServerTransport` also accepts an optional fourth constructor argument: ```ts new WebSocketServerTransport(wss, clientId, options, (ws, req) => extras) ``` The default behavior is unchanged. Without a factory, River stores the same cleaned upgrade headers that it stores today. The factory is synchronous because River must install the socket message handler during the connection event. Applications can finish asynchronous authentication before this event and let the factory read the verified result. Existing three-argument `validate` functions still compile and work. This PR does not change protocol messages or package versions. The typing and tests follow the precedent in #403. The README now documents the new validator argument, factory, and synchronous constraint. ## Test plan - `npm run check` - `npm run test:single` (785 passed, 1 skipped) - `npm run build` - `npx prettier README.md --check` ## Versioning - [ ] Breaking protocol change - [ ] Breaking ts/js API change ~ written by Zerg 👾 ([volatile-queen-8e97](https://zerg.zergrush.dev/chat?id=volatile-queen-8e97))
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Exploration PR, alternative to #401. This sketches application-typed handshake rejection codes: applications declare their codes as a tuple of TypeBox literal schemas,
validatemay return them, and they travel in the handshake response'scodefield with compile-time checking on both peers.The generics are parameterized on the schema tuple itself (
ReadonlyArray<TLiteral<string>>), never on barestringunions — the code type is derived from the schemas, so this shape works end to end:Versioning