feat: add WebSocket class interceptor

[kettanaito]

• Closes feat: add WebSocket interceptor #236
• Closes feat: intercept WebSocket in the browser #484
• See this branch's README.md for the feature documentation.

Changes

• Adds a WebSocket interceptor based on the globalThis.WebSocket class.
• Introduces the client and the server APIs to represent the incoming client connection and the original server connection respectively in the connection listener of the interceptor.
• Adds the required infrastructure of the interceptor/client/server/transport classes that describe the generic class and also the WebSocket class-relevant implementations of them, such as WebSocketClassClient, WebSocketClassServer, WebSocketClassTransport.

Todo

• Tests only: The ws module we use for testing doesn't pass the instanceof check on dispatched events in Node, causing some tests to fail (Use Node.js 15 native EventTarget object websockets/ws#1818).
  • Once this is fixed, unskip the tests at test/modules/WebSocket/WebSocketClass/exchange/websocket.server.connect.test.ts
  • This was caused by JSDOM. It polyfills global Event.
• Write WebSocket compliance tests.
  • Default state
  • Events
  • Methods (.send() and .close() and its input)
  • Setters (.onopen and etc)
• Some third-parties also add origin on the MessageEvent from the socket. Check if the interceptor should do that too (inspect the original WebSocket event).
• Emit the error event correctly. It's emitted in the following scenarios:
  • Connection was closed with a > 1000 <= 1015 (https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1)
  • When sending data and being unable to buffer it anymore (the buffer is full, the connection is marked as full and closed). Such connection closures must "fire an event named error" (https://websockets.spec.whatwg.org/#dom-websocket-onerror).
    • I'll skip this; not sure we can implement it reliably.
• Close the actual server connection whenever the original (mocked) client is closed.
• Consider removing WebSocketClient#emit. It's non-standard.
• Support custom encoder/decoder for (a) JSON transfer; (b) to support custom event format (like SocketIO).
  • This may be out of scope. Consider this carefully.
  • Use bindings instead. I've implemented the socket.io-binding.
• Consider migrating to EventTarget-like public API: client.addEventListener().

Third-party support

• SocketIO
  • Proposed to expose higher-level encoding/decoding utilities Expose a higher-level string -> packet utility socketio/socket.io-parser#129

[kettanaito]

The WebSocketInterceptor itself has started as a batched interceptor on a premise that in the future it will combine multiple, transport-related interceptors (WebSocket, XHR polling).

I believe that's redundant now. I don't plan to support any non-standard WebSocket implementations, and this pull request implements the interceptor for the standard implementation already.

[kettanaito]

The WebSocket interceptor will be available anywhere where the global WebSocket class is present.

For testing, we are setting that class in a custom Vitest environment, taking it from undici and making it a global class.

[kettanaito]

All constructed WebSocket instances will point to a "dummy" implementation of the WebSocket class (i.e. mock). This makes all connections mocked by default (will never reach the actual server unless you tell them to). I find this to be a good default when developing against non-existing WebSocket servers.

Reason

new WebSocket(url) connections to non-existing addresses throw a special kind of error in the browser that cannot be caught by any means.

[kettanaito]

Transport is an abstract class responsible for handling incoming and outgoing events from a WebSocket instance.

At its core, the transport is the barebones implementation of how to apply client.send() events and how to listen to client.on() events.

Later, the transport is wrapped in the Connection instance to acquire a nicer public API.

[kettanaito]

This is a WebSocket client connection class. It represents a single WebSocket client connected to the "server" (the interceptor).

This API is implementation-agnostic and provides the public methods to interact with the intercepted WebSocket client.

[kettanaito]

Similar to the WebSocket client representation, this is the actual WebSocket server connection representation. It's used to:

• Establish the original connection to the server;
• Intercept the incoming server events (the real ones);
• Forward any (intercepted) outgoing client events to the actual server (if you wish a full passthrough interception).

[kettanaito]

Socket.IO support

import { io } from '@mswjs/socket.io-parser'

interceptor.on('connection', (args) => {
  const client = io(args.client)
  const server = io(args.server)

  // MessageEvent data is decoded.
  client.on('message', (event) => {
    console.log(event.data) // "hello"
  })

  // Custom events are supported
  // (decoded from the generic MessageEvent).
  client.on('custom-event', (data) => {})

  // Outgoing messages are encoded.
  client.send('hello')
  // Custom events are encoded and transformed
  // into the generic MessageEvent.
  client.emit('custom-event',new Blob(['hello']))

  // Incoming original server events are decoded.
  server.on('server-event', (data) => {})
  // Sent messages to the server are encoded.
  // Also sent in 2 packets as Socket.IO does it.
  server.send(new Blob(['hello']))
})

[kettanaito]

The API itself is complete. One thing remaining is proper test coverage, specifically addressing the bug in the ws module (the Event instance check) or migrating to a different server package to use for testing.

[kettanaito]

Released: v0.26.0 🎉

This has been released in v0.26.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.