@powersync/service-module-mongodb 0.18.2 → 0.19.0

package/src/replication/MongoRelation.ts

@@ -14,7 +14,9 @@ import {
 } from '@powersync/service-sync-rules';
 
 import { ErrorCode, logger, ServiceAssertionError, ServiceError } from '@powersync/lib-services-framework';
+import { ObjectId } from 'bson';
 import { MongoLSN } from '../common/MongoLSN.js';
+import { SentinelLSN } from '../common/SentinelLSN.js';
 
 export function getMongoRelation(
   source: mongo.ChangeStreamNameSpace,
@@ -173,15 +175,24 @@ function filterJsonData(data: any, context: CompatibilityContext, depth = 0): an
  */
 export const STANDALONE_CHECKPOINT_ID = '_standalone_checkpoint';
 
-export async function createCheckpoint(
-  client: mongo.MongoClient,
-  db: mongo.Db,
-  id: mongo.ObjectId | string
-): Promise<string> {
+/**
+ * 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(client, db, id);
+      return await createCheckpointInner(db, id);
     } catch (e) {
       if (i < TRIES - 1) {
         logger.warn(`Failed to create checkpoint on attempt ${i + 1}`, e);
@@ -193,11 +204,7 @@ export async function createCheckpoint(
   throw new ServiceAssertionError(`Unreachable code`);
 }
 
-async function createCheckpointInner(
-  client: mongo.MongoClient,
-  db: mongo.Db,
-  id: mongo.ObjectId | string
-): Promise<string> {
+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.
@@ -208,6 +215,8 @@ async function createCheckpointInner(
   // 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: {
@@ -215,9 +224,7 @@ async function createCheckpointInner(
     },
     new: true,
     upsert: true,
-    update: {
-      $inc: { i: 1 }
-    }
+    update
   });
 
   const time = response.operationTime as mongo.Timestamp | undefined;
@@ -227,6 +234,109 @@ async function createCheckpointInner(
   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,
+  changeStreamId?: ObjectId
+): Promise<string> {
+  const session = client.startSession();
+  try {
+    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.`
+    );
+  } finally {
+    await session.endSession();
+  }
+}
+
 const mongoTimeOptions: DateTimeSourceOptions = {
   subSecondPrecision: TimeValuePrecision.milliseconds,
   defaultSubSecondPrecision: TimeValuePrecision.milliseconds

package/src/replication/MongoSnapshotter.ts

@@ -14,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 {
@@ -72,6 +74,9 @@ export class MongoSnapshotter {
   private nextItemQueued: PromiseWithResolvers<void> | 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;
@@ -108,6 +113,48 @@ 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.snapshotDone) {
@@ -119,12 +166,18 @@ export class MongoSnapshotter {
   }
 
   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);
@@ -135,12 +188,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,
@@ -256,7 +319,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);
     }
@@ -300,7 +363,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;
     }
@@ -312,7 +375,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) {
@@ -336,7 +399,7 @@ 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 durably records the persisted ops, so a later checkpoint covers them.
@@ -516,19 +579,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
@@ -541,14 +592,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
@@ -563,7 +619,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;
@@ -573,14 +629,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;
@@ -638,7 +695,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) {
@@ -655,12 +717,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.
@@ -669,27 +734,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 {
@@ -697,9 +767,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,

package/src/replication/RawChangeStream.ts

@@ -6,18 +6,36 @@ import {
   ReplicationAssertionError
 } from '@powersync/lib-services-framework';
 import { PerformanceTracer } from '@powersync/service-core';
+import { performance } from 'node:perf_hooks';
+import { setTimeout as delay } from 'node:timers/promises';
 import { ChangeStreamInvalidatedError } from './ChangeStream.js';
 
+// Keep the DocumentDB idle-poll workaround from adding the full maxAwaitTimeMS
+// as local latency when an update arrives just after an empty batch.
+const CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS = 1_000;
+
 export interface RawChangeStreamOptions {
   signal?: AbortSignal;
 
   /**
    * How long to wait for new data per batch (max time for long-polling).
+   * This is sent as maxTimeMS for the getMore command.
    *
-   * This is used for maxTimeMS for the getMore command.
+   * A value of 0 is allowed for probe-style streams that do not want an idle
+   * wait; in that case PowerSync also skips the local empty-batch delay.
    */
   maxAwaitTimeMS: number;
 
+  /**
+   * Also enforce maxAwaitTimeMS on the client for empty getMore batches.
+   *
+   * Azure DocumentDB currently returns idle getMore calls before maxTimeMS. When
+   * this is enabled, empty batches are delayed locally (capped at 1s) to avoid
+   * tight polling. We still send maxTimeMS so this remains compatible with
+   * servers that handle maxAwaitTimeMS correctly.
+   */
+  clientSideMaxAwaitTimeMS?: boolean;
+
   /**
    * Timeout for the initial aggregate command.
    */
@@ -212,31 +230,32 @@ async function* rawChangeStreamInner(
       options.signal?.throwIfAborted();
 
       using commandSpan = options.tracer?.span('changestream', 'getmore');
-      const getMoreResult: mongo.Document = await db
-        .command(
-          {
-            getMore: cursorId,
-            collection: nsCollection,
-            batchSize: batchSizer.next(),
-            maxTimeMS: options.maxAwaitTimeMS
-          },
-          { session, raw: true }
-        )
-        .catch((e) => {
-          if (isMongoServerError(e) && e.codeName == 'CursorKilled') {
-            // This may be due to the killCursors command issued when aborting.
-            // In that case, use the abort error instead.
-            options.signal?.throwIfAborted();
-          }
-
-          if (isResumableChangeStreamError(e)) {
-            if (isTimeoutError(e)) {
-              batchSizer.reduceAfterError();
-            }
-            throw new ResumableChangeStreamError(e.message, { cause: e });
+      const getMoreStartedAt = performance.now();
+      const getMoreCommand: mongo.Document = {
+        getMore: cursorId,
+        collection: nsCollection,
+        batchSize: batchSizer.next(),
+        maxTimeMS: options.maxAwaitTimeMS
+      };
+      // Azure DocumentDB currently returns empty getMore batches before
+      // maxTimeMS expires. Keep maxTimeMS for forward compatibility with the
+      // server-side behavior, and when client-side mode is enabled, enforce the
+      // capped idle wait locally for empty batches below.
+      const getMoreResult: mongo.Document = await db.command(getMoreCommand, { session, raw: true }).catch((e) => {
+        if (isMongoServerError(e) && e.codeName == 'CursorKilled') {
+          // This may be due to the killCursors command issued when aborting.
+          // In that case, use the abort error instead.
+          options.signal?.throwIfAborted();
+        }
+
+        if (isResumableChangeStreamError(e)) {
+          if (isTimeoutError(e)) {
+            batchSizer.reduceAfterError();
           }
-          throw mapChangeStreamError(e);
-        });
+          throw new ResumableChangeStreamError(e.message, { cause: e });
+        }
+        throw mapChangeStreamError(e);
+      });
 
       commandSpan?.end();
 
@@ -249,6 +268,13 @@ async function* rawChangeStreamInner(
         // postBatchResumeToken is returned in MongoDB 4.0.7 and later, and we support 6.0+
         throw new ReplicationAssertionError(`postBatchResumeToken from aggregate response`);
       }
+      if (options.clientSideMaxAwaitTimeMS && nextBatch.length == 0) {
+        const remainingMaxAwaitTimeMS = Math.ceil(options.maxAwaitTimeMS - (performance.now() - getMoreStartedAt));
+        if (remainingMaxAwaitTimeMS > 0) {
+          const clientSideDelayMs = Math.min(remainingMaxAwaitTimeMS, CLIENT_SIDE_MAX_AWAIT_TIME_MS_DELAY_CAP_MS);
+          await delay(clientSideDelayMs, undefined, { signal: options.signal });
+        }
+      }
       yield {
         events: nextBatch,
         resumeToken: cursor.postBatchResumeToken,
@@ -400,8 +426,18 @@ export function parseChangeDocument(buffer: Buffer): ProjectedChangeStreamDocume
   return doc as any;
 }
 
+function isMaxTimeMSExpiredError(e: unknown) {
+  return (
+    isMongoServerError(e) &&
+    (e.codeName == 'MaxTimeMSExpired' ||
+      // MongoDB documents code 50 as MaxTimeMSExpired. Azure DocumentDB reports
+      // this code with codeName ExceededTimeLimit.
+      e.code == 50)
+  );
+}
+
 function isTimeoutError(e: unknown) {
-  return isMongoNetworkTimeoutError(e) || (isMongoServerError(e) && e.codeName == 'MaxTimeMSExpired');
+  return isMongoNetworkTimeoutError(e) || isMaxTimeMSExpiredError(e);
 }
 
 function isResumableChangeStreamError(e: unknown) {
@@ -415,8 +451,8 @@ function isResumableChangeStreamError(e: unknown) {
   } else if (e.hasErrorLabel('ResumableChangeStreamError')) {
     // For servers with wire version 9 or higher (server version 4.4 or higher), any server error with the ResumableChangeStreamError error label.
     return true;
-  } else if (e.codeName == 'MaxTimeMSExpired') {
-    // Our own exception for MaxTimeMSExpired.
+  } else if (isMaxTimeMSExpiredError(e)) {
+    // Our own exception for maxTimeMS timeouts.
     // This can help us retry faster, with a smaller batch size (if initialBatchSize is set to 1), which should hopefully avoid the timeout.
     return true;
   } else {