@lenne.tech/nest-server 11.32.3 → 11.33.0

package/src/core/modules/hub/services/hub-log-buffer.service.ts

@@ -7,12 +7,14 @@ import {
   LogLevel,
   OnModuleDestroy,
   OnModuleInit,
+  Optional,
 } from '@nestjs/common';
 import { inspect } from 'util';
 
 import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { CoreRedisService } from '../../../common/services/core-redis.service';
 import { HUB_CONFIG } from '../hub.constants';
-import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubBuffer } from '../hub-buffer';
 import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface';
 import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
 
@@ -90,22 +92,32 @@ class HubDelegatingLogger implements LoggerService {
  */
 @Injectable()
 export class HubLogBufferService implements OnModuleDestroy, OnModuleInit {
-  private buffer?: HubRingBuffer<BufferedLog>;
+  private buffer?: HubBuffer<BufferedLog>;
   private cfg?: Exclude<ResolvedHubConfig['collectors']['logs'], false>;
   private delegating?: HubDelegatingLogger;
   private excludeContexts = new Set<string>();
+
+  /**
+   * Set by onModuleDestroy. The Nest Logger override is PROCESS-GLOBAL, and with a shutdown
+   * delay the HTTP server keeps serving while the app drains — so a Hub poll arriving in that
+   * window could re-install a logger belonging to an app that no longer exists.
+   */
+  private destroyed = false;
   private previousRef?: LoggerService;
 
-  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {}
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    @Optional() protected readonly redis?: CoreRedisService,
+  ) {}
 
   /** Idempotent install of the delegating logger. Public so reads can self-heal after a foreign override. */
   attach(): void {
-    if (this.config.collectors.logs === false) {
+    if (this.destroyed || this.config.collectors.logs === false) {
       return;
     }
     if (!this.cfg) {
       this.cfg = this.config.collectors.logs;
-      this.buffer = new HubRingBuffer<BufferedLog>(this.cfg.capacity);
+      this.buffer = new HubBuffer<BufferedLog>(this.cfg.capacity, 'logs', this.redis);
       this.excludeContexts = new Set(this.cfg.excludeContexts);
     }
     const current = this.staticRef();
@@ -149,13 +161,17 @@ export class HubLogBufferService implements OnModuleDestroy, OnModuleInit {
     return this.config.collectors.logs !== false;
   }
 
-  getData(since?: number): HubLogsData {
+  async getData(since?: number): Promise<HubLogsData> {
     this.selfHeal();
-    const records = !this.buffer ? [] : since === undefined ? this.buffer.recent() : this.buffer.since(since);
-    return { cursor: this.buffer?.lastSeq ?? -1, dropped: this.buffer?.firstRetainedSeq ?? -1, records };
+    if (!this.buffer) {
+      return { cursor: -1, dropped: -1, records: [] };
+    }
+    const { cursor, dropped, entries } = await this.buffer.read(since);
+    return { cursor, dropped, records: entries };
   }
 
   onModuleDestroy(): void {
+    this.destroyed = true;
     this.detach();
   }
 

package/src/core/modules/hub/services/hub-query-profiler.service.ts

@@ -3,8 +3,9 @@ import { InjectConnection } from '@nestjs/mongoose';
 import { Connection } from 'mongoose';
 
 import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { CoreRedisService } from '../../../common/services/core-redis.service';
 import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants';
-import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubBuffer } from '../hub-buffer';
 import { normalizeCommandShape } from '../helpers/hub-command-shape.helper';
 import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface';
 import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
@@ -58,7 +59,7 @@ const SHAPED_FIELDS = ['filter', 'query', 'pipeline', 'sort', 'projection', 'q',
 export class HubQueryProfilerService implements OnModuleDestroy, OnModuleInit {
   protected readonly logger = new Logger(HubQueryProfilerService.name);
 
-  private buffer?: HubRingBuffer<ProfilerRecord>;
+  private buffer?: HubBuffer<ProfilerRecord>;
   private client?: {
     off?: (e: string, l: (...a: any[]) => void) => void;
     on: (e: string, l: (...a: any[]) => void) => void;
@@ -78,6 +79,7 @@ export class HubQueryProfilerService implements OnModuleDestroy, OnModuleInit {
   constructor(
     @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
     @Optional() @InjectConnection() protected readonly connection?: Connection,
+    @Optional() protected readonly redis?: CoreRedisService,
   ) {}
 
   /** Clear the buffer (Hub action). */
@@ -90,10 +92,11 @@ export class HubQueryProfilerService implements OnModuleDestroy, OnModuleInit {
     return this.config.collectors.queries !== false;
   }
 
-  getData(): HubQueriesData {
-    const records = this.buffer?.recent() ?? [];
+  async getData(): Promise<HubQueriesData> {
+    const data = this.buffer ? await this.buffer.read() : { cursor: -1, entries: [] };
+    const records = data.entries;
     return {
-      cursor: this.buffer?.lastSeq ?? -1,
+      cursor: data.cursor,
       recent: records.slice(-100),
       slowest: [...records].sort((a, b) => b.durationMs - a.durationMs).slice(0, 10),
       summary: this.summary(records),
@@ -118,7 +121,7 @@ export class HubQueryProfilerService implements OnModuleDestroy, OnModuleInit {
       return; // zero cost when disabled
     }
     this.cfg = this.config.collectors.queries;
-    this.buffer = new HubRingBuffer<ProfilerRecord>(this.cfg.capacity);
+    this.buffer = new HubBuffer<ProfilerRecord>(this.cfg.capacity, 'queries', this.redis);
     if (this.cfg.ignoreCommands?.length) {
       this.ignore = new Set(this.cfg.ignoreCommands.map((c) => c.toLowerCase()));
     }

package/src/core/modules/hub/services/hub-trace-buffer.service.ts

@@ -1,8 +1,9 @@
-import { Inject, Injectable } from '@nestjs/common';
+import { Inject, Injectable, Optional } from '@nestjs/common';
 import { Request, Response } from 'express';
 
+import { CoreRedisService } from '../../../common/services/core-redis.service';
 import { HUB_CONFIG } from '../hub.constants';
-import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubBuffer } from '../hub-buffer';
 import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface';
 import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
 
@@ -19,14 +20,17 @@ interface TraceRecord extends HubTraceRecord {
  */
 @Injectable()
 export class HubTraceBufferService {
-  private readonly buffer?: HubRingBuffer<TraceRecord>;
+  private readonly buffer?: HubBuffer<TraceRecord>;
   private readonly cfg?: Exclude<ResolvedHubConfig['collectors']['traces'], false>;
   private readonly excludePrefixes: string[];
 
-  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    @Optional() protected readonly redis?: CoreRedisService,
+  ) {
     if (config.collectors.traces !== false) {
       this.cfg = config.collectors.traces;
-      this.buffer = new HubRingBuffer<TraceRecord>(this.cfg.capacity);
+      this.buffer = new HubBuffer<TraceRecord>(this.cfg.capacity, 'traces', redis);
     }
     // Always exclude the Hub's own routes so polling does not flood the trace list with self-noise.
     this.excludePrefixes = [...(this.cfg?.excludePaths ?? []), '/' + config.path];
@@ -40,8 +44,9 @@ export class HubTraceBufferService {
     return this.config.collectors.traces !== false;
   }
 
-  getData(since?: number): HubTracesData {
-    const records = !this.buffer ? [] : since === undefined ? this.buffer.recent() : this.buffer.since(since);
+  async getData(since?: number): Promise<HubTracesData> {
+    const data = this.buffer ? await this.buffer.read(since) : { cursor: -1, dropped: -1, entries: [] };
+    const records = data.entries;
     let totalMs = 0;
     let slowCount = 0;
     let errorCount = 0;
@@ -55,8 +60,8 @@ export class HubTraceBufferService {
       }
     }
     return {
-      cursor: this.buffer?.lastSeq ?? -1,
-      dropped: this.buffer?.firstRetainedSeq ?? -1,
+      cursor: data.cursor,
+      dropped: data.dropped,
       summary: { avgMs: records.length ? totalMs / records.length : 0, errorCount, slowCount, total: records.length },
       traces: records,
     };

package/src/core/modules/migrate/README.md

@@ -230,7 +230,7 @@ The migration state is stored in a MongoDB collection (default: `migrations`) as
 
 ### Locking Mechanism
 
-When using `synchronizedMigration` or `synchronizedUp`:
+How the lock works, regardless of which entry point uses it:
 
 1. A unique index is created on the lock collection
 2. The migration process attempts to insert a lock document
@@ -240,6 +240,27 @@ When using `synchronizedMigration` or `synchronizedUp`:
 
 This ensures that in a cluster with multiple nodes, migrations run on only one machine at a time.
 
+**Active by default for `migrate up`.** Stores built by `createMigrationStore()` use the
+lock collection `migrations_lock` unless another name is given, and `MigrationRunner.up()`
+(the CLI's `up` command) acquires that lock around the whole run. This matters because the
+container entrypoint runs migrations on **every** boot: without the lock, N replicas
+starting together each read the same empty state and apply the same pending migration N
+times. A replica that waited re-reads the state inside the lock and finds nothing pending.
+
+With a single replica nothing changes — the lock is acquired and released uncontended.
+
+Opt out by passing an empty lock collection name:
+
+```javascript
+module.exports = createMigrationStore(uri, 'migrations', ''); // no locking
+```
+
+A `MongoStateStore` constructed **directly** still locks only when you pass
+`lockCollectionName` yourself; the default lives in `createMigrationStore()`.
+
+The legacy `synchronizedMigration` / `synchronizedUp` helpers use the same lock and still
+require `lockCollectionName` to be set explicitly (they throw otherwise).
+
 ## Examples
 
 ### Example: Migration File
@@ -356,11 +377,17 @@ Factory function to create a migration store class for use with the migrate CLI:
 const { createMigrationStore } = require('@lenne.tech/nest-server');
 const config = require('../src/config.env');
 
-module.exports = createMigrationStore(
-  config.default.mongoose.uri,
-  'migrations', // optional collection name
-  'migration_lock', // optional lock collection for clusters
-);
+module.exports = createMigrationStore(config.default.mongoose.uri);
+```
+
+**Locking is on by default.** The third parameter defaults to `'migrations_lock'`, so
+`migrate up` is serialized across replicas without any project change (see
+[Locking Mechanism](#locking-mechanism)):
+
+```javascript
+createMigrationStore(uri); // collection 'migrations', lock 'migrations_lock'
+createMigrationStore(uri, 'migrations', 'custom_lock'); // custom lock collection
+createMigrationStore(uri, 'migrations', ''); // opt out: no locking
 ```
 
 ### getDb()
@@ -387,6 +414,41 @@ const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', '../assets/i
 });
 ```
 
+`relativePath` is resolved against the **helper module's** directory, not the migration file's — the
+paths in this example and in the migration template are written accordingly.
+
+The returned promise settles only after three guarantees hold:
+
+| Guarantee                       | Behaviour                                                                                                                                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The bytes are stored            | Chunk completeness is verified before resolving (see `assertGridFsFileComplete()` below). An incomplete upload **rejects** and the incomplete file is removed, rather than returning an id that points at nothing |
+| An unreadable source fails fast | A missing or unreadable file **rejects** with the underlying `ENOENT`. It used to hang forever, because `pipe()` does not forward read-stream errors                                                              |
+| The connection is released      | The MongoClient it opens is always closed, on the success and the failure path alike. A leaked connection keeps the Node event loop alive and `migrate up` never exits                                            |
+
+Since these are hard failures, a seed migration whose asset is missing or only partially stored now
+fails the migration — and with the default `MIGRATE_FAILURE_POLICY=abort` in `docker-entrypoint.sh`,
+the container refuses to start rather than booting with broken data. That is intentional: the point
+of running migrations before the server is to find exactly this.
+
+### assertGridFsFileComplete()
+
+Verifies that every chunk of an already-stored GridFS file is present. `uploadFileToGridFS()` calls
+it for you; call it directly to check files written by something else (a restored dump, another
+service, a manual upload):
+
+```typescript
+import { assertGridFsFileComplete, getDb } from '@lenne.tech/nest-server';
+
+const db = await getDb('mongodb://localhost/mydb');
+await assertGridFsFileComplete(db, 'images', fileId, 'logo.png'); // throws if incomplete
+```
+
+Throws when the files document is missing entirely, or when fewer chunks are stored than its
+`length` implies. It counts chunk documents rather than reading bytes back, so a chunk that was
+written but truncated is **not** detected — the check targets the failure that actually occurs, a
+connection lost mid-upload. Empty files are valid and pass: GridFS stores a zero-byte file with no
+chunk documents at all.
+
 ### Migration Templates
 
 Ready-to-use template for nest-server projects:

package/src/core/modules/migrate/cli/migrate-cli.ts

@@ -328,13 +328,76 @@ Environment Variables:
 `);
 }
 
-// Run CLI if executed directly
-if (require.main === module) {
-  main().catch((error) => {
+/**
+ * Exit with `code`, but never before our own output has actually left the process.
+ *
+ * `process.exit()` does NOT drain stdout, and stdout is asynchronous whenever it
+ * is a pipe — which is exactly the Docker / CI / `| tee` case. Exiting straight
+ * after the completion log therefore discards the record of what this run did,
+ * and the line at risk is the last one ("All migrations completed successfully"),
+ * which is precisely what a CI step greps for. Measured: past the 64 KiB pipe
+ * buffer everything beyond it is lost.
+ *
+ * `process.exitCode` is assigned first so that a future `exitCode = 1` elsewhere
+ * is honoured rather than overwritten by a hardcoded 0. The timer is the safety
+ * net for the opposite failure — a consumer that never reads — and is `unref`'d
+ * so it cannot itself keep the process alive.
+ */
+const flushAndExit = async (code: number): Promise<void> => {
+  process.exitCode = code;
+
+  const guard = setTimeout(() => process.exit(code), 5000);
+  guard.unref();
+
+  await Promise.all(
+    [process.stdout, process.stderr].map(
+      (stream) =>
+        new Promise<void>((resolve) => {
+          if (!stream.writableLength) {
+            resolve();
+            return;
+          }
+          stream.write('', () => resolve());
+        }),
+    ),
+  );
+
+  clearTimeout(guard);
+  process.exit(code);
+};
+
+/**
+ * Run the CLI and terminate the process when it is done.
+ *
+ * This is the entry point the `migrate` / `nest-migrate` bin uses. It exists
+ * separately from `main()` because the shell around it matters: migrations touch
+ * MongoDB, GridFS and — via the state store — a second connection, and any handle
+ * one of them leaves behind keeps Node alive forever. The CLI then prints
+ * "All migrations completed successfully" and simply never returns: a CI job
+ * blocks until its timeout, and a container entrypoint that runs migrations
+ * before `exec`ing the server never reaches the server at all.
+ *
+ * Note this must NOT be guarded by `require.main === module`: the shipped
+ * `bin/migrate.js` loads this module and calls in, so `require.main` is the shim,
+ * never this file. A guard here would make the exit unreachable on every path
+ * that actually ships.
+ */
+const runCli = async (): Promise<void> => {
+  try {
+    await main();
+  } catch (error) {
     console.error('Fatal error:', error);
-    process.exit(1);
-  });
+    await flushAndExit(1);
+    return;
+  }
+  await flushAndExit(0);
+};
+
+// Run CLI if executed directly (`node migrate-cli.js`). The bin shim calls
+// runCli() itself, so this only covers a direct invocation of the compiled file.
+if (require.main === module) {
+  void runCli();
 }
 
 // parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
-export { main, parseArgs };
+export { flushAndExit, main, parseArgs, runCli };

package/src/core/modules/migrate/helpers/migration.helper.ts

@@ -2,6 +2,8 @@ import * as fs from 'fs';
 import { Db, GridFSBucket, MongoClient, ObjectId } from 'mongodb';
 import * as path from 'path';
 
+import { MongoStateStore } from '../mongo-state-store';
+
 /**
  * Migration helper functions for database operations
  */
@@ -67,13 +69,76 @@ export const getDb = async (mongoUrl: string): Promise<Db> => {
   return client.db();
 };
 
+/**
+ * Throw unless every chunk of a stored GridFS file is present.
+ *
+ * A GridFS upload is not one write but many: N chunk documents plus the files
+ * document that describes them. The write stream's `'finish'` event says the
+ * stream ended — it does not prove every chunk is durably there, and a
+ * connection that goes away at the wrong moment can leave a files document
+ * behind that promises more bytes than exist. The upload then "succeeds", the
+ * caller stores the id, and the defect only surfaces much later as a broken
+ * download from a record that looks perfectly healthy.
+ *
+ * Counts documents rather than reading bytes, so a chunk that was written but
+ * truncated still passes. Catching that would mean streaming the whole file
+ * back on every upload; the cheap count catches the failure that actually
+ * occurs (a missing chunk) and is index-only via the GridFS default index.
+ *
+ * @param db - Database holding the bucket
+ * @param bucketName - GridFS bucket name, i.e. the prefix of `<bucket>.files` / `<bucket>.chunks`
+ * @param id - `_id` of the files document
+ * @param label - Optional human-readable name for the error message; defaults to the id
+ * @throws Error if the files document is missing or fewer chunks are stored than its length implies
+ *
+ * @example
+ * ```typescript
+ * await assertGridFsFileComplete(db, 'images', fileId, 'logo.png');
+ * ```
+ */
+export const assertGridFsFileComplete = async (
+  db: Db,
+  bucketName: string,
+  id: ObjectId,
+  label?: string,
+): Promise<void> => {
+  const name = label || String(id);
+  const fileDoc = await db.collection(`${bucketName}.files`).findOne({ _id: id });
+  if (!fileDoc) {
+    throw new Error(`GridFS file '${name}' has no file document (id ${String(id)})`);
+  }
+
+  const chunkSize: number = fileDoc.chunkSize || 255 * 1024;
+  // NO `Math.max(1, …)` floor here: GridFS stores ZERO chunk documents for a
+  // zero-byte file — the driver's `writeRemnant()` returns early on `pos === 0`
+  // rather than inserting an empty chunk. A floor of 1 would reject every
+  // legitimately empty asset, and because the container entrypoint defaults to
+  // `MIGRATE_FAILURE_POLICY=abort`, that failure would keep the server from
+  // starting at all.
+  const expected = Math.ceil((fileDoc.length || 0) / chunkSize);
+  const actual = await db
+    .collection(`${bucketName}.chunks`)
+    // Read from the primary: this is a read-your-own-write, and a URI carrying
+    // `readPreference=secondaryPreferred` would otherwise fail a healthy upload
+    // against a secondary that has not caught up yet.
+    .countDocuments({ files_id: id }, { readPreference: 'primary' });
+  if (actual < expected) {
+    throw new Error(`GridFS file '${name}' is incomplete: ${actual} of ${expected} chunks stored (id ${String(id)})`);
+  }
+};
+
 /**
  * Upload file to GridFS
  *
+ * Resolves only once the upload is verified complete (see
+ * {@link assertGridFsFileComplete}); rejects — rather than hanging — when the
+ * source file cannot be read. Closes its own connection either way.
+ *
  * @param mongoUrl - MongoDB connection URI
- * @param relativePath - Relative path to the file
+ * @param relativePath - Path to the file, resolved against this module's directory
  * @param options - Optional bucket name and filename
  * @returns Promise with ObjectId of uploaded file
+ * @throws Error if the source cannot be read, or if the stored file is incomplete
  *
  * @example
  * ```typescript
@@ -100,19 +165,83 @@ export const uploadFileToGridFS = async (
   };
 
   const client = await MongoClient.connect(mongoUrl);
+  // Registered unconditionally — unlike `getDb()`, which only registers inside a
+  // migration context. This client is always ours to close, so `_endMigration()`
+  // stays a backstop for the case where the upload throws before `settle()` runs.
+  activeConnections.add(client);
+
   const db = client.db();
   const bucket = new GridFSBucket(db, { bucketName });
   const writeStream = bucket.openUploadStream(filename);
 
-  const rs = fs.createReadStream(path.resolve(__dirname, relativePath)).pipe(writeStream);
+  const readStream = fs.createReadStream(path.resolve(__dirname, relativePath));
+  const rs = readStream.pipe(writeStream);
+
+  /**
+   * Read errors need their own handler — `pipe()` does not forward them.
+   *
+   * An unreadable source (missing file, wrong path inside a container image)
+   * emits on the READ stream, where nothing was listening: the write stream
+   * never finished, the promise below never settled, and the migration hung
+   * until something else timed out. Destroying the write stream routes it into
+   * the rejection path so the caller sees the actual cause.
+   */
+  readStream.on('error', (err) => {
+    writeStream.destroy(err);
+  });
+
+  /**
+   * Close the connection before settling.
+   *
+   * This client used to be opened and never closed, and it was not registered
+   * either — so `_endMigration()` could not reach it. Every uploaded file left a
+   * live connection behind, and a live connection keeps an SDAM monitor timer
+   * alive, which keeps the Node event loop busy: `migrate up` finished its work,
+   * printed "All migrations completed successfully" and then never exited. That
+   * is invisible on a developer machine and blocks a CI job until its timeout.
+   *
+   * A failing `close()` must never become the error the caller sees: the reason
+   * the upload ended is what matters, and the settle path is also reached while
+   * rejecting. So the close error is logged and swallowed, and `settled` keeps a
+   * second call (success path falling into `.catch`) from closing twice.
+   */
+  let settled = false;
+  const settle = async <T>(action: () => T): Promise<T> => {
+    if (!settled) {
+      settled = true;
+      try {
+        await client.close();
+      } catch (closeErr) {
+        console.warn('Failed to close migration connection:', closeErr);
+      } finally {
+        activeConnections.delete(client);
+      }
+    }
+    return action();
+  };
 
   return new Promise<ObjectId>((resolve, reject) => {
     rs.on('finish', () => {
-      resolve(writeStream.id as ObjectId);
+      const id = writeStream.id as ObjectId;
+      // Verify BEFORE closing: the check needs the same open client, and a
+      // failure has to reject rather than hand back an id that points at nothing.
+      assertGridFsFileComplete(db, bucketName, id, filename)
+        .then(() => settle(() => id))
+        .then(resolve)
+        .catch((err: unknown) => {
+          // Drop the incomplete file, otherwise every re-run of the migration
+          // leaves another orphaned files document (plus its partial chunks)
+          // behind, since a retry uploads under a fresh ObjectId.
+          bucket
+            .delete(id)
+            .catch(() => undefined)
+            .then(() => settle(() => undefined))
+            .finally(() => reject(err));
+        });
     });
 
     rs.on('error', (err) => {
-      reject(err);
+      settle(() => undefined).finally(() => reject(err));
     });
   });
 };
@@ -120,9 +249,13 @@ export const uploadFileToGridFS = async (
 /**
  * Create a migration state store factory
  *
+ * The lock collection is set by DEFAULT, so `migrate up` from N replicas booting at
+ * the same time serializes instead of applying the same migration twice (the container
+ * entrypoint runs migrations on every boot). Pass an empty string to opt out.
+ *
  * @param mongoUrl - MongoDB connection URI
  * @param collectionName - Optional collection name (default: 'migrations')
- * @param lockCollectionName - Optional lock collection name for cluster environments
+ * @param lockCollectionName - Lock collection name (default: 'migrations_lock'); `''` disables locking
  * @returns MongoStateStore class that can be used with migrate CLI
  *
  * @example
@@ -137,15 +270,16 @@ export const uploadFileToGridFS = async (
 export const createMigrationStore = (
   mongoUrl: string,
   collectionName: string = 'migrations',
-  lockCollectionName?: string,
-) => {
-  const { MongoStateStore } = require('../mongo-state-store');
-
+  lockCollectionName: string = 'migrations_lock',
+  // Explicit return type: the returned class is anonymous to the declaration emitter, and
+  // MongoStateStore has private members, so an inferred type cannot be written to the .d.ts
+  // (TS4094).
+): new () => MongoStateStore => {
   return class MigrationStateStore extends MongoStateStore {
     constructor() {
       super({
         collectionName,
-        lockCollectionName,
+        lockCollectionName: lockCollectionName || undefined,
         uri: mongoUrl,
       });
     }

package/src/core/modules/migrate/migration-runner.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MongoStateStore } from './mongo-state-store';
+import { MongoStateStore, withMigrationLock } from './mongo-state-store';
 
 /**
  * Migration file interface
@@ -221,8 +221,17 @@ export class MigrationRunner {
 
   /**
    * Run all pending migrations (up)
+   *
+   * Serialized via the state store's lock collection when it has one (the default for
+   * stores built by `createMigrationStore()`). Reading the state INSIDE the lock is what
+   * makes it safe: a replica that waited sees the migrations the holder just applied and
+   * finds nothing pending, instead of applying them a second time.
    */
   async up(): Promise<void> {
+    await withMigrationLock(this.options.stateStore, () => this.runUp());
+  }
+
+  protected async runUp(): Promise<void> {
     const { _endMigration, _startMigration } = await import('./helpers/migration.helper');
 
     const allMigrations = await this.loadMigrationFiles();