@sentry/replay 7.58.0 → 7.59.0-beta.0

package/esm/index.js

@@ -14,9 +14,6 @@ const UNABLE_TO_SEND_REPLAY = 'Unable to send Replay';
 // The idle limit for a session after which recording is paused.
 const SESSION_IDLE_PAUSE_DURATION = 300000; // 5 minutes in ms
 
-// The idle limit for a session after which the session expires.
-const SESSION_IDLE_EXPIRE_DURATION = 900000; // 15 minutes in ms
-
 // The maximum length of a session
 const MAX_SESSION_LIFE = 3600000; // 60 minutes in ms
 
@@ -3279,26 +3276,26 @@ function addBreadcrumbEvent(replay, breadcrumb) {
   }
 
   if (['ui.click', 'ui.input'].includes(breadcrumb.category )) {
-    replay.triggerUserActivity();
-  } else {
-    replay.checkAndHandleExpiredSession();
+    replay.updateUserActivity();
   }
 
-  replay.addUpdate(() => {
-    void replay.throttledAddEvent({
-      type: EventType.Custom,
-      // TODO: We were converting from ms to seconds for breadcrumbs, spans,
-      // but maybe we should just keep them as milliseconds
-      timestamp: (breadcrumb.timestamp || 0) * 1000,
-      data: {
-        tag: 'breadcrumb',
-        // normalize to max. 10 depth and 1_000 properties per object
-        payload: normalize(breadcrumb, 10, 1000),
-      },
-    });
+  replay.checkSessionState(() => {
+    replay.addUpdate(() => {
+      void replay.throttledAddEvent({
+        type: EventType.Custom,
+        // TODO: We were converting from ms to seconds for breadcrumbs, spans,
+        // but maybe we should just keep them as milliseconds
+        timestamp: (breadcrumb.timestamp || 0) * 1000,
+        data: {
+          tag: 'breadcrumb',
+          // normalize to max. 10 depth and 1_000 properties per object
+          payload: normalize(breadcrumb, 10, 1000),
+        },
+      });
 
-    // Do not flush after console log messages
-    return breadcrumb.category === 'console';
+      // Do not flush after console log messages
+      return breadcrumb.category === 'console';
+    });
   });
 }
 
@@ -4389,6 +4386,66 @@ function createEventBuffer({ useCompression }) {
   return new EventBufferArray();
 }
 
+/**
+ * Given an initial timestamp and an expiry duration, checks to see if current
+ * time should be considered as expired.
+ */
+function isExpired(
+  initialTime,
+  expiry,
+  targetTime = +new Date(),
+) {
+  // Always expired if < 0
+  if (initialTime === null || expiry === undefined || expiry < 0) {
+    return true;
+  }
+
+  // Never expires if == 0
+  if (expiry === 0) {
+    return false;
+  }
+
+  return initialTime + expiry <= targetTime;
+}
+
+/** Check the state of the session. */
+function checkSessionState(
+  session,
+  recordingMode,
+  timeouts,
+  callbacks
+
+,
+) {
+  const _isIdle = () => {
+    return isExpired(session.lastActivity, timeouts.sessionIdlePause);
+  };
+
+  const _exceedsMaxLength = () => {
+    return isExpired(session.started, timeouts.maxSessionLife);
+  };
+
+  // When buffering, we never want to expire/end/pause/restart the recording
+  if (recordingMode === 'buffer') {
+    callbacks.onContinue();
+    return;
+  }
+
+  if (_exceedsMaxLength()) {
+    callbacks.onEnd();
+    return;
+  }
+
+  if (_isIdle()) {
+    callbacks.onPause();
+    return;
+  }
+
+  callbacks.ensureResumed();
+
+  callbacks.onContinue();
+}
+
 /** If sessionStorage is available. */
 function hasSessionStorage() {
   return 'sessionStorage' in WINDOW && !!WINDOW.sessionStorage;
@@ -4417,41 +4474,6 @@ function deleteSession() {
   }
 }
 
-/**
- * Given an initial timestamp and an expiry duration, checks to see if current
- * time should be considered as expired.
- */
-function isExpired(
-  initialTime,
-  expiry,
-  targetTime = +new Date(),
-) {
-  // Always expired if < 0
-  if (initialTime === null || expiry === undefined || expiry < 0) {
-    return true;
-  }
-
-  // Never expires if == 0
-  if (expiry === 0) {
-    return false;
-  }
-
-  return initialTime + expiry <= targetTime;
-}
-
-/**
- * Checks to see if session is expired
- */
-function isSessionExpired(session, timeouts, targetTime = +new Date()) {
-  return (
-    // First, check that maximum session length has not been exceeded
-    isExpired(session.started, timeouts.maxSessionLife, targetTime) ||
-    // check that the idle timeout has not been exceeded (i.e. user has
-    // performed an action within the last `sessionIdleExpire` ms)
-    isExpired(session.lastActivity, timeouts.sessionIdleExpire, targetTime)
-  );
-}
-
 /**
  * Given a sample rate, returns true if replay should be sampled.
  *
@@ -4500,24 +4522,20 @@ function makeSession(session) {
     lastActivity,
     segmentId,
     sampled,
-    shouldRefresh: true,
   };
 }
 
-/**
- * Get the sampled status for a session based on sample rates & current sampled status.
- */
-function getSessionSampleType(sessionSampleRate, allowBuffering) {
-  return isSampled(sessionSampleRate) ? 'session' : allowBuffering ? 'buffer' : false;
-}
-
 /**
  * Create a new session, which in its current implementation is a Sentry event
  * that all replays will be saved to as attachments. Currently, we only expect
  * one of these Sentry events per "replay session".
  */
-function createSession({ sessionSampleRate, allowBuffering, stickySession = false }) {
-  const sampled = getSessionSampleType(sessionSampleRate, allowBuffering);
+function createSession({
+  sampled,
+  stickySession = false,
+}
+
+) {
   const session = makeSession({
     sampled,
   });
@@ -4555,47 +4573,31 @@ function fetchSession() {
   }
 }
 
-/**
- * Get or create a session
- */
-function getSession({
-  timeouts,
-  currentSession,
+/** Either restore a session from sessionStorage, or create a new one. */
+function restoreOrCreateSession({
   stickySession,
-  sessionSampleRate,
-  allowBuffering,
-}) {
-  // If session exists and is passed, use it instead of always hitting session storage
-  const session = currentSession || (stickySession && fetchSession());
-
-  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 });
-      return { type: 'new', session: discardedSession };
-    } else {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Session has expired');
-    }
-    // Otherwise continue to create a new session
+  sampled,
+  forceSampled,
+}
+
+) {
+  const currentSession = stickySession && fetchSession();
+
+  if (currentSession && currentSession.sampled !== sampled && forceSampled) {
+    // If for whatever reason the session from sessionStorage has a different sampling, we force to the new sampling
+    (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) &&
+      logger.log(`[Replay] Tried to restore session with different sampling: ${currentSession.sampled} !== ${sampled}`);
+  } else if (currentSession) {
+    (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log(`[Replay] Loaded session from sessionStorage: id=${currentSession.id}`);
+    return currentSession;
   }
 
   const newSession = createSession({
     stickySession,
-    sessionSampleRate,
-    allowBuffering,
+    sampled,
   });
 
-  return { type: 'new', session: newSession };
+  return newSession;
 }
 
 function isCustomEvent(event) {
@@ -4908,12 +4910,14 @@ function handleHistorySpanListener(replay) {
 
     // Need to collect visited URLs
     replay.getContext().urls.push(result.name);
-    replay.triggerUserActivity();
+    replay.updateUserActivity();
 
-    replay.addUpdate(() => {
-      createPerformanceSpans(replay, [result]);
-      // Returning false to flush
-      return false;
+    replay.checkSessionState(() => {
+      replay.addUpdate(() => {
+        createPerformanceSpans(replay, [result]);
+        // Returning false to flush
+        return false;
+      });
     });
   };
 }
@@ -6529,79 +6533,64 @@ function getHandleRecordingEmit(replay) {
   let hadFirstEvent = false;
 
   return (event, _isCheckout) => {
-    // If this is false, it means session is expired, create and a new session and wait for checkout
-    if (!replay.checkAndHandleExpiredSession()) {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.warn('[Replay] Received replay event after session expired.');
-
-      return;
-    }
-
-    // `_isCheckout` is only set when the checkout is due to `checkoutEveryNms`
-    // We also want to treat the first event as a checkout, so we handle this specifically here
-    const isCheckout = _isCheckout || !hadFirstEvent;
-    hadFirstEvent = true;
-
-    // The handler returns `true` if we do not want to trigger debounced flush, `false` if we want to debounce flush.
-    replay.addUpdate(() => {
-      // The session is always started immediately on pageload/init, but for
-      // error-only replays, it should reflect the most recent checkout
-      // when an error occurs. Clear any state that happens before this current
-      // checkout. This needs to happen before `addEvent()` which updates state
-      // dependent on this reset.
-      if (replay.recordingMode === 'buffer' && isCheckout) {
-        replay.setInitialState();
-      }
-
-      // We need to clear existing events on a checkout, otherwise they are
-      // incremental event updates and should be appended
-      void addEvent(replay, event, isCheckout);
-
-      // Different behavior for full snapshots (type=2), ignore other event types
-      // See https://github.com/rrweb-io/rrweb/blob/d8f9290ca496712aa1e7d472549480c4e7876594/packages/rrweb/src/types.ts#L16
-      if (!isCheckout) {
-        return false;
-      }
+    replay.checkSessionState(() => {
+      // `_isCheckout` is only set when the checkout is due to `checkoutEveryNms`
+      // We also want to treat the first event as a checkout, so we handle this specifically here
+      const isCheckout = _isCheckout || !hadFirstEvent;
+      hadFirstEvent = true;
+
+      // The handler returns `true` if we do not want to trigger debounced flush, `false` if we want to debounce flush.
+      replay.addUpdate(() => {
+        // The session is always started immediately on pageload/init, but for
+        // error-only replays, it should reflect the most recent checkout
+        // when an error occurs. Clear any state that happens before this current
+        // checkout. This needs to happen before `addEvent()` which updates state
+        // dependent on this reset.
+        if (replay.recordingMode === 'buffer' && isCheckout) {
+          replay.setInitialState();
+        }
 
-      // Additionally, create a meta event that will capture certain SDK settings.
-      // In order to handle buffer mode, this needs to either be done when we
-      // receive checkout events or at flush time.
-      //
-      // `isCheckout` is always true, but want to be explicit that it should
-      // only be added for checkouts
-      void addSettingsEvent(replay, isCheckout);
-
-      // If there is a previousSessionId after a full snapshot occurs, then
-      // the replay session was started due to session expiration. The new session
-      // is started before triggering a new checkout and contains the id
-      // of the previous session. Do not immediately flush in this case
-      // to avoid capturing only the checkout and instead the replay will
-      // be captured if they perform any follow-up actions.
-      if (replay.session && replay.session.previousSessionId) {
-        return true;
-      }
+        // We need to clear existing events on a checkout, otherwise they are
+        // incremental event updates and should be appended
+        void addEvent(replay, event, isCheckout);
 
-      // When in buffer mode, make sure we adjust the session started date to the current earliest event of the buffer
-      // this should usually be the timestamp of the checkout event, but to be safe...
-      if (replay.recordingMode === 'buffer' && replay.session && replay.eventBuffer) {
-        const earliestEvent = replay.eventBuffer.getEarliestTimestamp();
-        if (earliestEvent) {
-          replay.session.started = earliestEvent;
+        // Different behavior for full snapshots (type=2), ignore other event types
+        // See https://github.com/rrweb-io/rrweb/blob/d8f9290ca496712aa1e7d472549480c4e7876594/packages/rrweb/src/types.ts#L16
+        if (!isCheckout) {
+          return false;
+        }
 
-          if (replay.getOptions().stickySession) {
-            saveSession(replay.session);
+        // Additionally, create a meta event that will capture certain SDK settings.
+        // In order to handle buffer mode, this needs to either be done when we
+        // receive checkout events or at flush time.
+        //
+        // `isCheckout` is always true, but want to be explicit that it should
+        // only be added for checkouts
+        void addSettingsEvent(replay, isCheckout);
+
+        // When in buffer mode, make sure we adjust the session started date to the current earliest event of the buffer
+        // this should usually be the timestamp of the checkout event, but to be safe...
+        if (replay.recordingMode === 'buffer' && replay.session && replay.eventBuffer) {
+          const earliestEvent = replay.eventBuffer.getEarliestTimestamp();
+          if (earliestEvent) {
+            replay.session.started = earliestEvent;
+
+            if (replay.getOptions().stickySession) {
+              saveSession(replay.session);
+            }
           }
         }
-      }
 
-      if (replay.recordingMode === 'session') {
-        // If the full snapshot is due to an initial load, we will not have
-        // a previous session ID. In this case, we want to buffer events
-        // for a set amount of time before flushing. This can help avoid
-        // capturing replays of users that immediately close the window.
-        void replay.flush();
-      }
+        if (replay.recordingMode === 'session') {
+          // If the full snapshot is due to an initial load, we will not have
+          // a previous session ID. In this case, we want to buffer events
+          // for a set amount of time before flushing. This can help avoid
+          // capturing replays of users that immediately close the window.
+          void replay.flush();
+        }
 
-      return true;
+        return true;
+      });
     });
   };
 }
@@ -6646,6 +6635,26 @@ function addSettingsEvent(replay, isCheckout) {
   return addEvent(replay, createOptionsEvent(replay), false);
 }
 
+/**
+ * Sample a session based on the provided sample rates.
+ */
+function sampleSession({
+  errorSampleRate,
+  sessionSampleRate,
+}
+
+) {
+  if (errorSampleRate <= 0 && sessionSampleRate <= 0) {
+    return false;
+  }
+
+  if (isSampled(sessionSampleRate)) {
+    return 'session';
+  }
+
+  return errorSampleRate > 0 ? 'buffer' : false;
+}
+
 /**
  * Create a replay envelope ready to be sent.
  * This includes both the replay event, as well as the recording data.
@@ -7037,7 +7046,6 @@ class ReplayContainer  {
    */
     __init4() {this.timeouts = {
     sessionIdlePause: SESSION_IDLE_PAUSE_DURATION,
-    sessionIdleExpire: SESSION_IDLE_EXPIRE_DURATION,
     maxSessionLife: MAX_SESSION_LIFE,
   }; }
 
@@ -7049,35 +7057,30 @@ class ReplayContainer  {
 
    __init6() {this._flushLock = null;}
 
-  /**
-   * Timestamp of the last user activity. This lives across sessions.
-   */
-   __init7() {this._lastActivity = Date.now();}
-
   /**
    * Is the integration currently active?
    */
-   __init8() {this._isEnabled = false;}
+   __init7() {this._isEnabled = false;}
 
   /**
    * Paused is a state where:
    * - DOM Recording is not listening at all
    * - Nothing will be added to event buffer (e.g. core SDK events)
    */
-   __init9() {this._isPaused = false;}
+   __init8() {this._isPaused = false;}
 
   /**
    * Have we attached listeners to the core SDK?
    * Note we have to track this as there is no way to remove instrumentation handlers.
    */
-   __init10() {this._hasInitializedCoreListeners = false;}
+   __init9() {this._hasInitializedCoreListeners = false;}
 
   /**
    * Function to stop recording
    */
-   __init11() {this._stopRecording = null;}
+   __init10() {this._stopRecording = null;}
 
-   __init12() {this._context = {
+   __init11() {this._context = {
     errorIds: new Set(),
     traceIds: new Set(),
     urls: [],
@@ -7090,7 +7093,7 @@ class ReplayContainer  {
     recordingOptions,
   }
 
-) {ReplayContainer.prototype.__init.call(this);ReplayContainer.prototype.__init2.call(this);ReplayContainer.prototype.__init3.call(this);ReplayContainer.prototype.__init4.call(this);ReplayContainer.prototype.__init5.call(this);ReplayContainer.prototype.__init6.call(this);ReplayContainer.prototype.__init7.call(this);ReplayContainer.prototype.__init8.call(this);ReplayContainer.prototype.__init9.call(this);ReplayContainer.prototype.__init10.call(this);ReplayContainer.prototype.__init11.call(this);ReplayContainer.prototype.__init12.call(this);ReplayContainer.prototype.__init13.call(this);ReplayContainer.prototype.__init14.call(this);ReplayContainer.prototype.__init15.call(this);ReplayContainer.prototype.__init16.call(this);ReplayContainer.prototype.__init17.call(this);ReplayContainer.prototype.__init18.call(this);
+) {ReplayContainer.prototype.__init.call(this);ReplayContainer.prototype.__init2.call(this);ReplayContainer.prototype.__init3.call(this);ReplayContainer.prototype.__init4.call(this);ReplayContainer.prototype.__init5.call(this);ReplayContainer.prototype.__init6.call(this);ReplayContainer.prototype.__init7.call(this);ReplayContainer.prototype.__init8.call(this);ReplayContainer.prototype.__init9.call(this);ReplayContainer.prototype.__init10.call(this);ReplayContainer.prototype.__init11.call(this);ReplayContainer.prototype.__init12.call(this);ReplayContainer.prototype.__init13.call(this);ReplayContainer.prototype.__init14.call(this);ReplayContainer.prototype.__init15.call(this);ReplayContainer.prototype.__init16.call(this);ReplayContainer.prototype.__init17.call(this);
     this._recordingOptions = recordingOptions;
     this._options = options;
 
@@ -7148,37 +7151,13 @@ class ReplayContainer  {
    */
    initializeSampling() {
     const { errorSampleRate, sessionSampleRate } = this._options;
+    const sampled = sampleSession({ errorSampleRate, sessionSampleRate });
 
-    // If neither sample rate is > 0, then do nothing - user will need to call one of
-    // `start()` or `startBuffering` themselves.
-    if (errorSampleRate <= 0 && sessionSampleRate <= 0) {
-      return;
-    }
-
-    // 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.
+    if (!sampled) {
       return;
     }
 
-    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';
-    }
-
+    this._initializeSession(sampled);
     this._initializeRecording();
   }
 
@@ -7198,20 +7177,7 @@ class ReplayContainer  {
       throw new Error('Replay buffering is in progress, call `flush()` to save the replay');
     }
 
-    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,
-    });
-
-    session.previousSessionId = previousSessionId;
-    this.session = session;
-
+    this._initializeSession('session', { forceSampled: true });
     this._initializeRecording();
   }
 
@@ -7224,20 +7190,7 @@ class ReplayContainer  {
       throw new Error('Replay recording is already in progress');
     }
 
-    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,
-    });
-
-    session.previousSessionId = previousSessionId;
-    this.session = session;
-
-    this.recordingMode = 'buffer';
+    this._initializeSession('buffer', { forceSampled: true });
     this._initializeRecording();
   }
 
@@ -7319,8 +7272,7 @@ class ReplayContainer  {
       this.eventBuffer && this.eventBuffer.destroy();
       this.eventBuffer = null;
 
-      // Clear session from session storage, note this means if a new session
-      // is started after, it will not have `previousSessionId`
+      // Clear session from session storage
       clearSession(this);
     } catch (err) {
       this._handleException(err);
@@ -7333,6 +7285,10 @@ class ReplayContainer  {
    * not as thorough of a shutdown as `stop()`.
    */
    pause() {
+    if (this.isPaused()) {
+      return;
+    }
+
     this._isPaused = true;
     this.stopRecording();
   }
@@ -7344,12 +7300,14 @@ class ReplayContainer  {
    * new DOM checkout.`
    */
    resume() {
-    if (!this._loadAndCheckSession()) {
+    if (!this.isPaused()) {
       return;
     }
 
     this._isPaused = false;
-    this.startRecording();
+    this.checkSessionState(() => {
+      this.startRecording();
+    });
   }
 
   /**
@@ -7384,20 +7342,8 @@ class ReplayContainer  {
     // starting a new recording
     this.recordingMode = 'session';
 
-    // Once this session ends, we do not want to refresh it
     if (this.session) {
-      this.session.shouldRefresh = false;
-
-      // It's possible that the session lifespan is > max session lifespan
-      // because we have been buffering beyond max session lifespan (we ignore
-      // expiration given that `shouldRefresh` is true). Since we flip
-      // `shouldRefresh`, the session could be considered expired due to
-      // lifespan, which is not what we want. Update session start date to be
-      // the current timestamp, so that session is not considered to be
-      // expired. This means that max replay duration can be MAX_SESSION_LIFE +
-      // (length of buffer), which we are ok with.
-      this._updateUserActivity(activityTime);
-      this._updateSessionActivity(activityTime);
+      this.session.lastActivity = activityTime;
       this.session.started = activityTime;
       this._maybeSaveSession();
     }
@@ -7435,42 +7381,9 @@ class ReplayContainer  {
   }
 
   /**
-   * Updates the user activity timestamp and resumes recording. This should be
-   * called in an event handler for a user action that we consider as the user
-   * being "active" (e.g. a mouse click).
-   */
-   triggerUserActivity() {
-    this._updateUserActivity();
-
-    // This case means that recording was once stopped due to inactivity.
-    // Ensure that recording is resumed.
-    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()) {
-        return;
-      }
-
-      // Note: This will cause a new DOM checkout
-      this.resume();
-      return;
-    }
-
-    // Otherwise... recording was never suspended, continue as normalish
-    this.checkAndHandleExpiredSession();
-
-    this._updateSessionActivity();
-  }
-
-  /**
-   * Updates the user activity timestamp *without* resuming
-   * recording. Some user events (e.g. keydown) can be create
-   * low-value replays that only contain the keypress as a
-   * breadcrumb. Instead this would require other events to
-   * create a new replay after a session has expired.
+   * Updates the user activity timestamp.
    */
    updateUserActivity() {
-    this._updateUserActivity();
     this._updateSessionActivity();
   }
 
@@ -7515,54 +7428,6 @@ class ReplayContainer  {
     return this.session && this.session.id;
   }
 
-  /**
-   * Checks if recording should be stopped due to user inactivity. Otherwise
-   * check if session is expired and create a new session if so. Triggers a new
-   * full snapshot on new session.
-   *
-   * Returns true if session is not expired, false otherwise.
-   * @hidden
-   */
-   checkAndHandleExpiredSession() {
-    const oldSessionId = this.getSessionId();
-
-    // Prevent starting a new session if the last user activity is older than
-    // SESSION_IDLE_PAUSE_DURATION. Otherwise non-user activity can trigger a new
-    // session+recording. This creates noisy replays that do not have much
-    // content in them.
-    if (
-      this._lastActivity &&
-      isExpired(this._lastActivity, this.timeouts.sessionIdlePause) &&
-      this.session &&
-      this.session.sampled === 'session'
-    ) {
-      // Pause recording only for session-based replays. Otherwise, resuming
-      // will create a new replay and will conflict with users who only choose
-      // to record error-based replays only. (e.g. the resumed replay will not
-      // contain a reference to an error)
-      this.pause();
-      return;
-    }
-
-    // --- There is recent user activity --- //
-    // This will create a new session if expired, based on expiry length
-    if (!this._loadAndCheckSession()) {
-      return;
-    }
-
-    // Session was expired if session ids do not match
-    const expired = oldSessionId !== this.getSessionId();
-
-    if (!expired) {
-      return true;
-    }
-
-    // Session is expired, trigger a full snapshot (which will create a new session)
-    this._triggerFullSnapshot();
-
-    return false;
-  }
-
   /**
    * Capture some initial state that can change throughout the lifespan of the
    * replay. This is required because otherwise they would be captured at the
@@ -7615,6 +7480,23 @@ class ReplayContainer  {
     return res;
   }
 
+  /**
+   * Check the state/expiration of the session.
+   * The callback is called when the session is neither paused nor expired.
+   */
+   checkSessionState(onContinue) {
+    if (!this.session || !this.session.sampled) {
+      return;
+    }
+
+    checkSessionState(this.session, this.recordingMode, this.timeouts, {
+      onPause: () => this.pause(),
+      ensureResumed: () => this.resume(),
+      onEnd: () => this._refreshSession(),
+      onContinue,
+    });
+  }
+
   /**
    * This will get the parametrized route name of the current page.
    * This is only available if performance is enabled, and if an instrumented router is used.
@@ -7628,6 +7510,31 @@ class ReplayContainer  {
     return lastTransaction.name;
   }
 
+  /**
+   * Initialize a new session.
+   */
+   _initializeSession(sampled, { forceSampled = false } = {}) {
+    const { stickySession } = this._options;
+
+    // If neither sample rate is > 0, then do nothing - user will need to call one of
+    // `start()` or `startBuffering` themselves.
+    if (!sampled) {
+      return;
+    }
+
+    const session = restoreOrCreateSession({ stickySession, sampled, forceSampled });
+
+    // This shouldn't be possible really, but just in case...
+    if (!session.sampled) {
+      return;
+    }
+
+    this.session = session;
+    this.recordingMode = this.session.sampled === 'buffer' ? 'buffer' : 'session';
+
+    return;
+  }
+
   /**
    * Initialize and start all listeners to varying events (DOM,
    * Performance Observer, Recording, Sentry SDK, etc)
@@ -7637,7 +7544,7 @@ class ReplayContainer  {
 
     // this method is generally called on page load or manually - in both cases
     // we should treat it as an activity
-    this._updateSessionActivity();
+    this.updateUserActivity();
 
     this.eventBuffer = createEventBuffer({
       useCompression: this._options.useCompression,
@@ -7648,6 +7555,7 @@ class ReplayContainer  {
 
     // Need to set as enabled before we start recording, as `record()` can trigger a flush with a new checkout
     this._isEnabled = true;
+    this._isPaused = false;
 
     this.startRecording();
   }
@@ -7662,37 +7570,31 @@ class ReplayContainer  {
   }
 
   /**
-   * Loads (or refreshes) the current session.
-   * Returns false if session is not recorded.
+   * Refresh a session that has ended, either when it exceeded the max. age or when it was inactive for too long.
+   * This means there was a sampled & sent session before - this will never be called while the session is buffering.
    */
-   _loadAndCheckSession() {
-    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',
-    });
-
-    // If session was newly created (i.e. was not loaded from storage), then
-    // enable flag to create the root replay
-    if (type === 'new') {
-      this.setInitialState();
-    }
-
-    const currentSessionId = this.getSessionId();
-    if (session.id !== currentSessionId) {
-      session.previousSessionId = currentSessionId;
+   _refreshSession() {
+    // To avoid firing this multiple times, we check if we are even recording
+    if (!this.isEnabled()) {
+      return;
     }
 
-    this.session = session;
+    const { errorSampleRate, sessionSampleRate } = this._options;
+    const sampled = sampleSession({ errorSampleRate, sessionSampleRate });
 
-    if (!this.session.sampled) {
-      void this.stop('session unsampled');
-      return false;
+    if (!sampled || !this.session) {
+      void this.stop('session expired without new session');
+      return;
     }
 
-    return true;
+    void this.stop('session expired with refreshing').then(() => {
+      if (sampled === 'session') {
+        return this.start();
+      }
+      if (sampled === 'buffer') {
+        return this.startBuffering();
+      }
+    });
   }
 
   /**
@@ -7757,7 +7659,7 @@ class ReplayContainer  {
    * be hidden. Likewise, moving a different window to cover the contents of the
    * page will also trigger a change to a hidden state.
    */
-   __init13() {this._handleVisibilityChange = () => {
+   __init12() {this._handleVisibilityChange = () => {
     if (WINDOW.document.visibilityState === 'visible') {
       this._doChangeToForegroundTasks();
     } else {
@@ -7768,7 +7670,7 @@ class ReplayContainer  {
   /**
    * Handle when page is blurred
    */
-   __init14() {this._handleWindowBlur = () => {
+   __init13() {this._handleWindowBlur = () => {
     const breadcrumb = createBreadcrumb({
       category: 'ui.blur',
     });
@@ -7781,7 +7683,7 @@ class ReplayContainer  {
   /**
    * Handle when page is focused
    */
-   __init15() {this._handleWindowFocus = () => {
+   __init14() {this._handleWindowFocus = () => {
     const breadcrumb = createBreadcrumb({
       category: 'ui.focus',
     });
@@ -7792,7 +7694,7 @@ class ReplayContainer  {
   };}
 
   /** Ensure page remains active when a key is pressed. */
-   __init16() {this._handleKeyboardEvent = (event) => {
+   __init15() {this._handleKeyboardEvent = (event) => {
     handleKeyboardEvent(this, event);
   };}
 
@@ -7800,71 +7702,35 @@ class ReplayContainer  {
    * Tasks to run when we consider a page to be hidden (via blurring and/or visibility)
    */
    _doChangeToBackgroundTasks(breadcrumb) {
-    if (!this.session) {
-      return;
-    }
-
-    const expired = isSessionExpired(this.session, this.timeouts);
-
-    if (breadcrumb && !expired) {
-      this._createCustomBreadcrumb(breadcrumb);
-    }
+    this.checkSessionState(() => {
+      if (breadcrumb) {
+        this._createCustomBreadcrumb(breadcrumb);
+      }
 
-    // Send replay when the page/tab becomes hidden. There is no reason to send
-    // replay if it becomes visible, since no actions we care about were done
-    // while it was hidden
-    void this.conditionalFlush();
+      // Send replay when the page/tab becomes hidden. There is no reason to send
+      // replay if it becomes visible, since no actions we care about were done
+      // while it was hidden
+      void this.conditionalFlush();
+    });
   }
 
   /**
    * Tasks to run when we consider a page to be visible (via focus and/or visibility)
    */
    _doChangeToForegroundTasks(breadcrumb) {
-    if (!this.session) {
-      return;
-    }
-
-    const isSessionActive = this.checkAndHandleExpiredSession();
-
-    if (!isSessionActive) {
-      // If the user has come back to the page within SESSION_IDLE_PAUSE_DURATION
-      // ms, we will re-use the existing session, otherwise create a new
-      // session
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Document has become active, but session has expired');
-      return;
-    }
-
-    if (breadcrumb) {
-      this._createCustomBreadcrumb(breadcrumb);
-    }
-  }
-
-  /**
-   * Trigger rrweb to take a full snapshot which will cause this plugin to
-   * create a new Replay event.
-   */
-   _triggerFullSnapshot(checkout = true) {
-    try {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.log('[Replay] Taking full rrweb snapshot');
-      record.takeFullSnapshot(checkout);
-    } catch (err) {
-      this._handleException(err);
-    }
-  }
-
-  /**
-   * Update user activity (across session lifespans)
-   */
-   _updateUserActivity(_lastActivity = Date.now()) {
-    this._lastActivity = _lastActivity;
+    this.checkSessionState(() => {
+      if (breadcrumb) {
+        this._createCustomBreadcrumb(breadcrumb);
+      }
+    });
   }
 
   /**
    * Updates the session's last activity timestamp
    */
-   _updateSessionActivity(_lastActivity = Date.now()) {
+   _updateSessionActivity(lastActivity = Date.now()) {
     if (this.session) {
-      this.session.lastActivity = _lastActivity;
+      this.session.lastActivity = lastActivity;
       this._maybeSaveSession();
     }
   }
@@ -8015,7 +7881,7 @@ class ReplayContainer  {
    * Flush recording data to Sentry. Creates a lock so that only a single flush
    * can be active at a time. Do not call this directly.
    */
-   __init17() {this._flush = async ({
+   __init16() {this._flush = async ({
     force = false,
   }
 
@@ -8025,42 +7891,58 @@ class ReplayContainer  {
       return;
     }
 
-    if (!this.checkAndHandleExpiredSession()) {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] Attempting to finish replay event after session expired.');
-      return;
-    }
+    return new Promise(resolve => {
+      if (!this.session) {
+        resolve();
+        return;
+      }
+      checkSessionState(this.session, this.recordingMode, this.timeouts, {
+        onPause: () => {
+          this.pause();
+          resolve();
+        },
+        ensureResumed: () => this.resume(),
+        onEnd: () => {
+          (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] Attempting to finish replay event after session expired.');
+          this._refreshSession();
+          resolve();
+        },
+        onContinue: () => {
+          void this._flushLocked().then(resolve);
+        },
+      });
+    });
+  };}
 
-    if (!this.session) {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error('[Replay] No session found to flush.');
-      return;
-    }
+  /**
+   * Flush, while locking so any future flush attemps while this is ongoing are queued.
+   */
+   async _flushLocked() {
+    try {
+      // A flush is about to happen, cancel any queued flushes
+      this._debouncedFlush.cancel();
 
-    // A flush is about to happen, cancel any queued flushes
-    this._debouncedFlush.cancel();
+      // this._flushLock acts as a lock so that future calls to `_flush()`
+      // will be blocked until this promise resolves
+      if (!this._flushLock) {
+        this._flushLock = this._runFlush();
+        await this._flushLock;
+        this._flushLock = null;
+        return;
+      }
 
-    // this._flushLock acts as a lock so that future calls to `_flush()`
-    // will be blocked until this promise resolves
-    if (!this._flushLock) {
-      this._flushLock = this._runFlush();
+      // Wait for previous flush to finish, then call the debounced `_flush()`.
+      // It's possible there are other flush requests queued and waiting for it
+      // to resolve. We want to reduce all outstanding requests (as well as any
+      // new flush requests that occur within a second of the locked flush
+      // completing) into a single flush.
       await this._flushLock;
-      this._flushLock = null;
-      return;
+    } catch (error) {
+      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error(error);
     }
 
-    // Wait for previous flush to finish, then call the debounced `_flush()`.
-    // It's possible there are other flush requests queued and waiting for it
-    // to resolve. We want to reduce all outstanding requests (as well as any
-    // new flush requests that occur within a second of the locked flush
-    // completing) into a single flush.
-
-    try {
-      await this._flushLock;
-    } catch (err) {
-      (typeof __SENTRY_DEBUG__ === 'undefined' || __SENTRY_DEBUG__) && logger.error(err);
-    } finally {
-      this._debouncedFlush();
-    }
-  };}
+    this._debouncedFlush();
+  }
 
   /** Save the session, if it is sticky */
    _maybeSaveSession() {
@@ -8070,7 +7952,7 @@ class ReplayContainer  {
   }
 
   /** Handler for rrweb.record.onMutation */
-   __init18() {this._onMutationHandler = (mutations) => {
+   __init17() {this._onMutationHandler = (mutations) => {
     const count = mutations.length;
 
     const mutationLimit = this._options.mutationLimit;