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

package/test/src/checkpoint_retry.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+
+import { mongo } from '@powersync/lib-service-mongodb';
+
+import { MongoLSN } from '@module/common/MongoLSN.js';
+import { createCheckpoint } from '@module/replication/MongoRelation.js';
+import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
+import { clearTestDb, connectMongoData, requireFailCommand } from './util.js';
+
+// This suite uses configureFailPoint to force retry timing. Azure DocumentDB
+// does not support configureFailPoint.
+describe.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('checkpoint retryable writes', () => {
+  test('returns the persisted checkpoint clusterTime after a retryable write', { repeats: 1 }, async (ctx) => {
+    // This test relies on very specific timing:
+    //
+    // 1. _powersync_checkpoints findAndModify command starts and is sent to the server
+    // 2. command is written to the server
+    // 3. _powersync_checkpoints findAndModify command fails with a retryable error (e.g. connection timeout)
+    // 4. command is retried
+    // 5. another write lands on the server, increasing the server's operationTime
+    // 6. command succeeds with a new operationTime, but without actually writing again (server de-duplicates based on transaction id)
+    //
+    // It is quite difficult to simulate this, even with failCommand. We currently rely on triggering a socket timeout for the first command,
+    // with another write happening right after that.
+
+    const TIMEOUT = 200;
+    const INSERT_COUNT = 5;
+
+    const { db, client } = await connectMongoData({
+      monitorCommands: true,
+      socketTimeoutMS: TIMEOUT,
+      maxPoolSize: 1
+    });
+
+    await using _client = { [Symbol.asyncDispose]: async () => await client.close() };
+    await client.connect();
+    await using failCommand = await requireFailCommand(client, ctx);
+
+    await clearTestDb(db);
+
+    const checkpointId = new mongo.ObjectId();
+    const advanceClusterTime = db.collection('_advance_cluster_time');
+
+    const changeStream = db.watch([], { maxAwaitTimeMS: TIMEOUT * 0.8 });
+    await using _changeStream = { [Symbol.asyncDispose]: async () => await changeStream.close() };
+
+    const checkpointEventPromise = waitForCheckpointEvent(changeStream, checkpointId, INSERT_COUNT).catch((e) =>
+      console.error(e)
+    );
+
+    const commandsStarted: mongo.CommandStartedEvent[] = [];
+
+    client.on('commandStarted', (event) => {
+      commandsStarted.push(event);
+    });
+
+    const DEBUG_COMMANDS = false;
+    if (DEBUG_COMMANDS) {
+      // For debugging: Log all commands
+      client.on('commandStarted', (event) => {
+        console.log('commandStarted:', event);
+      });
+
+      client.on('commandSucceeded', (event) => {
+        console.log('commandSucceeded:', event);
+      });
+
+      client.on('commandFailed', (event) => {
+        console.log('commandFailed:', event);
+      });
+    }
+
+    await failCommand.configure({
+      mode: { times: 1 },
+      data: {
+        failCommands: ['commitTransaction', 'findAndModify'],
+        blockConnection: true,
+        blockTimeMS: TIMEOUT
+      }
+    });
+    const returnedLsnPromise = createCheckpoint(db, checkpointId);
+
+    for (let i = 0; i < INSERT_COUNT; i++) {
+      await advanceClusterTime.insertOne({ at: new Date() });
+    }
+
+    const returnedLsn = await returnedLsnPromise;
+    const checkpointEvent = await checkpointEventPromise;
+    if (checkpointEvent == null) {
+      throw new Error('change stream failed');
+    }
+
+    const eventLsn = new MongoLSN({
+      timestamp: checkpointEvent.clusterTime!,
+      resume_token: checkpointEvent._id
+    }).comparable;
+
+    if (DEBUG_COMMANDS) {
+      const commands = commandsStarted
+        .filter((c) => ['findAndModify', 'insert'].includes(c.commandName))
+        .map((c) => c.commandName);
+      // In the failure case, we had findAndModify, insert, findAndModify, potentially with more inserts in between.
+      // With updated behavior, we only have a single findAndModify.
+      console.log('Command order:', commands);
+    }
+
+    expect(eventLsn >= returnedLsn).toBe(true);
+    expect(checkpointEvent.clusterTime).toEqual(MongoLSN.fromSerialized(returnedLsn).timestamp);
+  });
+});
+
+async function waitForCheckpointEvent(
+  changeStream: mongo.ChangeStream,
+  checkpointId: mongo.ObjectId,
+  insertCount: number
+): Promise<mongo.ChangeStreamDocument | null> {
+  let lastEvent: mongo.ChangeStreamDocument | null = null;
+  let seenInserts = 0;
+  for await (const event of changeStream) {
+    if (
+      (event.operationType == 'insert' || event.operationType == 'update' || event.operationType == 'replace') &&
+      checkpointId.equals(event.documentKey._id)
+    ) {
+      lastEvent = event;
+    } else if (event.operationType == 'insert' && event.ns.coll === '_advance_cluster_time') {
+      seenInserts++;
+      if (seenInserts >= insertCount) {
+        // We finish when we hit the expected number of inserts, since the number of checkpoint events are unknown.
+        break;
+      }
+    }
+  }
+  return lastEvent;
+}

package/test/src/documentdb_helpers.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from 'vitest';
+
+import { SentinelLSN } from '@module/common/SentinelLSN.js';
+import { getEventTimestamp } from '@module/replication/checkpoints/CheckpointImplementation.js';
+import { createSentinelCheckpointLsn, SENTINEL_CHECKPOINT_ID } from '@module/replication/MongoRelation.js';
+import { CHECKPOINTS_COLLECTION } from '@module/replication/replication-utils.js';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { connectMongoData } from './util.js';
+
+describe('DocumentDB helpers', () => {
+  describe('getEventTimestamp', () => {
+    // getEventTimestamp is used by the timestamp checkpoint implementation (standard
+    // MongoDB): it prefers clusterTime and falls back to second-precision wallTime.
+    // The DocumentDB sentinel implementation does not use it — DocumentDB LSNs are
+    // sentinel-counter based, not timestamp based.
+
+    test('returns clusterTime when present', () => {
+      const clusterTime = mongo.Timestamp.fromBits(1, 1700000000);
+      const event = { clusterTime, wallTime: new Date('2024-01-01T00:00:00Z') } as any;
+      expect(getEventTimestamp(event)).toEqual(clusterTime);
+    });
+
+    test('falls back to second-precision wallTime when clusterTime is absent', () => {
+      const wallTime = new Date('2024-06-15T12:00:00.789Z');
+      const result = getEventTimestamp({ wallTime } as any);
+      expect(result.getHighBitsUnsigned()).toEqual(Math.floor(wallTime.getTime() / 1000));
+      // Increment is always 0 — wallTime only has second resolution in this conversion.
+      expect(result.getLowBitsUnsigned()).toEqual(0);
+    });
+
+    test('throws when neither clusterTime nor wallTime is present', () => {
+      expect(() => getEventTimestamp({} as any)).toThrow();
+    });
+  });
+
+  describe('DocumentDB detection', () => {
+    // Detection logic: hello.internal?.documentdb_versions != null
+    const isDocumentDb = (hello: any) => hello.internal?.documentdb_versions != null;
+
+    test('hello with documentdb_versions — detected as DocumentDB', () => {
+      const hello = {
+        isWritablePrimary: true,
+        msg: 'isdbgrid',
+        internal: {
+          documentdb_versions: ['1.111-0', '1.112.0', '12.1-1']
+        }
+      };
+      expect(isDocumentDb(hello)).toBe(true);
+    });
+
+    test('standard hello response — not DocumentDB', () => {
+      const hello = {
+        isWritablePrimary: true,
+        setName: 'rs0',
+        hosts: ['localhost:27017']
+      };
+      expect(isDocumentDb(hello)).toBe(false);
+    });
+  });
+
+  describe('sentinel checkpoint format', () => {
+    test('sentinel counter is seeded at a timestamp value on creation', { timeout: 30_000 }, async () => {
+      // If a consumer deletes the sentinel checkpoint document in their
+      // source database, the re-created counter must not restart below
+      // already-committed LSNs. createSentinelCheckpointLsn seeds new counters at
+      // the current epoch seconds shifted into the high 32 bits (resembling a
+      // MongoDB timestamp), so the coordinate jumps forward instead of resetting.
+      const { client, db: sharedDb } = await connectMongoData();
+      // Use an isolated database: other test files run in parallel against the
+      // shared test database and both bump and clear the sentinel checkpoint
+      // document, which would make these exact assertions racy.
+      const db = client.db(`${sharedDb.databaseName}_seed_test`);
+      const seed = (epochMs: number) => (BigInt(Math.floor(epochMs / 1000)) << 32n) + 1n;
+      try {
+        const before = Date.now();
+        const first = SentinelLSN.fromSerialized(await createSentinelCheckpointLsn(client, db));
+        const after = Date.now();
+
+        // Seeded at (epoch_seconds << 32) + 1, not at 1.
+        expect(first.sentinel).toBeGreaterThanOrEqual(seed(before));
+        expect(first.sentinel).toBeLessThanOrEqual(seed(after));
+
+        // Subsequent calls increment normally.
+        const second = SentinelLSN.fromSerialized(await createSentinelCheckpointLsn(client, db));
+        expect(second.sentinel).toEqual(first.sentinel + 1n);
+
+        // Simulate a consumer deleting the document after the counter has
+        // accumulated increments: the re-created counter resumes ahead. The seed
+        // has second granularity, and in production the document lives from
+        // initial sync onward, so re-creation always lands in a later second;
+        // wait for the clock to advance to reproduce that here.
+        await new Promise((resolve) => setTimeout(resolve, 1_100));
+        await db.collection(CHECKPOINTS_COLLECTION).deleteOne({ _id: SENTINEL_CHECKPOINT_ID as any });
+        const recreated = SentinelLSN.fromSerialized(await createSentinelCheckpointLsn(client, db));
+        expect(recreated.sentinel).toBeGreaterThan(second.sentinel);
+      } finally {
+        await db.dropDatabase().catch(() => {});
+        await client.close();
+      }
+    });
+
+    test('createSentinelCheckpointLsn stamps stream_id on the sentinel document', async () => {
+      // A batch barrier passes the stream's checkpointStreamId, which is stamped
+      // on the shared sentinel document so the stream can recognise its own
+      // barriers (and ignore other streams') by content.
+      const { client, db } = await connectMongoData();
+      try {
+        const barrierId = new mongo.ObjectId();
+        await createSentinelCheckpointLsn(client, db, barrierId);
+
+        const doc = await db.collection(CHECKPOINTS_COLLECTION).findOne({ _id: SENTINEL_CHECKPOINT_ID as any });
+        expect(barrierId.equals(doc!.stream_id)).true;
+      } finally {
+        await client.close();
+      }
+    });
+  });
+
+  // Note: the DocumentDB keepalive does not build an LSN from Date.now() — it bumps
+  // the shared sentinel via createSentinelCheckpointLsn and commits when the bump's
+  // own event is observed. The only Date.now()-derived value is the sentinel
+  // counter seed, which is covered by the 'sentinel counter is seeded at a
+  // timestamp value on creation' test above.
+});