msw 2.0.11 → 2.0.13

package/src/browser/setupWorker/glossary.ts

@@ -0,0 +1,259 @@
+import { Emitter } from 'strict-event-emitter'
+import {
+  LifeCycleEventEmitter,
+  LifeCycleEventsMap,
+  SharedOptions,
+} from '~/core/sharedOptions'
+import { ServiceWorkerMessage } from './start/utils/createMessageChannel'
+import {
+  RequestHandler,
+  RequestHandlerDefaultInfo,
+} from '~/core/handlers/RequestHandler'
+import type { HttpRequestEventMap, Interceptor } from '@mswjs/interceptors'
+import { Path } from '~/core/utils/matching/matchRequestUrl'
+import { RequiredDeep } from '~/core/typeUtils'
+
+export type ResolvedPath = Path | URL
+
+type RequestWithoutMethods = Omit<
+  Request,
+  | 'text'
+  | 'body'
+  | 'json'
+  | 'blob'
+  | 'arrayBuffer'
+  | 'formData'
+  | 'clone'
+  | 'signal'
+  | 'isHistoryNavigation'
+  | 'isReloadNavigation'
+>
+
+/**
+ * Request representation received from the worker message event.
+ */
+export interface ServiceWorkerIncomingRequest extends RequestWithoutMethods {
+  /**
+   * Unique ID of the request generated once the request is
+   * intercepted by the "fetch" event in the Service Worker.
+   */
+  id: string
+  body?: ArrayBuffer | null
+}
+
+export type ServiceWorkerIncomingResponse = Pick<
+  Response,
+  'type' | 'ok' | 'status' | 'statusText' | 'body' | 'headers' | 'redirected'
+> & {
+  requestId: string
+  isMockedResponse: boolean
+}
+
+/**
+ * Map of the events that can be received from the Service Worker.
+ */
+export interface ServiceWorkerIncomingEventsMap {
+  MOCKING_ENABLED: boolean
+  INTEGRITY_CHECK_RESPONSE: string
+  KEEPALIVE_RESPONSE: never
+  REQUEST: ServiceWorkerIncomingRequest
+  RESPONSE: ServiceWorkerIncomingResponse
+}
+
+/**
+ * Map of the events that can be sent to the Service Worker
+ * from any execution context.
+ */
+export type ServiceWorkerOutgoingEventTypes =
+  | 'MOCK_ACTIVATE'
+  | 'MOCK_DEACTIVATE'
+  | 'INTEGRITY_CHECK_REQUEST'
+  | 'KEEPALIVE_REQUEST'
+  | 'CLIENT_CLOSED'
+
+export interface StringifiedResponse extends ResponseInit {
+  body: string | ArrayBuffer | ReadableStream<Uint8Array> | null
+}
+
+/**
+ * Map of the events that can be sent to the Service Worker
+ * only as a part of a single `fetch` event handler.
+ */
+export interface ServiceWorkerFetchEventMap {
+  MOCK_RESPONSE(payload: StringifiedResponse): void
+  MOCK_RESPONSE_START(payload: StringifiedResponse): void
+
+  MOCK_NOT_FOUND(): void
+  NETWORK_ERROR(payload: { name: string; message: string }): void
+  INTERNAL_ERROR(payload: { status: number; body: string }): void
+}
+
+export interface ServiceWorkerBroadcastChannelMessageMap {
+  MOCK_RESPONSE_CHUNK(payload: Uint8Array): void
+  MOCK_RESPONSE_END(): void
+}
+
+export interface StrictEventListener<EventType extends Event> {
+  (event: EventType): void
+}
+
+export interface SetupWorkerInternalContext {
+  isMockingEnabled: boolean
+  startOptions: RequiredDeep<StartOptions>
+  worker: ServiceWorker | null
+  registration: ServiceWorkerRegistration | null
+  requestHandlers: Array<RequestHandler>
+  emitter: Emitter<LifeCycleEventsMap>
+  keepAliveInterval?: number
+  workerChannel: {
+    /**
+     * Adds a Service Worker event listener.
+     */
+    on<EventType extends keyof ServiceWorkerIncomingEventsMap>(
+      eventType: EventType,
+      callback: (
+        event: MessageEvent,
+        message: ServiceWorkerMessage<
+          EventType,
+          ServiceWorkerIncomingEventsMap[EventType]
+        >,
+      ) => void,
+    ): void
+    send<EventType extends ServiceWorkerOutgoingEventTypes>(
+      eventType: EventType,
+    ): void
+  }
+  events: {
+    /**
+     * Adds an event listener on the given target.
+     * Returns a clean-up function that removes that listener.
+     */
+    addListener<EventType extends Event>(
+      target: EventTarget,
+      eventType: string,
+      callback: StrictEventListener<EventType>,
+    ): () => void
+    /**
+     * Removes all currently attached listeners.
+     */
+    removeAllListeners(): void
+    /**
+     * Awaits a given message type from the Service Worker.
+     */
+    once<EventType extends keyof ServiceWorkerIncomingEventsMap>(
+      eventType: EventType,
+    ): Promise<
+      ServiceWorkerMessage<EventType, ServiceWorkerIncomingEventsMap[EventType]>
+    >
+  }
+  supports: {
+    serviceWorkerApi: boolean
+    readableStreamTransfer: boolean
+  }
+  fallbackInterceptor?: Interceptor<HttpRequestEventMap>
+}
+
+export type ServiceWorkerInstanceTuple = [
+  ServiceWorker | null,
+  ServiceWorkerRegistration,
+]
+
+export type FindWorker = (
+  scriptUrl: string,
+  mockServiceWorkerUrl: string,
+) => boolean
+
+export interface StartOptions extends SharedOptions {
+  /**
+   * Service Worker registration options.
+   */
+  serviceWorker?: {
+    /**
+     * Custom url to the worker script.
+     * @default "/mockServiceWorker.js"
+     */
+    url?: string
+    options?: RegistrationOptions
+  }
+
+  /**
+   * Disables the logging of the intercepted requests
+   * into browser's console.
+   * @default false
+   */
+  quiet?: boolean
+
+  /**
+   * Defers any network requests until the Service Worker
+   * instance is activated.
+   * @default true
+   */
+  waitUntilReady?: boolean
+
+  /**
+   * A custom lookup function to find a Mock Service Worker in the list
+   * of all registered Service Workers on the page.
+   */
+  findWorker?: FindWorker
+}
+
+export type StartReturnType = Promise<ServiceWorkerRegistration | undefined>
+export type StartHandler = (
+  options: RequiredDeep<StartOptions>,
+  initialOptions: StartOptions,
+) => StartReturnType
+export type StopHandler = () => void
+
+export interface SetupWorker {
+  /**
+   * Registers and activates the mock Service Worker.
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/start `worker.start()` API reference}
+   */
+  start: (options?: StartOptions) => StartReturnType
+
+  /**
+   * Stops requests interception for the current client.
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/stop `worker.stop()` API reference}
+   */
+  stop: StopHandler
+
+  /**
+   * Prepends given request handlers to the list of existing handlers.
+   * @param {RequestHandler[]} handlers List of runtime request handlers.
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
+   */
+  use: (...handlers: RequestHandler[]) => void
+
+  /**
+   * Marks all request handlers that respond using `res.once()` as unused.
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/restore-handlers `worker.restoreHandlers()` API reference}
+   */
+  restoreHandlers: () => void
+
+  /**
+   * Resets request handlers to the initial list given to the `setupWorker` call, or to the explicit next request handlers list, if given.
+   * @param {RequestHandler[]} nextHandlers List of the new initial request handlers.
+   *
+   * @see {@link https://mswjs.io/docs/api/setup-worker/reset-handlers `worker.resetHandlers()` API reference}
+   */
+  resetHandlers: (...nextHandlers: RequestHandler[]) => 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>>
+
+  /**
+   * Life-cycle events.
+   * Life-cycle events allow you to subscribe to the internal library events occurring during the request/response handling.
+   *
+   * @see {@link https://mswjs.io/docs/api/life-cycle-events Life-cycle Events API reference}
+   */
+  events: LifeCycleEventEmitter<LifeCycleEventsMap>
+}

package/src/browser/setupWorker/setupWorker.node.test.ts

@@ -0,0 +1,10 @@
+/**
+ * @vitest-environment node
+ */
+import { setupWorker } from './setupWorker'
+
+test('returns an error when run in a Node.js environment', () => {
+  expect(setupWorker).toThrow(
+    '[MSW] Failed to execute `setupWorker` in a non-browser environment',
+  )
+})

package/src/browser/setupWorker/setupWorker.ts

@@ -0,0 +1,199 @@
+import { invariant } from 'outvariant'
+import { isNodeProcess } from 'is-node-process'
+import {
+  SetupWorkerInternalContext,
+  ServiceWorkerIncomingEventsMap,
+  StartReturnType,
+  StopHandler,
+  StartHandler,
+  StartOptions,
+} from './glossary'
+import { createStartHandler } from './start/createStartHandler'
+import { createStop } from './stop/createStop'
+import { ServiceWorkerMessage } from './start/utils/createMessageChannel'
+import { RequestHandler } from '~/core/handlers/RequestHandler'
+import { DEFAULT_START_OPTIONS } from './start/utils/prepareStartHandler'
+import { createFallbackStart } from './start/createFallbackStart'
+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 { SetupWorker } from './glossary'
+import { supportsReadableStreamTransfer } from '../utils/supportsReadableStreamTransfer'
+
+interface Listener {
+  target: EventTarget
+  eventType: string
+  callback: EventListenerOrEventListenerObject
+}
+
+export class SetupWorkerApi
+  extends SetupApi<LifeCycleEventsMap>
+  implements SetupWorker
+{
+  private context: SetupWorkerInternalContext
+  private startHandler: StartHandler = null as any
+  private stopHandler: StopHandler = null as any
+  private listeners: Array<Listener>
+
+  constructor(...handlers: Array<RequestHandler>) {
+    super(...handlers)
+
+    invariant(
+      !isNodeProcess(),
+      devUtils.formatMessage(
+        'Failed to execute `setupWorker` in a non-browser environment. Consider using `setupServer` for Node.js environment instead.',
+      ),
+    )
+
+    this.listeners = []
+    this.context = this.createWorkerContext()
+  }
+
+  private createWorkerContext(): SetupWorkerInternalContext {
+    const context: SetupWorkerInternalContext = {
+      // Mocking is not considered enabled until the worker
+      // signals back the successful activation event.
+      isMockingEnabled: false,
+      startOptions: null as any,
+      worker: null,
+      registration: null,
+      requestHandlers: this.currentHandlers,
+      emitter: this.emitter,
+      workerChannel: {
+        on: (eventType, callback) => {
+          this.context.events.addListener<
+            MessageEvent<ServiceWorkerMessage<typeof eventType, any>>
+          >(navigator.serviceWorker, 'message', (event) => {
+            // Avoid messages broadcasted from unrelated workers.
+            if (event.source !== this.context.worker) {
+              return
+            }
+
+            const message = event.data
+
+            if (!message) {
+              return
+            }
+
+            if (message.type === eventType) {
+              callback(event, message)
+            }
+          })
+        },
+        send: (type) => {
+          this.context.worker?.postMessage(type)
+        },
+      },
+      events: {
+        addListener: (target, eventType, callback) => {
+          target.addEventListener(eventType, callback as EventListener)
+          this.listeners.push({
+            eventType,
+            target,
+            callback: callback as EventListener,
+          })
+
+          return () => {
+            target.removeEventListener(eventType, callback as EventListener)
+          }
+        },
+        removeAllListeners: () => {
+          for (const { target, eventType, callback } of this.listeners) {
+            target.removeEventListener(eventType, callback)
+          }
+          this.listeners = []
+        },
+        once: (eventType) => {
+          const bindings: Array<() => void> = []
+
+          return new Promise<
+            ServiceWorkerMessage<
+              typeof eventType,
+              ServiceWorkerIncomingEventsMap[typeof eventType]
+            >
+          >((resolve, reject) => {
+            const handleIncomingMessage = (event: MessageEvent) => {
+              try {
+                const message = event.data
+
+                if (message.type === eventType) {
+                  resolve(message)
+                }
+              } catch (error) {
+                reject(error)
+              }
+            }
+
+            bindings.push(
+              this.context.events.addListener(
+                navigator.serviceWorker,
+                'message',
+                handleIncomingMessage,
+              ),
+              this.context.events.addListener(
+                navigator.serviceWorker,
+                'messageerror',
+                reject,
+              ),
+            )
+          }).finally(() => {
+            bindings.forEach((unbind) => unbind())
+          })
+        },
+      },
+      supports: {
+        serviceWorkerApi:
+          !('serviceWorker' in navigator) || location.protocol === 'file:',
+        readableStreamTransfer: supportsReadableStreamTransfer(),
+      },
+    }
+
+    /**
+     * @todo Not sure I like this but "this.currentHandlers"
+     * updates never bubble to "this.context.requestHandlers".
+     */
+    Object.defineProperties(context, {
+      requestHandlers: {
+        get: () => this.currentHandlers,
+      },
+    })
+
+    this.startHandler = context.supports.serviceWorkerApi
+      ? createFallbackStart(context)
+      : createStartHandler(context)
+
+    this.stopHandler = context.supports.serviceWorkerApi
+      ? createFallbackStop(context)
+      : createStop(context)
+
+    return context
+  }
+
+  public async start(options: StartOptions = {}): StartReturnType {
+    this.context.startOptions = mergeRight(
+      DEFAULT_START_OPTIONS,
+      options,
+    ) as SetupWorkerInternalContext['startOptions']
+
+    return await this.startHandler(this.context.startOptions, options)
+  }
+
+  public stop(): void {
+    super.dispose()
+    this.context.events.removeAllListeners()
+    this.context.emitter.removeAllListeners()
+    this.stopHandler()
+  }
+}
+
+/**
+ * Sets up a requests interception in the browser with the given request handlers.
+ * @param {RequestHandler[]} handlers List of request handlers.
+ *
+ * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker()` API reference}
+ */
+export function setupWorker(...handlers: Array<RequestHandler>): SetupWorker {
+  return new SetupWorkerApi(...handlers)
+}

package/src/browser/setupWorker/start/createFallbackRequestListener.ts

@@ -0,0 +1,67 @@
+import {
+  Interceptor,
+  BatchInterceptor,
+  HttpRequestEventMap,
+} from '@mswjs/interceptors'
+import { FetchInterceptor } from '@mswjs/interceptors/fetch'
+import { XMLHttpRequestInterceptor } from '@mswjs/interceptors/XMLHttpRequest'
+import { SetupWorkerInternalContext, StartOptions } from '../glossary'
+import type { RequiredDeep } from '~/core/typeUtils'
+import { handleRequest } from '~/core/utils/handleRequest'
+
+export function createFallbackRequestListener(
+  context: SetupWorkerInternalContext,
+  options: RequiredDeep<StartOptions>,
+): Interceptor<HttpRequestEventMap> {
+  const interceptor = new BatchInterceptor({
+    name: 'fallback',
+    interceptors: [new FetchInterceptor(), new XMLHttpRequestInterceptor()],
+  })
+
+  interceptor.on('request', async ({ request, requestId }) => {
+    const requestCloneForLogs = request.clone()
+
+    const response = await handleRequest(
+      request,
+      requestId,
+      context.requestHandlers,
+      options,
+      context.emitter,
+      {
+        onMockedResponse(_, { handler, parsedResult }) {
+          if (!options.quiet) {
+            context.emitter.once('response:mocked', ({ response }) => {
+              handler.log({
+                request: requestCloneForLogs,
+                response,
+                parsedResult,
+              })
+            })
+          }
+        },
+      },
+    )
+
+    if (response) {
+      request.respondWith(response)
+    }
+  })
+
+  interceptor.on(
+    'response',
+    ({ response, isMockedResponse, request, requestId }) => {
+      context.emitter.emit(
+        isMockedResponse ? 'response:mocked' : 'response:bypass',
+        {
+          response,
+          request,
+          requestId,
+        },
+      )
+    },
+  )
+
+  interceptor.apply()
+
+  return interceptor
+}

package/src/browser/setupWorker/start/createFallbackStart.ts

@@ -0,0 +1,21 @@
+import { createFallbackRequestListener } from './createFallbackRequestListener'
+import { SetupWorkerInternalContext, StartHandler } from '../glossary'
+import { printStartMessage } from './utils/printStartMessage'
+
+export function createFallbackStart(
+  context: SetupWorkerInternalContext,
+): StartHandler {
+  return async function start(options) {
+    context.fallbackInterceptor = createFallbackRequestListener(
+      context,
+      options,
+    )
+
+    printStartMessage({
+      message: 'Mocking enabled (fallback mode).',
+      quiet: options.quiet,
+    })
+
+    return undefined
+  }
+}

package/src/browser/setupWorker/start/createRequestListener.ts

@@ -0,0 +1,127 @@
+import {
+  StartOptions,
+  SetupWorkerInternalContext,
+  ServiceWorkerIncomingEventsMap,
+} from '../glossary'
+import {
+  ServiceWorkerMessage,
+  WorkerChannel,
+} from './utils/createMessageChannel'
+import { parseWorkerRequest } from '../../utils/parseWorkerRequest'
+import { handleRequest } from '~/core/utils/handleRequest'
+import { RequiredDeep } from '~/core/typeUtils'
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { toResponseInit } from '~/core/utils/toResponseInit'
+
+export const createRequestListener = (
+  context: SetupWorkerInternalContext,
+  options: RequiredDeep<StartOptions>,
+) => {
+  return async (
+    event: MessageEvent,
+    message: ServiceWorkerMessage<
+      'REQUEST',
+      ServiceWorkerIncomingEventsMap['REQUEST']
+    >,
+  ) => {
+    const messageChannel = new WorkerChannel(event.ports[0])
+
+    const requestId = message.payload.id
+    const request = parseWorkerRequest(message.payload)
+    const requestCloneForLogs = request.clone()
+
+    try {
+      await handleRequest(
+        request,
+        requestId,
+        context.requestHandlers,
+        options,
+        context.emitter,
+        {
+          onPassthroughResponse() {
+            messageChannel.postMessage('NOT_FOUND')
+          },
+          async onMockedResponse(response, { handler, parsedResult }) {
+            // Clone the mocked response so its body could be read
+            // to buffer to be sent to the worker and also in the
+            // ".log()" method of the request handler.
+            const responseClone = response.clone()
+            const responseCloneForLogs = response.clone()
+            const responseInit = toResponseInit(response)
+
+            /**
+             * @note Safari doesn't support transferring a "ReadableStream".
+             * Check that the browser supports that before sending it to the worker.
+             */
+            if (context.supports.readableStreamTransfer) {
+              const responseStreamOrNull = response.body
+
+              messageChannel.postMessage(
+                'MOCK_RESPONSE',
+                {
+                  ...responseInit,
+                  body: responseStreamOrNull,
+                },
+                responseStreamOrNull ? [responseStreamOrNull] : undefined,
+              )
+            } else {
+              /**
+               * @note If we are here, this means the current environment doesn't
+               * support "ReadableStream" as transferable. In that case,
+               * attempt to read the non-empty response body as ArrayBuffer, if it's not empty.
+               * @see https://github.com/mswjs/msw/issues/1827
+               */
+              const responseBufferOrNull =
+                response.body === null
+                  ? null
+                  : await responseClone.arrayBuffer()
+
+              messageChannel.postMessage('MOCK_RESPONSE', {
+                ...responseInit,
+                body: responseBufferOrNull,
+              })
+            }
+
+            if (!options.quiet) {
+              context.emitter.once('response:mocked', () => {
+                handler.log({
+                  request: requestCloneForLogs,
+                  response: responseCloneForLogs,
+                  parsedResult,
+                })
+              })
+            }
+          },
+        },
+      )
+    } catch (error) {
+      if (error instanceof Error) {
+        devUtils.error(
+          `Uncaught exception in the request handler for "%s %s":
+
+%s
+
+This exception has been gracefully handled as a 500 response, however, it's strongly recommended to resolve this error, as it indicates a mistake in your code. If you wish to mock an error response, please see this guide: https://mswjs.io/docs/recipes/mocking-error-responses`,
+          request.method,
+          request.url,
+          error.stack ?? error,
+        )
+
+        // Treat all other exceptions in a request handler as unintended,
+        // alerting that there is a problem that needs fixing.
+        messageChannel.postMessage('MOCK_RESPONSE', {
+          status: 500,
+          statusText: 'Request Handler Error',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+          }),
+        })
+      }
+    }
+  }
+}