undici 4.8.1 → 4.8.2

package/docs/api/ProxyAgent.md

@@ -0,0 +1,100 @@
+# Class: ProxyAgent
+
+Extends: `undici.Dispatcher`
+
+A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.
+
+## `new ProxyAgent([options])`
+
+Arguments:
+
+* **options** `ProxyAgentOptions` (required) - It extends the `Agent` options.
+
+Returns: `ProxyAgent`
+
+### Parameter: `ProxyAgentOptions`
+
+Extends: [`AgentOptions`](docs/api/Agent.md#parameter-agentoptions)
+
+* **uri** `string` (required) - It can be passed either by a string or a object containing `uri` as string.
+
+Examples:
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+// or
+const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
+```
+
+#### Example - Basic ProxyAgent instantiation
+
+This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
+import { ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+```
+
+#### Example - Basic Proxy Request with global agent dispatcher
+
+```js
+import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+const { statusCode, body } = await request('http://localhost:3000/foo')
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+#### Example - Basic Proxy Request with local agent dispatcher
+
+```js
+import { ProxyAgent, request } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+
+const {
+  statusCode,
+  body
+} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
+
+console.log('response received', statusCode) // response received 200
+
+for await (const data of body) {
+  console.log('data', data.toString('utf8')) // data foo
+}
+```
+
+### `ProxyAgent.close()`
+
+Closes the proxy agent and waits for registered pools and clients to also close before resolving.
+
+Returns: `Promise<void>`
+
+#### Example - clean up after tests are complete
+
+```js
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+
+const proxyAgent = new ProxyAgent('my.proxy.server')
+setGlobalDispatcher(proxyAgent)
+
+await proxyAgent.close()
+```
+
+### `ProxyAgent.dispatch(options, handlers)`
+
+Implements [`Agent.dispatch(options, handlers)`](docs/api/Agent.md#parameter-agentdispatchoptions).
+
+### `ProxyAgent.request(options[, callback])`
+
+See [`Dispatcher.request(options [, callback])`](docs/api/Dispatcher.md#clientrequestoptions--callback).

package/docs/best-practices/proxy.md

@@ -1,6 +1,9 @@
 # Connecting through a proxy
 
-Connecting through a proxy is possible by properly configuring the `Client` or `Pool` constructor and request.
+Connecting through a proxy is possible by:
+
+- Using [AgentProxy](docs/api/ProxyAgent.md).
+- Configuring `Client` or `Pool` constructor.
 
 The proxy url should be passed to the `Client` or `Pool` constructor, while the upstream server url
 should be added to every request call in the `path`.

package/index.d.ts

@@ -10,13 +10,14 @@ import MockClient = require('./types/mock-client')
 import MockPool = require('./types/mock-pool')
 import MockAgent = require('./types/mock-agent')
 import mockErrors = require('./types/mock-errors')
+import ProxyAgent from './types/proxy-agent'
 import { request, pipeline, stream, connect, upgrade } from './types/api'
 
 export * from './types/fetch'
 export * from './types/file'
 export * from './types/formdata'
 
-export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors }
+export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent }
 export default Undici
 
 declare function Undici(url: string, opts: Pool.Options): Pool

package/index.js

@@ -14,6 +14,7 @@ const MockClient = require('./lib/mock/mock-client')
 const MockAgent = require('./lib/mock/mock-agent')
 const MockPool = require('./lib/mock/mock-pool')
 const mockErrors = require('./lib/mock/mock-errors')
+const ProxyAgent = require('./lib/proxy-agent')
 
 const nodeVersion = process.versions.node.split('.')
 const nodeMajor = Number(nodeVersion[0])
@@ -26,6 +27,7 @@ module.exports.Client = Client
 module.exports.Pool = Pool
 module.exports.BalancedPool = BalancedPool
 module.exports.Agent = Agent
+module.exports.ProxyAgent = ProxyAgent
 
 module.exports.buildConnector = buildConnector
 module.exports.errors = errors

package/lib/client.js

@@ -397,76 +397,77 @@ class Client extends Dispatcher {
   }
 }
 
-const { resolve } = require('path')
-const { readFileSync } = require('fs')
 const constants = require('./llhttp/constants')
 const EMPTY_BUF = Buffer.alloc(0)
 
+let llhttpPromise
 let llhttpInstance
-function lazyllhttp () {
-  if (!llhttpInstance) {
-    let mod
-    try {
-      mod = new WebAssembly.Module(readFileSync(resolve(__dirname, './llhttp/llhttp_simd.wasm')))
-    } catch (e) {
-      /* istanbul ignore next */
+async function lazyllhttp () {
+  const { resolve } = require('path')
+  const { readFile } = require('fs').promises
 
-      // We could check if the error was caused by the simd option not
-      // being enabled, but the occurring of this other error
-      // * https://github.com/emscripten-core/emscripten/issues/11495
-      // got me to remove that check to avoid breaking Node 12.
-      mod = new WebAssembly.Module(readFileSync(resolve(__dirname, './llhttp/llhttp.wasm')))
-    }
+  let mod
+  try {
+    mod = await WebAssembly.compile(await readFile(resolve(__dirname, './llhttp/llhttp_simd.wasm')))
+  } catch (e) {
+    /* istanbul ignore next */
 
-    llhttpInstance = new WebAssembly.Instance(mod, {
-      env: {
-        /* eslint-disable camelcase */
+    // We could check if the error was caused by the simd option not
+    // being enabled, but the occurring of this other error
+    // * https://github.com/emscripten-core/emscripten/issues/11495
+    // got me to remove that check to avoid breaking Node 12.
+    mod = await WebAssembly.compile(await readFile(resolve(__dirname, './llhttp/llhttp.wasm')))
+  }
 
-        wasm_on_url: (p, at, len) => {
-          /* istanbul ignore next */
-          return 0
-        },
-        wasm_on_status: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onStatus(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_message_begin: (p) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onMessageBegin() || 0
-        },
-        wasm_on_header_field: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onHeaderField(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_header_value: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onHeaderValue(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_headers_complete: (p, statusCode, upgrade, shouldKeepAlive) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onHeadersComplete(statusCode, Boolean(upgrade), Boolean(shouldKeepAlive)) || 0
-        },
-        wasm_on_body: (p, at, len) => {
-          assert.strictEqual(currentParser.ptr, p)
-          const start = at - currentBufferPtr
-          const end = start + len
-          return currentParser.onBody(currentBufferRef.slice(start, end)) || 0
-        },
-        wasm_on_message_complete: (p) => {
-          assert.strictEqual(currentParser.ptr, p)
-          return currentParser.onMessageComplete() || 0
-        }
+  llhttpInstance = new WebAssembly.Instance(mod, {
+    env: {
+      /* eslint-disable camelcase */
 
-        /* eslint-enable camelcase */
+      wasm_on_url: (p, at, len) => {
+        /* istanbul ignore next */
+        return 0
+      },
+      wasm_on_status: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onStatus(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_message_begin: (p) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onMessageBegin() || 0
+      },
+      wasm_on_header_field: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onHeaderField(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_header_value: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onHeaderValue(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_headers_complete: (p, statusCode, upgrade, shouldKeepAlive) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onHeadersComplete(statusCode, Boolean(upgrade), Boolean(shouldKeepAlive)) || 0
+      },
+      wasm_on_body: (p, at, len) => {
+        assert.strictEqual(currentParser.ptr, p)
+        const start = at - currentBufferPtr
+        const end = start + len
+        return currentParser.onBody(currentBufferRef.slice(start, end)) || 0
+      },
+      wasm_on_message_complete: (p) => {
+        assert.strictEqual(currentParser.ptr, p)
+        return currentParser.onMessageComplete() || 0
       }
-    })
-  }
+
+      /* eslint-enable camelcase */
+    }
+  })
+
   return llhttpInstance
 }
 
@@ -480,10 +481,10 @@ const TIMEOUT_BODY = 2
 const TIMEOUT_IDLE = 3
 
 class Parser {
-  constructor (client, socket) {
+  constructor (client, socket, { exports }) {
     assert(Number.isFinite(client[kMaxHeadersSize]) && client[kMaxHeadersSize] > 0)
 
-    this.llhttp = lazyllhttp().exports
+    this.llhttp = exports
     this.ptr = this.llhttp.llhttp_alloc(constants.TYPE.RESPONSE)
     this.client = client
     this.socket = socket
@@ -1096,7 +1097,7 @@ function onSocketClose () {
   resume(client)
 }
 
-function connect (client) {
+async function connect (client) {
   assert(!client[kConnecting])
   assert(!client[kSocket])
 
@@ -1128,78 +1129,97 @@ function connect (client) {
     })
   }
 
-  client[kConnector]({
-    host,
-    hostname,
-    protocol,
-    port,
-    servername: client[kServerName]
-  }, function (err, socket) {
-    client[kConnecting] = false
-
-    if (err) {
-      if (channels.connectError.hasSubscribers) {
-        channels.connectError.publish({
-          connectParams: {
-            host,
-            hostname,
-            protocol,
-            port,
-            servername: client[kServerName]
-          },
-          connector: client[kConnector],
-          error: err
-        })
+  try {
+    if (!llhttpInstance) {
+      if (!llhttpPromise) {
+        llhttpPromise = lazyllhttp()
       }
+      await llhttpPromise
+      assert(llhttpInstance)
+      llhttpPromise = null
+    }
 
-      if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
-        assert(client[kRunning] === 0)
-        while (client[kPending] > 0 && client[kQueue][client[kPendingIdx]].servername === client[kServerName]) {
-          const request = client[kQueue][client[kPendingIdx]++]
-          errorRequest(client, request, err)
+    const socket = await new Promise((resolve, reject) => {
+      client[kConnector]({
+        host,
+        hostname,
+        protocol,
+        port,
+        servername: client[kServerName]
+      }, (err, socket) => {
+        if (err) {
+          reject(err)
+        } else {
+          resolve(socket)
         }
-      } else {
-        onError(client, err)
-      }
+      })
+    })
 
-      client.emit('connectionError', client[kUrl], [client], err)
-    } else {
-      assert(socket)
+    client[kConnecting] = false
 
-      client[kSocket] = socket
+    assert(socket)
 
-      socket[kNoRef] = false
-      socket[kWriting] = false
-      socket[kReset] = false
-      socket[kBlocking] = false
-      socket[kError] = null
-      socket[kParser] = new Parser(client, socket)
-      socket[kClient] = client
-      socket
-        .on('error', onSocketError)
-        .on('readable', onSocketReadable)
-        .on('end', onSocketEnd)
-        .on('close', onSocketClose)
-
-      if (channels.connected.hasSubscribers) {
-        channels.connected.publish({
-          connectParams: {
-            host,
-            hostname,
-            protocol,
-            port,
-            servername: client[kServerName]
-          },
-          connector: client[kConnector],
-          socket
-        })
-      }
+    client[kSocket] = socket
+
+    socket[kNoRef] = false
+    socket[kWriting] = false
+    socket[kReset] = false
+    socket[kBlocking] = false
+    socket[kError] = null
+    socket[kParser] = new Parser(client, socket, llhttpInstance)
+    socket[kClient] = client
+    socket
+      .on('error', onSocketError)
+      .on('readable', onSocketReadable)
+      .on('end', onSocketEnd)
+      .on('close', onSocketClose)
+
+    if (channels.connected.hasSubscribers) {
+      channels.connected.publish({
+        connectParams: {
+          host,
+          hostname,
+          protocol,
+          port,
+          servername: client[kServerName]
+        },
+        connector: client[kConnector],
+        socket
+      })
+    }
 
-      client.emit('connect', client[kUrl], [client])
+    client.emit('connect', client[kUrl], [client])
+  } catch (err) {
+    client[kConnecting] = false
+
+    if (channels.connectError.hasSubscribers) {
+      channels.connectError.publish({
+        connectParams: {
+          host,
+          hostname,
+          protocol,
+          port,
+          servername: client[kServerName]
+        },
+        connector: client[kConnector],
+        error: err
+      })
     }
 
-    resume(client)
-  })
+    if (err.code === 'ERR_TLS_CERT_ALTNAME_INVALID') {
+      assert(client[kRunning] === 0)
+      while (client[kPending] > 0 && client[kQueue][client[kPendingIdx]].servername === client[kServerName]) {
+        const request = client[kQueue][client[kPendingIdx]++]
+        errorRequest(client, request, err)
+      }
+    } else {
+      onError(client, err)
+    }
+
+    client.emit('connectionError', client[kUrl], [client], err)
+  }
+
+  resume(client)
 }
 
 function emitDrain (client) {

package/lib/core/symbols.js

@@ -40,5 +40,6 @@ module.exports = {
   kHostHeader: Symbol('host header'),
   kConnector: Symbol('connector'),
   kStrictContentLength: Symbol('strict content length'),
-  kMaxRedirections: Symbol('maxRedirections')
+  kMaxRedirections: Symbol('maxRedirections'),
+  kProxy: Symbol('proxy agent options')
 }

package/lib/proxy-agent.js

@@ -0,0 +1,59 @@
+'use strict'
+
+const { kClients, kProxy } = require('./core/symbols')
+const url = require('url')
+const Agent = require('./agent')
+const Dispatcher = require('./dispatcher')
+const { InvalidArgumentError } = require('./core/errors')
+
+const kAgent = Symbol('proxy agent')
+
+class ProxyAgent extends Dispatcher {
+  constructor (opts) {
+    super(opts)
+    this[kProxy] = buildProxyOptions(opts)
+
+    const agent = new Agent(opts)
+    this[kAgent] = agent
+
+    this[kClients] = agent[kClients]
+  }
+
+  dispatch (opts, handler) {
+    const { host } = url.parse(opts.origin)
+    return this[kAgent].dispatch(
+      {
+        ...opts,
+        origin: this[kProxy].uri,
+        path: opts.origin + opts.path,
+        headers: {
+          ...opts.headers,
+          host
+        },
+      },
+      handler
+    )
+  }
+
+  async close () {
+    await this[kAgent].close()
+    this[kClients].clear()
+  }
+}
+
+function buildProxyOptions(opts) {
+  if (typeof opts === 'string') {
+    opts = { uri: opts }
+  }
+
+  if (!opts || !opts.uri) {
+    throw new InvalidArgumentError('Proxy opts.uri is mandatory')
+  }
+
+  return {
+    uri: opts.uri,
+    protocol: opts.protocol || 'https'
+  }
+}
+
+module.exports = ProxyAgent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "undici",
-  "version": "4.8.1",
+  "version": "4.8.2",
   "description": "An HTTP/1.1 client, written from scratch for Node.js",
   "homepage": "https://undici.nodejs.org",
   "bugs": {

package/types/proxy-agent.d.ts

@@ -0,0 +1,17 @@
+import Agent = require('./agent')
+import Dispatcher = require('./dispatcher')
+
+export = ProxyAgent
+
+declare class ProxyAgent extends Dispatcher {
+  constructor(options: ProxyAgent.Options | string)
+
+  dispatch(options: Agent.DispatchOptions, handler: Dispatcher.DispatchHandlers): void;
+  close(): Promise<void>;
+}
+
+declare namespace ProxyAgent {
+  export interface Options extends Agent.Options {
+    uri: string;
+  }
+}