fix(core): Account for clock drift in initial timestampInSeconds() call

packages/core/src/utils/time.ts

@@ -40,6 +40,11 @@ function createUnixTimestampInSecondsFunc(): () => number {
   }
 
   const timeOrigin = performance.timeOrigin;
+  const performanceNow = withRandomSafeContext(() => performance.now());
+  const dateNow = safeDateNow();
+  if (!hasAccuratePerformanceTimestamp(timeOrigin, performanceNow, dateNow)) {
+    return dateTimestampInSeconds;
+  }
 
   // performance.now() is a monotonic clock, which means it starts at 0 when the process begins. To get the current
   // wall clock time (actual UNIX timestamp), we need to add the starting time origin and the current time elapsed.
@@ -92,16 +97,12 @@ function getBrowserTimeOrigin(): number | undefined {
     return undefined;
   }
 
-  const threshold = 300_000; // 5 minutes in milliseconds
   const performanceNow = withRandomSafeContext(() => performance.now());
   const dateNow = safeDateNow();
-
   const timeOrigin = performance.timeOrigin;
-  if (typeof timeOrigin === 'number') {
-    const timeOriginDelta = Math.abs(timeOrigin + performanceNow - dateNow);
-    if (timeOriginDelta < threshold) {
-      return timeOrigin;
-    }
+
+  if (hasAccuratePerformanceTimestamp(timeOrigin, performanceNow, dateNow)) {
+    return timeOrigin;
   }
 
   // TODO: Remove all code related to `performance.timing.navigationStart` once we drop support for Safari 14.
@@ -117,7 +118,7 @@ function getBrowserTimeOrigin(): number | undefined {
   const navigationStart = performance.timing?.navigationStart;
   if (typeof navigationStart === 'number') {
     const navigationStartDelta = Math.abs(navigationStart + performanceNow - dateNow);
-    if (navigationStartDelta < threshold) {
+    if (navigationStartDelta < WALL_CLOCK_DRIFT_THESHOLD) {
       return navigationStart;
     }
   }
@@ -138,3 +139,34 @@ export function browserPerformanceTimeOrigin(): number | undefined {
 
   return cachedTimeOrigin;
 }
+
+const WALL_CLOCK_DRIFT_THESHOLD = 300_000; // 5 minutes in milliseconds
+
+/**
+ * Check if the current timestamp calculated from the Performance API from
+ * `performance.timeOrigin + performance.now()` is within a reasonable threshold of
+ * the current time calculated from the Date API from `Date.now()`.
+ *
+ * The `performance.now()` clock is a monotonic clock, which means it starts at 0 when the process starts.
+ * Unfortunately, it is known to drift behind the actual wall clock, for example when a device hibernates,
+ * or tabs are suspended / inactive for a long period of time.
+ *
+ * Our threshold is 5 minutes, which is a reasonable compromise between accuracy and performance.
+ *
+ * @param performanceTimeOrigin - The time origin reported by the Performance API.
+ * @param performanceNow - The current time reported by the Performance API.
+ * @param dateNow - The current time reported by the Date API.
+ *
+ * @returns `true` if the current performance API-derive time is considered accurate, `false` otherwise.
+ */
+function hasAccuratePerformanceTimestamp(
+  performanceTimeOrigin: number,
+  performanceNow: number,
+  dateNow: number,
+): boolean {
+  if (typeof performanceTimeOrigin === 'number') {
+    const timeOriginDelta = Math.abs(performanceTimeOrigin + performanceNow - dateNow);
+    return timeOriginDelta < WALL_CLOCK_DRIFT_THESHOLD;
+  }
+  return false;
+}

packages/core/test/lib/utils/time.test.ts

@@ -1,13 +1,60 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+let freshImportId = 0;
+
+async function getFreshTimeModule() {
+  return import(`../../../src/utils/time?update=${freshImportId++}`);
+}
 
 async function getFreshPerformanceTimeOrigin() {
-  // Adding the query param with the date, forces a fresh import each time this is called
+  // Adding a query param forces a fresh import each time this is called
   // otherwise, the dynamic import would be cached and thus fall back to the cached value.
-  const timeModule = await import(`../../../src/utils/time?update=${Date.now()}`);
+  const timeModule = await getFreshTimeModule();
   return timeModule.browserPerformanceTimeOrigin();
 }
 
 const RELIABLE_THRESHOLD_MS = 300_000;
+const DAY_MS = 24 * 60 * 60 * 1_000;
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe('timestampInSeconds', () => {
+  it('uses the Date API when the performance timestamp is inaccurate on initialization', async () => {
+    const currentTimeMs = 1_800_000_000_000;
+
+    vi.useFakeTimers();
+    vi.setSystemTime(currentTimeMs);
+    vi.stubGlobal('performance', {
+      timeOrigin: currentTimeMs - 10 * DAY_MS,
+      now: () => 3 * DAY_MS,
+    });
+    const timeModule = await getFreshTimeModule();
+
+    expect(timeModule.timestampInSeconds()).toBe(currentTimeMs / 1_000);
+  });
+
+  it.fails('uses the Date API when the performance clock drifts after initialization', async () => {
+    const initialTimeMs = 1_800_000_000_000;
+    let performanceNow = 0;
+
+    vi.useFakeTimers();
+    vi.setSystemTime(initialTimeMs);
+    vi.stubGlobal('performance', {
+      timeOrigin: initialTimeMs,
+      now: () => performanceNow,
+    });
+    const timeModule = await getFreshTimeModule();
+    timeModule.timestampInSeconds();
+
+    vi.setSystemTime(initialTimeMs + 10 * DAY_MS);
+    performanceNow += 3 * DAY_MS;
+
+    expect(timeModule.timestampInSeconds()).toBe((initialTimeMs + 10 * DAY_MS) / 1_000);
+  });
+});
 
 describe('browserPerformanceTimeOrigin', () => {
   it('returns `performance.timeOrigin` if it is available and reliable', async () => {