@rehearsal-db/core 0.1.0-beta.7 → 0.1.0-beta.9

package/src/application/session.mjs

@@ -0,0 +1,313 @@
+/** 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 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);
+
+export const summarizeProjectCommandFailure = ({
+  error,
+  status,
+  stdout = "",
+  stderr = "",
+}) => {
+  const stdoutBytes = Buffer.byteLength(String(stdout));
+  const stderrBytes = 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`;
+  }
+  return `exit ${Number.isInteger(status) ? status : "unknown"}; 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 (child.exitCode !== null || child.signalCode !== null)
+      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) => {
+  const exited = () => child.exitCode !== null || child.signalCode !== null;
+  if (exited()) return;
+  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([
+    new Promise((resolve) => child.once("exit", resolve)),
+    new Promise((resolve) => setTimeout(resolve, 5_000)),
+  ]);
+  if (!exited()) {
+    kill("SIGKILL");
+    await new Promise((resolve) => child.once("exit", resolve));
+  }
+};
+
+export const startApplicationSession = async ({
+  command,
+  cwd,
+  files,
+  mappings,
+  readiness,
+  inheritedEnvironment = process.env,
+  spawnImplementation = spawn,
+  fetchImplementation = fetch,
+}) => {
+  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);
+  });
+  try {
+    const ready = await waitForReadiness({
+      readiness,
+      fetchImplementation,
+      child,
+    });
+    return Object.freeze({
+      pid: child.pid,
+      ready,
+      stop: () => stopOwnedChild(child),
+      diagnostics: () => ({
+        stdoutBytes: Buffer.byteLength(stdout),
+        stderrBytes: Buffer.byteLength(stderr),
+      }),
+    });
+  } catch (error) {
+    await stopOwnedChild(child);
+    throw error;
+  }
+};
+
+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));
@@ -515,10 +573,48 @@ export const planBaselineGenerationPrune = async ({
   );
   const removed = entries
     .map((entry) => entry.name)
-    .filter((name) => !retained.has(name));
+    .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,

package/{scripts/lib/rehearsal/baseline_builder.mjs → src/baseline/builder.mjs}

@@ -12,13 +12,13 @@ import { pathToFileURL } from "node:url";
 import {
   createAndActivateBaseline,
   createBaselineGenerationId,
-} from "./baseline_artifact.mjs";
-import { loadRehearsalConfig } from "./configuration.mjs";
+} from "./artifact.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
 import {
   buildMigrationLedgerInventory,
   createMigrationReplayReceipt,
   readMigrationSourceBundle,
-} from "./migration_history.mjs";
+} from "../runtime/migration_history.mjs";
 import { validateRuntimeSanitizationPolicy } from "./sanitization_policy.mjs";
 
 const resolveProjectInput = (projectRoot, value, label) => {
@@ -109,7 +109,11 @@ export const createSyntheticBaselineFromFiles = async ({
   );
   const expectedTables = policy.tables
     .filter((table) => table.sourceRows !== "EXCLUDE")
-    .map((table) => table.name);
+    .map((table) =>
+      (table.schema ?? "public") === "public"
+        ? table.name
+        : `${table.schema}.${table.name}`,
+    );
   if (expectedTables.length === 0) {
     throw new Error("The sanitization policy includes no restorable tables.");
   }

package/{scripts/lib/rehearsal/baseline_preparation.mjs → src/baseline/preparation.mjs}

@@ -7,8 +7,8 @@ import { createReadStream } from "node:fs";
 import { access, lstat, mkdir, open, readFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { loadRehearsalConfig } from "./configuration.mjs";
-import { buildMigrationLedgerInventory } from "./migration_history.mjs";
+import { loadRehearsalConfig } from "../project/configuration.mjs";
+import { buildMigrationLedgerInventory } from "../runtime/migration_history.mjs";
 
 const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
 const storageBucketPattern = /^[a-z0-9][a-z0-9.-]{0,99}$/u;
@@ -70,6 +70,7 @@ const inspectSyntheticRecords = async (path) => {
     }
     if (
       !record ||
+      !identifierPattern.test(record.schema ?? "public") ||
       !identifierPattern.test(record.table ?? "") ||
       !record.row ||
       typeof record.row !== "object" ||
@@ -86,14 +87,18 @@ const inspectSyntheticRecords = async (path) => {
         `Synthetic baseline table ${record.table} has invalid or empty columns.`,
       );
     }
-    const table = tables.get(record.table) ?? {
+    const schema = record.schema ?? "public";
+    const key =
+      schema === "public" ? record.table : `${schema}.${record.table}`;
+    const table = tables.get(key) ?? {
+      schema,
       name: record.table,
       rowCount: 0,
       columns: new Set(),
     };
     table.rowCount += 1;
     for (const column of columns) table.columns.add(column);
-    tables.set(record.table, table);
+    tables.set(key, table);
     rowCount += 1;
   }
   if (rowCount === 0) {
@@ -104,6 +109,7 @@ const inspectSyntheticRecords = async (path) => {
     tables: [...tables.values()]
       .sort((left, right) => left.name.localeCompare(right.name))
       .map((table) => ({
+        schema: table.schema,
         name: table.name,
         rowCount: table.rowCount,
         columns: [...table.columns].sort(),
@@ -232,6 +238,7 @@ const renderPolicyDraft = ({ migrationCutoff, tables }) =>
       draft: true,
       migrationCutoff,
       tables: tables.map((table) => ({
+        ...(table.schema === "public" ? {} : { schema: table.schema }),
         name: table.name,
         group: "synthetic",
         sourceRows: "STREAM AND SANITIZE",