@lakutata/mutex 0.0.0-stage → 3.0.0-beta.1

package/dist/esm/mutex/MutexLock.js

@@ -0,0 +1,109 @@
+/**
+ * A lock held, returned by {@link Mutex.acquire} and {@link Mutex.tryAcquire} (and given to the function of
+ * {@link Mutex.synchronized}); the component creates it. It stays held until it is released (once: the next releases do
+ * nothing) or lost; the component renews it in the store meanwhile. Declared with `await using`, it is released at the
+ * end of its scope.
+ *
+ * Its {@link MutexLock.signal} is aborted when it is lost: a renewal found it expired or taken by another holder, a
+ * renewal failed, or the connection holding it closed. A lost lock is not released in the store: another holder may get
+ * it once it expires. The work it protects should stop then, and the writes it makes may carry its
+ * {@link MutexLock.fence} so that the store refuses the writes of an older holder.
+ * @example
+ * ```typescript
+ * import type {Mutex, MutexLock} from 'lakutata/com/mutex'
+ *
+ * declare const mutex: Mutex
+ * declare function writeReport(fence: number | undefined, signal: AbortSignal): Promise<void>
+ *
+ * await using lock: MutexLock = await mutex.acquire('report:daily')
+ * lock.signal.addEventListener('abort', (): void => console.warn(`lost: ${lock.signal.reason}`))
+ * await writeReport(lock.fence, lock.signal)
+ * console.log(lock.held, Date.now() - lock.acquiredAt.getTime())
+ * ```
+ */
+export class MutexLock {
+    #abort;
+    #held;
+    /**
+     * Create a held lock (the component does it, when the store grants a lock).
+     * @param name The lock name, without the component's prefix.
+     * @param token The random token identifying this holder in the store.
+     * @param fence The fencing token given by the store, or `undefined` when the driver gives none.
+     * @param actions How the component releases and renews the lock.
+     */
+    constructor(name, token, fence, actions) {
+        this.name = name;
+        this.token = token;
+        this.fence = fence;
+        this.actions = actions;
+        this.#abort = new AbortController();
+        this.#held = true;
+        /**
+         * When the lock was acquired (the time this object was created, once the store granted it).
+         */
+        this.acquiredAt = new Date();
+    }
+    /**
+     * Whether the lock is still held: `false` once it is released or lost. It reflects what the component knows; an
+     * expiring lock whose renewal is late may already be expired in the store.
+     */
+    get held() {
+        return this.#held;
+    }
+    /**
+     * Aborted when the lock is lost, with a {@link MutexLostException} as its reason: a renewal found it expired or taken,
+     * a renewal failed, or the connection holding it closed. The work the lock protects should stop then. It is not
+     * aborted by a release.
+     */
+    get signal() {
+        return this.#abort.signal;
+    }
+    /**
+     * Release the lock in the store and stop its renewal. Only the first call releases it; the next ones, and the calls
+     * on a lost lock, return `false` without reaching the store. The lock no longer counts as held even when the store
+     * fails, in which case it stays in the store until it expires.
+     * @returns Whether the store still had the lock for this holder (`false` when it had expired, been taken, or its
+     * connection had closed).
+     * @throws {MutexDriverException} When the store fails.
+     */
+    async release() {
+        if (!this.#held)
+            return false;
+        this.#held = false;
+        return await this.actions.release(this);
+    }
+    /**
+     * Renew the lock now, for `ttl` milliseconds from now; the component already renews it automatically every third of
+     * its `ttl`. A `ttl` given here is used by the next automatic renewals too, their interval following it. For the
+     * advisory locks (which do not expire), it checks that the lock is still held by a query on its connection.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds; the lock's last `ttl` (the one of its
+     * acquisition) by default.
+     * @returns Whether the lock is still held; when the store no longer has it, the lock is marked lost (its signal
+     * aborted) and `false` is returned.
+     * @throws {MutexDriverException} When the store fails (the lock is not marked lost then).
+     */
+    async extend(ttl) {
+        if (!this.#held)
+            return false;
+        return await this.actions.extend(this, ttl);
+    }
+    /**
+     * Mark the lock as lost and abort its signal with the reason; the component calls it when a renewal fails or the
+     * connection holding the lock closes. It does nothing on a lock no longer held, and it does not release the lock in
+     * the store nor stop its renewal: the applications do not call it.
+     * @param reason The signal's abort reason, a {@link MutexLostException} from the component.
+     */
+    lose(reason) {
+        if (!this.#held)
+            return;
+        this.#held = false;
+        this.#abort.abort(reason);
+    }
+    /**
+     * Release the lock at the end of an `await using` scope, as {@link MutexLock.release} does.
+     * @throws {MutexDriverException} When the store fails.
+     */
+    async [Symbol.asyncDispose]() {
+        await this.release();
+    }
+}

package/dist/esm/mutex/Synchronized.js

@@ -0,0 +1,89 @@
+/**
+ * Build a lock name from a template, replacing each `{field}` with that field of the input (`{a.b}` reads a nested
+ * field). {@link Synchronized} uses it for its template names; a template without `{}` is returned as it is.
+ * @param template The template, such as `'order:{id}'` or `'user:{user.id}:export'`.
+ * @param input The object whose fields fill the template (an action's validated input).
+ * @returns The lock name.
+ * @throws {TypeError} When a field of the template is missing, `null`, or an object (only strings, numbers and other
+ * primitives are accepted).
+ * @example
+ * ```typescript
+ * import {lockNameOf} from 'lakutata/com/mutex'
+ *
+ * console.log(lockNameOf('order:{id}', {id: 42})) //order:42
+ * console.log(lockNameOf('user:{user.id}:export', {user: {id: 'u7'}})) //user:u7:export
+ * ```
+ */
+export function lockNameOf(template, input) {
+    return template.replace(/\{([^{}]+)}/g, (_, field) => {
+        const value = field.split('.').reduce((current, key) => current === null || current === undefined ? undefined : current[key], input);
+        if (value === undefined || value === null || (typeof value === 'object'))
+            throw new TypeError(`The lock "${template}" needs the field ${field} of the input of the action (a string or a number)`);
+        return String(value);
+    });
+}
+/**
+ * Run a controller action holding a lock, acquired once its input is validated and its access control passed, released
+ * after it (whether it returns or throws). The requests needing the same lock run one at a time in every instance
+ * sharing the lock store, whatever their transport (HTTP, CLI, service); the others run in parallel.
+ *
+ * The lock comes from the {@link Mutex} component registered as `mutex` (or `options.mutex`); a missing component
+ * fails the request. The wait for the lock stops when the request is aborted (its client gone), and a request not
+ * getting the lock in time fails with a {@link MutexTimeoutException} (HTTP 409). The action is not interrupted when
+ * its lock is lost: check the controller's `this.signal` for a long work.
+ * @param name The lock name: a template filled from the fields of the action's input (`'order:{id}'`, see
+ * {@link lockNameOf}; a missing field fails the request with a `TypeError`), or a function of the input and the
+ * request's context returning it.
+ * @param options The lock component, the wait and the lock's `ttl`.
+ * @returns The method decorator.
+ * @throws {TypeError} When the class is declared, if the name is neither a non-empty string nor a function, or if the
+ * decorated member is not a method.
+ * @throws {MutexTimeoutException} From the action, when the lock is not acquired in time (HTTP 409).
+ * @throws {MutexDriverException} From the action, when the lock store fails.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {ServiceAction} from 'lakutata/decorator/ctrl'
+ * import {Synchronized} from 'lakutata/com/mutex'
+ *
+ * class OrderController extends Controller {
+ *     //The payments of an order one at a time, the other orders in parallel
+ *     @ServiceAction({cmd: 'order.pay'})
+ *     @Synchronized('order:{id}')
+ *     public async pay(input: {id: number}): Promise<void> {
+ *     }
+ *
+ *     //Fails at once (HTTP 409) while another request rebuilds the index
+ *     @ServiceAction({cmd: 'search.reindex'})
+ *     @Synchronized('search:reindex', {wait: false})
+ *     public async reindex(): Promise<void> {
+ *     }
+ *
+ *     //A lock named by a function, from the component registered as "locks"
+ *     @ServiceAction({cmd: 'user.export'})
+ *     @Synchronized((input: {userId: string}): string => `export:${input.userId}`, {timeout: 5000, mutex: 'locks'})
+ *     public async export(input: {userId: string}): Promise<void> {
+ *     }
+ * }
+ * ```
+ */
+export function Synchronized(name, options = {}) {
+    if (typeof name !== 'function' && (typeof name !== 'string' || !name))
+        throw new TypeError('The lock of a synchronized action is a template or a function');
+    return (_target, propertyKey, descriptor) => {
+        const action = descriptor.value;
+        if (typeof action !== 'function')
+            throw new TypeError(`@Synchronized decorates a method (${String(propertyKey)})`);
+        descriptor.value = async function (...args) {
+            const input = args[0] ?? {};
+            const lockName = typeof name === 'function' ? name(input, this.context) : lockNameOf(name, input);
+            const mutex = await this.getObject(options.mutex ?? 'mutex');
+            return await mutex.synchronized(lockName, (_lock) => action.apply(this, args), {
+                timeout: options.wait === false ? 0 : options.timeout,
+                ttl: options.ttl,
+                signal: this.signal
+            });
+        };
+        return descriptor;
+    };
+}

package/dist/esm/mutex/drivers/FileMutexDriver.js

@@ -0,0 +1,223 @@
+import { link, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import path from 'node:path';
+import { MutexDriver } from './MutexDriver.js';
+import { lockToken, nameDigest } from '../lib/Names.js';
+/**
+ * Whether a process of this host runs
+ * @param pid
+ */
+function processRuns(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        //Running, but not ours to signal
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * The file driver (`{type: 'file'}`): each lock is a file of a directory, created exclusively, shared by the processes of
+ * one host using the same directory and prefix (several workers or applications of a machine). It needs no package.
+ * The processes must share the directory: the default one (`lakutata-mutex` in the operating system's temporary
+ * directory) can differ between users. A directory shared by several hosts (a network file system) works only as far
+ * as its exclusive creation and renames are atomic, and only the expiration then frees the lock of a crashed host.
+ *
+ * The locks expire after their `ttl` unless renewed; a lock whose process is gone on this host is taken over at once,
+ * without waiting for its expiration. The driver gives no fencing token (`fence` is `undefined`).
+ * @example
+ * ```typescript
+ * import {FileMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * //The workers of this machine run the migration one at a time
+ * const driver: FileMutexDriver = new FileMutexDriver('/var/lock/my-app', 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('migrate', 60000)
+ * if (lock) {
+ *     try {
+ *         console.log('migrating')
+ *     } finally {
+ *         await driver.release('migrate', lock)
+ *     }
+ * }
+ * ```
+ */
+export class FileMutexDriver extends MutexDriver {
+    #host;
+    /**
+     * Create a driver on a directory, created at the first acquisition when it does not exist.
+     * @param directory The directory of the lock files.
+     * @param prefix The prefix added to the lock names; `''` by default.
+     */
+    constructor(directory, prefix = '') {
+        super();
+        this.directory = directory;
+        this.prefix = prefix;
+        /**
+         * `true`: the locks expire after their `ttl` unless renewed.
+         */
+        this.expiring = true;
+        this.#host = hostname();
+    }
+    /**
+     * The path of a lock's file: the SHA-256 digest of the prefixed name, with the extension `.lock`.
+     * @param name The lock name.
+     * @returns The file path.
+     */
+    file(name) {
+        return path.join(this.directory, `${nameDigest(this.prefix + name)}.lock`);
+    }
+    /**
+     * Read a lock file.
+     * @param file The file path.
+     * @returns Its content, or `undefined` when it does not exist or cannot be parsed (being written).
+     */
+    async read(file) {
+        try {
+            return JSON.parse(await readFile(file, 'utf8'));
+        }
+        catch {
+            //Not there, or being written
+            return undefined;
+        }
+    }
+    /**
+     * Whether a lock file is no longer held: expired, or written by another process of this host which no longer runs.
+     * @param lock The content of the lock file.
+     * @returns Whether it may be taken over.
+     */
+    stale(lock) {
+        return lock.expires <= Date.now() || (lock.host === this.#host && lock.pid !== process.pid && !processRuns(lock.pid));
+    }
+    /**
+     * Whether a lock file which cannot be read was abandoned (its process ended while writing it) rather than being
+     * written: unchanged for more than 5 seconds.
+     * @param file The file path.
+     * @returns Whether it may be taken over.
+     */
+    async abandoned(file) {
+        try {
+            return Date.now() - (await stat(file)).mtimeMs > 5000;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Remove a lock file when it is still the one read, by renaming it first so that only one process takes it. A file
+     * of another holder taken by mistake is put back when its place is still free.
+     * @param file The file path.
+     * @param token The token read in the file, or `undefined` for a file which could not be read.
+     * @returns Whether the file was removed.
+     */
+    async take(file, token) {
+        const taken = `${file}.${lockToken()}`;
+        try {
+            await rename(file, taken);
+        }
+        catch {
+            return false;
+        }
+        const content = await this.read(taken);
+        if (content?.token === token) {
+            await unlink(taken).catch(() => undefined);
+            return true;
+        }
+        //Another lock was taken: given back when its place is free
+        await link(taken, file).catch(() => undefined);
+        await unlink(taken).catch(() => undefined);
+        return false;
+    }
+    /**
+     * Try to acquire a lock once: create its file exclusively, or take over a file expired, abandoned, or whose process
+     * of this host is gone.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds.
+     * @returns The lock (without fencing token), or `undefined` when another holder has it.
+     * @throws {Error} When the directory cannot be created or the file written (permissions, disk full).
+     */
+    async acquire(name, ttl) {
+        await mkdir(this.directory, { recursive: true });
+        const file = this.file(name);
+        const lock = { token: lockToken() };
+        const content = JSON.stringify({ name: name, token: lock.token, pid: process.pid, host: this.#host, expires: Date.now() + ttl });
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await writeFile(file, content, { flag: 'wx' });
+                return lock;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            const current = await this.read(file);
+            if (current ? !this.stale(current) : !(await this.abandoned(file)))
+                return undefined;
+            if (!(await this.take(file, current?.token)))
+                return undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Release a lock by removing its file, when the file still holds this holder's token.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released.
+     */
+    async release(name, lock) {
+        const file = this.file(name);
+        if ((await this.read(file))?.token !== lock.token)
+            return false;
+        return await this.take(file, lock.token);
+    }
+    /**
+     * Renew a lock whose file still holds this holder's token, for `ttl` milliseconds from now: the file is taken away
+     * (renamed), checked, rewritten and given back without replacing a lock another process acquired meanwhile (the
+     * renewal fails then). A lock expired is not renewed (lost), even when no other process took it over yet.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds.
+     * @returns Whether it was renewed.
+     */
+    async extend(name, lock, ttl) {
+        const file = this.file(name);
+        const current = await this.read(file);
+        //Expired: lost, even when nobody took it yet
+        if (current?.token !== lock.token || current.expires <= Date.now())
+            return false;
+        //Taken away (renamed: only one taker has it) and checked, renewed, then given back without replacing a lock
+        //acquired meanwhile (linked: it fails when the file exists)
+        const taken = `${file}.${lockToken()}`;
+        try {
+            await rename(file, taken);
+        }
+        catch {
+            return false;
+        }
+        const content = await this.read(taken);
+        if (content?.token !== lock.token) {
+            //Another holder's lock, taken over meanwhile: given back
+            await link(taken, file).catch(() => undefined);
+            await unlink(taken).catch(() => undefined);
+            return false;
+        }
+        await writeFile(taken, JSON.stringify({ ...content, expires: Date.now() + ttl }));
+        try {
+            await link(taken, file);
+            return true;
+        }
+        catch {
+            //Acquired by another process while it was taken away: lost
+            return false;
+        }
+        finally {
+            await unlink(taken).catch(() => undefined);
+        }
+    }
+    /**
+     * Do nothing: the driver keeps no file open; the lock files stay until they are released or taken over.
+     */
+    async close() {
+        //Nothing kept open
+    }
+}

package/dist/esm/mutex/drivers/MemoryMutexDriver.js

@@ -0,0 +1,91 @@
+import { MutexDriver } from './MutexDriver.js';
+import { lockToken } from '../lib/Names.js';
+/**
+ * The locks of the process, shared by its components: the ones of a single instance (its development, its tests)
+ */
+const LOCKS = new Map();
+let FENCE = 0;
+/**
+ * The memory driver (`{type: 'memory'}`, the default of a {@link Mutex}): the locks live in the process memory, shared
+ * by every component and driver of the process using the same prefix, and invisible to the other processes. Use it for
+ * development, tests and an application running as a single process. It needs no package.
+ *
+ * The locks expire after their `ttl` unless renewed. The fencing token is a counter of the process, starting again at 1
+ * when the process restarts. The locks are lost with the process.
+ * @example
+ * ```typescript
+ * import {MemoryMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: MemoryMutexDriver = new MemoryMutexDriver('test:')
+ * const first: DriverLock | undefined = await driver.acquire('job', 1000)
+ * console.log(await driver.acquire('job', 1000)) //undefined: held by the first
+ * if (first) console.log(await driver.release('job', first)) //true
+ * await driver.close()
+ * ```
+ */
+export class MemoryMutexDriver extends MutexDriver {
+    #locks;
+    /**
+     * Create a driver on the process memory.
+     * @param prefix The prefix added to the lock names; the drivers of the process with the same prefix share their
+     * locks. `''` by default.
+     */
+    constructor(prefix = '') {
+        super();
+        this.prefix = prefix;
+        /**
+         * `true`: the locks expire after their `ttl` unless renewed.
+         */
+        this.expiring = true;
+        this.#locks = LOCKS;
+    }
+    /**
+     * Try to acquire a lock once: granted when nobody holds it or its holder let it expire.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds.
+     * @returns The lock with a fencing token, or `undefined` when another holder has it.
+     */
+    async acquire(name, ttl) {
+        const key = this.prefix + name;
+        const current = this.#locks.get(key);
+        if (current && current.expires > Date.now())
+            return undefined;
+        const lock = { token: lockToken(), fence: ++FENCE };
+        this.#locks.set(key, { token: lock.token, expires: Date.now() + ttl });
+        return lock;
+    }
+    /**
+     * Release a lock still held by this holder.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when another holder has taken it since).
+     */
+    async release(name, lock) {
+        if (this.#locks.get(this.prefix + name)?.token !== lock.token)
+            return false;
+        this.#locks.delete(this.prefix + name);
+        return true;
+    }
+    /**
+     * Renew a lock still held by this holder, for `ttl` milliseconds from now. A lock expired is not renewed (lost),
+     * even when no other holder took it yet.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds.
+     * @returns Whether it was renewed.
+     */
+    async extend(name, lock, ttl) {
+        const current = this.#locks.get(this.prefix + name);
+        //Expired: lost, even when nobody took it yet
+        if (current?.token !== lock.token || current.expires <= Date.now())
+            return false;
+        current.expires = Date.now() + ttl;
+        return true;
+    }
+    /**
+     * Do nothing: the locks stay in the process memory until they are released or expire.
+     */
+    async close() {
+        //The locks of the process kept: the ones of this component are released by it
+    }
+}

package/dist/esm/mutex/drivers/MutexDriver.js

@@ -0,0 +1,34 @@
+/**
+ * The base class of the lock drivers: it acquires, releases and renews the locks in a store shared by their holders.
+ * A {@link Mutex} creates its driver from its `driver` option and adds the waiting, the automatic renewal and the lost
+ * locks; a custom subclass cannot be given to it. The drivers are exported to use a store directly (scripts, tests):
+ * they neither wait nor renew, and their errors are the clients' errors, not a {@link MutexDriverException}.
+ * @example
+ * ```typescript
+ * import {MemoryMutexDriver, type DriverLock, type MutexDriver} from 'lakutata/com/mutex'
+ *
+ * async function once(driver: MutexDriver, name: string, work: () => Promise<void>): Promise<boolean> {
+ *     const lock: DriverLock | undefined = await driver.acquire(name, 10000)
+ *     if (!lock) return false
+ *     try {
+ *         await work()
+ *     } finally {
+ *         await driver.release(name, lock)
+ *     }
+ *     return true
+ * }
+ *
+ * const driver: MutexDriver = new MemoryMutexDriver('script:')
+ * console.log(await once(driver, 'migrate', async (): Promise<void> => undefined))
+ * await driver.close()
+ * ```
+ */
+export class MutexDriver {
+    constructor() {
+        /**
+         * Called with the names of the locks the driver lost at once, when the connection holding advisory locks closes or
+         * fails. A {@link Mutex} sets it; it does nothing by default.
+         */
+        this.onLost = () => undefined;
+    }
+}