@nocobase/lock-manager 2.1.0-beta.7 → 2.1.0-beta.9

package/lib/lock-manager.d.ts

@@ -7,9 +7,20 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 export type Releaser = () => void | Promise<void>;
+/**
+ * A lock handle returned by {@link ILockAdapter.tryAcquire}.
+ *
+ * **Important**: the underlying mutex is already held when this object is
+ * returned.  The caller MUST invoke one of `acquire()`, `runExclusive()`, or
+ * `release()` promptly; if none is called the lock will be held indefinitely.
+ *
+ * Use `release()` to abandon the lock without executing any work (e.g. when an
+ * early-return or error prevents the caller from proceeding).
+ */
 export interface ILock {
     acquire(ttl: number): Releaser | Promise<Releaser>;
     runExclusive<T>(fn: () => Promise<T>, ttl: number): Promise<T>;
+    release(): void | Promise<void>;
 }
 export interface ILockAdapter {
     connect(): Promise<void>;
@@ -41,6 +52,6 @@ export declare class LockManager {
     close(): Promise<void>;
     acquire(key: string, ttl?: number): Promise<Releaser>;
     runExclusive<T>(key: string, fn: () => Promise<T>, ttl?: number): Promise<T>;
-    tryAcquire(key: string): Promise<ILock>;
+    tryAcquire(key: string, timeout?: number): Promise<ILock>;
 }
 export default LockManager;

package/lib/lock-manager.js

@@ -97,17 +97,69 @@ const _LocalLockAdapter = class _LocalLockAdapter {
       clearTimeout(timer);
     }
   }
-  async tryAcquire(key) {
-    const lock = this.getLock(key);
-    if (lock.isLocked()) {
-      throw new LockAcquireError("lock is locked");
+  async tryAcquire(key, timeout = 0) {
+    const mutex = this.getLock(key);
+    let preAcquiredRelease;
+    if (timeout === 0) {
+      if (mutex.isLocked()) {
+        throw new LockAcquireError("lock is locked");
+      }
+      preAcquiredRelease = await mutex.acquire();
+    } else {
+      try {
+        preAcquiredRelease = await (0, import_async_mutex.withTimeout)(mutex, timeout).acquire();
+      } catch (e) {
+        throw new LockAcquireError("lock acquire timed out", { cause: e });
+      }
     }
+    let preAcquiredConsumed = false;
+    const getRelease = /* @__PURE__ */ __name(async () => {
+      const rawRelease = !preAcquiredConsumed ? (preAcquiredConsumed = true, preAcquiredRelease) : await mutex.acquire();
+      let released = false;
+      return () => {
+        if (!released) {
+          released = true;
+          return rawRelease();
+        }
+      };
+    }, "getRelease");
     return {
+      release: /* @__PURE__ */ __name(async () => {
+        const release = await getRelease();
+        await release();
+      }, "release"),
       acquire: /* @__PURE__ */ __name(async (ttl) => {
-        return this.acquire(key, ttl);
+        const release = await getRelease();
+        const timer = setTimeout(() => {
+          if (mutex.isLocked()) {
+            release();
+          }
+        }, ttl);
+        return () => {
+          release();
+          clearTimeout(timer);
+        };
       }, "acquire"),
       runExclusive: /* @__PURE__ */ __name(async (fn, ttl) => {
-        return this.runExclusive(key, fn, ttl);
+        const release = await getRelease();
+        let timer;
+        try {
+          timer = setTimeout(() => {
+            if (mutex.isLocked()) {
+              release();
+            }
+          }, ttl);
+          return await fn();
+        } catch (e) {
+          if (e === import_async_mutex.E_CANCELED) {
+            throw new LockAbortError("Lock aborted", { cause: import_async_mutex.E_CANCELED });
+          } else {
+            throw e;
+          }
+        } finally {
+          clearTimeout(timer);
+          release();
+        }
       }, "runExclusive")
     };
   }
@@ -155,9 +207,9 @@ const _LockManager = class _LockManager {
     const client = await this.getAdapter();
     return client.runExclusive(key, fn, ttl);
   }
-  async tryAcquire(key) {
+  async tryAcquire(key, timeout = 0) {
     const client = await this.getAdapter();
-    return client.tryAcquire(key);
+    return client.tryAcquire(key, timeout);
   }
 };
 __name(_LockManager, "LockManager");

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@nocobase/lock-manager",
-  "version": "2.1.0-beta.7",
+  "version": "2.1.0-beta.9",
   "main": "lib/index.js",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@nocobase/utils": "2.1.0-beta.7",
+    "@nocobase/utils": "2.1.0-beta.9",
     "async-mutex": "^0.5.0"
   },
-  "gitHead": "da7dfef2b6d6854988a56119463c8c38e3221e79"
+  "gitHead": "c3a2875e4cbbb43b1f2361e6f9f5f84a7d3f3c3c"
 }

package/src/__tests__/lock-manager.test.ts

@@ -165,5 +165,71 @@ describe('lock manager', () => {
       await r2();
       expect(order).toEqual([1, 2, 3, 4]);
     });
+
+    it('tryAcquire: only one concurrent caller wins (TOCTOU race)', async () => {
+      // Simulate two nodes calling tryAcquire at the same time (single-process,
+      // like createMockCluster). Only one should succeed; the other must throw.
+      const results: Array<'acquired' | 'skipped'> = [];
+      await Promise.all(
+        [0, 1].map(async () => {
+          try {
+            const lock = await lockManager.tryAcquire('race-test');
+            const release = await lock.acquire(1000);
+            results.push('acquired');
+            await release();
+          } catch (e) {
+            if (e instanceof LockAcquireError) {
+              results.push('skipped');
+            } else {
+              throw e;
+            }
+          }
+        }),
+      );
+      expect(results.filter((r) => r === 'acquired').length).toBe(1);
+      expect(results.filter((r) => r === 'skipped').length).toBe(1);
+    });
+
+    it('tryAcquire: waits up to timeout ms before throwing when lock is held', async () => {
+      // Acquire the lock manually so it is held during the tryAcquire call.
+      const holdRelease = await lockManager.acquire('wait-test');
+
+      // Release the lock after 50 ms — tryAcquire with timeout=1000 should
+      // succeed because the lock becomes available well within the window.
+      // Using a large margin (50ms release vs 1000ms timeout) to avoid flakiness
+      // on slow CI machines under load.
+      setTimeout(() => holdRelease(), 50);
+      const lock = await lockManager.tryAcquire('wait-test', 1000);
+      const release = await lock.acquire(1000);
+      await release();
+    });
+
+    it('tryAcquire: throws LockAcquireError when timeout expires before lock is released', async () => {
+      const holdRelease = await lockManager.acquire('timeout-test');
+      // Lock is held; tryAcquire with a very short timeout should fail.
+      await expect(lockManager.tryAcquire('timeout-test', 50)).rejects.toThrowError(LockAcquireError);
+      await holdRelease();
+    });
+
+    it('tryAcquire: subsequent call succeeds after previous lock is released', async () => {
+      const lock1 = await lockManager.tryAcquire('seq-test');
+      const release = await lock1.acquire(1000);
+      await release();
+      // After release, a second tryAcquire on the same key should succeed
+      const lock2 = await lockManager.tryAcquire('seq-test');
+      const release2 = await lock2.acquire(1000);
+      await release2();
+    });
+
+    it('tryAcquire: release() abandons the pre-acquired lock without executing work', async () => {
+      // Acquire the lock via tryAcquire, then immediately release it.
+      const lock = await lockManager.tryAcquire('cancel-test');
+      await lock.release();
+
+      // The lock should now be free; a subsequent tryAcquire must succeed.
+      const lock2 = await lockManager.tryAcquire('cancel-test');
+      const r = await lock2.acquire(1000);
+      await r();
+    });
   });
 });

package/src/lock-manager.ts

@@ -8,13 +8,24 @@
  */
 
 import { Registry } from '@nocobase/utils';
-import { Mutex, MutexInterface, E_CANCELED } from 'async-mutex';
+import { Mutex, MutexInterface, E_CANCELED, withTimeout } from 'async-mutex';
 
 export type Releaser = () => void | Promise<void>;
 
+/**
+ * A lock handle returned by {@link ILockAdapter.tryAcquire}.
+ *
+ * **Important**: the underlying mutex is already held when this object is
+ * returned.  The caller MUST invoke one of `acquire()`, `runExclusive()`, or
+ * `release()` promptly; if none is called the lock will be held indefinitely.
+ *
+ * Use `release()` to abandon the lock without executing any work (e.g. when an
+ * early-return or error prevents the caller from proceeding).
+ */
 export interface ILock {
   acquire(ttl: number): Releaser | Promise<Releaser>;
   runExclusive<T>(fn: () => Promise<T>, ttl: number): Promise<T>;
+  release(): void | Promise<void>;
 }
 
 export interface ILockAdapter {
@@ -87,17 +98,85 @@ class LocalLockAdapter implements ILockAdapter {
     }
   }
 
-  async tryAcquire(key: string) {
-    const lock = this.getLock(key);
-    if (lock.isLocked()) {
-      throw new LockAcquireError('lock is locked');
+  async tryAcquire(key: string, timeout = 0) {
+    const mutex = this.getLock(key);
+    let preAcquiredRelease: Releaser;
+
+    if (timeout === 0) {
+      // Non-blocking: throw immediately if the lock is already held.
+      // mutex.acquire() is called synchronously (before any await boundary) so
+      // that _locked=true is set atomically within the current JS execution
+      // slice, preventing TOCTOU races in single-process cluster simulations
+      // (e.g. tests using createMockCluster).
+      if (mutex.isLocked()) {
+        throw new LockAcquireError('lock is locked');
+      }
+      preAcquiredRelease = (await mutex.acquire()) as Releaser;
+    } else {
+      // Blocking with timeout: wait up to `timeout` ms for the lock, then
+      // throw. withTimeout() from async-mutex handles queue cleanup properly
+      // when the timeout fires before the lock is acquired.
+      try {
+        preAcquiredRelease = (await withTimeout(mutex, timeout).acquire()) as Releaser;
+      } catch (e) {
+        throw new LockAcquireError('lock acquire timed out', { cause: e });
+      }
     }
+
+    let preAcquiredConsumed = false;
+
+    const getRelease = async (): Promise<Releaser> => {
+      const rawRelease: Releaser = !preAcquiredConsumed
+        ? ((preAcquiredConsumed = true), preAcquiredRelease)
+        : ((await mutex.acquire()) as Releaser);
+      // Idempotency guard: prevents double-release when both the TTL auto-
+      // release timer and the caller-facing releaser (or finally block) fire.
+      let released = false;
+      return () => {
+        if (!released) {
+          released = true;
+          return (rawRelease as () => void | Promise<void>)();
+        }
+      };
+    };
+
     return {
-      acquire: async (ttl) => {
-        return this.acquire(key, ttl);
+      release: async (): Promise<void> => {
+        const release = await getRelease();
+        await release();
+      },
+      acquire: async (ttl: number): Promise<Releaser> => {
+        const release = await getRelease();
+        const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+          if (mutex.isLocked()) {
+            release();
+          }
+        }, ttl);
+        return () => {
+          release();
+          clearTimeout(timer);
+        };
       },
-      runExclusive: async (fn: () => Promise<any>, ttl) => {
-        return this.runExclusive(key, fn, ttl);
+      runExclusive: async <T>(fn: () => Promise<T>, ttl: number): Promise<T> => {
+        const release = await getRelease();
+        let timer: ReturnType<typeof setTimeout>;
+        try {
+          timer = setTimeout(() => {
+            if (mutex.isLocked()) {
+              release();
+            }
+          }, ttl);
+          return await fn();
+        } catch (e) {
+          if (e === E_CANCELED) {
+            throw new LockAbortError('Lock aborted', { cause: E_CANCELED });
+          } else {
+            throw e;
+          }
+        } finally {
+          clearTimeout(timer);
+          release();
+        }
       },
     };
   }
@@ -160,9 +239,9 @@ export class LockManager {
     return client.runExclusive(key, fn, ttl);
   }
 
-  public async tryAcquire(key: string) {
+  public async tryAcquire(key: string, timeout = 0) {
     const client = await this.getAdapter();
-    return client.tryAcquire(key);
+    return client.tryAcquire(key, timeout);
   }
 }