@powersync/service-core 1.23.3 → 1.24.0

package/src/util/config/compound-config-collector.ts

@@ -6,6 +6,7 @@ import { Base64ConfigCollector } from './collectors/impl/base64-config-collector
 import { FallbackConfigCollector } from './collectors/impl/fallback-config-collector.js';
 import { FileSystemConfigCollector } from './collectors/impl/filesystem-config-collector.js';
 import {
+  DEFAULT_CHECKPOINT_REQUEST_RETENTION_MINUTES,
   DEFAULT_CHECKSUM_CACHE_TTL_MINUTES,
   DEFAULT_MAX_BUCKETS_PER_CONNECTION,
   DEFAULT_MAX_CONCURRENT_CONNECTIONS,
@@ -195,6 +196,9 @@ export class CompoundConfigCollector {
           baseConfig.api?.parameters?.max_concurrent_connections ?? DEFAULT_MAX_CONCURRENT_CONNECTIONS,
         max_data_fetch_concurrency:
           baseConfig.api?.parameters?.max_data_fetch_concurrency ?? DEFAULT_MAX_DATA_FETCH_CONCURRENCY,
+        checkpoint_request_retention_minutes: normalizeCheckpointRequestRetentionMinutes(
+          baseConfig.api?.parameters?.checkpoint_request_retention_minutes
+        ),
         bucket_count_cache_ttl_minutes: normalizeChecksumCacheTtlMinutes(
           baseConfig.api?.parameters?.bucket_count_cache_ttl_minutes
         )
@@ -261,3 +265,11 @@ function normalizeChecksumCacheTtlMinutes(ttlMinutes: number | undefined): numbe
   }
   return normalized;
 }
+
+function normalizeCheckpointRequestRetentionMinutes(retentionMinutes: number | undefined): number {
+  const normalized = retentionMinutes ?? DEFAULT_CHECKPOINT_REQUEST_RETENTION_MINUTES;
+  if (!Number.isFinite(normalized) || !Number.isInteger(normalized) || normalized < 1) {
+    throw new Error('api.parameters.checkpoint_request_retention_minutes must be a positive integer');
+  }
+  return normalized;
+}

package/src/util/config/defaults.ts

@@ -3,4 +3,5 @@ export const DEFAULT_MAX_CONCURRENT_CONNECTIONS = 200;
 export const DEFAULT_MAX_DATA_FETCH_CONCURRENCY = 10;
 export const DEFAULT_MAX_BUCKETS_PER_CONNECTION = 1000;
 export const DEFAULT_MAX_PARAMETER_QUERY_RESULTS = 1000;
+export const DEFAULT_CHECKPOINT_REQUEST_RETENTION_MINUTES = 60;
 export const DEFAULT_CHECKSUM_CACHE_TTL_MINUTES = 1 * 60;

package/src/util/config/types.ts

@@ -53,6 +53,7 @@ export type ResolvedPowerSyncConfig = {
     max_data_fetch_concurrency: number;
     max_buckets_per_connection: number;
     max_parameter_query_results: number;
+    checkpoint_request_retention_minutes: number;
     bucket_count_cache_ttl_minutes: number;
   };
 

package/src/util/write-checkpoint-batcher.ts

@@ -1,6 +1,11 @@
 import { ErrorCode, ServiceAssertionError, ServiceError } from '@powersync/lib-services-framework';
 import { RouteAPI } from '../api/RouteAPI.js';
-import { BucketStorageFactory, SyncRulesBucketStorage } from '../storage/storage-index.js';
+import {
+  BucketStorageFactory,
+  CreateManagedWriteCheckpointsResult,
+  ManagedWriteCheckpointOptions,
+  SyncRulesBucketStorage
+} from '../storage/storage-index.js';
 
 // Keep up to three source-head/storage batches executing concurrently under load.
 // There is intentionally no explicit batch-size cap here: the HTTP request queue
@@ -16,6 +21,7 @@ export interface CreateWriteCheckpointResult {
 
 interface QueuedWriteCheckpoint {
   userId: string;
+  checkpointRequestId: bigint | undefined;
   resolvers: PromiseWithResolvers<CreateWriteCheckpointResult>;
 }
 
@@ -29,9 +35,9 @@ export class WriteCheckpointBatcher {
     private readonly getStorage: () => BucketStorageFactory
   ) {}
 
-  enqueue(userId: string): Promise<CreateWriteCheckpointResult> {
+  enqueue(userId: string, checkpointRequestId?: bigint): Promise<CreateWriteCheckpointResult> {
     const resolvers = Promise.withResolvers<CreateWriteCheckpointResult>();
-    this.pending.push({ userId, resolvers });
+    this.pending.push({ userId, checkpointRequestId, resolvers });
     this.schedulePump();
     return resolvers.promise;
   }
@@ -74,10 +80,18 @@ export class WriteCheckpointBatcher {
         throw new ServiceError(ErrorCode.PSYNC_S2302, `Cannot create Write Checkpoint since no sync config is active.`);
       }
 
+      // The source adapter reads the head, hands it to this callback to persist the
+      // write-checkpoint mapping, then forces a source marker only when storage
+      // reports an advance. Keeping the marker inside the callback means it is
+      // causally ordered after the head within a single source session.
       const { writeCheckpoints, currentCheckpoint } = await this.getAPI().createReplicationHead(
         async (currentCheckpoint) => {
-          const writeCheckpoints = await this.createBatchWriteCheckpoints(syncBucketStorage, batch, currentCheckpoint);
-          return { writeCheckpoints, currentCheckpoint };
+          const { writeCheckpoints, shouldAdvance } = await this.createBatchWriteCheckpoints(
+            syncBucketStorage,
+            batch,
+            currentCheckpoint
+          );
+          return { response: { writeCheckpoints, currentCheckpoint }, shouldAdvance };
         }
       );
 
@@ -111,12 +125,18 @@ export class WriteCheckpointBatcher {
     syncBucketStorage: SyncRulesBucketStorage,
     batch: QueuedWriteCheckpoint[],
     currentCheckpoint: string
-  ) {
+  ): Promise<CreateManagedWriteCheckpointsResult> {
     return syncBucketStorage.createManagedWriteCheckpoints(
-      batch.map((request) => ({
-        user_id: request.userId,
-        heads: { '1': currentCheckpoint }
-      }))
+      batch.map((request) => {
+        const checkpoint: ManagedWriteCheckpointOptions = {
+          user_id: request.userId,
+          heads: { '1': currentCheckpoint }
+        };
+        if (request.checkpointRequestId != null) {
+          checkpoint.checkpoint_request_id = request.checkpointRequestId;
+        }
+        return checkpoint;
+      })
     );
   }
 }

package/test/src/AbstractReplicator.test.ts

@@ -0,0 +1,147 @@
+import { AbstractReplicationJob } from '@/replication/AbstractReplicationJob.js';
+import { AbstractReplicator, AbstractReplicatorOptions, CreateJobOptions } from '@/replication/AbstractReplicator.js';
+import { PersistedReplicationStream } from '@/storage/PersistedReplicationStream.js';
+import { SyncRulesBucketStorage } from '@/storage/SyncRulesBucketStorage.js';
+import { describe, expect, it, vi } from 'vitest';
+
+class TestReplicator extends AbstractReplicator {
+  constructor(
+    private readonly cleanup: (storage: SyncRulesBucketStorage) => Promise<void>,
+    options: AbstractReplicatorOptions = {
+      id: 'test',
+      storageEngine: {} as AbstractReplicatorOptions['storageEngine'],
+      metricsEngine: {} as AbstractReplicatorOptions['metricsEngine'],
+      syncRuleProvider: {} as AbstractReplicatorOptions['syncRuleProvider'],
+      rateLimiter: {} as AbstractReplicatorOptions['rateLimiter']
+    }
+  ) {
+    super(options);
+  }
+
+  createJob(_options: CreateJobOptions): AbstractReplicationJob {
+    throw new Error('Not implemented');
+  }
+
+  cleanUp(storage: SyncRulesBucketStorage): Promise<void> {
+    return this.cleanup(storage);
+  }
+
+  async testConnection() {
+    return { connectionDescription: 'test' };
+  }
+
+  terminateStoppedStream(
+    replicationStream: PersistedReplicationStream,
+    syncRuleStorage: SyncRulesBucketStorage
+  ): Promise<void> {
+    return this.terminateStoppedReplicationStream(replicationStream, syncRuleStorage);
+  }
+
+  addClearingJob(replicationStreamId: number, promise: Promise<void>): void {
+    this.clearingJobs.set(replicationStreamId, promise);
+  }
+
+  get heartbeatIntervalNanosForTest(): bigint | null {
+    return (this as any).heartbeatIntervalNanos;
+  }
+}
+
+describe('AbstractReplicator heartbeat interval', () => {
+  const options: AbstractReplicatorOptions = {
+    id: 'test',
+    storageEngine: {} as AbstractReplicatorOptions['storageEngine'],
+    metricsEngine: {} as AbstractReplicatorOptions['metricsEngine'],
+    syncRuleProvider: {} as AbstractReplicatorOptions['syncRuleProvider'],
+    rateLimiter: {} as AbstractReplicatorOptions['rateLimiter']
+  };
+
+  it.each([undefined, null])('uses the default for %s', (heartbeatIntervalSeconds) => {
+    const replicator = new TestReplicator(async () => {}, { ...options, heartbeatIntervalSeconds });
+
+    expect(replicator.heartbeatIntervalNanosForTest).toBe(60_000_000_000n);
+  });
+
+  it('disables the heartbeat interval with 0', () => {
+    const replicator = new TestReplicator(async () => {}, { ...options, heartbeatIntervalSeconds: 0 });
+
+    expect(replicator.heartbeatIntervalNanosForTest).toBeNull();
+  });
+
+  it('converts a positive heartbeat interval to nanoseconds', () => {
+    const replicator = new TestReplicator(async () => {}, { ...options, heartbeatIntervalSeconds: 5 });
+
+    expect(replicator.heartbeatIntervalNanosForTest).toBe(5_000_000_000n);
+  });
+});
+
+describe('AbstractReplicator stopped stream cleanup', () => {
+  it('holds the replication stream lock across source and storage cleanup', async () => {
+    const calls: string[] = [];
+    const release = vi.fn(async () => {
+      calls.push('release');
+    });
+    const replicationStream = {
+      async lock() {
+        calls.push('lock');
+        return { sync_rules_id: 1, release };
+      }
+    } as unknown as PersistedReplicationStream;
+    const syncRuleStorage = {
+      logger: { info: vi.fn() },
+      async terminate() {
+        calls.push('terminate');
+      }
+    } as unknown as SyncRulesBucketStorage;
+    const replicator = new TestReplicator(async () => {
+      calls.push('cleanup');
+    });
+
+    await replicator.terminateStoppedStream(replicationStream, syncRuleStorage);
+
+    expect(calls).toEqual(['lock', 'cleanup', 'terminate', 'release']);
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('releases the replication stream lock when cleanup fails', async () => {
+    const cleanupError = new Error('cleanup failed');
+    const release = vi.fn(async () => {});
+    const replicationStream = {
+      async lock() {
+        return { sync_rules_id: 1, release };
+      }
+    } as unknown as PersistedReplicationStream;
+    const terminate = vi.fn(async () => {});
+    const syncRuleStorage = {
+      logger: { info: vi.fn() },
+      terminate
+    } as unknown as SyncRulesBucketStorage;
+    const replicator = new TestReplicator(async () => {
+      throw cleanupError;
+    });
+
+    await expect(replicator.terminateStoppedStream(replicationStream, syncRuleStorage)).rejects.toBe(cleanupError);
+
+    expect(terminate).not.toHaveBeenCalled();
+    expect(release).toHaveBeenCalledOnce();
+  });
+
+  it('waits for stopped stream cleanup when stopping', async () => {
+    let finishCleanup: () => void;
+    const cleanup = new Promise<void>((resolve) => {
+      finishCleanup = resolve;
+    });
+    const replicator = new TestReplicator(async () => {});
+    replicator.addClearingJob(1, cleanup);
+
+    let stopped = false;
+    const stop = replicator.stop().then(() => {
+      stopped = true;
+    });
+    await Promise.resolve();
+    expect(stopped).toBe(false);
+
+    finishCleanup!();
+    await stop;
+    expect(stopped).toBe(true);
+  });
+});

package/test/src/config.test.ts

@@ -70,6 +70,66 @@ describe('Config', () => {
     expect(config.api_parameters.max_buckets_per_connection).toBe(1);
   });
 
+  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

package/test/src/routes/checkpointing.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CheckpointRequestPayload, checkpointRequest } from '../../../src/routes/endpoints/checkpointing.js';
+
+describe('checkpoint request route', () => {
+  const payload = (checkpointRequestId: string | number | bigint) => ({
+    client_id: 'client-a',
+    checkpoint_request_id: checkpointRequestId
+  });
+
+  it.each([
+    ['safe JSON number', 1, 1n],
+    ['max int64 string', '9223372036854775807', 9_223_372_036_854_775_807n],
+    ['bigint value', 42n, 42n]
+  ])('decodes a positive int64 checkpoint request id from a %s', (_description, checkpointRequestId, expected) => {
+    expect(CheckpointRequestPayload.decode(payload(checkpointRequestId)).checkpoint_request_id).toEqual(expected);
+  });
+
+  it.each([1, '9223372036854775807'])(
+    'accepts API payloads with positive int64 checkpoint request id %s',
+    (checkpointRequestId) => {
+      expect(checkpointRequest.validator!.validate(payload(checkpointRequestId)).valid).toBe(true);
+    }
+  );
+
+  it.each([
+    0,
+    -1,
+    '0',
+    '-1',
+    '9223372036854775808',
+    '999999999999999999999999999999999999999999999',
+    Number.MAX_SAFE_INTEGER + 1
+  ])('rejects invalid API checkpoint request id %s', (checkpointRequestId) => {
+    expect(checkpointRequest.validator!.validate(payload(checkpointRequestId)).valid).toBe(false);
+  });
+
+  it('returns the stored checkpoint request id from the checkpoint request route', async () => {
+    const writeCheckpointBatcher = {
+      enqueue: vi.fn(async () => ({ replicationHead: 'head-1', writeCheckpoint: '43' }))
+    };
+
+    await expect(
+      checkpointRequest.handler({
+        context: {
+          token_payload: { userIdString: 'user-a' },
+          service_context: { writeCheckpointBatcher }
+        },
+        params: payload(42)
+      } as any)
+    ).resolves.toEqual({ checkpoint_request_id: '43' });
+
+    expect(writeCheckpointBatcher.enqueue).toHaveBeenCalledWith('user-a/client-a', 42n);
+  });
+});

package/test/src/sync/BucketChecksumState.test.ts

@@ -1183,7 +1183,7 @@ streams:
       ).rejects.toThrow('Too many buckets: 60 (limit of 50');
 
       // Verify error log includes breakdown
-      expect(errorMessages[0]).toContain('Buckets by definition:');
+      expect(errorMessages[0]).toContain('(limit of 50)\nBuckets by sync stream:');
       expect(errorMessages[0]).toContain('projects: 30');
       expect(errorMessages[0]).toContain('tasks: 20');
       expect(errorMessages[0]).toContain('comments: 10');
@@ -1197,15 +1197,60 @@ streams:
       });
     });
 
-    test('limits bucket breakdown to top 10 definitions', async () => {
-      // Create sync streams with 15 different definitions with dynamic parameters
+    test('labels the bucket breakdown as bucket definitions for legacy sync rules', async () => {
+      const legacySyncRules = SqlSyncRules.fromYaml(
+        `
+bucket_definitions:
+  projects:
+    parameters: SELECT id FROM projects WHERE user_id = request.user_id()
+    data: []
+    `,
+        { defaultSchema: 'public' }
+      ).config.hydrate({ hydrationState: versionedHydrationState(5), sqlite: nodeSqlite(sqlite) });
+
+      const storage = new MockBucketChecksumStateStorage();
+      const errorMessages: string[] = [];
+      const state = new BucketChecksumState({
+        syncContext: new SyncContext({
+          maxBuckets: 50,
+          maxParameterQueryResults: 100,
+          maxDataFetchConcurrency: 10
+        }),
+        tokenPayload: new JwtPayload({ sub: 'u1' }),
+        syncRequest,
+        syncRules: legacySyncRules,
+        bucketStorage: storage,
+        logger: {
+          info: () => {},
+          error: (message: string) => errorMessages.push(message),
+          warn: () => {},
+          debug: () => {}
+        } as any
+      });
+
+      await expect(
+        state.buildNextCheckpointLine({
+          base: storage.makeCheckpoint(1n, (lookups) => [
+            { lookup: lookups[0], rows: Array.from({ length: 60 }, (_, id) => ({ id })) }
+          ]),
+          writeCheckpoint: null,
+          update: CHECKPOINT_INVALIDATE_ALL
+        })
+      ).rejects.toThrow('Too many buckets: 60 (limit of 50)');
+
+      expect(errorMessages[0]).toContain('(limit of 50)\nBuckets by bucket definition:');
+      expect(errorMessages[0]).toContain('projects: 60');
+    });
+
+    test('limits bucket breakdown to top 100 sync streams', async () => {
+      // Create 105 sync streams with dynamic parameters.
       let yamlDefinitions = `
 config:
   edition: 3
 
 streams:
 `;
-      for (let i = 1; i <= 15; i++) {
+      for (let i = 1; i <= 105; i++) {
         yamlDefinitions += `  def${i}:\n`;
         yamlDefinitions += `    auto_subscribe: true\n`;
         yamlDefinitions += `    query: SELECT * FROM tbl WHERE b = auth.parameter('${i}')\n`;
@@ -1229,7 +1274,7 @@ streams:
       };
 
       const smallContext = new SyncContext({
-        maxBuckets: 10,
+        maxBuckets: 100,
         maxParameterQueryResults: 10,
         maxDataFetchConcurrency: 10
       });
@@ -1238,7 +1283,7 @@ streams:
         syncContext: smallContext,
         tokenPayload: new JwtPayload({
           sub: 'u1',
-          ...Object.fromEntries(Array.from({ length: 30 }, (_, i) => [i.toString(), BigInt(i)]))
+          ...Object.fromEntries(Array.from({ length: 106 }, (_, i) => [i.toString(), BigInt(i)]))
         }),
         syncRequest,
         syncRules: SYNC_RULES_MANY,
@@ -1252,15 +1297,16 @@ streams:
           writeCheckpoint: null,
           update: CHECKPOINT_INVALIDATE_ALL
         })
-      ).rejects.toThrow('Too many buckets: 15 (limit of 10)');
+      ).rejects.toThrow('Too many buckets: 105 (limit of 100)');
 
-      // Verify only top 10 are shown
+      // Verify only the first 100 are shown.
       const errorMessage = errorMessages[0];
-      expect(errorMessage).toContain('... and 5 more results from 5 definitions');
+      expect(errorMessage).toContain('Buckets by sync stream:');
+      expect(errorMessage).toContain('... and 5 more buckets from 5 sync streams');
 
-      // Count how many definitions are listed (should be exactly 10)
+      // Count how many sync streams are listed (should be exactly 100).
       const defMatches = errorMessage.match(/def\d+:/g);
-      expect(defMatches?.length).toBe(10);
+      expect(defMatches?.length).toBe(100);
     });
   });
 });

package/test/src/sync/util.test.ts

@@ -1,7 +1,19 @@
-import { acquireSemaphoreAbortable } from '@/index.js';
+import { acquireSemaphoreAbortable, isAbortError } from '@/index.js';
 import { Semaphore, SemaphoreInterface } from 'async-mutex';
+import { AbortError } from 'ix/aborterror.js';
 import { describe, expect, test, vi } from 'vitest';
 
+describe('isAbortError', () => {
+  test('recognizes ix and native abort errors', () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    expect(isAbortError(new AbortError())).toBe(true);
+    expect(isAbortError(controller.signal.reason)).toBe(true);
+    expect(isAbortError(new Error('not aborted'))).toBe(false);
+  });
+});
+
 describe('acquireSemaphoreAbortable', () => {
   test('can acquire', async () => {
     const semaphore = new Semaphore(1);