@alexify/migronaut 2.0.0 → 2.1.0

package/src/core/options.js

@@ -0,0 +1,251 @@
+const { ConfigInvalidError, MigrationInvalidNameError } = require('../errors/index.js');
+const { actorIssue } = require('../utils/actor.js');
+const { isCollectionName } = require('../utils/collection-name.js');
+
+/**
+ * Validation of the options the kit's run methods take. Pure — no config, no
+ * database, no file system — so every one runs before a run method resolves
+ * its config or connects: a caller mistake costs neither a round trip nor the
+ * lock, and is reported as itself rather than as whatever it would have
+ * broken later.
+ *
+ * Each `assert*Options` is the whole preamble of one method, its checks in
+ * the order that decides which error a caller sees when several apply.
+ */
+
+/**
+ * Reject non-string filenames before they reach a changelog query or a path
+ * join. A programmatic caller passing e.g. `{ $ne: null }` would otherwise
+ * become a query-operator injection in `findOne({ name })`.
+ */
+function assertFilename(filename) {
+  if (filename !== undefined && typeof filename !== 'string') {
+    throw new MigrationInvalidNameError('Migration name must be a string', {
+      name: filename,
+    });
+  }
+}
+
+/**
+ * Validate the `--steps` option for `down`/`dry-run down`: a positive integer,
+ * mutually exclusive with a filename and `--batch`. No-op when steps is unset.
+ */
+function assertStepsValid(steps, filename, batch) {
+  if (steps === undefined) {
+    return;
+  }
+  if (filename) {
+    throw new ConfigInvalidError('Cannot combine a filename with --steps', { filename });
+  }
+  if (batch !== undefined) {
+    throw new ConfigInvalidError('Cannot combine --batch with --steps', { batch, steps });
+  }
+  if (!Number.isInteger(steps) || steps < 1) {
+    throw new ConfigInvalidError('--steps must be a positive integer', { steps });
+  }
+}
+
+/**
+ * `--to` names a point in the sequence, so it cannot be combined with the
+ * other ways of choosing targets.
+ */
+function assertToValid(to, filename, options = {}) {
+  if (to === undefined) return;
+  assertFilename(to);
+  if (filename) {
+    throw new ConfigInvalidError('Cannot combine a filename with --to', { filename, to });
+  }
+  if (options.steps !== undefined) {
+    throw new ConfigInvalidError('Cannot combine --steps with --to', {
+      steps: options.steps,
+      to,
+    });
+  }
+  if (options.batch !== undefined) {
+    throw new ConfigInvalidError('Cannot combine --batch with --to', {
+      batch: options.batch,
+      to,
+    });
+  }
+}
+
+/**
+ * Validate `--batch`. Without this a typo (`--batch abc` → NaN) matches no
+ * records, so the run prints "Nothing to rollback" and exits 0 — the worst
+ * possible answer to a mistyped rollback.
+ */
+function assertBatchValid(batch) {
+  if (batch === undefined) return;
+  if (!Number.isInteger(batch) || batch < 1) {
+    throw new ConfigInvalidError('--batch must be a positive integer', { batch });
+  }
+}
+
+/**
+ * Validate `requestedBy` / `reason`: who asked for a run, and why — stamped
+ * on what it writes to the changelog (and on a converge's history entry).
+ * The OS user that ran it is `executedBy` already; on a queue worker that is
+ * the container's, which is why the requester has a field of its own.
+ */
+function assertActorValid(options) {
+  for (const key of ['requestedBy', 'reason']) {
+    const issue = actorIssue(key, options?.[key]);
+    if (issue) {
+      throw new ConfigInvalidError(issue, {
+        [key]:
+          typeof options[key] === 'string'
+            ? `${options[key].length} characters`
+            : typeof options[key],
+      });
+    }
+  }
+}
+
+/**
+ * Validate `checksum`: the SHA-256 the caller expects the named file to have
+ * — how a queue job says which version of the file it was planned with.
+ */
+function assertChecksumValid(checksum, filename) {
+  if (checksum === undefined) return;
+  if (typeof checksum !== 'string' || !/^[0-9a-f]{64}$/.test(checksum)) {
+    throw new ConfigInvalidError('checksum must be a SHA-256 hex digest', {
+      checksum: typeof checksum,
+    });
+  }
+  if (!filename) {
+    throw new ConfigInvalidError('checksum requires a filename', {});
+  }
+}
+
+/**
+ * Validate `ordered`: a boolean, and only meaningful for a named file — a
+ * bulk run is in order by construction, so asking for it there is a caller
+ * mistake worth naming rather than silently ignoring.
+ */
+function assertOrderedValid(ordered, filename) {
+  if (ordered === undefined) return;
+  if (typeof ordered !== 'boolean') {
+    throw new ConfigInvalidError('ordered must be a boolean', { ordered });
+  }
+  if (ordered && !filename) {
+    throw new ConfigInvalidError('ordered requires a filename', { ordered });
+  }
+}
+
+/** `up`'s `converge` option: a boolean, and only for a bulk run that reaches the head */
+function assertConvergeAfterUpValid(converge, filename, to) {
+  if (converge === undefined) return;
+  if (typeof converge !== 'boolean') {
+    throw new ConfigInvalidError('converge must be a boolean', { converge });
+  }
+  if (converge && filename !== undefined) {
+    throw new ConfigInvalidError('converge cannot follow a single-file up', {
+      converge,
+      filename,
+    });
+  }
+  if (converge && to !== undefined) {
+    throw new ConfigInvalidError(
+      'converge cannot follow up --to: the declared state describes the newest migration',
+      { converge, to },
+    );
+  }
+}
+
+/** `up(filename, options)` */
+function assertUpOptions(filename, options) {
+  assertFilename(filename);
+  // `to` is checked against a filename only: unlike `down`, an explicit
+  // `batch` here is a label for whatever gets applied, not a selector.
+  assertToValid(options.to, filename);
+  assertBatchValid(options.batch);
+  if (options.batch !== undefined && options.step) {
+    throw new ConfigInvalidError('Cannot combine --batch with --step', {
+      batch: options.batch,
+    });
+  }
+  assertOrderedValid(options.ordered, filename);
+  assertConvergeAfterUpValid(options.converge, filename, options.to);
+  assertChecksumValid(options.checksum, filename);
+  assertActorValid(options);
+}
+
+/** `down(filename, options)` */
+function assertDownOptions(filename, options) {
+  assertFilename(filename);
+  assertStepsValid(options.steps, filename, options.batch);
+  assertBatchValid(options.batch);
+  assertToValid(options.to, filename, options);
+  assertOrderedValid(options.ordered, filename);
+  assertActorValid(options);
+}
+
+/** `redo(filename, options)` */
+function assertRedoOptions(filename, options) {
+  assertFilename(filename);
+  assertActorValid(options);
+}
+
+/** `dryRun(direction, filename, options)` */
+function assertDryRunOptions(filename, options) {
+  assertFilename(filename);
+  // `batch`/`to` must be passed too, or a conflict that `down` rejects would
+  // be silently allowed in its own preview.
+  assertStepsValid(options.steps, filename, options.batch);
+  assertBatchValid(options.batch);
+  assertToValid(options.to, filename, options);
+}
+
+/** `converge(options)` */
+function assertConvergeOptions(options) {
+  for (const key of ['dryRun', 'prune', 'noLock', 'ordered', 'rebuildUnique']) {
+    if (options[key] !== undefined && typeof options[key] !== 'boolean') {
+      throw new ConfigInvalidError(`${key} must be a boolean`, { [key]: options[key] });
+    }
+  }
+  assertActorValid(options);
+}
+
+/** `convergeHistory({ limit })` */
+function assertHistoryLimit(limit) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+    throw new ConfigInvalidError('limit must be an integer from 1 to 1000', { limit });
+  }
+}
+
+/** `list(filter, options)` */
+function assertListOptions(filter, options) {
+  if (options.checksums !== undefined && typeof options.checksums !== 'boolean') {
+    throw new ConfigInvalidError('checksums must be a boolean', { checksums: options.checksums });
+  }
+  // An unknown filter silently returning [] reads as "nothing to report" —
+  // the worst possible answer to a typo.
+  if (filter !== 'all' && filter !== 'pending' && filter !== 'applied') {
+    throw new ConfigInvalidError("list filter must be 'all', 'pending' or 'applied'", { filter });
+  }
+}
+
+/**
+ * `import(options)`: a bad --from/--to must not cost a round trip or take the
+ * lock. Defaults come from the already-validated config.
+ */
+function assertImportOptions(options) {
+  if (options.from !== undefined && !isCollectionName(options.from)) {
+    throw new ConfigInvalidError('Invalid source collection name', { from: options.from });
+  }
+  if (options.to !== undefined && !isCollectionName(options.to)) {
+    throw new ConfigInvalidError('Invalid target collection name', { to: options.to });
+  }
+}
+
+module.exports = {
+  assertConvergeOptions,
+  assertDownOptions,
+  assertDryRunOptions,
+  assertFilename,
+  assertHistoryLimit,
+  assertImportOptions,
+  assertListOptions,
+  assertRedoOptions,
+  assertUpOptions,
+};

package/src/core/run-recorder.js

@@ -0,0 +1,157 @@
+const { LockAlreadyHeldError, MigronautError } = require('../errors/index.js');
+const { errorText } = require('../utils/error.js');
+const { ATTRIBUTES } = require('../utils/telemetry.js');
+
+/**
+ * The record one run under the lock leaves behind: its `run:start` /
+ * `run:end` and lock events, its run metrics, the end of its span, and the
+ * closing "Done" line. Kept apart from MigratorKit#withLock, which is left
+ * with what is its own — reentrancy, the abort wiring, and the lock.
+ *
+ * Built from the kit's own capabilities: `emit` (runId stamped, listeners
+ * contained), `telemetry` (a no-op without one), the resolved `logger` and
+ * `fields`. All of them are guarded, so nothing recorded here can fail a run.
+ * The span itself is opened by the kit — the run span is one of its two wrap
+ * sites — and handed over with {@link RunRecorder#spanOpened}.
+ */
+class RunRecorder {
+  #info;
+  #runId;
+  #telemetry;
+  #emit;
+  #logger;
+  #fields;
+  #startedAt;
+  /** What the lock reported when it was acquired — the run span's lock attributes */
+  #acquired;
+  /** The first reason the lock was lost */
+  #lostReason;
+  /** Set once the lock is held and the run span is open */
+  #span;
+
+  constructor({ info, runId, telemetry, emit, logger, fields }) {
+    this.#info = info;
+    this.#runId = runId;
+    this.#telemetry = telemetry;
+    this.#emit = emit;
+    this.#logger = logger;
+    this.#fields = fields;
+  }
+
+  start() {
+    this.#startedAt = Date.now();
+    this.#emit('run:start', { ...this.#info });
+  }
+
+  lockAcquired(extra) {
+    this.#acquired = extra;
+    if (typeof extra?.acquireMs === 'number') this.#telemetry.lockAcquired(extra.acquireMs);
+    this.#emit('lock:acquired', { owner: this.#runId, ...extra });
+  }
+
+  lockReleased(extra) {
+    this.#emit('lock:released', { owner: this.#runId, ...extra });
+  }
+
+  lockLost(reason) {
+    // The heartbeat and the TTL deadline can each report the same loss: the
+    // first reason is the cause, and it is one lost lock.
+    if (this.#lostReason === undefined) {
+      this.#lostReason = reason;
+      this.#telemetry.lockLost();
+    }
+    this.#emit('lock:lost', { owner: this.#runId, reason });
+  }
+
+  /** The run span's attributes — complete once the lock is held */
+  spanAttributes() {
+    return {
+      [ATTRIBUTES.RUN_ID]: this.#runId,
+      [ATTRIBUTES.RUN_COMMAND]: this.#info.command,
+      [ATTRIBUTES.RUN_DIRECTION]: this.#info.direction,
+      [ATTRIBUTES.LOCK_ACQUIRE_MS]: this.#acquired?.acquireMs,
+      [ATTRIBUTES.LOCK_SKIPPED]: this.#acquired?.skipped,
+    };
+  }
+
+  spanOpened(span) {
+    this.#span = span;
+  }
+
+  /** Close the record: `result` on success, `failure` (what the run threw) otherwise */
+  finish(result, failure) {
+    // Result counts, so a metrics subscriber gets "3 applied in 812ms"
+    // without reconstructing it from per-migration events. On the failure
+    // path the partial rows live on the error's context — exactly the case
+    // where "how far did it get?" is the question, so they count too.
+    const rows = Array.isArray(result)
+      ? result
+      : failure instanceof MigronautError && Array.isArray(failure.context?.results)
+        ? failure.context.results
+        : null;
+    const { summary, skipped } = countRows(rows);
+    const durationMs = Date.now() - this.#startedAt;
+    const telemetry = this.#telemetry;
+    if (this.#span) {
+      this.#span.finish(
+        {
+          [ATTRIBUTES.RUN_APPLIED]: summary.applied,
+          [ATTRIBUTES.RUN_REVERTED]: summary.reverted,
+          [ATTRIBUTES.RUN_SKIPPED]: skipped,
+          [ATTRIBUTES.RUN_TOTAL]: summary.total,
+          [ATTRIBUTES.LOCK_LOST_REASON]: this.#lostReason,
+        },
+        failure,
+      );
+      telemetry.runEnded({ ...this.#info, durationMs, error: failure });
+    } else if (failure instanceof LockAlreadyHeldError) {
+      // Never held the lock, so there is no run to time — only a refusal to
+      // count. Any other failure this early (an unreachable database) is the
+      // caller's to report; it is not contention.
+      telemetry.lockRefused();
+    }
+    this.#emit('run:end', {
+      ...this.#info,
+      success: failure === undefined,
+      durationMs,
+      ...summary,
+      // A raw Error here would hand subscribers an unredacted driver message
+      // (which can echo the credentialed URI) — errorText is the same
+      // chokepoint every log line and result row already goes through.
+      ...(failure ? { error: errorText(failure) } : {}),
+    });
+    // One human rollup after the per-migration lines: total wall-clock time
+    // (lock wait and hooks included) is otherwise unobtainable from the
+    // output — per-file durations exclude all overhead. Success path only;
+    // a failure already ends with its own error line.
+    if (failure === undefined && (summary.applied || summary.reverted)) {
+      const parts = [];
+      if (summary.applied) parts.push(`${summary.applied} applied`);
+      if (summary.reverted) parts.push(`${summary.reverted} reverted`);
+      this.#logger.info(
+        `✔ Done     ${parts.join(', ')} in ${durationMs}ms`,
+        this.#fields({ ...this.#info, ...summary, durationMs }),
+      );
+    }
+  }
+}
+
+/**
+ * `{ summary: { applied, reverted, total }, skipped }` of a run's rows, in one
+ * pass — `summary` is empty when the run produced no rows (a converge, a
+ * failure before the first migration).
+ */
+function countRows(rows) {
+  if (!rows) return { summary: {}, skipped: undefined };
+  let applied = 0;
+  let reverted = 0;
+  let skipped = 0;
+  for (const row of rows) {
+    if (row.status === 'applied') applied += 1;
+    else if (row.status === 'reverted') reverted += 1;
+    else if (row.status === 'skipped') skipped += 1;
+  }
+  return { summary: { applied, reverted, total: rows.length }, skipped };
+}
+
+module.exports = { RunRecorder };

package/src/core/run.js

@@ -1,21 +1,7 @@
-const { setTimeout: delay } = require('node:timers/promises');
-const { ConfigInvalidError, LockAlreadyHeldError } = require('../errors/index.js');
-const { MigratorKit } = require('./migrator.js');
-
-/**
- * Longer than the default 60s lock TTL on purpose: with a shorter budget, a peer
- * migration that outlives it makes every waiting instance fail to boot, even
- * though the peer is healthy and still holding a valid lock.
- */
-const DEFAULT_LOCK_WAIT_TIMEOUT_MS = 90_000;
-const DEFAULT_LOCK_POLL_INTERVAL_MS = 500;
-/** ±25% jitter so N instances booting together stop polling in lockstep */
-const POLL_JITTER_RATIO = 0.25;
-
-function jitteredDelay(baseMs) {
-  const spread = baseMs * POLL_JITTER_RATIO;
-  return Math.max(1, Math.round(baseMs - spread + Math.random() * spread * 2));
-}
+const { ConfigInvalidError, RunAbortedError } = require('../errors/index.js');
+const { errorText } = require('../utils/error.js');
+const { assertLockWaitOptions, withLockWait } = require('./lock-wait.js');
+const { MigratorKit, RECORD_LOCK_WAIT } = require('./migrator.js');
 
 /**
  * Run all pending migrations and return a summary — the blessed one-call entry
@@ -31,7 +17,9 @@ function jitteredDelay(baseMs) {
  *
  * For multi-instance deploys, set `onLockHeld: 'wait'` so instances that lose
  * the race to acquire the lock block until the migrating peer finishes, then
- * confirm there is nothing left to apply.
+ * confirm there is nothing left to apply. Pass a `signal` (wired to SIGTERM)
+ * so a pod being shut down stops waiting — and stops between migrations if it
+ * already holds the lock — instead of taking the lock just before SIGKILL.
  *
  * Running several kits against several databases in ONE process: pass
  * `envFile: false` and supply `uri`/`dbName` directly. `.env` loading mutates
@@ -54,95 +42,75 @@ async function runMigrations(config = {}, options = {}) {
   const {
     noLock,
     onLockHeld = 'throw',
-    lockWaitTimeoutMs = DEFAULT_LOCK_WAIT_TIMEOUT_MS,
-    lockPollIntervalMs = DEFAULT_LOCK_POLL_INTERVAL_MS,
+    // Left undefined unless given: the default then follows the holder's TTL.
+    lockWaitTimeoutMs,
+    lockPollIntervalMs,
     onKit,
+    signal,
     ...kitOptions
   } = options;
 
   if (onKit !== undefined && typeof onKit !== 'function') {
     throw new ConfigInvalidError('onKit must be a function', { onKit: typeof onKit });
   }
-
-  // Validated before anything connects. A NaN here (or any non-positive value)
-  // disables every deadline comparison below — `NaN > deadline` is always
-  // false — turning the wait loop into an unbounded retry storm against the
-  // lock collection that never returns and never surfaces the real error.
-  if (!Number.isFinite(lockWaitTimeoutMs) || lockWaitTimeoutMs <= 0) {
-    throw new ConfigInvalidError('lockWaitTimeoutMs must be a positive finite number', {
-      lockWaitTimeoutMs,
-    });
-  }
-  if (!Number.isFinite(lockPollIntervalMs) || lockPollIntervalMs <= 0) {
-    throw new ConfigInvalidError('lockPollIntervalMs must be a positive finite number', {
-      lockPollIntervalMs,
-    });
+  if (signal !== undefined && !(signal instanceof AbortSignal)) {
+    throw new ConfigInvalidError('signal must be an AbortSignal', { signal: typeof signal });
   }
 
+  // Validated before anything connects — see assertLockWaitOptions.
+  assertLockWaitOptions({ onLockHeld, lockWaitTimeoutMs, lockPollIntervalMs });
+
   const kit = new MigratorKit(config, kitOptions);
   // Handed out before connect so listeners catch every lifecycle event —
   // this is the metrics/alerting injection point for apps that embed
   // runMigrations and cannot reach the internally-constructed kit otherwise.
   onKit?.(kit);
-  let waited = false;
-  let waitedMs = 0;
-  let attempts = 0;
+  // `up` keeps returning the migration rows; with `convergeAfterUp` the
+  // converge outcome rides along in the summary, from the kit's own event.
+  let converge;
+  kit.on('converge:end', (event) => {
+    if (event.trigger === 'up' && event.success) converge = event.result;
+  });
 
+  // An abort reaches the run wherever it is: the wait loop sees the signal
+  // between polls, and kit.stop() stops a run that is setting up or between
+  // migrations (one already executing finishes — as stop() always has).
+  const onAbort = () => kit.stop(errorText(signal.reason ?? 'Aborted'));
+  signal?.addEventListener('abort', onAbort, { once: true });
   try {
-    await kit.connect();
-    // Resolved AFTER connect, from the kit's own merged config: a `logger:
-    // null` in the config file must silence this module's lines too, not only
-    // the kit's own.
-    const logger = kit.logger;
-    // The clock starts at the first contention, not before the first attempt —
-    // otherwise a slow initial attempt eats the whole waiting budget.
-    let deadline;
-    // The holder's lockedAt from the last refusal: its heartbeat advances it
-    // every TTL/2, so a change between polls is proof of a live, progressing
-    // peer.
-    let lastHolderLockedAt;
-
-    for (;;) {
-      try {
-        attempts += 1;
-        const applied = await kit.up(undefined, noLock ? { noLock: true } : {});
-        return { applied, upToDate: applied.length === 0, waited, waitedMs, attempts };
-      } catch (error) {
-        if (onLockHeld !== 'wait' || !(error instanceof LockAlreadyHeldError)) {
-          throw error;
-        }
-        // The timeout bounds *stall* time, not total wait: while the holder's
-        // heartbeat visibly advances, it is healthy and working through its
-        // backlog — timing out then would crash-loop every waiting instance
-        // on exactly the deploys (a large first backlog) that take longest.
-        // Only a holder that stops renewing runs the deadline down.
-        const holderLockedAt = error.context?.holder?.lockedAt?.getTime?.();
-        const holderAdvanced =
-          holderLockedAt !== undefined &&
-          lastHolderLockedAt !== undefined &&
-          holderLockedAt > lastHolderLockedAt;
-        if (deadline === undefined || holderAdvanced) {
-          deadline = Date.now() + lockWaitTimeoutMs;
-        }
-        if (holderLockedAt !== undefined) lastHolderLockedAt = holderLockedAt;
-        const nextDelay = jitteredDelay(lockPollIntervalMs);
-        if (Date.now() + nextDelay > deadline) {
-          throw error;
-        }
-        if (!waited) {
-          logger.info('Migration lock held by another process — waiting for it to release…');
-        }
-        waited = true;
-        logger.debug('Migration lock still held — retrying', {
-          attempts,
-          waitedMs,
-          nextDelayMs: nextDelay,
-        });
-        waitedMs += nextDelay;
-        await delay(nextDelay);
-      }
+    if (signal?.aborted) {
+      throw new RunAbortedError('Aborted before the run started', {
+        reason: errorText(signal.reason ?? 'aborted'),
+        results: [],
+      });
     }
+    await kit.connect();
+    const {
+      result: applied,
+      waited,
+      waitedMs,
+      attempts,
+    } = await withLockWait(() => kit.up(undefined, noLock ? { noLock: true } : {}), {
+      onLockHeld,
+      ...(lockWaitTimeoutMs !== undefined ? { lockWaitTimeoutMs } : {}),
+      ...(lockPollIntervalMs !== undefined ? { lockPollIntervalMs } : {}),
+      // Resolved AFTER connect, from the kit's own merged config: a `logger:
+      // null` in the config file must silence the wait lines too, not only
+      // the kit's own.
+      logger: kit.logger,
+      ...(signal ? { signal } : {}),
+      onSettle: (wait) => kit[RECORD_LOCK_WAIT](wait),
+    });
+    return {
+      applied,
+      upToDate: applied.length === 0,
+      waited,
+      waitedMs,
+      attempts,
+      ...(converge ? { converge } : {}),
+    };
   } finally {
+    signal?.removeEventListener('abort', onAbort);
     await kit.disconnect().catch(() => undefined);
   }
 }