@stage5/lumine 0.2.65 → 0.2.67

package/lib/admin-workflows.js

@@ -3,7 +3,9 @@ import {
   chmodSync,
   closeSync,
   createReadStream,
+  fchmodSync,
   fsyncSync,
+  linkSync,
   lstatSync,
   mkdirSync,
   openSync,
@@ -74,9 +76,198 @@ function pathWithCursor(requestPath, cursor) {
   return `${url.pathname}${url.search}`;
 }
 
-function defaultCheckpointPath({ runId, operationName }) {
+function defaultCheckpointPath({
+  runId,
+  operationName,
+  operationFingerprint = "",
+}) {
   const safeName = String(operationName).replace(/[^a-z0-9_.-]+/gi, "-");
-  return path.join(os.tmpdir(), `lumine-admin-run-${runId}-${safeName}.json`);
+  const fingerprintSuffix = operationFingerprint
+    ? `-${operationFingerprint}`
+    : "";
+  return path.join(
+    os.tmpdir(),
+    `lumine-admin-run-${runId}-${safeName}${fingerprintSuffix}.json`,
+  );
+}
+
+function resolveAutomaticCheckpointPath({
+  options,
+  operation,
+  runId,
+  operationFingerprint,
+}) {
+  if (String(options.adminCheckpoint || "").trim()) {
+    return path.resolve(options.adminCheckpoint);
+  }
+  const keyedPath = defaultCheckpointPath({
+    runId,
+    operationName: operation.name,
+    operationFingerprint,
+  });
+  if (
+    options.adminResume &&
+    !pathEntryExists(keyedPath) &&
+    !pathEntryExists(`${keyedPath}.lock`) &&
+    !pathEntryExists(`${keyedPath}.lock.reclaim`)
+  ) {
+    const legacyPath = defaultCheckpointPath({
+      runId,
+      operationName: operation.name,
+    });
+    if (pathEntryExists(legacyPath)) return legacyPath;
+  }
+  return keyedPath;
+}
+
+function pathEntryExists(filePath) {
+  try {
+    lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function acquireCheckpointLock(checkpointPath, operationFingerprint) {
+  const lockPath = `${checkpointPath}.lock`;
+  const reclaimPath = `${lockPath}.reclaim`;
+  mkdirSync(path.dirname(lockPath), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (pathEntryExists(reclaimPath)) {
+      throw validationError(
+        `Another Lumine admin scan is recovering checkpoint ${checkpointPath}. Wait for it to finish or choose a different --checkpoint.`,
+      );
+    }
+    const token = randomUUID();
+    let descriptor;
+    let ownsLock = false;
+    try {
+      descriptor = openSync(lockPath, "wx", 0o600);
+      ownsLock = true;
+      fchmodSync(descriptor, 0o600);
+      writeFileSync(
+        descriptor,
+        `${JSON.stringify({
+          kind: "admin-pagination-lock",
+          pid: process.pid,
+          token,
+          operationFingerprint,
+          createdAt: new Date().toISOString(),
+        })}\n`,
+      );
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = undefined;
+      // A stale-lock reclaimer can begin after the check above but before this
+      // O_EXCL create. It hard-links the exact old inode before removal. If
+      // that claim still exists, relinquish our new lock rather than allowing
+      // two owners to cross during the handoff.
+      if (pathEntryExists(reclaimPath)) {
+        releaseCheckpointLock({ lockPath, token });
+        ownsLock = false;
+        throw validationError(
+          `Another Lumine admin scan is recovering checkpoint ${checkpointPath}. Retry after it finishes.`,
+        );
+      }
+      return { lockPath, token };
+    } catch (error) {
+      if (descriptor !== undefined) {
+        try {
+          closeSync(descriptor);
+        } catch {
+          // The failed lock initialization may already have closed it.
+        }
+      }
+      if (ownsLock) {
+        try {
+          unlinkSync(lockPath);
+        } catch {
+          // A failed initialization may leave no owned lock to remove.
+        }
+      }
+      if (error?.code !== "EEXIST") throw error;
+      if (attempt > 0 || !removeDeadCheckpointLock(lockPath)) {
+        throw validationError(
+          `Another Lumine admin scan owns checkpoint ${checkpointPath}. Wait for it to finish or choose a different --checkpoint.`,
+        );
+      }
+    }
+  }
+  throw validationError(
+    `Could not acquire the pagination checkpoint lock for ${checkpointPath}.`,
+  );
+}
+
+function removeDeadCheckpointLock(lockPath) {
+  const reclaimPath = `${lockPath}.reclaim`;
+  let ownsReclaim = false;
+  try {
+    // Creating a fixed-name hard link is an atomic claim on the exact lock
+    // inode. It serializes reclaimers and lets us prove we are not unlinking a
+    // replacement lock created after another process removed the stale one.
+    linkSync(lockPath, reclaimPath);
+    ownsReclaim = true;
+    const fileState = lstatSync(reclaimPath);
+    if (!fileState.isFile() || fileState.isSymbolicLink()) return false;
+    if (fileState.size > 16 * 1024) return false;
+    const state = JSON.parse(readFileSync(reclaimPath, "utf8"));
+    if (
+      state?.kind !== "admin-pagination-lock" ||
+      !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(
+        String(state?.token || ""),
+      ) ||
+      !/^[a-f0-9]{64}$/i.test(String(state?.operationFingerprint || ""))
+    ) {
+      return false;
+    }
+    const pid = Number(state?.pid);
+    if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      if (error?.code !== "ESRCH") return false;
+    }
+    const claimedState = lstatSync(reclaimPath);
+    const currentState = lstatSync(lockPath);
+    if (
+      claimedState.dev !== currentState.dev ||
+      claimedState.ino !== currentState.ino
+    ) {
+      return false;
+    }
+    unlinkSync(lockPath);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (ownsReclaim) {
+      try {
+        unlinkSync(reclaimPath);
+      } catch {
+        // A failed or completed reclaim leaves the current lock untouched.
+      }
+    }
+  }
+}
+
+function releaseCheckpointLock(lock) {
+  try {
+    const fileState = lstatSync(lock.lockPath);
+    if (!fileState.isFile() || fileState.isSymbolicLink()) return;
+    const saved = JSON.parse(readFileSync(lock.lockPath, "utf8"));
+    if (saved?.token === lock.token && Number(saved?.pid) === process.pid) {
+      unlinkSync(lock.lockPath);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") {
+      process.stderr.write(
+        `Lumine admin: could not release pagination lock ${lock.lockPath} (${error?.message || error}).\n`,
+      );
+    }
+  }
 }
 
 function operationFingerprintValue({
@@ -91,6 +282,13 @@ function operationFingerprintValue({
     apiUrl: String(options.apiUrl || "").replace(/\/$/, ""),
     name: operation.name,
     path: pathWithCursor(operation.path, ""),
+    ...(operation.name === "builds.candidates"
+      ? {
+          resultTransform: {
+            siteUrl: String(options.siteUrl || "").replace(/\/$/, ""),
+          },
+        }
+      : {}),
     pagination: {
       collectionKey: operation.pagination.collectionKey,
       coverageQueue: operation.pagination.coverageQueue || null,
@@ -141,9 +339,13 @@ function createCandidateSpool(checkpointPath) {
 function loadSupersededCandidateSpool(checkpointPath) {
   let saved;
   try {
-    saved = readAdminJsonFile(checkpointPath, "the previous pagination checkpoint", {
-      maxBytes: MAX_LEGACY_ADMIN_CHECKPOINT_BYTES,
-    });
+    saved = readAdminJsonFile(
+      checkpointPath,
+      "the previous pagination checkpoint",
+      {
+        maxBytes: MAX_LEGACY_ADMIN_CHECKPOINT_BYTES,
+      },
+    );
   } catch {
     return null;
   }
@@ -215,8 +417,7 @@ function normalizeClientFilterSummary(value) {
   if (
     !Array.isArray(value.contentTypes) ||
     value.contentTypes.some(
-      (contentType) =>
-        typeof contentType !== "string" || !contentType.trim(),
+      (contentType) => typeof contentType !== "string" || !contentType.trim(),
     )
   ) {
     throw validationError(
@@ -324,7 +525,9 @@ function verifyCandidateSpool({
   try {
     fileState = lstatSync(spoolPath);
   } catch {
-    throw validationError(`Could not read pagination candidates at ${spoolPath}.`);
+    throw validationError(
+      `Could not read pagination candidates at ${spoolPath}.`,
+    );
   }
   if (!fileState.isFile() || fileState.isSymbolicLink()) {
     throw validationError(
@@ -430,7 +633,9 @@ function serializedObjectEntries(value, excludedKeys = new Set()) {
 export async function forEachPaginatedResultItem(result, visit) {
   const storage = paginationStorageFromResult(result);
   if (!storage) {
-    throw validationError("The result does not contain spooled pagination data.");
+    throw validationError(
+      "The result does not contain spooled pagination data.",
+    );
   }
   verifyCandidateSpool({ ...storage, discardUnconfirmedTail: false });
   const input = createReadStream(storage.spoolPath, { encoding: "utf8" });
@@ -604,22 +809,87 @@ function aggregatePageResult({ operation, lastPage, checkpointPath, state }) {
   });
 }
 
-export async function runAutomaticPagination({
+export async function runAutomaticPagination(args) {
+  const { options, operation, runId } = args;
+  if (!operation.pagination) {
+    throw validationError(
+      "--all is supported only by paginated admin listings.",
+    );
+  }
+  const operationFingerprint = operationFingerprintValue({
+    schemaVersion: ADMIN_PAGINATION_SCHEMA_VERSION,
+    options,
+    operation,
+    runId,
+  });
+  const checkpointPath = resolveAutomaticCheckpointPath({
+    options,
+    operation,
+    runId,
+    operationFingerprint,
+  });
+  const lock = acquireCheckpointLock(checkpointPath, operationFingerprint);
+  const signalSource = args.signalSource || process;
+  const controller = new AbortController();
+  let interruptedSignal = "";
+  const interrupt = (signalName) => {
+    interruptedSignal ||= signalName;
+    controller.abort(
+      new Error(`Lumine admin scan interrupted by ${signalName}.`),
+    );
+  };
+  const onSigint = () => interrupt("SIGINT");
+  const onSigterm = () => interrupt("SIGTERM");
+  signalSource.once("SIGINT", onSigint);
+  signalSource.once("SIGTERM", onSigterm);
+  try {
+    return await runAutomaticPaginationWithLock({
+      ...args,
+      checkpointPath,
+      operationFingerprint,
+      signal: controller.signal,
+    });
+  } catch (error) {
+    if (interruptedSignal) {
+      const interrupted = validationError(
+        `Canonical scan cancelled by ${interruptedSignal}. Confirmed progress remains at ${checkpointPath}; rerun the same command with --resume to continue it.`,
+      );
+      interrupted.code = "LUMINE_ADMIN_SCAN_CANCELLED";
+      interrupted.data = {
+        ok: false,
+        status: "validation_error",
+        error: {
+          code: interrupted.code,
+          message: interrupted.message,
+          details: {
+            checkpointPath,
+            signal: interruptedSignal,
+            resumable: true,
+          },
+        },
+      };
+      throw interrupted;
+    }
+    throw error;
+  } finally {
+    signalSource.removeListener("SIGINT", onSigint);
+    signalSource.removeListener("SIGTERM", onSigterm);
+    releaseCheckpointLock(lock);
+  }
+}
+
+async function runAutomaticPaginationWithLock({
   options,
   operation,
   runId,
+  checkpointPath,
+  operationFingerprint,
   fetchPage,
   transformPage,
   recordCoverage,
   reportProgress = (message) => process.stderr.write(`${message}\n`),
+  signal,
 }) {
-  if (!operation.pagination) {
-    throw validationError("--all is supported only by paginated admin listings.");
-  }
-  const checkpointPath = path.resolve(
-    options.adminCheckpoint ||
-      defaultCheckpointPath({ runId, operationName: operation.name }),
-  );
   const requestedOutputPath = String(options.adminOutput || "").trim();
   if (options.adminOutput && !requestedOutputPath) {
     throw validationError("An output file path is required.");
@@ -632,12 +902,6 @@ export async function runAutomaticPagination({
       "The pagination checkpoint and result output must use different files.",
     );
   }
-  const operationFingerprint = operationFingerprintValue({
-    schemaVersion: ADMIN_PAGINATION_SCHEMA_VERSION,
-    options,
-    operation,
-    runId,
-  });
   const legacyOperationFingerprint = operationFingerprintValue({
     schemaVersion: LEGACY_ADMIN_PAGINATION_SCHEMA_VERSION,
     options,
@@ -774,15 +1038,12 @@ export async function runAutomaticPagination({
             : null,
         snapshotTimeStamp:
           savedPages > 0
-            ? normalizeBoundary(
-                saved?.snapshotTimeStamp,
-                "snapshotTimeStamp",
-              )
+            ? normalizeBoundary(saved?.snapshotTimeStamp, "snapshotTimeStamp")
             : null,
         after:
           savedPages > 0
             ? normalizeBoundary(saved?.after, "after")
-            : operation.pagination.after ?? null,
+            : (operation.pagination.after ?? null),
         boundariesConfirmed: saved?.boundariesConfirmed,
         candidateCount,
         spoolPath: path.resolve(String(saved?.spoolPath || "")),
@@ -849,19 +1110,27 @@ export async function runAutomaticPagination({
   }
   let lastPage = null;
   while (!state.exhausted) {
+    signal?.throwIfAborted();
     if (state.pages >= MAX_AUTOMATIC_PAGES) {
       throw validationError(
         `Automatic pagination stopped at the ${MAX_AUTOMATIC_PAGES}-page safety ceiling. Start a narrower request with a new checkpoint.`,
       );
     }
     const requestPath = pathWithCursor(operation.path, state.nextCursor);
-    const raw = await fetchPage(requestPath);
+    const raw = await fetchPage(requestPath, signal);
+    signal?.throwIfAborted();
     const page = transformPage(raw);
     lastPage = page;
     const data = page?.data || {};
     const pagination = data.pagination;
-    if (!pagination || typeof pagination !== "object" || Array.isArray(pagination)) {
-      throw validationError("The API response is missing canonical pagination metadata.");
+    if (
+      !pagination ||
+      typeof pagination !== "object" ||
+      Array.isArray(pagination)
+    ) {
+      throw validationError(
+        "The API response is missing canonical pagination metadata.",
+      );
     }
     const items = Array.isArray(data[operation.pagination.collectionKey])
       ? data[operation.pagination.collectionKey]
@@ -873,7 +1142,9 @@ export async function runAutomaticPagination({
     }
     const nextCursor = String(pagination.nextCursor || "");
     if (nextCursor && nextCursor === state.nextCursor) {
-      throw validationError("The API returned the same pagination cursor twice.");
+      throw validationError(
+        "The API returned the same pagination cursor twice.",
+      );
     }
     if (!pagination.exhausted && !nextCursor) {
       throw validationError(
@@ -895,7 +1166,11 @@ export async function runAutomaticPagination({
     );
     const pageAfter = normalizeBoundary(pagination.after, "after");
     if (state.boundariesConfirmed) {
-      assertStableBoundary("snapshotMaxId", state.snapshotMaxId, pageSnapshotMaxId);
+      assertStableBoundary(
+        "snapshotMaxId",
+        state.snapshotMaxId,
+        pageSnapshotMaxId,
+      );
       assertStableBoundary(
         "snapshotTimeStamp",
         state.snapshotTimeStamp,
@@ -903,7 +1178,10 @@ export async function runAutomaticPagination({
       );
       assertStableBoundary("after", state.after, pageAfter);
     } else {
-      const requestedAfter = normalizeBoundary(operation.pagination.after, "after");
+      const requestedAfter = normalizeBoundary(
+        operation.pagination.after,
+        "after",
+      );
       if (requestedAfter !== null) {
         assertStableBoundary("after", requestedAfter, pageAfter);
       }
@@ -931,10 +1209,7 @@ export async function runAutomaticPagination({
       pages: state.pages + 1,
       scannedCount:
         state.scannedCount +
-        normalizeScannedCount(
-          pagination.scannedCount,
-          items.length,
-        ),
+        normalizeScannedCount(pagination.scannedCount, items.length),
       candidateCount: state.candidateCount + items.length,
       spoolBytes: state.spoolBytes + appended.addedBytes,
       spoolSha256: appended.spoolSha256,
@@ -961,19 +1236,24 @@ export async function runAutomaticPagination({
     checkpointPath,
     state,
   });
+  signal?.throwIfAborted();
   if (recordCoverage && operation.pagination.coverageQueue) {
-    await recordCoverage({
-      queue: operation.pagination.coverageQueue,
-      mode: operation.pagination.coverageMode || "all",
-      after: state.after,
-      pages: state.pages,
-      scannedCount: state.scannedCount,
-      candidateCount: state.candidateCount,
-      snapshotMaxId: state.snapshotMaxId,
-      snapshotTimeStamp: state.snapshotTimeStamp,
-      exhausted: state.exhausted,
-      filters: operation.pagination.filters || {},
-    });
+    await recordCoverage(
+      {
+        queue: operation.pagination.coverageQueue,
+        mode: operation.pagination.coverageMode || "all",
+        after: state.after,
+        pages: state.pages,
+        scannedCount: state.scannedCount,
+        candidateCount: state.candidateCount,
+        snapshotMaxId: state.snapshotMaxId,
+        snapshotTimeStamp: state.snapshotTimeStamp,
+        exhausted: state.exhausted,
+        filters: operation.pagination.filters || {},
+      },
+      signal,
+    );
+    signal?.throwIfAborted();
   }
   if (outputPath) {
     result.data.scan.outputPath = outputPath;
@@ -1010,12 +1290,16 @@ export function readBatchSkipTargets({ filePath, parseTarget, defaultReason }) {
     throw validationError("The batch target file contains no targets.");
   }
   if (values.length > MAX_BATCH_TARGETS) {
-    throw validationError(`A batch can contain at most ${MAX_BATCH_TARGETS} targets.`);
+    throw validationError(
+      `A batch can contain at most ${MAX_BATCH_TARGETS} targets.`,
+    );
   }
   const deduped = new Map();
   for (const value of values) {
     const rawTarget =
-      typeof value === "string" ? value : value?.target || value?.url || value?.id;
+      typeof value === "string"
+        ? value
+        : value?.target || value?.url || value?.id;
     const parsed = parseTarget({
       target: rawTarget,
       explicitType: typeof value === "object" ? value?.type || "" : "",
@@ -1082,7 +1366,9 @@ export async function runBatchSkips({
       !saved.completed ||
       typeof saved.completed !== "object"
     ) {
-      throw validationError("The checkpoint does not match this exact skip batch.");
+      throw validationError(
+        "The checkpoint does not match this exact skip batch.",
+      );
     }
     state = saved;
   } else {
@@ -1123,8 +1409,9 @@ export async function runBatchSkips({
       batch: {
         targetCount: targets.length,
         completedCount: Object.keys(state.completed).length,
-        changedCount: Object.values(state.completed).filter((entry) => entry.changed)
-          .length,
+        changedCount: Object.values(state.completed).filter(
+          (entry) => entry.changed,
+        ).length,
         checkpointPath,
         resumed: options.adminResume === true,
         targets: state.completed,
@@ -1132,10 +1419,14 @@ export async function runBatchSkips({
     },
   };
   if (options.adminOutput) {
-    result.data.batch.outputPath = writeAdminJsonFile(options.adminOutput, result, {
-      privateFile: true,
-      maxBytes: MAX_BATCH_CHECKPOINT_BYTES,
-    });
+    result.data.batch.outputPath = writeAdminJsonFile(
+      options.adminOutput,
+      result,
+      {
+        privateFile: true,
+        maxBytes: MAX_BATCH_CHECKPOINT_BYTES,
+      },
+    );
   }
   return result;
 }