msw 2.3.0-ws.rc-1 → 2.3.0-ws.rc-3

package/src/core/utils/logging/getTimestamp.test.ts

@@ -1,18 +1,32 @@
 import { getTimestamp } from './getTimestamp'
 
 beforeAll(() => {
-  // Stub native `Date` prototype methods used in the tested module,
-  // to always produce a predictable value for testing purposes.
-  vi.spyOn(global.Date.prototype, 'getHours').mockImplementation(() => 12)
-  vi.spyOn(global.Date.prototype, 'getMinutes').mockImplementation(() => 4)
-  vi.spyOn(global.Date.prototype, 'getSeconds').mockImplementation(() => 8)
+  vi.useFakeTimers()
 })
 
 afterAll(() => {
-  vi.restoreAllMocks()
+  vi.useRealTimers()
 })
 
 test('returns a timestamp string of the invocation time', () => {
+  vi.setSystemTime(new Date('2024-01-01 12:4:8'))
   const timestamp = getTimestamp()
   expect(timestamp).toBe('12:04:08')
 })
+
+test('returns a timestamp with milliseconds', () => {
+  vi.setSystemTime(new Date('2024-01-01 12:4:8'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.000')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.000'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.000')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.4'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.400')
+
+  vi.setSystemTime(new Date('2024-01-01 12:4:8.123'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:04:08.123')
+
+  vi.setSystemTime(new Date('2024-01-01 12:00:00'))
+  expect(getTimestamp({ milliseconds: true })).toBe('12:00:00.000')
+})

package/src/core/utils/logging/getTimestamp.ts

@@ -1,12 +1,17 @@
+interface GetTimestampOptions {
+  milliseconds?: boolean
+}
+
 /**
  * Returns a timestamp string in a "HH:MM:SS" format.
  */
-export function getTimestamp(): string {
+export function getTimestamp(options?: GetTimestampOptions): string {
   const now = new Date()
+  const timestamp = `${now.getHours().toString().padStart(2, '0')}:${now.getMinutes().toString().padStart(2, '0')}:${now.getSeconds().toString().padStart(2, '0')}`
+
+  if (options?.milliseconds) {
+    return `${timestamp}.${now.getMilliseconds().toString().padStart(3, '0')}`
+  }
 
-  return [now.getHours(), now.getMinutes(), now.getSeconds()]
-    .map(String)
-    .map((chunk) => chunk.slice(0, 2))
-    .map((chunk) => chunk.padStart(2, '0'))
-    .join(':')
+  return timestamp
 }

package/src/core/ws/handleWebSocketEvent.ts

@@ -0,0 +1,59 @@
+import type { WebSocketConnectionData } from '@mswjs/interceptors/lib/browser/interceptors/WebSocket'
+import { RequestHandler } from '../handlers/RequestHandler'
+import { WebSocketHandler, kDispatchEvent } from '../handlers/WebSocketHandler'
+import { webSocketInterceptor } from './webSocketInterceptor'
+
+interface HandleWebSocketEventOptions {
+  getHandlers: () => Array<RequestHandler | WebSocketHandler>
+  onMockedConnection: (connection: WebSocketConnectionData) => void
+  onPassthroughConnection: (onnection: WebSocketConnectionData) => void
+}
+
+export function handleWebSocketEvent(options: HandleWebSocketEventOptions) {
+  webSocketInterceptor.on('connection', (connection) => {
+    const handlers = options.getHandlers()
+
+    const connectionEvent = new MessageEvent('connection', {
+      data: connection,
+    })
+
+    // First, filter only those WebSocket handlers that
+    // match the "ws.link()" endpoint predicate. Don't dispatch
+    // anything yet so the logger can be attached to the connection
+    // before it potentially sends events.
+    const matchingHandlers = handlers.filter<WebSocketHandler>(
+      (handler): handler is WebSocketHandler => {
+        if (handler instanceof WebSocketHandler) {
+          return handler.predicate({
+            event: connectionEvent,
+            parsedResult: handler.parse({
+              event: connectionEvent,
+            }),
+          })
+        }
+
+        return false
+      },
+    )
+
+    if (matchingHandlers.length > 0) {
+      options?.onMockedConnection(connection)
+
+      // Iterate over the handlers and forward the connection
+      // event to WebSocket event handlers. This is equivalent
+      // to dispatching that event onto multiple listeners.
+      for (const handler of matchingHandlers) {
+        handler[kDispatchEvent](connectionEvent)
+      }
+    } else {
+      options?.onPassthroughConnection(connection)
+
+      // If none of the "ws" handlers matched,
+      // establish the WebSocket connection as-is.
+      connection.server.connect()
+      connection.client.addEventListener('message', (event) => {
+        connection.server.send(event.data)
+      })
+    }
+  })
+}

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)}…`
+}

package/src/core/{ws/ws.ts → ws.ts}

@@ -7,12 +7,53 @@ import {
   WebSocketHandler,
   kEmitter,
   type WebSocketHandlerEventMap,
-} from '../handlers/WebSocketHandler'
-import { Path, isPath } from '../utils/matching/matchRequestUrl'
-import { WebSocketClientManager } from './WebSocketClientManager'
+} from './handlers/WebSocketHandler'
+import { Path, isPath } from './utils/matching/matchRequestUrl'
+import { WebSocketClientManager } from './ws/WebSocketClientManager'
 
 const wsBroadcastChannel = new BroadcastChannel('msw:ws-client-manager')
 
+export type WebSocketLink = {
+  /**
+   * A set of all WebSocket clients connected
+   * to this link.
+   */
+  clients: Set<WebSocketClientConnectionProtocol>
+
+  on<EventType extends keyof WebSocketHandlerEventMap>(
+    event: EventType,
+    listener: (...args: WebSocketHandlerEventMap[EventType]) => void,
+  ): WebSocketHandler
+
+  /**
+   * Broadcasts the given data to all WebSocket clients.
+   *
+   * @example
+   * const service = ws.link('wss://example.com')
+   * service.on('connection', () => {
+   *   service.broadcast('hello, everyone!')
+   * })
+   */
+  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.on('connection', ({ client }) => {
+   *   service.broadcastExcept(client, 'hi, the rest of you!')
+   * })
+   */
+  broadcastExcept(
+    clients:
+      | WebSocketClientConnectionProtocol
+      | Array<WebSocketClientConnectionProtocol>,
+    data: WebSocketData,
+  ): void
+}
+
 /**
  * Intercepts outgoing WebSocket connections to the given URL.
  *
@@ -22,12 +63,12 @@ const wsBroadcastChannel = new BroadcastChannel('msw:ws-client-manager')
  *   client.send('hello from server!')
  * })
  */
-function createWebSocketLinkHandler(url: Path) {
+function createWebSocketLinkHandler(url: Path): WebSocketLink {
   invariant(url, 'Expected a WebSocket server URL but got undefined')
 
   invariant(
     isPath(url),
-    'Expected a WebSocket server URL but got %s',
+    'Expected a WebSocket server URL to be a valid path but got %s',
     typeof url,
   )
 
@@ -35,10 +76,7 @@ function createWebSocketLinkHandler(url: Path) {
 
   return {
     clients: clientManager.clients,
-    on<K extends keyof WebSocketHandlerEventMap>(
-      event: K,
-      listener: (...args: WebSocketHandlerEventMap[K]) => void,
-    ): WebSocketHandler {
+    on(event, listener) {
       const handler = new WebSocketHandler(url)
 
       // Add the connection event listener for when the
@@ -58,38 +96,14 @@ function createWebSocketLinkHandler(url: Path) {
       return handler
     },
 
-    /**
-     * Broadcasts the given data to all WebSocket clients.
-     *
-     * @example
-     * const service = ws.link('wss://example.com')
-     * service.on('connection', () => {
-     *   service.broadcast('hello, everyone!')
-     * })
-     */
-    broadcast(data: WebSocketData): void {
+    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)
     },
 
-    /**
-     * 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.on('connection', ({ client }) => {
-     *   service.broadcastExcept(client, 'hi, the rest of you!')
-     * })
-     */
-    broadcastExcept(
-      clients:
-        | WebSocketClientConnectionProtocol
-        | Array<WebSocketClientConnectionProtocol>,
-      data: WebSocketData,
-    ): void {
+    broadcastExcept(clients, data) {
       const ignoreClients = Array.prototype
         .concat(clients)
         .map((client) => client.id)

package/src/mockServiceWorker.js

@@ -2,12 +2,13 @@
 /* tslint:disable */
 
 /**
- * Mock Service Worker (<PACKAGE_VERSION>).
+ * Mock Service Worker.
  * @see https://github.com/mswjs/msw
  * - Please do NOT modify this file.
  * - Please do NOT serve this file on production.
  */
 
+const PACKAGE_VERSION = '<PACKAGE_VERSION>'
 const INTEGRITY_CHECKSUM = '<INTEGRITY_CHECKSUM>'
 const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
 const activeClientIds = new Set()
@@ -48,7 +49,10 @@ self.addEventListener('message', async function (event) {
     case 'INTEGRITY_CHECK_REQUEST': {
       sendToClient(client, {
         type: 'INTEGRITY_CHECK_RESPONSE',
-        payload: INTEGRITY_CHECKSUM,
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
       })
       break
     }
@@ -202,13 +206,6 @@ async function getResponse(event, client, requestId) {
     return passthrough()
   }
 
-  // Bypass requests with the explicit bypass header.
-  // Such requests can be issued by "ctx.fetch()".
-  const mswIntention = request.headers.get('x-msw-intention')
-  if (['bypass', 'passthrough'].includes(mswIntention)) {
-    return passthrough()
-  }
-
   // Notify the client that a request has been intercepted.
   const requestBuffer = await request.arrayBuffer()
   const clientMessage = await sendToClient(
@@ -240,7 +237,7 @@ async function getResponse(event, client, requestId) {
       return respondWithMock(clientMessage.data)
     }
 
-    case 'MOCK_NOT_FOUND': {
+    case 'PASSTHROUGH': {
       return passthrough()
     }
   }

package/src/node/SetupServerApi.ts

@@ -61,10 +61,10 @@ export class SetupServerApi
     this.handlersController = new AsyncHandlersController(handlers)
   }
 
-  public boundary<Fn extends (...args: Array<any>) => unknown>(
-    callback: Fn,
-  ): (...args: Parameters<Fn>) => ReturnType<Fn> {
-    return (...args: Parameters<Fn>): ReturnType<Fn> => {
+  public boundary<Args extends Array<any>, R>(
+    callback: (...args: Args) => R,
+  ): (...args: Args) => R {
+    return (...args: Args): R => {
       return store.run<any, any>(
         {
           initialHandlers: this.handlersController.currentHandlers(),