@milpa/comal 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,27 @@
+# Class: ClientStats
+
+Stats for a [Client](/docs/docs/api/Client.md).
+
+## `new ClientStats(client)`
+
+Arguments:
+
+* **client** `Client` - Client from which to return stats.
+
+## Instance Properties
+
+### `ClientStats.connected`
+
+Boolean if socket as open connection by this client.
+
+### `ClientStats.pending`
+
+Number of pending requests of this client.
+
+### `ClientStats.running`
+
+Number of currently active requests across this client.
+
+### `ClientStats.size`
+
+Number of active, pending, or queued requests of this clients.

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

@@ -0,0 +1,115 @@
+# Connector
+
+Undici creates the underlying socket via the connector builder.
+Normally, this happens automatically and you don't need to care about this,
+but if you need to perform some additional check over the currently used socket,
+this is the right place.
+
+If you want to create a custom connector, you must import the `buildConnector` utility.
+
+#### Parameter: `buildConnector.BuildOptions`
+
+Every Tls option, see [here](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback).
+Furthermore, the following options can be passed:
+
+* **socketPath** `string | null` (optional) - Default: `null` - An IPC endpoint, either Unix domain socket or Windows named pipe.
+* **maxCachedSessions** `number | null` (optional) - Default: `100` - Maximum number of TLS cached sessions. Use 0 to disable TLS session caching. Default: `100`.
+* **timeout** `number | null` (optional) -  In milliseconds. Default `10e3`.
+* **servername** `string | null` (optional)
+
+Once you call `buildConnector`, it will return a connector function, which takes the following parameters.
+
+#### Parameter: `connector.Options`
+
+* **hostname** `string` (required)
+* **host** `string` (optional)
+* **protocol** `string` (required)
+* **port** `string` (required)
+* **servername** `string` (optional)
+* **localAddress** `string | null` (optional) Local address the socket should connect from.
+* **httpSocket** `Socket` (optional) Establish secure connection on a given socket rather than creating a new socket. It can only be sent on TLS update.
+
+### Basic example
+
+```js
+'use strict'
+
+import { Client, buildConnector } from 'undici'
+
+const connector = buildConnector({ rejectUnauthorized: false })
+const client = new Client('https://localhost:3000', {
+  connect (opts, cb) {
+    connector(opts, (err, socket) => {
+      if (err) {
+        cb(err)
+      } else if (/* assertion */) {
+        socket.destroy()
+        cb(new Error('kaboom'))
+      } else {
+        cb(null, socket)
+      }
+    })
+  }
+})
+```
+
+### Example: validate the CA fingerprint
+
+```js
+'use strict'
+
+import { Client, buildConnector } from 'undici'
+
+const caFingerprint = 'FO:OB:AR'
+const connector = buildConnector({ rejectUnauthorized: false })
+const client = new Client('https://localhost:3000', {
+  connect (opts, cb) {
+    connector(opts, (err, socket) => {
+      if (err) {
+        cb(err)
+      } else if (getIssuerCertificate(socket).fingerprint256 !== caFingerprint) {
+        socket.destroy()
+        cb(new Error('Fingerprint does not match or malformed certificate'))
+      } else {
+        cb(null, socket)
+      }
+    })
+  }
+})
+
+client.request({
+  path: '/',
+  method: 'GET'
+}, (err, data) => {
+  if (err) throw err
+
+  const bufs = []
+  data.body.on('data', (buf) => {
+    bufs.push(buf)
+  })
+  data.body.on('end', () => {
+    console.log(Buffer.concat(bufs).toString('utf8'))
+    client.close()
+  })
+})
+
+function getIssuerCertificate (socket) {
+  let certificate = socket.getPeerCertificate(true)
+  while (certificate && Object.keys(certificate).length > 0) {
+    // invalid certificate
+    if (certificate.issuerCertificate == null) {
+      return null
+    }
+
+    // We have reached the root certificate.
+    // In case of self-signed certificates, `issuerCertificate` may be a circular reference.
+    if (certificate.fingerprint256 === certificate.issuerCertificate.fingerprint256) {
+      break
+    }
+
+    // continue the loop
+    certificate = certificate.issuerCertificate
+  }
+  return certificate
+}
+```

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

@@ -0,0 +1,57 @@
+# MIME Type Parsing
+
+## `MIMEType` interface
+
+* **type** `string`
+* **subtype** `string`
+* **parameters** `Map<string, string>`
+* **essence** `string`
+
+## `parseMIMEType(input)`
+
+Implements [parse a MIME type](https://mimesniff.spec.whatwg.org/#parse-a-mime-type).
+
+Parses a MIME type, returning its type, subtype, and any associated parameters. If the parser can't parse an input it returns the string literal `'failure'`.
+
+```js
+import { parseMIMEType } from 'undici'
+
+parseMIMEType('text/html; charset=gbk')
+// {
+//   type: 'text',
+//   subtype: 'html',
+//   parameters: Map(1) { 'charset' => 'gbk' },
+//   essence: 'text/html'
+// }
+```
+
+Arguments:
+
+* **input** `string`
+
+Returns: `MIMEType|'failure'`
+
+## `serializeAMimeType(input)`
+
+Implements [serialize a MIME type](https://mimesniff.spec.whatwg.org/#serialize-a-mime-type).
+
+Serializes a MIMEType object.
+
+```js
+import { serializeAMimeType } from 'undici'
+
+serializeAMimeType({
+  type: 'text',
+  subtype: 'html',
+  parameters: new Map([['charset', 'gbk']]),
+  essence: 'text/html'
+})
+// text/html;charset=gbk
+
+```
+
+Arguments:
+
+* **mimeType** `MIMEType`
+
+Returns: `string`

package/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/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/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