msw 2.0.12 → 2.0.13

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,
+          }),
+        })
+      }
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+import {
+  ServiceWorkerIncomingEventsMap,
+  SetupWorkerInternalContext,
+} from '../glossary'
+import { ServiceWorkerMessage } from './utils/createMessageChannel'
+import { isResponseWithoutBody } from '@mswjs/interceptors'
+
+export function createResponseListener(context: SetupWorkerInternalContext) {
+  return (
+    _: MessageEvent,
+    message: ServiceWorkerMessage<
+      'RESPONSE',
+      ServiceWorkerIncomingEventsMap['RESPONSE']
+    >,
+  ) => {
+    const { payload: responseJson } = message
+
+    /**
+     * CORS requests with `mode: "no-cors"` result in "opaque" responses.
+     * That kind of responses cannot be manipulated in JavaScript due
+     * to the security considerations.
+     * @see https://fetch.spec.whatwg.org/#concept-filtered-response-opaque
+     * @see https://github.com/mswjs/msw/issues/529
+     */
+    if (responseJson.type?.includes('opaque')) {
+      return
+    }
+
+    const response =
+      responseJson.status === 0
+        ? Response.error()
+        : new Response(
+            /**
+             * Responses may be streams here, but when we create a response object
+             * with null-body status codes, like 204, 205, 304 Response will
+             * throw when passed a non-null body, so ensure it's null here
+             * for those codes
+             */
+            isResponseWithoutBody(responseJson.status)
+              ? null
+              : responseJson.body,
+            responseJson,
+          )
+
+    context.emitter.emit(
+      responseJson.isMockedResponse ? 'response:mocked' : 'response:bypass',
+      {
+        response,
+        /**
+         * @todo @fixme In this context, we don't know anything about
+         * the request.
+         */
+        request: null as any,
+        requestId: responseJson.requestId,
+      },
+    )
+  }
+}

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

@@ -0,0 +1,143 @@
+import { until } from '@open-draft/until'
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { getWorkerInstance } from './utils/getWorkerInstance'
+import { enableMocking } from './utils/enableMocking'
+import { SetupWorkerInternalContext, StartHandler } from '../glossary'
+import { createRequestListener } from './createRequestListener'
+import { requestIntegrityCheck } from '../../utils/requestIntegrityCheck'
+import { deferNetworkRequestsUntil } from '../../utils/deferNetworkRequestsUntil'
+import { createResponseListener } from './createResponseListener'
+import { validateWorkerScope } from './utils/validateWorkerScope'
+
+export const createStartHandler = (
+  context: SetupWorkerInternalContext,
+): StartHandler => {
+  return function start(options, customOptions) {
+    const startWorkerInstance = async () => {
+      // Remove all previously existing event listeners.
+      // This way none of the listeners persists between Fast refresh
+      // of the application's code.
+      context.events.removeAllListeners()
+
+      // Handle requests signaled by the worker.
+      context.workerChannel.on(
+        'REQUEST',
+        createRequestListener(context, options),
+      )
+
+      // Handle responses signaled by the worker.
+      context.workerChannel.on('RESPONSE', createResponseListener(context))
+
+      const instance = await getWorkerInstance(
+        options.serviceWorker.url,
+        options.serviceWorker.options,
+        options.findWorker,
+      )
+
+      const [worker, registration] = instance
+
+      if (!worker) {
+        const missingWorkerMessage = customOptions?.findWorker
+          ? devUtils.formatMessage(
+              `Failed to locate the Service Worker registration using a custom "findWorker" predicate.
+
+Please ensure that the custom predicate properly locates the Service Worker registration at "%s".
+More details: https://mswjs.io/docs/api/setup-worker/start#findworker
+`,
+              options.serviceWorker.url,
+            )
+          : devUtils.formatMessage(
+              `Failed to locate the Service Worker registration.
+
+This most likely means that the worker script URL "%s" cannot resolve against the actual public hostname (%s). This may happen if your application runs behind a proxy, or has a dynamic hostname.
+
+Please consider using a custom "serviceWorker.url" option to point to the actual worker script location, or a custom "findWorker" option to resolve the Service Worker registration manually. More details: https://mswjs.io/docs/api/setup-worker/start`,
+              options.serviceWorker.url,
+              location.host,
+            )
+
+        throw new Error(missingWorkerMessage)
+      }
+
+      context.worker = worker
+      context.registration = registration
+
+      context.events.addListener(window, 'beforeunload', () => {
+        if (worker.state !== 'redundant') {
+          // Notify the Service Worker that this client has closed.
+          // Internally, it's similar to disabling the mocking, only
+          // client close event has a handler that self-terminates
+          // the Service Worker when there are no open clients.
+          context.workerChannel.send('CLIENT_CLOSED')
+        }
+        // Make sure we're always clearing the interval - there are reports that not doing this can
+        // cause memory leaks in headless browser environments.
+        window.clearInterval(context.keepAliveInterval)
+      })
+
+      // Check if the active Service Worker is the latest published one
+      const integrityCheckResult = await until(() =>
+        requestIntegrityCheck(context, worker),
+      )
+
+      if (integrityCheckResult.error) {
+        devUtils.error(`\
+Detected outdated Service Worker: ${integrityCheckResult.error.message}
+
+The mocking is still enabled, but it's highly recommended that you update your Service Worker by running:
+
+$ npx msw init <PUBLIC_DIR>
+
+This is necessary to ensure that the Service Worker is in sync with the library to guarantee its stability.
+If this message still persists after updating, please report an issue: https://github.com/open-draft/msw/issues\
+      `)
+      }
+
+      context.keepAliveInterval = window.setInterval(
+        () => context.workerChannel.send('KEEPALIVE_REQUEST'),
+        5000,
+      )
+
+      // Warn the user when loading the page that lies outside
+      // of the worker's scope.
+      validateWorkerScope(registration, context.startOptions)
+
+      return registration
+    }
+
+    const workerRegistration = startWorkerInstance().then(
+      async (registration) => {
+        const pendingInstance = registration.installing || registration.waiting
+
+        // Wait until the worker is activated.
+        // Assume the worker is already activated if there's no pending registration
+        // (i.e. when reloading the page after a successful activation).
+        if (pendingInstance) {
+          await new Promise<void>((resolve) => {
+            pendingInstance.addEventListener('statechange', () => {
+              if (pendingInstance.state === 'activated') {
+                return resolve()
+              }
+            })
+          })
+        }
+
+        // Print the activation message only after the worker has been activated.
+        await enableMocking(context, options).catch((error) => {
+          throw new Error(`Failed to enable mocking: ${error?.message}`)
+        })
+
+        return registration
+      },
+    )
+
+    // Defer any network requests until the Service Worker instance is ready.
+    // This prevents a race condition between the Service Worker registration
+    // and application's runtime requests (i.e. requests on mount).
+    if (options.waitUntilReady) {
+      deferNetworkRequestsUntil(workerRegistration)
+    }
+
+    return workerRegistration
+  }
+}

package/src/browser/setupWorker/start/utils/createMessageChannel.ts

@@ -0,0 +1,32 @@
+import {
+  StringifiedResponse,
+  ServiceWorkerIncomingEventsMap,
+} from '../../glossary'
+
+export interface ServiceWorkerMessage<
+  EventType extends keyof ServiceWorkerIncomingEventsMap,
+  EventPayload,
+> {
+  type: EventType
+  payload: EventPayload
+}
+
+interface WorkerChannelEventsMap {
+  MOCK_RESPONSE: [
+    data: StringifiedResponse,
+    transfer?: [ReadableStream<Uint8Array>],
+  ]
+  NOT_FOUND: []
+}
+
+export class WorkerChannel {
+  constructor(private readonly port: MessagePort) {}
+
+  public postMessage<Event extends keyof WorkerChannelEventsMap>(
+    event: Event,
+    ...rest: WorkerChannelEventsMap[Event]
+  ): void {
+    const [data, transfer] = rest
+    this.port.postMessage({ type: event, data }, { transfer })
+  }
+}

package/src/browser/setupWorker/start/utils/enableMocking.ts

@@ -0,0 +1,32 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { StartOptions, SetupWorkerInternalContext } from '../../glossary'
+import { printStartMessage } from './printStartMessage'
+
+/**
+ * Signals the worker to enable the interception of requests.
+ */
+export async function enableMocking(
+  context: SetupWorkerInternalContext,
+  options: StartOptions,
+) {
+  context.workerChannel.send('MOCK_ACTIVATE')
+  await context.events.once('MOCKING_ENABLED')
+
+  // Warn the developer on multiple "worker.start()" calls.
+  // While this will not affect the worker in any way,
+  // it likely indicates an issue with the developer's code.
+  if (context.isMockingEnabled) {
+    devUtils.warn(
+      `Found a redundant "worker.start()" call. Note that starting the worker while mocking is already enabled will have no effect. Consider removing this "worker.start()" call.`,
+    )
+    return
+  }
+
+  context.isMockingEnabled = true
+
+  printStartMessage({
+    quiet: options.quiet,
+    workerScope: context.registration?.scope,
+    workerUrl: context.worker?.scriptURL,
+  })
+}