dd-trace 6.18.0 → 6.20.0

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

@@ -0,0 +1,181 @@
+'use strict'
+
+const { EVP_EVENT_SIZE_LIMIT, EVP_PAYLOAD_SIZE_LIMIT } = require('../constants/constants')
+const { validateContextSnapshot } = require('./flag-evaluation-context')
+const { prefixedTargetingKeyDigest, normalizeTargetingKey, protectedErrorCode } = require('./flag-evaluation-pii')
+const { recordDegraded, recordDropped, recordPayloadSplit } = require('./flag-evaluation-telemetry')
+
+/** @typedef {import('./flag-evaluation-aggregation').AggregationEntry} AggregationEntry */
+/** @typedef {import('./flag-evaluation-context').ContextSnapshot} ContextSnapshot */
+/**
+ * @typedef {object} FlagEvaluationBatchContext
+ * @property {string} service
+ * @property {string} [env]
+ * @property {string} [version]
+ */
+/**
+ * @typedef {object} FlagEvaluationRow
+ * @property {number} timestamp
+ * @property {{ key: string }} flag
+ * @property {number} first_evaluation
+ * @property {number} last_evaluation
+ * @property {number} evaluation_count
+ * @property {boolean} [runtime_default_used]
+ * @property {string} [targeting_key]
+ * @property {{ evaluation: ContextSnapshot }} [context]
+ * @property {{ key: string }} [variant]
+ * @property {{ key: string }} [allocation]
+ * @property {{ message: string }} [error]
+ */
+/** @typedef {{ encoded: string, rows: number, evaluations: number }} EncodedFlagEvaluationPayload */
+
+/**
+ * @param {AggregationEntry} entry
+ * @param {number} timestamp
+ * @param {boolean} degraded
+ * @returns {FlagEvaluationRow | undefined}
+ */
+function makeRow (entry, timestamp, degraded) {
+  const flagKey = normalizeTargetingKey(entry.flagKey)
+  if (flagKey === undefined || !Number.isSafeInteger(entry.first) || !Number.isSafeInteger(entry.last) ||
+    !Number.isSafeInteger(entry.count) || entry.count < 1) return
+  /** @type {FlagEvaluationRow} */
+  const row = {
+    timestamp,
+    flag: { key: flagKey },
+    first_evaluation: entry.first,
+    last_evaluation: entry.last,
+    evaluation_count: entry.count,
+  }
+  if (entry.runtimeDefault === true) row.runtime_default_used = true
+  const variant = normalizeTargetingKey(entry.variant)
+  const allocation = normalizeTargetingKey(entry.allocation)
+  if (variant) row.variant = { key: variant }
+  if (allocation) row.allocation = { key: allocation }
+  const error = protectedErrorCode(entry.error)
+  if (error !== undefined) row.error = { message: error }
+  if (!degraded) {
+    const targetingKey = entry.consent === true
+      ? normalizeTargetingKey(entry.rawTargetingKey)
+      : prefixedTargetingKeyDigest(entry.rawTargetingKey)
+    if (targetingKey !== undefined) row.targeting_key = targetingKey
+    const attrs = entry.consent === true ? validateContextSnapshot(entry.attrs) : undefined
+    if (attrs !== undefined) row.context = { evaluation: attrs }
+  }
+  return row
+}
+
+/**
+ * Advance serialization only when the transport has room for another complete envelope.
+ * Takes ownership of the detached aggregate maps and clears them when iteration starts.
+ *
+ * @param {Map<string, AggregationEntry>} full
+ * @param {Map<string, AggregationEntry>} degraded
+ * @param {FlagEvaluationBatchContext} context
+ * @param {number} timestamp
+ * @param {(count: number) => void} [onConsumed] - Transfer observation ownership on encoding or discard
+ * @yields {EncodedFlagEvaluationPayload} One envelope bounded by the existing EVP payload limit.
+ */
+function * iterateFlagEvaluationPayloads (full, degraded, context, timestamp, onConsumed) {
+  const prefix = '{"context":' + JSON.stringify(context) + ',"flagEvaluations":['
+  const suffix = ']}'
+  /** @type {string[]} */
+  let encodedRows = []
+  let evaluations = 0
+  let payloadCount = 0
+  let size = Buffer.byteLength(prefix) + Buffer.byteLength(suffix)
+
+  const close = () => {
+    const payload = { encoded: prefix + encodedRows.join(',') + suffix, rows: encodedRows.length, evaluations }
+    if (payloadCount > 0) recordPayloadSplit()
+    payloadCount++
+    evaluations = 0
+    encodedRows = []
+    size = Buffer.byteLength(prefix) + Buffer.byteLength(suffix)
+    return payload
+  }
+
+  /**
+   * @param {string} reason
+   * @param {number} count
+   */
+  const drop = (reason, count) => {
+    onConsumed?.(count)
+    recordDropped(reason, count)
+  }
+
+  /** @type {Array<[AggregationEntry, boolean]>} */
+  const entries = []
+  for (const entry of full.values()) entries.push([entry, false])
+  for (const entry of degraded.values()) entries.push([entry, true])
+
+  // Lookup keys are no longer needed after aggregation. Pop entries in their original
+  // order so a paused flush does not retain entries that have already been encoded.
+  full.clear()
+  degraded.clear()
+  entries.reverse()
+  while (entries.length > 0) {
+    const [entry, aggregateDegraded] = /** @type {[AggregationEntry, boolean]} */ (entries.pop())
+    const row = makeRow(entry, timestamp, aggregateDegraded)
+    if (row === undefined) {
+      drop('serialization_error', entry.count)
+      continue
+    }
+    let serializedRow = row
+    let encoded
+    try {
+      encoded = JSON.stringify(serializedRow)
+    } catch {
+      drop('serialization_error', serializedRow.evaluation_count)
+      continue
+    }
+
+    let canDegrade = serializedRow.targeting_key !== undefined || serializedRow.context !== undefined
+    const degrade = () => {
+      if (!canDegrade) return false
+      serializedRow = { ...serializedRow }
+      delete serializedRow.targeting_key
+      delete serializedRow.context
+      encoded = JSON.stringify(serializedRow)
+      recordDegraded('payload_limit', serializedRow.evaluation_count)
+      canDegrade = false
+      return true
+    }
+
+    try {
+      if (Buffer.byteLength(encoded) > EVP_EVENT_SIZE_LIMIT) degrade()
+    } catch {
+      drop('serialization_error', serializedRow.evaluation_count)
+      continue
+    }
+    if (Buffer.byteLength(encoded) > EVP_EVENT_SIZE_LIMIT) {
+      drop('payload_limit', serializedRow.evaluation_count)
+      continue
+    }
+
+    let addition = Buffer.byteLength(encoded) + Number(encodedRows.length > 0)
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT && encodedRows.length > 0) {
+      yield close()
+      addition = Buffer.byteLength(encoded)
+    }
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT) {
+      try {
+        if (degrade()) addition = Buffer.byteLength(encoded)
+      } catch {
+        drop('serialization_error', serializedRow.evaluation_count)
+        continue
+      }
+    }
+    if (size + addition > EVP_PAYLOAD_SIZE_LIMIT) {
+      drop('payload_limit', serializedRow.evaluation_count)
+      continue
+    }
+    encodedRows.push(encoded)
+    onConsumed?.(serializedRow.evaluation_count)
+    evaluations += serializedRow.evaluation_count
+    size += addition
+  }
+  if (encodedRows.length > 0) yield close()
+}
+
+module.exports = { iterateFlagEvaluationPayloads }

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

@@ -0,0 +1,108 @@
+'use strict'
+
+const { hashTargetingKey: digestTargetingKey } = require('../encoding')
+
+// Keep this vocabulary explicit: an upstream enum addition needs a privacy review.
+const ERROR_CODES = new Set([
+  'PROVIDER_NOT_READY',
+  'PROVIDER_FATAL',
+  'FLAG_NOT_FOUND',
+  'PARSE_ERROR',
+  'TYPE_MISMATCH',
+  'TARGETING_KEY_MISSING',
+  'INVALID_CONTEXT',
+  'GENERAL',
+])
+
+/**
+ * Validate targeting text before UTF-8 encoding, which would repair lone surrogates.
+ * Empty text is valid and distinct from a missing key. Do not coerce customer input.
+ *
+ * @param {unknown} value - Evaluation targeting key
+ * @returns {string | undefined}
+ */
+function normalizeTargetingKey (value) {
+  if (typeof value !== 'string') return
+
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i)
+    if (code >= 0xD8_00 && code <= 0xDB_FF) {
+      if (++i === value.length) return
+      const low = value.charCodeAt(i)
+      if (low < 0xDC_00 || low > 0xDF_FF) return
+    } else if (code >= 0xDC_00 && code <= 0xDF_FF) {
+      return
+    }
+  }
+
+  return value
+}
+
+/**
+ * Apply EVP's protected targeting-key policy using the shared SHA-256 primitive.
+ * The cross-SDK contract deliberately uses an unsalted, stable digest for subject counts.
+ * This is pseudonymization, not anonymity: guessable keys remain guessable and equal
+ * keys produce equal hashes across services and organizations. An org-scoped salt
+ * requires a coordinated configuration/backend contract, not a JS-only secret.
+ * This runs after queue handoff; hashing must not move onto the evaluation hot path.
+ *
+ * @param {unknown} value - Raw evaluation targeting key, never a previously emitted hash
+ * @returns {string | undefined}
+ */
+function prefixedTargetingKeyDigest (value) {
+  const key = normalizeTargetingKey(value)
+  if (key === undefined || key === '') return key
+  return 'sha256_' + digestTargetingKey(key)
+}
+
+/**
+ * Preserve only approved OpenFeature codes on the wire, in every consent mode.
+ * Absence means no error; malformed or unknown supplied codes become GENERAL.
+ *
+ * @param {unknown} value - OpenFeature errorCode, never errorMessage
+ * @returns {string | undefined}
+ */
+function protectedErrorCode (value) {
+  if (value === undefined || value === null || value === '') return
+  return typeof value === 'string' && ERROR_CODES.has(value) ? value : 'GENERAL'
+}
+
+/**
+ * Optional metadata dimensions omit empty text; targeting keys deliberately preserve it.
+ *
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function optionalKey (value) {
+  const key = normalizeTargetingKey(value)
+  return key === undefined || key.length === 0 ? undefined : key
+}
+
+/**
+ * Shape observations at both admission boundaries; each caller counts omitted targeting keys.
+ *
+ * @param {import('./flag-evaluation-aggregation').FlagEvaluationEvent} event
+ * @param {string | undefined} targetingKey - Targeting key already validated by the caller
+ */
+function normalizeFlagEvaluationEvent (event, targetingKey) {
+  const consent = event.observeFullEvaluationData === true
+  return {
+    flagKey: normalizeTargetingKey(event.flagKey),
+    variant: optionalKey(event.variant),
+    allocationKey: optionalKey(event.allocationKey),
+    runtimeDefault: event.runtimeDefault === true,
+    errorCode: protectedErrorCode(event.errorCode),
+    targetingKey,
+    attrs: consent ? event.attrs : undefined,
+    observeFullEvaluationData: consent,
+    timestamp: typeof event.timestamp === 'number' ? event.timestamp : NaN,
+  }
+}
+
+module.exports = {
+  normalizeFlagEvaluationEvent,
+  normalizeTargetingKey,
+  optionalKey,
+  prefixedTargetingKeyDigest,
+  protectedErrorCode,
+}

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

@@ -0,0 +1,154 @@
+'use strict'
+
+let metrics
+/** @type {Int32Array | undefined} */
+let workerState
+
+// Namespace resets clear points, not metric instances. Names and reasons are fixed below.
+/** @type {Map<string, { inc: (value: number) => void }>} */
+const countMetrics = new Map()
+
+const DROP_REASONS = new Set([
+  'pre_queue_overflow',
+  'queue_overflow',
+  'closed',
+  'unavailable',
+  'degraded_cap',
+  'payload_limit',
+  'serialization_error',
+  // Discarded after failed delivery; an ambiguous response does not prove the receiver lost the batch.
+  'delivery_failure',
+  'worker_failure',
+  'shutdown_timeout',
+])
+const DEGRADE_REASONS = new Set(['cardinality_cap', 'payload_limit'])
+const CONTEXT_REASONS = new Set([
+  'max_context_fields',
+  'max_key_length',
+  'max_value_length',
+  'max_list_elements',
+  'max_structure_properties',
+  'max_snapshot_depth',
+  'max_visited_nodes',
+  'cycle',
+  'invalid_encoding',
+  'unsupported_type',
+  'snapshot_error',
+])
+
+// Slot 0 owns admitted input until aggregation; slot 1 owns all accepted observations until delivery/drop.
+// Fixed metric slots follow. Only the application drains them; no message per event or flush.
+/** @type {Array<[string, string | undefined]>} */
+const metricKeys = [
+  ...[...DROP_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.rows.dropped', reason])),
+  ...[...DEGRADE_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.rows.degraded', reason])),
+  ...[...CONTEXT_REASONS].map(reason => /** @type {[string, string]} */ (['flagevaluation.context.truncated', reason])),
+  ['flagevaluation.payload.splits', undefined],
+  ['flagevaluation.targeting_key.omitted', 'invalid'],
+  ['flagevaluation.hook.errors', undefined],
+]
+const metricSlots = new Map(metricKeys.map(([name, reason], index) => [name + ':' + reason, index + 2]))
+
+/** @param {Int32Array} state */
+function configureWorkerTelemetry (state) {
+  workerState = state
+}
+
+function createWorkerState () {
+  return new Int32Array(new SharedArrayBuffer((metricKeys.length + 2) * Int32Array.BYTES_PER_ELEMENT))
+}
+
+/** @param {Int32Array} state */
+function collectWorkerTelemetry (state) {
+  for (let i = 0; i < metricKeys.length; i++) {
+    const value = Atomics.exchange(state, i + 2, 0)
+    const [name, reason] = metricKeys[i]
+    count(name, value, reason)
+  }
+}
+
+/**
+ * Best-effort telemetry must never affect an evaluation or writer drain.
+ *
+ * @param {string} name - Bounded metric name
+ * @param {number} value - Count to add
+ * @param {string} [reason] - Bounded reason tag
+ */
+function count (name, value, reason) {
+  if (!Number.isSafeInteger(value) || value <= 0) return
+  if (workerState) {
+    const slot = /** @type {number} */ (metricSlots.get(name + ':' + reason))
+    // Saturate instead of wrapping if the application stops collecting metrics for a long time.
+    let previous = Atomics.load(workerState, slot)
+    while (Atomics.compareExchange(workerState, slot, previous,
+      Math.min(0x7F_FF_FF_FF, previous + value)) !== previous) {
+      previous = Atomics.load(workerState, slot)
+    }
+    return
+  }
+  try {
+    const id = name + ':' + reason
+    let metric = countMetrics.get(id)
+    if (metric === undefined) {
+      metrics ??= require('../../telemetry/metrics').manager.namespace('general')
+      metric = /** @type {{ inc: (value: number) => void }} */ (
+        metrics.count(name, reason === undefined ? undefined : { reason })
+      )
+      countMetrics.set(id, metric)
+    }
+    metric.inc(value)
+  } catch {}
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordDropped (reason, value = 1) {
+  if (!DROP_REASONS.has(reason)) return
+  if (workerState && Number.isSafeInteger(value) && value > 0) Atomics.sub(workerState, 1, value)
+  count('flagevaluation.rows.dropped', value, reason)
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordDegraded (reason, value = 1) {
+  if (DEGRADE_REASONS.has(reason)) count('flagevaluation.rows.degraded', value, reason)
+}
+
+/** @param {number} [value] */
+function recordPayloadSplit (value = 1) {
+  count('flagevaluation.payload.splits', value)
+}
+
+/**
+ * @param {string} reason
+ * @param {number} [value]
+ */
+function recordContextTruncated (reason, value = 1) {
+  if (CONTEXT_REASONS.has(reason)) count('flagevaluation.context.truncated', value, reason)
+}
+
+/** @param {number} [value] */
+function recordTargetingKeyOmitted (value = 1) {
+  count('flagevaluation.targeting_key.omitted', value, 'invalid')
+}
+
+/** @param {number} [value] */
+function recordHookError (value = 1) {
+  count('flagevaluation.hook.errors', value)
+}
+
+module.exports = {
+  collectWorkerTelemetry,
+  configureWorkerTelemetry,
+  createWorkerState,
+  recordContextTruncated,
+  recordDegraded,
+  recordDropped,
+  recordHookError,
+  recordPayloadSplit,
+  recordTargetingKeyOmitted,
+}

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

@@ -0,0 +1,77 @@
+'use strict'
+
+const { parentPort, workerData } = require('node:worker_threads')
+const port = /** @type {import('node:worker_threads').MessagePort} */ (parentPort)
+
+// Bootstrap only the lifecycle registry, never the tracer or its preload entrypoints.
+globalThis[Symbol.for('dd-trace')] = { beforeExitHandlers: new Set() }
+
+const logWriter = require('../../log/writer')
+const { configureWorkerTelemetry } = require('./flag-evaluation-telemetry')
+const state = new Int32Array(workerData.state)
+configureWorkerTelemetry(state)
+const FlagEvaluationConsumer = require('./flag-evaluation-consumer')
+
+/** @param {'debug' | 'info' | 'warn' | 'error'} level */
+function forwardLog (level) {
+  /** @param {unknown} message */
+  return message => {
+    try {
+      port.postMessage({ type: 'log', level, message: message instanceof Error ? message.stack : String(message) })
+    } catch {
+      // Diagnostics are best-effort when the parent port is closing.
+    }
+  }
+}
+
+// Use the parent's effective settings, not a second environment-only configuration.
+// The custom logger itself stays in the parent isolate because functions cannot be cloned.
+const { enabled = false, level } = workerData.logging ?? {}
+logWriter.configure(enabled, level, {
+  debug: forwardLog('debug'),
+  info: forwardLog('info'),
+  warn: forwardLog('warn'),
+  error: forwardLog('error'),
+})
+
+/** @param {import('./flag-evaluations').SerializedFlagEvaluationRoute} route */
+function deserializeRoute (route) {
+  return {
+    url: new URL(route.url),
+    basePath: route.basePath,
+    headers: route.headers,
+    fallback: route.fallback && deserializeRoute(route.fallback),
+    onFallback: route.onFallback
+      ? () => port.postMessage({ type: 'route', id: route.id, status: 'fallback' })
+      : undefined,
+    onUnavailable: route.onUnavailable
+      ? () => port.postMessage({ type: 'route', id: route.id, status: 'unavailable' })
+      : undefined,
+  }
+}
+
+const route = deserializeRoute(workerData.route)
+const consumer = new FlagEvaluationConsumer({ ...workerData.context, url: route.url }, route, {
+  onProcessed: count => Atomics.sub(state, 0, count),
+  onDelivered: count => Atomics.sub(state, 1, count),
+  onIdle: () => port.close(),
+})
+consumer.setEnabled(true, route)
+port.on('message', message => {
+  switch (message.type) {
+    case 'batch':
+      for (const event of message.events) {
+        if (!consumer.enqueue(event)) Atomics.sub(state, 0, 1)
+      }
+      break
+    case 'enabled':
+      consumer.setEnabled(message.enabled, message.route && deserializeRoute(message.route))
+      break
+    case 'flush':
+      consumer.flush()
+      break
+    case 'close':
+      consumer.destroy()
+      break
+  }
+})