feat(openfeature): preserve configuration source semantics

leoromanovsky · leoromanovsky · commit 4f57fe88db30 · 2026-07-20T11:10:09.000-06:00
diff --git a/integration-tests/openfeature/openfeature-agentless.spec.js b/integration-tests/openfeature/openfeature-agentless.spec.js
@@ -86,7 +86,7 @@ describe('OpenFeature agentless configuration integration', () => {
       cwd,
       env: {
         DD_API_KEY: 'integration-api-key',
-        DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'true',
+        DD_FEATURE_FLAGS_ENABLED: 'true',
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: backendUrl,
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: '5',
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: '1',
diff --git a/integration-tests/openfeature/openfeature-exposure-events.spec.js b/integration-tests/openfeature/openfeature-exposure-events.spec.js
@@ -60,7 +60,7 @@ describe('OpenFeature Remote Config and Exposure Events Integration', () => {
           env: {
             DD_TRACE_AGENT_PORT: agent.port,
             DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: '0.1',
-            DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'true',
+            DD_FEATURE_FLAGS_ENABLED: 'true',
             // Preserve the existing RC exposure path until agentless emission is supported.
             DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: 'remote_config',
           },
@@ -161,7 +161,7 @@ describe('OpenFeature Remote Config and Exposure Events Integration', () => {
           env: {
             DD_TRACE_AGENT_PORT: agent.port,
             DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: '0.1',
-            DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'true',
+            DD_FEATURE_FLAGS_ENABLED: 'true',
             DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: 'remote_config',
           },
         })
@@ -245,7 +245,7 @@ describe('OpenFeature Remote Config and Exposure Events Integration', () => {
         env: {
           DD_TRACE_AGENT_PORT: agent.port,
           DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS: '0.1',
-          DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'true',
+          DD_FEATURE_FLAGS_ENABLED: 'true',
           DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: 'remote_config',
         },
       })
@@ -307,7 +307,7 @@ describe('OpenFeature Remote Config and Exposure Events Integration', () => {
         cwd,
         env: {
           DD_TRACE_AGENT_PORT: agent.port,
-          DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED: 'false',
+          DD_FEATURE_FLAGS_ENABLED: 'false',
         },
       })
     })
diff --git a/packages/dd-trace/src/config/generated-config-types.d.ts b/packages/dd-trace/src/config/generated-config-types.d.ts
@@ -87,6 +87,7 @@ export interface GeneratedConfig {
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: string | undefined;
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: number;
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: number;
+  DD_FEATURE_FLAGS_ENABLED: boolean;
   DD_GIT_BRANCH: string | undefined;
   DD_GIT_COMMIT_AUTHOR_DATE: string | undefined;
   DD_GIT_COMMIT_AUTHOR_EMAIL: string | undefined;
@@ -696,6 +697,7 @@ export interface GeneratedEnvVarConfig {
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: string | undefined;
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: number;
   DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: number;
+  DD_FEATURE_FLAGS_ENABLED: boolean;
   DD_GIT_BRANCH: string | undefined;
   DD_GIT_COMMIT_AUTHOR_DATE: string | undefined;
   DD_GIT_COMMIT_AUTHOR_EMAIL: string | undefined;
diff --git a/packages/dd-trace/src/config/supported-configurations.json b/packages/dd-trace/src/config/supported-configurations.json
@@ -817,6 +817,13 @@
         "default": "false"
       }
     ],
+    "DD_FEATURE_FLAGS_ENABLED": [
+      {
+        "implementation": "A",
+        "type": "boolean",
+        "default": "true"
+      }
+    ],
     "DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED": [
       {
         "implementation": "A",
diff --git a/packages/dd-trace/src/openfeature/configuration_source.js b/packages/dd-trace/src/openfeature/configuration_source.js
@@ -3,6 +3,7 @@
 const log = require('../log')
 
 const CONFIGURATION_SOURCE_AGENTLESS = 'agentless'
+const CONFIGURATION_SOURCE_DISABLED = 'disabled'
 const CONFIGURATION_SOURCE_REMOTE_CONFIG = 'remote_config'
 
 const DEFAULT_AGENTLESS_PATH = '/api/v2/feature-flagging/config/rules-based/server'
@@ -19,7 +20,7 @@ const MAX_POLL_INTERVAL_SECONDS = 60 * 60
 function resolve (config) {
   const mode = resolveMode(config)
 
-  if (mode === CONFIGURATION_SOURCE_REMOTE_CONFIG) {
+  if (mode !== CONFIGURATION_SOURCE_AGENTLESS) {
     return { mode }
   }
 
@@ -86,6 +87,23 @@ function isRemoteConfig (config) {
   }
 }
 
+/**
+ * Reports whether the provider should be exposed for the resolved source.
+ *
+ * Invalid source values fail closed.
+ *
+ * @param {import('../config/config-base')} config - Tracer configuration.
+ * @returns {boolean} Whether Feature Flagging is enabled.
+ */
+function isEnabled (config) {
+  try {
+    return resolveMode(config) !== CONFIGURATION_SOURCE_DISABLED
+  } catch (error) {
+    log.error('Unable to configure Feature Flagging configuration source', error)
+    return false
+  }
+}
+
 /**
  * Normalizes and validates source selection without resolving agentless
  * endpoint or timing configuration.
@@ -94,7 +112,25 @@ function isRemoteConfig (config) {
  * @returns {string} Selected configuration-source mode.
  */
 function resolveMode (config) {
+  if (config.DD_FEATURE_FLAGS_ENABLED === false) return CONFIGURATION_SOURCE_DISABLED
+
   const value = config.DD_FEATURE_FLAGS_CONFIGURATION_SOURCE
+  const origin = config.getOrigin?.('DD_FEATURE_FLAGS_CONFIGURATION_SOURCE')
+  const hasExplicitSource = origin ? origin !== 'default' : value !== undefined && value !== null
+
+  if (!hasExplicitSource) {
+    const legacyEnabled = config.experimental?.flaggingProvider?.enabled
+    const legacyOrigin = config.getOrigin?.('experimental.flaggingProvider.enabled')
+    const hasExplicitLegacySetting = legacyOrigin
+      ? legacyOrigin !== 'default'
+      : legacyEnabled !== undefined && legacyEnabled !== null
+
+    if (hasExplicitLegacySetting) {
+      if (legacyEnabled === true) return CONFIGURATION_SOURCE_REMOTE_CONFIG
+      if (legacyEnabled === false) return CONFIGURATION_SOURCE_DISABLED
+    }
+  }
+
   const mode = String(value ?? '').trim().toLowerCase() || CONFIGURATION_SOURCE_AGENTLESS
   if (mode !== CONFIGURATION_SOURCE_AGENTLESS && mode !== CONFIGURATION_SOURCE_REMOTE_CONFIG) {
     throw new Error(`Unsupported Feature Flagging configuration source: ${mode}`)
@@ -176,6 +212,7 @@ function positiveMilliseconds (value, fallbackSeconds, setting, maximumSeconds)
 
 module.exports = {
   enable,
+  isEnabled,
   isRemoteConfig,
   resolve,
 }
diff --git a/packages/dd-trace/src/openfeature/index.js b/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')
 }
 
 /**
diff --git a/packages/dd-trace/src/openfeature/register.js b/packages/dd-trace/src/openfeature/register.js
@@ -11,7 +11,36 @@ const noop = new (require('./noop'))()
 function hasFlaggingProvider (proxy) {
   const descriptor = Reflect.getOwnPropertyDescriptor(proxy, 'openfeature')
 
-  return descriptor?.value !== undefined && descriptor.value !== noop
+  return descriptor?.get !== undefined || (descriptor?.value !== undefined && descriptor.value !== noop)
+}
+
+/**
+ * Exposes the provider without constructing it until application code reads it.
+ * The generic tracer lazy proxy is eager outside serverless environments, while
+ * agentless delivery must remain silent until the application uses OpenFeature.
+ *
+ * @param {import('../proxy')} proxy
+ * @param {import('../tracer')} tracer
+ * @param {import('../config/config-base')} config
+ * @param {object} configurationSource
+ */
+function defineFlaggingProvider (proxy, tracer, config, configurationSource) {
+  Reflect.defineProperty(proxy, 'openfeature', {
+    get () {
+      const FlaggingProvider = require('./flagging_provider')
+      const provider = new FlaggingProvider(tracer, config)
+
+      Reflect.defineProperty(proxy, 'openfeature', {
+        value: provider,
+        configurable: true,
+        enumerable: true,
+      })
+      configurationSource.enable(config, () => provider)
+      return provider
+    },
+    configurable: true,
+    enumerable: true,
+  })
 }
 
 registerFeature({
@@ -27,28 +56,26 @@ registerFeature({
   remoteConfig (rc, config, proxy) {
     const configurationSource = require('./configuration_source')
     const openfeatureRemoteConfig = require('./remote_config')
+    const subscribe = configurationSource.isRemoteConfig(config)
     openfeatureRemoteConfig.enable(
       rc,
-      config,
       () => proxy.openfeature,
-      configurationSource.isRemoteConfig(config)
+      subscribe
     )
   },
 
   /**
    * @param {import('../config/config-base')} config
    * @param {import('../tracer')} tracer
    * @param {import('../proxy')} proxy
-   * @param {Function} lazyProxy
    */
-  enable (config, tracer, proxy, lazyProxy) {
-    if (config.experimental.flaggingProvider.enabled) {
-      proxy._modules.openfeature.enable(config)
-      if (!hasFlaggingProvider(proxy)) {
-        lazyProxy(proxy, 'openfeature', () => require('./flagging_provider'), tracer, config)
-      }
-      const configurationSource = require('./configuration_source')
-      configurationSource.enable(config, () => proxy.openfeature)
+  enable (config, tracer, proxy) {
+    const configurationSource = require('./configuration_source')
+    if (!configurationSource.isEnabled(config)) return
+
+    proxy._modules.openfeature.enable(config)
+    if (!hasFlaggingProvider(proxy)) {
+      defineFlaggingProvider(proxy, tracer, config, configurationSource)
     }
   },
 })
diff --git a/packages/dd-trace/src/openfeature/remote_config.js b/packages/dd-trace/src/openfeature/remote_config.js
@@ -6,19 +6,15 @@ 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 {boolean} [subscribe] - Whether Agent Remote Config owns UFC delivery
  */
-function enable (rc, config, getOpenfeatureProxy, subscribe = true) {
-  // 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 = true) {
+  // Capability advertisement and product subscription both opt into the billed
+  // Agent Remote Config delivery path.
+  if (!subscribe) return
 
-  // Only register the product handler when the provider is enabled and Agent
-  // Remote Config is the selected UFC source. The capability stays enabled
-  // because it describes library support, not the active delivery mode.
-  if (!config.experimental.flaggingProvider.enabled || !subscribe) return
+  rc.updateCapabilities(RemoteConfigCapabilities.FFE_FLAG_CONFIGURATION_RULES, true)
 
   // Set product handler for FFE_FLAGS
   rc.setProductHandler('FFE_FLAGS', (action, conf) => {
diff --git a/packages/dd-trace/test/config/index.spec.js b/packages/dd-trace/test/config/index.spec.js
@@ -4939,17 +4939,38 @@ rules:
   })
 
   context('Feature Flagging configuration source', () => {
-    it('defaults to agentless delivery with cross-SDK timings', () => {
+    it('defaults to an enabled provider with agentless delivery and cross-SDK timings', () => {
       const config = getConfig()
 
       assertObjectContains(config, {
+        DD_FEATURE_FLAGS_ENABLED: true,
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: 'agentless',
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: undefined,
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: 30,
         DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: 2,
       })
+      assert.strictEqual(config.experimental.flaggingProvider.enabled, false)
     })
 
+    it('reads the stable provider kill switch', () => {
+      process.env.DD_FEATURE_FLAGS_ENABLED = 'false'
+
+      const config = getConfig()
+
+      assert.strictEqual(config.DD_FEATURE_FLAGS_ENABLED, false)
+    })
+
+    for (const value of ['true', 'false']) {
+      it(`retains the deprecated experimental provider setting when set to ${value}`, () => {
+        process.env.DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED = value
+
+        const config = getConfig()
+
+        assert.strictEqual(config.DD_FEATURE_FLAGS_ENABLED, true)
+        assert.strictEqual(config.experimental.flaggingProvider.enabled, value === 'true')
+      })
+    }
+
     it('reads the configuration source environment variable', () => {
       process.env.DD_FEATURE_FLAGS_CONFIGURATION_SOURCE = 'remote_config'
 
diff --git a/packages/dd-trace/test/openfeature/configuration_source.spec.js b/packages/dd-trace/test/openfeature/configuration_source.spec.js
@@ -16,10 +16,17 @@ describe('OpenFeature configuration source', () => {
   beforeEach(() => {
     config = {
       DD_API_KEY: 'test-api-key',
+      DD_FEATURE_FLAGS_ENABLED: true,
       DD_FEATURE_FLAGS_CONFIGURATION_SOURCE: 'agentless',
       DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_BASE_URL: undefined,
       DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_POLL_INTERVAL_SECONDS: 30,
       DD_FEATURE_FLAGS_CONFIGURATION_SOURCE_AGENTLESS_REQUEST_TIMEOUT_SECONDS: 2,
+      experimental: {
+        flaggingProvider: {
+          enabled: false,
+        },
+      },
+      getOrigin: sinon.stub().returns('default'),
       site: 'datadoghq.com',
       env: 'my env',
     }
@@ -43,6 +50,54 @@ describe('OpenFeature configuration source', () => {
     })
   }
 
+  it('grandfathers the legacy enabled setting onto Remote Config when the source is defaulted', () => {
+    config.experimental.flaggingProvider.enabled = true
+    config.getOrigin.withArgs('experimental.flaggingProvider.enabled').returns('env_var')
+
+    assert.deepStrictEqual(configurationSource.resolve(config), { mode: 'remote_config' })
+    assert.strictEqual(configurationSource.isRemoteConfig(config), true)
+    assert.strictEqual(configurationSource.isEnabled(config), true)
+  })
+
+  it('keeps the provider disabled for the legacy false setting when the source is defaulted', () => {
+    config.experimental.flaggingProvider.enabled = false
+    config.getOrigin.withArgs('experimental.flaggingProvider.enabled').returns('env_var')
+
+    assert.deepStrictEqual(configurationSource.resolve(config), { mode: 'disabled' })
+    assert.strictEqual(configurationSource.isRemoteConfig(config), false)
+    assert.strictEqual(configurationSource.isEnabled(config), false)
+  })
+
+  it('lets an explicit agentless source override legacy enablement', () => {
+    config.experimental.flaggingProvider.enabled = true
+    config.getOrigin.returns('env_var')
+
+    assert.strictEqual(configurationSource.resolve(config).mode, 'agentless')
+    assert.strictEqual(configurationSource.isRemoteConfig(config), false)
+    assert.strictEqual(configurationSource.isEnabled(config), true)
+  })
+
+  it('lets an explicit Remote Config source override legacy disablement', () => {
+    config.DD_FEATURE_FLAGS_CONFIGURATION_SOURCE = 'remote_config'
+    config.experimental.flaggingProvider.enabled = false
+    config.getOrigin.returns('env_var')
+
+    assert.deepStrictEqual(configurationSource.resolve(config), { mode: 'remote_config' })
+    assert.strictEqual(configurationSource.isRemoteConfig(config), true)
+    assert.strictEqual(configurationSource.isEnabled(config), true)
+  })
+
+  it('lets the stable kill switch override every configuration source', () => {
+    config.DD_FEATURE_FLAGS_ENABLED = false
+    config.DD_FEATURE_FLAGS_CONFIGURATION_SOURCE = 'remote_config'
+    config.experimental.flaggingProvider.enabled = true
+    config.getOrigin.returns('env_var')
+
+    assert.deepStrictEqual(configurationSource.resolve(config), { mode: 'disabled' })
+    assert.strictEqual(configurationSource.isRemoteConfig(config), false)
+    assert.strictEqual(configurationSource.isEnabled(config), false)
+  })
+
   it('defaults to the Datadog UFC CDN endpoint and includes the environment', () => {
     config.DD_SITE = 'raw-env-key.invalid'
     const resolved = configurationSource.resolve(config)
diff --git a/packages/dd-trace/test/openfeature/register.spec.js b/packages/dd-trace/test/openfeature/register.spec.js
diff --git a/packages/dd-trace/test/openfeature/remote_config.spec.js b/packages/dd-trace/test/openfeature/remote_config.spec.js
diff --git a/packages/dd-trace/test/proxy.spec.js b/packages/dd-trace/test/proxy.spec.js

Original file line number	Diff line number	Diff line change
`@@ -817,6 +817,13 @@`
`817`	`817`	`"default": "false"`
`818`	`818`	`}`
`819`	`819`	`],`
	`820`	`+ "DD_FEATURE_FLAGS_ENABLED": [`
	`821`	`+ {`
	`822`	`+ "implementation": "A",`
	`823`	`+ "type": "boolean",`
	`824`	`+ "default": "true"`
	`825`	`+ }`
	`826`	`+ ],`
`820`	`827`	`"DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED": [`
`821`	`828`	`{`
`822`	`829`	`"implementation": "A",`
Original file line number	Diff line number	Diff line change
`@@ -47,8 +47,6 @@ function enable (config) {`
`47`	`47`	`setAgentStrategy(config, hasAgent => {`
`48`	`48`	`exposuresWriter?.setEnabled(hasAgent)`
`49`	`49`	`})`
`50`		`-`
`51`		`- log.debug('OpenFeature module enabled')`
`52`	`50`	`}`
`53`	`51`
`54`	`52`	`/**`