feat(WebSocket): support passthrough, correctly emit the error event

[kettanaito]

Warning

Since WebSocket connections will now be established as-is if you haven't provided any interceptors, this is technically a breaking change despite fixing a bug.

Interceptors has a bug that it will always emit the open even on the WebSocket client, even when there are no interceptor set up for any connections (so the connection cannot physically be intercepted). This results in such connections pending forever.

This may be a big against previously established expectations of WebSocket interception always being mock-first. But this is still a bug for bypassed connections, and it has to be fixed.

I'm fixing this here without breaking any previously established promises.

• WebSocket connection will be mock-first if at least one connection listener on the interceptor is present;
• WebSocket connection will be established as-is if no connection listeners on the interceptors are present (previously, the connection would be OPEN and pend forever).

Discoveries

• The error event is NOT dispatched on non-configurable closure codes, even if those codes represent errors (e.g. data cannot be accepted).
• The error event is dispatched in cases like connection errors or abrupt connection closures.
• Also, Undici v5 has a bug validating WebSocket protocols: WebSocket: wrong subprotocol choose check (response Sec-WebSocket-Protocol header) nodejs/undici#2844. Fixed in Node.js v20 but not in v18.

Roadmap

• Add a failing test.
• Establish the connection as-is if there were no interceptors set (this.emit() returned false).
• Fix the issue where .close() would dispatch an error event on non-configurable closure codes (that's not how WebSocket behave).

[kettanaito]

Alternative solution

Push the WebSocket interception a layer higher, letting the interceptor decide on the connection, whether to mock it, error it, or establish as-is.

interceptor.on('connection', ({ handshake }) => {
  handshake.accept()
  // handleshake.errorWith()
  // handshake.passthrough()
})

This may also be an answer to handling the handshake (protocol upgrade) request. It's been reported that we don't do that at the moment, which may cause issues (mostly in the browser).

[kettanaito]

Released: v0.34.0 🎉

This has been released in v0.34.0!

• 📄 Release notes
• 📦 npm package

Make sure to always update to the latest version (npm i @mswjs/interceptors@latest) to get the newest features and bug fixes.

---

Predictable release automation by @ossjs/release.