@powersync/service-module-mongodb 0.18.2 → 0.19.0

package/src/replication/checkpoints/CheckpointImplementation.ts

@@ -0,0 +1,167 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { Logger } from '@powersync/lib-services-framework';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+
+import { ProjectedChangeStreamDocument } from '../RawChangeStream.js';
+
+/**
+ * Classification of an event on the `_powersync_checkpoints` collection.
+ *
+ * - 'standalone': source-wide checkpoint (write checkpoints, keepalive bumps,
+ *   snapshot markers). Processed regardless of which process created it.
+ * - 'own-barrier': this stream's private batch barrier document.
+ * - 'foreign': another stream's barrier document — ignore.
+ */
+export type CheckpointEventKind = 'standalone' | 'own-barrier' | 'foreign';
+
+export interface StreamResumePosition {
+  resumeAfter: mongo.ResumeToken | null;
+  /**
+   * Legacy startAtOperationTime fallback. Only produced by the timestamp implementation,
+   * and only for old LSNs persisted without a resume token.
+   */
+  startAfter: mongo.Timestamp | null;
+}
+
+export interface CheckpointImplementationContext {
+  client: mongo.MongoClient;
+  db: mongo.Db;
+  checkpointStreamId: mongo.ObjectId;
+  logger: Logger;
+}
+
+/**
+ * Event-interpretation surface of a {@link CheckpointImplementation}. Every method
+ * operates on a single raw change event.
+ *
+ * Ordering contract: {@link observe} must be called before {@link lsn} for a given
+ * event, so the sentinel implementation's coordinate is current.
+ */
+export interface CheckpointEventApi {
+  /**
+   * Classify a checkpoint-collection event and absorb any coordinate it
+   * carries (sentinel implementation). Must be called for every checkpoint event, in
+   * stream order.
+   */
+  observe(doc: ProjectedChangeStreamDocument): CheckpointEventKind;
+
+  /**
+   * Comparable LSN for committing/resuming at this event.
+   *
+   * Note this is not purely a function of `doc`. The timestamp implementation
+   * derives the whole LSN from the event (its coordinate is the event's
+   * clusterTime). The sentinel implementation pairs the *tracked* coordinate
+   * (updated by {@link observe}) with the event's resume token, because data
+   * events carry no coordinate of their own — hence the observe-before-lsn
+   * contract.
+   */
+  lsn(doc: ProjectedChangeStreamDocument): string;
+
+  /** Whether a barrier marker from {@link CheckpointImplementation.createBatchCheckpoint} is resolved by this event. */
+  resolvesBarrier(marker: string, doc: ProjectedChangeStreamDocument): boolean;
+}
+
+/**
+ * Strategy for producing and interpreting replication checkpoints.
+ *
+ * Two implementations exist:
+ *
+ * - {@link TimestampCheckpointImplementation}: standard MongoDB. The ordered LSN
+ *   coordinate is the oplog clusterTime, which is unique per operation and
+ *   parseable from resume tokens.
+ * - {@link SentinelCheckpointImplementation}: for sources without a usable clusterTime
+ *   (DocumentDB, and technically usable on any MongoDB). The ordered coordinate
+ *   is a shared monotonic counter document, observed through the change
+ *   stream itself.
+ *
+ * An implementation instance belongs to a single ChangeStream (or API adapter) and may
+ * hold per-stream coordinate state; call {@link seedPosition} at the start of
+ * each streaming loop.
+ */
+export interface CheckpointImplementation {
+  /** LSN representing "before any data". */
+  readonly zeroLsn: string;
+
+  /** Parse a stored LSN into change stream resume options. Pure. */
+  parseResumePosition(lsn: string): StreamResumePosition;
+
+  /** Reset/seed the implementation's coordinate state for a new stream loop. */
+  seedPosition(lsn: string | null): void;
+
+  /** Log the resume position at the start of a streaming loop. */
+  logResume(lsn: string): void;
+
+  /**
+   * Create a source-wide consistency checkpoint (snapshot boundaries,
+   * `no_checkpoint_before` markers). Returns a comparable LSN.
+   */
+  createStandaloneCheckpoint(): Promise<string>;
+
+  /**
+   * Create a batch barrier for this stream. Returns a marker that is resolved
+   * by a later change stream event via {@link CheckpointEventApi.resolvesBarrier}.
+   */
+  createBatchCheckpoint(): Promise<string>;
+
+  /**
+   * Create the first batch barrier for snapshot-LSN acquisition and return the
+   * LSN to open the change stream from, or null to open from "now".
+   *
+   * The timestamp implementation's barrier marker is itself a comparable LSN, so
+   * the stream resumes from it. The sentinel implementation's marker is opaque
+   * (content-matched) and carries no resume position, so it returns null and the
+   * stream opens from the current point.
+   */
+  createFirstBarrier(): Promise<string | null>;
+
+  /**
+   * Idle keepalive for an empty change stream batch. May persist a checkpoint
+   * directly (timestamp implementation) or nudge the source so that a later event
+   * commits (sentinel implementation).
+   */
+  keepalive(batch: storage.BucketStorageBatch, resumeToken: mongo.ResumeToken): Promise<void>;
+
+  /**
+   * Build a comparable LSN from a bare batch-level resume token (no change
+   * event). Used for the per-batch `setResumeLsn` progress marker.
+   *
+   * The timestamp implementation parses the timestamp embedded in the token.
+   * The sentinel implementation pairs the token with the current coordinate.
+   */
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string;
+
+  /**
+   * Source-side replication head for write checkpoints. The LSN passed to the
+   * callback must compare at or below any LSN committed after the caller's
+   * preceding writes.
+   */
+  createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T>;
+
+  /** Event-interpretation methods, all operating on a single raw change event. */
+  readonly event: CheckpointEventApi;
+
+  /** Filter for clearing the checkpoints collection on startup. */
+  readonly checkpointClearFilter: mongo.Filter<mongo.Document>;
+}
+
+/**
+ * Extract the event timestamp: clusterTime when present, otherwise wallTime
+ * truncated to second precision.
+ */
+export function getEventTimestamp(changeDocument: ProjectedChangeStreamDocument): mongo.Timestamp {
+  if (changeDocument.clusterTime) {
+    return changeDocument.clusterTime;
+  }
+  const wallTime = (changeDocument as any).wallTime as Date | undefined;
+  if (wallTime != null) {
+    return mongo.Timestamp.fromBits(0, Math.floor(wallTime.getTime() / 1000));
+  }
+  throw new Error('Change event has neither clusterTime nor wallTime');
+}
+
+export function getCheckpointId(doc: ProjectedChangeStreamDocument): string | mongo.ObjectId | null {
+  if (!('documentKey' in doc)) {
+    return null;
+  }
+  return doc.documentKey._id as string | mongo.ObjectId;
+}

package/src/replication/checkpoints/SentinelCheckpointImplementation.ts

@@ -0,0 +1,267 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+import { JSONBig } from '@powersync/service-jsonbig';
+import { SentinelLSN } from '../../common/SentinelLSN.js';
+import { ChangeStreamInvalidatedError } from '../ChangeStream.js';
+import { createSentinelCheckpointLsn, SENTINEL_CHECKPOINT_ID } from '../MongoRelation.js';
+import { ProjectedChangeStreamDocument } from '../RawChangeStream.js';
+import {
+  CheckpointEventApi,
+  CheckpointEventKind,
+  CheckpointImplementation,
+  CheckpointImplementationContext,
+  getCheckpointId,
+  StreamResumePosition
+} from './CheckpointImplementation.js';
+
+/**
+ * Sentinel checkpoint implementation, used for sources without a usable clusterTime
+ * (DocumentDB). The ordered LSN coordinate is a single shared sentinel checkpoint
+ * counter ({@link SENTINEL_CHECKPOINT_ID}), observed through the change stream:
+ *
+ * - Batch checkpoints advance the global counter and stamp it with this stream's
+ *   id, so the stream recognises its own private barriers by content (stream_id
+ *   + counter) rather than by cross-document event ordering.
+ * - Standalone bumps (write checkpoint heads, snapshot markers) advance the same
+ *   counter with a null stream_id; every stream observes these as the global
+ *   coordinate.
+ * - Keepalives advance the counter without persisting; the bump's own event
+ *   flows through the stream and commits via the standalone handling,
+ *   preserving the "commit only what the stream has seen" barrier property.
+ *
+ * See docs/documentdb/documentdb-lsn-sentinel-checkpoints.md for the full design.
+ */
+export class SentinelCheckpointImplementation implements CheckpointImplementation {
+  readonly zeroLsn = SentinelLSN.ZERO.comparable;
+
+  /**
+   * The highest global sentinel value proven so far, merged monotonically from
+   * the resume seed, standalone events and embedded barrier values. Needed
+   * for lsnFromResumeToken: per-batch resume markers carry only a resume token,
+   * so they need the latest observed coordinate paired in.
+   */
+  private position = SentinelLSN.ZERO.sentinel;
+
+  constructor(private context: CheckpointImplementationContext) {}
+
+  parseResumePosition(lsn: string): StreamResumePosition {
+    const parsed = SentinelLSN.fromSerialized(lsn);
+    return { resumeAfter: parsed.resumeToken ?? null, startAfter: null };
+  }
+
+  seedPosition(lsn: string | null): void {
+    this.position = lsn == null ? SentinelLSN.ZERO.sentinel : SentinelLSN.fromSerialized(lsn).sentinel;
+  }
+
+  logResume(lsn: string): void {
+    const parsed = SentinelLSN.fromSerialized(lsn);
+    this.context.logger.info(`Resume streaming at sentinel ${parsed.sentinel} / ${parsed}`);
+  }
+
+  async createStandaloneCheckpoint(): Promise<string> {
+    return createSentinelCheckpointLsn(this.context.client, this.context.db);
+  }
+
+  async createBatchCheckpoint(): Promise<string> {
+    // Advance the shared sentinel checkpoint — the global source-database
+    // coordinate. It must be shared so the LSN domain survives new
+    // ChangeStream instances and new sync rules.
+    // This advance is associated with the change stream in order to track stream
+    // barriers. The returned LSN (counter only, no resume token) is the barrier
+    // marker matched by resolvesBarrier.
+    return createSentinelCheckpointLsn(this.context.client, this.context.db, this.context.checkpointStreamId);
+  }
+
+  async createFirstBarrier(): Promise<string | null> {
+    // The barrier marker is an opaque content-matched marker, not a resume
+    // position, so there is no LSN to open the stream from: a fresh DocumentDB
+    // stream opens from "now" and the snapshot loop re-creates barriers until
+    // one is observed.
+    await this.createBatchCheckpoint();
+    return null;
+  }
+
+  async keepalive(_batch: storage.BucketStorageBatch, _resumeToken: mongo.ResumeToken): Promise<void> {
+    // Advance the shared sentinel, but do not persist a checkpoint here. The
+    // bump is stamped with this stream's id, so its own change event flows
+    // through the stream as an own-barrier event and is committed by the
+    // own-barrier handling, which advances the ordered LSN prefix and refreshes
+    // the resume token (using the event's own token).
+    //
+    // Why bump at all: with an unchanged sentinel, LSN comparison against the
+    // previously persisted LSN falls to the opaque base64 token suffix, which
+    // is not lexicographically meaningful — storage would silently reject
+    // roughly half of plain token refreshes, leaving the persisted resume
+    // token to go stale on an idle stream. (The timestamp implementation avoids this
+    // because its keepalive timestamp is parsed from the resume token itself,
+    // so the ordered prefix always advances with the token.)
+    //
+    // Why not persist immediately: writes that landed after this empty batch
+    // was read — including a write checkpoint head — would be covered by the
+    // persisted LSN before the stream has processed them, allowing write
+    // checkpoints to resolve before the corresponding data is replicated.
+    // Committing only when the bump's event is observed preserves the
+    // "commit only what the stream has seen" barrier property.
+    await createSentinelCheckpointLsn(this.context.client, this.context.db, this.context.checkpointStreamId);
+    this.context.logger.info(
+      `Idle change stream (sentinel implementation). Bumped sentinel to advance the checkpoint.`
+    );
+  }
+
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string {
+    // Pair the bare token with the current coordinate. The coordinate is
+    // frozen between checkpoint events, so a per-batch resume marker only
+    // advances the token; that is all resumption needs (see the design doc).
+    return new SentinelLSN({ sentinel: this.position, resume_token: resumeToken }).comparable;
+  }
+
+  async createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T> {
+    const head = await createSentinelCheckpointLsn(this.context.client, this.context.db);
+    const result = await callback(head);
+    // Create another bump to ensure movement after the reported head. This
+    // covers the race where the head's own event is committed before the
+    // write checkpoint document is stored.
+    // Note that this checkpoint should not be associated with a change stream Id.
+    await createSentinelCheckpointLsn(this.context.client, this.context.db);
+    return result;
+  }
+
+  readonly event: CheckpointEventApi = {
+    observe: (doc) => {
+      const checkpointId = getCheckpointId(doc);
+      if (checkpointId != SENTINEL_CHECKPOINT_ID) {
+        // The sentinel implementation only uses the SENTINEL_CHECKPOINT_ID
+        // document; anything else (including the timestamp impl's standalone
+        // document) is foreign.
+        return 'foreign';
+      }
+      const fullDoc = deserializeFullDocument(doc);
+      if (fullDoc == null) {
+        // An insert/update/replace on our sentinel document must carry a
+        // post-image. A missing fullDocument means the document was deleted or
+        // replaced out from under us, which destroys the coordinate; invalidate
+        // so replication restarts clean instead of stalling.
+        throw new ChangeStreamInvalidatedError(
+          'Sentinel checkpoint event has no fullDocument — cannot read the sentinel',
+          new Error(`Unexpected ${doc.operationType} event on the sentinel checkpoint document`)
+        );
+      }
+      const streamId = fullDoc.stream_id;
+
+      let kind: CheckpointEventKind;
+      if (streamId == null) {
+        // No stream_id: a standalone bump (write checkpoint head, snapshot
+        // marker). Every stream tracks these as the global coordinate.
+        kind = 'standalone';
+      } else if (this.context.checkpointStreamId.equals(streamId)) {
+        // Stamped with our id: one of our own private batch/keepalive barriers.
+        kind = 'own-barrier';
+      } else {
+        // Another stream's private barrier — ignore.
+        return 'foreign';
+      }
+
+      // Both kinds carry the global coordinate in `i`; keep our position current.
+      this.mergePosition(this.readSentinel(fullDoc));
+      return kind;
+    },
+
+    lsn: (doc) => {
+      const fullDoc = deserializeFullDocument(doc);
+      if (fullDoc == null) {
+        throw new ChangeStreamInvalidatedError(
+          'Sentinel checkpoint event has no fullDocument — cannot read the sentinel',
+          new Error(`Unexpected ${doc.operationType} event on the sentinel checkpoint document`)
+        );
+      }
+
+      // Checkpoint events carry the global coordinate in `i`; pair that exact
+      // coordinate with this event's resume token. Plain data-batch resume
+      // markers use lsnFromResumeToken, which pairs the token with the tracked
+      // position instead.
+      return new SentinelLSN({
+        sentinel: this.readSentinel(fullDoc),
+        resume_token: doc._id
+      }).comparable;
+    },
+
+    resolvesBarrier: (marker, doc) => {
+      const fullDoc = deserializeFullDocument(doc);
+      if (fullDoc == null) {
+        this.context.logger.warn('Checkpoint event missing fullDocument — cannot match sentinel barrier');
+        return false;
+      }
+      const parsed = SentinelLSN.fromSerialized(marker);
+      return this.context.checkpointStreamId.equals(fullDoc.stream_id) && fullDoc.i >= parsed.sentinel;
+    }
+  };
+
+  // The sentinel checkpoint document must survive restarts (hence the $ne
+  // below — the startup cleanup deletes every other checkpoint document). Its
+  // counter is the globally-ordered component of every committed LSN, including
+  // write checkpoint heads. Deleting it would re-seed the counter on the next
+  // upsert, risking moving the LSN coordinate system backwards: new commits
+  // could compare below the persisted last_checkpoint_lsn (so storage rejects
+  // them via checkpointBlocked and the checkpoint stalls), and new write
+  // checkpoint heads could resolve against old, higher committed LSNs before
+  // their data has actually replicated.
+  //
+  // Note: this only protects against our own startup cleanup. The global
+  // LSN coordinate still lives in a user-visible collection, so a consumer
+  // can delete it in their source database. Dropping the whole checkpoints
+  // collection is detected (the streaming loop invalidates the stream on the
+  // collection drop event). Deleting just this document is mitigated by
+  // createSentinelCheckpointLsn seeding re-created counters at the current
+  // epoch seconds, so the coordinate jumps forward instead of resetting
+  // below already-committed LSNs.
+  readonly checkpointClearFilter: mongo.Filter<mongo.Document> = { _id: { $ne: SENTINEL_CHECKPOINT_ID } as any };
+
+  /** Never move the position backwards — replayed or reordered events must not regress the coordinate. */
+  private mergePosition(observed: bigint) {
+    if (observed > this.position) {
+      this.position = observed;
+    }
+  }
+
+  /**
+   * Read the sentinel counter from a sentinel checkpoint post-image.
+   *
+   * The `i` field is required: every sentinel write `$inc`s it. If it is
+   * missing, the document was replaced externally, which destroys the LSN
+   * coordinate system (a re-created counter restarts below already-committed
+   * LSNs). Invalidate the stream so replication restarts from scratch instead
+   * of stalling against a broken coordinate.
+   */
+  private readSentinel(fullDoc: mongo.Document): bigint {
+    if (fullDoc.i == null) {
+      throw new ChangeStreamInvalidatedError(
+        'Sentinel checkpoint document has no `i` field — cannot read the sentinel',
+        // JSONBig.stringify, since the post-image is deserialized with useBigInt64.
+        new Error(`Sentinel checkpoint document: ${JSONBig.stringify(fullDoc)}`)
+      );
+    }
+    return fullDoc.i;
+  }
+}
+
+/**
+ * A change event with the decoded `fullDocument` post-image memoized on it, so
+ * a consumer that reads it more than once — e.g. observe() then resolvesBarrier()
+ * for the same event — decodes the buffer only once. `undefined` until first
+ * decoded; `null` when there is no fullDocument.
+ */
+type MemoizedChangeStreamDocument = ProjectedChangeStreamDocument & {
+  parsedFullDocument?: mongo.Document | null;
+};
+
+function deserializeFullDocument(doc: ProjectedChangeStreamDocument): mongo.Document | null {
+  const memo = doc as MemoizedChangeStreamDocument;
+  if (memo.parsedFullDocument !== undefined) {
+    return memo.parsedFullDocument;
+  }
+  const fullDocument = 'fullDocument' in doc ? doc.fullDocument : null;
+  // fullDocument is a raw BSON Buffer from parseChangeDocument.
+  const parsed = fullDocument ? mongo.BSON.deserialize(fullDocument as Buffer, { useBigInt64: true }) : null;
+  memo.parsedFullDocument = parsed;
+  return parsed;
+}

package/src/replication/checkpoints/TimestampCheckpointImplementation.ts

@@ -0,0 +1,142 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import { ReplicationHeadCallback, storage } from '@powersync/service-core';
+import { MongoLSN } from '../../common/MongoLSN.js';
+import { createCheckpoint, SENTINEL_CHECKPOINT_ID, STANDALONE_CHECKPOINT_ID } from '../MongoRelation.js';
+import { CHECKPOINTS_COLLECTION, timestampToDate } from '../replication-utils.js';
+import {
+  CheckpointEventApi,
+  CheckpointImplementation,
+  CheckpointImplementationContext,
+  getCheckpointId,
+  getEventTimestamp,
+  StreamResumePosition
+} from './CheckpointImplementation.js';
+
+/**
+ * Standard MongoDB checkpoint implementation. The ordered LSN coordinate is the oplog
+ * clusterTime — unique per operation, monotonic, and parseable from resume
+ * tokens. Barriers and event LSNs are plain comparable LSN strings.
+ */
+export class TimestampCheckpointImplementation implements CheckpointImplementation {
+  readonly zeroLsn = MongoLSN.ZERO.comparable;
+
+  constructor(private context: CheckpointImplementationContext) {}
+
+  parseResumePosition(lsn: string): StreamResumePosition {
+    const parsed = MongoLSN.fromSerialized(lsn);
+    return { resumeAfter: parsed.resumeToken ?? null, startAfter: parsed.timestamp };
+  }
+
+  seedPosition(_lsn: string | null): void {
+    // The coordinate comes from each event's clusterTime; no state to seed.
+  }
+
+  logResume(lsn: string): void {
+    const parsed = MongoLSN.fromSerialized(lsn);
+    // It is normal for this to be a minute or two old when there is a low volume
+    // of ChangeStream events.
+    const tokenAgeSeconds = Math.round((Date.now() - timestampToDate(parsed.timestamp).getTime()) / 1000);
+    this.context.logger.info(
+      `Resume streaming at ${parsed.timestamp.inspect()} / ${parsed} | Token age: ${tokenAgeSeconds}s`
+    );
+  }
+
+  async createStandaloneCheckpoint(): Promise<string> {
+    return createCheckpoint(this.context.db, STANDALONE_CHECKPOINT_ID);
+  }
+
+  async createBatchCheckpoint(): Promise<string> {
+    return createCheckpoint(this.context.db, this.context.checkpointStreamId);
+  }
+
+  async createFirstBarrier(): Promise<string | null> {
+    // The barrier marker is a comparable LSN; resume the snapshot stream from it.
+    return this.createBatchCheckpoint();
+  }
+
+  async keepalive(batch: storage.BucketStorageBatch, resumeToken: mongo.ResumeToken): Promise<void> {
+    // Parse the timestamp from the resume token. The ordered LSN prefix
+    // advances together with the token, so persisting is always safe.
+    const { comparable: lsn, timestamp } = MongoLSN.fromResumeToken(resumeToken);
+    await batch.keepalive(lsn);
+    // Log the token update. This helps as a general "replication is still active" message in the logs.
+    // This token would typically be around 10s behind.
+    this.context.logger.info(
+      `Idle change stream. Persisted resumeToken for ${timestampToDate(timestamp).toISOString()}`
+    );
+  }
+
+  lsnFromResumeToken(resumeToken: mongo.ResumeToken): string {
+    // The timestamp is embedded in the resume token.
+    return MongoLSN.fromResumeToken(resumeToken).comparable;
+  }
+
+  async createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T> {
+    const session = this.context.client.startSession();
+    try {
+      await this.context.db.command({ hello: 1 }, { session });
+      const head = session.clusterTime?.clusterTime;
+      if (head == null) {
+        throw new ServiceAssertionError(`clusterTime not available for write checkpoint`);
+      }
+
+      const r = await callback(new MongoLSN({ timestamp: head }).comparable);
+
+      // Trigger a change on the changestream, so that the write checkpoint
+      // is processed without waiting for other writes.
+      await this.context.db.collection(CHECKPOINTS_COLLECTION).findOneAndUpdate(
+        {
+          _id: STANDALONE_CHECKPOINT_ID as any
+        },
+        {
+          $inc: { i: 1 }
+        },
+        {
+          upsert: true,
+          returnDocument: 'after',
+          session
+        }
+      );
+      const time = session.operationTime!;
+      if (time == null) {
+        throw new ServiceAssertionError(`operationTime not available for write checkpoint`);
+      } else if (time.lt(head)) {
+        throw new ServiceAssertionError(`operationTime must be > clusterTime`);
+      }
+
+      return r;
+    } finally {
+      await session.endSession();
+    }
+  }
+
+  readonly event: CheckpointEventApi = {
+    observe: (doc) => {
+      const checkpointId = getCheckpointId(doc);
+      if (checkpointId == null || checkpointId == SENTINEL_CHECKPOINT_ID) {
+        return 'foreign';
+      }
+      // The STANDALONE_CHECKPOINT_ID is only used for the TimestampCheckpointImplementation
+      if (checkpointId == STANDALONE_CHECKPOINT_ID) {
+        return 'standalone';
+      }
+      return this.context.checkpointStreamId.equals(checkpointId) ? 'own-barrier' : 'foreign';
+    },
+
+    lsn: (doc) => {
+      return new MongoLSN({
+        timestamp: getEventTimestamp(doc),
+        resume_token: doc._id
+      }).comparable;
+    },
+
+    resolvesBarrier: (marker, doc) => {
+      // Barrier markers are comparable LSNs in this implementation.
+      return this.event.lsn(doc) >= marker;
+    }
+  };
+
+  // It's safe to clear the entire _powersync_checkpoints collection in this mode.
+  readonly checkpointClearFilter: mongo.Filter<mongo.Document> = {};
+}

package/src/replication/checkpoints/create-checkpoint-implementation.ts

@@ -0,0 +1,14 @@
+import { CheckpointImplementation, CheckpointImplementationContext } from './CheckpointImplementation.js';
+import { SentinelCheckpointImplementation } from './SentinelCheckpointImplementation.js';
+import { TimestampCheckpointImplementation } from './TimestampCheckpointImplementation.js';
+
+/**
+ * Select the checkpoint implementation for a source: sentinel-based for DocumentDB
+ * DB, clusterTime-based for standard MongoDB.
+ */
+export function createCheckpointImplementation(
+  isDocumentDb: boolean,
+  context: CheckpointImplementationContext
+): CheckpointImplementation {
+  return isDocumentDb ? new SentinelCheckpointImplementation(context) : new TimestampCheckpointImplementation(context);
+}

package/src/replication/replication-utils.ts

@@ -1,3 +1,4 @@
+import { mongo } from '@powersync/lib-service-mongodb';
 import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import * as bson from 'bson';
 import { PostImagesOption } from '../types/types.js';
@@ -7,16 +8,36 @@ export const CHECKPOINTS_COLLECTION = '_powersync_checkpoints';
 
 const REQUIRED_CHECKPOINT_PERMISSIONS = ['find', 'insert', 'update', 'remove', 'changeStream', 'createCollection'];
 
+/**
+ * Whether a `hello` response indicates Azure DocumentDB (formerly Azure Cosmos
+ * DB for MongoDB vCore), which reports `documentdb_versions` in the `internal`
+ * section.
+ */
+function isDocumentDbHello(hello: mongo.Document): boolean {
+  return hello.internal?.documentdb_versions != null;
+}
+
+/**
+ * Detect whether the connected server is DocumentDB. DocumentDB lacks usable
+ * clusterTime/operationTime and uses the sentinel checkpoint implementation.
+ */
+export async function detectDocumentDb(db: mongo.Db): Promise<boolean> {
+  const hello = await db.command({ hello: 1 });
+  return isDocumentDbHello(hello);
+}
+
 export async function checkSourceConfiguration(connectionManager: MongoManager): Promise<void> {
   const db = connectionManager.db;
 
   const hello = await db.command({ hello: 1 });
-  if (hello.msg == 'isdbgrid') {
+  const isDocumentDb = isDocumentDbHello(hello);
+
+  if (hello.msg == 'isdbgrid' && !isDocumentDb) {
     throw new ServiceError(
       ErrorCode.PSYNC_S1341,
       'Sharded MongoDB Clusters are not supported yet (including MongoDB Serverless instances).'
     );
-  } else if (hello.setName == null) {
+  } else if (hello.setName == null && !isDocumentDb) {
     throw new ServiceError(ErrorCode.PSYNC_S1342, 'Standalone MongoDB instances are not supported - use a replicaset.');
   }