@pixel-point/toolcraft 0.0.18 → 0.0.19

package/templates/starter/scripts/toolcraft-motion-reference-publication-lease.mjs

@@ -0,0 +1,254 @@
+import path from "node:path";
+
+function fail(message, cause) {
+  throw new Error(`Toolcraft motion reference publication failed: ${message}`, { cause });
+}
+
+function existsError(error) {
+  return [error?.code, error?.cause?.code].some((code) =>
+    code === "EEXIST" || code === "ENOTEMPTY");
+}
+
+function validateOptions(options) {
+  if (!path.isAbsolute(options.lockDirectory ?? "") ||
+      typeof options.sourceIdentity !== "string" || !options.sourceIdentity ||
+      !Number.isSafeInteger(options.pid) || options.pid <= 0 ||
+      typeof options.now !== "function" || typeof options.tokenFactory !== "function" ||
+      !Number.isFinite(options.lockLeaseMilliseconds) ||
+      options.lockLeaseMilliseconds <= 0 ||
+      !Number.isFinite(options.maximumUninterruptibleOperationMilliseconds) ||
+      options.maximumUninterruptibleOperationMilliseconds <= 0 ||
+      options.maximumUninterruptibleOperationMilliseconds * 2 >
+        options.lockLeaseMilliseconds) {
+    fail("lock identity, clock, lease, operation bound, PID, and token factory are required");
+  }
+}
+
+function validateOwner(owner) {
+  if (!owner || !Number.isSafeInteger(owner.pid) || owner.pid <= 0 ||
+      !Number.isFinite(owner.leaseExpiresAt) ||
+      typeof owner.sourceIdentity !== "string" || !owner.sourceIdentity ||
+      typeof owner.token !== "string" || !owner.token) {
+    fail("existing lock metadata is invalid and must be inspected manually");
+  }
+  return owner;
+}
+
+async function readOwnerFile(fileSystem, ownerPath) {
+  try {
+    return validateOwner(JSON.parse(await fileSystem.readFile(ownerPath, "utf8")));
+  } catch (error) {
+    if (error.message?.startsWith("Toolcraft motion reference publication failed:")) {
+      throw error;
+    }
+    fail("existing lock metadata could not be read", error);
+  }
+}
+
+const ownerPath = (lockDirectory) => path.join(lockDirectory, "owner.json");
+const claimPath = (lockDirectory) => path.join(lockDirectory, "reclaim.json");
+
+async function readOwner(options) {
+  return readOwnerFile(options.fileSystem, ownerPath(options.lockDirectory));
+}
+
+function freshOwner(options, token) {
+  return {
+    leaseExpiresAt: options.now() + options.lockLeaseMilliseconds,
+    pid: options.pid,
+    sourceIdentity: options.sourceIdentity,
+    token,
+  };
+}
+
+async function writeNewOwner(fileSystem, directory, owner) {
+  try {
+    await fileSystem.writeFile(ownerPath(directory), `${JSON.stringify(owner)}\n`, {
+      flag: "wx",
+    });
+  } catch (error) {
+    fail("lock ownership metadata could not be written", error);
+  }
+}
+
+async function replaceOwner(options, owner) {
+  const target = ownerPath(options.lockDirectory);
+  const temporary = `${target}.tmp-${owner.token}`;
+  try {
+    await options.fileSystem.writeFile(temporary, `${JSON.stringify(owner)}\n`, {
+      flag: "wx",
+    });
+    await options.fileSystem.rename(temporary, target);
+  } catch (error) {
+    await options.fileSystem.rm(temporary, { force: true }).catch(() => {});
+    fail("lock lease renewal could not be persisted atomically", error);
+  }
+}
+
+function leaseIsActive(options, owner) {
+  return options.now() < owner.leaseExpiresAt;
+}
+
+function residuePrefixes(lockDirectory) {
+  const base = path.basename(lockDirectory);
+  return ["incomplete", "prepare", "release", "stale"].map(
+    (kind) => `${base}.${kind}-`,
+  );
+}
+
+async function cleanupResidues(options) {
+  const parent = path.dirname(options.lockDirectory);
+  const prefixes = residuePrefixes(options.lockDirectory);
+  const entries = await options.fileSystem.readdir(parent, { withFileTypes: true });
+  for (const entry of entries) {
+    const name = typeof entry === "string" ? entry : entry.name;
+    if (prefixes.some((prefix) => name.startsWith(prefix))) {
+      await options.fileSystem.rm(path.join(parent, name), {
+        force: true, recursive: true,
+      });
+    }
+  }
+}
+
+async function createFreshLock(options, owner) {
+  const prepared = `${options.lockDirectory}.prepare-${owner.token}`;
+  try {
+    await options.fileSystem.mkdir(prepared);
+    await writeNewOwner(options.fileSystem, prepared, owner);
+    await options.fileSystem.rename(prepared, options.lockDirectory);
+  } catch (error) {
+    await options.fileSystem.rm(prepared, { force: true, recursive: true })
+      .catch(() => {});
+    throw error;
+  }
+  await cleanupResidues(options);
+}
+
+async function removeOwnedClaim(options, token) {
+  const target = claimPath(options.lockDirectory);
+  let claim;
+  try {
+    claim = await readOwnerFile(options.fileSystem, target);
+  } catch (error) {
+    if (error?.cause?.code === "ENOENT") return;
+    throw error;
+  }
+  if (claim.token === token && claim.sourceIdentity === options.sourceIdentity) {
+    await options.fileSystem.rm(target, { force: true });
+  }
+}
+
+async function claimTransition(options, claimant) {
+  const target = claimPath(options.lockDirectory);
+  const temporary = path.join(options.lockDirectory,
+    `.reclaim-${claimant.token}.json`);
+  await options.fileSystem.writeFile(temporary, `${JSON.stringify(claimant)}\n`, {
+    flag: "wx",
+  });
+  try {
+    await options.fileSystem.link(temporary, target);
+  } catch (error) {
+    await options.fileSystem.rm(temporary, { force: true }).catch(() => {});
+    if (error?.code !== "EEXIST") fail("source lock transition claim failed", error);
+    const current = await readOwnerFile(options.fileSystem, target);
+    if (leaseIsActive(options, current)) {
+      fail("another command owns an active source lock transition", error);
+    }
+    await options.fileSystem.rm(target, { force: true });
+    return claimTransition(options, claimant);
+  }
+  await options.fileSystem.rm(temporary, { force: true });
+  return target;
+}
+
+async function heartbeat(options, token) {
+  const renewed = freshOwner(options, token);
+  await claimTransition(options, renewed);
+  try {
+    const current = await readOwner(options);
+    const claim = await readOwnerFile(
+      options.fileSystem, claimPath(options.lockDirectory),
+    );
+    if (current.token !== token || current.sourceIdentity !== options.sourceIdentity ||
+        claim.token !== token || claim.sourceIdentity !== options.sourceIdentity) {
+      fail("source lock ownership token was lost before the next mutation");
+    }
+    await replaceOwner(options, renewed);
+  } finally {
+    await removeOwnedClaim(options, token).catch(() => {});
+  }
+}
+
+async function reclaim(options, observed, claimant) {
+  await claimTransition(options, claimant);
+  const current = await readOwner(options);
+  const claim = await readOwnerFile(
+    options.fileSystem, claimPath(options.lockDirectory),
+  );
+  if (claim.token !== claimant.token || !leaseIsActive(options, claim)) {
+    fail("stale source lock reclaim ownership expired before quarantine");
+  }
+  if (current.sourceIdentity !== options.sourceIdentity ||
+      current.token !== observed.token || leaseIsActive(options, current)) {
+    await removeOwnedClaim(options, claimant.token).catch(() => {});
+    fail("source lock owner renewed or changed during stale reclaim");
+  }
+  const quarantine = `${options.lockDirectory}.stale-${claimant.token}`;
+  try {
+    await options.fileSystem.rename(options.lockDirectory, quarantine);
+    await createFreshLock(options, claimant);
+  } catch (error) {
+    await options.fileSystem.rm(quarantine, { force: true, recursive: true })
+      .catch(() => {});
+    if (existsError(error)) {
+      fail("another command acquired the fresh source lock during reclaim", error);
+    }
+    throw error;
+  }
+}
+
+async function acquire(options) {
+  const token = options.tokenFactory();
+  if (typeof token !== "string" || !token) fail("lock token factory returned no token");
+  const claimant = freshOwner(options, token);
+  try {
+    await createFreshLock(options, claimant);
+    return token;
+  } catch (error) {
+    if (!existsError(error)) throw error;
+  }
+  const current = await readOwner(options);
+  if (current.sourceIdentity !== options.sourceIdentity) {
+    fail("existing lock belongs to a different source identity");
+  }
+  if (leaseIsActive(options, current)) {
+    fail(`an unexpired publication lease already exists for this source (PID ${current.pid})`);
+  }
+  await reclaim(options, current, claimant);
+  return token;
+}
+
+async function release(options, token) {
+  try {
+    await heartbeat(options, token);
+  } catch {
+    return "Source lock ownership could not be verified; the lock was retained.";
+  }
+  const quarantine = `${options.lockDirectory}.release-${token}`;
+  try {
+    await options.fileSystem.rename(options.lockDirectory, quarantine);
+    await options.fileSystem.rm(quarantine, { force: true, recursive: true });
+  } catch {
+    return `Source lock cleanup was retained for stale-owner recovery: ${quarantine}`;
+  }
+}
+
+export async function acquireToolcraftMotionReferenceLease(options) {
+  validateOptions(options);
+  const token = await acquire(options);
+  return {
+    heartbeat: () => heartbeat(options, token),
+    release: () => release(options, token),
+    token,
+  };
+}

package/templates/starter/scripts/toolcraft-motion-reference-publication-lease.test.mjs

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  acquireToolcraftMotionReferenceLease,
+} from "./toolcraft-motion-reference-publication-lease.mjs";
+
+async function fixture(context) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "motion-lease-"));
+  context.after(() => fs.rm(root, { force: true, recursive: true }));
+  return { lockDirectory: path.join(root, "reference.lock") };
+}
+
+function settings(value, clock, token, fileSystem = fs) {
+  return {
+    fileSystem,
+    lockDirectory: value.lockDirectory,
+    lockLeaseMilliseconds: 100,
+    maximumUninterruptibleOperationMilliseconds: 40,
+    now: () => clock.value,
+    pid: token === "owner-a" ? 101 : 202,
+    sourceIdentity: "motion-reference-v1-lease-race",
+    tokenFactory: () => token,
+  };
+}
+
+test("a reclaim claimant rereads the owner lease after a racing heartbeat", async (context) => {
+  const value = await fixture(context);
+  const clock = { value: 1_000 };
+  const owner = await acquireToolcraftMotionReferenceLease(
+    settings(value, clock, "owner-a"),
+  );
+  clock.value = 1_150;
+  let reclaimLinkEntered;
+  let releaseReclaimLink;
+  const reclaimLinkStarted = new Promise((resolve) => {
+    reclaimLinkEntered = resolve;
+  });
+  const reclaimLinkGate = new Promise((resolve) => {
+    releaseReclaimLink = resolve;
+  });
+  const contenderFileSystem = {
+    ...fs,
+    link: async (...args) => {
+      reclaimLinkEntered();
+      await reclaimLinkGate;
+      return fs.link(...args);
+    },
+  };
+  const contender = acquireToolcraftMotionReferenceLease(
+    settings(value, clock, "owner-b", contenderFileSystem),
+  );
+  await reclaimLinkStarted;
+  await owner.heartbeat();
+  releaseReclaimLink();
+
+  await assert.rejects(contender, /renewed|active|lease/iu);
+  const persisted = JSON.parse(await fs.readFile(
+    path.join(value.lockDirectory, "owner.json"), "utf8",
+  ));
+  assert.equal(persisted.token, "owner-a");
+  assert.equal(persisted.leaseExpiresAt, 1_250);
+  assert.equal(await owner.release(), undefined);
+});
+
+test("a lock owner fails closed before mutation after its token is replaced", async (context) => {
+  const value = await fixture(context);
+  const clock = { value: 1_000 };
+  const owner = await acquireToolcraftMotionReferenceLease(
+    settings(value, clock, "owner-a"),
+  );
+  await fs.writeFile(path.join(value.lockDirectory, "owner.json"), `${JSON.stringify({
+    leaseExpiresAt: 1_200,
+    pid: 202,
+    sourceIdentity: "motion-reference-v1-lease-race",
+    token: "owner-b",
+  })}\n`);
+
+  await assert.rejects(owner.heartbeat(), /ownership|token|lost/iu);
+  const persisted = JSON.parse(await fs.readFile(
+    path.join(value.lockDirectory, "owner.json"), "utf8",
+  ));
+  assert.equal(persisted.token, "owner-b");
+});
+
+test("the declared uninterruptible operation bound stays within half a lease", async (context) => {
+  const value = await fixture(context);
+  const clock = { value: 1_000 };
+  await assert.rejects(() => acquireToolcraftMotionReferenceLease({
+    ...settings(value, clock, "owner-a"),
+    maximumUninterruptibleOperationMilliseconds: 51,
+  }), /operation bound|lease/iu);
+  await assert.rejects(fs.stat(value.lockDirectory), { code: "ENOENT" });
+});
+
+test("heartbeat persists the renewed owner by atomic sibling replacement", async (context) => {
+  const value = await fixture(context);
+  const clock = { value: 1_000 };
+  const operations = [];
+  const fileSystem = {
+    ...fs,
+    rename: async (from, to) => {
+      if (to === path.join(value.lockDirectory, "owner.json")) {
+        operations.push(["rename", from, to]);
+      }
+      return fs.rename(from, to);
+    },
+    writeFile: async (target, contents, options) => {
+      if (target.includes("owner.json.tmp-")) {
+        operations.push(["write", target, options]);
+      }
+      return fs.writeFile(target, contents, options);
+    },
+  };
+  const owner = await acquireToolcraftMotionReferenceLease(
+    settings(value, clock, "owner-a", fileSystem),
+  );
+  clock.value = 1_050;
+  await owner.heartbeat();
+
+  assert.equal(operations.length, 2);
+  assert.equal(operations[0][0], "write");
+  assert.equal(operations[0][2].flag, "wx");
+  assert.deepEqual(operations[1], ["rename", operations[0][1],
+    path.join(value.lockDirectory, "owner.json")]);
+  await owner.release();
+});

package/templates/starter/scripts/toolcraft-motion-reference-publication-staging.mjs

@@ -0,0 +1,128 @@
+import path from "node:path";
+
+import {
+  requireToolcraftMotionReferenceSourceIdentity,
+} from "./toolcraft-motion-reference-roots.mjs";
+
+function fail(message, cause) {
+  throw new Error(`Toolcraft motion reference staging scope failed: ${message}`, {
+    cause,
+  });
+}
+
+function isStrictDescendant(root, target) {
+  const relative = path.relative(root, target);
+  return relative !== "" && relative !== ".." &&
+    !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function requireCanonicalAbsolute(target, label) {
+  if (typeof target !== "string" || !path.isAbsolute(target) ||
+      path.resolve(target) !== target) {
+    fail(`${label} must be a canonical absolute path without traversal`);
+  }
+  return target;
+}
+
+function publicationRecords(records) {
+  if (!Array.isArray(records) || records.length === 0) {
+    fail("a nonempty publication record group is required");
+  }
+  const published = records.filter(({ stagingDirectory }) =>
+    stagingDirectory !== null);
+  if (published.length === 0) {
+    fail("a publication group must contain at least one staged study");
+  }
+  return published;
+}
+
+export function defineToolcraftMotionReferenceStagingScope(
+  records,
+  { sourceIdentity, stagingRoot, temporaryRoot },
+) {
+  requireToolcraftMotionReferenceSourceIdentity(sourceIdentity);
+  requireCanonicalAbsolute(temporaryRoot, "temporary root");
+  const published = publicationRecords(records);
+  const derivedRoots = new Set(published.map(({ stagingDirectory }) => {
+    requireCanonicalAbsolute(stagingDirectory, "staging directory");
+    return path.dirname(stagingDirectory);
+  }));
+  if (derivedRoots.size !== 1) {
+    fail("one complete publication must use one canonical staging root");
+  }
+  const derivedRoot = derivedRoots.values().next().value;
+  if (stagingRoot !== undefined && stagingRoot !== derivedRoot) {
+    fail("declared staging root must own every staged study directly");
+  }
+  requireCanonicalAbsolute(derivedRoot, "staging root");
+  if (!isStrictDescendant(temporaryRoot, derivedRoot) ||
+      path.basename(derivedRoot) !== `${sourceIdentity}.staging`) {
+    fail("staging root must be source-owned beneath the checked temporary root");
+  }
+  for (const { finalDirectory, stagingDirectory } of published) {
+    requireCanonicalAbsolute(finalDirectory, "final directory");
+    if (path.dirname(stagingDirectory) !== derivedRoot ||
+        path.basename(stagingDirectory) !== path.basename(finalDirectory)) {
+      fail("each staged study must be the direct expected child of its staging root");
+    }
+  }
+  return { sourceIdentity, stagingRoot: derivedRoot, temporaryRoot };
+}
+
+async function requireDirectDirectoryChain(
+  fileSystem,
+  root,
+  target,
+  { allowMissingTarget },
+) {
+  const relative = path.relative(root, target);
+  let current = root;
+  for (const component of ["", ...relative.split(path.sep)]) {
+    if (component !== "") current = path.join(current, component);
+    let status;
+    try {
+      status = await fileSystem.lstat(current);
+    } catch (error) {
+      if (allowMissingTarget && error?.code === "ENOENT") return;
+      fail(`staging path is missing or unreadable: ${current}`, error);
+    }
+    if (!status.isDirectory() || status.isSymbolicLink()) {
+      fail(`staging path must contain only direct directories, not links: ${current}`);
+    }
+  }
+  const [realRoot, realTarget] = await Promise.all([
+    fileSystem.realpath(root),
+    fileSystem.realpath(target),
+  ]);
+  const contained = target === root ? realTarget === realRoot :
+    isStrictDescendant(realRoot, realTarget);
+  if (!contained) {
+    fail("staging path real location escapes its checked directory boundary");
+  }
+}
+
+export async function requireToolcraftMotionReferenceStagingScope(
+  records,
+  {
+    allowMissingStagingDirectories = false,
+    fileSystem,
+    sourceIdentity,
+    stagingRoot,
+    temporaryRoot,
+  },
+) {
+  const scope = defineToolcraftMotionReferenceStagingScope(records, {
+    sourceIdentity, stagingRoot, temporaryRoot,
+  });
+  await requireDirectDirectoryChain(
+    fileSystem, temporaryRoot, scope.stagingRoot,
+    { allowMissingTarget: allowMissingStagingDirectories },
+  );
+  for (const { stagingDirectory } of publicationRecords(records)) {
+    await requireDirectDirectoryChain(
+      fileSystem, scope.stagingRoot, stagingDirectory,
+      { allowMissingTarget: allowMissingStagingDirectories },
+    );
+  }
+  return scope;
+}