msw 2.2.13 → 2.3.0-ws.rc-2

package/src/core/ws/WebSocketClientManager.test.ts

@@ -0,0 +1,159 @@
+/**
+ * @vitest-environment node-websocket
+ */
+import { randomUUID } from 'node:crypto'
+import {
+  WebSocketClientConnection,
+  WebSocketTransport,
+} from '@mswjs/interceptors/WebSocket'
+import {
+  WebSocketClientManager,
+  WebSocketBroadcastChannelMessage,
+  WebSocketRemoteClientConnection,
+} from './WebSocketClientManager'
+
+const channel = new BroadcastChannel('test:channel')
+vi.spyOn(channel, 'postMessage')
+
+const socket = new WebSocket('ws://localhost')
+const transport = {
+  onOutgoing: vi.fn(),
+  onIncoming: vi.fn(),
+  onClose: vi.fn(),
+  send: vi.fn(),
+  close: vi.fn(),
+} satisfies WebSocketTransport
+
+afterEach(() => {
+  vi.resetAllMocks()
+})
+
+it('adds a client from this runtime to the list of clients', () => {
+  const manager = new WebSocketClientManager(channel)
+  const connection = new WebSocketClientConnection(socket, transport)
+
+  manager.addConnection(connection)
+
+  // Must add the client to the list of clients.
+  expect(Array.from(manager.clients.values())).toEqual([connection])
+
+  // Must emit the connection open event to notify other runtimes.
+  expect(channel.postMessage).toHaveBeenCalledWith({
+    type: 'connection:open',
+    payload: {
+      clientId: connection.id,
+      url: socket.url,
+    },
+  } satisfies WebSocketBroadcastChannelMessage)
+})
+
+it('adds a client from another runtime to the list of clients', async () => {
+  const clientId = randomUUID()
+  const url = new URL('ws://localhost')
+  const manager = new WebSocketClientManager(channel)
+
+  channel.dispatchEvent(
+    new MessageEvent<WebSocketBroadcastChannelMessage>('message', {
+      data: {
+        type: 'connection:open',
+        payload: {
+          clientId,
+          url: url.href,
+        },
+      },
+    }),
+  )
+
+  await vi.waitFor(() => {
+    expect(Array.from(manager.clients.values())).toEqual([
+      new WebSocketRemoteClientConnection(clientId, url, channel),
+    ])
+  })
+})
+
+it('replays a "send" event coming from another runtime', async () => {
+  const manager = new WebSocketClientManager(channel)
+  const connection = new WebSocketClientConnection(socket, transport)
+  manager.addConnection(connection)
+  vi.spyOn(connection, 'send')
+
+  // Emulate another runtime signaling this connection to receive data.
+  channel.dispatchEvent(
+    new MessageEvent<WebSocketBroadcastChannelMessage>('message', {
+      data: {
+        type: 'extraneous:send',
+        payload: {
+          clientId: connection.id,
+          data: 'hello',
+        },
+      },
+    }),
+  )
+
+  await vi.waitFor(() => {
+    // Must execute the requested operation on the connection.
+    expect(connection.send).toHaveBeenCalledWith('hello')
+    expect(connection.send).toHaveBeenCalledTimes(1)
+  })
+})
+
+it('replays a "close" event coming from another runtime', async () => {
+  const manager = new WebSocketClientManager(channel)
+  const connection = new WebSocketClientConnection(socket, transport)
+  manager.addConnection(connection)
+  vi.spyOn(connection, 'close')
+
+  // Emulate another runtime signaling this connection to close.
+  channel.dispatchEvent(
+    new MessageEvent<WebSocketBroadcastChannelMessage>('message', {
+      data: {
+        type: 'extraneous:close',
+        payload: {
+          clientId: connection.id,
+          code: 1000,
+          reason: 'Normal closure',
+        },
+      },
+    }),
+  )
+
+  await vi.waitFor(() => {
+    // Must execute the requested operation on the connection.
+    expect(connection.close).toHaveBeenCalledWith(1000, 'Normal closure')
+    expect(connection.close).toHaveBeenCalledTimes(1)
+  })
+})
+
+it('removes the extraneous message listener when the connection closes', async () => {
+  const manager = new WebSocketClientManager(channel)
+  const connection = new WebSocketClientConnection(socket, transport)
+  vi.spyOn(connection, 'close').mockImplementationOnce(() => {
+    /**
+     * @note This is a nasty hack so we don't have to uncouple
+     * the connection from transport. Creating a mock transport
+     * is difficult because it relies on the `WebSocketOverride` class.
+     * All we care here is that closing the connection triggers
+     * the transport closure, which it always does.
+     */
+    connection['transport'].onClose()
+  })
+  vi.spyOn(connection, 'send')
+
+  manager.addConnection(connection)
+  connection.close()
+
+  // Signals from other runtimes have no effect on the closed connection.
+  channel.dispatchEvent(
+    new MessageEvent<WebSocketBroadcastChannelMessage>('message', {
+      data: {
+        type: 'extraneous:send',
+        payload: {
+          clientId: connection.id,
+          data: 'hello',
+        },
+      },
+    }),
+  )
+
+  expect(connection.send).not.toHaveBeenCalled()
+})

package/src/core/ws/WebSocketClientManager.ts

@@ -0,0 +1,170 @@
+import type {
+  WebSocketData,
+  WebSocketClientConnection,
+  WebSocketClientConnectionProtocol,
+} from '@mswjs/interceptors/WebSocket'
+
+export type WebSocketBroadcastChannelMessage =
+  | {
+      type: 'connection:open'
+      payload: {
+        clientId: string
+        url: string
+      }
+    }
+  | {
+      type: 'extraneous:send'
+      payload: {
+        clientId: string
+        data: WebSocketData
+      }
+    }
+  | {
+      type: 'extraneous:close'
+      payload: {
+        clientId: string
+        code?: number
+        reason?: string
+      }
+    }
+
+export const kAddByClientId = Symbol('kAddByClientId')
+
+/**
+ * A manager responsible for accumulating WebSocket client
+ * connections across different browser runtimes.
+ */
+export class WebSocketClientManager {
+  /**
+   * All active WebSocket client connections.
+   */
+  public clients: Set<WebSocketClientConnectionProtocol>
+
+  constructor(private channel: BroadcastChannel) {
+    this.clients = new Set()
+
+    this.channel.addEventListener('message', (message) => {
+      const { type, payload } = message.data as WebSocketBroadcastChannelMessage
+
+      switch (type) {
+        case 'connection:open': {
+          // When another runtime notifies about a new connection,
+          // create a connection wrapper class and add it to the set.
+          this.onRemoteConnection(payload.clientId, new URL(payload.url))
+          break
+        }
+      }
+    })
+  }
+
+  /**
+   * Adds the given `WebSocket` client connection to the set
+   * of all connections. The given connection is always the complete
+   * connection object because `addConnection()` is called only
+   * for the opened connections in the same runtime.
+   */
+  public addConnection(client: WebSocketClientConnection): void {
+    this.clients.add(client)
+
+    // Signal to other runtimes about this connection.
+    this.channel.postMessage({
+      type: 'connection:open',
+      payload: {
+        clientId: client.id,
+        url: client.url.toString(),
+      },
+    } as WebSocketBroadcastChannelMessage)
+
+    // Instruct the current client how to handle events
+    // coming from other runtimes (e.g. when calling `.broadcast()`).
+    const handleExtraneousMessage = (
+      message: MessageEvent<WebSocketBroadcastChannelMessage>,
+    ) => {
+      const { type, payload } = message.data
+
+      // Ignore broadcasted messages for other clients.
+      if (
+        typeof payload === 'object' &&
+        'clientId' in payload &&
+        payload.clientId !== client.id
+      ) {
+        return
+      }
+
+      switch (type) {
+        case 'extraneous:send': {
+          client.send(payload.data)
+          break
+        }
+
+        case 'extraneous:close': {
+          client.close(payload.code, payload.reason)
+          break
+        }
+      }
+    }
+
+    const abortController = new AbortController()
+
+    this.channel.addEventListener('message', handleExtraneousMessage, {
+      signal: abortController.signal,
+    })
+
+    // Once closed, this connection cannot be operated on.
+    // This must include the extraneous runtimes as well.
+    client.addEventListener('close', () => abortController.abort(), {
+      once: true,
+    })
+  }
+
+  /**
+   * Adds a client connection wrapper to operate with
+   * WebSocket client connections in other runtimes.
+   */
+  private onRemoteConnection(id: string, url: URL): void {
+    this.clients.add(
+      // Create a connection-compatible instance that can
+      // operate with this client from a different runtime
+      // using the BroadcastChannel messages.
+      new WebSocketRemoteClientConnection(id, url, this.channel),
+    )
+  }
+}
+
+/**
+ * A wrapper class to operate with WebSocket client connections
+ * from other runtimes. This class maintains 1-1 public API
+ * compatibility to the `WebSocketClientConnection` but relies
+ * on the given `BroadcastChannel` to communicate instructions
+ * with the client connections from other runtimes.
+ */
+export class WebSocketRemoteClientConnection
+  implements WebSocketClientConnectionProtocol
+{
+  constructor(
+    public readonly id: string,
+    public readonly url: URL,
+    private channel: BroadcastChannel,
+  ) {}
+
+  send(data: WebSocketData): void {
+    this.channel.postMessage({
+      type: 'extraneous:send',
+      payload: {
+        clientId: this.id,
+        data,
+      },
+    } as WebSocketBroadcastChannelMessage)
+  }
+
+  close(code?: number | undefined, reason?: string | undefined): void {
+    this.channel.postMessage({
+      type: 'extraneous:close',
+      payload: {
+        clientId: this.id,
+        code,
+        reason,
+      },
+    } as WebSocketBroadcastChannelMessage)
+  }
+}

package/src/core/ws/utils/attachWebSocketLogger.ts

@@ -0,0 +1,262 @@
+import type {
+  WebSocketClientConnection,
+  WebSocketConnectionData,
+  WebSocketData,
+} from '@mswjs/interceptors/WebSocket'
+import { devUtils } from '../../utils/internal/devUtils'
+import { getTimestamp } from '../../utils/logging/getTimestamp'
+import { toPublicUrl } from '../../utils/request/toPublicUrl'
+import { getMessageLength } from './getMessageLength'
+import { getPublicData } from './getPublicData'
+
+export function attachWebSocketLogger(
+  connection: WebSocketConnectionData,
+): void {
+  const { client, server } = connection
+
+  logConnectionOpen(client)
+
+  // Log the events sent from the WebSocket client.
+  // WebSocket client connection object is written from the
+  // server's perspective so these message events are outgoing.
+  /**
+   * @todo Provide the reference to the exact event handler
+   * that called this `client.send()`.
+   */
+  client.addEventListener('message', (event) => {
+    logOutgoingClientMessage(event)
+  })
+
+  client.addEventListener('close', (event) => {
+    logConnectionClose(event)
+  })
+
+  // Log the events received by the WebSocket client.
+  // "client.socket" references the actual WebSocket instance
+  // so these message events are incoming messages.
+  client.socket.addEventListener('message', (event) => {
+    logIncomingClientMessage(event)
+  })
+
+  // Log client errors (connection closures due to errors).
+  client.socket.addEventListener('error', (event) => {
+    logClientError(event)
+  })
+
+  client.send = new Proxy(client.send, {
+    apply(target, thisArg, args) {
+      const [data] = args
+      const messageEvent = new MessageEvent('message', { data })
+      Object.defineProperties(messageEvent, {
+        currentTarget: {
+          enumerable: true,
+          writable: false,
+          value: client.socket,
+        },
+        target: {
+          enumerable: true,
+          writable: false,
+          value: client.socket,
+        },
+      })
+      logIncomingMockedClientMessage(messageEvent)
+
+      return Reflect.apply(target, thisArg, args)
+    },
+  })
+
+  server.addEventListener(
+    'open',
+    () => {
+      server.addEventListener('message', (event) => {
+        logIncomingServerMessage(event)
+      })
+    },
+    { once: true },
+  )
+
+  // Log outgoing client events initiated by the event handler.
+  // The actual client never sent these but the handler did.
+  server.send = new Proxy(server.send, {
+    apply(target, thisArg, args) {
+      const [data] = args
+      const messageEvent = new MessageEvent('message', { data })
+      Object.defineProperties(messageEvent, {
+        currentTarget: {
+          enumerable: true,
+          writable: false,
+          value: server['realWebSocket'],
+        },
+        target: {
+          enumerable: true,
+          writable: false,
+          value: server['realWebSocket'],
+        },
+      })
+
+      logOutgoingMockedClientMessage(messageEvent)
+
+      return Reflect.apply(target, thisArg, args)
+    },
+  })
+}
+
+/**
+ * Prints the WebSocket connection.
+ * This is meant to be logged by every WebSocket handler
+ * that intercepted this connection. This helps you see
+ * what handlers observe this connection.
+ */
+export function logConnectionOpen(client: WebSocketClientConnection) {
+  const publicUrl = toPublicUrl(client.url)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(`${getTimestamp()} %c▸%c ${publicUrl}`),
+    'color:blue',
+    'color:inherit',
+  )
+  console.log('Client:', client.socket)
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message.
+ */
+export async function logOutgoingClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c↑%c ${publicData} %c${byteLength}%c`,
+    ),
+    'color:green',
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message initiated
+ * by `server.send()` in the event handler.
+ */
+export async function logOutgoingMockedClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c⇡%c ${publicData} %c${byteLength}%c`,
+    ),
+    'color:orangered',
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+/**
+ * Prings the message received by the WebSocket client.
+ * This is fired when the "message" event is dispatched
+ * on the actual WebSocket client instance, and translates to
+ * the client receiving a message from the server.
+ */
+export async function logIncomingClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c↓%c ${publicData} %c${byteLength}%c`,
+    ),
+    'color:red',
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message initiated
+ * by `client.send()` in the event handler.
+ */
+export async function logIncomingMockedClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c⇣%c ${publicData} %c${byteLength}%c`,
+    ),
+    'color:orangered',
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+function logConnectionClose(event: CloseEvent) {
+  const target = event.target as WebSocket
+  const publicUrl = toPublicUrl(target.url)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c■%c ${publicUrl}`,
+    ),
+    'color:blue',
+    'color:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+export async function logIncomingServerMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c⇣%c ${publicData} %c${byteLength}%c`,
+    ),
+    'color:orangered',
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}
+
+function logClientError(event: Event) {
+  const socket = event.target as WebSocket
+  const publicUrl = toPublicUrl(socket.url)
+
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c\u00D7%c ${publicUrl}`,
+    ),
+    'color:red',
+    'color:inherit',
+  )
+  console.log(event)
+  console.groupEnd()
+}

package/src/core/ws/utils/getMessageLength.test.ts

@@ -0,0 +1,16 @@
+import { getMessageLength } from './getMessageLength'
+
+it('returns the length of the string', () => {
+  expect(getMessageLength('')).toBe(0)
+  expect(getMessageLength('hello')).toBe(5)
+})
+
+it('returns the size of the Blob', () => {
+  expect(getMessageLength(new Blob())).toBe(0)
+  expect(getMessageLength(new Blob(['hello']))).toBe(5)
+})
+
+it('returns the byte length of ArrayBuffer', () => {
+  expect(getMessageLength(new ArrayBuffer(0))).toBe(0)
+  expect(getMessageLength(new ArrayBuffer(5))).toBe(5)
+})

package/src/core/ws/utils/getMessageLength.ts

@@ -0,0 +1,19 @@
+import type { WebSocketData } from '@mswjs/interceptors/lib/browser/interceptors/WebSocket'
+
+/**
+ * Returns the byte length of the given WebSocket message.
+ * @example
+ * getMessageLength('hello') // 5
+ * getMessageLength(new Blob(['hello'])) // 5
+ */
+export function getMessageLength(data: WebSocketData): number {
+  if (data instanceof Blob) {
+    return data.size
+  }
+
+  if (data instanceof ArrayBuffer) {
+    return data.byteLength
+  }
+
+  return new Blob([data]).size
+}

package/src/core/ws/utils/getPublicData.test.ts

@@ -0,0 +1,38 @@
+import { getPublicData } from './getPublicData'
+
+it('returns a short string as-is', async () => {
+  expect(await getPublicData('')).toBe('')
+  expect(await getPublicData('hello')).toBe('hello')
+})
+
+it('returns a truncated long string', async () => {
+  expect(await getPublicData('this is a very long string')).toBe(
+    'this is a very long stri…',
+  )
+})
+
+it('returns a short Blob text as-is', async () => {
+  expect(await getPublicData(new Blob(['']))).toBe('Blob()')
+  expect(await getPublicData(new Blob(['hello']))).toBe('Blob(hello)')
+})
+
+it('returns a truncated long Blob text', async () => {
+  expect(await getPublicData(new Blob(['this is a very long string']))).toBe(
+    'Blob(this is a very long stri…)',
+  )
+})
+
+it('returns a short ArrayBuffer text as-is', async () => {
+  expect(await getPublicData(new TextEncoder().encode(''))).toBe(
+    'ArrayBuffer()',
+  )
+  expect(await getPublicData(new TextEncoder().encode('hello'))).toBe(
+    'ArrayBuffer(hello)',
+  )
+})
+
+it('returns a truncated ArrayBuffer text', async () => {
+  expect(
+    await getPublicData(new TextEncoder().encode('this is a very long string')),
+  ).toBe('ArrayBuffer(this is a very long stri…)')
+})

package/src/core/ws/utils/getPublicData.ts

@@ -0,0 +1,17 @@
+import { WebSocketData } from '@mswjs/interceptors/WebSocket'
+import { truncateMessage } from './truncateMessage'
+
+export async function getPublicData(data: WebSocketData): Promise<string> {
+  if (data instanceof Blob) {
+    const text = await data.text()
+    return `Blob(${truncateMessage(text)})`
+  }
+
+  // Handle all ArrayBuffer-like objects.
+  if (typeof data === 'object' && 'byteLength' in data) {
+    const text = new TextDecoder().decode(data)
+    return `ArrayBuffer(${truncateMessage(text)})`
+  }
+
+  return truncateMessage(data)
+}

package/src/core/ws/utils/truncateMessage.test.ts

@@ -0,0 +1,12 @@
+import { truncateMessage } from './truncateMessage'
+
+it('returns a short string as-is', () => {
+  expect(truncateMessage('')).toBe('')
+  expect(truncateMessage('hello')).toBe('hello')
+})
+
+it('truncates a long string', () => {
+  expect(truncateMessage('this is a very long string')).toBe(
+    'this is a very long stri…',
+  )
+})

package/src/core/ws/utils/truncateMessage.ts

@@ -0,0 +1,9 @@
+const MAX_LENGTH = 24
+
+export function truncateMessage(message: string): string {
+  if (message.length <= MAX_LENGTH) {
+    return message
+  }
+
+  return `${message.slice(0, MAX_LENGTH)}…`
+}