@newrelic/browser-agent 1.319.0 → 1.320.0

package/src/loaders/api/register.js

@@ -78,11 +78,11 @@ function register (agentRef, target) {
   target.blocked = false
   if (typeof target.tags !== 'object' || target.tags === null || Array.isArray(target.tags)) target.tags = {}
   target.parent ??= {
-    get id () { return agentRef.runtime.appMetadata.agents[0].entityGuid }, // getter because this is asyncronously set
+    get id () { return agentRef.runtime.appMetadata.agents?.[0].entityGuid }, // getter because this is asynchronously set
     type: V2_TYPES.BA
   }
 
-  const timings = findScriptTimings()
+  const timings = findScriptTimings(target)
 
   // Track MFE vitals for this entity
   const vitals = trackMFEVitals(target, timings)
@@ -154,7 +154,10 @@ function register (agentRef, target) {
       get customAttributes () { return attrs },
       target,
       timings,
-      vitals
+      vitals,
+      events: {
+        latestTimestamp: undefined
+      }
     }
   }
 
@@ -234,8 +237,9 @@ function register (agentRef, target) {
   const report = (methodToCall, args, target) => {
     /** Even if we are blocked, if registering we should still return a child register API so nested API calls do not throw errors */
     if (isBlocked() && methodToCall !== register) return
-    /** set the timestamp before the async part of waiting for the rum response for better accuracy */
-    const timestamp = now()
+    /** use the timestamp captured inside the iframe for this call, if one was supplied (see iframe-message-handler.js); otherwise fall back to now(). Consume it immediately so a stale value can't leak into a later call that isn't preceded by a fresh iframe message (e.g. deregister() via page unload) */
+    const timestamp = api.metadata.events.latestTimestamp ?? now()
+    api.metadata.events.latestTimestamp = undefined
     const methodName = METHOD_NAMES.get(methodToCall) || 'unknown'
     handle(SUPPORTABILITY_METRIC_CHANNEL, [`API/register/${methodName}/called`], undefined, FEATURE_NAMES.metrics, agentRef.ee)
     try {

package/src/loaders/configure/configure.js

@@ -7,11 +7,13 @@ import { gosCDN } from '../../common/window/nreum'
 import { mergeInfo } from '../../common/config/info'
 import { mergeInit } from '../../common/config/init'
 import { mergeRuntime } from '../../common/config/runtime'
-import { isWorkerScope } from '../../common/constants/runtime'
+import { isWorkerScope, globalScope } from '../../common/constants/runtime'
 import { redefinePublicPath } from './public-path'
 import { ee } from '../../common/event-emitter/contextual-ee'
 import { dispatchGlobalEvent } from '../../common/dispatch/global-event'
 import { mergeLoaderConfig } from '../../common/config/loader-config'
+import { handle } from '../../common/event-emitter/handle'
+import { prefix as iframePrefix } from '../../common/constants/iframe-constants'
 
 /**
  * Sets or re-sets the agent's configuration values from global settings. This also attach those as properties to the agent instance.
@@ -81,6 +83,18 @@ export function configure (agent, opts = {}, loaderType, forceDrain) {
       data: agent.config
     })
 
+    // Set up iframe postMessage listener for registered entities
+    if (agent.init.api.register.allow_iframe_bridge) {
+      globalScope.addEventListener('message', (event) => {
+        // Pre-filter here rather than in setupIframeMFEMessageListener, so unrelated MessageEvents
+        // (there can be many, from any script on the page) aren't buffered/held onto in memory
+        // while waiting for the iframe bridge's lazy chunk to load and drain the buffer.
+        if (typeof event.data?.type === 'string' && event.data.type.startsWith(iframePrefix)) {
+          handle('iframe-message', [event], undefined, 'IFRAME', agent.ee)
+        }
+      })
+    }
+
     agent.runtime.configured = true
   }
 }

package/src/loaders/configure/iframe-message-handler.js

@@ -0,0 +1,244 @@
+/**
+ * Copyright 2020-2026 New Relic, Inc. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { warn } from '../../common/util/console'
+import { getRegisteredEntityByIframeInterfaceId } from '../../common/v2/utils'
+import { IFRAME_TIMING_UPDATE, IFRAME_API, IFRAME_API_RESPONSE, IFRAME_VITALS_UPDATE, IFRAME_AJAX } from '../../common/constants/iframe-constants'
+import { REGISTER } from '../api/constants'
+import { handle } from '../../common/event-emitter/handle'
+import { FEATURE_NAMES } from '../features/features'
+import { stringify } from '../../common/util/stringify'
+import { registerHandler } from '../../common/event-emitter/register-handler'
+import { drain } from '../../common/drain/drain'
+import { isBrowserScope } from '../../common/constants/runtime'
+
+/**
+ * Retrieves the registered entity associated with the iframeInterfaceId from the event data, and validates that the origin of the message event matches the expected origin for that entity.
+ * @param {MessageEvent} event - The message event containing the method call or registration request
+ * @param {Object} agent - The browser agent instance
+ * @returns {Object|undefined} - The registered entity if it exists and the origin is valid, otherwise undefined
+ */
+function getValidEntity (event, agent) {
+  try {
+    const { iframeInterfaceId } = event.data
+    if (!iframeInterfaceId) return
+    const entity = getRegisteredEntityByIframeInterfaceId(iframeInterfaceId, agent)
+    if (!isValidOrigin(event, entity)) return
+    return entity
+  } catch (e) {
+    // couldnt get entity or validate origin, just let the method return undefined
+  }
+}
+
+function isSafeProperty (obj, property) {
+  return property in obj && typeof property === 'string' && !['__proto__', 'constructor', 'prototype'].includes(property)
+}
+
+/**
+ * Handles timing property updates from iframes. Mutates the timings object on the entity's metadata with the new value for the specified property.
+ * @param {MessageEvent} event - The message event containing the timing update
+ * @param {Object} agent - The browser agent instance
+ * @returns
+ */
+function handleTimingUpdate (event, agent) {
+  const entity = getValidEntity(event, agent)
+  if (!entity) return
+
+  if (!entity.metadata.timings) return
+
+  event.data.entries?.forEach(({ property, value }) => {
+    if (isSafeProperty(entity.metadata.timings, property)) {
+      entity.metadata.timings[property] = value
+    }
+  })
+}
+
+/**
+ * Handles vitals property updates from iframes. Mutates the vitals object on the entity's metadata with the new value for the specified property.
+ * @param {MessageEvent} event - The message event containing the vitals update
+ * @param {Object} agent - The browser agent instance
+ * @returns
+ */
+function handleVitalsUpdate (event, agent) {
+  const entity = getValidEntity(event, agent)
+  if (!entity) return
+
+  if (!entity.metadata?.vitals) return
+
+  event.data.entries?.forEach(({ property, value }) => {
+    if (isSafeProperty(entity.metadata.vitals, property) && (!!Number(value) || value === 0)) {
+      entity.metadata.vitals[property].value = value
+    }
+  })
+}
+
+/**
+ * Handles ajax events from iframes and forwards them to the agent's event emitter
+ * @param {MessageEvent} event  - The message event containing the method call or registration request
+ * @param {Object} agent - The browser agent instance
+ * @returns
+ */
+function handleAjax (event, agent) {
+  const entity = getValidEntity(event, agent)
+  if (!entity) return
+  const { entries } = event.data
+  entries?.forEach(({ params, metrics, start, end, initiatorType }) => {
+    handle('xhr', [params, metrics, start, end, initiatorType, entity.metadata.target], undefined, FEATURE_NAMES.ajax, agent.ee)
+  })
+}
+
+/**
+ * Validates that the origin of the message event matches the expected origin for the registered entity
+ * @param {MessageEvent} event - The message event containing the method call or registration request
+ * @param {Object} entity - The registered entity associated with the iframeInterfaceId from the event data
+ * @returns {boolean}
+ */
+function isValidOrigin (event, entity) {
+  if (!entity) return false
+  try {
+    // "null" is the literal serialization the spec uses for every opaque origin (sandboxed iframes
+    // without allow-same-origin, data:/javascript: URLs, etc.) -- it does not uniquely identify a
+    // single origin, so treating two "null" origins as a match would let an unrelated opaque-origin
+    // frame impersonate the one that actually registered.
+    if (event.origin === 'null' || entity.metadata.target.iframeOrigin === 'null') return false
+    return event.origin === entity.metadata.target.iframeOrigin
+  } catch (e) {
+    warn(77, e)
+    return false
+  }
+}
+
+/**
+ * Handles both entity registration and method calls on existing entities
+ * @async
+ * @param {MessageEvent} event - The message event containing the method call or registration request
+ * @param {Object} agent - The browser agent instance
+ * @returns {Promise<{entity: Object|null, result: any}>}
+ */
+export async function handleMethodCall (event, agent) {
+  const { target, iframeInterfaceId, timestamp } = event.data
+  // Method calls are always sent one-at-a-time (each has its own postMessage response), so only
+  // the first entry is ever populated -- but the payload shape stays consistent with every other
+  // iframe message type (timing/vitals/ajax), which all wrap their data in an `entries` array.
+  const [{ method, args } = {}] = event.data.entries || []
+  const output = { entity: null, result: null }
+  // Registration of a new entity needs to be handled differently than method calls on existing entities
+  if (method === REGISTER) {
+    // "null" is the opaque-origin serialization (sandboxed iframes, data:/javascript: URLs) -- it
+    // doesn't identify a single origin, so an entity registered from one can never be safely
+    // distinguished from another later on (see isValidOrigin). Reject up front rather than
+    // registering an entity that would silently fail every subsequent call.
+    if (event.origin === 'null') {
+      warn(74, event.origin)
+      return output
+    }
+
+    const iframeDomains = agent.init.api.register.iframe_domains
+    if (iframeDomains.length && !iframeDomains.includes(event.origin)) {
+      warn(74, event.origin)
+      return output
+    }
+    const targetData = args?.[0] || target || {}
+    if (!agent[REGISTER]) {
+      warn(35, REGISTER)
+      return output
+    }
+
+    const freshTarget = {
+      id: targetData.id,
+      name: targetData.name,
+      type: targetData.type,
+      version: targetData.version,
+      tags: targetData.tags
+    }
+
+    output.entity = agent[REGISTER](freshTarget)
+    output.entity.metadata.target.iframeInterfaceId = iframeInterfaceId
+    output.entity.metadata.target.iframeOrigin = event.origin
+
+    return output
+  }
+
+  const entity = getRegisteredEntityByIframeInterfaceId(iframeInterfaceId, agent)
+  if (!isValidOrigin(event, entity)) {
+    warn(76)
+    return output
+  }
+
+  output.entity = entity
+  const methodFn = entity[method]
+  if (!isSafeProperty(entity, method) || typeof methodFn !== 'function') {
+    warn(35, method)
+    return output
+  }
+
+  // Supply the timestamp captured inside the iframe at call time (from event.data.timestamp)
+  entity.metadata.events.latestTimestamp = timestamp
+  output.result = await methodFn.apply(entity, args || [])
+  return output
+}
+
+/**
+ * Serializes entity metadata for postMessage response.
+ * Strips out any non-serializable properties and returns a plain object.
+ * postMessage cant handle complex objects that cause DataCloneErrors to throw like functions, circular references, etc.
+ * @param {Object} entity - The registered entity whose metadata is to be serialized.  Uses a pattern of stringify and parse to remove any non-serializable properties from the metadata object.
+ * @returns {Object} - The serialized metadata object
+*/
+function serializeMetadata (entity) {
+  const meta = entity.metadata
+
+  return JSON.parse(stringify(meta))
+}
+
+/**
+ * Sends a postMessage response to the iframe
+ * @param {MessageEvent} event - The message event containing the method call or registration request
+ * @param {Object} payload - The response payload to send back to the iframe
+ */
+function sendResponse (event, payload) {
+  event.source.postMessage({
+    type: IFRAME_API_RESPONSE,
+    messageId: event.data.messageId,
+    iframeInterfaceId: event.data.iframeInterfaceId,
+    ...payload
+  }, event.origin)
+}
+
+/**
+ * Sets up a postMessage listener to handle API calls and timing updates from iframes
+ * @param {Object} agent The agent instance
+ */
+export function setupIframeMFEMessageListener (agent) {
+  if (!isBrowserScope || !window.addEventListener || agent.runtime.listeningForIframeMessages) return
+
+  registerHandler('iframe-message', async (event) => {
+    if (!event.data) return
+
+    switch (event.data.type) {
+      case IFRAME_TIMING_UPDATE:
+        handleTimingUpdate(event, agent)
+        return
+      case IFRAME_VITALS_UPDATE:
+        handleVitalsUpdate(event, agent)
+        return
+      case IFRAME_AJAX:
+        handleAjax(event, agent)
+        return
+      case IFRAME_API:
+        try {
+          if (!event.source || !event.data.messageId || !event.data.entries?.[0]?.method) return
+          const { entity, result } = await handleMethodCall(event, agent)
+          const metadata = entity ? serializeMetadata(entity) : undefined
+          sendResponse(event, { result, metadata })
+        } catch (error) {
+          const errorMessage = error?.message || String(error)
+          sendResponse(event, { error: errorMessage })
+        }
+    }
+  }, 'IFRAME', agent.ee)
+
+  drain(agent, 'IFRAME', true) // drain any buffered iframe messages that were received before the listener was set up
+  agent.runtime.listeningForIframeMessages = true
+}