feat: add WebSocket class interceptor

[kettanaito]

• Closes #236
• Closes #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

• [x] Tests only: The ws module we use for testing doesn't pass the instanceofcheck on dispatched events in Node, causing some tests to fail (https://github.com/websockets/ws/issues/1818).
  • [x] 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.
• [x] Write WebSocket compliance tests.
  • [x] Default state
  • [x] Events
  • [x] Methods (.send() and .close() and its input)
  • [x] Setters (.onopen and etc)
• [x] 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).
• [x] Emit the error event correctly. It's emitted in the following scenarios:
  • [x] Connection was closed with a > 1000 <= 1015 (https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1)
  • [x] 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.
• [x] Close the actual server connection whenever the original (mocked) client is closed.
• [x] Consider removing WebSocketClient#emit. It's non-standard.
• [x] 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.
• [x] Consider migrating to EventTarget-like public API: client.addEventListener().

Third-party support

• [x] SocketIO
  • Proposed to expose higher-level encoding/decoding utilities https://github.com/socketio/socket.io-parser/issues/129

[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.