@crvouga/mockingbird-service-postgres 3.4.1 → 3.5.0

package/dist/server.js

@@ -30533,6 +30533,9 @@ var start = async (options) => {
   });
 };
 
+// src/wire/fleet.ts
+import { createHash as createHash4 } from "node:crypto";
+
 // ../core/dist/clock.js
 var createClock = (source = Date.now) => {
   let offsetMs = 0;
@@ -30574,6 +30577,310 @@ var createClock = (source = Date.now) => {
   };
 };
 
+// ../core/dist/controls.js
+var ControlError = class extends RangeError {
+  constructor(message2) {
+    super(message2);
+    this.name = "ControlError";
+  }
+};
+var UNITS = {
+  ms: 1,
+  s: 1e3,
+  m: 6e4,
+  h: 36e5,
+  d: 864e5
+};
+var parseDuration = (value) => {
+  if (typeof value === "number")
+    return Number.isFinite(value) ? value : void 0;
+  if (typeof value !== "string")
+    return void 0;
+  const match = /^(-?\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/.exec(value.trim());
+  if (!match)
+    return void 0;
+  return Number(match[1]) * UNITS[match[2] ?? "ms"];
+};
+var parseInstant = (value) => {
+  if (typeof value === "number")
+    return Number.isFinite(value) ? value : void 0;
+  if (typeof value !== "string")
+    return void 0;
+  const text = value.trim();
+  if (/^-?\d+$/.test(text))
+    return Number(text);
+  const parsed = Date.parse(text);
+  return Number.isNaN(parsed) ? void 0 : parsed;
+};
+var durationMs = (value, label, negative = false) => {
+  const parsed = parseDuration(value);
+  if (parsed === void 0)
+    throw new ControlError(`${label}: expected milliseconds or a duration like "250ms" or "15m"`);
+  if (!negative && parsed < 0)
+    throw new ControlError(`${label}: must not be negative`);
+  return parsed;
+};
+var instantMs = (value, label) => {
+  const parsed = parseInstant(value);
+  if (parsed === void 0)
+    throw new ControlError(`${label}: expected epoch ms or ISO-8601`);
+  return parsed;
+};
+var normalizeSeed = (seed, label = "seed") => {
+  if (typeof seed === "number" && Number.isFinite(seed))
+    return seed;
+  if (typeof seed === "string" && seed !== "")
+    return /^\d+$/.test(seed) ? Number(seed) : seed;
+  throw new ControlError(`${label}: expected a number or a non-empty string`);
+};
+var SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
+var NAMESPACE_KEYS = /* @__PURE__ */ new Set(["seed", "clock", "virtualTime", "latency", "faults", "snapshot"]);
+var MOCK_KEYS = /* @__PURE__ */ new Set([...NAMESPACE_KEYS, "credentials", "namespaces"]);
+var REPORTED_KEYS = /* @__PURE__ */ new Set(["namespace", "snapshots"]);
+var REPORTED_CLOCK_KEYS = /* @__PURE__ */ new Set(["iso", "offsetMs"]);
+var KEY_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var unknownKeys = (value, known, label, reported) => {
+  for (const key of Object.keys(value)) {
+    if (!known.has(key) && !reported?.has(key))
+      throw new ControlError(`${label}: unknown control ${JSON.stringify(key)}; expected ${[...known].join(", ")}`);
+  }
+};
+var latencyRule = (value, label) => {
+  if (!isRecord2(value))
+    return { delayMs: durationMs(value, label), jitterMs: 0 };
+  unknownKeys(value, /* @__PURE__ */ new Set(["delay", "jitter", "delayMs", "jitterMs", "operations"]), label);
+  return {
+    delayMs: durationMs(value.delay ?? value.delayMs ?? 0, `${label}.delay`),
+    jitterMs: durationMs(value.jitter ?? value.jitterMs ?? 0, `${label}.jitter`)
+  };
+};
+var normalizeLatency = (value, label = "latency") => {
+  const base = latencyRule(value, label);
+  const operations = {};
+  if (isRecord2(value) && value.operations !== void 0) {
+    if (!isRecord2(value.operations))
+      throw new ControlError(`${label}.operations: expected an object keyed by operationId`);
+    for (const [operationId, rule] of Object.entries(value.operations)) {
+      if (isRecord2(rule) && rule.operations !== void 0)
+        throw new ControlError(`${label}.operations.${operationId}: cannot nest operations`);
+      operations[operationId] = latencyRule(rule, `${label}.operations.${operationId}`);
+    }
+  }
+  return { ...base, operations };
+};
+var normalizeClock = (value, label = "clock") => {
+  if (!isRecord2(value))
+    throw new ControlError(`${label}: expected an object`);
+  unknownKeys(value, /* @__PURE__ */ new Set(["now", "set", "frozen", "freeze", "autoAdvance", "autoAdvanceMs"]), label, REPORTED_CLOCK_KEYS);
+  const plan = {};
+  const now = value.now ?? value.set;
+  if (now !== void 0)
+    plan.now = instantMs(now, `${label}.now`);
+  const frozen = value.frozen ?? value.freeze;
+  if (frozen !== void 0) {
+    if (typeof frozen !== "boolean")
+      throw new ControlError(`${label}.frozen: expected a boolean`);
+    plan.frozen = frozen;
+  }
+  const auto = value.autoAdvance ?? value.autoAdvanceMs;
+  if (auto !== void 0)
+    plan.autoAdvanceMs = durationMs(auto, `${label}.autoAdvance`);
+  return plan;
+};
+var assertSnapshotDocument = (value, label = "snapshot") => {
+  if (!isRecord2(value))
+    throw new ControlError(`${label}: expected a snapshot document`);
+  if (value.format !== SNAPSHOT_FORMAT)
+    throw new ControlError(`${label}.format: expected ${JSON.stringify(SNAPSHOT_FORMAT)}`);
+  if (!Array.isArray(value.records))
+    throw new ControlError(`${label}.records: expected a list`);
+  value.records.forEach((row, index) => {
+    if (!isRecord2(row) || typeof row.collection !== "string" || typeof row.id !== "string" || row.value === void 0 && typeof row.raw !== "string" || row.seq !== void 0 && !Number.isSafeInteger(row.seq))
+      throw new ControlError(`${label}.records[${index}]: expected {collection, id, value, seq?}`);
+  });
+  if (value.sequences !== void 0) {
+    if (!Array.isArray(value.sequences))
+      throw new ControlError(`${label}.sequences: expected a list`);
+    value.sequences.forEach((row, index) => {
+      if (!isRecord2(row) || typeof row.name !== "string" || typeof row.kind !== "string" || !Number.isSafeInteger(row.value))
+        throw new ControlError(`${label}.sequences[${index}]: expected {name, kind, value}`);
+    });
+  }
+  if (value.clock !== void 0) {
+    if (!isRecord2(value.clock) || typeof value.clock.now !== "number" || !Number.isFinite(value.clock.now) || typeof value.clock.frozen !== "boolean")
+      throw new ControlError(`${label}.clock: expected {now, frozen}`);
+  }
+  return value;
+};
+var normalizeControls = (value, label = "controls") => {
+  if (!isRecord2(value))
+    throw new ControlError(`${label}: expected an object`);
+  unknownKeys(value, NAMESPACE_KEYS, label, REPORTED_KEYS);
+  const plan = {};
+  if (value.seed !== void 0)
+    plan.seed = normalizeSeed(value.seed, `${label}.seed`);
+  if (value.clock !== void 0)
+    plan.clock = normalizeClock(value.clock, `${label}.clock`);
+  if (value.virtualTime !== void 0) {
+    if (typeof value.virtualTime !== "boolean")
+      throw new ControlError(`${label}.virtualTime: expected a boolean`);
+    plan.virtualTime = value.virtualTime;
+  }
+  if (value.latency !== void 0)
+    plan.latency = normalizeLatency(value.latency, `${label}.latency`);
+  if (value.faults !== void 0) {
+    if (!Array.isArray(value.faults) || !value.faults.every(isRecord2))
+      throw new ControlError(`${label}.faults: expected a list of fault rules`);
+    plan.faults = value.faults;
+  }
+  if (value.snapshot !== void 0)
+    plan.snapshot = assertSnapshotDocument(value.snapshot, `${label}.snapshot`);
+  return plan;
+};
+var normalizeBootControls = (value, label = "controls") => {
+  if (value === void 0)
+    return { shared: {}, namespaces: {}, credentials: {} };
+  if (!isRecord2(value))
+    throw new ControlError(`${label}: expected an object`);
+  unknownKeys(value, MOCK_KEYS, label);
+  const { credentials, namespaces, ...shared } = value;
+  const plan = {
+    shared: normalizeControls(shared, label),
+    namespaces: {},
+    credentials: {}
+  };
+  if (namespaces !== void 0) {
+    if (!isRecord2(namespaces))
+      throw new ControlError(`${label}.namespaces: expected an object`);
+    for (const [name, each] of Object.entries(namespaces)) {
+      if (!KEY_PATTERN.test(name))
+        throw new ControlError(`${label}.namespaces: bad namespace ${JSON.stringify(name)}`);
+      plan.namespaces[name] = normalizeControls(each, `${label}.namespaces.${name}`);
+    }
+  }
+  if (credentials !== void 0) {
+    if (!isRecord2(credentials))
+      throw new ControlError(`${label}.credentials: expected an object`);
+    for (const [credential, namespace] of Object.entries(credentials)) {
+      if (typeof namespace !== "string" || !KEY_PATTERN.test(namespace))
+        throw new ControlError(`${label}.credentials: bad namespace for a credential`);
+      plan.credentials[credential] = namespace;
+    }
+  }
+  return plan;
+};
+var CONTROL_HEADERS = {
+  namespace: "x-mockingbird-namespace",
+  adminKey: "x-mockingbird-admin-key",
+  branch: "x-mockingbird-branch",
+  at: "x-mockingbird-at",
+  reset: "x-mockingbird-reset",
+  restore: "x-mockingbird-restore",
+  seed: "x-mockingbird-seed",
+  time: "x-mockingbird-time",
+  advance: "x-mockingbird-advance",
+  virtualTime: "x-mockingbird-virtual-time",
+  fault: "x-mockingbird-fault",
+  delay: "x-mockingbird-delay",
+  timeout: "x-mockingbird-timeout",
+  snapshot: "x-mockingbird-snapshot"
+};
+var CONTROL_HEADER_REFERENCE = [
+  {
+    header: CONTROL_HEADERS.namespace,
+    value: "<key>",
+    scope: "select",
+    guarded: false,
+    summary: "Isolation key. Each key has its own records, clock, random streams, faults, latency, journal and snapshots."
+  },
+  {
+    header: CONTROL_HEADERS.branch,
+    value: "<name>",
+    scope: "select",
+    guarded: false,
+    summary: "Read and write a named copy-on-write branch of the namespace's history."
+  },
+  {
+    header: CONTROL_HEADERS.at,
+    value: "<checkpoint>",
+    scope: "select",
+    guarded: false,
+    summary: "Read the namespace as it was at a checkpoint. With a branch, start the branch there."
+  },
+  {
+    header: CONTROL_HEADERS.reset,
+    value: "true",
+    scope: "namespace",
+    guarded: true,
+    summary: "Reset the namespace to its boot state before the request is handled."
+  },
+  {
+    header: CONTROL_HEADERS.restore,
+    value: "<snapshot>",
+    scope: "namespace",
+    guarded: true,
+    summary: "Restore a snapshot before the request is handled."
+  },
+  {
+    header: CONTROL_HEADERS.seed,
+    value: "<seed>",
+    scope: "namespace",
+    guarded: true,
+    summary: "Restart the namespace's random streams from this seed."
+  },
+  {
+    header: CONTROL_HEADERS.time,
+    value: "<epoch ms | ISO-8601>",
+    scope: "namespace",
+    guarded: true,
+    summary: "Freeze the namespace clock at this instant."
+  },
+  {
+    header: CONTROL_HEADERS.advance,
+    value: "<duration>",
+    scope: "namespace",
+    guarded: true,
+    summary: "Move the namespace clock by this much, forward or (negative) back."
+  },
+  {
+    header: CONTROL_HEADERS.virtualTime,
+    value: "true | false",
+    scope: "namespace",
+    guarded: true,
+    summary: "Spend injected waits on the mock clock (true) or the wall clock (false)."
+  },
+  {
+    header: CONTROL_HEADERS.delay,
+    value: "<duration>",
+    scope: "request",
+    guarded: true,
+    summary: "Hold this response back this long, on top of the namespace's latency."
+  },
+  {
+    header: CONTROL_HEADERS.timeout,
+    value: "<duration>",
+    scope: "request",
+    guarded: true,
+    summary: "Never answer this request: hold it this long, then drop the connection."
+  },
+  {
+    header: CONTROL_HEADERS.fault,
+    value: '<status> | drop | <preset> | key=value; \u2026 | {"status": 503, \u2026}',
+    scope: "request",
+    guarded: true,
+    summary: "Fault this request only. Stored fault rules are not consulted when it answers."
+  },
+  {
+    header: CONTROL_HEADERS.snapshot,
+    value: "<name>",
+    scope: "namespace",
+    guarded: true,
+    summary: "Snapshot the namespace after the request is handled. Echoed on the response."
+  }
+];
+var GUARDED = CONTROL_HEADER_REFERENCE.filter((each) => each.guarded).map((each) => each.header);
+
 // src/wire/probe.ts
 import { createHash as createHash3, createHmac as createHmac2, pbkdf2Sync as pbkdf2Sync2, randomBytes as randomBytes2 } from "node:crypto";
 import { createConnection } from "node:net";
@@ -30678,26 +30985,38 @@ function probe(connectionString) {
 async function startProtocol(entry) {
   const namespaces = /* @__PURE__ */ new Map();
   const selectors = { default: entry.database ?? "postgres", ...entry.namespaces };
+  if (entry.seed !== void 0 && (!String(entry.seed).trim() || !Number.isFinite(Number(entry.seed))))
+    throw new Error("Postgres seed must be a finite number");
+  let admission;
+  const boot = normalizeBootControls(entry.adminControls);
+  const create = async (name, databaseName, port = 0) => {
+    if (!/^[A-Za-z0-9_.-]{1,64}$/.test(name) || typeof databaseName !== "string" || !databaseName.length)
+      throw new Error("invalid Postgres namespace/database name");
+    const clock = createClock();
+    const control = { ...boot.shared.clock, ...boot.namespaces[name]?.clock };
+    if (control.frozen) clock.freeze();
+    if (control.now !== void 0) clock.set(control.now);
+    const database = new Database({
+      now: () => new Date(clock.now()),
+      ...entry.seed !== void 0 ? { seed: Number(entry.seed) } : {}
+    });
+    const server = await serve({
+      database,
+      databaseName,
+      allowDatabaseSelection: true,
+      host: entry.host ?? "127.0.0.1",
+      port,
+      ...entry.password !== void 0 ? { password: entry.password } : {},
+      ...entry.user !== void 0 ? { user: entry.user } : {}
+    });
+    server.server.prependListener("connection", (socket) => {
+      if (admission?.(name) === false) socket.destroy();
+    });
+    namespaces.set(name, { server, clock });
+  };
   try {
-    for (const [name, databaseName] of Object.entries(selectors)) {
-      if (!/^[A-Za-z0-9_.-]{1,64}$/.test(name) || typeof databaseName !== "string")
-        throw new Error("invalid Postgres namespace/database name");
-      const clock = createClock();
-      const database = new Database({
-        now: () => new Date(clock.now()),
-        ...entry.seed !== void 0 ? { seed: Number(entry.seed) } : {}
-      });
-      const server = await serve({
-        database,
-        databaseName,
-        allowDatabaseSelection: true,
-        host: entry.host ?? "127.0.0.1",
-        port: name === "default" ? entry.port ?? 0 : 0,
-        ...entry.password !== void 0 ? { password: entry.password } : {},
-        ...entry.user !== void 0 ? { user: entry.user } : {}
-      });
-      namespaces.set(name, { server, clock });
-    }
+    for (const [name, databaseName] of Object.entries(selectors))
+      await create(name, databaseName, name === "default" ? entry.port ?? 0 : 0);
   } catch (error) {
     await Promise.allSettled([...namespaces.values()].map(({ server }) => server.close()));
     throw error;
@@ -30719,17 +31038,143 @@ async function startProtocol(entry) {
     protocol: "postgres",
     url: publicUrl("default"),
     connection: get("default").server.connectionString,
-    connections: Object.fromEntries([...namespaces].map(([name, { server }]) => [name, server.connectionString])),
-    namespaces: {
-      mechanism: "endpoint",
-      endpoints: Object.fromEntries([...namespaces.keys()].map((name) => [name, publicUrl(name)]))
+    get connections() {
+      return Object.fromEntries([...namespaces].map(([name, { server }]) => [name, server.connectionString]));
+    },
+    get namespaces() {
+      return {
+        mechanism: "endpoint",
+        endpoints: Object.fromEntries([...namespaces.keys()].map((name) => [name, publicUrl(name)]))
+      };
+    },
+    async createNamespace(name) {
+      if (namespaces.has(name)) throw new Error("namespace already exists");
+      await create(name, entry.database ?? "postgres");
+      origins.set(name, get(name).server.snapshotAll());
+    },
+    async deleteNamespace(name) {
+      const { server } = get(name);
+      if (server.connections) throw new Error("Postgres namespace has open sessions");
+      await server.close();
+      for (const database of server.databaseNames()) server.getDatabase(database).close();
+      namespaces.delete(name);
+      origins.delete(name);
+    },
+    async exportCheckpoint(namespace, handle) {
+      const point = typeof handle === "object" && handle !== null ? snapshots.get(handle) : void 0;
+      if (!point || point.namespace !== namespace) throw new Error("invalid Postgres checkpoint");
+      return {
+        format: "mockingbird.postgres/v1",
+        inventory: Object.fromEntries(
+          [...point.databases].map(([name, snapshot]) => {
+            const database = snapshot.open();
+            try {
+              const tables = database.prepare("SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema = 'public'").all();
+              return [
+                name,
+                Object.fromEntries(
+                  tables.map((table) => {
+                    const identifier2 = table.table_name.replaceAll('"', '""');
+                    const rows = database.prepare(`SELECT * FROM public."${identifier2}"`).all();
+                    return [
+                      table.table_name,
+                      {
+                        count: rows.length,
+                        records: Object.fromEntries(
+                          rows.map((row, index) => [
+                            String(row.id ?? index),
+                            createHash4("sha256").update(
+                              JSON.stringify(
+                                row,
+                                (_key, value) => typeof value === "bigint" ? String(value) : value
+                              )
+                            ).digest("hex")
+                          ])
+                        )
+                      }
+                    ];
+                  })
+                )
+              ];
+            } finally {
+              database.close();
+            }
+          })
+        ),
+        databases: [...point.databases].map(([name, snapshot]) => ({
+          name,
+          bytes: Buffer.from(snapshot.encode()).toString("base64")
+        })),
+        clock: point.clock,
+        faults: point.faults
+      };
+    },
+    async importCheckpoint(namespace, document) {
+      const doc = document;
+      if (doc?.format !== "mockingbird.postgres/v1" || !Array.isArray(doc.databases) || !doc.databases.length || !Number.isFinite(doc.clock?.now) || typeof doc.clock?.frozen !== "boolean")
+        throw new Error("invalid Postgres archive");
+      const databases = /* @__PURE__ */ new Map();
+      for (const row of doc.databases) {
+        if (typeof row.name !== "string" || databases.has(row.name) || typeof row.bytes !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(row.bytes))
+          throw new Error("invalid Postgres archive database");
+        databases.set(row.name, Snapshot.decode(Buffer.from(row.bytes, "base64")));
+      }
+      const handle = {};
+      snapshots.set(handle, { namespace, databases, clock: doc.clock, faults: doc.faults ?? {} });
+      return handle;
+    },
+    async inspect(namespace, { offset, limit, collection }) {
+      const { server } = get(namespace);
+      const database = server.getDatabase(server.databaseNames()[0]);
+      const tables = database.prepare("SELECT table_schema, table_name FROM information_schema.tables WHERE table_schema = 'public'").all();
+      if (!collection) return { tables };
+      const table = collection.replaceAll('"', '""');
+      return {
+        records: database.prepare(`SELECT * FROM public."${table}" LIMIT ${limit} OFFSET ${offset}`).all(),
+        offset
+      };
+    },
+    async initializationAccess() {
+      const privateServers = [];
+      const connections = {};
+      try {
+        for (const [name, { server }] of namespaces) {
+          const databaseName = server.databaseNames()[0];
+          const seedServer = await serve({
+            database: server.getDatabase(databaseName),
+            databaseName,
+            port: 0,
+            host: "127.0.0.1",
+            ...entry.user ? { user: entry.user } : {},
+            ...entry.password ? { password: entry.password } : {}
+          });
+          privateServers.push(seedServer);
+          connections[name] = seedServer.connectionString;
+        }
+      } catch (error) {
+        await Promise.allSettled(privateServers.map((s) => s.close()));
+        throw error;
+      }
+      return {
+        connections,
+        close: async () => {
+          await Promise.all(privateServers.map((s) => s.close()));
+        }
+      };
+    },
+    setAdmission(allow) {
+      admission = allow;
     },
     async ready() {
+      if (admission) return [...namespaces.values()].every(({ server }) => server.server.listening);
       const results = await Promise.all(
         [...namespaces.values()].map(
           ({ server }) => server.server.listening ? probe(server.connectionString) : false
         )
       );
+      const deadline = Date.now() + 2e3;
+      while ([...namespaces.values()].some(({ server }) => server.connections > 0) && Date.now() < deadline)
+        await new Promise((resolve) => setTimeout(resolve, 1));
       return results.every(Boolean);
     },
     async close() {
@@ -30791,7 +31236,11 @@ async function startProtocol(entry) {
       for (const name of server.databaseNames()) server.getDatabase(name).now = () => new Date(clock.now());
       server.clearFaults();
       clock.reset();
+      const control = { ...boot.shared.clock, ...boot.namespaces[namespace]?.clock };
+      if (control.frozen) clock.freeze();
+      if (control.now !== void 0) clock.set(control.now);
     },
+    nextEvent: () => void 0,
     clock: (namespace) => get(namespace).clock
   };
 }