✨ Use optional MatchHeader name to account for default headers (#4825)

Author: bdibon

packages/browser-rum-core/src/boot/rumPublicApi.ts

@@ -586,7 +586,9 @@ export interface RumPublicApi extends PublicApi {
   failFeatureOperation: (name: string, failureReason: FailureReason, options?: FeatureOperationOptions) => void
 
   /**
-   * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option. See configuration example for extending them.
+   * List of default headers used by the {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders} option.
+   *
+   * @deprecated You can now omit `name` from a MatchHeader entry to include default headers.
    */
   DEFAULT_TRACKED_RESOURCE_HEADERS: typeof DEFAULT_TRACKED_RESOURCE_HEADERS
 }

packages/browser-rum-core/src/domain/configuration/configuration.spec.ts

@@ -431,6 +431,42 @@ describe('validateAndBuildRumConfiguration', () => {
         expect(result).toEqual(DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })))
       })
 
+      it('accepts a MatchHeader without name for default headers', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{}],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([{}])
+      })
+
+      it('preserves location when name is absent', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{ location: 'response' }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([{ location: 'response' }])
+      })
+
+      it('combines default header matcher with custom matchers in array order', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{}, { name: 'x-custom' }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([{}, { name: 'x-custom' }])
+      })
+
+      it('treats undefined name like absent name', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{ name: undefined }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([{}])
+      })
+
       it('accepts a MatchHeader with only name', () => {
         const result = validateAndBuildRumConfiguration({
           ...DEFAULT_INIT_CONFIGURATION,
@@ -518,21 +554,26 @@ describe('validateAndBuildRumConfiguration', () => {
         })!.trackResourceHeaders
 
         expect(result).toEqual([{ name: 'x-valid' }, { name: 'x-also-valid' }])
-        expect(displayWarnSpy).toHaveBeenCalledOnceWith(
-          "trackResourceHeaders[1] should be a MatchHeader object with a 'name' property"
-        )
+        expect(displayWarnSpy).toHaveBeenCalledOnceWith('trackResourceHeaders[1] should be a MatchHeader object')
       })
 
-      it('warns and skips item without name', () => {
+      it('accepts a MatchHeader without name', () => {
         const result = validateAndBuildRumConfiguration({
           ...DEFAULT_INIT_CONFIGURATION,
-          trackResourceHeaders: [{ url: 'https://example.com' } as any],
+          trackResourceHeaders: [{ url: 'https://example.com' }],
+        })!.trackResourceHeaders
+
+        expect(result).toEqual([{ url: 'https://example.com' }])
+      })
+
+      it('warns and skips item with invalid name', () => {
+        const result = validateAndBuildRumConfiguration({
+          ...DEFAULT_INIT_CONFIGURATION,
+          trackResourceHeaders: [{ name: 42 as any }],
         })!.trackResourceHeaders
 
         expect(result).toEqual([])
-        expect(displayWarnSpy).toHaveBeenCalledOnceWith(
-          "trackResourceHeaders[0] should be a MatchHeader object with a 'name' property"
-        )
+        expect(displayWarnSpy).toHaveBeenCalledOnceWith('trackResourceHeaders[0].name should be a MatchOption')
       })
 
       it('warns and skips item with invalid url', () => {

packages/browser-rum-core/src/domain/configuration/configuration.ts

@@ -22,31 +22,7 @@ export const DEFAULT_PROPAGATOR_TYPES: PropagatorType[] = ['tracecontext', 'data
 
 /**
  * Default list of headers collected on resource events when {@link RumInitConfiguration.trackResourceHeaders | trackResourceHeaders}
- * is set to `true`. Re-exported by the `@datadog/browser-rum` and `@datadog/browser-rum-slim` packages, and exposed on the
- * `DD_RUM` global object when the SDK is loaded via the CDN, so it can be referenced when building a custom matcher list.
- *
- * @example NPM
- * ```ts
- * import { datadogRum, DEFAULT_TRACKED_RESOURCE_HEADERS } from '@datadog/browser-rum'
- *
- * datadogRum.init({
- *   // ...
- *   trackResourceHeaders: [
- *     ...DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })),
- *     { name: 'x-request-id' },
- *   ],
- * })
- * ```
- * @example CDN
- * ```ts
- * DD_RUM.init({
- *   // ...
- *   trackResourceHeaders: [
- *     ...DD_RUM.DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })),
- *     { name: 'x-request-id' },
- *   ],
- * })
- * ```
+ * is set to `true`.
  */
 export const DEFAULT_TRACKED_RESOURCE_HEADERS = [
   'cache-control',
@@ -283,9 +259,9 @@ export interface RumInitConfiguration extends InitConfiguration {
    *
    * - `true`: collect {@link DEFAULT_TRACKED_RESOURCE_HEADERS} for all URLs, both directions
    * - `MatchHeader[]`: each {@link MatchHeader} targets a header name, with optional URL scope
-   * (`url`), value extraction (`extractor`), and `location`. By default, both request and
-   * response headers are captured; set `location` to `'request'` or `'response'` to restrict
-   * to one.
+   * (`url`), value extraction (`extractor`), and `location`. When `name` is omitted, the matcher
+   * applies to {@link DEFAULT_TRACKED_RESOURCE_HEADERS}. By default, both request and response
+   * headers are captured; set `location` to `'request'` or `'response'` to restrict to one.
    *
    * Headers whose names match a built-in sensitive-data pattern are always dropped, regardless
    * of the configured matchers. The pattern blocks headers whose names contain: `token`, `cookie`,
@@ -296,10 +272,10 @@ export interface RumInitConfiguration extends InitConfiguration {
    * @defaultValue false (disabled)
    * @example
    * // Collect default headers plus custom ones for all URLs
-   * trackResourceHeaders: [
-   *   ...DEFAULT_TRACKED_RESOURCE_HEADERS.map((h) => ({ name: h })),
-   *   { name: 'x-request-id' },
-   * ]
+   * trackResourceHeaders: [{}, { name: 'x-request-id' }]
+   * @example
+   * // Collect default headers from responses only
+   * trackResourceHeaders: [{ location: 'response' }]
    * @example
    * // URL-scoped rule: capture specific response headers only for calls to /api
    * trackResourceHeaders: [{ url: /\/api\//, name: 'cache-control', location: 'response' }]
@@ -386,7 +362,7 @@ export interface GraphQlUrlOption {
 
 export interface MatchHeader {
   url?: MatchOption
-  name: MatchOption
+  name?: MatchOption
   extractor?: RegExp
   location?: 'request' | 'response' | 'any'
 }
@@ -613,8 +589,12 @@ function validateAndBuildTrackResourceHeaders(initConfiguration: RumInitConfigur
   const result: MatchHeader[] = []
 
   option.forEach((item, index) => {
-    if (!isIndexableObject(item) || !isMatchOption(item.name)) {
-      display.warn(`trackResourceHeaders[${index}] should be a MatchHeader object with a 'name' property`)
+    if (!isIndexableObject(item)) {
+      display.warn(`trackResourceHeaders[${index}] should be a MatchHeader object`)
+      return
+    }
+    if (item.name !== undefined && !isMatchOption(item.name)) {
+      display.warn(`trackResourceHeaders[${index}].name should be a MatchOption`)
       return
     }
     if (item.url !== undefined && !isMatchOption(item.url)) {
@@ -625,14 +605,18 @@ function validateAndBuildTrackResourceHeaders(initConfiguration: RumInitConfigur
       display.warn(`trackResourceHeaders[${index}].extractor should be a RegExp`)
       return
     }
-    if (item.location !== undefined && !VALID_HEADER_LOCATIONS.includes(item.location)) {
+    if (
+      item.location !== undefined &&
+      (typeof item.location !== 'string' || !VALID_HEADER_LOCATIONS.includes(item.location))
+    ) {
       display.warn(`trackResourceHeaders[${index}].location should be 'request', 'response', or 'any'`)
       return
     }
 
+    const { name, ...rest } = item
     result.push({
-      ...item,
-      name: typeof item.name === 'string' ? item.name.toLowerCase() : item.name,
+      ...rest,
+      ...(name !== undefined ? { name: typeof name === 'string' ? name.toLowerCase() : name } : {}),
     })
   })
 

packages/browser-rum-core/src/domain/resource/resourceCollection.spec.ts

@@ -749,6 +749,27 @@ describe('resourceCollection', () => {
       expect(event.resource.response!.headers!['content-type']).toBeUndefined()
     })
 
+    it('should collect default headers when name is absent', () => {
+      setupResourceCollection({ trackResourceHeaders: [{ location: 'response' }] })
+
+      notifyRequest({
+        request: {
+          type: RequestType.FETCH,
+          response: new Response('', {
+            headers: { 'Content-Type': 'text/html', 'Cache-Control': 'no-cache', 'X-Other': 'ignored' },
+          }),
+        },
+      })
+
+      const event = rawRumEvents[0].rawRumEvent as RawRumResourceEvent
+      expect(event.resource.response).toEqual({
+        headers: {
+          'content-type': 'text/html',
+          'cache-control': 'no-cache',
+        },
+      })
+    })
+
     describe('forbidden headers', () => {
       const forbiddenHeaders = [
         'authorization',

packages/browser-rum-core/src/domain/resource/resourceCollection.ts

@@ -10,6 +10,7 @@ import {
   safeTruncate,
   setTimeout,
 } from '@datadog/browser-core'
+import type { MatchOption } from '@datadog/browser-core'
 import type { Duration } from '@datadog/js-core/time'
 import { elapsed, relativeToClocks, toServerDuration } from '@datadog/js-core/time'
 import { combine } from '@datadog/js-core/util'
@@ -19,6 +20,7 @@ import type { RumResourceEventDomainContext } from '../../domainContext.types'
 import type { NetworkHeaders, RawRumResourceEvent, ResourceRequest, ResourceResponse } from '../../rawRumEvent.types'
 import { RumEventType } from '../../rawRumEvent.types'
 import type { MatchHeader, RumConfiguration } from '../configuration'
+import { DEFAULT_TRACKED_RESOURCE_HEADERS } from '../configuration'
 import { startEventTracker } from '../eventTracker'
 import { extractRegexMatch } from '../extractRegexMatch'
 import type { LifeCycle, RawRumEventCollectedData } from '../lifeCycle'
@@ -387,6 +389,8 @@ const FORBIDDEN_HEADER_PATTERN =
   /(token|cookie|secret|authorization|(api|secret|access|app).?key|(client|connecting|real).?ip|forwarded)/
 const MAX_HEADER_COUNT = 100
 const MAX_HEADER_VALUE_LENGTH = 128
+const defaultHeadersMatchOption: MatchOption = (headerName) =>
+  (DEFAULT_TRACKED_RESOURCE_HEADERS as readonly string[]).includes(headerName)
 
 function filterHeaders(headers: Headers, matchers: MatchHeader[]): NetworkHeaders | undefined {
   const result: NetworkHeaders = {}
@@ -409,7 +413,7 @@ function filterHeaders(headers: Headers, matchers: MatchHeader[]): NetworkHeader
       return
     }
 
-    const matchHeader = matchers.find((m) => matchList([m.name], lowerName))
+    const matchHeader = matchers.find((m) => matchList([m.name ?? defaultHeadersMatchOption], lowerName))
     if (!matchHeader) {
       return
     }

test/e2e/scenario/rum/resources.scenario.ts

@@ -476,13 +476,10 @@ test.describe('resource headers with trackResourceHeaders', () => {
       expect(fetchEvent!.resource.response?.headers?.['cache-control']).toBeUndefined()
     })
 
-  createTest('collect default and custom headers using DEFAULT_TRACKED_RESOURCE_HEADERS pattern')
+  createTest('collect default and custom headers using optional name matcher')
     .withRum()
     .withRumInit((configuration) => {
-      configuration.trackResourceHeaders = [
-        ...window.DD_RUM!.DEFAULT_TRACKED_RESOURCE_HEADERS.map((name) => ({ name })),
-        { name: 'x-request-id' },
-      ]
+      configuration.trackResourceHeaders = [{}, { name: 'x-request-id' }]
       window.DD_RUM!.init(configuration)
     })
     .run(async ({ intakeRegistry, flushEvents, page }) => {