@poe-platform/safe-fs 0.1.695 → 0.1.697

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

@@ -0,0 +1,23 @@
+export interface ObjectIoQualificationBindings {
+    readonly QUALIFICATION_TOKEN?: string;
+    readonly QUALIFICATION_OWNER?: string;
+    readonly QUALIFICATION_EXPIRES_AT?: string;
+}
+export declare function authorizeObjectIoRequest(request: Request, bindings: ObjectIoQualificationBindings, now?: number): Response | undefined;
+export interface ObjectIoCleanupBucket {
+    list(options: {
+        limit: number;
+    }): Promise<{
+        objects: readonly {
+            key: string;
+        }[];
+        truncated: boolean;
+    }>;
+    delete(keys: string[]): Promise<unknown>;
+}
+export declare function cleanupObjectIoBucket(bucket: ObjectIoCleanupBucket, maxPages?: number): Promise<{
+    removedObjects: number;
+    listedPages: number;
+    remainingObjects: 0;
+    truncated: false;
+}>;

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

@@ -0,0 +1,39 @@
+export function authorizeObjectIoRequest(request, bindings, now = Date.now()) {
+    const expires = Number(bindings.QUALIFICATION_EXPIRES_AT);
+    if (typeof bindings.QUALIFICATION_TOKEN !== "string" || bindings.QUALIFICATION_TOKEN.length < 32
+        || !bindings.QUALIFICATION_OWNER || bindings.QUALIFICATION_OWNER.length > 128 || !Number.isSafeInteger(expires) || expires <= 0) {
+        return new Response("Qualification bindings required", { status: 503 });
+    }
+    if (request.headers.get("Authorization") !== `Bearer ${bindings.QUALIFICATION_TOKEN}`)
+        return new Response("Unauthorized", { status: 401 });
+    const url = new URL(request.url);
+    if (expires <= now && url.pathname !== "/cleanup")
+        return new Response("Qualification expired", { status: 410 });
+    if (expires - now > 3600000)
+        return new Response("Expiry must be within one hour", { status: 503 });
+    if (request.method !== "POST")
+        return new Response("POST required", { status: 405 });
+    if (request.headers.get("Content-Length") !== "0" || request.headers.has("Transfer-Encoding"))
+        return new Response("Empty request required", { status: 400 });
+    if (!["/ready", "/cleanup", "/conformance", "/unhandled-errors", "/object-io-781"].includes(url.pathname))
+        return new Response("Not found", { status: 404 });
+    if (url.pathname !== "/object-io-781" && url.search)
+        return new Response("Control queries forbidden", { status: 400 });
+    return undefined;
+}
+export async function cleanupObjectIoBucket(bucket, maxPages = 32) {
+    if (!Number.isSafeInteger(maxPages) || maxPages < 1 || maxPages > 32)
+        throw new RangeError("Invalid cleanup page cap");
+    let removedObjects = 0;
+    for (let listedPages = 1; listedPages <= maxPages; listedPages++) {
+        const page = await bucket.list({ limit: 100 });
+        if (!page.objects.length) {
+            if (page.truncated)
+                throw new Error("Qualification cleanup returned a truncated empty page");
+            return { removedObjects, listedPages, remainingObjects: 0, truncated: false };
+        }
+        await bucket.delete(page.objects.map(object => object.key));
+        removedObjects += page.objects.length;
+    }
+    throw new Error("Qualification cleanup cap exhausted; bucket emptiness unverified");
+}

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

@@ -0,0 +1,28 @@
+export interface ObjectIoOperationMetrics {
+    count: number;
+    failed: number;
+    elapsedMs: number;
+}
+export interface ObjectIoPhaseMetrics {
+    elapsedMs: number;
+    operations: Record<string, ObjectIoOperationMetrics>;
+}
+export declare class ObjectIoMetrics {
+    private readonly now;
+    private readonly phases;
+    private current;
+    private started;
+    constructor(now?: () => number);
+    phase(name: string): void;
+    measure<Value>(category: string, name: string, operation: () => Value | Promise<Value>): Promise<Value>;
+    snapshot(): Record<string, ObjectIoPhaseMetrics>;
+}
+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>;
+    readonly size: number;
+    readonly metrics: ObjectIoMetrics;
+    dispose(): Promise<void>;
+    summary(): Record<string, unknown>;
+}
+export declare function createObjectIoReadbackStream(options: ObjectIoReadbackOptions): ReadableStream<Uint8Array>;

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

@@ -0,0 +1,114 @@
+export class ObjectIoMetrics {
+    now;
+    phases = {};
+    current = "setup";
+    started;
+    constructor(now = () => performance.now()) {
+        this.now = now;
+        this.started = now();
+        this.phases[this.current] = { elapsedMs: 0, operations: {} };
+    }
+    phase(name) {
+        const time = this.now();
+        this.phases[this.current].elapsedMs += time - this.started;
+        this.started = time;
+        this.current = name;
+        this.phases[name] ??= { elapsedMs: 0, operations: {} };
+    }
+    async measure(category, name, operation) {
+        const operations = this.phases[this.current].operations;
+        const entry = operations[`${category}.${name}`] ??= { count: 0, failed: 0, elapsedMs: 0 };
+        entry.count++;
+        const started = this.now();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            entry.failed++;
+            throw error;
+        }
+        finally {
+            entry.elapsedMs += this.now() - started;
+        }
+    }
+    snapshot() {
+        const result = structuredClone(this.phases);
+        result[this.current].elapsedMs += this.now() - this.started;
+        return result;
+    }
+}
+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");
+    return new Proxy(backend, { get(target, property) {
+            const value = Reflect.get(target, property, target);
+            if (typeof value !== "function")
+                return value;
+            return (...args) => metrics.measure("backend", String(property), async () => {
+                if (delayMs)
+                    await sleep(delayMs);
+                return value.apply(target, args);
+            });
+        } });
+}
+export function createObjectIoReadbackStream(options) {
+    const reader = options.body.getReader({ mode: "byob" });
+    const encoder = new TextEncoder();
+    let offset = 0;
+    let cleanup;
+    const dispose = () => cleanup ??= (async () => {
+        options.metrics.phase("fixtureCleanup");
+        await options.dispose();
+        options.metrics.phase("complete");
+    })();
+    options.metrics.phase("canonicalStream");
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const chunk = await options.metrics.measure("stream", "read", () => reader.read(new Uint8Array(65536)));
+                if (chunk.done) {
+                    if (offset !== options.size)
+                        throw new Error("Canonical readback size mismatch");
+                    await dispose();
+                    controller.enqueue(encoder.encode(JSON.stringify({ ...options.summary(), type: "summary", completed: true,
+                        canonicalBytes: offset, phases: options.metrics.snapshot() }) + "\n"));
+                    controller.close();
+                    reader.releaseLock();
+                    return;
+                }
+                if (offset + chunk.value.length > options.size)
+                    throw new Error("Canonical readback size mismatch");
+                const base64 = btoa(String.fromCharCode(...chunk.value));
+                controller.enqueue(encoder.encode(JSON.stringify({ type: "chunk", offset, base64 }) + "\n"));
+                offset += chunk.value.length;
+            }
+            catch (error) {
+                let failure = error;
+                try {
+                    await reader.cancel(error);
+                }
+                catch (cancelError) {
+                    if (cancelError !== error)
+                        failure = new AggregateError([error, cancelError], "Readback and cancellation failed");
+                }
+                try {
+                    await dispose();
+                }
+                catch (cleanupError) {
+                    failure = new AggregateError([failure, cleanupError], "Readback and cleanup failed");
+                }
+                reader.releaseLock();
+                controller.error(failure);
+            }
+        },
+        async cancel(reason) {
+            try {
+                await reader.cancel(reason);
+            }
+            finally {
+                await dispose();
+                reader.releaseLock();
+            }
+        },
+    });
+}

package/package.json

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