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

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

@@ -0,0 +1,240 @@
+import { MutexDriver } from './MutexDriver.js';
+import { loadDriver } from '../lib/LoadDriver.js';
+import { lockToken, nameDigest } from '../lib/Names.js';
+/**
+ * The MySQL driver (`{type: 'mysql'}`, MySQL or MariaDB): the locks are shared by every instance connected to the same
+ * server with the same prefix. It needs the optional peer dependency `mysql2` (3); without it, the first acquisition
+ * fails with {@link MutexDriverNotFoundException}. It has two modes:
+ * - `'advisory'` (the default): named locks (`GET_LOCK`) taken on one connection of the driver, opened at the first use.
+ *   They do not expire and need no renewal: MySQL releases them when the connection closes, so a crashed process frees
+ *   them at once. When the connection closes or fails, every lock it held is lost (a {@link Mutex} aborts their
+ *   signals) and the next acquisition opens a new connection. A connection cut without the client noticing it is not
+ *   detected by the renewals. No fencing token. The named locks are not replicated by the clusters (Galera, Group
+ *   Replication): every holder must connect to the same server.
+ * - `'table'`: one row per lock in a table, created at the first use with its counter table `<table>_fence`. The rows
+ *   expire by the database clock after their `ttl` unless renewed, so it works through the poolers and the clusters, and
+ *   each acquisition gets a fencing token from the counter. A pool of 4 connections is used.
+ * @example
+ * ```typescript
+ * import {MysqlMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: MysqlMutexDriver = new MysqlMutexDriver({
+ *     host: '127.0.0.1',
+ *     database: 'app',
+ *     username: 'app',
+ *     password: 'secret'
+ * }, 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) await driver.release('invoice:7', lock)
+ * //Closing the connection releases its named locks
+ * await driver.close()
+ * ```
+ */
+export class MysqlMutexDriver extends MutexDriver {
+    #connection;
+    #pool;
+    #connecting;
+    #table;
+    #held = new Map();
+    /**
+     * Create a driver on a MySQL server; it connects at its first use.
+     * @param connection The connection to the server.
+     * @param prefix The prefix added to the lock names.
+     * @param mode `'advisory'` (the default) or `'table'`.
+     * @param table The table of the `table` mode, in the connection's database; `'lakutata_mutex'` by default.
+     * @throws {Error} When the table is not a valid name (letters, digits and `_`, not starting with a digit, without a
+     * database qualifier).
+     */
+    constructor(connection, prefix, mode = 'advisory', table = 'lakutata_mutex') {
+        super();
+        this.connection = connection;
+        this.prefix = prefix;
+        this.mode = mode;
+        this.table = table;
+        this.expiring = mode === 'table';
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table))
+            throw new Error(`The table of the locks "${table}" is not a name of MySQL`);
+    }
+    /**
+     * The configuration given to `mysql2` for the connections.
+     * @returns The `mysql2` connection configuration.
+     */
+    config() {
+        return { host: this.connection.host, port: this.connection.port ?? 3306, database: this.connection.database, user: this.connection.username, password: this.connection.password };
+    }
+    /**
+     * The name of a lock for `GET_LOCK`: `lakutata:` and the start of the SHA-256 digest of the prefixed name, 64
+     * characters in all (the limit of MySQL).
+     * @param name The lock name.
+     * @returns The MySQL lock name.
+     */
+    lockName(name) {
+        return `lakutata:${nameDigest(this.prefix + name).slice(0, 55)}`;
+    }
+    /**
+     * The connection holding the named locks, opened at the first call; when it ends or fails, its locks are reported
+     * lost through {@link MutexDriver.onLost}.
+     * @returns The `mysql2` connection.
+     * @throws {MutexDriverNotFoundException} When the package `mysql2` is not installed.
+     */
+    async session() {
+        if (this.#connection)
+            return this.#connection;
+        this.#connecting ??= (async () => {
+            const mysql = await loadDriver('createConnection', 'mysql2/promise');
+            const connection = await mysql.createConnection(this.config());
+            const lost = () => {
+                if (this.#connection !== connection)
+                    return;
+                this.#connection = undefined;
+                const names = [...this.#held.keys()];
+                this.#held.clear();
+                if (names.length)
+                    this.onLost(names);
+            };
+            connection.on('error', lost);
+            connection.on('end', lost);
+            this.#connection = connection;
+            return connection;
+        })().finally(() => {
+            this.#connecting = undefined;
+        });
+        return await this.#connecting;
+    }
+    /**
+     * The connection pool of the `table` mode, created at the first call along with the tables; created again at the
+     * next call when that fails.
+     * @returns The `mysql2` pool.
+     * @throws {MutexDriverNotFoundException} When the package `mysql2` is not installed.
+     */
+    async pool() {
+        //Created once: the first uses at the same time share it
+        this.#table ??= (async () => {
+            const mysql = await loadDriver('createPool', 'mysql2/promise');
+            const pool = mysql.createPool({ ...this.config(), connectionLimit: 4 });
+            this.#pool = pool;
+            await this.#pool.query(`CREATE TABLE IF NOT EXISTS \`${this.table}\` (\`key\` VARCHAR(64) PRIMARY KEY, name TEXT NOT NULL, token VARCHAR(64) NOT NULL, fence BIGINT NOT NULL, expires_at DATETIME(3) NOT NULL)`);
+            await this.#pool.query(`CREATE TABLE IF NOT EXISTS \`${this.table}_fence\` (id TINYINT PRIMARY KEY, value BIGINT NOT NULL)`);
+            await this.#pool.query(`INSERT IGNORE INTO \`${this.table}_fence\` (id, value) VALUES (1, 0)`);
+        })().catch(async (error) => {
+            //Created again at the next use: this pool closed
+            this.#table = undefined;
+            const failed = this.#pool;
+            this.#pool = undefined;
+            await failed?.end().catch(() => undefined);
+            throw error;
+        });
+        await this.#table;
+        return this.#pool;
+    }
+    /**
+     * Try to acquire a lock once: a named lock of the driver's connection, or a row inserted (or taken over when
+     * expired) in the table.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (the `table` mode only).
+     * @returns The lock (with a fencing token in the `table` mode), or `undefined` when another holder has it, this
+     * driver included.
+     * @throws {MutexDriverNotFoundException} When the package `mysql2` is not installed.
+     */
+    async acquire(name, ttl) {
+        const token = lockToken();
+        if (this.mode === 'table') {
+            const connection = await (await this.pool()).getConnection();
+            try {
+                //The fencing token: the counter incremented, read by the connection (LAST_INSERT_ID)
+                await connection.query(`UPDATE \`${this.table}_fence\` SET value = LAST_INSERT_ID(value + 1) WHERE id = 1`);
+                const [[{ fence }]] = await connection.query('SELECT LAST_INSERT_ID() AS fence');
+                const key = nameDigest(this.prefix + name);
+                //Taken when it is expired: the columns kept otherwise (expires_at assigned last, read before)
+                await connection.query(`INSERT INTO \`${this.table}\` (\`key\`, name, token, fence, expires_at) VALUES (?, ?, ?, ?, NOW(3) + INTERVAL ? MICROSECOND)
+                     ON DUPLICATE KEY UPDATE name = IF(expires_at <= NOW(3), VALUES(name), name), token = IF(expires_at <= NOW(3), VALUES(token), token),
+                     fence = IF(expires_at <= NOW(3), VALUES(fence), fence), expires_at = IF(expires_at <= NOW(3), VALUES(expires_at), expires_at)`, [key, name, token, fence, Math.ceil(ttl) * 1000]);
+                const [rows] = await connection.query(`SELECT token FROM \`${this.table}\` WHERE \`key\` = ?`, [key]);
+                return rows[0]?.token === token ? { token: token, fence: Number(fence) } : undefined;
+            }
+            finally {
+                connection.release();
+            }
+        }
+        if (this.#held.has(name))
+            return undefined;
+        this.#held.set(name, undefined);
+        try {
+            const [[{ locked }]] = await (await this.session()).query('SELECT GET_LOCK(?, 0) AS locked', [this.lockName(name)]);
+            //NULL: an error of the server (the thread killed, out of memory), not a lock held by another
+            if (locked === null)
+                throw new Error(`GET_LOCK failed for the lock ${name}`);
+            if (Number(locked) !== 1) {
+                this.#held.delete(name);
+                return undefined;
+            }
+            this.#held.set(name, token);
+            return { token: token };
+        }
+        catch (error) {
+            this.#held.delete(name);
+            throw error;
+        }
+    }
+    /**
+     * Release a lock still held by this holder: `RELEASE_LOCK`, or delete the row.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the row expired and was taken, or the connection was lost).
+     */
+    async release(name, lock) {
+        if (this.mode === 'table') {
+            const [result] = await (await this.pool()).query(`DELETE FROM \`${this.table}\` WHERE \`key\` = ? AND token = ?`, [nameDigest(this.prefix + name), lock.token]);
+            return result.affectedRows === 1;
+        }
+        if (this.#held.get(name) !== lock.token)
+            return false;
+        this.#held.delete(name);
+        const connection = this.#connection;
+        if (!connection)
+            return false;
+        const [[{ released }]] = await connection.query('SELECT RELEASE_LOCK(?) AS released', [this.lockName(name)]);
+        return Number(released) === 1;
+    }
+    /**
+     * Renew a lock: in the `table` mode, push back the expiration of its row when it still holds this holder's token; in
+     * the `advisory` mode, check that the driver still holds it on its connection, by a query (a connection cut without
+     * notice fails it).
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (the `table` mode only).
+     * @returns Whether the lock is still held by this holder.
+     */
+    async extend(name, lock, ttl) {
+        if (this.mode === 'table') {
+            const [result] = await (await this.pool()).query(`UPDATE \`${this.table}\` SET expires_at = NOW(3) + INTERVAL ? MICROSECOND WHERE \`key\` = ? AND token = ?`, [Math.ceil(ttl) * 1000, nameDigest(this.prefix + name), lock.token]);
+            return result.affectedRows === 1;
+        }
+        //Held as long as its connection: checked by a query (a connection cut silently fails it)
+        const connection = this.#connection;
+        if (this.#held.get(name) !== lock.token || !connection)
+            return false;
+        try {
+            await connection.query('SELECT 1');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Close the connection (MySQL releases its named locks) and the pool; the rows of the `table` mode stay until they
+     * expire.
+     */
+    async close() {
+        const connection = this.#connection;
+        this.#connection = undefined;
+        this.#held.clear();
+        await connection?.end().catch(() => undefined);
+        const pool = this.#pool;
+        this.#pool = undefined;
+        //Created again at the next use
+        this.#table = undefined;
+        await pool?.end().catch(() => undefined);
+    }
+}

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

@@ -0,0 +1,226 @@
+import { MutexDriver } from './MutexDriver.js';
+import { loadDriver } from '../lib/LoadDriver.js';
+import { lockToken, nameDigest, nameKey64 } from '../lib/Names.js';
+/**
+ * The PostgreSQL driver (`{type: 'postgres'}`): the locks are shared by every instance connected to the same database
+ * with the same prefix. It needs the optional peer dependency `pg` (8); without it, the first acquisition fails with
+ * {@link MutexDriverNotFoundException}. It has two modes:
+ * - `'advisory'` (the default): session advisory locks (`pg_try_advisory_lock`) taken on one connection of the driver,
+ *   opened at the first use. They do not expire and need no renewal: PostgreSQL releases them when the connection
+ *   closes, so a crashed process frees them at once. When the connection closes or fails, every lock it held is lost
+ *   (a {@link Mutex} aborts their signals) and the next acquisition opens a new connection. A connection cut without
+ *   the client noticing it is not detected by the renewals. No fencing token. The lock names are hashed to 64-bit keys,
+ *   shared with the other advisory locks of the database. It does not work through a pooler in transaction mode
+ *   (PgBouncer), which does not keep the session.
+ * - `'table'`: one row per lock in a table, created at the first use with its sequence `<table>_fence`. The rows expire
+ *   by the database clock after their `ttl` unless renewed, so it works through the poolers and on the replicated
+ *   setups writing to one primary, and each acquisition gets a fencing token from the sequence. A pool of 4 connections
+ *   is used.
+ * @example
+ * ```typescript
+ * import {PostgresMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: PostgresMutexDriver = new PostgresMutexDriver({
+ *     host: '127.0.0.1',
+ *     database: 'app',
+ *     username: 'app',
+ *     password: 'secret'
+ * }, 'my-app:', 'table', 'app_locks')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) await driver.release('invoice:7', lock)
+ * await driver.close()
+ * ```
+ */
+export class PostgresMutexDriver extends MutexDriver {
+    #client;
+    #pool;
+    #connecting;
+    #table;
+    /**
+     * The advisory locks the connection holds, by name (the ones being acquired too: a session acquires its own lock
+     * again)
+     */
+    #held = new Map();
+    /**
+     * Create a driver on a PostgreSQL database; it connects at its first use.
+     * @param connection The connection to the database.
+     * @param prefix The prefix added to the lock names.
+     * @param mode `'advisory'` (the default) or `'table'`.
+     * @param table The table of the `table` mode, optionally qualified by its schema (`locks.mutex`); `'lakutata_mutex'`
+     * by default.
+     * @throws {Error} When the table is not a valid PostgreSQL name (letters, digits and `_`, not starting with a digit).
+     */
+    constructor(connection, prefix, mode = 'advisory', table = 'lakutata_mutex') {
+        super();
+        this.connection = connection;
+        this.prefix = prefix;
+        this.mode = mode;
+        this.table = table;
+        this.expiring = mode === 'table';
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/.test(table))
+            throw new Error(`The table of the locks "${table}" is not a name of PostgreSQL`);
+    }
+    /**
+     * The configuration given to `pg` for the connection.
+     * @returns The `pg` client configuration.
+     */
+    config() {
+        return { host: this.connection.host, port: this.connection.port ?? 5432, database: this.connection.database, user: this.connection.username, password: this.connection.password, ssl: this.connection.ssl || undefined };
+    }
+    /**
+     * The connection holding the advisory locks, opened at the first call; when it ends or fails, its locks are reported
+     * lost through {@link MutexDriver.onLost}.
+     * @returns The connected `pg` client.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    async client() {
+        if (this.#client)
+            return this.#client;
+        this.#connecting ??= (async () => {
+            const pg = await loadDriver('Client', 'pg');
+            const client = new pg.Client(this.config());
+            const lost = () => {
+                if (this.#client !== client)
+                    return;
+                this.#client = undefined;
+                const names = [...this.#held.keys()];
+                this.#held.clear();
+                if (names.length)
+                    this.onLost(names);
+            };
+            client.on('error', lost);
+            client.on('end', lost);
+            await client.connect();
+            this.#client = client;
+            return client;
+        })().finally(() => {
+            this.#connecting = undefined;
+        });
+        return await this.#connecting;
+    }
+    /**
+     * The connection pool of the `table` mode, created at the first call along with the table and its sequence; created
+     * again at the next call when that fails.
+     * @returns The `pg` pool.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     * @protected
+     */
+    async pool() {
+        //Created once: the first uses at the same time share it
+        this.#table ??= (async () => {
+            const pg = await loadDriver('Pool', 'pg');
+            const pool = new pg.Pool({ ...this.config(), max: 4 });
+            pool.on('error', () => undefined);
+            this.#pool = pool;
+            await this.#pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (key VARCHAR(64) PRIMARY KEY, name TEXT NOT NULL, token VARCHAR(64) NOT NULL, fence BIGINT NOT NULL, expires_at TIMESTAMPTZ NOT NULL)`);
+            await this.#pool.query(`CREATE SEQUENCE IF NOT EXISTS ${this.table}_fence`);
+        })().catch(async (error) => {
+            //Created again at the next use: this pool closed
+            this.#table = undefined;
+            const failed = this.#pool;
+            this.#pool = undefined;
+            await failed?.end().catch(() => undefined);
+            throw error;
+        });
+        await this.#table;
+        return this.#pool;
+    }
+    /**
+     * Try to acquire a lock once: an advisory lock of the driver's connection, or a row inserted (or taken over when
+     * expired) in the table.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (the `table` mode only).
+     * @returns The lock (with a fencing token in the `table` mode), or `undefined` when another holder has it, this
+     * driver included.
+     * @throws {MutexDriverNotFoundException} When the package `pg` is not installed.
+     */
+    async acquire(name, ttl) {
+        const token = lockToken();
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            const result = await pool.query(`INSERT INTO ${this.table} (key, name, token, fence, expires_at) VALUES ($1, $2, $3, nextval('${this.table}_fence'), now() + $4 * interval '1 millisecond')
+                 ON CONFLICT (key) DO UPDATE SET name = excluded.name, token = excluded.token, fence = excluded.fence, expires_at = excluded.expires_at
+                 WHERE ${this.table}.expires_at <= now() RETURNING fence`, [nameDigest(this.prefix + name), name, token, Math.ceil(ttl)]);
+            return result.rows.length ? { token: token, fence: Number(result.rows[0].fence) } : undefined;
+        }
+        if (this.#held.has(name))
+            return undefined;
+        //Being acquired: the other acquisitions of the process refused meanwhile
+        this.#held.set(name, undefined);
+        try {
+            const client = await this.client();
+            const result = await client.query('SELECT pg_try_advisory_lock($1::bigint) AS locked', [nameKey64(this.prefix + name)]);
+            if (!result.rows[0].locked) {
+                this.#held.delete(name);
+                return undefined;
+            }
+            this.#held.set(name, token);
+            return { token: token };
+        }
+        catch (error) {
+            this.#held.delete(name);
+            throw error;
+        }
+    }
+    /**
+     * Release a lock still held by this holder: unlock the advisory lock, or delete the row.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the row expired and was taken, or the connection was lost).
+     */
+    async release(name, lock) {
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            return (await pool.query(`DELETE FROM ${this.table} WHERE key = $1 AND token = $2`, [nameDigest(this.prefix + name), lock.token])).rowCount === 1;
+        }
+        if (this.#held.get(name) !== lock.token)
+            return false;
+        this.#held.delete(name);
+        const client = this.#client;
+        if (!client)
+            return false;
+        return !!(await client.query('SELECT pg_advisory_unlock($1::bigint) AS unlocked', [nameKey64(this.prefix + name)])).rows[0].unlocked;
+    }
+    /**
+     * Renew a lock: in the `table` mode, push back the expiration of its row when it still holds this holder's token; in
+     * the `advisory` mode, check that the driver still holds it on its connection, by a query (a connection cut
+     * without notice fails it).
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (the `table` mode only).
+     * @returns Whether the lock is still held by this holder.
+     */
+    async extend(name, lock, ttl) {
+        if (this.mode === 'table') {
+            const pool = await this.pool();
+            return (await pool.query(`UPDATE ${this.table} SET expires_at = now() + $3 * interval '1 millisecond' WHERE key = $1 AND token = $2`, [nameDigest(this.prefix + name), lock.token, Math.ceil(ttl)])).rowCount === 1;
+        }
+        //Held as long as its connection: checked by a query (a connection cut silently fails it)
+        const client = this.#client;
+        if (this.#held.get(name) !== lock.token || !client)
+            return false;
+        try {
+            await client.query('SELECT 1');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Close the connection (PostgreSQL releases its advisory locks) and the pool; the rows of the `table` mode stay until
+     * they expire.
+     */
+    async close() {
+        const client = this.#client;
+        this.#client = undefined;
+        this.#held.clear();
+        await client?.end().catch(() => undefined);
+        const pool = this.#pool;
+        this.#pool = undefined;
+        //Created again at the next use
+        this.#table = undefined;
+        await pool?.end().catch(() => undefined);
+    }
+}

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

@@ -0,0 +1,176 @@
+import { MutexDriver } from './MutexDriver.js';
+import { loadDriver } from '../lib/LoadDriver.js';
+import { lockToken } from '../lib/Names.js';
+/**
+ * The milliseconds a connection to the server is waited for
+ */
+const CONNECT_TIMEOUT = 5000;
+/**
+ * Set the key when it does not exist, its fencing token incremented: the token, or 0
+ */
+const ACQUIRE = `if redis.call('SET', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then return redis.call('INCR', KEYS[2]) end return 0`;
+/**
+ * Delete the key when it is the one of the holder
+ */
+const RELEASE = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) end return 0`;
+/**
+ * Renew the key when it is the one of the holder
+ */
+const EXTEND = `if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) end return 0`;
+/**
+ * The Redis driver (`{type: 'redis'}`): the locks are Redis keys holding their holder's token, shared by every instance
+ * connected to the same server (or cluster) with the same prefix. It needs the optional peer dependency `redis` (4.6 or
+ * 5); without it, the first acquisition fails with {@link MutexDriverNotFoundException}.
+ *
+ * The keys expire after their `ttl` unless renewed (`PEXPIRE`), and are released and renewed only for their holder's
+ * token. Each acquisition increments a fencing token kept in a second key (`<key>:fence`, never expiring); the lock's
+ * name is the key's hash tag, so both keys stay in the same slot of a cluster. Configure the server with
+ * `maxmemory-policy noeviction`: an evicted key is a lock lost. The locks of one primary are lost if it fails over before
+ * replicating them.
+ *
+ * The client connects at the first use. While the server cannot be reached, the calls wait for it to come back
+ * instead of failing (the client retries without limit): an acquisition does not end at its timeout, and the renewals
+ * do not complete, so the held locks are not marked lost while their keys may expire in Redis.
+ * @example
+ * ```typescript
+ * import {RedisMutexDriver, type DriverLock} from 'lakutata/com/mutex'
+ *
+ * const driver: RedisMutexDriver = new RedisMutexDriver({url: 'redis://127.0.0.1:6379'}, 'my-app:')
+ * const lock: DriverLock | undefined = await driver.acquire('invoice:7', 30000)
+ * if (lock) {
+ *     //Increases with each acquisition: written along with the data to refuse an older holder's writes
+ *     console.log(lock.fence)
+ *     await driver.release('invoice:7', lock)
+ * }
+ * await driver.close()
+ * ```
+ */
+export class RedisMutexDriver extends MutexDriver {
+    #client;
+    #connecting;
+    /**
+     * Create a driver on a Redis server; it connects at its first use.
+     * @param connection The connection to the server.
+     * @param prefix The prefix of the keys.
+     */
+    constructor(connection, prefix) {
+        super();
+        this.connection = connection;
+        this.prefix = prefix;
+        /**
+         * `true`: the locks expire after their `ttl` unless renewed.
+         */
+        this.expiring = true;
+    }
+    /**
+     * The Redis client, connected at the first call; the concurrent first calls share one connection. An unreachable
+     * server fails the calls: the first connection is given up after 5 seconds, and while the client reconnects the
+     * calls fail at once (its commands are not queued).
+     * @returns The connected client.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     * @throws {Error} When the server is not reachable.
+     * @protected
+     */
+    async client() {
+        const current = this.#client;
+        if (current?.isReady)
+            return current;
+        //Reconnecting: the calls fail at once until it is connected again (no new client)
+        if (current?.isOpen)
+            throw new Error('The Redis server of the locks is not reachable: reconnecting');
+        this.#connecting ??= (async () => {
+            const { createClient } = await loadDriver('createClient', 'redis');
+            const options = this.connection;
+            const client = createClient({
+                ...options.url ? { url: options.url } : {},
+                socket: {
+                    ...options.url ? {} : { host: options.host ?? '127.0.0.1', port: options.port ?? 6379, tls: options.tls || undefined },
+                    connectTimeout: CONNECT_TIMEOUT
+                },
+                username: options.username,
+                password: options.password,
+                database: options.database,
+                //The commands sent while disconnected fail at once rather than waiting for the connection
+                disableOfflineQueue: true
+            });
+            //The errors of the connection are the ones of the calls (reconnected by the client)
+            client.on('error', () => undefined);
+            let timer;
+            try {
+                //The client retries its first connection endlessly: given up after a while
+                await Promise.race([client.connect(), new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => reject(new Error(`The Redis server of the locks is not reachable in ${CONNECT_TIMEOUT} ms`)), CONNECT_TIMEOUT);
+                    })]);
+            }
+            catch (error) {
+                try {
+                    await client.disconnect();
+                }
+                catch {
+                    //Not connected
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            this.#client = client;
+            return client;
+        })().finally(() => {
+            this.#connecting = undefined;
+        });
+        return await this.#connecting;
+    }
+    /**
+     * The key of a lock: `<prefix>{<name>}`, the name being the hash tag that keeps the lock and its fencing token in the
+     * same slot of a cluster.
+     * @param name The lock name.
+     * @returns The Redis key.
+     */
+    key(name) {
+        return `${this.prefix}{${name}}`;
+    }
+    /**
+     * Try to acquire a lock once: set its key when it does not exist, with a fencing token incremented.
+     * @param name The lock name.
+     * @param ttl How long the lock stays held without a renewal, in milliseconds (rounded up).
+     * @returns The lock with its fencing token, or `undefined` when another holder has it.
+     * @throws {MutexDriverNotFoundException} When the package `redis` is not installed.
+     */
+    async acquire(name, ttl) {
+        const client = await this.client();
+        const token = lockToken();
+        const fence = Number(await client.eval(ACQUIRE, { keys: [this.key(name), `${this.key(name)}:fence`], arguments: [token, String(Math.ceil(ttl))] }));
+        return fence ? { token: token, fence: fence } : undefined;
+    }
+    /**
+     * Release a lock by deleting its key, when it still holds this holder's token.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @returns Whether it was released (`false` when the key expired or was taken).
+     */
+    async release(name, lock) {
+        const client = await this.client();
+        return Number(await client.eval(RELEASE, { keys: [this.key(name)], arguments: [lock.token] })) === 1;
+    }
+    /**
+     * Renew a lock whose key still holds this holder's token, for `ttl` milliseconds from now.
+     * @param name The lock name.
+     * @param lock The lock acquired.
+     * @param ttl How long the lock stays held without another renewal, in milliseconds (rounded up).
+     * @returns Whether it was renewed (`false` when the key expired or was taken).
+     */
+    async extend(name, lock, ttl) {
+        const client = await this.client();
+        return Number(await client.eval(EXTEND, { keys: [this.key(name)], arguments: [lock.token, String(Math.ceil(ttl))] })) === 1;
+    }
+    /**
+     * Close the connection (`QUIT`, or a disconnection when it fails); the keys stay until they expire.
+     */
+    async close() {
+        const client = this.#client;
+        this.#client = undefined;
+        if (client?.isOpen)
+            await client.quit().catch(() => client.disconnect());
+    }
+}

package/dist/esm/mutex/exceptions/MutexDriverException.js

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by the {@link Mutex} methods when the lock store fails (unreachable, a failed query, a file error), its
+ * message carrying the driver's error. An automatic renewal failing this way makes the lock lost instead. Its `errno` is
+ * `'E_MUTEX_DRIVER'`.
+ */
+export class MutexDriverException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_MUTEX_DRIVER'`.
+         */
+        this.errno = 'E_MUTEX_DRIVER';
+    }
+}

package/dist/esm/mutex/exceptions/MutexDriverNotFoundException.js

@@ -0,0 +1,15 @@
+import { Exception } from '@lakutata/core';
+/**
+ * Thrown by the first acquisition of a {@link Mutex} (or a driver) whose client package is not installed: `redis` for
+ * the Redis driver, `pg` for PostgreSQL, `mysql2` for MySQL. Its message names the package to install. Its `errno` is
+ * `'E_MUTEX_DRIVER_NOT_FOUND'`.
+ */
+export class MutexDriverNotFoundException extends Exception {
+    constructor() {
+        super(...arguments);
+        /**
+         * `'E_MUTEX_DRIVER_NOT_FOUND'`.
+         */
+        this.errno = 'E_MUTEX_DRIVER_NOT_FOUND';
+    }
+}