@noodleseed/one 0.21.0 → 0.23.0

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

@@ -1,274 +1,250 @@
-# Class: Socks5ProxyAgent
+# Socks5ProxyAgent
 
-Extends: `undici.Dispatcher`
+<!--introduced_in=v7.23.0-->
+<!--type=module-->
+<!-- source_link=lib/dispatcher/socks5-proxy-agent.js -->
 
-A SOCKS5 proxy wrapper class that implements the Dispatcher API. It enables HTTP requests to be routed through a SOCKS5 proxy server, providing connection tunneling and authentication support.
+> Stability: 1 - Experimental
 
-## `new Socks5ProxyAgent(proxyUrl[, options])`
+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.
 
-Arguments:
+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.
 
-* **proxyUrl** `string | URL` (required) - The SOCKS5 proxy server URL. Must use `socks5://` or `socks://` protocol.
-* **options** `Socks5ProxyAgent.Options` (optional) - Additional configuration options.
+Import it from `'undici'`:
 
-Returns: `Socks5ProxyAgent`
-
-### Parameter: `Socks5ProxyAgent.Options`
-
-Extends: [`PoolOptions`](/docs/docs/api/Pool.md#parameter-pooloptions)
-
-* **headers** `IncomingHttpHeaders` (optional) - Additional headers to send with proxy connections.
-* **username** `string` (optional) - SOCKS5 proxy username for authentication. Can also be provided in the proxy URL.
-* **password** `string` (optional) - SOCKS5 proxy password for authentication. Can also be provided in the proxy URL.
-* **connect** `Function` (optional) - Custom connector function for the proxy connection.
-* **proxyTls** `BuildOptions` (optional) - TLS options for the proxy connection (when using SOCKS5 over TLS).
-
-Examples:
-
-```js
+```mjs
 import { Socks5ProxyAgent } from 'undici'
-
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-// or with authentication
-const socks5ProxyWithAuth = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
-// or with options
-const socks5ProxyWithOptions = new Socks5ProxyAgent('socks5://localhost:1080', {
-  username: 'user',
-  password: 'pass',
-  connections: 10
-})
 ```
 
-#### Example - Basic SOCKS5 Proxy instantiation
+Constructing the agent emits a one-time `ExperimentalWarning`, reflecting the
+experimental status of SOCKS5 support.
 
-This will instantiate the Socks5ProxyAgent. It will not do anything until registered as the dispatcher to use with requests.
+## Class: `Socks5ProxyAgent`
 
-```js
-import { Socks5ProxyAgent } from 'undici'
+<!-- YAML
+added: v7.23.0
+-->
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-```
+> Stability: 1 - Experimental
 
-#### Example - Basic SOCKS5 Proxy Request with global dispatcher
+* Extends: {Dispatcher}
 
-```js
-import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
+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.
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(socks5Proxy)
+### `new Socks5ProxyAgent(proxyUrl[, options])`
 
-const { statusCode, body } = await request('http://localhost:3000/foo')
+<!-- YAML
+added: v7.23.0
+-->
 
-console.log('response received', statusCode) // response received 200
+> Stability: 1 - Experimental
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
-```
-
-#### Example - Basic SOCKS5 Proxy Request with local dispatcher
+* `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`.
+  * `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.
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+Throws an `InvalidArgumentError` if `proxyUrl` is missing or does not use the
+`socks5:` or `socks:` protocol.
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+```mjs
+import { Socks5ProxyAgent } from 'undici'
 
-const {
-  statusCode,
-  body
-} = await request('http://localhost:3000/foo', { dispatcher: socks5Proxy })
+// Without authentication.
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-console.log('response received', statusCode) // response received 200
+// With credentials in the URL.
+const authAgent = new Socks5ProxyAgent('socks5://user:pass@localhost:1080')
 
-for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
-}
+// With credentials and pool options.
+const configuredAgent = new Socks5ProxyAgent('socks5://localhost:1080', {
+  username: 'user',
+  password: 'pass',
+  connections: 10
+})
 ```
 
-#### Example - SOCKS5 Proxy Request with authentication
+Using the agent as the global dispatcher:
 
-```js
+```mjs
 import { setGlobalDispatcher, request, Socks5ProxyAgent } from 'undici'
 
-// Authentication via URL
-const socks5Proxy = new Socks5ProxyAgent('socks5://username:password@localhost:1080')
-
-// Or authentication via options
-// const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {
-//   username: 'username',
-//   password: 'password'
-// })
-
-setGlobalDispatcher(socks5Proxy)
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
+setGlobalDispatcher(agent)
 
 const { statusCode, body } = await request('http://localhost:3000/foo')
-
-console.log('response received', statusCode) // response received 200
+console.log('response received', statusCode)
 
 for await (const data of body) {
-  console.log('data', data.toString('utf8')) // data foo
+  console.log('data', data.toString('utf8'))
 }
 ```
 
-#### Example - SOCKS5 Proxy with HTTPS requests
-
-SOCKS5 proxy supports both HTTP and HTTPS requests through tunneling:
+Using the agent per request:
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+```mjs
+import { request, Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-const response = await request('https://api.example.com/data', {
-  dispatcher: socks5Proxy,
-  method: 'GET'
+const { statusCode, body } = await request('http://localhost:3000/foo', {
+  dispatcher: agent
 })
 
-console.log('Response status:', response.statusCode)
-console.log('Response data:', await response.body.json())
+console.log('response received', statusCode)
 ```
 
-#### Example - SOCKS5 Proxy with Fetch
+HTTPS targets are tunnelled and encrypted end-to-end:
 
-```js
-import { Socks5ProxyAgent, fetch } from 'undici'
+```mjs
+import { request, Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-const response = await fetch('http://localhost:3000/api/users', {
-  dispatcher: socks5Proxy,
-  method: 'GET'
+const { statusCode, body } = await request('https://api.example.com/data', {
+  dispatcher: agent
 })
 
-console.log('Response status:', response.status)
-console.log('Response data:', await response.text())
+console.log('Response status:', statusCode)
+console.log('Response data:', await body.json())
 ```
 
-#### Example - Connection Pooling
+### `socks5ProxyAgent.close()`
 
-SOCKS5ProxyWrapper automatically manages connection pooling for better performance:
+<!-- YAML
+added: v7.23.0
+-->
 
-```js
-import { Socks5ProxyAgent, request } from 'undici'
+> Stability: 1 - Experimental
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080', {
-  connections: 10, // Allow up to 10 concurrent connections
-  pipelining: 1    // Enable HTTP/1.1 pipelining
-})
+* Returns: {Promise<void>} Resolves once every per-origin pool has been closed.
 
-// Multiple requests will reuse connections through the SOCKS5 tunnel
-const responses = await Promise.all([
-  request('http://api.example.com/endpoint1', { dispatcher: socks5Proxy }),
-  request('http://api.example.com/endpoint2', { dispatcher: socks5Proxy }),
-  request('http://api.example.com/endpoint3', { dispatcher: socks5Proxy })
-])
+Gracefully closes the agent, waiting for all underlying pools and their
+connections to drain and close before resolving.
 
-console.log('All requests completed through the same SOCKS5 proxy')
-```
+```mjs
+import { setGlobalDispatcher, Socks5ProxyAgent } from 'undici'
 
-### `Socks5ProxyAgent.close()`
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
+setGlobalDispatcher(agent)
 
-Closes the SOCKS5 proxy wrapper and waits for all underlying pools and connections to close before resolving.
+// ... make requests ...
 
-Returns: `Promise<void>`
-
-#### Example - clean up after tests are complete
-
-```js
-import { Socks5ProxyAgent, setGlobalDispatcher } from 'undici'
-
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
-setGlobalDispatcher(socks5Proxy)
-
-// ... make requests
-
-await socks5Proxy.close()
+await agent.close()
 ```
 
-### `Socks5ProxyAgent.destroy([err])`
+### `socks5ProxyAgent.destroy([err])`
 
-Destroys the SOCKS5 proxy wrapper and all underlying connections immediately.
+<!-- YAML
+added: v7.23.0
+-->
 
-Arguments:
-* **err** `Error` (optional) - The error that caused the destruction.
+> Stability: 1 - Experimental
 
-Returns: `Promise<void>`
+* `err` {Error} (optional) The error to reject in-flight requests with.
+* Returns: {Promise<void>} Resolves once every per-origin pool has been
+  destroyed.
 
-#### Example - force close all connections
+Forcibly destroys the agent and all underlying connections immediately, without
+waiting for in-flight requests to complete.
 
-```js
+```mjs
 import { Socks5ProxyAgent } from 'undici'
 
-const socks5Proxy = new Socks5ProxyAgent('socks5://localhost:1080')
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-// Force close all connections
-await socks5Proxy.destroy()
+await agent.destroy()
 ```
 
-### `Socks5ProxyAgent.dispatch(options, handlers)`
-
-Implements [`Dispatcher.dispatch(options, handlers)`](/docs/docs/api/Dispatcher.md#dispatcherdispatchoptions-handlers).
+### `socks5ProxyAgent.dispatch(options, handlers)`
 
-### `Socks5ProxyAgent.request(options[, callback])`
+<!-- YAML
+added: v7.23.0
+-->
 
-See [`Dispatcher.request(options [, callback])`](/docs/docs/api/Dispatcher.md#dispatcherrequestoptions-callback).
+> Stability: 1 - Experimental
 
-## Debugging
-
-SOCKS5 proxy connections can be debugged using Node.js diagnostics:
-
-```sh
-NODE_DEBUG=undici:socks5 node script.js
-```
+* `options` {DispatchOptions}
+* `handlers` {DispatchHandler}
+* Returns: {boolean} `false` if the dispatcher is busy and the request should be
+  retried later, otherwise `true`.
 
-This will output detailed information about the SOCKS5 handshake, authentication, and connection establishment.
+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.
 
-## SOCKS5 Protocol Support
+This is the lower-level entry point implementing
+[`Dispatcher.dispatch(options, handlers)`][]. Prefer
+[`socks5ProxyAgent.request()`][] for most use cases.
 
-The Socks5ProxyAgent supports the following SOCKS5 features:
+### `socks5ProxyAgent.request(options[, callback])`
 
-### Authentication Methods
+<!-- YAML
+added: v7.23.0
+-->
 
-- **No Authentication** (`0x00`) - For public or internal proxies
-- **Username/Password** (`0x02`) - RFC 1929 authentication
+> Stability: 1 - Experimental
 
-### Address Types
+* `options` {DispatchOptions}
+* `callback` {Function} (optional)
+* Returns: {Promise|void} A promise resolving to the response when `callback` is
+  omitted.
 
-- **IPv4** (`0x01`) - Standard IPv4 addresses
-- **Domain Name** (`0x03`) - Domain names (recommended for flexibility)
-- **IPv6** (`0x04`) - IPv6 addresses (full support for standard and compressed notation)
+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.
 
-### Commands
+```mjs
+import { fetch, Socks5ProxyAgent } from 'undici'
 
-- **CONNECT** (`0x01`) - Establish TCP connection (primary use case for HTTP)
+const agent = new Socks5ProxyAgent('socks5://localhost:1080')
 
-### Error Handling
-
-The wrapper handles various SOCKS5 error conditions:
-
-- Connection refused by proxy
-- Authentication failures
-- Network unreachable
-- Host unreachable
-- Unsupported address types or commands
+const response = await fetch('http://localhost:3000/api/users', {
+  dispatcher: agent
+})
 
-## Performance Considerations
+console.log('Response status:', response.status)
+console.log('Response data:', await response.text())
+```
 
-- **Connection Pooling**: Automatically pools connections through the SOCKS5 tunnel for better performance
-- **HTTP/1.1 Pipelining**: Supports pipelining when enabled
-- **DNS Resolution**: Domain names are resolved by the SOCKS5 proxy, reducing local DNS queries
-- **TLS Termination**: HTTPS connections are encrypted end-to-end, with the SOCKS5 proxy only handling the TCP tunnel
+## Debugging
 
-## Security Notes
+SOCKS5 proxy activity can be traced with the `undici:socks5-proxy` debug scope:
 
-1. **Authentication**: Credentials are sent to the SOCKS5 proxy in plaintext unless using SOCKS5 over TLS
-2. **DNS Leaks**: All DNS resolution happens on the proxy server, preventing DNS leaks
-3. **End-to-end Encryption**: HTTPS traffic remains encrypted between client and final destination
-4. **Connection Security**: Consider using authenticated proxies and secure networks
+```bash
+NODE_DEBUG=undici:socks5-proxy node script.js
+```
 
-## Compatibility
+This logs the SOCKS5 handshake, authentication, and tunnel establishment steps.
 
-- **Protocol**: SOCKS5 (RFC 1928) with Username/Password Authentication (RFC 1929)
-- **Transport**: TCP only (UDP support not implemented)
-- **Node.js**: Compatible with all supported Node.js versions
-- **HTTP Versions**: Works with HTTP/1.1 and HTTP/2 over the tunnel
+[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/api/Util.md

@@ -1,25 +1,82 @@
 # Util
 
-Utility API for third-party implementations of the dispatcher API.
+<!--introduced_in=v1.2.0-->
+<!--type=module-->
+<!-- source_link=lib/core/util.js -->
 
-## `parseHeaders(headers, [obj])`
+> Stability: 2 - Stable
 
-Receives a header object and returns the parsed value.
+A small set of utility helpers exposed for third-party implementations of the
+[`Dispatcher`][] API. They cover the header-handling primitives undici uses
+internally, so that custom dispatchers and handlers can normalize header names
+and parse raw header lists exactly the way undici does.
 
-Arguments:
+```mjs
+import { util } from 'undici'
 
-- **headers** `(Buffer | string | (Buffer | string)[])[]` (required) - Header object.
+const { parseHeaders, headerNameToString } = util
+```
 
-- **obj** `Record<string, string | string[]>` (optional) - Object to specify a proxy object. The parsed value is assigned to this object. But, if **headers** is an object, it is not used.
+```cjs
+const { util } = require('undici')
 
-Returns: `Record<string, string | string[]>` If **obj** is specified, it is equivalent to **obj**.
+const { parseHeaders, headerNameToString } = util
+```
+
+## `parseHeaders(headers[, obj])`
+
+<!-- YAML
+added: v1.2.0
+changes:
+  - version: v6.1.0
+    pr-url: https://github.com/nodejs/undici/pull/2501
+    description: Header names supplied as a `Buffer` are accepted and normalized.
+-->
+
+* `headers` {Array} A flat list of raw header entries where even indices are
+  header names and odd indices are the corresponding values. Each entry is a
+  {string}, {Buffer}, or an array of {string}/{Buffer}.
+* `obj` {Record<string, string|string[]>} An object to assign the parsed values
+  to. When omitted, a new object is created. **Default:** `{}`.
+* Returns: {Record<string, string|string[]>} The object the parsed headers were
+  assigned to. When `obj` is provided, the same reference is returned.
+
+Receives a flat list of raw header name/value pairs and returns them as an
+object keyed by lowercased header name. Header names are normalized with
+[`headerNameToString()`][], and `Buffer` values are decoded as `latin1`. When a
+header name appears more than once, its values are collected into an array.
+
+```mjs
+import { util } from 'undici'
+
+const raw = ['Content-Type', 'text/plain', 'Set-Cookie', 'a=1', 'Set-Cookie', 'b=2']
+
+console.log(util.parseHeaders(raw))
+// { 'content-type': 'text/plain', 'set-cookie': [ 'a=1', 'b=2' ] }
+```
 
 ## `headerNameToString(value)`
 
-Retrieves a header name and returns its lowercase value.
+<!-- YAML
+added: v6.1.0
+-->
+
+* `value` {string|Buffer} The header name to normalize.
+* Returns: {string} The lowercased header name.
+
+Returns the lowercased form of a header name. The `value` may be provided as a
+{string} or as a {Buffer}, in which case it is decoded as `latin1`. Common
+header names are resolved through an internal lookup table for performance.
+
+```mjs
+import { util } from 'undici'
 
-Arguments:
+console.log(util.headerNameToString('Content-Type'))
+// 'content-type'
 
-- **value** `string | Buffer` (required) - Header name.
+console.log(util.headerNameToString(Buffer.from('X-Custom-Header')))
+// 'x-custom-header'
+```
 
-Returns: `string`
+[`Dispatcher`]: Dispatcher.md#class-dispatcher
+[`headerNameToString()`]: #headernametostringvalue