nock 14.0.12 → 15.0.0-beta.10

package/README.md

@@ -53,6 +53,7 @@ For instance, if a module performs HTTP requests to a CouchDB server or makes HT
   - [Request Headers Matching](#request-headers-matching)
   - [Optional Requests](#optional-requests)
   - [Allow **unmocked** requests on a mocked hostname](#allow-unmocked-requests-on-a-mocked-hostname)
+  - [Passthrough requests](#passthrough-requests)
 - [Expectations](#expectations)
   - [.isDone()](#isdone)
   - [.cleanAll()](#cleanall)
@@ -911,6 +912,44 @@ const scope = nock('http://my.existing.service.com', { allowUnmocked: true })
 
 > Note: When applying `{allowUnmocked: true}`, if the request is made to the real server, no interceptor is removed.
 
+### Passthrough requests
+
+For more granular control over which requests should hit the real server, you can use `passthrough()`. While `allowUnmocked` lets through any request that doesn't match an interceptor, `passthrough()` lets you specify exactly which requests go through the HTTP stack.
+
+```js
+const scope = nock('http://my.existing.service.com')
+  .get('/mock')
+  .reply(200, { users: ['fake'] })
+  .post('/live')
+  .passthrough()
+
+// GET /mock => goes through nock
+// POST /live => actually makes request to the server
+```
+
+You can use `passthrough()` with query strings, header matching, and other interceptor features:
+
+```js
+nock('http://my.existing.service.com')
+  .get('/api/data')
+  .query({ live: 'true' })
+  .matchHeader('authorization', /^Bearer /)
+  .passthrough()
+```
+
+Like other interceptors, passthrough interceptors are consumed when matched. They work with modifiers like `times()`, `persist()`, and `optionally()`:
+
+```js
+// Passthrough the first 3 requests, then fail
+nock('http://example.com').get('/').times(3).passthrough()
+
+// Passthrough indefinitely
+nock('http://example.com').persist().get('/').passthrough()
+
+// Don't fail scope.done() if this is never called
+nock('http://example.com').get('/maybe').optionally().passthrough()
+```
+
 ## Expectations
 
 Every time an HTTP request is performed for a scope that is mocked, Nock expects to find a handler for it. If it doesn't, it will throw an error.
@@ -1311,7 +1350,7 @@ nock.removeInterceptor({
   hostname: 'localhost',
   path: '/mockedResource',
   // method defaults to `GET`
-  // proto defaullts to `http`
+  // proto defaults to `http`
 })
 ```
 
@@ -1353,9 +1392,39 @@ A scope emits the following events:
 You can also listen for no match events like this:
 
 ```js
-nock.emitter.on('no match', req => {})
+nock.emitter.on('no match', (req, interceptorResults) => {
+  console.log('Request did not match any interceptors:', req.url)
+
+  if (interceptorResults && interceptorResults.length > 0) {
+    interceptorResults.forEach(({ interceptor, reasons }) => {
+      console.log(
+        'Interceptor:',
+        interceptor.method,
+        interceptor.basePath + interceptor.path,
+      )
+      console.log('Reasons:', reasons)
+    })
+  }
+})
 ```
 
+The callback receives two parameters:
+
+- `req` - The request object that didn't match
+- `interceptorResults` - An array of objects containing detailed information about each interceptor that was tested.
+  Each object contains:
+  - `interceptor` - The interceptor that was tested against the request
+  - `reasons` - An array of strings describing why the request didn't match this interceptor
+    > ⚠️ **Experimental**: The structure and format of the detailed mismatch information may change in future versions as we gather user feedback and refine the API. The feature itself is stable and ready for use and we're seeking community input on the API design before marking it stable.
+
+Common mismatch reasons include:
+
+- **Method mismatch**: `"Method mismatch: expected GET, got POST"`
+- **Path mismatch**: `"Path mismatch: expected /api/users, got /api/posts"`
+- **Header mismatch**: `"Header mismatch: expected authorization to match Bearer token, got null"`
+- **Body mismatch**: `"Body mismatch: expected "expected body", got actual body"`
+- **Query mismatch**: `"query matching failed"`
+
 ## Nock Back
 
 Fixture recording support and playback.

package/index.js

@@ -17,6 +17,7 @@ const {
 } = require('./lib/intercept')
 const recorder = require('./lib/recorder')
 const { Scope, load, loadDefs, define } = require('./lib/scope')
+const { getGetRequestBody } = require('./lib/utils/node')
 
 module.exports = (basePath, options) => new Scope(basePath, options)
 
@@ -42,6 +43,7 @@ Object.assign(module.exports, {
   },
   restore: recorder.restore,
   back,
+  getGetRequestBody,
 })
 
 // We always activate Nock on import, overriding the globals.

package/lib/back.js

@@ -1,6 +1,7 @@
 'use strict'
 
-const assert = require('assert')
+const fs = require('node:fs')
+const assert = require('node:assert')
 const recorder = require('./recorder')
 const {
   activate,
@@ -10,19 +11,11 @@ const {
 } = require('./intercept')
 const { loadDefs, define } = require('./scope')
 const { back: debug } = require('./debug')
-const { format } = require('util')
-const path = require('path')
+const { format } = require('node:util')
+const path = require('node:path')
 
 let _mode = null
 
-let fs
-
-try {
-  fs = require('fs')
-} catch (err) {
-  // do nothing, probably in browser
-}
-
 /**
  * nock the current function with the fixture given
  *
@@ -198,7 +191,7 @@ const update = {
     return context
   },
 
-  finish: function (fixture, options, context) {
+  finish: function (fixture, options) {
     let outputs = recorder.outputs()
 
     if (typeof options.afterRecord === 'function') {
@@ -271,7 +264,7 @@ function load(fixture, options) {
   return context
 }
 
-function removeFixture(fixture, options) {
+function removeFixture(fixture) {
   const context = {
     scopes: [],
     assertScopesFinished: function () {},

package/lib/common.js

@@ -1,10 +1,9 @@
 'use strict'
 
 const { common: debug } = require('./debug')
-const timers = require('timers')
-const url = require('url')
-const util = require('util')
-const http = require('http')
+const timers = require('node:timers')
+const util = require('node:util')
+const zlib = require('node:zlib')
 
 /**
  * Normalizes the request options so that it always has `host` property.
@@ -42,49 +41,48 @@ function normalizeRequestOptions(options) {
  * Returns true if the data contained in buffer can be reconstructed
  * from its utf8 representation.
  *
- * @param  {Object} buffer - a Buffer object
+ * @param  {ArrayBuffer} buffer
  * @returns {boolean}
  */
 function isUtf8Representable(buffer) {
-  const utfEncodedBuffer = buffer.toString('utf8')
-  const reconstructedBuffer = Buffer.from(utfEncodedBuffer, 'utf8')
-  return reconstructedBuffer.equals(buffer)
+  try {
+    new TextDecoder('utf8', { fatal: true }).decode(buffer)
+    return true
+  } catch {
+    return false
+  }
 }
 
 /**
  * In WHATWG URL vernacular, this returns the origin portion of a URL.
  * However, the port is not included if it's standard and not already present on the host.
+ *
+ * @param {URL} url
  */
-function normalizeOrigin(proto, host, port) {
-  const hostHasPort = host.includes(':')
-  const portIsStandard =
-    (proto === 'http' && (port === 80 || port === '80')) ||
-    (proto === 'https' && (port === 443 || port === '443'))
-  const portStr = hostHasPort || portIsStandard ? '' : `:${port}`
-
-  return `${proto}://${host}${portStr}`
+function normalizeOrigin(url) {
+  // Remove brackets from hostname if IPV6
+  const normalizedOrigin = url.hostname.startsWith('[')
+    ? `${url.protocol}//${url.hostname.slice(1, -1)}${url.port ? `:${url.port}` : ''}`
+    : url.origin
+  if (url.port) {
+    return normalizedOrigin
+  } else {
+    return normalizedOrigin + (url.protocol === 'http:' ? ':80' : ':443')
+  }
 }
 
 /**
  * Get high level information about request as string
- * @param  {Object} options
- * @param  {string} options.method
- * @param  {number|string} options.port
- * @param  {string} options.proto Set internally. always http or https
- * @param  {string} options.hostname
- * @param  {string} options.path
- * @param  {Object} options.headers
+ * @param  {Request} request
  * @param  {string} body
- * @return {string}
  */
-function stringifyRequest(options, body) {
-  const { method = 'GET', path = '', port } = options
-  const origin = normalizeOrigin(options.proto, options.hostname, port)
+function stringifyRequest(request, body) {
+  const url = new URL(request.url)
 
   const log = {
-    method,
-    url: `${origin}${path}`,
-    headers: options.headers,
+    method: request.method,
+    url: `${url.origin}${url.pathname}`,
+    headers: Object.fromEntries(request.headers.entries()),
   }
 
   if (body) {
@@ -99,14 +97,22 @@ function isContentEncoded(headers) {
   return typeof contentEncoding === 'string' && contentEncoding !== ''
 }
 
+/**
+ * @param {Headers} headers
+ * @param {'gzip' | 'deflate'} encoder
+ * @returns
+ */
 function contentEncoding(headers, encoder) {
-  const contentEncoding = headers['content-encoding']
-  return contentEncoding !== undefined && contentEncoding.toString() === encoder
+  const contentEncoding = headers.get('content-encoding')
+  return contentEncoding?.toString() === encoder
 }
 
+/**
+ * @param {Headers} headers
+ */
 function isJSONContent(headers) {
   // https://tools.ietf.org/html/rfc8259
-  const contentType = String(headers['content-type'] || '').toLowerCase()
+  const contentType = String(headers.get('content-type') || '').toLowerCase()
   return contentType.startsWith('application/json')
 }
 
@@ -320,7 +326,7 @@ function forEachHeader(rawHeaders, callback) {
 function percentDecode(str) {
   try {
     return decodeURIComponent(str.replace(/\+/g, ' '))
-  } catch (e) {
+  } catch {
     return str
   }
 }
@@ -409,65 +415,6 @@ function isStream(obj) {
   )
 }
 
-/**
- * Converts the arguments from the various signatures of http[s].request into a standard
- * options object and an optional callback function.
- *
- * https://nodejs.org/api/http.html#http_http_request_url_options_callback
- *
- * Taken from the beginning of the native `ClientRequest`.
- * https://github.com/nodejs/node/blob/908292cf1f551c614a733d858528ffb13fb3a524/lib/_http_client.js#L68
- */
-function normalizeClientRequestArgs(input, options, cb) {
-  if (typeof input === 'string') {
-    input = urlToOptions(new url.URL(input))
-  } else if (input instanceof url.URL) {
-    input = urlToOptions(input)
-  } else {
-    cb = options
-    options = input
-    input = null
-  }
-
-  if (typeof options === 'function') {
-    cb = options
-    options = input || {}
-  } else {
-    options = Object.assign(input || {}, options)
-  }
-
-  return { options, callback: cb }
-}
-
-/**
- * Utility function that converts a URL object into an ordinary
- * options object as expected by the http.request and https.request APIs.
- *
- * This was copied from Node's source
- * https://github.com/nodejs/node/blob/908292cf1f551c614a733d858528ffb13fb3a524/lib/internal/url.js#L1257
- */
-function urlToOptions(url) {
-  const options = {
-    protocol: url.protocol,
-    hostname:
-      typeof url.hostname === 'string' && url.hostname.startsWith('[')
-        ? url.hostname.slice(1, -1)
-        : url.hostname,
-    hash: url.hash,
-    search: url.search,
-    pathname: url.pathname,
-    path: `${url.pathname}${url.search || ''}`,
-    href: url.href,
-  }
-  if (url.port !== '') {
-    options.port = Number(url.port)
-  }
-  if (url.username || url.password) {
-    options.auth = `${url.username}:${url.password}`
-  }
-  return options
-}
-
 /**
  * Determines if request data matches the expected schema.
  *
@@ -526,7 +473,6 @@ const wrapTimer =
   (callback, ...timerArgs) => {
     const cb = (...callbackArgs) => {
       try {
-        // eslint-disable-next-line n/no-callback-literal
         callback(...callbackArgs)
       } finally {
         ids.delete(id)
@@ -551,59 +497,6 @@ function removeAllTimers() {
   clearTimer(clearImmediate, immediates)
 }
 
-/**
- * Check if the Client Request has been cancelled.
- *
- * Until Node 14 is the minimum, we need to look at both flags to see if the request has been cancelled.
- * The two flags have the same purpose, but the Node maintainers are migrating from `abort(ed)` to
- * `destroy(ed)` terminology, to be more consistent with `stream.Writable`.
- * In Node 14.x+, Calling `abort()` will set both `aborted` and `destroyed` to true, however,
- * calling `destroy()` will only set `destroyed` to true.
- * Falling back on checking if the socket is destroyed to cover the case of Node <14.x where
- * `destroy()` is called, but `destroyed` is undefined.
- *
- * Node Client Request history:
- * - `request.abort()`: Added in: v0.3.8, Deprecated since: v14.1.0, v13.14.0
- * - `request.aborted`: Added in: v0.11.14, Became a boolean instead of a timestamp: v11.0.0, Not deprecated (yet)
- * - `request.destroy()`: Added in: v0.3.0
- * - `request.destroyed`: Added in: v14.1.0, v13.14.0
- *
- * @param {ClientRequest} req
- * @returns {boolean}
- */
-function isRequestDestroyed(req) {
-  return !!(
-    req.destroyed === true ||
-    req.aborted ||
-    (req.socket && req.socket.destroyed)
-  )
-}
-
-/**
- * @param {Request} request
- */
-function convertFetchRequestToClientRequest(request) {
-  const url = new URL(request.url)
-  const options = {
-    ...urlToOptions(url),
-    method: request.method,
-    host: url.hostname,
-    port: url.port || (url.protocol === 'https:' ? 443 : 80),
-    path: url.pathname + url.search,
-    proto: url.protocol.slice(0, -1),
-    headers: Object.fromEntries(request.headers.entries()),
-  }
-
-  // By default, Node adds a host header, but for maximum backward compatibility, we are now removing it.
-  // However, we need to consider leaving the header and fixing the tests.
-  if (options.headers.host === options.host) {
-    const { host, ...restHeaders } = options.headers
-    options.headers = restHeaders
-  }
-
-  return new http.ClientRequest(options)
-}
-
 /**
  * Returns true if the given value is a plain object and not an Array.
  * @param {*} value
@@ -682,8 +575,6 @@ const expand = input => {
           } else {
             resultPtr[part] = {}
           }
-        } else if (typeof resultPtr[part] !== 'object') {
-          return undefined
         }
         resultPtr = resultPtr[part]
       }
@@ -692,6 +583,40 @@ const expand = input => {
   return result
 }
 
+/**
+ * @param {ArrayBuffer} buffer
+ * @param {string} contentEncoding
+ */
+function decompressRequestBody(buffer, contentEncoding) {
+  const encodings = contentEncoding
+    .toLowerCase()
+    .split(',')
+    .map(coding => coding.trim())
+
+  for (const encoding of encodings) {
+    if (encoding === 'gzip') {
+      return zlib.gunzipSync(buffer)
+    } else if (encoding === 'deflate') {
+      return zlib.inflateSync(buffer)
+    } else if (encoding === 'br') {
+      return zlib.brotliDecompressSync(buffer)
+    }
+  }
+
+  return buffer
+}
+
+/**
+ * @param {Headers} headers
+ */
+function convertHeadersToRaw(headers) {
+  const rawHeaders = []
+  for (const [name, value] of headers.entries()) {
+    rawHeaders.push(name, value)
+  }
+  return rawHeaders
+}
+
 module.exports = {
   contentEncoding,
   dataEqual,
@@ -706,11 +631,9 @@ module.exports = {
   isContentEncoded,
   isJSONContent,
   isPlainObject,
-  isRequestDestroyed,
   isStream,
   isUtf8Representable,
   matchStringOrRegexp,
-  normalizeClientRequestArgs,
   normalizeOrigin,
   normalizeRequestOptions,
   percentDecode,
@@ -719,5 +642,6 @@ module.exports = {
   setImmediate,
   setTimeout,
   stringifyRequest,
-  convertFetchRequestToClientRequest,
+  decompressRequestBody,
+  convertHeadersToRaw,
 }

package/lib/create_response.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { STATUS_CODES } = require('http')
+const { STATUS_CODES } = require('node:http')
 
 /**
  * Creates a Fetch API `Response` instance from the given

package/lib/debug.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { debuglog } = require('util')
+const { debuglog } = require('node:util')
 
 module.exports.back = debuglog('nock:back')
 module.exports.common = debuglog('nock:common')

package/lib/global_emitter.js

@@ -1,5 +1,5 @@
 'use strict'
 
-const { EventEmitter } = require('events')
+const { EventEmitter } = require('node:events')
 
 module.exports = new EventEmitter()

package/lib/handle-request.js

@@ -0,0 +1,125 @@
+'use strict'
+const { inherits } = require('node:util')
+const globalEmitter = require('./global_emitter')
+const common = require('./common')
+const { playbackInterceptor } = require('./playback_interceptor')
+
+/**
+ * @param {Request} request
+ */
+async function handleRequest(request) {
+  const {
+    interceptorsFor,
+    isOn,
+    isEnabledForNetConnect,
+  } = require('./intercept')
+  const url = new URL(request.url)
+  const interceptors = interceptorsFor(url)
+
+  if (isOn() && interceptors) {
+    const matches = interceptors.some(interceptor =>
+      interceptor.matchOrigin(request),
+    )
+    const allowUnmocked = interceptors.some(
+      interceptor => interceptor.options.allowUnmocked,
+    )
+    if (!matches && allowUnmocked) {
+      globalEmitter.emit('no match', request)
+    } else {
+      const requestBodyBuffer = await request.clone().arrayBuffer()
+      // When request body is a binary buffer we internally use in its hexadecimal representation.
+      const requestBodyIsUtf8Representable =
+        common.isUtf8Representable(requestBodyBuffer)
+      const requestBodyString = Buffer.from(requestBodyBuffer).toString(
+        requestBodyIsUtf8Representable ? 'utf8' : 'hex',
+      )
+
+      const matchResults = []
+      const matchedInterceptor = interceptors.find(i => {
+        const reasons = i.match(request, requestBodyString)
+        if (reasons.length > 0) {
+          matchResults.push({ interceptor: i, reasons })
+          return false
+        } else {
+          return true
+        }
+      })
+
+      if (matchedInterceptor) {
+        matchedInterceptor.scope.logger(
+          'interceptor identified, starting mocking',
+        )
+
+        matchedInterceptor.markConsumed()
+
+        if (matchedInterceptor.isPassthrough) {
+          return
+        }
+
+        const response = await playbackInterceptor({
+          decompressedRequest: request,
+          requestBodyString,
+          interceptor: matchedInterceptor,
+          requestBodyIsUtf8Representable,
+        })
+
+        return response
+      } else {
+        globalEmitter.emit(
+          'no match',
+          request,
+          matchResults.sort((a, b) => a.reasons.length - b.reasons.length),
+        )
+
+        // Try to find a hostname match that allows unmocked.
+        const allowUnmocked = interceptors.some(
+          i => i.matchHostName(url.hostname) && i.options.allowUnmocked,
+        )
+
+        if (!allowUnmocked) {
+          const body = JSON.stringify({
+            code: 'ERR_NOCK_NO_MATCH',
+            message: `Nock: No match for request ${common.stringifyRequest(request, requestBodyString)}`,
+          })
+          return new Response(body, {
+            status: 501,
+            headers: { 'Content-Type': 'application/json' },
+          })
+        }
+      }
+    }
+  } else {
+    globalEmitter.emit('no match', request)
+    // Remove http(s):// for backward compatibility until we decide this Error.
+    const normalizedUrl = common
+      .normalizeOrigin(url)
+      .replace(`${url.protocol}//`, '')
+    if (isOn() && !isEnabledForNetConnect(normalizedUrl)) {
+      throw new NetConnectNotAllowedError(normalizedUrl, url.pathname)
+    }
+  }
+}
+
+/**
+ * @name NetConnectNotAllowedError
+ * @private
+ * @desc Error trying to make a connection when disabled external access.
+ * @class
+ * @example
+ * nock.disableNetConnect();
+ * http.get('http://zombo.com');
+ * // throw NetConnectNotAllowedError
+ */
+function NetConnectNotAllowedError(host, path) {
+  Error.call(this)
+
+  this.name = 'NetConnectNotAllowedError'
+  this.code = 'ENETUNREACH'
+  this.message = `Nock: Disallowed net connect for "${host}${path}"`
+
+  Error.captureStackTrace(this, this.constructor)
+}
+
+inherits(NetConnectNotAllowedError, Error)
+
+module.exports = handleRequest