@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.10

package/src/application/session.mjs

@@ -0,0 +1,435 @@
+/** Launch ordinary application commands against verified local runtime files. */
+
+import { spawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { parseEnv } from "node:util";
+import {
+  createCleanProcessEnvironment,
+  isLoopbackUrl,
+} from "../shared/process_environment.mjs";
+
+const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
+const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
+const SESSION_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
+
+const parseCommand = (source) => {
+  if (typeof source !== "string" || !source.trim())
+    throw new Error("Application command is empty.");
+  const values = [];
+  let value = "";
+  let quote = null;
+  for (const character of source) {
+    if (quote) {
+      if (character === quote) quote = null;
+      else value += character;
+    } else if (character === '"' || character === "'") quote = character;
+    else if (/\s/u.test(character)) {
+      if (value) values.push(value);
+      value = "";
+    } else value += character;
+  }
+  if (quote)
+    throw new Error("Application command contains an unmatched quote.");
+  if (value) values.push(value);
+  return values;
+};
+
+const readOwnedEnvironment = async (path) => {
+  const details = await stat(path);
+  if (!details.isFile() || (details.mode & 0o077) !== 0) {
+    throw new Error(
+      "Runtime environment file must be an owner-only regular file.",
+    );
+  }
+  return parseEnv(await readFile(path, "utf8"));
+};
+
+const assertLocalValue = (key, value) => {
+  if (/(_URL|_URI|_ENDPOINT)$/u.test(key)) {
+    let parsed;
+    try {
+      parsed = new URL(value);
+    } catch {
+      throw new Error(`Mapped runtime variable ${key} is not a URL.`);
+    }
+    if (
+      !isLoopbackUrl(value) &&
+      !["postgres:", "postgresql:"].includes(parsed.protocol)
+    ) {
+      throw new Error(`Mapped runtime variable ${key} is not local.`);
+    }
+    if (
+      ["postgres:", "postgresql:"].includes(parsed.protocol) &&
+      !["127.0.0.1", "::1", "localhost"].includes(parsed.hostname)
+    ) {
+      throw new Error(`Mapped runtime variable ${key} is not local.`);
+    }
+  }
+};
+
+export const buildApplicationEnvironment = async ({ files, mappings }) => {
+  if (!files?.primary)
+    throw new Error("Primary runtime environment file is required.");
+  const environments = {};
+  for (const [name, path] of Object.entries(files)) {
+    environments[name] = await readOwnedEnvironment(path);
+  }
+  if (!mappings || typeof mappings !== "object" || Array.isArray(mappings)) {
+    throw new Error("Application environment mappings must be an object.");
+  }
+  const result = {};
+  for (const [destination, reference] of Object.entries(mappings)) {
+    if (!ENV_KEY.test(destination) || typeof reference !== "string") {
+      throw new Error("Application environment mapping is invalid.");
+    }
+    const separator = reference.indexOf(":");
+    if (separator < 1)
+      throw new Error(
+        `Application mapping ${destination} has an invalid reference.`,
+      );
+    const target = reference.slice(0, separator);
+    const source = reference.slice(separator + 1);
+    if (!ENV_KEY.test(source) || !environments[target]?.[source]) {
+      throw new Error(
+        `Application mapping ${destination} references a missing runtime value.`,
+      );
+    }
+    assertLocalValue(source, environments[target][source]);
+    result[destination] = environments[target][source];
+  }
+  return result;
+};
+
+const boundedAppend = (current, chunk) =>
+  `${current}${chunk}`.slice(-MAX_DIAGNOSTIC_BYTES);
+
+const childHasExited = (child) =>
+  child.exitCode !== null || child.signalCode !== null;
+
+const waitForChildExit = (child) => {
+  if (childHasExited(child)) {
+    return Promise.resolve({
+      status: child.exitCode,
+      signal: child.signalCode,
+    });
+  }
+  return new Promise((resolve) => {
+    child.once("exit", (status, signal) => resolve({ status, signal }));
+  });
+};
+
+export const summarizeProjectCommandFailure = ({
+  error,
+  status,
+  signal,
+  stdout = "",
+  stderr = "",
+  stdoutByteCount,
+  stderrByteCount,
+}) => {
+  const stdoutBytes = stdoutByteCount ?? Buffer.byteLength(String(stdout));
+  const stderrBytes = stderrByteCount ?? Buffer.byteLength(String(stderr));
+  if (error) {
+    const code = /^[A-Z0-9_]+$/u.test(error.code ?? "")
+      ? ` (${error.code})`
+      : "";
+    return `command could not start${code}; output withheld`;
+  }
+  const outcome = signal
+    ? `signal ${signal}`
+    : `exit ${Number.isInteger(status) ? status : "unknown"}`;
+  return `${outcome}; stdout ${stdoutBytes} bytes; stderr ${stderrBytes} bytes; output withheld`;
+};
+
+const waitForReadiness = async ({ readiness, fetchImplementation, child }) => {
+  if (!readiness || !isLoopbackUrl(readiness.url)) {
+    throw new Error("Application readiness must use a loopback URL.");
+  }
+  const expected = readiness.expectedStatus ?? 200;
+  const deadline = Date.now() + (readiness.timeoutSeconds ?? 30) * 1_000;
+  let lastStatus = null;
+  while (Date.now() < deadline) {
+    if (childHasExited(child))
+      throw new Error("Application exited before becoming ready.");
+    try {
+      const response = await fetchImplementation(readiness.url, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(2_000),
+      });
+      lastStatus = response.status;
+      if (response.status === expected)
+        return { url: readiness.url, status: response.status };
+    } catch {
+      // A bounded retry is expected while the local process starts.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error(
+    `Application readiness timed out${lastStatus === null ? "" : ` after HTTP ${lastStatus}`}.`,
+  );
+};
+
+const stopOwnedChild = async (child) => {
+  if (childHasExited(child)) return;
+  const exit = waitForChildExit(child);
+  const kill = (signal) => {
+    try {
+      if (process.platform === "win32") child.kill(signal);
+      else process.kill(-child.pid, signal);
+    } catch (error) {
+      if (error?.code !== "ESRCH") throw error;
+    }
+  };
+  kill("SIGTERM");
+  await Promise.race([
+    exit,
+    new Promise((resolve) => setTimeout(resolve, 5_000)),
+  ]);
+  if (!childHasExited(child)) {
+    kill("SIGKILL");
+    await exit;
+  }
+};
+
+export const startApplicationSession = async ({
+  command,
+  cwd,
+  files,
+  mappings,
+  readiness,
+  inheritedEnvironment = process.env,
+  spawnImplementation = spawn,
+  fetchImplementation = fetch,
+  signalTarget = process,
+}) => {
+  const mapped = await buildApplicationEnvironment({ files, mappings });
+  const [program, ...args] = parseCommand(command);
+  const child = spawnImplementation(program, args, {
+    cwd,
+    env: createCleanProcessEnvironment({
+      inheritedEnvironment,
+      overrides: mapped,
+    }),
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout?.on("data", (chunk) => {
+    stdout = boundedAppend(stdout, chunk.toString("utf8"));
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr = boundedAppend(stderr, chunk.toString("utf8"));
+  });
+  await new Promise((resolve, reject) => {
+    child.once("spawn", resolve);
+    child.once("error", reject);
+  });
+  let interruptStartup;
+  const interruption = new Promise((_, reject) => {
+    interruptStartup = (signal) =>
+      reject(new Error(`Application startup was interrupted by ${signal}.`));
+  });
+  const startupHandlers = new Map(
+    SESSION_SIGNALS.map((signal) => [signal, () => interruptStartup(signal)]),
+  );
+  for (const [signal, handler] of startupHandlers) {
+    signalTarget.prependListener(signal, handler);
+  }
+  try {
+    const ready = await Promise.race([
+      waitForReadiness({
+        readiness,
+        fetchImplementation,
+        child,
+      }),
+      interruption,
+    ]);
+    return Object.freeze({
+      pid: child.pid,
+      ready,
+      stop: () => stopOwnedChild(child),
+      wait: () => waitForChildExit(child),
+      diagnostics: () => ({
+        stdoutBytes: Buffer.byteLength(stdout),
+        stderrBytes: Buffer.byteLength(stderr),
+      }),
+    });
+  } catch (error) {
+    await stopOwnedChild(child);
+    throw error;
+  } finally {
+    for (const [signal, handler] of startupHandlers) {
+      signalTarget.removeListener(signal, handler);
+    }
+  }
+};
+
+/**
+ * Keep a ready application session attached until the user interrupts it.
+ * The child process group is always stopped before this function returns.
+ */
+export const holdApplicationSession = async ({
+  session,
+  signalTarget = process,
+  input = process.stdin,
+  onReady = () => undefined,
+}) => {
+  if (
+    !session ||
+    typeof session.wait !== "function" ||
+    typeof session.stop !== "function"
+  ) {
+    throw new Error("A started application session is required.");
+  }
+  let finishInterruption;
+  const interruption = new Promise((resolve) => {
+    finishInterruption = resolve;
+  });
+  const handlers = new Map(
+    SESSION_SIGNALS.map((signal) => [
+      signal,
+      () => finishInterruption({ kind: "interrupted", signal }),
+    ]),
+  );
+  for (const [signal, handler] of handlers) {
+    signalTarget.prependListener(signal, handler);
+  }
+  const onInput = (chunk) => {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (bytes.includes(0x03)) {
+      finishInterruption({ kind: "interrupted", signal: "SIGINT" });
+    } else if (bytes.includes(0x1a)) {
+      finishInterruption({ kind: "interrupted", signal: "SIGTSTP" });
+    }
+  };
+  if (input?.isTTY) input.prependListener("data", onInput);
+  try {
+    onReady(session.ready);
+    const outcome = await Promise.race([
+      interruption,
+      session.wait().then((exit) => ({ kind: "exited", ...exit })),
+    ]);
+    if (outcome.kind === "exited") {
+      const diagnostics = session.diagnostics?.() ?? {};
+      throw new Error(
+        `Application exited before the sandbox was closed (${summarizeProjectCommandFailure(
+          {
+            status: outcome.status,
+            signal: outcome.signal,
+            stdoutByteCount: diagnostics.stdoutBytes ?? 0,
+            stderrByteCount: diagnostics.stderrBytes ?? 0,
+          },
+        )}).`,
+      );
+    }
+    return Object.freeze({
+      signal: outcome.signal,
+      diagnostics: session.diagnostics?.() ?? {
+        stdoutBytes: 0,
+        stderrBytes: 0,
+      },
+    });
+  } finally {
+    try {
+      // npm can forward the terminal's SIGINT after the CLI receives it.
+      // Keep our handlers installed until the owned process group is fully
+      // stopped so a duplicate signal cannot terminate Rehearsal mid-cleanup.
+      await session.stop();
+    } finally {
+      for (const [signal, handler] of handlers) {
+        signalTarget.removeListener(signal, handler);
+      }
+      if (input?.isTTY) input.removeListener("data", onInput);
+    }
+  }
+};
+
+const valueAtPath = (value, path) => {
+  let current = value;
+  for (const segment of path) {
+    if (
+      current === null ||
+      typeof current !== "object" ||
+      !Object.hasOwn(current, segment)
+    ) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+};
+
+export const runHttpProofs = async ({
+  checks,
+  fetchImplementation = fetch,
+}) => {
+  if (!Array.isArray(checks) || checks.length < 2) {
+    throw new Error(
+      "HTTP proof requires explicit positive and negative checks.",
+    );
+  }
+  if (
+    !checks.some((check) => check.kind === "positive") ||
+    !checks.some((check) => check.kind === "negative")
+  ) {
+    throw new Error(
+      "HTTP proof requires at least one positive and one negative check.",
+    );
+  }
+  const results = [];
+  for (const check of checks) {
+    if (!isLoopbackUrl(check.url))
+      throw new Error(`HTTP proof ${check.name} is not local.`);
+    const response = await fetchImplementation(check.url, {
+      method: check.method ?? "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(check.timeoutMs ?? 5_000),
+    });
+    if (response.status !== check.expectedStatus) {
+      throw new Error(
+        `HTTP proof ${check.name} expected status ${check.expectedStatus} but received ${response.status}.`,
+      );
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length > 1024 * 1024)
+      throw new Error(`HTTP proof ${check.name} returned too much data.`);
+    if (check.json) {
+      let parsed;
+      try {
+        parsed = JSON.parse(bytes.toString("utf8"));
+      } catch {
+        throw new Error(`HTTP proof ${check.name} did not return JSON.`);
+      }
+      const actual = valueAtPath(parsed, check.json.path);
+      if (
+        Object.hasOwn(check.json, "equals") &&
+        !Object.is(actual, check.json.equals)
+      ) {
+        throw new Error(
+          `HTTP proof ${check.name} did not return its required value.`,
+        );
+      }
+      if (
+        Object.hasOwn(check.json, "notEquals") &&
+        Object.is(actual, check.json.notEquals)
+      ) {
+        throw new Error(`HTTP proof ${check.name} returned a forbidden value.`);
+      }
+      if (
+        check.json.minimumItems !== undefined &&
+        (!Array.isArray(actual) || actual.length < check.json.minimumItems)
+      ) {
+        throw new Error(
+          `HTTP proof ${check.name} returned too few matching items.`,
+        );
+      }
+    }
+    results.push({
+      name: check.name,
+      kind: check.kind,
+      status: response.status,
+    });
+  }
+  return Object.freeze(results);
+};

package/{scripts/lib/rehearsal/baseline_artifact.mjs → src/baseline/artifact.mjs}

@@ -18,7 +18,7 @@ import {
   symlink,
 } from "node:fs/promises";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
-import { createMigrationReplayReceipt } from "./migration_history.mjs";
+import { createMigrationReplayReceipt } from "../runtime/migration_history.mjs";
 
 const generationPattern = /^\d{8}T\d{6}Z-[a-f0-9]{12}$/u;
 const buildPrefix = ".building-";
@@ -28,6 +28,9 @@ const migrationNamePattern = /^\d{14}_[a-z0-9_]+\.sql$/u;
 const storageBucketPattern = /^[a-z0-9][a-z0-9.-]{0,99}$/u;
 const maximumAssetBytes = 50 * 1024 * 1024;
 const maximumTotalAssetBytes = 2 * 1024 * 1024 * 1024;
+const relationPattern = /^(?:[a-z][a-z0-9_]{0,62}\.)?[a-z][a-z0-9_]{0,62}$/u;
+const relationKey = (schema, table) =>
+  schema === "public" ? table : `${schema}.${table}`;
 
 const canonicalJson = (value) => `${JSON.stringify(value, null, "\t")}\n`;
 
@@ -136,6 +139,7 @@ export const createAndActivateBaseline = async ({
   migrationFiles = [],
   assets = [],
   schemaSql = null,
+  activate = true,
 }) => {
   const root = assertArtifactRoot(artifactRoot);
   assertGenerationId(generationId);
@@ -149,7 +153,7 @@ export const createAndActivateBaseline = async ({
   }
   if (
     !Array.isArray(expectedTables) ||
-    expectedTables.some((name) => !/^[a-z][a-z0-9_]*$/u.test(name)) ||
+    expectedTables.some((name) => !relationPattern.test(name)) ||
     new Set(expectedTables).size !== expectedTables.length
   ) {
     throw new Error(
@@ -190,23 +194,25 @@ export const createAndActivateBaseline = async ({
     for await (const record of records) {
       if (
         !record ||
+        (record.schema !== undefined &&
+          !/^[a-z][a-z0-9_]{0,62}$/u.test(record.schema)) ||
         typeof record.table !== "string" ||
+        !/^[a-z][a-z0-9_]{0,62}$/u.test(record.table) ||
         !record.row ||
         typeof record.row !== "object" ||
         Array.isArray(record.row)
       ) {
         throw new Error("A sanitized baseline record has an invalid shape.");
       }
-      if (expectedTableSet.size && !expectedTableSet.has(record.table)) {
-        throw new Error(
-          `The baseline stream exposed unexpected table ${record.table}.`,
-        );
+      const key = relationKey(record.schema ?? "public", record.table);
+      if (expectedTableSet.size && !expectedTableSet.has(key)) {
+        throw new Error(`The baseline stream exposed unexpected table ${key}.`);
       }
       const line = `${JSON.stringify(record)}\n`;
       dataHash.update(line);
       await dataHandle.write(line, null, "utf8");
       rowCount += 1;
-      tableCounts.set(record.table, (tableCounts.get(record.table) ?? 0) + 1);
+      tableCounts.set(key, (tableCounts.get(key) ?? 0) + 1);
     }
     await dataHandle.sync();
     await dataHandle.close();
@@ -358,12 +364,12 @@ export const createAndActivateBaseline = async ({
     finalCreated = true;
     await chmod(finalDirectory, 0o500);
 
-    const temporaryLink = assertInsideRoot(
-      root,
-      join(root, `.current-${randomBytes(4).toString("hex")}`),
-    );
-    await symlink(join(generationsDirectoryName, generationId), temporaryLink);
-    await rename(temporaryLink, join(root, currentLinkName));
+    if (activate) {
+      await activateBaselineGeneration({
+        artifactRoot: root,
+        generationId,
+      });
+    }
     return manifest;
   } catch (error) {
     if (dataHandle) await dataHandle.close().catch(() => undefined);
@@ -377,6 +383,58 @@ export const createAndActivateBaseline = async ({
   }
 };
 
+export const activateBaselineGeneration = async ({
+  artifactRoot,
+  generationId,
+}) => {
+  const root = assertArtifactRoot(artifactRoot);
+  assertGenerationId(generationId);
+  const generationDirectory = assertInsideRoot(
+    root,
+    join(root, generationsDirectoryName, generationId),
+  );
+  const manifest = JSON.parse(
+    await readFile(join(generationDirectory, "baseline-manifest.json"), "utf8"),
+  );
+  if (manifest.generationId !== generationId) {
+    throw new Error(
+      "The staged baseline identifier does not match its manifest.",
+    );
+  }
+  const temporaryLink = assertInsideRoot(
+    root,
+    join(root, `.current-${randomBytes(4).toString("hex")}`),
+  );
+  await symlink(join(generationsDirectoryName, generationId), temporaryLink);
+  await rename(temporaryLink, join(root, currentLinkName));
+  return manifest;
+};
+
+export const removeStagedBaselineGeneration = async ({
+  artifactRoot,
+  generationId,
+}) => {
+  const root = assertArtifactRoot(artifactRoot);
+  assertGenerationId(generationId);
+  try {
+    const active = await resolveActiveBaselinePaths({ artifactRoot: root });
+    if (basename(active.generationDirectory) === generationId) {
+      throw new Error(
+        "Refusing to remove the active Rehearsal baseline generation.",
+      );
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const target = assertInsideRoot(
+    root,
+    join(root, generationsDirectoryName, generationId),
+  );
+  await verifyNoSymlink(target, "A staged Rehearsal baseline generation");
+  await makeArtifactTreeWritable(target);
+  await rm(target, { recursive: true, force: true });
+};
+
 export const resolveActiveBaselinePaths = async ({ artifactRoot }) => {
   const root = assertArtifactRoot(artifactRoot);
   const currentTarget = await readlink(join(root, currentLinkName));
@@ -478,7 +536,7 @@ export const listIncompleteBaselineBuilds = async ({ artifactRoot }) => {
   }
 };
 
-export const pruneBaselineGenerations = async ({
+export const planBaselineGenerationPrune = async ({
   artifactRoot,
   retain = 2,
 }) => {
@@ -515,8 +573,75 @@ export const pruneBaselineGenerations = async ({
   );
   const removed = entries
     .map((entry) => entry.name)
-    .filter((name) => !retained.has(name));
-  for (const name of removed) {
+    .filter((name) => !retained.has(name))
+    .sort();
+  return { retained: [...retained], removed };
+};
+
+export const planBaselineReplacementPrune = async ({
+  artifactRoot,
+  retain = 2,
+}) => {
+  const root = assertArtifactRoot(artifactRoot);
+  if (!Number.isSafeInteger(retain) || retain < 1) {
+    throw new Error("Rehearsal baseline retention must be a positive integer.");
+  }
+  await resolveActiveBaselinePaths({ artifactRoot: root });
+  const generationsRoot = join(root, generationsDirectoryName);
+  await verifyNoSymlink(generationsRoot, "The Rehearsal generations directory");
+  const entries = await readdir(generationsRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    if (
+      !entry.isDirectory() ||
+      entry.isSymbolicLink() ||
+      !generationPattern.test(entry.name)
+    ) {
+      throw new Error(
+        `Refusing to plan replacement around an unexpected Rehearsal generation entry: ${entry.name}`,
+      );
+    }
+  }
+  const current = entries
+    .map((entry) => entry.name)
+    .sort()
+    .reverse();
+  const retained = current.slice(0, Math.max(0, retain - 1));
+  const retainedSet = new Set(retained);
+  return {
+    retainedAfterReplacement: retained,
+    removedAfterReplacement: current
+      .filter((name) => !retainedSet.has(name))
+      .sort(),
+  };
+};
+
+export const pruneBaselineGenerations = async ({
+  artifactRoot,
+  retain = 2,
+  expectedRemoved,
+}) => {
+  const root = assertArtifactRoot(artifactRoot);
+  const plan = await planBaselineGenerationPrune({
+    artifactRoot: root,
+    retain,
+  });
+  const generationsRoot = join(root, generationsDirectoryName);
+  if (
+    expectedRemoved &&
+    (expectedRemoved.length !== plan.removed.length ||
+      expectedRemoved.some((name, index) => name !== plan.removed[index]))
+  ) {
+    throw new Error(
+      "Rehearsal baseline generations changed after the cleanup preview.",
+    );
+  }
+  for (const name of plan.removed) {
+    const active = await resolveActiveBaselinePaths({ artifactRoot: root });
+    if (basename(active.generationDirectory) === name) {
+      throw new Error(
+        "Refusing to prune the active Rehearsal baseline generation.",
+      );
+    }
     const target = assertInsideRoot(
       generationsRoot,
       join(generationsRoot, name),
@@ -525,7 +650,7 @@ export const pruneBaselineGenerations = async ({
     await makeArtifactTreeWritable(target);
     await rm(target, { recursive: true, force: true });
   }
-  return { retained: [...retained], removed };
+  return plan;
 };
 
 export const removeBaselineArtifactRoot = async ({ artifactRoot }) => {