@mswjs/interceptors 0.41.8 → 0.42.0

package/src/interceptors/net/utils/address-info.ts

@@ -0,0 +1,54 @@
+import net from 'node:net'
+import { NetworkConnectionOptions } from './normalize-net-connect-args'
+
+export function getAddressInfoByConnectionOptions(
+  options?: NetworkConnectionOptions
+): ReturnType<net.Socket['address']> {
+  if (options == null) {
+    return {}
+  }
+
+  const isIPv6 = options.family === 6 || net.isIPv6(options.host || '')
+
+  return {
+    address: isIPv6 ? '::1' : '127.0.0.1',
+    /**
+     * @note Coerce the port to a number. Connection options may
+     * describe it as a string (e.g. when created from a URL), while
+     * the address info always reports a numeric port.
+     */
+    port: Number(options.port) || (options.protocol === 'https:' ? 443 : 80),
+    family: isIPv6 ? 'IPv6' : 'IPv4',
+  }
+}
+
+/**
+ * Get the local address info for the given connection options.
+ * This describes the client-side end of the connection: the socket
+ * is bound to the loopback interface and an ephemeral port, the same
+ * way the operating system binds an outgoing connection.
+ */
+export function getLocalAddressInfoByConnectionOptions(
+  options?: NetworkConnectionOptions
+): ReturnType<net.Socket['address']> {
+  if (options == null) {
+    return {}
+  }
+
+  const isIPv6 = options.family === 6 || net.isIPv6(options.host || '')
+
+  return {
+    address: options.localAddress || (isIPv6 ? '::1' : '127.0.0.1'),
+    port: options.localPort || getEphemeralPort(),
+    family: isIPv6 ? 'IPv6' : 'IPv4',
+  }
+}
+
+/**
+ * Get a random port from the ephemeral range (IANA: 49152-65535),
+ * the range the operating system draws from when binding an
+ * outgoing connection.
+ */
+function getEphemeralPort(): number {
+  return 49152 + Math.floor(Math.random() * (65535 - 49152 + 1))
+}

package/src/interceptors/net/utils/connection-options-to-url.ts

@@ -0,0 +1,56 @@
+import net from 'node:net'
+import tls from 'node:tls'
+import { NetworkConnectionOptions } from './normalize-net-connect-args'
+
+/**
+ * Creates a `URL` instance out of the `net.connect()` options.
+ * @note This implies that the passed connection is an HTTP connection.
+ */
+export function connectionOptionsToUrl(
+  options: NetworkConnectionOptions,
+  socket: net.Socket
+): URL {
+  const isIPv6 = net.isIPv6(options.host || '')
+  const protocol =
+    socket instanceof tls.TLSSocket
+      ? 'https:'
+      : getProtocolByConnectionOptions(options)
+  const host = options.host || 'localhost'
+
+  const url = new URL(`${protocol}//${isIPv6 ? `[${host}]` : host}`)
+
+  if (options.path) {
+    url.pathname = options.path
+  }
+
+  if (options.port) {
+    url.port = options.port.toString()
+  }
+
+  if (options.auth) {
+    const [username, password] = options.auth.split(':')
+    /**
+     * Authentication options are provided as plain values.
+     * Encode them to form a valid URL.
+     * @see https://github.com/nodejs/node/blob/f3adc11e37b8bfaaa026ea85c1cf22e3a0e29ae9/lib/internal/url.js#L1452
+     */
+    url.username = encodeURIComponent(username)
+    url.password = encodeURIComponent(password)
+  }
+
+  return url
+}
+
+function getProtocolByConnectionOptions(
+  options: NetworkConnectionOptions
+): 'https:' | 'http:' | (string & {}) {
+  if (options.protocol) {
+    return options.protocol
+  }
+
+  if (options.port === 443) {
+    return 'https:'
+  }
+
+  return 'http:'
+}

package/src/interceptors/net/utils/flush-writes.ts

@@ -0,0 +1,57 @@
+import net from 'node:net'
+
+/**
+ * Write the given pending data to the socket using its public
+ * "write()" method. Unlike direct "_writeGeneric()" calls, public
+ * writes go through the "Writable" queue that only dispatches the
+ * next write once the previous one completes. TLS sockets rely on
+ * that serialization: their "TLSWrap" handle supports a single
+ * write in flight and crashes the process with a native
+ * "Assertion failed: !current_write_" abort when writes overlap
+ * (e.g. multiple direct "_writeGeneric()" calls issued on a
+ * connecting socket replay back-to-back on "connect").
+ */
+export function writePendingData(
+  socket: net.Socket,
+  data: NonNullable<net.Socket['_pendingData']>,
+  encoding: BufferEncoding,
+  callback?: (error?: Error | null) => void
+): void {
+  if (Array.isArray(data)) {
+    for (let index = 0; index < data.length; index++) {
+      const entry = data[index]
+      const isLastEntry = index === data.length - 1
+
+      /**
+       * @note Per-entry callbacks are intentionally ignored, the same
+       * way "writevGeneric()" only honors the batch-level callback.
+       */
+      if (isLastEntry) {
+        socket.write(entry.chunk, entry.encoding, callback)
+      } else {
+        socket.write(entry.chunk, entry.encoding)
+      }
+    }
+
+    return
+  }
+
+  socket.write(data, encoding, callback)
+}
+
+export function unwrapPendingData(
+  data: NonNullable<net.Socket['_pendingData']>,
+  callback: (
+    chunk: string | Buffer,
+    encoding?: BufferEncoding,
+    callback?: (error?: Error | null) => void
+  ) => void
+) {
+  if (Array.isArray(data)) {
+    for (const entry of data) {
+      callback(entry.chunk, entry.encoding, entry.callback)
+    }
+  } else {
+    callback(data)
+  }
+}

package/src/interceptors/net/utils/get-tls-connect-options.ts

@@ -0,0 +1,23 @@
+import type tls from 'node:tls'
+
+/**
+ * Returns the original options the given TLS socket was created with.
+ * The original `tls.connect()` stores them on the socket instance
+ * under an internal symbol before connecting its transport.
+ * @see https://github.com/nodejs/node/blob/3178a762d6a2b1a37b74f02266eea0f3d86603f1/lib/_tls_wrap.js#L1690
+ */
+export function getTlsConnectOptions(
+  socket: tls.TLSSocket
+): tls.ConnectionOptions | undefined {
+  const kConnectOptions = Object.getOwnPropertySymbols(socket).find(
+    (symbol) => {
+      return symbol.description === 'connect-options'
+    }
+  )
+
+  if (kConnectOptions == null) {
+    return undefined
+  }
+
+  return Reflect.get(socket, kConnectOptions)
+}

package/src/interceptors/net/utils/normalize-net-connect-args.test.ts

@@ -0,0 +1,233 @@
+import {
+  normalizeNetConnectArgs,
+  type NetConnectArgs,
+} from './normalize-net-connect-args'
+
+it('normalizes an empty arguments list', () => {
+  expect(normalizeNetConnectArgs([])).toEqual([{ path: '' }, null])
+})
+
+it('normalizes "(port)"', () => {
+  expect(normalizeNetConnectArgs([8080])).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: undefined,
+    },
+    null,
+  ])
+})
+
+it('normalizes "(port, callback)"', () => {
+  const callback = () => {}
+
+  expect(normalizeNetConnectArgs([8080, callback])).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: undefined,
+    },
+    callback,
+  ])
+})
+
+it('normalizes "(port, host)"', () => {
+  expect(normalizeNetConnectArgs([8080, 'example.com'])).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: 'example.com',
+    },
+    null,
+  ])
+})
+
+it('normalizes "(port, host, callback)"', () => {
+  const callback = () => {}
+
+  expect(normalizeNetConnectArgs([8080, 'example.com', callback])).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: 'example.com',
+    },
+    callback,
+  ])
+})
+
+it('normalizes a zero port', () => {
+  expect(normalizeNetConnectArgs([0, 'example.com'])).toEqual([
+    {
+      port: 0,
+      path: '',
+      host: 'example.com',
+    },
+    null,
+  ])
+})
+
+it('normalizes "(options)"', () => {
+  expect(
+    normalizeNetConnectArgs([{ port: 8080, host: 'example.com' }])
+  ).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: 'example.com',
+      auth: undefined,
+      family: undefined,
+      session: undefined,
+      localAddress: undefined,
+      localPort: undefined,
+    },
+    null,
+  ])
+})
+
+it('normalizes "(options, callback)"', () => {
+  const callback = () => {}
+
+  expect(
+    normalizeNetConnectArgs([{ port: 8080, host: 'example.com' }, callback])
+  ).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: 'example.com',
+    },
+    callback,
+  ])
+})
+
+it('normalizes "(options)" with connection-specific options', () => {
+  const session = Buffer.from('session')
+
+  expect(
+    normalizeNetConnectArgs([
+      {
+        port: 8080,
+        host: 'example.com',
+        family: 6,
+        localAddress: '10.0.0.1',
+        localPort: 34567,
+      },
+    ])
+  ).toEqual([
+    {
+      port: 8080,
+      path: '',
+      host: 'example.com',
+      family: 6,
+      localAddress: '10.0.0.1',
+      localPort: 34567,
+    },
+    null,
+  ])
+
+  expect(
+    normalizeNetConnectArgs([
+      // The type definitions of "net.connect()" omit
+      // the TLS-specific options ("auth", "session").
+      Object.assign({ port: 8080 }, { auth: 'user:pass', session }),
+    ])
+  ).toEqual([
+    expect.objectContaining({
+      port: 8080,
+      auth: 'user:pass',
+      session,
+    }),
+    null,
+  ])
+})
+
+it('normalizes "(options)" with the "path" option', () => {
+  expect(normalizeNetConnectArgs([{ path: '/tmp/service.sock' }])).toEqual([
+    {
+      path: '/tmp/service.sock',
+      auth: undefined,
+      family: undefined,
+      session: undefined,
+    },
+    null,
+  ])
+})
+
+it('normalizes "(path)"', () => {
+  expect(normalizeNetConnectArgs(['/tmp/service.sock'])).toEqual([
+    {
+      path: '/tmp/service.sock',
+    },
+    null,
+  ])
+})
+
+it('normalizes "(path, callback)"', () => {
+  const callback = () => {}
+
+  expect(normalizeNetConnectArgs(['/tmp/service.sock', callback])).toEqual([
+    {
+      path: '/tmp/service.sock',
+    },
+    callback,
+  ])
+})
+
+/**
+ * @note Node.js does not support URL arguments and reads them
+ * as plain options objects. Reproduce that reading exactly:
+ * "url.port" is a string, "url.host" includes the port.
+ */
+it('treats "(url)" as a plain options object, like Node.js', () => {
+  expect(
+    normalizeNetConnectArgs([new URL('http://example.com:8080/path?query=1')])
+  ).toEqual([
+    {
+      path: '',
+      port: '8080',
+      host: 'example.com:8080',
+    },
+    null,
+  ])
+})
+
+it('treats a port-less "(url)" as a plain options object, like Node.js', () => {
+  expect(normalizeNetConnectArgs([new URL('http://example.com/')])).toEqual([
+    {
+      path: '',
+      port: '',
+      host: 'example.com',
+    },
+    null,
+  ])
+})
+
+it('normalizes "(url, callback)"', () => {
+  const callback = () => {}
+
+  expect(
+    normalizeNetConnectArgs([new URL('http://example.com:8080/'), callback])
+  ).toEqual([
+    expect.objectContaining({
+      port: '8080',
+      host: 'example.com:8080',
+    }),
+    callback,
+  ])
+})
+
+it('returns a new options object for the "(options)" signature', () => {
+  const inputOptions = { port: 8080, host: 'example.com' }
+  const [normalizedOptions] = normalizeNetConnectArgs([inputOptions])
+
+  expect(normalizedOptions).not.toBe(inputOptions)
+
+  // Modifying the normalized options must not affect the input.
+  normalizedOptions.host = 'changed.com'
+  expect(inputOptions).toEqual({ port: 8080, host: 'example.com' })
+})
+
+it('throws on invalid arguments', () => {
+  expect(() => {
+    return normalizeNetConnectArgs([true] as unknown as NetConnectArgs)
+  }).toThrow('Invalid arguments passed to net.connect: true')
+})

package/src/interceptors/net/utils/normalize-net-connect-args.ts

@@ -0,0 +1,121 @@
+import net from 'node:net'
+
+export interface NetworkConnectionOptions {
+  /**
+   * @note The port may be a string when a URL is (incorrectly) passed
+   * to `net.connect()`. Node.js reads URLs as plain options objects.
+   */
+  port?: number | string | null
+  path: string | null
+  host?: string | null
+  protocol?: string | null
+  auth?: string | null
+  family?: number | null
+  hints?: number | null
+  session?: Buffer
+  localAddress?: string | null
+  localPort?: number | null
+  timeout?: number
+  lookup?: net.LookupFunction
+  allowHalfOpen?: boolean | null
+  noDelay?: boolean | null
+  keepAlive?: boolean | null
+  keepAliveInitialDelay?: number | null
+  autoSelectFamily?: boolean | null
+  autoSelectFamilyAttemptTimeout?: number | null
+}
+
+export type NetConnectArgs =
+  | []
+  | [options: net.NetConnectOpts, callback?: () => void]
+  | [url: URL, callback?: () => void]
+  | [port: number, host?: string, callback?: () => void]
+  | [port: number, callback?: () => void]
+  | [path: string, callback?: () => void]
+
+export type NormalizedNetConnectArgs = [
+  options: NetworkConnectionOptions,
+  callback: (() => void) | null,
+]
+
+/**
+ * Normalizes the arguments passed to `net.connect()`.
+ */
+export function normalizeNetConnectArgs(
+  args: NetConnectArgs
+): NormalizedNetConnectArgs {
+  if (args.length === 0) {
+    return [{ path: '' }, null]
+  }
+
+  const callback = typeof args[1] === 'function' ? args[1] : args[2] || null
+
+  if (typeof args[0] === 'string') {
+    return [{ path: args[0] }, callback]
+  }
+
+  if (typeof args[0] === 'number') {
+    return [
+      {
+        port: args[0],
+        path: '',
+        /**
+         * @note The host is optional in the "(port[, host][, callback])"
+         * signatures and defaults to "localhost" in Node.js.
+         */
+        host: typeof args[1] === 'string' ? args[1] : undefined,
+      },
+      callback,
+    ]
+  }
+
+  if (typeof args[0] === 'object') {
+    /**
+     * @note URL arguments receive no special treatment on purpose.
+     * Node.js does not support them and reads a given URL as a plain
+     * options object (e.g. "url.port" is a string, "url.host" includes
+     * the port). The "port" branch below reproduces that reading.
+     */
+    if ('port' in args[0]) {
+      return [
+        {
+          path: '',
+          port: Reflect.get(args[0], 'port'),
+          host: Reflect.get(args[0], 'host'),
+          auth: Reflect.get(args[0], 'auth'),
+          family: Reflect.get(args[0], 'family'),
+          hints: Reflect.get(args[0], 'hints'),
+          session: Reflect.get(args[0], 'session'),
+          localAddress: Reflect.get(args[0], 'localAddress'),
+          localPort: Reflect.get(args[0], 'localPort'),
+          timeout: Reflect.get(args[0], 'timeout'),
+          lookup: Reflect.get(args[0], 'lookup'),
+          allowHalfOpen: Reflect.get(args[0], 'allowHalfOpen'),
+          noDelay: Reflect.get(args[0], 'noDelay'),
+          keepAlive: Reflect.get(args[0], 'keepAlive'),
+          keepAliveInitialDelay: Reflect.get(args[0], 'keepAliveInitialDelay'),
+          autoSelectFamily: Reflect.get(args[0], 'autoSelectFamily'),
+          autoSelectFamilyAttemptTimeout: Reflect.get(
+            args[0],
+            'autoSelectFamilyAttemptTimeout'
+          ),
+        },
+        callback,
+      ]
+    }
+
+    return [
+      {
+        path: args[0].path || '',
+        family: Reflect.get(args[0], 'family'),
+        session: Reflect.get(args[0], 'session'),
+        auth: Reflect.get(args[0], 'auth'),
+        timeout: Reflect.get(args[0], 'timeout'),
+        allowHalfOpen: Reflect.get(args[0], 'allowHalfOpen'),
+      },
+      callback,
+    ]
+  }
+
+  throw new Error(`Invalid arguments passed to net.connect: ${args}`)
+}

package/src/interceptors/net/utils/normalize-tls-connect-args.ts

@@ -0,0 +1,50 @@
+import tls from 'node:tls'
+import {
+  type NetConnectArgs,
+  type NetworkConnectionOptions,
+  normalizeNetConnectArgs,
+} from './normalize-net-connect-args'
+
+type TlsConnectArgs =
+  | []
+  | [options: tls.ConnectionOptions, callback?: () => void]
+  | [url: URL, callback?: () => void]
+  | [port: number, options?: tls.ConnectionOptions, callback?: () => void]
+  | [
+      port: number,
+      host?: string,
+      options?: tls.ConnectionOptions,
+      callback?: () => void,
+    ]
+
+export type TlsConnectionOptions = tls.ConnectionOptions &
+  NetworkConnectionOptions
+
+type NormalizedTlsConnectionArgs = [
+  options: TlsConnectionOptions,
+  callback?: () => void,
+]
+
+export function normalizeTlsConnectArgs(
+  args: TlsConnectArgs
+): NormalizedTlsConnectionArgs {
+  /**
+   * @note Despite incorrect type definitions, "tls.connect()" has all the
+   * options of "net.connect()" and then those specific to TLS connections,
+   * like "session" or "socket".
+   * @see https://github.com/nodejs/node/blob/bdc8131fa78089b81b74dbff467365afb6536e6a/lib/internal/tls/wrap.js#L1615
+   */
+  const netConnectArgs = normalizeNetConnectArgs(args as NetConnectArgs)
+  const options = netConnectArgs[0] as TlsConnectionOptions
+  const callback = netConnectArgs[1]
+
+  if (args[0] !== null && typeof args[0] === 'object') {
+    Object.assign(options, args[0])
+  } else if (args[1] !== null && typeof args[1] === 'object') {
+    Object.assign(options, args[1])
+  } else if (args[2] !== null && typeof args[2] === 'object') {
+    Object.assign(options, args[2])
+  }
+
+  return callback ? [options, callback] : [options]
+}

package/src/presets/browser.ts

@@ -1,9 +1,9 @@
-import { FetchInterceptor } from '../interceptors/fetch'
-import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest'
+import { FetchInterceptor } from '../interceptors/fetch/web'
+import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest/web'
 
 /**
- * The default preset provisions the interception of requests
- * regardless of their type (fetch/XMLHttpRequest).
+ * A browser preset for the request interception regardless
+ * of their initiator (fetch, XMLHttpRequest).
  */
 export default [
   new FetchInterceptor(),

package/src/presets/node.ts

@@ -1,10 +1,10 @@
 import { ClientRequestInterceptor } from '../interceptors/ClientRequest'
-import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest'
-import { FetchInterceptor } from '../interceptors/fetch'
+import { XMLHttpRequestInterceptor } from '../interceptors/XMLHttpRequest/node'
+import { FetchInterceptor } from '../interceptors/fetch/node'
 
 /**
- * The default preset provisions the interception of requests
- * regardless of their type (http/https/XMLHttpRequest).
+ * A Node.js preset for the request interception regardless
+ * of their initiator (http, fetch, XMLHttpRequest).
  */
 export default [
   new ClientRequestInterceptor(),