@powersync/service-module-mongodb-storage 0.0.0-dev-20250829094737 → 0.0.0-dev-20250903064005

package/src/storage/implementation/MongoStorageProvider.ts

@@ -4,8 +4,9 @@ import { POWERSYNC_VERSION, storage } from '@powersync/service-core';
 import { MongoStorageConfig } from '../../types/types.js';
 import { MongoBucketStorage } from '../MongoBucketStorage.js';
 import { PowerSyncMongo } from './db.js';
+import { MongoReportStorage } from '../MongoReportStorage.js';
 
-export class MongoStorageProvider implements storage.BucketStorageProvider {
+export class MongoStorageProvider implements storage.StorageProvider {
   get type() {
     return lib_mongo.MONGO_CONNECTION_TYPE;
   }
@@ -37,15 +38,19 @@ export class MongoStorageProvider implements storage.BucketStorageProvider {
     await client.connect();
 
     const database = new PowerSyncMongo(client, { database: resolvedConfig.storage.database });
-    const factory = new MongoBucketStorage(database, {
+    const syncStorageFactory = new MongoBucketStorage(database, {
       // TODO currently need the entire resolved config due to this
       slot_name_prefix: resolvedConfig.slot_name_prefix
     });
+
+    // Storage factory for reports
+    const reportStorageFactory = new MongoReportStorage(database);
     return {
-      storage: factory,
+      storage: syncStorageFactory,
+      reportStorage: reportStorageFactory,
       shutDown: async () => {
         shuttingDown = true;
-        await factory[Symbol.asyncDispose]();
+        await syncStorageFactory[Symbol.asyncDispose]();
         await client.close();
       },
       tearDown: () => {

package/src/storage/implementation/MongoSyncBucketStorage.ts

@@ -31,11 +31,16 @@ import { MongoBucketStorage } from '../MongoBucketStorage.js';
 import { PowerSyncMongo } from './db.js';
 import { BucketDataDocument, BucketDataKey, BucketStateDocument, SourceKey, SourceTableDocument } from './models.js';
 import { MongoBucketBatch } from './MongoBucketBatch.js';
-import { MongoChecksums } from './MongoChecksums.js';
+import { MongoChecksumOptions, MongoChecksums } from './MongoChecksums.js';
 import { MongoCompactor } from './MongoCompactor.js';
 import { MongoParameterCompactor } from './MongoParameterCompactor.js';
 import { MongoWriteCheckpointAPI } from './MongoWriteCheckpointAPI.js';
-import { idPrefixFilter, mapOpEntry, readSingleBatch, setSessionSnapshotTime } from './util.js';
+import { idPrefixFilter, mapOpEntry, readSingleBatch, setSessionSnapshotTime } from '../../utils/util.js';
+
+
+export interface MongoSyncBucketStorageOptions {
+  checksumOptions?: MongoChecksumOptions;
+}
 
 export class MongoSyncBucketStorage
   extends BaseObserver<storage.SyncRulesBucketStorageListener>
@@ -52,14 +57,15 @@ export class MongoSyncBucketStorage
     public readonly group_id: number,
     private readonly sync_rules: storage.PersistedSyncRulesContent,
     public readonly slot_name: string,
-    writeCheckpointMode: storage.WriteCheckpointMode = storage.WriteCheckpointMode.MANAGED
+    writeCheckpointMode?: storage.WriteCheckpointMode,
+    options?: MongoSyncBucketStorageOptions
   ) {
     super();
     this.db = factory.db;
-    this.checksums = new MongoChecksums(this.db, this.group_id);
+    this.checksums = new MongoChecksums(this.db, this.group_id, options?.checksumOptions);
     this.writeCheckpointAPI = new MongoWriteCheckpointAPI({
       db: this.db,
-      mode: writeCheckpointMode,
+      mode: writeCheckpointMode ?? storage.WriteCheckpointMode.MANAGED,
       sync_rules_id: group_id
     });
   }

package/src/storage/implementation/PersistedBatch.ts

@@ -16,7 +16,7 @@ import {
   CurrentDataDocument,
   SourceKey
 } from './models.js';
-import { replicaIdToSubkey } from './util.js';
+import { replicaIdToSubkey } from '../../utils/util.js';
 
 /**
  * Maximum size of operations we write in a single transaction.

package/src/storage/implementation/db.ts

@@ -8,6 +8,7 @@ import {
   BucketParameterDocument,
   BucketStateDocument,
   CheckpointEventDocument,
+  ClientConnectionDocument,
   CurrentDataDocument,
   CustomWriteCheckpointDocument,
   IdSequenceDocument,
@@ -37,6 +38,7 @@ export class PowerSyncMongo {
   readonly locks: mongo.Collection<lib_mongo.locks.Lock>;
   readonly bucket_state: mongo.Collection<BucketStateDocument>;
   readonly checkpoint_events: mongo.Collection<CheckpointEventDocument>;
+  readonly connection_report_events: mongo.Collection<ClientConnectionDocument>;
 
   readonly client: mongo.MongoClient;
   readonly db: mongo.Db;
@@ -61,6 +63,7 @@ export class PowerSyncMongo {
     this.locks = this.db.collection('locks');
     this.bucket_state = this.db.collection('bucket_state');
     this.checkpoint_events = this.db.collection('checkpoint_events');
+    this.connection_report_events = this.db.collection('connection_report_events');
   }
 
   /**
@@ -127,6 +130,34 @@ export class PowerSyncMongo {
       max: 50 // max number of documents
     });
   }
+
+  /**
+   * Only use in migrations and tests.
+   */
+  async createConnectionReportingCollection() {
+    const existingCollections = await this.db
+      .listCollections({ name: 'connection_report_events' }, { nameOnly: false })
+      .toArray();
+    const collection = existingCollections[0];
+    if (collection != null) {
+      return;
+    }
+    await this.db.createCollection('connection_report_events');
+  }
+
+  /**
+   * Only use in migrations and tests.
+   */
+  async createBucketStateIndex() {
+    // TODO: Implement a better mechanism to use migrations in tests
+    await this.bucket_state.createIndex(
+      {
+        '_id.g': 1,
+        last_op: 1
+      },
+      { name: 'bucket_updates', unique: true }
+    );
+  }
 }
 
 export function createPowerSyncMongo(config: MongoStorageConfig, options?: lib_mongo.MongoConnectionOptions) {

package/src/storage/implementation/models.ts

@@ -1,6 +1,7 @@
 import { InternalOpId, storage } from '@powersync/service-core';
 import { SqliteJsonValue } from '@powersync/service-sync-rules';
 import * as bson from 'bson';
+import { event_types } from '@powersync/service-types';
 
 /**
  * Replica id uniquely identifying a row on the source database.
@@ -97,6 +98,10 @@ export interface BucketStateDocument {
     g: number;
     b: string;
   };
+  /**
+   * Important: There is an unique index on {'_id.g': 1, last_op: 1}.
+   * That means the last_op must match an actual op in the bucket, and not the commit checkpoint.
+   */
   last_op: bigint;
   /**
    * If set, this can be treated as "cache" of a checksum at a specific point.
@@ -234,3 +239,5 @@ export interface InstanceDocument {
   // The instance UUID
   _id: string;
 }
+
+export interface ClientConnectionDocument extends event_types.ClientConnection {}

package/src/storage/storage-index.ts

@@ -7,8 +7,9 @@ export * from './implementation/MongoPersistedSyncRulesContent.js';
 export * from './implementation/MongoStorageProvider.js';
 export * from './implementation/MongoSyncBucketStorage.js';
 export * from './implementation/MongoSyncRulesLock.js';
-export * from './implementation/MongoTestStorageFactoryGenerator.js';
 export * from './implementation/OperationBatch.js';
 export * from './implementation/PersistedBatch.js';
-export * from './implementation/util.js';
+export * from '../utils/util.js';
 export * from './MongoBucketStorage.js';
+export * from './MongoReportStorage.js';
+export * as test_utils from '../utils/test-utils.js';

package/src/utils/test-utils.ts

@@ -0,0 +1,57 @@
+import { mongo } from '@powersync/lib-service-mongodb';
+import { PowerSyncMongo } from '../storage/implementation/db.js';
+import { TestStorageOptions } from '@powersync/service-core';
+import { MongoReportStorage } from '../storage/MongoReportStorage.js';
+import { MongoBucketStorage } from '../storage/MongoBucketStorage.js';
+import { MongoSyncBucketStorageOptions } from '../storage/implementation/MongoSyncBucketStorage.js';
+
+export type MongoTestStorageOptions = {
+  url: string;
+  isCI: boolean;
+  internalOptions?: MongoSyncBucketStorageOptions;
+};
+
+export function mongoTestStorageFactoryGenerator(factoryOptions: MongoTestStorageOptions) {
+  return async (options?: TestStorageOptions) => {
+    const db = connectMongoForTests(factoryOptions.url, factoryOptions.isCI);
+
+    // None of the tests insert data into this collection, so it was never created
+    if (!(await db.db.listCollections({ name: db.bucket_parameters.collectionName }).hasNext())) {
+      await db.db.createCollection('bucket_parameters');
+    }
+
+    // Full migrations are not currently run for tests, so we manually create this
+    await db.createCheckpointEventsCollection();
+
+    if (!options?.doNotClear) {
+      await db.clear();
+    }
+
+    return new MongoBucketStorage(db, { slot_name_prefix: 'test_' }, factoryOptions.internalOptions);
+  };
+}
+
+export function mongoTestReportStorageFactoryGenerator(factoryOptions: MongoTestStorageOptions) {
+  return async (options?: TestStorageOptions) => {
+    const db = connectMongoForTests(factoryOptions.url, factoryOptions.isCI);
+
+    await db.createConnectionReportingCollection();
+
+    if (!options?.doNotClear) {
+      await db.clear();
+    }
+
+    return new MongoReportStorage(db);
+  };
+}
+
+export const connectMongoForTests = (url: string, isCI: boolean) => {
+  // Short timeout for tests, to fail fast when the server is not available.
+  // Slightly longer timeouts for CI, to avoid arbitrary test failures
+  const client = new mongo.MongoClient(url, {
+    connectTimeoutMS: isCI ? 15_000 : 5_000,
+    socketTimeoutMS: isCI ? 15_000 : 5_000,
+    serverSelectionTimeoutMS: isCI ? 15_000 : 2_500
+  });
+  return new PowerSyncMongo(client);
+};

package/src/{storage/implementation → utils}/util.ts

@@ -3,11 +3,9 @@ import * as crypto from 'crypto';
 import * as uuid from 'uuid';
 
 import { mongo } from '@powersync/lib-service-mongodb';
-import { BucketChecksum, PartialChecksum, PartialOrFullChecksum, storage, utils } from '@powersync/service-core';
-
-import { PowerSyncMongo } from './db.js';
-import { BucketDataDocument } from './models.js';
+import { storage, utils } from '@powersync/service-core';
 import { ServiceAssertionError } from '@powersync/lib-services-framework';
+import { BucketDataDocument } from '../storage/implementation/models.js';
 
 export function idPrefixFilter<T>(prefix: Partial<T>, rest: (keyof T)[]): mongo.Condition<T> {
   let filter = {
@@ -105,20 +103,6 @@ export function replicaIdToSubkey(table: bson.ObjectId, id: storage.ReplicaId):
   }
 }
 
-/**
- * Helper for unit tests
- */
-export const connectMongoForTests = (url: string, isCI: boolean) => {
-  // Short timeout for tests, to fail fast when the server is not available.
-  // Slightly longer timeouts for CI, to avoid arbitrary test failures
-  const client = new mongo.MongoClient(url, {
-    connectTimeoutMS: isCI ? 15_000 : 5_000,
-    socketTimeoutMS: isCI ? 15_000 : 5_000,
-    serverSelectionTimeoutMS: isCI ? 15_000 : 2_500
-  });
-  return new PowerSyncMongo(client);
-};
-
 export function setSessionSnapshotTime(session: mongo.ClientSession, time: bson.Timestamp) {
   // This is a workaround for the lack of direct support for snapshot reads in the MongoDB driver.
   if (!session.snapshotEnabled) {

package/src/utils/utils-index.ts

@@ -0,0 +1,2 @@
+export * as test_utils from './test-utils.js';
+export * from './util.js';

package/test/src/__snapshots__/connection-report-storage.test.ts.snap

@@ -0,0 +1,215 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Connection reporting storage > Should create a connection report if its after a day 1`] = `
+[
+  {
+    "client_id": "client_week",
+    "sdk": "powersync-js/1.24.5",
+    "user_agent": "powersync-js/1.21.0 powersync-web Firefox/141 linux",
+    "user_id": "user_week",
+  },
+  {
+    "client_id": "client_week",
+    "sdk": "powersync-js/1.24.5",
+    "user_agent": "powersync-js/1.21.0 powersync-web Firefox/141 linux",
+    "user_id": "user_week",
+  },
+]
+`;
+
+exports[`Connection reporting storage > Should delete rows older than specified range 1`] = `
+{
+  "sdks": [
+    {
+      "clients": 1,
+      "sdk": "powersync-dart/1.6.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.1",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.2",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.24.5",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "unknown",
+      "users": 1,
+    },
+  ],
+  "users": 5,
+}
+`;
+
+exports[`Connection reporting storage > Should update a connected connection report and make it disconnected 1`] = `
+[
+  {
+    "client_id": "client_three",
+    "sdk": "powersync-js/1.21.2",
+    "user_agent": "powersync-js/1.21.0 powersync-web Firefox/141 linux",
+    "user_id": "user_three",
+  },
+]
+`;
+
+exports[`Connection reporting storage > Should update a connection report if its within a day 1`] = `
+[
+  {
+    "client_id": "client_one",
+    "sdk": "powersync-dart/1.6.4",
+    "user_agent": "powersync-dart/1.6.4 Dart (flutter-web) Chrome/128 android",
+    "user_id": "user_one",
+  },
+]
+`;
+
+exports[`Report storage tests > Should show connection report data for user over the past day 1`] = `
+{
+  "sdks": [
+    {
+      "clients": 1,
+      "sdk": "powersync-dart/1.6.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.1",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "unknown",
+      "users": 1,
+    },
+  ],
+  "users": 3,
+}
+`;
+
+exports[`Report storage tests > Should show connection report data for user over the past month 1`] = `
+{
+  "sdks": [
+    {
+      "clients": 1,
+      "sdk": "powersync-dart/1.6.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.1",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.2",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.23.6",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.23.7",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.24.5",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "unknown",
+      "users": 1,
+    },
+  ],
+  "users": 7,
+}
+`;
+
+exports[`Report storage tests > Should show connection report data for user over the past week 1`] = `
+{
+  "sdks": [
+    {
+      "clients": 1,
+      "sdk": "powersync-dart/1.6.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.1",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.2",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.24.5",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "unknown",
+      "users": 1,
+    },
+  ],
+  "users": 5,
+}
+`;
+
+exports[`Report storage tests > Should show currently connected users 1`] = `
+{
+  "sdks": [
+    {
+      "clients": 1,
+      "sdk": "powersync-dart/1.6.4",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "powersync-js/1.21.1",
+      "users": 1,
+    },
+    {
+      "clients": 1,
+      "sdk": "unknown",
+      "users": 1,
+    },
+  ],
+  "users": 2,
+}
+`;

package/test/src/__snapshots__/storage.test.ts.snap

@@ -1,6 +1,22 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Mongo Sync Bucket Storage > empty storage metrics 1`] = `
+exports[`Mongo Sync Bucket Storage - Data > empty storage metrics 1`] = `
+{
+  "operations_size_bytes": 0,
+  "parameters_size_bytes": 0,
+  "replication_size_bytes": 0,
+}
+`;
+
+exports[`Mongo Sync Bucket Storage - split buckets > empty storage metrics 1`] = `
+{
+  "operations_size_bytes": 0,
+  "parameters_size_bytes": 0,
+  "replication_size_bytes": 0,
+}
+`;
+
+exports[`Mongo Sync Bucket Storage - split operations > empty storage metrics 1`] = `
 {
   "operations_size_bytes": 0,
   "parameters_size_bytes": 0,

package/test/src/connection-report-storage.test.ts

@@ -0,0 +1,133 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { INITIALIZED_MONGO_REPORT_STORAGE_FACTORY } from './util.js';
+import { register, ReportUserData } from '@powersync/service-core-tests';
+import { event_types } from '@powersync/service-types';
+import { MongoReportStorage } from '@module/storage/MongoReportStorage.js';
+
+const userData = register.REPORT_TEST_USERS;
+const dates = register.REPORT_TEST_DATES;
+const factory = await INITIALIZED_MONGO_REPORT_STORAGE_FACTORY();
+
+function removeVolatileFields(
+  connections: event_types.ClientConnection[]
+): Partial<event_types.ClientConnection & { _id: string }>[] {
+  return connections.map((sdk: Partial<event_types.ClientConnection & { _id: string }>) => {
+    const { _id, disconnected_at, connected_at, jwt_exp, ...rest } = sdk;
+    return {
+      ...rest
+    };
+  });
+}
+
+async function loadData(data: ReportUserData, factory: MongoReportStorage) {
+  await factory.db.connection_report_events.insertMany(Object.values(data));
+}
+
+async function deleteData(factory: MongoReportStorage) {
+  await factory.db.connection_report_events.deleteMany();
+}
+
+beforeAll(async () => {
+  await loadData(userData, factory);
+});
+afterAll(async () => {
+  await deleteData(factory);
+});
+
+describe('Report storage tests', async () => {
+  await register.registerReportTests(factory);
+});
+
+describe('Connection reporting storage', async () => {
+  it('Should create a connection report if its after a day', async () => {
+    const newConnectAt = new Date(
+      dates.now.getFullYear(),
+      dates.now.getMonth(),
+      dates.now.getDate() + 1,
+      dates.now.getHours()
+    );
+    const jwtExp = new Date(newConnectAt.getFullYear(), newConnectAt.getMonth(), newConnectAt.getDate() + 1);
+
+    await factory.reportClientConnection({
+      sdk: userData.user_week.sdk,
+      connected_at: newConnectAt,
+      jwt_exp: jwtExp,
+      client_id: userData.user_week.client_id,
+      user_id: userData.user_week.user_id,
+      user_agent: userData.user_week.user_agent
+    });
+
+    const connection = await factory.db.connection_report_events.find({ user_id: userData.user_week.user_id }).toArray();
+    expect(connection).toHaveLength(2);
+    const cleaned = removeVolatileFields(connection);
+    expect(cleaned).toMatchSnapshot();
+  });
+
+  it('Should update a connection report if its within a day', async () => {
+    const newConnectAt = new Date(
+      dates.now.getFullYear(),
+      dates.now.getMonth(),
+      dates.now.getDate(),
+      dates.now.getHours(),
+      dates.now.getMinutes() + 20
+    );
+    const jwtExp = new Date(newConnectAt.getFullYear(), newConnectAt.getMonth(), newConnectAt.getDate() + 1);
+    await factory.reportClientConnection({
+      sdk: userData.user_one.sdk,
+      connected_at: newConnectAt,
+      jwt_exp: jwtExp,
+      client_id: userData.user_one.client_id,
+      user_id: userData.user_one.user_id,
+      user_agent: userData.user_one.user_agent
+    });
+
+    const connection = await factory.db.connection_report_events
+      .find({ user_id: userData.user_one.user_id, client_id: userData.user_one.client_id })
+      .toArray();
+    expect(connection).toHaveLength(1);
+    expect(new Date(connection[0].connected_at)).toEqual(newConnectAt);
+    expect(new Date(connection[0].jwt_exp!)).toEqual(jwtExp);
+    expect(connection[0].disconnected_at).toBeUndefined();
+    const cleaned = removeVolatileFields(connection);
+    expect(cleaned).toMatchSnapshot();
+  });
+
+  it('Should update a connected connection report and make it disconnected', async () => {
+    const disconnectAt = new Date(
+      dates.now.getFullYear(),
+      dates.now.getMonth(),
+      dates.now.getDate(),
+      dates.now.getHours(),
+      dates.now.getMinutes() + 20
+    );
+    const jwtExp = new Date(disconnectAt.getFullYear(), disconnectAt.getMonth(), disconnectAt.getDate() + 1);
+
+    await factory.reportClientDisconnection({
+      disconnected_at: disconnectAt,
+      jwt_exp: jwtExp,
+      client_id: userData.user_three.client_id,
+      user_id: userData.user_three.user_id,
+      user_agent: userData.user_three.user_agent,
+      connected_at: userData.user_three.connected_at
+    });
+
+    const connection = await factory.db.connection_report_events.find({ user_id: userData.user_three.user_id }).toArray();
+    expect(connection).toHaveLength(1);
+    expect(new Date(connection[0].disconnected_at!)).toEqual(disconnectAt);
+    const cleaned = removeVolatileFields(connection);
+    expect(cleaned).toMatchSnapshot();
+  });
+
+  it('Should delete rows older than specified range', async () => {
+    await deleteData(factory);
+    await loadData(userData, factory);
+    await factory.deleteOldConnectionData({
+      date: dates.weekAgo
+    });
+    const connection = await factory.getClientConnectionReports({
+      start: dates.monthAgo,
+      end: dates.now
+    });
+    expect(connection).toMatchSnapshot();
+  });
+});