@pratham.raval/browser-core 6.22.3

package/src/domain/session/README.md

@@ -0,0 +1,193 @@
+## possible states:
+
+| state                   | value                                                        |
+| ----------------------- | ------------------------------------------------------------ |
+| NotStarted<sup>\*</sup> | `{}`                                                         |
+| Expired                 | `{expired: '1'}` or `expire >  15 minutes` or `created > 4H` |
+| Tracked                 | `{id: 'xxxx-xx-xx}`                                          |
+| NotTracked              | `{rum: 0}` or `{logs: 0}`                                    |
+
+(<sup>\*</sup>) `NotStarted` is a state that can happen in a few different ways:
+
+- First load of the page if there is no cookie present already
+- After the cookie has been deleted by a 3rd party (user, ad blocker, ...)
+- After the cookie has expired (it is deleted by the browser)
+
+Other terminology:
+
+- A _started_ session is a session that is either `Expired`, `Tracked`, or `NotTracked`.
+- An _active_ session is a session that is either `Tracked` or `NotTracked`.
+
+## start session
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+state fork_state2 <<fork>>
+
+[*] --> fork_state
+
+fork_state --> NotStarted
+fork_state --> Expired
+fork_state --> Tracked
+fork_state --> NotTracked
+NotStarted --> Expired: startSession()
+
+Expired --> fork_state2
+Tracked --> fork_state2
+NotTracked --> fork_state2
+fork_state2 --> [*]: expandOrRenew()
+```
+
+## On User Activity
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+
+[*] --> fork_state
+
+fork_state --> [*]: expandOrRenew()
+```
+
+## On Visibility Change
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+state visibility <<choice>>
+
+[*] --> visibility: VisibilityChange
+
+visibility --> [*]: hidden
+visibility --> fork_state : visible
+
+fork_state --> [*]: extendOrExpire()
+```
+
+## On resume from frozen state
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+state fork_state2 <<fork>>
+
+[*] --> fork_state: Resume
+
+fork_state --> NotStarted
+fork_state --> Expired
+fork_state --> Tracked
+fork_state --> NotTracked
+
+NotStarted --> Expired: restartSession()
+Expired --> fork_state2
+Tracked --> fork_state2
+NotTracked --> fork_state2
+
+fork_state2 --> [*]: extendOrExpire()
+```
+
+## Watch (every second)
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+
+
+[*] --> fork_state
+fork_state --> [*]: extendOrExpire()
+```
+
+## 3rd party cookie clearing
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+state join_state <<join>>
+NotStarted2: NotStarted
+
+[*] --> fork_state
+
+fork_state --> NotStarted
+fork_state --> Expired
+fork_state --> Tracked
+fork_state --> NotTracked
+
+Expired --> join_state
+Tracked --> join_state
+NotTracked --> join_state
+NotStarted --> join_state
+
+join_state --> NotStarted2 : clearCookies()
+
+NotStarted2 --> [*]
+```
+
+## Expand Or Renew
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+state fork_state2 <<fork>>
+state fork_state3 <<fork>>
+
+
+state expandOrRenew() {
+  [*] --> fork_state: expandOrRenew()
+  Tracked2: Tracked
+  NotTracked2: NotTracked
+
+  fork_state --> NotStarted
+  fork_state --> Expired
+  fork_state --> Tracked
+  fork_state --> NotTracked
+
+  NotStarted --> [*]
+
+  Expired --> fork_state2: renew()
+  Tracked --> fork_state2: extend()
+  NotTracked --> fork_state2: extend()
+
+  fork_state2 --> fork_state3: computeTrackingType()
+
+  fork_state3 --> Tracked2
+  fork_state3 --> NotTracked2
+
+  Tracked2 --> [*]
+  NotTracked2 --> [*]
+}
+```
+
+> [!NOTE]  
+> Because `computeTrackingType()` happens at every `expandOrRenew()`, it is in theory possible to switch from `Tracked` to `NotTracked` and vice versa within an active session. However, this is not expected to happen in practice at this time.
+
+## Extend Or Expire
+
+```mermaid
+stateDiagram-v2
+state fork_state <<fork>>
+
+state extendOrExpire() {
+  [*] --> fork_state : extendOrExpire()
+  Tracked2: Tracked
+  NotTracked2: NotTracked
+  Expired2: Expired
+
+  fork_state --> NotStarted
+  fork_state --> Expired
+  fork_state --> Tracked
+  fork_state --> NotTracked
+
+  Tracked --> Tracked2: extend()
+  NotTracked --> NotTracked2: extend()
+  Expired --> Expired2: expire()
+
+  NotStarted --> [*]
+  Tracked2 --> [*]
+  NotTracked2 --> [*]
+  Expired2 --> [*]
+}
+```
+
+> [!NOTE]  
+> Because a session time out can result in an `Expired` state, `expire()` explicitly normalizes the state to `isExpired=1`

package/src/domain/session/oldCookiesMigration.ts

@@ -0,0 +1,42 @@
+import { getInitCookie } from '../../browser/cookie'
+import type { SessionStoreStrategy } from './storeStrategies/sessionStoreStrategy'
+import { SESSION_STORE_KEY } from './storeStrategies/sessionStoreStrategy'
+import type { SessionState } from './sessionState'
+import { expandSessionState, isSessionStarted } from './sessionState'
+
+export const OLD_SESSION_COOKIE_NAME = '_dd'
+export const OLD_RUM_COOKIE_NAME = '_dd_r'
+export const OLD_LOGS_COOKIE_NAME = '_dd_l'
+
+// duplicate values to avoid dependency issues
+export const RUM_SESSION_KEY = 'rum'
+export const LOGS_SESSION_KEY = 'logs'
+
+/**
+ * This migration should remain in the codebase as long as older versions are available/live
+ * to allow older sdk versions to be upgraded to newer versions without compatibility issues.
+ */
+export function tryOldCookiesMigration(cookieStoreStrategy: SessionStoreStrategy) {
+  const sessionString = getInitCookie(SESSION_STORE_KEY)
+  if (!sessionString) {
+    const oldSessionId = getInitCookie(OLD_SESSION_COOKIE_NAME)
+    const oldRumType = getInitCookie(OLD_RUM_COOKIE_NAME)
+    const oldLogsType = getInitCookie(OLD_LOGS_COOKIE_NAME)
+    const session: SessionState = {}
+
+    if (oldSessionId) {
+      session.id = oldSessionId
+    }
+    if (oldLogsType && /^[01]$/.test(oldLogsType)) {
+      session[LOGS_SESSION_KEY] = oldLogsType
+    }
+    if (oldRumType && /^[012]$/.test(oldRumType)) {
+      session[RUM_SESSION_KEY] = oldRumType
+    }
+
+    if (isSessionStarted(session)) {
+      expandSessionState(session)
+      cookieStoreStrategy.persistSession(session)
+    }
+  }
+}

package/src/domain/session/sessionConstants.ts

@@ -0,0 +1,19 @@
+import { ONE_HOUR, ONE_MINUTE, ONE_YEAR } from '../../tools/utils/timeUtils'
+
+export const SESSION_TIME_OUT_DELAY = 4 * ONE_HOUR
+export const SESSION_EXPIRATION_DELAY = 15 * ONE_MINUTE
+export const SESSION_COOKIE_EXPIRATION_DELAY = ONE_YEAR
+export const SESSION_NOT_TRACKED = '0'
+
+/**
+ * @internal
+ */
+export const SessionPersistence = {
+  COOKIE: 'cookie',
+  LOCAL_STORAGE: 'local-storage',
+} as const
+
+/**
+ * @inline
+ */
+export type SessionPersistence = (typeof SessionPersistence)[keyof typeof SessionPersistence]

package/src/domain/session/sessionManager.ts

@@ -0,0 +1,244 @@
+import { Observable } from '../../tools/observable'
+import type { Context } from '../../tools/serialisation/context'
+import { createValueHistory } from '../../tools/valueHistory'
+import type { RelativeTime } from '../../tools/utils/timeUtils'
+import { clocksOrigin, dateNow, ONE_MINUTE, relativeNow } from '../../tools/utils/timeUtils'
+import { addEventListener, addEventListeners, DOM_EVENT } from '../../browser/addEventListener'
+import { clearInterval, setInterval } from '../../tools/timer'
+import type { Configuration } from '../configuration'
+import type { TrackingConsentState } from '../trackingConsent'
+import { addTelemetryDebug } from '../telemetry'
+import { isSyntheticsTest } from '../synthetics/syntheticsWorkerValues'
+import type { CookieStore } from '../../browser/browser.types'
+import { getCurrentSite } from '../../browser/cookie'
+import { ExperimentalFeature, isExperimentalFeatureEnabled } from '../../tools/experimentalFeatures'
+import { findLast } from '../../tools/utils/polyfills'
+import { monitorError } from '../../tools/monitor'
+import { SESSION_NOT_TRACKED, SESSION_TIME_OUT_DELAY } from './sessionConstants'
+import { startSessionStore } from './sessionStore'
+import type { SessionState } from './sessionState'
+import { toSessionState } from './sessionState'
+import { retrieveSessionCookie } from './storeStrategies/sessionInCookie'
+import { SESSION_STORE_KEY } from './storeStrategies/sessionStoreStrategy'
+
+export interface SessionManager<TrackingType extends string> {
+  findSession: (
+    startTime?: RelativeTime,
+    options?: { returnInactive: boolean }
+  ) => SessionContext<TrackingType> | undefined
+  renewObservable: Observable<void>
+  expireObservable: Observable<void>
+  sessionStateUpdateObservable: Observable<{ previousState: SessionState; newState: SessionState }>
+  expire: () => void
+  updateSessionState: (state: Partial<SessionState>) => void
+}
+
+export interface SessionContext<TrackingType extends string> extends Context {
+  id: string
+  trackingType: TrackingType
+  isReplayForced: boolean
+  anonymousId: string | undefined
+}
+
+export const VISIBILITY_CHECK_DELAY = ONE_MINUTE
+const SESSION_CONTEXT_TIMEOUT_DELAY = SESSION_TIME_OUT_DELAY
+let stopCallbacks: Array<() => void> = []
+
+export function startSessionManager<TrackingType extends string>(
+  configuration: Configuration,
+  productKey: string,
+  computeTrackingType: (rawTrackingType?: string) => TrackingType,
+  trackingConsentState: TrackingConsentState
+): SessionManager<TrackingType> {
+  const renewObservable = new Observable<void>()
+  const expireObservable = new Observable<void>()
+
+  // TODO - Improve configuration type and remove assertion
+  const sessionStore = startSessionStore(
+    configuration.sessionStoreStrategyType!,
+    configuration,
+    productKey,
+    computeTrackingType
+  )
+  stopCallbacks.push(() => sessionStore.stop())
+
+  const sessionContextHistory = createValueHistory<SessionContext<TrackingType>>({
+    expireDelay: SESSION_CONTEXT_TIMEOUT_DELAY,
+  })
+  stopCallbacks.push(() => sessionContextHistory.stop())
+
+  sessionStore.renewObservable.subscribe(() => {
+    sessionContextHistory.add(buildSessionContext(), relativeNow())
+    renewObservable.notify()
+  })
+  sessionStore.expireObservable.subscribe(() => {
+    expireObservable.notify()
+    sessionContextHistory.closeActive(relativeNow())
+  })
+
+  // We expand/renew session unconditionally as tracking consent is always granted when the session
+  // manager is started.
+  sessionStore.expandOrRenewSession()
+  sessionContextHistory.add(buildSessionContext(), clocksOrigin().relative)
+  if (isExperimentalFeatureEnabled(ExperimentalFeature.SHORT_SESSION_INVESTIGATION)) {
+    const session = sessionStore.getSession()
+    if (session) {
+      detectSessionIdChange(configuration, session)
+    }
+  }
+
+  trackingConsentState.observable.subscribe(() => {
+    if (trackingConsentState.isGranted()) {
+      sessionStore.expandOrRenewSession()
+    } else {
+      sessionStore.expire()
+    }
+  })
+
+  trackActivity(configuration, () => {
+    if (trackingConsentState.isGranted()) {
+      sessionStore.expandOrRenewSession()
+    }
+  })
+  trackVisibility(configuration, () => sessionStore.expandSession())
+  trackResume(configuration, () => sessionStore.restartSession())
+
+  function buildSessionContext() {
+    const session = sessionStore.getSession()
+
+    if (!session) {
+      reportUnexpectedSessionState().catch(() => void 0) // Ignore errors
+
+      return {
+        id: 'invalid',
+        trackingType: SESSION_NOT_TRACKED as TrackingType,
+        isReplayForced: false,
+        anonymousId: undefined,
+      }
+    }
+
+    return {
+      id: session.id!,
+      trackingType: session[productKey] as TrackingType,
+      isReplayForced: !!session.forcedReplay,
+      anonymousId: session.anonymousId,
+    }
+  }
+
+  return {
+    findSession: (startTime, options) => sessionContextHistory.find(startTime, options),
+    renewObservable,
+    expireObservable,
+    sessionStateUpdateObservable: sessionStore.sessionStateUpdateObservable,
+    expire: sessionStore.expire,
+    updateSessionState: sessionStore.updateSessionState,
+  }
+}
+
+export function stopSessionManager() {
+  stopCallbacks.forEach((e) => e())
+  stopCallbacks = []
+}
+
+function trackActivity(configuration: Configuration, expandOrRenewSession: () => void) {
+  const { stop } = addEventListeners(
+    configuration,
+    window,
+    [DOM_EVENT.CLICK, DOM_EVENT.TOUCH_START, DOM_EVENT.KEY_DOWN, DOM_EVENT.SCROLL],
+    expandOrRenewSession,
+    { capture: true, passive: true }
+  )
+  stopCallbacks.push(stop)
+}
+
+function trackVisibility(configuration: Configuration, expandSession: () => void) {
+  const expandSessionWhenVisible = () => {
+    if (document.visibilityState === 'visible') {
+      expandSession()
+    }
+  }
+
+  const { stop } = addEventListener(configuration, document, DOM_EVENT.VISIBILITY_CHANGE, expandSessionWhenVisible)
+  stopCallbacks.push(stop)
+
+  const visibilityCheckInterval = setInterval(expandSessionWhenVisible, VISIBILITY_CHECK_DELAY)
+  stopCallbacks.push(() => {
+    clearInterval(visibilityCheckInterval)
+  })
+}
+
+function trackResume(configuration: Configuration, cb: () => void) {
+  const { stop } = addEventListener(configuration, window, DOM_EVENT.RESUME, cb, { capture: true })
+  stopCallbacks.push(stop)
+}
+
+async function reportUnexpectedSessionState() {
+  const rawSession = retrieveSessionCookie()
+  // monitor-until: forever, could be handy to troubleshoot issues until session manager rework
+  addTelemetryDebug('Unexpected session state', {
+    session: rawSession,
+    isSyntheticsTest: isSyntheticsTest(),
+    createdTimestamp: rawSession?.created,
+    expireTimestamp: rawSession?.expire,
+    cookie: await getSessionCookies(),
+    currentDomain: `${window.location.protocol}//${window.location.hostname}`,
+  })
+}
+
+function detectSessionIdChange(configuration: Configuration, initialSessionState: SessionState) {
+  if (!window.cookieStore || !initialSessionState.created) {
+    return
+  }
+
+  const sessionCreatedTime = Number(initialSessionState.created)
+  const sdkInitTime = dateNow()
+
+  const { stop } = addEventListener(configuration, cookieStore as CookieStore, DOM_EVENT.CHANGE, listener)
+  stopCallbacks.push(stop)
+
+  function listener(event: CookieChangeEvent) {
+    const changed = findLast(event.changed, (change): change is CookieListItem => change.name === SESSION_STORE_KEY)
+    if (!changed) {
+      return
+    }
+
+    const sessionAge = dateNow() - sessionCreatedTime
+    if (sessionAge > 14 * ONE_MINUTE) {
+      // The session might have expired just because it's too old or lack activity
+      stop()
+    } else {
+      const newSessionState = toSessionState(changed.value)
+      if (newSessionState.id && newSessionState.id !== initialSessionState.id) {
+        stop()
+        const time = dateNow() - sdkInitTime
+        getSessionCookies()
+          .then((cookie) => {
+            // monitor-until: 2025-12-01, after RUM-10845 investigation done
+            addTelemetryDebug('Session cookie changed', {
+              time,
+              session_age: sessionAge,
+              old: initialSessionState,
+              new: newSessionState,
+              cookie,
+            })
+          })
+          .catch(monitorError)
+      }
+    }
+  }
+}
+
+async function getSessionCookies(): Promise<{ count: number; domain: string }> {
+  let sessionCookies: string[] | Awaited<ReturnType<CookieStore['getAll']>>
+  if ('cookieStore' in window) {
+    sessionCookies = await (window as { cookieStore: CookieStore }).cookieStore.getAll(SESSION_STORE_KEY)
+  } else {
+    sessionCookies = document.cookie.split(/\s*;\s*/).filter((cookie) => cookie.startsWith(SESSION_STORE_KEY))
+  }
+
+  return {
+    count: sessionCookies.length,
+    domain: getCurrentSite() || 'undefined',
+    ...sessionCookies,
+  }
+}

package/src/domain/session/sessionState.ts

@@ -0,0 +1,88 @@
+import { isEmptyObject } from '../../tools/utils/objectUtils'
+import { objectEntries } from '../../tools/utils/polyfills'
+import { dateNow } from '../../tools/utils/timeUtils'
+import { generateUUID } from '../../tools/utils/stringUtils'
+import type { Configuration } from '../configuration'
+import { SESSION_EXPIRATION_DELAY, SESSION_TIME_OUT_DELAY } from './sessionConstants'
+import { isValidSessionString, SESSION_ENTRY_REGEXP, SESSION_ENTRY_SEPARATOR } from './sessionStateValidation'
+export const EXPIRED = '1'
+
+export interface SessionState {
+  id?: string
+  created?: string
+  expire?: string
+  isExpired?: typeof EXPIRED
+
+  [key: string]: string | undefined
+}
+
+export function getExpiredSessionState(
+  previousSessionState: SessionState | undefined,
+  configuration: Configuration
+): SessionState {
+  const expiredSessionState: SessionState = {
+    isExpired: EXPIRED,
+  }
+  if (configuration.trackAnonymousUser) {
+    if (previousSessionState?.anonymousId) {
+      expiredSessionState.anonymousId = previousSessionState?.anonymousId
+    } else {
+      expiredSessionState.anonymousId = generateUUID()
+    }
+  }
+  return expiredSessionState
+}
+
+export function isSessionInNotStartedState(session: SessionState) {
+  return isEmptyObject(session)
+}
+
+export function isSessionStarted(session: SessionState) {
+  return !isSessionInNotStartedState(session)
+}
+
+export function isSessionInExpiredState(session: SessionState) {
+  return session.isExpired !== undefined || !isActiveSession(session)
+}
+
+// An active session is a session in either `Tracked` or `NotTracked` state
+function isActiveSession(sessionState: SessionState) {
+  // created and expire can be undefined for versions which was not storing them
+  // these checks could be removed when older versions will not be available/live anymore
+  return (
+    (sessionState.created === undefined || dateNow() - Number(sessionState.created) < SESSION_TIME_OUT_DELAY) &&
+    (sessionState.expire === undefined || dateNow() < Number(sessionState.expire))
+  )
+}
+
+export function expandSessionState(session: SessionState) {
+  session.expire = String(dateNow() + SESSION_EXPIRATION_DELAY)
+}
+
+export function toSessionString(session: SessionState) {
+  return (
+    objectEntries(session)
+      // we use `aid` as a key for anonymousId
+      .map(([key, value]) => (key === 'anonymousId' ? `aid=${value}` : `${key}=${value}`))
+      .join(SESSION_ENTRY_SEPARATOR)
+  )
+}
+
+export function toSessionState(sessionString: string | undefined | null) {
+  const session: SessionState = {}
+  if (isValidSessionString(sessionString)) {
+    sessionString.split(SESSION_ENTRY_SEPARATOR).forEach((entry) => {
+      const matches = SESSION_ENTRY_REGEXP.exec(entry)
+      if (matches !== null) {
+        const [, key, value] = matches
+        if (key === 'aid') {
+          // we use `aid` as a key for anonymousId
+          session.anonymousId = value
+        } else {
+          session[key] = value
+        }
+      }
+    })
+  }
+  return session
+}

package/src/domain/session/sessionStateValidation.ts

@@ -0,0 +1,9 @@
+export const SESSION_ENTRY_REGEXP = /^([a-zA-Z]+)=([a-z0-9-]+)$/
+export const SESSION_ENTRY_SEPARATOR = '&'
+
+export function isValidSessionString(sessionString: string | undefined | null): sessionString is string {
+  return (
+    !!sessionString &&
+    (sessionString.indexOf(SESSION_ENTRY_SEPARATOR) !== -1 || SESSION_ENTRY_REGEXP.test(sessionString))
+  )
+}