dd-trace 6.9.0 → 6.10.0

package/packages/datadog-instrumentations/src/helpers/rewriter/instrumentations/webdriverio.js

@@ -172,4 +172,85 @@ module.exports = [
     },
     channelName: 'testFrameworkFnWrapper',
   },
+  {
+    module: {
+      name: '@wdio/utils',
+      versionRange: '>=9.0.0',
+      filePath: 'build/index.js',
+    },
+    functionQuery: {
+      functionName: 'executeAsync',
+      kind: 'Async',
+    },
+    channelName: 'executeAsync',
+  },
+  {
+    module: {
+      name: '@wdio/utils',
+      versionRange: '>=9.0.0',
+      filePath: 'build/index.js',
+    },
+    astQuery: 'FunctionDeclaration[id.name="executeAsync"] CatchClause ' +
+      'IfStatement[test.operator=">"][test.left.object.name="retries"]' +
+      '[test.left.property.name="limit"][test.right.object.name="retries"]' +
+      '[test.right.property.name="attempts"]',
+    channelName: 'executeAsync',
+    transform: 'awaitContextCallback',
+    transformOptions: {
+      callbackArgumentNames: ['err'],
+      callbackName: 'retryCallback',
+    },
+  },
+  {
+    module: {
+      name: 'jasmine-core',
+      versionRange: '>=5.0.0 <6.0.0',
+      filePath: 'lib/jasmine-core/jasmine.js',
+    },
+    astQuery: 'AssignmentExpression[left.object.object.name="Spec"]' +
+      '[left.object.property.name="prototype"][left.property.name="execute"] > FunctionExpression',
+    functionQuery: {
+      kind: 'Sync',
+    },
+    channelName: 'Spec_execute',
+  },
+  {
+    module: {
+      name: 'jasmine-core',
+      versionRange: '>=5.0.0 <6.0.0',
+      filePath: 'lib/jasmine-core/jasmine.js',
+    },
+    astQuery: 'AssignmentExpression[left.object.object.name="Spec"]' +
+      '[left.object.property.name="prototype"][left.property.name="status"] > FunctionExpression',
+    functionQuery: {
+      kind: 'Sync',
+    },
+    channelName: 'Spec_attemptDone',
+  },
+  {
+    module: {
+      name: 'jasmine-core',
+      versionRange: '>=5.0.0 <6.0.0',
+      filePath: 'lib/jasmine-core/jasmine.js',
+    },
+    functionQuery: {
+      className: 'Spec',
+      methodName: 'executionFinished',
+      kind: 'Sync',
+    },
+    channelName: 'Spec_attemptDone',
+  },
+  {
+    module: {
+      name: 'jasmine-core',
+      versionRange: '>=5.0.0 <6.0.0',
+      filePath: 'lib/jasmine-core/jasmine.js',
+    },
+    functionQuery: {
+      className: 'TreeRunner',
+      methodName: '_executeSpec',
+      kind: 'Sync',
+    },
+    channelName: 'Spec_execute',
+  },
 ]

package/packages/datadog-instrumentations/src/helpers/rewriter/targets.json

@@ -54,6 +54,7 @@
   "graphql/utilities/index.mjs": "graphql",
   "graphql/validation/validate.js": "graphql",
   "graphql/validation/validate.mjs": "graphql",
+  "jasmine-core/lib/jasmine-core/jasmine.js": "jasmine-core",
   "mercurius/index.js": "mercurius",
   "playwright-core/lib/coreBundle.js": "playwright-core",
   "playwright/lib/index.js": "playwright",

package/packages/datadog-instrumentations/src/helpers/rewriter/transforms.js

@@ -14,7 +14,89 @@ const clone = require('../../../../../vendor/dist/rfdc')({ proto: false, circles
 
 const { parse, query } = require('./compiler')
 
-module.exports = { waitForAsyncEnd }
+const functionTypes = new Set(['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression'])
+const identifierPattern = /^[$A-Z_a-z][$\w]*$/
+
+module.exports = { awaitContextCallback, waitForAsyncEnd }
+
+/**
+ * Awaits an optional context callback before continuing through a matched conditional branch.
+ *
+ * The branch condition is checked again after the callback settles so the
+ * original body does not run against state that changed while awaiting.
+ *
+ * @param {{
+ *   transformOptions?: {
+ *     callbackArgumentNames?: string[],
+ *     callbackName?: string
+ *   }
+ * }} state
+ * @param {import('estree').IfStatement} node
+ * @param {import('estree').Node} _parent
+ * @param {import('estree').Node[]} ancestry
+ * @returns {void}
+ */
+function awaitContextCallback (state, node, _parent, ancestry) {
+  assert(node.type === 'IfStatement' && node.consequent?.type === 'BlockStatement',
+    'awaitContextCallback: expected an if statement with a block body')
+
+  const { callbackArgumentNames = [], callbackName } = state.transformOptions ?? {}
+
+  assert(identifierPattern.test(callbackName), 'awaitContextCallback: callbackName must be an identifier')
+  assert(callbackArgumentNames.every(name => identifierPattern.test(name)),
+    'awaitContextCallback: callbackArgumentNames must be identifiers')
+
+  let enclosingFunction
+  let hasTraceWrapper = false
+  for (const ancestor of ancestry) {
+    if (!functionTypes.has(ancestor.type)) continue
+
+    enclosingFunction ??= ancestor
+    if (ancestor.body?.type !== 'BlockStatement') continue
+
+    let hasContextBinding = false
+    let hasTracedBinding = false
+    for (const statement of ancestor.body.body) {
+      if (statement.type !== 'VariableDeclaration') continue
+
+      for (const declaration of statement.declarations) {
+        hasContextBinding ||= declaration.id?.name === '__apm$ctx'
+        hasTracedBinding ||= declaration.id?.name === '__apm$traced'
+      }
+    }
+    hasTraceWrapper ||= hasContextBinding && hasTracedBinding
+  }
+
+  assert(enclosingFunction?.async, 'awaitContextCallback: expected an enclosing async function')
+  assert(hasTraceWrapper, 'awaitContextCallback: expected an enclosing trace wrapper')
+
+  const callbackVariable = `__apm$${callbackName}`
+  if (query(node, `[id.name="${callbackVariable}"]`).length > 0) {
+    return
+  }
+
+  const originalStatements = node.consequent.body
+  const callbackStatements = parse(`
+    async function wrapper () {
+      const ${callbackVariable} = __apm$ctx.${callbackName};
+      if (typeof ${callbackVariable} === 'function') {
+        try {
+          await ${callbackVariable}(${callbackArgumentNames.join(', ')});
+        } catch {}
+        if (true) {}
+      } else {
+      }
+    }
+  `).body[0].body.body
+
+  const callbackBranch = callbackStatements[1]
+  const recheckedBranch = callbackBranch.consequent.body[1]
+  recheckedBranch.test = clone(node.test)
+  recheckedBranch.consequent.body.push(...clone(originalStatements))
+  recheckedBranch.alternate = clone(node.alternate)
+  callbackBranch.alternate.body.push(...originalStatements)
+  node.consequent.body = callbackStatements
+}
 
 /**
  * Injects settlement-specific asyncEnd waits into a generated `tracePromise`

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

@@ -49,7 +49,7 @@ const {
   getRawJestTestName,
   getJestSuitesToRun,
   removeSeedSuffixFromTestName,
-} = require('../../datadog-plugin-jest/src/util')
+} = require('../../dd-trace/src/plugins/util/jest')
 const {
   addCoverageBackfillUntestedFiles,
   getCoverageBackfillFiles,

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

@@ -10,7 +10,6 @@ const {
 } = require('../helpers/channel')
 const { addHook, channel } = require('../helpers/instrument')
 const shimmer = require('../../../datadog-shimmer')
-const { isMarkedAsUnskippable } = require('../../../datadog-plugin-jest/src/util')
 const { EMPTY_EFD_RETRY_POLICY } = require('../../../dd-trace/src/ci-visibility/efd-retry-policy')
 const { writeCoverageBackfillToCache } = require('../../../dd-trace/src/ci-visibility/test-optimization-cache')
 const log = require('../../../dd-trace/src/log')
@@ -33,6 +32,7 @@ const {
   TEST_IMPACT_ANALYSIS_ALL_TESTS_SKIPPED_MESSAGE,
   getTestOptimizationRequestResults,
   isModifiedTest,
+  isMarkedAsUnskippable,
 } = require('../../../dd-trace/src/plugins/util/test')
 
 const {

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

@@ -11,6 +11,7 @@ const {
 const {
   getTestSuitePath,
   DYNAMIC_NAME_RE,
+  getFailedTestReplayPromise,
   recordTestManagementExecution,
   recordAttemptToFixExecution,
   logAttemptToFixTestExecution,
@@ -953,14 +954,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)

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 }