@mark1russell7/service 0.5.12 → 0.5.13

package/build/websocket.d.ts

@@ -0,0 +1,275 @@
+import { Y as Poll, wt as Operation } from "./lifecycle-fgYfxrHK.js";
+import { C as MANIFESTATIONS, D as firstDetector, E as Situation, O as unwatched, S as Detector, T as Meeting, _ as Sent, a as ClientKnobs, b as retryProblems, c as ClientSpec, d as Factory, f as ReadyWait, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, m as RetrySchedule, n as CheckOptions, o as ClientOptions, p as RetryKnobs, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as readyWait, w as Manifestation, x as retrySchedule, y as retryBackoff } from "./core-BPLRDcUJ.js";
+import { n as statusLineJudge, t as Judge } from "./dial-DA8vJfh2.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/websocket/connection.d.ts
+/**
+ * These are the listeners of one connection. The connection holds each event until the client
+ * listens. Thus an event that comes between the creation and the listen does not go away.
+ */
+interface WsListeners {
+  /** This event tells that the upgrade ended with 101, and the connection can send. */
+  open(): void;
+  /** This event gives one message of the server. A text message is UTF-8 in the buffer. */
+  message(data: Buffer, binary: boolean): void;
+  /** This event gives the payload of one pong frame. */
+  pong(data: Buffer): void;
+  /** This event tells that the connection closed, with the code and the reason of the close frame. Code 1006 tells that no close frame came. */
+  close(code: number, reason: string): void;
+  /** This event gives an error of the connection. A close follows it. */
+  error(error: Error): void;
+}
+/**
+ * A connection is the part of a `WebSocket` of ws 8 that the wrapper uses. A fake for tests has
+ * each part too. Thus the package depends on no type of ws.
+ */
+interface WsConnection {
+  /** This method gives the listeners of the connection. The connection then gives each event that it holds. */
+  listen(listeners: WsListeners): void;
+  /** This method writes one message. The callback gets an error when the write fails. It throws while the connection is not open. */
+  send(data: string | Buffer, callback: (error?: Error) => void): void;
+  /** This method writes one ping frame with this payload. It throws while the connection is not open. */
+  ping(data: Buffer): void;
+  /** This method writes a close frame, and waits for the close frame of the server. It destroys nothing. */
+  close(code: number, reason: string): void;
+  /** This method destroys the socket at once. The cells measured 0.3 ms to 1 ms from the call to the close of the socket. */
+  terminate(): void;
+  /** This field holds the socket after the upgrade, or undefined before it. The join reads its addresses. */
+  readonly socket: ClientSocket | undefined;
+  /** This text is the subprotocol that the server chose, or "" when it chose none. */
+  readonly protocol: string;
+}
+/**
+ * These are the options that the wrapper gives `new WebSocket(url, protocols, options)` of ws. Each
+ * time comes from the declaration. ws gives the options that it does not read to `net.connect`.
+ */
+interface WsDriverOptions {
+  /** This time bounds the TCP connect and the upgrade, in milliseconds. */
+  readonly handshakeTimeout: number;
+  /** ws answers each ping of the server with a pong. The heartbeat of the server then finds the client alive. */
+  readonly autoPong: true;
+  /** This time bounds the close handshake of ws, in milliseconds. The wrapper gives its own bound, `close_bound`. */
+  readonly closeTimeout: number;
+  /** ws sets no keepalive on its socket. The wrapper turns it on only when the declaration gives an idle time. */
+  readonly keepAlive: boolean;
+  /** This time is the idle time of TCP keepalive, in milliseconds. Node truncates it to whole seconds. */
+  readonly keepAliveInitialDelay?: number | undefined;
+  /** These headers go with the upgrade request, for example `authorization`. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+/** These are the arguments of `new WebSocket(url, protocols, options)`. */
+interface WsConnectOptions {
+  readonly url: string;
+  readonly protocols: readonly string[];
+  readonly options: WsDriverOptions;
+}
+/** A connection factory makes one connection from its options. The connection opens later, and tells it with the event `open`. */
+type WsFactory = Factory<WsConnectOptions, WsConnection>;
+/** This type is the part of a `WebSocket` of ws 8 that the adapter uses. */
+interface WsDriver {
+  on(event: string, listener: (...args: never[]) => void): unknown;
+  send(data: string | Buffer, callback: (error?: Error | null) => void): void;
+  ping(data: Buffer): void;
+  close(code: number, reason: string): void;
+  terminate(): void;
+  readonly protocol: string;
+}
+/**
+ * This function adapts a `WebSocket` of ws to a connection. It listens to `error` at once, because
+ * in Node an error with no listener throws. It takes the socket from the event `upgrade`.
+ */
+export declare const adaptWs: (ws: WsDriver) => WsConnection;
+/**
+ * This factory makes a `WebSocket` of ws. It loads ws only when a client connects, thus a service
+ * that does not use WebSocket does not need it. The specifier is a value, thus the package needs no types of ws.
+ */
+export declare const nodeWs: WsFactory;
+//#endregion
+//#region src/websocket/client.d.ts
+/**
+ * These are the knobs of the client, each a time, by the names of the ordering law. The runtime has
+ * no defaults, thus each knob is necessary. A bound that nobody gives is "infinite", not zero. The
+ * constant `WS_CLIENT_STARTING_KNOBS` gives a declaration from the WS cells. The knobs that each client has come from the core.
+ */
+interface WsKnobs extends ClientKnobs, RetryKnobs {
+  /** This time bounds the TCP connect and the upgrade (`handshakeTimeout` of ws). The wrapper also bounds the open with it. */
+  readonly connect_bound: Quantity;
+  /** This time bounds each call: a request until its reply, and a ping until its pong. The wrapper has this timer, because ws has none. */
+  readonly request_timeout: Quantity;
+  /** This time is the interval of the ping frames of the heartbeat, from the start of one to the start of the next. "infinite" sends no ping. */
+  readonly heartbeat_interval: Extent;
+  /** This time bounds each ping of the heartbeat. A ping with no pong in this time is a miss. */
+  readonly heartbeat_timeout: Quantity;
+  /** This time is the first delay before a new try to connect. The delay doubles after each try. */
+  readonly retry_base: Quantity;
+  /** This time is the most that one delay can be, before its jitter. */
+  readonly retry_cap: Quantity;
+  /** This time is the idle time of TCP keepalive (`keepAliveInitialDelay`), in whole seconds. "infinite" keeps keepalive off, as ws does. */
+  readonly keepalive_idle: Extent;
+  /** The client does not replace its connection at an age, thus this knob must be "infinite". */
+  readonly max_connection_age: Extent;
+  /** This time bounds the close at the shutdown: the calls in flight, then the close handshake. At the bound, `terminate()` destroys the socket. */
+  readonly close_bound: Quantity;
+}
+/** A reply is the id of the request that a message answers, and the error of the server when the reply tells one. */
+interface WsReply {
+  readonly id: string;
+  readonly error?: string | undefined;
+}
+/**
+ * The replies of a protocol tell which message of the server answers which request. WebSocket has no
+ * reply of its own: each application protocol puts an id in its messages, for example JSON-RPC 2.0.
+ */
+interface WsReplies {
+  /** This function reads one message of the server. It gives its reply, or null for a message that answers no request. */
+  reply(data: Buffer, binary: boolean): WsReply | null;
+}
+/** A WebSocket client spec is the declaration of one WebSocket client: where it connects, and its knobs. */
+interface WsClientSpec extends ClientSpec<WsKnobs> {
+  /** This path is the path of the upgrade request. The default is "/". */
+  readonly path?: string | undefined;
+  /** These names are the subprotocols that the client offers (`Sec-WebSocket-Protocol`). */
+  readonly protocols?: readonly string[] | undefined;
+  /** These headers go with the upgrade request and with the dial, for example `authorization`. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  /** This count is the number of heartbeat misses in sequence that end the connection. The cells used 1. */
+  readonly heartbeatMisses: number;
+  /** These replies match a message of the server to its request. Without them, the client sends no request. */
+  readonly replies?: WsReplies | undefined;
+  /**
+   * These operations are the calls of the service, by name, with their idempotency. A message does
+   * not tell if the server removes its duplicates. Thus the client sends again only a call that this table names, and a ping.
+   */
+  readonly operations?: ClientSpec<WsKnobs>["operations"];
+}
+/** These options make a client. Without them, it uses ws, the real clock, `Math.random`, and a dial with the upgrade request. */
+interface WsClientOptions extends ClientOptions<WsFactory> {
+  readonly random?: (() => number) | undefined;
+  /**
+   * This function waits one turn of the event loop. The heartbeat waits it before it counts a miss,
+   * thus a pong that is in the socket counts first. The default is `setImmediate`.
+   */
+  readonly turn?: (() => Promise<void>) | undefined;
+}
+/** A join is one generation of the client: one connection, when its upgrade ended with 101 (D1, D2). WebSocket gives no id of a connection. */
+interface WsJoin extends ClientJoin {
+  /** This URL is the URL of the connection. */
+  readonly url: string;
+  /** This text is the subprotocol that the server chose, or "" when it chose none. */
+  readonly protocol: string;
+}
+/** A request is one message to the server, with the id that its reply gives back. */
+interface WsRequest {
+  readonly id: string;
+  /** This data goes as one message. A string goes as a text message, and a buffer as a binary message. */
+  readonly data: string | Buffer;
+}
+/** A response is the message of the server that answered a request. */
+interface WsResponse {
+  readonly data: Buffer;
+  readonly binary: boolean;
+}
+/** A message listener receives each message of the server that answers no request. */
+type WsMessageListener = (data: Buffer, binary: boolean) => void;
+/** A WebSocket client is a dependency of a service: its declaration, its handle, its checks and its calls. */
+interface WsClient extends Client<ClientStep, WsJoin> {
+  /** This text is the state of the client, as `WS_CLIENT_MACHINE` names it. */
+  readonly status: string;
+  /**
+   * This method sends a request, and waits for its reply. A reply is `ok`, or a certain error when it
+   * tells one. The client sends again only an idempotent operation, one time at most, after an outcome that is not certain.
+   */
+  request(operation: string, call: WsRequest, options?: SendOptions): Promise<Sent<WsResponse>>;
+  /** This method sends a ping frame, and waits for a pong. A pong is `ok`. A ping is idempotent, thus the client can send it again. */
+  ping(options?: SendOptions): Promise<Sent<void>>;
+  /** This method sends one message with no reply. It gives true when ws took the message, and false when the client is not ready. */
+  send(data: string | Buffer): boolean;
+  /** This method adds a listener of the messages that answer no request. It gives the function that removes it. */
+  onMessage(listener: WsMessageListener): () => void;
+}
+/** These operations are in each table: a ping frame is idempotent (RFC 6455 §5.5.2). */
+export declare const WS_OPERATIONS: Readonly<Record<string, Operation>>;
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+export declare const specProblems: (name: string, spec: WsClientSpec) => string[];
+/** This function gives the URL of a spec. The client speaks ws:// only. */
+export declare const wsUrl: (spec: WsClientSpec) => string;
+/** This function gives the arguments of `new WebSocket` from a spec. Each timer of ws comes from the declaration. */
+export declare const wsOptions: (spec: WsClientSpec) => WsConnectOptions;
+/** This function gives the bytes of the dial: the upgrade request of RFC 6455 §4.1, with the subprotocols and the headers of the spec. */
+export declare const upgradeRequest: (spec: Pick<WsClientSpec, "host" | "port" | "path" | "protocols" | "headers">) => string;
+/** This judge reads the status line of the answer to the upgrade. Only 101 passes: a WebSocket server takes the upgrade. */
+export declare const upgradeJudge: Judge;
+/** This function makes the dial of a spec: a new TCP connection, the upgrade request, and a wait for 101. The dial then destroys its socket. */
+export declare const wsDial: (spec: Pick<WsClientSpec, "path" | "protocols" | "headers">) => DialFn;
+/**
+ * This function makes a WebSocket client, a dependency of a service over ws 8.
+ * - It has one connection as one generation. The end of the connection ends the generation. The
+ *   client then connects again by itself, after a backoff.
+ * - Its calls are a request until its reply, and a ping until its pong. Each call has a timer of
+ *   the wrapper, because ws has none.
+ * - Its heartbeat sends a ping frame each interval, one at a time. A ping with no pong in its timeout
+ *   is a miss. At the last miss, `terminate()` destroys the socket at once, and the client connects again.
+ * - It tells the outcome of a call in three values, and it settles each call in flight at the end of its generation (C8, C10).
+ * - It records the URL and the ends of the socket of each connection at its open (D1).
+ *
+ * These parts come from the core of the clients: the outcomes, the second try and the wait for a ready
+ * client. The backoff and its schedule, the calls in flight, the bounded close and the checks come from
+ * the core too. The heartbeat is the heartbeat of the package. This entry gives what ws does in its own way.
+ */
+export declare const wsClient: (name: string, spec: WsClientSpec, options?: WsClientOptions) => WsClient;
+//#endregion
+//#region src/websocket/machine.d.ts
+/**
+ * The WebSocket client of the service as a `mark1russell7.machine/1` document. It is one generation
+ * at a time: one `WebSocket` of ws 8. The states:
+ * - `ready`: the upgrade ended with 101, and the client sends each call. Its heartbeat sends a ping frame each interval.
+ * - `failing`: no generation is open. The client connects again after its backoff.
+ * - `closing`: the calls in flight, then the close handshake, in `close_bound`. At the bound, `terminate()`.
+ *
+ * The end of the connection and the last miss of the heartbeat end the generation. A test records
+ * the transitions of the client and replays them against this document.
+ */
+export declare const WS_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/websocket/meets.d.ts
+/**
+ * This function gives the manifestations that a WebSocket client can meet, and the detectors of
+ * each, from its knobs. The WS cells measured them on ws 8:
+ * - At a heartbeat of 2 s, a timeout of 1 s and 1 miss, the drop came 0.999 s to 1.0035 s after the
+ *   ping that got no pong. The slowest of 495 runs took 1.003761 s.
+ * - `terminate()` closes the socket 0.3 ms to 1 ms after the drop. The close of the global WebSocket
+ *   only writes a close frame, and its socket stayed ESTABLISHED.
+ * - The kernel of a frozen server acknowledges each ping, thus only the heartbeat finds it.
+ * - At `tcp_retries2 = 3`, the kernel gave up before a pong timeout of 10 s.
+ * - Without a heartbeat, the client waited for the keepalive of undici: 70 s. ws sets no keepalive.
+ */
+export declare const wsMeetings: (name: string, knobs: WsKnobs, misses: number) => Meeting[];
+//#endregion
+//#region src/websocket/starting.d.ts
+/**
+ * This poll is the poll of the checks that `WS_CLIENT_STARTING_KNOBS` fits. It is `STARTING_POLL` of
+ * the core: each 5 s with a jitter of 20 %, and a timeout of 4 s (B6, O12). The poll does not depend on the driver.
+ */
+export declare const WS_CLIENT_STARTING_POLL: Poll;
+/** This count is the heartbeat misses to start from: 1, as in the WS cells. The drop came 0.999 s to 1.0035 s after the ping with no pong. */
+export declare const WS_CLIENT_STARTING_MISSES = 1;
+/**
+ * These knobs are a declaration to start from, from what the WS cells measured on ws 8. The runtime
+ * has no defaults: a service gives these knobs, or its own. Each value holds the borders that the cells measured:
+ * - `connect_bound` 5 s: the connect timeout of DP44. ws sets no handshake timeout by default.
+ * - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13).
+ * - `heartbeat_interval` 4 s: in the WST cells, a ping each 4 s kept a flow through a router that
+ *   forgets it at 5 s. A ping each 6 s did not (O03).
+ * - `heartbeat_timeout` 3 s: a stall of 1 s with a pong timeout of 3 s dropped nothing. The detection is 4 s + 3 s = 7 s.
+ * - `retry_base` 0.5 s and `retry_cap` 4 s: the reconnect of the cells, from 500 ms, doubling to 4 s.
+ *   The client adds a jitter up to the base. Thus the most delay is 4.5 s, in the slowest poll of 10 s.
+ * - `keepalive_idle` "infinite": ws sets no keepalive, and the heartbeat refreshes an idle flow.
+ * - `max_connection_age` "infinite": the client does not replace its connection at an age.
+ * - `close_bound` 2 s: a close frame to a silent server gets no answer. The `closeTimeout` of ws is 30 s.
+ * - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+ */
+export declare const WS_CLIENT_STARTING_KNOBS: WsKnobs;
+//#endregion
+export { type Attempt, type CheckOptions, type Client, type ClientJoin, type ClientKnobs, type ClientOptions, type ClientSocket, type ClientSpec, type ClientStep, type Detector, type DialFn, type Factory, type Judge, MANIFESTATIONS, type Manifestation, type Meeting, type ReadyWait, type RetryKnobs, type RetrySchedule, STARTING_POLL, type SendOptions, type Sent, type Situation, type WsClient, type WsClientOptions, type WsClientSpec, type WsConnectOptions, type WsConnection, type WsDriverOptions, type WsFactory, type WsJoin, type WsKnobs, type WsListeners, type WsMessageListener, type WsReplies, type WsReply, type WsRequest, type WsResponse, firstDetector, readyWait, retryBackoff, retryProblems, retrySchedule, statusLineJudge, unwatched };
+//# sourceMappingURL=websocket.d.ts.map