msw 2.12.13 → 2.13.0

package/src/core/experimental/request-utils.ts

@@ -0,0 +1,39 @@
+export const REQUEST_INTENTION_HEADER_NAME = 'x-msw-intention'
+
+export enum RequestIntention {
+  passthrough = 'passthrough',
+}
+
+export function shouldBypassRequest(request: Request): boolean {
+  return !!request.headers.get('accept')?.includes('msw/passthrough')
+}
+
+export function isPassthroughResponse(response: Response): boolean {
+  return (
+    response.status === 302 &&
+    response.headers.get(REQUEST_INTENTION_HEADER_NAME) ===
+      RequestIntention.passthrough
+  )
+}
+
+/**
+ * Remove the internal passthrough instruction from the request's `Accept` header.
+ */
+export function deleteRequestPassthroughHeader(request: Request): void {
+  const acceptHeader = request.headers.get('accept')
+
+  /**
+   * @note Remove the internal bypass request header.
+   * In the browser, this is done by the worker script.
+   * In Node.js, it has to be done here.
+   */
+  if (acceptHeader) {
+    const nextAcceptHeader = acceptHeader.replace(/(,\s+)?msw\/passthrough/, '')
+
+    if (nextAcceptHeader) {
+      request.headers.set('accept', nextAcceptHeader)
+    } else {
+      request.headers.delete('accept')
+    }
+  }
+}

package/src/core/experimental/setup-api.ts

@@ -0,0 +1,59 @@
+import { type DefaultEventMap, Emitter } from 'rettime'
+import { LifeCycleEventEmitter } from '../sharedOptions'
+import {
+  AnyHandler,
+  HandlersController,
+  InMemoryHandlersController,
+} from './handlers-controller'
+import { Disposable } from '../utils/internal/Disposable'
+import { toReadonlyArray } from '../utils/internal/toReadonlyArray'
+
+/**
+ * Generic class for the mock API setup.
+ * Preserved only for backward compatibility.
+ * @deprecated
+ */
+export abstract class SetupApi<
+  EventMap extends DefaultEventMap,
+> extends Disposable {
+  protected handlersController: HandlersController
+  protected emitter: Emitter<EventMap>
+  protected publicEmitter: Emitter<EventMap>
+
+  public readonly events: LifeCycleEventEmitter<EventMap>
+
+  constructor(...initialHandlers: Array<AnyHandler>) {
+    super()
+
+    this.handlersController = new InMemoryHandlersController(initialHandlers)
+
+    this.emitter = new Emitter()
+    this.publicEmitter = new Emitter()
+    this.events = this.emitter
+
+    this.subscriptions.push(() => {
+      this.emitter.removeAllListeners()
+      this.publicEmitter.removeAllListeners()
+    })
+  }
+
+  public use(...runtimeHandlers: Array<AnyHandler>): void {
+    this.handlersController.use(runtimeHandlers)
+  }
+
+  public restoreHandlers(): void {
+    this.handlersController.currentHandlers().forEach((handler) => {
+      if ('isUsed' in handler) {
+        handler.isUsed = false
+      }
+    })
+  }
+
+  public resetHandlers(...nextHandlers: Array<AnyHandler>): void {
+    this.handlersController.reset(nextHandlers)
+  }
+
+  public listHandlers(): ReadonlyArray<AnyHandler> {
+    return toReadonlyArray(this.handlersController.currentHandlers())
+  }
+}

package/src/core/experimental/sources/interceptor-source.ts

@@ -0,0 +1,185 @@
+import {
+  BatchInterceptor,
+  Interceptor,
+  RequestController,
+  type HttpRequestEventMap,
+} from '@mswjs/interceptors'
+import type {
+  WebSocketConnectionData,
+  WebSocketEventMap,
+} from '@mswjs/interceptors/WebSocket'
+import { NetworkSource } from './network-source'
+import { InternalError } from '../../utils/internal/devUtils'
+import { HttpNetworkFrame, ResponseEvent } from '../frames/http-frame'
+import { WebSocketNetworkFrame } from '../frames/websocket-frame'
+import { deleteRequestPassthroughHeader } from '../request-utils'
+
+export interface InterceptorSourceOptions {
+  interceptors: Array<Interceptor<HttpRequestEventMap | WebSocketEventMap>>
+}
+
+/**
+ * Create a network source from the given list of interceptors.
+ */
+export class InterceptorSource extends NetworkSource {
+  #interceptor: BatchInterceptor<
+    InterceptorSourceOptions['interceptors'],
+    HttpRequestEventMap | WebSocketEventMap
+  >
+
+  #frames: Map<string, HttpNetworkFrame>
+
+  constructor(options: InterceptorSourceOptions) {
+    super()
+
+    this.#interceptor = new BatchInterceptor({
+      name: 'interceptor-source',
+      interceptors: options.interceptors,
+    })
+    this.#frames = new Map()
+  }
+
+  public enable(): void {
+    this.#interceptor.apply()
+
+    /**
+     * @todo @fixme BatchInterceptor infers event types but not listener types.
+     */
+    this.#interceptor
+      .on('request', this.#handleRequest.bind(this) as any)
+      .on('response', this.#handleResponse.bind(this) as any)
+      .on('connection', this.#handleWebSocketConnection.bind(this) as any)
+  }
+
+  public disable(): void {
+    super.disable()
+    this.#interceptor.dispose()
+
+    /**
+     * @todo We can also abort any pending frames here, given we implement
+     * the `NetworkFrame.abort()` method.
+     */
+    this.#frames.clear()
+  }
+
+  async #handleRequest({
+    requestId,
+    request,
+    controller,
+  }: HttpRequestEventMap['request'][0]): Promise<void> {
+    const httpFrame = new InterceptorHttpNetworkFrame({
+      id: requestId,
+      request,
+      controller,
+    })
+
+    this.#frames.set(requestId, httpFrame)
+    await this.queue(httpFrame)
+  }
+
+  async #handleResponse({
+    requestId,
+    request,
+    response,
+    isMockedResponse,
+  }: HttpRequestEventMap['response'][0]): Promise<void> {
+    const httpFrame = this.#frames.get(requestId)
+    this.#frames.delete(requestId)
+
+    if (httpFrame == null) {
+      return
+    }
+
+    queueMicrotask(() => {
+      httpFrame.events.emit(
+        new ResponseEvent(
+          isMockedResponse ? 'response:mocked' : 'response:bypass',
+          {
+            requestId,
+            request,
+            response,
+          },
+        ),
+      )
+    })
+  }
+
+  async #handleWebSocketConnection(
+    connection: WebSocketEventMap['connection'][0],
+  ): Promise<void> {
+    await this.queue(
+      new InterceptorWebSocketNetworkFrame({
+        connection,
+      }),
+    )
+  }
+}
+
+class InterceptorHttpNetworkFrame extends HttpNetworkFrame {
+  #controller: RequestController
+
+  constructor(options: {
+    id: string
+    request: Request
+    controller: RequestController
+  }) {
+    super({
+      id: options.id,
+      request: options.request,
+    })
+
+    this.#controller = options.controller
+  }
+
+  public passthrough(): void {
+    deleteRequestPassthroughHeader(this.data.request)
+  }
+
+  public respondWith(response?: Response): void {
+    if (response) {
+      this.#controller.respondWith(response)
+    }
+  }
+
+  public errorWith(reason?: unknown): void {
+    if (reason instanceof Response) {
+      return this.respondWith(reason)
+    }
+
+    if (reason instanceof InternalError) {
+      this.#controller.errorWith(reason)
+    }
+
+    throw reason
+  }
+}
+
+class InterceptorWebSocketNetworkFrame extends WebSocketNetworkFrame {
+  constructor(args: { connection: WebSocketConnectionData }) {
+    super({ connection: args.connection })
+  }
+
+  public errorWith(reason?: unknown): void {
+    if (reason instanceof Error) {
+      const { client } = this.data.connection
+
+      /**
+       * Use `client.errorWith(reason)` in the future.
+       * @see https://github.com/mswjs/interceptors/issues/747
+       */
+      const errorEvent = new Event('error')
+
+      Object.defineProperty(errorEvent, 'cause', {
+        enumerable: true,
+        configurable: false,
+        value: reason,
+      })
+
+      client.socket.dispatchEvent(errorEvent)
+    }
+  }
+
+  public passthrough() {
+    this.data.connection.server.connect()
+  }
+}

package/src/core/experimental/sources/network-source.test.ts

@@ -0,0 +1,74 @@
+import { NetworkFrame } from '../frames/network-frame'
+import { NetworkSource } from './network-source'
+
+class TestFrame extends NetworkFrame<any, any, any> {
+  constructor() {
+    super('test', {})
+  }
+
+  getHandlers = () => []
+  passthrough = vi.fn()
+  errorWith = vi.fn()
+  resolve = vi.fn()
+  getUnhandledMessage = vi.fn()
+}
+
+afterEach(() => {
+  vi.clearAllMocks()
+})
+
+it('emits the "frame" event when a frame is queued', async () => {
+  class CustomNetworkSource extends NetworkSource {
+    enable = async () => {}
+  }
+
+  const source = new CustomNetworkSource()
+  const frameListener = vi.fn()
+  source.on('frame', frameListener)
+
+  const frame = new TestFrame()
+  await expect(source.queue(frame)).resolves.toBeUndefined()
+
+  expect(frameListener).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({ frame }),
+  )
+})
+
+it('removes all listeners when "disable" is called', async () => {
+  class CustomNetworkSource extends NetworkSource {
+    enable = async () => {}
+  }
+
+  const source = new CustomNetworkSource()
+  const frameListener = vi.fn()
+  source.on('frame', frameListener)
+
+  expect(source.disable()).toBeUndefined()
+  await expect(source.queue(new TestFrame())).resolves.toBeUndefined()
+
+  expect.soft(frameListener).not.toHaveBeenCalled()
+})
+
+it('accepts AbortSignal when attaching event listeners', async () => {
+  class CustomNetworkSource extends NetworkSource {
+    enable = async () => {}
+  }
+
+  const source = new CustomNetworkSource()
+  const frame = new TestFrame()
+
+  const frameListener = vi.fn()
+  const controller = new AbortController()
+  source.on('frame', frameListener, { signal: controller.signal })
+
+  await expect(source.queue(frame)).resolves.toBeUndefined()
+  expect(frameListener).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({ frame }),
+  )
+
+  frameListener.mockClear()
+  controller.abort()
+
+  await expect(source.queue(frame)).resolves.toBeUndefined()
+  expect(frameListener).not.toHaveBeenCalled()
+})

package/src/core/experimental/sources/network-source.ts

@@ -0,0 +1,56 @@
+import { Emitter, TypedEvent, type TypedListenerOptions } from 'rettime'
+import {
+  type AnyNetworkFrame,
+  type ExtractFrameEvents,
+} from '../frames/network-frame'
+
+class NetworkFrameEvent<
+  DataType = void,
+  ReturnType = void,
+  EventType extends string = string,
+> extends TypedEvent<DataType, ReturnType, EventType> {
+  public frame: AnyNetworkFrame
+
+  constructor(type: string, frame: AnyNetworkFrame) {
+    super(...([type, {}] as any))
+    this.frame = frame
+  }
+}
+
+type NetworkSourceEventMap<Frame extends AnyNetworkFrame> = {
+  frame: NetworkFrameEvent<Frame>
+}
+
+export type ExtractSourceEvents<Source> =
+  Source extends NetworkSource<infer Frame> ? ExtractFrameEvents<Frame> : never
+
+export abstract class NetworkSource<
+  Frame extends AnyNetworkFrame = AnyNetworkFrame,
+> {
+  protected emitter: Emitter<NetworkSourceEventMap<Frame>>
+
+  constructor() {
+    this.emitter = new Emitter()
+  }
+
+  public abstract enable(): unknown | Promise<unknown>
+
+  public async queue(frame: Frame): Promise<void> {
+    await this.emitter.emitAsPromise(
+      // @ts-expect-error Trouble handling a conditional type parameter.
+      new NetworkFrameEvent('frame', frame),
+    )
+  }
+
+  public on<Type extends keyof NetworkSourceEventMap<Frame>>(
+    type: Type,
+    listener: Emitter.ListenerType<typeof this.emitter, Type>,
+    options?: TypedListenerOptions,
+  ): void {
+    this.emitter.on(type, listener, options)
+  }
+
+  public disable(): void | Promise<void> {
+    this.emitter.removeAllListeners()
+  }
+}

package/src/core/handlers/RequestHandler.ts

@@ -11,7 +11,6 @@ import {
   HttpResponse,
   DefaultUnsafeFetchResponse,
 } from '../HttpResponse'
-import type { HandlerKind } from './common'
 import type { GraphQLRequestBody } from './GraphQLHandler'
 
 export type DefaultRequestMultipartBody = Record<
@@ -133,14 +132,7 @@ export abstract class RequestHandler<
     StrictRequest<DefaultBodyType>
   >()
 
-  private readonly __kind: HandlerKind
-
-  public info: HandlerInfo & RequestHandlerInternalInfo
-  /**
-   * Indicates whether this request handler has been used
-   * (its resolver has successfully executed).
-   */
-  public isUsed: boolean
+  public readonly kind = 'request' as const
 
   protected resolver: ResponseResolver<ResolverExtras, any, any>
   private resolverIterator?:
@@ -157,6 +149,14 @@ export abstract class RequestHandler<
   private resolverIteratorResult?: Response | HttpResponse<any>
   private options?: HandlerOptions
 
+  public info: HandlerInfo & RequestHandlerInternalInfo
+
+  /**
+   * Indicates whether this request handler has been used
+   * (its resolver has successfully executed).
+   */
+  public isUsed: boolean
+
   constructor(args: RequestHandlerArgs<HandlerInfo, HandlerOptions>) {
     this.resolver = args.resolver
     this.options = args.options
@@ -169,7 +169,6 @@ export abstract class RequestHandler<
     }
 
     this.isUsed = false
-    this.__kind = 'RequestHandler'
   }
 
   /**

package/src/core/handlers/WebSocketHandler.ts

@@ -12,7 +12,7 @@ import {
   matchRequestUrl,
 } from '../utils/matching/matchRequestUrl'
 import { getCallFrame } from '../utils/internal/getCallFrame'
-import type { HandlerKind } from './common'
+import { attachWebSocketLogger } from '../ws/utils/attachWebSocketLogger'
 
 type WebSocketHandlerParsedResult = {
   match: Match
@@ -31,18 +31,21 @@ export interface WebSocketHandlerConnection {
 
 export interface WebSocketResolutionContext {
   baseUrl?: string
+  [kAutoConnect]?: boolean
 }
 
 export const kEmitter = Symbol('kEmitter')
 export const kSender = Symbol('kSender')
+export const kConnect = Symbol('kConnect')
+export const kAutoConnect = Symbol('kAutoConnect')
+
 const kStopPropagationPatched = Symbol('kStopPropagationPatched')
 const KOnStopPropagation = Symbol('KOnStopPropagation')
 
 export class WebSocketHandler {
-  private readonly __kind: HandlerKind
-
   public id: string
   public callFrame?: string
+  public kind = 'websocket' as const
 
   protected [kEmitter]: Emitter<WebSocketHandlerEventMap>
 
@@ -51,7 +54,6 @@ export class WebSocketHandler {
 
     this[kEmitter] = new Emitter()
     this.callFrame = getCallFrame(new Error())
-    this.__kind = 'EventHandler'
   }
 
   public parse(args: {
@@ -95,16 +97,16 @@ export class WebSocketHandler {
   }
 
   public async run(
-    connection: Omit<WebSocketHandlerConnection, 'params'>,
+    connection: WebSocketConnectionData,
     resolutionContext?: WebSocketResolutionContext,
-  ): Promise<boolean> {
+  ): Promise<WebSocketHandlerConnection | null> {
     const parsedResult = this.parse({
       url: connection.client.url,
       resolutionContext,
     })
 
     if (!this.predicate({ url: connection.client.url, parsedResult })) {
-      return false
+      return null
     }
 
     const resolvedConnection: WebSocketHandlerConnection = {
@@ -112,10 +114,18 @@ export class WebSocketHandler {
       params: parsedResult.match.params || {},
     }
 
-    return this.connect(resolvedConnection)
+    if (resolutionContext?.[kAutoConnect]) {
+      if (this[kConnect](resolvedConnection)) {
+        return resolvedConnection
+      }
+
+      return null
+    }
+
+    return resolvedConnection
   }
 
-  protected connect(connection: WebSocketHandlerConnection): boolean {
+  protected [kConnect](connection: WebSocketHandlerConnection): boolean {
     // Support `event.stopPropagation()` for various client/server events.
     connection.client.addEventListener(
       'message',
@@ -143,11 +153,17 @@ export class WebSocketHandler {
       createStopPropagationListener(this),
     )
 
-    // Emit the connection event on the handler.
-    // This is what the developer adds listeners for.
+    /**
+     * @fixme Use "rettime" and await these events to have
+     * exceptions propagate properly.
+     */
     return this[kEmitter].emit('connection', connection)
   }
 
+  public log(connection: WebSocketConnectionData): () => void {
+    return attachWebSocketLogger(connection)
+  }
+
   #resolveWebSocketUrl(url: string, baseUrl?: string): string {
     const resolvedUrl = resolveWebSocketUrl(
       baseUrl

package/src/core/index.ts

@@ -1,6 +1,6 @@
 import { checkGlobals } from './utils/internal/checkGlobals'
 
-export { SetupApi } from './SetupApi'
+export { SetupApi } from './experimental/setup-api'
 
 /* HTTP handlers */
 export { RequestHandler } from './handlers/RequestHandler'
@@ -26,12 +26,6 @@ export {
   type ServerSentEventMessage,
 } from './sse'
 
-import type { HttpHandler } from './handlers/HttpHandler'
-import type { GraphQLHandler } from './handlers/GraphQLHandler'
-import type { WebSocketHandler } from './handlers/WebSocketHandler'
-
-export type AnyHandler = HttpHandler | GraphQLHandler | WebSocketHandler
-
 /* Utils */
 export { matchRequestUrl } from './utils/matching/matchRequestUrl'
 export { handleRequest, type HandleRequestOptions } from './utils/handleRequest'
@@ -47,6 +41,8 @@ export { cleanUrl } from './utils/url/cleanUrl'
  * Type definitions.
  */
 
+export type { AnyHandler } from './experimental/handlers-controller'
+
 export type { SharedOptions, LifeCycleEventsMap } from './sharedOptions'
 
 export type {

package/src/core/sharedOptions.ts

@@ -1,4 +1,4 @@
-import type { Emitter } from 'strict-event-emitter'
+import type { Emitter, DefaultEventMap } from 'rettime'
 import type { UnhandledRequestStrategy } from './utils/request/onUnhandledRequest'
 
 export interface SharedOptions {
@@ -13,6 +13,10 @@ export interface SharedOptions {
   onUnhandledRequest?: UnhandledRequestStrategy
 }
 
+/**
+ * @deprecated
+ * Please use `HttpNetworkFrameEventMap` or `WebSocketNetworkFrameEventMap` instead.
+ */
 export type LifeCycleEventsMap = {
   'request:start': [
     args: {
@@ -61,6 +65,7 @@ export type LifeCycleEventsMap = {
   ]
 }
 
-export type LifeCycleEventEmitter<
-  EventsMap extends Record<string | symbol, any>,
-> = Pick<Emitter<EventsMap>, 'on' | 'removeListener' | 'removeAllListeners'>
+export type LifeCycleEventEmitter<EventMap extends DefaultEventMap> = Pick<
+  Emitter<EventMap>,
+  'on' | 'removeListener' | 'removeAllListeners'
+>

package/src/core/sse.ts

@@ -6,7 +6,7 @@ import {
   type HttpRequestResolverExtras,
   type HttpRequestParsedResult,
 } from './handlers/HttpHandler'
-import type { ResponseResolutionContext } from '~/core/utils/executeHandlers'
+import type { ResponseResolutionContext } from '#core/utils/executeHandlers'
 import type { Path, PathParams } from './utils/matching/matchRequestUrl'
 import { delay } from './delay'
 import { getTimestamp } from './utils/logging/getTimestamp'

package/src/core/utils/cookieStore.ts

@@ -4,6 +4,7 @@ import {
   Cookie,
   CookieJar,
   MemoryCookieStore,
+  SerializedCookie,
   type MemoryCookieStoreIndex,
 } from 'tough-cookie'
 import { jsonParse } from './internal/jsonParse'
@@ -76,7 +77,7 @@ class CookieStore {
       return
     }
 
-    const data = []
+    const data: Array<SerializedCookie> = []
     const { idx } = this.#memoryStore
 
     for (const domain in idx) {