msw 2.0.11 → 2.0.13

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

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

@@ -0,0 +1,25 @@
+import { FindWorker } from '../../glossary'
+
+/**
+ * Attempts to resolve a Service Worker instance from a given registration,
+ * regardless of its state (active, installing, waiting).
+ */
+export function getWorkerByRegistration(
+  registration: ServiceWorkerRegistration,
+  absoluteWorkerUrl: string,
+  findWorker: FindWorker,
+): ServiceWorker | null {
+  const allStates = [
+    registration.active,
+    registration.installing,
+    registration.waiting,
+  ]
+  const relevantStates = allStates.filter((state): state is ServiceWorker => {
+    return state != null
+  })
+  const worker = relevantStates.find((worker) => {
+    return findWorker(worker.scriptURL, absoluteWorkerUrl)
+  })
+
+  return worker || null
+}

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

@@ -0,0 +1,94 @@
+import { until } from '@open-draft/until'
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { getAbsoluteWorkerUrl } from '../../../utils/getAbsoluteWorkerUrl'
+import { getWorkerByRegistration } from './getWorkerByRegistration'
+import { ServiceWorkerInstanceTuple, FindWorker } from '../../glossary'
+
+/**
+ * Returns an active Service Worker instance.
+ * When not found, registers a new Service Worker.
+ */
+export const getWorkerInstance = async (
+  url: string,
+  options: RegistrationOptions = {},
+  findWorker: FindWorker,
+): Promise<ServiceWorkerInstanceTuple> => {
+  // Resolve the absolute Service Worker URL.
+  const absoluteWorkerUrl = getAbsoluteWorkerUrl(url)
+
+  const mockRegistrations = await navigator.serviceWorker
+    .getRegistrations()
+    .then((registrations) =>
+      registrations.filter((registration) =>
+        getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+      ),
+    )
+  if (!navigator.serviceWorker.controller && mockRegistrations.length > 0) {
+    // Reload the page when it has associated workers, but no active controller.
+    // The absence of a controller can mean either:
+    // - page has no Service Worker associated with it
+    // - page has been hard-reloaded and its workers won't be used until the next reload.
+    // Since we've checked that there are registrations associated with this page,
+    // at this point we are sure it's hard reload that falls into this clause.
+    location.reload()
+  }
+
+  const [existingRegistration] = mockRegistrations
+
+  if (existingRegistration) {
+    // When the Service Worker is registered, update it and return the reference.
+    return existingRegistration.update().then(() => {
+      return [
+        getWorkerByRegistration(
+          existingRegistration,
+          absoluteWorkerUrl,
+          findWorker,
+        ),
+        existingRegistration,
+      ]
+    })
+  }
+
+  // When the Service Worker wasn't found, register it anew and return the reference.
+  const registrationResult = await until<Error, ServiceWorkerInstanceTuple>(
+    async () => {
+      const registration = await navigator.serviceWorker.register(url, options)
+      return [
+        // Compare existing worker registration by its worker URL,
+        // to prevent irrelevant workers to resolve here (such as Codesandbox worker).
+        getWorkerByRegistration(registration, absoluteWorkerUrl, findWorker),
+        registration,
+      ]
+    },
+  )
+
+  // Handle Service Worker registration errors.
+  if (registrationResult.error) {
+    const isWorkerMissing = registrationResult.error.message.includes('(404)')
+
+    // Produce a custom error message when given a non-existing Service Worker url.
+    // Suggest developers to check their setup.
+    if (isWorkerMissing) {
+      const scopeUrl = new URL(options?.scope || '/', location.href)
+
+      throw new Error(
+        devUtils.formatMessage(`\
+Failed to register a Service Worker for scope ('${scopeUrl.href}') with script ('${absoluteWorkerUrl}'): Service Worker script does not exist at the given path.
+
+Did you forget to run "npx msw init <PUBLIC_DIR>"?
+
+Learn more about creating the Service Worker script: https://mswjs.io/docs/cli/init`),
+      )
+    }
+
+    // Fallback error message for any other registration errors.
+    throw new Error(
+      devUtils.formatMessage(
+        'Failed to register the Service Worker:\n\n%s',
+        registrationResult.error.message,
+      ),
+    )
+  }
+
+  return registrationResult.data
+}

package/src/browser/setupWorker/start/utils/prepareStartHandler.test.ts

@@ -0,0 +1,59 @@
+import { SetupWorkerInternalContext, StartOptions } from '../../glossary'
+import {
+  DEFAULT_START_OPTIONS,
+  resolveStartOptions,
+  prepareStartHandler,
+} from './prepareStartHandler'
+
+describe('resolveStartOptions', () => {
+  test('returns default options given no custom start options', () => {
+    expect(resolveStartOptions()).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions(undefined)).toEqual(DEFAULT_START_OPTIONS)
+    expect(resolveStartOptions({})).toEqual(DEFAULT_START_OPTIONS)
+  })
+
+  test('deeply merges the default and custom start options', () => {
+    expect(
+      resolveStartOptions({
+        quiet: true,
+        serviceWorker: {
+          url: './custom.js',
+        },
+      }),
+    ).toEqual({
+      ...DEFAULT_START_OPTIONS,
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+        options: null,
+      },
+    })
+  })
+})
+
+describe('prepareStartHandler', () => {
+  test('exposes resolved start options to the generated star handler', () => {
+    const createStartHandler = vi.fn()
+    const context: SetupWorkerInternalContext = {} as any
+    const startHandler = prepareStartHandler(createStartHandler, context)
+    expect(startHandler).toBeInstanceOf(Function)
+
+    const initialOptions: StartOptions = {
+      quiet: true,
+      serviceWorker: {
+        url: './custom.js',
+      },
+    }
+    const resolvedOptions = resolveStartOptions(initialOptions)
+    startHandler(initialOptions)
+
+    // Calls the handler creator with both resolved and initial options.
+    expect(createStartHandler).toHaveBeenCalledWith(
+      resolvedOptions,
+      initialOptions,
+    )
+
+    // Sets the resolved options on the internal context.
+    expect(context).toHaveProperty('startOptions', resolvedOptions)
+  })
+})

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

@@ -0,0 +1,44 @@
+import { RequiredDeep } from '~/core/typeUtils'
+import { mergeRight } from '~/core/utils/internal/mergeRight'
+import {
+  SetupWorker,
+  SetupWorkerInternalContext,
+  StartHandler,
+  StartOptions,
+} from '../../glossary'
+
+export const DEFAULT_START_OPTIONS: RequiredDeep<StartOptions> = {
+  serviceWorker: {
+    url: '/mockServiceWorker.js',
+    options: null as any,
+  },
+  quiet: false,
+  waitUntilReady: true,
+  onUnhandledRequest: 'warn',
+  findWorker(scriptURL, mockServiceWorkerUrl) {
+    return scriptURL === mockServiceWorkerUrl
+  },
+}
+
+/**
+ * Returns resolved worker start options, merging the default options
+ * with the given custom options.
+ */
+export function resolveStartOptions(
+  initialOptions?: StartOptions,
+): RequiredDeep<StartOptions> {
+  return mergeRight(
+    DEFAULT_START_OPTIONS,
+    initialOptions || {},
+  ) as RequiredDeep<StartOptions>
+}
+
+export function prepareStartHandler(
+  handler: StartHandler,
+  context: SetupWorkerInternalContext,
+): SetupWorker['start'] {
+  return (initialOptions) => {
+    context.startOptions = resolveStartOptions(initialOptions)
+    return handler(context.startOptions, initialOptions || {})
+  }
+}

package/src/browser/setupWorker/start/utils/printStartMessage.test.ts

@@ -0,0 +1,84 @@
+import { printStartMessage } from './printStartMessage'
+
+beforeEach(() => {
+  vi.spyOn(console, 'groupCollapsed').mockImplementation(() => void 0)
+  vi.spyOn(console, 'log').mockImplementation(() => void 0)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test('prints out a default start message into console', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/',
+    workerUrl: 'http://localhost:3000/worker.js',
+  })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Mocking enabled.',
+    expect.anything(),
+  )
+
+  // Includes a link to the documentation.
+  expect(console.log).toHaveBeenCalledWith(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    expect.anything(),
+    expect.anything(),
+  )
+
+  // Includes a link to the GitHub issues page.
+  expect(console.log).toHaveBeenCalledWith(
+    'Found an issue? https://github.com/mswjs/msw/issues',
+  )
+
+  // Includes service worker scope.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/',
+  )
+
+  // Includes service worker script location.
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/worker.js',
+  )
+})
+
+test('supports printing a custom start message', () => {
+  printStartMessage({ message: 'Custom start message' })
+
+  expect(console.groupCollapsed).toHaveBeenCalledWith(
+    '%c[MSW] Custom start message',
+    expect.anything(),
+  )
+})
+
+test('does not print any messages when log level is quiet', () => {
+  printStartMessage({ quiet: true })
+
+  expect(console.groupCollapsed).not.toHaveBeenCalled()
+  expect(console.log).not.toHaveBeenCalled()
+})
+
+test('prints a worker scope in the start message', () => {
+  printStartMessage({
+    workerScope: 'http://localhost:3000/user',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker scope:',
+    'http://localhost:3000/user',
+  )
+})
+
+test('prints a worker script url in the start message', () => {
+  printStartMessage({
+    workerUrl: 'http://localhost:3000/mockServiceWorker.js',
+  })
+
+  expect(console.log).toHaveBeenCalledWith(
+    'Worker script URL:',
+    'http://localhost:3000/mockServiceWorker.js',
+  )
+})

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

@@ -0,0 +1,40 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+
+export interface PrintStartMessageArgs {
+  quiet?: boolean
+  message?: string
+  workerUrl?: string
+  workerScope?: string
+}
+
+/**
+ * Prints a worker activation message in the browser's console.
+ */
+export function printStartMessage(args: PrintStartMessageArgs = {}) {
+  if (args.quiet) {
+    return
+  }
+
+  const message = args.message || 'Mocking enabled.'
+
+  console.groupCollapsed(
+    `%c${devUtils.formatMessage(message)}`,
+    'color:orangered;font-weight:bold;',
+  )
+  console.log(
+    '%cDocumentation: %chttps://mswjs.io/docs',
+    'font-weight:bold',
+    'font-weight:normal',
+  )
+  console.log('Found an issue? https://github.com/mswjs/msw/issues')
+
+  if (args.workerUrl) {
+    console.log('Worker script URL:', args.workerUrl)
+  }
+
+  if (args.workerScope) {
+    console.log('Worker scope:', args.workerScope)
+  }
+
+  console.groupEnd()
+}

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

@@ -0,0 +1,18 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { StartOptions } from '../../glossary'
+
+export function validateWorkerScope(
+  registration: ServiceWorkerRegistration,
+  options?: StartOptions,
+): void {
+  if (!options?.quiet && !location.href.startsWith(registration.scope)) {
+    devUtils.warn(
+      `\
+Cannot intercept requests on this page because it's outside of the worker's scope ("${registration.scope}"). If you wish to mock API requests on this page, you must resolve this scope issue.
+
+- (Recommended) Register the worker at the root level ("/") of your application.
+- Set the "Service-Worker-Allowed" response header to allow out-of-scope workers.\
+`,
+    )
+  }
+}

package/src/browser/setupWorker/stop/createFallbackStop.ts

@@ -0,0 +1,11 @@
+import { SetupWorkerInternalContext, StopHandler } from '../glossary'
+import { printStopMessage } from './utils/printStopMessage'
+
+export function createFallbackStop(
+  context: SetupWorkerInternalContext,
+): StopHandler {
+  return function stop() {
+    context.fallbackInterceptor?.dispose()
+    printStopMessage({ quiet: context.startOptions?.quiet })
+  }
+}

package/src/browser/setupWorker/stop/createStop.ts

@@ -0,0 +1,29 @@
+import { devUtils } from '~/core/utils/internal/devUtils'
+import { SetupWorkerInternalContext, StopHandler } from '../glossary'
+import { printStopMessage } from './utils/printStopMessage'
+
+export const createStop = (
+  context: SetupWorkerInternalContext,
+): StopHandler => {
+  return function stop() {
+    // Warn developers calling "worker.stop()" more times than necessary.
+    // This likely indicates a mistake in their code.
+    if (!context.isMockingEnabled) {
+      devUtils.warn(
+        'Found a redundant "worker.stop()" call. Note that stopping the worker while mocking already stopped has no effect. Consider removing this "worker.stop()" call.',
+      )
+      return
+    }
+
+    /**
+     * Signal the Service Worker to disable mocking for this client.
+     * Use this an an explicit way to stop the mocking, while preserving
+     * the worker-client relation. Does not affect the worker's lifecycle.
+     */
+    context.workerChannel.send('MOCK_DEACTIVATE')
+    context.isMockingEnabled = false
+    window.clearInterval(context.keepAliveInterval)
+
+    printStopMessage({ quiet: context.startOptions?.quiet })
+  }
+}