feat(openfeature): return a ready provider from the openfeature entrypoint

dd-trace/openfeature previously only existed as a side-effect require for
file tracers (#9324). Turn it into the real public entrypoint: it now
returns a usable FlaggingProvider instance after tracer.init(), and
tracer.openfeature is deprecated in its favor since it doesn't work in
bundled applications.

Extract the base provider class into a factory so it can be constructed
from either the bundler-opaque require-provider wrapper (legacy
tracer.openfeature) or a plain require (the new entrypoint) without
duplicating the class body.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: rochdev

README.md

@@ -93,23 +93,24 @@ Regardless of where you open the issue, someone at Datadog will try to help.
 
 If you would like to trace your bundled application then please read this page on [bundling and dd-trace](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs/#bundling). It includes information on how to use our ESBuild plugin and includes caveats for other bundlers.
 
-When using the experimental OpenFeature provider, file-traced deployments can force the optional provider and
-its dependencies into the output with a side-effect import before accessing `tracer.openfeature`:
+When using the experimental OpenFeature provider in a bundled application, require it through the
+`dd-trace/openfeature` subpath. This subpath uses a plain `require`/`import` for its dependencies, so
+bundlers can resolve and include them at build time. It must be loaded after `tracer.init()`:
 
 CommonJS:
 
 ```js
-require('dd-trace/openfeature')
+const tracer = require('dd-trace').init()
+const openfeatureProvider = require('dd-trace/openfeature')
 ```
 
-ES modules:
+ES modules: initialize the tracer with the `--import` flag (see the [ESM support](#ecmascript-modules-esm-support)
+section above) so it's ready before your application code runs, then import the provider normally:
 
 ```js
-import 'dd-trace/openfeature.js'
+import openfeatureProvider from 'dd-trace/openfeature.js'
 ```
 
-This is a fallback for build tools that do not recognize the provider's optional-require wrapper.
-
 
 ## Security Vulnerabilities
 

index.d.ts

@@ -163,6 +163,7 @@ interface Tracer extends opentracing.Tracer {
    * @env DD_FEATURE_FLAGS_ENABLED
    * @env DD_FEATURE_FLAGS_CONFIGURATION_SOURCE
    * @beta This feature is in preview and not ready for production use
+   * @deprecated Use `require('dd-trace/openfeature')` instead, which also works in bundled applications.
    */
   openfeature: tracer.OpenFeatureProvider;
 

index.d.v5.ts

@@ -163,6 +163,7 @@ interface Tracer extends opentracing.Tracer {
    * @env DD_FEATURE_FLAGS_ENABLED
    * @env DD_FEATURE_FLAGS_CONFIGURATION_SOURCE
    * @beta This feature is in preview and not ready for production use
+   * @deprecated Use `require('dd-trace/openfeature')` instead, which also works in bundled applications.
    */
   openfeature: tracer.OpenFeatureProvider;
 

openfeature.d.ts

@@ -1 +1,11 @@
-export {};
+import tracer = require('.')
+
+/**
+ * OpenFeature provider that integrates with Datadog's feature flagging system.
+ * Must be required after `tracer.init()`.
+ *
+ * @beta This feature is in preview and not ready for production use
+ */
+declare const provider: tracer.OpenFeatureProvider
+
+export = provider

openfeature.js

@@ -1,4 +1,16 @@
 'use strict'
 
-// Static fallback for file tracers that do not recognize the optional-peer wrapper.
-require('@datadog/openfeature-node-server')
+const { DatadogNodeServerProvider } = require('@datadog/openfeature-node-server')
+
+const tracer = require('./packages/dd-trace')
+const createFlaggingProviderClass = require('./packages/dd-trace/src/openfeature/flagging_provider')
+
+const config = tracer._tracer._config
+
+if (!config) {
+  throw new Error('dd-trace/openfeature must be required after tracer.init().')
+}
+
+const FlaggingProvider = createFlaggingProviderClass(DatadogNodeServerProvider)
+
+module.exports = new FlaggingProvider(tracer._tracer, config)

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

@@ -7,57 +7,65 @@ const { EXPOSURE_CHANNEL } = require('./constants/constants')
 const EvalMetricsHook = require('./eval-metrics-hook')
 const SpanEnrichmentHook = require('./span-enrichment-hook')
 
-const { DatadogNodeServerProvider } = require('./require-provider')
-
 /**
- * OpenFeature provider that integrates with Datadog's feature flagging system.
- * Extends DatadogNodeServerProvider to add tracer integration and configuration management.
+ * Builds the OpenFeature provider that integrates with Datadog's feature flagging system.
+ * Takes the base provider class as a parameter so callers can supply it either through the
+ * bundler-opaque `require-provider` wrapper (legacy `tracer.openfeature`) or a plain `require`
+ * (the `dd-trace/openfeature` entrypoint), without duplicating this class.
+ *
+ * @param {typeof import('@datadog/openfeature-node-server').DatadogNodeServerProvider} DatadogNodeServerProvider
+ * @returns {typeof FlaggingProvider}
  */
-class FlaggingProvider extends DatadogNodeServerProvider {
-  /** @type {SpanEnrichmentHook | undefined} */
-  #spanEnrichmentHook
-
-  /** @type {{ start: Function, stop: Function } | undefined} */
-  #configurationSource
-
+module.exports = function createFlaggingProviderClass (DatadogNodeServerProvider) {
   /**
-   * @param {import('../tracer')} tracer - Datadog tracer instance
-   * @param {import('../config/config-base')} config - Tracer configuration object
+   * Extends DatadogNodeServerProvider to add tracer integration and configuration management.
    */
-  constructor (tracer, config) {
-    super({
-      exposureChannel: channel(EXPOSURE_CHANNEL),
-      initializationTimeoutMs: config.experimental.flaggingProvider.initializationTimeoutMs,
-    })
-
-    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 {
-      log.info('%s span enrichment disabled', this.constructor.name)
-    }
+  class FlaggingProvider extends DatadogNodeServerProvider {
+    /** @type {SpanEnrichmentHook | undefined} */
+    #spanEnrichmentHook
 
-    log.debug('%s created with timeout: %dms', this.constructor.name,
-      config.experimental.flaggingProvider.initializationTimeoutMs)
+    /** @type {{ start: Function, stop: Function } | undefined} */
+    #configurationSource
 
-    this.#configurationSource = configurationSource.create(config, this.setConfiguration.bind(this))
-    this.#configurationSource?.start()
-  }
+    /**
+     * @param {import('../tracer')} tracer - Datadog tracer instance
+     * @param {import('../config/config-base')} config - Tracer configuration object
+     */
+    constructor (tracer, config) {
+      super({
+        exposureChannel: channel(EXPOSURE_CHANNEL),
+        initializationTimeoutMs: config.experimental.flaggingProvider.initializationTimeoutMs,
+      })
 
-  /**
-   * Called when the provider is shut down.
-   * Cleans up resources including channel subscriptions.
-   */
-  onClose () {
-    this.#configurationSource?.stop()
-    this.#configurationSource = undefined
-    this.#spanEnrichmentHook?.destroy()
-    this.#spanEnrichmentHook = undefined
+      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 {
+        log.info('%s span enrichment disabled', this.constructor.name)
+      }
+
+      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()
+    }
+
+    /**
+     * Called when the provider is shut down.
+     * Cleans up resources including channel subscriptions.
+     */
+    onClose () {
+      this.#configurationSource?.stop()
+      this.#configurationSource = undefined
+      this.#spanEnrichmentHook?.destroy()
+      this.#spanEnrichmentHook = undefined
+    }
   }
-}
 
-module.exports = FlaggingProvider
+  return FlaggingProvider
+}

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

@@ -10,7 +10,7 @@ registerFeature({
   name: 'openfeature',
   noop,
   factory: () => require('./index'),
-  provider: () => require('./flagging_provider'),
+  provider: () => require('./flagging_provider')(require('./require-provider').DatadogNodeServerProvider),
 
   /** @param {import('../config/config-base')} config */
   isEnabled (config) {

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

@@ -6,7 +6,7 @@ const RemoteConfigCapabilities = require('../remote_config/capabilities')
  * Configures remote config handlers for openfeature feature flagging
  *
  * @param {import('../remote_config')} rc - RemoteConfig instance
- * @param {() => import('./flagging_provider')} getOpenfeatureProxy
+ * @param {() => InstanceType<ReturnType<typeof import('./flagging_provider')>>} getOpenfeatureProxy
  * @param {boolean} subscribe - Whether Agent Remote Config owns UFC delivery
  */
 function enable (rc, getOpenfeatureProxy, subscribe) {

packages/dd-trace/test/openfeature/file-tracing.spec.js

@@ -38,15 +38,34 @@ async function assertTracesProvider (entrypoint) {
 
 describe('OpenFeature file tracing', () => {
   it('traces the provider dependency tree through the runtime wrapper', async () => {
-    await assertTracesProvider(path.join(repoRoot, 'packages/dd-trace/src/openfeature/flagging_provider.js'))
+    await assertTracesProvider(path.join(repoRoot, 'packages/dd-trace/src/openfeature/require-provider.js'))
   })
 
   it('traces the provider dependency tree through the explicit entrypoint', async () => {
     await assertTracesProvider(path.join(repoRoot, 'openfeature.js'))
   })
 
   it('loads the provider through the explicit entrypoint', () => {
-    require(path.join(repoRoot, 'openfeature.js'))
+    const tracerPath = JSON.stringify(path.join(repoRoot, 'packages/dd-trace'))
+    const entrypointPath = JSON.stringify(path.join(repoRoot, 'openfeature.js'))
+    const result = spawnSync(
+      process.execPath,
+      ['--eval', `require(${tracerPath}).init({ plugins: false }); require(${entrypointPath})`],
+      { encoding: 'utf8' }
+    )
+
+    assert.strictEqual(result.status, 0, result.stderr)
+  })
+
+  it('throws a clear error when required before tracer.init()', () => {
+    const result = spawnSync(
+      process.execPath,
+      ['--eval', `require(${JSON.stringify(path.join(repoRoot, 'openfeature.js'))})`],
+      { encoding: 'utf8' }
+    )
+
+    assert.notStrictEqual(result.status, 0)
+    assert.match(result.stderr, /must be required after tracer\.init\(\)/)
   })
 
   it('loads the explicit entrypoint as a CommonJS and ESM package subpath', () => {
@@ -58,14 +77,18 @@ describe('OpenFeature file tracing', () => {
       symlinkSync(repoRoot, path.join(nodeModulesPath, 'dd-trace'), 'junction')
       const commonJsResult = spawnSync(
         process.execPath,
-        ['--eval', "require('dd-trace/openfeature')"],
+        ['--eval', "require('dd-trace').init({ plugins: false }); require('dd-trace/openfeature')"],
         { cwd: fixtureRoot, encoding: 'utf8' }
       )
       assert.strictEqual(commonJsResult.status, 0, commonJsResult.stderr)
 
       const esmResult = spawnSync(
         process.execPath,
-        ['--input-type=module', '--eval', "import 'dd-trace/openfeature.js'"],
+        [
+          '--import', 'dd-trace/initialize.mjs',
+          '--input-type=module',
+          '--eval', "import 'dd-trace/openfeature.js'",
+        ],
         { cwd: fixtureRoot, encoding: 'utf8' }
       )
       assert.strictEqual(esmResult.status, 0, esmResult.stderr)

packages/dd-trace/test/openfeature/flagging_provider.spec.js

@@ -1,9 +1,9 @@
 'use strict'
 
 const assert = require('node:assert/strict')
-const fs = require('node:fs')
 
-const { describe, it, beforeEach, afterEach } = require('mocha')
+const { DatadogNodeServerProvider } = require('@datadog/openfeature-node-server')
+const { describe, it, beforeEach } = require('mocha')
 const sinon = require('sinon')
 const proxyquire = require('proxyquire')
 
@@ -68,7 +68,7 @@ describe('FlaggingProvider', () => {
     }
     mockSpanEnrichmentHookClass = sinon.stub().returns(mockSpanEnrichmentHook)
 
-    FlaggingProvider = proxyquire('../../src/openfeature/flagging_provider', {
+    const createFlaggingProviderClass = proxyquire('../../src/openfeature/flagging_provider', {
       'dc-polyfill': {
         channel: channelStub,
       },
@@ -77,6 +77,7 @@ describe('FlaggingProvider', () => {
       './eval-metrics-hook': mockEvalMetricsHookClass,
       './span-enrichment-hook': mockSpanEnrichmentHookClass,
     })
+    FlaggingProvider = createFlaggingProviderClass(DatadogNodeServerProvider)
   })
 
   describe('constructor', () => {
@@ -208,82 +209,20 @@ describe('FlaggingProvider', () => {
 
   describe('inheritance', () => {
     it('should extend DatadogNodeServerProvider', () => {
-      const { DatadogNodeServerProvider } = require('@datadog/openfeature-node-server')
       const provider = new FlaggingProvider(mockTracer, mockConfig)
 
       assert.ok(provider instanceof DatadogNodeServerProvider)
     })
   })
 
-  // Pins the optional-peer gate against leaking the provider chain into customer bundles (#8635).
-  // `file-tracing.spec.js` covers the same wrapper's nft contract.
-  describe('optional-peer gate', () => {
-    const modulePath = require.resolve('../../src/openfeature/flagging_provider')
-    const providerModulePath = require.resolve('../../src/openfeature/require-provider')
-    const peer = '@datadog/openfeature-node-server'
-
-    afterEach(() => {
-      delete require.cache[modulePath]
-      delete require.cache[providerModulePath]
-      delete globalThis.__webpack_require__
-      delete globalThis.__non_webpack_require__
-    })
-
-    it('uses `require` outside a bundler', () => {
-      assert.strictEqual(typeof globalThis.__webpack_require__, 'undefined')
-      delete require.cache[modulePath]
-      delete require.cache[providerModulePath]
-
-      const ReloadedFlaggingProvider = require(modulePath)
-
-      assert.strictEqual(typeof ReloadedFlaggingProvider, 'function')
-      assert.strictEqual(ReloadedFlaggingProvider.name, 'FlaggingProvider')
-    })
+  describe('factory', () => {
+    it('builds a distinct class per call, extending the given base class', () => {
+      const createFlaggingProviderClass = require('../../src/openfeature/flagging_provider')
 
-    it('uses `__non_webpack_require__`, never `__webpack_require__`, under webpack', () => {
-      const loadCalls = []
-      globalThis.__webpack_require__ = () => {
-        throw new Error('webpack require must not run for an optional peer')
-      }
-      /** @param {string} request */
-      globalThis.__non_webpack_require__ = (request) => {
-        loadCalls.push(request)
-        return require(request)
-      }
-
-      delete require.cache[modulePath]
-      delete require.cache[providerModulePath]
-      const ReloadedFlaggingProvider = require(modulePath)
-
-      assert.deepStrictEqual(loadCalls, [peer])
-      assert.strictEqual(typeof ReloadedFlaggingProvider, 'function')
-    })
-
-    it('falls back to `require` when `__non_webpack_require__` is absent', () => {
-      globalThis.__webpack_require__ = () => {
-        throw new Error('webpack require must not run for an optional peer')
-      }
-
-      delete require.cache[modulePath]
-      delete require.cache[providerModulePath]
-      const ReloadedFlaggingProvider = require(modulePath)
-
-      assert.strictEqual(typeof ReloadedFlaggingProvider, 'function')
-    })
+      const OtherFlaggingProvider = createFlaggingProviderClass(DatadogNodeServerProvider)
 
-    it('keeps the provider load opaque to bundlers', () => {
-      const source = fs.readFileSync(providerModulePath, 'utf8')
-
-      assert.doesNotMatch(
-        source,
-        /require\(\s*['"]@datadog\/openfeature-node-server['"]\s*\)/,
-        'a literal require would let bundlers resolve the optional peer chain at build time'
-      )
-      assert.doesNotMatch(
-        source,
-        /\brequire\(\s*[^'"\s]/,
-        'a dynamic require would create a webpack expression dependency'
-      )
+      assert.notStrictEqual(OtherFlaggingProvider, FlaggingProvider)
+      assert.strictEqual(OtherFlaggingProvider.name, 'FlaggingProvider')
     })
   })
 })