@emiliosp/pi-maestro 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,536 @@
+# WebSocket
+
+<!--introduced_in=v5.15.0-->
+<!--type=module-->
+<!-- source_link=lib/web/websocket/websocket.js -->
+
+> Stability: 2 - Stable
+
+The `WebSocket` API provides a way to manage a WebSocket connection to a
+server, allowing bidirectional communication. It follows the
+[WHATWG WebSocket specification][] and [RFC 6455][], and is intended to be
+interchangeable with the global `WebSocket` available in browsers.
+
+```mjs
+import { WebSocket } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events')
+
+ws.addEventListener('open', () => {
+  ws.send('Hello, world!')
+})
+
+ws.addEventListener('message', (event) => {
+  console.log('received:', event.data)
+})
+```
+
+In addition to the standard `WebSocket` interface, this module exports the
+streams-based [`WebSocketStream`][] and [`WebSocketError`][] APIs, as well as a
+[`ping()`][] helper for sending ping frames.
+
+## Class: `WebSocket`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Extends: {EventTarget}
+
+The `WebSocket` object represents a single WebSocket connection. Constructing a
+`WebSocket` immediately begins the opening handshake; the connection cannot be
+reused once it has been closed.
+
+### `new WebSocket(url[, protocols])`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* `url` {URL|string} The URL of the server to connect to. Must use the `ws:`
+  or `wss:` scheme.
+* `protocols` {string|string[]|WebSocketInit} A single subprotocol, a list of
+  subprotocols to negotiate with the server, or a `WebSocketInit` object.
+  **Default:** `[]`.
+  * `protocols` {string|string[]} Subprotocol(s) to request the server use.
+    **Default:** `[]`.
+  * `dispatcher` {Dispatcher} The dispatcher used to open the connection.
+    **Default:** the global dispatcher.
+  * `headers` {HeadersInit|null} Additional headers to send with the handshake
+    request. (optional)
+
+Creates a new `WebSocket` and begins connecting to `url`. The second argument
+may be a string or array of subprotocols, or a `WebSocketInit` object. The
+object form is an undici extension and is not available in browsers; it allows a
+custom `dispatcher` and additional `headers` to be supplied.
+
+If a value in `protocols` is repeated or is not a valid subprotocol name, the
+constructor throws a `SyntaxError` `DOMException`.
+
+```mjs
+import { WebSocket } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events', ['echo', 'chat'])
+```
+
+To route the connection through a custom dispatcher, such as a
+[`ProxyAgent`][], pass a `WebSocketInit` object:
+
+```mjs
+import { WebSocket, ProxyAgent } from 'undici'
+
+const dispatcher = new ProxyAgent('http://localhost:8080')
+
+const ws = new WebSocket('wss://echo.websocket.events', {
+  dispatcher,
+  protocols: ['echo', 'chat']
+})
+```
+
+WebSocket over HTTP/2 is experimental and may change in the future. It can be
+enabled by passing a dispatcher configured with `allowH2`:
+
+```mjs
+import { WebSocket, Agent } from 'undici'
+
+const dispatcher = new Agent({ allowH2: true })
+
+const ws = new WebSocket('wss://echo.websocket.events', {
+  dispatcher,
+  protocols: ['echo', 'chat']
+})
+```
+
+### `websocket.close([code[, reason]])`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* `code` {number} The status code explaining why the connection is being
+  closed. **Default:** `null`.
+* `reason` {string} A human-readable string explaining why the connection is
+  being closed. **Default:** `''`.
+
+Starts the closing handshake. The `code` is clamped to an unsigned 16-bit
+integer; when omitted, no status code is sent. The `reason` is encoded as
+UTF-8 and must not exceed 123 bytes.
+
+```mjs
+ws.close(1000, 'Done')
+```
+
+### `websocket.send(data)`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* `data` {string|ArrayBuffer|TypedArray|DataView|Blob} The data to enqueue for
+  transmission.
+
+Enqueues `data` to be transmitted to the server. String data is sent as a text
+frame; `ArrayBuffer`, any `TypedArray`, `DataView`, and `Blob` values are sent
+as binary frames. The number of bytes queued is added to
+[`websocket.bufferedAmount`][].
+
+If [`websocket.readyState`][] is `CONNECTING`, an `InvalidStateError`
+`DOMException` is thrown. If the connection is closing or already closed, the
+call is silently ignored.
+
+```mjs
+ws.send('a text message')
+ws.send(new Uint8Array([1, 2, 3]))
+```
+
+### `websocket.readyState`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {number}
+
+The current state of the connection. One of the numeric constants
+`WebSocket.CONNECTING` (`0`), `WebSocket.OPEN` (`1`),
+`WebSocket.CLOSING` (`2`), or `WebSocket.CLOSED` (`3`). This property is
+read-only.
+
+### `websocket.bufferedAmount`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {number}
+
+The number of bytes of data that have been queued using
+[`websocket.send()`][] but not yet transmitted to the network. This value
+resets to `0` once all queued data is sent. This property is read-only.
+
+### `websocket.url`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The absolute URL of the WebSocket as resolved during construction. This
+property is read-only.
+
+### `websocket.extensions`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The extensions negotiated by the server, taken from the
+`Sec-WebSocket-Extensions` response header. Empty until the connection is
+established. This property is read-only.
+
+### `websocket.protocol`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string}
+
+The subprotocol selected by the server, taken from the
+`Sec-WebSocket-Protocol` response header. Empty until the connection is
+established and only set when a subprotocol was negotiated. This property is
+read-only.
+
+### `websocket.binaryType`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {string} **Default:** `'blob'`.
+
+Controls the type used to represent binary data delivered by the
+[`'message'`][] event. Must be either `'blob'` (binary frames are exposed as a
+`Blob`) or `'arraybuffer'` (binary frames are exposed as an `ArrayBuffer`).
+Assigning any other value resets it to `'blob'`.
+
+### `websocket.onopen`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'open'`][] event. Setting this property replaces any
+previously registered `onopen` handler.
+
+### `websocket.onerror`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'error'`][] event. Setting this property replaces any
+previously registered `onerror` handler.
+
+### `websocket.onclose`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'close'`][] event. Setting this property replaces any
+previously registered `onclose` handler.
+
+### `websocket.onmessage`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+* Type: {Function|null} **Default:** `null`.
+
+An event handler for the [`'message'`][] event. Setting this property replaces
+any previously registered `onmessage` handler.
+
+### Event: `'open'`
+
+<!-- YAML
+added: v5.21.0
+-->
+
+Emitted when the WebSocket connection is established. After this event,
+[`websocket.readyState`][] is `OPEN` and data may be sent with
+[`websocket.send()`][]. The listener receives an `Event`.
+
+### Event: `'message'`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+Emitted when a message is received from the server. The listener receives a
+`MessageEvent` whose `data` property is a `string` for text frames, and either a
+`Blob` or an `ArrayBuffer` for binary frames depending on
+[`websocket.binaryType`][]. The event's `origin` is the origin of
+[`websocket.url`][].
+
+### Event: `'error'`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+Emitted when the connection is terminated abnormally, for example when no close
+frame was received before the underlying transport was lost. The listener
+receives an `ErrorEvent`.
+
+### Event: `'close'`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+Emitted when the connection is closed. The listener receives a `CloseEvent`
+whose `code` and `reason` describe why the connection closed, and whose
+`wasClean` property is `true` only when the closing handshake completed in both
+directions.
+
+## `ping(websocket[, payload])`
+
+<!-- YAML
+added: v7.12.0
+-->
+
+* `websocket` {WebSocket} The WebSocket to send the ping frame on.
+* `payload` {Buffer} Optional payload to include in the ping frame. Must not
+  exceed 125 bytes. **Default:** `undefined`.
+
+Sends a ping control frame to the server. A conforming server replies with a
+pong frame containing the same payload, which can be used to keep the connection
+alive or to verify that it is still active.
+
+The frame is only sent when the connection is open; if it is connecting,
+closing, or closed, the call is a no-op. A `TypeError` is thrown if `payload`
+is not a `Buffer` or is larger than 125 bytes.
+
+```mjs
+import { WebSocket, ping } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events')
+
+ws.addEventListener('open', () => {
+  ping(ws)
+  ping(ws, Buffer.from('hello'))
+})
+```
+
+## Class: `WebSocketStream`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+`WebSocketStream` is a streams-based alternative to the event-based
+[`WebSocket`][] interface, exposing a connection as a pair of `ReadableStream`
+and `WritableStream` objects. See [MDN][MDN WebSocketStream] for background.
+
+Constructing a `WebSocketStream` for the first time emits an
+`ExperimentalWarning` with the code `UNDICI-WSS`.
+
+### `new WebSocketStream(url[, options])`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* `url` {URL|string} The URL of the server to connect to.
+* `options` {WebSocketStreamOptions}
+  * `protocols` {string|string[]} Subprotocol(s) to request the server use.
+    **Default:** `[]`.
+  * `signal` {AbortSignal|null} An `AbortSignal` that aborts the opening
+    handshake and rejects [`webSocketStream.opened`][] and
+    [`webSocketStream.closed`][] when triggered. **Default:** `null`.
+
+Creates a new `WebSocketStream` and begins connecting to `url`. As with
+[`new WebSocket()`][], a repeated or invalid subprotocol causes a `SyntaxError`
+`DOMException` to be thrown.
+
+```mjs
+import { WebSocketStream } from 'undici'
+
+const stream = new WebSocketStream('wss://echo.websocket.events')
+const { readable, writable } = await stream.opened
+
+const writer = writable.getWriter()
+await writer.write('Hello, world!')
+writer.releaseLock()
+
+const reader = readable.getReader()
+const { value } = await reader.read()
+console.log('received:', value)
+```
+
+### `webSocketStream.url`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+The serialized URL of the WebSocket. This property is read-only.
+
+### `webSocketStream.opened`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Promise} Fulfills once the connection is established.
+
+A promise that resolves with an object describing the open connection, or
+rejects if the connection could not be established. The fulfillment value has
+the following shape:
+
+* `extensions` {string} The negotiated extensions.
+* `protocol` {string} The negotiated subprotocol.
+* `readable` {ReadableStream} A stream of incoming messages. Text frames are
+  delivered as strings and binary frames as `Uint8Array` chunks.
+* `writable` {WritableStream} A stream for sending messages. Writing a string
+  sends a text frame; writing a `BufferSource` sends a binary frame.
+
+### `webSocketStream.closed`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {Promise} Fulfills once the connection is closed cleanly.
+
+A promise that resolves with a `WebSocketCloseInfo` object when the connection
+closes cleanly, or rejects with a [`WebSocketError`][] when it closes
+abnormally. The fulfillment value has the following shape:
+
+* `closeCode` {number} The status code the connection was closed with.
+* `reason` {string} The reason the connection was closed with.
+
+### `webSocketStream.close([closeInfo])`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* `closeInfo` {Object}
+  * `closeCode` {number} The status code to close with.
+  * `reason` {string} The reason to close with. **Default:** `''`.
+
+Starts the closing handshake. When `closeInfo` is omitted, the connection is
+closed without a status code.
+
+## Class: `WebSocketError`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* Extends: {DOMException}
+
+An error type used by [`WebSocketStream`][] to report close information. It is
+used to reject [`webSocketStream.closed`][] when the connection closes
+abnormally, and may be passed to a stream's abort or cancel operations to close
+the connection with a specific code and reason.
+
+### `new WebSocketError([message[, init]])`
+
+<!-- YAML
+added: v7.0.0
+-->
+
+> Stability: 1 - Experimental
+
+* `message` {string} A human-readable description of the error.
+  **Default:** `''`.
+* `init` {Object}
+  * `closeCode` {number} The status code to associate with the error.
+  * `reason` {string} The reason to associate with the error.
+    **Default:** `''`.
+
+Creates a new `WebSocketError`. If `reason` is non-empty but no `closeCode` is
+given, `closeCode` defaults to `1000` ("Normal Closure"). The `closeCode` and
+`reason` are validated, so an out-of-range code or an over-long reason throws.
+
+### `webSocketError.closeCode`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {number|null}
+
+The status code associated with the error, or `null` if none was set. This
+property is read-only.
+
+### `webSocketError.reason`
+
+<!-- YAML
+added: v5.15.0
+-->
+
+> Stability: 1 - Experimental
+
+* Type: {string}
+
+The reason associated with the error. This property is read-only.
+
+## Read more
+
+* [MDN: WebSocket][]
+* [RFC 6455][]
+* [WHATWG WebSocket specification][]
+
+[MDN WebSocketStream]: https://developer.mozilla.org/docs/Web/API/WebSocketStream
+[MDN: WebSocket]: https://developer.mozilla.org/docs/Web/API/WebSocket
+[RFC 6455]: https://www.rfc-editor.org/rfc/rfc6455
+[WHATWG WebSocket specification]: https://websockets.spec.whatwg.org/
+[`'close'`]: #event-close
+[`'error'`]: #event-error
+[`'message'`]: #event-message
+[`'open'`]: #event-open
+[`ProxyAgent`]: ProxyAgent.md#class-proxyagent
+[`WebSocket`]: #class-websocket
+[`WebSocketError`]: #class-websocketerror
+[`WebSocketStream`]: #class-websocketstream
+[`new WebSocket()`]: #new-websocketurl-protocols
+[`ping()`]: #pingwebsocket-payload
+[`webSocketStream.closed`]: #websocketstreamclosed
+[`webSocketStream.opened`]: #websocketstreamopened
+[`websocket.bufferedAmount`]: #websocketbufferedamount
+[`websocket.binaryType`]: #websocketbinarytype
+[`websocket.readyState`]: #websocketreadystate
+[`websocket.send()`]: #websocketsenddata
+[`websocket.url`]: #websocketurl

package/node_modules/undici/docs/docs/api/api-lifecycle.md

@@ -0,0 +1,159 @@
+# Client Lifecycle
+
+<!--type=misc-->
+
+A {Client} can be understood as a state machine. As requests are dispatched,
+processed, and drained, the client moves through a well-defined set of states
+until it is eventually destroyed. This document describes those states and the
+transitions between them.
+
+The {Client} class is not literally implemented as a state machine, so the
+actual execution may deviate slightly from what is described here. Treat this
+guide as a conceptual model for reasoning about a client's behavior rather than
+as a formal specification.
+
+## State transition overview
+
+* A {Client} begins in the **idle** state with no socket connection and no
+  queued requests.
+  * The *connect* transition moves the {Client} to the **pending** state, where
+    requests can be queued before they are processed.
+  * Calling [`client.close()`][] or [`client.destroy()`][] moves the {Client}
+    to the **destroyed** state. Because there are no queued requests in this
+    state, *close* transitions straight to **destroyed**.
+* The **pending** state indicates that the underlying socket connection has been
+  established and that requests are queueing.
+  * The *process* transition moves the {Client} to the **processing** state,
+    where requests are processed.
+  * If requests are queued, *close* transitions to **processing**; otherwise it
+    transitions to **destroyed**.
+  * The *destroy* transition moves the {Client} to **destroyed**.
+* The **processing** state initializes to the **processing.running** sub-state.
+  * If the current request body requires draining, *needDrain* moves the
+    {Client} into the **processing.busy** sub-state, which returns to
+    **processing.running** once *drainComplete* fires.
+  * After all queued requests complete, *keepalive* moves the {Client} back to
+    the **pending** state. If no requests are queued before the socket times
+    out, the {Client} transitions to **idle**.
+  * If *close* is fired while the {Client} still has queued requests, the
+    {Client} transitions to **processing.closing**, where it completes all
+    outstanding requests before firing *done*.
+  * The *done* transition moves the {Client} gracefully to **destroyed**.
+  * At any time, *destroy* moves the {Client} from **processing** to
+    **destroyed**, aborting any queued requests.
+* The **destroyed** state is final; the {Client} is no longer functional.
+
+A state diagram representing a {Client} instance:
+
+```mermaid
+stateDiagram-v2
+  [*] --> idle
+  idle --> pending : connect
+  idle --> destroyed : destroy/close
+
+  pending --> idle : timeout
+  pending --> destroyed : destroy
+
+  state close_fork <<fork>>
+  pending --> close_fork : close
+  close_fork --> processing
+  close_fork --> destroyed
+
+  pending --> processing : process
+
+  processing --> pending : keepalive
+  processing --> destroyed : done
+  processing --> destroyed : destroy
+
+  destroyed --> [*]
+
+  state processing {
+      [*] --> running
+      running --> closing : close
+      running --> busy : needDrain
+      busy --> running : drainComplete
+      running --> [*] : keepalive
+      closing --> [*] : done
+  }
+```
+
+## State details
+
+### idle
+
+**idle** is the initial state of a {Client} instance. Although an `origin` is
+required to construct a {Client}, the underlying socket connection is not
+established until a request is queued through [`client.dispatch()`][]. Calling
+`client.dispatch()` directly, or through one of its higher-level wrappers
+([`client.connect()`][], [`client.pipeline()`][], [`client.request()`][],
+[`client.stream()`][], or [`client.upgrade()`][]), moves the {Client} from
+**idle** to **pending**, and then usually directly on to **processing**.
+
+Calling [`client.close()`][] or [`client.destroy()`][] in this state moves the
+{Client} straight to **destroyed**, since there are no queued requests.
+
+### pending
+
+**pending** signifies a connected but non-processing {Client}. On entering this
+state, the {Client} establishes a socket connection and emits the
+[`'connect'`][] event, signalling that a connection to the `origin` supplied at
+construction time has been established. The internal queue starts empty, and
+requests can begin queueing.
+
+Calling [`client.close()`][] with queued requests moves the {Client} to the
+**processing** state; without queued requests it moves to **destroyed**.
+
+Calling [`client.destroy()`][] moves the {Client} directly to **destroyed**,
+regardless of any queued requests.
+
+### processing
+
+**processing** is itself a sub-state machine that initializes to the
+**processing.running** sub-state. [`client.dispatch()`][], [`client.close()`][],
+and [`client.destroy()`][] can all be called while the {Client} is in this
+state. `client.dispatch()` queues additional requests while existing ones
+continue to be processed, `client.close()` moves the {Client} to the
+**processing.closing** sub-state, and `client.destroy()` moves it to
+**destroyed**.
+
+#### running
+
+In **processing.running**, queued requests are processed in FIFO order. If a
+request body requires draining, *needDrain* moves the {Client} to the
+**processing.busy** sub-state. The *close* transition moves the {Client} to the
+**processing.closing** sub-state. When all queued requests have completed and
+neither [`client.close()`][] nor [`client.destroy()`][] has been called, the
+*keepalive* transition moves the {Client} back to the **pending** state. There
+the {Client} waits for the socket connection to time out; once it does, the
+{Client} returns to the **idle** state.
+
+#### busy
+
+This sub-state is entered only when a request body is a {stream.Readable} that
+requires draining. The {Client} cannot process additional requests while in
+this state and waits until the current request body has been fully drained
+before returning to **processing.running**.
+
+#### closing
+
+This sub-state is entered only when a {Client} has queued requests and
+[`client.close()`][] is called. The {Client} continues to process requests as
+usual, except that no additional requests may be queued. Once all queued
+requests have been processed, *done* fires and the {Client} moves gracefully to
+**destroyed** without an error.
+
+### destroyed
+
+**destroyed** is the final state of a {Client} instance. Once in this state, the
+{Client} is no longer functional, and calling any further {Client} method
+rejects or fails with a {ClientDestroyedError}.
+
+[`'connect'`]: Client.md#event-connect
+[`client.close()`]: Client.md#clientclosecallback
+[`client.connect()`]: Client.md#clientconnectoptions-callback
+[`client.destroy()`]: Client.md#clientdestroyerror-callback
+[`client.dispatch()`]: Client.md#clientdispatchoptions-handlers
+[`client.pipeline()`]: Client.md#clientpipelineoptions-handler
+[`client.request()`]: Client.md#clientrequestoptions-callback
+[`client.stream()`]: Client.md#clientstreamoptions-factory-callback
+[`client.upgrade()`]: Client.md#clientupgradeoptions-callback