172 lines
5.6 KiB
Plaintext
172 lines
5.6 KiB
Plaintext
# EnvHttpProxyAgent
|
|
|
|
<!--introduced_in=v6.14.0-->
|
|
|
|
<!--type=module-->
|
|
|
|
<!-- source_link=lib/dispatcher/env-http-proxy-agent.js -->
|
|
|
|
> Stability: 2 - Stable
|
|
|
|
`EnvHttpProxyAgent` is a [`Dispatcher`][] that reads its proxy configuration from
|
|
the `http_proxy`, `https_proxy`, and `no_proxy` environment variables and routes
|
|
requests through the appropriate proxy automatically. Import it from `undici`:
|
|
|
|
```mjs
|
|
import { EnvHttpProxyAgent } from 'undici'
|
|
```
|
|
|
|
When `http_proxy` and `https_proxy` are both set, `http_proxy` is used for HTTP
|
|
requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is
|
|
set, it is used for both HTTP and HTTPS requests. If only `https_proxy` is set,
|
|
it is used only for HTTPS requests.
|
|
|
|
`no_proxy` is a comma- or space-separated list of hosts that must not be
|
|
proxied. Each entry may include a leading dot or `*.` wildcard (for example
|
|
`.example.com`) to match subdomains, and an optional `:port` suffix to restrict
|
|
the match to a specific port. A request bypasses the proxy when its host equals
|
|
an entry or is a subdomain of one. A trailing dot is ignored on both sides, so
|
|
`example.com.` and `example.com` match each other. Setting `no_proxy` to `*`
|
|
bypasses the proxy for every request.
|
|
|
|
The uppercase variants `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are also
|
|
honored. When both the lowercase and uppercase forms of a variable are set, the
|
|
lowercase form takes precedence and the uppercase form is ignored. The `no_proxy`
|
|
value is re-read from the environment on demand, so changes to it after the agent
|
|
is created take effect on subsequent requests; this does not apply when `noProxy`
|
|
is passed as an option.
|
|
|
|
## Class: `EnvHttpProxyAgent`
|
|
|
|
<!-- YAML
|
|
added: v6.14.0
|
|
-->
|
|
|
|
* Extends: {Dispatcher}
|
|
|
|
### `new EnvHttpProxyAgent([options])`
|
|
|
|
<!-- YAML
|
|
added: v6.14.0
|
|
-->
|
|
|
|
* `options` {EnvHttpProxyAgentOptions} Extends the [`ProxyAgent`][] options
|
|
(except `uri`). (optional)
|
|
* `httpProxy` {string} When set, overrides the `http_proxy` and `HTTP_PROXY`
|
|
environment variables. (optional)
|
|
* `httpsProxy` {string} When set, overrides the `https_proxy` and
|
|
`HTTPS_PROXY` environment variables. (optional)
|
|
* `noProxy` {string} When set, overrides the `no_proxy` and `NO_PROXY`
|
|
environment variables. (optional)
|
|
* Returns: {EnvHttpProxyAgent}
|
|
|
|
Creates a new `EnvHttpProxyAgent`. Any options other than `httpProxy`,
|
|
`httpsProxy`, and `noProxy` are forwarded to the underlying [`Agent`][] and
|
|
[`ProxyAgent`][] instances. Constructing the agent only configures it; it does
|
|
not affect any request until it is registered as a dispatcher, either globally
|
|
with `setGlobalDispatcher()` or per-request through the `dispatcher` option.
|
|
|
|
```mjs
|
|
import { EnvHttpProxyAgent } from 'undici'
|
|
|
|
const envHttpProxyAgent = new EnvHttpProxyAgent()
|
|
// or, overriding the environment variables explicitly:
|
|
const envHttpProxyAgentWithOpts = new EnvHttpProxyAgent({
|
|
httpProxy: 'my.proxy.server:8080',
|
|
httpsProxy: 'my.proxy.server:8443',
|
|
noProxy: 'localhost'
|
|
})
|
|
```
|
|
|
|
#### Example - Proxied `fetch()` with the global dispatcher
|
|
|
|
```mjs
|
|
import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
|
|
|
|
const envHttpProxyAgent = new EnvHttpProxyAgent()
|
|
setGlobalDispatcher(envHttpProxyAgent)
|
|
|
|
const response = await fetch('http://localhost:3000/foo')
|
|
|
|
console.log('response received', response.status) // response received 200
|
|
|
|
const data = await response.json() // data { foo: 'bar' }
|
|
```
|
|
|
|
#### Example - Proxied `request()` with the global dispatcher
|
|
|
|
```mjs
|
|
import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
|
|
|
|
const envHttpProxyAgent = new EnvHttpProxyAgent()
|
|
setGlobalDispatcher(envHttpProxyAgent)
|
|
|
|
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 - Proxied `request()` with a local dispatcher
|
|
|
|
```mjs
|
|
import { EnvHttpProxyAgent, request } from 'undici'
|
|
|
|
const envHttpProxyAgent = new EnvHttpProxyAgent()
|
|
|
|
const { statusCode, body } = await request('http://localhost:3000/foo', {
|
|
dispatcher: envHttpProxyAgent
|
|
})
|
|
|
|
console.log('response received', statusCode) // response received 200
|
|
|
|
for await (const data of body) {
|
|
console.log('data', data.toString('utf8')) // data foo
|
|
}
|
|
```
|
|
|
|
#### Example - Proxied `fetch()` with a local dispatcher
|
|
|
|
```mjs
|
|
import { EnvHttpProxyAgent, fetch } from 'undici'
|
|
|
|
const envHttpProxyAgent = new EnvHttpProxyAgent()
|
|
|
|
const response = await fetch('http://localhost:3000/foo', {
|
|
dispatcher: envHttpProxyAgent
|
|
})
|
|
|
|
console.log('response received', response.status) // response received 200
|
|
|
|
const data = await response.json() // data { foo: 'bar' }
|
|
```
|
|
|
|
### `envHttpProxyAgent.dispatch(options, handler)`
|
|
|
|
<!-- YAML
|
|
added: v6.14.0
|
|
-->
|
|
|
|
* `options` {AgentDispatchOptions}
|
|
* `origin` {string|URL}
|
|
* `handler` {DispatchHandler}
|
|
* Returns: {boolean}
|
|
|
|
Dispatches a request through the proxy selected for `options.origin`. The origin's
|
|
protocol, host, and port are compared against the `no_proxy` configuration: when
|
|
the host should be proxied, the request is routed to the HTTPS proxy agent for
|
|
`https:` origins or the HTTP proxy agent otherwise; when the host is excluded by
|
|
`no_proxy`, the request is sent directly through a non-proxying [`Agent`][].
|
|
|
|
This method is not normally called directly. Use the higher-level
|
|
[`Dispatcher`][] methods such as [`dispatcher.request()`][] or the top-level
|
|
`request()` and `fetch()` helpers instead.
|
|
|
|
[`Agent`]: Agent.md#class-agent
|
|
[`Dispatcher`]: Dispatcher.md#class-dispatcher
|
|
[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
|
|
[`dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
|