{ "type": "module", "source": "doc/api/api-proxyagent.md", "modules": [ { "textRaw": "ProxyAgent", "name": "proxyagent", "introduced_in": "v4.8.2", "type": "module", "stability": 2, "stabilityText": "Stable", "desc": "

A ProxyAgent routes every request through an HTTP, HTTPS, or SOCKS5 proxy\nserver. It implements the Agent API, so it can be used wherever a\ndispatcher is accepted, for example with request or fetch, or\ninstalled globally with setGlobalDispatcher.

\n

For secure (https:) endpoints the proxy connection is established through an\nHTTP CONNECT tunnel. SOCKS5 proxies (socks5: or socks: URIs) are handled\nby delegating to a Socks5ProxyAgent.

\n
import { ProxyAgent, setGlobalDispatcher } from 'undici'\n\nconst proxyAgent = new ProxyAgent('http://localhost:8000')\nsetGlobalDispatcher(proxyAgent)\n
", "classes": [ { "textRaw": "Class: `ProxyAgent`", "name": "ProxyAgent", "type": "class", "meta": { "added": [ "v4.8.2" ], "changes": [] }, "desc": "\n

ProxyAgent keeps an internal Agent that creates per-origin dispatchers\non demand. The proxy connection is set up lazily when the first request to an\norigin is dispatched, then reused for subsequent requests to the same origin.

", "signatures": [ { "textRaw": "`new ProxyAgent(options)`", "name": "ProxyAgent", "type": "ctor", "meta": { "added": [ "v4.8.2" ], "changes": [] }, "params": [ { "textRaw": "`options` {ProxyAgentOptions|string|URL} The proxy URI, or an options object. Required. When a `string` or {URL} is passed it is used as the proxy `uri`. The options object extends {AgentOptions} (omitting `connect`).", "name": "options", "type": "ProxyAgentOptions|string|URL", "desc": "The proxy URI, or an options object. Required. When a `string` or {URL} is passed it is used as the proxy `uri`. The options object extends {AgentOptions} (omitting `connect`).", "options": [ { "textRaw": "`uri` {string} The URI of the proxy server. Required when `options` is an object. Parsed into a {URL} according to the WHATWG URL Specification.", "name": "uri", "type": "string", "desc": "The URI of the proxy server. Required when `options` is an object. Parsed into a {URL} according to the WHATWG URL Specification." }, { "textRaw": "`token` {string} A pre-formatted `proxy-authorization` header value sent to the proxy on every request, for example ``Bearer ${apiKey}``.", "name": "token", "type": "string", "desc": "A pre-formatted `proxy-authorization` header value sent to the proxy on every request, for example ``Bearer ${apiKey}``." }, { "textRaw": "`auth` {string} A base64-encoded `username:password` credential sent as a `Basic` `proxy-authorization` header. Cannot be combined with `token`.", "name": "auth", "type": "string", "desc": "A base64-encoded `username:password` credential sent as a `Basic` `proxy-authorization` header. Cannot be combined with `token`." }, { "textRaw": "`headers` {Object} Additional headers sent to the proxy server on the `CONNECT` request (or on every request for an untunneled HTTP proxy). **Default:** `{}`.", "name": "headers", "type": "Object", "default": "`{}`", "desc": "Additional headers sent to the proxy server on the `CONNECT` request (or on every request for an untunneled HTTP proxy)." }, { "textRaw": "`requestTls` {BuildOptions} TLS options for the connection to the request endpoint, passed to the connector builder.", "name": "requestTls", "type": "BuildOptions", "desc": "TLS options for the connection to the request endpoint, passed to the connector builder." }, { "textRaw": "`proxyTls` {BuildOptions} TLS options for the connection to the proxy server, passed to the connector builder.", "name": "proxyTls", "type": "BuildOptions", "desc": "TLS options for the connection to the proxy server, passed to the connector builder." }, { "textRaw": "`clientFactory` {Function} Builds the {Dispatcher} used to talk to the proxy server itself. **Default:** `(origin, opts) => new Pool(origin, opts)`.", "name": "clientFactory", "type": "Function", "default": "`(origin, opts) => new Pool(origin, opts)`", "desc": "Builds the {Dispatcher} used to talk to the proxy server itself.", "options": [ { "textRaw": "`origin` {URL} The proxy origin.", "name": "origin", "type": "URL", "desc": "The proxy origin." }, { "textRaw": "`opts` {Object} The resolved options for the dispatcher.", "name": "opts", "type": "Object", "desc": "The resolved options for the dispatcher." }, { "textRaw": "Returns: {Dispatcher}", "name": "return", "type": "Dispatcher" } ] }, { "textRaw": "`proxyTunnel` {boolean} Forces tunneling through the proxy. By default, Undici detects tunneling based on the request protocol. If the target endpoint uses HTTPS, Undici establishes a `CONNECT` tunnel through the proxy (after the TLS handshake to the proxy itself when the proxy URL is HTTPS). If the target endpoint uses plain HTTP, Undici forwards the request to the proxy using an HTTP/1.1 absolute-form request target (over TLS when the proxy URL is HTTPS), as required by RFC 9112 §3.2.2. This non-tunneled forwarding path does not negotiate HTTP/2 with the proxy. Set `proxyTunnel` to `true` to force tunneling for plain HTTP requests as well. Currently, there is no way to facilitate HTTP/1.1 IP tunneling as described in RFC 9484.", "name": "proxyTunnel", "type": "boolean", "desc": "Forces tunneling through the proxy. By default, Undici detects tunneling based on the request protocol. If the target endpoint uses HTTPS, Undici establishes a `CONNECT` tunnel through the proxy (after the TLS handshake to the proxy itself when the proxy URL is HTTPS). If the target endpoint uses plain HTTP, Undici forwards the request to the proxy using an HTTP/1.1 absolute-form request target (over TLS when the proxy URL is HTTPS), as required by RFC 9112 §3.2.2. This non-tunneled forwarding path does not negotiate HTTP/2 with the proxy. Set `proxyTunnel` to `true` to force tunneling for plain HTTP requests as well. Currently, there is no way to facilitate HTTP/1.1 IP tunneling as described in RFC 9484." } ] } ], "desc": "

Throws an <InvalidArgumentError> when no proxy URI is provided, when clientFactory is not a function, or when both auth and token are supplied.

\n

The proxy-authorization header is derived, in order of precedence, from\ntoken, then auth, then the username and password embedded in the proxy\nuri. Credentials in the URI are URL-decoded before being base64-encoded.

\n
\n

[!NOTE]\nUnless <AgentOptions> connections is set to 0, the non-standard\nproxy-connection: keep-alive header is added to the tunnel CONNECT\nrequest. This includes the default case where connections is unset.

\n
\n

The auth option is deprecated; use token instead.

\n
import { ProxyAgent } from 'undici'\n\n// A string or URL is treated as the proxy uri.\nconst a = new ProxyAgent('http://localhost:8000')\nconst b = new ProxyAgent(new URL('http://localhost:8000'))\n\n// An options object requires a `uri`.\nconst c = new ProxyAgent({ uri: 'http://localhost:8000' })\n\n// With proxy TLS settings.\nconst d = new ProxyAgent({\n  uri: 'https://secure.proxy.server',\n  proxyTls: {\n    signal: AbortSignal.timeout(1000),\n  },\n})\n
", "modules": [ { "textRaw": "Example - proxy request with the global dispatcher", "name": "example_-_proxy_request_with_the_global_dispatcher", "type": "module", "desc": "
import { setGlobalDispatcher, request, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('http://localhost:8000')\nsetGlobalDispatcher(proxyAgent)\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\nconsole.log('data', await body.text())\n
", "displayName": "Example - proxy request with the global dispatcher" }, { "textRaw": "Example - proxy request with a local dispatcher", "name": "example_-_proxy_request_with_a_local_dispatcher", "type": "module", "desc": "
import { ProxyAgent, request } from 'undici'\n\nconst proxyAgent = new ProxyAgent('http://localhost:8000')\n\nconst { statusCode, body } = await request('http://localhost:3000/foo', {\n  dispatcher: proxyAgent,\n})\n\nconsole.log('response received', statusCode)\nconsole.log('data', await body.text())\n
", "displayName": "Example - proxy request with a local dispatcher" }, { "textRaw": "Example - proxy request with authentication", "name": "example_-_proxy_request_with_authentication", "type": "module", "desc": "
import { setGlobalDispatcher, request, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent({\n  uri: 'http://localhost:8000',\n  token: `Basic ${Buffer.from('username:password').toString('base64')}`,\n})\nsetGlobalDispatcher(proxyAgent)\n\nconst { statusCode } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode)\n
", "displayName": "Example - proxy request with authentication" } ] } ], "methods": [ { "textRaw": "`proxyAgent.dispatch(options, handler)`", "name": "dispatch", "type": "method", "meta": { "added": [ "v4.8.2" ], "changes": [] }, "signatures": [ { "params": [ { "textRaw": "`options` {AgentDispatchOptions} Extends {DispatchOptions}.", "name": "options", "type": "AgentDispatchOptions", "desc": "Extends {DispatchOptions}.", "options": [ { "textRaw": "`origin` {string|URL} The origin to dispatch the request against. Required.", "name": "origin", "type": "string|URL", "desc": "The origin to dispatch the request against. Required." } ] }, { "textRaw": "`handler` {DispatchHandler}", "name": "handler", "type": "DispatchHandler" } ], "return": { "textRaw": "Returns: {boolean} `false` if the dispatcher is busy and the caller should wait for the `'drain'` event before dispatching again.", "name": "return", "type": "boolean", "desc": "`false` if the dispatcher is busy and the caller should wait for the `'drain'` event before dispatching again." } } ], "desc": "

Dispatches the request through the proxy. Throws an <InvalidArgumentError> if\nthe request headers contain a proxy-authorization header, which must instead\nbe supplied through the constructor's token or auth option. A host header\nis derived from options.origin when one is not already present. Implements\nDispatcher.dispatch().

" }, { "textRaw": "`proxyAgent.close()`", "name": "close", "type": "method", "meta": { "added": [ "v4.8.2" ], "changes": [ { "version": "v7.10.0", "pr-url": "https://github.com/nodejs/undici/pull/4180", "description": "Untunneled HTTP-to-HTTP proxy connections match `curl` behavior." } ] }, "signatures": [ { "params": [], "return": { "textRaw": "Returns: {Promise}", "name": "return", "type": "Promise" } } ], "desc": "

Closes the proxy agent and waits for its internal agent and proxy client (when\npresent) to close before resolving. Implements Dispatcher.close().

\n
import { ProxyAgent, setGlobalDispatcher } from 'undici'\n\nconst proxyAgent = new ProxyAgent('http://localhost:8000')\nsetGlobalDispatcher(proxyAgent)\n\nawait proxyAgent.close()\n
" }, { "textRaw": "`proxyAgent.request(options[, callback])`", "name": "request", "type": "method", "meta": { "added": [ "v5.0.0" ], "changes": [] }, "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

See Dispatcher.request(). The request is routed through the proxy.

", "modules": [ { "textRaw": "Example - proxy request with `fetch`", "name": "example_-_proxy_request_with_`fetch`", "type": "module", "desc": "
import { ProxyAgent, fetch } from 'undici'\n\nconst proxyAgent = new ProxyAgent('http://localhost:8000')\n\nconst response = await fetch('http://localhost:3000/foo', {\n  dispatcher: proxyAgent,\n  method: 'GET',\n})\n\nconsole.log('response status', response.status)\nconsole.log('response data', await response.text())\n
", "displayName": "Example - proxy request with `fetch`" }, { "textRaw": "Example - HTTPS tunneling", "name": "example_-_https_tunneling", "type": "module", "desc": "
import { ProxyAgent, fetch } from 'undici'\n\nconst proxyAgent = new ProxyAgent('https://secure.proxy.server')\n\nconst response = await fetch('https://secure.endpoint.com/api/data', {\n  dispatcher: proxyAgent,\n  method: 'GET',\n})\n\nconsole.log('response status', response.status)\nconsole.log('response data', await response.json())\n
", "displayName": "Example - HTTPS tunneling" } ] } ] } ] } ] }