@powersync/service-core 1.23.3 → 1.25.0

package/src/sync/util.ts

@@ -2,6 +2,7 @@ import * as timers from 'timers/promises';
 
 import { SemaphoreInterface } from 'async-mutex';
 import { serialize } from 'bson';
+import { AbortError } from 'ix/aborterror.js';
 import * as util from '../util/util-index.js';
 import { RequestTracker } from './RequestTracker.js';
 
@@ -23,6 +24,17 @@ const DEFAULT_TOKEN_STREAM_OPTIONS: TokenStreamOptions = {
   expire_warning_period: 20_000
 };
 
+/**
+ * Recognize both ix's AbortError and native abort errors, which Node represents
+ * as DOMExceptions with the name "AbortError".
+ */
+export function isAbortError(error: unknown): boolean {
+  return (
+    error instanceof AbortError ||
+    (typeof error == 'object' && error != null && 'name' in error && error.name === 'AbortError')
+  );
+}
+
 /**
  * An iterator that periodically yields token and optionally keepalive events, and returns once the
  * provided token expiry is reached.

package/src/util/checkpointing.ts

@@ -3,12 +3,13 @@ import { WriteCheckpointBatcher } from './write-checkpoint-batcher.js';
 export interface CreateWriteCheckpointOptions {
   userId: string | undefined;
   clientId: string | undefined;
+  checkpointRequestId?: bigint;
   batcher: WriteCheckpointBatcher;
 }
 export async function createWriteCheckpoint(options: CreateWriteCheckpointOptions) {
   const full_user_id = checkpointUserId(options.userId, options.clientId);
 
-  return options.batcher.enqueue(full_user_id);
+  return options.batcher.enqueue(full_user_id, options.checkpointRequestId);
 }
 
 export function checkpointUserId(user_id: string | undefined, client_id: string | undefined) {

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/utils.ts

@@ -33,7 +33,7 @@ export interface PartialChecksum {
  */
 export type InternalOpId = bigint;
 
-export const ID_NAMESPACE = 'a396dd91-09fc-4017-a28d-3df722f651e9';
+export const ID_NAMESPACE = uuid.parse('a396dd91-09fc-4017-a28d-3df722f651e9');
 
 export function escapeIdentifier(identifier: string) {
   return `"${identifier.replace(/"/g, '""').replace(/\./g, '"."')}"`;

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);
+  });
+});