@powersync/service-module-mongodb 0.18.2 → 0.20.0

package/dist/replication/checkpoints/TimestampCheckpointImplementation.js

@@ -0,0 +1,116 @@
+import { ServiceAssertionError } from '@powersync/lib-services-framework';
+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 { getCheckpointId, getEventTimestamp } 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 {
+    context;
+    zeroLsn = MongoLSN.ZERO.comparable;
+    constructor(context) {
+        this.context = context;
+    }
+    parseResumePosition(lsn) {
+        const parsed = MongoLSN.fromSerialized(lsn);
+        return { resumeAfter: parsed.resumeToken ?? null, startAfter: parsed.timestamp };
+    }
+    seedPosition(_lsn) {
+        // The coordinate comes from each event's clusterTime; no state to seed.
+    }
+    logResume(lsn) {
+        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() {
+        return createCheckpoint(this.context.db, STANDALONE_CHECKPOINT_ID);
+    }
+    async createBatchCheckpoint() {
+        return createCheckpoint(this.context.db, this.context.checkpointStreamId);
+    }
+    async createFirstBarrier() {
+        // The barrier marker is a comparable LSN; resume the snapshot stream from it.
+        return this.createBatchCheckpoint();
+    }
+    async keepalive(batch, resumeToken) {
+        // 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) {
+        // The timestamp is embedded in the resume token.
+        const lsn = MongoLSN.fromResumeToken(resumeToken);
+        return { lsn: lsn.comparable, timestamp: timestampToDate(lsn.timestamp) };
+    }
+    async createReplicationHead(callback) {
+        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 { response, shouldAdvance } = await callback(new MongoLSN({ timestamp: head }).comparable);
+            if (shouldAdvance) {
+                // 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
+                }, {
+                    $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 response;
+        }
+        finally {
+            await session.endSession();
+        }
+    }
+    event = {
+        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.
+    checkpointClearFilter = {};
+}
+//# sourceMappingURL=TimestampCheckpointImplementation.js.map

package/dist/replication/checkpoints/TimestampCheckpointImplementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimestampCheckpointImplementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/TimestampCheckpointImplementation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAIL,eAAe,EACf,iBAAiB,EAElB,MAAM,+BAA+B,CAAC;AAEvC;;;;GAIG;AACH,MAAM,OAAO,iCAAiC;IAGxB;IAFX,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;IAE5C,YAAoB,OAAwC;QAAxC,YAAO,GAAP,OAAO,CAAiC;IAAG,CAAC;IAEhE,mBAAmB,CAAC,GAAW;QAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IACnF,CAAC;IAED,YAAY,CAAC,IAAmB;QAC9B,wEAAwE;IAC1E,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAC5C,6EAA6E;QAC7E,0BAA0B;QAC1B,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACtG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CACtB,uBAAuB,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,MAAM,iBAAiB,eAAe,GAAG,CACjG,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,0BAA0B;QAC9B,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,wBAAwB,CAAC,CAAC;IACrE,CAAC;IAED,KAAK,CAAC,qBAAqB;QACzB,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,kBAAkB;QACtB,8EAA8E;QAC9E,OAAO,IAAI,CAAC,qBAAqB,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,KAAiC,EAAE,WAA8B;QAC/E,oEAAoE;QACpE,kEAAkE;QAClE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;QAC7E,MAAM,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC3B,mGAAmG;QACnG,mDAAmD;QACnD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CACtB,iDAAiD,eAAe,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAC5F,CAAC;IACJ,CAAC;IAED,kBAAkB,CAAC,WAA8B;QAC/C,iDAAiD;QACjD,MAAM,GAAG,GAAG,QAAQ,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;QAClD,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,qBAAqB,CAAI,QAAoC;QACjE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YACzD,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,WAAW,CAAC;YAC9C,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACjB,MAAM,IAAI,qBAAqB,CAAC,gDAAgD,CAAC,CAAC;YACpF,CAAC;YAED,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,QAAQ,CAAC,IAAI,QAAQ,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;YAEjG,IAAI,aAAa,EAAE,CAAC;gBAClB,qEAAqE;gBACrE,iDAAiD;gBACjD,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,sBAAsB,CAAC,CAAC,gBAAgB,CACvE;oBACE,GAAG,EAAE,wBAA+B;iBACrC,EACD;oBACE,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE;iBACf,EACD;oBACE,MAAM,EAAE,IAAI;oBACZ,cAAc,EAAE,OAAO;oBACvB,OAAO;iBACR,CACF,CAAC;gBACF,MAAM,IAAI,GAAG,OAAO,CAAC,aAAc,CAAC;gBACpC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;oBACjB,MAAM,IAAI,qBAAqB,CAAC,kDAAkD,CAAC,CAAC;gBACtF,CAAC;qBAAM,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;oBACzB,MAAM,IAAI,qBAAqB,CAAC,qCAAqC,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;YAED,OAAO,QAAQ,CAAC;QAClB,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC7B,CAAC;IACH,CAAC;IAEQ,KAAK,GAAuB;QACnC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACf,MAAM,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YAC1C,IAAI,YAAY,IAAI,IAAI,IAAI,YAAY,IAAI,sBAAsB,EAAE,CAAC;gBACnE,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,sFAAsF;YACtF,IAAI,YAAY,IAAI,wBAAwB,EAAE,CAAC;gBAC7C,OAAO,YAAY,CAAC;YACtB,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC1F,CAAC;QAED,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE;YACX,OAAO,IAAI,QAAQ,CAAC;gBAClB,SAAS,EAAE,iBAAiB,CAAC,GAAG,CAAC;gBACjC,YAAY,EAAE,GAAG,CAAC,GAAG;aACtB,CAAC,CAAC,UAAU,CAAC;QAChB,CAAC;QAED,eAAe,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;YAC/B,8DAA8D;YAC9D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC;QACvC,CAAC;KACF,CAAC;IAEF,gFAAgF;IACvE,qBAAqB,GAAiC,EAAE,CAAC;CACnE"}

package/dist/replication/checkpoints/create-checkpoint-implementation.d.ts

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

package/dist/replication/checkpoints/create-checkpoint-implementation.js

@@ -0,0 +1,10 @@
+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, context) {
+    return isDocumentDb ? new SentinelCheckpointImplementation(context) : new TimestampCheckpointImplementation(context);
+}
+//# sourceMappingURL=create-checkpoint-implementation.js.map

package/dist/replication/checkpoints/create-checkpoint-implementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-checkpoint-implementation.js","sourceRoot":"","sources":["../../../src/replication/checkpoints/create-checkpoint-implementation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAC;AAE3F;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC5C,YAAqB,EACrB,OAAwC;IAExC,OAAO,YAAY,CAAC,CAAC,CAAC,IAAI,gCAAgC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,iCAAiC,CAAC,OAAO,CAAC,CAAC;AACvH,CAAC"}

package/dist/replication/replication-utils.d.ts

@@ -1,5 +1,11 @@
+import { mongo } from '@powersync/lib-service-mongodb';
 import * as bson from 'bson';
 import { MongoManager } from './MongoManager.js';
 export declare const CHECKPOINTS_COLLECTION = "_powersync_checkpoints";
+/**
+ * Detect whether the connected server is DocumentDB. DocumentDB lacks usable
+ * clusterTime/operationTime and uses the sentinel checkpoint implementation.
+ */
+export declare function detectDocumentDb(db: mongo.Db): Promise<boolean>;
 export declare function checkSourceConfiguration(connectionManager: MongoManager): Promise<void>;
 export declare function timestampToDate(timestamp: bson.Timestamp): Date;

package/dist/replication/replication-utils.js

@@ -2,13 +2,30 @@ import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import { PostImagesOption } from '../types/types.js';
 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) {
+    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) {
+    const hello = await db.command({ hello: 1 });
+    return isDocumentDbHello(hello);
+}
 export async function checkSourceConfiguration(connectionManager) {
     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.');
     }
     // https://www.mongodb.com/docs/manual/reference/command/connectionStatus/

package/dist/replication/replication-utils.js.map

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

package/dist/types/types.d.ts

@@ -43,6 +43,7 @@ export interface NormalizedMongoConnectionConfig {
     password?: string;
     lookup?: LookupFunction;
     postImages: PostImagesOption;
+    heartbeat_interval_seconds: number;
     connectionParams: MongoConnectionParams;
 }
 export declare const MongoConnectionConfig: t.Intersection<t.Codec<{
@@ -71,6 +72,10 @@ export declare const MongoConnectionConfig: t.Intersection<t.Codec<{
     reject_ip_ranges?: string[] | undefined;
 }, string, t.CodecProps>, t.ObjectCodec<{
     post_images: t.OptionalCodec<t.Codec<"off" | "auto_configure" | "read_only", "off" | "auto_configure" | "read_only", string, t.CodecProps>>;
+    /**
+     * Interval in seconds between source connection heartbeats. Null or omitted defaults to 60 seconds.
+     */
+    heartbeat_interval_seconds: t.OptionalCodec<t.Codec<number | null, number | null, string, t.CodecProps>>;
 }>>;
 /**
  * Config input specified when starting services

package/dist/types/types.js

@@ -1,4 +1,5 @@
 import * as lib_mongo from '@powersync/lib-service-mongodb/types';
+import { ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 import * as service_types from '@powersync/service-types';
 import * as t from 'ts-codec';
 export var PostImagesOption;
@@ -35,9 +36,16 @@ export var PostImagesOption;
      */
     PostImagesOption["READ_ONLY"] = "read_only";
 })(PostImagesOption || (PostImagesOption = {}));
+const DEFAULT_PING_INTERVAL_SECONDS = 60;
+const MIN_PING_INTERVAL_SECONDS = 5;
+const MAX_PING_INTERVAL_SECONDS = 60;
 export const MongoConnectionConfig = service_types.configFile.DataSourceConfig.and(lib_mongo.BaseMongoConfig).and(t.object({
     // Replication specific settings
-    post_images: t.literal('off').or(t.literal('auto_configure')).or(t.literal('read_only')).optional()
+    post_images: t.literal('off').or(t.literal('auto_configure')).or(t.literal('read_only')).optional(),
+    /**
+     * Interval in seconds between source connection heartbeats. Null or omitted defaults to 60 seconds.
+     */
+    heartbeat_interval_seconds: t.number.or(t.Null).optional()
 }));
 /**
  * Validate and normalize connection options.
@@ -50,7 +58,17 @@ export function normalizeConnectionConfig(options) {
         ...base,
         id: options.id ?? 'default',
         tag: options.tag ?? 'default',
-        postImages: options.post_images ?? PostImagesOption.OFF
+        postImages: options.post_images ?? PostImagesOption.OFF,
+        heartbeat_interval_seconds: normalizeHeartbeatInterval(options.heartbeat_interval_seconds)
     };
 }
+function normalizeHeartbeatInterval(value) {
+    if (value == null) {
+        return DEFAULT_PING_INTERVAL_SECONDS;
+    }
+    if (!Number.isFinite(value) || value < MIN_PING_INTERVAL_SECONDS || value > MAX_PING_INTERVAL_SECONDS) {
+        throw new ServiceError(ErrorCode.PSYNC_S1109, `MongoDB connection: heartbeat_interval_seconds must be between ${MIN_PING_INTERVAL_SECONDS} and ${MAX_PING_INTERVAL_SECONDS} seconds; null or omitted defaults to ${DEFAULT_PING_INTERVAL_SECONDS}`);
+    }
+    return value;
+}
 //# sourceMappingURL=types.js.map

package/dist/types/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAC;AAClE,OAAO,KAAK,aAAa,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,MAAM,CAAN,IAAY,gBAkCX;AAlCD,WAAY,gBAAgB;IAC1B;;;;;;;OAOG;IACH,+BAAW,CAAA;IAEX;;;;;;;OAOG;IACH,qDAAiC,CAAA;IAEjC;;;;;;;;;;;OAWG;IACH,2CAAuB,CAAA;AACzB,CAAC,EAlCW,gBAAgB,KAAhB,gBAAgB,QAkC3B;AAmBD,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,GAAG,CAC/G,CAAC,CAAC,MAAM,CAAC;IACP,gCAAgC;IAChC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE;CACpG,CAAC,CACH,CAAC;AAaF;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAqC;IAC7E,MAAM,IAAI,GAAG,SAAS,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAErD,OAAO;QACL,GAAG,IAAI;QACP,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS;QAC3B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,SAAS;QAC7B,UAAU,EAAG,OAAO,CAAC,WAA4C,IAAI,gBAAgB,CAAC,GAAG;KAC1F,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,aAAa,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAE9B,MAAM,CAAN,IAAY,gBAkCX;AAlCD,WAAY,gBAAgB;IAC1B;;;;;;;OAOG;IACH,+BAAW,CAAA;IAEX;;;;;;;OAOG;IACH,qDAAiC,CAAA;IAEjC;;;;;;;;;;;OAWG;IACH,2CAAuB,CAAA;AACzB,CAAC,EAlCW,gBAAgB,KAAhB,gBAAgB,QAkC3B;AAED,MAAM,6BAA6B,GAAG,EAAE,CAAC;AACzC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AACpC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAqBrC,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC,GAAG,CAC/G,CAAC,CAAC,MAAM,CAAC;IACP,gCAAgC;IAChC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnG;;OAEG;IACH,0BAA0B,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;CAC3D,CAAC,CACH,CAAC;AAaF;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAqC;IAC7E,MAAM,IAAI,GAAG,SAAS,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAErD,OAAO;QACL,GAAG,IAAI;QACP,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS;QAC3B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,SAAS;QAC7B,UAAU,EAAG,OAAO,CAAC,WAA4C,IAAI,gBAAgB,CAAC,GAAG;QACzF,0BAA0B,EAAE,0BAA0B,CAAC,OAAO,CAAC,0BAA0B,CAAC;KAC3F,CAAC;AACJ,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAgC;IAClE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,6BAA6B,CAAC;IACvC,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,yBAAyB,IAAI,KAAK,GAAG,yBAAyB,EAAE,CAAC;QACtG,MAAM,IAAI,YAAY,CACpB,SAAS,CAAC,WAAW,EACrB,kEAAkE,yBAAyB,QAAQ,yBAAyB,yCAAyC,6BAA6B,EAAE,CACrM,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@powersync/service-module-mongodb",
   "repository": "https://github.com/powersync-ja/powersync-service",
-  "version": "0.18.2",
+  "version": "0.20.0",
   "license": "FSL-1.1-ALv2",
   "type": "module",
   "publishConfig": {
@@ -15,17 +15,17 @@
     "bson": "^6.10.4",
     "ts-codec": "^1.3.0",
     "uuid": "^14.0.0",
-    "@powersync/lib-service-mongodb": "0.6.28",
-    "@powersync/lib-services-framework": "0.9.7",
-    "@powersync/service-core": "1.23.2",
+    "@powersync/lib-service-mongodb": "0.6.30",
+    "@powersync/lib-services-framework": "0.10.0",
+    "@powersync/service-core": "1.24.0",
     "@powersync/service-jsonbig": "0.17.13",
-    "@powersync/service-sync-rules": "0.38.1",
-    "@powersync/service-types": "0.16.1"
+    "@powersync/service-sync-rules": "0.40.0",
+    "@powersync/service-types": "0.17.0"
   },
   "devDependencies": {
-    "@powersync/service-core-tests": "0.17.1",
-    "@powersync/service-module-mongodb-storage": "0.18.2",
-    "@powersync/service-module-postgres-storage": "0.16.2"
+    "@powersync/service-core-tests": "0.18.0",
+    "@powersync/service-module-mongodb-storage": "0.19.0",
+    "@powersync/service-module-postgres-storage": "0.17.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/api/MongoRouteAPIAdapter.ts

@@ -4,11 +4,12 @@ import { api, ParseSyncConfigOptions, ReplicationHeadCallback } from '@powersync
 import * as sync_rules from '@powersync/service-sync-rules';
 import * as service_types from '@powersync/service-types';
 
-import { ServiceAssertionError } from '@powersync/lib-services-framework';
-import { MongoLSN } from '../common/MongoLSN.js';
+import { logger } from '@powersync/lib-services-framework';
+import { CheckpointImplementation } from '../replication/checkpoints/CheckpointImplementation.js';
+import { createCheckpointImplementation } from '../replication/checkpoints/create-checkpoint-implementation.js';
 import { MongoManager } from '../replication/MongoManager.js';
-import { constructAfterRecord, STANDALONE_CHECKPOINT_ID } from '../replication/MongoRelation.js';
-import { CHECKPOINTS_COLLECTION } from '../replication/replication-utils.js';
+import { constructAfterRecord } from '../replication/MongoRelation.js';
+import { CHECKPOINTS_COLLECTION, detectDocumentDb } from '../replication/replication-utils.js';
 import * as types from '../types/types.js';
 import { escapeRegExp } from '../utils.js';
 
@@ -19,6 +20,8 @@ export class MongoRouteAPIAdapter implements api.RouteAPI {
   connectionTag: string;
   defaultSchema: string;
 
+  private checkpointImplementation: CheckpointImplementation | null = null;
+
   constructor(protected config: types.ResolvedConnectionConfig) {
     const manager = new MongoManager(config);
     this.client = manager.client;
@@ -199,41 +202,27 @@ export class MongoRouteAPIAdapter implements api.RouteAPI {
   }
 
   async createReplicationHead<T>(callback: ReplicationHeadCallback<T>): Promise<T> {
-    const session = this.client.startSession();
-    try {
-      await this.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.
-      await this.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`);
-      }
+    const checkpointImplementation = await this.getCheckpointImplementation();
+    return checkpointImplementation.createReplicationHead(callback);
+  }
 
-      return r;
-    } finally {
-      await session.endSession();
+  private async getCheckpointImplementation(): Promise<CheckpointImplementation> {
+    if (this.checkpointImplementation == null) {
+      const isDocumentDb = await detectDocumentDb(this.db);
+      this.checkpointImplementation = createCheckpointImplementation(isDocumentDb, {
+        client: this.client,
+        db: this.db,
+        // The adapter never streams, so it has no real barrier document. This
+        // random id is only safe because the adapter only ever calls
+        // createReplicationHead, which produces a standalone (stream_id = null)
+        // head that every real ChangeStream observes. It must NOT be used for a
+        // batch barrier (createBatchCheckpoint stamps this id), or the head would
+        // become an own-barrier of a phantom stream that nothing resolves.
+        checkpointStreamId: new mongo.ObjectId(),
+        logger
+      });
     }
+    return this.checkpointImplementation;
   }
 
   async getConnectionSchema(): Promise<service_types.DatabaseSchema[]> {

package/src/common/SentinelLSN.ts

@@ -0,0 +1,78 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { storage } from '@powersync/service-core';
+
+export type SentinelLSNSpecification = {
+  sentinel: bigint;
+  /**
+   * Resume tokens are opaque on sentinel-based sources (e.g. DocumentDB). The
+   * sentinel component is the comparable position; this token is only used to
+   * resume the change stream.
+   */
+  resume_token?: mongo.ResumeToken | null;
+};
+
+const DELIMINATOR = '|';
+
+/**
+ * Width of the sentinel coordinate, matching a MongoDB cluster timestamp
+ * (64-bit → 16 hex chars). The sentinel counter is a 64-bit `Long`, so this is
+ * sufficient and never truncates.
+ */
+const SENTINEL_HEX_LENGTH = 16;
+
+/**
+ * LSN for sentinel-based checkpointing (sources without a usable clusterTime,
+ * e.g. DocumentDB). The ordered coordinate is a monotonic sentinel counter; the
+ * opaque resume token is carried alongside it only for `resumeAfter`.
+ *
+ * The coordinate is serialized as a 16-hex-char value with the **same shape as
+ * a MongoDB timestamp LSN** ({@link MongoLSN}): the high 32 bits resemble epoch
+ * seconds and the low 32 bits an increment. This is deliberate — it makes
+ * sentinel LSNs directly string-comparable with timestamp LSNs, so a sentinel
+ * coordinate (seeded at the current epoch seconds; see createSentinelCheckpointLsn)
+ * always sorts **above** any real-timestamp LSN issued in the past.
+ *
+ * It only *resembles* a timestamp. The value is a synthetic monotonic counter,
+ * not a real cluster time, and must never be used as one (e.g. it is never fed
+ * to `startAtOperationTime`; the sentinel implementation resumes purely via the
+ * resume token).
+ */
+export class SentinelLSN {
+  static ZERO = new SentinelLSN({ sentinel: 0n });
+
+  static fromSerialized(comparable: string): SentinelLSN {
+    const [sentinelString, resumeString] = comparable.split(DELIMINATOR);
+
+    return new SentinelLSN({
+      sentinel: BigInt(`0x${sentinelString}`),
+      resume_token: resumeString ? storage.deserializeBson(Buffer.from(resumeString, 'base64')).resumeToken : null
+    });
+  }
+
+  constructor(protected options: SentinelLSNSpecification) {}
+
+  get sentinel() {
+    return this.options.sentinel;
+  }
+
+  get resumeToken() {
+    return this.options.resume_token;
+  }
+
+  get comparable() {
+    // padStart(16) of the combined 64-bit value yields the identical string to
+    // MongoLSN's high(8)+low(8) formatting, keeping the two formats comparable.
+    const sentinel = this.sentinel.toString(16).padStart(SENTINEL_HEX_LENGTH, '0');
+    const segments = [sentinel];
+
+    if (this.resumeToken) {
+      segments.push(storage.serializeBson({ resumeToken: this.resumeToken }).toString('base64'));
+    }
+
+    return segments.join(DELIMINATOR);
+  }
+
+  toString() {
+    return this.comparable;
+  }
+}

package/src/module/MongoModule.ts

@@ -39,7 +39,8 @@ export class MongoModule extends replication.ReplicationModule<types.MongoConnec
       storageEngine: context.storageEngine,
       metricsEngine: context.metricsEngine,
       connectionFactory: connectionFactory,
-      rateLimiter: new MongoErrorRateLimiter()
+      rateLimiter: new MongoErrorRateLimiter(),
+      heartbeatIntervalSeconds: normalisedConfig.heartbeat_interval_seconds
     });
   }