dd-trace 6.19.0 → 6.20.0

package/packages/dd-trace/src/openfeature/writers/flag-eval-evp-hook.js

@@ -0,0 +1,105 @@
+'use strict'
+
+const { MAX_EVALUATION_TIMESTAMP_MS } = require('../constants/constants')
+const { snapshotEvaluationContext } = require('./flag-evaluation-context')
+const {
+  recordContextTruncated, recordDropped, recordHookError, recordTargetingKeyOmitted,
+} = require('./flag-evaluation-telemetry')
+const FlagEvaluationsWriter = require('./flag-evaluations')
+const { setExposureDeliveryStrategy } = require('./util')
+
+/** Captures terminal SDK results; the writer owns deferred aggregation and delivery. */
+class FlagEvalEVPHook {
+  /** @type {FlagEvaluationsWriter} */
+  #writer
+  #closed = false
+  #stopDeliveryStrategy
+
+  /**
+   * The provider only constructs this hook when evaluation counts are enabled.
+   *
+   * @param {import('../../config/config-base')} config
+   */
+  constructor (config) {
+    const writer = new FlagEvaluationsWriter(config)
+    this.#writer = writer
+    this.#stopDeliveryStrategy = setExposureDeliveryStrategy(config, (enabled, route) => {
+      if (this.#closed) return
+      writer.setEnabled(enabled, route)
+    })
+  }
+
+  /**
+   * Provider hooks run in finally even when the SDK short-circuits before resolution.
+   * Consent belongs to the captured result, never the provider's current configuration.
+   *
+   * @param {import('@openfeature/core').HookContext} hookContext
+   * @param {import('@openfeature/core').EvaluationDetails<import('@openfeature/core').FlagValue>} evaluationDetails
+   */
+  finally (hookContext, evaluationDetails) {
+    try {
+      const unavailableReason = this.#closed ? 'closed' : this.#writer.getUnavailableReason()
+      if (unavailableReason !== undefined) {
+        recordDropped(unavailableReason)
+        return
+      }
+      if (!this.#writer.hasCapacity()) {
+        recordDropped('pre_queue_overflow')
+        return
+      }
+
+      const metadata = evaluationDetails.flagMetadata
+      const consent = metadata?.__dd_observe_full_evaluation_data === true
+      const capturedTime = metadata?.__dd_eval_timestamp_ms
+      const timestamp = typeof capturedTime === 'number' && Number.isSafeInteger(capturedTime) &&
+        Math.abs(capturedTime) <= MAX_EVALUATION_TIMESTAMP_MS
+        ? capturedTime
+        : Date.now()
+      const context = hookContext.context
+      let targetingKey
+      try {
+        targetingKey = context?.targetingKey
+      } catch {
+        // An unreadable identity must not discard an otherwise valid evaluation count.
+        recordTargetingKeyOmitted()
+      }
+      let attrs
+      if (consent) {
+        let snapshot
+        try {
+          snapshot = snapshotEvaluationContext(context)
+        } catch {
+          // Preserve the evaluation count without the failed context. Never log caller-controlled errors.
+          recordContextTruncated('snapshot_error')
+        }
+        if (snapshot !== undefined) {
+          attrs = snapshot.attrs
+          for (const reason of snapshot.reasons) recordContextTruncated(reason)
+        }
+      }
+
+      this.#writer.enqueue({
+        flagKey: hookContext.flagKey,
+        variant: evaluationDetails.variant,
+        allocationKey: typeof metadata?.__dd_allocation_key === 'string' ? metadata.__dd_allocation_key : undefined,
+        runtimeDefault: evaluationDetails.variant === undefined,
+        errorCode: evaluationDetails.errorCode,
+        targetingKey,
+        attrs,
+        observeFullEvaluationData: consent,
+        timestamp,
+      })
+    } catch {
+      recordHookError()
+    }
+  }
+
+  destroy () {
+    if (this.#closed) return
+    this.#closed = true
+    this.#stopDeliveryStrategy?.()
+    this.#writer.destroy()
+  }
+}
+
+module.exports = FlagEvalEVPHook

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-aggregation.js

@@ -0,0 +1,190 @@
+'use strict'
+
+const { createHash } = require('node:crypto')
+
+const {
+  FLAG_EVALUATION_DEGRADED_CAP,
+  FLAG_EVALUATION_GLOBAL_CAP,
+  FLAG_EVALUATION_PER_FLAG_CAP,
+} = require('../constants/constants')
+const { validatedContextEntries, snapshotFromEntries } = require('./flag-evaluation-context')
+const { normalizeTargetingKey, optionalKey, protectedErrorCode } =
+  require('./flag-evaluation-pii')
+const { recordDegraded, recordDropped } = require('./flag-evaluation-telemetry')
+
+// V8 hashes longer strings by length alone, making equal-length identities expensive to distinguish.
+const MAX_DIRECT_IDENTITY_LENGTH = 16_383
+
+/** @typedef {import('./flag-evaluation-context').ContextSnapshot} ContextSnapshot */
+/**
+ * @typedef {object} FlagEvaluationEvent
+ * @property {string} flagKey
+ * @property {string} [variant]
+ * @property {string} [allocationKey]
+ * @property {boolean} runtimeDefault
+ * @property {unknown} [errorCode]
+ * @property {unknown} [targetingKey]
+ * @property {ContextSnapshot} [attrs]
+ * @property {unknown} [observeFullEvaluationData]
+ * @property {number} timestamp
+ */
+/**
+ * @typedef {object} AggregationDimensions
+ * @property {string} flagKey
+ * @property {string} [variant]
+ * @property {string} [allocation]
+ * @property {string} [error]
+ */
+/**
+ * @typedef {AggregationDimensions & {
+ *   runtimeDefault: boolean,
+ *   rawTargetingKey?: string,
+ *   attrs?: ContextSnapshot,
+ *   consent: boolean,
+ *   count: number,
+ *   first: number,
+ *   last: number
+ * }} AggregationEntry
+ */
+/**
+ * @typedef {object} AggregationResult
+ * @property {Map<string, AggregationEntry>} full
+ * @property {Map<string, AggregationEntry>} degraded
+ */
+
+/**
+ * Merge one observation into an aggregation entry.
+ *
+ * @param {AggregationEntry} entry
+ * @param {number} timestamp
+ * @param {unknown} consent
+ */
+function observeEntry (entry, timestamp, consent) {
+  entry.count++
+  entry.first = Math.min(entry.first, timestamp)
+  entry.last = Math.max(entry.last, timestamp)
+  entry.consent &&= consent === true
+}
+
+/** @param {Map<string, AggregationEntry>} entries */
+function evaluationCount (entries) {
+  let count = 0
+  for (const entry of entries.values()) count += entry.count
+  return count
+}
+
+class FlagEvaluationAggregator {
+  /** @type {Map<string, AggregationEntry>} */
+  #full = new Map()
+  /** @type {Map<string, AggregationEntry>} */
+  #degraded = new Map()
+  /** @type {Map<string, number>} */
+  #perFlag = new Map()
+
+  /** @param {FlagEvaluationEvent} event */
+  add (event) {
+    const flagKey = normalizeTargetingKey(event.flagKey)
+    if (flagKey === undefined || !Number.isSafeInteger(event.timestamp)) {
+      recordDropped('serialization_error')
+      return
+    }
+    const consent = event.observeFullEvaluationData === true
+    const targetingKey = normalizeTargetingKey(event.targetingKey)
+    const contextEntries = consent ? validatedContextEntries(event.attrs) : undefined
+    const error = protectedErrorCode(event.errorCode)
+    const variant = optionalKey(event.variant)
+    const allocation = optionalKey(event.allocationKey)
+    // Group by the raw key; the serializer independently hashes protected rows once per output bucket.
+    const identity = JSON.stringify([
+      flagKey, variant, allocation, event.runtimeDefault === true, error,
+      targetingKey, contextEntries, consent,
+    ])
+    // Keep digest keys separate from short JSON identities, which always start with '['.
+    const fullKey = identity.length > MAX_DIRECT_IDENTITY_LENGTH
+      ? '#' + createHash('sha256').update(identity).digest('base64')
+      : identity
+    const existing = this.#full.get(fullKey)
+    if (existing) {
+      observeEntry(existing, event.timestamp, consent)
+      return
+    }
+
+    const perFlag = this.#perFlag.get(flagKey) ?? 0
+    if (perFlag >= FLAG_EVALUATION_PER_FLAG_CAP) {
+      this.#addDegraded(event, { flagKey, variant, allocation, error })
+      return
+    }
+    if (this.#full.size >= FLAG_EVALUATION_GLOBAL_CAP) {
+      this.#addDegraded(event, { flagKey, variant, allocation, error })
+      return
+    }
+
+    this.#perFlag.set(flagKey, perFlag + 1)
+    this.#full.set(fullKey, {
+      flagKey,
+      variant,
+      allocation,
+      runtimeDefault: event.runtimeDefault === true,
+      error,
+      rawTargetingKey: targetingKey,
+      // Repeated observations need validation and identity, but no new retained snapshot.
+      attrs: snapshotFromEntries(contextEntries),
+      consent,
+      count: 1,
+      first: event.timestamp,
+      last: event.timestamp,
+    })
+  }
+
+  /** @returns {AggregationResult} */
+  take () {
+    const result = { full: this.#full, degraded: this.#degraded }
+    this.#full = new Map()
+    this.#degraded = new Map()
+    this.#perFlag = new Map()
+    return result
+  }
+
+  clear () {
+    const count = evaluationCount(this.#full) + evaluationCount(this.#degraded)
+    this.#full = new Map()
+    this.#degraded = new Map()
+    this.#perFlag = new Map()
+    return count
+  }
+
+  get size () {
+    return this.#full.size + this.#degraded.size
+  }
+
+  /**
+   * @param {FlagEvaluationEvent} event
+   * @param {AggregationDimensions} dimensions
+   */
+  #addDegraded (event, dimensions) {
+    recordDegraded('cardinality_cap')
+    const key = JSON.stringify([
+      dimensions.flagKey, dimensions.variant, dimensions.allocation,
+      event.runtimeDefault === true, dimensions.error,
+    ])
+    const existing = this.#degraded.get(key)
+    if (existing) {
+      observeEntry(existing, event.timestamp, event.observeFullEvaluationData)
+      return
+    }
+    if (this.#degraded.size >= FLAG_EVALUATION_DEGRADED_CAP) {
+      recordDropped('degraded_cap')
+      return
+    }
+    this.#degraded.set(key, {
+      ...dimensions,
+      runtimeDefault: event.runtimeDefault === true,
+      consent: event.observeFullEvaluationData === true,
+      count: 1,
+      first: event.timestamp,
+      last: event.timestamp,
+    })
+  }
+}
+
+module.exports = { FlagEvaluationAggregator }

package/packages/dd-trace/src/openfeature/writers/flag-evaluation-consumer.js

@@ -0,0 +1,233 @@
+'use strict'
+
+const {
+  EVP_PAYLOAD_SIZE_LIMIT,
+  FLAG_EVALUATION_ENDPOINT,
+  FLAG_EVALUATION_FLUSH_INTERVAL,
+  FLAG_EVALUATION_QUEUE_CAP,
+} = require('../constants/constants')
+const {
+  EVP_EVENT_PLATFORM_SUBDOMAIN,
+  EVP_PROXY_PATH_V2,
+  EVP_SUBDOMAIN_HEADER_NAME,
+} = require('../../evp_proxy/constants')
+const { joinEVPProxyPath } = require('../../evp_proxy/path')
+const { FlagEvaluationAggregator } = require('./flag-evaluation-aggregation')
+const { iterateFlagEvaluationPayloads } = require('./flag-evaluation-payload')
+const { normalizeFlagEvaluationEvent, normalizeTargetingKey } = require('./flag-evaluation-pii')
+const { recordDropped, recordTargetingKeyOmitted } = require('./flag-evaluation-telemetry')
+const BaseFFEWriter = require('./base')
+
+/** @typedef {import('./flag-evaluation-aggregation').FlagEvaluationEvent} FlagEvaluationEvent */
+
+/**
+ * @typedef {object} FlagEvaluationRoute
+ * @property {URL} url
+ * @property {string} basePath
+ * @property {object} [headers]
+ * @property {import('node:https').Agent} [agent]
+ * @property {() => void} [onFallback]
+ * @property {() => void} [onUnavailable]
+ * @property {FlagEvaluationRoute} [fallback]
+ */
+
+class FlagEvaluationConsumer extends BaseFFEWriter {
+  #enabled = false
+  #closed = false
+  #queue = []
+  #immediate
+  #aggregator = new FlagEvaluationAggregator()
+  #context
+  #pendingBytes = 0
+  #pending
+  #pendingCount = 0
+  #pumping = false
+  #flushRequested = false
+  #onProcessed
+  #onDelivered
+  #onIdle
+
+  /**
+   * @param {import('../../config/config-base')} config
+   * @param {FlagEvaluationRoute} [route]
+   * @param {object} [callbacks] - Worker ownership callbacks
+   * @param {(count: number) => void} [callbacks.onProcessed] - Release input credit after processing
+   * @param {(count: number) => void} [callbacks.onDelivered] - Release observations after successful delivery
+   * @param {() => void} [callbacks.onIdle] - Called once shutdown has drained delivery
+   */
+  constructor (config, route, { onProcessed, onDelivered, onIdle } = {}) {
+    route ??= {
+      url: /** @type {URL} */ (config.url),
+      basePath: EVP_PROXY_PATH_V2,
+    }
+    const headers = route.headers ?? { [EVP_SUBDOMAIN_HEADER_NAME]: EVP_EVENT_PLATFORM_SUBDOMAIN }
+    super({
+      config,
+      interval: FLAG_EVALUATION_FLUSH_INTERVAL,
+      agentUrl: route.url,
+      endpoint: joinEVPProxyPath(route.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers,
+      // Consent to send evaluation data never permits logging an echoed response body or error message.
+      formatError: (error, statusCode) => statusCode === undefined
+        ? `Transport error ${error.code ?? 'UNKNOWN'}`
+        : `HTTP status ${statusCode}`,
+    })
+    this.#setRoute({ ...route, headers })
+    this.#onProcessed = onProcessed
+    this.#onDelivered = onDelivered
+    this.#onIdle = onIdle
+
+    this.#context = { service: typeof config.service === 'string' ? config.service : '' }
+    if (typeof config.env === 'string') this.#context.env = config.env
+    if (typeof config.version === 'string') this.#context.version = config.version
+  }
+
+  hasCapacity () {
+    return this.#enabled && !this.#closed && this.#queue.length < FLAG_EVALUATION_QUEUE_CAP
+  }
+
+  /**
+   * @param {boolean} enabled
+   * @param {FlagEvaluationRoute} [route]
+   */
+  setEnabled (enabled, route) {
+    if (route) this.#setRoute(route)
+    if (!enabled && this.#enabled) this.#discardBuffered('unavailable')
+    this.#enabled = enabled && !this.#closed
+  }
+
+  /** @param {FlagEvaluationEvent} event */
+  enqueue (event) {
+    if (this.#closed) {
+      recordDropped('closed')
+      return false
+    }
+    if (!this.#enabled) {
+      recordDropped('unavailable')
+      return false
+    }
+    if (this.#queue.length >= FLAG_EVALUATION_QUEUE_CAP) {
+      recordDropped('queue_overflow')
+      return false
+    }
+
+    const targetingKey = normalizeTargetingKey(event.targetingKey)
+    if (targetingKey === undefined && event.targetingKey !== undefined && event.targetingKey !== null) {
+      recordTargetingKeyOmitted()
+    }
+    this.#queue.push(normalizeFlagEvaluationEvent(event, targetingKey))
+    if (this.#immediate === undefined) {
+      this.#immediate = setImmediate(() => this.#drain())
+      this.#immediate.unref?.()
+    }
+    return true
+  }
+
+  flush () {
+    this.#cancelImmediate()
+    this.#drain()
+    if (!this.#enabled && !this.#closed) return
+    this.#flushRequested = true
+    this.#pump()
+  }
+
+  destroy () {
+    if (this.#closed) return
+    this.#cancelImmediate()
+    this.#drain()
+    this.#closed = true
+    this.#enabled = false
+    super.destroy()
+  }
+
+  #pump () {
+    if (this.#pumping) return
+    this.#pumping = true
+    try {
+      // Reserve a maximum-sized payload before advancing the iterator. HTTP callbacks release this budget.
+      while (this.#pendingBytes <= EVP_PAYLOAD_SIZE_LIMIT) {
+        if (!this.#pending) {
+          if ((!this.#flushRequested && !this.#closed) || this.#aggregator.size === 0) break
+          this.#flushRequested = false
+          const { full, degraded } = this.#aggregator.take()
+          for (const entry of full.values()) this.#pendingCount += entry.count
+          for (const entry of degraded.values()) this.#pendingCount += entry.count
+          this.#pending = iterateFlagEvaluationPayloads(full, degraded, this.#context, Date.now(), count => {
+            this.#pendingCount -= count
+          })
+        }
+        const next = this.#pending.next()
+        if (next.done) {
+          this.#pending = undefined
+          continue
+        }
+        const payload = next.value
+        const bytes = Buffer.byteLength(payload.encoded)
+        this.#pendingBytes += bytes
+        this._sendPayload(payload.encoded, payload.rows, delivered => {
+          this.#pendingBytes -= bytes
+          if (delivered) this.#onDelivered?.(payload.evaluations)
+          else recordDropped('delivery_failure', payload.evaluations)
+          this.#pump()
+        })
+      }
+    } finally {
+      this.#pumping = false
+    }
+    if (this.#closed && !this.#pending && this.#aggregator.size === 0 && this.#pendingBytes === 0) {
+      this.#onIdle?.()
+      this.#onIdle = undefined
+    }
+  }
+
+  /** @param {FlagEvaluationRoute} route */
+  #setRoute (route) {
+    const headers = route.headers ?? { [EVP_SUBDOMAIN_HEADER_NAME]: EVP_EVENT_PLATFORM_SUBDOMAIN }
+    const fallback = route.fallback && {
+      url: route.fallback.url,
+      endpoint: joinEVPProxyPath(route.fallback.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers: route.fallback.headers ?? {},
+      agent: route.fallback.agent,
+      onFallback: route.fallback.onFallback,
+      onUnavailable: route.fallback.onUnavailable,
+    }
+    this._setRoutes({
+      url: route.url,
+      endpoint: joinEVPProxyPath(route.basePath, FLAG_EVALUATION_ENDPOINT),
+      headers,
+      agent: route.agent,
+      onFallback: route.onFallback,
+      onUnavailable: route.onUnavailable,
+    }, fallback)
+  }
+
+  #cancelImmediate () {
+    if (this.#immediate !== undefined) clearImmediate(this.#immediate)
+    this.#immediate = undefined
+  }
+
+  #drain () {
+    this.#immediate = undefined
+    const queue = this.#queue
+    this.#queue = []
+    for (const event of queue) {
+      this.#aggregator.add(event)
+      this.#onProcessed?.(1)
+    }
+  }
+
+  /** @param {string} reason */
+  #discardBuffered (reason) {
+    this.#cancelImmediate()
+    const count = this.#queue.length + this.#aggregator.clear() + this.#pendingCount
+    this.#pending?.return()
+    this.#pending = undefined
+    this.#pendingCount = 0
+    this.#flushRequested = false
+    this.#onProcessed?.(this.#queue.length)
+    this.#queue = []
+    recordDropped(reason, count)
+  }
+}
+
+module.exports = FlagEvaluationConsumer