@poe-platform/safe-fs 0.1.720 → 0.1.722

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

@@ -8,9 +8,10 @@ import { compareIdentity } from "../mount/identity.js";
 import { compareEntries, registerEntryView } from "../mount/comparison.js";
 import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, opaqueIdentity, opaqueVersion, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
+    const { type, filesystemType, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, opaqueIdentity, opaqueVersion, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(filesystemType === undefined ? {} : { filesystemType }),
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
         ...(ioBlockSize === undefined ? {} : { ioBlockSize }),
         ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
@@ -80,15 +81,14 @@ export class OverlayFileSystem {
             const entry = await this.required(path, options);
             return { filesystem: entry.backend, path: entry.path, readOnly: this.capabilities.readOnly === true };
         }, false));
-        this.maxBufferBytes = options.maxBufferBytes ?? 64 * 1024 * 1024;
-        integer(this.maxBufferBytes, "/");
+        this.maxBufferBytes = options.maxBufferBytes ?? Infinity;
+        if (options.maxBufferBytes !== undefined)
+            integer(options.maxBufferBytes, "/");
         const writable = !this.#upper.capabilities.readOnly && this.#upper.capabilities.atomicRename === true;
-        const readable = [this.#upper, this.#lower].map((backend) => typeof backend.readStream === "function" ? backend.capabilities.streamingRead : false);
+        const readable = [this.#upper, this.#lower].map((backend) => retainedReadCapabilities(backend).retainedRead);
         const streamingRead = readable.every((capability) => capability === true) ? true
             : readable.every((capability) => capability === false) ? false : undefined;
-        const retained = [this.#upper, this.#lower].map((backend) => retainedReadCapabilities(backend).retainedRead);
-        const retainedRead = retained.every((capability) => capability === true) ? true
-            : retained.every((capability) => capability === false) ? false : undefined;
+        const retainedRead = streamingRead;
         const streamingWrite = writable && this.#upper.capabilities.streamingWrite === true
             && this.#upper.capabilities.streamingRead === true
             && typeof this.#upper.writeStream === "function" && typeof this.#upper.readStream === "function"
@@ -101,7 +101,7 @@ export class OverlayFileSystem {
         const effectiveStreamingWrite = requireCapabilities(streamingWrite, mutation);
         const semantics = Object.fromEntries([
             ...["read", "stat", "readdir", "realpath", "access"].map(capability => [capability,
-                requireCapabilities(upper[capability], this.#lower.capabilities[capability])]),
+                requireCapabilities(upper[capability], this.#lower.capabilities[capability], ...(capability === "read" ? readable : []))]),
             ["write", requireCapabilities(mutation, upper.write)],
             ["exclusiveCreate", requireCapabilities(mutation, upper.exclusiveCreate)],
             ["mkdir", requireCapabilities(mutation, upper.mkdir)],
@@ -120,7 +120,7 @@ export class OverlayFileSystem {
         this.capabilities = Object.freeze({
             ...semantics,
             open: false,
-            atomicFilePublication: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false,
+            atomicFilePublication: false, atomicFileMutation: false, atomicFileStaging: false, atomicDirectoryMetadata: false, trustedOwnedStaging: false,
             implicitDirectories: false,
             readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
                 : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
@@ -169,7 +169,7 @@ export class OverlayFileSystem {
     }
     capabilitiesFor(path, options = {}) {
         return this.run(options, async () => {
-            const location = await this.resolve(path, options, true, true);
+            const location = await this.resolve(path, options, options.create !== undefined || options.creation !== "exclusive", true);
             const backend = location.entry?.backend ?? this.#upper;
             const capabilities = await backend.capabilitiesFor?.(location.path, options) ?? backend.capabilities;
             options.signal?.throwIfAborted();
@@ -188,9 +188,60 @@ export class OverlayFileSystem {
                     fail("EISDIR", path);
             }
             this.permission(entry, 4);
-            return openRetainedReadFile(entry.backend, entry.path, options);
+            return this.pinRead(entry, options);
         }, false);
     }
+    async pinRead(entry, options) {
+        // A retained object, not the resolved pathname, carries read authority.
+        if (compareIdentity(entry.stat, entry.stat) !== "same")
+            fail("ENOTSUP", entry.path, "overlay reads require stable backend identity");
+        const ancestors = [];
+        let parent = dirname(entry.path);
+        while (true) {
+            const stat = await entry.backend.lstat(parent, options);
+            if (stat.type !== "directory" || compareIdentity(stat, stat) !== "same")
+                fail("ENOTSUP", entry.path, "overlay reads require stable directory ancestry");
+            ancestors.push({ backend: entry.backend, path: parent, stat });
+            if (parent === "/")
+                break;
+            parent = dirname(parent);
+        }
+        const handle = await openRetainedReadFile(entry.backend, entry.path, options);
+        try {
+            if (compareIdentity(entry.stat, await handle.stat(options)) !== "same")
+                fail("ENOTSUP", entry.path, "backend read object changed during admission");
+            for (const ancestor of ancestors) {
+                const stat = await entry.backend.lstat(ancestor.path, options);
+                if (stat.type !== "directory" || compareIdentity(ancestor.stat, stat) !== "same")
+                    fail("ENOTSUP", entry.path, "backend read ancestry changed during admission");
+            }
+            const current = await this.required(entry.path, options);
+            if (current.backend !== entry.backend || compareIdentity(entry.stat, current.stat) !== "same")
+                fail("ENOTSUP", entry.path, "overlay read layer changed during admission");
+            options.signal?.throwIfAborted();
+            return handle;
+        }
+        catch (error) {
+            await finishCleanup(() => handle.close(), true);
+            throw error;
+        }
+    }
+    async *handleBytes(handle, options) {
+        let position = options.start ?? 0;
+        const end = options.endExclusive ?? Number.MAX_SAFE_INTEGER;
+        const chunkSize = options.chunkSize ?? 64 * 1024;
+        while (position < end) {
+            const size = Math.min(chunkSize, end - position);
+            const chunk = await handle.read(position, size, options);
+            options.signal?.throwIfAborted();
+            if (!(chunk instanceof Uint8Array) || chunk.byteLength > size)
+                fail("EIO", "", "backend returned invalid retained bytes");
+            if (!chunk.byteLength)
+                break;
+            position += chunk.byteLength;
+            yield new Uint8Array(chunk);
+        }
+    }
     writable(path) {
         if (this.#upper.capabilities.readOnly)
             fail("EROFS", path);
@@ -435,13 +486,16 @@ export class OverlayFileSystem {
         const limit = Math.min(options.maxBytes ?? this.maxBufferBytes, this.maxBufferBytes);
         if (entry.stat.size > limit)
             fail("EFBIG", entry.path);
-        const result = await entry.backend.readFile(entry.path, { ...options, maxBytes: limit });
-        options.signal?.throwIfAborted();
-        if (!(result instanceof Uint8Array))
-            fail("EIO", entry.path, "backend returned non-byte data");
-        if (result.byteLength > limit)
-            fail("EFBIG", entry.path);
-        return new Uint8Array(result);
+        const handle = await this.pinRead(entry, options);
+        let failed = true;
+        try {
+            const result = await collectBytes(this.handleBytes(handle, options), { ...options, ...(limit === Infinity ? {} : { maxBytes: limit }) });
+            failed = false;
+            return result;
+        }
+        finally {
+            await finishCleanup(() => handle.close(), failed);
+        }
     }
     async cleanGarbage(strict) {
         const failures = [];
@@ -501,8 +555,16 @@ export class OverlayFileSystem {
             this.permission(entry, 4);
             if (entry.stat.size > this.maxBufferBytes)
                 fail("EFBIG", entry.path);
-            const source = this.bounded(entry.backend.readStream(entry.path, options), entry.path, options);
-            await this.streamToUpper(destination, source, { ...options, mode: 0o600, flag: "wx" });
+            const handle = await this.pinRead(entry, options);
+            let failed = true;
+            try {
+                const source = this.bounded(this.handleBytes(handle, options), entry.path, options);
+                await this.streamToUpper(destination, source, { ...options, mode: 0o600, flag: "wx" });
+                failed = false;
+            }
+            finally {
+                await finishCleanup(() => handle.close(), failed);
+            }
         }
         else
             await this.#upper.writeFile(destination, await this.bytes(entry, options), { ...options, mode: 0o600, flag: "wx" });
@@ -918,7 +980,7 @@ export class OverlayFileSystem {
                 if (this.#upper.truncate)
                     await this.#upper.truncate(temporary, length, options);
                 else {
-                    const previous = await this.#upper.readFile(temporary, { ...options, maxBytes: this.maxBufferBytes });
+                    const previous = await this.#upper.readFile(temporary, { ...options, ...(this.maxBufferBytes === Infinity ? {} : { maxBytes: this.maxBufferBytes }) });
                     const bytes = new Uint8Array(length);
                     bytes.set(previous.subarray(0, length));
                     await this.#upper.writeFile(temporary, bytes, options);
@@ -939,27 +1001,21 @@ export class OverlayFileSystem {
             if (options.endExclusive < start)
                 fail("EINVAL", path);
         }
-        const entry = await this.run(options, async () => {
+        const handle = await this.run(options, async () => {
             const entry = await this.required(path, options);
             if (entry.stat.type !== "file")
                 fail("EISDIR", path);
             this.permission(entry, 4);
-            return entry;
+            return this.pinRead(entry, options);
         });
-        if (entry.backend.readStream && entry.backend.capabilities.streamingRead !== false) {
-            for await (const chunk of readBytes(entry.backend.readStream(entry.path, options), options.signal)) {
-                yield new Uint8Array(chunk);
-            }
-            options.signal?.throwIfAborted();
-            return;
+        let failed = true;
+        try {
+            yield* readBytes(this.handleBytes(handle, options), options.signal);
+            failed = false;
         }
-        const bytes = await this.bytes(entry, options);
-        const end = Math.min(bytes.byteLength, options.endExclusive ?? bytes.byteLength);
-        for (let offset = start; offset < end; offset += chunkSize) {
-            options.signal?.throwIfAborted();
-            yield bytes.slice(offset, Math.min(end, offset + chunkSize));
+        finally {
+            await finishCleanup(() => handle.close(), failed);
         }
-        options.signal?.throwIfAborted();
     }
     async *bounded(source, path, options) {
         let size = 0;
@@ -1007,7 +1063,7 @@ export class OverlayFileSystem {
             });
             return;
         }
-        const bytes = await collectBytes(source, { maxBytes: this.maxBufferBytes, ...(options.signal ? { signal: options.signal } : {}) });
+        const bytes = await collectBytes(source, { ...(this.maxBufferBytes === Infinity ? {} : { maxBytes: this.maxBufferBytes }), ...(options.signal ? { signal: options.signal } : {}) });
         await this.writeFile(path, bytes, options);
     }
 }

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

@@ -40,7 +40,7 @@ async function scanUsedBytes(fs, limits, options, change, retained = change?.ret
         if (!directory)
             break;
         const signal = options?.signal;
-        const listing = fs.readdir(directory.path, { ...options, ...(signal ? { signal } : {}), maxEntries: remaining });
+        const listing = fs.readdir(directory.path, { ...options, ...(signal ? { signal } : {}), ...(remaining === Infinity ? {} : { maxEntries: remaining }) });
         const entries = await (retained ? namespaceMetadata(listing, signal) : listing);
         options?.signal?.throwIfAborted();
         const count = entries.length;
@@ -136,11 +136,11 @@ export function withFileSystemQuota(fs, options) {
     if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0)
         throw new RangeError("maxBytes must be a nonnegative safe integer");
     const scanLimits = {
-        maxScanEntries: options.maxScanEntries === undefined ? 4096 : options.maxScanEntries,
-        maxScanDepth: options.maxScanDepth === undefined ? 64 : options.maxScanDepth,
+        maxScanEntries: options.maxScanEntries ?? Infinity,
+        maxScanDepth: options.maxScanDepth ?? Infinity,
     };
-    for (const [name, value] of Object.entries(scanLimits)) {
-        if (!Number.isSafeInteger(value) || value < 0)
+    for (const [name, value] of Object.entries({ maxScanEntries: options.maxScanEntries, maxScanDepth: options.maxScanDepth })) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
             throw new RangeError(`${name} must be a nonnegative safe integer`);
     }
     let queue = Promise.resolve();
@@ -189,11 +189,11 @@ export function withFileSystemQuota(fs, options) {
     const mutations = {
         open(path, openOptions) {
             return openFileDescriptor(path, openOptions, {
-                positionedRead: true, positionedWrite: true, truncate: true, synchronization: "storage",
+                noFollow: true, positionedRead: true, positionedWrite: true, truncate: true, synchronization: "storage",
             }, admitted => mutate(async () => {
                 admitted.signal?.throwIfAborted();
                 const open = fs.open;
-                const capabilities = admitted.creation === "exclusive" ? fs.capabilities : await fs.capabilitiesFor?.(path, admitted) ?? fs.capabilities;
+                const capabilities = admitted.noFollow || admitted.creation === "exclusive" ? fs.capabilities : await fs.capabilitiesFor?.(path, admitted) ?? fs.capabilities;
                 admitted.signal?.throwIfAborted();
                 if (!open || capabilities.open === false)
                     throw new FsError("ENOTSUP", { syscall: "open", path });
@@ -389,15 +389,17 @@ export function withFileSystemQuota(fs, options) {
                 await fs.appendFile(path, data, appendOptions);
             });
         },
-        async rename(source, destination, renameOptions) {
-            if (renameOptions?.noReplace) {
-                renameOptions.signal?.throwIfAborted();
-                const capabilities = await fs.capabilitiesFor?.(destination, renameOptions) ?? fs.capabilities;
-                renameOptions?.signal?.throwIfAborted();
-                if (capabilities.atomicRenameNoReplace !== true)
-                    throw new FsError("ENOTSUP", { syscall: "rename", path: source, dest: destination });
-            }
-            await fs.rename(source, destination, renameOptions);
+        rename(source, destination, renameOptions) {
+            return mutate(async () => {
+                if (renameOptions?.noReplace) {
+                    renameOptions.signal?.throwIfAborted();
+                    const capabilities = await fs.capabilitiesFor?.(destination, renameOptions) ?? fs.capabilities;
+                    renameOptions.signal?.throwIfAborted();
+                    if (capabilities.atomicRenameNoReplace !== true)
+                        throw new FsError("ENOTSUP", { syscall: "rename", path: source, dest: destination });
+                }
+                await fs.rename(source, destination, renameOptions);
+            });
         },
         copyFile(source, destination, copyOptions) {
             return mutate(async () => {

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

@@ -11,9 +11,10 @@ function readOnly(syscall, path, dest) {
     throw new FsError("EROFS", { syscall, path, ...(dest === undefined ? {} : { dest }) });
 }
 function snapshotStat(stat) {
-    const { type, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, opaqueIdentity, opaqueVersion, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
+    const { type, filesystemType, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, opaqueIdentity, opaqueVersion, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
     return {
         type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(filesystemType === undefined ? {} : { filesystemType }),
         ...(revision === undefined ? {} : { revision }),
         ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
         ...(ioBlockSize === undefined ? {} : { ioBlockSize }),
@@ -72,9 +73,10 @@ export class ReadOnlyFileSystem {
             || options.creation === "ifMissing" || options.creation === "exclusive"))
             readOnly("open", path);
         return openFileDescriptor(path, options, {
-            positionedRead: true, positionedWrite: false, truncate: false, synchronization: "none",
+            noFollow: true, positionedRead: true, positionedWrite: false, truncate: false, synchronization: "none",
         }, async (admitted) => {
-            const capabilities = await this.#filesystem.capabilitiesFor?.(path, admitted) ?? this.#filesystem.capabilities;
+            const capabilities = admitted.noFollow ? this.#filesystem.capabilities
+                : await this.#filesystem.capabilitiesFor?.(path, admitted) ?? this.#filesystem.capabilities;
             if (!this.#filesystem.open || capabilities.open === false)
                 throw new FsError("ENOTSUP", { syscall: "open", path });
             admitted.signal?.throwIfAborted();

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

@@ -1,8 +1,16 @@
 import type { FileDescriptor, OpenFileOptions } from "../../contracts/descriptor.js";
-import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, OpenReadFileOptions, OpenResizeFileOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
+import type { AppendFileOptions, ByteSource, CopyFileOptions, DirectoryEntry, FileReadHandle, FileResizeHandle, FileStat, FileSystem, FileSystemCapabilities, FsOptions, RenameOptions, MkdirOptions, ConditionalWriteFileOptions, ConditionalRemoveFileOptions, CreateStagedFileOptions, FileStaging, PublishStagedFileOptions, PrepareDirectoryOptions, StagedFileContent, OpenReadFileOptions, OpenResizeFileOptions, ReadDirectoryOptions, ReadFileOptions, ReadStreamOptions, RemoveOptions, WriteFileOptions } from "../../contracts/index.js";
 export interface RealFileSystemOptions {
     /** An existing, absolute host directory. It is never created implicitly. */
     readonly root: string;
+    /**
+     * Trusted host primitive for an atomic no-replace move (e.g. renameat2 with
+     * RENAME_NOREPLACE). Receives resolved absolute host paths. Must reject EEXIST
+     * for any existing entry, including dangling symlinks, without mutation.
+     * Never implement with an existence check, ordinary rename, or copy/delete.
+     * Unsupported filesystems must reject ENOTSUP; cross-device moves reject EXDEV.
+     */
+    readonly renameNoReplace?: (source: string, destination: string, options: FsOptions) => Promise<void>;
 }
 /**
  * Async byte filesystem for trusted POSIX hosts (Windows is unsupported).
@@ -42,6 +50,7 @@ export interface RealFileSystemOptions {
 export declare class RealFileSystem implements FileSystem {
     readonly capabilities: FileSystemCapabilities;
     private readonly configuredRoot;
+    private readonly renameNoReplace;
     private rootPromise;
     constructor(options: RealFileSystemOptions | string);
     private root;
@@ -50,6 +59,17 @@ export declare class RealFileSystem implements FileSystem {
     private path;
     private operation;
     private protectRoot;
+    private stagingSnapshot;
+    private expectStaging;
+    private stagingMetadata;
+    createStagedFile(directoryPath: string, name: string, content: StagedFileContent, options: CreateStagedFileOptions): Promise<FileStaging>;
+    private stagingPaths;
+    private checkStaging;
+    publishStagedFile(staging: FileStaging, destination: string, options: PublishStagedFileOptions): Promise<void>;
+    removeStagedFile(staging: FileStaging, options?: FsOptions): Promise<void>;
+    writeFileConditional(path: string, data: Uint8Array, options: ConditionalWriteFileOptions): Promise<FileStat>;
+    removeFileConditional(path: string, options: ConditionalRemoveFileOptions): Promise<void>;
+    prepareDirectory(path: string, options: PrepareDirectoryOptions): Promise<FileStat>;
     open(path: string, options: OpenFileOptions): Promise<FileDescriptor>;
     private protectTerminal;
     readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array>;