dd-trace 5.109.0 → 5.111.0

package/packages/datadog-plugin-vitest/src/index.js

@@ -9,6 +9,7 @@ const {
   finishAllTraceSpans,
   getTestSuitePath,
   getTestSuiteCommonTags,
+  getTestLevelsMetadataTags,
   getTestSessionName,
   getIsFaultyEarlyFlakeDetection,
   TEST_SOURCE_FILE,
@@ -16,6 +17,7 @@ const {
   TEST_CODE_COVERAGE_LINES_PCT,
   TEST_CODE_OWNERS,
   TEST_COMMAND,
+  TEST_LEVELS_METADATA,
   TEST_SESSION_NAME,
   TEST_SOURCE_START,
   TEST_IS_NEW,
@@ -28,12 +30,12 @@ const {
   TEST_MANAGEMENT_IS_ATTEMPT_TO_FIX,
   TEST_MANAGEMENT_ATTEMPT_TO_FIX_PASSED,
   TEST_HAS_FAILED_ALL_RETRIES,
-  getLibraryCapabilitiesTags,
+  getLibraryCapabilitiesTags: getDefaultLibraryCapabilitiesTags,
   TEST_RETRY_REASON_TYPES,
-  isModifiedTest,
   TEST_IS_MODIFIED,
   TEST_HAS_DYNAMIC_NAME,
   TEST_FINAL_STATUS,
+  TEST_IS_TEST_FRAMEWORK_WORKER,
 } = require('../../dd-trace/src/plugins/util/test')
 const { COMPONENT } = require('../../dd-trace/src/constants')
 const {
@@ -68,49 +70,6 @@ class VitestPlugin extends CiPlugin {
       })
     })
 
-    this.addSub('ci:vitest:test:is-new', ({ knownTests, testSuiteAbsolutePath, testName, onDone }) => {
-      // if for whatever reason the worker does not receive valid known tests, we don't consider it as new
-      if (!knownTests.vitest) {
-        return onDone(false)
-      }
-      const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const testsForThisTestSuite = knownTests.vitest[testSuite] || []
-      onDone(!testsForThisTestSuite.includes(testName))
-    })
-
-    this.addSub('ci:vitest:test:is-attempt-to-fix', ({
-      testManagementTests,
-      testSuiteAbsolutePath,
-      testName,
-      onDone,
-    }) => {
-      const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const { isAttemptToFix } = this.getTestProperties(testManagementTests, testSuite, testName)
-
-      onDone(isAttemptToFix ?? false)
-    })
-
-    this.addSub('ci:vitest:test:is-disabled', ({ testManagementTests, testSuiteAbsolutePath, testName, onDone }) => {
-      const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const { isDisabled } = this.getTestProperties(testManagementTests, testSuite, testName)
-
-      onDone(isDisabled)
-    })
-
-    this.addSub('ci:vitest:test:is-quarantined', ({ testManagementTests, testSuiteAbsolutePath, testName, onDone }) => {
-      const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const { isQuarantined } = this.getTestProperties(testManagementTests, testSuite, testName)
-
-      onDone(isQuarantined)
-    })
-
-    this.addSub('ci:vitest:test:is-modified', ({ modifiedFiles, testSuiteAbsolutePath, onDone }) => {
-      const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const isModified = isModifiedTest(testSuite, 0, 0, modifiedFiles, this.constructor.id)
-
-      onDone(isModified)
-    })
-
     this.addSub('ci:vitest:is-early-flake-detection-faulty', ({
       knownTests,
       testFilepaths,
@@ -139,12 +98,16 @@ class VitestPlugin extends CiPlugin {
         isRetryReasonAttemptToFix,
         isRetryReasonAtr,
         isModified,
+        isTestFrameworkWorker,
+        requestErrorTags,
       } = ctx
 
       const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
-      const store = storage('legacy').getStore()
+      const store = ctx.currentStore || storage('legacy').getStore()
+      const testSuiteSpan = store?.testSuiteSpan || this.testSuiteSpan
 
       const extraTags = {
+        ...requestErrorTags,
         [TEST_SOURCE_FILE]: testSuite,
       }
       if (isRetry) {
@@ -177,11 +140,14 @@ class VitestPlugin extends CiPlugin {
       if (isModified) {
         extraTags[TEST_IS_MODIFIED] = 'true'
       }
+      if (isTestFrameworkWorker) {
+        extraTags[TEST_IS_TEST_FRAMEWORK_WORKER] = 'true'
+      }
 
       const span = this.startTestSpan(
         testName,
         testSuite,
-        this.testSuiteSpan,
+        testSuiteSpan,
         extraTags
       )
 
@@ -202,7 +168,7 @@ class VitestPlugin extends CiPlugin {
     })
 
     this.addBind('ci:vitest:test:finish-time', (ctx) => {
-      const { status, task, attemptToFixPassed, attemptToFixFailed } = ctx
+      const { status, task, attemptToFixPassed, attemptToFixFailed, duration } = ctx
       const span = ctx.currentStore?.span
 
       // we store the finish time to finish at a later hook
@@ -216,7 +182,8 @@ class VitestPlugin extends CiPlugin {
           span.setTag(TEST_MANAGEMENT_ATTEMPT_TO_FIX_PASSED, 'false')
         }
 
-        this.taskToFinishTime.set(task, span._getTime())
+        const finishTime = typeof duration === 'number' ? span._startTime + duration : span._getTime()
+        this.taskToFinishTime.set(task, finishTime)
 
         ctx.parentStore = ctx.currentStore
         ctx.currentStore = { ...ctx.currentStore, span }
@@ -289,19 +256,29 @@ class VitestPlugin extends CiPlugin {
       finishAllTraceSpans(span)
     })
 
-    this.addSub('ci:vitest:test:skip', ({ testName, testSuiteAbsolutePath, isNew, isDisabled }) => {
+    this.addSub('ci:vitest:test:skip', ({
+      testName,
+      testSuiteAbsolutePath,
+      isNew,
+      isDisabled,
+      isTestFrameworkWorker,
+      requestErrorTags,
+      testSuiteSpan,
+    }) => {
       const testSuite = getTestSuitePath(testSuiteAbsolutePath, this.repositoryRoot)
       const testSpan = this.startTestSpan(
         testName,
         testSuite,
-        this.testSuiteSpan,
+        testSuiteSpan || this.testSuiteSpan,
         {
+          ...requestErrorTags,
           [TEST_SOURCE_FILE]: testSuite,
           [TEST_SOURCE_START]: 1, // we can't get the proper start line in vitest
           [TEST_STATUS]: 'skip',
           [TEST_FINAL_STATUS]: 'skip',
           ...(isDisabled ? { [TEST_MANAGEMENT_IS_DISABLED]: 'true' } : {}),
           ...(isNew ? { [TEST_IS_NEW]: 'true' } : {}),
+          ...(isTestFrameworkWorker ? { [TEST_IS_TEST_FRAMEWORK_WORKER]: 'true' } : {}),
         }
       )
       this.telemetry.ciVisEvent(TELEMETRY_EVENT_FINISHED, 'test', this.getTestTelemetryTags(testSpan))
@@ -309,7 +286,15 @@ class VitestPlugin extends CiPlugin {
     })
 
     this.addBind('ci:vitest:test-suite:start', (ctx) => {
-      const { codeOwnersEntries, repositoryRoot, testSuiteAbsolutePath, frameworkVersion } = ctx
+      const {
+        codeOwnersEntries,
+        repositoryRoot,
+        requestErrorTags,
+        testSuiteAbsolutePath,
+        frameworkVersion,
+        isTestFrameworkWorker,
+        isVitestNoWorkerInitActive,
+      } = ctx
 
       const testCommand = ctx.testCommand || 'vitest run'
       const { testSessionId, testModuleId } = ctx
@@ -327,9 +312,16 @@ class VitestPlugin extends CiPlugin {
       // test suites run in a different process, so they also need to init the metadata dictionary
       const testSessionName = getTestSessionName(this.config, trimmedCommand, this.testEnvironmentMetadata)
       if (this.tracer._exporter.addMetadataTags) {
+        const libraryCapabilitiesTags = this.getLibraryCapabilitiesTags(frameworkVersion, {
+          isVitestNoWorkerInitActive,
+        })
         this.tracer._exporter.addMetadataTags({
-          '*': { [TEST_COMMAND]: testCommand, [TEST_SESSION_NAME]: testSessionName },
-          test: getLibraryCapabilitiesTags(this.constructor.id),
+          [TEST_LEVELS_METADATA]: {
+            [TEST_COMMAND]: testCommand,
+            [TEST_SESSION_NAME]: testSessionName,
+            ...getTestLevelsMetadataTags(this.testEnvironmentMetadata),
+          },
+          test: libraryCapabilitiesTags,
         })
       }
 
@@ -342,9 +334,13 @@ class VitestPlugin extends CiPlugin {
           testSuite,
           'vitest'
         ),
+        ...requestErrorTags,
         [TEST_SOURCE_FILE]: testSuite,
         [TEST_SOURCE_START]: 1,
       }
+      if (isTestFrameworkWorker) {
+        testSuiteMetadata[TEST_IS_TEST_FRAMEWORK_WORKER] = 'true'
+      }
 
       const codeOwners = this.getCodeOwners(testSuiteMetadata)
       if (codeOwners) {
@@ -368,13 +364,17 @@ class VitestPlugin extends CiPlugin {
       return ctx.currentStore
     })
 
-    this.addSub('ci:vitest:test-suite:finish', ({ testSuiteSpan, status, onFinish }) => {
+    this.addSub('ci:vitest:test-suite:finish', ({ testSuiteSpan, status, deferFlush, onFinish }) => {
       if (testSuiteSpan) {
         testSuiteSpan.setTag(TEST_STATUS, status)
         testSuiteSpan.finish()
         finishAllTraceSpans(testSuiteSpan)
       }
       this.telemetry.ciVisEvent(TELEMETRY_EVENT_FINISHED, 'suite')
+      if (deferFlush) {
+        onFinish()
+        return
+      }
       this.tracer._exporter.flush(onFinish)
       if (this.runningTestProbe) {
         this.removeDiProbe(this.runningTestProbe)
@@ -403,9 +403,15 @@ class VitestPlugin extends CiPlugin {
       isEarlyFlakeDetectionEnabled,
       isEarlyFlakeDetectionFaulty,
       isTestManagementTestsEnabled,
+      requestErrorTags,
       vitestPool,
+      isVitestNoWorkerInitActive,
       onFinish,
     }) => {
+      for (const [tag, value] of Object.entries(requestErrorTags || {})) {
+        this.testSessionSpan.setTag(tag, value)
+        this.testModuleSpan.setTag(tag, value)
+      }
       this.testSessionSpan.setTag(TEST_STATUS, status)
       this.testModuleSpan.setTag(TEST_STATUS, status)
       if (error) {
@@ -432,12 +438,12 @@ class VitestPlugin extends CiPlugin {
       this.telemetry.ciVisEvent(TELEMETRY_EVENT_FINISHED, 'module')
       this.testSessionSpan.finish()
       this.telemetry.ciVisEvent(TELEMETRY_EVENT_FINISHED, 'session', {
-        hasFailedTestReplay: this.libraryConfig?.isDiEnabled || undefined,
+        hasFailedTestReplay: this.libraryConfig?.isDiEnabled && !isVitestNoWorkerInitActive ? true : undefined,
       })
       finishAllTraceSpans(this.testSessionSpan)
       this.telemetry.count(TELEMETRY_TEST_SESSION, {
         provider: this.ciProviderName,
-        autoInjected: !!this._tracerConfig.DD_CIVISIBILITY_AUTO_INSTRUMENTATION_PROVIDER,
+        autoInjected: !!this._tracerConfig.testOptimization.DD_CIVISIBILITY_AUTO_INSTRUMENTATION_PROVIDER,
       })
       this.tracer._exporter.flush(onFinish)
     })
@@ -447,6 +453,19 @@ class VitestPlugin extends CiPlugin {
     })
   }
 
+  /**
+   * Returns Vitest library capability metadata tags.
+   * @param {string} frameworkVersion - The Vitest version.
+   * @param {object} [ctx] - Diagnostic channel context.
+   * @param {boolean} [ctx.isVitestNoWorkerInitActive] - Whether no-worker init is active for this run.
+   * @returns {Record<string, string|undefined>}
+   */
+  getLibraryCapabilitiesTags (frameworkVersion, ctx = {}) {
+    return getDefaultLibraryCapabilitiesTags(this.constructor.id, frameworkVersion, {
+      omitFailedTestReplay: ctx.isVitestNoWorkerInitActive,
+    })
+  }
+
   /**
    * Handles the coverage report by discovering and uploading it if enabled.
    * @param {string} rootDir - The root directory where coverage reports are located.
@@ -463,13 +482,6 @@ class VitestPlugin extends CiPlugin {
       onDone,
     })
   }
-
-  getTestProperties (testManagementTests, testSuite, testName) {
-    const { attempt_to_fix: isAttemptToFix, disabled: isDisabled, quarantined: isQuarantined } =
-      testManagementTests?.vitest?.suites?.[testSuite]?.tests?.[testName]?.properties || {}
-
-    return { isAttemptToFix, isDisabled, isQuarantined }
-  }
 }
 
 module.exports = VitestPlugin

package/packages/datadog-shimmer/src/shimmer.js

@@ -119,11 +119,14 @@ function wrapCallback (original, wrapper) {
  * object.
  * @param {string | symbol} name - The property key of the method to wrap.
  * @param {(original: Function) => (...args: unknown[]) => unknown} wrapper - The wrapper function.
- * @param {{ replaceGetter?: boolean }} [options] - If `replaceGetter` is set to
- * true, the getter is accessed and the getter is replaced with one that just
- * returns the earlier retrieved value. Use with care! This may only be done in
- * case the getter absolutely has no side effect and no setter is defined for the
- * property.
+ * @param {{ replaceGetter?: boolean }} [options] - By default the getter is
+ * wrapped in place, so each property access runs the wrapper. A getter+setter
+ * pair keeps its setter; a setter-only property throws. If `replaceGetter` is
+ * true, the getter is instead accessed once and replaced with one returning the
+ * resolved wrapped value — for a lazy getter+setter pair (e.g. Node 20's
+ * `fs.opendir`) the setter is rebuilt to materialize a writable data property on
+ * assignment, keeping the descriptor observationally identical for downstream
+ * consumers. Use with care! This may only be done when the getter has no side effect.
  * @returns {Record<string | symbol, unknown> | Function | undefined} The target object with
  * the wrapped method.
  */
@@ -151,17 +154,13 @@ function wrap (target, name, wrapper, options) {
     enumerable: false,
   }
 
-  if (descriptor.set && (!descriptor.get || options?.replaceGetter)) {
-    // It is possible to support these cases by instrumenting both the getter
-    // and setter (or only the setter, in case that is a use case).
-    // For now, this is not supported due to the complexity and the fact that
-    // this is not a common use case.
-    throw new Error(options?.replaceGetter
-      ? 'Replacing a getter/setter pair is not supported. Implement if required.'
-      : 'Replacing setters is not supported. Implement if required.')
+  // A setter-only property has nothing to wrap. Instrumenting the setter is not
+  // implemented; a getter+setter pair is handled below.
+  if (descriptor.set && !descriptor.get) {
+    throw new Error('Replacing setters is not supported. Implement if required.')
   }
 
-  const original = descriptor.value ?? options?.replaceGetter ? target[name] : descriptor.get
+  const original = (descriptor.value ?? options?.replaceGetter) ? target[name] : descriptor.get
 
   assertMethod(target, name, original)
 
@@ -176,8 +175,30 @@ function wrap (target, name, wrapper, options) {
     }
     descriptor.value = wrapped
   } else {
-    if (descriptor.get) {
-      // `replaceGetter` may only be used when the getter has no side effect.
+    if (descriptor.set && options?.replaceGetter) {
+      // A lazy accessor pair (e.g. Node 20's `fs.opendir`). `original` already
+      // resolved the value through the getter. Keep the property an accessor pair
+      // so the shape stays observationally identical — a downstream consumer may
+      // read the descriptor or assign to it on a specific Node.js version. The
+      // getter returns the wrapped value; the setter mirrors the native lazy
+      // contract (assignment self-replaces the property with a writable data
+      // property holding the assigned value), so a caller that overwrites the
+      // method gets exactly what they set, unwrapped, as before. The descriptor
+      // is the original accessor descriptor (no `value`/`writable` slots), so
+      // reassigning `get`/`set` keeps it a valid accessor descriptor.
+      descriptor.get = () => wrapped
+      descriptor.set = function (value) {
+        Object.defineProperty(this, name, {
+          configurable: descriptor.configurable,
+          enumerable: descriptor.enumerable,
+          writable: true,
+          value,
+        })
+      }
+    } else if (descriptor.get) {
+      // Wrap the getter in place; for a getter+setter pair the original setter
+      // stays untouched. `replaceGetter` (no side effect on read) instead returns
+      // the value resolved once into `wrapped`.
       descriptor.get = options?.replaceGetter ? () => wrapped : wrapped
     } else {
       descriptor.value = wrapped

package/packages/datadog-webpack/index.js

@@ -6,6 +6,7 @@ const fs = require('node:fs')
 const instrumentations = require('../datadog-instrumentations/src/helpers/instrumentations')
 const extractPackageAndModulePath = require('../datadog-instrumentations/src/helpers/extract-package-and-module-path')
 const hooks = require('../datadog-instrumentations/src/helpers/hooks')
+const { matchesOptionalPeerFile } = require('../datadog-instrumentations/src/helpers/optional-peer-bundler')
 const { isESMFile } = require('../datadog-esbuild/src/utils')
 const log = require('./src/log')
 
@@ -130,11 +131,26 @@ class DatadogWebpackPlugin {
       nmf.hooks.afterResolve.tap(PLUGIN_NAME, (resolveData) => {
         const { createData } = resolveData
         const resource = createData?.resource
-        if (!resource || !resource.includes('node_modules')) {
+        if (!resource) {
           return
         }
 
         const normalizedResource = resource.replaceAll('\\', '/')
+
+        // Rewrite optional-peer loads so installed peers get bundled and survive relocation
+        // (#8980); absent peers stay opaque, so a build that does not opt into the feature does
+        // not follow their dependency chain (#8635).
+        if (matchesOptionalPeerFile(normalizedResource)) {
+          createData.loaders = createData.loaders || []
+          createData.loaders.push({ loader: require.resolve('./src/optional-peer-loader') })
+          log.debug('INLINE: optional-peer loader applied to %s', normalizedResource)
+          return
+        }
+
+        if (!resource.includes('node_modules')) {
+          return
+        }
+
         const { pkg, path: modulePath, pkgJson } = extractPackageAndModulePath(normalizedResource)
         if (!pkg) {
           return

package/packages/datadog-webpack/src/optional-peer-loader.js

@@ -0,0 +1,17 @@
+'use strict'
+
+const { rewriteOptionalPeerLoads } = require('../../datadog-instrumentations/src/helpers/optional-peer-bundler')
+
+/**
+ * Webpack loader applied to the optional-peer loader files. Rewrites each
+ * `requireOptionalPeer('name')` whose peer is installed at build time into a literal
+ * `require('name')` so webpack bundles the peer (#8980). Peers that are absent stay opaque, so
+ * builds that do not opt into the feature keep the #8635 guarantee.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+module.exports = function optionalPeerLoader (source) {
+  this.cacheable(false)
+  return rewriteOptionalPeerLoads(source, this.context)
+}

package/packages/dd-trace/src/aiguard/sdk.js

@@ -63,6 +63,18 @@ class AIGuardClientError extends Error {
   }
 }
 
+/**
+ * Resolves the AI Guard host for a given Datadog site. Sites with a single subdomain level
+ * (e.g. `datadoghq.com`, `ddog-gov.com`) are served from the `app.` subdomain, while regional
+ * sites (e.g. `us3.datadoghq.com`, `ap1.datadoghq.com`) are used as-is.
+ *
+ * @param {string} site - Datadog site (e.g. `datadoghq.com`, `us3.datadoghq.com`)
+ * @returns {string} The host to use for the AI Guard endpoint
+ */
+function aiGuardHost (site) {
+  return site.split('.').length === 2 ? `app.${site}` : site
+}
+
 class AIGuard extends NoopAIGuard {
   #initialized
   #tracer
@@ -81,20 +93,20 @@ class AIGuard extends NoopAIGuard {
   constructor (tracer, config) {
     super()
 
-    if (!config.apiKey || !config.DD_APP_KEY) {
+    if (!config.DD_API_KEY || !config.DD_APP_KEY) {
       log.error('AIGuard: missing api and/or app keys, use env DD_API_KEY and DD_APP_KEY')
       this.#initialized = false
       return
     }
     this.#tracer = tracer
     this.#headers = {
-      'DD-API-KEY': config.apiKey,
+      'DD-API-KEY': config.DD_API_KEY,
       'DD-APPLICATION-KEY': config.DD_APP_KEY,
       'DD-AI-GUARD-VERSION': tracerVersion,
       'DD-AI-GUARD-SOURCE': 'SDK',
       'DD-AI-GUARD-LANGUAGE': 'nodejs',
     }
-    const endpoint = config.experimental.aiguard.endpoint || `https://app.${config.site}/api/v2/ai-guard`
+    const endpoint = config.experimental.aiguard.endpoint || `https://${aiGuardHost(config.site)}/api/v2/ai-guard`
     this.#evaluateUrl = `${endpoint}/evaluate`
     this.#timeout = config.experimental.aiguard.timeout
     this.#maxMessagesLength = config.experimental.aiguard.maxMessagesLength

package/packages/dd-trace/src/appsec/api_security/index.js

@@ -0,0 +1,55 @@
+'use strict'
+
+const web = require('../../plugins/util/web')
+const { isSchemaAttribute } = require('../reporter')
+const appsecTelemetry = require('../telemetry')
+const sampler = require('./sampler')
+
+/**
+ * Map a sampling decision into the corresponding API Security telemetry metric.
+ *
+ * The decision is done by the sampler, here the outcome is translated to emitted metrics:
+ *   - SAMPLE: request.schema / request.no_schema depending on WAF schema attributes
+ *   - MISSING_ROUTE: missing_route
+ *   - SKIP: no metric emitted
+ *
+ * @param {import('http').IncomingMessage} req
+ * @param {'sample' | 'missing_route' | 'skip'} samplingDecision Sampler decision
+ * @param {{ attributes?: Record<string, unknown> } | undefined} wafResult WAF run result
+ */
+function reportRequest (req, samplingDecision, wafResult) {
+  switch (samplingDecision) {
+    case sampler.SamplingDecision.SAMPLE: {
+      const framework = getFramework(req)
+      if (hasSchemaAttributes(wafResult?.attributes)) {
+        appsecTelemetry.incrementApiSecRequestSchemaMetric(framework)
+      } else {
+        appsecTelemetry.incrementApiSecRequestNoSchemaMetric(framework)
+      }
+      break
+    }
+    case sampler.SamplingDecision.MISSING_ROUTE:
+      appsecTelemetry.incrementApiSecMissingRouteMetric(getFramework(req))
+      break
+  }
+}
+
+function getFramework (req) {
+  return web.root(req)?.context()?.getTag?.('component')
+}
+
+function hasSchemaAttributes (attributes) {
+  if (!attributes) return false
+  for (const key of Object.keys(attributes)) {
+    if (isSchemaAttribute(key)) return true
+  }
+  return false
+}
+
+module.exports = {
+  configure: sampler.configure,
+  disable: sampler.disable,
+  sampleRequest: sampler.sampleRequest,
+  reportRequest,
+  SamplingDecision: sampler.SamplingDecision,
+}

package/packages/dd-trace/src/appsec/api_security/sampler.js

@@ -0,0 +1,147 @@
+'use strict'
+
+const { TTLCache } = require('../../../../../vendor/dist/@isaacs/ttlcache')
+const web = require('../../plugins/util/web')
+const log = require('../../log')
+const { AUTO_REJECT, USER_REJECT } = require('../../../../../ext/priority')
+const { keepTrace } = require('../../priority_sampler')
+const { ASM } = require('../../standalone/product')
+const { isBlocked } = require('../blocking')
+
+const MAX_SIZE = 4096
+
+const SamplingDecision = Object.freeze({
+  SAMPLE: 'sample',
+  MISSING_ROUTE: 'missing_route',
+  SKIP: 'skip',
+})
+
+let enabled
+let asmStandaloneEnabled
+
+/**
+ * @type {TTLCache}
+ */
+let sampledRequests
+
+class NoopTTLCache {
+  clear () {}
+  set (_key, _value) {}
+  has (_key) { return false }
+}
+
+function configure ({ appsec, apmTracingEnabled }) {
+  enabled = appsec.DD_API_SECURITY_ENABLED
+  asmStandaloneEnabled = apmTracingEnabled === false
+  sampledRequests = appsec.DD_API_SECURITY_SAMPLE_DELAY === 0
+    ? new NoopTTLCache()
+    : new TTLCache({ max: MAX_SIZE, ttl: appsec.DD_API_SECURITY_SAMPLE_DELAY * 1000 })
+}
+
+function disable () {
+  enabled = false
+  sampledRequests?.clear()
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {boolean} record When true and the decision is SAMPLE, records the endpoint in the TTL cache
+ * @returns {'sample' | 'missing_route' | 'skip'}
+ */
+function sampleRequest (req, res, record = false) {
+  if (!enabled) return SamplingDecision.SKIP
+
+  const rootSpan = web.root(req)
+  if (!rootSpan) return SamplingDecision.SKIP
+
+  if (!asmStandaloneEnabled) {
+    let priority = getSpanPriority(rootSpan)
+    if (!priority) {
+      rootSpan._prioritySampler?.sample(rootSpan)
+      priority = getSpanPriority(rootSpan)
+    }
+
+    if (priority === AUTO_REJECT || priority === USER_REJECT) {
+      return SamplingDecision.SKIP
+    }
+  }
+
+  const resolved = resolveSamplingKey(req, res)
+  if (!resolved) return SamplingDecision.SKIP
+
+  if (record && resolved.route === null) {
+    if (resolved.status === 404 || isBlocked(res)) return SamplingDecision.SKIP
+    return SamplingDecision.MISSING_ROUTE
+  }
+
+  if (sampledRequests.has(resolved.key)) return SamplingDecision.SKIP
+
+  if (asmStandaloneEnabled) {
+    keepTrace(rootSpan, ASM)
+  }
+
+  if (record) {
+    sampledRequests.set(resolved.key, undefined)
+  }
+
+  return SamplingDecision.SAMPLE
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @returns {boolean} Whether this request's endpoint is currently recorded in the TTL cache.
+ */
+function wasSampled (req, res) {
+  const resolved = resolveSamplingKey(req, res)
+  return resolved !== null && sampledRequests.has(resolved.key)
+}
+
+function resolveSamplingKey (req, res) {
+  const method = req.method
+  const status = res.statusCode
+
+  if (!method || !status) {
+    log.warn('[ASM] Unsupported groupkey for API security')
+    return null
+  }
+
+  const context = web.getContext(req)
+  const route = getRouteOrEndpoint(context, status)
+
+  // route === null signals "no route information at all". An empty string is still a valid
+  // route (dd-trace-js represents the express root path '/' as an empty path segment).
+  return { method, status, route, key: method + (route ?? '') + status }
+}
+
+function getRouteOrEndpoint (context, statusCode) {
+  // The router plugin populates `context.paths` whenever the framework matched something.
+  // For express's root '/' route the matched path is normalized to '' (see datadog-plugin-router),
+  // so `paths.length > 0` is the signal that the framework provided route information — even when
+  // the joined string is empty. An empty `paths` array means no router involvement at all.
+  const paths = context?.paths
+  if (paths !== undefined && paths.length > 0) {
+    return paths.join('')
+  }
+
+  if (statusCode === 404) return null
+
+  const endpoint = context?.span?.context()?.getTag?.('http.endpoint')
+  if (endpoint) return endpoint
+
+  return null
+}
+
+function getSpanPriority (span) {
+  const spanContext = span.context?.()
+  return spanContext._sampling?.priority
+}
+
+module.exports = {
+  configure,
+  disable,
+  sampleRequest,
+  wasSampled,
+  SamplingDecision,
+}