msw 2.5.1 → 2.6.0

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

@@ -0,0 +1,259 @@
+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'
+
+const colors = {
+  system: '#3b82f6',
+  outgoing: '#22c55e',
+  incoming: '#ef4444',
+  mocked: '#ff6a33',
+}
+
+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 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,
+        },
+      })
+
+      queueMicrotask(() => {
+        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.socket,
+        },
+        target: {
+          enumerable: true,
+          writable: false,
+          value: server.socket,
+        },
+      })
+
+      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)
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(`${getTimestamp()} %c▶%c ${publicUrl}`),
+    `color:${colors.system}`,
+    'color:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log('Client:', client.socket)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+function logConnectionClose(event: CloseEvent) {
+  const target = event.target as WebSocket
+  const publicUrl = toPublicUrl(target.url)
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c■%c ${publicUrl}`,
+    ),
+    `color:${colors.system}`,
+    'color:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+function logClientError(event: Event) {
+  const socket = event.target as WebSocket
+  const publicUrl = toPublicUrl(socket.url)
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c\u00D7%c ${publicUrl}`,
+    ),
+    `color:${colors.system}`,
+    'color:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message.
+ */
+async function logOutgoingClientMessage(event: MessageEvent<WebSocketData>) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+  const arrow = event.defaultPrevented ? '⇡' : '⬆'
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c${arrow}%c ${publicData} %c${byteLength}%c`,
+    ),
+    `color:${colors.outgoing}`,
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message initiated
+ * by `server.send()` in the event handler.
+ */
+async function logOutgoingMockedClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c⬆%c ${publicData} %c${byteLength}%c`,
+    ),
+    `color:${colors.mocked}`,
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+/**
+ * Prints the outgoing client message initiated
+ * by `client.send()` in the event handler.
+ */
+async function logIncomingMockedClientMessage(
+  event: MessageEvent<WebSocketData>,
+) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c⬇%c ${publicData} %c${byteLength}%c`,
+    ),
+    `color:${colors.mocked}`,
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  console.groupEnd()
+}
+
+async function logIncomingServerMessage(event: MessageEvent<WebSocketData>) {
+  const byteLength = getMessageLength(event.data)
+  const publicData = await getPublicData(event.data)
+  const arrow = event.defaultPrevented ? '⇣' : '⬇'
+
+  // eslint-disable-next-line no-console
+  console.groupCollapsed(
+    devUtils.formatMessage(
+      `${getTimestamp({ milliseconds: true })} %c${arrow}%c ${publicData} %c${byteLength}%c`,
+    ),
+    `color:${colors.incoming}`,
+    'color:inherit',
+    'color:gray;font-weight:normal',
+    'color:inherit;font-weight:inherit',
+  )
+  // eslint-disable-next-line no-console
+  console.log(event)
+  // eslint-disable-next-line no-console
+  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)}…`
+}

package/src/core/ws/webSocketInterceptor.ts

@@ -0,0 +1,3 @@
+import { WebSocketInterceptor } from '@mswjs/interceptors/WebSocket'
+
+export const webSocketInterceptor = new WebSocketInterceptor()

package/src/core/ws.test.ts

@@ -0,0 +1,23 @@
+/**
+ * @vitest-environment node-websocket
+ */
+import { ws } from './ws'
+
+it('exports the "link()" method', () => {
+  expect(ws).toHaveProperty('link')
+  expect(ws.link).toBeInstanceOf(Function)
+})
+
+it('throws an error when calling "ws.link()" without a URL argument', () => {
+  expect(() =>
+    // @ts-expect-error Intentionally invalid call.
+    ws.link(),
+  ).toThrow('Expected a WebSocket server URL but got undefined')
+})
+
+it('throws an error when given a non-path argument to "ws.link()"', () => {
+  expect(() =>
+    // @ts-expect-error Intentionally invalid argument.
+    ws.link(2),
+  ).toThrow('Expected a WebSocket server URL to be a valid path but got number')
+})

package/src/core/ws.ts

@@ -0,0 +1,166 @@
+import { invariant } from 'outvariant'
+import type {
+  WebSocketData,
+  WebSocketClientConnectionProtocol,
+} from '@mswjs/interceptors/WebSocket'
+import {
+  WebSocketHandler,
+  kEmitter,
+  type WebSocketHandlerEventMap,
+} from './handlers/WebSocketHandler'
+import { Path, isPath } from './utils/matching/matchRequestUrl'
+import { WebSocketClientManager } from './ws/WebSocketClientManager'
+
+function isBroadcastChannelWithUnref(
+  channel: BroadcastChannel,
+): channel is BroadcastChannel & NodeJS.RefCounted {
+  return typeof Reflect.get(channel, 'unref') !== 'undefined'
+}
+
+const webSocketChannel = new BroadcastChannel('msw:websocket-client-manager')
+
+if (isBroadcastChannelWithUnref(webSocketChannel)) {
+  // Allows the Node.js thread to exit if it is the only active handle in the event system.
+  // https://nodejs.org/api/worker_threads.html#broadcastchannelunref
+  webSocketChannel.unref()
+}
+
+export type WebSocketEventListener<
+  EventType extends keyof WebSocketHandlerEventMap,
+> = (...args: WebSocketHandlerEventMap[EventType]) => void
+
+export type WebSocketLink = {
+  /**
+   * A set of all WebSocket clients connected
+   * to this link.
+   *
+   * @see {@link https://mswjs.io/docs/api/ws#clients `clients` API reference}
+   */
+  clients: Set<WebSocketClientConnectionProtocol>
+
+  /**
+   * Adds an event listener to this WebSocket link.
+   *
+   * @example
+   * const chat = ws.link('wss://chat.example.com')
+   * chat.addEventListener('connection', listener)
+   *
+   * @see {@link https://mswjs.io/docs/api/ws#onevent-listener `on()` API reference}
+   */
+  addEventListener<EventType extends keyof WebSocketHandlerEventMap>(
+    event: EventType,
+    listener: WebSocketEventListener<EventType>,
+  ): WebSocketHandler
+
+  /**
+   * Broadcasts the given data to all WebSocket clients.
+   *
+   * @example
+   * const service = ws.link('wss://example.com')
+   * service.addEventListener('connection', () => {
+   *   service.broadcast('hello, everyone!')
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/ws#broadcastdata `broadcast()` API reference}
+   */
+  broadcast(data: WebSocketData): void
+
+  /**
+   * Broadcasts the given data to all WebSocket clients
+   * except the ones provided in the `clients` argument.
+   *
+   * @example
+   * const service = ws.link('wss://example.com')
+   * service.addEventListener('connection', ({ client }) => {
+   *   service.broadcastExcept(client, 'hi, the rest of you!')
+   * })
+   *
+   * @see {@link https://mswjs.io/docs/api/ws#broadcastexceptclients-data `broadcast()` API reference}
+   */
+  broadcastExcept(
+    clients:
+      | WebSocketClientConnectionProtocol
+      | Array<WebSocketClientConnectionProtocol>,
+    data: WebSocketData,
+  ): void
+}
+
+/**
+ * Intercepts outgoing WebSocket connections to the given URL.
+ *
+ * @example
+ * const chat = ws.link('wss://chat.example.com')
+ * chat.addEventListener('connection', ({ client }) => {
+ *   client.send('hello from server!')
+ * })
+ */
+function createWebSocketLinkHandler(url: Path): WebSocketLink {
+  invariant(url, 'Expected a WebSocket server URL but got undefined')
+
+  invariant(
+    isPath(url),
+    'Expected a WebSocket server URL to be a valid path but got %s',
+    typeof url,
+  )
+
+  const clientManager = new WebSocketClientManager(webSocketChannel)
+
+  return {
+    get clients() {
+      return clientManager.clients
+    },
+    addEventListener(event, listener) {
+      const handler = new WebSocketHandler(url)
+
+      // Add the connection event listener for when the
+      // handler matches and emits a connection event.
+      // When that happens, store that connection in the
+      // set of all connections for reference.
+      handler[kEmitter].on('connection', async ({ client }) => {
+        await clientManager.addConnection(client)
+      })
+
+      // The "handleWebSocketEvent" function will invoke
+      // the "run()" method on the WebSocketHandler.
+      // If the handler matches, it will emit the "connection"
+      // event. Attach the user-defined listener to that event.
+      handler[kEmitter].on(event, listener)
+
+      return handler
+    },
+
+    broadcast(data) {
+      // This will invoke "send()" on the immediate clients
+      // in this runtime and post a message to the broadcast channel
+      // to trigger send for the clients in other runtimes.
+      this.broadcastExcept([], data)
+    },
+
+    broadcastExcept(clients, data) {
+      const ignoreClients = Array.prototype
+        .concat(clients)
+        .map((client) => client.id)
+
+      clientManager.clients.forEach((otherClient) => {
+        if (!ignoreClients.includes(otherClient.id)) {
+          otherClient.send(data)
+        }
+      })
+    },
+  }
+}
+
+/**
+ * A namespace to intercept and mock WebSocket connections.
+ *
+ * @example
+ * const chat = ws.link('wss://chat.example.com')
+ *
+ * @see {@link https://mswjs.io/docs/api/ws `ws` API reference}
+ * @see {@link https://mswjs.io/docs/basics/handling-websocket-events Handling WebSocket events}
+ */
+export const ws = {
+  link: createWebSocketLinkHandler,
+}
+
+export { WebSocketData }

package/src/node/SetupServerApi.ts

@@ -4,14 +4,15 @@ import { XMLHttpRequestInterceptor } from '@mswjs/interceptors/XMLHttpRequest'
 import { FetchInterceptor } from '@mswjs/interceptors/fetch'
 import { HandlersController } from '~/core/SetupApi'
 import type { RequestHandler } from '~/core/handlers/RequestHandler'
+import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
 import type { SetupServer } from './glossary'
 import { SetupServerCommonApi } from './SetupServerCommonApi'
 
 const store = new AsyncLocalStorage<RequestHandlersContext>()
 
 type RequestHandlersContext = {
-  initialHandlers: Array<RequestHandler>
-  handlers: Array<RequestHandler>
+  initialHandlers: Array<RequestHandler | WebSocketHandler>
+  handlers: Array<RequestHandler | WebSocketHandler>
 }
 
 /**
@@ -22,7 +23,7 @@ type RequestHandlersContext = {
 class AsyncHandlersController implements HandlersController {
   private rootContext: RequestHandlersContext
 
-  constructor(initialHandlers: Array<RequestHandler>) {
+  constructor(initialHandlers: Array<RequestHandler | WebSocketHandler>) {
     this.rootContext = { initialHandlers, handlers: [] }
   }
 
@@ -30,18 +31,18 @@ class AsyncHandlersController implements HandlersController {
     return store.getStore() || this.rootContext
   }
 
-  public prepend(runtimeHandlers: Array<RequestHandler>) {
+  public prepend(runtimeHandlers: Array<RequestHandler | WebSocketHandler>) {
     this.context.handlers.unshift(...runtimeHandlers)
   }
 
-  public reset(nextHandlers: Array<RequestHandler>) {
+  public reset(nextHandlers: Array<RequestHandler | WebSocketHandler>) {
     const context = this.context
     context.handlers = []
     context.initialHandlers =
       nextHandlers.length > 0 ? nextHandlers : context.initialHandlers
   }
 
-  public currentHandlers(): Array<RequestHandler> {
+  public currentHandlers(): Array<RequestHandler | WebSocketHandler> {
     const { initialHandlers, handlers } = this.context
     return handlers.concat(initialHandlers)
   }
@@ -51,7 +52,7 @@ export class SetupServerApi
   extends SetupServerCommonApi
   implements SetupServer
 {
-  constructor(handlers: Array<RequestHandler>) {
+  constructor(handlers: Array<RequestHandler | WebSocketHandler>) {
     super(
       [ClientRequestInterceptor, XMLHttpRequestInterceptor, FetchInterceptor],
       handlers,