fix(openfeature): support file-traced optional provider loading (#9324)

Next.js standalone builds using pnpm omitted the OpenFeature provider because the shared optional-peer wrapper was invisible to nft, leaving tracer.openfeature as the no-op provider at runtime. Keep the bundler escape hatch while exposing a file-traceable fallback entrypoint for tools that cannot recognize the wrapper.
Also document CommonJS and ESM entrypoints.

Fixes: #8635

Author: BridgeAR

README.md

@@ -93,6 +93,23 @@ 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`:
+
+CommonJS:
+
+```js
+require('dd-trace/openfeature')
+```
+
+ES modules:
+
+```js
+import 'dd-trace/openfeature.js'
+```
+
+This is a fallback for build tools that do not recognize the provider's optional-require wrapper.
+
 
 ## Security Vulnerabilities
 

openfeature.d.ts

@@ -0,0 +1 @@
+export {};

openfeature.js

@@ -0,0 +1,4 @@
+'use strict'
+
+// Static fallback for file tracers that do not recognize the optional-peer wrapper.
+require('@datadog/openfeature-node-server')

package.json

@@ -153,6 +153,8 @@
     "LICENSE.Apache",
     "LICENSE.BSD3",
     "loader-hook.mjs",
+    "openfeature.d.ts",
+    "openfeature.js",
     "packages/*/index.js",
     "packages/*/index.electron.js",
     "packages/*/lib/**/*",
@@ -196,6 +198,7 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^18.19.106",
     "@types/sinon": "^22.0.0",
+    "@vercel/nft": "^0.29.4",
     "axios": "^1.18.1",
     "benchmark": "^2.1.4",
     "body-parser": "^2.3.0",

packages/datadog-esbuild/test/plugin.spec.js

@@ -11,17 +11,17 @@ function captureOptionalPeerOnLoad () {
     initialOptions: {},
     onResolve () {},
     onLoad (options, callback) {
-      if (options.filter.source.includes('flagging_provider')) onLoad = callback
+      if (options.filter.source.includes('require-provider')) onLoad = callback
     },
   })
   return onLoad
 }
 
 describe('datadog-esbuild plugin', () => {
   describe('optional peer bundling', () => {
-    it('rewrites the installed peer load in flagging_provider into a literal require', () => {
+    it('rewrites the installed peer load in require-provider into a literal require', () => {
       const onLoad = captureOptionalPeerOnLoad()
-      const providerPath = require.resolve('../../dd-trace/src/openfeature/flagging_provider')
+      const providerPath = require.resolve('../../dd-trace/src/openfeature/require-provider')
 
       const result = onLoad({ path: providerPath })
 
@@ -35,7 +35,7 @@ describe('datadog-esbuild plugin', () => {
     it('ignores files that match the filter but are not an optional-peer file', () => {
       const onLoad = captureOptionalPeerOnLoad()
 
-      assert.strictEqual(onLoad({ path: '/somewhere/else/flagging_provider.js' }), undefined)
+      assert.strictEqual(onLoad({ path: '/somewhere/else/require-provider.js' }), undefined)
     })
   })
 })

packages/datadog-instrumentations/src/helpers/optional-peer-bundler.js

@@ -4,19 +4,19 @@ const path = require('node:path')
 
 // Build-time half of the optional-peer mechanism shared by the webpack and esbuild plugins.
 //
-// Runtime files load an optional peer through `requireOptionalPeer('name')` (see
-// `require-optional-peer.js`), which bundlers cannot follow, so a build that does not opt into
-// the feature never pulls in the peer's (possibly optional) dependency chain (#8635). When the
-// peer is installed at build time the user has opted in, so the plugins rewrite the call into a
-// literal `require('name')` and let the bundler inline the peer, which keeps it working after
-// the bundle is relocated to a tree without the peer on disk (#8980). Peers that are absent at
-// build time stay opaque, so the rewrite is a no-op and the #8635 guarantee holds.
+// Runtime files load an optional peer through a local `requireOptionalPeer('name')` wrapper.
+// File tracers recognize its bound-require shape, while bundlers cannot follow the dynamic
+// argument, so a build that does not opt into the feature never pulls in the peer's dependency
+// chain (#8635). When the peer is installed at build time the user has opted in, so the plugins
+// rewrite the call into a literal `require('name')` and let the bundler inline the peer, which
+// keeps it working after the bundle is relocated without the peer on disk (#8980). Peers that
+// are absent at build time stay opaque, so the rewrite is a no-op and the #8635 guarantee holds.
 
 // Files that load an optional peer this way, as suffixes of the resolved module path. The same
 // suffix matches the repo layout and `node_modules/dd-trace`. Add a file here to extend the
 // mechanism to a new optional peer; no plugin change is needed.
 const OPTIONAL_PEER_FILES = [
-  'packages/dd-trace/src/openfeature/flagging_provider.js',
+  'packages/dd-trace/src/openfeature/require-provider.js',
 ]
 
 // Captures the peer name from `requireOptionalPeer('name')` / `requireOptionalPeer("name")`.

packages/datadog-instrumentations/src/helpers/require-optional-peer.js

@@ -39,7 +39,7 @@ describe('optional-peer-bundler', () => {
   describe('matchesOptionalPeerFile', () => {
     it('matches a registered optional-peer file suffix', () => {
       assert.strictEqual(
-        matchesOptionalPeerFile('/app/node_modules/dd-trace/packages/dd-trace/src/openfeature/flagging_provider.js'),
+        matchesOptionalPeerFile('/app/node_modules/dd-trace/packages/dd-trace/src/openfeature/require-provider.js'),
         true
       )
     })

packages/datadog-instrumentations/test/helpers/optional-peer-bundler.spec.js

@@ -68,8 +68,8 @@ describe('DatadogWebpackPlugin', () => {
       return afterResolve
     }
 
-    it('applies the optional-peer loader to flagging_provider', () => {
-      const createData = { resource: require.resolve('../../dd-trace/src/openfeature/flagging_provider') }
+    it('applies the optional-peer loader to require-provider', () => {
+      const createData = { resource: require.resolve('../../dd-trace/src/openfeature/require-provider') }
 
       captureAfterResolve()({ createData })