@alexify/migronaut 2.1.0 → 2.3.0

package/src/core/index-spec.js

@@ -53,6 +53,9 @@ const INDEX_KEYS = new Set([
   ...IGNORED_OPTIONS,
 ]);
 
+/** Every option an index is normalized with — built once, read per index */
+const NORMALIZED_OPTIONS = Object.freeze([...SEMANTIC_OPTIONS, ...DECLARED_ONLY_OPTIONS]);
+
 const BOOLEAN_OPTIONS = new Set(['unique', 'sparse', 'hidden', 'background']);
 const OBJECT_OPTIONS = new Set([
   'partialFilterExpression',
@@ -98,16 +101,20 @@ function keyIssues(key, report) {
     return null;
   }
   let usable = true;
+  let integerLike = false;
   for (const [field, direction] of entries) {
     if (typeof field !== 'string' || field.length === 0) {
       report('field names must be non-empty strings');
       usable = false;
-    } else if (!DIRECTIONS.has(direction)) {
+      continue;
+    }
+    if (!integerLike && INTEGER_LIKE.test(field)) integerLike = true;
+    if (!DIRECTIONS.has(direction)) {
       report(`direction of "${field}" must be 1, -1, 'text', 'hashed', '2d' or '2dsphere'`);
       usable = false;
     }
   }
-  if (usable && entries.length > 1 && entries.some(([field]) => INTEGER_LIKE.test(field))) {
+  if (usable && entries.length > 1 && integerLike) {
     if (!(key instanceof Map)) {
       report(
         'has an integer-like field name — JavaScript reorders such keys, so declare this key ' +
@@ -145,10 +152,14 @@ function indexIssues(index, path) {
     if (!INDEX_KEYS.has(key)) report(key)('is not a supported index option');
   }
   const entries = keyIssues(index.key, report('key'));
-  const isText = entries?.some(([, direction]) => direction === TEXT) ?? false;
+  let isText = false;
   // `wildcardProjection` belongs to an all-fields wildcard (`$**`, compound or
   // not) — the server refuses it on a path wildcard such as `a.$**`.
-  const isAllFieldsWildcard = entries?.some(([field]) => field === '$**') ?? false;
+  let isAllFieldsWildcard = false;
+  for (const [field, direction] of entries ?? []) {
+    if (direction === TEXT) isText = true;
+    if (field === '$**') isAllFieldsWildcard = true;
+  }
 
   if (index.name !== undefined) {
     if (typeof index.name !== 'string' || index.name.length === 0) {
@@ -209,23 +220,23 @@ function indexIssues(index, path) {
 }
 
 /**
- * The key as the server stores it. A text index is not stored under its
- * fields: they collapse into `_fts: 'text', _ftsx: 1` at the position of the
- * first text field, and move into `weights`.
+ * The key as the server stores it, and whether it is a text index — in one
+ * pass. A text index is not stored under its fields: they collapse into
+ * `_fts: 'text', _ftsx: 1` at the position of the first text field, and move
+ * into `weights`.
  */
 function serverKeyOf(entries) {
-  if (!entries.some(([, direction]) => direction === TEXT)) return entries;
   const out = [];
-  let placed = false;
+  let isText = false;
   for (const entry of entries) {
     if (entry[1] !== TEXT) {
       out.push(entry);
-    } else if (!placed) {
+    } else if (!isText) {
       out.push(['_fts', TEXT], ['_ftsx', 1]);
-      placed = true;
+      isText = true;
     }
   }
-  return out;
+  return { serverKey: isText ? out : entries, isText };
 }
 
 /** Text fields at weight 1, then whatever the declaration weighs differently */
@@ -243,10 +254,10 @@ function textWeights(entries, declared) {
  */
 function normalizeDeclaredIndex(index) {
   const entries = keyEntries(index.key);
-  const isText = entries.some(([, direction]) => direction === TEXT);
+  const { serverKey, isText } = serverKeyOf(entries);
   const name = index.name ?? defaultIndexName(entries);
   const options = {};
-  for (const option of [...SEMANTIC_OPTIONS, ...DECLARED_ONLY_OPTIONS]) {
+  for (const option of NORMALIZED_OPTIONS) {
     const value = index[option];
     if (value === undefined) continue;
     // `false` is the server default; sending it would only make the stored
@@ -258,7 +269,7 @@ function normalizeDeclaredIndex(index) {
   return {
     name,
     entries,
-    serverKey: serverKeyOf(entries),
+    serverKey,
     isText,
     options,
     // The key travels as a Map: the field order is the index, and the driver
@@ -271,7 +282,7 @@ function normalizeDeclaredIndex(index) {
 function normalizeLiveIndex(raw) {
   const entries = Object.entries(raw.key ?? {});
   const options = {};
-  for (const option of [...SEMANTIC_OPTIONS, ...DECLARED_ONLY_OPTIONS]) {
+  for (const option of NORMALIZED_OPTIONS) {
     const value = raw[option];
     if (value === undefined) continue;
     if (BOOLEAN_OPTIONS.has(option)) {

package/src/core/lock.js

@@ -8,9 +8,15 @@ const { errorText } = require('../utils/error.js');
 const { randomId } = require('../utils/id.js');
 const { safeUsername } = require('../utils/user.js');
 
-/** Fixed `_id` of the singleton lock document */
+/** Fixed `_id` of the singleton migration lock document */
 const LOCK_ID = 'migronaut_lock';
 
+/** What the migration lock is called in messages — another lock passes its own `label` */
+const LOCK_LABEL = 'migration lock';
+
+/** `migration lock` → `Migration lock`, for the start of a sentence */
+const sentence = (label) => label.charAt(0).toUpperCase() + label.slice(1);
+
 /** Returns true when an error is a MongoDB duplicate-key error (code 11000) */
 function isDuplicateKeyError(error) {
   return typeof error === 'object' && error !== null && 'code' in error && error.code === 11000;
@@ -40,11 +46,19 @@ function toLockInfo(doc) {
  * MongoDB-native distributed lock backed by a single document, using an atomic
  * upsert as a test-and-set. A lock older than `ttlSeconds` is considered stale
  * and may be reclaimed.
+ *
+ * `options.id` is the lock document's `_id` (default: the migration lock's)
+ * and `options.label` what messages call it — so other locks (a background
+ * migration's coordinator, `background:<name>`) live next to the migration
+ * lock in the same collection without ever touching it: `unlock`, the audit
+ * and `forceRelease` of the migration lock only see its own document.
  */
 class MigrationLock {
   #db;
   #collectionName;
   #ttlSeconds;
+  #id;
+  #label;
   /** Token naming this instance as the current holder; set on acquire, cleared on release */
   #owner;
   /**
@@ -55,10 +69,22 @@ class MigrationLock {
    */
   #nonce;
 
-  constructor(db, collectionName, ttlSeconds) {
+  constructor(db, collectionName, ttlSeconds, { id = LOCK_ID, label = LOCK_LABEL } = {}) {
     this.#db = db;
     this.#collectionName = collectionName;
     this.#ttlSeconds = ttlSeconds;
+    this.#id = id;
+    this.#label = label;
+  }
+
+  /** The lock document's `_id` */
+  get id() {
+    return this.#id;
+  }
+
+  /** What messages call this lock */
+  get label() {
+    return this.#label;
   }
 
   /** The token identifying this holder, or undefined when the lock is not held */
@@ -91,7 +117,7 @@ class MigrationLock {
     // strings: a pipeline expression would otherwise interpret a leading `$`
     // in a value as a field path.
     const lockDoc = {
-      _id: LOCK_ID,
+      _id: this.#id,
       lockedAt: '$$NOW',
       pid: { $literal: process.pid },
       host: { $literal: os.hostname() },
@@ -109,7 +135,7 @@ class MigrationLock {
       // or the holder is stale; otherwise keep the current document untouched.
       // The read-back below tells those outcomes apart.
       result = await collection.updateOne(
-        { _id: LOCK_ID },
+        { _id: this.#id },
         [
           {
             $replaceWith: {
@@ -131,8 +157,8 @@ class MigrationLock {
     } catch (error) {
       if (isDuplicateKeyError(error)) {
         // Two processes raced the very first insert; the loser lands here.
-        const holder = await collection.findOne({ _id: LOCK_ID });
-        throw new LockAlreadyHeldError('Migration lock is already held', {
+        const holder = await collection.findOne({ _id: this.#id });
+        throw new LockAlreadyHeldError(`${sentence(this.#label)} is already held`, {
           holder: toLockInfo(holder) ?? undefined,
           ttlMs: this.ttlMs,
         });
@@ -155,9 +181,9 @@ class MigrationLock {
     // writer's document wins; either way the loser reads a different one here
     // and backs off instead of running concurrently. The nonce is what makes
     // that hold when both carry the same owner token.
-    const current = await collection.findOne({ _id: LOCK_ID });
+    const current = await collection.findOne({ _id: this.#id });
     if (!current || current.owner !== owner || current.nonce !== nonce) {
-      throw new LockAlreadyHeldError('Migration lock is already held', {
+      throw new LockAlreadyHeldError(`${sentence(this.#label)} is already held`, {
         holder: toLockInfo(current) ?? undefined,
         ttlMs: this.ttlMs,
       });
@@ -178,7 +204,7 @@ class MigrationLock {
     }
     const result = await this.#db
       .collection(this.#collectionName)
-      .updateOne({ _id: LOCK_ID, owner: this.#owner, nonce: this.#nonce }, [
+      .updateOne({ _id: this.#id, owner: this.#owner, nonce: this.#nonce }, [
         { $set: { lockedAt: '$$NOW' } },
       ]);
     return result.matchedCount === 1;
@@ -186,7 +212,7 @@ class MigrationLock {
 
   /** Read the current lock document, or null when no lock is held */
   async inspect() {
-    return this.#db.collection(this.#collectionName).findOne({ _id: LOCK_ID });
+    return this.#db.collection(this.#collectionName).findOne({ _id: this.#id });
   }
 
   /**
@@ -196,8 +222,8 @@ class MigrationLock {
    */
   async forceRelease() {
     const collection = this.#db.collection(this.#collectionName);
-    const existing = await collection.findOne({ _id: LOCK_ID });
-    await collection.deleteOne({ _id: LOCK_ID });
+    const existing = await collection.findOne({ _id: this.#id });
+    await collection.deleteOne({ _id: this.#id });
     return existing;
   }
 
@@ -213,14 +239,14 @@ class MigrationLock {
    */
   async release() {
     if (!this.#owner) return;
-    const filter = { _id: LOCK_ID, owner: this.#owner, nonce: this.#nonce };
+    const filter = { _id: this.#id, owner: this.#owner, nonce: this.#nonce };
     try {
       await this.#db.collection(this.#collectionName).deleteOne(filter);
       this.#owner = undefined;
       this.#nonce = undefined;
     } catch (error) {
       throw new LockReleaseFailedError(
-        'Failed to release migration lock',
+        `Failed to release ${this.#label}`,
         { error: errorText(error) },
         { cause: error },
       );
@@ -229,10 +255,18 @@ class MigrationLock {
 }
 
 /**
- * Run `fn(signal)` while holding the migration lock. The lock is always
- * released in a `finally` block. While `fn` runs, a heartbeat renews the lock
- * every `ttlMs/2` so a migration that takes longer than the TTL never lets its
- * lock go stale and get reclaimed by another process.
+ * Run `fn(signal, control)` while holding the migration lock. The lock is
+ * always released in a `finally` block. While `fn` runs, a heartbeat renews the
+ * lock every `ttlMs/2` so a migration that takes longer than the TTL never lets
+ * its lock go stale and get reclaimed by another process.
+ *
+ * `control.release()` gives the lock up before `fn` returns — once, for a
+ * tail of work that only reads (converge waiting for search index builds):
+ * the heartbeat stops, the lock document goes, `onLockReleased({ early: true })`
+ * fires, and the signal no longer aborts on a lost lock. It resolves to
+ * whether the lock was released: one that fails is only warned about (the
+ * lock frees itself once its TTL runs out) and tried again at the end. With
+ * `noLock` there is nothing to release (`false`).
  *
  * If the lock is nonetheless lost — another process reclaimed it, or the
  * heartbeat cannot reach the database — the `signal` is aborted with a
@@ -245,6 +279,9 @@ class MigrationLock {
  */
 async function runWithLock(lock, options, fn) {
   const controller = new AbortController();
+  // Any object with acquire/renew/release/ttlMs is a lock here — a partition
+  // lease included; `label` names it in the messages.
+  const label = typeof lock?.label === 'string' ? lock.label : LOCK_LABEL;
 
   if (options.noLock) {
     options.logger.warn('⚠ Running without a lock (--no-lock) — concurrent runs are unsafe', {
@@ -254,7 +291,7 @@ async function runWithLock(lock, options, fn) {
     // `skipped: true` tells them apart from a real lock.
     options.onLockAcquired?.({ skipped: true });
     try {
-      return await fn(controller.signal);
+      return await fn(controller.signal, { release: async () => false });
     } finally {
       options.onLockReleased?.({ skipped: true });
     }
@@ -270,15 +307,13 @@ async function runWithLock(lock, options, fn) {
   const loseLock = (reason) => {
     // The most alert-worthy line this module emits — structured fields so a
     // JSON sink can trigger on it without parsing the human string.
-    options.logger.warn(`⚠ Lost the migration lock mid-run (${reason})`, {
+    options.logger.warn(`⚠ Lost the ${label} mid-run (${reason})`, {
       event: 'lock:lost',
       reason,
     });
     options.onLockLostEvent?.(reason);
     if (abortOnLoss && !controller.signal.aborted) {
-      controller.abort(
-        new LockLostError('Lost the migration lock mid-run', { reason, aborted: true }),
-      );
+      controller.abort(new LockLostError(`Lost the ${label} mid-run`, { reason, aborted: true }));
     }
   };
 
@@ -352,23 +387,53 @@ async function runWithLock(lock, options, fn) {
   }, intervalMs);
   heartbeat.unref?.();
 
+  const stopHeartbeat = async () => {
+    stopped = true;
+    clearInterval(heartbeat);
+    clearTimeout(deadline);
+    // Let any renewal already in flight settle, so no stray query outlives this
+    // call and lands after the caller has closed the client.
+    await inFlight;
+  };
+  let released = false;
+  let releasing;
+  const control = {
+    release: () =>
+      (releasing ??= (async () => {
+        await stopHeartbeat();
+        try {
+          await lock.release();
+          released = true;
+          options.onLockReleased?.({ early: true });
+        } catch (releaseError) {
+          const message = errorText(releaseError);
+          options.logger.warn(
+            `⚠ Failed to release the ${label} early: ${message} — it frees itself once ` +
+              'its TTL runs out',
+            { event: 'lock:release-failed', error: message, early: true },
+          );
+        }
+        return released;
+      })()),
+  };
+
   let result;
   let runError;
   let failed = false;
   try {
-    result = await fn(controller.signal);
+    result = await fn(controller.signal, control);
   } catch (error) {
     failed = true;
     runError = error;
   } finally {
-    stopped = true;
-    clearInterval(heartbeat);
-    clearTimeout(deadline);
-    // Let any renewal already in flight settle, so no stray query outlives this
-    // call and lands after the caller has closed the client.
-    await inFlight;
+    await releasing;
+    await stopHeartbeat();
   }
 
+  if (released) {
+    if (failed) throw runError;
+    return result;
+  }
   try {
     await lock.release();
     options.onLockReleased?.();
@@ -386,7 +451,7 @@ async function runWithLock(lock, options, fn) {
       throw releaseError;
     }
     const message = errorText(releaseError);
-    options.logger.warn(`⚠ Failed to release the migration lock: ${message}`, {
+    options.logger.warn(`⚠ Failed to release the ${label}: ${message}`, {
       event: 'lock:release-failed',
       error: message,
     });
@@ -396,4 +461,4 @@ async function runWithLock(lock, options, fn) {
   return result;
 }
 
-module.exports = { LOCK_ID, MigrationLock, runWithLock, toLockInfo };
+module.exports = { LOCK_ID, LOCK_LABEL, MigrationLock, runWithLock, toLockInfo };