@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/file-lock-queue.js

@@ -1,219 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Waiter tickets for `withFileLock`: who is queued for a contended lock, in
- * what order, and whose turn it is.
- *
- * The tickets decide the grant: only the head of the queue may attempt the
- * lock, so the position printed is the position honoured. A free-for-all of
- * `mkdir` polls would let later arrivals polling at 100 ms take every free
- * moment from a waiter whose poll interval had backed off to 2 s, so a run
- * told it was next could watch later runs take the lock in turn.
- *
- * A ticket is a file in `<lock>.waiters/` named
- * `<startedAtMs>-<pid>-<uuid>`. Arrival order is the wait start, with the
- * whole name as a tie-break so every reader sorts the queue identically.
- * Because a ticket blocks everyone behind it, a ticket whose owner is
- * gone must not hold the queue: a dead PID (or a reused one, where the
- * start-tick check can tell) drops out and its ticket is removed, and a
- * ticket its owner has stopped refreshing drops out without being removed,
- * which covers a stopped (^Z) waiter and a reused PID on platforms with no
- * start tick.
- */
-import { randomUUID } from 'node:crypto';
-import { readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { toError } from '../utils/errors.js';
-import { ensureDir } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { isLockOwnerAlive, readProcessStartTick } from './file-lock-owner.js';
-/**
- * How often a waiter refreshes its ticket. Every wait loop iteration
- * refreshes once this much time has passed, and no caller sleeps longer
- * than a few seconds between iterations.
- */
-const WAITER_HEARTBEAT_MS = 5_000;
-/**
- * A ticket not refreshed for this long is skipped when the queue is read.
- * Six heartbeats of slack: long enough that a loaded host never skips a
- * waiter that is merely slow, short enough that a stopped waiter does not
- * hold the head of the queue for more than half a minute.
- */
-export const WAITER_STALE_MS = 30_000;
-/** Prefix of the ticket line carrying the waiter's process start tick. */
-const START_TICK_PREFIX = 'start-tick=';
-/** Sibling directory holding the waiter tickets of a lock. */
-export function lockWaitersDir(lockPath) {
-    return `${lockPath}.waiters`;
-}
-/** Parses a ticket name: `<startedAtMs>-<pid>-<uuid>`. */
-function parseTicketName(name) {
-    const match = /^(\d+)-(\d+)-/.exec(name);
-    const startedAt = match?.[1];
-    const pid = match?.[2];
-    if (startedAt === undefined || pid === undefined)
-        return undefined;
-    return { name, startedAt: Number.parseInt(startedAt, 10), pid: Number.parseInt(pid, 10) };
-}
-/** Arrival order: wait start first, then the name, so every reader agrees. */
-function compareTickets(a, b) {
-    if (a.startedAt !== b.startedAt)
-        return a.startedAt - b.startedAt;
-    if (a.name === b.name)
-        return 0;
-    return a.name < b.name ? -1 : 1;
-}
-/** Reads the start tick a ticket recorded, when its writer could record one. */
-async function readTicketStartTick(path) {
-    const content = await readFile(path, 'utf-8');
-    const line = content.split('\n').find((entry) => entry.startsWith(START_TICK_PREFIX));
-    if (line === undefined)
-        return undefined;
-    const tick = Number.parseInt(line.slice(START_TICK_PREFIX.length), 10);
-    return Number.isFinite(tick) ? tick : undefined;
-}
-/**
- * Whether a ticket still holds a place in the queue. A ticket whose owner is
- * provably gone is removed so the directory does not accumulate them; one
- * that has merely stopped being refreshed is skipped but left alone, since
- * its owner may resume and refresh it.
- */
-async function isTicketLive(dir, ticket, now) {
-    const path = join(dir, ticket.name);
-    let startTick;
-    let mtimeMs;
-    try {
-        startTick = await readTicketStartTick(path);
-        mtimeMs = (await stat(path)).mtimeMs;
-    }
-    catch {
-        // Deregistered between the listing and this read.
-        return false;
-    }
-    if (!isLockOwnerAlive({ pid: ticket.pid, startTick })) {
-        await rm(path, { force: true }).catch((error) => {
-            verbose(`Could not remove dead lock waiter ticket ${path}: ${toError(error).message}`);
-        });
-        return false;
-    }
-    return now - mtimeMs <= WAITER_STALE_MS;
-}
-/**
- * Reads the live waiter queue around `lockPath`.
- *
- * Advisory and fail-open: an unreadable registry reports an empty queue
- * rather than failing whatever asked. The caller's own ticket always counts
- * as live, since this process knows it is waiting.
- *
- * @param lockPath - The lock directory whose queue to inspect
- * @param self - This waiter, to compute `ahead`
- */
-export async function readLockQueue(lockPath, self) {
-    const dir = lockWaitersDir(lockPath);
-    let names;
-    try {
-        names = await readdir(dir);
-    }
-    catch {
-        return { depth: 0, ahead: 0 };
-    }
-    const now = Date.now();
-    const tickets = names
-        .map(parseTicketName)
-        .filter((ticket) => ticket !== undefined);
-    const liveFlags = await Promise.all(tickets.map((ticket) => ticket.name === self?.ticket ? Promise.resolve(true) : isTicketLive(dir, ticket, now)));
-    const live = tickets.filter((_, index) => liveFlags[index] === true);
-    if (self === undefined)
-        return { depth: live.length, ahead: 0 };
-    if (self.ticket === undefined) {
-        return {
-            depth: live.length,
-            ahead: live.filter((ticket) => ticket.startedAt < self.startedAt).length,
-        };
-    }
-    const own = parseTicketName(self.ticket);
-    // Our ticket can be missing from the listing only if something removed it;
-    // we still count ourselves, and the next heartbeat recreates it.
-    const listed = live.some((ticket) => ticket.name === self.ticket);
-    return {
-        depth: live.length + (listed ? 0 : 1),
-        ahead: own === undefined
-            ? 0
-            : live.filter((ticket) => ticket.name !== own.name && compareTickets(ticket, own) < 0)
-                .length,
-    };
-}
-/**
- * Takes a ticket in the lock's waiter queue.
- *
- * Never fails the acquisition: a registry that cannot be written yields a
- * registration without a ticket, and the waiter falls back to contending
- * for the lock without queue order, which is how every waiter behaved
- * before tickets decided the grant.
- *
- * @param lockPath - The contended lock directory
- * @param startedAt - When this waiter started waiting (its arrival time)
- */
-export async function registerWaiter(lockPath, startedAt) {
-    const dir = lockWaitersDir(lockPath);
-    const ticket = `${startedAt}-${process.pid}-${randomUUID()}`;
-    const file = join(dir, ticket);
-    const startTick = readProcessStartTick(process.pid);
-    const content = `${process.pid}\n${startTick !== undefined ? `${START_TICK_PREFIX}${startTick}\n` : ''}`;
-    try {
-        await ensureDir(dir);
-        await writeFile(file, content, 'utf-8');
-    }
-    catch (error) {
-        verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
-        return {
-            ticket: undefined,
-            heartbeat: async () => {
-                /* nothing to refresh */
-            },
-            deregister: async () => {
-                /* nothing to remove */
-            },
-        };
-    }
-    let lastBeatAt = Date.now();
-    return {
-        ticket,
-        heartbeat: async () => {
-            if (Date.now() - lastBeatAt < WAITER_HEARTBEAT_MS)
-                return;
-            lastBeatAt = Date.now();
-            try {
-                // A rewrite, not a utimes: it also recreates a ticket that was
-                // removed while this process was stopped long enough to look dead.
-                await ensureDir(dir);
-                await writeFile(file, content, 'utf-8');
-            }
-            catch (error) {
-                verbose(`Could not refresh lock waiter ticket ${file}: ${toError(error).message}`);
-            }
-        },
-        deregister: async () => {
-            try {
-                await rm(file, { force: true });
-            }
-            catch (error) {
-                // A leftover ticket of a process about to exit drops out on its own
-                // (dead PID), so this never needs to fail the caller.
-                verbose(`Could not remove lock waiter ticket ${file}: ${toError(error).message}`);
-            }
-        },
-    };
-}
-/**
- * Renders the queue position for a wait line, with the ordering rule, so the
- * reader knows the count is a promise and not a snapshot. Empty when nothing
- * is queued.
- */
-export function formatLockQueuePosition(queue) {
-    if (queue === undefined || queue.depth === 0)
-        return '';
-    if (queue.ahead === 0) {
-        return ` You are next in a queue of ${queue.depth} (granted in arrival order).`;
-    }
-    return ` ${queue.ahead} ahead of you (queue of ${queue.depth}, granted in arrival order).`;
-}

package/dist/src/core/file-lock-shared.d.ts

@@ -1,57 +0,0 @@
-/**
- * Shared holds on a FireForge directory lock.
- *
- * Two build-less `fireforge test` runs on one objdir, each with its own
- * profile and (under auto ports) its own ports, have no reason to wait for
- * each other; with only exclusive holds the gate's browser tiers would run
- * strictly serially on a many-core host. A shared hold lets such runs overlap while
- * anything that writes (a build, a re-export, a test run that builds)
- * still holds the lock alone.
- *
- * The scheme reuses the exclusive lock as a turnstile, so arrival order and
- * stale-holder reaping come from the machinery that already exists:
- *
- *  - A shared holder takes the exclusive lock in the ordinary way, records
- *    itself under `<lock>.shared/<uuid>/` (an owner record like the lock's
- *    own), and releases the exclusive lock at once.
- *  - An exclusive holder takes the exclusive lock, then waits until no live
- *    shared holder is left. While it waits it already holds the turnstile,
- *    so no new shared holder can slip in ahead of it: a writer queued
- *    behind readers is served once they finish, never starved by newcomers.
- *
- * A shared holder whose process died is reaped by the same PID-first
- * liveness check the exclusive lock uses.
- */
-/** How a caller holds a lock. */
-export type LockMode = 'exclusive' | 'shared';
-/** The directory holding a lock's shared-holder records. */
-export declare function sharedHoldersDir(lockPath: string): string;
-/**
- * Counts the live shared holders of a lock, reaping any whose process is
- * gone. A missing directory means none.
- *
- * @param lockPath - The lock directory
- * @param options - `reap: false` only counts (status reads)
- */
-export declare function countLiveSharedHolders(lockPath: string, options?: {
-    reap?: boolean;
-}): Promise<number>;
-/** A registered shared hold. */
-export interface SharedHold {
-    /** Removes the hold. Never throws. */
-    release(): Promise<void>;
-}
-/**
- * Records a shared hold. Call while holding the lock's exclusive turnstile.
- *
- * @param lockPath - The lock directory
- * @param metadata - Owner metadata lines (`command=…`)
- */
-export declare function registerSharedHold(lockPath: string, metadata: readonly string[] | undefined): Promise<SharedHold>;
-/**
- * Removes every shared hold this process registered, for the signal path.
- * Never throws.
- *
- * @returns The holder paths removed
- */
-export declare function releaseSharedHoldsForSignal(): Promise<string[]>;

package/dist/src/core/file-lock-shared.js

@@ -1,117 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared holds on a FireForge directory lock.
- *
- * Two build-less `fireforge test` runs on one objdir, each with its own
- * profile and (under auto ports) its own ports, have no reason to wait for
- * each other; with only exclusive holds the gate's browser tiers would run
- * strictly serially on a many-core host. A shared hold lets such runs overlap while
- * anything that writes (a build, a re-export, a test run that builds)
- * still holds the lock alone.
- *
- * The scheme reuses the exclusive lock as a turnstile, so arrival order and
- * stale-holder reaping come from the machinery that already exists:
- *
- *  - A shared holder takes the exclusive lock in the ordinary way, records
- *    itself under `<lock>.shared/<uuid>/` (an owner record like the lock's
- *    own), and releases the exclusive lock at once.
- *  - An exclusive holder takes the exclusive lock, then waits until no live
- *    shared holder is left. While it waits it already holds the turnstile,
- *    so no new shared holder can slip in ahead of it: a writer queued
- *    behind readers is served once they finish, never starved by newcomers.
- *
- * A shared holder whose process died is reaped by the same PID-first
- * liveness check the exclusive lock uses.
- */
-import { randomUUID } from 'node:crypto';
-import { mkdir, readdir, rm } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { verbose } from '../utils/logger.js';
-import { isLockOwnerAlive, readLockOwner, writeLockOwner } from './file-lock-owner.js';
-/** The directory holding a lock's shared-holder records. */
-export function sharedHoldersDir(lockPath) {
-    return `${lockPath}.shared`;
-}
-/** Holder directories this process registered, for the signal sweep. */
-const heldShares = new Set();
-/**
- * Counts the live shared holders of a lock, reaping any whose process is
- * gone. A missing directory means none.
- *
- * @param lockPath - The lock directory
- * @param options - `reap: false` only counts (status reads)
- */
-export async function countLiveSharedHolders(lockPath, options = {}) {
-    const dir = sharedHoldersDir(lockPath);
-    let entries;
-    try {
-        entries = await readdir(dir);
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) === 'ENOENT')
-            return 0;
-        if (options.reap === false)
-            return 0;
-        throw toError(error);
-    }
-    let live = 0;
-    for (const entry of entries) {
-        const holder = join(dir, entry);
-        const owner = await readLockOwner(holder);
-        if (owner.present && isLockOwnerAlive(owner)) {
-            live += 1;
-            continue;
-        }
-        // A record still being written has no owner yet; only an owner that
-        // names a dead process is reaped, so a racing registration survives.
-        if (owner.present && options.reap !== false) {
-            verbose(`Reaping shared hold ${holder}: PID ${owner.pid} is gone.`);
-            await rm(holder, { recursive: true, force: true });
-        }
-    }
-    return live;
-}
-/**
- * Records a shared hold. Call while holding the lock's exclusive turnstile.
- *
- * @param lockPath - The lock directory
- * @param metadata - Owner metadata lines (`command=…`)
- */
-export async function registerSharedHold(lockPath, metadata) {
-    const holder = join(sharedHoldersDir(lockPath), randomUUID());
-    await mkdir(holder, { recursive: true });
-    await writeLockOwner(holder, randomUUID(), [...(metadata ?? []), 'mode=shared']);
-    heldShares.add(holder);
-    return {
-        async release() {
-            heldShares.delete(holder);
-            try {
-                await rm(holder, { recursive: true, force: true });
-            }
-            catch (error) {
-                verbose(`Could not remove shared hold ${holder}: ${toError(error).message}`);
-            }
-        },
-    };
-}
-/**
- * Removes every shared hold this process registered, for the signal path.
- * Never throws.
- *
- * @returns The holder paths removed
- */
-export async function releaseSharedHoldsForSignal() {
-    const removed = [];
-    for (const holder of [...heldShares]) {
-        heldShares.delete(holder);
-        try {
-            await rm(holder, { recursive: true, force: true });
-            removed.push(holder);
-        }
-        catch {
-            // Shutdown path: nothing to do.
-        }
-    }
-    return removed;
-}

package/dist/src/core/file-lock.d.ts

@@ -1,143 +0,0 @@
-import { LOCK_PID_FILE } from './file-lock-owner.js';
-import { type LockQueueState } from './file-lock-queue.js';
-import { type LockMode } from './file-lock-shared.js';
-export { LOCK_PID_FILE };
-export { formatLockQueuePosition, type LockQueueState } from './file-lock-queue.js';
-export type { LockMode } from './file-lock-shared.js';
-/**
- * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
- * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
- * e.g. `command=build`, `started=…`) written via
- * {@link FileLockOptions.ownerMetadata}.
- */
-export interface LockHolder {
-    pid: number;
-    alive: boolean;
-    metadata: string[];
-}
-export interface FileLockOptions {
-    timeoutMs?: number;
-    pollMs?: number;
-    /**
-     * When set, the poll interval doubles after every contended poll (starting
-     * from `pollMs`) up to this cap. When absent, polling stays at the fixed
-     * `pollMs` interval, with zero behavior change for existing callers.
-     * Keep it far below `WAITER_STALE_MS` (30 s): a waiter refreshes its queue
-     * ticket between polls, and a ticket left unrefreshed that long is skipped.
-     */
-    pollMaxMs?: number;
-    staleMs?: number;
-    /**
-     * Interval between stale-lock probes while waiting (defaults to
-     * {@link STALE_REPROBE_INTERVAL_MS}). Exists mainly so tests can exercise
-     * the mid-wait reaping path without multi-second sleeps.
-     */
-    staleReprobeMs?: number;
-    /**
-     * Interval between {@link onWaitProgress} callbacks while the lock is
-     * contended. Progress reporting is off unless both this and
-     * `onWaitProgress` are set.
-     */
-    waitProgressMs?: number;
-    /**
-     * Invoked roughly every `waitProgressMs` while waiting for a contended
-     * lock. `holder` is `undefined` when the owner PID file is missing or
-     * unreadable.
-     */
-    onWaitProgress?: (progress: {
-        waitedMs: number;
-        timeoutMs: number;
-        holder: LockHolder | undefined;
-        /** Queue state at this poll, when the waiter registry is available. */
-        queue?: LockQueueState | undefined;
-    }) => void;
-    /**
-     * When set, a wait whose queue position is still improving is granted a
-     * fresh `timeoutMs` budget on each advance, up to `maxWaitMs` total.
-     *
-     * A fixed wall-clock budget against a queue whose depth the tool knows is
-     * the wrong shape under several concurrent sessions: a wait that expires
-     * one position from the head pays the entire wait and gets nothing. The
-     * question that matters is whether the queue is moving, not how long the
-     * wait has been. A stalled queue still starves on the original budget,
-     * which is the case the timeout exists for.
-     *
-     * Requires the waiter registry (see {@link LockQueueState}). A lock with
-     * no readable queue never extends, because nothing observed an advance.
-     */
-    extendWhileAdvancing?: {
-        maxWaitMs: number;
-    };
-    /**
-     * Invoked when {@link extendWhileAdvancing} actually grants an extension.
-     *
-     * Separate from {@link onWaitProgress} on purpose: an extension is the one
-     * moment the budget the operator asked for stops being the budget in
-     * force, and a wait that silently outlives its stated timeout is
-     * indistinguishable from a broken one. `budgetMs` is the new total budget
-     * measured from the start of the wait, so it can be compared directly
-     * against the requested figure.
-     */
-    onWaitExtended?: (extension: {
-        ahead: number;
-        budgetMs: number;
-    }) => void;
-    onTimeoutMessage?: string;
-    onStaleLockMessage?: (ageMs: number) => string | undefined;
-    /** Extra owner-file lines for human diagnostics. Lock mechanics ignore them. */
-    ownerMetadata?: readonly string[];
-    /**
-     * `exclusive` (default) or `shared`. Shared holders overlap each other and
-     * exclude exclusive ones; see `file-lock-shared.ts`.
-     */
-    mode?: LockMode | undefined;
-}
-/** Derives the sibling lock-directory path used to guard a file-based resource. */
-export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
-/**
- * Snapshot of a lock for `fireforge status --lock`: who holds
- * it, for how long, and how deep the queue behind it is.
- */
-export interface LockStatusSnapshot {
-    held: boolean;
-    holder?: LockHolder | undefined;
-    /** Milliseconds since the lock directory was created, when held. */
-    heldForMs?: number | undefined;
-    queueDepth: number;
-    /** Live shared holders (build-less test runs under a shared lock). */
-    sharedHolders?: number | undefined;
-}
-/**
- * Inspects a lock without acquiring it. Read-only and fail-open: a missing
- * lock is reported as free, never as an error.
- */
-export declare function readLockStatus(lockPath: string): Promise<LockStatusSnapshot>;
-/**
- * Removes a lock directory only if this process still owns it, for callers
- * that hold no acquisition token.
- *
- * The ownership half of {@link releaseLock}, minus the token check: a
- * signal-time sweeper knows which lock paths its own operations opened, but
- * not the per-acquisition UUID those acquisitions minted. The PID check is
- * still the one that matters: it stops the sweeper deleting a lock a
- * different process acquired in the window between our operation dying and
- * the sweep running.
- *
- * Never throws: callers are shutdown paths where a slow or failing I/O must
- * not prevent the process from exiting. Returns whether the directory was
- * removed so callers can log accurately.
- *
- * @param lockPath - Lock directory to remove
- * @returns True when the lock was removed, false when it was left in place
- */
-export declare function releaseLockIfOwned(lockPath: string): Promise<boolean>;
-/**
- * Releases every lock this process still holds, for the signal path.
- *
- * Never throws and never rejects: a shutdown path must not be able to keep
- * the process alive. Returns the paths actually removed so the caller can
- * report accurately.
- */
-export declare function forceReleaseHeldLocksForSignal(): Promise<string[]>;
-/** Runs an async operation while holding a directory lock, with stale-lock recovery. */
-export declare function withFileLock<T>(lockPath: string, operation: () => Promise<T>, options?: FileLockOptions): Promise<T>;