@kubesense/kubesense-browser-rum-core 1.0.0

package/src/domain/resource/matchRequestResourceEntry.ts

@@ -0,0 +1,68 @@
+import type { Duration, RelativeTime } from '@kubesense/kubesense-browser-core'
+import { addDuration } from '@kubesense/kubesense-browser-core'
+import type { RumPerformanceResourceTiming } from '../../browser/performanceObservable'
+import type { RequestCompleteEvent } from '../requestCollection'
+import { hasValidResourceEntryDuration } from './resourceUtils'
+
+interface Timing {
+  startTime: RelativeTime
+  duration: Duration
+}
+
+const alreadyMatchedEntries = new WeakSet<PerformanceEntry>()
+
+/**
+ * Look for corresponding timing in resource timing buffer
+ *
+ * Observations:
+ * - Timing (start, end) are nested inside the request (start, end)
+ * - Some timing can be not exactly nested, being off by < 1 ms
+ *
+ * Strategy:
+ * - from valid nested entries (with 1 ms error margin)
+ * - filter out timing that were already matched to a request
+ * - then, if a single timing match, return the timing
+ * - otherwise we can't decide, return undefined
+ */
+export function matchRequestResourceEntry(request: RequestCompleteEvent) {
+  if (!performance || !('getEntriesByName' in performance)) {
+    return
+  }
+  const sameNameEntries = performance.getEntriesByName(request.url, 'resource') as RumPerformanceResourceTiming[]
+
+  if (!sameNameEntries.length || !('toJSON' in sameNameEntries[0])) {
+    return
+  }
+
+  const candidates = sameNameEntries
+    .filter((entry) => !alreadyMatchedEntries.has(entry))
+    // Only require valid duration — needed for the isBetween time-window check.
+    // hasValidResourceEntryTimings is intentionally NOT used here: cached resources often have
+    // timing fields zeroed out (browser behaviour) even though their duration and start time
+    // are correct and the entry should still be matched to its request.
+    .filter((entry) => hasValidResourceEntryDuration(entry))
+    .filter((entry) =>
+      isBetween(
+        entry,
+        request.startClocks.relative,
+        endTime({ startTime: request.startClocks.relative, duration: request.duration })
+      )
+    )
+
+  if (candidates.length === 1) {
+    alreadyMatchedEntries.add(candidates[0])
+
+    return candidates[0].toJSON() as RumPerformanceResourceTiming
+  }
+
+  return
+}
+
+function endTime(timing: Timing) {
+  return addDuration(timing.startTime, timing.duration)
+}
+
+function isBetween(timing: Timing, start: RelativeTime, end: RelativeTime) {
+  const errorMargin = 1 as Duration
+  return timing.startTime >= start - errorMargin && endTime(timing) <= addDuration(end, errorMargin)
+}

package/src/domain/resource/requestRegistry.ts

@@ -0,0 +1,52 @@
+import { addTelemetryDebug } from '@kubesense/kubesense-browser-core'
+import type { RumPerformanceResourceTiming } from '../../browser/performanceObservable'
+import type { LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { RequestCompleteEvent } from '../requestCollection'
+
+export interface RequestRegistry {
+  getMatchingRequest(entry: RumPerformanceResourceTiming): RequestCompleteEvent | undefined
+  stop(): void
+}
+
+// Maximum number of requests to keep in the registry. Requests should be removed quite quickly in
+// general, this is just a safety limit to avoid memory leaks in case of a bug.
+export const MAX_REQUESTS = 1000
+
+export function createRequestRegistry(lifeCycle: LifeCycle): RequestRegistry {
+  const requests = new Set<RequestCompleteEvent>()
+
+  const subscription = lifeCycle.subscribe(LifeCycleEventType.REQUEST_COMPLETED, (request) => {
+    requests.add(request)
+    if (requests.size > MAX_REQUESTS) {
+      // monitor-until: 2026-01-01, after early request collection GA
+      addTelemetryDebug('Too many requests')
+      requests.delete(requests.values().next().value!)
+    }
+  })
+
+  return {
+    getMatchingRequest(entry) {
+      // Returns the closest request object that happened before the entry
+      let minTimeDifference = Infinity
+      let closestRequest: RequestCompleteEvent | undefined
+      for (const request of requests) {
+        const timeDifference = entry.startTime - request.startClocks.relative
+        if (0 <= timeDifference && timeDifference < minTimeDifference && request.url === entry.name) {
+          minTimeDifference = Math.abs(timeDifference)
+          closestRequest = request
+        }
+      }
+
+      if (closestRequest) {
+        requests.delete(closestRequest)
+      }
+
+      return closestRequest
+    },
+
+    stop() {
+      subscription.unsubscribe()
+    },
+  }
+}

package/src/domain/resource/resourceCollection.ts

@@ -0,0 +1,273 @@
+import type { ClocksState, Duration } from '@kubesense/kubesense-browser-core'
+import {
+  combine,
+  generateUUID,
+  RequestType,
+  ResourceType,
+  toServerDuration,
+  relativeToClocks,
+  createTaskQueue,
+} from '@kubesense/kubesense-browser-core'
+import type { RumConfiguration } from '../configuration'
+import type { RumPerformanceResourceTiming } from '../../browser/performanceObservable'
+import { RumPerformanceEntryType, createPerformanceObservable } from '../../browser/performanceObservable'
+import type {
+  RumXhrResourceEventDomainContext,
+  RumFetchResourceEventDomainContext,
+  RumOtherResourceEventDomainContext,
+} from '../../domainContext.types'
+import type { RawRumResourceEvent } from '../../rawRumEvent.types'
+import { RumEventType } from '../../rawRumEvent.types'
+import type { RawRumEventCollectedData, LifeCycle } from '../lifeCycle'
+import { LifeCycleEventType } from '../lifeCycle'
+import type { RequestCompleteEvent } from '../requestCollection'
+import type { PageStateHistory } from '../contexts/pageStateHistory'
+import { PageState } from '../contexts/pageStateHistory'
+import { createSpanIdentifier } from '../tracing/identifier'
+import { matchRequestResourceEntry } from './matchRequestResourceEntry'
+import {
+  computeResourceEntryDetails,
+  computeResourceEntryDuration,
+  computeResourceEntryType,
+  computeResourceEntrySize,
+  computeResourceEntryProtocol,
+  computeResourceEntryDeliveryType,
+  computeResourceProvider,
+  isResourceEntryRequestType,
+  sanitizeIfLongDataUrl,
+} from './resourceUtils'
+import { retrieveInitialDocumentResourceTiming } from './retrieveInitialDocumentResourceTiming'
+import type { RequestRegistry } from './requestRegistry'
+import { createRequestRegistry } from './requestRegistry'
+import type { GraphQlMetadata } from './graphql'
+import { extractGraphQlMetadata, findGraphQlConfiguration } from './graphql'
+
+export function startResourceCollection(
+  lifeCycle: LifeCycle,
+  configuration: RumConfiguration,
+  pageStateHistory: PageStateHistory,
+  taskQueue = createTaskQueue(),
+  retrieveInitialDocumentResourceTimingImpl = retrieveInitialDocumentResourceTiming
+) {
+  let requestRegistry: RequestRegistry | undefined
+  const isEarlyRequestCollectionEnabled = configuration.trackEarlyRequests
+
+  if (isEarlyRequestCollectionEnabled) {
+    requestRegistry = createRequestRegistry(lifeCycle)
+  } else {
+    lifeCycle.subscribe(LifeCycleEventType.REQUEST_COMPLETED, (request: RequestCompleteEvent) => {
+      handleResource(() => processRequest(request, configuration, pageStateHistory))
+    })
+  }
+
+  const performanceResourceSubscription = createPerformanceObservable(configuration, {
+    type: RumPerformanceEntryType.RESOURCE,
+    buffered: true,
+  }).subscribe((entries) => {
+    for (const entry of entries) {
+      if (isEarlyRequestCollectionEnabled || !isResourceEntryRequestType(entry)) {
+        handleResource(() => processResourceEntry(entry, configuration, pageStateHistory, requestRegistry))
+      }
+    }
+  })
+
+  retrieveInitialDocumentResourceTimingImpl(configuration, (timing) => {
+    handleResource(() => processResourceEntry(timing, configuration, pageStateHistory, requestRegistry))
+  })
+
+  function handleResource(computeRawEvent: () => RawRumEventCollectedData<RawRumResourceEvent> | undefined) {
+    taskQueue.push(() => {
+      const rawEvent = computeRawEvent()
+      if (rawEvent) {
+        lifeCycle.notify(LifeCycleEventType.RAW_RUM_EVENT_COLLECTED, rawEvent)
+      }
+    })
+  }
+
+  return {
+    stop: () => {
+      taskQueue.stop()
+      performanceResourceSubscription.unsubscribe()
+    },
+  }
+}
+
+function processRequest(
+  request: RequestCompleteEvent,
+  configuration: RumConfiguration,
+  pageStateHistory: PageStateHistory
+): RawRumEventCollectedData<RawRumResourceEvent> | undefined {
+  const matchingTiming = matchRequestResourceEntry(request)
+  return assembleResource(matchingTiming, request, pageStateHistory, configuration)
+}
+
+function processResourceEntry(
+  entry: RumPerformanceResourceTiming,
+  configuration: RumConfiguration,
+  pageStateHistory: PageStateHistory,
+  requestRegistry: RequestRegistry | undefined
+): RawRumEventCollectedData<RawRumResourceEvent> | undefined {
+  const matchingRequest =
+    isResourceEntryRequestType(entry) && requestRegistry ? requestRegistry.getMatchingRequest(entry) : undefined
+  return assembleResource(entry, matchingRequest, pageStateHistory, configuration)
+}
+
+// TODO: In the future, the `entry` parameter should be required, making things simpler.
+function assembleResource(
+  entry: RumPerformanceResourceTiming | undefined,
+  request: RequestCompleteEvent | undefined,
+  pageStateHistory: PageStateHistory,
+  configuration: RumConfiguration
+): RawRumEventCollectedData<RawRumResourceEvent> | undefined {
+  if (!entry && !request) {
+    return
+  }
+
+  const tracingInfo = request
+    ? computeRequestTracingInfo(request, configuration)
+    : computeResourceEntryTracingInfo(entry!, configuration)
+  if (!configuration.trackResources && !tracingInfo) {
+    return
+  }
+
+  const startClocks = entry ? relativeToClocks(entry.startTime) : request!.startClocks
+  const duration = entry
+    ? computeResourceEntryDuration(entry)
+    : computeRequestDuration(pageStateHistory, startClocks, request!.duration)
+
+  const graphql = request && computeGraphQlMetaData(request, configuration)
+
+  const resourceEvent = combine(
+    {
+      date: startClocks.timeStamp,
+      resource: {
+        id: generateUUID(),
+        duration: toServerDuration(duration),
+        // TODO: in the future when `entry` is required, we can probably only rely on `computeResourceEntryType`
+        type: request
+          ? request.type === RequestType.XHR
+            ? ResourceType.XHR
+            : ResourceType.FETCH
+          : computeResourceEntryType(entry!),
+        method: request ? request.method : undefined,
+        status_code: request ? request.status : discardZeroStatus(entry!.responseStatus),
+        url: request ? sanitizeIfLongDataUrl(request.url) : entry!.name,
+        protocol: entry && computeResourceEntryProtocol(entry),
+        delivery_type: entry && computeResourceEntryDeliveryType(entry),
+        provider: computeResourceProvider(request ? request.url : entry!.name, configuration.firstPartyDomains),
+        graphql,
+      },
+      type: RumEventType.RESOURCE,
+      _kubesense: {
+        discarded: !configuration.trackResources,
+      },
+    },
+    tracingInfo,
+    entry && computeResourceEntryMetrics(entry)
+  )
+
+  return {
+    startTime: startClocks.relative,
+    duration,
+    rawRumEvent: resourceEvent,
+    domainContext: getResourceDomainContext(entry, request),
+  }
+}
+
+function computeGraphQlMetaData(
+  request: RequestCompleteEvent,
+  configuration: RumConfiguration
+): GraphQlMetadata | undefined {
+  const graphQlConfig = findGraphQlConfiguration(request.url, configuration)
+  if (!graphQlConfig) {
+    return
+  }
+
+  return extractGraphQlMetadata(request, graphQlConfig)
+}
+
+function getResourceDomainContext(
+  entry: RumPerformanceResourceTiming | undefined,
+  request: RequestCompleteEvent | undefined
+): RumFetchResourceEventDomainContext | RumXhrResourceEventDomainContext | RumOtherResourceEventDomainContext {
+  if (request) {
+    const baseDomainContext = {
+      performanceEntry: entry,
+      isAborted: request.isAborted,
+      handlingStack: request.handlingStack,
+    }
+
+    if (request.type === RequestType.XHR) {
+      return {
+        xhr: request.xhr!,
+        ...baseDomainContext,
+      }
+    }
+    return {
+      requestInput: request.input as RequestInfo,
+      requestInit: request.init,
+      response: request.response,
+      error: request.error,
+      ...baseDomainContext,
+    }
+  }
+  return {
+    // Currently, at least one of `entry` or `request` must be defined when calling this function.
+    // So `entry` is guaranteed to be defined here. In the future, when `entry` is required, we can
+    // remove the `!` assertion.
+    performanceEntry: entry!,
+  }
+}
+
+function computeResourceEntryMetrics(entry: RumPerformanceResourceTiming) {
+  const { renderBlockingStatus } = entry
+  return {
+    resource: {
+      render_blocking_status: renderBlockingStatus,
+      ...computeResourceEntrySize(entry),
+      ...computeResourceEntryDetails(entry),
+    },
+  }
+}
+
+function computeRequestTracingInfo(request: RequestCompleteEvent, configuration: RumConfiguration) {
+  const hasBeenTraced = request.traceSampled && request.traceId && request.spanId
+  if (!hasBeenTraced) {
+    return undefined
+  }
+  return {
+    _kubesense: {
+      span_id: request.spanId!.toString(),
+      trace_id: request.traceId!.toString(),
+      rule_psr: configuration.rulePsr,
+    },
+  }
+}
+
+function computeResourceEntryTracingInfo(entry: RumPerformanceResourceTiming, configuration: RumConfiguration) {
+  const hasBeenTraced = entry.traceId
+  if (!hasBeenTraced) {
+    return undefined
+  }
+  return {
+    _kubesense: {
+      trace_id: entry.traceId,
+      span_id: createSpanIdentifier().toString(),
+      rule_psr: configuration.rulePsr,
+    },
+  }
+}
+
+function computeRequestDuration(pageStateHistory: PageStateHistory, startClocks: ClocksState, duration: Duration) {
+  return !pageStateHistory.wasInPageStateDuringPeriod(PageState.FROZEN, startClocks.relative, duration)
+    ? duration
+    : undefined
+}
+
+/**
+ * The status is 0 for cross-origin resources without CORS headers, so the status is meaningless, and we shouldn't report it
+ * https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming/responseStatus#cross-origin_response_status_codes
+ */
+function discardZeroStatus(statusCode: number | undefined): number | undefined {
+  return statusCode === 0 ? undefined : statusCode
+}