@poe-platform/safe-fs 0.1.511 → 0.1.513

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

@@ -1,10 +1,11 @@
 import { FsError } from "../contracts/errors.js";
 import { finishCleanup } from "../contracts/cleanup.js";
 import { registerEntryView } from "./mount/comparison.js";
+import { openRetainedResizeFile, retainedResizeCapabilities } from "./capabilities.js";
 const originals = new WeakMap();
 const operations = new Set([
     "access", "appendFile", "canonicalizeMissingTarget", "capabilitiesFor", "chmod", "compareEntry",
-    "copyFile", "link", "lstat", "mkdir", "openReadFile", "readFile", "readStream", "readdir",
+    "copyFile", "link", "lstat", "mkdir", "openReadFile", "openResizeFile", "readFile", "readStream", "readdir",
     "readlink", "realpath", "rename", "rm", "rmdir", "stat", "symlink", "truncate", "utimes",
     "writeFile", "writeStream",
 ]);
@@ -19,11 +20,98 @@ export function scopeFileSystem(filesystem, charge, signal) {
         assertOpen(options);
         charge();
     };
-    const wrapHandle = (handle) => ({
-        async stat(options) { admit(options); return handle.stat(options); },
-        async read(position, maxBytes, options) { admit(options); return handle.read(position, maxBytes, options); },
-        close: handle.close.bind(handle),
-    });
+    const wrapHandle = (handle) => {
+        let closed = false;
+        const close = handle.close.bind(handle);
+        return {
+            async stat(options) { admit(options); return handle.stat(options); },
+            async read(position, maxBytes, options) { admit(options); return handle.read(position, maxBytes, options); },
+            get seekEnd() {
+                const seek = handle.seekEnd;
+                if (typeof seek !== "function")
+                    return undefined;
+                return async (options = {}) => {
+                    assertOpen(options);
+                    if (closed)
+                        throw new FsError("EBADF");
+                    admit(options);
+                    assertOpen(options);
+                    if (closed)
+                        throw new FsError("EBADF");
+                    try {
+                        const result = await Reflect.apply(seek, handle, [resizeOptions(options)]);
+                        assertOpen(options);
+                        return result;
+                    }
+                    catch (error) {
+                        assertOpen(options);
+                        throw error;
+                    }
+                };
+            },
+            close() { closed = true; return close(); },
+        };
+    };
+    const resizeOptions = (options) => {
+        const scopedOptions = {
+            ...options, signal: options.signal ? AbortSignal.any([signal, options.signal]) : signal,
+        };
+        scopedOptions.signal.throwIfAborted();
+        return scopedOptions;
+    };
+    const wrapResizeHandle = (handle) => {
+        let closing;
+        const admitOperation = (options) => {
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            admit(options);
+            assertOpen(options);
+            if (closing)
+                throw new FsError("EBADF");
+            return resizeOptions(options);
+        };
+        return {
+            async stat(options = {}) {
+                try {
+                    const result = await handle.stat(admitOperation(options));
+                    assertOpen(options);
+                    return result;
+                }
+                catch (error) {
+                    assertOpen(options);
+                    throw error;
+                }
+            },
+            async truncate(length, options = {}) {
+                try {
+                    await handle.truncate(length, admitOperation(options));
+                    assertOpen(options);
+                }
+                catch (error) {
+                    assertOpen(options);
+                    throw error;
+                }
+            },
+            get seekEnd() {
+                const seek = handle.seekEnd;
+                if (typeof seek !== "function")
+                    return undefined;
+                return async (options = {}) => {
+                    try {
+                        const result = await Reflect.apply(seek, handle, [admitOperation(options)]);
+                        assertOpen(options);
+                        return result;
+                    }
+                    catch (error) {
+                        assertOpen(options);
+                        throw error;
+                    }
+                };
+            },
+            close: () => closing ??= Promise.resolve().then(() => handle.close()),
+        };
+    };
     const wrapStream = (source, options) => ({
         [Symbol.asyncIterator]() {
             assertOpen(options);
@@ -62,6 +150,8 @@ export function scopeFileSystem(filesystem, charge, signal) {
             return Reflect.set(original, property, value, original);
         },
         get(_target, property) {
+            if (property === "capabilities")
+                return retainedResizeCapabilities(original);
             const method = Reflect.get(original, property, original);
             if (typeof method !== "function")
                 return method;
@@ -90,13 +180,21 @@ export function scopeFileSystem(filesystem, charge, signal) {
                     })();
                 return Reflect.apply(method, original, args);
             };
-            const scoped = property === "openReadFile"
-                ? async (...args) => wrapHandle(await dispatch(...args))
-                : property === "readStream"
-                    ? (...args) => wrapStream(dispatch(...args), args[1])
-                    : operations.has(property) && property !== "canonicalizeMissingTarget"
-                        ? async (...args) => dispatch(...args)
-                        : dispatch;
+            const scoped = property === "openResizeFile"
+                ? async (path, options = {}) => {
+                    admit(options);
+                    assertOpen(options);
+                    return wrapResizeHandle(await openRetainedResizeFile(original, path, resizeOptions(options)));
+                }
+                : property === "capabilitiesFor"
+                    ? async (...args) => retainedResizeCapabilities(original, await dispatch(...args))
+                    : property === "openReadFile"
+                        ? async (...args) => wrapHandle(await dispatch(...args))
+                        : property === "readStream"
+                            ? (...args) => wrapStream(dispatch(...args), args[1])
+                            : operations.has(property) && property !== "canonicalizeMissingTarget"
+                                ? async (...args) => dispatch(...args)
+                                : dispatch;
             methods.set(property, { original: method, scoped });
             return scoped;
         },

package/dist/safe-fs/native/fs-seek/loader.d.ts

@@ -0,0 +1,5 @@
+export interface NativeSeekBinding {
+  seekEnd(descriptor: number): Promise<{ offset: bigint; errno: number }>;
+}
+
+export function loadBinding(): Promise<NativeSeekBinding>;

package/dist/safe-fs/native/fs-seek/loader.mjs

@@ -0,0 +1,120 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { createRequire } from "node:module";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const maxManifestBytes = 16384;
+const maxBinaryBytes = 1048576;
+let loading;
+
+function failure(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function identifier(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 32
+    && [...value].every(character => "abcdefghijklmnopqrstuvwxyz0123456789_".includes(character));
+}
+
+function decimal(value) {
+  return typeof value === "string" && value.length > 0 && value.length <= 6
+    && [...value].every(character => "0123456789".includes(character));
+}
+
+function libcVersion(value) {
+  if (typeof value !== "string") return undefined;
+  const parts = value.split(".");
+  return parts.length === 2 && parts.every(decimal) ? parts.map(Number) : undefined;
+}
+
+function atLeast(version, minimum) {
+  return version[0] > minimum[0] || version[0] === minimum[0] && version[1] >= minimum[1];
+}
+
+async function readAsset(filename, limit) {
+  const handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let failed = false;
+  let primary;
+  let bytes;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw failure("EINVAL", "Native asset must be a regular file");
+    if (!Number.isSafeInteger(stat.size) || stat.size <= 0) throw failure("EINVAL", "Invalid native asset size");
+    if (stat.size > limit) throw failure("EFBIG", "Native asset exceeds its byte limit");
+    bytes = Buffer.alloc(stat.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const remaining = bytes.length - offset;
+      const { bytesRead } = await handle.read(bytes, offset, remaining, offset);
+      if (!Number.isSafeInteger(bytesRead) || bytesRead <= 0 || bytesRead > remaining) throw failure("EIO", "Incomplete native asset read");
+      offset += bytesRead;
+    }
+    const { bytesRead } = await handle.read(Buffer.alloc(1), 0, 1, offset);
+    if (bytesRead !== 0) throw failure("EIO", "Native asset changed while reading");
+  } catch (error) {
+    failed = true;
+    primary = error;
+  }
+  try { await handle.close(); }
+  catch (error) { if (!failed) throw error; }
+  if (failed) throw primary;
+  return bytes;
+}
+
+function validateManifest(value) {
+  const invalid = () => { throw failure("EINVAL", "Invalid native seek manifest"); };
+  if (value === null || typeof value !== "object" || Array.isArray(value)
+    || value.version !== 1 || value.napi !== 6 || value.maxBinaryBytes !== maxBinaryBytes
+    || !Array.isArray(value.targets)) invalid();
+  const selected = new Set();
+  for (const target of value.targets) {
+    if (target === null || typeof target !== "object" || Array.isArray(target)
+      || !identifier(target.platform) || !identifier(target.arch) || !identifier(target.libc)
+      || !Number.isSafeInteger(target.size) || target.size <= 0 || target.size > maxBinaryBytes
+      || typeof target.sha256 !== "string" || target.sha256.length !== 64
+      || ![...target.sha256].every(character => "0123456789abcdef".includes(character))) invalid();
+    const minimum = libcVersion(target.minimumLibc);
+    if (!minimum || !atLeast(minimum, [2, 31])) invalid();
+    const key = `${target.platform}-${target.arch}-${target.libc}`;
+    if (selected.has(key)) invalid();
+    selected.add(key);
+  }
+  return value;
+}
+
+async function load() {
+  const platform = process.platform;
+  const arch = process.arch;
+  const napi = process.versions.napi;
+  if (platform !== "linux" || arch !== "x64" || !decimal(napi) || Number(napi) < 6) {
+    throw failure("ENOTSUP", "Native seek is unavailable for this runtime");
+  }
+  const report = process.report;
+  const getReport = report?.getReport;
+  if (typeof getReport !== "function") throw failure("ENOTSUP", "Native seek requires a known glibc runtime");
+  const version = libcVersion(Reflect.apply(getReport, report, [])?.header?.glibcVersionRuntime);
+  if (!version || !atLeast(version, [2, 31])) throw failure("ENOTSUP", "Native seek requires glibc 2.31 or newer");
+  const manifestPath = fileURLToPath(new URL("manifest.json", import.meta.url));
+  const manifest = validateManifest(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await readAsset(manifestPath, maxManifestBytes))));
+  const target = manifest.targets.find(candidate => candidate.platform === platform && candidate.arch === arch && candidate.libc === "glibc");
+  if (!target || !atLeast(version, libcVersion(target.minimumLibc))) throw failure("ENOTSUP", "Native seek has no compatible asset");
+  const filename = fileURLToPath(new URL(`${target.platform}-${target.arch}-${target.libc}.node`, import.meta.url));
+  const bytes = await readAsset(filename, maxBinaryBytes);
+  if (bytes.length !== target.size || createHash("sha256").update(bytes).digest("hex") !== target.sha256) {
+    throw failure("EIO", "Native seek asset integrity check failed");
+  }
+  const require = createRequire(import.meta.url);
+  const binding = require(filename);
+  if (binding === null || typeof binding !== "object" || typeof binding.seekEnd !== "function") {
+    throw failure("EIO", "Invalid native seek binding");
+  }
+  return binding;
+}
+
+export function loadBinding() {
+  loading ??= Promise.resolve().then(load);
+  return loading;
+}

package/dist/safe-fs/native/fs-seek/manifest.json

@@ -0,0 +1,46 @@
+{
+  "version": 1,
+  "napi": 6,
+  "maxBinaryBytes": 1048576,
+  "targets": [
+    {
+      "platform": "linux",
+      "arch": "x64",
+      "libc": "glibc",
+      "minimumLibc": "2.31",
+      "size": 17064,
+      "sha256": "7e0b6e24f5e49a0a058e3d95c2aee8b438a753d4f36052537b91084a81ef0d53"
+    }
+  ],
+  "build": {
+    "sourceSha256": "e689d83731bc7ce2ab9632d5927f7f6c8af05a5258b057efa9c1566a888ced6e",
+    "loaderSha256": "337c49bc6744b137633eeb1fd19c19568fdc6d5eb0dfdc34d6bf45dd02573e38",
+    "declarationSha256": "19105e59e4bcc7a1706f74d261a5b09d2404eccaa27cc0bbc9d2af0dc9ef3684",
+    "headers": {
+      "version": "1.9.0",
+      "files": {
+        "node_api.h": {
+          "size": 10370,
+          "sha256": "2d4560831e525b47b060ec8a0864ab73993df9e20215ce9f0fe7b24cd31af32a"
+        },
+        "node_api_types.h": {
+          "size": 1930,
+          "sha256": "a25356630d3058f0a0c8937d9f297e9471e037fda58c2696d8a505c2bd99cb00"
+        },
+        "js_native_api.h": {
+          "size": 31081,
+          "sha256": "0953395662ea63697cd7a77a9320d94aa2829f9c9569abf3a74272b7a2923ce8"
+        },
+        "js_native_api_types.h": {
+          "size": 6896,
+          "sha256": "e785c16a9ce200e801242275cfd59090b029b5dae309a1a258f48d1570bf35ab"
+        }
+      }
+    },
+    "compiler": {
+      "path": "/usr/bin/cc",
+      "sha256": "1b99826121ae6682a634e5efe09bd3e3df58ce58e0b28f849114ab5b89139c26",
+      "version": "x86_64-linux-gnu-gcc-13 (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0\nCopyright (C) 2023 Free Software Foundation, Inc.\nThis is free software; see the source for copying conditions.  There is NO\nwarranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\n"
+    }
+  }
+}

package/dist/safe-fs/node/native-seek.d.ts

@@ -0,0 +1,3 @@
+import type { NativeSeekBinding } from "#safe-fs-native-seek";
+export declare function loadNativeSeekBinding(signal?: AbortSignal): Promise<NativeSeekBinding>;
+export declare function callNativeSeekEnd(binding: NativeSeekBinding, seek: NativeSeekBinding["seekEnd"], descriptor: number): Promise<bigint>;

package/dist/safe-fs/node/native-seek.js

@@ -0,0 +1,54 @@
+import { getSystemErrorName } from "node:util";
+import { FsError, isErrnoCode } from "../contracts/errors.js";
+export async function loadNativeSeekBinding(signal) {
+    signal?.throwIfAborted();
+    const initialization = (async () => {
+        const module = await import("#safe-fs-native-seek");
+        signal?.throwIfAborted();
+        const load = module.loadBinding;
+        signal?.throwIfAborted();
+        if (typeof load !== "function")
+            throw new FsError("EIO");
+        const binding = await Reflect.apply(load, module, []);
+        signal?.throwIfAborted();
+        if (binding === null || typeof binding !== "object" || Array.isArray(binding))
+            throw new FsError("EIO");
+        return binding;
+    })();
+    if (!signal)
+        return initialization;
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+        initialization.then(binding => {
+            signal.removeEventListener("abort", abort);
+            if (signal.aborted)
+                reject(signal.reason);
+            else
+                resolve(binding);
+        }, error => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.aborted ? signal.reason : error);
+        });
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+export async function callNativeSeekEnd(binding, seek, descriptor) {
+    const result = await Reflect.apply(seek, binding, [descriptor]);
+    if (result === null || typeof result !== "object" || Array.isArray(result))
+        throw new FsError("EIO");
+    const { offset, errno } = result;
+    if (typeof offset !== "bigint" || typeof errno !== "number" || !Number.isSafeInteger(errno)
+        || errno < 0 || errno > 2147483647)
+        throw new FsError("EIO");
+    if (errno !== 0) {
+        if (offset !== -1n)
+            throw new FsError("EIO");
+        const code = getSystemErrorName(-errno);
+        throw new FsError(isErrnoCode(code) ? code : "EIO");
+    }
+    if (offset < 0n || offset > 9223372036854775807n)
+        throw new FsError("EIO");
+    return offset;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poe-platform/safe-fs",
-  "version": "0.1.511",
+  "version": "0.1.513",
   "description": "Composable filesystem with a portable core and explicit Node adapters",
   "type": "module",
   "license": "MIT",
@@ -107,6 +107,12 @@
       },
       "browser": "./dist/safe-fs/platform/browser.js",
       "default": "./dist/safe-fs/platform/node.js"
+    },
+    "#safe-fs-native-seek": {
+      "types": "./dist/safe-fs/native/fs-seek/loader.d.ts",
+      "workerd": null,
+      "browser": null,
+      "default": "./dist/safe-fs/native/fs-seek/loader.mjs"
     }
   }
 }