dd-trace 6.3.0 → 6.5.0

package/packages/dd-trace/src/openfeature/agentless_configuration_source.js

@@ -0,0 +1,322 @@
+'use strict'
+
+/* eslint-disable no-await-in-loop -- Polls and retries must remain sequential. */
+
+const { setTimeout: sleep } = require('node:timers/promises')
+
+const request = require('../exporters/common/request')
+const { getClientLibraryHeaders } = require('../exporters/common/client-library-headers')
+const log = require('../log')
+
+const MAX_ATTEMPTS = 3
+const FIRST_RETRY_MIN_MS = 2000
+const FIRST_RETRY_MAX_MS = 10_000
+const SECOND_RETRY_MIN_MS = 5000
+const SECOND_RETRY_MAX_MS = 30_000
+const RETRY_JITTER = 0.2
+
+/**
+ * @typedef {object} AgentlessSourceConfig
+ * @property {URL} endpoint
+ * @property {number} pollIntervalMs
+ * @property {number} requestTimeoutMs
+ * @property {string} apiKey
+ */
+
+/**
+ * @typedef {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} UniversalFlagConfiguration
+ */
+
+/**
+ * @typedef {object} PollResponse
+ * @property {Error | null | undefined} error
+ * @property {string | undefined} body
+ * @property {number | undefined} statusCode
+ * @property {import('node:http').IncomingHttpHeaders | undefined} headers
+ */
+
+class AgentlessConfigurationSource {
+  /** @type {AbortController | undefined} */
+  #abortController
+
+  /** @type {(configuration: UniversalFlagConfiguration) => void} */
+  #applyConfiguration
+
+  #applicationFailureLogged = false
+
+  /** @type {AgentlessSourceConfig} */
+  #config
+
+  /** @type {string | undefined} */
+  #etag
+
+  /** @type {Set<string>} */
+  #failureWarnings = new Set()
+
+  #malformedPayloadLogged = false
+
+  /**
+   * @param {AgentlessSourceConfig} config
+   * @param {(configuration: UniversalFlagConfiguration) => void} applyConfiguration
+   */
+  constructor (config, applyConfiguration) {
+    this.#config = config
+    this.#applyConfiguration = applyConfiguration
+  }
+
+  /**
+   * @returns {void}
+   */
+  start () {
+    if (this.#abortController) return
+
+    const abortController = new AbortController()
+    this.#abortController = abortController
+    this.#poll(abortController)
+  }
+
+  /**
+   * @returns {void}
+   */
+  stop () {
+    this.#abortController?.abort()
+    this.#abortController = undefined
+  }
+
+  /**
+   * @param {AbortController} abortController
+   * @returns {Promise<void>}
+   */
+  async #poll (abortController) {
+    try {
+      do {
+        await this.#pollOnce(abortController)
+      } while (
+        this.#abortController === abortController &&
+        await wait(this.#config.pollIntervalMs, abortController.signal)
+      )
+    } catch (error) {
+      if (this.#abortController === abortController) {
+        this.#warnFailure(undefined, error, 1)
+      }
+    } finally {
+      if (this.#abortController === abortController) {
+        this.#abortController = undefined
+      }
+    }
+  }
+
+  /**
+   * @param {AbortController} abortController
+   * @returns {Promise<void>}
+   */
+  async #pollOnce (abortController) {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const response = await this.#request(abortController.signal)
+      if (this.#abortController !== abortController) return
+
+      const retryable = response.statusCode === undefined || isRetryableStatus(response.statusCode)
+      if (!retryable) {
+        this.#apply(response)
+        return
+      }
+
+      if (attempt === MAX_ATTEMPTS) {
+        this.#warnFailure(response.statusCode, response.error, attempt)
+        return
+      }
+
+      const delay = retryDelay(this.#config.pollIntervalMs, attempt, Math.random())
+      if (!await wait(delay, abortController.signal)) return
+    }
+  }
+
+  /**
+   * @param {AbortSignal} signal
+   * @returns {Promise<PollResponse>}
+   */
+  #request (signal) {
+    const headers = getClientLibraryHeaders()
+    headers['Accept-Encoding'] = 'gzip'
+    headers['DD-API-KEY'] = this.#config.apiKey
+    if (this.#etag) headers['If-None-Match'] = this.#etag
+
+    /**
+     * @param {(response: PollResponse) => void} resolve
+     */
+    const execute = (resolve) => {
+      /**
+       * @param {Error | null} error
+       * @param {string | import('node:http').IncomingMessage | null | undefined} body
+       * @param {number | undefined} statusCode
+       * @param {import('node:http').IncomingHttpHeaders | undefined} responseHeaders
+       */
+      const onResponse = (error, body, statusCode, responseHeaders) => {
+        resolve({
+          error,
+          body: typeof body === 'string' ? body : undefined,
+          statusCode,
+          headers: responseHeaders,
+        })
+      }
+
+      request('', {
+        url: this.#config.endpoint,
+        method: 'GET',
+        headers,
+        retry: false,
+        signal,
+        timeout: this.#config.requestTimeoutMs,
+      }, onResponse)
+    }
+
+    return new Promise(execute)
+  }
+
+  /**
+   * @param {PollResponse} response
+   * @returns {void}
+   */
+  #apply (response) {
+    const statusCode = response.statusCode
+    if (statusCode === 304) return
+
+    if (statusCode === 401 || statusCode === 403) {
+      this.#warnFailure(statusCode, undefined, 1)
+      return
+    }
+
+    if (statusCode !== 200) return
+
+    let configuration
+    try {
+      configuration = parseConfiguration(response.body)
+    } catch {
+      if (!this.#malformedPayloadLogged) {
+        this.#malformedPayloadLogged = true
+        log.error('Feature Flagging agentless endpoint returned malformed UFC payload')
+      }
+      return
+    }
+
+    try {
+      this.#applyConfiguration(configuration)
+    } catch (error) {
+      if (!this.#applicationFailureLogged) {
+        this.#applicationFailureLogged = true
+        log.warn('Feature Flagging agentless UFC payload could not be applied: %s', errorMessage(error))
+      }
+      return
+    }
+
+    const etag = response.headers?.etag
+    const value = Array.isArray(etag) ? etag[0] : etag
+    this.#etag = value?.trim() || undefined
+  }
+
+  /**
+   * @param {number | undefined} statusCode
+   * @param {unknown} error
+   * @param {number} attempts
+   * @returns {void}
+   */
+  #warnFailure (statusCode, error, attempts) {
+    const category = statusCode === 401 || statusCode === 403
+      ? 'authentication'
+      : statusCode ? 'http' : 'request'
+    if (this.#failureWarnings.has(category)) return
+    this.#failureWarnings.add(category)
+
+    if (statusCode === 401 || statusCode === 403) {
+      log.warn(
+        'Feature Flagging agentless endpoint returned HTTP %d; verify DD_API_KEY is configured and valid',
+        statusCode
+      )
+    } else if (statusCode) {
+      log.warn('Feature Flagging agentless endpoint returned HTTP %d after %d attempts', statusCode, attempts)
+    } else if (attempts > 1) {
+      log.warn('Feature Flagging agentless request failed after %d attempts: %s', attempts, errorMessage(error))
+    } else {
+      log.warn('Feature Flagging agentless request failed: %s', errorMessage(error))
+    }
+  }
+}
+
+/**
+ * @param {number} delay
+ * @param {AbortSignal} signal
+ * @returns {Promise<boolean>}
+ */
+async function wait (delay, signal) {
+  try {
+    await sleep(delay, undefined, { ref: false, signal })
+    return true
+  } catch (error) {
+    if (error?.name === 'AbortError') return false
+    throw error
+  }
+}
+
+/**
+ * @param {string | undefined} body
+ * @returns {UniversalFlagConfiguration}
+ */
+function parseConfiguration (body) {
+  const { data } = JSON.parse(body)
+  if (data?.type !== 'universal-flag-configuration') {
+    throw new Error('Expected a JSON:API Universal Flag Configuration resource')
+  }
+
+  const { attributes } = data
+  if (typeof attributes?.format !== 'string' ||
+      typeof attributes.createdAt !== 'string' ||
+      typeof attributes.environment?.name !== 'string' ||
+      !attributes.flags ||
+      typeof attributes.flags !== 'object' ||
+      Array.isArray(attributes.flags)) {
+    throw new Error('Expected a Universal Flag Configuration v1 object')
+  }
+
+  return attributes
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function errorMessage (error) {
+  return error instanceof Error ? error.message : String(error ?? 'request was not sent')
+}
+
+/**
+ * @param {number | undefined} status
+ * @returns {boolean}
+ */
+function isRetryableStatus (status) {
+  return status === 408 || status === 429 || (status >= 500 && status <= 599)
+}
+
+/**
+ * @param {number} pollIntervalMs
+ * @param {number} attempt
+ * @param {number} random
+ * @returns {number}
+ */
+function retryDelay (pollIntervalMs, attempt, random) {
+  const base = attempt === 1
+    ? clamp(pollIntervalMs / 6, FIRST_RETRY_MIN_MS, FIRST_RETRY_MAX_MS)
+    : clamp(pollIntervalMs / 3, SECOND_RETRY_MIN_MS, SECOND_RETRY_MAX_MS)
+  return Math.max(1, Math.round(base * (1 - RETRY_JITTER + random * RETRY_JITTER * 2)))
+}
+
+/**
+ * @param {number} value
+ * @param {number} minimum
+ * @param {number} maximum
+ * @returns {number}
+ */
+function clamp (value, minimum, maximum) {
+  return Math.max(minimum, Math.min(maximum, value))
+}
+
+module.exports = AgentlessConfigurationSource

package/packages/dd-trace/src/openfeature/configuration_source.js

@@ -0,0 +1,90 @@
+'use strict'
+
+const { isLoopbackHost } = require('../exporters/common/url')
+const log = require('../log')
+
+const DEFAULT_AGENTLESS_PATH = '/api/v2/feature-flagging/config/rules-based/server'
+const MAX_POLL_INTERVAL_SECONDS = 60 * 60
+
+/**
+ * @typedef {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} UniversalFlagConfiguration
+ */
+
+/**
+ * @param {import('../config/config-base')} config
+ * @param {(configuration: UniversalFlagConfiguration) => void} applyConfiguration
+ */
+function create (config, applyConfiguration) {
+  const {
+    DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: source,
+    DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: baseUrl,
+    DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: pollIntervalSeconds,
+    DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: requestTimeoutSeconds,
+    DD_FEATURE_FLAGS_ENABLED: enabled,
+  } = config.featureFlags
+
+  if (!enabled || source !== 'agentless') {
+    return
+  }
+
+  try {
+    if (!config.DD_API_KEY) {
+      throw new Error('DD_API_KEY is required for Feature Flagging agentless delivery')
+    }
+
+    const AgentlessConfigurationSource = require('./agentless_configuration_source')
+    return new AgentlessConfigurationSource({
+      endpoint: endpoint(config, baseUrl),
+      pollIntervalMs: Math.min(pollIntervalSeconds, MAX_POLL_INTERVAL_SECONDS) * 1000,
+      requestTimeoutMs: requestTimeoutSeconds * 1000,
+      apiKey: config.DD_API_KEY,
+    }, applyConfiguration)
+  } catch (error) {
+    log.error('Unable to configure Feature Flagging configuration source', error)
+  }
+}
+
+/**
+ * Builds the agentless rules-based server endpoint.
+ *
+ * A configured URL with a non-root path is treated as the exact endpoint. A
+ * configured origin (or root URL) receives the standard rules-based server
+ * path.
+ *
+ * @param {import('../config/config-base')} config - Tracer configuration.
+ * @param {string | undefined} configuredBaseUrl - Optional endpoint or origin override.
+ * @returns {URL} Agentless endpoint.
+ */
+function endpoint (config, configuredBaseUrl) {
+  const configured = configuredBaseUrl?.trim()
+
+  if (!configured) {
+    const url = new URL(`https://ufc-server.ff-cdn.${config.site.toLowerCase()}${DEFAULT_AGENTLESS_PATH}`)
+    if (config.env) url.searchParams.set('dd_env', config.env)
+    return url
+  }
+
+  let url
+  try {
+    url = new URL(configured)
+  } catch {
+    throw new Error('Invalid Feature Flagging agentless URL')
+  }
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error('Feature Flagging agentless URL must use HTTP or HTTPS')
+  }
+  if (url.protocol === 'http:' && !isLoopbackHost(url.hostname)) {
+    throw new Error('Feature Flagging agentless URL must use HTTPS unless it targets loopback')
+  }
+
+  if (url.pathname === '' || url.pathname === '/') {
+    url.pathname = DEFAULT_AGENTLESS_PATH
+  }
+
+  return url
+}
+
+module.exports = {
+  create,
+}

package/packages/dd-trace/src/openfeature/flagging_provider.js

@@ -1,40 +1,40 @@
 'use strict'
 
 const { channel } = require('dc-polyfill')
-const requireOptionalPeer = require('../../../datadog-instrumentations/src/helpers/require-optional-peer')
 const log = require('../log')
+const configurationSource = require('./configuration_source')
 const { EXPOSURE_CHANNEL } = require('./constants/constants')
 const EvalMetricsHook = require('./eval-metrics-hook')
 const SpanEnrichmentHook = require('./span-enrichment-hook')
 
-const { DatadogNodeServerProvider } = requireOptionalPeer('@datadog/openfeature-node-server')
+const { DatadogNodeServerProvider } = require('./require-provider')
 
 /**
  * OpenFeature provider that integrates with Datadog's feature flagging system.
  * Extends DatadogNodeServerProvider to add tracer integration and configuration management.
  */
 class FlaggingProvider extends DatadogNodeServerProvider {
-  /** @type {SpanEnrichmentHook?} */
+  /** @type {SpanEnrichmentHook | undefined} */
   #spanEnrichmentHook
 
+  /** @type {{ start: Function, stop: Function } | undefined} */
+  #configurationSource
+
   /**
    * @param {import('../tracer')} tracer - Datadog tracer instance
-   * @param {import('../config')} config - Tracer configuration object
+   * @param {import('../config/config-base')} config - Tracer configuration object
    */
   constructor (tracer, config) {
-    // Call parent constructor with required options and timeout
     super({
       exposureChannel: channel(EXPOSURE_CHANNEL),
       initializationTimeoutMs: config.experimental.flaggingProvider.initializationTimeoutMs,
     })
 
-    this._tracer = tracer
-    this._config = config
-
     this.hooks.push(new EvalMetricsHook(config))
 
     if (config.experimental.flaggingProvider.spanEnrichment?.enabled) {
       this.#spanEnrichmentHook = new SpanEnrichmentHook(tracer)
+      // @ts-expect-error The upstream constructor always initializes its optional hooks property.
       this.hooks.push(this.#spanEnrichmentHook)
       log.info('%s span enrichment enabled', this.constructor.name)
     } else {
@@ -43,6 +43,9 @@ class FlaggingProvider extends DatadogNodeServerProvider {
 
     log.debug('%s created with timeout: %dms', this.constructor.name,
       config.experimental.flaggingProvider.initializationTimeoutMs)
+
+    this.#configurationSource = configurationSource.create(config, this.setConfiguration.bind(this))
+    this.#configurationSource?.start()
   }
 
   /**
@@ -50,22 +53,10 @@ class FlaggingProvider extends DatadogNodeServerProvider {
    * Cleans up resources including channel subscriptions.
    */
   onClose () {
+    this.#configurationSource?.stop()
+    this.#configurationSource = undefined
     this.#spanEnrichmentHook?.destroy()
-  }
-
-  /**
-   * Internal method to update flag configuration from Remote Config.
-   * This method is called automatically when Remote Config delivers UFC updates.
-   *
-   * @internal
-   * @param {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} ufc
-   * - Universal Flag Configuration object
-   */
-  _setConfiguration (ufc) {
-    if (typeof this.setConfiguration === 'function') {
-      this.setConfiguration(ufc)
-    }
-    log.debug('%s provider configuration updated', this.constructor.name)
+    this.#spanEnrichmentHook = undefined
   }
 }
 

package/packages/dd-trace/src/openfeature/index.js

@@ -47,8 +47,6 @@ function enable (config) {
   setAgentStrategy(config, hasAgent => {
     exposuresWriter?.setEnabled(hasAgent)
   })
-
-  log.debug('OpenFeature module enabled')
 }
 
 /**

package/packages/dd-trace/src/openfeature/noop.js

@@ -20,12 +20,7 @@ function resolveDefault (defaultValue) {
  * https://openfeature.dev/docs/reference/concepts/provider/
  */
 class NoopFlaggingProvider {
-  /**
-   * @param {object} [noopTracer] - Optional noop tracer instance
-   */
-  constructor (noopTracer) {
-    this._tracer = noopTracer
-    this._config = {}
+  constructor () {
     this.metadata = { name: 'NoopFlaggingProvider' }
     this.status = 'NOT_READY'
     this.runsOn = 'server'
@@ -78,28 +73,6 @@ class NoopFlaggingProvider {
   resolveObjectEvaluation (flagKey, defaultValue, context, logger) {
     return resolveDefault(defaultValue)
   }
-
-  /**
-   * @returns {object} Current configuration
-   */
-  getConfiguration () {
-    return this._config
-  }
-
-  /**
-   * @param {object} config - Configuration to set
-   */
-  setConfiguration (config) {
-    this._config = config
-  }
-
-  /**
-   * @internal
-   * @param {object} ufc - Universal Flag Configuration object
-   */
-  _setConfiguration (ufc) {
-    this.setConfiguration(ufc)
-  }
 }
 
 module.exports = NoopFlaggingProvider

package/packages/dd-trace/src/openfeature/register.js

@@ -0,0 +1,35 @@
+'use strict'
+
+const { registerFeature } = require('../feature-registry')
+
+const noop = new (require('./noop'))()
+
+/** @typedef {import('../proxy') & { openfeature: object }} OpenFeatureProxy */
+
+registerFeature({
+  name: 'openfeature',
+  noop,
+  factory: () => require('./index'),
+  provider: () => require('./flagging_provider'),
+
+  /** @param {import('../config/config-base')} config */
+  isEnabled (config) {
+    return config.featureFlags.DD_FEATURE_FLAGS_ENABLED
+  },
+
+  /**
+   * @param {import('../remote_config')} rc - RemoteConfig instance
+   * @param {import('../config/config-base')} config
+   * @param {OpenFeatureProxy} proxy
+   */
+  remoteConfig (rc, config, proxy) {
+    const openfeatureRemoteConfig = require('./remote_config')
+    const subscribe = config.featureFlags.DD_FEATURE_FLAGS_ENABLED &&
+      config.featureFlags.DD_FEATURE_FLAGS_CONFIGURATION_SOURCE === 'remote_config'
+    openfeatureRemoteConfig.enable(
+      rc,
+      () => proxy.openfeature,
+      subscribe
+    )
+  },
+})

package/packages/dd-trace/src/openfeature/remote_config.js

@@ -5,30 +5,27 @@ const RemoteConfigCapabilities = require('../remote_config/capabilities')
 /**
  * Configures remote config handlers for openfeature feature flagging
  *
- * @param {object} rc - RemoteConfig instance
- * @param {object} config - Tracer config
- * @param {Function} getOpenfeatureProxy - Function that returns the OpenFeature proxy from tracer
+ * @param {import('../remote_config')} rc - RemoteConfig instance
+ * @param {() => import('./flagging_provider')} getOpenfeatureProxy
+ * @param {boolean} subscribe - Whether Agent Remote Config owns UFC delivery
  */
-function enable (rc, config, getOpenfeatureProxy) {
-  // Always enable capability for feature flag configuration
-  // This indicates the library supports this capability via remote config
-  rc.updateCapabilities(RemoteConfigCapabilities.FFE_FLAG_CONFIGURATION_RULES, true)
+function enable (rc, getOpenfeatureProxy, subscribe) {
+  if (!subscribe) return
 
-  // Only register product handler if the experimental feature is enabled
-  if (!config.experimental.flaggingProvider.enabled) return
+  rc.updateCapabilities(RemoteConfigCapabilities.FFE_FLAG_CONFIGURATION_RULES, true)
 
-  // Set product handler for FFE_FLAGS
-  rc.setProductHandler('FFE_FLAGS', (action, conf) => {
+  /**
+   * @param {string} action
+   * @param {import('@datadog/openfeature-node-server').UniversalFlagConfigurationV1} conf
+   */
+  const updateConfiguration = (action, conf) => {
     if (action === 'apply' || action === 'modify') {
-      // Feed UFC config directly to OpenFeature provider
-      getOpenfeatureProxy()._setConfiguration(conf)
+      getOpenfeatureProxy().setConfiguration(conf)
     } else if (action === 'unapply') {
-      // Clear the configuration so evaluations return PROVIDER_NOT_READY,
-      // consistent with Go and Python which also set config to null on RC deletion.
-      // The evaluator returns PROVIDER_NOT_READY when config is null/undefined.
-      getOpenfeatureProxy()._setConfiguration(null)
+      getOpenfeatureProxy().setConfiguration(undefined)
     }
-  })
+  }
+  rc.setProductHandler('FFE_FLAGS', updateConfiguration)
 }
 
 module.exports = {

package/packages/dd-trace/src/openfeature/require-provider.js

@@ -0,0 +1,18 @@
+'use strict'
+
+/** @type {(request: string) => typeof import('@datadog/openfeature-node-server')} */
+let requireOptionalPeer
+
+// @ts-expect-error webpack exposes this escape hatch as a free variable.
+// eslint-disable-next-line camelcase
+if (typeof __non_webpack_require__ === 'function') {
+  // eslint-disable-next-line camelcase, no-undef
+  requireOptionalPeer = __non_webpack_require__
+} else {
+  // nft recognizes createRequire through a binding named `module`.
+  const module = require('node:module')
+  const runtimeRequire = module.createRequire(__filename)
+  requireOptionalPeer = runtimeRequire
+}
+
+module.exports = requireOptionalPeer('@datadog/openfeature-node-server')

package/packages/dd-trace/src/opentelemetry/span-ending-hook.js

@@ -0,0 +1,10 @@
+'use strict'
+
+// Pre-finish hook for OTel-bridge spans. `Span.end()` runs it before `finish()` formats and
+// (synchronously, for the last span in a trace) exports the trace, so a framework instrumentation
+// can rewrite the operation name / resource while the DD span is still unfinished; `onEnd` only sees
+// the already-built payload. Its own dependency-free module so an instrumentation can register
+// without loading the OTel bridge, and a plain holder so the caller gates on `hook` existing.
+
+/** @type {{ hook: ((ddSpan: import('../opentracing/span')) => void) | undefined }} */
+module.exports = { hook: undefined }

package/packages/dd-trace/src/opentelemetry/span.js

@@ -15,6 +15,7 @@ const kinds = require('../../../../ext/kinds')
 const id = require('../id')
 const BridgeSpanBase = require('./bridge-span-base')
 const SpanContext = require('./span_context')
+const spanEndingHook = require('./span-ending-hook')
 const { setOtelOperationName, setOtelResource } = require('./span-helpers')
 
 const spanKindNames = {
@@ -255,6 +256,10 @@ class Span extends BridgeSpanBase {
     const hrEndTime = timeInputToHrTime(timeInput || (performance.now() + timeOrigin))
     const endTime = hrTimeToMilliseconds(hrEndTime)
 
+    // Must run before `finish()`, while the DD span is still unfinished. See span-ending-hook.js.
+    if (spanEndingHook.hook !== undefined) {
+      spanEndingHook.hook(this._ddSpan)
+    }
     this._ddSpan.finish(endTime)
     this._spanProcessor.onEnd(this)
   }