@alexify/migronaut 2.1.0 → 2.2.0

package/src/core/server-info.js

@@ -0,0 +1,63 @@
+/**
+ * What converge and audit read about the server, and how: the read options
+ * forced onto every read, the pace of reading many collections, the server's
+ * version and topology, and the error codes for a namespace or an index that
+ * is not there. Mechanism only — no logger, no decisions.
+ */
+
+/**
+ * Read options forced onto both reads: the primary (a secondary may not have
+ * an index build yet), and BSON values as plain JavaScript — an injected
+ * client configured with `promoteValues: false` or `useBigInt64: true` would
+ * otherwise hand back `Int32` objects or `1n`, and everything would compare as
+ * changed.
+ */
+const READ_OPTIONS = Object.freeze({
+  readPreference: 'primary',
+  promoteLongs: true,
+  promoteValues: true,
+  useBigInt64: false,
+  bsonRegExp: false,
+});
+
+/** listIndexes calls in flight while reading many collections — a pace, not a pool */
+const READ_CONCURRENCY = 8;
+
+/**
+ * What the server is: a mongos in front of shards (its shard keys matter to
+ * prune), and its version (what it can change in place). Best-effort — a
+ * server that refuses to say gets the conservative answer: no in-place
+ * extras, no shard-key handling.
+ */
+async function readServer(db) {
+  const server = { mongos: false, version: undefined };
+  if (typeof db.admin !== 'function') return server;
+  try {
+    const hello = await db.admin().command({ hello: 1 });
+    server.mongos = hello?.msg === 'isdbgrid';
+  } catch {
+    // Unknown — treated as a replica set or standalone.
+  }
+  try {
+    const info = await db.admin().command({ buildInfo: 1 });
+    const [major, minor, patch] = Array.isArray(info?.versionArray) ? info.versionArray : [];
+    if (Number.isInteger(major) && Number.isInteger(minor)) {
+      server.version = { major, minor, ...(Number.isInteger(patch) ? { patch } : {}) };
+    }
+  } catch {
+    // Unknown version: only the always-available in-place changes.
+  }
+  return server;
+}
+
+const NAMESPACE_NOT_FOUND = 26;
+
+const INDEX_NOT_FOUND = 27;
+
+module.exports = {
+  INDEX_NOT_FOUND,
+  NAMESPACE_NOT_FOUND,
+  READ_CONCURRENCY,
+  READ_OPTIONS,
+  readServer,
+};

package/src/errors/index.js

@@ -243,11 +243,15 @@ class QueueJobFailedError extends MigronautError {
 
 /**
  * Thrown by `converge` when the database cannot be brought to the declared
- * state: the plan has a conflict (refused before any write — `context.phase`
- * is `'plan'`), or a step failed (`'apply'`). `context.converge` is the
- * converge result so far — which steps were applied, which failed, which were
- * never reached — and `context.hint`, when present, says what usually fixes
- * the server error behind it.
+ * state. `context.phase` says where it stopped: `'plan'` (a conflict refused
+ * the run before any write), `'replan'` (a collection changed while the run
+ * was under way), `'apply'` (a step failed) or `'wait'` (the search index
+ * builds did not finish — `context.reason`: `'failed'`, `'timeout'` or
+ * `'unreadable'`). A search index list that could not be read is reported in
+ * the phase that read it. `context.converge` is the converge result so far —
+ * which steps were applied, which failed, which were never reached — and
+ * `context.hint`, when present, says what usually fixes the server error
+ * behind it.
  */
 class ConvergeFailedError extends MigronautError {
   constructor(message, context, options) {

package/src/utils/canonical.js

@@ -100,6 +100,31 @@ function regExpIssue(value, seen = new Set()) {
   return null;
 }
 
+/**
+ * Why `value` cannot be sent as declared — a function, a symbol, a cycle, or a
+ * RegExp the driver would change (see {@link regExpIssue}) — or null. Walks
+ * plain objects and arrays, the shapes a declaration is written in.
+ */
+function unsendable(value, seen = new Set()) {
+  if (seen.size === 0) {
+    const issue = regExpIssue(value);
+    if (issue) return issue;
+  }
+  const type = typeof value;
+  if (type === 'function') return 'must not contain functions';
+  if (type === 'symbol') return 'must not contain symbols';
+  if (value === null || type !== 'object') return null;
+  if (seen.has(value)) return 'must not contain circular references';
+  seen.add(value);
+  const items = Array.isArray(value) ? value : isPlainObject(value) ? Object.values(value) : [];
+  for (const item of items) {
+    const reason = unsendable(item, seen);
+    if (reason) return reason;
+  }
+  seen.delete(value);
+  return null;
+}
+
 /**
  * Assign without invoking setters: a key named `__proto__` (JSON.parse makes
  * one an own property) must stay a key, not replace the object's prototype —
@@ -176,4 +201,12 @@ function toWire(value) {
   return out;
 }
 
-module.exports = { canonical, deepEqual, isPlainObject, regExpIssue, toWire };
+module.exports = {
+  assign,
+  canonical,
+  deepEqual,
+  isPlainObject,
+  regExpIssue,
+  toWire,
+  unsendable,
+};

package/src/utils/telemetry.js

@@ -28,6 +28,7 @@ const ATTRIBUTES = {
   LOCK_SKIPPED: 'migronaut.lock.skipped',
   LOCK_LOST_REASON: 'migronaut.lock.lost_reason',
   LOCK_WAIT_OUTCOME: 'migronaut.lock.wait.outcome',
+  SEARCH_WAIT_OUTCOME: 'migronaut.converge.search.wait.outcome',
   MIGRATION_NAME: 'migronaut.migration.name',
   MIGRATION_DIRECTION: 'migronaut.migration.direction',
   MIGRATION_BATCH: 'migronaut.migration.batch',
@@ -46,6 +47,7 @@ const METRICS = {
   LOCK_WAIT_DURATION: 'migronaut.lock.wait.duration',
   LOCK_REFUSED: 'migronaut.lock.refused',
   LOCK_LOST: 'migronaut.lock.lost',
+  SEARCH_WAIT_DURATION: 'migronaut.converge.search.wait.duration',
 };
 
 /**
@@ -130,6 +132,9 @@ function failureText(error) {
 
 /** The parts of `telemetry` — anything else in it is a typo, mentioned at debug level */
 const TELEMETRY_KEYS = Object.freeze(['tracer', 'meter', 'attributes']);
+
+/** The types a static attribute's value may have */
+const ATTRIBUTE_VALUE_TYPES = new Set(['string', 'number', 'boolean']);
 /** Static attributes are dimensions: a handful at most */
 const MAX_STATIC_ATTRIBUTES = 20;
 
@@ -184,7 +189,7 @@ function telemetryIssues(telemetry) {
       }
       for (const key of keys) {
         const value = attributes[key];
-        if (!['string', 'number', 'boolean'].includes(typeof value)) {
+        if (!ATTRIBUTE_VALUE_TYPES.has(typeof value)) {
           issues.push({
             path: `telemetry.attributes.${key}`,
             message: 'must be a string, a number or a boolean',
@@ -329,6 +334,10 @@ function createTelemetry(telemetry, { dbName } = {}) {
     '{refusal}',
   );
   const lockLost = counter(METRICS.LOCK_LOST, 'Migration locks lost mid-run', '{loss}');
+  const searchWaitDuration = histogram(
+    METRICS.SEARCH_WAIT_DURATION,
+    'Time a converge waited for its search index builds, by how the wait ended',
+  );
 
   // Durations are measured in milliseconds everywhere in migronaut and
   // reported in seconds, the unit OpenTelemetry's conventions settle on.
@@ -374,6 +383,14 @@ function createTelemetry(telemetry, { dbName } = {}) {
     lockLost() {
       increment(lockLost);
     },
+    /**
+     * A converge's wait for search index builds ended — `outcome` is
+     * `'ready'`, `'failed'`, `'timeout'`, `'unreadable'` or `'aborted'`. One
+     * point per wait, however many polls.
+     */
+    searchWaited({ waitedMs, outcome }) {
+      record(searchWaitDuration, waitedMs, { [ATTRIBUTES.SEARCH_WAIT_OUTCOME]: outcome });
+    },
   };
 }
 

package/src/utils/template.js

@@ -358,6 +358,13 @@ function configBody(values, createExtension) {
   // collectionsDir: './collections',
   // Converge at the end of every bulk \`migronaut up\`.
   // convergeAfterUp: false,
+  // Search indexes declared for a server without Atlas Search: refuse the
+  // converge ('fail'), or converge everything else and skip them ('skip').
+  // onSearchUnavailable: 'fail',
+  // Hold converge until every declared search index is queryable — for at
+  // most searchIndexWaitTimeoutMs (10 minutes by default).
+  // waitForSearchIndexes: false,
+  // searchIndexWaitTimeoutMs: 600000,
 
   // ── Lifecycle hooks (code only — not available in JSON config) ──
   // hooks: {