@mark1russell7/service 0.5.11 → 0.5.12

package/build/pg.d.ts

@@ -0,0 +1,230 @@
+import { Y as Poll, wt as Operation } from "./lifecycle-fgYfxrHK.js";
+import { _ as Manifestation, a as ClientKnobs, b as firstDetector, c as ClientSpec, d as Factory, f as STARTING_POLL, g as MANIFESTATIONS, h as Detector, i as ClientJoin, l as ClientStep, m as Sent, n as CheckOptions, o as ClientOptions, p as SendOptions, r as Client, s as ClientSocket, t as Attempt, u as DialFn, v as Meeting, x as unwatched, y as Situation } from "./core-C2wnF4mg.js";
+import { Extent, Quantity } from "@mark1russell7/quantity";
+import { Machine } from "@mark1russell7/algebra";
+//#region src/pg/connection.d.ts
+/** A pg socket is the socket of a client in the core: the join of the prober and the bounded close read it. */
+type PgSocket = ClientSocket;
+/** A query result is the part of a result of pg that the wrapper gives back. */
+interface PgResult<Row = Record<string, unknown>> {
+  readonly rows: Row[];
+  readonly rowCount: number | null;
+}
+/**
+ * A pool client is the part of a `pg.PoolClient` that the wrapper uses. A pg 8 client has each part.
+ * A fake for tests has them too. Thus the package depends on no type of pg.
+ */
+interface PgPoolClient {
+  /** This number is the id of the backend from BackendKeyData, which the server sends at the startup. */
+  readonly processID?: number | null | undefined;
+  /** This connection holds the socket of the client. */
+  readonly connection?: {
+    readonly stream?: PgSocket | undefined;
+  } | undefined;
+  query(text: string, values?: readonly unknown[]): Promise<PgResult<never>>;
+  /** This method gives the client back to the pool. With an error, the pool ends the client. */
+  release(error?: Error | boolean): void;
+  on(event: "error", listener: (error: Error) => void): unknown;
+  off(event: "error", listener: (error: Error) => void): unknown;
+}
+/** A pool is the part of a `pg.Pool` that the wrapper uses. */
+interface PgPool {
+  readonly totalCount: number;
+  readonly idleCount: number;
+  readonly waitingCount: number;
+  connect(): Promise<PgPoolClient>;
+  end(): Promise<void>;
+  on(event: "connect" | "remove", listener: (client: PgPoolClient) => void): unknown;
+  on(event: "error", listener: (error: Error, client: PgPoolClient) => void): unknown;
+  off(event: "connect" | "remove", listener: (client: PgPoolClient) => void): unknown;
+  off(event: "error", listener: (error: Error, client: PgPoolClient) => void): unknown;
+}
+/**
+ * These are the options that the wrapper gives `pg.Pool`. Each one comes from the declaration. The
+ * wrapper sets each option that has an effect on a timer, thus no default of pg decides one. A knob
+ * of pg at 0 has no timer. The wrapper writes "infinite" as 0, and it refuses a bound of 0.
+ */
+interface PgPoolOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly database?: string | undefined;
+  readonly user?: string | undefined;
+  readonly password?: string | undefined;
+  /** The server shows this name in `pg_stat_activity`, thus the prober can join on it too. */
+  readonly application_name: string;
+  readonly max: number;
+  readonly min: number;
+  /** This time bounds the TCP connect, the startup and the authentication. It also bounds a checkout from a full pool. */
+  readonly connectionTimeoutMillis: number;
+  /** This time bounds each query on the client, from `client.query`. The client sends no cancel at its end. */
+  readonly query_timeout: number;
+  /** This time is the deadline of each statement on the server. The client sends it in the startup message. Undefined does not send it. */
+  readonly statement_timeout: number | undefined;
+  /** This time ends an idle client of the pool. 0 is no idle timer. */
+  readonly idleTimeoutMillis: number;
+  /** This time ends a client at this age from its connect, in whole seconds. 0 is no age. */
+  readonly maxLifetimeSeconds: number;
+  readonly keepAlive: boolean;
+  /** This time is the idle time of TCP keepalive. Node truncates it to whole seconds. */
+  readonly keepAliveInitialDelayMillis: number;
+  /** The idle timer and the idle sockets do not keep the process alive (A14). The lifecycle holds the process. */
+  readonly allowExitOnIdle: true;
+}
+/** A pool factory makes the pool of the client from its options. */
+type PoolFactory = Factory<PgPoolOptions, PgPool>;
+/**
+ * This factory makes a `pg.Pool`. It loads pg only when a client connects, thus a service that does
+ * not use PostgreSQL does not need pg. The specifier is a value, thus the package needs no types of pg.
+ */
+export declare const nodePostgres: PoolFactory;
+//#endregion
+//#region src/pg/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. `PG_STARTING_KNOBS` gives a declaration from the cells of S1. The knobs
+ * that each client has come from the core.
+ */
+interface PgKnobs extends ClientKnobs {
+  /**
+   * This time bounds a new connection (`connectionTimeoutMillis`): the TCP connect, the startup and
+   * the authentication. The pool uses the same knob to bound a checkout from a full pool.
+   * At the defaults pg has no bound, and the kernel gives up on the SYNs only after 131 s (A3, O15).
+   */
+  readonly connect_bound: Quantity;
+  /** This time bounds each query on the client (`query_timeout`). pg sends no cancel at its end. */
+  readonly request_timeout: Quantity;
+  /**
+   * This time is the deadline of each statement on the server (`statement_timeout`). The server then
+   * ends the statement with ERROR 57014, a certain outcome. "infinite" sends no deadline.
+   */
+  readonly statement_timeout: Extent;
+  /** This time ends an idle client of the pool (`idleTimeoutMillis`). The pool sends no test on an idle client. */
+  readonly pool_idle_expiry: Extent;
+  /** This time is the idle time of TCP keepalive, in whole seconds. Node then sends 10 probes 1 s apart. */
+  readonly keepalive_idle: Extent;
+  /** This time is the age at which the pool replaces a client (`maxLifetimeSeconds`), in whole seconds. */
+  readonly max_connection_age: Extent;
+  /** This time bounds the close of the pool at the shutdown: its end, then a destroy of each socket that stays. */
+  readonly close_bound: Quantity;
+}
+/** A pg client spec is the declaration of one PostgreSQL client: where it connects, its pool, and its knobs. */
+interface PgClientSpec extends ClientSpec<PgKnobs> {
+  readonly database?: string | undefined;
+  readonly user?: string | undefined;
+  /** These counts are the sizes of the pool: at most `max` clients, and an idle timer only above `min`. */
+  readonly pool: {
+    readonly max: number;
+    readonly min: number;
+  };
+  /**
+   * These operations are the queries of the service, by name, with their idempotency. SQL text does
+   * not tell if a statement changes a state, thus the client sends again only a query that this table names.
+   */
+  readonly operations?: Readonly<Record<string, Operation>> | undefined;
+}
+/** These options make a client. Without them, it uses pg, the real clock, and a dial with an SSLRequest. */
+type PgClientOptions = ClientOptions<PoolFactory>;
+/**
+ * A join is one connection of the pool, at its connect (D1, D2). The prober joins its kernel records
+ * to the server's view of the connection through it. The server's view is the process id of the backend.
+ */
+interface PgJoin extends ClientJoin {
+  /** This number is the process id of the backend, or null when the server gave none. Through a pooler, it is the id that the pooler gives. */
+  readonly backendPid: number | null;
+}
+/** The steps that the pg client gives a check for: the steps of each client, and a checkout from the pool (B14). */
+type PgStep = ClientStep | "checkout";
+/** A pg client is a dependency of a service: its declaration, its handle, its checks and its queries. */
+interface PgClient extends Client<PgStep, PgJoin> {
+  /** This text is the state of the client, as `PG_CLIENT_MACHINE` names it. */
+  readonly status: string;
+  /**
+   * This method sends a query, and gives its outcome in three values. `operation` names the query
+   * in the table of operations. The client sends again only an idempotent operation, one time at
+   * most, after an outcome that is not certain. The second try stays in the bound of the request.
+   */
+  query<Row = Record<string, unknown>>(operation: string, text: string, values?: readonly unknown[], options?: SendOptions): Promise<Sent<PgResult<Row>>>;
+}
+/** This function gives the problems of a spec: the knobs that pg cannot use. */
+export declare const specProblems: (name: string, spec: PgClientSpec) => string[];
+/** This function gives the options of `pg.Pool` from a spec. Each timer of pg comes from the declaration. */
+export declare const poolOptions: (name: string, spec: PgClientSpec) => PgPoolOptions;
+/**
+ * This dial function opens a TCP connection, sends an SSLRequest, and waits for its one byte. The
+ * server answers it before the authentication, thus the dial needs no password and opens no backend.
+ */
+export declare const sslRequestDial: DialFn;
+/**
+ * This function makes a PostgreSQL client, a dependency of a service over a `pg.Pool`.
+ * - It sets each timer of pg from the declaration. The driver sends nothing again by itself, and the client
+ *   sends again only an idempotent operation of its table.
+ * - It tells the outcome of a query in three values. An ERROR of the server is certain. A FATAL
+ *   ends the session, thus its outcome is not certain.
+ * - It gives back a client whose query has no certain outcome with an error. The pool then ends it,
+ *   thus an orphaned query does not hold the next checkout.
+ * - It listens to each error of the pool and of a client that it holds. In Node, an error with no
+ *   listener throws, and library code does not end the process (A5).
+ * - It records the process id of the backend of each connection (D1).
+ *
+ * The outcomes, the second try, the queries in flight, the bounded close and the checks come from
+ * the core of the clients. This entry gives what pg does in its own way.
+ */
+export declare const pgClient: (name: string, spec: PgClientSpec, options?: PgClientOptions) => PgClient;
+//#endregion
+//#region src/pg/machine.d.ts
+/**
+ * The pg client of the service as a `mark1russell7.machine/1` document. It is the pool as the
+ * wrapper sees it, not one connection: the document `node-postgres` of `@mark1russell7/machines`
+ * gives each client of the pool. The state is the outcome of the last connect:
+ * - `ready`: the last connect of the pool succeeded.
+ * - `failing`: the last connect failed. pg does not connect again by itself. The next checkout tries again.
+ *
+ * An idle client that fails and a client that the pool removes do not change the state. The pool
+ * removed that client, and the next checkout opens a new connection. A test records the transitions
+ * of the client and replays them against this document.
+ */
+export declare const PG_CLIENT_MACHINE: Machine;
+//#endregion
+//#region src/pg/meets.d.ts
+/**
+ * This function gives the manifestations that a pg client can meet, and the detectors of each, from
+ * its knobs. The cells of S1 measured each one on node-postgres 8.23.1:
+ * - A reset of a query gives ECONNRESET in 0.6 ms, and a FIN to an idle client gives EOF in 18 µs.
+ * - A frozen server and a black hole have no detector in 60 s at the defaults: pg has no timer on a query and no keepalive.
+ * - `query_timeout` ends a query in a black hole on time (9.503 s for 9.5 s).
+ * - `statement_timeout` ends a slow statement on the server with ERROR 57014 (10.002 s for 10 s).
+ *
+ * pg has no watchdog and does not test an idle client. In place of a watchdog, the pool ends an
+ * idle client at its idle timer. A later checkout then opens a new connection, which `connect_bound` bounds.
+ */
+export declare const pgMeetings: (name: string, knobs: PgKnobs) => Meeting[];
+//#endregion
+//#region src/pg/starting.d.ts
+/**
+ * This poll is the poll of the checks that `PG_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 PG_STARTING_POLL: Poll;
+/**
+ * These knobs are a declaration to start from, from what the cells of S1 measured on node-postgres
+ * 8.23.1 against PostgreSQL 17.11. 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: at the defaults pg has no bound, and the kernel gives up on the SYNs only
+ *   after 131 s. The timer of the pool fired 7 ms late at most. Thus 5 s is in a startup budget of 30 s (O15).
+ * - `request_timeout` 9.5 s: the cells ended a query in a black hole at 9.503 s. That is in the slowest poll of 10 s (O13).
+ * - `statement_timeout` 9 s: below `request_timeout`, thus the server ends a slow statement first,
+ *   with ERROR 57014 (O07). The cells measured that end 2 ms after the deadline.
+ * - `pool_idle_expiry` 10 s: the idle timer of pg-pool at its defaults, measured at 10.004 s. It is
+ *   below a router that forgets an idle flow at 12 s (O03), and below a `client_idle_timeout` of PgBouncer at 12 s (O01).
+ * - `keepalive_idle` 30 s: at the defaults pg has no keepalive. This value refreshes a held idle
+ *   connection through the NAT forms of the cells (240 s and 350 s).
+ * - `max_connection_age` "infinite": no cell measured an age, thus the declaration gives none.
+ * - `close_bound` 2 s: behind a black hole the end of the pool waits with no bound. The cells saw
+ *   the pool emit `remove` only when the socket closes.
+ * - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`. The cells measured 3.120 s at `tcp_retries2 = 3`.
+ */
+export declare const PG_STARTING_KNOBS: PgKnobs;
+//#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 PgClient, type PgClientOptions, type PgClientSpec, type PgJoin, type PgKnobs, type PgPool, type PgPoolClient, type PgPoolOptions, type PgResult, type PgSocket, type PgStep, type PoolFactory, STARTING_POLL, type SendOptions, type Sent, type Situation, firstDetector, unwatched };
+//# sourceMappingURL=pg.d.ts.map