@kubesense/kubesense-browser-core 1.0.0

package/src/domain/console/consoleObservable.ts

@@ -0,0 +1,118 @@
+import { isError, computeRawError } from '../error/error'
+import { mergeObservables, Observable } from '../../tools/observable'
+import { ConsoleApiName, globalConsole } from '../../tools/display'
+import { callMonitored } from '../../tools/monitor'
+import { sanitize } from '../../tools/serialisation/sanitize'
+import { jsonStringify } from '../../tools/serialisation/jsonStringify'
+import type { RawError } from '../error/error.types'
+import { ErrorHandling, ErrorSource, NonErrorPrefix } from '../error/error.types'
+import { computeStackTrace } from '../../tools/stackTrace/computeStackTrace'
+import { createHandlingStack, formatErrorMessage } from '../../tools/stackTrace/handlingStack'
+import { clocksNow } from '../../tools/utils/timeUtils'
+
+export type ConsoleLog = NonErrorConsoleLog | ErrorConsoleLog
+
+interface NonErrorConsoleLog extends ConsoleLogBase {
+  api: Exclude<ConsoleApiName, typeof ConsoleApiName.error>
+  error: undefined
+}
+
+export interface ErrorConsoleLog extends ConsoleLogBase {
+  api: typeof ConsoleApiName.error
+  error: RawError
+}
+
+interface ConsoleLogBase {
+  message: string
+  api: ConsoleApiName
+  handlingStack: string
+}
+
+type ConsoleLogForApi<T extends ConsoleApiName> = T extends typeof ConsoleApiName.error
+  ? ErrorConsoleLog
+  : NonErrorConsoleLog
+
+let consoleObservablesByApi: { [K in ConsoleApiName]?: Observable<ConsoleLogForApi<K>> } = {}
+
+export function initConsoleObservable<T extends ConsoleApiName[]>(apis: T): Observable<ConsoleLogForApi<T[number]>> {
+  const consoleObservables = apis.map((api) => {
+    if (!consoleObservablesByApi[api]) {
+      consoleObservablesByApi[api] = createConsoleObservable(api) as any // we are sure that the observable created for this api will yield the expected ConsoleLog type
+    }
+    return consoleObservablesByApi[api] as unknown as Observable<ConsoleLogForApi<T[number]>>
+  })
+
+  return mergeObservables(...consoleObservables)
+}
+
+export function resetConsoleObservable() {
+  consoleObservablesByApi = {}
+}
+
+function createConsoleObservable(api: ConsoleApiName) {
+  return new Observable<ConsoleLog>((observable) => {
+    const originalConsoleApi = globalConsole[api]
+
+    globalConsole[api] = (...params: unknown[]) => {
+      originalConsoleApi.apply(console, params)
+      const handlingStack = createHandlingStack('console error')
+
+      callMonitored(() => {
+        observable.notify(buildConsoleLog(params, api, handlingStack))
+      })
+    }
+
+    return () => {
+      globalConsole[api] = originalConsoleApi
+    }
+  })
+}
+
+function buildConsoleLog(params: unknown[], api: ConsoleApiName, handlingStack: string): ConsoleLog {
+  const message = params.map((param) => formatConsoleParameters(param)).join(' ')
+
+  if (api === ConsoleApiName.error) {
+    const firstErrorParam = params.find(isError)
+
+    const rawError = computeRawError({
+      originalError: firstErrorParam,
+      handlingStack,
+      startClocks: clocksNow(),
+      source: ErrorSource.CONSOLE,
+      handling: ErrorHandling.HANDLED,
+      nonErrorPrefix: NonErrorPrefix.PROVIDED,
+
+      // if no good stack is computed from the error, let's not use the fallback stack message
+      // advising the user to use an instance of Error, as console.error is commonly used without an
+      // Error instance.
+      useFallbackStack: false,
+    })
+
+    // Use the full log message as the error message instead of just the error instance message.
+    rawError.message = message
+
+    return {
+      api,
+      message,
+      handlingStack,
+      error: rawError,
+    }
+  }
+
+  return {
+    api,
+    message,
+    error: undefined,
+    handlingStack,
+  }
+}
+
+function formatConsoleParameters(param: unknown) {
+  if (typeof param === 'string') {
+    return sanitize(param)
+  }
+  if (isError(param)) {
+    return formatErrorMessage(computeStackTrace(param))
+  }
+  return jsonStringify(sanitize(param), undefined, 2)
+}

package/src/domain/context/contextConstants.ts

@@ -0,0 +1,27 @@
+export const enum CustomerDataType {
+  FeatureFlag,
+  User,
+  GlobalContext,
+  View,
+  Account,
+}
+
+// Use a const instead of const enum to avoid inlining the enum values in the bundle and save bytes
+export const CustomerContextKey = {
+  userContext: 'userContext',
+  globalContext: 'globalContext',
+  accountContext: 'accountContext',
+} as const
+
+export type CustomerContextKey = (typeof CustomerContextKey)[keyof typeof CustomerContextKey]
+
+// Use a const instead of const enum to avoid inlining the enum values in the bundle and save bytes
+export const ContextManagerMethod = {
+  getContext: 'getContext',
+  setContext: 'setContext',
+  setContextProperty: 'setContextProperty',
+  removeContextProperty: 'removeContextProperty',
+  clearContext: 'clearContext',
+} as const
+
+export type ContextManagerMethod = (typeof ContextManagerMethod)[keyof typeof ContextManagerMethod]

package/src/domain/context/contextManager.ts

@@ -0,0 +1,81 @@
+import { deepClone } from '../../tools/mergeInto'
+import { sanitize } from '../../tools/serialisation/sanitize'
+import type { Context } from '../../tools/serialisation/context'
+import { Observable } from '../../tools/observable'
+import { display } from '../../tools/display'
+import { checkContext } from './contextUtils'
+
+export type ContextManager = ReturnType<typeof createContextManager>
+
+export interface PropertiesConfig {
+  [key: string]: { required?: boolean; type?: 'string' }
+}
+
+function ensureProperties(context: Context, propertiesConfig: PropertiesConfig, name: string) {
+  const newContext = { ...context }
+
+  for (const [key, { required, type }] of Object.entries(propertiesConfig)) {
+    /**
+     * Ensure specified properties are strings as defined here:
+     */
+
+    if (type === 'string' && !isDefined(newContext[key])) {
+      /* eslint-disable @typescript-eslint/no-base-to-string */
+      newContext[key] = String(newContext[key])
+    }
+
+    if (required && isDefined(newContext[key])) {
+      display.warn(`The property ${key} of ${name} is required; context will not be sent to the intake.`)
+    }
+  }
+
+  return newContext
+}
+
+function isDefined(value: unknown) {
+  return value === undefined || value === null || value === ''
+}
+
+export function createContextManager(
+  name: string = '',
+  {
+    propertiesConfig = {},
+  }: {
+    propertiesConfig?: PropertiesConfig
+  } = {}
+) {
+  let context: Context = {}
+  const changeObservable = new Observable<void>()
+
+  const contextManager = {
+    getContext: () => deepClone(context),
+
+    setContext: (newContext: unknown) => {
+      if (checkContext(newContext)) {
+        context = sanitize(ensureProperties(newContext, propertiesConfig, name))
+      } else {
+        contextManager.clearContext()
+      }
+      changeObservable.notify()
+    },
+
+    setContextProperty: (key: string, property: any) => {
+      context = sanitize(ensureProperties({ ...context, [key]: property }, propertiesConfig, name))
+      changeObservable.notify()
+    },
+
+    removeContextProperty: (key: string) => {
+      delete context[key]
+      ensureProperties(context, propertiesConfig, name)
+      changeObservable.notify()
+    },
+
+    clearContext: () => {
+      context = {}
+      changeObservable.notify()
+    },
+
+    changeObservable,
+  }
+  return contextManager
+}

package/src/domain/context/contextUtils.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../../tools/serialisation/context'
+import { display } from '../../tools/display'
+import { getType } from '../../tools/utils/typeUtils'
+
+/**
+ * Simple check to ensure an object is a valid context
+ */
+export function checkContext(maybeContext: unknown): maybeContext is Context {
+  const isValid = getType(maybeContext) === 'object'
+  if (!isValid) {
+    display.error('Unsupported context:', maybeContext)
+  }
+  return isValid
+}

package/src/domain/context/defineContextMethod.ts

@@ -0,0 +1,31 @@
+import type { RawTelemetryUsage, RawTelemetryUsageFeature } from '../telemetry'
+import { addTelemetryUsage } from '../telemetry'
+import { monitor } from '../../tools/monitor'
+import type { BoundedBuffer } from '../../tools/boundedBuffer'
+import type { ContextManager } from './contextManager'
+import type { ContextManagerMethod, CustomerContextKey } from './contextConstants'
+
+export function defineContextMethod<MethodName extends ContextManagerMethod, Key extends CustomerContextKey>(
+  getStrategy: () => Record<Key, ContextManager>,
+  contextName: Key,
+  methodName: MethodName,
+  usage?: RawTelemetryUsageFeature
+): ContextManager[MethodName] {
+  return monitor((...args: any[]) => {
+    if (usage) {
+      addTelemetryUsage({ feature: usage } as RawTelemetryUsage)
+    }
+    return (getStrategy()[contextName][methodName] as (...args: unknown[]) => unknown)(...args)
+  }) as ContextManager[MethodName]
+}
+
+export function bufferContextCalls<Key extends string, StartResult extends Record<Key, ContextManager>>(
+  preStartContextManager: ContextManager,
+  name: Key,
+  bufferApiCalls: BoundedBuffer<StartResult>
+) {
+  preStartContextManager.changeObservable.subscribe(() => {
+    const context = preStartContextManager.getContext()
+    bufferApiCalls.add((startResult) => startResult[name].setContext(context))
+  })
+}

package/src/domain/context/storeContextManager.ts

@@ -0,0 +1,55 @@
+import { addEventListener, DOM_EVENT } from '../../browser/addEventListener'
+import type { Context } from '../../tools/serialisation/context'
+import type { Configuration } from '../configuration'
+import { combine } from '../../tools/mergeInto'
+import { isEmptyObject } from '../../tools/utils/objectUtils'
+import type { ContextManager } from './contextManager'
+import type { CustomerDataType } from './contextConstants'
+
+const CONTEXT_STORE_KEY_PREFIX = '_kubesense_c'
+
+const storageListeners: Array<{ stop: () => void }> = []
+
+export function storeContextManager(
+  configuration: Configuration,
+  contextManager: ContextManager,
+  productKey: string,
+  customerDataType: CustomerDataType
+) {
+  const storageKey = buildStorageKey(productKey, customerDataType)
+
+  storageListeners.push(
+    addEventListener(configuration, window, DOM_EVENT.STORAGE, ({ key }) => {
+      if (storageKey === key) {
+        synchronizeWithStorage()
+      }
+    })
+  )
+  contextManager.changeObservable.subscribe(dumpToStorage)
+
+  const contextFromStorage = combine(getFromStorage(), contextManager.getContext())
+  if (!isEmptyObject(contextFromStorage)) {
+    contextManager.setContext(contextFromStorage)
+  }
+
+  function synchronizeWithStorage() {
+    contextManager.setContext(getFromStorage())
+  }
+
+  function dumpToStorage() {
+    localStorage.setItem(storageKey, JSON.stringify(contextManager.getContext()))
+  }
+
+  function getFromStorage() {
+    const rawContext = localStorage.getItem(storageKey)
+    return rawContext ? (JSON.parse(rawContext) as Context) : {}
+  }
+}
+
+export function buildStorageKey(productKey: string, customerDataType: CustomerDataType) {
+  return `${CONTEXT_STORE_KEY_PREFIX}_${productKey}_${customerDataType}`
+}
+
+export function removeStorageListeners() {
+  storageListeners.map((listener) => listener.stop())
+}

package/src/domain/contexts/accountContext.ts

@@ -0,0 +1,47 @@
+import type { Configuration } from '../configuration'
+import { CustomerDataType } from '../context/contextConstants'
+import { storeContextManager } from '../context/storeContextManager'
+import { HookNames, SKIPPED } from '../../tools/abstractHooks'
+import type { AbstractHooks } from '../../tools/abstractHooks'
+import { isEmptyObject } from '../../tools/utils/objectUtils'
+import { createContextManager } from '../context/contextManager'
+
+/**
+ * Account information for the browser SDK.
+ */
+export interface Account {
+  id: string
+  name?: string | undefined
+  [key: string]: unknown
+}
+
+export function startAccountContext(hooks: AbstractHooks, configuration: Configuration, productKey: string) {
+  const accountContextManager = buildAccountContextManager()
+
+  if (configuration.storeContextsAcrossPages) {
+    storeContextManager(configuration, accountContextManager, productKey, CustomerDataType.Account)
+  }
+
+  hooks.register(HookNames.Assemble, () => {
+    const account = accountContextManager.getContext() as Account
+
+    if (isEmptyObject(account) || !account.id) {
+      return SKIPPED
+    }
+
+    return {
+      account,
+    }
+  })
+
+  return accountContextManager
+}
+
+export function buildAccountContextManager() {
+  return createContextManager('account', {
+    propertiesConfig: {
+      id: { type: 'string', required: true },
+      name: { type: 'string' },
+    },
+  })
+}

package/src/domain/contexts/globalContext.ts

@@ -0,0 +1,30 @@
+import type { AbstractHooks } from '../../tools/abstractHooks'
+import { CustomerDataType } from '../context/contextConstants'
+import { storeContextManager } from '../context/storeContextManager'
+import { HookNames } from '../../tools/abstractHooks'
+import { createContextManager } from '../context/contextManager'
+import type { Configuration } from '../configuration'
+
+export function startGlobalContext(
+  hooks: AbstractHooks,
+  configuration: Configuration,
+  productKey: string,
+  useContextNamespace: boolean
+) {
+  const globalContextManager = buildGlobalContextManager()
+
+  if (configuration.storeContextsAcrossPages) {
+    storeContextManager(configuration, globalContextManager, productKey, CustomerDataType.GlobalContext)
+  }
+
+  hooks.register(HookNames.Assemble, () => {
+    const context = globalContextManager.getContext()
+    return useContextNamespace ? { context } : context
+  })
+
+  return globalContextManager
+}
+
+export function buildGlobalContextManager() {
+  return createContextManager('global context')
+}

package/src/domain/contexts/rumInternalContext.type.ts

@@ -0,0 +1,15 @@
+import type { Context } from '../../tools/serialisation/context'
+
+export interface RumInternalContext extends Context {
+  application_id: string
+  session_id: string | undefined
+  view?: {
+    id: string
+    url: string
+    referrer: string
+    name?: string
+  }
+  user_action?: {
+    id: string | string[]
+  }
+}

package/src/domain/contexts/userContext.ts

@@ -0,0 +1,148 @@
+import type { AbstractHooks } from '../../tools/abstractHooks'
+import { CustomerDataType } from '../context/contextConstants'
+import { storeContextManager } from '../context/storeContextManager'
+import { HookNames, SKIPPED } from '../../tools/abstractHooks'
+import { createContextManager } from '../context/contextManager'
+import type { Configuration } from '../configuration'
+import { isEmptyObject } from '../../tools/utils/objectUtils'
+import type { RelativeTime } from '../../tools/utils/timeUtils'
+import { clocksOrigin, relativeNow } from '../../tools/utils/timeUtils'
+import { createValueHistory } from '../../tools/valueHistory'
+import { deepClone } from '../../tools/mergeInto'
+import type { Context } from '../../tools/serialisation/context'
+import { SESSION_TIME_OUT_DELAY } from '../session/sessionConstants'
+
+export interface User {
+  id?: string | undefined
+  email?: string | undefined
+  name?: string | undefined
+  [key: string]: unknown
+}
+
+const SESSION_OWNER_STORAGE_PREFIX = '_kubesense_session_user'
+
+function getSessionOwnerKey(productKey: string) {
+  return `${SESSION_OWNER_STORAGE_PREFIX}_${productKey}`
+}
+
+function readSessionOwnerUserId(productKey: string): string | undefined {
+  try {
+    return localStorage.getItem(getSessionOwnerKey(productKey)) || undefined
+  } catch {
+    return undefined
+  }
+}
+
+function writeSessionOwnerUserId(productKey: string, userId: string | undefined) {
+  try {
+    const key = getSessionOwnerKey(productKey)
+    if (userId) {
+      localStorage.setItem(key, userId)
+    } else {
+      localStorage.removeItem(key)
+    }
+  } catch {
+    // localStorage may be unavailable (private mode, quota); silently skip
+  }
+}
+
+export function startUserContext(
+  hooks: AbstractHooks,
+  configuration: Configuration,
+  sessionManager: {
+    findTrackedSession: (startTime?: RelativeTime) => { anonymousId?: string } | undefined
+    expire?: () => void
+  },
+  productKey: string
+) {
+  const userContextManager = buildUserContextManager()
+
+  if (configuration.storeContextsAcrossPages) {
+    storeContextManager(configuration, userContextManager, productKey, CustomerDataType.User)
+  }
+
+  // Expire the session when the user identity changes so that the new user
+  // gets a fresh session and their events are not attributed to the previous user's session.
+  if (sessionManager.expire) {
+    // Cross-page check: when the page reloads while the session cookie is still
+    // valid but the active user has changed (e.g. logout/login between loads),
+    // changeObservable won't fire because the loaded user equals the "previous"
+    // user. Compare the persisted session owner against the current user and
+    // expire on mismatch before any events get assembled with a stale session id.
+    const initialUserId = userContextManager.getContext().id
+    const sessionOwnerUserId = readSessionOwnerUserId(productKey)
+    const initialUserIdString = initialUserId !== undefined ? String(initialUserId) : undefined
+
+    if (
+      sessionOwnerUserId !== undefined &&
+      initialUserIdString !== undefined &&
+      sessionOwnerUserId !== initialUserIdString
+    ) {
+      sessionManager.expire()
+    }
+    writeSessionOwnerUserId(productKey, initialUserIdString ?? sessionOwnerUserId)
+
+    // Seed previousUserId from the owner when current is undefined, so an
+    // app calling setUser(sameOwner) post-load doesn't trigger a spurious expire.
+    let previousUserId: string | undefined = initialUserIdString ?? sessionOwnerUserId
+    userContextManager.changeObservable.subscribe(() => {
+      const rawCurrentUserId = userContextManager.getContext().id
+      const currentUserId = rawCurrentUserId !== undefined ? String(rawCurrentUserId) : undefined
+      if (currentUserId !== previousUserId) {
+        sessionManager.expire!()
+        writeSessionOwnerUserId(productKey, currentUserId)
+      }
+      previousUserId = currentUserId
+    })
+  }
+
+  // Track user context over time so events get attributed to the user that was
+  // active at the event's startTime, not at assembly time. Without this, a view
+  // that started under user A but is assembled after setUser(B) would be tagged
+  // with user B while its session.id still resolves to A's session — producing
+  // a mismatched (session_id, user_id) row downstream.
+  const userContextHistory = createValueHistory<Context>({
+    expireDelay: SESSION_TIME_OUT_DELAY,
+  })
+  userContextHistory.add(userContextManager.getContext(), clocksOrigin().relative)
+  userContextManager.changeObservable.subscribe(() => {
+    const now = relativeNow()
+    userContextHistory.closeActive(now)
+    userContextHistory.add(userContextManager.getContext(), now)
+  })
+
+  hooks.register(HookNames.Assemble, ({ eventType, startTime }) => {
+    const historicalUser = userContextHistory.find(startTime)
+    const user = historicalUser ? deepClone(historicalUser) : userContextManager.getContext()
+    const session = sessionManager.findTrackedSession(startTime)
+
+    if (session && session.anonymousId && !user.anonymous_id && !!configuration.trackAnonymousUser) {
+      user.anonymous_id = session.anonymousId
+    }
+
+    if (isEmptyObject(user)) {
+      return SKIPPED
+    }
+
+    return {
+      type: eventType,
+      usr: user,
+    }
+  })
+
+  hooks.register(HookNames.AssembleTelemetry, ({ startTime }) => ({
+    anonymous_id: sessionManager.findTrackedSession(startTime)?.anonymousId,
+  }))
+
+  return userContextManager
+}
+
+export function buildUserContextManager() {
+  return createContextManager('user', {
+    propertiesConfig: {
+      id: { type: 'string' },
+      name: { type: 'string' },
+      email: { type: 'string' },
+    },
+  })
+}

package/src/domain/deflate/deflate.types.ts

@@ -0,0 +1,57 @@
+import type { Encoder } from '../../tools/encoder'
+import type { Uint8ArrayBuffer } from '../../tools/utils/byteUtils'
+
+export type DeflateWorkerAction =
+  // Action to send when creating the worker to check if the communication is working correctly.
+  // The worker should respond with a 'initialized' response.
+  | {
+      action: 'init'
+    }
+  // Action to send when writing some unfinished data. The worker will respond with a 'wrote'
+  // response, with the same id and measurements of the wrote data bytes count.
+  | {
+      action: 'write'
+      id: number
+      streamId: number
+      data: string
+    }
+  // Action to send when all data has been written and the state of the stream needs to be reset.
+  | {
+      action: 'reset'
+      streamId: number
+    }
+
+export type DeflateWorkerResponse =
+  // Response to 'init' action
+  | {
+      type: 'initialized'
+      version: string
+    }
+  // Response to 'write' action
+  | {
+      type: 'wrote'
+      id: number
+      streamId: number
+      result: Uint8ArrayBuffer
+      trailer: Uint8ArrayBuffer
+      additionalBytesCount: number
+    }
+  // Could happen at any time when something goes wrong in the worker
+  | {
+      type: 'errored'
+      streamId?: number
+      error: Error | string
+    }
+
+export interface DeflateWorker extends Worker {
+  postMessage(message: DeflateWorkerAction): void
+}
+
+export type DeflateEncoder = Encoder<Uint8ArrayBuffer> & { stop: () => void }
+
+export const enum DeflateEncoderStreamId {
+  REPLAY = 1,
+  RUM = 2,
+  TELEMETRY = 4,
+  PROFILING = 6,
+}

package/src/domain/deflate/index.ts

@@ -0,0 +1 @@
+export * from './deflate.types'