msw 2.12.13 → 2.13.0

package/src/browser/setup-worker.ts

@@ -0,0 +1,148 @@
+import { invariant } from 'outvariant'
+import { isNodeProcess } from 'is-node-process'
+import { WebSocketInterceptor } from '@mswjs/interceptors/WebSocket'
+import {
+  defineNetwork,
+  NetworkReadyState,
+} from '#core/experimental/define-network'
+import { type AnyHandler } from '#core/experimental/handlers-controller'
+import { InterceptorSource } from '#core/experimental/sources/interceptor-source'
+import { fromLegacyOnUnhandledRequest } from '#core/experimental/compat'
+import type { LifeCycleEventEmitter } from '#core/sharedOptions'
+import type { HttpNetworkFrameEventMap } from '#core/experimental/frames/http-frame'
+import type { WebSocketNetworkFrameEventMap } from '#core/experimental/frames/websocket-frame'
+import { devUtils } from '#core/utils/internal/devUtils'
+import { supportsServiceWorker } from './utils/supports'
+import { ServiceWorkerSource } from './sources/service-worker-source'
+import { FallbackHttpSource } from './sources/fallback-http-source'
+import type {
+  SetupWorker,
+  StartOptions,
+  StartReturnType,
+  StopHandler,
+} from './glossary'
+
+const DEFAULT_WORKER_URL = '/mockServiceWorker.js'
+
+/**
+ * Sets up a requests interception in the browser with the given request handlers.
+ * @param {Array<AnyHandler>} handlers List of request handlers.
+ *
+ * @see {@link https://mswjs.io/docs/api/setup-worker `setupWorker()` API reference}
+ */
+export function setupWorker(...handlers: Array<AnyHandler>): SetupWorker {
+  invariant(
+    !isNodeProcess(),
+    devUtils.formatMessage(
+      'Failed to execute `setupWorker` in a non-browser environment',
+    ),
+  )
+
+  const network = defineNetwork<
+    Array<ServiceWorkerSource | FallbackHttpSource | InterceptorSource>
+  >({
+    sources: [],
+    handlers,
+  })
+
+  return {
+    async start(options) {
+      if (options?.waitUntilReady != null) {
+        devUtils.warn(
+          `The "waitUntilReady" option has been deprecated. Please remove it from this "worker.start()" call. Follow the recommended Browser integration (https://mswjs.io/docs/integrations/browser) to eliminate any race conditions between the Service Worker registration and any requests made by your application on initial render.`,
+        )
+      }
+
+      /**
+       * @todo @fixme
+       * This is kept for backward-compatibility reasons. We don't really need this check anymore.
+       */
+      if (network.readyState === NetworkReadyState.ENABLED) {
+        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
+      }
+
+      const httpSource = supportsServiceWorker()
+        ? new ServiceWorkerSource({
+            serviceWorker: {
+              url:
+                options?.serviceWorker?.url?.toString() || DEFAULT_WORKER_URL,
+              options: options?.serviceWorker?.options,
+            },
+            findWorker: options?.findWorker,
+            quiet: options?.quiet,
+          })
+        : new FallbackHttpSource({
+            quiet: options?.quiet,
+          })
+
+      network.configure({
+        sources: [
+          httpSource,
+          new InterceptorSource({
+            interceptors: [new WebSocketInterceptor() as any],
+          }),
+        ],
+        onUnhandledFrame: fromLegacyOnUnhandledRequest(() => {
+          return options?.onUnhandledRequest || 'warn'
+        }),
+        context: {
+          quiet: options?.quiet,
+        },
+      })
+
+      await network.enable()
+
+      if (httpSource instanceof ServiceWorkerSource) {
+        const [, registration] = await httpSource.workerPromise
+        return registration
+      }
+    },
+    stop() {
+      if (network.readyState === NetworkReadyState.DISABLED) {
+        devUtils.warn(
+          `Found a redundant "worker.stop()" call. Notice that stopping the worker after it has already been stopped has no effect. Consider removing this "worker.stop()" call.`,
+        )
+        return
+      }
+
+      network.disable()
+      window.postMessage({ type: 'msw/worker:stop' })
+    },
+    events: network.events,
+    use: network.use.bind(network),
+    resetHandlers: network.resetHandlers.bind(network),
+    restoreHandlers: network.restoreHandlers.bind(network),
+    listHandlers: network.listHandlers.bind(network),
+  }
+}
+
+/**
+ * @deprecated
+ * Please use the `defineNetwork` API instead.
+ */
+export class SetupWorkerApi implements SetupWorker {
+  start: (options?: StartOptions) => StartReturnType
+  stop: StopHandler
+  use: (...handlers: Array<AnyHandler>) => void
+  resetHandlers: (...nextHandlers: Array<AnyHandler>) => void
+  restoreHandlers: () => void
+  listHandlers: () => ReadonlyArray<AnyHandler>
+  events: LifeCycleEventEmitter<
+    HttpNetworkFrameEventMap | WebSocketNetworkFrameEventMap
+  >
+
+  constructor() {
+    const worker = setupWorker()
+
+    this.start = worker.start.bind(worker)
+    this.stop = worker.stop.bind(worker)
+    this.use = worker.use.bind(worker)
+    this.resetHandlers = worker.resetHandlers.bind(worker)
+    this.restoreHandlers = worker.restoreHandlers.bind(worker)
+    this.listHandlers = worker.listHandlers.bind(worker)
+    this.events = worker.events
+  }
+}

package/src/browser/sources/fallback-http-source.ts

@@ -0,0 +1,56 @@
+import { FetchInterceptor } from '@mswjs/interceptors/fetch'
+import { XMLHttpRequestInterceptor } from '@mswjs/interceptors/XMLHttpRequest'
+import { InterceptorSource } from '#core/experimental/sources/interceptor-source'
+import { devUtils } from '#core/utils/internal/devUtils'
+
+interface FallbackHttpSourceOptions {
+  quiet?: boolean
+}
+
+export class FallbackHttpSource extends InterceptorSource {
+  constructor(private readonly options: FallbackHttpSourceOptions) {
+    super({
+      interceptors: [new XMLHttpRequestInterceptor(), new FetchInterceptor()],
+    })
+  }
+
+  public enable(): void {
+    super.enable()
+
+    if (!this.options.quiet) {
+      this.#printStartMessage()
+    }
+  }
+
+  public disable(): void {
+    super.disable()
+
+    if (!this.options.quiet) {
+      this.#printStopMessage()
+    }
+  }
+
+  #printStartMessage(): void {
+    console.groupCollapsed(
+      `%c${devUtils.formatMessage('Mocking enabled (fallback mode).')}`,
+      'color:orangered;font-weight:bold;',
+    )
+    // eslint-disable-next-line no-console
+    console.log(
+      '%cDocumentation: %chttps://mswjs.io/docs',
+      'font-weight:bold',
+      'font-weight:normal',
+    )
+    // eslint-disable-next-line no-console
+    console.log('Found an issue? https://github.com/mswjs/msw/issues')
+    console.groupEnd()
+  }
+
+  #printStopMessage(): void {
+    // eslint-disable-next-line no-console
+    console.log(
+      `%c${devUtils.formatMessage('Mocking disabled.')}`,
+      'color:orangered;font-weight:bold;',
+    )
+  }
+}

package/src/browser/sources/service-worker-source.ts

@@ -0,0 +1,455 @@
+import { invariant } from 'outvariant'
+import { Emitter } from 'rettime'
+import { DeferredPromise } from '@open-draft/deferred-promise'
+import { FetchResponse } from '@mswjs/interceptors'
+import { NetworkSource } from '#core/experimental/sources/network-source'
+import { RequestHandler } from '#core/handlers/RequestHandler'
+import {
+  HttpNetworkFrame,
+  ResponseEvent,
+} from '#core/experimental/frames/http-frame'
+import { HttpResponse } from '#core/HttpResponse'
+import { toResponseInit } from '#core/utils/toResponseInit'
+import { devUtils } from '#core/utils/internal/devUtils'
+import {
+  supportsReadableStreamTransfer,
+  supportsServiceWorker,
+} from '../utils/supports'
+import { getWorkerInstance } from '../utils/get-worker-instance'
+import { WorkerChannel, WorkerChannelEventMap } from '../utils/workerChannel'
+import { FindWorker } from '../glossary'
+import { deserializeRequest } from '../utils/deserializeRequest'
+import { validateWorkerScope } from '../utils/validate-worker-scope'
+
+export interface ServiceWorkerSourceOptions {
+  quiet?: boolean
+  serviceWorker: {
+    url: string
+    options?: RegistrationOptions
+  }
+  findWorker?: FindWorker
+}
+
+type WorkerChannelRequestEvent = Emitter.EventType<
+  WorkerChannel,
+  'REQUEST',
+  WorkerChannelEventMap
+>
+
+type WorkerChannelResponseEvent = Emitter.EventType<
+  WorkerChannel,
+  'RESPONSE',
+  WorkerChannelEventMap
+>
+
+type WorkerChannelClient =
+  WorkerChannelEventMap['MOCKING_ENABLED']['data']['client']
+
+export class ServiceWorkerSource extends NetworkSource<ServiceWorkerHttpNetworkFrame> {
+  #frames: Map<string, ServiceWorkerHttpNetworkFrame>
+  #channel: WorkerChannel
+  #clientPromise?: Promise<WorkerChannelClient>
+  #keepAliveInterval?: number
+  #stoppedAt?: number
+
+  public workerPromise: DeferredPromise<
+    [ServiceWorker, ServiceWorkerRegistration]
+  >
+
+  constructor(private readonly options: ServiceWorkerSourceOptions) {
+    super()
+
+    invariant(
+      supportsServiceWorker(),
+      'Failed to use Service Worker as the network source: the Service Worker API is not supported in this environment',
+    )
+
+    this.#frames = new Map()
+    this.workerPromise = new DeferredPromise()
+    this.#channel = new WorkerChannel({
+      worker: this.workerPromise.then(([worker]) => worker),
+    })
+  }
+
+  public async enable(): Promise<ServiceWorkerRegistration> {
+    this.#stoppedAt = undefined
+
+    if (this.workerPromise.state !== 'pending') {
+      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 this.workerPromise.then(([, registration]) => registration)
+    }
+
+    this.#channel.removeAllListeners()
+    const [worker, registration] = await this.#startWorker()
+
+    if (worker.state !== 'activated') {
+      const controller = new AbortController()
+      const activationPromise = new DeferredPromise<void>()
+      activationPromise.then(() => controller.abort())
+
+      worker.addEventListener(
+        'statechange',
+        () => {
+          if (worker.state === 'activated') {
+            activationPromise.resolve()
+          }
+        },
+        { signal: controller.signal },
+      )
+
+      await activationPromise
+    }
+
+    this.#channel.postMessage('MOCK_ACTIVATE')
+
+    const clientConfirmationPromise = new DeferredPromise<WorkerChannelClient>()
+    this.#clientPromise = clientConfirmationPromise
+
+    this.#channel.once('MOCKING_ENABLED', (event) => {
+      clientConfirmationPromise.resolve(event.data.client)
+    })
+    await clientConfirmationPromise
+
+    if (!this.options.quiet) {
+      this.#printStartMessage()
+    }
+
+    return registration
+  }
+
+  public disable(): void {
+    /**
+     * @note Do NOT call `super.disable()` because it removes any "frame" listeners
+     * from this network source, effectively turning it off. The Service Worker source
+     * is a bit special since it might process in-flight requests that have been performed
+     * after it's been disabled.
+     */
+
+    if (typeof this.#stoppedAt !== 'undefined') {
+      devUtils.warn(
+        `Found a redundant "worker.stop()" call. Notice that stopping the worker after it has already been stopped has no effect. Consider removing this "worker.stop()" call.`,
+      )
+
+      return
+    }
+
+    this.#stoppedAt = Date.now()
+    this.#frames.clear()
+    this.workerPromise = new DeferredPromise()
+
+    if (!this.options.quiet) {
+      this.#printStopMessage()
+    }
+  }
+
+  async #startWorker() {
+    if (this.#keepAliveInterval) {
+      clearInterval(this.#keepAliveInterval)
+    }
+
+    const workerUrl = this.options.serviceWorker.url
+
+    const [worker, registration] = await getWorkerInstance(
+      workerUrl,
+      this.options.serviceWorker.options,
+      this.options.findWorker || this.#defaultFindWorker,
+    )
+
+    if (worker == null) {
+      const missingWorkerMessage = this.options?.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
+     `,
+            workerUrl,
+          )
+        : 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`,
+            workerUrl,
+            location.host,
+          )
+
+      throw new Error(missingWorkerMessage)
+    }
+
+    this.workerPromise.resolve([worker, registration])
+
+    this.#channel.on('REQUEST', this.#handleRequest.bind(this))
+    this.#channel.on('RESPONSE', this.#handleResponse.bind(this))
+
+    window.addEventListener('beforeunload', () => {
+      if (worker.state !== 'redundant') {
+        this.#channel.postMessage('CLIENT_CLOSED')
+      }
+
+      clearInterval(this.#keepAliveInterval)
+
+      window.postMessage({ type: 'msw/worker:stop' })
+    })
+
+    await this.#checkWorkerIntegrity().catch((error) => {
+      devUtils.error(
+        'Error while checking the worker script integrity. Please report this on GitHub (https://github.com/mswjs/msw/issues) and include the original error below.',
+      )
+      console.error(error)
+    })
+
+    this.#keepAliveInterval = window.setInterval(() => {
+      this.#channel.postMessage('KEEPALIVE_REQUEST')
+    }, 5000)
+
+    if (!this.options.quiet) {
+      validateWorkerScope(registration)
+    }
+
+    return [worker, registration] as const
+  }
+
+  async #handleRequest(event: WorkerChannelRequestEvent): Promise<void> {
+    if (this.#stoppedAt && event.data.interceptedAt > this.#stoppedAt) {
+      return event.postMessage('PASSTHROUGH')
+    }
+
+    const request = deserializeRequest(event.data)
+    RequestHandler.cache.set(request, request.clone())
+
+    const frame = new ServiceWorkerHttpNetworkFrame({
+      event,
+      request,
+    })
+    this.#frames.set(event.data.id, frame)
+
+    await this.queue(frame)
+  }
+
+  async #handleResponse(event: WorkerChannelResponseEvent): Promise<void> {
+    const { request, response, isMockedResponse } = event.data
+
+    /**
+     * 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 (response.type?.includes('opaque')) {
+      this.#frames.delete(request.id)
+      return
+    }
+
+    const frame = this.#frames.get(request.id)
+    this.#frames.delete(request.id)
+
+    /**
+     * @note A request frame will be missing in case of passthrough after the worker is stopped.
+     * Creating a frame is costly so it's better to handle it as an edge case here.
+     */
+    if (frame == null) {
+      return
+    }
+
+    const fetchRequest = deserializeRequest(request)
+    const fetchResponse =
+      response.status === 0
+        ? Response.error()
+        : new FetchResponse(
+            /**
+             * 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
+             */
+            FetchResponse.isResponseWithBody(response.status)
+              ? response.body
+              : null,
+            {
+              ...response,
+              /**
+               * Set response URL if it's not set already.
+               * @see https://github.com/mswjs/msw/issues/2030
+               * @see https://developer.mozilla.org/en-US/docs/Web/API/Response/url
+               */
+              url: request.url,
+            },
+          )
+
+    frame.events.emit(
+      new ResponseEvent(
+        isMockedResponse ? 'response:mocked' : 'response:bypass',
+        {
+          requestId: frame.data.id,
+          request: fetchRequest,
+          response: fetchResponse,
+          isMockedResponse,
+        },
+      ),
+    )
+  }
+
+  #defaultFindWorker: FindWorker = (workerUrl, mockServiceWorkerUrl) => {
+    return workerUrl === mockServiceWorkerUrl
+  }
+
+  async #checkWorkerIntegrity(): Promise<void> {
+    const integrityCheckPromise = new DeferredPromise<void>()
+
+    this.#channel.postMessage('INTEGRITY_CHECK_REQUEST')
+    this.#channel.once('INTEGRITY_CHECK_RESPONSE', (event) => {
+      const { checksum, packageVersion } = event.data
+
+      // Compare the response from the Service Worker and the
+      // global variable set during the build.
+
+      // The integrity is validated based on the worker script's checksum
+      // that's derived from its minified content during the build.
+      // The "SERVICE_WORKER_CHECKSUM" global variable is injected by the build.
+      if (checksum !== SERVICE_WORKER_CHECKSUM) {
+        devUtils.warn(
+          `The currently registered Service Worker has been generated by a different version of MSW (${packageVersion}) and may not be fully compatible with the installed version.
+
+It's recommended you update your worker script by running this command:
+
+  \u2022 npx msw init <PUBLIC_DIR>
+
+You can also automate this process and make the worker script update automatically upon the library installations. Read more: https://mswjs.io/docs/cli/init.`,
+        )
+      }
+
+      integrityCheckPromise.resolve()
+    })
+
+    return integrityCheckPromise
+  }
+
+  async #printStartMessage() {
+    if (this.workerPromise.state === 'rejected') {
+      return
+    }
+
+    invariant(
+      this.#clientPromise != null,
+      '[ServiceWorkerSource] Failed to print a start message: client confirmation not received',
+    )
+
+    const client = await this.#clientPromise
+    const [worker, registration] = await this.workerPromise
+
+    console.groupCollapsed(
+      `%c${devUtils.formatMessage('Mocking enabled.')}`,
+      'color:orangered;font-weight:bold;',
+    )
+    // eslint-disable-next-line no-console
+    console.log(
+      '%cDocumentation: %chttps://mswjs.io/docs',
+      'font-weight:bold',
+      'font-weight:normal',
+    )
+    // eslint-disable-next-line no-console
+    console.log('Found an issue? https://github.com/mswjs/msw/issues')
+
+    // eslint-disable-next-line no-console
+    console.log('Worker script URL:', worker.scriptURL)
+
+    // eslint-disable-next-line no-console
+    console.log('Worker scope:', registration.scope)
+
+    if (client) {
+      // eslint-disable-next-line no-console
+      console.log('Client ID: %s (%s)', client.id, client.frameType)
+    }
+
+    console.groupEnd()
+  }
+
+  #printStopMessage(): void {
+    // eslint-disable-next-line no-console
+    console.log(
+      `%c${devUtils.formatMessage('Mocking disabled.')}`,
+      'color:orangered;font-weight:bold;',
+    )
+  }
+}
+
+class ServiceWorkerHttpNetworkFrame extends HttpNetworkFrame {
+  #event: WorkerChannelRequestEvent
+
+  constructor(options: { event: WorkerChannelRequestEvent; request: Request }) {
+    super({ request: options.request })
+    this.#event = options.event
+  }
+
+  public passthrough(): void {
+    this.#event.postMessage('PASSTHROUGH')
+  }
+
+  public respondWith(response?: Response): void {
+    if (response) {
+      this.#respondWith(response)
+    }
+  }
+
+  public errorWith(reason?: unknown): void {
+    if (reason instanceof Response) {
+      return this.respondWith(reason)
+    }
+
+    devUtils.warn(
+      `Uncaught exception in the request handler for "%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/http/mocking-responses/error-responses`,
+      this.data.request.method,
+      this.data.request.url,
+    )
+
+    const error =
+      reason instanceof Error
+        ? reason
+        : new Error(reason?.toString() || 'Request failure')
+
+    // Treat exceptions during the request handling as 500 responses.
+    // This should alert the developer that there's a problem.
+    this.respondWith(
+      HttpResponse.json(
+        {
+          name: error.name,
+          message: error.message,
+          stack: error.stack,
+        },
+        {
+          status: 500,
+          statusText: 'Request Handler Error',
+        },
+      ),
+    )
+  }
+
+  async #respondWith(response: Response): Promise<void> {
+    let responseBody: ReadableStream<Uint8Array> | ArrayBuffer | null
+    let transfer: [ReadableStream<Uint8Array>] | undefined
+    const responseInit = toResponseInit(response)
+
+    if (supportsReadableStreamTransfer()) {
+      responseBody = response.body
+      transfer = response.body == null ? undefined : [response.body]
+    } else {
+      responseBody =
+        response.body == null ? null : await response.clone().arrayBuffer()
+    }
+
+    this.#event.postMessage(
+      'MOCK_RESPONSE',
+      {
+        ...responseInit,
+        body: responseBody,
+      },
+      transfer,
+    )
+  }
+}

package/src/browser/tsconfig.browser.json

@@ -1,9 +1,14 @@
 {
   "extends": "../tsconfig.src.json",
+  "include": ["../../global.d.ts", "./global.browser.d.ts", "./**/*.ts"],
+  "references": [
+    {
+      "path": "../tsconfig.core.json"
+    }
+  ],
   "compilerOptions": {
     // Expose browser-specific libraries only for the
     // source code under the "src/browser" directory.
     "lib": ["DOM", "WebWorker", "DOM.Iterable"]
-  },
-  "include": ["../../global.d.ts", "./global.browser.d.ts", "./**/*.ts"]
+  }
 }

package/src/browser/utils/deserializeRequest.ts

@@ -1,5 +1,5 @@
 import { pruneGetRequestBody } from './pruneGetRequestBody'
-import type { ServiceWorkerIncomingRequest } from '../setupWorker/glossary'
+import type { ServiceWorkerIncomingRequest } from '../glossary'
 
 /**
  * Converts a given request received from the Service Worker

package/src/browser/{setupWorker/start/utils/getWorkerByRegistration.ts → utils/get-worker-by-registration.ts}

@@ -1,4 +1,4 @@
-import { FindWorker } from '../../glossary'
+import type { FindWorker } from '../glossary'
 
 /**
  * Attempts to resolve a Service Worker instance from a given registration,
@@ -14,9 +14,11 @@ export function getWorkerByRegistration(
     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)
   })