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

package/dist/replication/MongoRelation.js

@@ -2,9 +2,9 @@ import { mongo } from '@powersync/lib-service-mongodb';
 import { storage } from '@powersync/service-core';
 import { JsonContainer } from '@powersync/service-jsonbig';
 import { CustomArray, CustomObject, CustomSqliteValue, DateTimeValue, 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 { MongoLSN } from '../common/MongoLSN.js';
-import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+import { SentinelLSN } from '../common/SentinelLSN.js';
 export function getMongoRelation(source, connectionTag) {
     return {
         connectionTag,
@@ -192,24 +192,139 @@ function filterJsonData(data, context, depth = 0) {
  * the checkpoint immediately, and not wait for batching.
  */
 export const STANDALONE_CHECKPOINT_ID = '_standalone_checkpoint';
-export async function createCheckpoint(client, db, id) {
+/**
+ * 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, id) {
+    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, id) {
+    // 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 = { $inc: { i: 1 } };
+    const response = await db.command({
+        findAndModify: '_powersync_checkpoints',
+        query: {
+            _id: id
+        },
+        new: true,
+        upsert: true,
+        update
+    });
+    const time = response.operationTime;
+    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, db, changeStreamId) {
     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
-        }, {
-            $inc: { i: 1 }
-        }, {
-            upsert: true,
-            returnDocument: 'after',
-            session
-        });
-        const time = session.operationTime;
-        // TODO: Use the above when we support custom write checkpoints
-        return new MongoLSN({ timestamp: time }).comparable;
+        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,
+                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
+            }, {
+                $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();

package/dist/replication/MongoRelation.js.map

@@ -1 +1 @@
-{"version":3,"file":"MongoRelation.js","sourceRoot":"","sources":["../../src/replication/MongoRelation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"MongoRelation.js","sourceRoot":"","sources":["../../src/replication/MongoRelation.ts"],"names":[],"mappings":"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"}

package/dist/replication/MongoSnapshotter.d.ts

@@ -41,12 +41,20 @@ export declare class MongoSnapshotter {
     private readonly queue;
     private initialSnapshotDone;
     private nextItemQueued;
-    private lastSnapshotOpId;
     private lastTouchedAt;
+    private isDocumentDb;
+    private _checkpointImplementation;
     constructor(options: MongoSnapshotterOptions);
     private get usePostImages();
     private get configurePostImages();
     get supportsConcurrentSnapshots(): boolean;
+    /** The active checkpoint strategy. Only valid after ensureDetected(). */
+    private get checkpointImplementation();
+    /**
+     * Detect DocumentDB and select the checkpoint implementation. Idempotent.
+     * Also validates server topology (sharded/standalone) for standard MongoDB.
+     */
+    private ensureDetected;
     checkSlot(): Promise<InitResult>;
     setupCheckpointsCollection(): Promise<void>;
     queueSnapshotTables(snapshotLsn: string | null): Promise<void>;

package/dist/replication/MongoSnapshotter.js

@@ -5,10 +5,11 @@ import { performance } from 'node:perf_hooks';
 import { MongoLSN } from '../common/MongoLSN.js';
 import { PostImagesOption } from '../types/types.js';
 import { escapeRegExp } from '../utils.js';
-import { createCheckpoint, getMongoRelation, STANDALONE_CHECKPOINT_ID } from './MongoRelation.js';
+import { createCheckpointImplementation } from './checkpoints/create-checkpoint-implementation.js';
+import { getMongoRelation } from './MongoRelation.js';
 import { ChunkedSnapshotQuery } from './MongoSnapshotQuery.js';
 import { parseChangeDocument, rawChangeStream } from './RawChangeStream.js';
-import { CHECKPOINTS_COLLECTION } from './replication-utils.js';
+import { CHECKPOINTS_COLLECTION, detectDocumentDb } from './replication-utils.js';
 import { DirectSourceRowConverter } from './SourceRowConverter.js';
 export class MongoSnapshotter {
     storage;
@@ -30,8 +31,9 @@ export class MongoSnapshotter {
     queue = new Set();
     initialSnapshotDone = Promise.withResolvers();
     nextItemQueued = null;
-    lastSnapshotOpId = null;
     lastTouchedAt = performance.now();
+    isDocumentDb = false;
+    _checkpointImplementation = null;
     constructor(options) {
         this.storage = options.storage;
         this.metrics = options.metrics;
@@ -53,6 +55,8 @@ 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(() => { });
     }
     get usePostImages() {
         return this.connections.options.postImages != PostImagesOption.OFF;
@@ -63,22 +67,58 @@ export class MongoSnapshotter {
     get supportsConcurrentSnapshots() {
         return this.storage.storageConfig.softDeleteCurrentData;
     }
+    /** The active checkpoint strategy. Only valid after ensureDetected(). */
+    get 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.
+     */
+    async ensureDetected() {
+        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() {
         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);
@@ -90,11 +130,21 @@ 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) {
         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,
@@ -205,7 +255,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);
         }
     }
@@ -220,19 +270,15 @@ export class MongoSnapshotter {
             return;
         }
         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;
         }
@@ -245,7 +291,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;
         }
@@ -256,7 +302,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();
     }
     async replicateTable(tableRequest) {
         await this.snapshotHooks?.beforeSnapshotStarted?.(tableRequest);
@@ -277,14 +323,11 @@ export class MongoSnapshotter {
             return;
         }
         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}`);
     }
     async resolveQualifiedTableNames(batch, tablePattern) {
@@ -292,6 +335,9 @@ export class MongoSnapshotter {
         if (tablePattern.connectionTag != this.connections.connectionTag) {
             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;
@@ -357,10 +403,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);
             table = await batch.updateTableProgress(table, {
@@ -384,10 +427,12 @@ export class MongoSnapshotter {
             // If collectionInfo is null, the collection may have been dropped.
             // 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.
         // This is generally not expected for MongoDB source dbs, so we log an error.
@@ -421,14 +466,7 @@ export class MongoSnapshotter {
         }
     }
     async getSnapshotLsn() {
-        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
         // snapshot isn't valid anymore.
@@ -440,12 +478,17 @@ 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
@@ -459,7 +502,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;
@@ -467,14 +510,15 @@ export class MongoSnapshotter {
                 const changeDocument = parseChangeDocument(rawChangeDocument);
                 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;
-                    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;
             }
@@ -522,7 +566,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) {
@@ -531,11 +580,15 @@ export class MongoSnapshotter {
         return { $match: nsFilter, multipleDatabases };
     }
     rawChangeStreamBatches(options) {
-        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;
-        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.
@@ -545,26 +598,31 @@ export class MongoSnapshotter {
             fullDocument = 'updateLookup';
         }
         const streamOptions = {
-            showExpandedEvents: true,
             fullDocument
         };
-        const pipeline = [
-            { $changeStream: streamOptions },
-            { $match: options.filters.$match },
-            { $changeStreamSplitLargeEvent: {} }
-        ];
+        if (!this.isDocumentDb) {
+            // DocumentDB does not support showExpandedEvents.
+            streamOptions.showExpandedEvents = true;
+        }
+        const pipeline = [{ $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;
-        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;
         }
@@ -572,9 +630,13 @@ export class MongoSnapshotter {
             // Same general result, but requires less permissions than the above
             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,