@poe-platform/safe-fs 0.1.727 → 0.1.729

package/dist/safe-fs/fs/capabilities.js

@@ -1,5 +1,6 @@
-import { FsError } from "../contracts/errors.js";
+import { FsError, toFsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
+import { inspectStagingBindings } from "./staging-ancestry.js";
 export function retainedReadCapabilities(filesystem, capabilities = filesystem.capabilities) {
     return typeof filesystem.openReadFile === "function" ? capabilities : { ...capabilities, retainedRead: false };
 }
@@ -104,11 +105,12 @@ export function readOnlyCapabilities(capabilities) {
         "symlinks", "streamingRead", "open", "retainedRead", "versionedDescriptors",
     ].filter(name => capabilities[name] !== undefined).map(name => [name, capabilities[name]]));
     return Object.freeze({
-        ...inspection, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        ...inspection, retainedStagingCleanup: false, readOnly: true, write: false, append: false, exclusiveCreate: false,
+        synchronousStagingResolution: false,
         mkdir: false, recursiveMkdir: false, remove: false, removeDirectory: false, recursiveRemove: false,
         rename: false, copy: false, exclusiveCopy: false, truncate: false, streamingAppend: false,
-        randomAccessWrite: false, hardlinks: false, permissions: false, timestamps: false,
-        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+        randomAccessWrite: false, hardlinks: false, permissions: false, conditionalChmod: false, timestamps: false,
+        descriptorWriteStream: false, atomicResize: false, retainedResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicTreeRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         atomicFilePublication: false, atomicRename: false, atomicRenameNoReplace: false, streamingWrite: false,
     });
 }
@@ -116,35 +118,71 @@ export function quotaCapabilities(capabilities) {
     const streamingWrite = requireCapabilities(capabilities.write, capabilities.append, !capabilities.readOnly);
     const streamingAppend = requireCapabilities(capabilities.append, !capabilities.readOnly);
     const { streamingWrite: ignoredWrite, streamingAppend: ignoredAppend, ...rest } = capabilities;
-    return Object.freeze({ ...rest, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
+    return Object.freeze({ ...rest, synchronousStagingResolution: false, retainedStagingCleanup: false, atomicStagingAncestry: false, synchronousDirectoryValidation: false, guardedStagingPublication: false, atomicFilePublication: false, descriptorWriteStream: false, atomicResize: false, atomicFileMutation: false, atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
         ...(streamingWrite === undefined ? {} : { streamingWrite }),
         ...(streamingAppend === undefined ? {} : { streamingAppend }),
     });
 }
+const TRUSTED_OWNED_STAGING_METHODS = [
+    "createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory",
+];
 export function ownedMutationCapabilities(filesystem, capabilities = filesystem.capabilities) {
-    const unavailable = {};
+    let unavailable;
     if (capabilities.atomicFilePublication === true && (capabilities.readOnly === true || typeof filesystem.publishFileConditional !== "function"))
-        unavailable.atomicFilePublication = false;
+        (unavailable ??= {}).atomicFilePublication = false;
     if (capabilities.atomicEntryRemoval === true && (capabilities.readOnly === true || typeof filesystem.removeEntryConditional !== "function"))
-        unavailable.atomicEntryRemoval = false;
+        (unavailable ??= {}).atomicEntryRemoval = false;
+    if (capabilities.atomicEntryRemovalReceipt === true && (capabilities.atomicEntryRemoval !== true || unavailable?.atomicEntryRemoval === false))
+        (unavailable ??= {}).atomicEntryRemovalReceipt = false;
     if (capabilities.atomicTreeRemoval === true && (capabilities.readOnly === true || typeof filesystem.removeTreeConditional !== "function"))
-        unavailable.atomicTreeRemoval = false;
+        (unavailable ??= {}).atomicTreeRemoval = false;
     if (capabilities.atomicFileMutation === true && (capabilities.readOnly === true || typeof filesystem.writeFileConditional !== "function" || typeof filesystem.removeFileConditional !== "function"))
-        unavailable.atomicFileMutation = false;
+        (unavailable ??= {}).atomicFileMutation = false;
     if (capabilities.atomicFileStaging === true && (capabilities.readOnly === true
         || typeof filesystem.createStagedFile !== "function" || typeof filesystem.publishStagedFile !== "function" || typeof filesystem.removeStagedFile !== "function"))
-        unavailable.atomicFileStaging = false;
+        (unavailable ??= {}).atomicFileStaging = false;
+    if (capabilities.retainedStagingCleanup === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).retainedStagingCleanup = false;
+    if (capabilities.atomicStagingAncestry === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).atomicStagingAncestry = false;
+    if (capabilities.synchronousDirectoryValidation === true && typeof filesystem.prepareDirectoryAncestry !== "function")
+        (unavailable ??= {}).synchronousDirectoryValidation = false;
+    if (capabilities.synchronousStagingResolution === true && (capabilities.readOnly === true || typeof filesystem.prepareStagingResolution !== "function"))
+        (unavailable ??= {}).synchronousStagingResolution = false;
+    if (capabilities.guardedStagingPublication === true && (capabilities.atomicFileStaging !== true || unavailable?.atomicFileStaging === false))
+        (unavailable ??= {}).guardedStagingPublication = false;
     if (capabilities.atomicDirectoryMetadata === true && (capabilities.readOnly === true || typeof filesystem.prepareDirectory !== "function"))
-        unavailable.atomicDirectoryMetadata = false;
-    if (capabilities.trustedOwnedStaging === true && (capabilities.readOnly === true
-        || ["createStagedFile", "publishStagedFile", "removeStagedFile", "writeFileConditional", "removeFileConditional", "prepareDirectory"].some(method => typeof filesystem[method] !== "function")))
-        unavailable.trustedOwnedStaging = false;
-    return Object.keys(unavailable).length ? { ...capabilities, ...unavailable } : capabilities;
+        (unavailable ??= {}).atomicDirectoryMetadata = false;
+    if (capabilities.trustedOwnedStaging === true) {
+        let missing = capabilities.readOnly === true;
+        if (!missing) {
+            for (let i = 0; i < TRUSTED_OWNED_STAGING_METHODS.length; i++) {
+                if (typeof filesystem[TRUSTED_OWNED_STAGING_METHODS[i]] !== "function") {
+                    missing = true;
+                    break;
+                }
+            }
+        }
+        if (missing)
+            (unavailable ??= {}).trustedOwnedStaging = false;
+    }
+    return unavailable ? { ...capabilities, ...unavailable } : capabilities;
 }
 export async function requireOwnedMutation(filesystem, path, capability, options, create = false) {
-    options.signal?.throwIfAborted();
-    const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, create ? { ...options, create: true } : options) ?? filesystem.capabilities);
-    options.signal?.throwIfAborted();
-    if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
-        throw new FsError("ENOTSUP", { path, syscall: capability });
+    try {
+        options.signal?.throwIfAborted();
+        const query = create ? { ...options, create: true } : options;
+        const capabilities = ownedMutationCapabilities(filesystem, await filesystem.capabilitiesFor?.(path, capability === "atomicStagingAncestry" ? { ...query, stagingAncestry: true } : query) ?? filesystem.capabilities);
+        options.signal?.throwIfAborted();
+        if (capabilities[capability] !== true && !(capabilities.trustedOwnedStaging === true && ["atomicFileStaging", "atomicFileMutation", "atomicDirectoryMetadata"].includes(capability)))
+            throw new FsError("ENOTSUP", { path, syscall: capability });
+    }
+    catch (error) {
+        options.signal?.throwIfAborted();
+        if (capability === "atomicStagingAncestry" && "ancestors" in options && options.ancestors !== undefined
+            && "destination" in options && ["ENOTSUP", "ENOENT", "ENOTDIR", "ELOOP"].includes(toFsError(error).code)) {
+            await inspectStagingBindings(entry => filesystem.lstat(entry, options), path, options);
+        }
+        throw error;
+    }
 }

package/dist/safe-fs/fs/conditional-chmod.d.ts

@@ -0,0 +1,7 @@
+import type { ChmodOptions, FileStagingEntry, FileStat } from "../contracts/filesystem.js";
+export interface ConditionalChmodOptions extends ChmodOptions {
+    readonly parent: FileStat;
+    readonly expected: FileStat;
+    readonly ancestors: readonly FileStagingEntry[];
+}
+export declare function snapshotConditionalChmod(path: string, options: ChmodOptions): ConditionalChmodOptions | undefined;

package/dist/safe-fs/fs/conditional-chmod.js

@@ -0,0 +1,19 @@
+import { FsError } from "../contracts/errors.js";
+import { dirname } from "../contracts/virtual-path.js";
+import { snapshotDirectoryAncestry } from "./staging-ancestry.js";
+export function snapshotConditionalChmod(path, options) {
+    const { signal, parent, expected, ancestors, commitGuard } = options;
+    signal?.throwIfAborted();
+    if (parent === undefined && expected === undefined && ancestors === undefined && commitGuard === undefined)
+        return undefined;
+    if (parent === undefined || expected === undefined || ancestors === undefined) {
+        throw new FsError("EINVAL", { syscall: "chmod", path, message: "complete conditional chmod receipt is required" });
+    }
+    if (commitGuard !== undefined && typeof commitGuard !== "function")
+        throw new FsError("EINVAL", { syscall: "chmod", path });
+    const entries = snapshotDirectoryAncestry(ancestors);
+    if (entries.at(-1)?.path !== dirname(path))
+        throw new FsError("EINVAL", { syscall: "chmod", path });
+    return { ...(signal === undefined ? {} : { signal }), parent: { ...parent }, expected: { ...expected }, ancestors: entries,
+        ...(commitGuard === undefined ? {} : { commitGuard }) };
+}

package/dist/safe-fs/fs/descriptor.js

@@ -45,6 +45,37 @@ function integer(value, syscall, path) {
     if (!Number.isSafeInteger(value) || value < 0)
         throw new FsError("EINVAL", { syscall, path });
 }
+const OPEN_FILE_OPTION_KEYS = new Set(["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"]);
+const managedCapabilitiesCache = new WeakMap();
+function getManagedCapabilities(capabilities, access, append) {
+    let byKey = managedCapabilitiesCache.get(capabilities);
+    const key = `${access}:${append ? 1 : 0}`;
+    if (byKey) {
+        const cached = byKey.get(key);
+        if (cached)
+            return cached;
+    }
+    else {
+        byKey = new Map();
+        managedCapabilitiesCache.set(capabilities, byKey);
+    }
+    const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && access !== "read";
+    const frozen = Object.freeze({
+        ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
+        ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
+        ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
+        ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
+        ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
+        positionedRead: capabilities.positionedRead && access !== "write",
+        positionedWrite: capabilities.positionedWrite && access !== "read" && (!append || positionedAppendWrite),
+        ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
+        ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && access !== "read" }),
+        truncate: capabilities.truncate && access !== "read",
+        synchronization: capabilities.synchronization,
+    });
+    byKey.set(key, frozen);
+    return frozen;
+}
 class ManagedFileDescriptor {
     capabilities;
     #path;
@@ -62,26 +93,13 @@ class ManagedFileDescriptor {
         const getPosition = capabilities.position === true ? backend.getPosition : undefined;
         if (capabilities.position === true && typeof getPosition !== "function")
             throw new FsError("ENOTSUP", { syscall: "getPosition", path });
-        this.#getPosition = getPosition?.bind(backend);
+        this.#getPosition = getPosition;
         const probeRead = capabilities.readObservation === true ? backend.probeRead : undefined;
         if (capabilities.readObservation === true && typeof probeRead !== "function")
             throw new FsError("ENOTSUP", { syscall: "probeRead", path });
-        this.#probeRead = probeRead?.bind(backend);
+        this.#probeRead = probeRead;
         this.#backend = backend;
-        const positionedAppendWrite = capabilities.positionedAppendWrite === true && capabilities.positionedWrite && options.access !== "read";
-        this.capabilities = Object.freeze({
-            ...(capabilities.noFollow === undefined ? {} : { noFollow: capabilities.noFollow }),
-            ...(capabilities.publication === undefined ? {} : { publication: capabilities.publication }),
-            ...(capabilities.position === undefined ? {} : { position: capabilities.position }),
-            ...(capabilities.readObservation === undefined ? {} : { readObservation: capabilities.readObservation }),
-            ...(capabilities.openTruncate === undefined ? {} : { openTruncate: capabilities.openTruncate }),
-            positionedRead: capabilities.positionedRead && options.access !== "write",
-            positionedWrite: capabilities.positionedWrite && options.access !== "read" && (!options.append || positionedAppendWrite),
-            ...(capabilities.positionedAppendWrite === undefined ? {} : { positionedAppendWrite }),
-            ...(capabilities.delegateZeroLengthWrite === undefined ? {} : { delegateZeroLengthWrite: capabilities.delegateZeroLengthWrite && options.access !== "read" }),
-            truncate: capabilities.truncate && options.access !== "read",
-            synchronization: capabilities.synchronization,
-        });
+        this.capabilities = getManagedCapabilities(capabilities, options.access, options.append);
     }
     #run(syscall, options, action) {
         const signal = options.signal;
@@ -128,7 +146,7 @@ class ManagedFileDescriptor {
         return this.#run("getPosition", options, async (backend, forwarded) => {
             if (!this.capabilities.position || !this.#getPosition)
                 throw new FsError("ENOTSUP", { syscall: "getPosition", path: this.#path });
-            const position = await this.#getPosition(backend.resource, forwarded);
+            const position = await this.#getPosition.call(backend, backend.resource, forwarded);
             if (!Number.isSafeInteger(position) || position < 0)
                 throw new FsError("EIO", { syscall: "getPosition", path: this.#path });
             return position;
@@ -138,7 +156,7 @@ class ManagedFileDescriptor {
         return this.#run("probeRead", options, async (backend, forwarded) => {
             if (!this.capabilities.readObservation || !this.#probeRead)
                 throw new FsError("ENOTSUP", { syscall: "probeRead", path: this.#path });
-            const readiness = await this.#probeRead(backend.resource, forwarded);
+            const readiness = await this.#probeRead.call(backend, backend.resource, forwarded);
             if (readiness !== "ready" && readiness !== "blocked" && readiness !== "unknown")
                 throw new FsError("EIO", { syscall: "probeRead", path: this.#path });
             return readiness;
@@ -209,11 +227,17 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         throw new FsError("EINVAL", { syscall: "open", path });
     const signal = options.signal;
     signal?.throwIfAborted();
-    const keys = ["access", "creation", "truncate", "append", "mode", "exactMode", "noFollow", "synchronization", "signal"];
     const { access, creation = "never", truncate = false, append = false, mode = 0o666, synchronization } = options;
-    if (Object.keys(options).some(key => !keys.includes(key))
-        || !["read", "write", "readwrite"].includes(access)
-        || !["never", "ifMissing", "exclusive"].includes(creation)
+    let invalidKey = false;
+    for (const key in options) {
+        if (Object.prototype.hasOwnProperty.call(options, key) && !OPEN_FILE_OPTION_KEYS.has(key)) {
+            invalidKey = true;
+            break;
+        }
+    }
+    if (invalidKey
+        || (access !== "read" && access !== "write" && access !== "readwrite")
+        || (creation !== "never" && creation !== "ifMissing" && creation !== "exclusive")
         || options.noFollow !== undefined && typeof options.noFollow !== "boolean"
         || options.exactMode !== undefined && typeof options.exactMode !== "boolean"
         || typeof truncate !== "boolean" || typeof append !== "boolean"
@@ -226,7 +250,7 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
         ...(options.noFollow === undefined ? {} : { noFollow: options.noFollow }),
         ...(options.exactMode === undefined ? {} : { exactMode: options.exactMode }),
         ...(signal === undefined ? {} : { signal }), ...(synchronization === undefined ? {} : { synchronization }) });
-    const admittedCapabilities = Object.freeze({ ...capabilities });
+    const admittedCapabilities = Object.isFrozen(capabilities) ? capabilities : Object.freeze({ ...capabilities });
     admitCapabilities(path, admitted, admittedCapabilities);
     let backend;
     try {
@@ -238,9 +262,11 @@ export async function openFileDescriptor(path, options, capabilities, acquire) {
     }
     try {
         signal?.throwIfAborted();
-        const selected = Object.freeze({ ...(backend.capabilities ?? admittedCapabilities) });
+        const rawBackendCapabilities = backend.capabilities;
+        const selected = rawBackendCapabilities ? Object.freeze({ ...rawBackendCapabilities }) : admittedCapabilities;
         signal?.throwIfAborted();
-        admitCapabilities(path, admitted, selected);
+        if (rawBackendCapabilities)
+            admitCapabilities(path, admitted, selected);
         const descriptor = new ManagedFileDescriptor(path, admitted, selected, backend);
         signal?.throwIfAborted();
         return descriptor;

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

@@ -1,5 +1,5 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
+import type { AppendFileOptions, CapabilityQueryOptions, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileResizeOperation, FileResizeOptions, FileStat, FileSystem, OpenReadFileOptions, OpenResizeFileOptions, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions, ConditionalFilePublicationOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, ConditionalRemoveEntryOptions, ConditionalRemoveEntryReceiptOptions, CreateStagedFileOptions, FileStaging, FileStagingEntry, FileStagingResolution, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent } from "../../contracts/filesystem.js";
 import type { ByteSource } from "../../contracts/io.js";
 export declare class DeviceFileSystem implements FileSystem {
     #private;
@@ -27,11 +27,16 @@ export declare class DeviceFileSystem implements FileSystem {
     rmdir(path: string, options?: FsOptions): Promise<void>;
     publishFileConditional(path: string, source: ByteSource, options: ConditionalFilePublicationOptions): Promise<FileStat>;
     writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
-    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryOptions & {
+        readonly returnRemainingStat?: false | undefined;
+    }): Promise<void>;
+    removeEntryConditional(path: string, options: ConditionalRemoveEntryReceiptOptions): Promise<void | FileStat>;
     removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
     removeTreeConditional(path: string, options: ConditionalRemoveEntryOptions): Promise<void>;
     createStagedFile(path: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
     publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    prepareDirectoryAncestry(ancestors: readonly FileStagingEntry[], options?: FsOptions): Promise<() => true>;
+    prepareStagingResolution(path: string, options?: FsOptions): Promise<FileStagingResolution>;
     removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
     prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     rename(source: string, destination: string, options?: RenameOptions): Promise<void>;