velocious 1.0.719 → 1.0.720

package/src/database/advisory-lock-runner.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+import {AsyncLocalStorage} from "node:async_hooks"
 import timeout, {TimeoutError} from "awaitery/build/timeout.js"
 import {DEFAULT_ADVISORY_LOCK_ACQUIRE_TIMEOUT_MS} from "./advisory-lock-bound.js"
 import {
@@ -59,6 +60,27 @@ class AdvisoryLockBusyError extends Error {
   }
 }
 
+/**
+ * Advisory locks held by one async context, keyed by
+ * `<databaseIdentifier>\u0000<lock name>` and carrying the re-entry depth plus
+ * the provenance of the tier that actually holds the lock.
+ *
+ * Re-entry is scoped to the async context, not to the process: a nested call
+ * made inside a held callback belongs to the same logical operation and must
+ * not contend with itself, while an unrelated concurrent request in the same
+ * process is a different context and must still wait. That is Ruby's `Monitor`
+ * ("re-entrant for the holding thread") expressed with the async-context
+ * analogue of a thread.
+ *
+ * Without this, the four tiers disagreed on re-entry: a nested acquisition on
+ * a `dedicatedConnection` opened a second connection and self-deadlocked, the
+ * file tier refused it as held, and the lock-server tier received
+ * `already-held` and treated it as contention. Applications worked around it
+ * with hand-passed `*LockHeld` booleans, which is exactly the parameter a
+ * monitor makes redundant.
+ */
+const heldAdvisoryLocks = new AsyncLocalStorage()
+
 /**
  * Thrown when a callback holds an advisory lock longer than `holdTimeoutMs`.
  */
@@ -107,6 +129,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLock(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return await this.runReentrantCallback({callback, entry: heldEntry, name})
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "wait", name})
 
     // The wait mode never returns a deferred outcome, so the value member is present.
@@ -159,6 +185,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async withAdvisoryLockOrFail(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return await this.runReentrantCallback({callback, entry: heldEntry, name})
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "or-fail", name})
 
     // The or-fail mode throws on contention, so the value member is present.
@@ -218,6 +248,10 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<{acquired: true, result: T} | {acquired: false, reason: "contended", lockName: string}>} - Either the held-callback result or the defer outcome.
    */
   async withAdvisoryLockOrDefer(name, callback, args = {}) {
+    const heldEntry = this.heldEntryFor(name)
+
+    if (heldEntry) return {acquired: true, result: await this.runReentrantCallback({callback, entry: heldEntry, name})}
+
     const lockServerResult = await this.attemptLockServer({args, callback, mode: "defer", name})
 
     if (lockServerResult) {
@@ -266,13 +300,69 @@ export default class AdvisoryLockRunner {
    * @returns {Promise<T>} - Resolves with the callback result.
    */
   async runLockedCallback({callback, holdTimeoutMs, lockBackend, name, release}) {
+    const store = new Map(heldAdvisoryLocks.getStore() ?? [])
+
+    store.set(this.lockStorageKey(name), {depth: 1, lockBackend})
+
     try {
-      return await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend)
+      // The lock is released outside the context scope: a release path that
+      // touches the same name (a cleanup hook, an error reporter) must not look
+      // like a re-entry of a hold that is already over.
+      return await heldAdvisoryLocks.run(store, async () => await AdvisoryLockRunner.runWithAdvisoryLockHoldTimeout(name, callback, holdTimeoutMs, lockBackend))
     } finally {
       await release()
     }
   }
 
+  /**
+   * Returns the held entry when this async context already holds the lock.
+   * @param {string} name - Lock name.
+   * @returns {{depth: number, lockBackend: AdvisoryLockBackendProvenance} | null} - The held entry, or null when this context does not hold the lock.
+   */
+  heldEntryFor(name) {
+    const store = heldAdvisoryLocks.getStore()
+
+    if (!store) return null
+
+    return store.get(this.lockStorageKey(name)) ?? null
+  }
+
+  /**
+   * Runs a callback as a re-entry of a lock this async context already holds.
+   *
+   * The re-entry adds no backend round trip and cannot fail on contention: the
+   * outer hold already owns the lock, so mutual exclusion is unchanged. The
+   * outer hold owns the hold timeout and the lease; a re-entry does not start a
+   * second one, and the callback therefore receives the outer provenance without
+   * a `control`.
+   * @template T
+   * @param {{callback: (args?: {control?: import("awaitery/build/timeout.js").TimeoutControl, lockBackend: AdvisoryLockBackendProvenance}) => Promise<T>, entry: {depth: number, lockBackend: AdvisoryLockBackendProvenance}, name: string}} args - Re-entry request.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async runReentrantCallback({callback, entry, name}) {
+    entry.depth += 1
+    this.configuration.recordAdvisoryLockReentry({lockName: name})
+
+    try {
+      return await callback({lockBackend: entry.lockBackend})
+    } finally {
+      entry.depth -= 1
+    }
+  }
+
+  /**
+   * Builds the async-context storage key for one lock name.
+   *
+   * The database identifier is part of the key because it is part of the lock's
+   * identity: two tenant databases reusing one name hold two different locks,
+   * and a nested call in the other database is not a re-entry.
+   * @param {string} name - Lock name.
+   * @returns {string} - Storage key for the held-entry map.
+   */
+  lockStorageKey(name) {
+    return `${this.databaseIdentifier}\u0000${name}`
+  }
+
   /**
    * Serves one acquisition on the lock-server tier when the lock name prefers
    * it (design §1/§9), falling *upward* to the driver path when the server is