@powersync/service-core 1.20.2 → 1.20.4

package/src/replication/ReplicationLagTracker.ts

@@ -0,0 +1,86 @@
+import { RollingBucketMax } from '../metrics/RollingBucketMax.js';
+
+/**
+ * Tracks replication lag across the current in-flight transaction and a rolling
+ * max of recently observed lag values.
+ */
+export class ReplicationLagTracker {
+  private readonly rollingReplicationLag = new RollingBucketMax();
+  private _oldestUncommittedChange: Date | null = null;
+  private _isStartingReplication = true;
+
+  /**
+   * The oldest source timestamp still part of the current in-flight work.
+   */
+  get oldestUncommittedChange(): Date | null {
+    return this._oldestUncommittedChange;
+  }
+
+  /**
+   * True until replication has seen its first completed commit or equivalent keepalive.
+   */
+  get isStartingReplication(): boolean {
+    return this._isStartingReplication;
+  }
+
+  /**
+   * Registers the first source timestamp for the current in-flight work,
+   * for example the start of a transaction
+   */
+  trackUncommittedChange(timestamp: Date | null | undefined): void {
+    if (this._oldestUncommittedChange == null && timestamp != null) {
+      this._oldestUncommittedChange = timestamp;
+    }
+  }
+
+  /**
+   * Clears the current in-flight timestamp without changing startup state.
+   */
+  clearUncommittedChange(): void {
+    this._oldestUncommittedChange = null;
+  }
+
+  /**
+   * Marks replication as started even if no committed transaction lag was recorded.
+   */
+  markStarted(): void {
+    this._isStartingReplication = false;
+  }
+
+  /**
+   * Mark the current pending changes as "committed".
+   *
+   * Records the current in-flight lag into the rolling window and clears it.
+   * The current lag is calculated as the differnence between current time and the oldest change,
+   * as marked by trackUncommittedChange.
+   */
+  markCommitted(timestampMs = Date.now()): void {
+    if (this._oldestUncommittedChange != null) {
+      this.rollingReplicationLag.report(timestampMs - this._oldestUncommittedChange.getTime(), timestampMs);
+    }
+    this.clearUncommittedChange();
+    this.markStarted();
+  }
+
+  /**
+   * Returns the lag for the current in-flight work.
+   *
+   * 0 if idle (no pending changes to replicate).
+   *
+   * undefined when replication is still starting up.
+   */
+  getCurrentLagMillis(timestampMs = Date.now()): number | undefined {
+    if (this._oldestUncommittedChange == null) {
+      return this._isStartingReplication ? undefined : 0;
+    }
+    return timestampMs - this._oldestUncommittedChange.getTime();
+  }
+
+  /**
+   * Returns the rolling lag metric value, including the current in-flight lag when present.
+   */
+  getLagMillis(timestampMs = Date.now()): number | undefined {
+    this.rollingReplicationLag.report(this.getCurrentLagMillis(timestampMs), timestampMs);
+    return this.rollingReplicationLag.getRollingMax(timestampMs);
+  }
+}

package/src/replication/replication-index.ts

@@ -1,6 +1,7 @@
 export * from './AbstractReplicationJob.js';
 export * from './AbstractReplicator.js';
 export * from './ErrorRateLimiter.js';
+export * from './ReplicationLagTracker.js';
 export * from './ReplicationEngine.js';
 export * from './ReplicationModule.js';
 export * from './replication-metrics.js';

package/test/src/ReplicationLagTracker.test.ts

@@ -0,0 +1,53 @@
+import { ReplicationLagTracker } from '@/replication/ReplicationLagTracker.js';
+import { describe, expect, it } from 'vitest';
+
+describe('ReplicationLagTracker', () => {
+  it('returns undefined before replication has started', () => {
+    const tracker = new ReplicationLagTracker();
+
+    expect(tracker.getLagMillis(0)).toBeUndefined();
+  });
+
+  it('tracks the oldest in-flight change and returns current lag', () => {
+    const tracker = new ReplicationLagTracker();
+
+    tracker.trackUncommittedChange(new Date(1_000));
+    tracker.trackUncommittedChange(new Date(2_000));
+
+    expect(tracker.oldestUncommittedChange?.getTime()).toBe(1_000);
+    expect(tracker.getCurrentLagMillis(4_000)).toBe(3_000);
+    expect(tracker.getLagMillis(4_000)).toBe(3_000);
+  });
+
+  it('records commit lag into the rolling window and clears in-flight state', () => {
+    const tracker = new ReplicationLagTracker();
+
+    tracker.trackUncommittedChange(new Date(0));
+    tracker.markCommitted(5_000);
+
+    expect(tracker.oldestUncommittedChange).toBeNull();
+    expect(tracker.isStartingReplication).toBe(false);
+    expect(tracker.getLagMillis(5_000)).toBe(5_000);
+    expect(tracker.getLagMillis(35_000)).toBe(0);
+  });
+
+  it('can clear in-flight state without changing started state', () => {
+    const tracker = new ReplicationLagTracker();
+
+    tracker.trackUncommittedChange(new Date(0));
+    tracker.clearUncommittedChange();
+
+    expect(tracker.oldestUncommittedChange).toBeNull();
+    expect(tracker.isStartingReplication).toBe(true);
+    expect(tracker.getLagMillis(5_000)).toBeUndefined();
+  });
+
+  it('can mark replication as started without a committed transaction', () => {
+    const tracker = new ReplicationLagTracker();
+
+    tracker.markStarted();
+
+    expect(tracker.isStartingReplication).toBe(false);
+    expect(tracker.getLagMillis(0)).toBe(0);
+  });
+});

package/test/src/RollingBucketMax.test.ts

@@ -0,0 +1,106 @@
+import { RollingBucketMax } from '@/metrics/RollingBucketMax.js';
+import { describe, expect, it } from 'vitest';
+
+describe('RollingBucketMax', () => {
+  it('returns undefined before any values are reported', () => {
+    const tracker = new RollingBucketMax();
+
+    expect(tracker.getRollingMax(0)).toBeUndefined();
+  });
+
+  it('tracks the maximum value within a single bucket', () => {
+    const tracker = new RollingBucketMax();
+
+    tracker.report(3, 100);
+    tracker.report(9, 1_000);
+    tracker.report(5, 4_999);
+
+    expect(tracker.getRollingMax(4_999)).toBe(9);
+  });
+
+  it('keeps the rolling max across the last six 5s buckets', () => {
+    const tracker = new RollingBucketMax();
+
+    tracker.report(20, 0);
+    tracker.report(11, 5_000);
+    tracker.report(12, 10_000);
+    tracker.report(13, 15_000);
+    tracker.report(14, 20_000);
+    tracker.report(15, 25_000);
+
+    expect(tracker.getRollingMax(29_999)).toBe(20);
+    expect(tracker.getRollingMax(30_000)).toBe(15);
+  });
+
+  it('slides the rolling max forward as older buckets age out', () => {
+    const tracker = new RollingBucketMax();
+
+    tracker.report(20, 0);
+    expect(tracker.getRollingMax(0)).toBe(20);
+
+    tracker.report(18, 5_000);
+    expect(tracker.getRollingMax(5_000)).toBe(20);
+
+    tracker.report(16, 10_000);
+    expect(tracker.getRollingMax(10_000)).toBe(20);
+
+    tracker.report(14, 15_000);
+    expect(tracker.getRollingMax(15_000)).toBe(20);
+
+    tracker.report(12, 20_000);
+    expect(tracker.getRollingMax(20_000)).toBe(20);
+
+    tracker.report(10, 25_000);
+    expect(tracker.getRollingMax(29_999)).toBe(20);
+
+    tracker.report(8, 30_000);
+    expect(tracker.getRollingMax(30_000)).toBe(18);
+
+    tracker.report(6, 35_000);
+    expect(tracker.getRollingMax(35_000)).toBe(16);
+
+    tracker.report(4, 40_000);
+    expect(tracker.getRollingMax(40_000)).toBe(14);
+  });
+
+  it('keeps newer buckets in the rolling window while older peaks fall out', () => {
+    const tracker = new RollingBucketMax();
+
+    tracker.report(50, 0);
+    tracker.report(11, 5_000);
+    tracker.report(12, 10_000);
+    tracker.report(13, 15_000);
+    tracker.report(14, 20_000);
+    tracker.report(15, 25_000);
+
+    expect(tracker.getRollingMax(29_999)).toBe(50);
+
+    tracker.report(40, 30_000);
+    expect(tracker.getRollingMax(30_000)).toBe(40);
+    expect(tracker.getRollingMax(34_999)).toBe(40);
+  });
+
+  it('expires values after the rolling window passes with no new reports', () => {
+    const tracker = new RollingBucketMax();
+
+    tracker.report(7, 0);
+
+    expect(tracker.getRollingMax(29_999)).toBe(7);
+    expect(tracker.getRollingMax(30_000)).toBeUndefined();
+  });
+
+  it('supports custom bucket and window sizes', () => {
+    const tracker = new RollingBucketMax({
+      bucketSizeMs: 1_000,
+      windowSizeMs: 3_000
+    });
+
+    tracker.report(4, 0);
+    tracker.report(6, 1_000);
+    tracker.report(5, 2_000);
+
+    expect(tracker.getRollingMax(2_999)).toBe(6);
+    expect(tracker.getRollingMax(3_000)).toBe(6);
+    expect(tracker.getRollingMax(4_000)).toBe(5);
+  });
+});