@yanglaofish/fishtools 0.5.1 → 0.5.3

package/node_modules/@mytools/fst-platform/node_modules/undici/docs/docs/api/Cookies.md

@@ -0,0 +1,128 @@
+# Cookie Handling
+
+## `Cookie` interface
+
+* **name** `string`
+* **value** `string`
+* **expires** `Date|number` (optional)
+* **maxAge** `number` (optional)
+* **domain** `string` (optional)
+* **path** `string` (optional)
+* **secure** `boolean` (optional)
+* **httpOnly** `boolean` (optional)
+* **sameSite** `'String'|'Lax'|'None'` (optional)
+* **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
+
+## `deleteCookie(headers, name[, attributes])`
+
+Sets the expiry time of the cookie to the unix epoch, causing browsers to delete it when received.
+
+```js
+import { deleteCookie, Headers } from 'undici'
+
+const headers = new Headers()
+deleteCookie(headers, 'name')
+
+console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```
+
+Arguments:
+
+* **headers** `Headers`
+* **name** `string`
+* **attributes** `{ path?: string, domain?: string }` (optional)
+
+Returns: `void`
+
+## `getCookies(headers)`
+
+Parses the `Cookie` header and returns a list of attributes and values.
+
+```js
+import { getCookies, Headers } from 'undici'
+
+const headers = new Headers({
+  cookie: 'get=cookies; and=attributes'
+})
+
+console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
+```
+
+Arguments:
+
+* **headers** `Headers`
+
+Returns: `Record<string, string>`
+
+## `getSetCookies(headers)`
+
+Parses all `Set-Cookie` headers.
+
+```js
+import { getSetCookies, Headers } from 'undici'
+
+const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
+
+console.log(getSetCookies(headers))
+// [
+//   {
+//     name: 'undici',
+//     value: 'getSetCookies',
+//     secure: true
+//   }
+// ]
+
+```
+
+Arguments:
+
+* **headers** `Headers`
+
+Returns: `Cookie[]`
+
+## `parseCookie(cookie)`
+
+Parses a single `Set-Cookie` header value into a `Cookie` object.
+
+```js
+import { parseCookie } from 'undici'
+
+console.log(parseCookie('undici=getSetCookies; Secure; SameSite=Lax'))
+// {
+//   name: 'undici',
+//   value: 'getSetCookies',
+//   secure: true,
+//   sameSite: 'Lax'
+// }
+```
+
+Notes:
+
+* The cookie value is returned as it appears in the header. Percent-encoded sequences such as `%20` or `%0D%0A` are **not** decoded.
+* `sameSite` is only set for exact case-insensitive matches of `Strict`, `Lax`, or `None`.
+
+Arguments:
+
+* **cookie** `string`
+
+Returns: `Cookie | null`
+
+## `setCookie(headers, cookie)`
+
+Appends a cookie to the `Set-Cookie` header.
+
+```js
+import { setCookie, Headers } from 'undici'
+
+const headers = new Headers()
+setCookie(headers, { name: 'undici', value: 'setCookie' })
+
+console.log(headers.get('Set-Cookie')) // undici=setCookie
+```
+
+Arguments:
+
+* **headers** `Headers`
+* **cookie** `Cookie`
+
+Returns: `void`

package/node_modules/@mytools/fst-platform/node_modules/undici/docs/docs/api/Debug.md

@@ -0,0 +1,62 @@
+# Debug
+
+Undici (and subsenquently `fetch` and `websocket`) exposes a debug statement that can be enabled by setting `NODE_DEBUG` within the environment.
+
+The flags available are:
+
+## `undici`
+
+This flag enables debug statements for the core undici library.
+
+```sh
+NODE_DEBUG=undici node script.js
+
+UNDICI 16241: connecting to nodejs.org using https:h1
+UNDICI 16241: connecting to nodejs.org using https:h1
+UNDICI 16241: connected to nodejs.org using https:h1
+UNDICI 16241: sending request to GET https://nodejs.org/
+UNDICI 16241: received response to GET https://nodejs.org/ - HTTP 307
+UNDICI 16241: connecting to nodejs.org using https:h1
+UNDICI 16241: trailers received from GET https://nodejs.org/
+UNDICI 16241: connected to nodejs.org using https:h1
+UNDICI 16241: sending request to GET https://nodejs.org/en
+UNDICI 16241: received response to GET https://nodejs.org/en - HTTP 200
+UNDICI 16241: trailers received from GET https://nodejs.org/en
+```
+
+## `fetch`
+
+This flag enables debug statements for the `fetch` API.
+
+> **Note**: statements are pretty similar to the ones in the `undici` flag, but scoped to `fetch`
+
+```sh
+NODE_DEBUG=fetch node script.js
+
+FETCH 16241: connecting to nodejs.org using https:h1
+FETCH 16241: connecting to nodejs.org using https:h1
+FETCH 16241: connected to nodejs.org using https:h1
+FETCH 16241: sending request to GET https://nodejs.org/
+FETCH 16241: received response to GET https://nodejs.org/ - HTTP 307
+FETCH 16241: connecting to nodejs.org using https:h1
+FETCH 16241: trailers received from GET https://nodejs.org/
+FETCH 16241: connected to nodejs.org using https:h1
+FETCH 16241: sending request to GET https://nodejs.org/en
+FETCH 16241: received response to GET https://nodejs.org/en - HTTP 200
+FETCH 16241: trailers received from GET https://nodejs.org/en
+```
+
+## `websocket`
+
+This flag enables debug statements for the `Websocket` API.
+
+> **Note**: statements can overlap with `UNDICI` ones if `undici` or `fetch` flag has been enabled as well.
+
+```sh
+NODE_DEBUG=websocket node script.js
+
+WEBSOCKET 18309: connecting to echo.websocket.org using https:h1
+WEBSOCKET 18309: connected to echo.websocket.org using https:h1
+WEBSOCKET 18309: sending request to GET https://echo.websocket.org/
+WEBSOCKET 18309: connection opened <ip_address>
+```

package/node_modules/@mytools/fst-platform/node_modules/undici/docs/docs/api/DiagnosticsChannel.md

@@ -0,0 +1,317 @@
+# Diagnostics Channel Support
+
+Stability: Experimental.
+
+Undici supports the [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) (currently available only on Node.js v16+).
+It is the preferred way to instrument Undici and retrieve internal information.
+
+The channels available are the following.
+
+## `undici:request:create`
+
+This message is published when a new outgoing request is created.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:create').subscribe(({ request }) => {
+  console.log('origin', request.origin)
+  console.log('completed', request.completed)
+  console.log('method', request.method)
+  console.log('path', request.path)
+  console.log('headers', request.headers) // array of strings, e.g: ['foo', 'bar']
+  request.addHeader('hello', 'world')
+  console.log('headers', request.headers) // e.g. ['foo', 'bar', 'hello', 'world']
+})
+```
+
+Note: a request is only loosely completed to a given socket.
+
+## `undici:request:bodyChunkSent`
+
+This message is published when a chunk of the request body is being sent.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:bodyChunkSent').subscribe(({ request, chunk }) => {
+  // request is the same object undici:request:create
+})
+```
+
+## `undici:request:bodySent`
+
+This message is published after the request body has been fully sent.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:bodySent').subscribe(({ request }) => {
+  // request is the same object undici:request:create
+})
+```
+
+## `undici:request:headers`
+
+This message is published after the response headers have been received. This includes a successful CONNECT or
+protocol upgrade response.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:headers').subscribe(({ request, response }) => {
+  // request is the same object undici:request:create
+  console.log('statusCode', response.statusCode)
+  console.log(response.statusText)
+  // response.headers are buffers.
+  console.log(response.headers.map((x) => x.toString()))
+})
+```
+
+## `undici:request:bodyChunkReceived`
+
+This message is published after a chunk of the response body has been received.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:bodyChunkReceived').subscribe(({ request, chunk }) => {
+  // request is the same object undici:request:create
+})
+```
+
+## `undici:request:trailers`
+
+This message is published after the response body and trailers have been received, i.e. the response has been completed.
+After an upgraded socket is passed to the request handler, this message is published with an empty `trailers` array.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:trailers').subscribe(({ request, trailers }) => {
+  // request is the same object undici:request:create
+  console.log('completed', request.completed)
+  // trailers are buffers.
+  console.log(trailers.map((x) => x.toString()))
+})
+```
+
+## `undici:request:error`
+
+This message is published if the request is going to error, but it has not errored yet.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:error').subscribe(({ request, error }) => {
+  // request is the same object undici:request:create
+})
+```
+
+## `undici:client:sendHeaders`
+
+This message is published right before the first byte of the request is written to the socket.
+
+*Note*: It will publish the exact headers that will be sent to the server in raw format.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:sendHeaders').subscribe(({ request, headers, socket }) => {
+  // request is the same object undici:request:create
+  console.log(`Full headers list ${headers.split('\r\n')}`);
+})
+```
+
+## `undici:client:beforeConnect`
+
+This message is published before creating a new connection for **any** request.
+You can not assume that this event is related to any specific request.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:beforeConnect').subscribe(({ connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername, version } = connectParams
+  // connector is a function that creates the socket
+})
+```
+
+## `undici:client:connected`
+
+This message is published after a connection is established.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:connected').subscribe(({ socket, connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername, version } = connectParams
+ // connector is a function that creates the socket
+})
+```
+
+## `undici:client:connectError`
+
+This message is published if it did not succeed to create new connection
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, socket, connectParams, connector }) => {
+  // const { host, hostname, protocol, port, servername, version } = connectParams
+  // connector is a function that creates the socket
+  console.log(`Connect failed with ${error.message}`)
+})
+```
+
+## `undici:websocket:open`
+
+This message is published after the client has successfully connected to a server.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:open').subscribe(({ 
+  address,           // { address: string, family: string, port: number }
+  protocol,          // string - negotiated subprotocol
+  extensions,        // string - negotiated extensions
+  websocket,         // WebSocket - the WebSocket instance
+  handshakeResponse  // object - HTTP response that upgraded the connection
+}) => {
+  console.log(address) // address, family, and port
+  console.log(protocol) // negotiated subprotocols
+  console.log(extensions) // negotiated extensions
+  console.log(websocket) // the WebSocket instance
+  
+  // Handshake response details
+  console.log(handshakeResponse.status) // 101 for HTTP/1.1, 200 for HTTP/2 extended CONNECT
+  console.log(handshakeResponse.statusText) // 'Switching Protocols' for HTTP/1.1, commonly 'OK' for HTTP/2 in Node.js
+  console.log(handshakeResponse.headers) // Object containing response headers
+})
+```
+
+### Handshake Response Object
+
+The `handshakeResponse` object contains the HTTP response that established the WebSocket connection:
+
+- `status` (number): The HTTP status code (`101` for HTTP/1.1 upgrade, `200` for HTTP/2 extended CONNECT)
+- `statusText` (string): The HTTP status message (`'Switching Protocols'` for HTTP/1.1, commonly `'OK'` for HTTP/2 in Node.js)
+- `headers` (object): The HTTP response headers from the server, including:
+  - `sec-websocket-accept` and other WebSocket-related headers
+  - `upgrade: 'websocket'`
+  - `connection: 'upgrade'`
+
+  The `upgrade` and `connection` headers are only present for HTTP/1.1 handshakes.
+
+This information is particularly useful for debugging and monitoring WebSocket connections, as it provides access to the initial HTTP handshake response that established the WebSocket connection.
+
+## `undici:websocket:close`
+
+This message is published after the connection has closed.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
+  console.log(websocket) // the WebSocket instance
+  console.log(code) // the closing status code
+  console.log(reason) // the closing reason
+})
+```
+
+## `undici:websocket:socket_error`
+
+This message is published if the socket experiences an error.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
+  console.log(error)
+})
+```
+
+## `undici:websocket:ping`
+
+This message is published after the client receives a ping frame, if the connection is not closing.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload, websocket }) => {
+  // a Buffer or undefined, containing the optional application data of the frame
+  console.log(payload)
+  console.log(websocket) // the WebSocket instance
+})
+```
+
+## `undici:websocket:pong`
+
+This message is published after the client receives a pong frame.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload, websocket }) => {
+  // a Buffer or undefined, containing the optional application data of the frame
+  console.log(payload)
+  console.log(websocket) // the WebSocket instance
+})
+```
+
+## `undici:proxy:connected`
+
+This message is published after the `ProxyAgent` establishes a connection to the proxy server.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:proxy:connected').subscribe(({ socket, connectParams }) => {
+  console.log(socket)
+  console.log(connectParams)
+  // const { origin, port, path, signal, headers, servername } = connectParams
+})
+```
+
+## `undici:request:pending-requests`
+
+This message is published when the deduplicate interceptor's pending request map changes. This is useful for monitoring and debugging request deduplication behavior.
+
+The deduplicate interceptor automatically deduplicates concurrent requests for the same resource. When multiple identical requests are made while one is already in-flight, only one request is sent to the origin server, and all waiting handlers receive the same response.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:request:pending-requests').subscribe(({ type, size, key }) => {
+  console.log(type)  // 'added' or 'removed'
+  console.log(size)  // current number of pending requests
+  console.log(key)   // the deduplication key for this request
+})
+```
+
+### Event Properties
+
+- `type` (`string`): Either `'added'` when a new pending request is registered, or `'removed'` when a pending request completes (successfully or with an error).
+- `size` (`number`): The current number of pending requests after the change.
+- `key` (`string`): The deduplication key for the request, composed of the origin, method, path, and request headers.
+
+### Example: Monitoring Request Deduplication
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+const channel = diagnosticsChannel.channel('undici:request:pending-requests')
+
+channel.subscribe(({ type, size, key }) => {
+  if (type === 'added') {
+    console.log(`New pending request: ${key} (${size} total pending)`)
+  } else {
+    console.log(`Request completed: ${key} (${size} remaining)`)
+  }
+})
+```
+
+This can be useful for:
+- Verifying that request deduplication is working as expected
+- Monitoring the number of concurrent in-flight requests
+- Debugging deduplication behavior in production environments