@yanglaofish/fishtools 0.5.2 → 0.5.3

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

@@ -1,101 +1,69 @@
-# EnvHttpProxyAgent
+# Class: EnvHttpProxyAgent
 
-<!--introduced_in=v6.14.0-->
+Stability: Experimental.
 
-<!--type=module-->
+Extends: `undici.Dispatcher`
 
-<!-- source_link=lib/dispatcher/env-http-proxy-agent.js -->
+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.
 
-> Stability: 2 - Stable
+`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.
 
-`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`:
+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.
 
-```mjs
+## `new EnvHttpProxyAgent([options])`
+
+Arguments:
+
+* **options** `EnvHttpProxyAgentOptions` (optional) - extends the `Agent` options.
+
+Returns: `EnvHttpProxyAgent`
+
+### Parameter: `EnvHttpProxyAgentOptions`
+
+Extends: [`AgentOptions`](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
 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' })
 ```
 
-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
+#### Example - EnvHttpProxyAgent instantiation
+
+This will instantiate the EnvHttpProxyAgent. It will not do anything until registered as the agent to use with requests.
+
+```js
 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
+#### Example - Basic Proxy Fetch with global agent dispatcher
 
-```mjs
+```js
 import { setGlobalDispatcher, fetch, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 setGlobalDispatcher(envHttpProxyAgent)
 
-const response = await fetch('http://localhost:3000/foo')
+const { status, json } = await fetch('http://localhost:3000/foo')
 
-console.log('response received', response.status) // response received 200
+console.log('response received', status) // response received 200
 
-const data = await response.json() // data { foo: 'bar' }
+const data = await json() // data { foo: "bar" }
 ```
 
-#### Example - Proxied `request()` with the global dispatcher
+#### Example - Basic Proxy Request with global agent dispatcher
 
-```mjs
+```js
 import { setGlobalDispatcher, request, EnvHttpProxyAgent } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
@@ -110,16 +78,17 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Proxied `request()` with a local dispatcher
+#### Example - Basic Proxy Request with local agent dispatcher
 
-```mjs
+```js
 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
 
@@ -128,44 +97,66 @@ for await (const data of body) {
 }
 ```
 
-#### Example - Proxied `fetch()` with a local dispatcher
+#### Example - Basic Proxy Fetch with local agent dispatcher
 
-```mjs
+```js
 import { EnvHttpProxyAgent, fetch } from 'undici'
 
 const envHttpProxyAgent = new EnvHttpProxyAgent()
 
-const response = await fetch('http://localhost:3000/foo', {
-  dispatcher: envHttpProxyAgent
-})
+const {
+  status,
+  json
+} = await fetch('http://localhost:3000/foo', { dispatcher: envHttpProxyAgent })
 
-console.log('response received', response.status) // response received 200
+console.log('response received', status) // response received 200
 
-const data = await response.json() // data { foo: 'bar' }
+const data = await json() // data { foo: "bar" }
 ```
 
-### `envHttpProxyAgent.dispatch(options, handler)`
+## Instance Methods
+
+### `EnvHttpProxyAgent.close([callback])`
+
+Implements [`Dispatcher.close([callback])`](Dispatcher.md#dispatcherclosecallback-promise).
+
+### `EnvHttpProxyAgent.destroy([error, callback])`
+
+Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.dispatch(options, handler: AgentDispatchOptions)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+
+#### Parameter: `AgentDispatchOptions`
+
+Extends: [`DispatchOptions`](Dispatcher.md#parameter-dispatchoptions)
+
+* **origin** `string | URL`
+* **maxRedirections** `Integer`.
+
+Implements [`Dispatcher.destroy([error, callback])`](Dispatcher.md#dispatcherdestroyerror-callback-promise).
+
+### `EnvHttpProxyAgent.connect(options[, callback])`
+
+See [`Dispatcher.connect(options[, callback])`](Dispatcher.md#dispatcherconnectoptions-callback).
+
+### `EnvHttpProxyAgent.dispatch(options, handler)`
+
+Implements [`Dispatcher.dispatch(options, handler)`](Dispatcher.md#dispatcherdispatchoptions-handler).
+
+### `EnvHttpProxyAgent.pipeline(options, handler)`
+
+See [`Dispatcher.pipeline(options, handler)`](Dispatcher.md#dispatcherpipelineoptions-handler).
+
+### `EnvHttpProxyAgent.request(options[, callback])`
 
-<!-- YAML
-added: v6.14.0
--->
+See [`Dispatcher.request(options [, callback])`](Dispatcher.md#dispatcherrequestoptions-callback).
 
-* `options` {AgentDispatchOptions}
-  * `origin` {string|URL}
-* `handler` {DispatchHandler}
-* Returns: {boolean}
+### `EnvHttpProxyAgent.stream(options, 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`][].
+See [`Dispatcher.stream(options, factory[, callback])`](Dispatcher.md#dispatcherstreamoptions-factory-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.
+### `EnvHttpProxyAgent.upgrade(options[, callback])`
 
-[`Agent`]: Agent.md#class-agent
-[`Dispatcher`]: Dispatcher.md#class-dispatcher
-[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
-[`dispatcher.request()`]: Dispatcher.md#dispatcherrequestoptions-callback
+See [`Dispatcher.upgrade(options[, callback])`](Dispatcher.md#dispatcherupgradeoptions-callback).