@crvouga/mockingbird-service-postgres 1.5.1 → 1.7.0

package/dist/wire/cluster.d.ts

@@ -1,13 +1,12 @@
-import type { Database } from "../api/database.js";
+import { Database } from "../api/database.js";
+import type { Snapshot } from "../api/snapshot.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.
+ * - The **turn** serializes individual synchronous engine calls. Explicit transactions use
+ *   per-session copy-on-write workspaces in the connection, so the turn is released after every
+ *   statement and unrelated sessions keep progressing.
  * - **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.
@@ -15,7 +14,7 @@ import type { Database } from "../api/database.js";
  *   (`pg_backend_pid`, `pg_advisory_lock`, `pg_notify`, …) know whom they serve.
  */
 export declare class Cluster {
-    readonly db: Database;
+    readonly defaultDatabaseName: string;
     turnHolder: Session | null;
     private readonly turnQueue;
     readonly locks: Map<string, {
@@ -28,7 +27,21 @@ export declare class Cluster {
     readonly sessions: Map<number, Session>;
     current: Session | null;
     private nextPid;
-    constructor(db: Database);
+    private readonly databases;
+    constructor(db: Database, defaultDatabaseName?: string);
+    /** The initial database, retained for the server's backwards-compatible public handle. */
+    get db(): Database;
+    databaseNames(): string[];
+    snapshotAll(): Map<string, Snapshot>;
+    restoreAll(points: ReadonlyMap<string, Snapshot>): void;
+    getDatabase(name: string): Database | undefined;
+    requireDatabase(name: string): Database;
+    createDatabase(name: string, template?: string): void;
+    dropDatabase(name: string, requester: Session): void;
+    renameDatabase(from: string, to: string, requester: Session): void;
+    private requireTemplate;
+    private activeConnections;
+    private installDatabase;
     newPid(): number;
     /** Wait until this session may execute: at once when nobody holds the turn, or it does. */
     acquireTurn(session: Session): Promise<void>;
@@ -59,6 +72,8 @@ export declare class LockWait extends Error {
 /** What the cluster needs from a connection. */
 export interface Session {
     readonly pid: number;
+    database: Database;
+    databaseName: string;
     waitingForTurn: Waiter | null;
     waitingForLock: string | null;
     /** NOTIFYs issued inside the current transaction block, sent at commit. */

package/dist/wire/connection.d.ts

@@ -1,4 +1,5 @@
 import type { Socket } from "node:net";
+import type { Database } from "../api/database.js";
 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. */
@@ -43,6 +44,8 @@ export declare class Connection implements Session {
         channel: string;
         payload: string;
     }[];
+    database: Database;
+    databaseName: string;
     private readonly frames;
     private readonly inbox;
     private pumping;
@@ -59,6 +62,10 @@ export declare class Connection implements Session {
     private readonly prepared;
     private readonly portals;
     private readonly notifications;
+    private copyIn;
+    private copyDrain;
+    /** Successful writes in this session's READ COMMITTED transaction workspace. */
+    private transaction;
     private closed;
     constructor(socket: Socket, cluster: Cluster, options: ConnectionOptions);
     private receive;
@@ -88,12 +95,29 @@ export declare class Connection implements Session {
     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. */
+    /** Release the statement turn; transaction-scoped locks live until COMMIT / ROLLBACK. */
     private afterStatement;
+    private transactionControl;
+    private findSavepoint;
+    /** Rebase this transaction's successful writes onto the latest committed state. */
+    private openWorkspace;
+    private replay;
+    private runQuery;
+    private lockRows;
+    private rowLockKey;
     private flushNotifies;
+    private executeClusterDdl;
     private listen;
     private unlisten;
     private query;
+    private copyStatement;
+    private copyColumnCount;
+    private handleCopyIn;
+    private beginCopyIn;
+    private finishCopyIn;
+    private flushCopyRecords;
+    private abortCopyIn;
+    private sendCopyOut;
     private sendOutcome;
     private columnFormats;
     private fields;

package/dist/wire/fleet.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The single source of time for a service.
+ *
+ * Every timestamp a mock writes reads from here, so a suite moves time instead of
+ * sleeping: appointment windows, result delays and expiries become reachable in
+ * milliseconds. A frozen clock also makes timestamps reproducible from a seed.
+ */
+type ClockState = {
+    /** Current epoch milliseconds. */
+    now: number;
+    /** True while time does not advance on its own. */
+    frozen: boolean;
+    /** Milliseconds this clock adds to its underlying source. */
+    offsetMs: number;
+};
+type Clock = {
+    now(): number;
+    /** Pin the clock to an exact instant, keeping it frozen if it already was. */
+    set(epochMs: number): void;
+    /** Move the clock forward, or back with a negative delta. */
+    advance(deltaMs: number): void;
+    /** Stop time at the current instant. */
+    freeze(): void;
+    /** Resume from the current instant. */
+    unfreeze(): void;
+    /** Drop back to the underlying source, live. */
+    reset(): void;
+    state(): ClockState;
+};
+
+type FleetDiagnostics = {
+    activeRequests: number;
+    activeConnections: number;
+    blockedCommands: number;
+    pendingJobs: number;
+    activeJobs?: number;
+    pendingWebhooks: number;
+    unmatchedRequests: number;
+};
+/** Protocol packages own their state, listeners, credentials and namespace selection. */
+type FleetChild = {
+    protocol: "http" | "postgres" | "redis";
+    url: string;
+    connection?: string;
+    connections?: Record<string, string>;
+    healthUrl?: string;
+    adminUrl?: string;
+    namespaces: Record<string, unknown>;
+    ready(): Promise<boolean>;
+    close(): Promise<void>;
+    /** Fence new work synchronously; diagnostics must also account for work already in flight. */
+    lock(namespace: string): () => void;
+    diagnostics(namespace: string): FleetDiagnostics;
+    checkpoint(namespace: string): Promise<unknown>;
+    restore(namespace: string, checkpoint: unknown): Promise<void>;
+    reset(namespace: string): Promise<void>;
+    clock(namespace: string): Clock;
+    settle?(namespace: string): Promise<void>;
+};
+
+/** A service entry in `mockingbird.json`. */
+type ConfigService = {
+    protocol?: "http" | "postgres" | "redis";
+    port?: number;
+    host?: string;
+    adminKey?: string;
+    seed?: string;
+    password?: string;
+    user?: string;
+    database?: string;
+    /** Protocol namespace selectors: database names for Postgres, logical DB indexes for Redis. */
+    namespaces?: Record<string, string | number>;
+    /** Service-specific serve flags, by long name: `{ "webhook-url": "…" }`. */
+    options?: Record<string, string | boolean>;
+};
+
+/** Separate database listeners make the protocol namespace explicit in discovery. */
+declare function startProtocol(entry: ConfigService): Promise<FleetChild>;
+
+export { startProtocol };

package/dist/wire/index.d.ts

@@ -55,6 +55,8 @@ export type ServeOptions = {
      * SQLSTATE `3D000`. Set from `url` when the path is non-empty. Unset accepts any name.
      */
     databaseName?: string;
+    /** Accept other databases in this listener's catalog while retaining its default URL. */
+    allowDatabaseSelection?: boolean;
     /** Role shown in `connectionString`. A URI's username fills this. Default `postgres`. */
     user?: string;
 };
@@ -67,14 +69,22 @@ export type PostgresServer = {
     readonly connectionString: string;
     /** The shared engine, for seeding, snapshotting or asserting from the test process. */
     readonly database: Database;
+    /** Names in the cluster catalog, in deterministic order. */
+    databaseNames(): readonly string[];
+    /** Resolve a named database, or throw SQLSTATE `3D000`. */
+    getDatabase(name: string): 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;
+    clearFaults(): void;
     /** Freeze the live state (the admin `snapshot()` control). */
-    snapshot(): Snapshot;
+    snapshot(name?: string): Snapshot;
+    snapshotAll(): Map<string, Snapshot>;
+    restoreAll(points: ReadonlyMap<string, Snapshot>): void;
+    faultState(): ServerFaults;
     /** Stop listening and close every connection. */
     close(): Promise<void>;
 };