@poe-platform/safe-fs 0.1.799 → 0.1.801

package/dist/safe-fs/fs/overlay/memory-publication.js

@@ -3,7 +3,10 @@ import { dirname, isPathWithin, validatePath } from "../../contracts/virtual-pat
 import { memoryAtomicView } from "../memory/atomic-view.js";
 import { compareIdentity } from "../mount/identity.js";
 import { snapshotConditionalChmod } from "../conditional-chmod.js";
+import { createStagingCleanup } from "../staging-cleanup.js";
 import { runStagingGuard } from "../staging-ancestry.js";
+// Enumerable ownership tokens survive caller snapshots without retaining stats forever.
+const overlayReceipt = Symbol("overlay observation");
 /** 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 class OverlayMemoryPublication {
@@ -16,6 +19,7 @@ export class OverlayMemoryPublication {
     directories = new Map();
     origins = new Map();
     stages = new WeakMap();
+    stagingAncestors = new WeakMap();
     constructor(upper, lower, whiteouts, opaque, hidden) {
         this.upper = upper;
         this.lower = lower;
@@ -75,7 +79,7 @@ export class OverlayMemoryPublication {
         const observation = this.observation(path);
         if (!this.same(physical, this.visible(observation), physical.type === "file"))
             throw new FsError("EAGAIN", { path });
-        let logical = physical;
+        let logical = { ...physical };
         if (physical.type === "directory") {
             let directory = this.directories.get(path);
             if (!directory || !this.same(directory.upper, observation.upper) || !this.same(directory.lower, observation.lower)) {
@@ -84,7 +88,9 @@ export class OverlayMemoryPublication {
             }
             logical = { ...physical, identityScope: directory.identityScope, dev: directory.dev, ino: directory.ino };
         }
-        this.receipts.set(logical, observation);
+        const token = {};
+        logical[overlayReceipt] = token;
+        this.receipts.set(token, observation);
         return logical;
     }
     same(actual, expected, unchanged = false) {
@@ -94,7 +100,7 @@ export class OverlayMemoryPublication {
             && (!unchanged || ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].every(key => actual[key] === expected[key]));
     }
     expect(path, expected, unchanged = false) {
-        const receipt = this.receipts.get(expected);
+        const receipt = this.receipts.get(expected[overlayReceipt] ?? expected);
         if (!receipt || receipt.path !== path)
             throw new FsError("ENOTSUP", { path, message: "unowned overlay publication receipt" });
         const actual = this.observation(path);
@@ -153,7 +159,7 @@ export class OverlayMemoryPublication {
         this.stores();
         this.path(path);
         const retain = (source, snapshot) => {
-            const receipt = this.receipts.get(source);
+            const receipt = this.receipts.get(source[overlayReceipt] ?? source);
             if (!receipt)
                 throw new FsError("ENOTSUP", { path, message: "unowned overlay chmod receipt" });
             this.receipts.set(snapshot, receipt);
@@ -175,6 +181,164 @@ export class OverlayMemoryPublication {
             return true;
         };
     }
+    prepareWrite(path, options) {
+        this.stores();
+        this.path(path);
+        const ancestors = this.capture(path);
+        return () => {
+            options.signal?.throwIfAborted();
+            this.stores();
+            this.check(ancestors);
+            this.expect(dirname(path), options.parent);
+            const current = this.inspect(path);
+            if (options.expected === null) {
+                if (current)
+                    throw new FsError("EAGAIN", { path });
+            }
+            else {
+                this.expect(path, options.expected, true);
+                if (current?.type !== "file")
+                    throw new FsError("EINVAL", { path });
+            }
+            return true;
+        };
+    }
+    async writeFile(path, data, options, maxBytes, guard) {
+        const check = this.prepareWrite(path, options);
+        check();
+        const current = this.inspect(path);
+        if (current && ((current.mode >> 6) & 2) !== 2)
+            throw new FsError("EACCES", { path });
+        if (current && !this.observation(path).upper && current.nlink !== 1)
+            throw new FsError("ENOTSUP", { path, message: "ambiguous hardlink copy-up" });
+        const controls = options.signal ? { signal: options.signal } : {};
+        let bytes = data;
+        if (options.append && current && !this.observation(path).upper) {
+            const previous = await this.lower.readFile(path, { ...controls, ...(maxBytes === Infinity ? {} : { maxBytes }) });
+            if (previous.byteLength + data.byteLength > maxBytes)
+                throw new FsError("EFBIG", { path });
+            bytes = new Uint8Array(previous.byteLength + data.byteLength);
+            bytes.set(previous);
+            bytes.set(data, previous.byteLength);
+        }
+        const ancestors = this.capture(path);
+        await this.copyParents(ancestors, controls);
+        guard?.();
+        check();
+        const upper = this.observation(path).upper;
+        if (data.byteLength + (options.append ? current?.size ?? 0 : 0) > maxBytes)
+            throw new FsError("EFBIG", { path });
+        const pending = this.upper.writeFileConditional(path, bytes, {
+            ...options, parent: this.observation(dirname(path)).upper, expected: upper ?? null,
+            append: options.append === true && upper !== undefined,
+            ...(current ? { mode: current.mode & 0o7777 } : {}),
+            ...(options.atimeMs === undefined && current ? { atimeMs: current.atimeMs } : {}),
+        });
+        // Retain the result before another caller can alter the upper store.
+        const result = this.inspect(path);
+        const receipt = result ? this.stat(path, result) : undefined;
+        await pending;
+        return receipt;
+    }
+    async removeFile(path, options) {
+        this.prepareWrite(path, options)();
+        const parent = this.inspect(dirname(path));
+        if (((parent.mode >> 6) & 3) !== 3)
+            throw new FsError("EACCES", { path });
+        const upper = this.observation(path).upper;
+        const removal = upper ? this.upper.removeFileConditional(path, {
+            ...options, parent: this.observation(dirname(path)).upper, expected: upper,
+        }) : undefined;
+        if (!upper || !this.physical(this.stores().upper, path))
+            this.whiteouts.add(path);
+        await removal;
+    }
+    async prepareDirectory(path, options, guard) {
+        const ancestors = this.capture(path);
+        const check = () => {
+            options.signal?.throwIfAborted();
+            guard?.();
+            this.check(ancestors);
+            this.expect(dirname(path), options.parent);
+            const current = this.inspect(path);
+            if (options.expected === null) {
+                if (current)
+                    throw new FsError("EAGAIN", { path });
+            }
+            else {
+                this.expect(path, options.expected);
+                if (current?.type !== "directory")
+                    throw new FsError("ENOTDIR", { path });
+            }
+        };
+        check();
+        const current = this.inspect(path);
+        await this.copyParents(current ? [...ancestors, { path, stat: options.expected }] : ancestors, options);
+        check();
+        const pending = this.upper.prepareDirectory(path, {
+            ...options, parent: this.observation(dirname(path)).upper, expected: this.observation(path).upper ?? null,
+        });
+        const physical = this.inspect(path);
+        if (physical && options.expected === null)
+            this.opaque.add(path);
+        const receipt = physical ? this.stat(path, physical) : undefined;
+        await pending;
+        return receipt;
+    }
+    prepareRename(source, destination) {
+        const ancestors = [...this.capture(source), ...this.capture(destination)];
+        const target = this.observation(destination);
+        const entries = [];
+        const pending = [source];
+        const stores = this.stores();
+        while (pending.length) {
+            const path = pending.pop();
+            const entry = this.observation(path);
+            const visible = this.visible(entry);
+            if (!visible)
+                continue;
+            entries.push(entry);
+            if (visible.type !== "directory")
+                continue;
+            const names = new Set([
+                ...(entry.upper?.type === "directory" ? stores.upper.names(path) : []),
+                ...(entry.lower?.type === "directory" && !this.opaque.has(path) ? stores.lower.names(path) : []),
+            ]);
+            for (const name of names)
+                pending.push(`${path}/${name}`);
+        }
+        return () => {
+            this.stores();
+            this.check(ancestors);
+            const current = this.observation(destination);
+            if (!this.same(current.upper, target.upper, true) || !this.same(current.lower, target.lower, true)) {
+                throw new FsError("EAGAIN", { path: destination });
+            }
+            for (const entry of entries) {
+                const actual = this.observation(entry.path);
+                // Copy-up may add upper entries; it never changes the lower store.
+                if (!this.same(actual.lower, entry.lower, true)
+                    || (entry.upper && !this.same(actual.upper, entry.upper, entry.upper.type !== "directory"))) {
+                    throw new FsError("EAGAIN", { path: entry.path });
+                }
+            }
+        };
+    }
+    async rename(source, destination, options, guard) {
+        options.signal?.throwIfAborted();
+        this.stores();
+        const current = this.inspect(destination);
+        if (options.noReplace && current)
+            throw new FsError("EEXIST", { path: destination });
+        guard();
+        if (!this.observation(source).upper)
+            throw new FsError("ENOENT", { path: source });
+        const moved = this.upper.rename(source, destination, options);
+        // Stock Memory commits synchronously; publish the whiteout in that same turn.
+        if (!this.physical(this.stores().upper, source))
+            this.whiteouts.add(source);
+        await moved;
+    }
     async copyParents(entries, options) {
         for (const entry of entries) {
             options.signal?.throwIfAborted();
@@ -189,7 +353,7 @@ export class OverlayMemoryPublication {
             await pending;
         }
     }
-    async create(directory, name, content, options) {
+    async create(directory, name, content, options, guard) {
         options.signal?.throwIfAborted();
         this.path(directory);
         this.expect(dirname(directory), options.parent);
@@ -198,24 +362,30 @@ export class OverlayMemoryPublication {
         const ancestors = this.capture(directory);
         await this.copyParents(ancestors, options);
         options.signal?.throwIfAborted();
+        guard?.();
         this.check(ancestors);
         this.expect(dirname(directory), options.parent);
         if (this.inspect(directory))
             throw new FsError("EEXIST", { path: directory });
         const parent = this.observation(dirname(directory)).upper;
-        const staging = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
-        this.stages.set(staging, staging);
+        const owned = await this.upper.createStagedFile(directory, name, content, { ...options, parent });
+        const staging = Object.freeze({
+            parent: owned.parent, directory: owned.directory, file: owned.file,
+            ...(owned.cleanup ? { cleanup: createStagingCleanup(directory, controls => this.cleanup(staging, controls, true), () => owned.cleanup.close()) } : {}),
+        });
+        this.stages.set(staging.directory, owned);
+        this.stagingAncestors.set(staging.directory, ancestors);
         this.hidden.add(directory);
         return staging;
     }
     async publish(staging, path, options) {
         options.signal?.throwIfAborted();
         this.path(path);
-        const owned = this.stages.get(staging);
+        const owned = this.stages.get(staging.directory);
         if (!owned)
             throw new FsError("ENOTSUP", { path });
         const paths = this.ancestors(path);
-        const ancestors = options.ancestors;
+        const ancestors = options.ancestors ?? this.stagingAncestors.get(staging.directory);
         if (!ancestors || ancestors.length !== paths.length || ancestors.some((entry, index) => entry.path !== paths[index])) {
             throw new FsError("EINVAL", { path, message: "complete overlay ancestry is required" });
         }
@@ -238,16 +408,22 @@ export class OverlayMemoryPublication {
             ...options, ancestors: translated, parent: translated.at(-1).stat, destination: target ?? null,
         });
     }
-    async cleanup(staging, options) {
+    async cleanup(staging, options, retained = false) {
         this.stores();
-        const owned = this.stages.get(staging);
+        const owned = this.stages.get(staging.directory);
         if (!owned)
             throw new FsError("ENOTSUP", { path: staging.directory.path });
-        await this.upper.removeStagedFile(owned, options);
+        if (retained && owned.cleanup)
+            await owned.cleanup.remove(options);
+        else {
+            await this.upper.removeStagedFile(owned, options);
+            await owned.cleanup?.close();
+        }
         this.hidden.delete(owned.directory.path);
-        this.stages.delete(staging);
+        this.stages.delete(staging.directory);
+        this.stagingAncestors.delete(staging.directory);
     }
-    confine(roots, options, run, fs) {
+    confine(roots, options, run, fs, maxBytes) {
         options.signal?.throwIfAborted();
         const retained = new Map();
         for (const root of roots) {
@@ -259,10 +435,60 @@ export class OverlayMemoryPublication {
                 retained.set(entry.path, entry.stat);
             }
         }
+        const admittedStages = new WeakSet();
+        const guard = (path) => {
+            this.path(path);
+            if (!roots.some(root => isPathWithin(root, path)))
+                throw new FsError("EPERM", { path });
+            this.check([...retained].filter(([root]) => isPathWithin(root, path)).map(([path, stat]) => ({ path, stat })));
+        };
         return new Proxy(fs, {
             get: (target, property) => {
                 if (property === "confineExtraction" || property === "objects")
                     return undefined;
+                if (property === "prepareDirectory")
+                    return (path, mutation) => run(mutation, () => this.prepareDirectory(path, { ...mutation }, () => guard(path)));
+                if (property === "createStagedFile")
+                    return (path, name, content, mutation) => run(mutation, async () => {
+                        guard(path);
+                        if (content.type === "file" && content.data.byteLength > maxBytes)
+                            throw new FsError("EFBIG", { path });
+                        const stage = await this.create(path, name, content, mutation, () => guard(path));
+                        admittedStages.add(stage.directory);
+                        return stage;
+                    });
+                if (property === "publishStagedFile")
+                    return (stage, path, mutation) => run(mutation, async () => {
+                        guard(path);
+                        if (!admittedStages.has(stage.directory))
+                            throw new FsError("ENOTSUP", { path });
+                        await this.publish(stage, path, mutation);
+                    });
+                if (property === "removeStagedFile")
+                    return (stage, mutation = {}) => run(mutation, async () => {
+                        if (!admittedStages.has(stage.directory))
+                            throw new FsError("ENOTSUP", { path: stage.directory.path });
+                        await this.cleanup(stage, mutation);
+                    });
+                if (property === "writeFileConditional")
+                    return async (path, data, mutation) => {
+                        mutation.signal?.throwIfAborted();
+                        if (!(data instanceof Uint8Array))
+                            throw new TypeError("Overlay files require Uint8Array data");
+                        if (data.byteLength > maxBytes)
+                            throw new FsError("EFBIG", { path });
+                        const bytes = new Uint8Array(data), captured = { ...mutation };
+                        return run(captured, async () => {
+                            const guard = () => {
+                                this.path(path);
+                                if (!roots.some(root => isPathWithin(root, path)))
+                                    throw new FsError("EPERM", { path });
+                                this.check([...retained].filter(([root]) => isPathWithin(root, path)).map(([path, stat]) => ({ path, stat })));
+                            };
+                            guard();
+                            return this.writeFile(path, bytes, captured, maxBytes, guard);
+                        });
+                    };
                 if (["mkdir", "rm", "rmdir"].includes(String(property)))
                     return (path, mutation = {}) => run(mutation, async () => {
                         mutation.signal?.throwIfAborted();

package/dist/safe-fs/fs/s3/http/request-fetch.d.ts

@@ -0,0 +1,4 @@
+import type { RequestOptions } from "node:http";
+import type { RequestScope, WireResponse } from "./request.js";
+import type { S3HttpRequestFactory } from "./types.js";
+export declare function sendRequest(options: RequestOptions, body: Uint8Array, scope: RequestScope, factory?: S3HttpRequestFactory): Promise<WireResponse>;

package/dist/safe-fs/fs/s3/http/request-fetch.js

@@ -0,0 +1,74 @@
+import { S3ServiceError } from "../transport.js";
+import { abortable } from "./request.js";
+export async function sendRequest(options, body, scope, factory) {
+    const { signal } = scope;
+    signal.throwIfAborted();
+    if (factory)
+        throw new S3ServiceError("InvalidArgument", 400, "Node request factories are unavailable in fetch runtimes");
+    const hostname = String(options.hostname);
+    const authority = `${hostname.includes(":") ? `[${hostname}]` : hostname}${options.port ? `:${options.port}` : ""}`;
+    const target = `${options.protocol}//${authority}${options.path}`;
+    const url = new URL(target);
+    // Fetch normalizes dot segments. Never sign one key and send another.
+    if (`${url.pathname}${url.search}` !== options.path)
+        throw new S3ServiceError("InvalidArgument", 400, "object key cannot be represented by fetch without normalization");
+    const response = await abortable(fetch(target, {
+        method: options.method, headers: options.headers,
+        ...(options.method === "PUT" ? { body: new Uint8Array(body) } : {}),
+        signal, redirect: "manual",
+    }), signal);
+    const reader = response.body?.getReader();
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        signal.removeEventListener("abort", close);
+        scope.finish();
+        void reader?.cancel().catch(() => { });
+    };
+    signal.addEventListener("abort", close, { once: true });
+    if (signal.aborted) {
+        close();
+        signal.throwIfAborted();
+    }
+    const headersDistinct = Object.create(null);
+    response.headers.forEach((value, name) => { headersDistinct[name] = [value]; });
+    let claimed = false;
+    return {
+        message: { statusCode: response.status, headersDistinct }, close,
+        body: {
+            [Symbol.asyncIterator]() {
+                if (claimed)
+                    throw new S3ServiceError("InvalidResponse", 502, "response body is single-use");
+                claimed = true;
+                return {
+                    async next() {
+                        try {
+                            signal.throwIfAborted();
+                            if (closed || !reader) {
+                                close();
+                                return { done: true, value: undefined };
+                            }
+                            const result = await abortable(reader.read(), signal);
+                            signal.throwIfAborted();
+                            if (result.done) {
+                                close();
+                                return { done: true, value: undefined };
+                            }
+                            return { done: false, value: result.value };
+                        }
+                        catch (error) {
+                            close();
+                            throw error;
+                        }
+                    },
+                    async return() {
+                        close();
+                        return { done: true, value: undefined };
+                    },
+                };
+            },
+        },
+    };
+}

package/dist/safe-fs/fs/s3/http/request-node.d.ts

@@ -0,0 +1,4 @@
+import type { RequestOptions } from "node:http";
+import type { S3HttpRequestFactory } from "./types.js";
+import type { RequestScope, WireResponse } from "./request.js";
+export declare function sendRequest(options: RequestOptions, body: Uint8Array, scope: RequestScope, factory?: S3HttpRequestFactory): Promise<WireResponse>;

package/dist/safe-fs/fs/s3/http/request-node.js

@@ -0,0 +1,111 @@
+import { once } from "node:events";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { S3ServiceError } from "../transport.js";
+import { abortable } from "./request.js";
+export async function sendRequest(options, body, scope, factory) {
+    const signal = scope.signal;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        let request;
+        let response;
+        let headersReceived = false;
+        let finished = false;
+        const cleanup = () => {
+            signal.removeEventListener("abort", abort);
+            scope.finish();
+        };
+        const close = () => {
+            if (finished)
+                return;
+            finished = true;
+            cleanup();
+            response?.destroy();
+            request?.destroy();
+        };
+        const fail = (error) => {
+            reject(signal.aborted ? signal.reason : error);
+            close();
+        };
+        const abort = () => fail(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+            const create = factory ?? (options.protocol === "https:" ? httpsRequest : httpRequest);
+            request = create(options, message => {
+                response = message;
+                message.on("error", () => { });
+                if (finished || signal.aborted) {
+                    close();
+                    message.destroy();
+                    return;
+                }
+                headersReceived = true;
+                message.once("close", cleanup);
+                let claimed = false;
+                const source = {
+                    [Symbol.asyncIterator]() {
+                        if (claimed)
+                            throw new S3ServiceError("InvalidResponse", 502, "response body is single-use");
+                        claimed = true;
+                        const iterator = message[Symbol.asyncIterator]();
+                        let ended = false;
+                        return {
+                            async next() {
+                                try {
+                                    signal.throwIfAborted();
+                                    if (ended)
+                                        return { done: true, value: undefined };
+                                    const result = await abortable(iterator.next(), signal);
+                                    signal.throwIfAborted();
+                                    if (result.done) {
+                                        ended = true;
+                                        if (!message.complete)
+                                            throw new S3ServiceError("InvalidResponse", 502, "incomplete HTTP response");
+                                        close();
+                                        return { done: true, value: undefined };
+                                    }
+                                    if (!(result.value instanceof Uint8Array))
+                                        throw new S3ServiceError("InvalidResponse", 502, "nonbinary HTTP body");
+                                    return { done: false, value: new Uint8Array(result.value) };
+                                }
+                                catch (error) {
+                                    ended = true;
+                                    close();
+                                    throw signal.aborted ? signal.reason : error;
+                                }
+                            },
+                            async return() {
+                                ended = true;
+                                close();
+                                return { done: true, value: undefined };
+                            },
+                        };
+                    },
+                };
+                resolve({ message, body: source, close });
+            });
+            request.on("error", fail);
+            request.once("close", () => {
+                if (!headersReceived)
+                    fail(new S3ServiceError("InvalidResponse", 502, "connection closed before response headers"));
+            });
+            if (signal.aborted || finished) {
+                abort();
+                request.destroy();
+                return;
+            }
+            void (async () => {
+                for (let offset = 0; offset < body.length; offset += 64 * 1024) {
+                    signal.throwIfAborted();
+                    if (!request.write(body.subarray(offset, offset + 64 * 1024)))
+                        await once(request, "drain", { signal });
+                }
+                signal.throwIfAborted();
+                request.end();
+            })().catch(fail);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}

package/dist/safe-fs/fs/s3/http/request.d.ts

@@ -1,5 +1,4 @@
-import type { IncomingMessage, RequestOptions } from "node:http";
-import type { S3HttpRequestFactory } from "./types.js";
+export { sendRequest } from "#safe-fs-s3-request";
 export interface RequestScope {
     readonly signal: AbortSignal;
     readonly finish: () => void;
@@ -7,10 +6,12 @@ export interface RequestScope {
 export declare function scopeFor(signal: AbortSignal | undefined, timeout: number | undefined): RequestScope;
 export declare function abortable<Value>(pending: Promise<Value>, signal: AbortSignal): Promise<Value>;
 export interface WireResponse {
-    readonly message: IncomingMessage;
+    readonly message: {
+        readonly statusCode?: number | undefined;
+        readonly headersDistinct: Record<string, string[] | undefined>;
+    };
     readonly body: AsyncIterable<Uint8Array>;
     readonly close: () => void;
 }
-export declare function sendRequest(options: RequestOptions, body: Uint8Array, scope: RequestScope, factory?: S3HttpRequestFactory): Promise<WireResponse>;
 export declare function limitedBody(response: WireResponse, maximum: number, expected?: number): AsyncIterable<Uint8Array>;
 export declare function collect(response: WireResponse, maximum: number, expected?: number): Promise<Uint8Array>;