@mswjs/interceptors 0.39.8 → 0.41.0

package/src/RequestController.ts

@@ -1,35 +1,59 @@
-import { invariant } from 'outvariant'
 import { DeferredPromise } from '@open-draft/deferred-promise'
+import { invariant } from 'outvariant'
 import { InterceptorError } from './InterceptorError'
 
-const kRequestHandled = Symbol('kRequestHandled')
-export const kResponsePromise = Symbol('kResponsePromise')
+export interface RequestControllerSource {
+  passthrough(): void
+  respondWith(response: Response): void
+  errorWith(reason?: unknown): void
+}
 
 export class RequestController {
+  static PENDING = 0 as const
+  static PASSTHROUGH = 1 as const
+  static RESPONSE = 2 as const
+  static ERROR = 3 as const
+
+  public readyState: number
+
   /**
-   * Internal response promise.
-   * Available only for the library internals to grab the
-   * response instance provided by the developer.
-   * @note This promise cannot be rejected. It's either infinitely
-   * pending or resolved with whichever Response was passed to `respondWith()`.
+   * A Promise that resolves when this controller handles a request.
+   * See `controller.readyState` for more information on the handling result.
    */
-  [kResponsePromise]: DeferredPromise<
-    Response | Record<string, any> | undefined
-  >;
+  public handled: Promise<void>
+
+  constructor(
+    protected readonly request: Request,
+    protected readonly source: RequestControllerSource
+  ) {
+    this.readyState = RequestController.PENDING
+    this.handled = new DeferredPromise<void>()
+  }
+
+  get #handled() {
+    return this.handled as DeferredPromise<void>
+  }
 
   /**
-   * Internal flag indicating if this request has been handled.
-   * @note The response promise becomes "fulfilled" on the next tick.
+   * Perform this request as-is.
    */
-  [kRequestHandled]: boolean
+  public async passthrough(): Promise<void> {
+    invariant.as(
+      InterceptorError,
+      this.readyState === RequestController.PENDING,
+      'Failed to passthrough the "%s %s" request: the request has already been handled',
+      this.request.method,
+      this.request.url
+    )
 
-  constructor(private request: Request) {
-    this[kRequestHandled] = false
-    this[kResponsePromise] = new DeferredPromise()
+    this.readyState = RequestController.PASSTHROUGH
+    await this.source.passthrough()
+    this.#handled.resolve()
   }
 
   /**
    * Respond to this request with the given `Response` instance.
+   *
    * @example
    * controller.respondWith(new Response())
    * controller.respondWith(Response.json({ id }))
@@ -38,22 +62,25 @@ export class RequestController {
   public respondWith(response: Response): void {
     invariant.as(
       InterceptorError,
-      !this[kRequestHandled],
-      'Failed to respond to the "%s %s" request: the "request" event has already been handled.',
+      this.readyState === RequestController.PENDING,
+      'Failed to respond to the "%s %s" request with "%d %s": the request has already been handled (%d)',
       this.request.method,
-      this.request.url
+      this.request.url,
+      response.status,
+      response.statusText || 'OK',
+      this.readyState
     )
 
-    this[kRequestHandled] = true
-    this[kResponsePromise].resolve(response)
+    this.readyState = RequestController.RESPONSE
+    this.#handled.resolve()
 
     /**
-     * @note The request controller doesn't do anything
-     * apart from letting the interceptor await the response
-     * provided by the developer through the response promise.
-     * Each interceptor implements the actual respondWith/errorWith
-     * logic based on that interceptor's needs.
+     * @note Although `source.respondWith()` is potentially asynchronous,
+     * do NOT await it for backward-compatibility. Awaiting it will short-circuit
+     * the request listener invocation as soon as a listener responds to a request.
+     * Ideally, that's what we want, but that's not what we promise the user.
      */
+    this.source.respondWith(response)
   }
 
   /**
@@ -64,22 +91,19 @@ export class RequestController {
    * controller.errorWith(new Error('Oops!'))
    * controller.errorWith({ message: 'Oops!'})
    */
-  public errorWith(reason?: Error | Record<string, any>): void {
+  public errorWith(reason?: unknown): void {
     invariant.as(
       InterceptorError,
-      !this[kRequestHandled],
-      'Failed to error the "%s %s" request: the "request" event has already been handled.',
+      this.readyState === RequestController.PENDING,
+      'Failed to error the "%s %s" request with "%s": the request has already been handled (%d)',
       this.request.method,
-      this.request.url
+      this.request.url,
+      reason?.toString(),
+      this.readyState
     )
 
-    this[kRequestHandled] = true
-
-    /**
-     * @note Resolve the response promise, not reject.
-     * This helps us differentiate between unhandled exceptions
-     * and intended errors ("errorWith") while waiting for the response.
-     */
-    this[kResponsePromise].resolve(reason)
+    this.readyState = RequestController.ERROR
+    this.source.errorWith(reason)
+    this.#handled.resolve()
   }
 }

package/src/index.ts

@@ -1,6 +1,10 @@
 export * from './glossary'
 export * from './Interceptor'
 export * from './BatchInterceptor'
+export {
+  RequestController,
+  type RequestControllerSource,
+} from './RequestController'
 
 /* Utils */
 export { createRequestId } from './createRequestId'

package/src/interceptors/ClientRequest/MockHttpSocket.ts

@@ -13,12 +13,12 @@ import { MockSocket } from '../Socket/MockSocket'
 import type { NormalizedSocketWriteArgs } from '../Socket/utils/normalizeSocketWriteArgs'
 import { isPropertyAccessible } from '../../utils/isPropertyAccessible'
 import { baseUrlFromConnectionOptions } from '../Socket/utils/baseUrlFromConnectionOptions'
-import { createServerErrorResponse } from '../../utils/responseUtils'
 import { createRequestId } from '../../createRequestId'
 import { getRawFetchHeaders } from './utils/recordRawHeaders'
 import { FetchResponse } from '../../utils/fetchUtils'
 import { setRawRequest } from '../../getRawRequest'
 import { setRawRequestBodyStream } from '../../utils/node'
+import { freeParser } from './utils/parserUtils'
 
 type HttpConnectionOptions = any
 
@@ -136,7 +136,7 @@ export class MockHttpSocket extends MockSocket {
 
     // Once the socket is finished, nothing can write to it
     // anymore. It has also flushed any buffered chunks.
-    this.once('finish', () => this.requestParser.free())
+    this.once('finish', () => freeParser(this.requestParser, this))
 
     if (this.baseUrl.protocol === 'https:') {
       Reflect.set(this, 'encrypted', true)
@@ -146,6 +146,11 @@ export class MockHttpSocket extends MockSocket {
       Reflect.set(this, 'getProtocol', () => 'TLSv1.3')
       Reflect.set(this, 'getSession', () => undefined)
       Reflect.set(this, 'isSessionReused', () => false)
+      Reflect.set(this, 'getCipher', () => ({
+        name: 'AES256-SHA',
+        standardName: 'TLS_RSA_WITH_AES_256_CBC_SHA',
+        version: 'TLSv1.3',
+      }))
     }
   }
 
@@ -164,7 +169,7 @@ export class MockHttpSocket extends MockSocket {
     // Destroy the response parser when the socket gets destroyed.
     // Normally, we should listen to the "close" event but it
     // can be suppressed by using the "emitClose: false" option.
-    this.responseParser.free()
+    freeParser(this.responseParser, this)
 
     if (error) {
       this.emit('error', error)
@@ -201,9 +206,18 @@ export class MockHttpSocket extends MockSocket {
       })
     }
 
-    // If the developer destroys the socket, destroy the original connection.
-    this.once('error', (error) => {
-      socket.destroy(error)
+    // The client-facing socket can be destroyed in two ways:
+    // 1. The developer destroys the socket.
+    // 2. The passthrough socket "close" is forwarded to the socket.
+    this.once('close', () => {
+      socket.removeAllListeners()
+
+      // If the closure didn't originate from the passthrough socket, destroy it.
+      if (!socket.destroyed) {
+        socket.destroy()
+      }
+
+      this.originalSocket = undefined
     })
 
     this.address = socket.address.bind(socket)
@@ -258,6 +272,7 @@ export class MockHttpSocket extends MockSocket {
         'getProtocol',
         'getSession',
         'isSessionReused',
+        'getCipher',
       ]
 
       tlsProperties.forEach((propertyName) => {
@@ -311,6 +326,16 @@ export class MockHttpSocket extends MockSocket {
       return
     }
 
+    // Prevent recursive calls.
+    invariant(
+      this.socketState !== 'mock',
+      '[MockHttpSocket] Failed to respond to the "%s %s" request with "%s %s": the request has already been handled',
+      this.request?.method,
+      this.request?.url,
+      response.status,
+      response.statusText
+    )
+
     // Handle "type: error" responses.
     if (isPropertyAccessible(response, 'type') && response.type === 'error') {
       this.errorWith(new TypeError('Network error'))
@@ -393,9 +418,18 @@ export class MockHttpSocket extends MockSocket {
           serverResponse.write(value)
         }
       } catch (error) {
-        // Coerce response stream errors to 500 responses.
-        this.respondWith(createServerErrorResponse(error))
-        return
+        if (error instanceof Error) {
+          serverResponse.destroy()
+          /**
+           * @note Destroy the request socket gracefully.
+           * Response stream errors do NOT produce request errors.
+           */
+          this.destroy()
+          return
+        }
+
+        serverResponse.destroy()
+        throw error
       }
     } else {
       serverResponse.end()

package/src/interceptors/ClientRequest/index.ts

@@ -153,30 +153,26 @@ export class ClientRequestInterceptor extends Interceptor<HttpRequestEventMap> {
     request,
     socket,
   }) => {
-    const requestId = Reflect.get(request, kRequestId)
-    const controller = new RequestController(request)
-
-    const isRequestHandled = await handleRequest({
-      request,
-      requestId,
-      controller,
-      emitter: this.emitter,
-      onResponse: (response) => {
-        socket.respondWith(response)
+    const controller = new RequestController(request, {
+      passthrough() {
+        socket.passthrough()
       },
-      onRequestError: (response) => {
-        socket.respondWith(response)
+      async respondWith(response) {
+        await socket.respondWith(response)
       },
-      onError: (error) => {
-        if (error instanceof Error) {
-          socket.errorWith(error)
+      errorWith(reason) {
+        if (reason instanceof Error) {
+          socket.errorWith(reason)
         }
       },
     })
 
-    if (!isRequestHandled) {
-      return socket.passthrough()
-    }
+    await handleRequest({
+      request,
+      requestId: Reflect.get(request, kRequestId),
+      controller,
+      emitter: this.emitter,
+    })
   }
 
   public onResponse: MockHttpSocketResponseCallback = async ({

package/src/interceptors/ClientRequest/utils/parserUtils.ts

@@ -0,0 +1,48 @@
+import type { Socket } from 'node:net'
+import { HTTPParser } from '_http_common'
+
+/**
+ * @see https://github.com/nodejs/node/blob/f3adc11e37b8bfaaa026ea85c1cf22e3a0e29ae9/lib/_http_common.js#L180
+ */
+export function freeParser(parser: HTTPParser<any>, socket?: Socket): void {
+  if (parser._consumed) {
+    parser.unconsume()
+  }
+
+  parser._headers = []
+  parser._url = ''
+  parser.socket = null
+  parser.incoming = null
+  parser.outgoing = null
+  parser.maxHeaderPairs = 2000
+  parser._consumed = false
+  parser.onIncoming = null
+
+  parser[HTTPParser.kOnHeaders] = null
+  parser[HTTPParser.kOnHeadersComplete] = null
+  parser[HTTPParser.kOnMessageBegin] = null
+  parser[HTTPParser.kOnMessageComplete] = null
+  parser[HTTPParser.kOnBody] = null
+  parser[HTTPParser.kOnExecute] = null
+  parser[HTTPParser.kOnTimeout] = null
+
+  parser.remove()
+  parser.free()
+
+  if (socket) {
+    /**
+     * @note Unassigning the socket's parser will fail this assertion
+     * if there's still some data being processed on the socket:
+     * @see https://github.com/nodejs/node/blob/4e1f39b678b37017ac9baa0971e3aeecd3b67b51/lib/_http_client.js#L613
+     */
+    if (socket.destroyed) {
+      // @ts-expect-error Node.js internals.
+      socket.parser = null
+    } else {
+      socket.once('end', () => {
+        // @ts-expect-error Node.js internals.
+        socket.parser = null
+      })
+    }
+  }
+}

package/src/interceptors/WebSocket/index.ts

@@ -19,7 +19,10 @@ import { bindEvent } from './utils/bindEvent'
 import { hasConfigurableGlobal } from '../../utils/hasConfigurableGlobal'
 import { emitAsync } from '../../utils/emitAsync'
 
-export { type WebSocketData, WebSocketTransport } from './WebSocketTransport'
+export {
+  type WebSocketData,
+  type WebSocketTransport,
+} from './WebSocketTransport'
 export {
   WebSocketClientEventMap,
   WebSocketClientConnectionProtocol,

package/src/interceptors/XMLHttpRequest/XMLHttpRequestController.ts

@@ -57,7 +57,10 @@ export class XMLHttpRequestController {
     Array<Function>
   >
 
-  constructor(readonly initialRequest: XMLHttpRequest, public logger: Logger) {
+  constructor(
+    readonly initialRequest: XMLHttpRequest,
+    public logger: Logger
+  ) {
     this[kIsRequestHandled] = false
 
     this.events = new Map()
@@ -111,7 +114,7 @@ export class XMLHttpRequestController {
           case 'addEventListener': {
             const [eventName, listener] = args as [
               keyof XMLHttpRequestEventTargetEventMap,
-              Function
+              Function,
             ]
 
             this.registerEvent(eventName, listener)
@@ -131,7 +134,7 @@ export class XMLHttpRequestController {
 
           case 'send': {
             const [body] = args as [
-              body?: XMLHttpRequestBodyInit | Document | null
+              body?: XMLHttpRequestBodyInit | Document | null,
             ]
 
             this.request.addEventListener('load', () => {
@@ -166,38 +169,44 @@ export class XMLHttpRequestController {
             const fetchRequest = this.toFetchApiRequest(requestBody)
             this[kFetchRequest] = fetchRequest.clone()
 
-            const onceRequestSettled =
-              this.onRequest?.call(this, {
-                request: fetchRequest,
-                requestId: this.requestId!,
-              }) || Promise.resolve()
-
-            onceRequestSettled.finally(() => {
-              // If the consumer didn't handle the request (called `.respondWith()`) perform it as-is.
-              if (!this[kIsRequestHandled]) {
-                this.logger.info(
-                  'request callback settled but request has not been handled (readystate %d), performing as-is...',
-                  this.request.readyState
-                )
-
-                /**
-                 * @note Set the intercepted request ID on the original request in Node.js
-                 * so that if it triggers any other interceptors, they don't attempt
-                 * to process it once again.
-                 *
-                 * For instance, XMLHttpRequest is often implemented via "http.ClientRequest"
-                 * and we don't want for both XHR and ClientRequest interceptors to
-                 * handle the same request at the same time (e.g. emit the "response" event twice).
-                 */
-                if (IS_NODE) {
-                  this.request.setRequestHeader(
-                    INTERNAL_REQUEST_ID_HEADER_NAME,
-                    this.requestId!
+            /**
+             * @note Start request handling on the next tick so that the user
+             * could add event listeners for "loadend" before the interceptor fires it.
+             */
+            queueMicrotask(() => {
+              const onceRequestSettled =
+                this.onRequest?.call(this, {
+                  request: fetchRequest,
+                  requestId: this.requestId!,
+                }) || Promise.resolve()
+
+              onceRequestSettled.finally(() => {
+                // If the consumer didn't handle the request (called `.respondWith()`) perform it as-is.
+                if (!this[kIsRequestHandled]) {
+                  this.logger.info(
+                    'request callback settled but request has not been handled (readystate %d), performing as-is...',
+                    this.request.readyState
                   )
-                }
 
-                return invoke()
-              }
+                  /**
+                   * @note Set the intercepted request ID on the original request in Node.js
+                   * so that if it triggers any other interceptors, they don't attempt
+                   * to process it once again.
+                   *
+                   * For instance, XMLHttpRequest is often implemented via "http.ClientRequest"
+                   * and we don't want for both XHR and ClientRequest interceptors to
+                   * handle the same request at the same time (e.g. emit the "response" event twice).
+                   */
+                  if (IS_NODE) {
+                    this.request.setRequestHeader(
+                      INTERNAL_REQUEST_ID_HEADER_NAME,
+                      this.requestId!
+                    )
+                  }
+
+                  return invoke()
+                }
+              })
             })
 
             break
@@ -241,7 +250,7 @@ export class XMLHttpRequestController {
             case 'addEventListener': {
               const [eventName, listener] = args as [
                 keyof XMLHttpRequestEventTargetEventMap,
-                Function
+                Function,
               ]
               this.registerUploadEvent(eventName, listener)
               this.logger.info('upload.addEventListener', eventName, listener)
@@ -312,6 +321,7 @@ export class XMLHttpRequestController {
         loaded: totalRequestBodyLength,
         total: totalRequestBodyLength,
       })
+
       this.trigger('loadend', this.request.upload, {
         loaded: totalRequestBodyLength,
         total: totalRequestBodyLength,
@@ -614,7 +624,7 @@ export class XMLHttpRequestController {
   private trigger<
     EventName extends keyof (XMLHttpRequestEventTargetEventMap & {
       readystatechange: ProgressEvent<XMLHttpRequestEventTarget>
-    })
+    }),
   >(
     eventName: EventName,
     target: XMLHttpRequest | XMLHttpRequestUpload,

package/src/interceptors/XMLHttpRequest/XMLHttpRequestProxy.ts

@@ -3,6 +3,7 @@ import { XMLHttpRequestEmitter } from '.'
 import { RequestController } from '../../RequestController'
 import { XMLHttpRequestController } from './XMLHttpRequestController'
 import { handleRequest } from '../../utils/handleRequest'
+import { isResponseError } from '../../utils/responseUtils'
 
 export interface XMLHttpRequestProxyOptions {
   emitter: XMLHttpRequestEmitter
@@ -52,7 +53,28 @@ export function createXMLHttpRequestProxy({
       )
 
       xhrRequestController.onRequest = async function ({ request, requestId }) {
-        const controller = new RequestController(request)
+        const controller = new RequestController(request, {
+          passthrough: () => {
+            this.logger.info(
+              'no mocked response received, performing request as-is...'
+            )
+          },
+          respondWith: async (response) => {
+            if (isResponseError(response)) {
+              this.errorWith(new TypeError('Network error'))
+              return
+            }
+
+            await this.respondWith(response)
+          },
+          errorWith: (reason) => {
+            this.logger.info('request errored!', { error: reason })
+
+            if (reason instanceof Error) {
+              this.errorWith(reason)
+            }
+          },
+        })
 
         this.logger.info('awaiting mocked response...')
 
@@ -61,31 +83,12 @@ export function createXMLHttpRequestProxy({
           emitter.listenerCount('request')
         )
 
-        const isRequestHandled = await handleRequest({
+        await handleRequest({
           request,
           requestId,
           controller,
           emitter,
-          onResponse: async (response) => {
-            await this.respondWith(response)
-          },
-          onRequestError: () => {
-            this.errorWith(new TypeError('Network error'))
-          },
-          onError: (error) => {
-            this.logger.info('request errored!', { error })
-
-            if (error instanceof Error) {
-              this.errorWith(error)
-            }
-          },
         })
-
-        if (!isRequestHandled) {
-          this.logger.info(
-            'no mocked response received, performing request as-is...'
-          )
-        }
       }
 
       xhrRequestController.onResponse = async function ({

package/src/interceptors/XMLHttpRequest/utils/getBodyByteLength.test.ts

@@ -88,7 +88,7 @@ it('calculates body length from the FormData request body', async () => {
         body: formData,
       })
     )
-  ).resolves.toBe(127)
+  ).resolves.toBe(129)
 })
 
 it('calculates body length from the ReadableStream request body', async () => {
@@ -149,7 +149,7 @@ it('calculates body length from the FormData response body', async () => {
   const formData = new FormData()
   formData.append('hello', 'world')
 
-  await expect(getBodyByteLength(new Response(formData))).resolves.toBe(127)
+  await expect(getBodyByteLength(new Response(formData))).resolves.toBe(129)
 })
 
 it('calculates body length from the ReadableStream response body', async () => {