feat(browser): Restart the session when endSession is called

`endSession` is now exported from `@sentry/browser` rather than re-exported
from core. Calling it ends the current session and immediately starts a new
one, so telemetry emitted after the call is attributed to the new session
instead of to nothing.

Expiry, navigation in the `route` lifecycle, and `endSession` all go through
the same rotate step, which under the `session` lifecycle also replaces the
`sessionStorage` record so the ended session is not resumed on the next page
load.

Author: logaretm

packages/browser/src/exports.ts

@@ -65,7 +65,6 @@ export {
   parameterize,
   startSession,
   captureSession,
-  endSession,
   spanToStaticSpanJSON,
   spanToJSON,
   spanToTraceHeader,
@@ -84,6 +83,8 @@ export {
 } from '@sentry/core/browser';
 
 export { WINDOW } from './helpers';
+// Shadows core's `endSession`: in the browser, ending a session also starts the next one.
+export { endSession } from './session/lifecycle';
 export { BrowserClient } from './client';
 export { makeFetchTransport } from './transports/fetch';
 export { uiProfiler } from './profiling';

packages/browser/src/integrations/browsersession.ts

@@ -13,6 +13,7 @@ import {
 } from '@sentry/browser-utils';
 import { DEBUG_BUILD } from '../debug-build';
 import { WINDOW } from '../helpers';
+import { setSessionRotator } from '../session/lifecycle';
 import type { PersistedSession, SessionExpiryOptions } from '../session/persistence';
 import { getPersistedSession, isSessionExpired, persistSession } from '../session/persistence';
 
@@ -114,6 +115,10 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
       // (page-view-like) sessions.
       let initialSessionSent = false;
 
+      // Ends the current session and starts a new one in its place, sending it right away. Expiry,
+      // navigation (in the `'route'` lifecycle) and the public `endSession()` all funnel through here.
+      let rotate: () => void;
+
       if (lifecycle === 'session') {
         const persisted = getPersistedSession();
         const now = Date.now();
@@ -122,16 +127,20 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
         );
         let lastPersistedAt = current.lastActivity;
 
+        rotate = () => {
+          current = startAndPersistSession();
+          lastPersistedAt = current.lastActivity;
+          captureSession();
+          // A session has now been sent, so the deferred initial capture (if still pending)
+          // must not re-send this session.
+          initialSessionSent = true;
+        };
+
         const onActivity = (): void => {
           const activityAt = Date.now();
 
           if (isSessionExpired(current, expiry, activityAt)) {
-            current = startAndPersistSession();
-            lastPersistedAt = current.lastActivity;
-            captureSession();
-            // A session has now been sent, so the deferred initial capture (if still pending)
-            // must not re-send this session.
-            initialSessionSent = true;
+            rotate();
             return;
           }
 
@@ -154,8 +163,16 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
         // Automatically captured sessions are akin to page views, and thus we
         // discard their duration.
         startSession({ ignoreDuration: true });
+
+        rotate = () => {
+          startSession({ ignoreDuration: true });
+          captureSession();
+          initialSessionSent = true;
+        };
       }
 
+      setSessionRotator(rotate);
+
       whenIdleOrHidden(() => {
         // A navigation (in `'route'` lifecycle) may start and send a new session before this
         // deferred callback fires. In that case the current session was already sent, so
@@ -198,11 +215,7 @@ export const browserSessionIntegration = defineIntegration((options: BrowserSess
         addHistoryInstrumentationHandler(({ from, to }) => {
           // Don't create an additional session for the initial route or if the location did not change
           if (from !== to) {
-            startSession({ ignoreDuration: true });
-            captureSession();
-            // A session has now been sent, so the deferred initial capture (if still pending)
-            // must not re-send this navigation session.
-            initialSessionSent = true;
+            rotate();
           }
         });
       }

packages/browser/src/session/lifecycle.ts

@@ -0,0 +1,35 @@
+import { endSession as endSessionOnScope } from '@sentry/core/browser';
+
+/**
+ * How the session lifecycle currently in effect replaces its session, registered by
+ * `browserSessionIntegration`. Rotating is lifecycle-specific (the persisted `'session'` lifecycle
+ * has a `sessionStorage` record to keep in sync, the others do not), so the integration owns the
+ * implementation and the public API below only triggers it.
+ */
+let rotateSession: (() => void) | undefined;
+
+/**
+ * Registers @param rotate as the way to end the current session and start a new one in its place.
+ */
+export function setSessionRotator(rotate: () => void): void {
+  rotateSession = rotate;
+}
+
+/**
+ * Ends the current session and immediately starts a new one. Everything the page reports from here
+ * on belongs to the new session.
+ *
+ * There is no gap between the two: a browser tab never stops producing telemetry, so a session that
+ * ended without a successor would leave whatever comes next unattributed.
+ *
+ * Requires `browserSessionIntegration` (enabled by default). Without it there is no session the SDK
+ * manages, so this only closes a session that was started manually.
+ */
+export function endSession(): void {
+  if (rotateSession) {
+    rotateSession();
+    return;
+  }
+
+  endSessionOnScope();
+}

packages/browser/test/integrations/browsersession.test.ts

@@ -7,6 +7,7 @@ import type { Scope, SessionContext, User } from '@sentry/core/browser';
 import * as SentryCore from '@sentry/core/browser';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { browserSessionIntegration } from '../../src/integrations/browsersession';
+import { endSession } from '../../src/session/lifecycle';
 import type { PersistedSession } from '../../src/session/persistence';
 import { SESSION_STORAGE_KEY } from '../../src/session/persistence';
 
@@ -211,6 +212,19 @@ describe('browserSessionIntegration', () => {
     expect(SentryCore.captureSession).toHaveBeenCalledTimes(2);
   });
 
+  it('starts and sends a new session when the current one is ended manually', () => {
+    setupBrowserSession({ lifecycle: 'page' });
+
+    endSession();
+
+    expect(SentryCore.startSession).toHaveBeenCalledTimes(2);
+    expect(SentryCore.captureSession).toHaveBeenCalledTimes(1);
+
+    // The new session was already sent, so the deferred initial capture must not send it again.
+    vi.runAllTimers();
+    expect(SentryCore.captureSession).toHaveBeenCalledTimes(1);
+  });
+
   describe('`session` lifecycle', () => {
     const IDLE_TIMEOUT = 30 * 60_000;
 
@@ -330,6 +344,32 @@ describe('browserSessionIntegration', () => {
       expect(getStoredSession()?.sid).toBe(stored?.sid);
     });
 
+    it('replaces the persisted session when the current one is ended manually', () => {
+      setupSessionLifecycle();
+      const ended = getStoredSession();
+
+      elapse(60_000);
+      endSession();
+
+      const started = getStoredSession();
+      expect(SentryCore.startSession).toHaveBeenLastCalledWith({ ignoreDuration: true });
+      expect(SentryCore.captureSession).toHaveBeenCalledTimes(1);
+      expect(started).toEqual({
+        sid: expect.not.stringMatching(ended?.sid as string),
+        started: Date.now(),
+        lastActivity: Date.now(),
+      });
+
+      // The ended session must not come back when the page reloads.
+      reload();
+      expect(SentryCore.startSession).toHaveBeenCalledWith({
+        sid: started?.sid,
+        started: (started as PersistedSession).started / 1000,
+        init: false,
+        ignoreDuration: true,
+      });
+    });
+
     it.each([{ lifecycle: 'page' } as const, { lifecycle: 'route' } as const, undefined])(
       'does not persist or resume anything with options %o',
       options => {

packages/browser/test/session/lifecycle.test.ts

@@ -0,0 +1,41 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import type * as SentryCore from '@sentry/core/browser';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type * as SessionLifecycle from '../../src/session/lifecycle';
+
+const coreEndSession = vi.hoisted(() => vi.fn());
+
+vi.mock('@sentry/core/browser', async importActual => ({
+  ...((await importActual()) as typeof SentryCore),
+  endSession: coreEndSession,
+}));
+
+describe('endSession', () => {
+  let lifecycle: typeof SessionLifecycle;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    // The registered rotator is module state, so every test needs its own copy of the module.
+    vi.resetModules();
+    lifecycle = await import('../../src/session/lifecycle');
+  });
+
+  it('hands off to the rotator registered by the session lifecycle', () => {
+    const rotate = vi.fn();
+    lifecycle.setSessionRotator(rotate);
+
+    lifecycle.endSession();
+
+    expect(rotate).toHaveBeenCalledTimes(1);
+    expect(coreEndSession).not.toHaveBeenCalled();
+  });
+
+  it('closes the session on the scope when no lifecycle is managing sessions', () => {
+    lifecycle.endSession();
+
+    expect(coreEndSession).toHaveBeenCalledTimes(1);
+  });
+});