@alexify/migronaut 2.1.0 → 2.2.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

@@ -229,10 +229,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
@@ -254,7 +262,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 });
     }
@@ -352,23 +360,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 migration lock 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?.();

package/src/core/migrator.js

@@ -408,10 +408,12 @@ class MigratorKit extends EventEmitter {
   }
 
   /**
-   * Run `fn` under the migration lock. The single place that pairs a lock with
-   * a unit of work, so `redo` can hold one lock across both directions instead
-   * of releasing between them. `info` names the run (`{command, direction?}`)
-   * for the `run:start`/`run:end` events.
+   * Run `fn(signal, lock)` under the migration lock. The single place that
+   * pairs a lock with a unit of work, so `redo` can hold one lock across both
+   * directions instead of releasing between them. `info` names the run
+   * (`{command, direction?}`) for the `run:start`/`run:end` events.
+   * `lock.release()` gives the lock up before `fn` returns, for a tail that
+   * only reads (see runWithLock) — the run, its id and its span go on.
    */
   async #withLock(options, info, fn) {
     // Not reentrant: a second overlapping run on this instance would clobber
@@ -468,7 +470,7 @@ class MigratorKit extends EventEmitter {
           onLockLostEvent: (reason) => recorder.lockLost(reason),
           ...(options.noLock ? { noLock: true } : {}),
         },
-        (lockSignal) =>
+        (lockSignal, lockControl) =>
           // The run's span exists only once the lock is held: a caller polling
           // for a busy lock retries the whole run every few hundred
           // milliseconds, and a span per refusal would bury the one run that
@@ -476,7 +478,7 @@ class MigratorKit extends EventEmitter {
           // recorder after the release, so the span's outcome is the run's.
           this.#telemetry.open(SPANS.RUN, recorder.spanAttributes(), (span) => {
             recorder.spanOpened(span);
-            return fn(AbortSignal.any([lockSignal, stopper.signal]));
+            return fn(AbortSignal.any([lockSignal, stopper.signal]), lockControl);
           }),
       );
       return result;
@@ -960,7 +962,7 @@ class MigratorKit extends EventEmitter {
           : [];
       return this.#keepDefinitionsWhileRefused(async () => {
         await this.connect();
-        return this.#withLock(options, { command: 'up', direction: 'up' }, async (signal) => {
+        return this.#withLock(options, { command: 'up', direction: 'up' }, async (signal, lock) => {
           const results = await this.#runUp(filename, options, signal);
           // Even when nothing was pending: a converge that failed last time is
           // retried by the next `up` instead of waiting for the next migration.
@@ -968,8 +970,13 @@ class MigratorKit extends EventEmitter {
             this.#assertNotAborted(signal, results);
             try {
               await runConverge(
-                this.#convergeDeps(),
-                { definitions, trigger: 'up', ...pickActor(options) },
+                this.#convergeDeps(lock),
+                {
+                  definitions,
+                  trigger: 'up',
+                  search: this.#convergeSearchOptions(),
+                  ...pickActor(options),
+                },
                 signal,
               );
             } catch (error) {
@@ -1550,6 +1557,7 @@ class MigratorKit extends EventEmitter {
       getDb: () => this.#requireDb(),
       inspectLock: () => this.#buildLock().inspect(),
       status: () => this.status(),
+      definitions: () => this.#resolveCollections(),
     });
   }
 
@@ -1855,7 +1863,13 @@ class MigratorKit extends EventEmitter {
       await this.connect();
       return runConverge(
         this.#convergeDeps(),
-        { definitions, prune: options.prune, rebuildUnique: options.rebuildUnique, dryRun: true },
+        {
+          definitions,
+          prune: options.prune,
+          rebuildUnique: options.rebuildUnique,
+          dryRun: true,
+          search: this.#convergeSearchOptions(),
+        },
         undefined,
       );
     }
@@ -1872,11 +1886,17 @@ class MigratorKit extends EventEmitter {
         return empty(false);
       }
       await this.connect();
-      return this.#withLock(options, { command: 'converge' }, async (signal) => {
+      return this.#withLock(options, { command: 'converge' }, async (signal, lock) => {
         if (options.ordered) await this.#assertNothingPending();
         return runConverge(
-          this.#convergeDeps(),
-          { definitions, prune: options.prune, rebuildUnique: options.rebuildUnique, ...actor },
+          this.#convergeDeps(lock),
+          {
+            definitions,
+            prune: options.prune,
+            rebuildUnique: options.rebuildUnique,
+            search: this.#convergeSearchOptions(options),
+            ...actor,
+          },
           signal,
         );
       });
@@ -1912,10 +1932,23 @@ class MigratorKit extends EventEmitter {
     });
   }
 
-  #convergeDeps() {
+  /** How converge treats search indexes: the config, and a call's own `waitForSearchIndexes` */
+  #convergeSearchOptions(options = {}) {
+    const config = this.#config;
+    return {
+      onUnavailable: config.onSearchUnavailable,
+      wait: options.waitForSearchIndexes ?? config.waitForSearchIndexes,
+      waitTimeoutMs: config.searchIndexWaitTimeoutMs,
+    };
+  }
+
+  /** What runConverge works with; `lock` (a run's) lets it give the lock up before waiting */
+  #convergeDeps(lock) {
     const db = this.#requireDb();
     return {
       db,
+      ...(lock ? { releaseLock: () => lock.release() } : {}),
+      recordSearchWait: (waitedMs, outcome) => this.#telemetry.searchWaited({ waitedMs, outcome }),
       logger: this.#logger,
       fields: (extra) => this.#fields(extra),
       emit: (event, payload) => this.#emit(event, payload),

package/src/core/options.js

@@ -198,11 +198,26 @@ function assertDryRunOptions(filename, options) {
 
 /** `converge(options)` */
 function assertConvergeOptions(options) {
-  for (const key of ['dryRun', 'prune', 'noLock', 'ordered', 'rebuildUnique']) {
+  for (const key of [
+    'dryRun',
+    'prune',
+    'noLock',
+    'ordered',
+    'rebuildUnique',
+    'waitForSearchIndexes',
+  ]) {
     if (options[key] !== undefined && typeof options[key] !== 'boolean') {
       throw new ConfigInvalidError(`${key} must be a boolean`, { [key]: options[key] });
     }
   }
+  // A dry run builds nothing, so there is nothing to wait for — asking for
+  // both is a mistake worth saying, not a wait that silently never happens.
+  if (options.dryRun && options.waitForSearchIndexes) {
+    throw new ConfigInvalidError('waitForSearchIndexes cannot be combined with dryRun', {
+      dryRun: true,
+      waitForSearchIndexes: true,
+    });
+  }
   assertActorValid(options);
 }