fix(replay): Streamline session creation/refresh

Author: mydea

packages/replay/src/replay.ts

@@ -18,7 +18,7 @@ import { handleKeyboardEvent } from './coreHandlers/handleKeyboardEvent';
 import { setupPerformanceObserver } from './coreHandlers/performanceObserver';
 import { createEventBuffer } from './eventBuffer';
 import { clearSession } from './session/clearSession';
-import { getSession } from './session/getSession';
+import { loadOrCreateSession, maybeRefreshSession } from './session/getSession';
 import { saveSession } from './session/saveSession';
 import type {
   AddEventResult,
@@ -228,28 +228,22 @@ export class ReplayContainer implements ReplayContainerInterface {
 
     // Otherwise if there is _any_ sample rate set, try to load an existing
     // session, or create a new one.
-    const isSessionSampled = this._loadAndCheckSession();
-
-    if (!isSessionSampled) {
-      // This should only occur if `errorSampleRate` is 0 and was unsampled for
-      // session-based replay. In this case there is nothing to do.
-      return;
-    }
+    this._initializeSessionForSampling();
 
     if (!this.session) {
       // This should not happen, something wrong has occurred
       this._handleException(new Error('Unable to initialize and create session'));
       return;
     }
 
-    if (this.session.sampled && this.session.sampled !== 'session') {
-      // If not sampled as session-based, then recording mode will be `buffer`
-      // Note that we don't explicitly check if `sampled === 'buffer'` because we
-      // could have sessions from Session storage that are still `error` from
-      // prior SDK version.
-      this.recordingMode = 'buffer';
+    if (this.session.sampled === false) {
+      // This should only occur if `errorSampleRate` is 0 and was unsampled for
+      // session-based replay. In this case there is nothing to do.
+      return;
     }
 
+    this.recordingMode = this.session.sampled === 'buffer' ? 'buffer' : 'session';
+
     logInfoNextTick(
       `[Replay] Starting replay in ${this.recordingMode} mode`,
       this._options._experiments.traceInternals,
@@ -276,19 +270,20 @@ export class ReplayContainer implements ReplayContainerInterface {
 
     logInfoNextTick('[Replay] Starting replay in session mode', this._options._experiments.traceInternals);
 
-    const previousSessionId = this.session && this.session.id;
-
-    const { session } = getSession({
-      timeouts: this.timeouts,
-      stickySession: Boolean(this._options.stickySession),
-      currentSession: this.session,
-      // This is intentional: create a new session-based replay when calling `start()`
-      sessionSampleRate: 1,
-      allowBuffering: false,
-      traceInternals: this._options._experiments.traceInternals,
-    });
+    const session = loadOrCreateSession(
+      this.session,
+      {
+        timeouts: this.timeouts,
+        traceInternals: this._options._experiments.traceInternals,
+      },
+      {
+        stickySession: this._options.stickySession,
+        // This is intentional: create a new session-based replay when calling `start()`
+        sessionSampleRate: 1,
+        allowBuffering: false,
+      },
+    );
 
-    session.previousSessionId = previousSessionId;
     this.session = session;
 
     this._initializeRecording();
@@ -305,18 +300,19 @@ export class ReplayContainer implements ReplayContainerInterface {
 
     logInfoNextTick('[Replay] Starting replay in buffer mode', this._options._experiments.traceInternals);
 
-    const previousSessionId = this.session && this.session.id;
-
-    const { session } = getSession({
-      timeouts: this.timeouts,
-      stickySession: Boolean(this._options.stickySession),
-      currentSession: this.session,
-      sessionSampleRate: 0,
-      allowBuffering: true,
-      traceInternals: this._options._experiments.traceInternals,
-    });
+    const session = loadOrCreateSession(
+      this.session,
+      {
+        timeouts: this.timeouts,
+        traceInternals: this._options._experiments.traceInternals,
+      },
+      {
+        stickySession: this._options.stickySession,
+        sessionSampleRate: 0,
+        allowBuffering: true,
+      },
+    );
 
-    session.previousSessionId = previousSessionId;
     this.session = session;
 
     this.recordingMode = 'buffer';
@@ -427,7 +423,7 @@ export class ReplayContainer implements ReplayContainerInterface {
    * new DOM checkout.`
    */
   public resume(): void {
-    if (!this._isPaused || !this._loadAndCheckSession()) {
+    if (!this._isPaused || !this._checkSession()) {
       return;
     }
 
@@ -535,7 +531,7 @@ export class ReplayContainer implements ReplayContainerInterface {
     if (!this._stopRecording) {
       // Create a new session, otherwise when the user action is flushed, it
       // will get rejected due to an expired session.
-      if (!this._loadAndCheckSession()) {
+      if (!this._checkSession()) {
         return;
       }
 
@@ -634,7 +630,7 @@ export class ReplayContainer implements ReplayContainerInterface {
 
     // --- There is recent user activity --- //
     // This will create a new session if expired, based on expiry length
-    if (!this._loadAndCheckSession()) {
+    if (!this._checkSession()) {
       return;
     }
 
@@ -751,31 +747,63 @@ export class ReplayContainer implements ReplayContainerInterface {
 
   /**
    * Loads (or refreshes) the current session.
+   */
+  private _initializeSessionForSampling(): void {
+    // Whenever there is _any_ error sample rate, we always allow buffering
+    // Because we decide on sampling when an error occurs, we need to buffer at all times if sampling for errors
+    const allowBuffering = this._options.errorSampleRate > 0;
+
+    const session = loadOrCreateSession(
+      this.session,
+      {
+        timeouts: this.timeouts,
+        traceInternals: this._options._experiments.traceInternals,
+      },
+      {
+        stickySession: this._options.stickySession,
+        sessionSampleRate: this._options.sessionSampleRate,
+        allowBuffering,
+      },
+    );
+
+    this.session = session;
+  }
+
+  /**
+   * Checks and potentially refreshes the current session.
    * Returns false if session is not recorded.
    */
-  private _loadAndCheckSession(): boolean {
-    const { type, session } = getSession({
-      timeouts: this.timeouts,
-      stickySession: Boolean(this._options.stickySession),
-      currentSession: this.session,
-      sessionSampleRate: this._options.sessionSampleRate,
-      allowBuffering: this._options.errorSampleRate > 0 || this.recordingMode === 'buffer',
-      traceInternals: this._options._experiments.traceInternals,
-    });
+  private _checkSession(): boolean {
+    // If there is no session yet, we do not want to refresh anything
+    // This should generally not happen, but to be safe....
+    if (!this.session) {
+      return false;
+    }
+
+    const currentSession = this.session;
+
+    const newSession = maybeRefreshSession(
+      currentSession,
+      {
+        timeouts: this.timeouts,
+        traceInternals: this._options._experiments.traceInternals,
+      },
+      {
+        stickySession: Boolean(this._options.stickySession),
+        sessionSampleRate: this._options.sessionSampleRate,
+        allowBuffering: this._options.errorSampleRate > 0,
+      },
+    );
+
+    const isNew = newSession.id !== currentSession.id;
 
     // If session was newly created (i.e. was not loaded from storage), then
     // enable flag to create the root replay
-    if (type === 'new') {
+    if (isNew) {
       this.setInitialState();
+      this.session = newSession;
     }
 
-    const currentSessionId = this.getSessionId();
-    if (session.id !== currentSessionId) {
-      session.previousSessionId = currentSessionId;
-    }
-
-    this.session = session;
-
     if (!this.session.sampled) {
       void this.stop({ reason: 'session not refreshed' });
       return false;

packages/replay/src/session/Session.ts

@@ -14,6 +14,7 @@ export function makeSession(session: Partial<Session> & { sampled: Sampled }): S
   const segmentId = session.segmentId || 0;
   const sampled = session.sampled;
   const shouldRefresh = typeof session.shouldRefresh === 'boolean' ? session.shouldRefresh : true;
+  const previousSessionId = session.previousSessionId;
 
   return {
     id,
@@ -22,5 +23,6 @@ export function makeSession(session: Partial<Session> & { sampled: Sampled }): S
     segmentId,
     sampled,
     shouldRefresh,
+    previousSessionId,
   };
 }

packages/replay/src/session/createSession.ts

@@ -15,10 +15,14 @@ export function getSessionSampleType(sessionSampleRate: number, allowBuffering:
  * that all replays will be saved to as attachments. Currently, we only expect
  * one of these Sentry events per "replay session".
  */
-export function createSession({ sessionSampleRate, allowBuffering, stickySession = false }: SessionOptions): Session {
+export function createSession(
+  { sessionSampleRate, allowBuffering, stickySession = false }: SessionOptions,
+  { previousSessionId }: { previousSessionId?: string } = {},
+): Session {
   const sampled = getSessionSampleType(sessionSampleRate, allowBuffering);
   const session = makeSession({
     sampled,
+    previousSessionId,
   });
 
   if (stickySession) {

packages/replay/src/session/getSession.ts

@@ -5,59 +5,95 @@ import { createSession } from './createSession';
 import { fetchSession } from './fetchSession';
 import { makeSession } from './Session';
 
-interface GetSessionParams extends SessionOptions {
-  timeouts: Timeouts;
+/**
+ * Check a session, and either return it or a refreshed version of it.
+ * The refreshed version may be unsampled.
+ * You can check if the session has changed by comparing the session IDs.
+ */
+export function maybeRefreshSession(
+  session: Session,
+  {
+    timeouts,
+    traceInternals,
+  }: {
+    timeouts: Timeouts;
+    traceInternals?: boolean;
+  },
+  sessionOptions: SessionOptions,
+): Session {
+  const isExpired = isSessionExpired(session, timeouts);
+
+  // If not expired, all good, just keep the session
+  if (!isExpired) {
+    return session;
+  }
+
+  const isBuffering = session.sampled === 'buffer';
+
+  // If we are buffering & the session may be refreshed, just return it
+  if (isBuffering && session.shouldRefresh) {
+    return session;
+  }
+
+  // If we are buffering & the session may not be refreshed (=it was converted to session previously already)
+  // We return an unsampled new session
+  if (isBuffering) {
+    logInfoNextTick('[Replay] Session should not be refreshed', traceInternals);
+    return makeSession({ sampled: false });
+  }
 
-  /**
-   * The current session (e.g. if stickySession is off)
-   */
-  currentSession?: Session;
+  // Else, we are not buffering, and the session is expired, so we need to create a new one
+  logInfoNextTick('[Replay] Session has expired, creating new one...', traceInternals);
 
-  traceInternals?: boolean;
+  const newSession = createSession(sessionOptions, { previousSessionId: session.id });
+
+  return newSession;
 }
 
 /**
- * Get or create a session
+ * Get or create a session, when initializing the replay.
+ * Returns a session that may be unsampled.
  */
-export function getSession({
-  timeouts,
-  currentSession,
-  stickySession,
-  sessionSampleRate,
-  allowBuffering,
-  traceInternals,
-}: GetSessionParams): { type: 'new' | 'saved'; session: Session } {
+export function loadOrCreateSession(
+  currentSession: Session | undefined,
+  {
+    timeouts,
+    traceInternals,
+  }: {
+    timeouts: Timeouts;
+    traceInternals?: boolean;
+  },
+  sessionOptions: SessionOptions,
+): Session {
   // If session exists and is passed, use it instead of always hitting session storage
-  const session = currentSession || (stickySession && fetchSession(traceInternals));
-
-  if (session) {
-    // If there is a session, check if it is valid (e.g. "last activity" time
-    // should be within the "session idle time", and "session started" time is
-    // within "max session time").
-    const isExpired = isSessionExpired(session, timeouts);
-
-    if (!isExpired || (allowBuffering && session.shouldRefresh)) {
-      return { type: 'saved', session };
-    } else if (!session.shouldRefresh) {
-      // This is the case if we have an error session that is completed
-      // (=triggered an error). Session will continue as session-based replay,
-      // and when this session is expired, it will not be renewed until user
-      // reloads.
-      const discardedSession = makeSession({ sampled: false });
-      logInfoNextTick('[Replay] Session should not be refreshed', traceInternals);
-      return { type: 'new', session: discardedSession };
-    } else {
-      logInfoNextTick('[Replay] Session has expired', traceInternals);
-    }
-    // Otherwise continue to create a new session
+  const existingSession = currentSession || (sessionOptions.stickySession && fetchSession(traceInternals));
+
+  // No session exists yet, just create a new one
+  if (!existingSession) {
+    logInfoNextTick('[Replay] Created new session', traceInternals);
+    return createSession(sessionOptions);
   }
 
-  const newSession = createSession({
-    stickySession,
-    sessionSampleRate,
-    allowBuffering,
-  });
-  logInfoNextTick('[Replay] Created new session', traceInternals);
+  // If a session exists, and it is not expired, just return it
+  if (!isSessionExpired(existingSession, timeouts)) {
+    return existingSession;
+  }
+
+  // If expired & we have a buffering session that should be refreshed, return it
+  if (existingSession.sampled === 'buffer' && existingSession.shouldRefresh) {
+    return existingSession;
+  }
+
+  // If expired & we have a buffering session that should _not_ be refreshed, return a new unsampled session
+  if (existingSession.sampled === 'buffer') {
+    logInfoNextTick('[Replay] Session should not be refreshed', traceInternals);
+    return makeSession({ sampled: false });
+  }
+
+  // Else, we have an expired session that should be refreshed & re-sampled
+  logInfoNextTick('[Replay] Session has expired, creating new one...', traceInternals);
+
+  const newSession = createSession(sessionOptions, { previousSessionId: existingSession.id });
 
-  return { type: 'new', session: newSession };
+  return newSession;
 }