keri-ts 2.0.1 → 2.1.0

package/esm/keri/npm/src/db/core/path-manager.js

@@ -5,7 +5,8 @@
  * Uses composition pattern instead of inheritance.
  */
 import * as dntShim from "../../_dnt.shims.js";
-import { isAbsolute, join } from "../../deps/jsr.io/@std/path/1.1.6/mod.js";
+import { dirname, extname, isAbsolute, join, resolve } from "../../deps/jsr.io/@std/path/1.1.6/mod.js";
+import { accessSync, constants } from "node:fs";
 import { action } from "effection";
 import { InvalidPathNameError, PathError } from "../../core/errors.js";
 import { consoleLogger } from "../../core/logger.js";
@@ -20,9 +21,27 @@ function isNotFoundLike(error) {
     return error instanceof dntShim.Deno.errors.NotFound
         || hasErrorCode(error, ["ENOENT"]);
 }
-function isPermissionDeniedLike(error) {
-    return error instanceof dntShim.Deno.errors.PermissionDenied
-        || hasErrorCode(error, ["EACCES", "EPERM"]);
+/** The temp root hio uses: `/tmp` on macOS, otherwise Python's `tempfile.gettempdir` order. */
+function tempHeadDir() {
+    if (dntShim.Deno.build.os === "darwin")
+        return "/tmp";
+    return dntShim.Deno.env.get("TMPDIR") || dntShim.Deno.env.get("TEMP") || dntShim.Deno.env.get("TMP") || "/tmp";
+}
+/** True when this process may read and write `path`, like `os.access(path, F_OK | R_OK | W_OK)`. */
+function isAccessible(path) {
+    try {
+        accessSync(path, constants.F_OK | constants.R_OK | constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Refuse an absolute name or base, which would escape the head directory. */
+function assertRelative(value, label) {
+    if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
+        throw new InvalidPathNameError(`Not relative ${label}=${value} path.`);
+    }
 }
 /** Defaults for the path manager */
 export const PATH_DEFAULTS = {
@@ -32,7 +51,6 @@ export const PATH_DEFAULTS = {
     altHeadDirPath: "~",
     altTailDirPath: ".tufa/db",
     altCleanTailDirPath: ".tufa/clean/db",
-    tempHeadDir: "/tmp",
     tempPrefix: "keri_lmdb_",
     tempSuffix: "_test",
     perm: 0o1700, // sticky + owner rwx
@@ -50,10 +68,11 @@ export const PATH_DEFAULTS = {
  * - centralize path naming constraints so higher-level DB/config wrappers do
  *   not each reimplement filesystem policy
  *
- * Current `keri-ts` difference:
- * - this is a local abstraction, not a direct KERIpy class port; it encodes
- *   the same path-layout intent while handling Deno/Node runtime differences in
- *   one place
+ * Current `keri-ts` differences from hio `Filer`, which it otherwise follows:
+ * - composition rather than inheritance, so stores own one instance
+ * - a temp store uses one stable directory per name instead of a fresh
+ *   `mkdtemp` per open, so its data survives a close and reopen; temp stores are
+ *   never shared with KERIpy
  */
 export class PathManager {
     constructor(options = {}, defaults) {
@@ -148,11 +167,20 @@ export class PathManager {
             writable: true,
             value: void 0
         });
+        // the temporary directory holding `path`, when temp
+        Object.defineProperty(this, "tempRoot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         this.defaults = { ...PATH_DEFAULTS, ...defaults };
-        this._name = options.name || "main";
-        this.base = options.base || "";
+        this._name = options.name ?? "main";
+        this.base = options.base ?? "";
+        assertRelative(this._name, "name");
+        assertRelative(this.base, "base");
         this.temp = options.temp || false;
-        this.headDirPath = options.headDirPath || this.defaults.headDirPath;
+        this.headDirPath = options.headDirPath ?? this.defaults.headDirPath;
         this.perm = options.perm ?? this.defaults.perm;
         this.path = null;
         this.filed = options.filed || false;
@@ -168,18 +196,9 @@ export class PathManager {
         return this._name;
     }
     set name(value) {
-        // Check if path is absolute
-        if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
-            throw new InvalidPathNameError(`Not relative name=${value} path.`);
-        }
+        assertRelative(value, "name");
         this._name = value;
     }
-    _getTempPath() {
-        const tempDir = dntShim.Deno.env.get("TMPDIR") || dntShim.Deno.env.get("TMP")
-            || dntShim.Deno.env.get("TEMP") || "/tmp";
-        const tempName = `${this.defaults.tempPrefix}${this.name}${this.defaults.tempSuffix}`;
-        return join(tempDir, tempName);
-    }
     /** Resolve user home directory with a Windows-aware fallback chain. */
     _resolveHomeDir() {
         const home = dntShim.Deno.env.get("HOME");
@@ -205,95 +224,21 @@ export class PathManager {
         }
         return path;
     }
-    _getPrimaryPath(headDirPath, clean) {
-        // head / tail / base / name
-        // Expand ~ to HOME directory
-        let head = headDirPath;
-        head = this._pathExpandTilde(head);
-        let tail;
-        if (clean) {
-            tail = this.defaults.cleanTailDirPath;
-        }
-        else {
-            tail = this.defaults.tailDirPath;
-        }
-        return this.base
-            ? join(head, tail, this.base, this.name)
-            : join(head, tail, this.name);
-    }
-    _getAltPath(clean) {
-        // HOME or ~ / tail / base / name
-        let head = dntShim.Deno.env.get("HOME") || "~";
-        head = this._pathExpandTilde(head);
-        let tail;
-        if (clean) {
-            tail = this.defaults.altCleanTailDirPath;
-        }
-        else {
-            tail = this.defaults.altTailDirPath;
-        }
-        return this.base
-            ? join(head, tail, this.base, this.name)
-            : join(head, tail, this.name);
-    }
-    /*
-     * Creates a file path based on head, tail, base, and name. Ensure path is created and optionally reuse it.
-     * @param options path creation options
-     * @returns File path to a persistent file or directory
-     */
-    _getPersistentPaths(options = {}) {
-        const headDirPath = options.headDirPath ?? this.headDirPath;
-        const clean = options.clean || false;
-        const primary = this._getPrimaryPath(headDirPath, clean);
-        const alt = this._getAltPath(clean);
-        return [primary, alt];
-    }
-    _getPaths(options = {}) {
-        const [primary, alt] = this._getPersistentPaths(options);
-        const tempPath = this._getTempPath();
-        return [primary, alt, tempPath];
-    }
     /**
      * Helper: Convert Promise-based file system operations to Effection operations
      * This ensures proper structured concurrency and cancellation support
      */
+    /** True when `path` exists; any failure to stat means absent, like `os.path.exists`. */
     *statOp(path) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.stat(path)
-                .then(() => resolve(true))
-                .catch((error) => {
-                if (isNotFoundLike(error)) {
-                    resolve(false);
-                }
-                else {
-                    reject(error);
-                }
-            });
+        return yield* action((resolve) => {
+            dntShim.Deno.stat(path).then(() => resolve(true)).catch(() => resolve(false));
             return () => { };
         });
     }
-    *accessOp(path) {
-        return yield* action((resolve, reject) => {
-            // In Deno, we check access by stating or trying to read/write.
-            // Simplified to checking existence and relying on OS permissions for now
-            dntShim.Deno.stat(path)
-                .then(() => resolve(true))
-                .catch(() => resolve(false));
-            return () => { };
-        });
-    }
-    *mkdirOp(path, perm) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.mkdir(path, { recursive: true, mode: perm })
-                .then(() => resolve(true))
-                .catch((error) => {
-                if (isPermissionDeniedLike(error)) {
-                    resolve(false);
-                }
-                else {
-                    reject(error);
-                }
-            });
+    /** Create a directory and its parents with default permissions, like `os.makedirs`. */
+    *mkdirOp(path) {
+        yield* action((resolve, reject) => {
+            dntShim.Deno.mkdir(path, { recursive: true }).then(() => resolve()).catch(reject);
             return () => { };
         });
     }
@@ -336,152 +281,93 @@ export class PathManager {
         });
     }
     /**
-     * Reopen/create the directory or file path.
-     * Replicates KERIpy/HIO Filer.remake logic:
-     * - Tries primary path (/usr/local/var/keri/*) first
-     * - Falls back to alt path (~/.tufa/*) on OS errors or access issues
-     *
-     * Returns Effection Operation with true if path is created and accessible, false otherwise.
+     * Close, then open the path, mirroring hio `Filer.reopen`. An existing path
+     * is kept only when `reuse` is set; otherwise the path is made again.
      */
     *reopen(options = {}) {
-        this._applyOptions(options);
-        const headDirPath = options.headDirPath ?? this.headDirPath;
-        const clean = options.clean || false;
-        const reuse = options.reuse || false;
-        const clear = options.clear || false;
-        const [primary, alt, tempPath] = this._getPaths({
-            ...options,
-            headDirPath,
-            clean,
-        });
-        const resolved = yield* this._resolvePath({
-            primary,
-            alt,
-            tempPath,
-            headDirPath,
-            reuse,
-        });
-        this.headDirPath = resolved.headDirPath;
-        if (clear) {
-            yield* this._clearPath(resolved.path);
-        }
-        if (!this.filed) {
-            yield* this._ensureDirectoryExists(resolved.path);
-        }
-        this.path = resolved.path;
-        this.opened = true;
-        return this.opened;
-    }
-    /** Update instance fields from caller-provided options. */
-    _applyOptions(options) {
+        yield* this.close(options.clear ?? false);
         this.temp = options.temp ?? this.temp;
+        this.headDirPath = options.headDirPath ?? this.headDirPath;
         this.perm = options.perm ?? this.perm;
         this.mode = options.mode ?? this.mode;
         this.fext = options.fext ?? this.fext;
-    }
-    /**
-     * Select which concrete path to use: temp, primary with alt fallback,
-     * reuse with alt fallback, or primary directly (custom headDirPath).
-     */
-    *_resolvePath(params) {
-        if (this.temp) {
-            return { path: params.tempPath, headDirPath: params.headDirPath };
+        if (!this.path || !options.reuse || !(yield* this.statOp(this.path))) {
+            this.path = yield* this.remake(options.clean ?? false);
         }
-        if (params.reuse) {
-            return yield* this._reuseOrFallback(params.primary, params.alt, params.headDirPath);
-        }
-        return yield* this._createOrFallback(params.primary, params.alt, params.headDirPath);
-    }
-    /**
-     * Try to use or create the primary path. If creation fails (e.g. EACCES),
-     * fall back to the alt path. Throws if alt path also fails.
-     */
-    *_createOrFallback(primary, alt, headDirPath) {
-        const exists = yield* this.statOp(primary);
-        if (exists) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Creating directory at ${primary}`);
-        const created = yield* this.mkdirOp(primary, this.perm);
-        if (created) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Failed to create primary path, falling back to alt path`);
-        const altReady = yield* this._ensurePathAccessible(alt);
-        if (!altReady) {
-            this.logger.error(`Alt path not available at ${alt}`);
-            throw new PathError(`Alt path not available at ${alt}`);
-        }
-        return { path: alt, headDirPath: this.defaults.altHeadDirPath };
+        this.opened = true;
+        return true;
     }
     /**
-     * Verify the primary path exists and is accessible for reuse.
-     * If not accessible and using the default head dir, fall back to alt.
+     * Choose and create the path, mirroring hio `Filer.remake`. `headDirPath` is
+     * left alone on fallback, so each open retries the primary location first.
      */
-    *_reuseOrFallback(primary, alt, headDirPath) {
-        const exists = yield* this.statOp(primary);
-        const accessible = exists ? yield* this.accessOp(primary) : false;
-        if (exists && accessible) {
-            return { path: primary, headDirPath };
+    *remake(clean) {
+        const tail = clean ? this.defaults.cleanTailDirPath : this.defaults.tailDirPath;
+        const name = this.fileName();
+        if (this.temp) {
+            this.tempRoot = join(tempHeadDir(), `${this.defaults.tempPrefix}${this.name}${this.defaults.tempSuffix}`);
+            const path = this.filed || this.extensioned ? join(this.tempRoot, name) : this.tempRoot;
+            yield* this.makePath(path);
+            return path;
         }
-        this.logger.debug(`Reuse path unavailable, attempting to (re)create primary path`);
-        const primaryReady = yield* this._ensurePathAccessible(primary);
-        if (primaryReady) {
-            return { path: primary, headDirPath };
+        let path = resolve(this._pathExpandTilde(join(this.headDirPath, tail, this.base, name)));
+        if (clean && (yield* this.statOp(path)))
+            yield* this.rmOp(path);
+        if (!(yield* this.statOp(path))) {
+            try {
+                yield* this.makePath(path);
+            }
+            catch (cause) {
+                this.logger.debug(`Failed to create ${path}, falling back to alt path`);
+                path = yield* this.makeAltPath(clean, name, cause);
+            }
         }
-        this.logger.debug(`Primary path unavailable, trying alt path`);
-        const altReady = yield* this._ensurePathAccessible(alt);
-        if (!altReady) {
-            this.logger.debug(`Alt path not available: ${alt}`);
+        else if (!isAccessible(path)) {
+            path = yield* this.makeAltPath(clean, name);
         }
-        return { path: alt, headDirPath: this.defaults.altHeadDirPath };
+        if (!this.extensioned && dntShim.Deno.build.os !== "windows")
+            dntShim.Deno.chmodSync(path, this.perm);
+        return path;
     }
-    /**
-     * Ensure a path exists and is accessible, creating it if necessary.
-     * Returns true if the path is ready for use.
-     */
-    *_ensurePathAccessible(path) {
-        const exists = yield* this.statOp(path);
-        if (!exists) {
-            this.logger.debug(`Creating directory at ${path}`);
-            return yield* this.mkdirOp(path, this.perm);
-        }
-        return yield* this.accessOp(path);
+    /** Name the path uses, with `fext` added to an extensionless file name. */
+    fileName() {
+        return (this.filed || this.extensioned) && !extname(this.name) ? `${this.name}.${this.fext}` : this.name;
     }
-    /** Remove existing file or directory at path. */
-    *_clearPath(path) {
-        const stat = yield* this.statFileOp(path);
-        if (stat.isDirectory || stat.isFile) {
-            yield* this.rmOp(path);
+    /** Create a directory path, or a file path's parents and the file when `filed`. */
+    *makePath(path) {
+        if (!this.filed && !this.extensioned) {
+            yield* this.mkdirOp(path);
+            return;
         }
+        yield* this.mkdirOp(dirname(path));
+        if (this.filed)
+            dntShim.Deno.openSync(path, { read: true, write: true, create: true, mode: this.perm }).close();
     }
-    /** Ensure the directory at path exists and is accessible, creating it if needed. */
-    *_ensureDirectoryExists(path) {
-        const exists = yield* this.statOp(path);
-        if (!exists) {
-            this.logger.debug(`Creating directory at ${path}`);
-            const created = yield* this.mkdirOp(path, this.perm);
-            if (!created) {
-                this.logger.debug(`Failed to create directory at ${path}`);
-            }
+    /** Make the home-directory alternate, failing when it is unavailable too. */
+    *makeAltPath(clean, name, cause) {
+        const tail = clean ? this.defaults.altCleanTailDirPath : this.defaults.altTailDirPath;
+        const path = resolve(this._pathExpandTilde(this.defaults.altHeadDirPath), tail, this.base, name);
+        try {
+            if (!(yield* this.statOp(path)))
+                yield* this.makePath(path);
         }
-        else {
-            const accessible = yield* this.accessOp(path);
-            if (!accessible) {
-                this.logger.debug(`Path exists but is not accessible: ${path}`);
-            }
+        catch (error) {
+            this.logger.error(`Alt path not available at ${path}`);
+            throw new PathError(`Alt path not available at ${path}`, { cause: cause ?? error });
         }
+        return path;
     }
     /**
-     * Close the path manager
-     * If clear is true, removes the directory/file
-     * Uses Effection for structured concurrency
+     * Mark closed, removing the path when `clear` is set. The path is retained so
+     * a later `reopen({ reuse: true })` finds it, as hio does.
      */
     *close(clear = false) {
         if (clear && this.path) {
             yield* this.rmOp(this.path);
+            if (this.tempRoot)
+                yield* this.rmOp(this.tempRoot);
+            this.tempRoot = null;
         }
-        this.path = null;
         this.opened = false;
         return true;
     }

package/esm/keri/npm/src/db/core/store-owner.js

@@ -0,0 +1,104 @@
+/**
+ * Composition seam between typed domain stores and a `DBer` backend.
+ *
+ * ADR-0015 owns the store contract. A `StoreOwner` is a domain store such as
+ * `Noter` or `Reger`: it borrows no backend knowledge and delegates lifecycle
+ * and transactions to the one store it composes over.
+ */
+import { DatabaseNotOpenError } from "../../core/errors.js";
+/** A domain store composed over one `DBer`. */
+export class StoreOwner {
+    constructor(store) {
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: store
+        });
+    }
+    get name() {
+        return this.store.name;
+    }
+    get base() {
+        return this.store.base;
+    }
+    get opened() {
+        return this.store.opened;
+    }
+    get readonly() {
+        return this.store.readonly;
+    }
+    get temp() {
+        return this.store.temp;
+    }
+    get inWriteTransaction() {
+        return this.store.inWriteTransaction;
+    }
+    /** Filesystem path on an LMDB-backed store; `null` elsewhere. */
+    get path() {
+        return this.store.path ?? null;
+    }
+    /** Native LMDB environment for low-level tests only; `null` on other backends. */
+    get env() {
+        return this.store.env ?? null;
+    }
+    get writeVersion() {
+        return this.store.writeVersion;
+    }
+    transaction(fn) {
+        return this.store.transaction(fn);
+    }
+    flushed() {
+        return this.store.flushed();
+    }
+    refreshRead() {
+        this.store.refreshRead();
+    }
+    hasTable(name) {
+        return this.store.hasTable(name);
+    }
+    getVer() {
+        return this.store.getVer();
+    }
+    setVer(val) {
+        this.store.setVer(val);
+    }
+    close(clear = false) {
+        return this.store.close(clear);
+    }
+}
+/**
+ * Open a ready owner for its caller, closing an unreturned acquisition on
+ * failure or cancellation without masking the original error.
+ */
+export function* openOwner(owner, label, options) {
+    let delivered = false;
+    let failure;
+    try {
+        if (!(yield* owner.reopen(options)))
+            throw new DatabaseNotOpenError(`Failed to open ${label}`);
+        delivered = true;
+        return owner;
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        if (!delivered) {
+            try {
+                yield* owner.close();
+            }
+            catch (error) {
+                if (failure) {
+                    // deno-lint-ignore no-unsafe-finally -- Preserve the operation failure alongside shutdown failure.
+                    throw new AggregateError([failure.error, error], "Database acquisition and close failed", {
+                        cause: failure.error,
+                    });
+                }
+                // deno-lint-ignore no-unsafe-finally -- A cancelled acquisition still reports its close failure.
+                throw error;
+            }
+        }
+    }
+}