@poe-platform/safe-fs 0.1.727 → 0.1.729

package/dist/safe-fs/fs/staging-ancestry.js

@@ -0,0 +1,115 @@
+import { FsError, toFsError } from "../contracts/errors.js";
+import { compareIdentity } from "./mount/identity.js";
+import { normalizePath, validatePath } from "../contracts/virtual-path.js";
+export function directoryAncestryPaths(directory) {
+    validatePath(directory);
+    if (!directory.startsWith("/") || normalizePath(directory) !== directory)
+        throw new FsError("EINVAL", { path: directory });
+    let path = "";
+    return ["/", ...directory.split("/").filter(Boolean).map(component => path += `/${component}`)];
+}
+export function snapshotDirectoryAncestry(ancestors) {
+    const entries = ancestors.map(entry => Object.freeze({ path: entry.path, stat: Object.freeze({ ...entry.stat }) }));
+    const paths = directoryAncestryPaths(entries.at(-1)?.path ?? "");
+    if (entries.length !== paths.length || entries.some((entry, index) => entry.path !== paths[index])) {
+        throw new FsError("EINVAL", { message: "directory ancestry requires a complete ordered root-to-directory list" });
+    }
+    for (const entry of entries) {
+        if (entry.stat.type !== "directory")
+            throw new FsError("EINVAL", { path: entry.path });
+        if (compareIdentity(entry.stat, entry.stat) !== "same")
+            throw new FsError("ENOTSUP", { path: entry.path });
+    }
+    return Object.freeze(entries);
+}
+export function runStagingGuard(guard) {
+    const result = guard();
+    if (result !== true) {
+        // A void callback would accept async implementations. Require a literal
+        // success value and observe a misdeclared asynchronous rejection.
+        void Promise.resolve(result).catch(() => { });
+        throw new FsError("ENOTSUP", { message: "staging validation must return true synchronously" });
+    }
+}
+export function snapshotStagingResolution(resolution) {
+    const path = resolution.path;
+    validatePath(path);
+    const ancestors = snapshotDirectoryAncestry(resolution.ancestors);
+    const validate = resolution.validate;
+    if (normalizePath(path) !== path || !path.startsWith("/") || path === "/"
+        || ancestors.at(-1).path !== (path.slice(0, path.lastIndexOf("/")) || "/")
+        || typeof validate !== "function")
+        throw new FsError("EINVAL", { path });
+    const parent = Object.freeze({ ...resolution.parent });
+    if (parent.type !== "directory")
+        throw new FsError("EINVAL", { path });
+    if (compareIdentity(parent, ancestors.at(-1).stat) !== "same")
+        throw new FsError("ENOTSUP", { path });
+    const supplied = resolution.destination;
+    const destination = supplied === null ? null : Object.freeze({ ...supplied });
+    const requireSnapshot = (stat) => {
+        if (compareIdentity(stat, stat) !== "same" || stat.type !== "directory" && (!Number.isSafeInteger(stat.revision) || stat.revision < 0)) {
+            throw new FsError("ENOTSUP", { path });
+        }
+    };
+    if (destination !== null) {
+        if (destination.type !== "file")
+            throw new FsError("EINVAL", { path });
+        requireSnapshot(destination);
+    }
+    if (!resolution.traversed.length)
+        throw new FsError("EINVAL", { path });
+    if (resolution.traversed.length > 4096)
+        throw new FsError("EFBIG", { path });
+    let recordedUnits = 0;
+    const traversed = resolution.traversed.map(entry => {
+        const entryPath = entry.path, stat = Object.freeze({ ...entry.stat }), linkTarget = entry.linkTarget;
+        validatePath(entryPath);
+        if (!entryPath.startsWith("/") || normalizePath(entryPath) !== entryPath
+            || !["directory", "file", "symlink"].includes(stat.type)
+            || stat.type === "symlink" && typeof linkTarget !== "string"
+            || stat.type !== "symlink" && linkTarget !== undefined)
+            throw new FsError("EINVAL", { path: entryPath });
+        requireSnapshot(stat);
+        recordedUnits += entryPath.length + (linkTarget?.length ?? 0);
+        if (recordedUnits > 1_048_576)
+            throw new FsError("EFBIG", { path });
+        return Object.freeze({ path: entryPath, stat, ...(linkTarget === undefined ? {} : { linkTarget }) });
+    });
+    return Object.freeze({ path, parent, destination, ancestors, traversed: Object.freeze(traversed), validate });
+}
+/** Diagnose failed admission against supplied receipts; this is never a commit
+ * guard. Successful publication still requires the backend's atomic checks. */
+export async function inspectStagingBindings(read, destination, options) {
+    options.signal?.throwIfAborted();
+    const ancestors = snapshotDirectoryAncestry(options.ancestors);
+    const parent = destination.slice(0, destination.lastIndexOf("/")) || "/";
+    if (normalizePath(destination) !== destination || ancestors.at(-1)?.path !== parent)
+        throw new FsError("EINVAL", { path: destination });
+    const expected = options.destination === null ? null : { ...options.destination };
+    if (expected !== null && (compareIdentity(expected, expected) !== "same"
+        || expected.type === "file" && (!Number.isSafeInteger(expected.revision) || expected.revision < 0)))
+        throw new FsError("ENOTSUP", { path: destination });
+    const entries = [...ancestors.map(entry => ({ ...entry, directory: true })), { path: destination, stat: expected, directory: false }];
+    for (const entry of entries) {
+        let current;
+        try {
+            current = await read(entry.path);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            const code = toFsError(error).code;
+            if (code === "ENOENT" && entry.stat === null)
+                continue;
+            if (["ENOENT", "ENOTDIR", "ELOOP"].includes(code))
+                throw new FsError("EAGAIN", { path: entry.path, cause: error });
+            throw error;
+        }
+        options.signal?.throwIfAborted();
+        if (entry.stat === null || current.type !== entry.stat.type || compareIdentity(current, entry.stat) !== "same")
+            throw new FsError("EAGAIN", { path: entry.path });
+        if (!entry.directory && ["revision", "size", "mode", "nlink", "mtimeMs", "ctimeMs"].some(field => current[field] !== entry.stat[field])) {
+            throw new FsError("EAGAIN", { path: entry.path });
+        }
+    }
+}

package/dist/safe-fs/fs/staging-cleanup.d.ts

@@ -0,0 +1,5 @@
+import type { CreateStagedFileOptions, FileStagingCleanup, FsOptions } from "../contracts/filesystem.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export declare function snapshotStagingCreation(options: CreateStagedFileOptions, path: string): CreateStagedFileOptions;
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export declare function createStagingCleanup(path: string, remove: (options: FsOptions) => void | Promise<void>, release: () => void | Promise<void>): FileStagingCleanup;

package/dist/safe-fs/fs/staging-cleanup.js

@@ -0,0 +1,63 @@
+import { FsError } from "../contracts/errors.js";
+import { finishCleanup } from "../contracts/cleanup.js";
+/** Capture creation controls before awaits or allocation can split their meaning. */
+export function snapshotStagingCreation(options, path) {
+    const captured = { ...options };
+    for (const key of ["signal", "retainCleanup", "parent", "mode", "atimeMs", "mtimeMs"]) {
+        if (!Object.hasOwn(captured, key))
+            Object.defineProperty(captured, key, { value: options[key], enumerable: true });
+    }
+    const { signal, retainCleanup, parent, mode, atimeMs, mtimeMs, ...extra } = captured;
+    signal?.throwIfAborted();
+    if (retainCleanup !== undefined && typeof retainCleanup !== "boolean")
+        throw new FsError("EINVAL", { syscall: "createStagedFile", path });
+    return {
+        ...extra, parent,
+        ...(signal === undefined ? {} : { signal }),
+        ...(retainCleanup === undefined ? {} : { retainCleanup }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(atimeMs === undefined ? {} : { atimeMs }),
+        ...(mtimeMs === undefined ? {} : { mtimeMs }),
+    };
+}
+/** Own admission and release outside wrappers that can fail before dispatch. */
+export function createStagingCleanup(path, remove, release) {
+    let accepting = true;
+    let removal;
+    let closing;
+    let released;
+    const dispose = () => released ??= Promise.resolve().then(release);
+    return Object.freeze({
+        remove(options = {}) {
+            if (removal)
+                return removal;
+            if (!accepting) {
+                const rejected = Promise.reject(new FsError("EBADF", { syscall: "removeStagedFile", path }));
+                void rejected.catch(() => { });
+                return rejected;
+            }
+            accepting = false;
+            removal = Promise.resolve().then(async () => {
+                let failed = true;
+                try {
+                    await remove(options);
+                    failed = false;
+                }
+                finally {
+                    await finishCleanup(dispose, failed);
+                }
+            });
+            void removal.catch(() => { });
+            return removal;
+        },
+        close() {
+            accepting = false;
+            closing ??= (async () => {
+                await removal?.catch(() => { });
+                await dispose();
+            })();
+            void closing.catch(() => { });
+            return closing;
+        },
+    });
+}

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

@@ -86,7 +86,9 @@ const resourceIdBody = '<?xml version="1.0" encoding="utf-8"?>'
 function fail(code, syscall, path, message) {
     throw new FsError(code, { syscall, path, ...(message === undefined ? {} : { message }) });
 }
-function positive(value, name, zero = false) {
+function positive(value, name, zero = false, unlimited = false) {
+    if (unlimited && value === Infinity)
+        return value;
     if (!Number.isSafeInteger(value) || value < (zero ? 0 : 1)) {
         throw new FsError("EINVAL", { message: `${name} must be a ${zero ? "nonnegative" : "positive"} safe integer` });
     }
@@ -286,9 +288,9 @@ export class WebDavFileSystem {
             removeDirectory: this.atomicEmptyDirectory !== undefined,
             streamingAppend: this.requestStreamSupport !== false,
         });
-        this.maxResponseBytes = options.maxResponseBytes === undefined ? 16 * 1024 * 1024 : positive(options.maxResponseBytes, "maxResponseBytes");
-        this.maxXmlBytes = options.maxXmlBytes === undefined ? 1024 * 1024 : positive(options.maxXmlBytes, "maxXmlBytes");
-        this.maxEntries = options.maxEntries === undefined ? Infinity : positive(options.maxEntries, "maxEntries");
+        this.maxResponseBytes = options.maxResponseBytes === undefined ? 16 * 1024 * 1024 : positive(options.maxResponseBytes, "maxResponseBytes", false, true);
+        this.maxXmlBytes = options.maxXmlBytes === undefined ? 1024 * 1024 : positive(options.maxXmlBytes, "maxXmlBytes", false, true);
+        this.maxEntries = options.maxEntries === undefined ? Infinity : positive(options.maxEntries, "maxEntries", false, true);
         this.timeoutMs = options.timeoutMs === undefined ? undefined : positive(options.timeoutMs, "timeoutMs");
         this.overwritePolicy = options.overwritePolicy ?? "lock";
         this.configuredComparison = options.compareEntry !== undefined;
@@ -867,7 +869,7 @@ export class WebDavFileSystem {
     }
     async readFile(path, options = {}) {
         const normalized = normalize(path);
-        const limit = Math.min(this.maxResponseBytes, options.maxBytes === undefined ? this.maxResponseBytes : positive(options.maxBytes, "maxBytes", true));
+        const limit = Math.min(this.maxResponseBytes, options.maxBytes === undefined ? this.maxResponseBytes : positive(options.maxBytes, "maxBytes", true, true));
         if ((await this.stat(path, options)).type === "directory")
             fail("EISDIR", "readFile", path);
         return this.request("GET", normalized, options, { headers: { "Accept-Encoding": "identity" } }, async (response, signal) => {

package/dist/safe-fs/platform/browser.d.ts

@@ -1,4 +1,5 @@
 import type { FsOptions } from "../contracts/filesystem.js";
+import type { ScopedTransportBudgetFrame } from "./transport-budget.js";
 export type PlatformErrno = number | undefined;
 export type PlatformComparisonCallback<Callback> = Callback & never;
 export declare const platform: Readonly<{
@@ -11,3 +12,7 @@ export declare const comparisonContext: Readonly<{
     active(options: FsOptions): boolean;
     run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
 }>;
+export declare function getScopedTransportBudget(): readonly ScopedTransportBudgetFrame[] | undefined;
+export declare function withScopedTransportBudget<Result>(frames: readonly ScopedTransportBudgetFrame[] | undefined, action: () => Result): Result;
+export declare function runScopedTransportBudget<Result>(_admit: (options?: FsOptions) => void, action: () => Result, _credit?: number): Result;
+export declare function chargeScopedTransportCall(options?: FsOptions): never;

package/dist/safe-fs/platform/browser.js

@@ -38,3 +38,20 @@ export const comparisonContext = Object.freeze({
         }
     }
 });
+// Scoped browser filesystems charge logical operations directly. S3 remains
+// Node-only; never pretend to provide its async transport budget context here.
+export function getScopedTransportBudget() {
+    return undefined;
+}
+export function withScopedTransportBudget(frames, action) {
+    if (frames !== undefined)
+        throw new FsError("ENOTSUP", { message: "S3 transport budget contexts require Node" });
+    return action();
+}
+export function runScopedTransportBudget(_admit, action, _credit = 1) {
+    return action();
+}
+export function chargeScopedTransportCall(options) {
+    options?.signal?.throwIfAborted();
+    throw new FsError("ENOTSUP", { message: "S3 transport budget contexts require Node" });
+}

package/dist/safe-fs/platform/node.d.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import type { FsOptions } from "../contracts/filesystem.js";
+import { type ScopedTransportBudgetFrame } from "./transport-budget.js";
 export type PlatformErrno = number;
 export type PlatformComparisonCallback<Callback> = Callback;
 export declare const platform: Readonly<{
@@ -12,3 +13,7 @@ export declare const comparisonContext: Readonly<{
     active(_options: FsOptions): boolean;
     run<Result>(options: FsOptions, action: (nested: FsOptions) => Promise<Result>): Promise<Result>;
 }>;
+export declare function getScopedTransportBudget(): readonly ScopedTransportBudgetFrame[] | undefined;
+export declare function withScopedTransportBudget<Result>(frames: readonly ScopedTransportBudgetFrame[] | undefined, action: () => Result): Result;
+export declare function runScopedTransportBudget<Result>(admit: (options?: FsOptions) => void, action: () => Result, credit?: number): Result;
+export declare function chargeScopedTransportCall(options?: FsOptions): void;

package/dist/safe-fs/platform/node.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import * as util from "node:util";
 import { constants } from "node:os";
+import { hasRegisteredS3FileSystem } from "./transport-budget.js";
 const systemErrnos = (() => {
     const fallback = new Map(Object.entries(constants.errno).map(([name, errno]) => [name, -Math.abs(errno)]));
     if (typeof util.getSystemErrorMap !== "function")
@@ -33,3 +34,30 @@ export const comparisonContext = Object.freeze({
         return negotiating.run(true, () => action(options));
     }
 });
+const transportBudgets = new AsyncLocalStorage();
+export function getScopedTransportBudget() {
+    return hasRegisteredS3FileSystem ? transportBudgets.getStore() : undefined;
+}
+export function withScopedTransportBudget(frames, action) {
+    return frames ? transportBudgets.run(frames, action) : action();
+}
+export function runScopedTransportBudget(admit, action, credit = 1) {
+    if (!hasRegisteredS3FileSystem)
+        return action();
+    const parent = transportBudgets.getStore() ?? [];
+    const frame = { credit, admit };
+    return transportBudgets.run([...parent, frame], action);
+}
+export function chargeScopedTransportCall(options) {
+    if (!hasRegisteredS3FileSystem)
+        return;
+    const frames = transportBudgets.getStore();
+    if (!frames)
+        return;
+    for (const frame of frames) {
+        if (frame.credit > 0)
+            frame.credit--;
+        else
+            frame.admit(options);
+    }
+}

package/dist/safe-fs/platform/transport-budget.d.ts

@@ -0,0 +1,7 @@
+import type { FsOptions } from "../contracts/filesystem.js";
+export interface ScopedTransportBudgetFrame {
+    credit: number;
+    readonly admit: (options?: FsOptions) => void;
+}
+export declare let hasRegisteredS3FileSystem: boolean;
+export declare function enableS3TransportBudget(): void;

package/dist/safe-fs/platform/transport-budget.js

@@ -0,0 +1,4 @@
+export let hasRegisteredS3FileSystem = false;
+export function enableS3TransportBudget() {
+    hasRegisteredS3FileSystem = true;
+}

package/dist/safe-fs/testing/object-io-metrics.d.ts

@@ -1,3 +1,4 @@
+import type { ObjectFilePublicationStore } from "../fs/object-publication/index.js";
 export interface ObjectIoOperationMetrics {
     count: number;
     failed: number;
@@ -17,6 +18,8 @@ export declare class ObjectIoMetrics {
     measure<Value>(category: string, name: string, operation: () => Value | Promise<Value>): Promise<Value>;
     snapshot(): Record<string, ObjectIoPhaseMetrics>;
 }
+/** Timings are inclusive: store publication can contain staging reads and backend I/O. */
+export declare function measureObjectIoStore(store: ObjectFilePublicationStore, metrics: ObjectIoMetrics): ObjectFilePublicationStore;
 export declare function delayObjectIoBackend<Backend extends object>(backend: Backend, metrics: ObjectIoMetrics, delayMs: number, sleep?: (duration: number) => Promise<void>): Backend;
 export interface ObjectIoReadbackOptions {
     readonly body: ReadableStream<Uint8Array>;

package/dist/safe-fs/testing/object-io-metrics.js

@@ -37,6 +37,35 @@ export class ObjectIoMetrics {
         return result;
     }
 }
+/** Timings are inclusive: store publication can contain staging reads and backend I/O. */
+export function measureObjectIoStore(store, metrics) {
+    const version = (head) => ({
+        revision: head.revision, stat: head.stat,
+        ...(head.publicationToken === undefined ? {} : { publicationToken: head.publicationToken }),
+        read: (...args) => metrics.measure("version", "read", () => head.read(...args)),
+        close: () => metrics.measure("version", "close", () => head.close()),
+    });
+    const publish = store.publish;
+    const createStaging = store.createStaging;
+    return {
+        async acquire(...args) {
+            const head = await metrics.measure("store", "acquire", () => store.acquire(...args));
+            return head && version(head);
+        },
+        ...(publish ? { async publish(...args) {
+                return version(await metrics.measure("store", "publish", () => publish.apply(store, args)));
+            } } : {}),
+        ...(createStaging ? { async createStaging(...args) {
+                const staging = await metrics.measure("store", "createStaging", () => createStaging.apply(store, args));
+                return {
+                    readPage: (...values) => metrics.measure("staging", "readPage", () => staging.readPage(...values)),
+                    writePage: (...values) => metrics.measure("staging", "writePage", () => staging.writePage(...values)),
+                    truncate: (...values) => metrics.measure("staging", "truncate", () => staging.truncate(...values)),
+                    close: () => metrics.measure("staging", "close", () => staging.close()),
+                };
+            } } : {}),
+    };
+}
 export function delayObjectIoBackend(backend, metrics, delayMs, sleep = duration => new Promise(resolve => setTimeout(resolve, duration))) {
     if (!Number.isSafeInteger(delayMs) || delayMs < 0)
         throw new RangeError("Backend delay must be a nonnegative integer");

package/dist/safe-fs/testing/object-publication.d.ts

@@ -1,14 +1,16 @@
 import type { FileSystem } from "../contracts/filesystem.js";
-import type { ObjectFilePublicationStore } from "../fs/object-publication/index.js";
+import type { ObjectFileDescriptorOptions, ObjectFilePublicationStore } from "../fs/object-publication/index.js";
 export interface ObjectFilePublicationConformanceFixture {
     readonly fs: FileSystem;
     readonly store: ObjectFilePublicationStore;
     readonly root: string;
+    readonly descriptorOptions?: ObjectFileDescriptorOptions;
     dispose(): void | Promise<void>;
 }
 export interface ObjectFilePublicationConformanceOptions {
     readonly createFixture: () => ObjectFilePublicationConformanceFixture | Promise<ObjectFilePublicationConformanceFixture>;
     readonly requireStaging?: boolean;
+    readonly descriptorOptions?: ObjectFileDescriptorOptions;
 }
 export interface ObjectFilePublicationConformanceCase {
     readonly name: string;

package/dist/safe-fs/testing/object-publication.js

@@ -92,7 +92,7 @@ export function createObjectFilePublicationConformanceCases(options) {
             async run({ fixture, path, track, publish }) {
                 const name = path("descriptor");
                 await publish(name, null, new Uint8Array([1, 2, 3, 4]));
-                const fs = withObjectFileDescriptors(fixture.fs, fixture.store, { chunkBytes: 4, maxStagedBytes: 16 });
+                const fs = withObjectFileDescriptors(fixture.fs, fixture.store, { chunkBytes: 4, maxStagedBytes: 16, maxFileBytes: 16, ...options.descriptorOptions, ...fixture.descriptorOptions });
                 const descriptor = track(await fs.open(name, { access: "readwrite" }));
                 check(descriptor.capabilities.publication === "conditional", "descriptor publication profile was lost");
                 await descriptor.write(new Uint8Array([7]), 1);
@@ -156,7 +156,7 @@ export function createObjectFilePublicationConformanceCases(options) {
             async run({ fixture, path, track, publish }) {
                 const name = path("stage-descriptor");
                 await publish(name, null, new Uint8Array([1, 2, 3, 4]));
-                const fs = withObjectFileDescriptors(fixture.fs, fixture.store, { chunkBytes: 4, maxStagedBytes: 4, maxStagedPages: 1, maxFileBytes: 16 });
+                const fs = withObjectFileDescriptors(fixture.fs, fixture.store, { chunkBytes: 4, maxStagedBytes: 4, maxStagedPages: 1, maxFileBytes: 16, ...options.descriptorOptions, ...fixture.descriptorOptions });
                 const descriptor = track(await fs.open(name, { access: "readwrite" }));
                 const content = new Uint8Array([5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]);
                 await descriptor.write(content, 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.727",
+  "version": "0.1.729",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",