@openclaw/crabline 0.1.14 → 0.1.15

package/dist/src/openclaw/private-file.js

@@ -4,6 +4,7 @@ import { constants as fsConstants, readFileSync } from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
+import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
 import { applyOwnerOnlyWindowsDirectoryAcl as applyOwnerOnlyWindowsDirectoryAclByHandle, createOwnerOnlyWindowsDirectoryAncestry as createOwnerOnlyWindowsDirectoryAncestryByHandle, } from "../platform/windows-acl.js";
 const execFileAsync = promisify(execFile);
@@ -1101,6 +1102,38 @@ const PRIVATE_MUTATION_CLAIM_ROOT_FILE = ".crabline-private-mutation.claim";
 const PRIVATE_MUTATION_CLAIM_OWNER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const PRIVATE_MUTATION_CLAIM_METADATA_MAX_BYTES = 4096;
 const PRIVATE_MUTATION_RESERVED_BASENAME_PATTERN = /^\.crabline-private-mutation(?:\.|$)/iu;
+const PRIVATE_MUTATION_CLAIM_WAIT_TIMEOUT_MS = 60_000;
+const PRIVATE_MUTATION_CLAIM_RETRY_DELAY_MS = 50;
+function preparePrivateMutationClaimWait(options) {
+    const timeoutMs = options.timeoutMs ?? PRIVATE_MUTATION_CLAIM_WAIT_TIMEOUT_MS;
+    const retryDelayMs = options.retryDelayMs ?? PRIVATE_MUTATION_CLAIM_RETRY_DELAY_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0) {
+        throw new Error("Private mutation claim wait timeout must be a non-negative safe integer.");
+    }
+    if (!Number.isSafeInteger(retryDelayMs) || retryDelayMs <= 0) {
+        throw new Error("Private mutation claim retry delay must be a positive safe integer.");
+    }
+    const now = options.now ?? performance.now.bind(performance);
+    const sleep = options.sleep ??
+        ((delayMs, signal) => delay(delayMs, undefined, { signal }));
+    if (typeof now !== "function" || typeof sleep !== "function") {
+        throw new Error("Private mutation claim wait callbacks must be functions.");
+    }
+    if (options.signal !== undefined && typeof options.signal.throwIfAborted !== "function") {
+        throw new Error("Private mutation claim wait signal is invalid.");
+    }
+    options.signal?.throwIfAborted();
+    if (!Number.isFinite(now())) {
+        throw new Error("Private mutation claim wait clock is invalid.");
+    }
+    return {
+        now,
+        retryDelayMs,
+        ...(options.signal ? { signal: options.signal } : {}),
+        sleep,
+        timeoutMs,
+    };
+}
 function assertNotReservedPrivateMutationPath(targetPath) {
     if (PRIVATE_MUTATION_RESERVED_BASENAME_PATTERN.test(path.basename(targetPath))) {
         throw new Error("Private path uses Crabline's reserved mutation claim namespace.");
@@ -1345,6 +1378,11 @@ class UnsupportedPrivateMutationHardLinkError extends Error {
         super("Private mutation claims require a non-hard-link fallback.", { cause });
     }
 }
+class ActivePrivateMutationClaimError extends Error {
+    constructor(cause) {
+        super("Private path mutation is already claimed.", { cause });
+    }
+}
 function isUnsupportedHardLinkError(error) {
     const code = error.code;
     return code === "EPERM" || code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "ENOSYS";
@@ -1426,15 +1464,15 @@ async function acquireHardLinkPrivateMutationClaim(parent, options) {
                 if (runtime.isProcessAlive(observed.owner.pid)) {
                     if (observed.owner.pid === runtime.pid &&
                         observed.owner.processStartedAtMs === runtime.processStartedAtMs) {
-                        throw new Error("Private path mutation is already claimed.", { cause: error });
+                        throw new ActivePrivateMutationClaimError(error);
                     }
                     else if (observed.owner.pid !== runtime.pid) {
                         if (observed.owner.processIdentity === undefined) {
-                            throw new Error("Private path mutation is already claimed.", { cause: error });
+                            throw new ActivePrivateMutationClaimError(error);
                         }
                         const actualIdentity = runtime.getProcessIdentity(observed.owner.pid);
                         if (actualIdentity === null || actualIdentity === observed.owner.processIdentity) {
-                            throw new Error("Private path mutation is already claimed.", { cause: error });
+                            throw new ActivePrivateMutationClaimError(error);
                         }
                     }
                 }
@@ -1796,7 +1834,7 @@ async function acquireDirectoryPrivateMutationClaim(parent, options) {
                     throw error;
                 }
                 if (privateMutationClaimOwnerIsActive(observed.metadata.owner, runtime)) {
-                    throw new Error("Private path mutation is already claimed.", { cause: error });
+                    throw new ActivePrivateMutationClaimError(error);
                 }
                 await parent.assertIdentityAt();
                 const revalidated = await readPrivateMutationDirectoryClaim(claimPath);
@@ -2131,8 +2169,7 @@ async function ownerOnlyPrivateClaimAncestry(leaf, platform) {
 async function acquirePrivateMutationClaimChain(leaf, options) {
     const platform = options.platform ?? process.platform;
     const ancestry = await ownerOnlyPrivateClaimAncestry(leaf, platform);
-    const highestClaimDirectory = ancestry.at(-1);
-    const outerBoundary = await captureSafePrivateDirectoryMutationParent(highestClaimDirectory.directoryPath, platform);
+    const outerBoundary = await captureSafePrivateDirectoryMutationParent(ancestry.at(-1).directoryPath, platform);
     const claims = [];
     let leafClaim;
     try {
@@ -2239,6 +2276,56 @@ async function acquirePrivateMutationClaimChain(leaf, options) {
         },
     };
 }
+function privateMutationClaimTimeoutError(timeoutMs, cause) {
+    return Object.assign(new Error(`Timed out after ${timeoutMs}ms waiting for a private mutation claim.`, { cause }), { code: "ETIMEDOUT" });
+}
+async function releaseClaimAfterWaitFailure(claim, error) {
+    try {
+        await claim.release();
+    }
+    catch (releaseError) {
+        const aggregateError = new AggregateError([error, releaseError], "Private mutation claim wait failed and its acquired claim could not be released.");
+        aggregateError.cause = error;
+        throw aggregateError;
+    }
+    throw error;
+}
+async function acquirePrivateMutationClaimWithWait(acquire, wait) {
+    if (wait === undefined) {
+        return await acquire();
+    }
+    const deadlineMs = wait.now() + wait.timeoutMs;
+    let lastContentionError;
+    for (;;) {
+        wait.signal?.throwIfAborted();
+        let claim;
+        try {
+            claim = await acquire();
+        }
+        catch (error) {
+            if (!(error instanceof ActivePrivateMutationClaimError) || wait.timeoutMs === 0) {
+                throw error;
+            }
+            lastContentionError = error;
+            const remainingMs = deadlineMs - wait.now();
+            if (remainingMs <= 0) {
+                throw privateMutationClaimTimeoutError(wait.timeoutMs, error);
+            }
+            await wait.sleep(Math.min(wait.retryDelayMs, remainingMs), wait.signal);
+            continue;
+        }
+        try {
+            wait.signal?.throwIfAborted();
+            if (lastContentionError && wait.now() >= deadlineMs) {
+                throw privateMutationClaimTimeoutError(wait.timeoutMs, lastContentionError);
+            }
+        }
+        catch (error) {
+            return await releaseClaimAfterWaitFailure(claim, error);
+        }
+        return claim;
+    }
+}
 async function secureOwnerOnlyMutationParent(directoryPath) {
     return await securePrivateDirectory(directoryPath, {
         markMutationRoot: false,
@@ -2247,6 +2334,7 @@ async function secureOwnerOnlyMutationParent(directoryPath) {
 }
 export async function publishPrivateFileAtomically(filePath, contents, options = {}) {
     assertNotReservedPrivateMutationPath(filePath);
+    const claimWait = preparePrivateMutationClaimWait(options.claimWait ?? {});
     const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
     const parentDirectory = path.resolve(path.dirname(filePath));
     const platform = options.platform ?? process.platform;
@@ -2285,11 +2373,14 @@ export async function publishPrivateFileAtomically(filePath, contents, options =
     await migrationBoundary?.assertIdentityAt();
     const parent = await secureOwnerOnlyMutationParent(parentDirectory);
     await migrationBoundary?.assertIdentityAt();
-    const claim = await acquirePrivateMutationClaimChain(parent, {
+    const claimOptions = {
         ...(options.claimRuntime ? { runtime: options.claimRuntime } : {}),
         ...(options.createWindowsFile ? { createWindowsFile: options.createWindowsFile } : {}),
         ...(options.platform ? { platform: options.platform } : {}),
-    });
+    };
+    // The full ancestry fence stays held for the temporary file's lifetime so supported removals
+    // cannot quarantine a secret. Active publishers wait here without serializing their whole flow.
+    const claim = await acquirePrivateMutationClaimWithWait(() => acquirePrivateMutationClaimChain(parent, claimOptions), claimWait);
     let handle;
     let identity;
     let publicationFailed = false;