@nowcrew/daemon 0.5.26 → 0.5.28

package/dist/execution-journal-lock.js

@@ -1,421 +0,0 @@
-import { mkdir, open, readFile, readdir, rename, rm, rmdir, stat, unlink, } from "node:fs/promises";
-import { renameSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { join, resolve } from "node:path";
-import { z } from "zod";
-const OwnerSchema = z.object({
-    pid: z.number().int().positive(),
-    processIdentity: z.string().min(1),
-    token: z.string().uuid(),
-}).strict();
-export class JournalLockedError extends Error {
-    journalPath;
-    ownerPid;
-    constructor(message, diagnostics = {}) {
-        super(message);
-        this.name = "JournalLockedError";
-        if (diagnostics.journalPath !== undefined)
-            this.journalPath = diagnostics.journalPath;
-        if (diagnostics.ownerPid !== undefined)
-            this.ownerPid = diagnostics.ownerPid;
-    }
-}
-export class JournalLockCorruptionError extends Error {
-    constructor(path, cause) {
-        super(`Invalid execution journal lock: ${path}`, { cause });
-        this.name = "JournalLockCorruptionError";
-    }
-}
-export const defaultJournalLockFileSystem = {
-    mkdir,
-    readFile: (path) => readFile(path, "utf8"),
-    readdir,
-    rename,
-    renameSync,
-    rm,
-    rmdir,
-    stat,
-    unlink,
-    writeDurableFile: async (path, contents) => {
-        const handle = await open(path, "wx", 0o600);
-        try {
-            await handle.writeFile(contents, "utf8");
-            await handle.sync();
-        }
-        finally {
-            await handle.close();
-        }
-    },
-};
-const defaultRegistry = { leases: new Map() };
-export function createJournalLeaseRegistry() {
-    return { leases: new Map() };
-}
-const codeOf = (error) => error instanceof Error && "code" in error ? error.code : undefined;
-const ownerFileName = (token) => `owner.${token}.json`;
-const releasedLockName = (token) => `.journal.released.${token}.lock`;
-const RELEASED_LOCK_PATTERN = /^\.journal\.released\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.lock$/i;
-const MAX_RELEASED_LOCK_CLEANUP = 8;
-const throwIfAborted = (signal) => {
-    if (signal?.aborted)
-        throw signal.reason ?? new Error("Journal close aborted");
-};
-function awaitAbortable(operation, signal) {
-    if (signal === undefined)
-        return operation;
-    throwIfAborted(signal);
-    return new Promise((resolveOperation, rejectOperation) => {
-        let settled = false;
-        const settle = (continuation) => {
-            if (settled)
-                return;
-            settled = true;
-            signal.removeEventListener("abort", onAbort);
-            continuation();
-        };
-        const onAbort = () => settle(() => {
-            rejectOperation(signal.reason ?? new Error("Journal close aborted"));
-        });
-        signal.addEventListener("abort", onAbort, { once: true });
-        if (signal.aborted)
-            onAbort();
-        operation.then((value) => settle(() => resolveOperation(value)), (error) => settle(() => rejectOperation(error)));
-    });
-}
-async function parseLockOwner(lockDirectory, fileName, fileSystem) {
-    const path = join(lockDirectory, fileName);
-    try {
-        const owner = OwnerSchema.parse(JSON.parse(await fileSystem.readFile(path)));
-        if (fileName !== ownerFileName(owner.token))
-            throw new Error("owner token does not match filename");
-        return owner;
-    }
-    catch (error) {
-        throw new JournalLockCorruptionError(path, error);
-    }
-}
-export async function inspectJournalLock(options) {
-    const fileSystem = options.fileSystem ?? defaultJournalLockFileSystem;
-    const lockDirectory = join(options.directory, ".journal.lock");
-    const orphanGraceMs = options.orphanGraceMs ?? 30_000;
-    const now = options.now ?? (() => new Date());
-    const missingDuringOwnerRead = (error) => codeOf(error) === "ENOENT"
-        || (error instanceof Error && codeOf(error.cause) === "ENOENT");
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        let names;
-        try {
-            names = (await fileSystem.readdir(lockDirectory)).map(String).sort();
-        }
-        catch (error) {
-            if (codeOf(error) === "ENOENT") {
-                return { status: "unlocked", detail: "lock directory does not exist" };
-            }
-            return { status: "corrupt", detail: `lock directory cannot be read: ${error.message}` };
-        }
-        if (names.length === 0) {
-            try {
-                const lockStat = await fileSystem.stat(lockDirectory);
-                const ageMs = now().valueOf() - lockStat.mtimeMs;
-                return ageMs < orphanGraceMs
-                    ? { status: "installing", detail: "lock owner installation is in progress" }
-                    : { status: "stale", detail: "empty lock directory exceeded the owner installation grace period" };
-            }
-            catch (error) {
-                if (codeOf(error) === "ENOENT" && attempt === 0)
-                    continue;
-                if (codeOf(error) === "ENOENT") {
-                    return { status: "unlocked", detail: "lock directory disappeared during inspection" };
-                }
-                return { status: "corrupt", detail: `empty lock directory cannot be inspected: ${error.message}` };
-            }
-        }
-        if (names.length !== 1 || !/^owner\.[0-9a-f-]+\.json$/i.test(names[0])) {
-            return { status: "corrupt", detail: "lock directory must contain one owner" };
-        }
-        let owner;
-        try {
-            owner = await parseLockOwner(lockDirectory, names[0], fileSystem);
-        }
-        catch (error) {
-            if (attempt === 0 && missingDuringOwnerRead(error))
-                continue;
-            return { status: "corrupt", detail: error.message };
-        }
-        let inspection;
-        try {
-            const identity = await options.inspectIdentity(owner.pid);
-            inspection = identity === owner.processIdentity
-                ? {
-                    status: "owned",
-                    ownerPid: owner.pid,
-                    ownerAlive: true,
-                    detail: `owned by live process ${owner.pid}`,
-                }
-                : {
-                    status: "stale",
-                    ownerPid: owner.pid,
-                    ownerAlive: false,
-                    detail: `owner process ${owner.pid} is absent or its identity changed`,
-                };
-        }
-        catch (error) {
-            inspection = {
-                status: "corrupt",
-                ownerPid: owner.pid,
-                detail: `owner process cannot be inspected: ${error.message}`,
-            };
-        }
-        try {
-            const confirmedOwner = await parseLockOwner(lockDirectory, names[0], fileSystem);
-            const confirmedNames = (await fileSystem.readdir(lockDirectory)).map(String).sort();
-            const unchanged = JSON.stringify(confirmedOwner) === JSON.stringify(owner)
-                && JSON.stringify(confirmedNames) === JSON.stringify(names);
-            if (!unchanged && attempt === 0)
-                continue;
-            if (!unchanged)
-                return { status: "corrupt", detail: "lock snapshot changed during bounded inspection" };
-            return inspection;
-        }
-        catch (error) {
-            if (attempt === 0 && missingDuringOwnerRead(error))
-                continue;
-            if (missingDuringOwnerRead(error)) {
-                return { status: "corrupt", detail: "lock snapshot remained unstable after bounded inspection" };
-            }
-            return { status: "corrupt", detail: error.message };
-        }
-    }
-    return { status: "corrupt", detail: "lock snapshot remained unstable after bounded inspection" };
-}
-function processLeaseMap(registry) {
-    return registry.leases;
-}
-export function createJournalLease(options) {
-    const fileSystem = options.fileSystem ?? defaultJournalLockFileSystem;
-    const registry = processLeaseMap(options.registry ?? defaultRegistry);
-    const now = options.now ?? (() => new Date());
-    const orphanGraceMs = options.orphanGraceMs ?? 30_000;
-    const journalPath = resolve(options.directory);
-    const lockDirectory = join(options.directory, ".journal.lock");
-    let attached = false;
-    let status = "open";
-    const cleanupReleasedDirectory = async (path) => {
-        try {
-            await fileSystem.rm(path, { recursive: true, force: true });
-            await options.syncDirectory(options.directory);
-        }
-        catch { /* released tombstones never block ownership or reverse a committed close */ }
-    };
-    const cleanupReleasedDirectories = async () => {
-        let names;
-        try {
-            names = (await fileSystem.readdir(options.directory)).map(String).sort();
-        }
-        catch {
-            return;
-        }
-        await Promise.all(names
-            .filter((name) => RELEASED_LOCK_PATTERN.test(name))
-            .slice(0, MAX_RELEASED_LOCK_CLEANUP)
-            .map((name) => cleanupReleasedDirectory(join(options.directory, name))));
-    };
-    const readOwner = async () => {
-        let names;
-        try {
-            names = (await fileSystem.readdir(lockDirectory)).map(String).sort();
-        }
-        catch (error) {
-            if (codeOf(error) === "ENOENT")
-                return null;
-            throw error;
-        }
-        if (names.length === 0) {
-            const lockStat = await fileSystem.stat(lockDirectory);
-            if (now().valueOf() - lockStat.mtimeMs < orphanGraceMs) {
-                throw new JournalLockedError("Execution journal lock owner installation is in progress", { journalPath });
-            }
-            try {
-                await fileSystem.rmdir(lockDirectory);
-                await options.syncDirectory(options.directory);
-            }
-            catch (error) {
-                if (codeOf(error) !== "ENOENT" && codeOf(error) !== "ENOTEMPTY")
-                    throw error;
-            }
-            return null;
-        }
-        if (names.length !== 1 || !/^owner\.[0-9a-f-]+\.json$/i.test(names[0])) {
-            throw new JournalLockCorruptionError(lockDirectory, new Error("lock directory must contain one owner"));
-        }
-        return { owner: await parseLockOwner(lockDirectory, names[0], fileSystem), fileName: names[0] };
-    };
-    const validateInstalledOwner = async (lease) => {
-        const observed = await readOwner();
-        if (observed === null
-            || observed.fileName !== lease.ownerFile
-            || JSON.stringify(observed.owner) !== JSON.stringify(lease.owner)) {
-            throw new JournalLockCorruptionError(lockDirectory, new Error("installed owner changed"));
-        }
-    };
-    const finishInstall = async (lease) => {
-        if (!lease.ownerInstalled) {
-            try {
-                await fileSystem.rename(lease.ownerTemp, join(lockDirectory, lease.ownerFile));
-            }
-            catch (error) {
-                if (codeOf(error) !== "ENOENT")
-                    throw error;
-                await validateInstalledOwner(lease);
-            }
-            lease.ownerInstalled = true;
-        }
-        await validateInstalledOwner(lease);
-        if (!lease.lockDirectorySynced) {
-            await options.syncDirectory(lockDirectory);
-            lease.lockDirectorySynced = true;
-        }
-        if (!lease.executionsDirectorySynced) {
-            await options.syncDirectory(options.directory);
-            lease.executionsDirectorySynced = true;
-        }
-        await fileSystem.rm(lease.ownerTemp, { force: true }).catch(() => undefined);
-    };
-    const install = async () => {
-        const token = randomUUID();
-        const owner = OwnerSchema.parse({
-            pid: options.currentPid,
-            processIdentity: await options.captureCurrentIdentity(),
-            token,
-        });
-        const ownerTemp = join(options.directory, `.journal-owner.${token}.tmp`);
-        await fileSystem.writeDurableFile(ownerTemp, `${JSON.stringify(owner)}\n`);
-        try {
-            for (;;) {
-                try {
-                    await fileSystem.mkdir(lockDirectory);
-                    const lease = {
-                        owner,
-                        ownerFile: ownerFileName(token),
-                        ownerTemp,
-                        refs: 1,
-                        ownerInstalled: false,
-                        lockDirectorySynced: false,
-                        executionsDirectorySynced: false,
-                        releasing: false,
-                    };
-                    registry.set(options.directory, lease);
-                    attached = true;
-                    await finishInstall(lease);
-                    return lease;
-                }
-                catch (error) {
-                    if (codeOf(error) !== "EEXIST")
-                        throw error;
-                }
-                const observed = await readOwner();
-                if (observed === null)
-                    continue;
-                const identity = await options.inspectIdentity(observed.owner.pid);
-                if (identity === observed.owner.processIdentity) {
-                    throw new JournalLockedError(`Execution journal is locked by process ${observed.owner.pid}`, { journalPath, ownerPid: observed.owner.pid });
-                }
-                await options.hooks?.beforeRemoveObservedOwner?.(observed.owner);
-                try {
-                    await fileSystem.unlink(join(lockDirectory, observed.fileName));
-                }
-                catch (error) {
-                    if (codeOf(error) !== "ENOENT")
-                        throw error;
-                    continue;
-                }
-                try {
-                    await fileSystem.rmdir(lockDirectory);
-                    await options.syncDirectory(options.directory);
-                }
-                catch (error) {
-                    if (codeOf(error) !== "ENOENT" && codeOf(error) !== "ENOTEMPTY")
-                        throw error;
-                }
-            }
-        }
-        finally {
-            if (!attached)
-                await fileSystem.rm(ownerTemp, { force: true }).catch(() => undefined);
-        }
-    };
-    const acquire = async () => {
-        if (status !== "open") {
-            throw new JournalLockedError(`Journal lease is ${status}`, { journalPath });
-        }
-        if (attached) {
-            const lease = registry.get(options.directory);
-            if (lease === undefined) {
-                throw new JournalLockedError("In-process journal lease is missing", { journalPath });
-            }
-            await finishInstall(lease);
-            return;
-        }
-        const existing = registry.get(options.directory);
-        if (existing !== undefined) {
-            if (existing.releasing) {
-                throw new JournalLockedError("Journal lease release is pending", {
-                    journalPath,
-                    ownerPid: existing.owner.pid,
-                });
-            }
-            await finishInstall(existing);
-            existing.refs += 1;
-            attached = true;
-            return;
-        }
-        void cleanupReleasedDirectories();
-        await install();
-    };
-    const close = async (closeOptions = {}) => {
-        if (status === "closed")
-            return;
-        const signal = closeOptions.signal;
-        throwIfAborted(signal);
-        if (!attached) {
-            status = "closed";
-            return;
-        }
-        const lease = registry.get(options.directory);
-        if (lease === undefined) {
-            throw new JournalLockedError("In-process journal lease is missing", { journalPath });
-        }
-        if (status === "open" && lease.refs > 1) {
-            throwIfAborted(signal);
-            lease.refs -= 1;
-            attached = false;
-            status = "closed";
-            return;
-        }
-        status = "closing";
-        lease.releasing = true;
-        await awaitAbortable((async () => {
-            await validateInstalledOwner(lease);
-            await options.hooks?.beforeReleaseOwner?.(lease.owner, {
-                ...(signal === undefined ? {} : { signal }),
-            });
-            await validateInstalledOwner(lease);
-        })(), signal);
-        throwIfAborted(signal);
-        const releasedDirectory = join(options.directory, releasedLockName(lease.owner.token));
-        fileSystem.renameSync(lockDirectory, releasedDirectory);
-        lease.refs -= 1;
-        registry.delete(options.directory);
-        attached = false;
-        status = "closed";
-        void cleanupReleasedDirectory(releasedDirectory);
-    };
-    return {
-        acquire,
-        assertUsable: () => {
-            if (status !== "open") {
-                throw new JournalLockedError(`Execution journal lease is ${status}`, { journalPath });
-            }
-        },
-        close,
-    };
-}