@openclaw/fs-safe 0.4.7 → 0.5.1

package/dist/publish-file.js

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pinDirectory, } from "./directory-durability.js";
+import { FsSafeError } from "./errors.js";
+import { hashFileHandle } from "./file-hash.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { syncNativeFileBestEffort } from "./native-operations.js";
+import { getNativeBinding, requireNativeBinding } from "./native.js";
+import { directorySyncFailure, publicationFailure, rememberCreatedTarget, } from "./publish-file-failure.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+const HARDLINK_FALLBACK_CODES = new Set([
+    "EPERM",
+    "EXDEV",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "ENOSYS",
+]);
+const NATIVE_COPY_FALLBACK_CODES = new Set([
+    "EINVAL",
+    "ENOSYS",
+    "ENOTSUP",
+    "EOPNOTSUPP",
+    "EPERM",
+    "EXDEV",
+]);
+export function isHardlinkFallbackError(error) {
+    return HARDLINK_FALLBACK_CODES.has(error?.code ?? "");
+}
+function sourceOpenFlags() {
+    return (fsSync.constants.O_RDONLY |
+        (process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+            ? fsSync.constants.O_NOFOLLOW
+            : 0));
+}
+function directoryOpenFlags() {
+    return (fsSync.constants.O_RDONLY |
+        (typeof fsSync.constants.O_DIRECTORY === "number" ? fsSync.constants.O_DIRECTORY : 0));
+}
+async function openNativeParent(binding, filePath) {
+    const parentPath = path.dirname(filePath);
+    const handle = await fs.open(parentPath, directoryOpenFlags());
+    try {
+        const pathname = await fs.lstat(parentPath);
+        const opened = binding.fstatIdentity(handle.fd);
+        if (pathname.isSymbolicLink() || !sameFileIdentity(pathname, opened)) {
+            throw new FsSafeError("path-mismatch", "publication parent changed while opening");
+        }
+        return { basename: path.basename(filePath), handle };
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+async function assertPinnedSourceCurrent(params) {
+    const opened = await params.handle.stat();
+    const current = await fs.lstat(params.sourcePath);
+    if (!opened.isFile() ||
+        current.isSymbolicLink() ||
+        !current.isFile() ||
+        !sameFileIdentity(opened, params.identity) ||
+        !sameFileIdentity(current, opened)) {
+        throw new FsSafeError("path-mismatch", "publication source changed during operation");
+    }
+}
+async function copyPinnedSource(params) {
+    if (params.native && params.targetNativeParent) {
+        for (const method of ["clone", "copy-file-range"]) {
+            let nativeFd;
+            try {
+                if (method === "clone") {
+                    nativeFd = params.native.cloneFileExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
+                }
+                else {
+                    const copied = await params.native.copyFileRangeExclusive(params.source.fd, params.targetNativeParent.handle.fd, params.targetNativeParent.basename);
+                    if (copied.errorCode) {
+                        throw Object.assign(new Error(copied.errorMessage ?? "native copy failed"), {
+                            code: copied.errorCode,
+                        });
+                    }
+                    nativeFd = copied.fd;
+                }
+            }
+            catch (error) {
+                if (NATIVE_COPY_FALLBACK_CODES.has(error.code ?? "")) {
+                    continue;
+                }
+                throw error;
+            }
+            let target;
+            const createdIdentity = params.native.fstatIdentity(nativeFd);
+            rememberCreatedTarget(params.failure, createdIdentity, "copy-verify");
+            try {
+                await getFsSafeTestHooks()?.afterPublishTargetCreated?.("exclusive-copy", params.targetPath, createdIdentity);
+                const identity = await fs.lstat(params.targetPath);
+                target = await fs.open(params.targetPath, sourceOpenFlags());
+                const opened = await target.stat();
+                if (identity.isSymbolicLink() ||
+                    !identity.isFile() ||
+                    !sameFileIdentity(createdIdentity, identity) ||
+                    !sameFileIdentity(createdIdentity, opened)) {
+                    throw new FsSafeError("path-mismatch", "native publication target changed after copy");
+                }
+                const hashed = await hashFileHandle(target, params.native);
+                fsSync.closeSync(nativeFd);
+                nativeFd = undefined;
+                return {
+                    handle: target,
+                    stat: await target.stat(),
+                    digest: hashed.digest,
+                    bytes: hashed.bytes,
+                };
+            }
+            catch (error) {
+                await target?.close().catch(() => undefined);
+                throw error;
+            }
+            finally {
+                if (nativeFd !== undefined)
+                    fsSync.closeSync(nativeFd);
+            }
+        }
+    }
+    const target = await fs.open(params.targetPath, "wx+", 0o600);
+    const identity = await target.stat();
+    rememberCreatedTarget(params.failure, identity, "copy-verify");
+    try {
+        await getFsSafeTestHooks()?.afterPublishTargetCreated?.("exclusive-copy", params.targetPath, identity);
+        const hash = createHash("sha256");
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        let position = 0;
+        while (true) {
+            const { bytesRead } = await params.source.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0) {
+                break;
+            }
+            hash.update(buffer.subarray(0, bytesRead));
+            let written = 0;
+            while (written < bytesRead) {
+                const result = await target.write(buffer, written, bytesRead - written, position + written);
+                if (result.bytesWritten <= 0) {
+                    throw new FsSafeError("helper-failed", "exclusive publication copy made no progress");
+                }
+                written += result.bytesWritten;
+            }
+            position += bytesRead;
+        }
+        await target.sync();
+        return { handle: target, stat: identity, digest: hash.digest("hex"), bytes: position };
+    }
+    catch (error) {
+        await target.close().catch(() => undefined);
+        throw error;
+    }
+}
+async function removeCreatedTargetIfUnchanged(targetPath, identity) {
+    if (!identity) {
+        return "unknown";
+    }
+    try {
+        const current = await fs.lstat(targetPath);
+        if (!current.isSymbolicLink() && sameFileIdentity(current, identity)) {
+            await fs.rm(targetPath);
+            return "removed";
+        }
+        return "preserved";
+    }
+    catch (error) {
+        return error.code === "ENOENT" ? "removed" : "unknown";
+    }
+}
+async function syncPublishedParent(params) {
+    params.failure.phase = "directory-sync";
+    try {
+        await getFsSafeTestHooks()?.beforePublishDirectorySync?.(params.method, params.targetPath, params.failure.targetIdentity);
+        // PinnedDirectory.sync() revalidates descriptor/path identity immediately
+        // before and after fsync; keep that check inside the shared sync boundary.
+        return await params.parent.sync();
+    }
+    catch (error) {
+        params.failure.directorySync = directorySyncFailure(error);
+        throw error;
+    }
+}
+export async function publishFileExclusive(params) {
+    const sourcePath = path.resolve(params.sourcePath);
+    const targetPath = path.resolve(params.targetPath);
+    const parentPath = path.dirname(targetPath);
+    if (params.parentReceipt && path.resolve(params.parentReceipt.path) !== parentPath) {
+        throw new FsSafeError("path-mismatch", "publication parent receipt does not match target parent");
+    }
+    const sourcePathStat = await fs.lstat(sourcePath);
+    if (sourcePathStat.isSymbolicLink() || !sourcePathStat.isFile()) {
+        throw new FsSafeError("not-file", "publication source must be a regular file");
+    }
+    const source = await fs.open(sourcePath, sourceOpenFlags());
+    let parent;
+    let sourceNativeParent;
+    let targetNativeParent;
+    const failure = {
+        phase: params.strategy === "rename-noreplace" ? "rename-create" : "hardlink-create",
+        targetCreated: false,
+        preserveTarget: false,
+    };
+    try {
+        parent = await pinDirectory(params.parentReceipt ?? parentPath, {
+            label: "publication parent",
+        });
+        const sourceIdentity = await source.stat();
+        if (!sameFileIdentity(sourcePathStat, sourceIdentity) ||
+            (params.expectedSourceIdentity &&
+                !sameFileIdentity(params.expectedSourceIdentity, sourceIdentity))) {
+            throw new FsSafeError("path-mismatch", "publication source identity did not match");
+        }
+        await parent.assertCurrent();
+        await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceIdentity });
+        const native = params.strategy === "rename-noreplace"
+            ? requireNativeBinding()
+            : getNativeBinding();
+        if (native) {
+            sourceNativeParent = await openNativeParent(native, sourcePath);
+            targetNativeParent = await openNativeParent(native, targetPath);
+        }
+        if (params.strategy === "rename-noreplace") {
+            const binding = requireNativeBinding();
+            binding.renameNoReplace(sourceNativeParent.handle.fd, sourceNativeParent.basename, targetNativeParent.handle.fd, targetNativeParent.basename);
+            rememberCreatedTarget(failure, sourceIdentity, "rename-verify");
+            // A failed post-rename fence must not delete the only remaining name.
+            failure.preserveTarget = true;
+            await getFsSafeTestHooks()?.afterPublishTargetCreated?.("rename-noreplace", targetPath, sourceIdentity);
+            const targetIdentity = await fs.lstat(targetPath);
+            if (targetIdentity.isSymbolicLink() ||
+                !targetIdentity.isFile() ||
+                !sameFileIdentity(targetIdentity, sourceIdentity)) {
+                throw new FsSafeError("path-mismatch", "no-replace publication target changed");
+            }
+            try {
+                await fs.lstat(sourcePath);
+                throw new FsSafeError("path-mismatch", "no-replace publication source still exists");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    throw error;
+                }
+            }
+            syncNativeFileBestEffort(sourceNativeParent.handle.fd);
+            return {
+                method: "rename-noreplace",
+                identity: targetIdentity,
+                directorySync: await syncPublishedParent({
+                    parent,
+                    failure,
+                    method: "rename-noreplace",
+                    targetPath,
+                }),
+            };
+        }
+        try {
+            if (native) {
+                native.linkBeneath(sourceNativeParent.handle.fd, sourceNativeParent.basename, targetNativeParent.handle.fd, targetNativeParent.basename);
+            }
+            else {
+                await fs.link(sourcePath, targetPath);
+            }
+            rememberCreatedTarget(failure, sourceIdentity, "hardlink-verify");
+            await getFsSafeTestHooks()?.afterPublishTargetCreated?.("hardlink", targetPath, sourceIdentity);
+            const targetIdentity = await fs.lstat(targetPath);
+            if (targetIdentity.isSymbolicLink() ||
+                !targetIdentity.isFile() ||
+                !sameFileIdentity(targetIdentity, sourceIdentity)) {
+                throw new FsSafeError("path-mismatch", "hardlink publication target changed");
+            }
+            await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceIdentity });
+            return {
+                method: "hardlink",
+                identity: targetIdentity,
+                directorySync: await syncPublishedParent({
+                    parent,
+                    failure,
+                    method: "hardlink",
+                    targetPath,
+                }),
+            };
+        }
+        catch (error) {
+            if (failure.targetCreated ||
+                !isHardlinkFallbackError(error) ||
+                params.strategy === "link-required") {
+                throw error;
+            }
+        }
+        failure.phase = "copy-create";
+        let target;
+        let targetIdentity;
+        try {
+            const copied = await copyPinnedSource({
+                source,
+                targetPath,
+                native,
+                targetNativeParent,
+                failure,
+            });
+            target = copied.handle;
+            targetIdentity = copied.stat;
+            const targetPathStat = await fs.lstat(targetPath);
+            const copiedBack = await hashFileHandle(target, native);
+            const sourceAfter = await hashFileHandle(source, native);
+            if (targetPathStat.isSymbolicLink() ||
+                !sameFileIdentity(targetPathStat, targetIdentity) ||
+                copiedBack.bytes !== copied.bytes ||
+                copiedBack.digest !== copied.digest ||
+                sourceAfter.bytes !== copied.bytes ||
+                sourceAfter.digest !== copied.digest) {
+                throw new FsSafeError("path-mismatch", "exclusive publication copy failed content fencing");
+            }
+            await assertPinnedSourceCurrent({ sourcePath, handle: source, identity: sourceIdentity });
+            const directorySync = await syncPublishedParent({
+                parent,
+                failure,
+                method: "exclusive-copy",
+                targetPath,
+            });
+            return { method: "exclusive-copy", identity: targetPathStat, directorySync };
+        }
+        catch (error) {
+            await target?.close().catch(() => undefined);
+            target = undefined;
+            throw error;
+        }
+        finally {
+            await target?.close().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        if (!failure.targetCreated)
+            throw error;
+        const preserveSyncFailure = failure.phase === "directory-sync" && params.onSyncFailure === "preserve";
+        const cleanup = failure.preserveTarget || preserveSyncFailure
+            ? "preserved"
+            : await removeCreatedTargetIfUnchanged(targetPath, failure.targetIdentity);
+        throw publicationFailure(error, failure, cleanup);
+    }
+    finally {
+        await sourceNativeParent?.handle.close().catch(() => undefined);
+        await targetNativeParent?.handle.close().catch(() => undefined);
+        await source.close().catch(() => undefined);
+        await parent?.close().catch(() => undefined);
+    }
+}

package/dist/read-opened-file.d.ts

@@ -1,12 +1,15 @@
 import type { Stats } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
+import type { ContainmentGuarantee } from "./containment.js";
 export type ReadResult = {
     buffer: Buffer;
+    containment: ContainmentGuarantee;
     realPath: string;
     stat: Stats;
 };
 type OpenedFile = {
     handle: FileHandle;
+    containment: ContainmentGuarantee;
     realPath: string;
     stat: Stats;
 };

package/dist/read-opened-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-opened-file.d.ts","sourceRoot":"","sources":["../src/read-opened-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgBtB"}
+{"version":3,"file":"read-opened-file.d.ts","sourceRoot":"","sources":["../src/read-opened-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAI7D,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBtB"}

package/dist/read-opened-file.js

@@ -9,6 +9,7 @@ export async function readOpenedFileSafely(params) {
         : await readFileHandleBounded(params.opened.handle, params.maxBytes);
     return {
         buffer,
+        containment: params.opened.containment,
         realPath: params.opened.realPath,
         stat: params.opened.stat,
     };

package/dist/replace-file-copy-fallback.d.ts

@@ -0,0 +1,34 @@
+import syncFs from "node:fs";
+export type ReplaceFileDestinationHardlinkPolicy = "reject";
+export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
+export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
+export type ReplaceFileAtomicRestoreFailureDetails = {
+    cleanup: ReplaceFileAtomicRestoreCleanup;
+};
+type AsyncFallbackFs = {
+    lstat: typeof import("node:fs/promises").lstat;
+    open: typeof import("node:fs/promises").open;
+    rm: typeof import("node:fs/promises").rm;
+    unlink: typeof import("node:fs/promises").unlink;
+};
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
+export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
+export declare function copyFallbackReplace(params: {
+    fsModule: AsyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+}): Promise<void>;
+export declare function copyFallbackReplaceSync(params: {
+    fsModule: SyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+}): void;
+export {};
+//# sourceMappingURL=replace-file-copy-fallback.d.ts.map

package/dist/replace-file-copy-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAsB,MAAM,SAAS,CAAC;AAK7C,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAuFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AA0HD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,IAAI,CA4EP"}