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

package/test/src/change_stream.test.ts

@@ -8,7 +8,7 @@ import { test_utils } from '@powersync/service-core-tests';
 
 import { MongoRouteAPIAdapter } from '@module/api/MongoRouteAPIAdapter.js';
 import { PostImagesOption } from '@module/types/types.js';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
 import { testTimeout } from './test-timeouts.js';
 import { describeWithStorage, StorageVersionTestContext, TEST_CONNECTION_OPTIONS } from './util.js';
@@ -27,8 +27,8 @@ describe('change stream', () => {
 function defineChangeStreamTests({ factory, storageVersion }: StorageVersionTestContext) {
   const supportsConcurrentSnapshots = storageVersion >= 3;
 
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factory, { ...options, storageVersion });
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factory, { ...options, storageVersion });
   };
   // DocumentDB does not support changeStreamPreAndPostImages, which this test requires via postImages: READ_ONLY.
   test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)('replicating basic values', async () => {
@@ -622,6 +622,79 @@ bucket_definitions:
     expect(data).toMatchObject([test_utils.putOp('test_data', { id: test_id, description: 'test1' })]);
   });
 
+  test.runIf(storageVersion >= 3)(
+    'does not resnapshot an unchanged event definition during incremental reprocessing',
+    async (testContext) => {
+      const eventDefinition = `
+event_definitions:
+  checkpoint_requests:
+    payloads:
+      - SELECT user_id, checkpoint, client_id, CASE WHEN checkpoint_requested_at IS NULL THEN true ELSE false END AS is_legacy FROM checkpoints
+`;
+      const syncConfig = (deploymentComment: string) => `
+config:
+  edition: 3
+  storage_version: 3
+  # ${deploymentComment}
+
+${eventDefinition}
+streams:
+  global:
+    auto_subscribe: true
+    queries:
+      - SELECT *, _id AS id FROM lists
+      - SELECT *, _id AS id FROM todos
+`;
+
+      let replicationStreamId: number;
+      {
+        await using context = await openContext();
+        const firstStorage = await context.updateSyncRules(syncConfig('initial deployment'));
+        if (
+          !('incrementalReprocessing' in firstStorage.storageConfig) ||
+          firstStorage.storageConfig.incrementalReprocessing !== true
+        ) {
+          testContext.skip('storage does not support incremental reprocessing');
+        }
+
+        const { db } = context;
+        await db.collection('lists').insertOne({ name: 'list' });
+        await db.collection('todos').insertOne({ description: 'todo' });
+        await db.collection('checkpoints').insertOne({
+          user_id: 'user-1',
+          checkpoint: 1n,
+          client_id: 'client-1',
+          checkpoint_requested_at: null
+        });
+
+        replicationStreamId = firstStorage.replicationStreamId;
+        await context.replicateSnapshot();
+        context.startStreaming();
+        await context.getCheckpoint();
+      }
+
+      const resnapshottedCollections: string[] = [];
+      await using context = await openContext({
+        doNotClear: true,
+        streamOptions: {
+          snapshotHooks: {
+            beforeSnapshotStarted: async (table) => {
+              resnapshottedCollections.push(table.name);
+            }
+          }
+        }
+      });
+
+      const processingStorage = await context.updateSyncRules(syncConfig('redeployed without behavioral changes'));
+      expect(processingStorage.replicationStreamId).toBe(replicationStreamId);
+      expect(await context.factory.getDeployingSyncConfig()).not.toBeNull();
+
+      await context.replicateSnapshot();
+
+      expect(resnapshottedCollections).toEqual([]);
+    }
+  );
+
   test('coalesces standalone checkpoints when backlog is buffered', async () => {
     await using context = await openContext();
     await context.updateSyncRules(BASIC_SYNC_RULES);

package/test/src/change_stream_test_setup.ts

@@ -0,0 +1,38 @@
+import { test_utils } from '@module/index.js';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { TestStorageFactory } from '@powersync/service-core';
+import { METRICS_HELPER } from '@powersync/service-core-tests';
+import { TEST_CONNECTION_OPTIONS } from './util.js';
+
+export const ChangeStreamTestContext = test_utils.ChangeStreamTestContext;
+
+/**
+ * Supply this suite's environment and metrics to the exported context.
+ */
+export function openChangeStreamTestContext(
+  factory: TestStorageFactory,
+  options?: Omit<test_utils.ChangeStreamTestContextOptions, 'factory' | 'connectionOptions' | 'metrics'> & {
+    mongoOptions?: Partial<test_utils.ChangeStreamTestContextOptions['connectionOptions']>;
+  }
+) {
+  return ChangeStreamTestContext.open({
+    ...options,
+    factory,
+    connectionOptions: { ...TEST_CONNECTION_OPTIONS, ...options?.mongoOptions },
+    metrics: METRICS_HELPER.metricsEngine
+  });
+}
+
+export async function setSnapshotHistorySeconds(client: mongo.MongoClient, seconds: number) {
+  const { minSnapshotHistoryWindowInSeconds: currentValue } = await client
+    .db('admin')
+    .command({ getParameter: 1, minSnapshotHistoryWindowInSeconds: 1 });
+
+  await client.db('admin').command({ setParameter: 1, minSnapshotHistoryWindowInSeconds: seconds });
+
+  return {
+    async [Symbol.asyncDispose]() {
+      await client.db('admin').command({ setParameter: 1, minSnapshotHistoryWindowInSeconds: currentValue });
+    }
+  };
+}

package/test/src/chunked_snapshot.test.ts

@@ -5,7 +5,7 @@ import { JSONBig } from '@powersync/service-jsonbig';
 import { SqliteJsonValue } from '@powersync/service-sync-rules';
 import * as timers from 'timers/promises';
 import { describe, expect, test } from 'vitest';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { describeWithStorage, StorageVersionTestContext } from './util.js';
 
 describe('chunked snapshots', () => {
@@ -13,8 +13,8 @@ describe('chunked snapshots', () => {
 });
 
 function defineBatchTests({ factory, storageVersion }: StorageVersionTestContext) {
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factory, { ...options, storageVersion });
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factory, { ...options, storageVersion });
   };
 
   // This is not as sensitive to the id type as postgres, but we still test a couple of cases

package/test/src/config.test.ts

@@ -0,0 +1,34 @@
+import { normalizeConnectionConfig } from '@module/types/types.js';
+import { describe, expect, test } from 'vitest';
+
+const BASE_CONFIG = {
+  type: 'mongodb' as const,
+  uri: 'mongodb://localhost:27017/powersync_test'
+};
+
+describe('MongoDB connection config', () => {
+  test('defaults heartbeat_interval_seconds to 60 seconds', () => {
+    expect(normalizeConnectionConfig(BASE_CONFIG).heartbeat_interval_seconds).toBe(60);
+  });
+
+  test('defaults a null heartbeat_interval_seconds to 60 seconds', () => {
+    expect(
+      normalizeConnectionConfig({ ...BASE_CONFIG, heartbeat_interval_seconds: null }).heartbeat_interval_seconds
+    ).toBe(60);
+  });
+
+  test('allows the MongoDB maximum heartbeat interval', () => {
+    expect(
+      normalizeConnectionConfig({ ...BASE_CONFIG, heartbeat_interval_seconds: 60 }).heartbeat_interval_seconds
+    ).toBe(60);
+  });
+
+  test.each([0, 4, 61, Number.NaN, Number.POSITIVE_INFINITY])(
+    'rejects invalid heartbeat_interval_seconds: %s',
+    (heartbeat_interval_seconds) => {
+      expect(() => normalizeConnectionConfig({ ...BASE_CONFIG, heartbeat_interval_seconds })).toThrow(
+        'heartbeat_interval_seconds'
+      );
+    }
+  );
+});

package/test/src/documentdb_mode.test.ts

@@ -9,7 +9,7 @@ import { SentinelLSN } from '@module/common/SentinelLSN.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 { ChangeStreamTestContext } from './change_stream_utils.js';
+import { openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
 import { env } from './env.js';
 import { testTimeout } from './test-timeouts.js';
@@ -584,8 +584,8 @@ describe.skipIf(DATABASE_TYPE != DatabaseType.DOCUMENTDB)('documentDbMode', () =
 });
 
 function defineDocumentDBDbModeTests({ factory, storageVersion }: StorageVersionTestContext) {
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factory, {
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factory, {
       ...options,
       storageVersion,
       streamOptions: {
@@ -759,8 +759,7 @@ bucket_definitions:
     expect(JSON.parse(lastOp.data as string)).toMatchObject({ description: 'after_keepalive' });
   });
 
-  // Skipped until Azure DocumentDB ships the server-side getMore maxAwaitTimeMS fix.
-  test.skip('respects maxAwaitTimeMS for idle getMore calls in documentDbMode', async () => {
+  test('respects maxAwaitTimeMS for idle getMore calls in documentDbMode', async () => {
     const maxAwaitTimeMS = 2_000;
 
     await using context = await openContext({

package/test/src/raw_change_stream.test.ts

@@ -5,7 +5,6 @@ import { getCursorBatchBytes } from '@module/replication/replication-index.js';
 import { mongo } from '@powersync/lib-service-mongodb';
 import { bson } from '@powersync/service-core';
 import { DATABASE_TYPE, DatabaseType } from './DatabaseType.js';
-import { testTimeout } from './test-timeouts.js';
 import { clearTestDb, connectMongoData, requireFailCommand } from './util.js';
 
 // DocumentDB only supports cluster-level change streams — collection- and
@@ -102,68 +101,6 @@ describe('internal mongodb utils', () => {
     }
   );
 
-  test(
-    'keeps getMore maxTimeMS when client-side maxAwaitTimeMS is enabled',
-    { timeout: testTimeout(30_000, { cloudOverride: 150_000 }) },
-    async () => {
-      const { db, client } = await connectMongoData({ monitorCommands: true });
-      await using _ = { [Symbol.asyncDispose]: async () => await client.close() };
-      await clearTestDb(db);
-      const collection = db.collection('test_data');
-      // Keep the local Mongo path fast, but give Azure DocumentDB enough time
-      // for slow cloud change-stream delivery when maxTimeMS is sent to getMore.
-      const maxAwaitTimeMS = testTimeout(50, { cloudOverride: 10_000 });
-
-      const started: any[] = [];
-      client.on('commandStarted', (event) => {
-        if (event.commandName == 'aggregate' || event.commandName == 'getMore') {
-          started.push(event);
-        }
-      });
-
-      const stream = rawChangeStream(
-        DATABASE_TYPE == DatabaseType.DOCUMENTDB ? client.db('admin') : db,
-        [
-          {
-            $changeStream: {
-              fullDocument: 'updateLookup',
-              ...(DATABASE_TYPE == DatabaseType.DOCUMENTDB ? { allChangesForCluster: true } : {})
-            }
-          },
-          ...(DATABASE_TYPE == DatabaseType.DOCUMENTDB
-            ? [
-                {
-                  $match: {
-                    'ns.db': db.databaseName,
-                    'ns.coll': collection.collectionName
-                  }
-                }
-              ]
-            : [])
-        ],
-        {
-          batchSize: 10,
-          maxAwaitTimeMS,
-          clientSideMaxAwaitTimeMS: true,
-          maxTimeMS: 1_000
-        }
-      );
-
-      await stream.next();
-      await collection.insertOne({ test: 1 });
-      const nextBatch = await readUntilNonEmptyBatch(stream);
-      await stream.return?.();
-
-      expect(nextBatch.events).toHaveLength(1);
-
-      const aggregate = started.find((event) => event.commandName == 'aggregate');
-      const getMore = started.find((event) => event.commandName == 'getMore');
-
-      expect(aggregate?.command.maxTimeMS).toEqual(1_000);
-      expect(getMore?.command.maxTimeMS).toEqual(maxAwaitTimeMS);
-    }
-  );
-
   // This test uses configureFailPoint to inject a getMore timeout. Azure
   // DocumentDB does not support configureFailPoint.
   test.skipIf(DATABASE_TYPE == DatabaseType.DOCUMENTDB)(

package/test/src/replication_stream.test.ts

@@ -0,0 +1,311 @@
+import { ChangeStreamInvalidatedError } from '@module/replication/ChangeStream.js';
+import { DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER } from '@module/replication/MongoReplicationQueryProvider.js';
+import { openMongoReplicationStream, readMongoReplicationStream } from '@module/replication/MongoReplicationStream.js';
+import { ChangeStreamBatch, mapChangeStreamError } from '@module/replication/RawChangeStream.js';
+import { mongo } from '@powersync/lib-service-mongodb';
+import { DatabaseConnectionError } from '@powersync/lib-services-framework';
+import { describe, expect, test, vi } from 'vitest';
+import { env } from './env.js';
+
+/**
+ * Exercise cursor construction and stream decoding without contacting MongoDB. Cursor tests intercept
+ * the driver's command method; reader tests supply BSON batches with explicit events and resume tokens.
+ */
+describe('MongoDB replication stream reader', () => {
+  test.each(['pre', 'post'])('invalidates replication when a required %s-image is missing', (image) => {
+    const error = new mongo.MongoServerError({
+      code: 47,
+      codeName: 'NoMatchingDocument',
+      errmsg: `Change stream was configured to require a ${image}-image, but the ${image}-image was not found for event: example`
+    });
+
+    // Invalidated streams trigger a fresh snapshot instead of retrying an unrecoverable position.
+    expect(() => mapChangeStreamError(error)).toThrow(ChangeStreamInvalidatedError);
+  });
+
+  test('does not invalidate replication for unrelated NoMatchingDocument errors', () => {
+    const error = new mongo.MongoServerError({
+      code: 47,
+      codeName: 'NoMatchingDocument',
+      errmsg: 'No matching document found'
+    });
+
+    expect(() => mapChangeStreamError(error)).toThrow(DatabaseConnectionError);
+  });
+
+  test.each([
+    { isDocumentDb: false, multipleDatabases: false, usePostImages: false },
+    { isDocumentDb: false, multipleDatabases: false, usePostImages: true },
+    { isDocumentDb: false, multipleDatabases: true, usePostImages: true },
+    { isDocumentDb: true, multipleDatabases: false, usePostImages: true }
+  ])('preserves the base cursor options for %j', async ({ isDocumentDb, multipleDatabases, usePostImages }) => {
+    const client = new mongo.MongoClient(env.MONGO_TEST_DATA_URL);
+    await using clientDisposer = { [Symbol.asyncDispose]: () => client.close() };
+    const db = client.db('app');
+    const resumeAfter = { _data: 'exact-position' };
+    // Observe the real cursor-opening path, stopping before any network operation. An exact token must
+    // take precedence even if the stored position also contains its transaction's shared timestamp.
+    const command = vi.spyOn(mongo.Db.prototype, 'command').mockRejectedValue(new Error('observed command'));
+    try {
+      await expect(
+        collect(
+          openMongoReplicationStream({
+            db,
+            queryProvider: DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+            namespaceFilter: { $match: { 'ns.coll': 'documents' }, multipleDatabases },
+            isDocumentDb,
+            usePostImages,
+            position: { resumeAfter, startAfter: new mongo.Timestamp({ t: 10, i: 1 }) },
+            skipInitialTimestamp: true,
+            options: { batchSize: 50, maxAwaitTimeMS: 200, maxTimeMS: 1000 }
+          })
+        )
+      ).rejects.toThrow('observed command');
+      expect(command).toHaveBeenCalledOnce();
+      expect((command.mock.contexts[0] as mongo.Db).databaseName).toBe(
+        isDocumentDb || multipleDatabases ? 'admin' : 'app'
+      );
+      expect(command.mock.calls[0][0]).toEqual({
+        aggregate: 1,
+        pipeline: [
+          {
+            $changeStream: {
+              fullDocument: !isDocumentDb && usePostImages ? 'required' : 'updateLookup',
+              ...(!isDocumentDb ? { showExpandedEvents: true } : {}),
+              ...(isDocumentDb || multipleDatabases ? { allChangesForCluster: true } : {}),
+              resumeAfter
+            }
+          },
+          { $match: { 'ns.coll': 'documents' } },
+          ...(!isDocumentDb ? [{ $changeStreamSplitLargeEvent: {} }] : [])
+        ],
+        cursor: { batchSize: 1 },
+        maxTimeMS: 1000
+      });
+    } finally {
+      command.mockRestore();
+    }
+  });
+
+  test('opens adapter stages after namespace selection, with pre-images and the shared resume settings', async () => {
+    // A provider requests pre-images and adds a stage. The shared opener must still supply the source
+    // position and post-image settings, and run the provider stage before large events are split.
+    const client = new mongo.MongoClient(env.MONGO_TEST_DATA_URL);
+    await using clientDisposer = { [Symbol.asyncDispose]: () => client.close() };
+    const command = vi.spyOn(mongo.Db.prototype, 'command').mockRejectedValue(new Error('observed command'));
+    const timestamp = new mongo.Timestamp({ t: 10, i: 1 });
+    try {
+      await expect(
+        collect(
+          openMongoReplicationStream({
+            db: client.db('app'),
+            queryProvider: {
+              ...DEFAULT_MONGO_REPLICATION_QUERY_PROVIDER,
+              openChangeStream: ({ open }) =>
+                open({
+                  pipelineStages: [{ $set: { marker: 'keep' } }],
+                  imageOptions: { fullDocumentBeforeChange: 'whenAvailable' }
+                })
+            },
+            namespaceFilter: { $match: { 'ns.coll': 'documents' }, multipleDatabases: false },
+            isDocumentDb: false,
+            usePostImages: true,
+            position: { startAfter: timestamp },
+            options: { batchSize: 50, maxAwaitTimeMS: 200, maxTimeMS: 1000 }
+          })
+        )
+      ).rejects.toThrow('observed command');
+      expect(command.mock.calls[0][0].pipeline).toEqual([
+        {
+          $changeStream: {
+            fullDocumentBeforeChange: 'whenAvailable',
+            fullDocument: 'required',
+            showExpandedEvents: true,
+            startAtOperationTime: timestamp
+          }
+        },
+        { $match: { 'ns.coll': 'documents' } },
+        { $set: { marker: 'keep' } },
+        { $changeStreamSplitLargeEvent: {} }
+      ]);
+    } finally {
+      command.mockRestore();
+    }
+  });
+
+  test('keeps raw rows, buffered checkpoint information and idle progress', async () => {
+    // Two changes arrive together, followed by an empty response. Preserve raw BSON document bodies
+    // and indicate whether another change is buffered, while exposing a resume boundary for each batch.
+    const onBatch = vi.fn();
+    const batches = [batch([event('first'), event('second')], 'data'), batch([], 'idle')];
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from(batches),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        onBatch
+      })
+    );
+    expect(items.map((item) => item.type)).toEqual(['change', 'change', 'progress', 'progress']);
+    expect(items[0]).toMatchObject({ type: 'change', hasBufferedChanges: true });
+    expect(items[1]).toMatchObject({ type: 'change', hasBufferedChanges: false });
+    if (items[0].type != 'change' || !('fullDocument' in items[0].event)) throw new Error('Expected a row');
+    expect(Buffer.isBuffer(items[0].event.fullDocument)).toBe(true);
+    expect(mongo.BSON.deserialize(items[0].event.fullDocument!)).toEqual({ _id: 'first', body: 'raw row' });
+    expect(items.slice(2)).toEqual([
+      { type: 'progress', resumeToken: { _data: 'data' }, filteredCount: 0 },
+      { type: 'progress', resumeToken: { _data: 'idle' }, filteredCount: 0 }
+    ]);
+    expect(onBatch.mock.calls.map(([value]) => value)).toEqual(batches);
+  });
+
+  test('withholds progress across split batches, including an idle response between fragments', async () => {
+    // A large event spans two nonempty batches with an idle response between them. Saving either
+    // intermediate token would lose the in-memory first fragment if replication restarted there.
+    const original = event('large');
+    const first = { ...original, fullDocument: undefined, splitEvent: { fragment: 1, of: 2 } };
+    const last = {
+      _id: { _data: 'fragment-2' },
+      fullDocument: original.fullDocument,
+      splitEvent: { fragment: 2, of: 2 }
+    };
+    const onBatch = vi.fn();
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from([
+          batch([event('before'), first], 'unsafe'),
+          batch([], 'still-unsafe'),
+          batch([last, event('after')], 'safe')
+        ]),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        onBatch
+      })
+    );
+    // A consumer must never save either partial token, even though all three transport batches are counted.
+    expect(items.map((item) => item.type)).toEqual(['change', 'change', 'change', 'progress']);
+    expect(items[1]).toMatchObject({
+      type: 'change',
+      event: { documentKey: { _id: 'large' }, _id: { _data: 'fragment-2' } }
+    });
+    expect(items[3]).toEqual({ type: 'progress', resumeToken: { _data: 'safe' }, filteredCount: 0 });
+    expect(onBatch).toHaveBeenCalledTimes(3);
+  });
+
+  test.each([
+    // The first fragment is missing.
+    [{ ...event('broken'), splitEvent: { fragment: 2, of: 2 } }],
+    // A fragment in the middle is missing.
+    [
+      { ...event('broken'), splitEvent: { fragment: 1, of: 3 } },
+      { _id: { _data: 'bad' }, splitEvent: { fragment: 3, of: 3 } }
+    ],
+    // An ordinary event interrupts reassembly.
+    [{ ...event('broken'), splitEvent: { fragment: 1, of: 2 } }, event('unrelated')],
+    // The source iterator ends before the final fragment arrives.
+    [{ ...event('broken'), splitEvent: { fragment: 1, of: 2 } }]
+  ])('fails closed on incomplete or out-of-order fragments %#', async (...events) => {
+    // Invalid fragment sequences must reject consumption and close the upstream iterator so a caller
+    // cannot mistake a partial document for a complete change or continue from its batch token.
+    const closed = vi.fn();
+    const stream = readMongoReplicationStream({
+      batches: from([batch(events, 'unsafe')], closed),
+      defaultSchema: 'app',
+      multipleDatabases: false
+    });
+    await expect(collect(stream)).rejects.toThrow('splitEvent');
+    expect(closed).toHaveBeenCalledOnce();
+  });
+
+  test.each(['return', 'abort'] as const)(
+    'closes the upstream iterator on %s without acknowledging unread work',
+    async (end) => {
+      // Stop after the first change while another remains in the same batch. Both consumer return
+      // and signal cancellation must run upstream cleanup before the batch's progress is yielded.
+      const closed = vi.fn();
+      const controller = new AbortController();
+      const stream = readMongoReplicationStream({
+        batches: from([batch([event('first'), event('unread')], 'unsafe')], closed),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        signal: controller.signal
+      });
+      expect((await stream.next()).value).toMatchObject({ type: 'change' });
+      if (end == 'return') await stream.return(undefined);
+      else {
+        controller.abort(new Error('cancelled'));
+        await expect(stream.next()).rejects.toThrow('cancelled');
+      }
+      expect(closed).toHaveBeenCalledOnce();
+    }
+  );
+
+  test('normalizes Atlas Flex namespaces and deduplicates legacy positions before adapter evaluation', async () => {
+    // Legacy positions contain only a timestamp, so an event at that timestamp is already covered.
+    // The remaining event uses an Atlas Flex database prefix that must be removed before delivery.
+    const timestamp = new mongo.Timestamp({ t: 10, i: 1 });
+    const items = await collect(
+      readMongoReplicationStream({
+        batches: from([
+          batch(
+            [
+              { ...event('old'), clusterTime: timestamp },
+              { ...event('new'), ns: { db: 'prefix_app', coll: 'documents' } }
+            ],
+            'safe'
+          )
+        ]),
+        defaultSchema: 'app',
+        multipleDatabases: false,
+        startAfter: timestamp
+      })
+    );
+    expect(items).toHaveLength(2);
+    expect(items[0]).toMatchObject({
+      type: 'change',
+      event: { ns: { db: 'app', coll: 'documents' }, documentKey: { _id: 'new' } }
+    });
+  });
+});
+
+/**
+ * Minimal insert event for the app.documents fixture namespace; callers override fields for each scenario.
+ */
+function event(id: string): mongo.Document {
+  return {
+    _id: { _data: id },
+    operationType: 'insert',
+    ns: { db: 'app', coll: 'documents' },
+    documentKey: { _id: id },
+    fullDocument: { _id: id, body: 'raw row' }
+  };
+}
+
+/**
+ * Encode events as raw BSON, matching the reader's transport input. Tokens are opaque test labels;
+ * the fixed byte count supports batch accounting assertions without depending on BSON payload size.
+ */
+function batch(events: mongo.Document[], token: string): ChangeStreamBatch {
+  return {
+    events: events.map((event) => Buffer.from(mongo.BSON.serialize(event))),
+    resumeToken: { _data: token },
+    byteSize: 1234
+  };
+}
+
+/**
+ * Supply deterministic source batches and expose iterator cleanup to cancellation and failure tests.
+ */
+async function* from<T>(values: T[], closed?: () => void) {
+  try {
+    yield* values;
+  } finally {
+    closed?.();
+  }
+}
+
+async function collect<T>(stream: AsyncIterable<T>): Promise<T[]> {
+  const items: T[] = [];
+  for await (const item of stream) items.push(item);
+  return items;
+}

package/test/src/resume.test.ts

@@ -1,8 +1,9 @@
 import { ChangeStreamInvalidatedError } from '@module/replication/ChangeStream.js';
 import { MongoManager } from '@module/replication/MongoManager.js';
 import { normalizeConnectionConfig } from '@module/types/types.js';
+import { METRICS_HELPER } from '@powersync/service-core-tests';
 import { describe, expect, test } from 'vitest';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { ChangeStreamTestContext, openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { env } from './env.js';
 import { describeWithStorage, StorageVersionTestContext } from './util.js';
 
@@ -11,8 +12,8 @@ describe('mongodb resuming replication', () => {
 });
 
 function defineResumeTest({ factory: factoryGenerator, storageVersion }: StorageVersionTestContext) {
-  const openContext = (options?: Parameters<typeof ChangeStreamTestContext.open>[1]) => {
-    return ChangeStreamTestContext.open(factoryGenerator, { ...options, storageVersion });
+  const openContext = (options?: Parameters<typeof openChangeStreamTestContext>[1]) => {
+    return openChangeStreamTestContext(factoryGenerator, { ...options, storageVersion });
   };
 
   test.skip('resuming with a different source database', async () => {
@@ -66,7 +67,12 @@ function defineResumeTest({ factory: factoryGenerator, storageVersion }: Storage
     const factory = await factoryGenerator({ doNotClear: true });
 
     // Create a new context without updating the sync config
-    await using context2 = new ChangeStreamTestContext(factory, connectionManager, {}, storageVersion);
+    await using context2 = new ChangeStreamTestContext({
+      factory,
+      connectionManager,
+      storageVersion,
+      metrics: METRICS_HELPER.metricsEngine
+    });
     const active = await factory.getActiveSyncConfig();
     context2.storage = active!.storage;
 

package/test/src/resuming_snapshots.test.ts

@@ -3,7 +3,7 @@ import { METRICS_HELPER } from '@powersync/service-core-tests';
 import { ReplicationMetric } from '@powersync/service-types';
 import * as timers from 'node:timers/promises';
 import { describe, expect, test } from 'vitest';
-import { ChangeStreamTestContext } from './change_stream_utils.js';
+import { openChangeStreamTestContext } from './change_stream_test_setup.js';
 import { env } from './env.js';
 import { describeWithStorage } from './util.js';
 
@@ -35,7 +35,7 @@ async function testResumingReplication(factory: TestStorageFactory, storageVersi
   let startRowCount: number;
 
   {
-    await using context = await ChangeStreamTestContext.open(factory, {
+    await using context = await openChangeStreamTestContext(factory, {
       storageVersion,
       streamOptions: { snapshotChunkLength: 1000 }
     });
@@ -88,7 +88,7 @@ async function testResumingReplication(factory: TestStorageFactory, storageVersi
 
   {
     // Bypass the usual "clear db on factory open" step.
-    await using context2 = await ChangeStreamTestContext.open(factory, {
+    await using context2 = await openChangeStreamTestContext(factory, {
       doNotClear: true,
       storageVersion,
       streamOptions: { snapshotChunkLength: 1000 }