codekingpro/portable-devtools

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 | URL` (required) - The URI of the proxy server.  This can be provided as a string, as an instance of the URL class, or as an object with a `uri` property of type string.
20If the `uri` is provided as a string or `uri` is an object with an `uri` property of type string, then it will be parsed into a `URL` object according to the [WHATWG URL Specification](https://url.spec.whatwg.org).
21For detailed information on the parsing process and potential validation errors, please refer to the ["Writing" section](https://url.spec.whatwg.org/#writing) of the WHATWG URL Specification.
22* **token** `string` (optional) - It can be passed by a string of token for authentication.
23* **auth** `string` (**deprecated**) - Use token.
24* **clientFactory** `(origin: URL, opts: Object) => Dispatcher` (optional) - Default: `(origin, opts) => new Pool(origin, opts)`
25* **requestTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the request. It extends from [`Client#ConnectOptions`](/docs/docs/api/Client.md#parameter-connectoptions).
26* **proxyTls** `BuildOptions` (optional) - Options object passed when creating the underlying socket via the connector builder for the proxy server. It extends from [`Client#ConnectOptions`](/docs/docs/api/Client.md#parameter-connectoptions).
27* **proxyTunnel** `boolean` (optional) - For connections involving secure protocols, Undici will always establish a tunnel via the HTTP2  CONNECT extension. If proxyTunnel is set to true, this will occur for unsecured proxy/endpoint connections as well. Currently, there is no way to facilitate HTTP1 IP tunneling as described in https://www.rfc-editor.org/rfc/rfc9484.html#name-http-11-request. If proxyTunnel is set to false (the default), ProxyAgent connections where both the Proxy and Endpoint are unsecured will issue all requests to the Proxy, and prefix the endpoint request path with the endpoint origin address.
28
29Examples:
30
31```js
32import { ProxyAgent } from 'undici'
33
34const proxyAgent = new ProxyAgent('my.proxy.server')
35// or
36const proxyAgent = new ProxyAgent(new URL('my.proxy.server'))
37// or
38const proxyAgent = new ProxyAgent({ uri: 'my.proxy.server' })
39```
40
41#### Example - Basic ProxyAgent instantiation
42
43This will instantiate the ProxyAgent. It will not do anything until registered as the agent to use with requests.
44
45```js
46import { ProxyAgent } from 'undici'
47
48const proxyAgent = new ProxyAgent('my.proxy.server')
49```
50
51#### Example - Basic Proxy Request with global agent dispatcher
52
53```js
54import { setGlobalDispatcher, request, ProxyAgent } from 'undici'
55
56const proxyAgent = new ProxyAgent('my.proxy.server')
57setGlobalDispatcher(proxyAgent)
58
59const { statusCode, body } = await request('http://localhost:3000/foo')
60
61console.log('response received', statusCode) // response received 200
62
63for await (const data of body) {
64  console.log('data', data.toString('utf8')) // data foo
65}
66```
67
68#### Example - Basic Proxy Request with local agent dispatcher
69
70```js
71import { ProxyAgent, request } from 'undici'
72
73const proxyAgent = new ProxyAgent('my.proxy.server')
74
75const {
76  statusCode,
77  body
78} = await request('http://localhost:3000/foo', { dispatcher: proxyAgent })
79
80console.log('response received', statusCode) // response received 200
81
82for await (const data of body) {
83  console.log('data', data.toString('utf8')) // data foo
84}
85```
86
87#### Example - Basic Proxy Request with authentication
88
89```js
90import { setGlobalDispatcher, request, ProxyAgent } from 'undici';
91
92const proxyAgent = new ProxyAgent({
93  uri: 'my.proxy.server',
94  // token: 'Bearer xxxx'
95  token: `Basic ${Buffer.from('username:password').toString('base64')}`
96});
97setGlobalDispatcher(proxyAgent);
98
99const { statusCode, body } = await request('http://localhost:3000/foo');
100
101console.log('response received', statusCode); // response received 200
102
103for await (const data of body) {
104  console.log('data', data.toString('utf8')); // data foo
105}
106```
107
108### `ProxyAgent.close()`
109
110Closes the proxy agent and waits for registered pools and clients to also close before resolving.
111
112Returns: `Promise<void>`
113
114#### Example - clean up after tests are complete
115
116```js
117import { ProxyAgent, setGlobalDispatcher } from 'undici'
118
119const proxyAgent = new ProxyAgent('my.proxy.server')
120setGlobalDispatcher(proxyAgent)
121
122await proxyAgent.close()
123```
124
125### `ProxyAgent.dispatch(options, handlers)`
126
127Implements [`Agent.dispatch(options, handlers)`](Agent.md#parameter-agentdispatchoptions).
128
129### `ProxyAgent.request(options[, callback])`
130
131See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
132