@poe-platform/safe-fs 0.1.799 → 0.1.801

package/dist/safe-fs/fs/memory/index.js

@@ -1,5 +1,5 @@
 import { FsError } from "../../contracts/errors.js";
-import { normalizePath } from "../../contracts/virtual-path.js";
+import { normalizePath, validatePath, pathByteLength } from "../../contracts/virtual-path.js";
 import { assertCallbackAuthorityAllowed, compareEntries, registerEntryAuthority } from "../mount/comparison.js";
 import { getOwnedS3Entry } from "../s3/registry.js";
 import { getOwnedWebDavEntry } from "../webdav/resource-id.js";
@@ -56,10 +56,10 @@ DUMMY_POOL_FILE_NODE.atimeMs = DUMMY_POOL_FILE_NODE.mtimeMs = DUMMY_POOL_FILE_NO
 const defaultDateNow = Date.now;
 let fastWriteCachedNow = Date.now();
 let fastWriteNowTick = 0;
-const lastFastMapMiss = {
-    map: undefined, key: "", slot: -1,
-};
 class FastDirectoryEntriesMap {
+    // Keep speculative slots local so a failed write cannot pin a tenant globally.
+    _missKey = "";
+    _missSlot = -1;
     _table = new Int16Array(128).fill(-1);
     _mask = 127;
     _keys = new Array(64).fill("");
@@ -96,9 +96,8 @@ class FastDirectoryEntriesMap {
     getForWriteWithHash(k, h) {
         let slot = h & this._mask;
         if (this.size === 0) {
-            lastFastMapMiss.map = this;
-            lastFastMapMiss.key = k;
-            lastFastMapMiss.slot = slot;
+            this._missKey = k;
+            this._missSlot = slot;
             return undefined;
         }
         const mask = this._mask;
@@ -108,9 +107,8 @@ class FastDirectoryEntriesMap {
         while (true) {
             const idx = table[slot];
             if (idx === -1) {
-                lastFastMapMiss.map = this;
-                lastFastMapMiss.key = k;
-                lastFastMapMiss.slot = firstDeleted !== -1 ? firstDeleted : slot;
+                this._missKey = k;
+                this._missSlot = firstDeleted !== -1 ? firstDeleted : slot;
                 return undefined;
             }
             if (idx === -2) {
@@ -160,6 +158,7 @@ class FastDirectoryEntriesMap {
         return this.get(k) !== undefined;
     }
     _rebuild(newCap) {
+        this._missKey = "";
         const newTableLen = newCap * 2;
         const newMask = newTableLen - 1;
         const newTable = newCap <= 16384 ? new Int16Array(newTableLen).fill(-1) : new Int32Array(newTableLen).fill(-1);
@@ -199,15 +198,16 @@ class FastDirectoryEntriesMap {
         this._next = writeIdx;
     }
     set(k, v) {
-        if (this === lastFastMapMiss.map && k === lastFastMapMiss.key && this._next < this._keys.length) {
+        if (k === this._missKey && this._next < this._keys.length) {
             const entryIdx = this._next++;
-            this._table[lastFastMapMiss.slot] = entryIdx;
+            this._table[this._missSlot] = entryIdx;
             this._keys[entryIdx] = k;
             this._vals[entryIdx] = v;
             this.size++;
-            lastFastMapMiss.map = undefined;
+            this._missKey = "";
             return this;
         }
+        this._missKey = "";
         if (this._next >= this._keys.length) {
             this._rebuild(this.size * 2 <= this._keys.length ? this._keys.length : this._keys.length * 2);
         }
@@ -239,6 +239,7 @@ class FastDirectoryEntriesMap {
         }
     }
     delete(k) {
+        this._missKey = "";
         if (this.size === 0)
             return false;
         let slot = this._hash(k);
@@ -266,6 +267,7 @@ class FastDirectoryEntriesMap {
         }
     }
     clear() {
+        this._missKey = "";
         if (this._next > 0) {
             this._table.fill(-1);
             for (let i = 0; i < this._next; i++) {
@@ -710,7 +712,7 @@ export class MemoryFileSystem {
         const owner = ownedStores.get(this);
         if (path !== "")
             this.validatePath(path, "realpath");
-        return resolveMissingTarget(owner.root, path || ".", options.signal);
+        return resolveMissingTarget(owner.root, path || ".", options.signal, this.ledger.limits);
     }
     async confineExtraction(roots, options = {}) {
         options.signal?.throwIfAborted();
@@ -968,6 +970,8 @@ export class MemoryFileSystem {
             this.fail("EINVAL", syscall, path);
         if (path.length === 0)
             this.fail("ENOENT", syscall, path);
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
     }
     permission(node, mask, syscall, path) {
         if (((node.mode >> 6) & mask) !== mask)
@@ -989,6 +993,8 @@ export class MemoryFileSystem {
         node.mtimeMs = node.ctimeMs = now;
     }
     resolveNode(path, syscall, followFinal = true) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         const cache = memoryCaches.get(this.ledger);
         if (this.symlinkCount === 0 && isCleanAbsolutePath(path)) {
             const fastDir = cache.lastFastDirNode;
@@ -1075,7 +1081,7 @@ export class MemoryFileSystem {
             }
         }
         // Bound all component arrays allocated by this resolution, including cycles.
-        let remainingPathUnits = 65_536 - path.length;
+        let remainingPathUnits = this.ledger.limits.maxPathBytes - pathByteLength(path);
         if (remainingPathUnits < 0)
             this.fail("ENAMETOOLONG", syscall, path);
         let initialComponents = 0;
@@ -1085,12 +1091,12 @@ export class MemoryFileSystem {
                 inComp = false;
             else if (!inComp) {
                 inComp = true;
-                if (++initialComponents > 256)
+                if (++initialComponents > this.ledger.limits.maxPathComponents)
                     this.fail("ENAMETOOLONG", syscall, path);
             }
         }
-        const pending = path.split("/").filter(Boolean);
-        let remainingComponents = 256 - pending.length;
+        let pending = path.split("/").filter(Boolean);
+        let remainingComponents = this.ledger.limits.maxPathComponents - pending.length;
         if (path.endsWith("/"))
             pending.push("");
         const stack = [{ node: this.root, name: "" }];
@@ -1140,9 +1146,9 @@ export class MemoryFileSystem {
             if (node.type === "symlink" && (options.followFinal !== false || pending.length > 0)) {
                 if (++links > 40)
                     this.fail("ELOOP", syscall, path);
-                if (node.target.length > remainingPathUnits)
+                if (pathByteLength(node.target) > remainingPathUnits)
                     this.fail("ENAMETOOLONG", syscall, path);
-                remainingPathUnits -= node.target.length;
+                remainingPathUnits -= pathByteLength(node.target);
                 const target = node.target.split("/").filter(Boolean);
                 if (target.length > remainingComponents)
                     this.fail("ENAMETOOLONG", syscall, path);
@@ -1151,7 +1157,7 @@ export class MemoryFileSystem {
                     target.push("");
                 if (options.resizeCreate !== undefined && target.at(-1) === "" && pending[0] === "")
                     target.pop();
-                pending.unshift(...target);
+                pending = target.concat(pending);
                 if (node.target.startsWith("/"))
                     stack.splice(1);
                 continue;
@@ -1167,6 +1173,8 @@ export class MemoryFileSystem {
         };
     }
     file(path, syscall) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         if (this.symlinkCount === 0 && path.charCodeAt(0) === 47 && path.length > 1 && path.indexOf("/", 1) === -1 && !path.includes("\0")) {
             const name = path === _lastFileSlice1Path ? _lastFileSlice1Name : (_lastFileSlice1Path = path, _lastFileSlice1Name = path.slice(1));
             if (name !== "." && name !== "..") {
@@ -1444,6 +1452,8 @@ export class MemoryFileSystem {
         }, syscall, path);
     }
     writeData(path, data, options, syscall) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         if (!(data instanceof Uint8Array))
             throw new TypeError("Memory files require Uint8Array data");
         const target = this.prepareWrite(path, options, syscall);
@@ -1574,6 +1584,8 @@ export class MemoryFileSystem {
         this.changed(node, now);
     }
     writeMemoryFileFast(path, data, append, mode) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(path, this.ledger.limits);
         const cache = memoryCaches.get(this.ledger);
         const syscall = append ? "appendFile" : "writeFile";
         if (append &&
@@ -1582,8 +1594,8 @@ export class MemoryFileSystem {
             cache.lastFastFileNode.nlink !== 0 &&
             cache.lastFastDirNode !== undefined &&
             cache.lastFastDirNode.nlink !== 0 &&
-            (cache.lastFastDirNode.mode & 1) !== 0 &&
-            (cache.lastFastFileNode.mode & 2) !== 0) {
+            (cache.lastFastDirNode.mode & 0o100) !== 0 &&
+            (cache.lastFastFileNode.mode & 0o200) !== 0) {
             const current = cache.lastFastFileNode;
             const length = current.byteLength + data.byteLength;
             this.admitSize(current, length, syscall, path);
@@ -1599,7 +1611,7 @@ export class MemoryFileSystem {
         const cachedDir = cache.lastFastDirNode;
         if (cachedDir !== undefined &&
             cachedDir.nlink !== 0 &&
-            (cachedDir.mode & 1) !== 0 &&
+            (cachedDir.mode & 0o100) !== 0 &&
             cachedPrefix.length > 1 &&
             path.startsWith(cachedPrefix) &&
             path.indexOf("/", cachedPrefix.length) === -1) {
@@ -1616,7 +1628,7 @@ export class MemoryFileSystem {
                     name = path.slice(start);
                     if (exceedsComponentByteLimit(name))
                         this.fail("ENAMETOOLONG", syscall, path);
-                    if (start > 1 && (parent.mode & 1) !== 0) {
+                    if (start > 1 && (parent.mode & 0o100) !== 0) {
                         cache.lastFastDirPrefix = path.slice(0, start);
                         cache.lastFastDirNode = parent;
                     }
@@ -1753,6 +1765,7 @@ export class MemoryFileSystem {
                 let ino = this.nextInode;
                 this.nextInode = ino + batchCount;
                 let nextIdx = 1;
+                entries._missKey = "";
                 entries._next = 1 + batchCount;
                 entries.size = 1 + batchCount;
                 const table = entries._table;
@@ -1802,6 +1815,8 @@ export class MemoryFileSystem {
         }
     }
     writeMemoryFileInDirFast(dirPrefix, name, data, append, mode, nameHash) {
+        if (this.ledger.limits.maxPathBytes !== Infinity || this.ledger.limits.maxPathComponents !== Infinity)
+            validatePath(dirPrefix + name, this.ledger.limits);
         const cache = this._cache;
         if (!append &&
             dirPrefix === cache.lastFastDirPrefix &&
@@ -1838,12 +1853,11 @@ export class MemoryFileSystem {
                 node.allocation = DUMMY_POOL_ALLOCATION;
                 node.sourceRef = node.data.subarray(0);
                 const entryIdx = entries._next++;
-                entries._table[lastFastMapMiss.slot] = entryIdx;
+                entries._table[entries._missSlot] = entryIdx;
                 entries._keys[entryIdx] = name;
                 entries._vals[entryIdx] = node;
                 entries.size++;
-                lastFastMapMiss.map = undefined;
-                lastFastMapMiss.key = "";
+                entries._missKey = "";
                 this.ledger.reserve(name.length * 2, 2, "writeFile", name);
                 this.totalBytes += length;
                 this.mutationTick = (this.mutationTick + 1) | 0;
@@ -1864,8 +1878,8 @@ export class MemoryFileSystem {
                 cache.lastFastFileNode.nlink !== 0 &&
                 cache.lastFastDirNode !== undefined &&
                 cache.lastFastDirNode.nlink !== 0 &&
-                (cache.lastFastDirNode.mode & 1) !== 0 &&
-                (cache.lastFastFileNode.mode & 2) !== 0) {
+                (cache.lastFastDirNode.mode & 0o100) !== 0 &&
+                (cache.lastFastFileNode.mode & 0o200) !== 0) {
                 const current = cache.lastFastFileNode;
                 const length = current.byteLength + data.byteLength;
                 this.admitSize(current, length, syscall, name);
@@ -1878,7 +1892,7 @@ export class MemoryFileSystem {
             const cachedDir = cache.lastFastDirNode;
             if (cachedDir !== undefined &&
                 cachedDir.nlink !== 0 &&
-                (cachedDir.mode & 1) !== 0 &&
+                (cachedDir.mode & 0o100) !== 0 &&
                 dirPrefix === cache.lastFastDirPrefix) {
                 parent = cachedDir;
                 if (exceedsComponentByteLimit(name))
@@ -1905,7 +1919,7 @@ export class MemoryFileSystem {
                 this.permission(parent, 1, syscall, name);
                 if (exceedsComponentByteLimit(name))
                     this.fail("ENAMETOOLONG", syscall, name);
-                if (dirPrefix.length > 1 && (parent.mode & 1) !== 0) {
+                if (dirPrefix.length > 1 && (parent.mode & 0o100) !== 0) {
                     cache.lastFastDirPrefix = dirPrefix;
                     cache.lastFastDirNode = parent;
                 }
@@ -1984,12 +1998,8 @@ export class MemoryFileSystem {
                         cache.lastFastFilePath = "";
                         cache.lastFastFileName = name;
                         cache.lastFastFileNode = node;
-                        lastFastMapMiss.map = undefined;
-                        lastFastMapMiss.key = "";
                     }
                     catch (error) {
-                        lastFastMapMiss.map = undefined;
-                        lastFastMapMiss.key = "";
                         this.ledger.release(nameBytes, 2);
                         throw error;
                     }
@@ -3175,6 +3185,7 @@ export function tryOpenMemoryRedirectHandleSync(filesystem, path, append, mode,
         return undefined;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     const validMode = (mode & 0o777) === mode
         ? mode
         : mem.mode(mode, 0o666, "open", path);
@@ -3276,14 +3287,13 @@ export function tryOpenMemoryRedirectHandleSync(filesystem, path, append, mode,
         }
         const prevNlink = parent.cachedNlinkRev === parent.revision ? parent.cachedNlink : (parent.entries.size === 0 ? 2 : undefined);
         const entries = parent.entries;
-        if (lastFastMapMiss.map === entries && lastFastMapMiss.key === name && entries._next < entries._keys.length) {
+        if (entries._missKey === name && entries._next < entries._keys.length) {
             const entryIdx = entries._next++;
-            entries._table[lastFastMapMiss.slot] = entryIdx;
+            entries._table[entries._missSlot] = entryIdx;
             entries._keys[entryIdx] = name;
             entries._vals[entryIdx] = newNode;
             entries.size++;
-            lastFastMapMiss.map = undefined;
-            lastFastMapMiss.key = "";
+            entries._missKey = "";
         }
         else {
             entries.set(name, newNode);
@@ -3359,6 +3369,7 @@ export function tryResolveMemoryDevicePath(filesystem, path, resizeCreate) {
     const mem = filesystem;
     if (!ownedStores.has(mem) || mem.symlinkCount !== 0 || !isStockMemoryMethods(mem, deviceFastMethodNames, false))
         return undefined;
+    validatePath(path, ownedStores.get(mem).ledger.limits);
     if (!isCleanAbsolutePath(path) || path === "/dev" || path.startsWith("/dev/"))
         return undefined;
     let current = mem.root;
@@ -3440,7 +3451,7 @@ function isStockMemoryMethods(mem, names, checkRootAccessor = true) {
 let lastReadViewData;
 let lastReadViewSourceRef;
 export function getLastReadMemoryFileSourceRef(view) {
-    const ref = view === lastReadViewData ? lastReadViewSourceRef : undefined;
+    const ref = view === lastReadViewData?.deref() ? lastReadViewSourceRef?.deref() : undefined;
     lastReadViewData = undefined;
     lastReadViewSourceRef = undefined;
     return ref;
@@ -3462,8 +3473,8 @@ export function tryReadMemoryFileViewSync(filesystem, path, maxBytes, signal, ca
     else if ((++fastWriteNowTick & 63) === 0)
         node.atimeMs = fastWriteCachedNow = Date.now();
     if (captureSourceRef && node.revision === 0) {
-        lastReadViewData = data;
-        lastReadViewSourceRef = node.sourceRef;
+        lastReadViewData = new WeakRef(data);
+        lastReadViewSourceRef = node.sourceRef === undefined ? undefined : new WeakRef(node.sourceRef);
     }
     return data;
 }
@@ -3540,6 +3551,7 @@ export function tryGetMemoryDirectoryEntryNamesSync(filesystem, path) {
     const owner = ownedStores.get(mem);
     if (!owner || mem.symlinkCount !== 0 || !isStockMemoryMethods(mem, readFileFastMethodNames, false))
         return undefined;
+    validatePath(path, owner.ledger.limits);
     const root = mem.root;
     if (path === "/") {
         if (((root.mode >> 6) & 4) !== 4)
@@ -3606,6 +3618,7 @@ export function tryMkdirMemorySync(filesystem, path, recursive, mode, signal, di
         return false;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     const validMode = mem.mode(mode, 0o777, "mkdir", path);
     if (recursive) {
         let current = owner.root;
@@ -3657,6 +3670,7 @@ export function tryRmRfMemorySync(filesystem, path, signal) {
         return false;
     }
     signal?.throwIfAborted();
+    validatePath(path, owner.ledger.limits);
     let current = owner.root;
     let start = 1;
     let targetNode;

package/dist/safe-fs/fs/memory/limits.d.ts

@@ -1,9 +1,13 @@
 export interface MemoryFileSystemLimits {
     readonly maxBytes?: number;
+    readonly maxPathBytes: number;
+    readonly maxPathComponents: number;
     readonly maxFileBytes: number;
     readonly maxRetainedBytes: number;
     readonly maxMetadataUnits: number;
 }
-export type MemoryFileSystemOptions = Partial<MemoryFileSystemLimits>;
+export type MemoryFileSystemOptions = {
+    readonly [Key in keyof MemoryFileSystemLimits]?: MemoryFileSystemLimits[Key] | undefined;
+};
 export declare const defaultMemoryFileSystemLimits: Readonly<MemoryFileSystemLimits>;
 export declare function normalizeMemoryFileSystemLimits(options: unknown): Readonly<MemoryFileSystemLimits>;

package/dist/safe-fs/fs/memory/limits.js

@@ -1,25 +1,21 @@
 import { readConfigRecord } from "../../config.js";
 export const defaultMemoryFileSystemLimits = Object.freeze({
+    maxPathBytes: Infinity,
+    maxPathComponents: Infinity,
     maxFileBytes: Infinity,
     maxRetainedBytes: Infinity,
     maxMetadataUnits: Infinity,
 });
 export function normalizeMemoryFileSystemLimits(options) {
-    const keys = ["maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
+    const keys = ["maxPathBytes", "maxPathComponents", "maxFileBytes", "maxRetainedBytes", "maxMetadataUnits"];
     const record = readConfigRecord(options, "memory option", [...keys, "maxBytes"]);
     const limits = { ...defaultMemoryFileSystemLimits };
-    if (Object.hasOwn(record, "maxBytes") && record.maxBytes !== undefined) {
-        if (typeof record.maxBytes !== "number" || !Number.isSafeInteger(record.maxBytes) || record.maxBytes < 0) {
-            throw new RangeError("maxBytes must be a nonnegative safe integer");
-        }
-        limits.maxBytes = record.maxBytes;
-    }
-    for (const key of keys) {
-        if (!Object.hasOwn(record, key))
-            continue;
+    for (const key of [...keys, "maxBytes"]) {
         const value = record[key];
+        if (value === undefined || value === Infinity)
+            continue;
         if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (key === "maxMetadataUnits" ? 1 : 0)) {
-            throw new RangeError(`${key} must be a ${key === "maxMetadataUnits" ? "positive" : "nonnegative"} safe integer`);
+            throw new RangeError(`${key} must be a ${key === "maxMetadataUnits" ? "positive" : "nonnegative"} safe integer or Infinity`);
         }
         limits[key] = value;
     }

package/dist/safe-fs/fs/memory/missing-target.d.ts

@@ -1,3 +1,4 @@
+import { type PathLimits } from "../../contracts/virtual-path.js";
 type Node = {
     type: "file";
     mode: number;
@@ -10,5 +11,5 @@ type Node = {
     mode: number;
     entries: ReadonlyMap<string, Node>;
 };
-export declare function resolveMissingTarget(root: Node, path: string, signal?: AbortSignal): string;
+export declare function resolveMissingTarget(root: Node, path: string, signal?: AbortSignal, limits?: PathLimits): string;
 export {};

package/dist/safe-fs/fs/memory/missing-target.js

@@ -1,3 +1,4 @@
+import { pathByteLength, validatePath } from "../../contracts/virtual-path.js";
 import { FsError } from "../../contracts/errors.js";
 function utf8ByteLength(value) {
     let bytes = 0;
@@ -32,11 +33,14 @@ function components(path, signal) {
     }
     return result;
 }
-export function resolveMissingTarget(root, path, signal) {
+export function resolveMissingTarget(root, path, signal, limits = {}) {
+    validatePath(path, limits);
     const fail = (code, failedPath = path) => {
         throw new FsError(code, { syscall: "realpath", path: failedPath });
     };
     const origin = components(path, signal);
+    let remainingBytes = (limits.maxPathBytes ?? Infinity) - pathByteLength(path);
+    let remainingComponents = (limits.maxPathComponents ?? Infinity) - origin.length;
     const initial = { node: root, name: "" };
     let position = initial;
     let links = 0;
@@ -89,7 +93,10 @@ export function resolveMissingTarget(root, path, signal) {
             if (node.type === "symlink") {
                 if (++links > 40)
                     return fail("ELOOP");
+                validatePath(node.target, { maxPathBytes: remainingBytes, maxPathComponents: remainingComponents });
                 const names = components(node.target, signal);
+                remainingBytes -= pathByteLength(node.target);
+                remainingComponents -= names.length;
                 if (node.target.endsWith("/"))
                     names.push({ name: ".", start: node.target.length });
                 if (node.target.startsWith("/"))

package/dist/safe-fs/fs/overlay/index.d.ts

@@ -1,6 +1,6 @@
 import type { ByteSource } from "../../contracts/io.js";
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
+import type { ConditionalWriteFileOptions, ConditionalRemoveFileOptions, PrepareDirectoryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, StagedFileContent, AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, OpenReadFileOptions, FileReadHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, ChmodOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/filesystem.js";
 export interface OverlayFileSystemOptions {
     readonly upper: FileSystem;
     readonly lower: FileSystem;
@@ -56,6 +56,9 @@ export declare class OverlayFileSystem implements FileSystem {
     private replace;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;
     writeFile(path: string, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     appendFile(path: string, data: Uint8Array, options?: AppendFileOptions): Promise<void>;
     stat(path: string, options?: FsOptions): Promise<FileStat>;
     lstat(path: string, options?: FsOptions): Promise<FileStat>;

package/dist/safe-fs/fs/overlay/index.js

@@ -126,13 +126,13 @@ export class OverlayFileSystem {
             ...semantics,
             open: false,
             conditionalChmod: this.publication.supported(),
-            atomicFilePublication: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+            atomicFilePublication: false, atomicFileMutation: this.publication.supported(), atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), retainedStagingCleanup: this.publication.supported(), atomicDirectoryMetadata: this.publication.supported(), trustedOwnedStaging: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
             ...(upper.readOnly === undefined ? {} : { readOnly: upper.readOnly }),
             ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
-            atomicRename: false, atomicRenameNoReplace: false,
+            atomicRename: this.publication.supported(), atomicRenameNoReplace: this.publication.supported(),
             descriptorWriteStream: false,
             retainedResize: false, atomicResize: false,
             hardlinks: false,
@@ -148,7 +148,7 @@ export class OverlayFileSystem {
         Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
     }
     confineExtraction(roots, options = {}) {
-        return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this), false);
+        return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this, this.maxBufferBytes), false);
     }
     createStagedFile(directory, name, content, options) {
         return this.run(options, async () => {
@@ -715,11 +715,38 @@ export class OverlayFileSystem {
             const append = options.flag === "a" || options.flag === "ax";
             if (append && (location.entry?.stat.size ?? 0) + bytes.byteLength > this.maxBufferBytes)
                 fail("EFBIG", path);
-            await this.replace(location, options, async (temporary) => {
-                await this.#upper.writeFile(temporary, bytes, { ...options, flag: append ? "a" : "w" });
-            });
+            if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                const parent = await this.required(dirname(location.path), options);
+                await this.publication.writeFile(location.path, bytes, {
+                    ...options, parent: this.publication.stat(parent.path, parent.stat),
+                    expected: this.publication.stat(location.path, location.entry.stat), append,
+                }, this.maxBufferBytes);
+            }
+            else {
+                await this.replace(location, options, async (temporary) => {
+                    await this.#upper.writeFile(temporary, bytes, { ...options, flag: append ? "a" : "w" });
+                });
+            }
         });
     }
+    prepareDirectory(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.prepareDirectory(path, captured), false);
+    }
+    async writeFileConditional(path, data, options) {
+        options.signal?.throwIfAborted();
+        if (!(data instanceof Uint8Array))
+            throw new TypeError("Overlay files require Uint8Array data");
+        const bytes = new Uint8Array(data);
+        if (bytes.byteLength > this.maxBufferBytes)
+            fail("EFBIG", path);
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.writeFile(path, bytes, captured, this.maxBufferBytes), false);
+    }
+    removeFileConditional(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.removeFile(path, captured), false);
+    }
     async appendFile(path, data, options = {}) {
         return this.writeFile(path, data, { ...options, flag: "a" });
     }
@@ -866,11 +893,13 @@ export class OverlayFileSystem {
     }
     async rename(source, destination, options = {}) {
         return this.run(options, async () => {
-            if (options.noReplace)
+            if (options.noReplace && !this.publication.supported())
                 fail("ENOTSUP", source, "atomic no-replace rename is unsupported");
             this.writable(source);
             const original = await this.required(source, options, false);
             const target = await this.resolve(destination, options, false, true);
+            if (options.noReplace && target.entry)
+                fail("EEXIST", destination);
             if (original.path === target.path)
                 return;
             if (original.path === "/" || target.path === "/")
@@ -885,6 +914,7 @@ export class OverlayFileSystem {
                 if (target.entry.stat.type === "directory" && (await this.listing(target.entry, options)).length)
                     fail("ENOTEMPTY", destination);
             }
+            const guard = this.capabilities.atomicRename ? this.publication.prepareRename(original.path, target.path) : undefined;
             await this.parent(original.path, options);
             await this.parent(target.path, options);
             await this.materialize(original, options);
@@ -902,7 +932,10 @@ export class OverlayFileSystem {
                 movedOrigins.push([destination, { ...origin, moves }]);
             }
             options.signal?.throwIfAborted();
-            await this.#upper.rename(original.path, target.path, options);
+            if (this.capabilities.atomicRename)
+                await this.publication.rename(original.path, target.path, options, guard);
+            else
+                await this.#upper.rename(original.path, target.path, options);
             this.whiteouts.add(original.path);
             if (original.stat.type === "directory")
                 this.opaque.add(target.path);
@@ -998,6 +1031,9 @@ export class OverlayFileSystem {
                 await this.copyUp(entry, options);
                 await operation(entry.path);
             }
+            else if (this.publication.supported() && entry.backend === this.#upper) {
+                await operation(entry.path);
+            }
             else
                 await this.replace({ path: entry.path, entry }, options, operation);
         });
@@ -1123,9 +1159,19 @@ export class OverlayFileSystem {
                     const append = options.flag === "a" || options.flag === "ax";
                     if (append && (location.entry?.stat.size ?? 0) + size > this.maxBufferBytes)
                         fail("EFBIG", path);
-                    await this.replace(location, options, async (temporary) => {
-                        await this.streamToUpper(temporary, this.#upper.readStream(incoming, options), { ...options, flag: append ? "a" : "w" });
-                    }, true);
+                    if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                        const bytes = await this.#upper.readFile(incoming, options);
+                        const parent = await this.required(dirname(location.path), options);
+                        await this.publication.writeFile(location.path, bytes, {
+                            ...options, parent: this.publication.stat(parent.path, parent.stat),
+                            expected: this.publication.stat(location.path, location.entry.stat), append,
+                        }, this.maxBufferBytes);
+                    }
+                    else {
+                        await this.replace(location, options, async (temporary) => {
+                            await this.streamToUpper(temporary, this.#upper.readStream(incoming, options), { ...options, flag: append ? "a" : "w" });
+                        }, true);
+                    }
                 });
             });
             return;

package/dist/safe-fs/fs/overlay/memory-publication.d.ts

@@ -1,4 +1,4 @@
-import type { CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, ChmodOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { ConditionalWriteFileOptions, ConditionalRemoveFileOptions, RenameOptions, PrepareDirectoryOptions, CreateStagedFileOptions, FileStaging, FileStat, FileSystem, FsOptions, ChmodOptions, PublishStagedFileOptions, StagedFileContent } from "../../contracts/filesystem.js";
 /** Stock Memory mutations commit before returning their promise. No user code or
  * await is allowed between inspecting the two stores and invoking a mutation. */
 export declare class OverlayMemoryPublication {
@@ -11,6 +11,7 @@ export declare class OverlayMemoryPublication {
     private readonly directories;
     private readonly origins;
     private readonly stages;
+    private readonly stagingAncestors;
     constructor(upper: FileSystem, lower: FileSystem, whiteouts: Set<string>, opaque: Set<string>, hidden: Set<string>);
     supported(): boolean;
     private stores;
@@ -27,9 +28,15 @@ export declare class OverlayMemoryPublication {
     private capture;
     private check;
     prepareChmod(path: string, options: ChmodOptions): (() => true) | undefined;
+    prepareWrite(path: string, options: ConditionalWriteFileOptions): () => true;
+    writeFile(path: string, data: Uint8Array, options: ConditionalWriteFileOptions, maxBytes: number, guard?: () => void): Promise<FileStat>;
+    removeFile(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions, guard?: () => void): Promise<FileStat>;
+    prepareRename(source: string, destination: string): () => void;
+    rename(source: string, destination: string, options: RenameOptions, guard: () => void): Promise<void>;
     private copyParents;
-    create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    create(directory: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions, guard?: () => void): Promise<FileStaging>;
     publish(staging: FileStaging, path: string, options: PublishStagedFileOptions): Promise<void>;
-    cleanup(staging: FileStaging, options: FsOptions): Promise<void>;
-    confine(roots: readonly string[], options: FsOptions, run: <T>(options: FsOptions, operation: () => Promise<T>) => Promise<T>, fs: FileSystem): FileSystem;
+    cleanup(staging: FileStaging, options: FsOptions, retained?: boolean): Promise<void>;
+    confine(roots: readonly string[], options: FsOptions, run: <T>(options: FsOptions, operation: () => Promise<T>) => Promise<T>, fs: FileSystem, maxBytes: number): FileSystem;
 }