@yanglaofish/fishtools 0.5.2 → 0.5.3

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

@@ -1,256 +0,0 @@
-# Socks5ProxyAgent
-
-<!--introduced_in=v7.23.0-->
-<!--type=module-->
-<!-- source_link=lib/dispatcher/socks5-proxy-agent.js -->
-
-> Stability: 1 - Experimental
-
-A [`Dispatcher`][] implementation that routes requests through a [SOCKS5][]
-proxy server. It tunnels both HTTP and HTTPS traffic over the proxy, supports
-optional username/password authentication, and pools connections per origin so
-that subsequent requests to the same host reuse the established tunnel.
-
-DNS resolution is delegated to the proxy: target host names are sent to the
-proxy as domain names rather than being resolved locally. For HTTPS targets the
-TLS session is negotiated end-to-end through the tunnel, so the proxy only sees
-encrypted bytes.
-
-Import it from `'undici'`:
-
-```mjs
-import { Socks5ProxyAgent } from 'undici'
-```
-
-Constructing the agent emits a one-time `ExperimentalWarning`, reflecting the
-experimental status of SOCKS5 support.
-
-## Class: `Socks5ProxyAgent`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* Extends: {Dispatcher}
-
-Routes dispatched requests through a SOCKS5 proxy. Register an instance as the
-global dispatcher with [`setGlobalDispatcher()`][], or pass it per request via
-the `dispatcher` option.
-
-### `new Socks5ProxyAgent(proxyUrl[, options])`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* `proxyUrl` {string|URL} The SOCKS5 proxy server URL. Must use the `socks5:` or
-  `socks:` protocol. Credentials may be embedded in the URL userinfo (for
-  example `socks5://user:pass@host:1080`).
-* `options` {Object} (optional) Extends {PoolOptions}; the pool options are
-  applied to the per-origin pools created behind the tunnel.
-  * `headers` {Object} Additional headers to send with the proxy connection.
-    **Default:** `{}`.
-  * `username` {string} Username for SOCKS5 authentication. Takes precedence over
-    a username embedded in `proxyUrl`. **Default:** the URL username, if any.
-  * `password` {string} Password for SOCKS5 authentication. Takes precedence over
-    a password embedded in `proxyUrl`. **Default:** the URL password, if any.
-  * `connect` {Function} Custom connector used to open the socket to the proxy.
-    **Default:** a connector built from `proxyTls`.
-  * `connectTimeout` {number} Maximum time in milliseconds for each proxy
-    connection, SOCKS5 negotiation, and target TLS negotiation stage. A value of
-    `0` disables these stage timeouts. `proxyTls.timeout` and
-    `requestTls.timeout` override it for their respective TLS stages.
-    **Default:** `5000`.
-  * `proxyTls` {BuildOptions} TLS options for the connection to the proxy itself
-    (SOCKS5 over TLS). When set, the proxy connection is established over TLS and
-    `servername` defaults to the proxy host name.
-  * `requestTls` {BuildOptions} TLS options applied to the end-to-end connection
-    to an HTTPS target through the tunnel, such as `ca`, `cert`, `key`,
-    `rejectUnauthorized`, and `servername`. `servername` defaults to the target
-    host name.
-
-Throws an `InvalidArgumentError` if `proxyUrl` is missing or does not use the
-`socks5:` or `socks:` protocol, or if `connectTimeout`, `proxyTls.timeout`, or
-`requestTls.timeout` is not a finite, non-negative number.
-
-```mjs
-import { Socks5ProxyAgent } from 'undici'
-
-// Without authentication.
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-
-// With credentials in the URL.
-const authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
-
-// With credentials and pool options.
-const configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {
-  username: 'user',
-  password: 'pass',
-  connections: 10
-})
-```
-
-Using the agent as the global dispatcher:
-
-```mjs
-import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(agent)
-
-const { statusCode, body } = await request('http://localhost:3000/foo')
-console.log('response received', statusCode)
-
-for await (const data of body) {
-  console.log('data', data.toString('utf8'))
-}
-```
-
-Using the agent per request:
-
-```mjs
-import { request, Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-
-const { statusCode, body } = await request('http://localhost:3000/foo', {
-  dispatcher: agent
-})
-
-console.log('response received', statusCode)
-```
-
-HTTPS targets are tunnelled and encrypted end-to-end:
-
-```mjs
-import { request, Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-
-const { statusCode, body } = await request('https://api.example.com/data', {
-  dispatcher: agent
-})
-
-console.log('Response status:', statusCode)
-console.log('Response data:', await body.json())
-```
-
-### `socks5ProxyAgent.close()`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* Returns: {Promise<void>} Resolves once every per-origin pool has been closed.
-
-Gracefully closes the agent, waiting for all underlying pools and their
-connections to drain and close before resolving.
-
-```mjs
-import { setGlobalDispatcher, Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(agent)
-
-// ... make requests ...
-
-await agent.close()
-```
-
-### `socks5ProxyAgent.destroy([err])`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* `err` {Error} (optional) The error to reject in-flight requests with.
-* Returns: {Promise<void>} Resolves once every per-origin pool has been
-  destroyed.
-
-Forcibly destroys the agent and all underlying connections immediately, without
-waiting for in-flight requests to complete.
-
-```mjs
-import { Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-
-await agent.destroy()
-```
-
-### `socks5ProxyAgent.dispatch(options, handlers)`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* `options` {DispatchOptions}
-* `handlers` {DispatchHandler}
-* Returns: {boolean} `false` if the dispatcher is busy and the request should be
-  retried later, otherwise `true`.
-
-Routes a request through the SOCKS5 tunnel. The agent maintains a [`Pool`][] per
-target origin; the first request to a given origin establishes the tunnel and
-upgrades to TLS when the target is HTTPS, and later requests reuse the pool.
-
-This is the lower-level entry point implementing
-[`Dispatcher.dispatch(options, handlers)`][]. Prefer
-[`socks5ProxyAgent.request()`][] for most use cases.
-
-### `socks5ProxyAgent.request(options[, callback])`
-
-<!-- YAML
-added: v7.23.0
--->
-
-> Stability: 1 - Experimental
-
-* `options` {DispatchOptions}
-* `callback` {Function} (optional)
-* Returns: {Promise|void} A promise resolving to the response when `callback` is
-  omitted.
-
-Performs a request through the SOCKS5 proxy. Inherited from
-[`Dispatcher.request(options[, callback])`][]; see that method for the full set
-of options and the shape of the resolved response.
-
-```mjs
-import { fetch, Socks5ProxyAgent } from 'undici'
-
-const agent = new Socks5ProxyAgent('socks5://localhost:1080')
-
-const response = await fetch('http://localhost:3000/api/users', {
-  dispatcher: agent
-})
-
-console.log('Response status:', response.status)
-console.log('Response data:', await response.text())
-```
-
-## Debugging
-
-SOCKS5 proxy activity can be traced with the `undici:socks5-proxy` debug scope:
-
-```bash
-NODE_DEBUG=undici:socks5-proxy node script.js
-```
-
-This logs the SOCKS5 handshake, authentication, and tunnel establishment steps.
-
-[SOCKS5]: https://www.rfc-editor.org/rfc/rfc1928
-[`Dispatcher.dispatch(options, handlers)`]: Dispatcher.md#dispatcherdispatchoptions-handler
-[`Dispatcher.request(options[, callback])`]: Dispatcher.md#dispatcherrequestoptions-callback
-[`Dispatcher`]: Dispatcher.md#class-dispatcher
-[`Pool`]: Pool.md#class-pool
-[`setGlobalDispatcher()`]: Dispatcher.md#setglobaldispatcherdispatcher
-[`socks5ProxyAgent.request()`]: #socks5proxyagentrequestoptions-callback

package/node_modules/undici/docs/docs/best-practices/migrating-from-v7-to-v8.md

@@ -1,233 +0,0 @@
-# Migrating from Undici 7 to 8
-
-<!--type=misc-->
-
-This guide covers the changes you are most likely to hit when upgrading an
-application or library from Undici v7 to v8.
-
-## Before you upgrade
-
-- Make sure your runtime is Node.js `>= 22.19.0`.
-- If you have custom dispatchers, interceptors, or handlers, review the
-  handler API changes before updating.
-- If you rely on HTTP/1.1-only behavior, plan to set `allowH2: false`
-  explicitly.
-
-## 1. Update your Node.js version
-
-Undici v8 requires Node.js `>= 22.19.0`.
-
-If you are still on Node.js 20 or an older Node.js 22 release, upgrade Node.js
-first:
-
-```bash
-node -v
-```
-
-If that command prints a version lower than `v22.19.0`, upgrade Node.js before
-installing Undici v8.
-
-## 2. Migrate custom dispatcher handlers to the v2 API
-
-Undici v8 uses the newer dispatcher handler API consistently.
-
-If you implemented custom dispatchers, interceptors, or wrappers around
-`dispatch()`, update legacy callbacks such as `onConnect`, `onHeaders`, and
-`onComplete` to the newer callback names.
-
-### Old handler callbacks vs. v8 callbacks
-
-| Undici 7 style | Undici 8 style |
-|---|---|
-| `onConnect(abort, context)` | `onRequestStart(controller, context)` |
-| `onHeaders(statusCode, rawHeaders, resume, statusText)` | `onResponseStart(controller, statusCode, headers, statusText)` |
-| `onData(chunk)` | `onResponseData(controller, chunk)` |
-| `onComplete(trailers)` | `onResponseEnd(controller, trailers)` |
-| `onError(err)` | `onResponseError(controller, err)` |
-| `onUpgrade(statusCode, rawHeaders, socket)` | `onRequestUpgrade(controller, statusCode, headers, socket)` |
-
-### Example
-
-Before:
-
-```js
-client.dispatch(options, {
-  onConnect (abort) {
-    this.abort = abort
-  },
-  onHeaders (statusCode, headers, resume) {
-    this.resume = resume
-    return true
-  },
-  onData (chunk) {
-    chunks.push(chunk)
-    return true
-  },
-  onComplete (trailers) {
-    console.log(trailers)
-  },
-  onError (err) {
-    console.error(err)
-  }
-})
-```
-
-After:
-
-```js
-client.dispatch(options, {
-  onRequestStart (controller) {
-    this.controller = controller
-  },
-  onResponseStart (controller, statusCode, headers, statusText) {
-    console.log(statusCode, statusText, headers)
-  },
-  onResponseData (controller, chunk) {
-    chunks.push(chunk)
-  },
-  onResponseEnd (controller, trailers) {
-    console.log(trailers)
-  },
-  onResponseError (controller, err) {
-    console.error(err)
-  }
-})
-```
-
-### Pause, resume, and abort now go through the controller
-
-In Undici v7, legacy handlers could return `false` or keep references to
-`abort()` and `resume()` callbacks. In Undici v8, use the controller instead:
-
-```js
-onRequestStart (controller) {
-  this.controller = controller
-}
-
-onResponseData (controller, chunk) {
-  controller.pause()
-  setImmediate(() => controller.resume())
-}
-
-onResponseError (controller, err) {
-  controller.abort(err)
-}
-```
-
-### Raw headers and trailers moved to the controller
-
-If you need the raw header arrays, read them from the controller:
-
-- `controller.rawHeaders`
-- `controller.rawTrailers`
-
-## 3. Update `onBodySent()` handlers
-
-If you implemented `onBodySent()`, note that its signature changed.
-
-Before, handlers received counters:
-
-```js
-onBodySent (chunkSize, totalBytesSent) {}
-```
-
-In Undici v8, handlers receive the actual chunk:
-
-```js
-onBodySent (chunk) {}
-```
-
-If you need a notification that the whole body has been sent, use
-`onRequestSent()`:
-
-```js
-onRequestSent () {
-  console.log('request body fully sent')
-}
-```
-
-## 4. If you need HTTP/1.1 only, disable HTTP/2 explicitly
-
-Undici v8 enables HTTP/2 by default when a TLS server negotiates it via ALPN.
-
-If your application depends on HTTP/1.1-specific behavior, set `allowH2: false`
-explicitly.
-
-Before:
-
-```js
-const client = new Client('https://example.com')
-```
-
-After, to keep HTTP/1.1 only:
-
-```js
-const client = new Client('https://example.com', {
-  allowH2: false
-})
-```
-
-The same applies when you configure an `Agent`:
-
-```js
-const agent = new Agent({
-  allowH2: false
-})
-```
-
-## 5. Use real `Blob` and `File` instances
-
-Undici v8 no longer accepts fake Blob-like values that only imitate `Blob` or
-`File` via properties such as `Symbol.toStringTag`.
-
-If you were passing custom objects that looked like `Blob`s, replace them with
-actual `Blob` or `File` instances:
-
-```js
-const body = new Blob(['hello'])
-```
-
-## 6. Avoid depending on the internal global dispatcher symbol
-
-`setGlobalDispatcher()` and `getGlobalDispatcher()` remain the public APIs and
-should continue to be used.
-
-Internally, Undici v8 stores its dispatcher under
-`Symbol.for('undici.globalDispatcher.2')` and mirrors a v1-compatible wrapper
-for legacy consumers such as Node.js built-in `fetch`.
-
-If your code was reading or writing `Symbol.for('undici.globalDispatcher.1')`
-directly, migrate to the public APIs instead:
-
-```js
-import { setGlobalDispatcher, getGlobalDispatcher, Agent } from 'undici'
-
-setGlobalDispatcher(new Agent())
-const dispatcher = getGlobalDispatcher()
-```
-
-If you must expose a dispatcher to legacy v1 handler consumers, wrap it with
-`Dispatcher1Wrapper`:
-
-```js
-import { Agent, Dispatcher1Wrapper } from 'undici'
-
-const legacyCompatibleDispatcher = new Dispatcher1Wrapper(new Agent())
-```
-
-## 7. Verify the upgrade
-
-After moving to Undici v8, it is worth checking these paths in your test suite:
-
-- requests that use a custom `dispatcher`
-- `setGlobalDispatcher()` behavior
-- any custom interceptor or retry handler
-- uploads that use `Blob`, `File`, or `FormData`
-- integrations that depend on HTTP/1.1-only behavior
-
-## Related documentation
-
-- [Dispatcher](../api/Dispatcher.md)
-- [Client](../api/Client.md)
-- [Global Installation](../api/GlobalInstallation.md)
-- [Undici Module vs. Node.js Built-in Fetch](./undici-vs-builtin-fetch.md)