msw 2.2.13 → 2.3.0-ws.rc-2

package/src/browser/setupWorker/glossary.ts

@@ -5,13 +5,11 @@ import {
   SharedOptions,
 } from '~/core/sharedOptions'
 import { ServiceWorkerMessage } from './start/utils/createMessageChannel'
-import {
-  RequestHandler,
-  RequestHandlerDefaultInfo,
-} from '~/core/handlers/RequestHandler'
+import { RequestHandler } from '~/core/handlers/RequestHandler'
 import type { HttpRequestEventMap, Interceptor } from '@mswjs/interceptors'
-import { Path } from '~/core/utils/matching/matchRequestUrl'
-import { RequiredDeep } from '~/core/typeUtils'
+import type { Path } from '~/core/utils/matching/matchRequestUrl'
+import type { RequiredDeep } from '~/core/typeUtils'
+import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
 
 export type ResolvedPath = Path | URL
 
@@ -87,7 +85,7 @@ export interface SetupWorkerInternalContext {
   startOptions: RequiredDeep<StartOptions>
   worker: ServiceWorker | null
   registration: ServiceWorkerRegistration | null
-  getRequestHandlers(): Array<RequestHandler>
+  getRequestHandlers(): Array<RequestHandler | WebSocketHandler>
   requests: Map<string, Request>
   emitter: Emitter<LifeCycleEventsMap>
   keepAliveInterval?: number
@@ -211,7 +209,7 @@ export interface SetupWorker {
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
    */
-  use: (...handlers: RequestHandler[]) => void
+  use: (...handlers: Array<RequestHandler | WebSocketHandler>) => void
 
   /**
    * Marks all request handlers that respond using `res.once()` as unused.
@@ -226,14 +224,16 @@ export interface SetupWorker {
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()` API reference}
    */
-  resetHandlers: (...nextHandlers: RequestHandler[]) => void
+  resetHandlers: (
+    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
+  ) => void
 
   /**
    * Returns a readonly list of currently active request handlers.
    *
    * @see {@link https://mswjs.io/docs/api/setup-worker/list-handlers `worker.listHandlers()` API reference}
    */
-  listHandlers(): ReadonlyArray<RequestHandler<RequestHandlerDefaultInfo, any>>
+  listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler>
 
   /**
    * Life-cycle events.

package/src/browser/setupWorker/setupWorker.ts

@@ -18,9 +18,13 @@ import { createFallbackStop } from './stop/createFallbackStop'
 import { devUtils } from '~/core/utils/internal/devUtils'
 import { SetupApi } from '~/core/SetupApi'
 import { mergeRight } from '~/core/utils/internal/mergeRight'
-import { LifeCycleEventsMap } from '~/core/sharedOptions'
+import type { LifeCycleEventsMap } from '~/core/sharedOptions'
+import type { WebSocketHandler } from '~/core/handlers/WebSocketHandler'
 import { SetupWorker } from './glossary'
 import { supportsReadableStreamTransfer } from '../utils/supportsReadableStreamTransfer'
+import { webSocketInterceptor } from '~/core/ws/webSocketInterceptor'
+import { handleWebSocketEvent } from '~/core/utils/handleWebSocketEvent'
+import { attachWebSocketLogger } from '~/core/ws/utils/attachWebSocketLogger'
 
 interface Listener {
   target: EventTarget
@@ -37,7 +41,7 @@ export class SetupWorkerApi
   private stopHandler: StopHandler = null as any
   private listeners: Array<Listener>
 
-  constructor(...handlers: Array<RequestHandler>) {
+  constructor(...handlers: Array<RequestHandler | WebSocketHandler>) {
     super(...handlers)
 
     invariant(
@@ -176,6 +180,31 @@ export class SetupWorkerApi
       options,
     ) as SetupWorkerInternalContext['startOptions']
 
+    // Enable WebSocket interception.
+    handleWebSocketEvent({
+      getHandlers: () => {
+        return this.handlersController.currentHandlers()
+      },
+      onMockedConnection: (connection) => {
+        if (!this.context.startOptions.quiet) {
+          // Attach the logger for mocked connections since
+          // those won't be visible in the browser's devtools.
+          attachWebSocketLogger(connection)
+        }
+      },
+      onPassthroughConnection() {
+        /**
+         * @fixme Call some "onUnhandledConnection".
+         */
+      },
+    })
+
+    webSocketInterceptor.apply()
+
+    this.subscriptions.push(() => {
+      webSocketInterceptor.dispose()
+    })
+
     return await this.startHandler(this.context.startOptions, options)
   }
 
@@ -193,6 +222,8 @@ export class SetupWorkerApi
  *
  * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker()` API reference}
  */
-export function setupWorker(...handlers: Array<RequestHandler>): SetupWorker {
+export function setupWorker(
+  ...handlers: Array<RequestHandler | WebSocketHandler>
+): SetupWorker {
   return new SetupWorkerApi(...handlers)
 }

package/src/core/SetupApi.ts

@@ -1,38 +1,42 @@
 import { invariant } from 'outvariant'
 import { EventMap, Emitter } from 'strict-event-emitter'
-import {
-  RequestHandler,
-  RequestHandlerDefaultInfo,
-} from './handlers/RequestHandler'
+import { RequestHandler } from './handlers/RequestHandler'
 import { LifeCycleEventEmitter } from './sharedOptions'
 import { devUtils } from './utils/internal/devUtils'
 import { pipeEvents } from './utils/internal/pipeEvents'
 import { toReadonlyArray } from './utils/internal/toReadonlyArray'
 import { Disposable } from './utils/internal/Disposable'
+import type { WebSocketHandler } from './handlers/WebSocketHandler'
 
 export abstract class HandlersController {
-  abstract prepend(runtimeHandlers: Array<RequestHandler>): void
-  abstract reset(nextHandles: Array<RequestHandler>): void
-  abstract currentHandlers(): Array<RequestHandler>
+  abstract prepend(
+    runtimeHandlers: Array<RequestHandler | WebSocketHandler>,
+  ): void
+  abstract reset(nextHandles: Array<RequestHandler | WebSocketHandler>): void
+  abstract currentHandlers(): Array<RequestHandler | WebSocketHandler>
 }
 
 export class InMemoryHandlersController implements HandlersController {
-  private handlers: Array<RequestHandler>
+  private handlers: Array<RequestHandler | WebSocketHandler>
 
-  constructor(private initialHandlers: Array<RequestHandler>) {
+  constructor(
+    private initialHandlers: Array<RequestHandler | WebSocketHandler>,
+  ) {
     this.handlers = [...initialHandlers]
   }
 
-  public prepend(runtimeHandles: Array<RequestHandler>): void {
+  public prepend(
+    runtimeHandles: Array<RequestHandler | WebSocketHandler>,
+  ): void {
     this.handlers.unshift(...runtimeHandles)
   }
 
-  public reset(nextHandlers: Array<RequestHandler>): void {
+  public reset(nextHandlers: Array<RequestHandler | WebSocketHandler>): void {
     this.handlers =
       nextHandlers.length > 0 ? [...nextHandlers] : [...this.initialHandlers]
   }
 
-  public currentHandlers(): Array<RequestHandler> {
+  public currentHandlers(): Array<RequestHandler | WebSocketHandler> {
     return this.handlers
   }
 }
@@ -47,7 +51,7 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
 
   public readonly events: LifeCycleEventEmitter<EventsMap>
 
-  constructor(...initialHandlers: Array<RequestHandler>) {
+  constructor(...initialHandlers: Array<RequestHandler | WebSocketHandler>) {
     super()
 
     invariant(
@@ -71,12 +75,14 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
     })
   }
 
-  private validateHandlers(handlers: ReadonlyArray<RequestHandler>): boolean {
+  private validateHandlers(handlers: ReadonlyArray<unknown>): boolean {
     // Guard against incorrect call signature of the setup API.
     return handlers.every((handler) => !Array.isArray(handler))
   }
 
-  public use(...runtimeHandlers: Array<RequestHandler>): void {
+  public use(
+    ...runtimeHandlers: Array<RequestHandler | WebSocketHandler>
+  ): void {
     invariant(
       this.validateHandlers(runtimeHandlers),
       devUtils.formatMessage(
@@ -89,17 +95,19 @@ export abstract class SetupApi<EventsMap extends EventMap> extends Disposable {
 
   public restoreHandlers(): void {
     this.handlersController.currentHandlers().forEach((handler) => {
-      handler.isUsed = false
+      if ('isUsed' in handler) {
+        handler.isUsed = false
+      }
     })
   }
 
-  public resetHandlers(...nextHandlers: Array<RequestHandler>): void {
+  public resetHandlers(
+    ...nextHandlers: Array<RequestHandler | WebSocketHandler>
+  ): void {
     this.handlersController.reset(nextHandlers)
   }
 
-  public listHandlers(): ReadonlyArray<
-    RequestHandler<RequestHandlerDefaultInfo, any, any>
-  > {
+  public listHandlers(): ReadonlyArray<RequestHandler | WebSocketHandler> {
     return toReadonlyArray(this.handlersController.currentHandlers())
   }
 

package/src/core/handlers/WebSocketHandler.ts

@@ -0,0 +1,71 @@
+import { Emitter } from 'strict-event-emitter'
+import type { WebSocketConnectionData } from '@mswjs/interceptors/WebSocket'
+import {
+  type Match,
+  type Path,
+  type PathParams,
+  matchRequestUrl,
+} from '../utils/matching/matchRequestUrl'
+import { getCallFrame } from '../utils/internal/getCallFrame'
+
+type WebSocketHandlerParsedResult = {
+  match: Match
+}
+
+export type WebSocketHandlerEventMap = {
+  connection: [args: WebSocketHandlerConnection]
+}
+
+interface WebSocketHandlerConnection extends WebSocketConnectionData {
+  params: PathParams
+}
+
+export const kEmitter = Symbol('kEmitter')
+export const kDispatchEvent = Symbol('kDispatchEvent')
+export const kSender = Symbol('kSender')
+
+export class WebSocketHandler {
+  public callFrame?: string
+
+  protected [kEmitter]: Emitter<WebSocketHandlerEventMap>
+
+  constructor(private readonly url: Path) {
+    this[kEmitter] = new Emitter()
+    this.callFrame = getCallFrame(new Error())
+  }
+
+  public parse(args: {
+    event: MessageEvent<WebSocketConnectionData>
+  }): WebSocketHandlerParsedResult {
+    const connection = args.event.data
+    const match = matchRequestUrl(connection.client.url, this.url)
+
+    return {
+      match,
+    }
+  }
+
+  public predicate(args: {
+    event: MessageEvent<WebSocketConnectionData>
+    parsedResult: WebSocketHandlerParsedResult
+  }): boolean {
+    return args.parsedResult.match.matches
+  }
+
+  async [kDispatchEvent](
+    event: MessageEvent<WebSocketConnectionData>,
+  ): Promise<void> {
+    const parsedResult = this.parse({ event })
+    const connection = event.data
+
+    const resolvedConnection: WebSocketHandlerConnection = {
+      client: connection.client,
+      server: connection.server,
+      params: parsedResult.match.params || {},
+    }
+
+    // Emit the connection event on the handler.
+    // This is what the developer adds listeners for.
+    this[kEmitter].emit('connection', resolvedConnection)
+  }
+}

package/src/core/index.ts

@@ -2,13 +2,20 @@ import { checkGlobals } from './utils/internal/checkGlobals'
 
 export { SetupApi } from './SetupApi'
 
-/* Request handlers */
+/* HTTP handlers */
 export { RequestHandler } from './handlers/RequestHandler'
 export { http } from './http'
 export { HttpHandler, HttpMethods } from './handlers/HttpHandler'
 export { graphql } from './graphql'
 export { GraphQLHandler } from './handlers/GraphQLHandler'
 
+/* WebSocket handler */
+export { ws } from './ws/ws'
+export {
+  WebSocketHandler,
+  type WebSocketHandlerEventMap,
+} from './handlers/WebSocketHandler'
+
 /* Utils */
 export { matchRequestUrl } from './utils/matching/matchRequestUrl'
 export * from './utils/handleRequest'

package/src/core/utils/executeHandlers.ts

@@ -1,6 +1,6 @@
 import {
   RequestHandler,
-  RequestHandlerExecutionResult,
+  type RequestHandlerExecutionResult,
 } from '../handlers/RequestHandler'
 
 export interface HandlersExecutionResult {
@@ -18,7 +18,7 @@ export interface ResponseResolutionContext {
  * Returns the execution result object containing any matching request
  * handler and any mocked response it returned.
  */
-export const executeHandlers = async <Handlers extends Array<RequestHandler>>({
+export const executeHandlers = async <Handlers extends Array<unknown>>({
   request,
   requestId,
   handlers,
@@ -33,6 +33,10 @@ export const executeHandlers = async <Handlers extends Array<RequestHandler>>({
   let result: RequestHandlerExecutionResult<any> | null = null
 
   for (const handler of handlers) {
+    if (!(handler instanceof RequestHandler)) {
+      continue
+    }
+
     result = await handler.run({ request, requestId, resolutionContext })
 
     // If the handler produces some result for this request,

package/src/core/utils/handleRequest.ts

@@ -1,6 +1,5 @@
 import { until } from '@open-draft/until'
 import { Emitter } from 'strict-event-emitter'
-import { RequestHandler } from '../handlers/RequestHandler'
 import { LifeCycleEventsMap, SharedOptions } from '../sharedOptions'
 import { RequiredDeep } from '../typeUtils'
 import { HandlersExecutionResult, executeHandlers } from './executeHandlers'
@@ -45,7 +44,7 @@ export interface HandleRequestOptions {
 export async function handleRequest(
   request: Request,
   requestId: string,
-  handlers: Array<RequestHandler>,
+  handlers: Array<unknown>,
   options: RequiredDeep<SharedOptions>,
   emitter: Emitter<LifeCycleEventsMap>,
   handleRequestOptions?: HandleRequestOptions,

package/src/core/utils/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 '../ws/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/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/utils/matching/matchRequestUrl.test.ts

@@ -61,6 +61,50 @@ describe('matchRequestUrl', () => {
     expect(match).toHaveProperty('matches', false)
     expect(match).toHaveProperty('params', {})
   })
+
+  test('returns true for matching WebSocket URL', () => {
+    expect(
+      matchRequestUrl(new URL('ws://test.mswjs.io'), 'ws://test.mswjs.io'),
+    ).toEqual({
+      matches: true,
+      params: {},
+    })
+    expect(
+      matchRequestUrl(new URL('wss://test.mswjs.io'), 'wss://test.mswjs.io'),
+    ).toEqual({
+      matches: true,
+      params: {},
+    })
+  })
+
+  test('returns false for non-matching WebSocket URL', () => {
+    expect(
+      matchRequestUrl(new URL('ws://test.mswjs.io'), 'ws://foo.mswjs.io'),
+    ).toEqual({
+      matches: false,
+      params: {},
+    })
+    expect(
+      matchRequestUrl(new URL('wss://test.mswjs.io'), 'wss://completely.diff'),
+    ).toEqual({
+      matches: false,
+      params: {},
+    })
+  })
+
+  test('returns path parameters when matched a WebSocket URL', () => {
+    expect(
+      matchRequestUrl(
+        new URL('wss://test.mswjs.io'),
+        'wss://:service.mswjs.io',
+      ),
+    ).toEqual({
+      matches: true,
+      params: {
+        service: 'test',
+      },
+    })
+  })
 })
 
 describe('coercePath', () => {

package/src/core/utils/matching/matchRequestUrl.ts

@@ -71,3 +71,7 @@ export function matchRequestUrl(url: URL, path: Path, baseUrl?: string): Match {
     params,
   }
 }
+
+export function isPath(value: unknown): value is Path {
+  return typeof value === 'string' || value instanceof RegExp
+}