dd-trace 6.9.0 → 6.11.0

package/packages/datadog-instrumentations/src/mocha/utils.js

@@ -11,6 +11,7 @@ const {
 const {
   getTestSuitePath,
   DYNAMIC_NAME_RE,
+  getFailedTestReplayPromise,
   recordTestManagementExecution,
   recordAttemptToFixExecution,
   logAttemptToFixTestExecution,
@@ -34,9 +35,13 @@ const testSuiteErrorCh = channel('ci:mocha:test-suite:error')
 /** @typedef {{ length: number, [index: number]: unknown } & Iterable<unknown>} ArgumentsLike */
 
 const testToContext = new WeakMap()
+const originalEfdFns = new WeakMap()
 const originalFns = new WeakMap()
+const originalPendingByTest = new WeakMap()
+const originalRetriesByTest = new WeakMap()
 const testToStartLine = new WeakMap()
 const testFileToSuiteCtx = new Map()
+const datadogRetryOriginals = new WeakMap()
 const wrappedFunctions = new WeakSet()
 const newTests = {}
 const efdTests = {}
@@ -168,6 +173,7 @@ function wrapOriginalEfdTest (test, retryPolicy) {
   }
   test._ddEfdDurationWrapped = true
   const originalFn = test.fn
+  originalEfdFns.set(test, originalFn)
   test.fn = shimmer.wrapFunction(originalFn, originalFn => function () {
     const start = performance.now()
     const recordDuration = () => {
@@ -264,6 +270,7 @@ function isEarlyFlakeDetectionTest (test, config) {
 function retryTest (test, numRetries, tags, retryPolicy) {
   const suite = test.parent
   const isEfdRetry = tags.includes('_ddIsEfdRetry')
+  if (!originalRetriesByTest.has(test)) originalRetriesByTest.set(test, test.retries())
   disableMochaRetries(test)
   if (isEfdRetry) {
     wrapOriginalEfdTest(test, retryPolicy)
@@ -271,6 +278,7 @@ function retryTest (test, numRetries, tags, retryPolicy) {
   for (let retryIndex = 0; retryIndex < numRetries; retryIndex++) {
     const clonedTest = test.clone()
     disableMochaRetries(clonedTest)
+    datadogRetryOriginals.set(clonedTest, test)
     suite.addTest(clonedTest)
     if (isEfdRetry) {
       clonedTest._ddEfdRetryIndex = retryIndex + 1
@@ -294,6 +302,91 @@ function retryTest (test, numRetries, tags, retryPolicy) {
   }
 }
 
+/**
+ * Restores a runnable function wrapped with its Test Optimization context.
+ *
+ * @param {import('mocha').Runnable} runnable
+ * @returns {void}
+ */
+function restoreRunnableFunction (runnable) {
+  const wrappedFunction = runnable.fn
+  if (!wrappedFunctions.has(wrappedFunction)) return
+
+  runnable.fn = originalFns.get(wrappedFunction)
+}
+
+/**
+ * Restores a test function wrapped to measure its EFD duration.
+ *
+ * @param {import('mocha').Test} test
+ * @returns {void}
+ */
+function restoreEfdTestFunction (test) {
+  if (!originalEfdFns.has(test)) return
+
+  test.fn = originalEfdFns.get(test)
+  originalEfdFns.delete(test)
+  delete test._ddEfdDurationWrapped
+}
+
+/**
+ * Clears state that belongs to one Mocha runner execution and removes retry clones from prior executions.
+ *
+ * @param {import('mocha').Suite} rootSuite
+ * @returns {void}
+ */
+function resetRunState (rootSuite) {
+  for (const key of Object.keys(newTests)) delete newTests[key]
+  for (const key of Object.keys(efdTests)) delete efdTests[key]
+  newTestsWithDynamicNames.clear()
+  testsAttemptToFix.clear()
+  testsQuarantined.clear()
+  testsStatuses.clear()
+  efdRetryCountByTestFullName.clear()
+  efdSlowAbortedTests.clear()
+  attemptToFixExecutions.clear()
+  loggedAttemptToFixTests.clear()
+
+  const suites = [rootSuite]
+  while (suites.length) {
+    const suite = suites.pop()
+    const originalTests = []
+    const retainedTests = new Set()
+    for (const runnable of suite.tests) {
+      const test = datadogRetryOriginals.get(runnable) || runnable
+      if (retainedTests.has(test)) continue
+      retainedTests.add(test)
+
+      restoreRunnableFunction(test)
+      restoreEfdTestFunction(test)
+      if (originalPendingByTest.has(test)) {
+        test.pending = originalPendingByTest.get(test)
+        originalPendingByTest.delete(test)
+      }
+      if (originalRetriesByTest.has(test)) {
+        test.retries(originalRetriesByTest.get(test))
+        originalRetriesByTest.delete(test)
+      }
+
+      delete test._ddIsAttemptToFix
+      delete test._ddIsDisabled
+      delete test._ddIsQuarantined
+      delete test._ddIsModified
+      delete test._ddIsNew
+      delete test._ddShouldSkipEfdRetry
+      delete test._ddTestFinishStarted
+      delete test._ddTestFinishPublished
+      delete test._ddIsFinalAttempt
+      delete test._ddHookFailed
+      delete test._ddReporterStartFailed
+      delete test._ddReporterTerminalFailed
+      originalTests.push(test)
+    }
+    suite.tests = originalTests
+    suites.push(...suite.suites)
+  }
+}
+
 function getSuitesByTestFile (root) {
   const suitesByTestFile = {}
   function getSuites (suite) {
@@ -370,6 +463,19 @@ function getTestContext (test) {
   return testToContext.get(key)
 }
 
+/**
+ * Claims publication of a test finish event across Mocha's terminal event paths.
+ *
+ * @param {object} test
+ * @returns {boolean}
+ */
+function startTestFinish (test) {
+  if (test._ddTestFinishStarted || test._ddTestFinishPublished) return false
+
+  test._ddTestFinishStarted = true
+  return true
+}
+
 /**
  * Copies Test Management metadata from Mocha's original runnable to its native retry clone.
  * @param {{
@@ -412,11 +518,7 @@ function runnableWrapper (RunnablePackage, libraryConfig) {
     const test = isTestHook ? this.ctx.currentTest : this
 
     // we restore the original user defined function
-    if (wrappedFunctions.has(this.fn)) {
-      const originalFn = originalFns.get(this.fn)
-      this.fn = originalFn
-      wrappedFunctions.delete(this.fn)
-    }
+    restoreRunnableFunction(this)
 
     if (isDatadogManagedRetryTest(test, libraryConfig)) {
       disableMochaRetries(this)
@@ -459,11 +561,7 @@ function getOnTestHandler (isMain) {
 
     // This may be a retry. If this is the case, `test.fn` is already wrapped,
     // so we need to restore it.
-    if (wrappedFunctions.has(test.fn)) {
-      const originalFn = originalFns.get(test.fn)
-      test.fn = originalFn
-      wrappedFunctions.delete(test.fn)
-    }
+    restoreRunnableFunction(test)
 
     inheritDatadogPropertiesFromRetriedTest(test)
 
@@ -526,6 +624,9 @@ function getOnTestHandler (isMain) {
     }
 
     if (!isAttemptToFix && isDisabled) {
+      if (!originalPendingByTest.has(test)) {
+        originalPendingByTest.set(test, test.pending)
+      }
       test.pending = true
     }
 
@@ -700,9 +801,16 @@ function getOnTestEndHandler (config, finalAttemptHandlers) {
     if (test._ddShouldSkipEfdRetry) {
       return
     }
+    const shouldWaitForHitProbe = test._retriedTest?._ddShouldWaitForHitProbe
     const ctx = getTestContext(test)
     const status = getTestStatus(test)
-    const shouldFinishTest = ctx && (!getAfterEachHooks(test).length || (test._ddIsDisabled && !test._ddIsAttemptToFix))
+    const shouldFinishTest = ctx && (
+      test._ddReporterStartFailed ||
+      test._ddReporterTerminalFailed ||
+      !getAfterEachHooks(test).length ||
+      (test._ddIsDisabled && !test._ddIsAttemptToFix)
+    )
+    if (shouldFinishTest && !startTestFinish(test)) return
     let testFinishInfo
     let isFinalAttempt = false
 
@@ -728,11 +836,12 @@ function getOnTestEndHandler (config, finalAttemptHandlers) {
       finalAttemptHandlers?.onStart?.(test)
     }
 
-    if (test._retriedTest?._ddShouldWaitForHitProbe) {
+    if (shouldWaitForHitProbe) {
       await waitForHitProbe()
     }
 
     if (shouldFinishTest) {
+      test._ddTestFinishPublished = true
       testFinishCh.publish({
         status,
         hasBeenRetried: isMochaRetry(test),
@@ -759,10 +868,11 @@ function getOnHookEndHandler (config, finalAttemptHandlers) {
         const ctx = getTestContext(test)
         // Disabled tests are already finished in getOnTestEndHandler,
         // skip to avoid double-publishing
-        if (ctx && (!test._ddIsDisabled || test._ddIsAttemptToFix)) {
+        if (ctx && (!test._ddIsDisabled || test._ddIsAttemptToFix) && startTestFinish(test)) {
           const testFinishInfo = getTestFinishInfo(test, status, config, ctx.err || test.err)
           const isFinalAttempt = testFinishInfo.finalStatus !== undefined
           const publishTestFinish = () => {
+            test._ddTestFinishPublished = true
             testFinishCh.publish({
               status,
               hasBeenRetried: isMochaRetry(test),
@@ -886,11 +996,13 @@ function getOnFailHandler (isMain, config) {
       testContext = getTestContext(test)
     }
     if (testContext) {
-      if (isHook) {
-        err.message = `${testOrHook.fullTitle()}: ${err.message}`
-        testContext.err = err
+      if (isHook && startTestFinish(test)) {
+        const hookError = new Error(`${testOrHook.fullTitle()}: ${err.message}`, { cause: err })
+        hookError.name = err.name
+        hookError.stack = err.stack
+        testContext.err = hookError
         errorCh.runStores(testContext, () => {})
-        const testFinishInfo = getTestFinishInfo(test, 'fail', config, err)
+        const testFinishInfo = getTestFinishInfo(test, 'fail', config, hookError)
         // ATR never retries hook failures: this.retries(N) is set in runnableWrapper
         // which only runs when the test function executes — hooks bypass that path,
         // so _retries stays at -1 and getIsLastRetry returns false, leaving finalStatus
@@ -905,6 +1017,7 @@ function getOnFailHandler (isMain, config) {
         // test.state is never set to 'failed' for hook failures (Mocha marks the hook,
         // not the test). Flag it so finishRootSuiteForFile can compute the correct status.
         test._ddHookFailed = true
+        test._ddTestFinishPublished = true
         testFinishCh.publish({
           status: 'fail',
           hasBeenRetried: isMochaRetry(test),
@@ -953,14 +1066,7 @@ function getOnTestRetryHandler (config) {
         promises,
         ...ctx.currentStore,
       })
-      if (promises.setProbePromise && promises.finishTestPromise) {
-        test._ddFailedTestReplayPromise = Promise.all([
-          promises.setProbePromise,
-          promises.finishTestPromise,
-        ]).then(() => {})
-      } else if (promises.setProbePromise || promises.finishTestPromise) {
-        test._ddFailedTestReplayPromise = promises.setProbePromise || promises.finishTestPromise
-      }
+      test._ddFailedTestReplayPromise = getFailedTestReplayPromise(promises)
     }
     const key = getTestToContextKey(test)
     testToContext.delete(key)
@@ -1094,6 +1200,7 @@ module.exports = {
   getOnPendingHandler,
   testFileToSuiteCtx,
   getRunTestsWrapper,
+  resetRunState,
   newTests,
   efdTests,
   newTestsWithDynamicNames,

package/packages/datadog-instrumentations/src/mysql.js

@@ -2,6 +2,13 @@
 
 const shimmer = require('../../datadog-shimmer')
 const { channel, addHook } = require('./helpers/instrument')
+const {
+  dispatchesAcquireSynchronously,
+  takePoolWaitTime,
+  wrapPoolClusterQueryMethod,
+  wrapPoolGetConnection,
+  wrapPoolQueryMethod,
+} = require('./helpers/pool-acquire')
 
 addHook({ name: 'mysql', file: 'lib/Connection.js', versions: ['>=2'] }, Connection => {
   const startCh = channel('apm:mysql:query:start')
@@ -17,6 +24,11 @@ addHook({ name: 'mysql', file: 'lib/Connection.js', versions: ['>=2'] }, Connect
     const conf = this.config
     const ctx = { sql, conf }
 
+    const waitTime = takePoolWaitTime(this)
+    if (waitTime !== undefined) {
+      ctx.poolWaitTime = waitTime
+    }
+
     return startCh.runStores(ctx, () => {
       if (args[0].sql) {
         args[0].sql = ctx.sql
@@ -61,20 +73,24 @@ addHook({ name: 'mysql', file: 'lib/Pool.js', versions: ['>=2'] }, Pool => {
   const connectionFinishCh = channel('apm:mysql:connection:finish')
   const startPoolQueryCh = channel('datadog:mysql:pool:query:start')
   const finishPoolQueryCh = channel('datadog:mysql:pool:query:finish')
-
-  shimmer.wrap(Pool.prototype, 'getConnection', getConnection => function (cb) {
-    arguments[0] = function (...args) {
-      return connectionFinishCh.runStores(ctx, cb, this, ...args)
-    }
-
-    const ctx = {}
-
-    connectionStartCh.publish(ctx)
-
-    return getConnection.apply(this, arguments)
-  })
-
-  shimmer.wrap(Pool.prototype, 'query', query => function (...args) {
+  const acquireStartCh = channel('apm:mysql:pool:acquire:start')
+  const acquireFinishCh = channel('apm:mysql:pool:acquire:finish')
+  const deferredPoolAcquire = !dispatchesAcquireSynchronously(
+    Pool.prototype.query,
+    Object.assign(Object.create(Pool.prototype), { config: { connectionConfig: {} } }),
+    'getConnection',
+    ['SELECT 1', () => {}]
+  )
+
+  shimmer.wrap(Pool.prototype, 'getConnection', getConnection => wrapPoolGetConnection(getConnection, {
+    connectionStartCh,
+    connectionFinishCh,
+    acquireStartCh,
+    acquireFinishCh,
+    reentersQueuedCallbacks: true,
+  }, deferredPoolAcquire))
+
+  shimmer.wrap(Pool.prototype, 'query', query => wrapPoolQueryMethod(function (...args) {
     if (!startPoolQueryCh.hasSubscribers) {
       return query.apply(this, args)
     }
@@ -99,7 +115,21 @@ addHook({ name: 'mysql', file: 'lib/Pool.js', versions: ['>=2'] }, Pool => {
 
       return retval
     })
-  })
+  }, connectionStartCh, deferredPoolAcquire))
 
   return Pool
 })
+
+// A `canRetry` failover re-invokes `query` with the same Query object. Key the acquire state by that
+// object so a retry remains part of the query even if a future mysql version defers it.
+addHook({ name: 'mysql', file: 'lib/PoolNamespace.js', versions: ['>=2'] }, PoolNamespace => {
+  const channels = {
+    connectionStartCh: channel('apm:mysql:connection:start'),
+    connectionFinishCh: channel('apm:mysql:connection:finish'),
+    acquireStartCh: channel('apm:mysql:pool:acquire:start'),
+    acquireFinishCh: channel('apm:mysql:pool:acquire:finish'),
+  }
+  shimmer.wrap(PoolNamespace.prototype, 'query', query => wrapPoolClusterQueryMethod(query, channels))
+
+  return PoolNamespace
+})

package/packages/datadog-instrumentations/src/mysql2.js

@@ -5,10 +5,55 @@ const { errorMonitor } = require('node:events')
 const shimmer = require('../../datadog-shimmer')
 const satisfies = require('../../../vendor/dist/semifies')
 const { channel, addHook } = require('./helpers/instrument')
+const {
+  dispatchesAcquireSynchronously,
+  takePoolWaitTime,
+  wrapPoolClusterGetConnection,
+  wrapPoolClusterMethod,
+  wrapPoolGetConnection,
+  wrapPoolQueryMethod,
+} = require('./helpers/pool-acquire')
 
 /** @type {WeakMap<object, Function>} */
 const wrappedOnResult = new WeakMap()
 
+/** @type {WeakSet<object>} */
+const flagWrappedNamespaces = new WeakSet()
+
+const connectionStartCh = channel('apm:mysql2:connection:start')
+const connectionFinishCh = channel('apm:mysql2:connection:finish')
+const acquireStartCh = channel('apm:mysql2:pool:acquire:start')
+const acquireFinishCh = channel('apm:mysql2:pool:acquire:finish')
+const poolAcquireChannels = {
+  connectionStartCh,
+  connectionFinishCh,
+  acquireStartCh,
+  acquireFinishCh,
+}
+
+/**
+ * Bracket a pool-cluster namespace's internal acquires and key retry state by its stable callback.
+ * @param {{ query?: Function, execute?: Function, getConnection?: Function }} poolNamespace
+ */
+function flagWrapNamespace (poolNamespace) {
+  if (poolNamespace == null || flagWrappedNamespaces.has(poolNamespace)) return
+  flagWrappedNamespaces.add(poolNamespace)
+
+  if (typeof poolNamespace.query === 'function') {
+    shimmer.wrap(poolNamespace, 'query', query => wrapPoolClusterMethod(query, connectionStartCh))
+  }
+  if (typeof poolNamespace.execute === 'function') {
+    shimmer.wrap(poolNamespace, 'execute', execute => wrapPoolClusterMethod(execute, connectionStartCh))
+  }
+  if (typeof poolNamespace.getConnection === 'function') {
+    shimmer.wrap(
+      poolNamespace,
+      'getConnection',
+      getConnection => wrapPoolClusterGetConnection(getConnection, poolAcquireChannels)
+    )
+  }
+}
+
 /**
  * @param {unknown} sql
  * @returns {string|undefined}
@@ -43,6 +88,11 @@ function wrapConnection (Connection, version) {
     const ctx = {}
 
     if (isQuery) {
+      const waitTime = takePoolWaitTime(this)
+      if (waitTime !== undefined) {
+        ctx.poolWaitTime = waitTime
+      }
+
       command.execute = wrapExecute(command, command.execute, ctx, this.config)
 
       return commandAddCh.runStores(ctx, addCommand, this, ...arguments)
@@ -212,22 +262,41 @@ function wrapConnection (Connection, version) {
  * by the queued query attach to the caller rather than the previous query that freed the connection.
  *
  * @param {Function} Pool
+ * @param {boolean} deferredPoolAcquire
  * @returns {Function}
  */
-function wrapGetConnection (Pool) {
-  const connectionStartCh = channel('apm:mysql2:connection:start')
-  const connectionFinishCh = channel('apm:mysql2:connection:finish')
+function wrapGetConnection (Pool, deferredPoolAcquire) {
+  shimmer.wrap(
+    Pool.prototype,
+    'getConnection',
+    getConnection => wrapPoolGetConnection(getConnection, poolAcquireChannels, deferredPoolAcquire)
+  )
 
-  shimmer.wrap(Pool.prototype, 'getConnection', getConnection => function (cb) {
-    const ctx = {}
-    arguments[0] = function (...args) {
-      return connectionFinishCh.runStores(ctx, cb, this, ...args)
-    }
-
-    connectionStartCh.publish(ctx)
+  return Pool
+}
 
-    return getConnection.apply(this, arguments)
-  })
+/**
+ * mysql2 >=3.11.5 keeps the outer-query abort at the connection level, so the pool only needs the
+ * acquire wrap plus the pool-query flag around `query` / `execute`.
+ *
+ * @param {Function} Pool
+ * @returns {Function}
+ */
+function wrapBasePool (Pool) {
+  const deferredQueryAcquire = defersPoolAcquire(Pool, 'query')
+  const deferredExecuteAcquire = defersPoolAcquire(Pool, 'execute')
+  wrapGetConnection(Pool, deferredQueryAcquire || deferredExecuteAcquire)
+
+  shimmer.wrap(
+    Pool.prototype,
+    'query',
+    query => wrapPoolQueryMethod(query, connectionStartCh, deferredQueryAcquire)
+  )
+  shimmer.wrap(
+    Pool.prototype,
+    'execute',
+    execute => wrapPoolQueryMethod(execute, connectionStartCh, deferredExecuteAcquire)
+  )
 
   return Pool
 }
@@ -240,10 +309,12 @@ function wrapGetConnection (Pool) {
 function wrapPool (Pool, version) {
   const startOuterQueryCh = channel('datadog:mysql2:outerquery:start')
   const shouldEmitEndAfterQueryAbort = satisfies(version, '>=1.3.3')
+  const deferredQueryAcquire = defersPoolAcquire(Pool, 'query')
+  const deferredExecuteAcquire = defersPoolAcquire(Pool, 'execute')
 
-  wrapGetConnection(Pool)
+  wrapGetConnection(Pool, deferredQueryAcquire || deferredExecuteAcquire)
 
-  shimmer.wrap(Pool.prototype, 'query', query => function (sql, values, cb) {
+  shimmer.wrap(Pool.prototype, 'query', query => wrapPoolQueryMethod(function (sql, values, cb) {
     if (!startOuterQueryCh.hasSubscribers) return query.apply(this, arguments)
 
     const resolvedSql = resolveSqlString(sql)
@@ -279,9 +350,9 @@ function wrapPool (Pool, version) {
     }
 
     return query.apply(this, arguments)
-  })
+  }, connectionStartCh, deferredQueryAcquire))
 
-  shimmer.wrap(Pool.prototype, 'execute', execute => function (sql, values, cb) {
+  shimmer.wrap(Pool.prototype, 'execute', execute => wrapPoolQueryMethod(function (sql, values, cb) {
     if (!startOuterQueryCh.hasSubscribers) return execute.apply(this, arguments)
 
     const resolvedSql = resolveSqlString(sql)
@@ -304,11 +375,25 @@ function wrapPool (Pool, version) {
     }
 
     return execute.apply(this, arguments)
-  })
+  }, connectionStartCh, deferredExecuteAcquire))
 
   return Pool
 }
 
+/**
+ * @param {Function} Pool
+ * @param {'query'|'execute'} method
+ * @returns {boolean}
+ */
+function defersPoolAcquire (Pool, method) {
+  return !dispatchesAcquireSynchronously(
+    Pool.prototype[method],
+    Object.assign(Object.create(Pool.prototype), { config: { connectionConfig: {} } }),
+    'getConnection',
+    ['SELECT 1', () => {}]
+  )
+}
+
 /**
  * @param {Function} PoolCluster
  * @returns {Function}
@@ -319,6 +404,7 @@ function wrapPoolCluster (PoolCluster) {
 
   shimmer.wrap(PoolCluster.prototype, 'of', of => function (...args) {
     const poolNamespace = of.apply(this, args)
+    flagWrapNamespace(poolNamespace)
 
     if (startOuterQueryCh.hasSubscribers && !wrappedPoolNamespaces.has(poolNamespace)) {
       shimmer.wrap(poolNamespace, 'query', query => function (sql, values, cb) {
@@ -404,7 +490,7 @@ addHook(
 // mysql2 >=3.11.5 moved the pool onto BasePool in lib/base/pool.js.
 addHook(
   { name: 'mysql2', file: 'lib/base/pool.js', versions: ['>=3.11.5'] },
-  /** @type {(moduleExports: unknown, version: string) => unknown} */ (wrapGetConnection)
+  /** @type {(moduleExports: unknown, version: string) => unknown} */ (wrapBasePool)
 )
 
 // PoolNamespace.prototype.query does not exist in mysql2<2.3.0
@@ -412,3 +498,18 @@ addHook(
   { name: 'mysql2', file: 'lib/pool_cluster.js', versions: ['2.3.0 - 3.11.4'] },
   /** @type {(moduleExports: unknown, version: string) => unknown} */ (wrapPoolCluster)
 )
+
+// mysql2 >=3.11.5 keeps the outer-query abort at the connection level, so a cluster namespace only
+// needs the pool-query flag so its internal query/execute acquire does not open an acquire span.
+addHook(
+  { name: 'mysql2', file: 'lib/pool_cluster.js', versions: ['>=3.11.5'] },
+  /** @type {(moduleExports: unknown, version: string) => unknown} */ (PoolCluster => {
+    shimmer.wrap(PoolCluster.prototype, 'of', of => function () {
+      const poolNamespace = of.apply(this, arguments)
+      flagWrapNamespace(poolNamespace)
+      return poolNamespace
+    })
+
+    return PoolCluster
+  })
+)

package/packages/datadog-instrumentations/src/path-to-regexp.js

@@ -5,6 +5,12 @@ const { addHook } = require('./helpers/instrument')
 /** @type {((pattern: string | RegExp) => RegExp | undefined) | undefined} */
 let compileToRegexp
 
+/** @type {((pattern: string) => { tokens: object[] } | undefined) | undefined} */
+let parseTokens
+
+/** @type {((route: string) => ((url: string) => object | undefined) | undefined) | undefined} */
+let makeMatcher
+
 addHook({ name: 'path-to-regexp', versions: ['*'] }, moduleExports => {
   // 0.1.x and 6.x: `module.exports = (path, ...) => RegExp`.
   // 7.x: `module.exports = { pathToRegexp(path, ...) => RegExp }`.
@@ -29,6 +35,47 @@ addHook({ name: 'path-to-regexp', versions: ['*'] }, moduleExports => {
   return moduleExports
 })
 
+// 8.x only: earlier majors also expose `parse`/`match`, but with incompatible shapes — 7.x returns
+// `{ tokens }` too, yet its tokens are bare strings rather than typed nodes. Gating on the version
+// keeps those from installing adapters the consumers would misread.
+addHook({ name: 'path-to-regexp', versions: ['>=8'] }, moduleExports => {
+  const { parse, match } = moduleExports
+
+  if (typeof parse === 'function' && typeof match === 'function') {
+    parseTokens = pattern => {
+      let result
+      try {
+        result = parse(pattern)
+      } catch {
+        return
+      }
+      if (Array.isArray(result?.tokens)) return result
+    }
+
+    makeMatcher = route => {
+      let matcher
+      try {
+        // Callers read which params matched, never their values: skipping decode is faster and
+        // stops a malformed escape ('%ZZ') from throwing URIError, which would read as "no match".
+        matcher = match(route, { decode: false })
+      } catch {
+        return
+      }
+      return url => {
+        let result
+        try {
+          result = matcher(url)
+        } catch {
+          return
+        }
+        return result ? result.params : undefined
+      }
+    }
+  }
+
+  return moduleExports
+})
+
 /**
  * Returns whatever path-to-regexp compile adapter the host most recently
  * loaded. Capture this once at addHook fire time so each express/router
@@ -41,4 +88,23 @@ function getCompileToRegexp () {
   return compileToRegexp
 }
 
-module.exports = { getCompileToRegexp }
+/**
+ * Returns the host's path-to-regexp `parse` adapter (8.x token tree), or `undefined` when the
+ * host has not loaded an 8.x path-to-regexp (e.g. Express 4 ships 0.1.x, which has no `parse`).
+ * @returns {((pattern: string) => { tokens: object[] } | undefined) | undefined}
+ */
+function getParse () {
+  return parseTokens
+}
+
+/**
+ * Returns the host's path-to-regexp 8.x `match` adapter: a factory `route => (url => params)` that
+ * compiles a route once and returns a matcher yielding the captured params (or undefined on no
+ * match / unusable route). `undefined` when the host has not loaded an 8.x path-to-regexp.
+ * @returns {((route: string) => ((url: string) => object | undefined) | undefined) | undefined}
+ */
+function getMatch () {
+  return makeMatcher
+}
+
+module.exports = { getCompileToRegexp, getParse, getMatch }