@depup/msw 2.12.13-depup.0

package/src/core/handlers/WebSocketHandler.test.ts

@@ -0,0 +1,127 @@
+import { WebSocketHandler } from './WebSocketHandler'
+
+describe('parse', () => {
+  it('matches an exact url', () => {
+    expect(
+      new WebSocketHandler('ws://localhost:3000').parse({
+        url: new URL('ws://localhost:3000'),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+  })
+
+  it('ignores trailing slash', () => {
+    expect(
+      new WebSocketHandler('ws://localhost:3000').parse({
+        url: new URL('ws://localhost:3000/'),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+
+    expect(
+      new WebSocketHandler('ws://localhost:3000/').parse({
+        url: new URL('ws://localhost:3000/'),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+  })
+
+  it('supports path parameters', () => {
+    expect(
+      new WebSocketHandler('ws://localhost:3000/:serviceName').parse({
+        url: new URL('ws://localhost:3000/auth'),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {
+          serviceName: 'auth',
+        },
+      },
+    })
+  })
+
+  it('ignores "/socket.io/" prefix in the client url', () => {
+    expect(
+      new WebSocketHandler('ws://localhost:3000').parse({
+        url: new URL(
+          'ws://localhost:3000/socket.io/?EIO=4&transport=websocket',
+        ),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+
+    expect(
+      new WebSocketHandler('ws://localhost:3000/non-matching').parse({
+        url: new URL(
+          'ws://localhost:3000/socket.io/?EIO=4&transport=websocket',
+        ),
+      }),
+    ).toEqual({
+      match: {
+        matches: false,
+        params: {},
+      },
+    })
+  })
+
+  it('preserves non-prefix "/socket.io/" path segment', () => {
+    /**
+     * @note It is highly unlikely but we still shouldn't modify the
+     * WebSocket client URL if it contains a user-defined "socket.io" segment.
+     */
+    expect(
+      new WebSocketHandler('ws://localhost:3000/clients/socket.io/123').parse({
+        url: new URL('ws://localhost:3000/clients/socket.io/123'),
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+
+    expect(
+      new WebSocketHandler('ws://localhost:3000').parse({
+        url: new URL('ws://localhost:3000/clients/socket.io/123'),
+      }),
+    ).toEqual({
+      match: {
+        matches: false,
+        params: {},
+      },
+    })
+  })
+
+  it('supports a custom resolution context (base url)', () => {
+    expect(
+      new WebSocketHandler('/api/ws').parse({
+        url: new URL('ws://localhost:3000/api/ws'),
+        resolutionContext: {
+          baseUrl: 'ws://localhost:3000/',
+        },
+      }),
+    ).toEqual({
+      match: {
+        matches: true,
+        params: {},
+      },
+    })
+  })
+})

package/src/core/handlers/WebSocketHandler.ts

@@ -0,0 +1,209 @@
+import { Emitter } from 'strict-event-emitter'
+import { createRequestId, resolveWebSocketUrl } from '@mswjs/interceptors'
+import type {
+  WebSocketClientConnectionProtocol,
+  WebSocketConnectionData,
+  WebSocketServerConnectionProtocol,
+} from '@mswjs/interceptors/WebSocket'
+import {
+  type Match,
+  type Path,
+  type PathParams,
+  matchRequestUrl,
+} from '../utils/matching/matchRequestUrl'
+import { getCallFrame } from '../utils/internal/getCallFrame'
+import type { HandlerKind } from './common'
+
+type WebSocketHandlerParsedResult = {
+  match: Match
+}
+
+export type WebSocketHandlerEventMap = {
+  connection: [args: WebSocketHandlerConnection]
+}
+
+export interface WebSocketHandlerConnection {
+  client: WebSocketClientConnectionProtocol
+  server: WebSocketServerConnectionProtocol
+  info: WebSocketConnectionData['info']
+  params: PathParams
+}
+
+export interface WebSocketResolutionContext {
+  baseUrl?: string
+}
+
+export const kEmitter = Symbol('kEmitter')
+export const kSender = Symbol('kSender')
+const kStopPropagationPatched = Symbol('kStopPropagationPatched')
+const KOnStopPropagation = Symbol('KOnStopPropagation')
+
+export class WebSocketHandler {
+  private readonly __kind: HandlerKind
+
+  public id: string
+  public callFrame?: string
+
+  protected [kEmitter]: Emitter<WebSocketHandlerEventMap>
+
+  constructor(protected readonly url: Path) {
+    this.id = createRequestId()
+
+    this[kEmitter] = new Emitter()
+    this.callFrame = getCallFrame(new Error())
+    this.__kind = 'EventHandler'
+  }
+
+  public parse(args: {
+    url: URL
+    resolutionContext?: WebSocketResolutionContext
+  }): WebSocketHandlerParsedResult {
+    const clientUrl = new URL(args.url)
+
+    // Resolve the WebSocket handler path:
+    // - Plain string URLs resolved as per the specification (via Interceptors).
+    // - String URLs starting with a wildcard are preserved (prepending a scheme there will break them).
+    // - RegExp paths are preserved.
+    const resolvedHandlerUrl =
+      this.url instanceof RegExp || this.url.startsWith('*')
+        ? this.url
+        : this.#resolveWebSocketUrl(this.url, args.resolutionContext?.baseUrl)
+
+    /**
+     * @note Remove the Socket.IO path prefix from the WebSocket
+     * client URL. This is an exception to keep the users from
+     * including the implementation details in their handlers.
+     */
+    clientUrl.pathname = clientUrl.pathname.replace(/^\/socket.io\//, '/')
+
+    const match = matchRequestUrl(
+      clientUrl,
+      resolvedHandlerUrl,
+      args.resolutionContext?.baseUrl,
+    )
+
+    return {
+      match,
+    }
+  }
+
+  public predicate(args: {
+    url: URL
+    parsedResult: WebSocketHandlerParsedResult
+  }): boolean {
+    return args.parsedResult.match.matches
+  }
+
+  public async run(
+    connection: Omit<WebSocketHandlerConnection, 'params'>,
+    resolutionContext?: WebSocketResolutionContext,
+  ): Promise<boolean> {
+    const parsedResult = this.parse({
+      url: connection.client.url,
+      resolutionContext,
+    })
+
+    if (!this.predicate({ url: connection.client.url, parsedResult })) {
+      return false
+    }
+
+    const resolvedConnection: WebSocketHandlerConnection = {
+      ...connection,
+      params: parsedResult.match.params || {},
+    }
+
+    return this.connect(resolvedConnection)
+  }
+
+  protected connect(connection: WebSocketHandlerConnection): boolean {
+    // Support `event.stopPropagation()` for various client/server events.
+    connection.client.addEventListener(
+      'message',
+      createStopPropagationListener(this),
+    )
+    connection.client.addEventListener(
+      'close',
+      createStopPropagationListener(this),
+    )
+
+    connection.server.addEventListener(
+      'open',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'message',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'error',
+      createStopPropagationListener(this),
+    )
+    connection.server.addEventListener(
+      'close',
+      createStopPropagationListener(this),
+    )
+
+    // Emit the connection event on the handler.
+    // This is what the developer adds listeners for.
+    return this[kEmitter].emit('connection', connection)
+  }
+
+  #resolveWebSocketUrl(url: string, baseUrl?: string): string {
+    const resolvedUrl = resolveWebSocketUrl(
+      baseUrl
+        ? /**
+           * @note Resolve against the base URL preemtively because `resolveWebSocketUrl` only
+           * resolves against `location.href`, which is missing in Node.js. Base URL allows
+           * the handler to accept a relative URL in Node.js.
+           */
+          new URL(url, baseUrl)
+        : url,
+    )
+
+    /**
+     * @note Omit the trailing slash.
+     * While the browser always produces a trailing slash at the end of a WebSocket URL,
+     * having it in as the handler's predicate would mean it is *required* in the actual URL.
+     */
+    return resolvedUrl.replace(/\/$/, '')
+  }
+}
+
+function createStopPropagationListener(handler: WebSocketHandler) {
+  return function stopPropagationListener(event: Event) {
+    const propagationStoppedAt = Reflect.get(event, 'kPropagationStoppedAt') as
+      | string
+      | undefined
+
+    if (propagationStoppedAt && handler.id !== propagationStoppedAt) {
+      event.stopImmediatePropagation()
+      return
+    }
+
+    Object.defineProperty(event, KOnStopPropagation, {
+      value(this: WebSocketHandler) {
+        Object.defineProperty(event, 'kPropagationStoppedAt', {
+          value: handler.id,
+        })
+      },
+      configurable: true,
+    })
+
+    // Since the same event instance is shared between all client/server objects,
+    // make sure to patch its `stopPropagation` method only once.
+    if (!Reflect.get(event, kStopPropagationPatched)) {
+      event.stopPropagation = new Proxy(event.stopPropagation, {
+        apply: (target, thisArg, args) => {
+          Reflect.get(event, KOnStopPropagation)?.call(handler)
+          return Reflect.apply(target, thisArg, args)
+        },
+      })
+
+      Object.defineProperty(event, kStopPropagationPatched, {
+        value: true,
+        // If something else attempts to redefine this, throw.
+        configurable: false,
+      })
+    }
+  }
+}

package/src/core/handlers/common.ts

@@ -0,0 +1 @@
+export type HandlerKind = 'RequestHandler' | 'EventHandler'

package/src/core/http.test.ts

@@ -0,0 +1,15 @@
+import { http } from './http'
+
+test('exports all REST API methods', () => {
+  expect(http).toBeDefined()
+  expect(Object.keys(http)).toEqual([
+    'all',
+    'head',
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+    'options',
+  ])
+})

package/src/core/http.ts

@@ -0,0 +1,64 @@
+import {
+  DefaultBodyType,
+  RequestHandlerOptions,
+  ResponseResolver,
+} from './handlers/RequestHandler'
+import {
+  HttpMethods,
+  HttpHandler,
+  HttpRequestResolverExtras,
+  HttpRequestPredicate,
+} from './handlers/HttpHandler'
+import type { PathParams } from './utils/matching/matchRequestUrl'
+
+export type HttpRequestHandler = <
+  Params extends PathParams<keyof Params> = PathParams,
+  RequestBodyType extends DefaultBodyType = DefaultBodyType,
+  // Response body type MUST be undefined by default.
+  // This is how we can distinguish between a handler that
+  // returns plain "Response" and the one returning "HttpResponse"
+  // to enforce a stricter response body type.
+  ResponseBodyType extends DefaultBodyType = undefined,
+>(
+  predicate: HttpRequestPredicate<Params>,
+  resolver: HttpResponseResolver<Params, RequestBodyType, ResponseBodyType>,
+  options?: RequestHandlerOptions,
+) => HttpHandler
+
+export type HttpResponseResolver<
+  Params extends PathParams<keyof Params> = PathParams,
+  RequestBodyType extends DefaultBodyType = DefaultBodyType,
+  ResponseBodyType extends DefaultBodyType = DefaultBodyType,
+> = ResponseResolver<
+  HttpRequestResolverExtras<Params>,
+  RequestBodyType,
+  ResponseBodyType
+>
+
+function createHttpHandler<Method extends HttpMethods | RegExp>(
+  method: Method,
+): HttpRequestHandler {
+  return (predicate, resolver, options = {}) => {
+    return new HttpHandler(method, predicate, resolver, options)
+  }
+}
+
+/**
+ * A namespace to intercept and mock HTTP requests.
+ *
+ * @example
+ * http.get('/user', resolver)
+ * http.post('/post/:id', resolver)
+ *
+ * @see {@link https://mswjs.io/docs/api/http `http` API reference}
+ */
+export const http = {
+  all: createHttpHandler(/.+/),
+  head: createHttpHandler(HttpMethods.HEAD),
+  get: createHttpHandler(HttpMethods.GET),
+  post: createHttpHandler(HttpMethods.POST),
+  put: createHttpHandler(HttpMethods.PUT),
+  delete: createHttpHandler(HttpMethods.DELETE),
+  patch: createHttpHandler(HttpMethods.PATCH),
+  options: createHttpHandler(HttpMethods.OPTIONS),
+}

package/src/core/index.ts

@@ -0,0 +1,110 @@
+import { checkGlobals } from './utils/internal/checkGlobals'
+
+export { SetupApi } from './SetupApi'
+
+/* HTTP handlers */
+export { RequestHandler } from './handlers/RequestHandler'
+export { http } from './http'
+export { HttpHandler, HttpMethods } from './handlers/HttpHandler'
+export { graphql } from './graphql'
+export { GraphQLHandler } from './handlers/GraphQLHandler'
+
+/* WebSocket handler */
+export { ws, type WebSocketLink } from './ws'
+export {
+  WebSocketHandler,
+  type WebSocketHandlerEventMap,
+  type WebSocketHandlerConnection,
+} from './handlers/WebSocketHandler'
+
+/* Server-Sent Events */
+export {
+  sse,
+  type ServerSentEventRequestHandler,
+  type ServerSentEventResolver,
+  type ServerSentEventResolverExtras,
+  type ServerSentEventMessage,
+} from './sse'
+
+import type { HttpHandler } from './handlers/HttpHandler'
+import type { GraphQLHandler } from './handlers/GraphQLHandler'
+import type { WebSocketHandler } from './handlers/WebSocketHandler'
+
+export type AnyHandler = HttpHandler | GraphQLHandler | WebSocketHandler
+
+/* Utils */
+export { matchRequestUrl } from './utils/matching/matchRequestUrl'
+export { handleRequest, type HandleRequestOptions } from './utils/handleRequest'
+export {
+  onUnhandledRequest,
+  type UnhandledRequestStrategy,
+  type UnhandledRequestCallback,
+} from './utils/request/onUnhandledRequest'
+export { getResponse } from './getResponse'
+export { cleanUrl } from './utils/url/cleanUrl'
+
+/**
+ * Type definitions.
+ */
+
+export type { SharedOptions, LifeCycleEventsMap } from './sharedOptions'
+
+export type {
+  ResponseResolver,
+  ResponseResolverReturnType,
+  AsyncResponseResolverReturnType,
+  RequestHandlerOptions,
+  DefaultBodyType,
+  DefaultRequestMultipartBody,
+  JsonBodyType,
+  ResponseResolverInfo,
+} from './handlers/RequestHandler'
+
+export type {
+  RequestQuery,
+  HttpRequestParsedResult,
+  HttpHandlerInfo,
+  HttpRequestResolverExtras,
+  HttpHandlerMethod,
+  HttpCustomPredicate,
+} from './handlers/HttpHandler'
+export type { HttpRequestHandler, HttpResponseResolver } from './http'
+
+export type {
+  GraphQLQuery,
+  GraphQLVariables,
+  GraphQLRequestBody,
+  GraphQLResponseBody,
+  GraphQLJsonRequestBody,
+  GraphQLOperationType,
+  GraphQLCustomPredicate,
+} from './handlers/GraphQLHandler'
+export type {
+  GraphQLRequestHandler,
+  GraphQLOperationHandler,
+  GraphQLResponseResolver,
+  GraphQLLinkHandlers,
+} from './graphql'
+
+export type { WebSocketData, WebSocketEventListener } from './ws'
+
+export type { Path, PathParams, Match } from './utils/matching/matchRequestUrl'
+export type { ParsedGraphQLRequest } from './utils/internal/parseGraphQLRequest'
+export type { ResponseResolutionContext } from './utils/executeHandlers'
+
+export {
+  HttpResponse,
+  type HttpResponseInit,
+  type StrictRequest,
+  type StrictResponse,
+} from './HttpResponse'
+export { delay, type DelayMode } from './delay'
+export { bypass } from './bypass'
+export { passthrough } from './passthrough'
+export { isCommonAssetRequest } from './isCommonAssetRequest'
+
+// Validate environmental globals before executing any code.
+// This ensures that the library gives user-friendly errors
+// when ran in the environments that require additional polyfills
+// from the end user.
+checkGlobals()

package/src/core/isCommonAssetRequest.ts

@@ -0,0 +1,45 @@
+/**
+ * Determines if the given request is a static asset request.
+ * Useful when deciding which unhandled requests to ignore.
+ * @note Despite being ignored, you can still intercept and mock
+ * static assets by creating request handlers for them.
+ *
+ * @example
+ * import { isCommonAssetRequest } from 'msw'
+ *
+ * await worker.start({
+ *   onUnhandledRequest(request, print) {
+ *     if (!isCommonAssetRequest(request)) {
+ *       print.warning()
+ *     }
+ *   }
+ * })
+ */
+export function isCommonAssetRequest(request: Request): boolean {
+  const url = new URL(request.url)
+
+  // Ignore certain protocols.
+  if (url.protocol === 'file:') {
+    return true
+  }
+
+  // Ignore static assets hosts.
+  if (/(fonts\.googleapis\.com)/.test(url.hostname)) {
+    return true
+  }
+
+  // Ignore node modules served over HTTP.
+  if (/node_modules/.test(url.pathname)) {
+    return true
+  }
+
+  // Ignore internal Vite requests, like "/@vite/client".
+  if (url.pathname.includes('@vite')) {
+    return true
+  }
+
+  // Ignore common static assets.
+  return /\.(s?css|less|m?jsx?|m?tsx?|html|ttf|otf|woff|woff2|eot|gif|jpe?g|png|avif|webp|svg|mp4|webm|ogg|mov|mp3|wav|ogg|flac|aac|pdf|txt|csv|json|xml|md|zip|tar|gz|rar|7z)$/i.test(
+    url.pathname,
+  )
+}

package/src/core/passthrough.test.ts

@@ -0,0 +1,11 @@
+// @vitest-environment node
+import { passthrough } from './passthrough'
+
+it('creates a 302 response with the intention header', () => {
+  const response = passthrough()
+
+  expect(response).toBeInstanceOf(Response)
+  expect(response.status).toBe(302)
+  expect(response.statusText).toBe('Passthrough')
+  expect(response.headers.get('x-msw-intention')).toBe('passthrough')
+})

package/src/core/passthrough.ts

@@ -0,0 +1,25 @@
+import type { HttpResponse } from './HttpResponse'
+
+/**
+ * Performs the intercepted request as-is.
+ *
+ * This stops request handler lookup so no other handlers
+ * can affect this request past this point.
+ * Unlike `bypass()`, this will not trigger an additional request.
+ *
+ * @example
+ * http.get('/resource', () => {
+ *   return passthrough()
+ * })
+ *
+ * @see {@link https://mswjs.io/docs/api/passthrough `passthrough()` API reference}
+ */
+export function passthrough(): HttpResponse<any> {
+  return new Response(null, {
+    status: 302,
+    statusText: 'Passthrough',
+    headers: {
+      'x-msw-intention': 'passthrough',
+    },
+  }) as HttpResponse<any>
+}

package/src/core/sharedOptions.ts

@@ -0,0 +1,66 @@
+import type { Emitter } from 'strict-event-emitter'
+import type { UnhandledRequestStrategy } from './utils/request/onUnhandledRequest'
+
+export interface SharedOptions {
+  /**
+   * Specifies how to react to a request that has no corresponding
+   * request handler. Warns on unhandled requests by default.
+   *
+   * @example worker.start({ onUnhandledRequest: 'bypass' })
+   * @example worker.start({ onUnhandledRequest: 'warn' })
+   * @example server.listen({ onUnhandledRequest: 'error' })
+   */
+  onUnhandledRequest?: UnhandledRequestStrategy
+}
+
+export type LifeCycleEventsMap = {
+  'request:start': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:match': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:unhandled': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'request:end': [
+    args: {
+      request: Request
+      requestId: string
+    },
+  ]
+  'response:mocked': [
+    args: {
+      response: Response
+      request: Request
+      requestId: string
+    },
+  ]
+  'response:bypass': [
+    args: {
+      response: Response
+      request: Request
+      requestId: string
+    },
+  ]
+  unhandledException: [
+    args: {
+      error: Error
+      request: Request
+      requestId: string
+    },
+  ]
+}
+
+export type LifeCycleEventEmitter<
+  EventsMap extends Record<string | symbol, any>,
+> = Pick<Emitter<EventsMap>, 'on' | 'removeListener' | 'removeAllListeners'>