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

package/dist/storage/MongoBucketStorage.js

@@ -1,34 +1,54 @@
 import { LEGACY_STORAGE_VERSION, SingleSyncConfigBucketDefinitionMapping, storage } from '@powersync/service-core';
-import { DO_NOT_LOG, ErrorCode, logger, ServiceError } from '@powersync/lib-services-framework';
+import { DO_NOT_LOG, ErrorCode, logger, ReplicationAssertionError, ServiceError } from '@powersync/lib-services-framework';
 import { v4 as uuid } from 'uuid';
 import * as lib_mongo from '@powersync/lib-service-mongodb';
 import { describeIncrementalSyncConfigUpdate, formatIncrementalSyncConfigUpdateLog, isCompatible } from '@powersync/service-core';
+import { Semaphore } from 'async-mutex';
 import { ObjectId } from 'bson';
-import { DEFAULT_CLEAR_BATCH_THROTTLE_RATE } from '../types/types.js';
+import { DEFAULT_CLEAR_BATCH_THROTTLE_RATE, normalizeChunkCompactionConcurrency } from '../types/types.js';
 import { generateReplicationStreamName } from '../utils/util.js';
 import { createMongoSyncBucketStorage } from './implementation/createMongoSyncBucketStorage.js';
 import { getMongoStorageConfig } from './implementation/models.js';
+import { MongoOpIdAllocator } from './implementation/MongoOpIdAllocator.js';
 import { MongoPersistedReplicationStream } from './implementation/MongoPersistedReplicationStream.js';
-import { syncRuleStateUpdatePipeline } from './implementation/SyncRuleStateUpdate.js';
+import { MongoSyncRulesLock } from './implementation/MongoSyncRulesLock.js';
+import { stopReplicationStreamPipeline } from './implementation/SyncRuleStateUpdate.js';
+import { ObjectStorageUsage } from './implementation/v3/object-storage/ObjectStorageUsage.js';
 export class MongoBucketStorage extends storage.BucketStorageFactory {
     options;
     [DO_NOT_LOG] = true;
     client;
-    session;
     replicationStreamNamePrefix;
+    opIdAllocators = new Map();
+    discardOpIdAllocator(streamId) {
+        this.opIdAllocators.get(streamId)?.allocator.discard();
+        this.opIdAllocators.delete(streamId);
+    }
+    getOpIdAllocator(stream, lock) {
+        lock.throwIfAborted();
+        const previous = this.opIdAllocators.get(stream.replicationStreamId);
+        if (previous?.lock === lock) {
+            return previous.allocator;
+        }
+        previous?.allocator.discard();
+        const allocator = new MongoOpIdAllocator(this.db.versioned(stream.getStorageConfig()));
+        this.opIdAllocators.set(stream.replicationStreamId, { lock, allocator });
+        return allocator;
+    }
     activeStorageCache;
     db;
-    constructor(db, options) {
-        super();
+    chunkCompactionConcurrency;
+    chunkCompactionSlots;
+    constructor(db, syncConfigParser, options) {
+        super({ syncConfigParser });
         this.options = options;
+        this.chunkCompactionConcurrency = normalizeChunkCompactionConcurrency(options.chunkCompactionConcurrency, options.objectStorage != null);
+        // All replication streams created by this factory share the configured limit.
+        this.chunkCompactionSlots = new Semaphore(this.chunkCompactionConcurrency);
         this.client = db.client;
         this.db = db;
-        this.session = this.client.startSession();
         this.replicationStreamNamePrefix = options.replicationStreamNamePrefix;
     }
-    async [Symbol.asyncDispose]() {
-        // No-op
-    }
     getInstance(replicationStream, options) {
         if (!(replicationStream instanceof MongoPersistedReplicationStream)) {
             throw new Error(`Expected MongoPersistedReplicationStream`);
@@ -38,6 +58,13 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             replicationStreamId = Number(replicationStreamId);
         }
         const storageConfig = replicationStream.getStorageConfig();
+        if (options?.replicationLock != null) {
+            if (!(options.replicationLock instanceof MongoSyncRulesLock) ||
+                options.replicationLock.sync_rules_id !== replicationStream.replicationStreamId) {
+                throw new ReplicationAssertionError('Replication lock does not belong to this MongoDB stream');
+            }
+            replicationStream.current_lock = options.replicationLock;
+        }
         const syncRuleStorage = createMongoSyncBucketStorage(this, replicationStreamId, replicationStream, replicationStreamName, undefined, {
             checksumOptions: this.options.checksumOptions,
             readPreference: this.options.readPreference,
@@ -72,131 +99,201 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
         };
     }
     async restartReplication(replicationStreamId) {
-        const next = await this.getDeployingSyncConfig();
-        const active = await this.getActiveSyncConfig();
-        if (next != null && next.content.replicationStreamId == replicationStreamId) {
-            // We need to redo the "next" replication stream
-            await this.updateSyncRules(next.content.asUpdateOptions());
-            // Pro-actively stop replicating
-            await this.db.sync_rules.updateOne({
-                _id: next.content.replicationStreamId,
-                state: storage.SyncRuleState.PROCESSING
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP));
-            await this.db.notifyCheckpoint();
-        }
-        else if (next == null && active?.content.replicationStreamId == replicationStreamId) {
-            // Slot removed for "active" replication stream, while there is no "next" one.
-            await this.updateSyncRules(active.content.asUpdateOptions());
-            // In this case we keep the old one as active for clients, so that that existing clients
-            // can still get the latest data while we replicate the new ones.
-            // It will however not replicate anymore.
-            await this.db.sync_rules.updateOne({
+        await this.withTransaction(async (session) => {
+            const next = await this.getDeployingSyncConfigInternal(session);
+            const active = await this.getActiveSyncConfigInternal(session);
+            if (next != null && next.content.replicationStreamId == replicationStreamId) {
+                // We need to redo the "next" replication stream.
+                // This creates a new stream, and stops the existing PROCESSING one.
+                await this.updateSyncRulesInTransaction(next.content.asUpdateOptions({ forceNewReplicationStream: true }), session);
+                const sharedActiveStream = active?.content.replicationStreamId == replicationStreamId;
+                if (sharedActiveStream) {
+                    // The same stream was also used for the ACTIVE config. Transition that to ERRORED
+                    await this.errorActiveStreamForReplacement(active, session);
+                }
+            }
+            else if (next == null && active?.content.replicationStreamId == replicationStreamId) {
+                // Slot removed for "active" replication stream, while there is no "next" one.
+                await this.updateSyncRulesInTransaction(active.content.asUpdateOptions({ forceNewReplicationStream: true }), session);
+                // In this case we keep the old one as active for clients, so that that existing clients
+                // can still get the latest data while we replicate the new ones.
+                // It will however not replicate anymore.
+                await this.errorActiveStreamForReplacement(active, session);
+            }
+            else if (next != null && active?.content.replicationStreamId == replicationStreamId) {
+                // Already have next replication stream, but need to stop replicating the active one.
+                await this.errorActiveStreamForReplacement(active, session);
+            }
+            else {
+                // replicationStreamId does not match the ACTIVE or PROCESSING streams - no-op.
+            }
+        });
+        await this.db.notifyCheckpoint();
+    }
+    /**
+     * Keep an active config readable after its replication stream is invalidated.
+     *
+     * Incremental V3 streams can retain stopped historical configs and embed a deploying config.
+     * Read-side storage requires exactly one ACTIVE or ERRORED config, so only the active config
+     * transitions to ERRORED; every other embedded config remains or becomes STOP.
+     */
+    async errorActiveStreamForReplacement(active, session) {
+        const activeSyncConfigId = active.content.syncConfigId;
+        if (activeSyncConfigId == null) {
+            // V1 documents
+            const result = await this.db.sync_rules.updateOne({
                 _id: active.content.replicationStreamId,
-                state: storage.SyncRuleState.ACTIVE
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.ERRORED));
-            await this.db.notifyCheckpoint();
+                state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
+            }, {
+                $set: {
+                    state: storage.SyncRuleState.ERRORED
+                }
+            }, { session });
+            if (result.matchedCount != 1) {
+                // This should generally not happen, since the entire process runs in a transaction.
+                // The filters just double-check that the state is what we expect, and fails hard otherwise.
+                throw new ReplicationAssertionError(`Active replication stream ${active.content.replicationStreamId} changed during restart`);
+            }
+            return;
         }
-        else if (next != null && active?.content.replicationStreamId == replicationStreamId) {
-            // Already have next replication stream, but need to stop replicating the active one.
-            await this.db.sync_rules.updateOne({
-                _id: active.content.replicationStreamId,
-                state: storage.SyncRuleState.ACTIVE
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.ERRORED));
-            await this.db.notifyCheckpoint();
+        const activeConfigObjectId = new ObjectId(activeSyncConfigId);
+        const result = await this.db.sync_rules.updateOne({
+            _id: active.content.replicationStreamId,
+            state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] },
+            sync_configs: {
+                // Confirm that this is still the ACTIVE/ERRORED one.
+                $elemMatch: {
+                    _id: activeConfigObjectId,
+                    state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
+                }
+            }
+        }, {
+            $set: {
+                state: storage.SyncRuleState.ERRORED,
+                // There must be exactly one config with an ERRORED state: This will be used to serve
+                // clients until there is a new ACTIVE one.
+                'sync_configs.$[activeConfig].state': storage.SyncRuleState.ERRORED,
+                // PROCESSING configs must stop. Historical STOP configs remain unchanged.
+                'sync_configs.$[processingConfig].state': storage.SyncRuleState.STOP
+            }
+        }, {
+            session,
+            arrayFilters: [
+                {
+                    'activeConfig._id': activeConfigObjectId,
+                    'activeConfig.state': { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
+                },
+                {
+                    'processingConfig._id': { $ne: activeConfigObjectId },
+                    'processingConfig.state': storage.SyncRuleState.PROCESSING
+                }
+            ]
+        });
+        if (result.matchedCount != 1) {
+            // This should generally not happen, since the entire process runs in a transaction.
+            // The filters just double-check that the state is what we expect, and fails hard otherwise.
+            throw new ReplicationAssertionError(`Active replication stream ${active.content.replicationStreamId} changed during restart`);
+        }
+    }
+    async updateSyncRulesInTransaction(options, session) {
+        const storageVersion = options.storageVersion ??
+            options.config.parsed.config.storageVersion ??
+            this.options.defaultStorageVersion ??
+            storage.CURRENT_STORAGE_VERSION;
+        const storageConfig = getMongoStorageConfig(storageVersion);
+        if (storageConfig.incrementalReprocessing) {
+            return this.updateSyncConfigV3InTransaction(options, storageVersion, storageConfig, session);
         }
+        return this.updateSyncConfigV1InTransaction(options, storageVersion, session);
     }
-    async updateSyncRulesV3(options, storageVersion, storageConfig) {
-        let rules = undefined;
+    /**
+     * Update to a V3 sync config.
+     *
+     * Does support cases where existing replication streams are on V1.
+     */
+    async updateSyncConfigV3InTransaction(options, storageVersion, storageConfig, session) {
         const versioned = this.db.versioned(storageConfig);
-        const session = this.session;
-        await session.withTransaction(async () => {
-            const active = await this.db.sync_rules.findOne({
-                state: storage.SyncRuleState.ACTIVE,
-                storage_version: storageVersion
-            }, { session, sort: { _id: -1 }, limit: 1 });
-            if (active != null) {
-                const existingConfigDocs = await this.loadSyncConfigDefinitions(versioned, active, session);
-                if (this.options.supportsMultipleSyncConfigs &&
-                    isCompatible(existingConfigDocs.map((d) => d.serialized_plan ?? null), options.config, logger)) {
-                    logger.info(`Using incremental reprocessing`);
-                    await this.db.sync_rules.updateMany({
-                        state: storage.SyncRuleState.PROCESSING
-                    }, syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP), { session });
-                    await this.stopEmbeddedDeployingConfigs(active, session);
-                    rules = await this.appendSyncConfigToStream({
-                        versioned,
-                        existing: active,
-                        existingConfigDocs,
-                        options,
-                        storageVersion,
-                        session
-                    });
-                    return;
-                }
-                await this.stopEmbeddedDeployingConfigs(active, session);
+        const active = await this.db.sync_rules.findOne({
+            state: storage.SyncRuleState.ACTIVE,
+            storage_version: storageVersion
+        }, { session, sort: { _id: -1 }, limit: 1 });
+        if (active != null) {
+            const existingConfigDocs = await this.loadSyncConfigDefinitions(versioned, active, session);
+            if (!options.forceNewReplicationStream &&
+                this.options.supportsMultipleSyncConfigs &&
+                isCompatible(existingConfigDocs.map((d) => d.serialized_plan ?? null), options.config, logger)) {
+                logger.info(`Using incremental reprocessing`);
+                await this.stopExistingProcessingWork(session);
+                return await this.appendSyncConfigToStream({
+                    versioned,
+                    existing: active,
+                    existingConfigDocs,
+                    options,
+                    storageVersion,
+                    session
+                });
             }
-            // Only have a single replication stream with PROCESSING.
-            await this.db.sync_rules.updateMany({
-                state: storage.SyncRuleState.PROCESSING
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP), { session });
-            const id_doc = await this.db.op_id_sequence.findOneAndUpdate({
-                _id: 'sync_rules'
-            }, {
-                $inc: {
-                    op_id: 1n
-                }
-            }, {
-                upsert: true,
-                returnDocument: 'after',
-                session
-            });
-            const id = Number(id_doc.op_id);
-            const replicationStreamName = generateReplicationStreamName(this.replicationStreamNamePrefix, id);
-            const mapping = options.config.plan == null
-                ? // For legacy sync rules and streams, use the parsed config directly to create a mapping
-                    SingleSyncConfigBucketDefinitionMapping.fromParsedSyncConfig(options.config.parsed)
-                : // For new sync streams, always use the serialized version
-                    SingleSyncConfigBucketDefinitionMapping.constructIncrementalMappingFromSerializedPlans([], options.config.plan.plan, []);
-            const syncConfigDoc = {
-                _id: new ObjectId(),
-                replication_stream_id: id,
-                created_at: new Date(),
-                storage_version: storageVersion,
-                content: options.config.yaml,
-                serialized_plan: options.config.plan,
-                rule_mapping: mapping.serialize()
-            };
-            await versioned.syncConfigDefinitions.insertOne(syncConfigDoc, { session });
-            const doc = {
-                _id: id,
-                storage_version: storageVersion,
-                sync_configs: [
-                    {
-                        _id: syncConfigDoc._id,
-                        state: storage.SyncRuleState.PROCESSING,
-                        last_checkpoint: null,
-                        last_checkpoint_lsn: null,
-                        no_checkpoint_before: null,
-                        snapshot_done: false
-                    }
-                ],
-                snapshot_lsn: undefined,
-                state: storage.SyncRuleState.PROCESSING,
-                slot_name: replicationStreamName,
-                last_checkpoint_ts: null,
-                last_fatal_error: null,
-                last_fatal_error_ts: null,
-                last_keepalive_ts: null
-            };
-            await this.db.sync_rules.insertOne(doc, { session });
-            rules = new MongoPersistedReplicationStream(this.db, doc, [syncConfigDoc]);
-            if (options.lock) {
-                // The lock is persisted on rules.current_lock
-                await rules.lock(session);
+        }
+        await this.stopExistingProcessingWork(session);
+        const id_doc = await this.db.op_id_sequence.findOneAndUpdate({
+            // Uses the legacy id "sync_rules" for backwards-compatibility. See AGENTS.md.
+            _id: 'sync_rules'
+        }, {
+            $inc: {
+                op_id: 1n
             }
+        }, {
+            upsert: true,
+            returnDocument: 'after',
+            session
         });
-        // Notify only after the transaction has committed, so listeners cannot observe pre-commit state.
-        await this.db.notifyCheckpoint();
+        const id = Number(id_doc.op_id);
+        const replicationStreamName = generateReplicationStreamName(this.replicationStreamNamePrefix, id);
+        const mapping = options.config.plan == null
+            ? // For legacy Sync Rules and Streams, use the parsed config directly to create a mapping
+                SingleSyncConfigBucketDefinitionMapping.fromParsedSyncConfig(options.config.parsed)
+            : // For new Sync Streams, always use the serialized version
+                SingleSyncConfigBucketDefinitionMapping.constructIncrementalMappingFromSerializedPlans([], options.config.plan.plan, []);
+        const syncConfigDoc = {
+            _id: new ObjectId(),
+            replication_stream_id: id,
+            created_at: new Date(),
+            storage_version: storageVersion,
+            content: options.config.yaml,
+            version_label: options.version_label,
+            serialized_plan: options.config.plan,
+            rule_mapping: mapping.serialize()
+        };
+        await versioned.syncConfigDefinitions.insertOne(syncConfigDoc, { session });
+        const doc = {
+            _id: id,
+            storage_version: storageVersion,
+            sync_configs: [
+                {
+                    _id: syncConfigDoc._id,
+                    state: storage.SyncRuleState.PROCESSING,
+                    last_checkpoint: null,
+                    last_checkpoint_lsn: null,
+                    no_checkpoint_before: null,
+                    snapshot_done: false
+                }
+            ],
+            snapshot_lsn: undefined,
+            state: storage.SyncRuleState.PROCESSING,
+            slot_name: replicationStreamName,
+            last_checkpoint_ts: null,
+            last_fatal_error: null,
+            last_fatal_error_ts: null,
+            last_keepalive_ts: null
+        };
+        await this.db.sync_rules.insertOne(doc, { session });
+        const rules = new MongoPersistedReplicationStream(this.db, doc, [syncConfigDoc], this.syncConfigParser);
+        if (options.lock) {
+            // We only lock when creating a new stream - otherwise we'll likely get lock contention
+            // from an existing job on the stream, which would fail the entire transaction.
+            // The lock is persisted on rules.current_lock
+            await rules.lock(session);
+        }
         return rules;
     }
     async loadSyncConfigDefinitions(versioned, existing, session) {
@@ -224,25 +321,6 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
         })
             .toArray();
     }
-    async stopEmbeddedDeployingConfigs(existing, session) {
-        const deployingConfigs = existing.sync_configs
-            .filter((config) => config.state == storage.SyncRuleState.PROCESSING)
-            .map((config) => config._id);
-        if (deployingConfigs.length == 0) {
-            return;
-        }
-        await this.db.sync_rules.updateOne({
-            _id: existing._id,
-            'sync_configs._id': { $in: deployingConfigs }
-        }, {
-            $set: {
-                'sync_configs.$[config].state': storage.SyncRuleState.STOP
-            }
-        }, {
-            session,
-            arrayFilters: [{ 'config._id': { $in: deployingConfigs } }]
-        });
-    }
     logIncrementalDefinitionChanges(changes) {
         logger.info(`Incremental reprocessing sync config update:\n${formatIncrementalSyncConfigUpdateLog(changes)}`);
     }
@@ -268,6 +346,7 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             created_at: new Date(),
             storage_version: storageVersion,
             content: updateOptions.config.yaml,
+            version_label: updateOptions.version_label,
             serialized_plan: updateOptions.config.plan,
             rule_mapping: mapping.serialize()
         };
@@ -296,75 +375,110 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
         const stream = new MongoPersistedReplicationStream(this.db, {
             ...existing,
             sync_configs: syncConfigStates
-        }, [...existingConfigDocs, syncConfigDoc]);
+        }, [...existingConfigDocs, syncConfigDoc], this.syncConfigParser);
         // The stream already exists, so an active replication job may already hold the stream lock.
         // Deployment only persists the appended sync config; replication job locking is handled by
         // the replicator.
         return stream;
     }
     async updateSyncRules(options) {
-        const storageVersion = options.storageVersion ?? options.config.parsed.config.storageVersion ?? storage.CURRENT_STORAGE_VERSION;
-        const storageConfig = getMongoStorageConfig(storageVersion);
-        if (storageConfig.incrementalReprocessing) {
-            return this.updateSyncRulesV3(options, storageVersion, storageConfig);
-        }
-        let rules = undefined;
-        const session = this.session;
-        await session.withTransaction(async () => {
-            // Only have a single replication stream with PROCESSING.
-            await this.db.sync_rules.updateMany({
-                state: storage.SyncRuleState.PROCESSING
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP), { session });
-            const id_doc = await this.db.op_id_sequence.findOneAndUpdate({
-                _id: 'sync_rules'
-            }, {
-                $inc: {
-                    op_id: 1n
-                }
-            }, {
-                upsert: true,
-                returnDocument: 'after',
-                session
-            });
-            const id = Number(id_doc.op_id);
-            const slot_name = generateReplicationStreamName(this.replicationStreamNamePrefix, id);
-            const doc = {
-                _id: id,
-                storage_version: storageVersion,
-                content: options.config.yaml,
-                serialized_plan: options.config.plan,
-                last_checkpoint: null,
-                last_checkpoint_lsn: null,
-                no_checkpoint_before: null,
-                keepalive_op: null,
-                snapshot_done: false,
-                snapshot_lsn: undefined,
-                state: storage.SyncRuleState.PROCESSING,
-                slot_name: slot_name,
-                last_checkpoint_ts: null,
-                last_fatal_error: null,
-                last_fatal_error_ts: null,
-                last_keepalive_ts: null
-            };
-            await this.db.sync_rules.insertOne(doc, { session });
-            await this.db.notifyCheckpoint();
-            rules = new MongoPersistedReplicationStream(this.db, doc);
-            if (options.lock) {
-                // The lock is persisted on rules.current_lock
-                await rules.lock(session);
+        let rules;
+        await this.withTransaction(async (session) => {
+            rules = await this.updateSyncRulesInTransaction(options, session);
+        });
+        await this.db.notifyCheckpoint();
+        return rules;
+    }
+    async withTransaction(callback) {
+        return this.client.withSession((session) => session.withTransaction(callback));
+    }
+    /**
+     * Update to a V1 sync config.
+     *
+     * Does support cases where existing replication streams are on V3.
+     */
+    async updateSyncConfigV1InTransaction(options, storageVersion, session) {
+        await this.stopExistingProcessingWork(session);
+        const id_doc = await this.db.op_id_sequence.findOneAndUpdate({
+            // Uses the legacy id "sync_rules" for backwards-compatibility. See AGENTS.md.
+            _id: 'sync_rules'
+        }, {
+            $inc: {
+                op_id: 1n
             }
+        }, {
+            upsert: true,
+            returnDocument: 'after',
+            session
         });
+        const id = Number(id_doc.op_id);
+        const slot_name = generateReplicationStreamName(this.replicationStreamNamePrefix, id);
+        // All V1 replication streams share both the `main` op id sequence and the `bucket_parameters`
+        // collection, so every parameter entry this stream writes gets an op id above the current
+        // head. Seeding the parameter compaction cursor with that head keeps the stream's first
+        // compaction from scanning other streams' history, which would otherwise be repeated for
+        // every new deployment. A concurrent replication flush can only advance the head after this
+        // read, which makes the seed conservative, never too high.
+        const opSequence = await this.db.op_id_sequence.findOne({ _id: 'main' }, { session });
+        const doc = {
+            _id: id,
+            storage_version: storageVersion,
+            content: options.config.yaml,
+            version_label: options.version_label,
+            serialized_plan: options.config.plan,
+            last_checkpoint: null,
+            last_checkpoint_lsn: null,
+            no_checkpoint_before: null,
+            keepalive_op: null,
+            snapshot_done: false,
+            snapshot_lsn: undefined,
+            state: storage.SyncRuleState.PROCESSING,
+            slot_name: slot_name,
+            last_checkpoint_ts: null,
+            last_fatal_error: null,
+            last_fatal_error_ts: null,
+            last_keepalive_ts: null,
+            parameter_compaction: { compacted_before: opSequence?.op_id ?? 0n }
+        };
+        await this.db.sync_rules.insertOne(doc, { session });
+        const rules = new MongoPersistedReplicationStream(this.db, doc, [], this.syncConfigParser);
+        if (options.lock) {
+            // The lock is persisted on rules.current_lock
+            await rules.lock(session);
+        }
         return rules;
     }
+    /**
+     * Stop top-level and embedded processing work before creating a replacement stream.
+     *
+     * Use in the same transaction that the replacement stream is created.
+     */
+    async stopExistingProcessingWork(session) {
+        await this.db.sync_rules.updateMany({
+            state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] },
+            'sync_configs.state': storage.SyncRuleState.PROCESSING
+        }, {
+            $set: {
+                'sync_configs.$[config].state': storage.SyncRuleState.STOP
+            }
+        }, {
+            session,
+            arrayFilters: [{ 'config.state': storage.SyncRuleState.PROCESSING }]
+        });
+        await this.db.sync_rules.updateMany({
+            state: storage.SyncRuleState.PROCESSING
+        }, stopReplicationStreamPipeline(), { session });
+    }
     async getActiveSyncConfig() {
+        return this.getActiveSyncConfigInternal();
+    }
+    async getActiveSyncConfigInternal(session) {
         const doc = await this.db.sync_rules.findOne({
             state: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
-        }, { sort: { _id: -1 }, limit: 1 });
-        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED], {
-            cacheActiveStorage: true
-        });
+        }, { session, sort: { _id: -1 }, limit: 1 });
+        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED], { cacheActiveStorage: session == null }, session);
     }
-    async replicationStreamFromDoc(doc, stateFilter) {
+    async replicationStreamFromDoc(doc, stateFilter, session) {
         if (doc == null) {
             return null;
         }
@@ -382,20 +496,23 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             const syncConfigDocs = await db.syncConfigDefinitions
                 .find({
                 _id: { $in: matching.map((config) => config._id) }
-            })
+            }, { session })
                 .toArray();
             if (syncConfigDocs.length == 0) {
                 return null;
             }
-            return new MongoPersistedReplicationStream(this.db, v3, syncConfigDocs);
+            return new MongoPersistedReplicationStream(this.db, v3, syncConfigDocs, this.syncConfigParser);
         }
-        return new MongoPersistedReplicationStream(this.db, doc);
+        return new MongoPersistedReplicationStream(this.db, doc, [], this.syncConfigParser);
     }
     async getDeployingSyncConfig() {
+        return this.getDeployingSyncConfigInternal();
+    }
+    async getDeployingSyncConfigInternal(session) {
         const doc = await this.db.sync_rules.findOne({
             $or: [{ state: storage.SyncRuleState.PROCESSING }, { 'sync_configs.state': storage.SyncRuleState.PROCESSING }]
-        }, { sort: { _id: -1 }, limit: 1 });
-        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.PROCESSING]);
+        }, { session, sort: { _id: -1 }, limit: 1 });
+        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.PROCESSING], {}, session);
     }
     async getReplicatingReplicationStreams() {
         const docs = await this.db.sync_rules
@@ -417,8 +534,8 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             return this.replicationStreamFromDoc(doc, [storage.SyncRuleState.STOP]);
         }))).filter((d) => d != null);
     }
-    async resolvedSyncConfigFromDoc(doc, stateFilter, options = {}) {
-        const stream = await this.replicationStreamFromDoc(doc, stateFilter);
+    async resolvedSyncConfigFromDoc(doc, stateFilter, options = {}, session) {
+        const stream = await this.replicationStreamFromDoc(doc, stateFilter, session);
         if (stream == null) {
             return null;
         }
@@ -445,7 +562,7 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
     }
     async getStorageMetrics() {
         const ignoreNotExisting = (e) => {
-            if (lib_mongo.isMongoServerError(e) && e.codeName == 'NamespaceNotFound') {
+            if (lib_mongo.isMongoNamespaceNotFoundError(e)) {
                 // Collection doesn't exist - return 0
                 return [{ storageStats: { size: 0 } }];
             }
@@ -453,8 +570,6 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
                 return Promise.reject(e);
             }
         };
-        // For now, we get storage metrics over all v1 and v3 collections.
-        // In the future, we may split these metrics to report separately for active replication streams versus processing streams.
         const aggregateStaticCollection = async (collection) => {
             // We check whether the collection exists before getting the statistics. This avoids repeated
             // errors in the MongoDB logs if the collection hasn't been created yet.
@@ -475,7 +590,8 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
                 .catch(ignoreNotExisting);
         };
         const operations_aggregate = await aggregateStaticCollection(this.db.bucket_data);
-        const v3_operation_aggregates = await Promise.all((await this.db.listBucketDataCollectionsV3()).map((collection) => collection
+        const v3OperationCollections = await this.db.listBucketDataCollectionsV3();
+        const v3_operation_aggregates = await Promise.all(v3OperationCollections.map((collection) => collection
             .aggregate([
             {
                 $collStats: {
@@ -486,7 +602,8 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             .toArray()
             .catch(ignoreNotExisting)));
         const parameters_aggregate = await aggregateStaticCollection(this.db.bucket_parameters);
-        const v3_parameter_aggregates = await Promise.all((await this.db.listAllParameterIndexCollectionsV3()).map((collection) => collection
+        const v3ParameterCollections = await this.db.listAllParameterIndexCollectionsV3();
+        const v3_parameter_aggregates = await Promise.all(v3ParameterCollections.map((collection) => collection
             .aggregate([
             {
                 $collStats: {
@@ -497,7 +614,8 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             .toArray()
             .catch(ignoreNotExisting)));
         const v1_source_record_aggregate = await aggregateStaticCollection(this.db.current_data);
-        const source_record_aggregates = await Promise.all((await this.db.listAllSourceRecordCollectionsV3()).map((collection) => collection
+        const v3SourceRecordCollections = await this.db.listAllSourceRecordCollectionsV3();
+        const source_record_aggregates = await Promise.all(v3SourceRecordCollections.map((collection) => collection
             .aggregate([
             {
                 $collStats: {
@@ -507,13 +625,84 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
         ])
             .toArray()
             .catch(ignoreNotExisting)));
+        const v3StorageConfig = getMongoStorageConfig(storage.STORAGE_VERSION_3);
+        const v3Db = this.db.versioned(v3StorageConfig);
+        const objectStorageDefinitionUsage = await ObjectStorageUsage.readAllDefinitionUsage(v3Db);
+        const v3StreamDocs = (await this.db.sync_rules
+            .find({ storage_version: { $gte: storage.STORAGE_VERSION_3 } }, { projection: { _id: 1, sync_configs: 1 } })
+            .toArray());
+        const collectionSizes = new Map();
+        const addCollectionSize = (collection, aggregate, prefix, sizes) => {
+            const match = collection.collectionName.match(new RegExp(`^${prefix}(\\d+)_(.+)$`));
+            if (match == null) {
+                return;
+            }
+            sizes.set(`${prefix}${match[1]}:${match[2]}`, Number(aggregate[0]?.storageStats?.size ?? 0));
+        };
+        v3OperationCollections.forEach((collection, index) => addCollectionSize(collection, v3_operation_aggregates[index], 'bucket_data_', collectionSizes));
+        v3ParameterCollections.forEach((collection, index) => addCollectionSize(collection, v3_parameter_aggregates[index], 'parameter_index_', collectionSizes));
+        v3SourceRecordCollections.forEach((collection, index) => addCollectionSize(collection, source_record_aggregates[index], 'source_records_', collectionSizes));
+        const syncConfigIds = v3StreamDocs.flatMap((stream) => (stream.sync_configs ?? []).map((config) => config._id));
+        const syncConfigDefinitions = syncConfigIds.length == 0
+            ? []
+            : await v3Db.syncConfigDefinitions
+                .find({ _id: { $in: syncConfigIds } }, { projection: { _id: 1, rule_mapping: 1, version_label: 1 } })
+                .toArray();
+        const syncConfigDefinitionsById = new Map(syncConfigDefinitions.map((definition) => [definition._id.toHexString(), definition]));
+        const sourceTablesByStream = new Map();
+        await Promise.all(v3StreamDocs.map(async (stream) => {
+            const sourceTables = await v3Db
+                .sourceTables(stream._id)
+                .find({}, { projection: { _id: 1, bucket_data_source_ids: 1, parameter_lookup_source_ids: 1 } })
+                .toArray();
+            sourceTablesByStream.set(stream._id, sourceTables);
+        }));
+        const objectStorageSizeByDefinition = new Map();
+        for (const usage of objectStorageDefinitionUsage) {
+            objectStorageSizeByDefinition.set(`${usage.replication_stream_id}:${usage.definition_id}`, Number(usage.active_bytes));
+        }
+        const sumCollectionSizes = (prefix, streamId, ids) => [...ids].reduce((total, id) => total + (collectionSizes.get(`${prefix}${streamId}:${id}`) ?? 0), 0);
+        const syncConfigMetrics = [];
+        for (const stream of v3StreamDocs) {
+            const sourceTables = sourceTablesByStream.get(stream._id) ?? [];
+            for (const syncConfig of stream.sync_configs ?? []) {
+                const definition = syncConfigDefinitionsById.get(syncConfig._id.toHexString());
+                if (definition == null) {
+                    continue;
+                }
+                const mapping = SingleSyncConfigBucketDefinitionMapping.fromPersistedMapping(definition.rule_mapping);
+                const bucketDefinitionIds = mapping.allBucketDefinitionIds();
+                const parameterIndexIds = mapping.allParameterIndexIds();
+                const bucketDefinitionIdSet = new Set(bucketDefinitionIds);
+                const parameterIndexIdSet = new Set(parameterIndexIds);
+                const replicationSize = sourceTables.reduce((total, sourceTable) => {
+                    if (!(sourceTable.bucket_data_source_ids ?? []).some((id) => bucketDefinitionIdSet.has(id)) &&
+                        !(sourceTable.parameter_lookup_source_ids ?? []).some((id) => parameterIndexIdSet.has(id))) {
+                        return total;
+                    }
+                    return total + (collectionSizes.get(`source_records_${stream._id}:${sourceTable._id.toHexString()}`) ?? 0);
+                }, 0);
+                syncConfigMetrics.push({
+                    sync_config_id: syncConfig._id.toHexString(),
+                    sync_config_state: String(syncConfig.state),
+                    version_label: definition.version_label,
+                    attributed_bucket_data_bytes: sumCollectionSizes('bucket_data_', stream._id, bucketDefinitionIdSet),
+                    attributed_parameter_indexes_bytes: sumCollectionSizes('parameter_index_', stream._id, parameterIndexIdSet),
+                    attributed_source_records_bytes: replicationSize,
+                    attributed_object_storage_bytes: [...bucketDefinitionIdSet].reduce((total, definitionId) => total + (objectStorageSizeByDefinition.get(`${stream._id}:${definitionId}`) ?? 0), 0)
+                });
+            }
+        }
+        const totalObjectStorageSize = objectStorageDefinitionUsage.reduce((total, usage) => total + usage.active_bytes, 0n);
         return {
             operations_size_bytes: Number(operations_aggregate[0].storageStats.size) +
                 v3_operation_aggregates.reduce((total, aggregate) => total + Number(aggregate[0].storageStats.size), 0),
             parameters_size_bytes: Number(parameters_aggregate[0].storageStats.size) +
                 v3_parameter_aggregates.reduce((total, aggregate) => total + Number(aggregate[0].storageStats.size), 0),
             replication_size_bytes: Number(v1_source_record_aggregate[0]?.storageStats?.size ?? 0) +
-                source_record_aggregates.reduce((total, aggregate) => total + Number(aggregate[0]?.storageStats?.size ?? 0), 0)
+                source_record_aggregates.reduce((total, aggregate) => total + Number(aggregate[0]?.storageStats?.size ?? 0), 0),
+            object_storage_size_bytes: Number(totalObjectStorageSize),
+            sync_config_metrics: syncConfigMetrics
         };
     }
     async getPowerSyncInstanceId() {