@crvouga/mockingbird-service-postgres 1.0.0 → 1.2.0

package/dist/wire/cluster.d.ts

@@ -0,0 +1,71 @@
+import type { Database } from "../api/database.js";
+/**
+ * What every connection of one server shares: the engine, and the coordination the engine
+ * (single-session, synchronous) does not do itself.
+ *
+ * - The **turn**: the engine holds one transaction at a time, so a connection inside an
+ *   explicit transaction block holds the turn until it commits or rolls back, and every other
+ *   connection's statement waits. A statement outside a block takes the turn for itself only.
+ *   Uncommitted rows are therefore never visible to another connection (read committed holds),
+ *   at the cost of running transaction blocks one at a time.
+ * - **Advisory locks** per session, with waiters woken in order, and deadlock detection
+ *   between a lock and the turn (`40P01`).
+ * - **LISTEN / NOTIFY** fan-out, delivered when a listening connection is idle.
+ * - Which session's statement is executing, so the SQL functions registered on the engine
+ *   (`pg_backend_pid`, `pg_advisory_lock`, `pg_notify`, …) know whom they serve.
+ */
+export declare class Cluster {
+    readonly db: Database;
+    turnHolder: Session | null;
+    private readonly turnQueue;
+    readonly locks: Map<string, {
+        holder: Session;
+        count: number;
+        xact: boolean;
+    }>;
+    private readonly lockQueues;
+    readonly listeners: Map<string, Set<Session>>;
+    readonly sessions: Map<number, Session>;
+    current: Session | null;
+    private nextPid;
+    constructor(db: Database);
+    newPid(): number;
+    /** Wait until this session may execute: at once when nobody holds the turn, or it does. */
+    acquireTurn(session: Session): Promise<void>;
+    releaseTurn(session: Session): void;
+    /** Take `key` for `session` now, or report that another session holds it. */
+    tryLock(session: Session, key: string, xact: boolean): boolean;
+    /** Wait until `key` is free for `session`; rejects with `40P01` when that can never happen. */
+    waitLock(session: Session, key: string): Promise<void>;
+    unlock(session: Session, key: string): boolean;
+    /** Release every lock `session` holds, or only its transaction-scoped ones. */
+    unlockAll(session: Session, xactOnly?: boolean): void;
+    /** Forget a session: its transaction, turn, locks, waits and subscriptions. */
+    drop(session: Session): void;
+    /** Run `fn` as `session`'s statement, so registered functions can tell who is calling. */
+    as<T>(session: Session, fn: () => T): T;
+    notify(from: Session, channel: string, payload: string): void;
+}
+type Waiter = {
+    session: Session;
+    resolve: () => void;
+    reject: (error: Error) => void;
+};
+/** A statement stopped by a lock another session holds; the session waits, then runs it again. */
+export declare class LockWait extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/** What the cluster needs from a connection. */
+export interface Session {
+    readonly pid: number;
+    waitingForTurn: Waiter | null;
+    waitingForLock: string | null;
+    /** NOTIFYs issued inside the current transaction block, sent at commit. */
+    pendingNotifies: {
+        channel: string;
+        payload: string;
+    }[];
+    queueNotification(pid: number, channel: string, payload: string): void;
+}
+export {};

package/dist/wire/connection.d.ts

@@ -0,0 +1,107 @@
+import type { Socket } from "node:net";
+import { type Cluster, type Session } from "./cluster.js";
+export type ServerFaults = {
+    /** Destroy the socket of the next connection that runs a statement inside a transaction block. */
+    dropConnection?: boolean;
+    /** Hold the next statement this long before it runs. */
+    delayStatementMs?: number;
+    /** Fail the next COMMIT with this SQLSTATE (`40001` serialization failure) after rolling back. */
+    failCommit?: string;
+};
+export type ServerLog = {
+    pid: number;
+    sql: string;
+    durationMs: number;
+    /** `ok`, or the SQLSTATE of the error. */
+    status: string;
+};
+export type ConnectionOptions = {
+    password?: string;
+    serverVersion: string;
+    parameters: Record<string, string>;
+    faults: ServerFaults;
+    onLog?: (entry: ServerLog) => void;
+};
+/**
+ * One client connection: the protocol state machine over the shared {@link Cluster}.
+ * Statements run one at a time per connection; between connections the cluster decides.
+ */
+export declare class Connection implements Session {
+    private readonly socket;
+    private readonly cluster;
+    private readonly options;
+    readonly pid: number;
+    readonly secret: number;
+    waitingForTurn: Session["waitingForTurn"];
+    waitingForLock: string | null;
+    pendingNotifies: {
+        channel: string;
+        payload: string;
+    }[];
+    private readonly frames;
+    private readonly inbox;
+    private pumping;
+    private started;
+    private scram;
+    private user;
+    /** After an error inside a transaction block: `25P02` until ROLLBACK (`E` in ReadyForQuery). */
+    private aborted;
+    /** A query is in flight (a CancelRequest applies to it). */
+    private busy;
+    private cancelled;
+    /** Extended protocol: an error was sent, so messages are ignored until Sync. */
+    private skipUntilSync;
+    private readonly prepared;
+    private readonly portals;
+    private readonly notifications;
+    private closed;
+    constructor(socket: Socket, cluster: Cluster, options: ConnectionOptions);
+    private receive;
+    private pump;
+    private write;
+    private dispose;
+    /** Terminate from the server side (close, or the drop-connection fault). */
+    destroy(): void;
+    queueNotification(pid: number, channel: string, payload: string): void;
+    private flushNotifications;
+    /** A CancelRequest with this connection's key: the query in flight fails with `57014`. */
+    cancel(): void;
+    private lockWaiter;
+    private handle;
+    private fatal;
+    private startup;
+    private authenticate;
+    private scramStarted;
+    private startupParameters;
+    private ready;
+    private get inTransaction();
+    private status;
+    private readyForQuery;
+    /** Run one statement against the engine, honoring the turn, locks, aborted state and faults. */
+    private execute;
+    private executeInner;
+    private waitForLock;
+    /** The engine call itself: statement-atomic, and transaction control handled as the server sees it. */
+    private runStatement;
+    /** Release the turn and transaction-scoped locks once no block is open; deliver NOTIFYs at commit. */
+    private afterStatement;
+    private flushNotifies;
+    private listen;
+    private unlisten;
+    private query;
+    private sendOutcome;
+    private columnFormats;
+    private fields;
+    private parse;
+    private bind;
+    private describe;
+    /**
+     * The row shape of a statement that returns rows, for Describe on a statement: a trial run with
+     * null parameters inside a transaction that is rolled back. Anything else (or a trial that
+     * fails) is described as returning no data.
+     */
+    private shapeOf;
+    private executePortal;
+    private close;
+    private sync;
+}

package/dist/wire/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A PostgreSQL wire-protocol (frontend/backend 3.0) TCP server in front of the in-memory
+ * engine, so a separate process can use it through a normal `postgres://` connection string:
+ * `pg`, `postgres.js`, a JDBC client, `psql`. It runs in Node and Bun (it needs `node:net`),
+ * not the browser.
+ *
+ * One {@link Database} is shared by every connection through a {@link Cluster}: the engine
+ * runs one statement at a time, so a connection inside an explicit `BEGIN` block holds the
+ * engine until it commits or rolls back and the others queue, which keeps read-committed
+ * visibility (uncommitted rows never reach another connection) at the cost of serializing
+ * transaction blocks. Advisory locks, `LISTEN`/`NOTIFY`, `CancelRequest` and per-connection
+ * aborted-transaction state (`25P02`) are coordinated across connections.
+ *
+ * @example
+ * ```ts
+ * import { serve } from "@crvouga/mockingbird-service-postgres/wire";
+ *
+ * const server = await serve({ port: 0 });
+ * // new pg.Pool({ connectionString: `postgres://postgres@127.0.0.1:${server.port}/db` })
+ * await server.close();
+ * ```
+ *
+ * @module
+ */
+import { type Server } from "node:net";
+import { Database } from "../api/database.js";
+import type { Snapshot } from "../api/snapshot.js";
+import { type ServerFaults, type ServerLog } from "./connection.js";
+export type ServeOptions = {
+    /** TCP port; `0` (the default) picks a free one, reported as `server.port`. */
+    port?: number;
+    /** Interface to bind; default `127.0.0.1`. */
+    host?: string;
+    /**
+     * The database to serve. Pass a {@link Database} to share an existing one, a {@link Snapshot}
+     * to boot every server from one frozen template, or omit it for a fresh deterministic engine.
+     */
+    database?: Database | Snapshot;
+    /** Require SCRAM-SHA-256 with this password; omitted means trust (AuthenticationOk). */
+    password?: string;
+    /** `server_version` reported at startup and by `SHOW server_version`. Default `18.3`. */
+    serverVersion?: string;
+    /** Extra `ParameterStatus` values sent at startup (override the defaults). */
+    parameters?: Record<string, string>;
+    /** Per-statement log sink, for tests and debugging. */
+    onLog?: (entry: ServerLog) => void;
+};
+export type PostgresServer = {
+    /** The bound port. */
+    readonly port: number;
+    /** The bound host. */
+    readonly host: string;
+    /** The shared engine, for seeding, snapshotting or asserting from the test process. */
+    readonly database: Database;
+    /** The underlying `net.Server`. */
+    readonly server: Server;
+    /** Open connections right now. */
+    readonly connections: number;
+    /** Arm a fault preset for the next statement / connection (see {@link ServerFaults}). */
+    fault(fault: ServerFaults): void;
+    /** Freeze the live state (the admin `snapshot()` control). */
+    snapshot(): Snapshot;
+    /** Stop listening and close every connection. */
+    close(): Promise<void>;
+};
+/** Start a server and resolve once it is listening. */
+export declare const serve: (options?: ServeOptions) => Promise<PostgresServer>;
+export { Cluster } from "./cluster.js";
+export type { ServerFaults, ServerLog } from "./connection.js";