@alexify/migronaut 1.0.0 → 2.0.0

package/src/core/runner.js

@@ -27,9 +27,9 @@ function isTransactionsUnsupported(error) {
  * timeout buys is the *run* stopping instead of hanging forever — which also
  * lets the lock's TTL expire, so a wedged migration no longer blocks every
  * other instance indefinitely. Migrations that need real cancellation should
- * watch `ctx.signal`.
+ * watch `ctx.signal`, which `onTimeout` aborts when the timer fires.
  */
-async function withTimeout(promise, timeoutMs, name, direction) {
+async function withTimeout(promise, timeoutMs, name, direction, onTimeout) {
   if (!timeoutMs) return promise;
   let timer;
   try {
@@ -43,16 +43,19 @@ async function withTimeout(promise, timeoutMs, name, direction) {
           // unhandledRejection long after the run already reported the
           // timeout. Swallow it: the timeout is the reported failure.
           Promise.resolve(promise).catch(() => {});
-          reject(
-            new MigrationTimeoutError(
-              `Migration ${direction} timed out after ${timeoutMs}ms: ${name}`,
-              {
-                name,
-                direction,
-                timeoutMs,
-              },
-            ),
+          const timeoutError = new MigrationTimeoutError(
+            `Migration ${direction} timed out after ${timeoutMs}ms: ${name}`,
+            {
+              name,
+              direction,
+              timeoutMs,
+            },
           );
+          // Told, not just abandoned: the caller aborts the context's signal
+          // with this error, so a body that watches ctx.signal can stop
+          // writing instead of racing whoever acquires the lock next.
+          onTimeout?.(timeoutError);
+          reject(timeoutError);
         }, timeoutMs);
         timer.unref?.();
       }),
@@ -77,7 +80,10 @@ async function withTimeout(promise, timeoutMs, name, direction) {
  *
  * On any error the `onError` hook is invoked before a
  * MigrationExecutionFailedError is thrown — the error is never swallowed, and a
- * throwing hook cannot mask the original failure.
+ * throwing hook cannot mask the original failure. The one exception: when the
+ * body succeeded and only the (non-transactional) changelog write failed, the
+ * error carries `context.phase = 'changelog-write'` and `onError` is not fired —
+ * the migration itself did not fail.
  */
 async function runMigration(params) {
   const { name, migration, direction, context, useTransaction, hooks, onSuccess, logger } = params;
@@ -87,30 +93,71 @@ async function runMigration(params) {
 
   const start = Date.now();
   let session;
-  let runtimeContext = context;
+  // JavaScript cannot cancel a running body, but it can tell it to stop: this
+  // controller feeds the context's signal, so the documented "watch ctx.signal"
+  // advice covers the migration's own timeout too — not only lock loss and
+  // stop(). Without it a timed-out body keeps writing after the lock is
+  // released, racing whoever acquires it next.
+  const timedOut = new AbortController();
+  const signal = context.signal
+    ? AbortSignal.any([context.signal, timedOut.signal])
+    : timedOut.signal;
+  let runtimeContext = { ...context, signal };
+  const onTimeout = (timeoutError) => timedOut.abort(timeoutError);
   let duration = 0;
+  // 'body' while the migration's own code runs; 'changelog' once it committed
+  // and only the record write remains. The two failures need different
+  // reporting: a changelog failure after a committed body must not read as
+  // "the migration failed" — that invites a re-run of already-applied writes.
+  let phase = 'body';
 
   try {
     if (useTransaction) {
       session = context.client.startSession();
-      runtimeContext = { ...context, session };
+      runtimeContext = { ...runtimeContext, session };
       // withTransaction may run the body more than once when the driver retries
-      // a transient failure, so duration is re-measured on each attempt.
+      // a transient failure, so duration is re-measured on each attempt. The
+      // changelog write stays inside the transaction, so a failure there
+      // aborts the body's writes too — 'body' phase is accurate throughout.
       await session.withTransaction(async () => {
         const attemptStart = Date.now();
-        await withTimeout(fn(runtimeContext), timeoutMs, name, direction);
+        await withTimeout(fn(runtimeContext), timeoutMs, name, direction, onTimeout);
         duration = Date.now() - attemptStart;
         await onSuccess?.(duration, session);
       });
     } else {
-      await withTimeout(fn(runtimeContext), timeoutMs, name, direction);
+      await withTimeout(fn(runtimeContext), timeoutMs, name, direction, onTimeout);
       duration = Date.now() - start;
+      phase = 'changelog';
       await onSuccess?.(duration, undefined);
     }
 
     return { duration };
   } catch (error) {
     const err = error instanceof Error ? error : new Error(String(error));
+    // Failures deserve timing data as much as successes — a slow-then-failing
+    // migration is exactly what an operator alerts on.
+    const elapsed = Date.now() - start;
+
+    // Without a transaction the body's writes are already committed when the
+    // changelog write fails — say exactly that, instead of the generic
+    // "migration failed" that would invite re-running committed writes. The
+    // onError hook is for migration failures, so it does not fire here.
+    if (phase === 'changelog') {
+      throw new MigrationExecutionFailedError(
+        `Migration ${direction} succeeded but recording it in the changelog failed: ${name} — ` +
+          'its own writes are committed; verify the changelog before re-running',
+        {
+          name,
+          direction,
+          phase: 'changelog-write',
+          bodySucceeded: true,
+          durationMs: elapsed,
+          cause: err.message,
+        },
+        { cause: err },
+      );
+    }
 
     if (hooks?.onError) {
       // A throwing onError hook must not replace the real cause.
@@ -122,14 +169,17 @@ async function runMigration(params) {
       }
     }
 
-    if (err instanceof MigrationTimeoutError) throw err;
+    if (err instanceof MigrationTimeoutError) {
+      err.context = { durationMs: elapsed, ...err.context };
+      throw err;
+    }
     // A standalone deployment refusing the transaction is a topology problem,
     // not a bug in the migration — say so instead of blaming the file.
     if (useTransaction && isTransactionsUnsupported(err)) {
       throw new TransactionsUnsupportedError(
         `Cannot run ${name} in a transaction — this deployment is standalone. ` +
           'Set useTransaction: false, or run against a replica set / mongos.',
-        { name, direction, cause: err.message },
+        { name, direction, durationMs: elapsed, cause: err.message },
         { cause: err },
       );
     }
@@ -137,7 +187,7 @@ async function runMigration(params) {
       `Migration ${direction} failed: ${name}`,
       // The message is duplicated into context because that is what survives
       // JSON serialization; `cause` keeps the real Error (and its stack).
-      { name, direction, cause: err.message },
+      { name, direction, durationMs: elapsed, cause: err.message },
       { cause: err },
     );
   } finally {

package/src/errors/index.js

@@ -183,7 +183,7 @@ class ImportTargetNotEmptyError extends MigronautError {
   }
 }
 
-/** Thrown when attempting to roll back a migrate-mongo-imported (forward-only) migration */
+/** Thrown when attempting to roll back a forward-only (imported or baselined) migration */
 class IrreversibleMigrationError extends MigronautError {
   constructor(message, context, options) {
     super('MIGRATION_IRREVERSIBLE', message, context, options);
@@ -191,6 +191,19 @@ class IrreversibleMigrationError extends MigronautError {
   }
 }
 
+/**
+ * Thrown by a bulk `up` under `onOutOfOrder: 'error'` when a pending migration
+ * sorts before the newest applied one — a file merged late from a parallel
+ * branch, which would otherwise run after migrations authored later and leave
+ * environments with different effective apply orders.
+ */
+class OutOfOrderMigrationError extends MigronautError {
+  constructor(message, context, options) {
+    super('MIGRATION_OUT_OF_ORDER', message, context, options);
+    this.name = 'OutOfOrderMigrationError';
+  }
+}
+
 module.exports = {
   MigronautError,
   LockAlreadyHeldError,
@@ -212,4 +225,5 @@ module.exports = {
   NotAppliedError,
   ImportTargetNotEmptyError,
   IrreversibleMigrationError,
+  OutOfOrderMigrationError,
 };

package/src/index.js

@@ -1,6 +1,7 @@
 const { EXIT_CODES } = require('./cli/exit-codes.js');
 const { MigratorKit } = require('./core/migrator.js');
 const { pendingMigrations, runMigrations } = require('./core/run.js');
+const { createLogger } = require('./utils/logger.js');
 const {
   ChecksumMismatchError,
   ConfigFileExistsError,
@@ -21,6 +22,7 @@ const {
   TransactionsUnsupportedError,
   MigronautError,
   NotAppliedError,
+  OutOfOrderMigrationError,
   RunAbortedError,
 } = require('./errors/index.js');
 
@@ -32,6 +34,11 @@ module.exports = {
   pendingMigrations,
   runMigrations,
 
+  // The default console logger, for programmatic callers who want migronaut's
+  // own output at a chosen level (e.g. createLogger(process.stdout, 'debug'))
+  // without hand-writing a four-method logger
+  createLogger,
+
   // The CLI's exit-code map, for wrappers that mirror its semantics
   EXIT_CODES,
 
@@ -55,5 +62,6 @@ module.exports = {
   TransactionsUnsupportedError,
   MigronautError,
   NotAppliedError,
+  OutOfOrderMigrationError,
   RunAbortedError,
 };

package/src/utils/logger.js

@@ -52,6 +52,13 @@ function createLogger(stream = process.stdout, level = 'info') {
 
 const hasMethod = (value, name) => typeof value?.[name] === 'function';
 
+/** A sink is usable when it exposes any of the four level methods */
+const isUsableSink = (value) =>
+  hasMethod(value, 'info') ||
+  hasMethod(value, 'debug') ||
+  hasMethod(value, 'warn') ||
+  hasMethod(value, 'error');
+
 /**
  * Wrap a sink method so a throwing user logger can never break a migration run.
  * `pinoStyle` swaps the argument order to `(fields, msg)`, which is what pino
@@ -75,10 +82,12 @@ const adapters = new WeakMap();
  * Resolve the effective logger from a config value: `null` → silent,
  * `undefined` → default console logger, otherwise the user's logger adapted
  * to the four-method surface. A pino-style `child` is bound once with a
- * `component` field; a missing `debug`/`warn`/`error` falls back to `info`
- * (or `debug` when only that exists), and every call is guarded so a
- * throwing logger can never abort a half-applied run. A structurally unfit
- * value (no `info`/`debug` function) silences output instead of crashing.
+ * `component` field; a missing method falls back to the nearest present one
+ * of similar severity (a warn/error-only logger keeps its warn/error output —
+ * its missing debug/info become no-ops, never a reason to silence failures),
+ * and every call is guarded so a throwing logger can never abort a
+ * half-applied run. A structurally unfit value (no level method at all)
+ * silences output instead of crashing.
  *
  * A logger exposing `child()` is treated as pino-style, so structured fields
  * are passed as the first argument rather than the second.
@@ -86,21 +95,30 @@ const adapters = new WeakMap();
 function resolveLogger(logger) {
   if (logger === null) return silentLogger;
   if (logger === undefined) return createLogger();
-  if (typeof logger !== 'object' || (!hasMethod(logger, 'info') && !hasMethod(logger, 'debug'))) {
+  if (typeof logger !== 'object' || !isUsableSink(logger)) {
     return silentLogger;
   }
   const cached = adapters.get(logger);
   if (cached !== undefined) return cached;
   const pinoStyle = hasMethod(logger, 'child');
   const child = pinoStyle ? logger.child({ component: 'migronaut' }) : null;
-  const sink = child && (hasMethod(child, 'info') || hasMethod(child, 'debug')) ? child : logger;
-  const base = hasMethod(sink, 'info') ? sink.info.bind(sink) : sink.debug.bind(sink);
-  const pick = (name) => (hasMethod(sink, name) ? sink[name].bind(sink) : base);
+  const sink = child && isUsableSink(child) ? child : logger;
+  const noop = () => {};
+  // Fallback preference per level: same severity first, then the neighbors a
+  // reader of that sink would expect. debug/info never escalate to warn/error
+  // (running commentary must not masquerade as problems); warn/error always
+  // find SOME sink so failures stay visible.
+  const pick = (order) => {
+    for (const name of order) {
+      if (hasMethod(sink, name)) return sink[name].bind(sink);
+    }
+    return noop;
+  };
   const adapter = {
-    debug: guard(pick('debug'), pinoStyle),
-    info: guard(pick('info'), pinoStyle),
-    warn: guard(pick('warn'), pinoStyle),
-    error: guard(pick('error'), pinoStyle),
+    debug: guard(pick(['debug', 'info']), pinoStyle),
+    info: guard(pick(['info', 'debug']), pinoStyle),
+    warn: guard(pick(['warn', 'info', 'debug', 'error']), pinoStyle),
+    error: guard(pick(['error', 'warn', 'info', 'debug']), pinoStyle),
   };
   adapters.set(logger, adapter);
   return adapter;

package/src/utils/redact.js

@@ -8,12 +8,45 @@
  * and the URI may sit anywhere inside a larger message (unlike
  * `maskUriCredentials` in template.js, which is anchored to a whole-string URI).
  */
-const URI_CREDENTIALS = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^:@/\s]+):([^@/\s]+)@/g;
+const URI_CREDENTIALS = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^:@/\s]*):([^@/\s]+)@/g;
 
-/** Mask `scheme://user:secret@` as `scheme://user:****@` anywhere in `text` */
+/**
+ * Query parameters whose value is a secret. The userinfo form is not the only
+ * place a MongoDB URI carries credentials: TLS key passphrases and proxy
+ * passwords travel as plain query parameters and would otherwise survive
+ * redaction into logs, error context and `--json` output.
+ */
+const URI_QUERY_SECRETS =
+  /([?&](?:tlsCertificateKeyFilePassword|proxyPassword|sslKeyPassword)=)[^&\s]+/gi;
+
+/**
+ * `authMechanismProperties` is a comma-separated `KEY:VALUE` list; only the
+ * values of secret-bearing keys (AWS_SESSION_TOKEN et al.) are masked, so
+ * non-secret properties (SERVICE_NAME, …) stay readable.
+ */
+const AUTH_MECHANISM_PROPS = /([?&]authMechanismProperties=)([^&\s]+)/gi;
+const SENSITIVE_PROP_KEY = /TOKEN|SECRET|PASSWORD/i;
+
+/**
+ * Mask credentials anywhere in `text`: `scheme://user:secret@` (an empty
+ * username still hides the password), secret-bearing query parameters, and
+ * secret values inside `authMechanismProperties`.
+ */
 function redactUris(text) {
   if (typeof text !== 'string') return text;
-  return text.replace(URI_CREDENTIALS, '$1$2:****@');
+  return text
+    .replace(URI_CREDENTIALS, '$1$2:****@')
+    .replace(URI_QUERY_SECRETS, '$1****')
+    .replace(AUTH_MECHANISM_PROPS, (_match, prefix, value) => {
+      const pairs = value.split(',');
+      for (let i = 0; i < pairs.length; i++) {
+        const colon = pairs[i].indexOf(':');
+        if (colon === -1) continue;
+        const key = pairs[i].slice(0, colon);
+        if (SENSITIVE_PROP_KEY.test(key)) pairs[i] = `${key}:****`;
+      }
+      return `${prefix}${pairs.join(',')}`;
+    });
 }
 
 /**

package/src/utils/sanitize.js

@@ -8,9 +8,14 @@
  * clear the screen, or restyle everything printed after them.
  */
 
-/** Control characters stripped from untrusted values (tab and newline survive) */
+/**
+ * Control characters stripped from untrusted values (tab and newline survive).
+ * The full C1 block (U+0080-U+009F) is included: CSI, OSC, DCS, PM and APC are
+ * single-codepoint escape introducers on terminals that decode C1, and none of
+ * them is ever legitimate text.
+ */
 // oxlint-disable-next-line no-control-regex -- stripping control characters is the point
-const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
+const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u0080-\u009f]/g;
 
 /**
  * SGR color sequences (`ESC[…m`) to preserve, or a control character to drop.
@@ -19,7 +24,7 @@ const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
  * titles — has no legitimate reason to be in a log line.
  */
 // oxlint-disable-next-line no-control-regex -- stripping control characters is the point
-const SGR_OR_CONTROL = /(\u001b\[[0-9;]*m)|[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
+const SGR_OR_CONTROL = /(\u001b\[[0-9;]*m)|[\u0000-\u0008\u000b-\u001f\u007f\u0080-\u009f]/g;
 
 /**
  * Strip every terminal control character from an untrusted value. For data

package/src/utils/template.js

@@ -8,6 +8,7 @@ const {
 } = require('../errors/index.js');
 const { formatStamp } = require('./date.js');
 const { errorText } = require('./error.js');
+const { redactUris } = require('./redact.js');
 
 /**
  * Convert an arbitrary migration name into a kebab-case slug. Unicode-aware —
@@ -255,21 +256,34 @@ const exportStatement = (esm, expression) =>
  * Mask the password in a connection URI (`user:secret@` → `user:****@`) so a
  * generated config file never carries plaintext credentials. Regex-based, not
  * `new URL()` — multi-host mongodb URIs (`mongodb://h1:27017,h2:27017/db`) fail
- * WHATWG URL parsing. `hasCredentials` is true whenever a userinfo part exists;
- * `masked` only when a non-empty password was actually replaced.
+ * WHATWG URL parsing. `hasCredentials` is true whenever a userinfo part exists
+ * or a query-string secret was masked; `masked` only when a secret was
+ * actually replaced.
  */
 function maskUriCredentials(uri) {
   const match = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^@/]+)@(.*)$/.exec(uri);
-  if (!match) {
-    return { uri, hasCredentials: false, masked: false };
+  let out = uri;
+  let hasCredentials = false;
+  let masked = false;
+  if (match) {
+    const [, scheme, userinfo, rest] = match;
+    hasCredentials = true;
+    const colon = userinfo.indexOf(':');
+    if (colon !== -1 && colon !== userinfo.length - 1) {
+      const username = userinfo.slice(0, colon);
+      out = `${scheme}${username}:****@${rest}`;
+      masked = true;
+    }
   }
-  const [, scheme, userinfo, rest] = match;
-  const colon = userinfo.indexOf(':');
-  if (colon === -1 || colon === userinfo.length - 1) {
-    return { uri, hasCredentials: true, masked: false };
+  // Secrets can also travel as query parameters (TLS key passphrases, proxy
+  // passwords, session tokens) — redactUris masks exactly those, and an
+  // already-masked `user:****@` round-trips unchanged, so comparing the
+  // result tells whether a query secret was found.
+  const queryMasked = redactUris(out);
+  if (queryMasked !== out) {
+    return { uri: queryMasked, hasCredentials: true, masked: true };
   }
-  const username = userinfo.slice(0, colon);
-  return { uri: `${scheme}${username}:****@${rest}`, hasCredentials: true, masked: true };
+  return { uri: out, hasCredentials, masked };
 }
 
 /** Merge caller-supplied config values over the built-in defaults */