@apexops/kernel 0.10.0-next.5 → 0.11.0-next.1

package/dist/directory-lock.d.ts

@@ -0,0 +1,118 @@
+/**
+ * A share window could not be closed, so snapshot readers may still trust it. The hold refuses to share again; its
+ * holder must write nothing more before it releases the lock, which takes the window with it.
+ */
+export declare class DirectoryLockShareCloseError extends Error {
+    constructor(label: string, cause: unknown);
+}
+/** One acquisition of a {@link DirectoryLock}. */
+export interface DirectoryLockHold {
+    /** Gives the lock up. Idempotent. */
+    release(): Promise<void>;
+    /**
+     * Runs `operation` with this generation open to {@link DirectoryLock.readShared} snapshot readers, for example while
+     * the holder waits for an external process. The lock stays held, so other holders still wait. The holder must not
+     * write the state the lock protects until `operation` settles: the window closes before `share` returns, and closing
+     * it is what invalidates a snapshot read that overlapped it. Concurrent calls run their operations in one window,
+     * which closes when the last of them settles, and none returns before it closed. A call made inside a shared
+     * operation runs in the enclosing window and returns into that operation, which must still not write. When the
+     * window cannot be closed `share` throws {@link DirectoryLockShareCloseError},
+     * then and on every later call; the holder must then stop writing until it releases the lock.
+     */
+    share<T>(operation: () => Promise<T>): Promise<T>;
+}
+export interface DirectoryLockOptions {
+    /** Prefix of metadata error messages, for example "Run mutation lock". */
+    label: string;
+    clock: () => Date;
+    idSource: () => string;
+    /** A generation is only taken over once it has expired and its local owner process is gone. */
+    ttlMs: number;
+    /** Selects Windows transient file-sharing handling. */
+    platform: NodeJS.Platform;
+    busyError: () => Error;
+}
+/**
+ * Cross-process exclusive lock published as a directory `<name>.lock` holding owner metadata. A generation is staged
+ * in `<name>.pending-*` and published by rename, so the lock path never holds partial metadata. A live owner is waited
+ * for; an expired generation whose local owner process is gone is taken over into a permanent tombstone under
+ * `<name>.retired/`, which makes takeover compare-and-swap; released generations are parked there and deleted.
+ */
+export declare class DirectoryLock {
+    private readonly lockPath;
+    private readonly retiredLockPath;
+    private readonly stagingPrefix;
+    private readonly label;
+    private readonly clock;
+    private readonly idSource;
+    private readonly ttlMs;
+    private readonly platform;
+    private readonly busyError;
+    constructor(lockPath: string, options: DirectoryLockOptions);
+    /** Runs `operation` while holding the lock; throws the configured busy error when it cannot be acquired in time. */
+    run<T>(operation: () => Promise<T>, options?: {
+        onContention?: () => Promise<Error | undefined>;
+        waitMs?: number;
+    }): Promise<T>;
+    /**
+     * Acquires the lock and returns its release, for holders that give the lock up and take it again while they run.
+     * Throws the configured busy error when it cannot be acquired in time. Release is idempotent.
+     */
+    acquire(options?: {
+        onContention?: () => Promise<Error | undefined>;
+        waitMs?: number;
+    }): Promise<DirectoryLockHold>;
+    /**
+     * Runs `read` without the lock while a holder shares its generation (see {@link DirectoryLockHold.share}) and returns
+     * its outcome only when the same window was still open after `read` settled, so the holder wrote nothing meanwhile.
+     * Returns undefined, discarding the outcome, when no window was open or it closed during the read; the caller then
+     * retries or waits for the lock. `read` must not write the state the lock protects.
+     */
+    readShared<T>(read: () => Promise<T>): Promise<{
+        value: T;
+    } | undefined>;
+    private openShare;
+    private closeShare;
+    /**
+     * Identity of the open share window: the holding generation's token and the window id, or undefined when there is no
+     * readable window. Any failure to read it counts as no window, so a reader falls back to the lock.
+     */
+    private shareWindow;
+    private acquireLock;
+    /** Cheap pre-check so contended waiters do not stage and fsync lock metadata on every poll. */
+    private lockPublished;
+    private readLock;
+    private ownerMayBeAlive;
+    /**
+     * Take over an expired generation whose local owner was confirmed dead after `snapshot` was read. Re-reading the lock
+     * after that liveness check is what lets released generations skip tombstones: a generation still present after its
+     * owner died can no longer be released by that owner, so it can only leave the lock path through another takeover,
+     * which leaves the permanent tombstone that makes this rename fail instead of retiring a replacement generation.
+     */
+    private retireStaleLock;
+    /**
+     * Retire a taken-over generation into a permanent tombstone named by its recovery id. Rename is not compare-and-swap,
+     * so the tombstone is the guard: a delayed contender that confirmed the same generation renames onto the existing
+     * non-empty tombstone and fails rather than moving a replacement lock. Tombstones are therefore never swept; they
+     * accumulate only once per crashed lock owner, not per mutation.
+     */
+    private retireLock;
+    /**
+     * Release a generation this process owns. While the owner is alive no contender can take its generation over (see
+     * `retireStaleLock`), so the rename moves exactly this generation and needs no tombstone: it is parked under a fresh
+     * unique name and deleted by `sweepReleasedLocks`.
+     */
+    private releaseLock;
+    private ensureRetiredRoot;
+    /**
+     * Best-effort deletion of every released generation, including ones left by earlier cleanup failures or crashes
+     * between release and deletion. Any process may delete any released entry at any time: each has a unique name that
+     * only its releasing owner ever renames to, and nothing reads, renames, or locks through it afterwards. Takeover
+     * tombstones, the live lock, and other processes' `.pending-` staging directories are never touched. Failures never
+     * fail the caller; Windows sharing violations (for example a contender's metadata handle still open) are retried
+     * briefly and otherwise left for the next sweep.
+     */
+    private sweepReleasedLocks;
+    private removeReleasedLock;
+}
+//# sourceMappingURL=directory-lock.d.ts.map

package/dist/directory-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-lock.d.ts","sourceRoot":"","sources":["../src/directory-lock.ts"],"names":[],"mappings":"AAgCA;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,YAAY,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAGxC;CACF;AASD,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnD;AAQD,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,+FAA+F;IAC/F,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,SAAS,EAAE,MAAM,KAAK,CAAC;CACxB;AAwBD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,YAAY,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAY1D;IAED,oHAAoH;IAC9G,GAAG,CAAC,CAAC,EACT,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GACjF,OAAO,CAAC,CAAC,CAAC,CAOZ;IAED;;;OAGG;IACG,OAAO,CACX,OAAO,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GACjF,OAAO,CAAC,iBAAiB,CAAC,CA0G5B;IAED;;;;;OAKG;IACG,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAA;KAAE,GAAG,SAAS,CAAC,CAY7E;YAEa,SAAS;YAmBT,UAAU;IAcxB;;;OAGG;YACW,WAAW;YAoCX,WAAW;IAuCzB,+FAA+F;YACjF,aAAa;YAUb,QAAQ;IAgGtB,OAAO,CAAC,eAAe;IAUvB;;;;;OAKG;YACW,eAAe;IAM7B;;;;;OAKG;YACW,UAAU;IAYxB;;;;OAIG;YACW,WAAW;YAKX,iBAAiB;IAQ/B;;;;;;;OAOG;YACW,kBAAkB;YAgBlB,kBAAkB;CAajC"}