@powersync/service-core 0.0.0-dev-20260602073133 → 0.0.0-dev-20260909133214

package/test/src/PersistedSyncConfigContent.test.ts

@@ -0,0 +1,152 @@
+import {
+  DEFAULT_HYDRATION_STATE,
+  DEFAULT_TAG,
+  nodeSqlite,
+  PrecompiledSyncConfig,
+  serializeSyncPlan,
+  SqlSyncRules
+} from '@powersync/service-sync-rules';
+import * as sqlite from 'node:sqlite';
+import { describe, expect, test } from 'vitest';
+import {
+  parsePersistedSyncConfigContent,
+  SerializedSyncPlan,
+  updateSyncRulesFromConfig
+} from '../../src/storage/storage-index.js';
+
+const EVENT_QUERY = 'SELECT user_id, checkpoint FROM checkpoints WHERE active = true';
+const yamlWithoutEvents = `
+config:
+  edition: 3
+
+streams:
+  checkpoints:
+    query: SELECT * FROM checkpoints
+`;
+const yamlWithEvents = `${yamlWithoutEvents}
+event_definitions:
+  write_checkpoints:
+    payloads:
+      - ${EVENT_QUERY}
+`;
+
+describe('persisted compiled replication events', () => {
+  test('dual-writes additive compiled events and restores the compiled evaluator', () => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const compiled = update.config.plan!;
+    const originalEvent = compiled.plan.events![0];
+
+    expect(compiled.plan.version).toBeLessThanOrEqual(2);
+    expect(compiled.plan.events).toHaveLength(1);
+    expect(originalEvent.name).toBe('write_checkpoints');
+    expect(compiled.eventDescriptors).toEqual({ write_checkpoints: [EVENT_QUERY] });
+
+    const restored = restore(compiled);
+    expect(restored.config).toBeInstanceOf(PrecompiledSyncConfig);
+    expect(restored.config).not.toHaveProperty('eventDescriptors');
+    expect(restored.config.eventDefinitions).toHaveLength(1);
+    expect(restored.config.eventDefinitions[0].name).toBe('write_checkpoints');
+
+    const hydrated = restored.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    });
+    expect(
+      hydrated.eventDescriptors[0].evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1', checkpoint: 4n, active: 1 }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1', checkpoint: 4n } }], errors: [] });
+
+    // This represents what an older compiler sees after ignoring the additive plan.events field. The raw descriptor
+    // mirror is normalized into the compiled representation by the new loading boundary, retaining the legacy behavior
+    // of ignoring payload filters until the sync config is redeployed.
+    const { events: _ignored, ...planWithoutCompiledEvents } = compiled.plan;
+    const legacyView = restore({ ...compiled, plan: planWithoutCompiledEvents });
+    expect(legacyView.config).not.toHaveProperty('eventDescriptors');
+    expect(legacyView.config.eventDefinitions).toHaveLength(1);
+    expect(legacyView.config.eventDefinitions[0].name).toBe('write_checkpoints');
+    expect(legacyView.errors).toHaveLength(1);
+    expect(legacyView.errors[0]).toMatchObject({ type: 'warning' });
+
+    const legacyEvent = serializeSyncPlan((legacyView.config as PrecompiledSyncConfig).plan).events![0];
+    expect(legacyEvent.sourceQueries[0].variants[0].filters).toEqual([]);
+    expect(originalEvent.sourceQueries[0].variants[0].filters).not.toEqual([]);
+
+    const legacyHydrated = legacyView.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    });
+    expect(
+      legacyHydrated.eventDescriptors[0].evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1', checkpoint: 4n, active: 0 }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1', checkpoint: 4n } }], errors: [] });
+  });
+
+  test('restores raw event descriptors attached to version 1 and 2 plans', () => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithoutEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const legacy: SerializedSyncPlan = {
+      ...update.config.plan!,
+      eventDescriptors: { write_checkpoints: [EVENT_QUERY] }
+    };
+
+    expect(legacy.plan.version).toBeLessThanOrEqual(2);
+    const restored = restore(legacy);
+    expect(restored.config).not.toHaveProperty('eventDescriptors');
+    expect(restored.config.eventDefinitions).toHaveLength(1);
+    expect((restored.config as PrecompiledSyncConfig).plan.events).toMatchObject([
+      { name: 'write_checkpoints', sourceQueries: [{ sql: EVENT_QUERY }] }
+    ]);
+    expect(restored.errors).toHaveLength(1);
+    expect(restored.errors[0]).toMatchObject({ type: 'warning' });
+    expect(
+      serializeSyncPlan((restored.config as PrecompiledSyncConfig).plan).events![0].sourceQueries[0].variants[0].filters
+    ).toEqual([]);
+  });
+
+  /**
+   * Event SQL accepted by the legacy evaluator must remain loadable after an upgrade, even when its ignored filter uses
+   * expressions that the compiled event evaluator intentionally rejects for new deployments.
+   */
+  test.each([
+    ['request parameters', 'SELECT user_id FROM checkpoints WHERE user_id = request.user_id()'],
+    ['unsupported expressions', 'SELECT user_id FROM checkpoints WHERE active IN (1, 2)']
+  ])('loads legacy event descriptors without validating ignored %s', (_description, eventQuery) => {
+    const parsed = SqlSyncRules.fromYaml(yamlWithoutEvents, { defaultSchema: 'test_schema' });
+    const update = updateSyncRulesFromConfig(parsed);
+    const legacy: SerializedSyncPlan = {
+      ...update.config.plan!,
+      eventDescriptors: {
+        write_checkpoints: [eventQuery]
+      }
+    };
+
+    const restored = restore(legacy);
+    expect(restored.errors).toHaveLength(1);
+    expect(restored.errors[0]).toMatchObject({ type: 'warning' });
+
+    const event = restored.config.hydrate({
+      hydrationState: DEFAULT_HYDRATION_STATE,
+      sqlite: nodeSqlite(sqlite)
+    }).eventDescriptors[0];
+    expect(
+      event.evaluateRowWithErrors({
+        sourceTable: { connectionTag: DEFAULT_TAG, schema: 'test_schema', name: 'checkpoints' },
+        record: { user_id: 'user-1' }
+      })
+    ).toEqual({ results: [{ data: { user_id: 'user-1' } }], errors: [] });
+  });
+});
+
+function restore(compiledPlan: SerializedSyncPlan) {
+  return parsePersistedSyncConfigContent({
+    content: yamlWithEvents,
+    compiledPlan,
+    storageVersion: 1,
+    parseOptions: { defaultSchema: 'test_schema' }
+  });
+}

package/test/src/checksum_cache.test.ts

@@ -482,4 +482,26 @@ describe('checksum cache', function () {
     expect(await cache.getChecksums(123n, [{ bucket: 'test', source: DUMMY_SOURCE }])).toEqual([TEST_123]);
     expect(await cache.getChecksums(1234n, [{ bucket: 'test', source: DUMMY_SOURCE }])).toEqual([TEST_1234]);
   });
+
+  it('should refresh cached checksums after the configured TTL', async function () {
+    let lookups: FetchPartialBucketChecksum[][] = [];
+    const cache = new ChecksumCache({
+      fetchChecksums: async (batch) => {
+        lookups.push(batch);
+        return fetchTestChecksums(batch);
+      },
+      ttlMs: 1
+    });
+
+    expect(await cache.getChecksums(123n, [{ bucket: 'test', source: DUMMY_SOURCE }])).toEqual([TEST_123]);
+    expect(await cache.getChecksums(123n, [{ bucket: 'test', source: DUMMY_SOURCE }])).toEqual([TEST_123]);
+
+    await new Promise((resolve) => setTimeout(resolve, 1001)); // Needs to be >1s
+
+    expect(await cache.getChecksums(123n, [{ bucket: 'test', source: DUMMY_SOURCE }])).toEqual([TEST_123]);
+    expect(lookups.map(removeLookupSources)).toEqual([
+      [{ bucket: 'test', end: 123n }],
+      [{ bucket: 'test', end: 123n }]
+    ]);
+  });
 });

package/test/src/config.test.ts

@@ -70,6 +70,146 @@ describe('Config', () => {
     expect(config.api_parameters.max_buckets_per_connection).toBe(1);
   });
 
+  it('should resolve the storage default version', {}, async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+        default_storage_version: 4
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.storage.default_storage_version).toBe(4);
+  });
+
+  it.each([1, 1.5, 5])('should reject unsupported storage default version %s', async (defaultStorageVersion) => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+        default_storage_version: ${defaultStorageVersion}
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    await expect(
+      collector.collectConfig({
+        config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+      })
+    ).rejects.toThrow(`Storage version ${defaultStorageVersion} is not supported`);
+  });
+
+  it('should resolve checkpoint request retention config', {}, async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      api:
+        parameters:
+          checkpoint_request_retention_minutes: 15
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.api_parameters.checkpoint_request_retention_minutes).toBe(15);
+  });
+
+  it('should default checkpoint request retention to 60 minutes', {}, async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.api_parameters.checkpoint_request_retention_minutes).toBe(60);
+  });
+
+  it.each([0, -1, 1.5])('should reject checkpoint request retention of %s minutes', async (retentionMinutes) => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      api:
+        parameters:
+          checkpoint_request_retention_minutes: ${retentionMinutes}
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    await expect(
+      collector.collectConfig({
+        config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+      })
+    ).rejects.toThrow('api.parameters.checkpoint_request_retention_minutes must be a positive integer');
+  });
+
+  it('should resolve checksum cache TTL from API parameters', async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      api:
+        parameters:
+          bucket_count_cache_ttl_minutes: 15
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    const config = await collector.collectConfig({
+      config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+    });
+
+    expect(config.api_parameters.bucket_count_cache_ttl_minutes).toBe(15);
+  });
+
+  it('should reject fractional checksum cache TTL minutes', async () => {
+    const yamlConfig = /* yaml */ `
+      # PowerSync config
+      replication:
+        connections: []
+      storage:
+        type: mongodb
+      api:
+        parameters:
+          bucket_count_cache_ttl_minutes: 1.5
+    `;
+
+    const collector = new CompoundConfigCollector();
+
+    await expect(
+      collector.collectConfig({
+        config_base64: Buffer.from(yamlConfig, 'utf-8').toString('base64')
+      })
+    ).rejects.toThrow('api.parameters.bucket_count_cache_ttl_minutes must be a positive integer');
+  });
+
   it('should throw YAML validation error for invalid base64 config', {}, async () => {
     const yamlConfig = /* yaml */ `
       # PowerSync config
@@ -96,6 +236,7 @@ describe('Config', () => {
       storage:
         type: mongodb
       sync_config:
+        version_label: v6
         content: |
           config:
             edition: 2
@@ -112,6 +253,7 @@ describe('Config', () => {
 
     expect(result.sync_rules).toEqual({
       present: true,
+      version_label: 'v6',
       exit_on_error: true,
       content: expect.stringContaining('edition: 2')
     });

package/test/src/diagnostics.test.ts

@@ -1,6 +1,6 @@
 import { DiagnosticsOptions, getSyncRulesStatus } from '@/api/diagnostics.js';
 import { RouteAPI, SlotWalBudgetInfo } from '@/api/RouteAPI.js';
-import { BucketStorageFactory, PersistedSyncRules, storage } from '@/index.js';
+import { ParsedSyncConfigSet, storage } from '@/index.js';
 import { SqlSyncRules } from '@powersync/service-sync-rules';
 import { describe, expect, test } from 'vitest';
 
@@ -13,53 +13,59 @@ bucket_definitions:
       - SELECT id FROM test_table
 `;
 
-function makeSyncRulesContent(overrides?: { slot_name?: string }): storage.PersistedSyncRulesContent {
+function makeSyncRulesContent(overrides?: {
+  slot_name?: string;
+  version_label?: string;
+  status?: storage.PersistedSyncConfigStatus;
+}): storage.PersistedSyncConfigContent {
   // We don't implement the entire interface correctly here - just enough to test the diagnostics logic.
-  return {
-    id: 1,
-    slot_name: overrides?.slot_name ?? 'test_slot',
-    sync_rules_content: MINIMAL_SYNC_RULES,
-    compiled_plan: null,
-    active: true,
-    storageVersion: 1,
+  const status = overrides?.status ?? {
+    id: '1',
+    replicationStreamId: 1,
+    state: storage.SyncRuleState.ACTIVE,
     last_checkpoint_lsn: 'some_lsn',
     last_fatal_error: null,
     last_fatal_error_ts: null,
     last_keepalive_ts: new Date(),
-    last_checkpoint_ts: new Date(),
+    last_checkpoint_ts: new Date()
+  };
+
+  return {
+    replicationStreamId: 1,
+    syncConfigId: null,
+    replicationStreamName: overrides?.slot_name ?? 'test_slot',
+    sync_rules_content: MINIMAL_SYNC_RULES,
+    compiled_plan: null,
+    storageVersion: 1,
+    syncConfigState: status.state,
+    version_label: overrides?.version_label,
     parsed(options?: any) {
       const syncRules = SqlSyncRules.fromYaml(MINIMAL_SYNC_RULES, {
         ...options,
         defaultSchema: 'public'
       });
       return {
-        syncConfigWithErrors: syncRules
-      } as PersistedSyncRules;
+        syncConfigs: [syncRules]
+      } as ParsedSyncConfigSet;
     },
-    lock() {
-      throw new Error('Not implemented in mock');
-    },
-    current_lock: null,
     logger: null as any,
     asUpdateOptions: null as any,
-    getStorageConfig: null as any
-  } as storage.PersistedSyncRulesContent;
+    getStorageConfig: null as any,
+    async getSyncConfigStatus() {
+      return status;
+    }
+  } as storage.PersistedSyncConfigContent;
 }
 
-function makeBucketStorage() {
+function makeSystemStorage() {
   return {
-    getInstance() {
+    async getStatus() {
       return {
-        async getStatus() {
-          return {
-            snapshot_done: true,
-            checkpoint_lsn: 'some_lsn',
-            active: true
-          };
-        }
+        snapshotDone: true,
+        resumeLsn: 'some_lsn'
       };
     }
-  } as unknown as BucketStorageFactory;
+  } as storage.SyncRulesBucketStorage;
 }
 
 function makeRouteAPI(walBudget?: SlotWalBudgetInfo | undefined): RouteAPI {
@@ -92,7 +98,8 @@ function makeRouteAPI(walBudget?: SlotWalBudgetInfo | undefined): RouteAPI {
 const OPTIONS: DiagnosticsOptions = {
   live_status: true,
   check_connection: true,
-  include_content: false
+  include_content: false,
+  active: true
 };
 
 describe('getSyncRulesStatus WAL budget warnings', () => {
@@ -102,7 +109,7 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
       safe_wal_size: 4 * GB,
       max_slot_wal_keep_size: 10 * GB
     });
-    const result = await getSyncRulesStatus(makeBucketStorage(), api, makeSyncRulesContent(), OPTIONS);
+    const result = await getSyncRulesStatus(api, makeSyncRulesContent(), OPTIONS, makeSystemStorage());
     const walWarnings = result!.errors.filter((e) => e.message.includes('WAL budget'));
     expect(walWarnings).toHaveLength(1);
     expect(walWarnings[0].level).toBe('warning');
@@ -115,7 +122,7 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
       safe_wal_size: 8 * GB,
       max_slot_wal_keep_size: 10 * GB
     });
-    const result = await getSyncRulesStatus(makeBucketStorage(), api, makeSyncRulesContent(), OPTIONS);
+    const result = await getSyncRulesStatus(api, makeSyncRulesContent(), OPTIONS, makeSystemStorage());
     const walWarnings = result!.errors.filter((e) => e.message.includes('WAL budget'));
     expect(walWarnings).toHaveLength(0);
   });
@@ -126,7 +133,7 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
       safe_wal_size: -2.4 * GB,
       max_slot_wal_keep_size: 1 * 1024 * 1024 // 1MB
     });
-    const result = await getSyncRulesStatus(makeBucketStorage(), api, makeSyncRulesContent(), OPTIONS);
+    const result = await getSyncRulesStatus(api, makeSyncRulesContent(), OPTIONS, makeSystemStorage());
     const walWarnings = result!.errors.filter((e) => e.message.includes('WAL budget'));
     expect(walWarnings).toHaveLength(1);
     expect(walWarnings[0].message).toContain('0%');
@@ -137,7 +144,7 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
     const api = makeRouteAPI({
       wal_status: 'lost'
     });
-    const result = await getSyncRulesStatus(makeBucketStorage(), api, makeSyncRulesContent(), OPTIONS);
+    const result = await getSyncRulesStatus(api, makeSyncRulesContent(), OPTIONS, makeSystemStorage());
     const walErrors = result!.errors.filter(
       (e) => e.message.includes('WAL budget') || e.message.includes('PSYNC_S1146')
     );
@@ -146,10 +153,56 @@ describe('getSyncRulesStatus WAL budget warnings', () => {
 
   test('no WAL error when getSlotWalBudget is not defined', async () => {
     const api = makeRouteAPI();
-    const result = await getSyncRulesStatus(makeBucketStorage(), api, makeSyncRulesContent(), OPTIONS);
+    const result = await getSyncRulesStatus(api, makeSyncRulesContent(), OPTIONS, makeSystemStorage());
     const walErrors = result!.errors.filter(
       (e) => e.message.includes('WAL budget') || e.message.includes('PSYNC_S1146')
     );
     expect(walErrors).toHaveLength(0);
   });
+
+  test('uses sync config status for status-derived diagnostics fields', async () => {
+    const configStatus: storage.PersistedSyncConfigStatus = {
+      id: 'config-a',
+      replicationStreamId: 1,
+      state: storage.SyncRuleState.ACTIVE,
+      last_checkpoint_lsn: 'config_lsn',
+      last_fatal_error: 'config failed',
+      last_fatal_error_ts: new Date('2026-01-01T00:00:00.000Z'),
+      last_keepalive_ts: new Date('2026-01-01T00:01:00.000Z'),
+      last_checkpoint_ts: new Date('2026-01-01T00:02:00.000Z')
+    };
+    const result = await getSyncRulesStatus(
+      makeRouteAPI(),
+      makeSyncRulesContent({ status: configStatus }),
+      OPTIONS,
+      makeSystemStorage()
+    );
+
+    expect(result!.connections[0].last_checkpoint_ts).toBe('2026-01-01T00:02:00.000Z');
+    expect(result!.connections[0].last_keepalive_ts).toBe('2026-01-01T00:01:00.000Z');
+    expect(result!.errors.some((error) => error.message == 'config failed')).toBe(true);
+  });
+
+  test('includes the sync config version label', async () => {
+    const result = await getSyncRulesStatus(
+      makeRouteAPI(),
+      makeSyncRulesContent({ version_label: 'v6' }),
+      OPTIONS,
+      makeSystemStorage()
+    );
+
+    expect(result!.version_label).toBe('v6');
+  });
+
+  test('includes the sync config version label when parsing fails', async () => {
+    const content = makeSyncRulesContent({ version_label: 'v6' });
+    content.parsed = () => {
+      throw new Error('Invalid sync config');
+    };
+
+    const result = await getSyncRulesStatus(makeRouteAPI(), content, OPTIONS, makeSystemStorage());
+
+    expect(result!.version_label).toBe('v6');
+    expect(result!.errors).toEqual([expect.objectContaining({ level: 'fatal', message: 'Invalid sync config' })]);
+  });
 });

package/test/src/module-loader.test.ts

@@ -1,4 +1,11 @@
-import { AbstractModule, loadModules, ServiceContextContainer, TearDownOptions } from '@/index.js';
+import {
+  AbstractModule,
+  loadModules,
+  ModuleManager,
+  ServiceContextContainer,
+  storage,
+  TearDownOptions
+} from '@/index.js';
 import { describe, expect, it } from 'vitest';
 
 interface MockConfig {
@@ -27,6 +34,19 @@ class MockPostgresStorageModule extends AbstractModule {
   async initialize(context: ServiceContextContainer): Promise<void> {}
   async teardown(options: TearDownOptions): Promise<void> {}
 }
+class RecordingModule extends AbstractModule {
+  teardownOptions: TearDownOptions | undefined;
+
+  constructor(name: string) {
+    super({ name });
+  }
+
+  async initialize(context: ServiceContextContainer): Promise<void> {}
+
+  async teardown(options: TearDownOptions): Promise<void> {
+    this.teardownOptions = options;
+  }
+}
 const mockLoaders = {
   connection: {
     mysql: async () => {
@@ -99,4 +119,16 @@ describe('module loader', () => {
 
     await expect(loadModules(config as any, loaders)).rejects.toThrowError('Failed to load MySQL module');
   });
+
+  it('passes replication streams through teardown options', async () => {
+    const module = new RecordingModule('RecordingModule');
+    const moduleManager = new ModuleManager();
+    const replicationStreams = [{ replicationStreamId: 1 }] as storage.PersistedReplicationStream[];
+
+    moduleManager.register([module]);
+    await moduleManager.tearDown({ replicationStreams, syncRules: replicationStreams });
+
+    expect(module.teardownOptions?.replicationStreams).toBe(replicationStreams);
+    expect(module.teardownOptions?.syncRules).toBe(replicationStreams);
+  });
 });