@noodleseed/one 0.22.0 → 0.24.0

package/node_modules/undici/docs/docs/api/EnvHttpProxyAgent.md

@@ -1,52 +1,85 @@
-# Class: EnvHttpProxyAgent
+# EnvHttpProxyAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v6.14.0-->
 
-EnvHttpProxyAgent automatically reads the proxy configuration from the environment variables `http_proxy`, `https_proxy`, and `no_proxy` and sets up the proxy agents accordingly. When `http_proxy` and `https_proxy` are set, `http_proxy` is used for HTTP requests and `https_proxy` is used for HTTPS requests. If only `http_proxy` is set, `http_proxy` is used for both HTTP and HTTPS requests. If only `https_proxy` is set, it is only used for HTTPS requests.
+<!--type=module-->
 
-`no_proxy` is a comma or space-separated list of hostnames that should not be proxied. The list may contain leading wildcard characters (`*`). If `no_proxy` is set, the EnvHttpProxyAgent will bypass the proxy for requests to hosts that match the list. If `no_proxy` is set to `"*"`, the EnvHttpProxyAgent will bypass the proxy for all requests.
+<!-- source_link=lib/dispatcher/env-http-proxy-agent.js -->
 
-Uppercase environment variables are also supported: `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`. However, if both the lowercase and uppercase environment variables are set, the uppercase environment variables will be ignored.
+> Stability: 2 - Stable
 
-## `new EnvHttpProxyAgent([options])`
+`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`:
 
-Arguments:
-
-* **options** `EnvHttpProxyAgentOptions` (optional) - extends the `Agent` options.
-
-Returns: `EnvHttpProxyAgent`
-
-### Parameter: `EnvHttpProxyAgentOptions`
-
-Extends: [`AgentOptions`](/docs/docs/api/Agent.md#parameter-agentoptions)
-
-* **httpProxy** `string` (optional) - When set, it will override the `HTTP_PROXY` environment variable.
-* **httpsProxy** `string` (optional) - When set, it will override the `HTTPS_PROXY` environment variable.
-* **noProxy** `string` (optional) - When set, it will override the `NO_PROXY` environment variable.
-
-Examples:
-
-```js
+```mjs
 import { EnvHttpProxyAgent } from 'undici'
-
-const envHttpProxyAgent = new EnvHttpProxyAgent()
-// or
-const envHttpProxyAgent = new EnvHttpProxyAgent({ httpProxy: 'my.proxy.server:8080', httpsProxy: 'my.proxy.server:8443', noProxy: 'localhost' })
 ```
 
-#### Example - EnvHttpProxyAgent instantiation
-
-This will instantiate the EnvHttpProxyAgent. It will not do anything until registered as the agent to use with requests.
-
-```js
+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. 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 - Basic Proxy Fetch with global agent dispatcher
+#### Example - Proxied `fetch()` with the global dispatcher
 
-```js
+```mjs
 import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
@@ -56,12 +89,12 @@ 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" }
+const data = await response.json() // data { foo: 'bar' }
 ```
 
-#### Example - Basic Proxy Request with global agent dispatcher
+#### Example - Proxied `request()` with the global dispatcher
 
-```js
+```mjs
 import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
@@ -76,17 +109,16 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Proxy Request with local agent dispatcher
+#### Example - Proxied `request()` with a local dispatcher
 
-```js
+```mjs
 import { EnvHttpProxyAgent, request } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: envHttpProxyAgent
+})
 
 console.log('response received', statusCode) // response received 200
 
@@ -95,62 +127,44 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Basic Proxy Fetch with local agent dispatcher
+#### Example - Proxied `fetch()` with a local dispatcher
 
-```js
+```mjs
 import { EnvHttpProxyAgent, fetch } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 
-const response = await fetch('http://localhost:3000/foo', { dispatcher: 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" }
+const data = await response.json() // data { foo: 'bar' }
 ```
 
-## Instance Methods
-
-### `EnvHttpProxyAgent.close([callback])`
-
-Implements [`Dispatcher.close([callback])`](/docs/docs/api/Dispatcher.md#dispatcherclosecallback-promise).
-
-### `EnvHttpProxyAgent.destroy([error, callback])`
-
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
-
-### `EnvHttpProxyAgent.dispatch(options, handler: AgentDispatchOptions)`
-
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
-
-#### Parameter: `AgentDispatchOptions`
-
-Extends: [`DispatchOptions`](/docs/docs/api/Dispatcher.md#parameter-dispatchoptions)
-
-* **origin** `string | URL`
-
-Implements [`Dispatcher.destroy([error, callback])`](/docs/docs/api/Dispatcher.md#dispatcherdestroyerror-callback-promise).
-
-### `EnvHttpProxyAgent.connect(options[, callback])`
-
-See [`Dispatcher.connect(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherconnectoptions-callback).
-
-### `EnvHttpProxyAgent.dispatch(options, handler)`
-
-Implements [`Dispatcher.dispatch(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handler).
-
-### `EnvHttpProxyAgent.pipeline(options, handler)`
-
-See [`Dispatcher.pipeline(options, handler)`](/docs/docs/api/Dispatcher.md#dispatcherpipelineoptions-handler).
-
-### `EnvHttpProxyAgent.request(options[, callback])`
+### `envHttpProxyAgent.dispatch(options, handler)`
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+<!-- YAML
+added: v6.14.0
+-->
 
-### `EnvHttpProxyAgent.stream(options, factory[, callback])`
+* `options` {AgentDispatchOptions}
+  * `origin` {string|URL}
+* `handler` {DispatchHandler}
+* Returns: {boolean}
 
-See [`Dispatcher.stream(options, factory[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherstreamoptions-factory-callback).
+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`][].
 
-### `EnvHttpProxyAgent.upgrade(options[, callback])`
+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.
 
-See [`Dispatcher.upgrade(options[, callback])`](/docs/docs/api/Dispatcher.md#dispatcherupgradeoptions-callback).
+[`Agent`]: Agent.md#class-agent
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
+[`dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback