@crvouga/mockingbird-service-postgres 1.4.0 → 1.5.1

package/dist/runtime/options.d.ts

@@ -29,6 +29,11 @@ export interface DatabaseOptions {
      * `"string"` is JSON-safe.
      */
     int8?: Int8Mode;
+    /**
+     * Retained timeline checkpoints. Branch heads and the origin pin are never
+     * collected. Default 1,000.
+     */
+    maxCheckpoints?: number;
 }
 /** Default {@link DatabaseOptions.seed} when constructing a {@link Database}. */
 export declare const DEFAULT_DATABASE_SEED = 1;

package/dist/wire/cli.js

@@ -3,6 +3,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(options2 = {}) {
+    const max = options2.maxCheckpoints ?? 1e3;
+    if (!Number.isSafeInteger(max) || max < 1)
+      throw new RangeError("maxCheckpoints must be a positive integer");
+    this.maxCheckpoints = max;
+    this.now = options2.now ?? (() => this.sequence);
+    this.makeId = options2.id ?? ((sequence) => `cp_${sequence.toString(36).padStart(8, "0")}`);
+  }
+  /** Capture a new immutable value and move `branch` to it. */
+  commit(value, options2 = {}) {
+    const branch = options2.branch ?? "main";
+    this.assertBranch(branch);
+    const parent = options2.parent === void 0 ? this.heads.get(branch) ?? null : options2.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, options2 = {}) {
+    this.assertBranch(branch);
+    if (this.heads.has(branch))
+      throw new RangeError(`branch already exists: ${branch}`);
+    const from = options2.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",
@@ -18735,7 +18896,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;
@@ -18743,8 +18904,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) {
@@ -23116,6 +23277,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;
@@ -23136,6 +23300,10 @@ var Database = class {
   closed = false;
   transactionSequence = 0;
   apiTransactionDepth = 0;
+  /** @internal Shared checkpoint DAG. Omitted from published declarations. */
+  timeline;
+  historyBranch = "main";
+  originId = "";
   constructor(options2 = {}) {
     if (isAdopted(options2)) {
       this.seed = options2.seed;
@@ -23148,16 +23316,23 @@ var Database = class {
       this.state.prng = this.prng;
       this.state.clock = () => this.now();
       this.transactions = txManagerFor(this.state);
-      return;
+    } else {
+      this.seed = options2.seed ?? DEFAULT_DATABASE_SEED;
+      this.randomMode = options2.random ?? "deterministic";
+      this.systemClock = options2.now === "system";
+      this.int8Mode = options2.int8 ?? "bigint";
+      this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
+      this.now = resolveClock(options2.now);
+      this.state = new DatabaseState(this.prng, () => this.now());
+      this.transactions = txManagerFor(this.state);
     }
-    this.seed = options2.seed ?? DEFAULT_DATABASE_SEED;
-    this.randomMode = options2.random ?? "deterministic";
-    this.systemClock = options2.now === "system";
-    this.int8Mode = options2.int8 ?? "bigint";
-    this.prng = this.randomMode === "os" ? new OsEntropy() : new Prng(this.seed);
-    this.now = resolveClock(options2.now);
-    this.state = new DatabaseState(this.prng, () => this.now());
-    this.transactions = txManagerFor(this.state);
+    this.timeline = new Timeline({
+      now: () => this.now().getTime(),
+      ...options2.maxCheckpoints !== void 0 ? { maxCheckpoints: options2.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
@@ -23212,7 +23387,15 @@ var Database = class {
   /** Execute a single-statement query and return all rows keyed by column name. */
   query(sql, params = [], options2 = {}) {
     this.assertOpen();
-    if (options2.at) return options2.at.open().query(sql, params);
+    const at = options2.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}. */
@@ -23260,23 +23443,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()) {
@@ -23321,6 +23558,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) {
@@ -24210,6 +24467,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"]));
@@ -24651,13 +24913,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 = (options2 = {}) => {
+var serve = (input = {}) => {
+  const options2 = normalize(input);
   const database = isSnapshot(options2.database) ? options2.database.open() : options2.database ?? new Database();
   const cluster = new Cluster(database);
   const faults = {};
   const connections = /* @__PURE__ */ new Set();
   const host = options2.host ?? "127.0.0.1";
+  const user = options2.user || "postgres";
   const server2 = createServer((socket) => {
     socket.setNoDelay(true);
     const connection = new Connection(socket, cluster, {
@@ -24665,6 +24967,7 @@ var serve = (options2 = {}) => {
       serverVersion: options2.serverVersion ?? "18.3",
       parameters: options2.parameters ?? {},
       faults,
+      ...options2.databaseName !== void 0 ? { database: options2.databaseName } : {},
       ...options2.onLog ? { onLog: options2.onLog } : {}
     });
     connections.add(connection);
@@ -24676,9 +24979,12 @@ var serve = (options2 = {}) => {
       server2.removeListener("error", reject);
       const address = server2.address();
       const port = typeof address === "object" && address !== null ? address.port : 0;
+      const name = options2.databaseName ?? "postgres";
+      const auth = options2.password ? `${encodeURIComponent(user)}:${encodeURIComponent(options2.password)}@` : `${encodeURIComponent(user)}@`;
       resolve({
         port,
         host,
+        connectionString: `postgres://${auth}${host}:${port}/${encodeURIComponent(name)}`,
         database,
         server: server2,
         get connections() {
@@ -24703,7 +25009,7 @@ var serve = (options2 = {}) => {
 };
 
 // src/wire/cli.ts
-var usage = `mockingbird-postgres serve [--port <n>] [--host <h>] [--password <p>] [--server-version <v>] [--log]`;
+var usage = `mockingbird-postgres serve [postgres://URI] [--port <n>] [--host <h>] [--password <p>] [--server-version <v>] [--log]`;
 var args = process.argv.slice(2);
 if (args[0] !== "serve") {
   console.error(usage);
@@ -24713,6 +25019,10 @@ var options = {};
 var log = false;
 for (let i = 1; i < args.length; i++) {
   const flag = args[i];
+  if (flag !== void 0 && (flag.startsWith("postgres://") || flag.startsWith("postgresql://"))) {
+    options.url = flag;
+    continue;
+  }
   const value = args[i + 1];
   const need = () => {
     if (value === void 0) {
@@ -24750,8 +25060,7 @@ if (log) {
   );
 }
 var server = await serve(options);
-var auth = options.password ? `postgres:${options.password}@` : "postgres@";
-console.log(`mockingbird-postgres listening on postgres://${auth}${server.host}:${server.port}/postgres`);
+console.log(`mockingbird-postgres listening on ${server.connectionString}`);
 var stop = async () => {
   await server.close();
   process.exit(0);