1# Class: ProxyAgent
2
3Extends: `undici.Dispatcher`
4
5A Proxy Agent class that implements the Agent API. It allows the connection through proxy in a simple way.
6
7## `new ProxyAgent([options])`
8
9Arguments:
10
11* **options** `ProxyAgentOptions` (required) - It extends the `Agent` options.
12
13Returns: `ProxyAgent`
14
15### Parameter: `ProxyAgentOptions`
16
17Extends: [`AgentOptions`](Agent.md#parameter-agentoptions)
18
19* **uri** `string` (required) - It can be passed either by a string or a object containing `uri` as string.
20* **token** `string` (optional) - It can be passed by a string of token for authentication.
21* **auth** `string` (**deprecated**) - Use token.
22* **clientFactory** `(origin: URL, opts: Object) => Dispatcher` (optional) - Default: `(origin, opts) => new Pool(origin, opts)`
23* **requestTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the request. See [TLS](https://nodejs.org/api/tls.html#tlsconnectoptions-callback).
24* **proxyTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the proxy server. See [TLS](https://nodejs.org/api/tls.html#tlsconnectoptions-callback).
25
26Examples:
27
28```js
29import { ProxyAgent } from 'undici'
30
31const proxyAgent = new ProxyAgent('my.proxy.server')
32// or
33const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
34```
35
36#### Example - Basic ProxyAgent instantiation
37
38This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
39
40```js
41import { ProxyAgent } from 'undici'
42
43const proxyAgent = new ProxyAgent('my.proxy.server')
44```
45
46#### Example - Basic Proxy Request with global agent dispatcher
47
48```js
49import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
50
51const proxyAgent = new ProxyAgent('my.proxy.server')
52setGlobalDispatcher(proxyAgent)
53
54const { statusCode, body } = await request('http://localhost:3000/foo')
55
56console.log('response received', statusCode) // response received 200
57
58for await (const data of body) {
59  console.log('data', data.toString('utf8')) // data foo
60}
61```
62
63#### Example - Basic Proxy Request with local agent dispatcher
64
65```js
66import { ProxyAgent, request } from 'undici'
67
68const proxyAgent = new ProxyAgent('my.proxy.server')
69
70const {
71  statusCode,
72  body
73} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
74
75console.log('response received', statusCode) // response received 200
76
77for await (const data of body) {
78  console.log('data', data.toString('utf8')) // data foo
79}
80```
81
82#### Example - Basic Proxy Request with authentication
83
84```js
85import { setGlobalDispatcher, request, ProxyAgent } from 'undici';
86
87const proxyAgent = new ProxyAgent({
88  uri: 'my.proxy.server',
89  // token: 'Bearer xxxx'
90  token: `Basic ${Buffer.from('username:password').toString('base64')}`
91});
92setGlobalDispatcher(proxyAgent);
93
94const { statusCode, body } = await request('http://localhost:3000/foo');
95
96console.log('response received', statusCode); // response received 200
97
98for await (const data of body) {
99  console.log('data', data.toString('utf8')); // data foo
100}
101```
102
103### `ProxyAgent.close()`
104
105Closes the proxy agent and waits for registered pools and clients to also close before resolving.
106
107Returns: `Promise<void>`
108
109#### Example - clean up after tests are complete
110
111```js
112import { ProxyAgent, setGlobalDispatcher } from 'undici'
113
114const proxyAgent = new ProxyAgent('my.proxy.server')
115setGlobalDispatcher(proxyAgent)
116
117await proxyAgent.close()
118```
119
120### `ProxyAgent.dispatch(options, handlers)`
121
122Implements [`Agent.dispatch(options, handlers)`](Agent.md#parameter-agentdispatchoptions).
123
124### `ProxyAgent.request(options[, callback])`
125
126See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
127