@metalntwx/metal-pay 0.2.0 → 0.3.0

package/dist/file-storage.js

@@ -1,195 +0,0 @@
-// Durable storage for the clearing client's position: one JSON file. Give
-// every process that signs with the same key the same file, so each sees
-// what the others signed.
-//
-// Kept apart from `clearing-client.ts` so the plug-in itself has no
-// filesystem dependency, the way the official batch-settlement client ships
-// its file storage as a separate entry point.
-import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-import { keepHighest, } from "./clearing-client.js";
-/** Thrown inside a write whose lock was taken over while it was working. */
-class LostLock extends Error {
-}
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Whether the process that wrote a lock is gone. Only meaningful for a
- * holder on this machine; an unparsable pid is not treated as dead. */
-function holderIsDead(token) {
-    const pid = Number(token.split(":")[0]);
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return false;
-    }
-    catch (error) {
-        return error.code === "ESRCH";
-    }
-}
-export class FileClearingPositionStorage {
-    path;
-    lockPath;
-    takeoverPath;
-    lockWaitMs;
-    lockStaleMs;
-    constructor(path, options = {}) {
-        this.path = path;
-        this.lockPath = `${path}.lock`;
-        this.takeoverPath = `${path}.lock.takeover`;
-        this.lockWaitMs = options.lockWaitMs ?? 5_000;
-        this.lockStaleMs = options.lockStaleMs ?? 30_000;
-    }
-    async read() {
-        let text;
-        try {
-            text = await readFile(this.path, "utf8");
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return {};
-            throw new Error(`clearing position file ${this.path} is unreadable`, {
-                cause: error,
-            });
-        }
-        // A file that exists but does not parse is not "no record": treating it
-        // as empty would drop the protection the record gives.
-        try {
-            const parsed = JSON.parse(text);
-            if (typeof parsed !== "object" ||
-                parsed === null ||
-                Array.isArray(parsed))
-                throw new Error("not an object");
-            return parsed;
-        }
-        catch (error) {
-            throw new Error(`clearing position file ${this.path} is unreadable`, {
-                cause: error,
-            });
-        }
-    }
-    /** Hold the lock file while `job` runs. The whole file is read, changed
-     * and rewritten, so two writers (two instances, or two processes) must
-     * not overlap or one would drop the other's record.
-     *
-     * The lock is a file created exclusively, holding a token unique to its
-     * holder. A lock left by a writer that died is taken over, and that is
-     * the delicate part: two waiters must not both conclude it is abandoned
-     * and both remove it, or the second would delete the first one's fresh
-     * lock. So removal itself is guarded (see `takeOver`), and a writer whose
-     * lock was taken over finds out before it writes (`stillHeld`). */
-    async locked(job) {
-        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
-        const deadline = Date.now() + this.lockWaitMs;
-        const token = `${process.pid}:${randomUUID()}`;
-        for (;;) {
-            try {
-                await writeFile(this.lockPath, token, { flag: "wx" });
-                break;
-            }
-            catch (error) {
-                if (error.code !== "EEXIST")
-                    throw error;
-                // Every way round this loop is bounded by the wait.
-                if (Date.now() > deadline)
-                    throw new Error(`timed out waiting for the clearing position lock ${this.lockPath}`, { cause: error });
-                const seen = await this.inspect(this.lockPath);
-                if (seen && (holderIsDead(seen.token) || seen.age > this.lockStaleMs))
-                    await this.takeOver(seen.token);
-                // Held by a live writer, unreadable, or already gone: wait and retry.
-                else
-                    await sleep(10);
-            }
-        }
-        const stillHeld = async () => {
-            if ((await this.inspect(this.lockPath))?.token !== token)
-                throw new LostLock(`the clearing position lock ${this.lockPath} was taken over mid-write`);
-        };
-        try {
-            return await job(stillHeld);
-        }
-        finally {
-            // Release only our own lock: if it was taken over, it is not ours.
-            if ((await this.inspect(this.lockPath))?.token === token)
-                await rm(this.lockPath, { force: true });
-        }
-    }
-    async inspect(path) {
-        // One open file for both reads, so the token and the age always belong
-        // to the same lock even if it is replaced meanwhile.
-        let handle;
-        try {
-            handle = await open(path, "r");
-            const info = await handle.stat();
-            const token = await handle.readFile("utf8");
-            return { token, age: Date.now() - info.mtimeMs };
-        }
-        catch {
-            return null;
-        }
-        finally {
-            await handle?.close();
-        }
-    }
-    /** Remove `path` only while it still holds `token`. */
-    async removeIfHolds(path, token) {
-        if ((await this.inspect(path))?.token === token)
-            await rm(path, { force: true });
-    }
-    /** Remove an abandoned lock, at most one waiter at a time. The takeover
-     * file is itself created exclusively, so only one waiter is ever inside;
-     * it removes the lock only if it is still the abandoned one it saw. A
-     * waiter that arrives later finds either no lock or a fresh one from a
-     * new holder, and leaves it alone. */
-    async takeOver(abandoned) {
-        const mine = `${process.pid}:${randomUUID()}`;
-        try {
-            await writeFile(this.takeoverPath, mine, { flag: "wx" });
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            // Another waiter is doing it. If that waiter itself died here, clear
-            // its marker so takeovers are not blocked for good.
-            const other = await this.inspect(this.takeoverPath);
-            if (other && (holderIsDead(other.token) || other.age > this.lockStaleMs))
-                await this.removeIfHolds(this.takeoverPath, other.token);
-            await sleep(10);
-            return;
-        }
-        try {
-            if ((await this.inspect(this.lockPath))?.token === abandoned)
-                await rm(this.lockPath, { force: true });
-        }
-        finally {
-            await this.removeIfHolds(this.takeoverPath, mine);
-        }
-    }
-    async get(key) {
-        return (await this.read())[key];
-    }
-    set(key, position) {
-        return this.locked(async (stillHeld) => {
-            const all = await this.read();
-            // Merged under the lock: another client may have signed since the
-            // caller read its position, and the high-water mark must not go down.
-            all[key] = keepHighest(all[key], position);
-            // Write beside the file under a name no other writer shares, then swap
-            // it in, so a crash mid-write cannot leave a truncated record.
-            const next = `${this.path}.${randomUUID()}.tmp`;
-            try {
-                await writeFile(next, `${JSON.stringify(all, null, 2)}\n`, {
-                    mode: 0o600,
-                });
-                // A writer that hung long enough to be taken over must not swap in
-                // what it read before the newer writer's change.
-                await stillHeld();
-                await rename(next, this.path);
-            }
-            catch (error) {
-                await rm(next, { force: true });
-                throw error;
-            }
-        });
-    }
-}