Expose WebSocket upgrade context to handshake validation

[Armster15]

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:

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:

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)