@openobserve/browser-core 0.2.11-rc1 → 0.2.12-beta.1

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

@@ -2,7 +2,7 @@ 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, isSessionInExpiredState } from './sessionState'
+import { expandSessionState, isSessionStarted } from './sessionState'
 
 export const OLD_SESSION_COOKIE_NAME = '_oo'
 export const OLD_RUM_COOKIE_NAME = '_oo_r'
@@ -34,7 +34,7 @@ export function tryOldCookiesMigration(cookieStoreStrategy: SessionStoreStrategy
       session[RUM_SESSION_KEY] = oldRumType
     }
 
-    if (!isSessionInExpiredState(session)) {
+    if (isSessionStarted(session)) {
       expandSessionState(session)
       cookieStoreStrategy.persistSession(session)
     }

package/src/domain/session/sessionConstants.ts

@@ -1,4 +1,19 @@
-import { ONE_HOUR, ONE_MINUTE } from '../../tools/utils/timeUtils'
+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

@@ -1,24 +1,44 @@
-import type { Observable } from '../../tools/observable'
+import { Observable } from '../../tools/observable'
 import type { Context } from '../../tools/serialisation/context'
-import { ValueHistory } from '../../tools/valueHistory'
+import { createValueHistory } from '../../tools/valueHistory'
 import type { RelativeTime } from '../../tools/utils/timeUtils'
-import { relativeNow, clocksOrigin, ONE_MINUTE } from '../../tools/utils/timeUtils'
-import { DOM_EVENT, addEventListener, addEventListeners } from '../../browser/addEventListener'
+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 { SESSION_TIME_OUT_DELAY } from './sessionConstants'
+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, SessionPersistence } 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'
+import { retrieveSessionFromLocalStorage } from './storeStrategies/sessionInLocalStorage'
 
 export interface SessionManager<TrackingType extends string> {
-  findActiveSession: (startTime?: RelativeTime) => SessionContext<TrackingType> | undefined
+  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
@@ -28,40 +48,91 @@ let stopCallbacks: Array<() => void> = []
 export function startSessionManager<TrackingType extends string>(
   configuration: Configuration,
   productKey: string,
-  computeSessionState: (rawTrackingType?: string) => { trackingType: TrackingType; isTracked: boolean }
+  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!, productKey, computeSessionState)
+  const sessionStore = startSessionStore(
+    configuration.sessionStoreStrategyType!,
+    configuration,
+    productKey,
+    computeTrackingType
+  )
   stopCallbacks.push(() => sessionStore.stop())
 
-  const sessionContextHistory = new ValueHistory<SessionContext<TrackingType>>(SESSION_CONTEXT_TIMEOUT_DELAY)
+  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)
+    }
+  }
 
-  trackActivity(configuration, () => sessionStore.expandOrRenewSession())
+  trackingConsentState.observable.subscribe(() => {
+    if (trackingConsentState.isGranted()) {
+      sessionStore.expandOrRenewSession()
+    } else {
+      sessionStore.expire(false)
+    }
+  })
+
+  trackActivity(configuration, () => {
+    if (trackingConsentState.isGranted()) {
+      sessionStore.expandOrRenewSession()
+    }
+  })
   trackVisibility(configuration, () => sessionStore.expandSession())
+  trackResume(configuration, () => sessionStore.restartSession())
 
   function buildSessionContext() {
+    const session = sessionStore.getSession()
+
+    if (!session) {
+      reportUnexpectedSessionState(configuration).catch(() => void 0) // Ignore errors
+
+      return {
+        id: 'invalid',
+        trackingType: SESSION_NOT_TRACKED as TrackingType,
+        isReplayForced: false,
+        anonymousId: undefined,
+      }
+    }
+
     return {
-      id: sessionStore.getSession().id!,
-      trackingType: sessionStore.getSession()[productKey] as TrackingType,
+      id: session.id!,
+      trackingType: session[productKey] as TrackingType,
+      isReplayForced: !!session.forcedReplay,
+      anonymousId: session.anonymousId,
     }
   }
 
   return {
-    findActiveSession: (startTime) => sessionContextHistory.find(startTime),
-    renewObservable: sessionStore.renewObservable,
-    expireObservable: sessionStore.expireObservable,
+    findSession: (startTime, options) => sessionContextHistory.find(startTime, options),
+    renewObservable,
+    expireObservable,
+    sessionStateUpdateObservable: sessionStore.sessionStateUpdateObservable,
     expire: sessionStore.expire,
+    updateSessionState: sessionStore.updateSessionState,
   }
 }
 
@@ -96,3 +167,96 @@ function trackVisibility(configuration: Configuration, expandSession: () => void
     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(configuration: Configuration) {
+  const sessionStoreStrategyType = configuration.sessionStoreStrategyType
+  if (!sessionStoreStrategyType) {
+    return
+  }
+
+  let rawSession
+  let cookieContext
+
+  if (sessionStoreStrategyType.type === SessionPersistence.COOKIE) {
+    rawSession = retrieveSessionCookie(sessionStoreStrategyType.cookieOptions, configuration)
+
+    cookieContext = {
+      cookie: await getSessionCookies(),
+      currentDomain: `${window.location.protocol}//${window.location.hostname}`,
+    }
+  } else {
+    rawSession = retrieveSessionFromLocalStorage()
+  }
+  // monitor-until: forever, could be handy to troubleshoot issues until session manager rework
+  addTelemetryDebug('Unexpected session state', {
+    sessionStoreStrategyType: sessionStoreStrategyType.type,
+    session: rawSession,
+    isSyntheticsTest: isSyntheticsTest(),
+    createdTimestamp: rawSession?.created,
+    expireTimestamp: rawSession?.expire,
+    ...cookieContext,
+  })
+}
+
+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

@@ -1,32 +1,66 @@
 import { isEmptyObject } from '../../tools/utils/objectUtils'
 import { objectEntries } from '../../tools/utils/polyfills'
 import { dateNow } from '../../tools/utils/timeUtils'
-import { SESSION_EXPIRATION_DELAY } from './sessionConstants'
-
-const SESSION_ENTRY_REGEXP = /^([a-z]+)=([a-z0-9-]+)$/
-const SESSION_ENTRY_SEPARATOR = '&'
+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
-  lock?: string
+  isExpired?: typeof EXPIRED
 
   [key: string]: string | undefined
 }
 
-export function isSessionInExpiredState(session: SessionState) {
+export function getExpiredSessionState(
+  previousSessionState: SessionState | undefined,
+  configuration: Configuration
+): SessionState {
+  const expiredSessionState: SessionState = {
+    isExpired: EXPIRED,
+  }
+  if (configuration.trackAnonymousUser && previousSessionState?.anonymousId) {
+    expiredSessionState.anonymousId = previousSessionState?.anonymousId
+  }
+  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)
-    .map(([key, value]) => `${key}=${value as string}`)
-    .join(SESSION_ENTRY_SEPARATOR)
+  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) {
@@ -36,16 +70,14 @@ export function toSessionState(sessionString: string | undefined | null) {
       const matches = SESSION_ENTRY_REGEXP.exec(entry)
       if (matches !== null) {
         const [, key, value] = matches
-        session[key] = value
+        if (key === 'aid') {
+          // we use `aid` as a key for anonymousId
+          session.anonymousId = value
+        } else {
+          session[key] = value
+        }
       }
     })
   }
   return session
 }
-
-function isValidSessionString(sessionString: string | undefined | null): sessionString is string {
-  return (
-    !!sessionString &&
-    (sessionString.indexOf(SESSION_ENTRY_SEPARATOR) !== -1 || SESSION_ENTRY_REGEXP.test(sessionString))
-  )
-}

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))
+  )
+}