@poe-platform/safe-fs 0.1.726 → 0.1.728

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.726",
+  "version": "0.1.728",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",