@crvouga/mockingbird-service-postgres 1.4.0 → 1.5.0

package/dist/wire/connection.d.ts

@@ -21,6 +21,11 @@ export type ConnectionOptions = {
     parameters: Record<string, string>;
     faults: ServerFaults;
     onLog?: (entry: ServerLog) => void;
+    /**
+     * When set, a startup packet that names a different database is fatal `3D000`.
+     * Unset accepts any database name.
+     */
+    database?: string;
 };
 /**
  * One client connection: the protocol state machine over the shared {@link Cluster}.

package/dist/wire/index.d.ts

@@ -44,12 +44,27 @@ export type ServeOptions = {
     parameters?: Record<string, string>;
     /** Per-statement log sink, for tests and debugging. */
     onLog?: (entry: ServerLog) => void;
+    /**
+     * `postgres://` or `postgresql://` URL. User, password, host, port, and database name
+     * fill the fields above when those fields are omitted. An omitted port means `5432`;
+     * pass port `0` in the URL (`postgres://postgres@127.0.0.1:0/app`) for an ephemeral port.
+     */
+    url?: string;
+    /**
+     * Database name clients must request in the startup packet. A different name is
+     * SQLSTATE `3D000`. Set from `url` when the path is non-empty. Unset accepts any name.
+     */
+    databaseName?: string;
+    /** Role shown in `connectionString`. A URI's username fills this. Default `postgres`. */
+    user?: string;
 };
 export type PostgresServer = {
     /** The bound port. */
     readonly port: number;
     /** The bound host. */
     readonly host: string;
+    /** `postgres://` URL for the bound address, including the database name. */
+    readonly connectionString: string;
     /** The shared engine, for seeding, snapshotting or asserting from the test process. */
     readonly database: Database;
     /** The underlying `net.Server`. */
@@ -63,7 +78,8 @@ export type PostgresServer = {
     /** 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 type ServeInput = ServeOptions | string;
+/** Start a server and resolve once it is listening. A string argument is a `postgres://` URI. */
+export declare const serve: (input?: ServeInput) => Promise<PostgresServer>;
 export { Cluster } from "./cluster.js";
 export type { ServerFaults, ServerLog } from "./connection.js";

package/dist/wire/index.js

@@ -1,6 +1,167 @@
 // src/wire/index.ts
 import { createServer } from "node:net";
 
+// ../../core/dist/timeline.js
+var BRANCH_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var Timeline = class {
+  maxCheckpoints;
+  now;
+  makeId;
+  nodes = /* @__PURE__ */ new Map();
+  heads = /* @__PURE__ */ new Map();
+  /** Unreferenced nodes in the exact order they became collectible. */
+  evictable = /* @__PURE__ */ new Set();
+  /** Branch heads plus explicit retainers. Absent means zero. */
+  references = /* @__PURE__ */ new Map();
+  explicitPins = /* @__PURE__ */ new Map();
+  sequence = 0;
+  constructor(options = {}) {
+    const max = options.maxCheckpoints ?? 1e3;
+    if (!Number.isSafeInteger(max) || max < 1)
+      throw new RangeError("maxCheckpoints must be a positive integer");
+    this.maxCheckpoints = max;
+    this.now = options.now ?? (() => this.sequence);
+    this.makeId = options.id ?? ((sequence) => `cp_${sequence.toString(36).padStart(8, "0")}`);
+  }
+  /** Capture a new immutable value and move `branch` to it. */
+  commit(value, options = {}) {
+    const branch = options.branch ?? "main";
+    this.assertBranch(branch);
+    const parent = options.parent === void 0 ? this.heads.get(branch) ?? null : options.parent;
+    if (parent !== null && !this.nodes.has(parent))
+      throw new RangeError(`no checkpoint ${parent}`);
+    const id = this.makeId(++this.sequence);
+    if (this.nodes.has(id))
+      throw new RangeError(`duplicate checkpoint id ${id}`);
+    const checkpoint = Object.freeze({ id, branch, parent, at: this.now(), value });
+    this.nodes.set(id, checkpoint);
+    this.moveHead(branch, id);
+    this.collect(this.maxCheckpoints);
+    return checkpoint;
+  }
+  /** Create a branch pointer without copying its checkpoint value. */
+  fork(branch, options = {}) {
+    this.assertBranch(branch);
+    if (this.heads.has(branch))
+      throw new RangeError(`branch already exists: ${branch}`);
+    const from = options.from ?? this.heads.get("main");
+    if (from === void 0)
+      return void 0;
+    const checkpoint = this.get(from);
+    this.moveHead(branch, checkpoint.id);
+    return checkpoint;
+  }
+  /** Move a branch pointer to an existing checkpoint. */
+  checkout(branch, id) {
+    this.assertBranch(branch);
+    const checkpoint = this.get(id);
+    this.moveHead(branch, checkpoint.id);
+    return checkpoint;
+  }
+  get(id) {
+    const checkpoint = this.nodes.get(id);
+    if (!checkpoint)
+      throw new RangeError(`no checkpoint ${id}`);
+    return checkpoint;
+  }
+  head(branch = "main") {
+    const id = this.heads.get(branch);
+    return id === void 0 ? void 0 : this.get(id);
+  }
+  hasBranch(branch) {
+    return this.heads.has(branch);
+  }
+  branches() {
+    return Object.freeze(Object.fromEntries([...this.heads].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+  }
+  checkpoints() {
+    return [...this.nodes.values()];
+  }
+  /** Number of retained checkpoints without allocating an array. */
+  get size() {
+    return this.nodes.size;
+  }
+  /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+  retain(id) {
+    const checkpoint = this.get(id);
+    this.explicitPins.set(id, (this.explicitPins.get(id) ?? 0) + 1);
+    this.addReference(id);
+    return checkpoint;
+  }
+  /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+  release(id) {
+    if (!this.nodes.has(id))
+      return false;
+    const pins = this.explicitPins.get(id) ?? 0;
+    if (pins === 0)
+      return false;
+    if (pins === 1)
+      this.explicitPins.delete(id);
+    else
+      this.explicitPins.set(id, pins - 1);
+    this.removeReference(id);
+    this.collect(this.maxCheckpoints);
+    return true;
+  }
+  deleteBranch(branch) {
+    if (branch === "main")
+      throw new RangeError("cannot delete main branch");
+    const previous = this.heads.get(branch);
+    const deleted = this.heads.delete(branch);
+    if (previous !== void 0)
+      this.removeReference(previous);
+    this.collect(this.maxCheckpoints);
+    return deleted;
+  }
+  /**
+   * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+   * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+   * storage dependency, so a retained node remains usable after pruning.
+   */
+  gc(max = this.maxCheckpoints) {
+    if (!Number.isSafeInteger(max) || max < 1)
+      throw new RangeError("max must be a positive integer");
+    const removed = [];
+    this.collect(max, removed);
+    return removed;
+  }
+  collect(max, removed) {
+    while (this.nodes.size > max && this.evictable.size > 0) {
+      const id = this.evictable.values().next().value;
+      this.evictable.delete(id);
+      this.nodes.delete(id);
+      removed?.push(id);
+    }
+  }
+  moveHead(branch, id) {
+    const previous = this.heads.get(branch);
+    if (previous === id)
+      return;
+    if (previous !== void 0)
+      this.removeReference(previous);
+    this.heads.set(branch, id);
+    this.addReference(id);
+  }
+  addReference(id) {
+    this.references.set(id, (this.references.get(id) ?? 0) + 1);
+    this.evictable.delete(id);
+  }
+  removeReference(id) {
+    const next = (this.references.get(id) ?? 0) - 1;
+    if (next > 0)
+      this.references.set(id, next);
+    else {
+      this.references.delete(id);
+      if (this.nodes.has(id))
+        this.evictable.add(id);
+    }
+  }
+  assertBranch(branch) {
+    if (!BRANCH_PATTERN.test(branch))
+      throw new RangeError(`branch must match ${BRANCH_PATTERN}`);
+  }
+};
+
 // src/errors/error.ts
 var CATEGORY_TO_SQLSTATE = {
   syntax: "42601",
@@ -18733,7 +18894,7 @@ function setOpRelation(env, op) {
     return t === UNKNOWN ? "text" : t;
   });
   const columns = left.columns.map((c, i) => ({ name: c.name, type: types[i], table: null }));
-  const normalize = (rel2) => rel2.rows.map(
+  const normalize2 = (rel2) => rel2.rows.map(
     (row) => row.map((v, i) => {
       if (v === null) return null;
       const srcT = rel2.columns[i].type;
@@ -18741,8 +18902,8 @@ function setOpRelation(env, op) {
       return castTo(ctx, tv(srcT === UNKNOWN ? "text" : srcT, v), types[i], {}).v;
     })
   );
-  const lrows = normalize(left);
-  const rrows = normalize(right);
+  const lrows = normalize2(left);
+  const rrows = normalize2(right);
   const keyOf = (row) => row.map((v, i) => v === null ? "\0N" : datumKey(types[i], v)).join("
");
   let rows;
   switch (op.op) {
@@ -23114,6 +23275,9 @@ var ADOPT = /* @__PURE__ */ Symbol("postgres-mem.adopt");
 function isAdopted(value) {
   return ADOPT in value;
 }
+function project(point) {
+  return { id: point.id, branch: point.branch, parent: point.parent, at: point.at };
+}
 var Database = class {
   /** @internal Engine catalog, tables, session settings. */
   state;
@@ -23134,6 +23298,10 @@ var Database = class {
   closed = false;
   transactionSequence = 0;
   apiTransactionDepth = 0;
+  /** @internal Shared checkpoint DAG. Omitted from published declarations. */
+  timeline;
+  historyBranch = "main";
+  originId = "";
   constructor(options = {}) {
     if (isAdopted(options)) {
       this.seed = options.seed;
@@ -23146,16 +23314,23 @@ var Database = class {
       this.state.prng = this.prng;
       this.state.clock = () => this.now();
       this.transactions = txManagerFor(this.state);
-      return;
+    } else {
+      this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
+      this.randomMode = options.random ?? "deterministic";
+      this.systemClock = options.now === "system";
+      this.int8Mode = options.int8 ?? "bigint";
+      this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
+      this.now = resolveClock(options.now);
+      this.state = new DatabaseState(this.prng, () => this.now());
+      this.transactions = txManagerFor(this.state);
     }
-    this.seed = options.seed ?? DEFAULT_DATABASE_SEED;
-    this.randomMode = options.random ?? "deterministic";
-    this.systemClock = options.now === "system";
-    this.int8Mode = options.int8 ?? "bigint";
-    this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
-    this.now = resolveClock(options.now);
-    this.state = new DatabaseState(this.prng, () => this.now());
-    this.transactions = txManagerFor(this.state);
+    this.timeline = new Timeline({
+      now: () => this.now().getTime(),
+      ...options.maxCheckpoints !== void 0 ? { maxCheckpoints: options.maxCheckpoints } : {}
+    });
+    const origin = this.timeline.commit(this.captureLive());
+    this.originId = origin.id;
+    this.timeline.retain(origin.id);
   }
   /**
    * Execute SQL for its side effects. Multiple semicolon-separated statements
@@ -23210,7 +23385,15 @@ var Database = class {
   /** Execute a single-statement query and return all rows keyed by column name. */
   query(sql, params = [], options = {}) {
     this.assertOpen();
-    if (options.at) return options.at.open().query(sql, params);
+    const at = options.at;
+    if (typeof at === "string") {
+      try {
+        return this.timeline.get(at).value.open().query(sql, params);
+      } catch (error) {
+        this.historyError(error);
+      }
+    }
+    if (at) return at.open().query(sql, params);
     return this.prepareSingle(sql).all(...params);
   }
   /** Compile a single SQL statement into a reusable {@link Statement}. */
@@ -23258,23 +23441,77 @@ var Database = class {
    * {@link Snapshot.open} for a copy-on-write fork.
    */
   snapshot() {
+    const point = this.record(this.historyBranch);
+    return this.timeline.get(point.id).value;
+  }
+  /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
+  checkpoint() {
+    return this.snapshot();
+  }
+  /**
+   * Commit the live state onto `branch` (default: the branch this database follows).
+   * Does not switch the live database. Illegal inside a transaction.
+   */
+  record(branch = this.historyBranch) {
     this.assertOpen();
     if (this.transactions.inTransaction) {
       throw pgError("transaction_state", "cannot snapshot during a transaction", "25P01");
     }
-    return captureSnapshot(
-      this.state,
-      this.prng,
-      this.now,
-      this.seed,
-      this.randomMode,
-      this.systemClock,
-      this.int8Mode
-    );
+    try {
+      return project(this.timeline.commit(this.captureLive(), { branch }));
+    } catch (error) {
+      this.historyError(error);
+    }
   }
-  /** Alias for {@link snapshot}, naming the value as a timeline checkpoint. */
-  checkpoint() {
-    return this.snapshot();
+  /** Point `name` at a checkpoint without copying rows or switching the live database. */
+  fork(name, at) {
+    this.assertOpen();
+    try {
+      const point = this.timeline.fork(name, at !== void 0 ? { from: at } : {});
+      if (!point) throw pgError("misuse", "no checkpoint to fork from", "XX000");
+      return project(point);
+    } catch (error) {
+      if (error instanceof PostgresError) throw error;
+      this.historyError(error);
+    }
+  }
+  /** Move `branch` to `id` and install that checkpoint as the live database. */
+  checkout(id, branch = this.historyBranch) {
+    this.assertOpen();
+    if (this.transactions.inTransaction) {
+      throw pgError("transaction_state", "cannot checkout during a transaction", "25P01");
+    }
+    try {
+      const point = this.timeline.checkout(branch, id);
+      this.historyBranch = branch;
+      this.install(point.value);
+      return project(point);
+    } catch (error) {
+      this.historyError(error);
+    }
+  }
+  /** Return the live database to the origin checkpoint on `main`. */
+  reset() {
+    return this.checkout(this.originId, "main");
+  }
+  /** Checkpoint ids and branch heads. Values stay inside the timeline. */
+  get history() {
+    const timeline = this.timeline;
+    return {
+      get size() {
+        return timeline.size;
+      },
+      head(branch) {
+        const point = timeline.head(branch);
+        return point ? project(point) : void 0;
+      },
+      branches() {
+        return timeline.branches();
+      },
+      checkpoints() {
+        return timeline.checkpoints().map(project);
+      }
+    };
   }
   /** Open a copy-on-write branch from `at`, or from the current state when omitted. */
   branch(at = this.snapshot()) {
@@ -23319,6 +23556,26 @@ var Database = class {
   assertOpen() {
     if (this.closed) throw pgError("misuse", "Database is closed", "XX000");
   }
+  historyError(error) {
+    const message2 = error instanceof Error ? error.message : String(error);
+    throw pgError("misuse", message2, "XX000");
+  }
+  captureLive() {
+    return captureSnapshot(
+      this.state,
+      this.prng,
+      this.now,
+      this.seed,
+      this.randomMode,
+      this.systemClock,
+      this.int8Mode
+    );
+  }
+  install(snapshot) {
+    this.state.restoreFrom(snapshot.state.cloneShallow());
+    this.prng.setState(snapshot.prngState);
+    if (!this.systemClock) this.now = fixedClock(new Date(snapshot.nowMs));
+  }
   prepareSingle(sql) {
     const statements = parse(sql);
     if (statements.length === 0) {
@@ -24208,6 +24465,11 @@ var Connection = class {
       return;
     }
     this.user = parameters.user ?? "postgres";
+    const requested = parameters.database && parameters.database.length > 0 ? parameters.database : this.user;
+    if (this.options.database !== void 0 && requested !== this.options.database) {
+      this.fatal("3D000", `database "${requested}" does not exist`);
+      return;
+    }
     if (this.options.password !== void 0) {
       this.scram = new ScramServer(this.options.password);
       this.write(backend.authenticationSASL(["SCRAM-SHA-256"]));
@@ -24649,13 +24911,53 @@ var ConnectionDropped = class extends Error {
 };
 
 // src/wire/index.ts
+var parseUri = (raw) => {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`invalid postgres URI: ${raw}`);
+  }
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
+    throw new Error(`unsupported postgres URI protocol ${url.protocol}`);
+  }
+  const databaseName = decodeURIComponent(url.pathname.replace(/^\//, ""));
+  const password = url.password === "" ? void 0 : decodeURIComponent(url.password);
+  const user = decodeURIComponent(url.username || "postgres");
+  const port = url.port === "" ? 5432 : Number(url.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`invalid postgres URI port: ${url.port}`);
+  return {
+    host: url.hostname || "127.0.0.1",
+    port,
+    user,
+    ...password !== void 0 ? { password } : {},
+    ...databaseName !== "" ? { databaseName } : {}
+  };
+};
+var normalize = (input) => {
+  if (typeof input === "string") return parseUri(input);
+  if (input.url === void 0) return input;
+  const parsed = parseUri(input.url);
+  return {
+    ...parsed,
+    ...input,
+    host: input.host ?? parsed.host,
+    port: input.port ?? parsed.port,
+    password: input.password ?? parsed.password,
+    databaseName: input.databaseName ?? parsed.databaseName,
+    user: input.user ?? parsed.user,
+    parameters: input.parameters ?? parsed.parameters
+  };
+};
 var isSnapshot = (value) => typeof value === "object" && value !== null && "open" in value && typeof value.open === "function";
-var serve = (options = {}) => {
+var serve = (input = {}) => {
+  const options = normalize(input);
   const database = isSnapshot(options.database) ? options.database.open() : options.database ?? new Database();
   const cluster = new Cluster(database);
   const faults = {};
   const connections = /* @__PURE__ */ new Set();
   const host = options.host ?? "127.0.0.1";
+  const user = options.user || "postgres";
   const server = createServer((socket) => {
     socket.setNoDelay(true);
     const connection = new Connection(socket, cluster, {
@@ -24663,6 +24965,7 @@ var serve = (options = {}) => {
       serverVersion: options.serverVersion ?? "18.3",
       parameters: options.parameters ?? {},
       faults,
+      ...options.databaseName !== void 0 ? { database: options.databaseName } : {},
       ...options.onLog ? { onLog: options.onLog } : {}
     });
     connections.add(connection);
@@ -24674,9 +24977,12 @@ var serve = (options = {}) => {
       server.removeListener("error", reject);
       const address = server.address();
       const port = typeof address === "object" && address !== null ? address.port : 0;
+      const name = options.databaseName ?? "postgres";
+      const auth = options.password ? `${encodeURIComponent(user)}:${encodeURIComponent(options.password)}@` : `${encodeURIComponent(user)}@`;
       resolve({
         port,
         host,
+        connectionString: `postgres://${auth}${host}:${port}/${encodeURIComponent(name)}`,
         database,
         server,
         get connections() {