@mark1russell7/service 0.5.12 → 0.5.14

package/build/mongodb.d.ts

@@ -0,0 +1,307 @@
+import { jt as Operation, nt as Poll } from "./lifecycle-CMedxaQd.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, c as ClientSpec, d as Factory, g as SendOptions, h as STARTING_POLL, i as ClientJoin, l as ClientStep, n as CheckOptions, o as ClientOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, w as Manifestation } from "./core-D8iXeoE4.js";
+import { t as Judge } from "./dial-DJolDmOK.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/mongodb/connection.d.ts
+/** A document is a BSON document as the driver gives it: a command, or the reply of the server. */
+type MongoDocument = Record<string, unknown>;
+/** A database is the part of a `Db` of the driver that the wrapper uses: `command` sends one command. */
+interface MongoDb {
+  /** This method sends a command. Its signal ends the command, and an abort during the read closes the connection. */
+  command(document: MongoDocument, options?: {
+    readonly signal?: AbortSignal | undefined;
+  }): Promise<MongoDocument>;
+}
+/** A server is the part of a `ServerDescription` that the wrapper reads: its type, for example `RSPrimary`. */
+interface MongoServer {
+  readonly type: string;
+}
+/** These are the events of the driver that the wrapper listens to, by name, with the fields that it reads. */
+interface MongoEvents {
+  /** The view of the topology changed. A writable server is a primary, a standalone, a mongos or a load balancer. */
+  topologyDescriptionChanged: {
+    readonly newDescription: {
+      readonly servers: ReadonlyMap<string, MongoServer>;
+    };
+  };
+  /** A connection of the pool finished its handshake. `connectionId` is the id that the pool gives. */
+  connectionReady: {
+    readonly connectionId: number | string;
+    readonly address: string;
+  };
+  /** A command went to a connection. `serverConnectionId` is the id that the server gave in its hello. */
+  commandStarted: {
+    readonly connectionId?: number | string | undefined;
+    readonly address: string;
+    readonly serverConnectionId?: bigint | number | null | undefined;
+  };
+  /** The pool of a server closed its connections, for example at the write-off of the server. */
+  connectionPoolCleared: {
+    readonly address: string;
+    readonly interruptInUseConnections?: boolean | undefined;
+  };
+  /** A hello of the monitor failed. `connectionId` is the address of the server. */
+  serverHeartbeatFailed: {
+    readonly connectionId: string;
+    readonly failure: Error;
+  };
+  /** An error of the topology. In Node, an error with no listener throws. */
+  error: Error;
+}
+/** An event name is a name of `MongoEvents`. */
+type MongoEventName = keyof MongoEvents;
+/**
+ * A driver client is the part of a `MongoClient` that the wrapper uses. A `MongoClient` of the
+ * driver 7 has each part. A fake for tests has them too. Thus the package depends on no type of the driver.
+ */
+interface MongoDriverClient {
+  /** This method opens the topology and waits for a server to select. A failure closes the topology, and a later command opens it again. */
+  connect(): Promise<unknown>;
+  /** This method fails the commands in flight, sends `endSessions` to a selectable server, and closes the topology. */
+  close(): Promise<void>;
+  db(name: string): MongoDb;
+  on<E extends MongoEventName>(event: E, listener: (payload: MongoEvents[E]) => void): unknown;
+  off<E extends MongoEventName>(event: E, listener: (payload: MongoEvents[E]) => void): unknown;
+}
+/**
+ * These are the options that the wrapper gives `MongoClient`. Each one comes from the declaration.
+ * The wrapper sets each option that has an effect on a timer, thus no default of the driver decides
+ * one. A knob of the driver at 0 has no timer. The wrapper writes "infinite" as 0, and it refuses a bound of 0.
+ */
+interface MongoDriverOptions {
+  /** The server shows this name in `$currentOp` and in its log, thus the prober can join on it too. */
+  readonly appName: string;
+  readonly replicaSet?: string | undefined;
+  readonly auth?: {
+    readonly username: string;
+    readonly password: string;
+  } | undefined;
+  readonly authSource?: string | undefined;
+  readonly maxPoolSize: number;
+  readonly minPoolSize: number;
+  /** This time bounds the TCP connect and the handshake of each connection, and of the monitor. */
+  readonly connectTimeoutMS: number;
+  /** This time bounds a read on a connection that has a command in flight. At its end, the driver closes the connection. */
+  readonly socketTimeoutMS: number;
+  /** This time bounds the wait for a server to select, for each command and for `connect`. */
+  readonly serverSelectionTimeoutMS: number;
+  /** This time is the period of the monitor, and the wait of its streaming hello. */
+  readonly heartbeatFrequencyMS: number;
+  /** This time bounds a checkout from a full pool. 0 is no bound. */
+  readonly waitQueueTimeoutMS: number;
+  /** A checkout ends an idle connection older than this time. 0 is no limit. The driver has no timer for it. */
+  readonly maxIdleTimeMS: number;
+  /** This time is the idle time of TCP keepalive. The driver always turns keepalive on. Node truncates the time to whole seconds. */
+  readonly keepAliveInitialDelay: number;
+  /** The monitor streams its hello, as in the cells. Thus a silent server is written off at `connectTimeoutMS + heartbeatFrequencyMS`. */
+  readonly serverMonitoringMode: "stream";
+  /** The driver does not send a command again by itself. The core sends again only an idempotent operation. */
+  readonly retryReads: false;
+  readonly retryWrites: false;
+  /** The driver emits `commandStarted`, which gives the id of the server for each connection (D1). */
+  readonly monitorCommands: true;
+}
+/** These are the arguments of `new MongoClient(url, options)`. The URL gives only the hosts. */
+interface MongoConnectOptions {
+  readonly url: string;
+  readonly options: MongoDriverOptions;
+}
+/** A driver factory makes the client of the driver from its options. */
+type MongoFactory = Factory<MongoConnectOptions, MongoDriverClient>;
+/**
+ * This factory makes a `MongoClient`. It loads the driver only when a client connects, thus a
+ * service that does not use MongoDB does not need it. The specifier is a value, thus the package
+ * needs no types of the driver. The driver gives `MongoClient` as a named export.
+ */
+export declare const nodeMongo: MongoFactory;
+//#endregion
+//#region src/mongodb/client.d.ts
+/**
+ * These are the knobs of the client, each a time, by the names of the ordering law where the law
+ * has them. The runtime has no defaults, thus each knob is necessary. A bound that nobody gives is
+ * "infinite", not zero. `MONGO_STARTING_KNOBS` gives a declaration from the cells of S1. The knobs
+ * that each client has come from the core.
+ */
+interface MongoKnobs extends ClientKnobs {
+  /** This time bounds the TCP connect and the handshake of each connection (`connectTimeoutMS`). It also bounds the wait of the startup. */
+  readonly connect_bound: Quantity;
+  /** This time bounds a read of a command in flight (`socketTimeoutMS`). At its end, the driver closes the connection. */
+  readonly request_timeout: Quantity;
+  /**
+   * This time is the deadline of each command on the server (`maxTimeMS`). The wrapper writes it in
+   * each command. The server then ends the command with error 50, a certain outcome. "infinite" sends no deadline.
+   */
+  readonly statement_timeout: Extent;
+  /** This time is the period of the monitor (`heartbeatFrequencyMS`). The driver takes 500 ms at least. */
+  readonly heartbeat_interval: Quantity;
+  /**
+   * This time bounds the wait for a writable server (`serverSelectionTimeoutMS`). A command waits
+   * through a failover in this time, thus it is the retry window of the client (O29).
+   */
+  readonly client_retry_window: Quantity;
+  /** This time bounds a checkout from a full pool (`waitQueueTimeoutMS`). */
+  readonly checkout_timeout: Extent;
+  /** A checkout ends an idle connection older than this time (`maxIdleTimeMS`). The driver checks it only at a checkout. */
+  readonly pool_idle_expiry: Extent;
+  /** This time is the idle time of TCP keepalive (`keepAliveInitialDelay`), in whole seconds. The driver always turns keepalive on. */
+  readonly keepalive_idle: Extent;
+  /** The driver has no age for a connection, thus this knob must be "infinite". */
+  readonly max_connection_age: Extent;
+  /** This time bounds the close of the client at the shutdown. */
+  readonly close_bound: Quantity;
+}
+/** A seed is one more host that the driver connects to first, for example a member of a replica set. */
+interface MongoSeed {
+  readonly host: string;
+  readonly port: number;
+}
+/** A MongoDB client spec is the declaration of one MongoDB client: where it connects, its pool, and its knobs. */
+interface MongoClientSpec extends ClientSpec<MongoKnobs> {
+  /** This name is the database of the commands of the client. */
+  readonly database: string;
+  readonly username?: string | undefined;
+  /** This name is the database of the user. The default of the driver is `database`, or `admin`. */
+  readonly authSource?: string | undefined;
+  readonly replicaSet?: string | undefined;
+  /** These hosts are more seeds of the topology, after `host` and `port`. */
+  readonly seeds?: readonly MongoSeed[] | undefined;
+  /** These counts are the sizes of the pool of each server: at most `max` connections, and `min` that the driver keeps open. */
+  readonly pool: {
+    readonly max: number;
+    readonly min: number;
+  };
+  /**
+   * These operations are the commands of the service, by name, with their idempotency. A command
+   * name does not tell if a command changes a state, for example an `aggregate` with `$merge`. Thus
+   * the client sends again only a command that this table names.
+   */
+  readonly operations?: Readonly<Record<string, Operation>> | undefined;
+}
+/** These options make a client. Without them, it uses the driver, the real clock, and a dial with a hello. */
+type MongoClientOptions = ClientOptions<MongoFactory>;
+/**
+ * A join is one connection of the pool, when its handshake is done (D1, D2). The prober joins its
+ * kernel records to the server's view of the connection through it. The driver gives no socket,
+ * thus the local address and port are null. The server's view is the connection id of its hello.
+ */
+interface MongoJoin extends ClientJoin {
+  /** This text is the address of the server, as `host:port`. */
+  readonly address: string;
+  /** This number is the connection id that the server gave, from the first command on the connection. Null until that command. */
+  readonly serverConnectionId: number | null;
+}
+/** The steps that the MongoDB client gives a check for. A pool of the driver has no checkout that the wrapper can use. */
+type MongoStep = ClientStep;
+/** A MongoDB client is a dependency of a service: its declaration, its handle, its checks and its commands. */
+interface MongoClient extends Client<MongoStep, MongoJoin> {
+  /** This text is the state of the client, as `MONGO_CLIENT_MACHINE` names it. */
+  readonly status: string;
+  /**
+   * This method sends a command to the database of the spec, and gives its outcome in three values.
+   * `operation` names the command in the table of operations. The client sends again only an
+   * idempotent operation, one time at most, after an outcome that is not certain.
+   */
+  command(operation: string, document: MongoDocument, options?: SendOptions): Promise<Sent<MongoDocument>>;
+}
+/** This function gives the problems of a spec: the knobs that the driver cannot use. */
+export declare const specProblems: (name: string, spec: MongoClientSpec) => string[];
+/** This function gives the arguments of `new MongoClient` from a spec. Each timer of the driver comes from the declaration. */
+export declare const mongoOptions: (name: string, spec: MongoClientSpec) => MongoConnectOptions;
+/**
+ * The bytes of an OP_MSG with the command `{ hello: 1, $db: "admin" }`. They are a header of 16
+ * bytes with the op code 2013, the flags, a section of kind 0, and the BSON document. The server answers a
+ * hello before the authentication, thus the dial needs no password.
+ */
+export declare const HELLO: Uint8Array;
+/**
+ * This judge reads the answer to the hello. It waits for the whole message. The message must be an
+ * OP_MSG with a section of kind 0, and its document must have `ok` 1.
+ */
+export declare const helloJudge: Judge;
+/** This dial function opens a TCP connection, sends a hello, and waits for its reply. The server opens no session for it. */
+export declare const helloCommandDial: DialFn;
+/**
+ * This function gives the outcome of a failure of the driver. The driver names each error class,
+ * thus the wrapper reads the name, and depends on no class of the driver:
+ * - A failure before the command left the client is certain: it did not apply.
+ * - An error of the server is certain, except an interruption, which can leave a part applied.
+ * - A write concern error, a network error after the handshake, and a timeout of the socket are not certain.
+ */
+export declare const failureOutcome: (error: unknown) => Attempt<never>;
+/**
+ * This function makes a MongoDB client, a dependency of a service over a `MongoClient`.
+ * - It sets each timer of the driver from the declaration, and it turns off the retries of the driver.
+ *   The client sends again only an idempotent operation of its table.
+ * - It tells the outcome of a command in three values, from the name of each error of the driver.
+ * - It writes the deadline of the server in each command (`maxTimeMS`), thus the server ends a slow command first (O07).
+ * - It gives the state from the view of the topology: ready while a server is writable.
+ * - It listens to each error of the driver. In Node, an error with no listener throws, and library code does not end the process (A5).
+ * - It records the connection id of the server for each connection of the pool (D1).
+ *
+ * The outcomes, the second try, the commands in flight, the bounded close and the checks come from
+ * the core of the clients. This entry gives what the driver does in its own way.
+ */
+export declare const mongoClient: (name: string, spec: MongoClientSpec, options?: MongoClientOptions) => MongoClient;
+//#endregion
+//#region src/mongodb/machine.d.ts
+/**
+ * The MongoDB client of the service as a `mark1russell7.machine/1` document. It is the topology as
+ * the wrapper sees it, not one connection: the document `mongodb-node` of `@mark1russell7/machines`
+ * gives the monitor and each connection. The state is the view of the topology:
+ * - `ready`: a server is writable: a primary, a standalone, a mongos, or a load balancer.
+ * - `failing`: no server is writable, or the startup found none in `connect_bound`. The monitor
+ *   goes on, and a command waits for a writable server in `client_retry_window`.
+ *
+ * A connection that closes and a pool that the driver clears do not change the state by themselves.
+ * The write-off of a server changes the view of the topology, and that changes the state. A test
+ * records the transitions of the client and replays them against this document.
+ */
+export declare const MONGO_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/mongodb/meets.d.ts
+/**
+ * This function gives the manifestations that a MongoDB client can meet, and the detectors of each,
+ * from its knobs. The cells of S1 measured them on the driver 7.7.0 against mongod 9.0.4:
+ * - The monitor writes off a silent server at `connectTimeoutMS + heartbeatFrequencyMS` after its last
+ *   answer: 40.002 s at the defaults, and 7 s for 5 s + 2 s. The driver then clears the pool, and
+ *   fails each command in flight. With `connectTimeoutMS` 0, nothing found a freeze in 60 s.
+ * - At `tcp_retries2 = 5`, the kernel gave up at 12.936 s.
+ * - A `keepAliveInitialDelay` of 27 s ended an idle stream at 37.255 s.
+ *
+ * The monitor tests the server, not each connection of the pool. Thus a write-off finds a failure of
+ * the server in flight and idle, and a failure of one connection waits for its own detector.
+ */
+export declare const mongoMeetings: (name: string, knobs: MongoKnobs) => Meeting[];
+//#endregion
+//#region src/mongodb/starting.d.ts
+/**
+ * This poll is the poll of the checks that `MONGO_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 MONGO_STARTING_POLL: Poll;
+/**
+ * These knobs are a declaration to start from, from what the cells of S1 measured on the driver
+ * 7.7.0 on Node 24.21.0 against mongod 9.0.4. 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 and `heartbeat_interval` 2 s: the write-off of a silent server came 7 s after
+ *   its last answer, and the cells T01.border-off.75 and .76 held. At the defaults it came at 40.002 s.
+ * - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13). At the defaults the driver has no
+ *   bound on a read, and only the write-off ends the command.
+ * - `statement_timeout` 9 s: below `request_timeout`, thus the server ends a slow command first,
+ *   with error 50 (O07).
+ * - `client_retry_window` 30 s: after an election, the first write took 17 s to 18 s, and the band
+ *   ended at 26.58 s (T11.defaults.10). The default of the driver, 30 s, holds that band.
+ * - `checkout_timeout` 5 s: a full pool fails a checkout in a startup budget. At the defaults the wait has no bound.
+ * - `pool_idle_expiry` 10 s: no cell measured it. It is the bound of O03 and O01 that the pg client
+ *   uses: below a router that forgets an idle flow at 12 s. The driver applies it at the next checkout.
+ * - `keepalive_idle` 30 s: the driver always turns keepalive on, at 120 s by default. This value
+ *   refreshes a held idle connection through the NAT forms of the cells (240 s and 350 s).
+ * - `max_connection_age` "infinite": the driver has no age for a connection.
+ * - `close_bound` 2 s: behind a black hole the close of the driver waits for `endSessions`.
+ * - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`. The cells measured 12.936 s at `tcp_retries2 = 5`.
+ */
+export declare const MONGO_STARTING_KNOBS: MongoKnobs;
+//#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, MANIFESTATIONS, type Manifestation, type Meeting, type MongoClient, type MongoClientOptions, type MongoClientSpec, type MongoConnectOptions, type MongoDb, type MongoDocument, type MongoDriverClient, type MongoDriverOptions, type MongoEventName, type MongoEvents, type MongoFactory, type MongoJoin, type MongoKnobs, type MongoSeed, type MongoServer, type MongoStep, STARTING_POLL, type SendOptions, type Sent, type Situation, firstDetector, unwatched };
+//# sourceMappingURL=mongodb.d.ts.map