@powersync/service-module-mongodb 0.0.0-dev-20260602073133 → 0.0.0-dev-20260803144812

package/src/replication/MongoRelation.ts

@@ -13,9 +13,10 @@ import {
   TimeValuePrecision
 } from '@powersync/service-sync-rules';
 
-import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { ErrorCode, logger, ServiceAssertionError, ServiceError } from '@powersync/lib-services-framework';
+import { ObjectId } from 'bson';
 import { MongoLSN } from '../common/MongoLSN.js';
-import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+import { SentinelLSN } from '../common/SentinelLSN.js';
 
 export function getMongoRelation(
   source: mongo.ChangeStreamNameSpace,
@@ -174,32 +175,163 @@ function filterJsonData(data: any, context: CompatibilityContext, depth = 0): an
  */
 export const STANDALONE_CHECKPOINT_ID = '_standalone_checkpoint';
 
-export async function createCheckpoint(
+/**
+ * Id for checkpoint records managed by the {@link SentinelCheckpointImplementation} implementation.
+ */
+export const SENTINEL_CHECKPOINT_ID = '_sentinel_checkpoint';
+
+/**
+ * Create a checkpoint by upserting a document in _powersync_checkpoints, and
+ * return a comparable LSN string derived from the write's operationTime.
+ *
+ * Standard MongoDB only: this requires session.operationTime, which DocumentDB
+ * does not provide (it throws PSYNC_S1004 when it is missing). The DocumentDB /
+ * sentinel path builds LSNs via {@link createSentinelCheckpointLsn} instead.
+ */
+export async function createCheckpoint(db: mongo.Db, id: mongo.ObjectId | string): Promise<string> {
+  const TRIES = 2;
+  for (let i = 0; i < TRIES; i++) {
+    try {
+      return await createCheckpointInner(db, id);
+    } catch (e) {
+      if (i < TRIES - 1) {
+        logger.warn(`Failed to create checkpoint on attempt ${i + 1}`, e);
+      } else {
+        throw e;
+      }
+    }
+  }
+  throw new ServiceAssertionError(`Unreachable code`);
+}
+
+async function createCheckpointInner(db: mongo.Db, id: mongo.ObjectId | string): Promise<string> {
+  // We use an unique id per process, and clear documents on startup.
+  // This is so that we can filter events for our own process only, and ignore
+  // events from other processes.
+
+  // We use a command instead of a regular update to avoid auto retries on writes.
+  // An auto retry on the write can trigger a weird edge case where the change stream event
+  // has the clusterTime of the first write, while the returned operation time is for the second no-op write.
+  // Instead, we do manual retries, which does not have the same write de-duplication logic.
+  // A sentinal-based approach would be better here, but that is a much bigger change.
+
+  const update: mongo.Document = { $inc: { i: 1 } };
+
+  const response = await db.command({
+    findAndModify: '_powersync_checkpoints',
+    query: {
+      _id: id as any
+    },
+    new: true,
+    upsert: true,
+    update
+  });
+
+  const time = response.operationTime as mongo.Timestamp | undefined;
+  if (time == null) {
+    throw new ServiceError(ErrorCode.PSYNC_S1004, `clusterTime not available for checkpoint`);
+  }
+  return new MongoLSN({ timestamp: time }).comparable;
+}
+
+/**
+ * Create a DocumentDB comparable LSN by advancing the shared sentinel checkpoint
+ * document ({@link SENTINEL_CHECKPOINT_ID}). The returned LSN encodes the
+ * checkpoint counter in the same 16-hex shape as a MongoDB timestamp LSN (see
+ * {@link SentinelLSN}), so the two formats are directly comparable. The counter is
+ * seeded in the epoch-seconds range (see below), so a sentinel LSN always sorts
+ * above any real-timestamp LSN issued in the past.
+ *
+ * This counter is intentionally global to the source database. It is used for
+ * storage/client checkpoint comparisons and write checkpoint heads, so it must
+ * not reset when a new ChangeStream instance or new sync rules start.
+ *
+ * The document is a single shared record whose `stream_id` field alternates:
+ * batch/keepalive bumps stamp it with the calling stream's id (so a stream can
+ * recognise its own private barriers), while standalone bumps (write checkpoint
+ * heads, snapshot markers) clear it to null. `i` advances globally regardless.
+ *
+ * @param changeStreamId
+ *   When provided, the bump is attributed to this stream (a private barrier).
+ *   When omitted, it is a standalone bump and stream_id is cleared to null.
+ */
+export async function createSentinelCheckpointLsn(
   client: mongo.MongoClient,
   db: mongo.Db,
-  id: mongo.ObjectId | string
+  changeStreamId?: ObjectId
 ): Promise<string> {
   const session = client.startSession();
   try {
-    // We use an unique id per process, and clear documents on startup.
-    // This is so that we can filter events for our own process only, and ignore
-    // events from other processes.
-    await db.collection(CHECKPOINTS_COLLECTION).findOneAndUpdate(
-      {
-        _id: id as any
-      },
-      {
-        $inc: { i: 1 }
-      },
-      {
-        upsert: true,
-        returnDocument: 'after',
-        session
+    const collection = db.collection('_powersync_checkpoints');
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      // Common path: increment the existing counter.
+      const result = await collection.findOneAndUpdate(
+        {
+          _id: SENTINEL_CHECKPOINT_ID as any,
+          i: { $exists: true }
+        },
+        {
+          $inc: { i: 1 },
+          // Standalone bumps (no changeStreamId) must explicitly clear the
+          // stream_id left by a previous batch bump — this is a single shared
+          // document whose stream_id alternates. Write null rather than relying
+          // on `undefined` being serialized (which depends on the driver's
+          // ignoreUndefined option, and collapses to an empty $set if enabled).
+          $set: {
+            stream_id: changeStreamId ?? null
+          }
+        },
+        {
+          returnDocument: 'after',
+          session
+        }
+      );
+
+      if (result != null) {
+        // `i` is a bigint: the client is configured with useBigInt64, and the
+        // seed exceeds 2^53 so it could not be safely represented as a number.
+        return new SentinelLSN({ sentinel: result.i }).comparable;
       }
+
+      // The counter document does not exist: first run, or a consumer deleted
+      // it in their source database. Seed the counter in the epoch-SECONDS range
+      // (seconds in the high 32 bits, mirroring a MongoDB timestamp) rather than
+      // starting at 1. Two properties follow:
+      //
+      // - A sentinel LSN sorts above any real-timestamp LSN issued in the past,
+      //   because its high 32 bits are the current epoch seconds.
+      // - A re-created counter jumps forward instead of backward across deletion:
+      //   the seed advances by 2^32 each wall-clock second, while checkpoints add
+      //   1 each, so any later re-seed exceeds the previously issued coordinate
+      //   (keeping the LSN domain monotonic; otherwise new write checkpoint heads
+      //   could resolve against old, higher committed LSNs).
+      //
+      // $setOnInsert cannot be combined with $inc on the same field, so this
+      // is a separate upsert; the loop then retries the increment. The
+      // $setOnInsert is a no-op if another process created the document
+      // concurrently.
+      await collection.updateOne(
+        {
+          _id: SENTINEL_CHECKPOINT_ID as any
+        },
+        {
+          $setOnInsert: {
+            i: BigInt(Math.floor(Date.now() / 1000)) << 32n,
+            stream_id: changeStreamId ?? null
+          }
+        },
+        {
+          upsert: true,
+          session
+        }
+      );
+    }
+
+    throw new ServiceError(
+      ErrorCode.PSYNC_S1301,
+      `Failed to increment the sentinel checkpoint counter - the checkpoint document may be getting deleted concurrently.`
     );
-    const time = session.operationTime!;
-    // TODO: Use the above when we support custom write checkpoints
-    return new MongoLSN({ timestamp: time }).comparable;
   } finally {
     await session.endSession();
   }

package/src/replication/MongoSnapshotter.ts

@@ -1,7 +1,6 @@
 import { mongo } from '@powersync/lib-service-mongodb';
 import { container, ErrorCode, Logger, ReplicationAbortedError, ServiceError } from '@powersync/lib-services-framework';
 import {
-  InternalOpId,
   MetricsEngine,
   PerformanceTracer,
   SaveOperationTag,
@@ -15,11 +14,13 @@ import { performance } from 'node:perf_hooks';
 import { MongoLSN } from '../common/MongoLSN.js';
 import { PostImagesOption } from '../types/types.js';
 import { escapeRegExp } from '../utils.js';
+import { CheckpointImplementation } from './checkpoints/CheckpointImplementation.js';
+import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
 import { MongoManager } from './MongoManager.js';
-import { createCheckpoint, getMongoRelation, STANDALONE_CHECKPOINT_ID } from './MongoRelation.js';
+import { getMongoRelation } from './MongoRelation.js';
 import { ChunkedSnapshotQuery } from './MongoSnapshotQuery.js';
 import { ChangeStreamBatch, parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
-import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+import { CHECKPOINTS_COLLECTION, detectDocumentDb } from './replication-utils.js';
 import { DirectSourceRowConverter, SourceRowConverter } from './SourceRowConverter.js';
 
 export interface MongoSnapshotterOptions {
@@ -71,9 +72,11 @@ export class MongoSnapshotter {
   private readonly queue = new Set<SnapshotQueueItem>();
   private initialSnapshotDone = Promise.withResolvers<void>();
   private nextItemQueued: PromiseWithResolvers<void> | null = null;
-  private lastSnapshotOpId: InternalOpId | null = null;
   private lastTouchedAt = performance.now();
 
+  private isDocumentDb = false;
+  private _checkpointImplementation: CheckpointImplementation | null = null;
+
   constructor(options: MongoSnapshotterOptions) {
     this.storage = options.storage;
     this.metrics = options.metrics;
@@ -96,6 +99,9 @@ export class MongoSnapshotter {
     this.abortSignal.addEventListener('abort', () => {
       this.nextItemQueued?.resolve();
     });
+
+    // Errors here should not result in uncaught rejection - calling waitForInitialSnapshot is optional.
+    void this.initialSnapshotDone.promise.catch(() => {});
   }
 
   private get usePostImages() {
@@ -110,23 +116,71 @@ export class MongoSnapshotter {
     return this.storage.storageConfig.softDeleteCurrentData;
   }
 
+  /** The active checkpoint strategy. Only valid after ensureDetected(). */
+  private get checkpointImplementation(): CheckpointImplementation {
+    if (this._checkpointImplementation == null) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_S1301,
+        'Checkpoint implementation not initialized - call ensureDetected() first'
+      );
+    }
+    return this._checkpointImplementation;
+  }
+
+  /**
+   * Detect DocumentDB and select the checkpoint implementation. Idempotent.
+   * Also validates server topology (sharded/standalone) for standard MongoDB.
+   */
+  private async ensureDetected(): Promise<void> {
+    if (this._checkpointImplementation != null) {
+      return;
+    }
+    this.isDocumentDb = await detectDocumentDb(this.defaultDb);
+    if (!this.isDocumentDb) {
+      const hello = await this.defaultDb.command({ hello: 1 });
+      if (hello.msg == 'isdbgrid') {
+        throw new ServiceError(
+          ErrorCode.PSYNC_S1341,
+          'Sharded MongoDB Clusters are not supported yet (including MongoDB Serverless instances).'
+        );
+      } else if (hello.setName == null) {
+        throw new ServiceError(
+          ErrorCode.PSYNC_S1342,
+          'Standalone MongoDB instances are not supported - use a replicaset.'
+        );
+      }
+    }
+    this._checkpointImplementation = createCheckpointImplementation(this.isDocumentDb, {
+      client: this.client,
+      db: this.defaultDb,
+      checkpointStreamId: this.checkpointStreamId,
+      logger: this.logger
+    });
+  }
+
   async checkSlot(): Promise<InitResult> {
     const status = await this.storage.getStatus();
-    if (status.snapshot_done && status.checkpoint_lsn) {
+    if (status.snapshotDone) {
       this.logger.info(`Initial replication already done`);
       return { needsInitialSync: false, snapshotLsn: null };
     }
 
-    return { needsInitialSync: true, snapshotLsn: status.snapshot_lsn };
+    return { needsInitialSync: true, snapshotLsn: status.resumeLsn };
   }
 
   async setupCheckpointsCollection() {
+    await this.ensureDetected();
     const collection = await this.getCollectionInfo(this.defaultDb.databaseName, CHECKPOINTS_COLLECTION);
     if (collection == null) {
       await this.defaultDb.createCollection(CHECKPOINTS_COLLECTION, {
-        changeStreamPreAndPostImages: { enabled: true }
+        // DocumentDB does not support changeStreamPreAndPostImages.
+        ...(this.isDocumentDb ? {} : { changeStreamPreAndPostImages: { enabled: true } })
       });
-    } else if (this.usePostImages && collection.options?.changeStreamPreAndPostImages?.enabled != true) {
+    } else if (
+      !this.isDocumentDb &&
+      this.usePostImages &&
+      collection.options?.changeStreamPreAndPostImages?.enabled != true
+    ) {
       // Drop + create requires less permissions than collMod,
       // and we don't care about the data in this collection.
       await this.defaultDb.dropCollection(CHECKPOINTS_COLLECTION);
@@ -137,12 +191,22 @@ export class MongoSnapshotter {
       // Clear the collection on startup, to keep it clean
       // We never query this collection directly, and don't want to keep the data around.
       // We only use this to get data into the oplog/changestream.
-      await this.defaultDb.collection(CHECKPOINTS_COLLECTION).deleteMany({});
+      //
+      // The implementation supplies the filter: the sentinel implementation must
+      // preserve the sentinel checkpoint document, since its counter is the
+      // globally-ordered component of every committed DocumentDB LSN.
+      await this.defaultDb
+        .collection(CHECKPOINTS_COLLECTION)
+        .deleteMany(this.checkpointImplementation.checkpointClearFilter);
     }
   }
 
   async queueSnapshotTables(snapshotLsn: string | null) {
     await this.client.connect();
+    // Ensure isDocumentDb is set before any getSourceNamespaceFilters() call below
+    // (notably the validateSnapshotLsn resume path, which does not go through
+    // getSnapshotLsn). Idempotent.
+    await this.ensureDetected();
     await using writer = await this.storage.createWriter({
       zeroLSN: MongoLSN.ZERO.comparable,
       defaultSchema: this.defaultDb.databaseName,
@@ -258,7 +322,7 @@ export class MongoSnapshotter {
       for (const table of tables) {
         await this.snapshotTable(batch, table);
       }
-      const noCheckpointBefore = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+      const noCheckpointBefore = await this.checkpointImplementation.createStandaloneCheckpoint();
 
       await batch.markTableSnapshotDone(tables, noCheckpointBefore);
     }
@@ -277,20 +341,16 @@ export class MongoSnapshotter {
     }
 
     const status = await this.storage.getStatus();
-    if (status.snapshot_done) {
+    if (status.snapshotDone) {
       return;
     }
 
-    const lastOp = this.lastSnapshotOpId ?? status.keepalive_op;
-    if (lastOp != null) {
-      // Populate the cache _after_ initial replication, but _before_ we switch to this replication stream.
-      // Keeping snapshot_done false until this completes makes this resumable after interruption.
-      await this.storage.populatePersistentChecksumCache({
-        // No checkpoint yet, but we do have the opId.
-        maxOpId: lastOp,
-        signal: this.abortSignal
-      });
-    }
+    // Populate the cache _after_ initial replication, but _before_ we switch to this replication stream.
+    // Keeping snapshot_done false until this completes makes this resumable after interruption.
+    // No checkpoint exists yet - storage defaults to its highest persisted op id.
+    await this.storage.populatePersistentChecksumCache({
+      signal: this.abortSignal
+    });
 
     if (this.queue.size != 0) {
       return;
@@ -306,7 +366,7 @@ export class MongoSnapshotter {
 
     // The checkpoint here is a marker - we need to replicate up to at least this
     // point before the data can be considered consistent.
-    const checkpoint = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    const checkpoint = await this.checkpointImplementation.createStandaloneCheckpoint();
     if (this.queue.size != 0) {
       return;
     }
@@ -318,7 +378,7 @@ export class MongoSnapshotter {
     // KLUDGE: We need to create an extra checkpoint _after_ marking the snapshot done, to fix
     // issues with order of processing commits(). This is picked up by tests on postgres storage,
     // the issue may be specific to that storage engine.
-    await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    await this.checkpointImplementation.createStandaloneCheckpoint();
   }
 
   private async replicateTable(tableRequest: SourceTable) {
@@ -342,16 +402,13 @@ export class MongoSnapshotter {
     }
 
     await this.snapshotTable(writer, table);
-    const noCheckpointBefore = await createCheckpoint(this.client, this.defaultDb, STANDALONE_CHECKPOINT_ID);
+    const noCheckpointBefore = await this.checkpointImplementation.createStandaloneCheckpoint();
     await writer.markTableSnapshotDone([table], noCheckpointBefore);
 
-    // This commit ensures we set keepalive_op.
+    // This commit durably records the persisted ops, so a later checkpoint covers them.
     const resumeLsn = writer.resumeFromLsn ?? MongoLSN.ZERO.comparable;
     await writer.commit(resumeLsn);
 
-    if (writer.last_flushed_op != null) {
-      this.lastSnapshotOpId = writer.last_flushed_op;
-    }
     this.logger.info(`Flushed snapshot at ${writer.last_flushed_op}`);
   }
 
@@ -364,6 +421,13 @@ export class MongoSnapshotter {
       return [];
     }
 
+    if (tablePattern.isSchemaWildcard) {
+      throw new ServiceError(
+        ErrorCode.PSYNC_R2201,
+        'Schema wildcards ("%") in table patterns are not supported for MongoDB connections.'
+      );
+    }
+
     const nameFilter = tablePattern.isWildcard
       ? new RegExp('^' + escapeRegExp(tablePattern.tablePrefix))
       : tablePattern.name;
@@ -445,10 +509,7 @@ export class MongoSnapshotter {
       }
 
       // Important: flush before marking progress
-      const result = await batch.flush();
-      if (result?.flushed_op != null) {
-        this.lastSnapshotOpId = result.flushed_op;
-      }
+      await batch.flush();
       at += docBatch.length;
       rowsReplicatedMetric.add(docBatch.length);
 
@@ -481,10 +542,12 @@ export class MongoSnapshotter {
       // Ignore the postImages check in this case.
     }
 
+    // Note: resolveTables uses the batch's own parsed sync config set. Passing
+    // this.syncRules here would pair sources from one parse with the batch's mapping
+    // from another parse.
     const result = await batch.resolveTables({
       connection_id: this.connectionId,
-      source: descriptor,
-      syncRules: this.syncRules
+      source: descriptor
     });
 
     // Drop conflicting collections.
@@ -526,19 +589,7 @@ export class MongoSnapshotter {
   }
 
   private async getSnapshotLsn(): Promise<string> {
-    const hello = await this.defaultDb.command({ hello: 1 });
-    // Basic sanity check
-    if (hello.msg == 'isdbgrid') {
-      throw new ServiceError(
-        ErrorCode.PSYNC_S1341,
-        'Sharded MongoDB Clusters are not supported yet (including MongoDB Serverless instances).'
-      );
-    } else if (hello.setName == null) {
-      throw new ServiceError(
-        ErrorCode.PSYNC_S1342,
-        'Standalone MongoDB instances are not supported - use a replicaset.'
-      );
-    }
+    await this.ensureDetected();
 
     // Open a change stream just to get a resume token for later use.
     // We could use clusterTime from the hello command, but that won't tell us if the
@@ -551,14 +602,19 @@ export class MongoSnapshotter {
     // Instead, we create a new checkpoint document, and wait until we get that document back in the stream.
     // To avoid potential race conditions with the checkpoint creation, we create a new checkpoint document
     // periodically until the timeout is reached.
+    //
+    // For the sentinel implementation (DocumentDB) there is no
+    // startAtOperationTime: the stream opens from "now" (lsn null) and the
+    // retry loop below re-creates checkpoints until one is observed.
 
     const LSN_TIMEOUT_SECONDS = 60;
     const LSN_CREATE_INTERVAL_SECONDS = 1;
 
-    const firstCheckpointLsn = await createCheckpoint(this.client, this.defaultDb, this.checkpointStreamId);
+    this.checkpointImplementation.seedPosition(null);
+    const startStreamFromLsn = await this.checkpointImplementation.createFirstBarrier();
     const filters = this.getSourceNamespaceFilters();
     const iter = this.rawChangeStreamBatches({
-      lsn: firstCheckpointLsn,
+      lsn: startStreamFromLsn,
       maxAwaitTimeMS: 0,
       signal: this.abortSignal,
       filters
@@ -573,7 +629,7 @@ export class MongoSnapshotter {
         break;
       }
       if (performance.now() - lastCheckpointCreated >= LSN_CREATE_INTERVAL_SECONDS * 1000) {
-        await createCheckpoint(this.client, this.defaultDb, this.checkpointStreamId);
+        await this.checkpointImplementation.createBatchCheckpoint();
         lastCheckpointCreated = performance.now();
       }
       batchesSeen += 1;
@@ -583,14 +639,15 @@ export class MongoSnapshotter {
         const ns = 'ns' in changeDocument && 'coll' in changeDocument.ns ? changeDocument.ns : undefined;
 
         if (ns?.coll == CHECKPOINTS_COLLECTION && 'documentKey' in changeDocument) {
-          const checkpointId = changeDocument.documentKey._id as string | mongo.ObjectId;
-          if (!this.checkpointStreamId.equals(checkpointId)) {
+          const kind = this.checkpointImplementation.event.observe(changeDocument);
+          if (kind != 'own-barrier') {
+            // Standalone events still feed the implementation's coordinate via
+            // event.observe above; we only resolve on our own barrier.
             continue;
           }
-          return new MongoLSN({
-            timestamp: changeDocument.clusterTime!,
-            resume_token: changeDocument._id
-          }).comparable;
+          // Observing our own barrier has set the coordinate (the barrier event
+          // carries the sentinel counter directly), so the LSN is ready.
+          return this.checkpointImplementation.event.lsn(changeDocument);
         }
 
         eventsSeen += 1;
@@ -648,7 +705,12 @@ export class MongoSnapshotter {
       }
     }
 
-    const nsFilter = multipleDatabases
+    // DocumentDB always opens a cluster-level change stream, even in single-database
+    // mode, so a coll-only filter would match same-named collections in other
+    // databases of the cluster. Filter on the full namespace whenever the stream
+    // is cluster-scoped. See ChangeStream.getSourceNamespaceFilters for details.
+    const useFullNamespaceFilter = this.isDocumentDb || multipleDatabases;
+    const nsFilter = useFullNamespaceFilter
       ? { ns: { $in: inFilters } }
       : { 'ns.coll': { $in: inFilters.map((ns) => ns.coll) } };
     if (regexFilters.length > 0) {
@@ -665,12 +727,15 @@ export class MongoSnapshotter {
     signal?: AbortSignal;
     tracer?: PerformanceTracer<'changestream'>;
   }): AsyncIterableIterator<ChangeStreamBatch> {
-    const lastLsn = options.lsn ? MongoLSN.fromSerialized(options.lsn) : null;
-    const startAfter = lastLsn?.timestamp;
-    const resumeAfter = lastLsn?.resumeToken;
+    const position = options.lsn ? this.checkpointImplementation.parseResumePosition(options.lsn) : null;
+    const startAfter = position?.startAfter ?? undefined;
+    const resumeAfter = position?.resumeAfter ?? undefined;
 
     let fullDocument: 'required' | 'updateLookup';
-    if (this.usePostImages) {
+    if (this.isDocumentDb) {
+      // DocumentDB does not support changeStreamPreAndPostImages, so 'required' won't work.
+      fullDocument = 'updateLookup';
+    } else if (this.usePostImages) {
       // 'read_only' or 'auto_configure'
       // Configuration happens during snapshot, or when we see new
       // collections.
@@ -679,27 +744,32 @@ export class MongoSnapshotter {
       fullDocument = 'updateLookup';
     }
     const streamOptions: mongo.ChangeStreamOptions & mongo.Document = {
-      showExpandedEvents: true,
       fullDocument
     };
-    const pipeline: mongo.Document[] = [
-      { $changeStream: streamOptions },
-      { $match: options.filters.$match },
-      { $changeStreamSplitLargeEvent: {} }
-    ];
+    if (!this.isDocumentDb) {
+      // DocumentDB does not support showExpandedEvents.
+      streamOptions.showExpandedEvents = true;
+    }
+    const pipeline: mongo.Document[] = [{ $changeStream: streamOptions }, { $match: options.filters.$match }];
+    if (!this.isDocumentDb) {
+      // DocumentDB does not support $changeStreamSplitLargeEvent.
+      pipeline.push({ $changeStreamSplitLargeEvent: {} });
+    }
 
     // Only one of these options can be supplied at a time.
     if (resumeAfter) {
       streamOptions.resumeAfter = resumeAfter;
-    } else {
+    } else if (startAfter != null) {
       // Legacy: We don't persist lsns without resumeTokens anymore, but we do still handle the
-      // case if we have an old one.
+      // case if we have an old one. The sentinel implementation never produces a startAfter,
+      // and a fresh DocumentDB stream opens from "now" with neither option set.
       streamOptions.startAtOperationTime = startAfter;
     }
 
     let watchDb: mongo.Db;
-    if (options.filters.multipleDatabases) {
-      // Requires readAnyDatabase@admin on Atlas
+    if (this.isDocumentDb || options.filters.multipleDatabases) {
+      // DocumentDB only supports cluster-level change streams.
+      // Requires readAnyDatabase@admin on Atlas.
       watchDb = this.client.db('admin');
       streamOptions.allChangesForCluster = true;
     } else {
@@ -707,9 +777,14 @@ export class MongoSnapshotter {
       watchDb = this.defaultDb;
     }
 
+    const maxAwaitTimeMS = options.maxAwaitTimeMS ?? this.maxAwaitTimeMS;
+
     return rawChangeStream(watchDb, pipeline, {
       batchSize: options.batchSize ?? this.snapshotChunkLength,
-      maxAwaitTimeMS: options.maxAwaitTimeMS ?? this.maxAwaitTimeMS,
+      maxAwaitTimeMS,
+      // maxAwaitTimeMS can be 0 for probe-style streams that do not want an idle wait.
+      // In that case there is no client-side wait to emulate for DocumentDB.
+      clientSideMaxAwaitTimeMS: this.isDocumentDb && maxAwaitTimeMS > 0,
       maxTimeMS: this.changeStreamTimeout,
       signal: options.signal,
       logger: this.logger,