@crvouga/mockingbird-service-postgres 3.2.0 → 3.4.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

@@ -10,7 +10,7 @@ type ClockState = {
     now: number;
     /** True while time does not advance on its own. */
     frozen: boolean;
-    /** Milliseconds this clock adds to its underlying source. */
+    /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
     offsetMs: number;
 };
 type Clock = {
@@ -28,6 +28,213 @@ type Clock = {
     state(): ClockState;
 };
 
+/**
+ * A deliberate failure injected in front of an operation.
+ *
+ * This is how a suite reaches the vendor's failure modes without the vendor: the
+ * quota error that only appears when a shared sandbox is full, the 429 that only
+ * appears under load, the 5xx that proves a retry path works.
+ *
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
+ */
+type FaultRule = {
+    /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
+    id: string;
+    /** Fault only this operation. Omit to match every operation. */
+    operationId?: string;
+    /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
+    method?: string;
+    /** Fault only this exact path. */
+    path?: string;
+    /** Fault only paths starting with this prefix. Omit to match every path. */
+    pathPrefix?: string;
+    /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
+    pathPattern?: string;
+    /** Fault only requests carrying these headers. `"*"` matches any value. */
+    requestHeaders?: Record<string, string>;
+    /** Fault only requests carrying these query parameters. `"*"` matches any value. */
+    query?: Record<string, string>;
+    /**
+     * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
+     * an in-process caller usually wants, and what a parallel worker usually does not:
+     * rules added through `POST /__admin/faults` default to the calling namespace.
+     */
+    namespace?: string;
+    /** Let this many matching requests through first. */
+    after?: number;
+    /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
+    every?: number;
+    /** Retire the rule after this many faults. Omit to keep it until removed. */
+    count?: number;
+    /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
+    rate?: number;
+    /**
+     * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
+     * clock when the rule was added. Listed as epoch ms.
+     */
+    from?: Instant | Duration;
+    /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
+    until?: Instant | Duration;
+    /**
+     * Status of the injected response. Omit for a rule that only delays, times out, drops,
+     * truncates, or switches on an `effect`: the request then still reaches the service.
+     */
+    status?: number;
+    /** Response body, serialized as JSON. A string is sent as-is. */
+    body?: unknown;
+    /** Response headers. */
+    headers?: Record<string, string>;
+    /** Hold the response back this long. Listed as `delayMs`. */
+    delay?: Duration;
+    /** `delay`, in milliseconds. */
+    delayMs?: number;
+    /** Alias of `delayMs`. */
+    latencyMs?: number;
+    /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
+    jitter?: Duration;
+    jitterMs?: number;
+    /**
+     * Never answer: hold the request this long, then drop the connection. Listed as
+     * `timeoutMs`. With virtual time the wait is spent on the mock clock.
+     */
+    timeout?: Duration;
+    timeoutMs?: number;
+    /**
+     * Drop the connection instead of answering: an in-process `fetch` rejects with a
+     * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
+     */
+    drop?: boolean;
+    /**
+     * Cut the response body off after this many bytes: the status and headers arrive, then
+     * the connection dies mid-body.
+     */
+    truncate?: number;
+    /**
+     * A named service behaviour to switch on for the matching request instead of (or
+     * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
+     * read it with `faultEffects(request)`.
+     */
+    effect?: string;
+    /** Parameters for `effect`. */
+    params?: Record<string, unknown>;
+    /** The preset this rule was expanded from, if any. */
+    fromPreset?: string;
+};
+
+/**
+ * The admin controls every mock shares, as one document.
+ *
+ * The same shape is accepted in three places, and means the same thing in each:
+ *
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
+ *   `MOCKINGBIRD_ADMIN_CONTROLS`
+ * - over HTTP: `PUT /__admin/controls`
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
+ *
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
+ */
+/** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
+type Duration = number | string;
+/** Epoch milliseconds, or an ISO-8601 string. */
+type Instant = number | string;
+type ClockControls = {
+    /** Move the clock to this instant. */
+    now?: Instant;
+    /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
+    frozen?: boolean;
+    /**
+     * Step the clock forward by this much before every vendor request. With a frozen clock
+     * each request still gets its own, reproducible timestamp.
+     */
+    autoAdvance?: Duration;
+};
+/** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
+type LatencyRuleInput = {
+    delay?: Duration;
+    jitter?: Duration;
+};
+type LatencyControls = LatencyRuleInput & {
+    /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
+    operations?: Record<string, Duration | LatencyRuleInput>;
+};
+/** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
+type FaultInput = (Omit<FaultRule, "id"> & {
+    id?: string;
+}) | ({
+    preset: string;
+} & Partial<FaultRule>);
+/** Identifies a {@link SnapshotDocument}. */
+declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
+/**
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
+ * `records` are required, so a hand-written seed file is a valid snapshot.
+ */
+type SnapshotDocument = {
+    format: typeof SNAPSHOT_FORMAT;
+    /** The service that wrote it. A snapshot is rejected by any other service. */
+    service?: string;
+    /**
+     * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
+     * the stored text of a row that is not a plain record, and replaces `value` when present.
+     */
+    records: {
+        collection: string;
+        id: string;
+        seq?: number;
+        value?: unknown;
+        raw?: string;
+    }[];
+    /** Id counters, so the next generated id continues where the snapshot left off. */
+    sequences?: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+    clock?: {
+        now: number;
+        frozen: boolean;
+        autoAdvanceMs?: number;
+    };
+    seed?: number | string;
+    /** Positions of the seeded random streams. */
+    rng?: {
+        state: number;
+        faults?: number;
+        latency?: number;
+    };
+    faults?: unknown;
+    latency?: unknown;
+    virtualTime?: boolean;
+};
+/** Controls for one namespace. */
+type NamespaceControls = {
+    /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
+    seed?: number | string;
+    clock?: ClockControls;
+    /**
+     * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
+     * wall clock: the request returns at once, the clock has moved, and the journal records
+     * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
+     */
+    virtualTime?: boolean;
+    /** Baseline response time for every vendor request. A bare duration is its `delay`. */
+    latency?: Duration | LatencyControls;
+    faults?: readonly FaultInput[];
+    /** Start from this state instead of the service's own seed data. */
+    snapshot?: SnapshotDocument;
+};
+/** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
+type MockControls = NamespaceControls & {
+    /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
+    credentials?: Record<string, string>;
+    /** Overrides for named namespaces. A key given here replaces the shared value. */
+    namespaces?: Record<string, NamespaceControls>;
+};
+
 type FleetDiagnostics = {
     activeRequests: number;
     activeConnections: number;
@@ -66,6 +273,8 @@ type ConfigService = {
     adminPrefix?: string;
     adminKey?: string;
     seed?: string;
+    /** Admin controls this service boots with. A key given here replaces the fleet-wide one. */
+    adminControls?: MockControls;
     fixtures?: Record<string, unknown>;
     baseUrl?: string;
     password?: 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";