@grafana/faro-react-native 1.3.1 → 1.4.1

package/src/instrumentations/session/sessionManager/MmkvPersistentSessionsManager.ts

@@ -1,37 +1,141 @@
-import { AppState, type AppStateStatus } from 'react-native';
+import { AppState, type AppStateStatus, Platform } from 'react-native';
 import type { MMKV } from 'react-native-mmkv';
 
-import { faro, stringifyExternalJson } from '@grafana/faro-core';
+import { dateNow, faro } from '@grafana/faro-core';
+import type { Metas } from '@grafana/faro-core';
 
-import { throttle } from '../../../utils/throttle';
+import { SessionActivityKind } from '../sessionActivity';
+import {
+  claimSessionPersistenceStorageId,
+  getSessionProcessInfo,
+  releaseSessionPersistenceOwnership,
+} from '../sessionProcess';
 
+import { parsePersistentSession, serializePersistentSession } from './persistentSessionRecord';
 import { STORAGE_KEY, STORAGE_UPDATE_DELAY } from './sessionConstants';
-import { getSessionMetaUpdateHandler, getUserSessionUpdater } from './sessionManagerUtils';
+import {
+  getSessionMetaUpdateHandler,
+  getUserSessionResetter,
+  getUserSessionUpdater,
+  toStorableSessionMeta,
+} from './sessionManagerUtils';
 import type { FaroUserSession } from './types';
 
-function createMmkvInstance(): MMKV {
+type MmkvConfiguration = {
+  id: string;
+  mode?: number | 'multi-process';
+};
+
+type MmkvModule = {
+  createMMKV?: (configuration: MmkvConfiguration) => MMKV;
+  MMKV?: new (configuration: MmkvConfiguration) => MMKV;
+  Mode?: { MULTI_PROCESS?: number };
+};
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function loadMmkvModule(): MmkvModule {
   try {
-    const { MMKV } = require('react-native-mmkv');
-    return new MMKV({ id: 'grafana-faro-react-native-session' });
-  } catch {
+    return require('react-native-mmkv') as MmkvModule;
+  } catch (error) {
     throw new Error(
-      'sessionTracking.persistent is true but react-native-mmkv could not be loaded. Install it: yarn add react-native-mmkv, then rebuild native projects.'
+      `react-native-mmkv could not be loaded. Install it and rebuild the native project. ${errorMessage(error)}`
     );
   }
 }
 
-let mmkvSingleton: MMKV | undefined;
+function mmkvConfiguration(mmkv: MmkvModule, storageId: string, isIosExtension: boolean): MmkvConfiguration {
+  if (!isIosExtension) {
+    return { id: storageId };
+  }
+
+  if (typeof mmkv.createMMKV === 'function') {
+    return { id: storageId, mode: 'multi-process' };
+  }
+
+  const legacyMultiProcessMode = mmkv.Mode?.MULTI_PROCESS;
+  if (typeof legacyMultiProcessMode !== 'number') {
+    throw new Error('Persisting sessions in an iOS extension requires react-native-mmkv v3 or newer.');
+  }
+
+  return { id: storageId, mode: legacyMultiProcessMode };
+}
+
+function createMmkvInstance(): MMKV {
+  // Load MMKV before taking native ownership so a missing dependency cannot
+  // leave the process-wide claim occupied.
+  const mmkv = loadMmkvModule();
+  const processInfo = getSessionProcessInfo();
+  const storageId = claimSessionPersistenceStorageId();
+  if (storageId == null || processInfo == null) {
+    throw new Error(
+      'Native session-storage coordination is unavailable or already owned by another runtime. Rebuild the native app after upgrading Faro, or use sessionTracking.persistent=false in runtimes that cannot own storage.'
+    );
+  }
 
-function getMmkv(): MMKV {
-  if (mmkvSingleton == null) {
+  try {
+    const configuration = mmkvConfiguration(mmkv, storageId, Platform.OS === 'ios' && !processInfo.isMain);
+    // react-native-mmkv v4 was rewritten to Nitro and removed the `new MMKV()`
+    // class constructor in favor of a `createMMKV()` factory (see the v4 upgrade
+    // guide). Support both so v2/v3 (class) and v4+ (factory) work.
+    if (typeof mmkv.createMMKV === 'function') {
+      return mmkv.createMMKV(configuration);
+    }
+    if (typeof mmkv.MMKV !== 'function') {
+      throw new Error('The installed react-native-mmkv package does not expose a supported storage API.');
+    }
+    return new mmkv.MMKV(configuration);
+  } catch (error) {
+    releaseSessionPersistenceOwnership();
+    throw new Error(`Session persistence could not be initialized. ${errorMessage(error)}`);
+  }
+}
+
+// undefined means MMKV has not been resolved; null means it is unavailable.
+let mmkvSingleton: MMKV | null | undefined;
+// undefined means storage has not been read, null means no persisted state is
+// available, and a session is the live value for this JavaScript runtime.
+let runtimeSession: FaroUserSession | null | undefined;
+
+function tryGetMmkv(): MMKV | null {
+  if (mmkvSingleton !== undefined) {
+    return mmkvSingleton;
+  }
+
+  try {
     mmkvSingleton = createMmkvInstance();
+  } catch (error) {
+    mmkvSingleton = null;
+    faro.unpatchedConsole?.warn?.('Session persistence is unavailable; using an in-memory session:', error);
   }
+
   return mmkvSingleton;
 }
 
+function removeMmkvValue(mmkv: MMKV, key: string): void {
+  const compatibleMmkv = mmkv as MMKV & {
+    delete?: (storageKey: string) => void;
+    remove?: (storageKey: string) => void;
+  };
+
+  if (typeof compatibleMmkv.remove === 'function') {
+    compatibleMmkv.remove(key);
+    return;
+  }
+  if (typeof compatibleMmkv.delete === 'function') {
+    compatibleMmkv.delete(key);
+    return;
+  }
+
+  throw new Error('The installed react-native-mmkv version cannot remove stored values.');
+}
+
 /** @internal */
 export function resetMmkvSingletonForTests(): void {
   mmkvSingleton = undefined;
+  runtimeSession = undefined;
 }
 
 /**
@@ -39,12 +143,24 @@ export function resetMmkvSingletonForTests(): void {
  * Used when `sessionTracking.persistent` is true.
  */
 export class MmkvPersistentSessionsManager {
+  private resetUserSession: ReturnType<typeof getUserSessionResetter>;
   private updateUserSession: ReturnType<typeof getUserSessionUpdater>;
   private appStateSubscription: ReturnType<typeof AppState.addEventListener> | null = null;
-  private metaUnsubscribe: (() => void) | null = null;
+  private activityWriteTimer: ReturnType<typeof setTimeout> | null = null;
+  private hasPendingActivityWrite = false;
+  private lastActivityWrite = 0;
+  private wasBackgrounded = AppState.currentState === 'background';
+  private metaUpdateHandler: ReturnType<typeof getSessionMetaUpdateHandler> | null = null;
+  private readonly metas: Metas;
 
-  constructor() {
+  constructor(metas: Metas = faro.metas) {
+    this.metas = metas;
     this.updateUserSession = getUserSessionUpdater({
+      fetchUserSession: MmkvPersistentSessionsManager.fetchUserSession,
+      recordUserSessionActivity: this.recordUserSessionActivity,
+      storeUserSession: MmkvPersistentSessionsManager.storeUserSession,
+    });
+    this.resetUserSession = getUserSessionResetter({
       fetchUserSession: MmkvPersistentSessionsManager.fetchUserSession,
       storeUserSession: MmkvPersistentSessionsManager.storeUserSession,
     });
@@ -53,63 +169,163 @@ export class MmkvPersistentSessionsManager {
   }
 
   static removeUserSession(): void {
+    runtimeSession = null;
+    const mmkv = tryGetMmkv();
+    if (mmkv == null) {
+      return;
+    }
     try {
-      getMmkv().remove(STORAGE_KEY);
+      removeMmkvValue(mmkv, STORAGE_KEY);
     } catch (error) {
       faro.unpatchedConsole?.warn?.('Failed to remove session from MMKV:', error);
     }
   }
 
   static storeUserSession(session: FaroUserSession): void {
+    MmkvPersistentSessionsManager.setRuntimeSession(session);
+    MmkvPersistentSessionsManager.persistSession(session);
+  }
+
+  private static setRuntimeSession(session: FaroUserSession): void {
+    runtimeSession =
+      session.sessionMeta == null
+        ? session
+        : {
+            ...session,
+            sessionMeta: toStorableSessionMeta(session.sessionMeta),
+          };
+  }
+
+  private static persistSession(session: FaroUserSession): void {
+    const mmkv = tryGetMmkv();
+    if (mmkv == null) {
+      return;
+    }
     try {
-      getMmkv().set(STORAGE_KEY, stringifyExternalJson(session));
+      mmkv.set(STORAGE_KEY, serializePersistentSession(session));
     } catch (error) {
       faro.unpatchedConsole?.warn?.('Failed to store session in MMKV:', error);
     }
   }
 
   static fetchUserSession(): FaroUserSession | null {
+    if (runtimeSession !== undefined) {
+      return runtimeSession;
+    }
+
+    const mmkv = tryGetMmkv();
+    if (mmkv == null) {
+      runtimeSession = null;
+      return null;
+    }
+
     try {
-      const storedSession = getMmkv().getString(STORAGE_KEY);
-      if (storedSession) {
-        return JSON.parse(storedSession) as FaroUserSession;
+      const storedSession = mmkv.getString(STORAGE_KEY);
+      if (storedSession == null) {
+        runtimeSession = null;
+        return null;
       }
-      return null;
+
+      runtimeSession = parsePersistentSession(storedSession);
+      if (runtimeSession == null) {
+        removeMmkvValue(mmkv, STORAGE_KEY);
+      }
+      return runtimeSession;
     } catch (error) {
+      runtimeSession = null;
       faro.unpatchedConsole?.warn?.('Failed to fetch session from MMKV:', error);
       return null;
     }
   }
 
-  updateSession = throttle(() => this.updateUserSession(), STORAGE_UPDATE_DELAY);
+  checkSession(activity: SessionActivityKind, currentSession?: FaroUserSession | null): FaroUserSession {
+    return this.updateUserSession(activity, currentSession);
+  }
+
+  resetSession(): FaroUserSession {
+    if (this.activityWriteTimer != null) {
+      clearTimeout(this.activityWriteTimer);
+      this.activityWriteTimer = null;
+    }
+    this.hasPendingActivityWrite = false;
+
+    const session = this.resetUserSession();
+    this.lastActivityWrite = dateNow();
+    return session;
+  }
+
+  private flushActivityWrite = (): void => {
+    if (this.activityWriteTimer != null) {
+      clearTimeout(this.activityWriteTimer);
+      this.activityWriteTimer = null;
+    }
+
+    if (!this.hasPendingActivityWrite) {
+      return;
+    }
+
+    const session = MmkvPersistentSessionsManager.fetchUserSession();
+    this.hasPendingActivityWrite = false;
+    if (session == null) {
+      return;
+    }
+
+    MmkvPersistentSessionsManager.persistSession(session);
+    this.lastActivityWrite = dateNow();
+  };
+
+  private recordUserSessionActivity = (session: FaroUserSession): void => {
+    // Keep expiry checks exact in memory while limiting native storage writes.
+    MmkvPersistentSessionsManager.setRuntimeSession(session);
+    this.hasPendingActivityWrite = true;
+
+    const elapsed = dateNow() - this.lastActivityWrite;
+    if (this.lastActivityWrite === 0 || elapsed < 0 || elapsed >= STORAGE_UPDATE_DELAY) {
+      this.flushActivityWrite();
+      return;
+    }
+
+    if (this.activityWriteTimer == null) {
+      this.activityWriteTimer = setTimeout(this.flushActivityWrite, STORAGE_UPDATE_DELAY - elapsed);
+    }
+  };
 
   private handleAppStateChange = (nextAppState: AppStateStatus) => {
-    if (nextAppState === 'active') {
-      this.updateSession();
+    if (nextAppState === 'background') {
+      this.wasBackgrounded = true;
+      this.flushActivityWrite();
+      return;
+    }
+
+    if (nextAppState === 'active' && this.wasBackgrounded) {
+      this.wasBackgrounded = false;
+      this.checkSession(SessionActivityKind.Meaningful);
     }
   };
 
   private init(): void {
     this.appStateSubscription = AppState.addEventListener('change', this.handleAppStateChange);
 
-    const unsubscribe = faro.metas.addListener(
-      getSessionMetaUpdateHandler({
-        fetchUserSession: MmkvPersistentSessionsManager.fetchUserSession,
-        storeUserSession: MmkvPersistentSessionsManager.storeUserSession,
-      })
-    );
-    this.metaUnsubscribe = typeof unsubscribe === 'function' ? unsubscribe : null;
+    const metaUpdateHandler = getSessionMetaUpdateHandler({
+      fetchUserSession: MmkvPersistentSessionsManager.fetchUserSession,
+      storeUserSession: MmkvPersistentSessionsManager.storeUserSession,
+    });
+    this.metas.addListener(metaUpdateHandler);
+    this.metaUpdateHandler = metaUpdateHandler;
   }
 
   unpatch(): void {
+    this.flushActivityWrite();
+
     if (this.appStateSubscription) {
       this.appStateSubscription.remove();
       this.appStateSubscription = null;
     }
 
-    if (this.metaUnsubscribe) {
-      this.metaUnsubscribe();
-      this.metaUnsubscribe = null;
+    const metaUpdateHandler = this.metaUpdateHandler;
+    this.metaUpdateHandler = null;
+    if (metaUpdateHandler) {
+      this.metas.removeListener(metaUpdateHandler);
     }
   }
 }

package/src/instrumentations/session/sessionManager/VolatileSessionManager.ts

@@ -1,24 +1,32 @@
 import { AppState, type AppStateStatus } from 'react-native';
 
 import { faro } from '@grafana/faro-core';
+import type { Metas } from '@grafana/faro-core';
 
-import { throttle } from '../../../utils/throttle';
+import { SessionActivityKind } from '../sessionActivity';
 
-import { STORAGE_UPDATE_DELAY } from './sessionConstants';
-import { getSessionMetaUpdateHandler, getUserSessionUpdater } from './sessionManagerUtils';
+import { getSessionMetaUpdateHandler, getUserSessionResetter, getUserSessionUpdater } from './sessionManagerUtils';
 import type { FaroUserSession } from './types';
 
 export class VolatileSessionsManager {
   private static volatileStorage: FaroUserSession | null = null;
+  private resetUserSession: ReturnType<typeof getUserSessionResetter>;
   private updateUserSession: ReturnType<typeof getUserSessionUpdater>;
   private appStateSubscription: ReturnType<typeof AppState.addEventListener> | null = null;
-  private metaUnsubscribe: (() => void) | null = null;
+  private wasBackgrounded = AppState.currentState === 'background';
+  private metaUpdateHandler: ReturnType<typeof getSessionMetaUpdateHandler> | null = null;
+  private readonly metas: Metas;
 
-  constructor() {
+  constructor(metas: Metas = faro.metas) {
+    this.metas = metas;
     this.updateUserSession = getUserSessionUpdater({
       fetchUserSession: VolatileSessionsManager.fetchUserSession,
       storeUserSession: VolatileSessionsManager.storeUserSession,
     });
+    this.resetUserSession = getUserSessionResetter({
+      fetchUserSession: VolatileSessionsManager.fetchUserSession,
+      storeUserSession: VolatileSessionsManager.storeUserSession,
+    });
 
     this.init();
   }
@@ -35,11 +43,23 @@ export class VolatileSessionsManager {
     return VolatileSessionsManager.volatileStorage;
   }
 
-  updateSession = throttle(() => this.updateUserSession(), STORAGE_UPDATE_DELAY);
+  checkSession(activity: SessionActivityKind, currentSession?: FaroUserSession | null): FaroUserSession {
+    return this.updateUserSession(activity, currentSession);
+  }
+
+  resetSession(): FaroUserSession {
+    return this.resetUserSession();
+  }
 
   private handleAppStateChange = (nextAppState: AppStateStatus) => {
-    if (nextAppState === 'active') {
-      this.updateSession();
+    if (nextAppState === 'background') {
+      this.wasBackgrounded = true;
+      return;
+    }
+
+    if (nextAppState === 'active' && this.wasBackgrounded) {
+      this.wasBackgrounded = false;
+      this.checkSession(SessionActivityKind.Meaningful);
     }
   };
 
@@ -48,13 +68,12 @@ export class VolatileSessionsManager {
     this.appStateSubscription = AppState.addEventListener('change', this.handleAppStateChange);
 
     // Users can call the setSession() method, so we need to sync this with the in-memory session
-    const unsubscribe = faro.metas.addListener(
-      getSessionMetaUpdateHandler({
-        fetchUserSession: VolatileSessionsManager.fetchUserSession,
-        storeUserSession: VolatileSessionsManager.storeUserSession,
-      })
-    );
-    this.metaUnsubscribe = typeof unsubscribe === 'function' ? unsubscribe : null;
+    const metaUpdateHandler = getSessionMetaUpdateHandler({
+      fetchUserSession: VolatileSessionsManager.fetchUserSession,
+      storeUserSession: VolatileSessionsManager.storeUserSession,
+    });
+    this.metas.addListener(metaUpdateHandler);
+    this.metaUpdateHandler = metaUpdateHandler;
   }
 
   /**
@@ -66,9 +85,10 @@ export class VolatileSessionsManager {
       this.appStateSubscription = null;
     }
 
-    if (this.metaUnsubscribe) {
-      this.metaUnsubscribe();
-      this.metaUnsubscribe = null;
+    const metaUpdateHandler = this.metaUpdateHandler;
+    this.metaUpdateHandler = null;
+    if (metaUpdateHandler) {
+      this.metas.removeListener(metaUpdateHandler);
     }
   }
 }

package/src/instrumentations/session/sessionManager/persistentSessionRecord.test.ts

@@ -0,0 +1,103 @@
+import {
+  parsePersistentSession,
+  PERSISTED_SESSION_SCHEMA_VERSION,
+  serializePersistentSession,
+} from './persistentSessionRecord';
+import type { FaroUserSession } from './types';
+
+const session: FaroUserSession = {
+  sessionId: 'current-session',
+  started: 100,
+  lastActivity: 200,
+  isSampled: false,
+  sessionMeta: {
+    id: 'current-session',
+    attributes: {
+      previousSession: 'previous-session',
+      device_model: 'Test Phone',
+      custom: 'not-persisted',
+    },
+    overrides: {
+      serviceName: 'not-persisted',
+    },
+  },
+};
+
+describe('persistentSessionRecord', () => {
+  it('serializes only the versioned minimal session state', () => {
+    expect(JSON.parse(serializePersistentSession(session))).toStrictEqual({
+      schemaVersion: PERSISTED_SESSION_SCHEMA_VERSION,
+      currentSessionId: 'current-session',
+      previousSessionId: 'previous-session',
+      startedAt: 100,
+      lastActivityAt: 200,
+      isSampled: false,
+    });
+  });
+
+  it('round-trips the fields needed for session continuity', () => {
+    expect(parsePersistentSession(serializePersistentSession(session))).toStrictEqual({
+      sessionId: 'current-session',
+      started: 100,
+      lastActivity: 200,
+      isSampled: false,
+      sessionMeta: {
+        id: 'current-session',
+        attributes: {
+          isSampled: 'false',
+          previousSession: 'previous-session',
+        },
+      },
+    });
+  });
+
+  it.each([
+    ['missing state', ''],
+    ['corrupt JSON', '{not-json'],
+    [
+      'an unsupported schema',
+      JSON.stringify({
+        schemaVersion: PERSISTED_SESSION_SCHEMA_VERSION + 1,
+        currentSessionId: 'current-session',
+        previousSessionId: null,
+        startedAt: 100,
+        lastActivityAt: 200,
+        isSampled: true,
+      }),
+    ],
+    [
+      'an unversioned legacy record',
+      JSON.stringify({
+        sessionId: 'legacy-session',
+        started: 100,
+        lastActivity: 200,
+        isSampled: true,
+      }),
+    ],
+    [
+      'invalid timing',
+      JSON.stringify({
+        schemaVersion: PERSISTED_SESSION_SCHEMA_VERSION,
+        currentSessionId: 'current-session',
+        previousSessionId: null,
+        startedAt: 200,
+        lastActivityAt: 100,
+        isSampled: true,
+      }),
+    ],
+  ])('rejects %s', (_name, serialized) => {
+    expect(parsePersistentSession(serialized)).toBeNull();
+  });
+
+  it('clamps a backward activity timestamp when serializing', () => {
+    expect(
+      JSON.parse(
+        serializePersistentSession({
+          ...session,
+          started: 200,
+          lastActivity: 100,
+        })
+      )
+    ).toMatchObject({ startedAt: 200, lastActivityAt: 200 });
+  });
+});

package/src/instrumentations/session/sessionManager/persistentSessionRecord.ts

@@ -0,0 +1,78 @@
+import type { FaroUserSession } from './types';
+
+export const PERSISTED_SESSION_SCHEMA_VERSION = 1;
+
+type PersistedSessionRecord = {
+  schemaVersion: typeof PERSISTED_SESSION_SCHEMA_VERSION;
+  currentSessionId: string;
+  previousSessionId: string | null;
+  startedAt: number;
+  lastActivityAt: number;
+  isSampled: boolean;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isValidTimestamp(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+export function serializePersistentSession(session: FaroUserSession): string {
+  const previousSession = session.sessionMeta?.attributes?.['previousSession'];
+  const record: PersistedSessionRecord = {
+    schemaVersion: PERSISTED_SESSION_SCHEMA_VERSION,
+    currentSessionId: session.sessionId,
+    previousSessionId: isNonEmptyString(previousSession) ? previousSession : null,
+    startedAt: session.started,
+    // Preserve the record invariant if the device clock moves backwards after
+    // the session starts.
+    lastActivityAt: Math.max(session.started, session.lastActivity),
+    isSampled: session.isSampled,
+  };
+
+  return JSON.stringify(record);
+}
+
+export function parsePersistentSession(serialized: string): FaroUserSession | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(serialized);
+  } catch {
+    return null;
+  }
+
+  if (
+    !isRecord(value) ||
+    value['schemaVersion'] !== PERSISTED_SESSION_SCHEMA_VERSION ||
+    !isNonEmptyString(value['currentSessionId']) ||
+    !(value['previousSessionId'] === null || isNonEmptyString(value['previousSessionId'])) ||
+    !isValidTimestamp(value['startedAt']) ||
+    !isValidTimestamp(value['lastActivityAt']) ||
+    value['lastActivityAt'] < value['startedAt'] ||
+    typeof value['isSampled'] !== 'boolean'
+  ) {
+    return null;
+  }
+
+  const previousSessionId = value['previousSessionId'];
+
+  return {
+    sessionId: value['currentSessionId'],
+    started: value['startedAt'],
+    lastActivity: value['lastActivityAt'],
+    isSampled: value['isSampled'],
+    sessionMeta: {
+      id: value['currentSessionId'],
+      attributes: {
+        isSampled: value['isSampled'].toString(),
+        ...(previousSessionId == null ? {} : { previousSession: previousSessionId }),
+      },
+    },
+  };
+}

package/src/instrumentations/session/sessionManager/sampling.test.ts

@@ -21,7 +21,7 @@ describe('Sampling', () => {
     expect(isSampled()).toBe(true);
   });
 
-  describe('Sampling interface (Flutter-style)', () => {
+  describe('Sampling interface', () => {
     it('SamplingRate(1) samples all sessions', () => {
       const config = mockConfig({
         sessionTracking: {

package/src/instrumentations/session/sessionManager/sessionConstants.ts

@@ -9,6 +9,6 @@ export const MAX_SESSION_PERSISTENCE_TIME = DEFAULT_SESSION_PERSISTENCE_MS;
 /** React Native session defaults */
 export const defaultSessionTrackingConfig: ReactNativeSessionTrackingConfig = {
   enabled: true,
-  persistent: false,
+  persistent: true,
   maxSessionPersistenceTime: MAX_SESSION_PERSISTENCE_TIME,
 };