{ "type": "module", "source": "doc/api/api-proxyagent.md", "modules": [ { "textRaw": "Class: ProxyAgent", "name": "class:_proxyagent", "type": "module", "desc": "

Extends: undici.Dispatcher

\n

A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.

", "signatures": [ { "textRaw": "`new ProxyAgent([options])`", "name": "ProxyAgent", "type": "ctor", "params": [ { "name": "options", "optional": true } ], "desc": "

Arguments:

\n\n

Returns: ProxyAgent

", "modules": [ { "textRaw": "Parameter: `ProxyAgentOptions`", "name": "parameter:_`proxyagentoptions`", "type": "module", "desc": "

Extends: AgentOptions

\n
\n

It ommits AgentOptions#connect.

\n
\n
\n

Note: When AgentOptions#connections is set, and different from 0, the non-standard proxy-connection header will be set to keep-alive in the request.

\n
\n\n

Examples:

\n
import { ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n// or\nconst proxyAgent = new ProxyAgent(new URL('my.proxy.server'))\n// or\nconst proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })\n// or\nconst proxyAgent = new ProxyAgent({\n  uri: new URL('my.proxy.server'),\n  proxyTls: {\n    signal: AbortSignal.timeout(1000)\n  }\n})\n
", "modules": [ { "textRaw": "Example - Basic ProxyAgent instantiation", "name": "example_-_basic_proxyagent_instantiation", "type": "module", "desc": "

This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.

\n
import { ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n
", "displayName": "Example - Basic ProxyAgent instantiation" }, { "textRaw": "Example - Basic Proxy Request with global agent dispatcher", "name": "example_-_basic_proxy_request_with_global_agent_dispatcher", "type": "module", "desc": "
import { setGlobalDispatcher, request, ProxyAgent } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\nsetGlobalDispatcher(proxyAgent)\n\nconst { statusCode, body } = await request('http://localhost:3000/foo')\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n  console.log('data', data.toString('utf8')) // data foo\n}\n
", "displayName": "Example - Basic Proxy Request with global agent dispatcher" }, { "textRaw": "Example - Basic Proxy Request with local agent dispatcher", "name": "example_-_basic_proxy_request_with_local_agent_dispatcher", "type": "module", "desc": "
import { ProxyAgent, request } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\n\nconst {\n  statusCode,\n  body\n} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })\n\nconsole.log('response received', statusCode) // response received 200\n\nfor await (const data of body) {\n  console.log('data', data.toString('utf8')) // data foo\n}\n
", "displayName": "Example - Basic Proxy Request with local agent dispatcher" }, { "textRaw": "Example - Basic Proxy Request with authentication", "name": "example_-_basic_proxy_request_with_authentication", "type": "module", "desc": "
import { setGlobalDispatcher, request, ProxyAgent } from 'undici';\n\nconst proxyAgent = new ProxyAgent({\n  uri: 'my.proxy.server',\n  // token: 'Bearer xxxx'\n  token: `Basic ${Buffer.from('username:password').toString('base64')}`\n});\nsetGlobalDispatcher(proxyAgent);\n\nconst { statusCode, body } = await request('http://localhost:3000/foo');\n\nconsole.log('response received', statusCode); // response received 200\n\nfor await (const data of body) {\n  console.log('data', data.toString('utf8')); // data foo\n}\n
", "displayName": "Example - Basic Proxy Request with authentication" } ], "displayName": "Parameter: `ProxyAgentOptions`" } ], "methods": [ { "textRaw": "`ProxyAgent.close()`", "name": "close", "type": "method", "signatures": [ { "params": [] } ], "desc": "

Closes the proxy agent and waits for registered pools and clients to also close before resolving.

\n

Returns: Promise<void>

", "modules": [ { "textRaw": "Example - clean up after tests are complete", "name": "example_-_clean_up_after_tests_are_complete", "type": "module", "desc": "
import { ProxyAgent, setGlobalDispatcher } from 'undici'\n\nconst proxyAgent = new ProxyAgent('my.proxy.server')\nsetGlobalDispatcher(proxyAgent)\n\nawait proxyAgent.close()\n
", "displayName": "Example - clean up after tests are complete" } ] }, { "textRaw": "`ProxyAgent.dispatch(options, handlers)`", "name": "dispatch", "type": "method", "signatures": [ { "params": [ { "name": "options" }, { "name": "handlers" } ] } ], "desc": "

Implements Agent.dispatch(options, handlers).

" }, { "textRaw": "`ProxyAgent.request(options[, callback])`", "name": "request", "type": "method", "signatures": [ { "params": [ { "name": "options" }, { "name": "callback", "optional": true } ] } ], "desc": "

See Dispatcher.request(options [, callback]).

", "modules": [ { "textRaw": "Example - ProxyAgent with Fetch", "name": "example_-_proxyagent_with_fetch", "type": "module", "desc": "

This example demonstrates how to use fetch with a proxy via ProxyAgent. It is particularly useful for scenarios requiring proxy tunneling.

\n
import { ProxyAgent, fetch } from 'undici';\n\n// Define the ProxyAgent\nconst proxyAgent = new ProxyAgent('http://localhost:8000');\n\n// Make a GET request through the proxy\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
\n
", "displayName": "Example - ProxyAgent with Fetch" }, { "textRaw": "Example - ProxyAgent with a Custom Proxy Server", "name": "example_-_proxyagent_with_a_custom_proxy_server", "type": "module", "desc": "

This example shows how to create a custom proxy server and use it with ProxyAgent.

\n
import * as http from 'node:http';\nimport { createProxy } from 'proxy';\nimport { ProxyAgent, fetch } from 'undici';\n\n// Create a proxy server\nconst proxyServer = createProxy(http.createServer());\nproxyServer.listen(8000, () => {\n  console.log('Proxy server running on port 8000');\n});\n\n// Define and use the ProxyAgent\nconst proxyAgent = new ProxyAgent('http://localhost:8000');\n\nconst response = await fetch('http://example.com', {\n  dispatcher: proxyAgent,\n  method: 'GET',\n});\n\nconsole.log('Response status:', response.status);\nconsole.log('Response data:', await response.text());\n
\n
", "displayName": "Example - ProxyAgent with a Custom Proxy Server" }, { "textRaw": "Example - ProxyAgent with HTTPS Tunneling", "name": "example_-_proxyagent_with_https_tunneling", "type": "module", "desc": "

This example demonstrates how to perform HTTPS tunneling using a proxy.

\n
import { ProxyAgent, fetch } from 'undici';\n\n// Define a ProxyAgent for HTTPS proxy\nconst proxyAgent = new ProxyAgent('https://secure.proxy.server');\n\n// Make a request to an HTTPS endpoint via the proxy\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 - ProxyAgent with HTTPS Tunneling" }, { "textRaw": "Example - ProxyAgent as a Global Dispatcher", "name": "example_-_proxyagent_as_a_global_dispatcher", "type": "module", "desc": "

ProxyAgent can be configured as a global dispatcher, making it available for all requests without explicitly passing it. This simplifies code and is useful when a single proxy configuration applies to all requests.

\n
import { ProxyAgent, setGlobalDispatcher, fetch } from 'undici';\n\n// Define and configure the ProxyAgent\nconst proxyAgent = new ProxyAgent('http://localhost:8000');\nsetGlobalDispatcher(proxyAgent);\n\n// Make requests without specifying the dispatcher\nconst response = await fetch('http://example.com');\nconsole.log('Response status:', response.status);\nconsole.log('Response data:', await response.text());\n
", "displayName": "Example - ProxyAgent as a Global Dispatcher" } ] } ] } ], "displayName": "Class: ProxyAgent" } ] }