@nocobase/lock-manager 2.1.0-beta.2 → 2.1.0-beta.21

package/README.md

@@ -0,0 +1,99 @@
+# NocoBase
+
+<video width="100%" controls>
+  <source src="https://github.com/user-attachments/assets/4d11a87b-00e2-48f3-9bf7-389d21072d13" type="video/mp4">
+</video>
+
+<p align="center">
+<a href="https://trendshift.io/repositories/4112" target="_blank"><img src="https://trendshift.io/api/badge/repositories/4112" alt="nocobase%2Fnocobase | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.producthunt.com/posts/nocobase?embed=true&utm_source=badge-top-post-topic-badge&utm_medium=badge&utm_souce=badge-nocobase" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-topic-badge.svg?post_id=456520&theme=light&period=weekly&topic_id=267" alt="NocoBase - Scalability&#0045;first&#0044;&#0032;open&#0045;source&#0032;no&#0045;code&#0032;platform | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+</p>
+
+## What is NocoBase
+
+NocoBase is the most extensible AI-powered no-code platform.   
+Total control. Infinite extensibility. AI collaboration.  
+Enable your team to adapt quickly and cut costs dramatically.  
+No years of development. No millions wasted.  
+Deploy NocoBase in minutes — and take control of everything.
+
+Homepage:  
+https://www.nocobase.com/  
+
+Online Demo:  
+https://demo.nocobase.com/new
+
+Documents:  
+https://docs.nocobase.com/
+
+Forum:  
+https://forum.nocobase.com/
+
+Use Cases:  
+https://www.nocobase.com/en/blog/tags/customer-stories
+
+## Release Notes
+
+Our [blog](https://www.nocobase.com/en/blog/timeline) is regularly updated with release notes and provides a weekly summary.
+
+## Distinctive features
+
+### 1. Data model-driven, not form/table–driven
+
+Instead of being constrained by forms or tables, NocoBase adopts a data model–driven approach, separating data structure from user interface to unlock unlimited possibilities.
+
+- UI and data structure are fully decoupled
+- Multiple blocks and actions can be created for the same table or record in any quantity or form
+- Supports the main database, external databases, and third-party APIs as data sources
+
+![model](https://static-docs.nocobase.com/model.png)
+
+### 2. AI employees, integrated into your business systems
+Unlike standalone AI demos, NocoBase allows you to embed AI capabilities seamlessly into your interfaces, workflows, and data context, making AI truly useful in real business scenarios.
+
+- Define AI employees for roles such as translator, analyst, researcher, or assistant
+- Seamless AI–human collaboration in interfaces and workflows
+- Ensure AI usage is secure, transparent, and customizable for your business needs
+
+![AI-employee](https://static-docs.nocobase.com/ai-employee-home.png)
+
+### 3. What you see is what you get, incredibly easy to use
+
+While enabling the development of complex business systems, NocoBase keeps the experience simple and intuitive.
+
+- One-click switch between usage mode and configuration mode
+- Pages serve as a canvas to arrange blocks and actions, similar to Notion
+- Configuration mode is designed for ordinary users, not just programmers
+
+![wysiwyg](https://static-docs.nocobase.com/wysiwyg.gif)
+
+### 4. Everything is a plugin, designed for extension
+Adding more no-code features will never cover every business case. NocoBase is built for extension through its plugin-based microkernel architecture.
+
+- All functionalities are plugins, similar to WordPress
+- Plugins are ready to use upon installation
+- Pages, blocks, actions, APIs, and data sources can all be extended through custom plugins
+
+![plugins](https://static-docs.nocobase.com/plugins.png)
+
+## Installation
+
+NocoBase supports three installation methods:
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/docker-compose">Installing With Docker (👍Recommended)</a>
+
+  Suitable for no-code scenarios, no code to write. When upgrading, just download the latest image and reboot.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/create-nocobase-app">Installing from create-nocobase-app CLI</a>
+
+  The business code of the project is completely independent and supports low-code development.
+
+- <a target="_blank" href="https://docs.nocobase.com/welcome/getting-started/installation/git-clone">Installing from Git source code</a>
+
+  If you want to experience the latest unreleased version, or want to participate in the contribution, you need to make changes and debug on the source code, it is recommended to choose this installation method, which requires a high level of development skills, and if the code has been updated, you can git pull the latest code.
+
+## How NocoBase works
+
+<video width="100%" controls>
+  <source src="https://github.com/user-attachments/assets/8d183b44-9bb5-4792-b08f-bc08fe8dfaaf" type="video/mp4">
+</video>

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.2",
+  "version": "2.1.0-beta.21",
   "main": "lib/index.js",
-  "license": "AGPL-3.0",
+  "license": "Apache-2.0",
   "devDependencies": {
-    "@nocobase/utils": "2.1.0-beta.2",
+    "@nocobase/utils": "2.1.0-beta.21",
     "async-mutex": "^0.5.0"
   },
-  "gitHead": "d80433799fb4a8d59ded4d7eea114d585a137ea0"
+  "gitHead": "324bd82f33fca58e98711688a17ceb65c186b65e"
 }

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);
   }
 }