msw 2.15.0 → 3.0.0

package/src/ws/websocket-upgrade.ts

@@ -0,0 +1,83 @@
+import { FetchResponse, resolveWebSocketUrl } from '@mswjs/interceptors'
+import { http } from '#http/http'
+import {
+  type Path,
+  type PathParams,
+  matchRequestUrl,
+} from '#core/utils/matching/match-request-url'
+
+const WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+
+export interface WebSocketUpgradeRequestInfo {
+  requestId: string
+  request: Request
+  params: PathParams
+}
+
+/**
+ * Response resolver for the `upgrade` requests to the WebSocket protocol.
+ * This requires a WebSocket handler to be present to fire.
+ * @note This only affects Node.js as the `upgrade` request header is
+ * forbidden and cannot be read in the browser. Consider using the
+ * `WebSocket` API for establishing WebSocket connections in the browser.
+ */
+export async function webSocketUpgrade({
+  request,
+}: WebSocketUpgradeRequestInfo): Promise<Response | undefined> {
+  const key = request.headers.get('sec-websocket-key')
+
+  if (!key) {
+    return
+  }
+
+  const keyBytes = new TextEncoder().encode(key + WEBSOCKET_GUID)
+  const digest = await crypto.subtle.digest('SHA-1', keyBytes)
+  const acceptValue = btoa(String.fromCharCode(...new Uint8Array(digest)))
+
+  // Forward the protocols requested by the client to the intercepted
+  // connection so WebSocket handlers can match on them.
+  const requestedProtocols = request.headers
+    .get('sec-websocket-protocol')
+    ?.split(',')
+    .map((protocol) => protocol.trim())
+
+  new WebSocket(resolveWebSocketUrl(request.url), requestedProtocols)
+
+  const headers = new Headers({
+    upgrade: 'websocket',
+    connection: 'upgrade',
+    'sec-websocket-accept': acceptValue,
+  })
+
+  // Confirm the first requested protocol as the accepted one.
+  // Clients that requested protocols are entitled to fail the
+  // connection if the server confirms none (RFC 6455, section 4.1).
+  if (requestedProtocols && requestedProtocols.length > 0) {
+    headers.set('sec-websocket-protocol', requestedProtocols[0])
+  }
+
+  return new FetchResponse(null, {
+    status: 101,
+    headers,
+  })
+}
+
+/**
+ * Creates a request handler that responds to WebSocket upgrade
+ * requests whose URL matches the given path.
+ *
+ * @internal
+ */
+export function createWebSocketUpgradeHandler(
+  url: Path,
+  resolver: (
+    info: WebSocketUpgradeRequestInfo,
+  ) => Promise<Response | undefined> | Response | undefined,
+) {
+  return http.get(({ request }) => {
+    return (
+      request.headers.get('upgrade')?.toLowerCase() === 'websocket' &&
+      matchRequestUrl(new URL(resolveWebSocketUrl(request.url)), url).matches
+    )
+  }, resolver)
+}

package/src/{core → ws}/ws.test.ts

@@ -1,19 +1,18 @@
-// @vitest-environment node-websocket
 import { ws } from './ws'
 
-it('exports the "link()" method', () => {
+test('exports the "link()" method', () => {
   expect(ws).toHaveProperty('link')
   expect(ws.link).toBeInstanceOf(Function)
 })
 
-it('throws an error when calling "ws.link()" without a URL argument', () => {
+test('throws an error when calling "ws.link()" without a URL argument', () => {
   expect(() =>
     // @ts-expect-error Intentionally invalid call.
     ws.link(),
   ).toThrow('Expected a WebSocket server URL but got undefined')
 })
 
-it('throws an error when given a non-path argument to "ws.link()"', () => {
+test('throws an error when given a non-path argument to "ws.link()"', () => {
   expect(() =>
     // @ts-expect-error Intentionally invalid argument.
     ws.link(2),

package/src/{core → ws}/ws.ts

@@ -1,24 +1,31 @@
 import { invariant } from 'outvariant'
-import { FetchResponse, resolveWebSocketUrl } from '@mswjs/interceptors'
+import type { EventMap } from 'rettime'
 import type {
   WebSocketData,
-  WebSocketClientConnectionProtocol,
+  WebSocketExtension,
+  WebSocketExtensionMessage,
+  WebSocketExtensionApi,
+  WebSocketClientHandle,
 } from '@mswjs/interceptors/WebSocket'
 import {
   WebSocketHandler,
   kEmitter,
+  type AnyWebSocketExtension,
   type WebSocketHandlerEventMap,
-} from './handlers/WebSocketHandler'
-import { hasRefCounted } from './utils/internal/hasRefCounted'
+} from './websocket-handler'
+import { hasRefCounted } from '#core/utils/internal/has-ref-counted'
+import type { UnionToIntersection } from '#core/type-utils'
 import {
   type Path,
   type PathParams,
   isPath,
-  matchRequestUrl,
-} from './utils/matching/matchRequestUrl'
-import { WebSocketClientManager } from './ws/WebSocketClientManager'
-import { http } from './http'
-import { attachSiblingHandlers } from './utils/internal/attachSiblingHandlers'
+} from '#core/utils/matching/match-request-url'
+import { attachSiblingHandlers } from '#core/utils/internal/attach-sibling-handlers'
+import {
+  createWebSocketUpgradeHandler,
+  webSocketUpgrade,
+} from './websocket-upgrade'
+import { WebSocketClientManager } from './websocket-client-manager'
 
 const webSocketChannel = new BroadcastChannel('msw:websocket-client-manager')
 
@@ -30,16 +37,74 @@ if (hasRefCounted(webSocketChannel)) {
 
 export type WebSocketEventListener<
   EventType extends keyof WebSocketHandlerEventMap,
-> = (...args: WebSocketHandlerEventMap[EventType]) => void
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> = EventMap.Listener<WebSocketHandlerEventMap<Extension>, EventType>
+
+type WebSocketExtensions = ReadonlyArray<AnyWebSocketExtension>
+
+/**
+ * The messages and the API of each extension, boxed one extension at a
+ * time. Intersecting the boxes intersects the values of different
+ * extensions only, so a value that is itself a union (e.g. a message
+ * union) stays intact.
+ */
+type BoxedExtension<Extension> = Extension extends unknown
+  ? {
+      message: WebSocketExtensionMessage<Extension>
+      api: WebSocketExtensionApi<Extension>
+    }
+  : never
+
+type MergedExtension<
+  Extension,
+  Fallback extends { message: unknown; api: unknown },
+> = [Extension] extends [never]
+  ? Fallback
+  : UnionToIntersection<BoxedExtension<Extension>>
+
+/**
+ * The extensions of a link merged into a single extension:
+ * the connections speak the messages of every extension, and the
+ * connection event carries the APIs of every extension. A link
+ * without extensions speaks raw WebSocket data.
+ */
+export type WebSocketLinkExtension<Extensions extends WebSocketExtensions> =
+  MergedExtension<
+    Extensions[number],
+    { message: WebSocketData; api: {} }
+  > extends infer Merged extends { message: unknown; api: unknown }
+    ? WebSocketExtension<Merged['message'], Merged['api']>
+    : never
+
+export interface WebSocketLinkOptions<
+  Extensions extends WebSocketExtensions = [],
+> {
+  /**
+   * Extensions applied to every connection intercepted by this link,
+   * left to right. Encoding and decoding happen behind the scenes:
+   * `client.send()`, `server.send()`, `broadcast()`, and the `message`
+   * events all operate on the extensions' messages, and each extension's
+   * own API is exposed on the connection event.
+   *
+   * @example
+   * const chat = ws.link('wss://chat.example.com', { extensions: [new SocketIo()] })
+   * chat.addEventListener('connection', ({ client, rooms }) => {
+   *   client.send({ event: 'greeting', args: ['hello'] })
+   * })
+   */
+  extensions?: Extensions
+}
 
-export type WebSocketLink = {
+export type WebSocketLink<
+  Extension extends AnyWebSocketExtension = WebSocketExtension,
+> = {
   /**
    * A set of all WebSocket clients connected
    * to this link.
    *
    * @see {@link https://mswjs.io/docs/api/ws#clients `clients` API reference}
    */
-  clients: Set<WebSocketClientConnectionProtocol>
+  clients: Set<WebSocketClientHandle<WebSocketExtensionMessage<Extension>>>
 
   /**
    * Adds an event listener to this WebSocket link.
@@ -52,8 +117,8 @@ export type WebSocketLink = {
    */
   addEventListener: <EventType extends keyof WebSocketHandlerEventMap>(
     event: EventType,
-    listener: WebSocketEventListener<EventType>,
-  ) => WebSocketHandler
+    listener: WebSocketEventListener<EventType, Extension>,
+  ) => WebSocketHandler<Extension>
 
   /**
    * Broadcasts the given data to all WebSocket clients.
@@ -66,7 +131,7 @@ export type WebSocketLink = {
    *
    * @see {@link https://mswjs.io/docs/api/ws#broadcastdata `broadcast()` API reference}
    */
-  broadcast: (data: WebSocketData) => void
+  broadcast: (data: WebSocketExtensionMessage<Extension>) => void
 
   /**
    * Broadcasts the given data to all WebSocket clients
@@ -82,9 +147,9 @@ export type WebSocketLink = {
    */
   broadcastExcept: (
     clients:
-      | WebSocketClientConnectionProtocol
-      | Array<WebSocketClientConnectionProtocol>,
-    data: WebSocketData,
+      | WebSocketClientHandle<WebSocketExtensionMessage<Extension>>
+      | Array<WebSocketClientHandle<WebSocketExtensionMessage<Extension>>>,
+    data: WebSocketExtensionMessage<Extension>,
   ) => void
 }
 
@@ -97,7 +162,12 @@ export type WebSocketLink = {
  *   client.send('hello from server!')
  * })
  */
-function createWebSocketLinkHandler(url: Path): WebSocketLink {
+function createWebSocketLinkHandler<
+  const Extensions extends WebSocketExtensions = [],
+>(
+  url: Path,
+  options?: WebSocketLinkOptions<Extensions>,
+): WebSocketLink<WebSocketLinkExtension<Extensions>> {
   invariant(url, 'Expected a WebSocket server URL but got undefined')
 
   invariant(
@@ -106,25 +176,31 @@ function createWebSocketLinkHandler(url: Path): WebSocketLink {
     typeof url,
   )
 
-  const clientManager = new WebSocketClientManager(webSocketChannel)
+  const clientManager = new WebSocketClientManager<
+    WebSocketExtensionMessage<WebSocketLinkExtension<Extensions>>
+  >(webSocketChannel)
 
   // The same upgrade handler instance is attached as a sibling to every
   // WebSocketHandler returned by this link. `groupHandlersByKind` dedupes
   // by reference, so it lands in the `request` bucket exactly once regardless
   // of which subset of WS handlers the user ends up registering.
-  const upgradeHandler = http.get(({ request }) => {
-    return (
-      request.headers.get('upgrade')?.toLowerCase() === 'websocket' &&
-      matchRequestUrl(new URL(resolveWebSocketUrl(request.url)), url).matches
-    )
-  }, ws.onUpgrade)
+  const upgradeHandler = createWebSocketUpgradeHandler(url, (info) => {
+    // Read `ws.onUpgrade` at request time so that overriding it
+    // (e.g. in runtimes with a custom upgrade flow) takes effect
+    // regardless of when the link was created.
+    return ws.onUpgrade(info)
+  })
 
   return {
     get clients() {
       return clientManager.clients
     },
     addEventListener(event, listener) {
-      const webSocketHandler = new WebSocketHandler(url)
+      const webSocketHandler = new WebSocketHandler<
+        WebSocketLinkExtension<Extensions>
+      >(url, {
+        extensions: options?.extensions,
+      })
 
       // Add the connection event listener for when the
       // handler matches and emits a connection event.
@@ -134,8 +210,8 @@ function createWebSocketLinkHandler(url: Path): WebSocketLink {
         await clientManager.addConnection(client)
       })
 
-      // The "handleWebSocketEvent" function will invoke
-      // the "run()" method on the WebSocketHandler.
+      // The WebSocket network frame invokes the "run()" method
+      // on the WebSocketHandler when resolving a connection.
       // If the handler matches, it will emit the "connection"
       // event. Attach the user-defined listener to that event.
       webSocketHandler[kEmitter].on(event, listener)
@@ -164,8 +240,6 @@ function createWebSocketLinkHandler(url: Path): WebSocketLink {
   }
 }
 
-const WEBSOCKET_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
-
 interface WebSocketNamespace {
   link: typeof createWebSocketLinkHandler
   /**
@@ -193,28 +267,7 @@ interface WebSocketNamespace {
  */
 export const ws: WebSocketNamespace = {
   link: createWebSocketLinkHandler,
-  async onUpgrade({ request }) {
-    const key = request.headers.get('sec-websocket-key')
-
-    if (!key) {
-      return
-    }
-
-    const keyBytes = new TextEncoder().encode(key + WEBSOCKET_GUID)
-    const digest = await crypto.subtle.digest('SHA-1', keyBytes)
-    const acceptValue = btoa(String.fromCharCode(...new Uint8Array(digest)))
-
-    new WebSocket(resolveWebSocketUrl(request.url))
-
-    return new FetchResponse(null, {
-      status: 101,
-      headers: {
-        upgrade: 'websocket',
-        connection: 'upgrade',
-        'sec-websocket-accept': acceptValue,
-      },
-    })
-  },
+  onUpgrade: webSocketUpgrade,
 }
 
 export { type WebSocketData }

package/browser/package.json

@@ -1,31 +0,0 @@
-{
-  "type": "module",
-  "main": "../lib/browser/index.js",
-  "module": "../lib/browser/index.mjs",
-  "types": "../lib/browser/index.d.ts",
-  "exports": {
-    ".": {
-      "module-sync": {
-        "types": "./../lib/browser/index.d.mts",
-        "default": "./../lib/browser/index.mjs"
-      },
-      "module": {
-        "types": "./../lib/browser/index.d.mts",
-        "default": "./../lib/browser/index.mjs"
-      },
-      "browser": {
-        "types": "./../lib/browser/index.d.mts",
-        "default": "./../lib/browser/index.mjs"
-      },
-      "import": {
-        "types": "./../lib/browser/index.d.mts",
-        "default": "./../lib/browser/index.mjs"
-      },
-      "default": {
-        "types": "./../lib/browser/index.d.ts",
-        "default": "./../lib/browser/index.js"
-      }
-    },
-    "./package.json": "./package.json"
-  }
-}

package/cli/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}

package/config/package.json

@@ -1,3 +0,0 @@
-{
-  "type": "module"
-}

package/config/scripts/postinstall.js

@@ -1,36 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import { execFileSync } from 'node:child_process'
-
-// When executing the "postinstall" script, the "process.cwd" equals
-// the package directory, not the parent project where the package is installed.
-// NPM stores the parent project directory in the "INIT_CWD" env variable.
-const parentPackageCwd = process.env.INIT_CWD
-
-function postInstall() {
-  const packageJson = JSON.parse(
-    fs.readFileSync(path.resolve(parentPackageCwd, 'package.json'), 'utf8'),
-  )
-
-  if (!packageJson.msw || !packageJson.msw.workerDirectory) {
-    return
-  }
-
-  const cliExecutable = path.resolve(process.cwd(), 'cli/index.js')
-
-  try {
-    /**
-     * @note Call the "init" command directly. It will now copy the worker script
-     * to all saved paths in "msw.workerDirectory"
-     */
-    execFileSync(process.execPath, [cliExecutable, 'init'], {
-      cwd: parentPackageCwd,
-    })
-  } catch (error) {
-    console.error(
-      `[MSW] Failed to automatically update the worker script.\n\n${error}`,
-    )
-  }
-}
-
-postInstall()

package/lib/browser/index.d.mts

@@ -1,112 +0,0 @@
-import { AnyHandler } from "../core/experimental/handlers-controller.mjs";
-import { SharedOptions, LifeCycleEventEmitter } from "../core/sharedOptions.mjs";
-import { HttpNetworkFrameEventMap } from "../core/experimental/frames/http-frame.mjs";
-import { WebSocketNetworkFrameEventMap } from "../core/experimental/frames/websocket-frame.mjs";
-
-type FindWorker = (scriptUrl: string, mockServiceWorkerUrl: string) => boolean;
-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
-     * @deprecated
-     * Please use a proper browser integration instead.
-     * @see https://mswjs.io/docs/integrations/browser
-     */
-    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;
-}
-type StartReturnType = Promise<ServiceWorkerRegistration | undefined>;
-type StopHandler = () => void;
-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 {Array<AnyHandler>} handlers List of runtime request handlers.
-     *
-     * @see {@link https://mswjs.io/docs/api/setup-worker/use `worker.use()` API reference}
-     */
-    use: (...handlers: Array<AnyHandler>) => 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 {Array<AnyHandler>} 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: Array<AnyHandler>) => 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<AnyHandler>;
-    /**
-     * 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<HttpNetworkFrameEventMap & WebSocketNetworkFrameEventMap>;
-}
-
-/**
- * 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}
- */
-declare function setupWorker(...handlers: Array<AnyHandler>): SetupWorker;
-/**
- * @deprecated
- * Please use the `defineNetwork` API instead.
- */
-declare 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();
-}
-
-export { type SetupWorker, SetupWorkerApi, type StartOptions, setupWorker };