@powersync/service-module-mongodb-storage 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/dist/storage/MongoBucketStorage.js

@@ -1,55 +1,62 @@
-import { LEGACY_STORAGE_VERSION, storage } from '@powersync/service-core';
-import { DO_NOT_LOG, ErrorCode, ServiceError } from '@powersync/lib-services-framework';
+import { LEGACY_STORAGE_VERSION, SingleSyncConfigBucketDefinitionMapping, storage } from '@powersync/service-core';
+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 { ObjectId } from 'bson';
-import { generateSlotName } from '../utils/util.js';
-import { BucketDefinitionMapping } from './implementation/BucketDefinitionMapping.js';
+import { DEFAULT_CLEAR_BATCH_THROTTLE_RATE } from '../types/types.js';
+import { generateReplicationStreamName } from '../utils/util.js';
 import { createMongoSyncBucketStorage } from './implementation/createMongoSyncBucketStorage.js';
 import { getMongoStorageConfig } from './implementation/models.js';
-import { MongoPersistedSyncRulesContentV1, MongoPersistedSyncRulesContentV3 } from './implementation/MongoPersistedSyncRulesContent.js';
-import { syncRuleStateUpdatePipeline } from './implementation/SyncRuleStateUpdate.js';
+import { MongoPersistedReplicationStream } from './implementation/MongoPersistedReplicationStream.js';
+import { stopReplicationStreamPipeline } from './implementation/SyncRuleStateUpdate.js';
+import { ObjectStorageUsage } from './implementation/v3/object-storage/ObjectStorageUsage.js';
 export class MongoBucketStorage extends storage.BucketStorageFactory {
-    internalOptions;
+    options;
     [DO_NOT_LOG] = true;
     client;
-    session;
-    // TODO: This is still Postgres specific and needs to be reworked
-    slot_name_prefix;
+    replicationStreamNamePrefix;
     activeStorageCache;
     db;
-    constructor(db, options, internalOptions) {
+    constructor(db, options) {
         super();
-        this.internalOptions = internalOptions;
+        this.options = options;
         this.client = db.client;
         this.db = db;
-        this.session = this.client.startSession();
-        this.slot_name_prefix = options.slot_name_prefix;
+        this.replicationStreamNamePrefix = options.replicationStreamNamePrefix;
     }
     async [Symbol.asyncDispose]() {
         // No-op
     }
-    getInstance(syncRules, options) {
-        let { id, slot_name } = syncRules;
-        if (typeof id == 'bigint') {
-            id = Number(id);
+    getInstance(replicationStream, options) {
+        if (!(replicationStream instanceof MongoPersistedReplicationStream)) {
+            throw new Error(`Expected MongoPersistedReplicationStream`);
         }
-        const storageConfig = syncRules.getStorageConfig();
-        const storage = createMongoSyncBucketStorage(this, id, syncRules, slot_name, undefined, {
-            ...this.internalOptions,
-            storageConfig
+        let { replicationStreamId, replicationStreamName } = replicationStream;
+        if (typeof replicationStreamId == 'bigint') {
+            replicationStreamId = Number(replicationStreamId);
+        }
+        const storageConfig = replicationStream.getStorageConfig();
+        const syncRuleStorage = createMongoSyncBucketStorage(this, replicationStreamId, replicationStream, replicationStreamName, undefined, {
+            checksumOptions: this.options.checksumOptions,
+            readPreference: this.options.readPreference,
+            checksumCacheTtlMs: this.options.checksumCacheTtlMs,
+            storageConfig,
+            objectStorage: this.options.objectStorage,
+            inlineThresholdBytes: this.options.inlineThresholdBytes,
+            clearBatchThrottleRate: this.options.clearBatchThrottleRate ?? DEFAULT_CLEAR_BATCH_THROTTLE_RATE
         });
         if (!options?.skipLifecycleHooks) {
-            this.iterateListeners((cb) => cb.syncStorageCreated?.(storage));
+            this.iterateListeners((cb) => cb.syncStorageCreated?.(syncRuleStorage));
         }
-        storage.registerListener({
+        syncRuleStorage.registerListener({
             batchStarted: (batch) => {
                 batch.registerListener({
                     replicationEvent: (payload) => this.iterateListeners((cb) => cb.replicationEvent?.(payload))
                 });
             }
         });
-        return storage;
+        return syncRuleStorage;
     }
     async getSystemIdentifier() {
         const { setName: id } = await this.db.db.command({
@@ -63,234 +70,469 @@ export class MongoBucketStorage extends storage.BucketStorageFactory {
             type: lib_mongo.MONGO_CONNECTION_TYPE
         };
     }
-    async restartReplication(sync_rules_group_id) {
-        const next = await this.getNextSyncRulesContent();
-        const active = await this.getActiveSyncRulesContent();
-        if (next != null && next.id == sync_rules_group_id) {
-            // We need to redo the "next" replication stream
-            await this.updateSyncRules(next.asUpdateOptions());
-            // Pro-actively stop replicating
-            await this.db.sync_rules.updateOne({
-                _id: next.id,
-                state: storage.SyncRuleState.PROCESSING
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.STOP));
-            await this.db.notifyCheckpoint();
-        }
-        else if (next == null && active?.id == sync_rules_group_id) {
-            // Slot removed for "active" replication stream, while there is no "next" one.
-            await this.updateSyncRules(active.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({
-                _id: active.id,
-                state: storage.SyncRuleState.ACTIVE
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.ERRORED));
-            await this.db.notifyCheckpoint();
-        }
-        else if (next != null && active?.id == sync_rules_group_id) {
-            // Already have next replication stream, but need to stop replicating the active one.
-            await this.db.sync_rules.updateOne({
-                _id: active.id,
-                state: storage.SyncRuleState.ACTIVE
-            }, syncRuleStateUpdatePipeline(storage.SyncRuleState.ERRORED));
-            await this.db.notifyCheckpoint();
-        }
+    async restartReplication(replicationStreamId) {
+        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();
     }
-    async updateSyncRulesV3(options, storageVersion, storageConfig) {
-        let rules = undefined;
-        const versioned = this.db.versioned(storageConfig);
-        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'
+    /**
+     * 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: { $in: [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED] }
             }, {
-                $inc: {
-                    op_id: 1n
+                $set: {
+                    state: storage.SyncRuleState.ERRORED
                 }
-            }, {
-                upsert: true,
-                returnDocument: 'after',
-                session
-            });
-            const id = Number(id_doc.op_id);
-            const slot_name = generateSlotName(this.slot_name_prefix, id);
-            const mapping = BucketDefinitionMapping.fromParsedSyncRules(options.config.parsed);
-            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,
-                        keepalive_op: null,
-                        last_checkpoint: null,
-                        last_checkpoint_lsn: null,
-                        no_checkpoint_before: 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 MongoPersistedSyncRulesContentV3(this.db, doc, syncConfigDoc);
-            if (options.lock) {
-                // The lock is persisted on rules.current_lock
-                await rules.lock(session);
+            }, { 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;
+        }
+        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
+                }
+            ]
         });
-        return rules;
+        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 updateSyncRules(options) {
-        const storageVersion = options.storageVersion ?? options.config.parsed.config.storageVersion ?? storage.CURRENT_STORAGE_VERSION;
+    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.updateSyncRulesV3(options, storageVersion, storageConfig);
+            return this.updateSyncConfigV3InTransaction(options, storageVersion, storageConfig, session);
         }
-        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
+        return this.updateSyncConfigV1InTransaction(options, storageVersion, session);
+    }
+    /**
+     * 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 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
+                });
+            }
+        }
+        await this.stopExistingProcessingWork(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,
+            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
                 }
-            }, {
-                upsert: true,
-                returnDocument: 'after',
-                session
-            });
-            const id = Number(id_doc.op_id);
-            const slot_name = generateSlotName(this.slot_name_prefix, 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,
+            ],
+            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]);
+        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) {
+        const activeConfigIds = existing.sync_configs
+            .filter((config) => config.state == storage.SyncRuleState.ACTIVE)
+            .map((config) => config._id);
+        return versioned.syncConfigDefinitions
+            .find({
+            _id: { $in: activeConfigIds }
+        }, { session })
+            .toArray();
+    }
+    /**
+     * Load _all_ definition mappings for a replication stream - used as a base to generate new ids.
+     */
+    async loadHistoricalSyncConfigRuleMappings(versioned, replicationStreamId, session) {
+        return versioned.syncConfigDefinitions
+            .find({
+            replication_stream_id: replicationStreamId
+        }, {
+            session,
+            projection: {
+                rule_mapping: 1
+            }
+        })
+            .toArray();
+    }
+    logIncrementalDefinitionChanges(changes) {
+        logger.info(`Incremental reprocessing sync config update:\n${formatIncrementalSyncConfigUpdateLog(changes)}`);
+    }
+    async appendSyncConfigToStream(options) {
+        const { versioned, existing, existingConfigDocs, options: updateOptions, storageVersion, session } = options;
+        const compatibleConfigs = existingConfigDocs.map((doc) => ({
+            plan: doc.serialized_plan.plan,
+            mapping: SingleSyncConfigBucketDefinitionMapping.fromPersistedMapping(doc.rule_mapping)
+        }));
+        const historicalRuleMappings = await this.loadHistoricalSyncConfigRuleMappings(versioned, existing._id, session);
+        const reservedMappings = historicalRuleMappings.map((doc) => SingleSyncConfigBucketDefinitionMapping.fromPersistedMapping(doc.rule_mapping));
+        const mappingResult = SingleSyncConfigBucketDefinitionMapping.constructIncrementalMappingWithChanges(compatibleConfigs, updateOptions.config.plan.plan, reservedMappings);
+        const mapping = mappingResult.mapping;
+        this.logIncrementalDefinitionChanges(describeIncrementalSyncConfigUpdate({
+            activeMappings: existingConfigDocs.map((doc) => SingleSyncConfigBucketDefinitionMapping.fromPersistedMapping(doc.rule_mapping)),
+            newMapping: mapping,
+            newSyncConfig: updateOptions.config.parsed,
+            mappingChanges: mappingResult.changes
+        }));
+        const syncConfigDoc = {
+            _id: new ObjectId(),
+            replication_stream_id: existing._id,
+            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()
+        };
+        await versioned.syncConfigDefinitions.insertOne(syncConfigDoc, { session });
+        const syncConfigState = {
+            _id: syncConfigDoc._id,
+            state: storage.SyncRuleState.PROCESSING,
+            last_checkpoint: null,
+            last_checkpoint_lsn: null,
+            no_checkpoint_before: null,
+            snapshot_done: false
+        };
+        await this.db.sync_rules.updateOne({ _id: existing._id }, {
+            $push: {
+                sync_configs: syncConfigState
+            },
+            $set: {
                 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 MongoPersistedSyncRulesContentV1(this.db, doc);
-            if (options.lock) {
-                // The lock is persisted on rules.current_lock
-                await rules.lock(session);
+                last_fatal_error_ts: null
             }
+        }, { session });
+        const syncConfigStates = [
+            ...existing.sync_configs.filter((config) => config.state == storage.SyncRuleState.ACTIVE),
+            syncConfigState
+        ];
+        const stream = new MongoPersistedReplicationStream(this.db, {
+            ...existing,
+            sync_configs: syncConfigStates
+        }, [...existingConfigDocs, syncConfigDoc]);
+        // 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) {
+        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({
+            _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);
+        if (options.lock) {
+            // The lock is persisted on rules.current_lock
+            await rules.lock(session);
+        }
         return rules;
     }
-    async getActiveSyncRulesContent() {
+    /**
+     * 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.getSyncRulesContent(doc, [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED]);
+        }, { session, sort: { _id: -1 }, limit: 1 });
+        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.ACTIVE, storage.SyncRuleState.ERRORED], { cacheActiveStorage: session == null }, session);
     }
-    async getSyncRulesContent(doc, stateFilter) {
+    async replicationStreamFromDoc(doc, stateFilter, session) {
         if (doc == null) {
             return null;
         }
         const storageConfig = getMongoStorageConfig(doc.storage_version ?? LEGACY_STORAGE_VERSION);
         if (storageConfig.incrementalReprocessing) {
             const v3 = doc;
-            const active = v3.sync_configs.find((c) => stateFilter.includes(c.state));
-            if (active == null) {
+            const matching = v3.sync_configs.filter((c) => stateFilter.includes(c.state));
+            if (matching.length == 0) {
                 return null;
             }
             // TODO: cache the config. It could specifically help for the main replication loop
             // that checks for active replication streams.
             // It is not a major bottleneck though, since it only runs once every couple of seconds at most.
             const db = this.db.versioned(storageConfig);
-            const syncConfigDoc = await db.syncConfigDefinitions.findOne({ _id: active._id });
-            if (syncConfigDoc == null) {
+            const syncConfigDocs = await db.syncConfigDefinitions
+                .find({
+                _id: { $in: matching.map((config) => config._id) }
+            }, { session })
+                .toArray();
+            if (syncConfigDocs.length == 0) {
                 return null;
             }
-            return new MongoPersistedSyncRulesContentV3(this.db, v3, syncConfigDoc);
+            return new MongoPersistedReplicationStream(this.db, v3, syncConfigDocs);
         }
-        return new MongoPersistedSyncRulesContentV1(this.db, doc);
+        return new MongoPersistedReplicationStream(this.db, doc);
+    }
+    async getDeployingSyncConfig() {
+        return this.getDeployingSyncConfigInternal();
     }
-    async getNextSyncRulesContent() {
+    async getDeployingSyncConfigInternal(session) {
         const doc = await this.db.sync_rules.findOne({
-            state: storage.SyncRuleState.PROCESSING
-        }, { sort: { _id: -1 }, limit: 1 });
-        return this.getSyncRulesContent(doc, [storage.SyncRuleState.PROCESSING]);
+            $or: [{ state: storage.SyncRuleState.PROCESSING }, { 'sync_configs.state': storage.SyncRuleState.PROCESSING }]
+        }, { session, sort: { _id: -1 }, limit: 1 });
+        return this.resolvedSyncConfigFromDoc(doc, [storage.SyncRuleState.PROCESSING], {}, session);
     }
-    async getReplicatingSyncRules() {
+    async getReplicatingReplicationStreams() {
         const docs = await this.db.sync_rules
             .find({
             state: { $in: [storage.SyncRuleState.PROCESSING, storage.SyncRuleState.ACTIVE] }
         })
             .toArray();
         return (await Promise.all(docs.map((doc) => {
-            return this.getSyncRulesContent(doc, [storage.SyncRuleState.PROCESSING, storage.SyncRuleState.ACTIVE]);
+            return this.replicationStreamFromDoc(doc, [storage.SyncRuleState.PROCESSING, storage.SyncRuleState.ACTIVE]);
         }))).filter((r) => r != null);
     }
-    async getStoppedSyncRules() {
+    async getStoppedReplicationStreams() {
         const docs = await this.db.sync_rules
             .find({
             state: storage.SyncRuleState.STOP
         })
             .toArray();
         return (await Promise.all(docs.map((doc) => {
-            return this.getSyncRulesContent(doc, [storage.SyncRuleState.STOP]);
+            return this.replicationStreamFromDoc(doc, [storage.SyncRuleState.STOP]);
         }))).filter((d) => d != null);
     }
-    async getActiveStorage() {
-        const content = await this.getActiveSyncRulesContent();
-        if (content == null) {
+    async resolvedSyncConfigFromDoc(doc, stateFilter, options = {}, session) {
+        const stream = await this.replicationStreamFromDoc(doc, stateFilter, session);
+        if (stream == null) {
             return null;
         }
-        // It is important that this instance is cached.
-        // Not for the instance construction itself, but to ensure that internal caches on the instance
-        // are re-used properly.
-        if (this.activeStorageCache?.group_id == content.id) {
-            return this.activeStorageCache;
-        }
-        else {
-            const instance = this.getInstance(content);
-            this.activeStorageCache = instance;
-            return instance;
-        }
+        const content = stream.syncConfigContent[0];
+        const thisFactory = this;
+        return {
+            content,
+            replicationStream: stream,
+            get storage() {
+                // It is important that this instance is cached.
+                // Not for the instance construction itself, but to ensure that internal caches on the instance
+                // are re-used properly.
+                if (options.cacheActiveStorage &&
+                    thisFactory.activeStorageCache?.replicationStream.replicationJobId == stream.replicationJobId) {
+                    return thisFactory.activeStorageCache;
+                }
+                const instance = thisFactory.getInstance(stream);
+                if (options.cacheActiveStorage) {
+                    thisFactory.activeStorageCache = instance;
+                }
+                return instance;
+            }
+        };
     }
     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 } }];
             }
@@ -298,8 +540,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.
@@ -320,7 +560,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: {
@@ -331,7 +572,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: {
@@ -342,7 +584,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: {
@@ -352,13 +595,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() {