@mswjs/interceptors 0.41.8 → 0.42.0

package/src/utils/{getUrlByRequestOptions.ts → get-url-by-request-options.ts}

@@ -1,8 +1,8 @@
-import { Agent } from 'http'
-import { RequestOptions, Agent as HttpsAgent } from 'https'
-import { Logger } from '@open-draft/logger'
+import { Agent } from 'node:http'
+import { RequestOptions, Agent as HttpsAgent } from 'node:https'
+import { createLogger } from './logger'
 
-const logger = new Logger('utils getUrlByRequestOptions')
+const logger = createLogger('get-url-by-request-options')
 
 // Request instance constructed by the "request" library
 // has a "self" property that has a "uri" field. This is
@@ -13,7 +13,7 @@ export interface RequestSelf {
 
 export type ResolvedRequestOptions = RequestOptions & RequestSelf
 
-export const DEFAULT_PATH = '/'
+const DEFAULT_PATH = '/'
 const DEFAULT_PROTOCOL = 'http:'
 const DEFAULT_HOSTNAME = 'localhost'
 const SSL_PORT = 443
@@ -94,7 +94,7 @@ function getHostname(options: ResolvedRequestOptions): string | undefined {
 
   if (host) {
     if (isRawIPv6Address(host)) {
-       host = `[${host}]`
+      host = `[${host}]`
     }
 
     // Check the presence of the port, and if it's present,
@@ -109,44 +109,44 @@ function getHostname(options: ResolvedRequestOptions): string | undefined {
  * Creates a `URL` instance from a given `RequestOptions` object.
  */
 export function getUrlByRequestOptions(options: ResolvedRequestOptions): URL {
-  logger.info('request options', options)
+  logger.verbose('request options %o', options)
 
   if (options.uri) {
-    logger.info(
+    logger.verbose(
       'constructing url from explicitly provided "options.uri": %s',
       options.uri
     )
     return new URL(options.uri.href)
   }
 
-  logger.info('figuring out url from request options...')
+  logger.verbose('figuring out URL from request options')
 
   const protocol = getProtocolByRequestOptions(options)
-  logger.info('protocol', protocol)
+  logger.verbose('protocol: %s', protocol)
 
   const port = getPortByRequestOptions(options)
-  logger.info('port', port)
+  logger.verbose('port: %s', port)
 
   const hostname = getHostname(options)
-  logger.info('hostname', hostname)
+  logger.verbose('hostname: %s', hostname)
 
   const path = options.path || DEFAULT_PATH
-  logger.info('path', path)
+  logger.verbose('path: %s', path)
 
   const credentials = getAuthByRequestOptions(options)
-  logger.info('credentials', credentials)
+  logger.verbose('credentials %o', credentials)
 
   const authString = credentials
     ? `${credentials.username}:${credentials.password}@`
     : ''
-  logger.info('auth string:', authString)
+  logger.verbose('auth string: %s', authString)
 
   const portString = typeof port !== 'undefined' ? `:${port}` : ''
   const url = new URL(`${protocol}//${hostname}${portString}${path}`)
   url.username = credentials?.username || ''
   url.password = credentials?.password || ''
 
-  logger.info('created url:', url)
+  logger.verbose('created URL: %s', url.href)
 
   return url
 }

package/src/utils/{getValueBySymbol.test.ts → get-value-by-symbol.test.ts}

@@ -1,5 +1,4 @@
-import { it, expect } from 'vitest'
-import { getValueBySymbol } from './getValueBySymbol'
+import { getValueBySymbol } from './get-value-by-symbol'
 
 it('returns undefined given a non-existing symbol', () => {
   expect(getValueBySymbol('non-existing', {})).toBeUndefined()

package/src/utils/{handleRequest.ts → handle-request.ts}

@@ -1,28 +1,40 @@
-import type { Emitter } from 'strict-event-emitter'
-import { DeferredPromise } from '@open-draft/deferred-promise'
+import type { Emitter } from 'rettime'
 import { until } from '@open-draft/until'
-import type { HttpRequestEventMap } from '../glossary'
-import { emitAsync } from './emitAsync'
-import { RequestController } from '../RequestController'
+import {
+  HttpRequestEvent,
+  HttpRequestEventData,
+  UnhandledHttpException,
+  type HttpRequestEventMap,
+} from '../events/http'
+import { RequestController } from '../request-controller'
 import {
   createServerErrorResponse,
   isResponseError,
   isResponseLike,
-} from './responseUtils'
-import { InterceptorError } from '../InterceptorError'
-import { isNodeLikeError } from './isNodeLikeError'
-import { isObject } from './isObject'
-
-interface HandleRequestOptions {
+} from './response-utils'
+import { InterceptorError } from '../interceptor-error'
+import { isNodeLikeError } from './is-node-like-error'
+import { isObject } from './is-object'
+import { formatRequest, type Logger } from './logger'
+
+export interface HandleRequestOptions {
+  initiator: unknown
   requestId: string
   request: Request
   emitter: Emitter<HttpRequestEventMap>
   controller: RequestController
+  logger?: Logger
 }
 
 export async function handleRequest(
   options: HandleRequestOptions
 ): Promise<void> {
+  if (options.logger?.isEnabled('default')) {
+    void formatRequest(options.request).then((message) => {
+      options.logger?.info('[%s] %s', options.requestId, message)
+    })
+  }
+
   const handleResponse = async (
     response: Response | Error | Record<string, any>
   ) => {
@@ -60,7 +72,7 @@ export async function handleRequest(
     // Forward the special interceptor error instances
     // to the developer. These must not be handled in any way.
     if (error instanceof InterceptorError) {
-      throw result.error
+      throw resultError
     }
 
     // Support mocking Node.js-like errors.
@@ -77,19 +89,14 @@ export async function handleRequest(
     return false
   }
 
-  // Add the last "request" listener to check if the request
-  // has been handled in any way. If it hasn't, resolve the
-  // response promise with undefined.
-  // options.emitter.once('request', async ({ requestId: pendingRequestId }) => {
-  //   if (
-  //     pendingRequestId === options.requestId &&
-  //     options.controller.readyState === RequestController.PENDING
-  //   ) {
-  //     await options.controller.passthrough()
-  //   }
-  // })
-
-  const requestAbortPromise = new DeferredPromise<void, unknown>()
+  const requestAbortPromise = Promise.withResolvers<void>()
+  let requestAbortReason: unknown
+  let isRequestAborted = false
+  const onAbort = () => {
+    isRequestAborted = true
+    requestAbortReason = options.request.signal?.reason
+    requestAbortPromise.reject(requestAbortReason)
+  }
 
   /**
    * @note `signal` is not always defined in React Native.
@@ -100,44 +107,53 @@ export async function handleRequest(
       return
     }
 
-    options.request.signal.addEventListener(
-      'abort',
-      () => {
-        requestAbortPromise.reject(options.request.signal.reason)
-      },
-      { once: true }
-    )
+    options.request.signal.addEventListener('abort', onAbort, { once: true })
   }
 
-  const result = await until(async () => {
+  const [resultError] = await until(async () => {
     // Emit the "request" event and wait until all the listeners
     // for that event are finished (e.g. async listeners awaited).
     // By the end of this promise, the developer cannot affect the
     // request anymore.
-    const requestListenersPromise = emitAsync(options.emitter, 'request', {
+    const requestEventData: HttpRequestEventData = {
+      initiator: options.initiator,
       requestId: options.requestId,
       request: options.request,
       controller: options.controller,
-    })
+    }
+    const requestEvent = new HttpRequestEvent(requestEventData)
+    const requestListenersPromise = options.emitter.emitAsPromise(requestEvent)
 
     await Promise.race([
       // Short-circuit the request handling promise if the request gets aborted.
-      requestAbortPromise,
+      requestAbortPromise.promise,
       requestListenersPromise,
       options.controller.handled,
     ])
+
+    /**
+     * @note If the "request" listener has replaced the request instance,
+     * propagate that mutation back to the underlying insterceptor.
+     * This happens with XMLHttpRequest that replaces request instances
+     * to correctly reflect the "withCredentials" option on the Fetch API request.
+     */
+    if (requestEvent.request !== options.request) {
+      options.request = requestEvent.request
+    }
   })
 
+  options.request.signal?.removeEventListener('abort', onAbort)
+
   // Handle the request being aborted while waiting for the request listeners.
-  if (requestAbortPromise.state === 'rejected') {
-    await options.controller.errorWith(requestAbortPromise.rejectionReason)
+  if (isRequestAborted) {
+    await options.controller.errorWith(requestAbortReason)
     return
   }
 
-  if (result.error) {
+  if (resultError) {
     // Handle the error during the request listener execution.
     // These can be thrown responses or request errors.
-    if (await handleResponseError(result.error)) {
+    if (await handleResponseError(resultError)) {
       return
     }
 
@@ -173,12 +189,15 @@ export async function handleRequest(
         }
       )
 
-      await emitAsync(options.emitter, 'unhandledException', {
-        error: result.error,
-        request: options.request,
-        requestId: options.requestId,
-        controller: unhandledExceptionController,
-      })
+      await options.emitter.emitAsPromise(
+        new UnhandledHttpException({
+          initiator: options.initiator,
+          error: resultError,
+          request: options.request,
+          requestId: options.requestId,
+          controller: unhandledExceptionController,
+        })
+      )
 
       // If all the "unhandledException" listeners have finished
       // but have not handled the request in any way, passthrough.
@@ -191,7 +210,7 @@ export async function handleRequest(
 
     // Otherwise, coerce unhandled exceptions to a 500 Internal Server Error response.
     await options.controller.respondWith(
-      createServerErrorResponse(result.error)
+      createServerErrorResponse(resultError)
     )
     return
   }

package/src/utils/{hasConfigurableGlobal.test.ts → has-configurable-global.test.ts}

@@ -1,5 +1,4 @@
-import { vi, beforeAll, afterEach, afterAll, it, expect } from 'vitest'
-import { hasConfigurableGlobal } from './hasConfigurableGlobal'
+import { hasConfigurableGlobal } from './has-configurable-global'
 
 let originalGlobalPrototype = Object.getPrototypeOf(globalThis)
 

package/src/utils/{hasConfigurableGlobal.ts → has-configurable-global.ts}

@@ -1,12 +1,10 @@
-import { getDeepPropertyDescriptor } from './patchesRegistry'
+import { getDeepPropertyDescriptor } from './patches-registry'
 
 /**
  * Returns a boolean indicating whether the given global property
  * is defined and is configurable.
  */
-export function hasConfigurableGlobal(
-  propertyName: keyof typeof globalThis
-): boolean {
+export function hasConfigurableGlobal(propertyName: string): boolean {
   const match = getDeepPropertyDescriptor(globalThis, propertyName)
 
   // The property is not set at all.

package/src/utils/{isObject.test.ts → is-object.test.ts}

@@ -1,5 +1,4 @@
-import { it, expect } from 'vitest'
-import { isObject } from './isObject'
+import { isObject } from './is-object'
 
 it('returns true given an object', () => {
   expect(isObject({})).toBe(true)

package/src/utils/logger.test.ts

@@ -0,0 +1,154 @@
+import debug from 'debug'
+import { createLogger, formatRequest, formatResponse } from './logger'
+import { Interceptor } from '../interceptor'
+
+let previousNamespaces: string
+let previousDebugLevel: string | undefined
+
+beforeEach(() => {
+  previousNamespaces = debug.disable()
+  previousDebugLevel = process.env.DEBUG_LEVEL
+  delete process.env.DEBUG_LEVEL
+})
+
+afterEach(() => {
+  debug.enable(previousNamespaces)
+
+  if (previousDebugLevel === undefined) {
+    delete process.env.DEBUG_LEVEL
+  } else {
+    process.env.DEBUG_LEVEL = previousDebugLevel
+  }
+
+  vi.restoreAllMocks()
+})
+
+it('writes default logs with a normalized namespace and concise timestamp', () => {
+  const writeLog = vi.spyOn(debug, 'log').mockImplementation(() => {
+    return undefined
+  })
+  debug.enable('interceptors:client-request')
+
+  const logger = createLogger('ClientRequest')
+  logger.info('apply')
+  logger.verbose('socket packet')
+
+  expect(writeLog).toHaveBeenCalledOnce()
+  expect(writeLog.mock.calls[0][0]).toMatch(
+    /^\d{2}:\d{2}:\d{2}\.\d{3} \u001b\[.*interceptors:client-request.* apply$/
+  )
+  expect(writeLog.mock.calls[0][0]).toContain('\u001b[')
+})
+
+it('writes verbose logs under the interceptor namespace', () => {
+  const writeLog = vi.spyOn(debug, 'log').mockImplementation(() => {
+    return undefined
+  })
+  debug.enable('interceptors:xhr')
+  process.env.DEBUG_LEVEL = 'verbose'
+
+  const logger = createLogger('xhr')
+  logger.info('apply')
+  logger.verbose('socket packet')
+
+  expect(writeLog).toHaveBeenCalledTimes(2)
+  expect(writeLog.mock.calls[1][0]).toMatch(
+    /^\d{2}:\d{2}:\d{2}\.\d{3} .*interceptors:xhr.* socket packet$/
+  )
+})
+
+it('formats a request as an HTTP message without consuming it', async () => {
+  const request = new Request('https://example.com/resource', {
+    method: 'POST',
+    headers: {
+      'content-type': 'text/plain',
+      'x-example': 'yes',
+    },
+    body: 'request body',
+  })
+
+  await expect(formatRequest(request)).resolves.toBe(
+    [
+      'POST https://example.com/resource',
+      'content-type: text/plain',
+      'x-example: yes',
+      '',
+      'request body',
+    ].join('\n')
+  )
+  await expect(request.text()).resolves.toBe('request body')
+})
+
+it('formats a response as an HTTP message without consuming it', async () => {
+  const response = new Response('response body', {
+    status: 201,
+    statusText: 'Created',
+    headers: {
+      'content-type': 'text/plain',
+      'x-example': 'yes',
+    },
+  })
+
+  await expect(formatResponse(response)).resolves.toBe(
+    [
+      'HTTP 201 Created',
+      'content-type: text/plain',
+      'x-example: yes',
+      '',
+      'response body',
+    ].join('\n')
+  )
+  await expect(response.text()).resolves.toBe('response body')
+})
+
+it('omits an unreadable body', async () => {
+  const response = new Response('response body')
+  await response.text()
+
+  await expect(formatResponse(response)).resolves.toBe(
+    ['HTTP 200', 'content-type: text/plain;charset=UTF-8', '', ''].join(
+      '\n'
+    )
+  )
+})
+
+it('omits an empty body', async () => {
+  const response = new Response('')
+
+  await expect(formatResponse(response)).resolves.toBe(
+    ['HTTP 200', 'content-type: text/plain;charset=UTF-8', '', ''].join(
+      '\n'
+    )
+  )
+})
+
+it('logs interceptor lifecycle operations', () => {
+  const writeLog = vi.spyOn(debug, 'log').mockImplementation(() => {
+    return undefined
+  })
+  debug.enable('interceptors:test')
+
+  class TestInterceptor extends Interceptor<{}> {
+    static symbol = Symbol.for('test-interceptor')
+
+    protected predicate(): boolean {
+      return true
+    }
+
+    protected setup(): void {
+      // Intentionally empty.
+    }
+  }
+
+  const interceptor = new TestInterceptor()
+  interceptor.apply()
+  interceptor.removeAllListeners()
+  interceptor.dispose()
+
+  expect(writeLog).toHaveBeenCalledTimes(3)
+  expect(writeLog.mock.calls[0][0]).toMatch(/ apply$/)
+  expect(writeLog.mock.calls[1][0]).toContain(' removeAllListeners ')
+  expect(writeLog.mock.calls[1][0]).toContain('eventType:')
+  expect(writeLog.mock.calls[1][0]).toContain("'*'")
+  expect(writeLog.mock.calls[2][0]).toMatch(/ disable$/)
+})

package/src/utils/logger.ts

@@ -0,0 +1,154 @@
+import debug from 'debug'
+
+export type LogLevel = 'default' | 'verbose'
+
+export interface Logger {
+  info(message: string, ...positionals: Array<unknown>): void
+  verbose(message: string, ...positionals: Array<unknown>): void
+  isEnabled(level: LogLevel): boolean
+}
+
+const LOG_TIMESTAMP_REGEXP = /\d{2}:\d{2}:\d{2}\.\d{3}/
+
+function normalizeNamespace(namespace: string): string {
+  return namespace
+    .split(':')
+    .map((segment) => {
+      return segment
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase()
+    })
+    .filter(Boolean)
+    .join(':')
+}
+
+function getTimestamp(): string {
+  return new Date().toISOString().slice(11, 23)
+}
+
+async function readBody(message: Request | Response): Promise<string | null> {
+  if (message.body == null) {
+    return null
+  }
+
+  try {
+    return await message.clone().text()
+  } catch {
+    return null
+  }
+}
+
+function formatHeaders(headers: Headers): Array<string> {
+  return Array.from(headers.entries()).map(([name, value]) => {
+    return `${name}: ${value}`
+  })
+}
+
+async function formatHttpMessage(
+  startLine: string,
+  message: Request | Response
+): Promise<string> {
+  const lines = [startLine, ...formatHeaders(message.headers)]
+  const body = await readBody(message)
+
+  lines.push('', body ?? '')
+
+  return lines.join('\n')
+}
+
+export async function formatRequest(request: Request): Promise<string> {
+  return formatHttpMessage(`${request.method} ${request.url}`, request)
+}
+
+export async function formatResponse(response: Response): Promise<string> {
+  const statusText = response.statusText ? ` ${response.statusText}` : ''
+  return formatHttpMessage(
+    `HTTP ${response.status}${statusText}`,
+    response
+  )
+}
+
+function formatLogArguments(arguments_: Array<unknown>): void {
+  const message = arguments_[0]
+
+  if (typeof message === 'string') {
+    const messageWithoutDebugTimestamp = message.replace(
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z /,
+      ''
+    )
+    const timestampMatch = messageWithoutDebugTimestamp.match(
+      LOG_TIMESTAMP_REGEXP
+    )
+
+    if (!timestampMatch || timestampMatch.index === undefined) {
+      arguments_[0] = messageWithoutDebugTimestamp
+      return
+    }
+
+    const messagePrefix = messageWithoutDebugTimestamp
+      .slice(0, timestampMatch.index)
+      .trim()
+    const messageBody = messageWithoutDebugTimestamp
+      .slice(timestampMatch.index + timestampMatch[0].length)
+      .trimStart()
+
+    arguments_[0] = `${timestampMatch[0]} ${messagePrefix} ${messageBody}`
+  }
+}
+
+function useConciseTimestamp(logger: debug.Debugger): void {
+  logger.log = (...arguments_) => {
+    formatLogArguments(arguments_)
+    debug.log(...arguments_)
+  }
+}
+
+function isVerboseLoggingEnabled(): boolean {
+  if (typeof process !== 'undefined' && process.env.DEBUG_LEVEL === 'verbose') {
+    return true
+  }
+
+  /**
+   * @note Consult the localStorage only in browser-like environments.
+   * In Node.js 26+, reading "globalThis.localStorage" without the
+   * "--localstorage-file" flag set emits an experimental warning
+   * (a try/catch cannot suppress it). Node.js consumers control the
+   * log level via the "DEBUG_LEVEL" environment variable above.
+   */
+  if (typeof document === 'undefined') {
+    return false
+  }
+
+  try {
+    return globalThis.localStorage?.getItem('debugLevel') === 'verbose'
+  } catch {
+    return false
+  }
+}
+
+export function createLogger(namespace: string): Logger {
+  const normalizedNamespace = normalizeNamespace(namespace)
+  const logger = debug(`interceptors:${normalizedNamespace}`)
+  Reflect.set(logger, 'useColors', true)
+  useConciseTimestamp(logger)
+
+  return {
+    info(message, ...positionals) {
+      logger(`${getTimestamp()} ${message}`, ...positionals)
+    },
+    verbose(message, ...positionals) {
+      if (!isVerboseLoggingEnabled()) {
+        return
+      }
+
+      logger(`${getTimestamp()} ${message}`, ...positionals)
+    },
+    isEnabled(level) {
+      return (
+        logger.enabled && (level === 'default' || isVerboseLoggingEnabled())
+      )
+    },
+  }
+}

package/src/utils/{parseJson.test.ts → parse-json.test.ts}

@@ -1,5 +1,4 @@
-import { it, expect } from 'vitest'
-import { parseJson } from './parseJson'
+import { parseJson } from './parse-json'
 
 it('parses a given string into JSON', () => {
   expect(parseJson('{"id":1}')).toEqual({ id: 1 })

package/src/utils/{patchesRegistry.test.ts → patches-registry.test.ts}

@@ -1,5 +1,5 @@
 import { it, beforeEach, afterEach, expect, vi } from 'vitest'
-import { patchesRegistry } from './patchesRegistry'
+import { patchesRegistry } from './patches-registry'
 
 declare global {
   var foo: { original: boolean }

package/src/utils/{patchesRegistry.ts → patches-registry.ts}

@@ -114,7 +114,7 @@ interface DeepDescriptorMatch {
  */
 export function getDeepPropertyDescriptor<Owner extends object>(
   owner: Owner,
-  key: keyof Owner
+  key: PropertyKey
 ): DeepDescriptorMatch | undefined {
   let currentOwner: Owner | null = owner
   let descriptor: PropertyDescriptor | undefined

package/src/utils/{responseUtils.ts → response-utils.ts}

@@ -1,5 +1,5 @@
-import { isObject } from './isObject'
-import { isPropertyAccessible } from './isPropertyAccessible'
+import { isObject } from './is-object'
+import { isPropertyAccessible } from './is-property-accessible'
 
 /**
  * Creates a generic 500 Unhandled Exception response.
@@ -27,6 +27,29 @@ export function createServerErrorResponse(body: unknown): Response {
 
 export type ResponseError = Response & { type: 'error' }
 
+/**
+ * A key on the error a mocked `Response.error()` destroys the socket
+ * with, referencing that error response. Allows the client-side
+ * interceptors (e.g. fetch) to surface the error response to the
+ * consumer instead of the internal socket error.
+ */
+export const kErrorResponse = Symbol('kErrorResponse')
+
+/**
+ * Get the mocked error response that caused the given error, if any.
+ */
+export function getErrorResponse(error: unknown): ResponseError | undefined {
+  if (
+    error instanceof Error &&
+    kErrorResponse in error &&
+    isResponseError(error[kErrorResponse])
+  ) {
+    return error[kErrorResponse]
+  }
+
+  return undefined
+}
+
 /**
  * Check if the given response is a `Response.error()`.
  *