@crvouga/mockingbird-service-postgres 3.1.0 → 3.3.0

package/dist/wire/cluster.d.ts

@@ -1,5 +1,6 @@
 import { Database } from "../api/database.js";
 import type { Snapshot } from "../api/snapshot.js";
+import type { Durability } from "./durable.js";
 /**
  * What every connection of one server shares: the engine, and the coordination the engine
  * (single-session, synchronous) does not do itself.
@@ -28,6 +29,8 @@ export declare class Cluster {
     current: Session | null;
     private nextPid;
     private readonly databases;
+    /** Set in durable mode: commits are persisted through it before they are acknowledged. */
+    durability: Durability | null;
     constructor(db: Database, defaultDatabaseName?: string);
     /** The initial database, retained for the server's backwards-compatible public handle. */
     get db(): Database;
@@ -35,6 +38,11 @@ export declare class Cluster {
     snapshotAll(): Map<string, Snapshot>;
     restoreAll(points: ReadonlyMap<string, Snapshot>): void;
     getDatabase(name: string): Database | undefined;
+    /** Add a database that already exists (restored from durable storage) to the catalog. */
+    attach(name: string, db: Database): void;
+    /** The catalog as it stands, to put back with {@link restoreCatalog} if a change cannot be persisted. */
+    catalog(): Map<string, Database>;
+    restoreCatalog(entries: ReadonlyMap<string, Database>): void;
     requireDatabase(name: string): Database;
     createDatabase(name: string, template?: string): void;
     dropDatabase(name: string, requester: Session): void;

package/dist/wire/connection.d.ts

@@ -8,6 +8,11 @@ export type ServerFaults = {
     delayStatementMs?: number;
     /** Fail the next COMMIT with this SQLSTATE (`40001` serialization failure) after rolling back. */
     failCommit?: string;
+    /**
+     * Interrupt the next `CREATE INDEX CONCURRENTLY` / `REINDEX ... CONCURRENTLY` with this SQLSTATE
+     * (`57014` canceled, `40P01` deadlock). The index it was building stays in the catalog, invalid.
+     */
+    failConcurrentIndexBuild?: string;
 };
 export type ServerLog = {
     pid: number;
@@ -67,11 +72,24 @@ export declare class Connection implements Session {
     /** Successful writes in this session's READ COMMITTED transaction workspace. */
     private transaction;
     private closed;
+    /** This session's settings. They stand in for the database's own around each of its engine calls. */
+    private settings;
+    /** What `RESET` returns to: the database's settings at connect, then the startup packet's. */
+    private settingDefaults;
+    /** Durable commits that are persisted and not yet acknowledged on the socket. */
+    private readonly unacknowledged;
+    /** A commit of this session is being persisted; it still owns the statement turn. */
+    private persisting;
     constructor(socket: Socket, cluster: Cluster, options: ConnectionOptions);
     private receive;
     private pump;
     private write;
     private dispose;
+    /**
+     * Run engine work with this session's settings in place of the database's own, so one
+     * connection's `SET` never reaches another. Whatever the work leaves behind is the session's.
+     */
+    private inSession;
     /** Terminate from the server side (close, or the drop-connection fault). */
     destroy(): void;
     queueNotification(pid: number, channel: string, payload: string): void;
@@ -92,6 +110,24 @@ export declare class Connection implements Session {
     /** Run one statement against the engine, honoring the turn, locks, aborted state and faults. */
     private execute;
     private executeInner;
+    /**
+     * Durable mode, before a statement that may commit: how to take that commit back out of
+     * memory if storage then refuses it. Null when the statement cannot commit a change.
+     */
+    private durableUndo;
+    /** What a transaction's BEGIN captures and its ROLLBACK restores, for a commit already applied. */
+    private checkpoint;
+    /**
+     * Persist a commit this session just applied, while it still holds the statement turn, so no
+     * other session has seen it. Storage refusing it takes the commit back out of memory and
+     * fails the statement (`58030`, or `53100` when storage is full); the transaction is gone,
+     * as after any failed COMMIT. Resolves to the commit when storage was written.
+     */
+    private persist;
+    /** The acknowledgement of every persisted commit is on the socket. */
+    private acknowledged;
+    /** CREATE / DROP / ALTER DATABASE in durable mode: the catalog change is persisted, or undone. */
+    private durableClusterDdl;
     private waitForLock;
     /** The engine call itself: statement-atomic, and transaction control handled as the server sees it. */
     private runStatement;
@@ -119,6 +155,8 @@ export declare class Connection implements Session {
     private copyStatement;
     private copyColumnCount;
     private handleCopyIn;
+    /** Engine work of a COPY in progress. A workspace already carries the session's settings. */
+    private inCopy;
     private beginCopyIn;
     private finishCopyIn;
     private flushCopyRecords;

package/dist/wire/durable.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Opt-in durable mode for the wire server: a commit is acknowledged only once the whole cluster,
+ * as PGMM snapshots, has reached a {@link DurableStorage}. It is snapshot persistence, not a
+ * write-ahead log and not PostgreSQL's on-disk format. The guarantee it models is the one a
+ * client relies on: https://www.postgresql.org/docs/18/wal-intro.html (an acknowledged COMMIT
+ * survives a crash) and https://www.postgresql.org/docs/18/sql-commit.html.
+ *
+ * Nothing here touches a filesystem: the storage is a port the server awaits, so a test can
+ * model failure and pauses, and {@link fileStorage} (./file-storage.ts) is the real one.
+ */
+import "../serialization/codec.js";
+import { type Database } from "../api/database.js";
+import { PostgresError } from "../errors/error.js";
+import type { Cluster } from "./cluster.js";
+/** One durable image of the cluster: each database's PGMM snapshot bytes by database name. */
+export type ClusterImage = ReadonlyMap<string, Uint8Array>;
+/** Where durable mode keeps the cluster. The server awaits it before acknowledging a commit. */
+export interface DurableStorage {
+    /** The image of the last {@link write} that resolved, or `null` when nothing was persisted yet. */
+    read(): Promise<ClusterImage | null>;
+    /**
+     * Replace the persisted image with `image`, atomically: resolve once it would survive the
+     * process being killed, or reject and leave the previous image intact. The server never
+     * calls it concurrently, and passes the same `Uint8Array` object for a database that did
+     * not change since the last call, so an implementation can skip rewriting it.
+     */
+    write(image: ClusterImage): Promise<void>;
+}
+/** A commit the server persisted, as the test controls of {@link DurableOptions} see it. */
+export type DurableCommit = {
+    /** Backend pid of the session that committed. */
+    pid: number;
+    /** Database the commit belongs to. */
+    database: string;
+    /** The statement that committed: the write itself in autocommit, else `COMMIT`. */
+    sql: string;
+};
+export type DurableOptions = {
+    /** A directory for the file-backed store, or an injected {@link DurableStorage}. */
+    storage: string | DurableStorage;
+    /**
+     * Test control: awaited after a commit was persisted and before the server acknowledges it.
+     * A process killed while this is pending restarts with the commit; the client never saw it.
+     */
+    beforeAcknowledge?: (commit: DurableCommit) => void | Promise<void>;
+    /**
+     * Test control: awaited right after the acknowledgement was written to the socket
+     * (`CommandComplete`, or `ReadyForQuery` for the implicit commit of a multi-statement query).
+     */
+    afterAcknowledge?: (commit: DurableCommit) => void | Promise<void>;
+};
+/**
+ * A storage failure as the client sees it: the commit is not acknowledged, and the statement
+ * ends with `58030` (io_error), or `53100` (disk_full) when the storage ran out of space.
+ */
+export declare const storageFailure: (cause: unknown) => PostgresError;
+/** Rebuild the databases of a persisted image, with the runtime (clock, seed, entropy) of `template`. */
+export declare const openImage: (image: ClusterImage, template: Database) => Map<string, Database>;
+/** Persists the cluster for the server, re-encoding only the databases a commit touched. */
+export declare class Durability {
+    private readonly cluster;
+    private readonly storage;
+    private readonly hooks;
+    /** PGMM bytes of each database as storage holds them. */
+    private readonly persisted;
+    private image;
+    private tail;
+    constructor(cluster: Cluster, storage: DurableStorage, hooks: Pick<DurableOptions, "beforeAcknowledge" | "afterAcknowledge">);
+    /** Record that storage already holds `image` for the cluster's databases (after a restart). */
+    adopt(image: ClusterImage): void;
+    /**
+     * Write the cluster with `changed` (or every database) encoded from its live state. Resolves
+     * to whether storage was written: an image identical to the persisted one is skipped. The
+     * caller holds the statement turn, so no session runs between the commit and this.
+     */
+    persist(changed: readonly Database[] | "all"): Promise<boolean>;
+    /** Resolves when no write is in flight. */
+    idle(): Promise<void>;
+    private write;
+    beforeAcknowledge(commit: DurableCommit): void | Promise<void>;
+    afterAcknowledge(commit: DurableCommit): void | Promise<void>;
+}

package/dist/wire/file-storage.d.ts

@@ -0,0 +1,3 @@
+import type { DurableStorage } from "./durable.js";
+/** Persist a cluster under the directory `root` (created when missing). One server per root. */
+export declare const fileStorage: (root: string) => DurableStorage;

package/dist/wire/fleet.d.ts

@@ -66,6 +66,8 @@ type ConfigService = {
     adminPrefix?: string;
     adminKey?: string;
     seed?: string;
+    fixtures?: Record<string, unknown>;
+    baseUrl?: string;
     password?: string;
     user?: string;
     database?: string;

package/dist/wire/index.d.ts

@@ -11,6 +11,9 @@
  * transaction blocks. Advisory locks, `LISTEN`/`NOTIFY`, `CancelRequest` and per-connection
  * aborted-transaction state (`25P02`) are coordinated across connections.
  *
+ * State lives in memory. The opt-in `durable` option persists the cluster before each commit is
+ * acknowledged (see ./durable.ts); without it the server touches no filesystem.
+ *
  * @example
  * ```ts
  * import { serve } from "@crvouga/mockingbird-service-postgres/wire";
@@ -26,6 +29,7 @@ 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";
+import { type DurableOptions, type DurableStorage } from "./durable.js";
 export type ServeOptions = {
     /** TCP port; `0` (the default) picks a free one, reported as `server.port`. */
     port?: number;
@@ -59,6 +63,15 @@ export type ServeOptions = {
     allowDatabaseSelection?: boolean;
     /** Role shown in `connectionString`. A URI's username fills this. Default `postgres`. */
     user?: string;
+    /**
+     * Opt-in durable mode: a directory (the file-backed store), an injected {@link DurableStorage},
+     * or {@link DurableOptions} with test controls. An autocommit write or `COMMIT` is then
+     * persisted before it is acknowledged, and a server started on the same storage resumes from
+     * the last acknowledged commit, even after a `SIGKILL`. Storage that already holds a cluster
+     * wins over `database`, which then only supplies the clock, seed and entropy mode. Omitted
+     * (the default), state lives in memory only and no filesystem is touched.
+     */
+    durable?: string | DurableStorage | DurableOptions;
 };
 export type PostgresServer = {
     /** The bound port. */
@@ -85,7 +98,12 @@ export type PostgresServer = {
     snapshotAll(): Map<string, Snapshot>;
     restoreAll(points: ReadonlyMap<string, Snapshot>): void;
     faultState(): ServerFaults;
-    /** Stop listening and close every connection. */
+    /**
+     * Durable mode: persist every database now, for changes made through `database` /
+     * `getDatabase()` / `restoreAll()` rather than a connection. Resolves at once without `durable`.
+     */
+    persist(): Promise<void>;
+    /** Stop listening and close every connection. Durable mode also waits for a write in flight. */
     close(): Promise<void>;
 };
 export type ServeInput = ServeOptions | string;
@@ -93,3 +111,5 @@ export type ServeInput = ServeOptions | string;
 export declare const serve: (input?: ServeInput) => Promise<PostgresServer>;
 export { Cluster } from "./cluster.js";
 export type { ServerFaults, ServerLog } from "./connection.js";
+export type { ClusterImage, DurableCommit, DurableOptions, DurableStorage } from "./durable.js";
+export { fileStorage } from "./file-storage.js";