@contrast/route-coverage 1.45.1 → 1.46.0

package/lib/index.d.ts

@@ -23,11 +23,13 @@ import { Scopes } from '@contrast/scopes';
 export { RouteInfo };
 
 export interface RouteCoverage extends Installable {
+  _normalizedUrlMapper: any;
   discover(info: RouteInfo): void;
   discoveryFinished(): void;
   queue(info: RouteInfo): void;
   queuingFinished(): void;
   observe(info: RouteInfo): void;
+  uriPathToNormalizedUrl(uriPath: string): string;
 }
 
 export interface Core {

package/lib/index.js

@@ -16,7 +16,6 @@
 'use strict';
 
 const { callChildComponentMethodsSync, Event } = require('@contrast/common');
-const NormalizedUrlMapper = require('./normalized-url-mapper');
 
 /**
  * @param {import('.').Core & {
@@ -36,18 +35,14 @@ module.exports = function init(core) {
   const routeQueue = new Map();
 
   const routeIdentifier = (method, signature) => `${method}.${signature}`;
-  const routeCoverage = core.routeCoverage = {
-    _normalizedUrlMapper: new NormalizedUrlMapper(),
-
-    uriPathToNormalizedUrl(uriPath) {
-      return this._normalizedUrlMapper.map(uriPath);
-    },
 
+  const routeCoverage = core.routeCoverage = {
     discover(info) {
-      logger.trace({ info }, 'Discovered new route:');
-      routeInfo.set(routeIdentifier(info.method, info.signature), info);
-      this._normalizedUrlMapper.handleDiscover(info);
+      const id = routeIdentifier(info.method, info.signature);
+      if (routeInfo.get(id)) return;
 
+      logger.trace({ info }, 'Discovered new route:');
+      routeInfo.set(id, info);
     },
 
     discoveryFinished() {
@@ -67,7 +62,7 @@ module.exports = function init(core) {
       if (routeQueue.size === 1) {
         setTimeout(() => {
           this.discoveryFinished();
-        }, 10000);
+        }, 10_000);
       }
     },
 
@@ -99,16 +94,12 @@ module.exports = function init(core) {
       route.method = info.method;
       route.url = info.url;
       const store = scopes.sources.getStore();
-      if (store && !store.route) {
-        store.route = route;
-      }
 
+      if (store) store.route = route;
       if (recentlyObserved.has(route.signature)) return;
 
       recentlyObserved.add(route.signature);
-
       logger.trace({ info }, 'Observed route:');
-
       // these events need source correlation
       messages.emit(Event.ROUTE_COVERAGE_OBSERVATION, {
         ...route,
@@ -122,7 +113,6 @@ module.exports = function init(core) {
     },
   };
 
-  require('./install/http')(core);
   require('./install/express')(core);
   require('./install/fastify')(core);
   require('./install/graphql')(core);
@@ -130,5 +120,13 @@ module.exports = function init(core) {
   require('./install/koa')(core);
   require('./install/restify')(core);
 
+  messages.on(Event.SERVER_LISTENING, () => {
+    // we wait to report in timers event loop phase, this way we can
+    // have components respond to this synchronously to finalize discovery
+    setImmediate(() => {
+      core.routeCoverage.discoveryFinished();
+    });
+  });
+
   return routeCoverage;
 };

package/lib/install/express/express5.js

@@ -14,6 +14,22 @@
  */
 'use strict';
 
+const { AsyncLocalStorage } = require('node:async_hooks');
+const {
+  get,
+  set,
+  isString,
+  Event,
+  primordials: {
+    ArrayPrototypeJoin,
+    StringPrototypeSubstring,
+    StringPrototypeToLowerCase,
+    StringPrototypeReplace,
+  }
+} = require('@contrast/common');
+const { funcInfo } = require('@contrast/fn-inspect');
+const Core = require('@contrast/core/lib/ioc/core');
+
 const METHODS = [
   'all',
   'get',
@@ -24,233 +40,504 @@ const METHODS = [
   'options',
   'head',
 ];
-const framework = 'express';
-const { patchType, createSignature } = require('../../utils/route-info');
-const {
-  isString,
-  primordials: {
-    ArrayPrototypeJoin,
-    ArrayPrototypeSlice,
-    StringPrototypeSplit,
-    StringPrototypeToLowerCase,
-    StringPrototypeReplace,
-    StringPrototypeSlice,
-    PathBasename
-  }
-} = require('@contrast/common');
-const { match } = require('path-to-regexp');
-const fnInspect = require('@contrast/fn-inspect');
-
-module.exports = function init(core) {
-
-  const discovered = [];
-  const routerMap = new Map();
-  const { patcher, depHooks, routeCoverage } = core;
-
-  const removeTrailingSlash = (url) => (url.endsWith('/') && url !== '/') ? StringPrototypeSlice.call(url, 0, -1) : url;
-  const format = (url) => Array.isArray(url)
-    ? `/[${ArrayPrototypeJoin.call(url)}]`
-    : removeTrailingSlash(url); // remove trailing slash
-  const isRouter = (layer) => layer?.name && StringPrototypeToLowerCase.call(layer.name) === 'router';
-
-  function getFnName({ method, file, lineNumber, column }) {
-    if (method) return method;
-    if (!file) return '(anonymous)';
-    const base = PathBasename(file);
-    return `(anonymous ${base} ${lineNumber}:${column})`;
-  }
+const componentName = 'routeCoverage.express5';
+const kMetaKey = Symbol('cs_meta');
+const enumerable = false;
 
-  function createRouteInfo(url, method, obj, fn) {
-    const fnInfo = fnInspect.funcInfo(fn);
-    const fnName = getFnName(fnInfo);
-    const originalUrl = url;
-    url = format(url);
-    return {
-      url,
-      method,
-      fnName,
-      framework,
-      originalUrl,
-      normalizedUrl: url,
-      signature: createSignature(url, method, obj, fnName)
-    };
-  }
+module.exports = Core.makeComponent({
+  name: componentName,
+  factory: (core) => new ExpressInstrumentation(core),
+});
+
+class ExpressInstrumentation {
+  constructor(core) {
+    // decorate
+    set(core, componentName, this);
 
-  function updateRouteInfo(prefix, routeInfo) {
-    const { url, normalizedUrl, fnName, method, addedPrefix = '' } = routeInfo;
-    const updatedUrl = removeTrailingSlash(prefix + url);
-    const updatedNormalizedUrl = removeTrailingSlash(prefix + normalizedUrl);
-    const updatedAddedPrefix = removeTrailingSlash(prefix + addedPrefix);
-    const updatedSignature = createSignature(updatedUrl, method, 'router', fnName);
-    return {
-      ...routeInfo,
-      url: updatedUrl,
-      addedPrefix: updatedAddedPrefix,
-      normalizedUrl: updatedNormalizedUrl,
-      signature: updatedSignature
-    };
+    this.core = core;
+    this.methodScope = new AsyncLocalStorage();
+    this.handleScope = new AsyncLocalStorage();
   }
 
-  function discover(routeInfo) {
-    const { url, normalizedUrl, signature, method, framework } = routeInfo;
-    if (!url || !normalizedUrl || !signature || !method || !framework) return;
-    routeCoverage.discover({
-      url,
-      normalizedUrl,
-      signature,
-      method,
-      framework
-    });
+  install() {
+    const self = this;
+    const { core, handleScope, methodScope } = this;
+    const patchType = 'route-coverage-express';
+    const name = 'express-5';
 
-    // Used to match urls during route observation
-    let urlToMatch = routeInfo.normalizedUrl;
-    if (Array.isArray(routeInfo.originalUrl)) {
-      const prefix = routeInfo?.addedPrefix || '';
-      urlToMatch = routeInfo.originalUrl.map(seg => prefix + seg);
-    }
-    const matchUrl = match(urlToMatch);
-    routeInfo.match = matchUrl;
+    //
+    // discovery instrumentation
+    //
 
-    discovered.push(routeInfo);
-  }
+    core.depHooks.resolve({ name: 'express', version: '5' }, (express) => {
+      // wrap router and app methods in "method scope" to capture info to help build signatures.
+      // express has a number of APIs that work at different levels of abstraction, and we need to patch
+      // all of them. the scopes let us know what top-level APIs are being called by application code.
+      [...METHODS, 'use', 'route'].forEach((method) => {
+        // then setup app and router to run in method scopes
+        core.patcher.patch(express.application, method, {
+          name: `express.application.${method}`,
+          patchType: `${patchType}-discovery`,
+          around(next, data) {
+            if (methodScope.getStore()) return next();
+            return methodScope.run({ method, args: data.args, type: 'app' }, next);
+          }
+        });
 
-  function wrapForObservation(handler, routeInfo, isRouter = false) {
-    const handlerInfo = fnInspect.funcInfo(handler);
-    const handlerName = getFnName(handlerInfo);
-    return patcher.patch(handler, {
-      name: 'handler',
-      patchType,
-      post(data) {
-        const [req] = data.args;
-        const [url] = StringPrototypeSplit.call(req.originalUrl, '?');
-        const method = StringPrototypeToLowerCase.call(req.method);
-        if (url && method) {
-          if (isRouter) {
-            for (const route of discovered) {
-              if (route.match(url) && route.fnName === handlerName) {
-                const { signature, normalizedUrl } = route;
-                routeCoverage.observe({ url, method, signature, framework, normalizedUrl });
-                break;
-              }
-            }
-          } else {
-            const { signature, normalizedUrl } = routeInfo;
-            routeCoverage.observe({ url, method, signature, framework, normalizedUrl });
+        core.patcher.patch(express.Router.prototype, method, {
+          name: `express.Router.prototype.${method}`,
+          patchType: `${patchType}-discovery`,
+          around(next, data) {
+            if (methodScope.getStore()) return next();
+            return methodScope.run({ method, args: data.args, type: 'router' }, next);
           }
-        }
-      }
-    });
-  }
+        });
+      });
 
-  return core.routeCoverage.express5 = {
-    install() {
-      depHooks.resolve({ name: 'express', version: '5' }, (express) => {
-        METHODS.forEach((method) => {
-          patcher.patch(express.application, method, {
-            name: `express.application.${method}`,
-            patchType,
-            pre(data) {
-              const [path, ...args] = data.args;
-              if ((!isString(path) && !Array.isArray(path)) || path === '') return;
+      // app[method] and router[method] end up calling this
+      // Append metadata to the created Route object at layer.route.
+      // we also patch the returned Route's methods for building signatures
+      core.patcher.patch(express.Router.prototype, 'route', {
+        name: 'express.Route',
+        patchType: `${patchType}-discovery`,
+        post(data) {
+          const { result } = data;
+          const methodStore = methodScope.getStore();
+          const meta = {
+            paths: ExpressInstrumentation.normalizePaths(data.args[0]),
+            method: methodStore?.method,
+            type: methodStore?.type || 'route',
+          };
 
-              const fns = args.flat(Infinity);
-              for (let i = 0; i < fns.length; i++) {
-                if (typeof fns[i] !== 'function') continue;
-                const routeInfo = createRouteInfo(path, method, 'app', fns[i]);
+          Object.defineProperty(result, kMetaKey, {
+            enumerable,
+            value: meta
+          });
 
-                discover(routeInfo);
-                fns[i] = wrapForObservation(fns[i], routeInfo);
-              }
-              data.args.splice(1, fns.length, ...fns);
+          // patch route instance methods we do that here when we have
+          // todo move to prototype to help w/ memory
+          METHODS.forEach((method) => {
+            if (result[method]) {
+              core.patcher.patch(result, method, {
+                name: `express.Router.prototype.route${method}`,
+                patchType: `${patchType}-discovery`,
+                pre(data) {
+                  data._stackIdx = data.obj.stack?.length;
+                },
+                post(data) {
+                  if (data.obj.stack?.length > data._stackIdx) {
+                    for (let i = data._stackIdx; i < data.obj.stack.length; i++) {
+                      const layer = data.obj.stack[i];
+                      const methodStore = methodScope.getStore();
+                      const meta = {
+                        type: methodStore?.type || 'route',
+                        method: methodStore?.method == 'all' ? 'all' : method,
+                      };
+
+                      Object.defineProperty(layer, kMetaKey, {
+                        enumerable,
+                        value: meta,
+                      });
+                    }
+                  }
+                },
+              });
             }
           });
 
-          patcher.patch(express.Router.prototype, method, {
-            name: `express.Router.prototype.${method}`,
-            patchType,
-            pre(data) {
-              const Router = data.obj;
-              const [path, ...args] = data.args;
-              if (!isString(path) && !Array.isArray(path)) return;
-
-              const fns = args.flat(Infinity);
-              const routes = routerMap.get(Router) || [];
-              for (let i = 0; i < fns.length; i++) {
-                if (typeof fns[i] !== 'function') continue;
-                const routeInfo = createRouteInfo(path, method, 'router', fns[i]);
+          return result;
+        },
+      });
 
-                fns[i] = wrapForObservation(fns[i], routeInfo, true);
+      core.patcher.patch(express.Router.prototype, 'use', {
+        name: `${name}.Router.prototype.use`,
+        patchType: `${patchType}-discovery`,
+        pre(data) {
+          data._stackLength = data.obj.stack?.length;
+        },
+        post(data) {
+          if (data.obj.stack.length > data._stackLength) {
+            for (let i = data._stackLength; i < data.obj.stack.length; i++) {
+              const layer = data.obj.stack[i];
+              const paths = ExpressInstrumentation.normalizePaths(data.args[0]);
+              const methodStore = methodScope.getStore();
+              const meta = {
+                paths,
+                method: 'use',
+                type: methodStore?.type || 'router',
+              };
 
-                routes.push(routeInfo);
-                data.args.splice(1, fns.length, ...fns);
+              if (layer) {
+                Object.defineProperty(layer, kMetaKey, {
+                  enumerable: false,
+                  value: meta
+                });
               }
-              routerMap.set(Router, routes);
             }
+          }
+        },
+      });
+
+      return core.patcher.patch(express, {
+        name: 'express-5.application',
+        patchType: `${patchType}-discovery`,
+        post(data) {
+          const app = data.result;
+          core.messages.on(Event.SERVER_LISTENING, () => {
+            if (!app.router.stack[0]) {
+              core.logger.debug('no routes detected in express router stack');
+              return;
+            }
+            self.handleDiscovery(app);
           });
-        });
+          return app;
+        }
+      });
+    });
 
-        let appRouter;
-        patcher.patch(express.application, 'use', {
-          name: 'express.application.use',
-          patchType,
-          pre(data) {
-            appRouter = data.obj.router;
-
-            const arg0 = data.args[0];
-            const prefix = (Array.isArray(arg0) || isString(arg0)) ? arg0 : undefined;
-            const args = prefix ? ArrayPrototypeSlice.call(data.args, 1) : data.args;
-            const fns = args.flat(Infinity);
-            for (let i = 0; i < fns.length; i++) {
-              if (isRouter(fns[i])) {
-                let routes = routerMap.get(fns[i]);
-                if (routes) {
-                  if (prefix) routes = routes.map(route => updateRouteInfo(prefix, route));
-                  routes.forEach((route) => discover(route));
+    core.depHooks.resolve({ name: 'express', version: '5' }, (express) => {
+      core.patcher.patch(express.application, 'handle', {
+        name: 'express.application.handle',
+        patchType: `${patchType}-discovery`,
+        around(next, data) {
+          // wrap request handling in "handle scope". the scope's store data
+          // helps for building observation templates as routing occurs
+          const store = {
+            matchIdx: -1,
+            templateSegments: [],
+          };
+          return handleScope.run(store, next);
+        }
+      });
+    });
+
+    //
+    // observation instrumentation
+    //
+
+    // when Layer.match gets called, matchers functions run underneath. the API doesn't present a really clean
+    // way to instrument, so we're using scopes. we reference the scope's store in the instrumented matcher
+    // functions so we can correlate a matcher that succeeds to its corresponding route template segment.
+    core.depHooks.resolve({ name: 'router', file: 'lib/layer.js', version: '2' }, (Layer) => {
+      core.patcher.patch(Layer.prototype, 'match', {
+        name: 'Layer.prototype.match',
+        patchType: `${patchType}-observation`,
+        pre(data) {
+          data._store = handleScope.getStore();
+          if (!data._store) return;
+
+          // we check in post hook whether any matcher instrumentation reset this in scope.
+          // matchers will set this to a number only if multiple matchers run and one succeeds.
+          // use the index of that matcher to get associated template segment from the metadata.
+          data._store.matcherIdx = null;
+          // save reference to metadata source
+          data[kMetaKey] = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
+        },
+        post(data) {
+          // whenever a layer matches, save the corresponding
+          // template segment metadata in the handle scope store
+          const { result } = data;
+          if (!result || !data._store || !data[kMetaKey]?.paths) return;
+
+          let template;
+          if (data._store.matcherIdx != null) {
+            template = data[kMetaKey].paths[data._store.matcherIdx];
+          } else {
+            template = data[kMetaKey].paths[0];
+          }
+
+          // if the layer matches, we know to push corresponding path to store's template segments.
+          // we pop this value from the array in hook to all `next` callbacks below.
+          data._store.templateSegments.push(template);
+        }
+      });
+
+      // patch the `next` callback of every Layer's request handler.
+      // we pop the value from the stack of route template segments being managed.
+      core.patcher.patch(Layer.prototype, 'handleRequest', {
+        name: 'Layer.prototype.handleRequest',
+        patchType: `${patchType}-observation`,
+        pre(data) {
+          const next = data.args[2];
+          const meta = data.obj[kMetaKey] || data.obj.route?.[kMetaKey];
+          if (meta?.paths) {
+            const store = handleScope.getStore();
+            // this runs often and there's no need to use patcher here. monkey patch directly to optimize
+            data.args[2] = function(...args) {
+              if (store) store.templateSegments.pop();
+              const ret = next(...args);
+              return ret;
+            };
+          }
+        }
+      });
+
+      // instrument the Layer constructor. this will allow us to patch
+      // created matchers to help us build observation template from metadata.
+      // if matcher was successful we store index of it in handle scope.
+      return core.patcher.patch(Layer, {
+        name: 'router.Layer',
+        patchType: `${patchType}-observation`,
+        pre(data) {
+          data._methodScope = methodScope.getStore();
+        },
+        post(data) {
+          const instance = data.result;
+          // only instrument matchers if the Layer is being instantiated within method scope, and
+          // if there are multiple matchers and we need the index to correlate to tempate segment
+          if (data._methodScope && instance.matchers.length > 1) {
+            for (let i = 0; i < instance.matchers.length; i++) {
+              const matcher = instance.matchers[i];
+              instance.matchers[i] = function(...args) {
+                const result = matcher.apply(this, args);
+                if (result) {
+                  const store = handleScope.getStore();
+                  if (store) store.matcherIdx = i;
                 }
-              } else if (prefix && typeof fns[i] === 'function') {
-                const routeInfo = createRouteInfo(prefix, 'use', 'app', fns[i]);
-                discover(routeInfo);
-                fns[i] = wrapForObservation(fns[i], routeInfo);
-              }
+                return result;
+              };
             }
-            data.args.splice(prefix ? 1 : 0, fns.length, ...fns);
           }
-        });
-        patcher.patch(express.Router.prototype, 'use', {
-          name: 'express.Router.prototype.use',
-          patchType,
-          pre(data) {
-            const Router = data.obj;
-            const isAppRouter = Router === appRouter;
-            if (isAppRouter) return;
-
-            let routerRoutes = routerMap.get(Router) || [];
-
-            const arg0 = data.args[0];
-            let prefix = (Array.isArray(arg0) || isString(arg0)) ? arg0 : undefined;
-            const args = prefix ? ArrayPrototypeSlice.call(data.args, 1) : data.args;
-            const fns = args.flat(Infinity);
-
-            for (let i = 0; i < fns.length; i++) {
-              const selfNested = fns[i] === Router;
-              if (isRouter(fns[i])) {
-                let routes = routerMap.get(fns[i]) || [];
-                if (prefix) {
-                  if (selfNested) prefix = StringPrototypeReplace.call(prefix, '/', '/*');
-                  routes = routes.map(route => updateRouteInfo(prefix, route));
+          // patch handle to report observation when called. it checks handle
+          // scope to get current request's template to match with discovery info
+          core.patcher.patch(instance, 'handle', {
+            name: 'router.Layer.handle',
+            patchType: `${patchType}-observation`,
+            pre(data) {
+              if (instance[kMetaKey]?.observables) {
+                const store = handleScope.getStore();
+                if (store) {
+                  const method = StringPrototypeToLowerCase.call(data.args[0].method || '');
+                  const template = ArrayPrototypeJoin.call(store.templateSegments, '') || '/';
+
+                  if (instance[kMetaKey]?.observables?.[template]) {
+                    self.observe({
+                      url: data.args[0].originalUrl,
+                      normalizedUrl: template,
+                      method,
+                      signature: instance[kMetaKey].observables[template],
+                    });
+                  } else {
+                    core.logger.error({
+                      // url: data.args[0].originalUrl, // this would need masking to log
+                      method,
+                      template,
+                      observables: instance[kMetaKey]?.observables,
+                    }, 'unable to map route template to signature');
+                  }
                 }
-                routerRoutes = selfNested ? routes : routerRoutes.concat(routes);
-              } else if (prefix && typeof fns[i] === 'function') {
-                const routeInfo = createRouteInfo(prefix, 'use', 'router', fns[i]);
-                routerRoutes.push(routeInfo);
-                fns[i] = wrapForObservation(fns[i], routeInfo);
               }
+            },
+          });
+        },
+      });
+    });
+  }
+
+  discover(info) {
+    const { method, observables } = info;
+    if (!method || !observables) return;
+
+    for (const [normalizedUrl, signature] of Object.entries(observables)) {
+      this.core.routeCoverage.discover({
+        url: normalizedUrl,
+        normalizedUrl,
+        method,
+        signature,
+        framework: 'express',
+      });
+    }
+  }
+
+  observe(info) {
+    this.core.routeCoverage.observe({ framework: 'express', ...info });
+  }
+
+  /**
+   * Traverse the application's router "stack" and generate route discovery events
+   * using layer/route metadata that was appended by methods like router.post().
+   * @param {object} app express instance
+   */
+  handleDiscovery(app) {
+    const self = this;
+    const router = app.router || app._router;
+
+    // traverse fn executes this callback when visiting Layer instances
+    this.traverse(router, (path, key, value, target, state) => {
+      if (value.stack?.length > 0 || value.route) return;
+
+      // get metadata for this Layer
+      // metadata is on Layers within stacks and on Routes instances.
+      const metas = [];
+      for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (Number.isFinite((Number(seg))) || seg == 'route') {
+          const metaPath = ArrayPrototypeJoin.call(path.slice(0, i + 1), '.');
+          const layerOrRoute = get(router, metaPath);
+          if (layerOrRoute?.[kMetaKey]) {
+            metas.push(layerOrRoute[kMetaKey]);
+          }
+        }
+      }
+
+      // mounted routers aren't discoverable since they themselves don't
+      // represent routes, they dispatch to sub routers/route handlers.
+      if (value.name != 'router' && value.handle?.name != 'router') {
+        // `value` is a terminal Layer with observable signatures.
+        // emit discovery after appending metadata.
+        if (value[kMetaKey]) {
+          const observables = this.generateObservables(metas, value.handle);
+          if (observables) {
+            if (!value[kMetaKey].observables) {
+              value[kMetaKey].observables = observables;
+            } else {
+              Object.assign(value[kMetaKey].observables, observables);
             }
-            routerMap.set(Router, routerRoutes);
-            data.args.splice(prefix ? 1 : 0, fns.length, ...fns);
           }
-        });
-      });
+          self.discover(value[kMetaKey]);
+        }
+      }
+    });
+  }
+
+  /**
+   * Traverses the top-level app's routing stack and executes the provided callback when
+   * visiting nodes. The callback is invoked only to visit Layer instances, objects and
+   * functions, since these are the only 2 types that could have our metadata attached.
+   */
+  traverse(target, cb, path = [], data = new Map()) {
+    loopKeys: for (const key in target) {
+      path.push(key);
+
+      // only visit Layer instances
+      const maybeLayer = target[key];
+      if (
+        maybeLayer?.constructor?.name == 'Layer' &&
+        !maybeLayer?.stack?.length
+      ) {
+        let _data = data.get(maybeLayer);
+
+        if (!_data) {
+          _data = { paths: [] };
+          data.set(maybeLayer, _data);
+        }
+
+        // you can mount a router on itself
+        // prevent infinitely recursing into self-mounted routers
+        for (const visitedPath of _data.paths) {
+          // these conditions indicate recursive nesting at particular path
+          if (
+            path.length > visitedPath.length &&
+            visitedPath.every((el, i) => path[i] == el)
+          ) {
+            path.pop();
+            continue loopKeys;
+          }
+        }
+
+        _data.paths.push([...path]); // copy because path argument mutates
+
+        const halt = cb(path, key, maybeLayer, target) === false;
+        if (halt) return;
+      }
+
+      // might be able to fine-tune this a bit more
+      if (typeof maybeLayer == 'object' || typeof maybeLayer == 'function') {
+        this.traverse(maybeLayer, cb, path, data);
+      }
+
+      path.pop();
     }
-  };
-};
+  }
+
+  generateObservables(metas, handler) {
+    const { core } = this;
+    handler = core.patcher.unwrap(handler);
+
+    let type = '';
+    let method = '';
+    let templates = [];
+    const info = funcInfo(handler);
+
+    // ignore 3rd-party mw/handlers
+    if (info.file?.includes?.('node_modules')) {
+      return null;
+    }
+
+    let file = info.file ?
+      StringPrototypeReplace.call(info.file, core.appInfo.app_dir, '') :
+      '';
+    if (file.length > 30) {
+      file = `...${StringPrototypeSubstring.call(file, file.length - 40)}`;
+    }
+    const handlerName = info.method || handler.name || 'anonymous';
+    const formattedHandler = (file && Number.isFinite(info.lineNumber) && Number.isFinite(info.column)) ?
+      `[${handlerName} ${file} ${info.lineNumber}:${info.column}]` :
+      `[Function: ${handlerName}]`; // what util.inspect(handler) would return
+
+    // loop backwards
+    for (let i = metas.length - 1; i >= 0; i--) {
+      const meta = metas[i];
+      // use the most recent `type` and `method` used when building routes, so don't overwrite if set
+      if (!type && meta.type) type = meta.type;
+      if (!method && meta.method) method = meta.method;
+
+      // builds out all possible template combinations that the Layer is able to handle during routing
+      if (Array.isArray(meta.paths)) {
+        if (!templates.length) {
+          templates = [...meta.paths];
+        } else {
+          const _t = [];
+          for (const templateSegment of meta.paths) {
+            for (const templateAcc of templates) {
+              _t.push(`${templateSegment}${templateAcc}`);
+            }
+          }
+          templates = [..._t];
+        }
+      }
+    }
+
+    // build signature lookup based on each template (normalizeUri)
+    const map = templates.reduce((acc, routeTemplate) => {
+      if (!routeTemplate) routeTemplate = '/';
+      acc[routeTemplate] = `${type}.${method}('${routeTemplate}', ${formattedHandler})`;
+      return acc;
+    }, {});
+
+    return map;
+  }
+
+  static normalizePathSegment(value) {
+    if (!value || value == '/') {
+      // app.[method](handler) and app.[method]('/', handler) are the same so default to empty string
+      return '';
+    }
+    if (value instanceof RegExp) {
+      const rxString = value.toString();
+      // todo: figure out best way to represent regexp in route template
+      return `/[${StringPrototypeSubstring.call(rxString, 1, rxString.length - 1)}]`;
+    }
+    return value;
+  }
+
+  static normalizePaths(paths) {
+    const ret = [];
+
+    // same as mounting as /
+    if (typeof paths == 'function') {
+      // default to ''
+      ret.push('');
+    } else if (isString(paths)) {
+      ret.push(ExpressInstrumentation.normalizePathSegment(paths));
+    } else if (Array.isArray(paths)) {
+      paths = paths.flat(Infinity).filter((v) => typeof v !== 'function');
+      if (paths.length) ret.push(...paths.map(ExpressInstrumentation.normalizePathSegment));
+      else ret.push('');
+    } else if (paths instanceof RegExp) {
+      ret.push(ExpressInstrumentation.normalizePathSegment(paths));
+    }
+
+    return ret;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.45.1",
+  "version": "1.46.0",
   "description": "Handles route discovery and observation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -20,14 +20,14 @@
     "test": "bash ../scripts/test.sh"
   },
   "dependencies": {
-    "@contrast/common": "1.34.1",
-    "@contrast/config": "1.49.1",
-    "@contrast/dep-hooks": "1.23.1",
+    "@contrast/common": "1.35.0",
+    "@contrast/config": "1.50.0",
+    "@contrast/core": "1.55.0",
+    "@contrast/dep-hooks": "1.24.0",
     "@contrast/fn-inspect": "^4.3.0",
-    "@contrast/logger": "1.27.1",
-    "@contrast/patcher": "1.26.1",
-    "@contrast/scopes": "1.24.1",
-    "semver": "^7.6.0",
-    "path-to-regexp": "^8.2.0"
+    "@contrast/logger": "1.28.0",
+    "@contrast/patcher": "1.27.0",
+    "@contrast/scopes": "1.25.0",
+    "semver": "^7.6.0"
   }
 }

package/lib/install/http.js

@@ -1,44 +0,0 @@
-/*
- * Copyright: 2025 Contrast Security, Inc
- * Contact: support@contrastsecurity.com
- * License: Commercial
-
- * NOTICE: This Software and the patented inventions embodied within may only be
- * used as part of Contrast Security’s commercial offerings. Even though it is
- * made available through public repositories, use of this Software is subject to
- * the applicable End User Licensing Agreement found at
- * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
- * between Contrast Security and the End User. The Software may not be reverse
- * engineered, modified, repackaged, sold, redistributed or otherwise used in a
- * way not consistent with the End User License Agreement.
- */
-'use strict';
-
-module.exports = function init(core) {
-  const { depHooks, patcher, routeCoverage } = core;
-
-  let handled;
-
-  return core.routeCoverage.http = {
-    install() {
-      [['http', '*'], ['https', '*'], ['spdy', '<5']].forEach(([name, version]) => {
-        depHooks.resolve({ name, version }, (_export) => {
-          if (!_export?.Server?.prototype) return;
-
-          patcher.patch(_export.Server.prototype, 'listen', {
-            name: `${name}.Server.prototype.listen`,
-            patchType: 'route-coverage',
-            post(data) {
-              data.result?.on('listening', () => {
-                if (!handled) {
-                  handled = true;
-                  routeCoverage.discoveryFinished();
-                }
-              });
-            }
-          });
-        });
-      });
-    }
-  };
-};

package/lib/normalized-url-mapper.js

@@ -1,174 +0,0 @@
-/*
- * Copyright: 2025 Contrast Security, Inc
- * Contact: support@contrastsecurity.com
- * License: Commercial
-
- * NOTICE: This Software and the patented inventions embodied within may only be
- * used as part of Contrast Security’s commercial offerings. Even though it is
- * made available through public repositories, use of this Software is subject to
- * the applicable End User Licensing Agreement found at
- * https://www.contrastsecurity.com/enduser-terms-0317a or as otherwise agreed
- * between Contrast Security and the End User. The Software may not be reverse
- * engineered, modified, repackaged, sold, redistributed or otherwise used in a
- * way not consistent with the End User License Agreement.
- */
-'use strict';
-
-const {
-  get,
-  set,
-  primordials: { StringPrototypeSubstr, StringPrototypeSplit }
-} = require('@contrast/common');
-
-class NormalizedUrlMapper {
-  constructor() {
-    this._db = {
-      // index by static routes e.g.
-      // '/' => {}
-      // '/home' => {}
-      static: new Map(),
-      // or segment-count for parameterized routes
-      // '2' => { '/users/:id', '/profile/:id' }
-      // '3' => { '/users/:id/orders', '/profile/:id/address' }
-      parameterized: {},
-      // regex is used instead of string path
-      regex: new Map(),
-      // dynamic beyond parameterization e.g. regex syntax, '/abc+', '/abc*', '/[v1|v1.1]/users'.
-      // we could key off of segment length here like we do above.
-      dynamic: {},
-    };
-    this._defaultDynamicRe = /\(|\?|\||\[|\*|\+|\{/;
-    this._hapiDynamicRe = /\(|\?|\||\[|\*|\+/;
-  }
-
-  _getPathSegments(uriPath) {
-    if (!uriPath?.length) return null;
-    return StringPrototypeSplit.call(StringPrototypeSubstr.call(uriPath, 1), '/');
-  }
-
-  _looksDynamic(segment, framework) {
-    if (framework == 'hapi') {
-      return this._hapiDynamicRe.test(segment);
-    }
-    // app.get('/::fiddle') will handle requests to '/:fiddle'
-    if (segment.includes('::')) return true;
-    return this._defaultDynamicRe.test(segment);
-  }
-
-  _looksParamaterized(segment, framework) {
-    if (framework == 'hapi') {
-      return segment.startsWith('{');
-    }
-
-    // no point iterating last character
-    for (let idx = 0; idx < segment.length - 1; idx++) {
-      // '/foo::bar' is not parameterized (fastify) - maps to '/foo:bar'
-      // make sure ':' appears by itself
-      if (
-        segment[idx] == ':' &&
-        segment[idx - 1] != ':' &&
-        segment[idx + 1] != ':'
-      ) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Tries to map a raw URL path to the "normalized" value used to declare the route.
-   * Aims to be as performant as possible.
-   * @param {string} uriPath path without queries
-   * @returns {}
-   */
-  _query(uriPath) {
-    // check if static first
-    if (this._db.static.has(uriPath)) return this._db.static.get(uriPath);
-
-    // else check dynamic routes by segment count
-    const _segments = this._getPathSegments(uriPath);
-    const entriesToCheck = this._db.parameterized[_segments.length];
-
-    if (entriesToCheck) {
-      for (const [, route] of entriesToCheck.entries()) {
-        const { segments } = route;
-        if (segments.every((seg, idx) => !seg || seg == _segments[idx])) {
-          return route;
-        }
-      }
-    }
-
-    return null;
-  }
-
-  /**
-   * Registers route discovery meta into _db.
-   * @param {import('@contrast/common').RouteInfo} routeInfo
-   */
-  handleDiscover(routeInfo) {
-    if (!routeInfo.normalizedUrl) {
-      // todo should log but don't have core
-      return;
-    }
-
-    let segments;
-    let dbIndex;
-    let isParameterized = false;
-    let isDynamic = false;
-    const isRegExp = routeInfo.normalizedUrl?.constructor?.name == 'RegExp';
-
-    if (!isRegExp) {
-      segments = this._getPathSegments(routeInfo.normalizedUrl);
-
-      for (let i = 0; i < segments.length; i++) {
-        const segment = segments[i];
-        // these heuristic checks may not scale for all frameworks. we may want to dispatch to
-        // a framework-specific strategy that can specialize in mapping to the _db entry index.
-        if (this._looksDynamic(segment, routeInfo.framework)) {
-          isDynamic = true;
-        } else if (this._looksParamaterized(segment, routeInfo.framework)) {
-          isParameterized = true;
-          // replace segments to check with undefined if parameterized
-          segments[i] = undefined;
-        }
-      }
-    }
-
-    const meta = {
-      normalizedUrl: routeInfo.normalizedUrl,
-      signature: routeInfo.signature,
-    };
-
-    if (isDynamic) {
-      dbIndex = `dynamic.${segments.length}`;
-    } else if (isParameterized) {
-      // can be both dynamic and parameterized, e.g. '/:file{.:ext}', '/api/(v1|v2)/:user'
-      // but that's not what we want in this case
-      dbIndex = `parameterized.${segments.length}`;
-      meta.segments = segments;
-    } else if (isRegExp) {
-      dbIndex = 'regex';
-    } else {
-      dbIndex = 'static';
-    }
-
-    // ensure appropriate collection is there
-    if (!get(this._db, dbIndex)) set(this._db, dbIndex, new Map());
-    get(this._db, dbIndex).set(routeInfo.normalizedUrl, meta);
-  }
-
-  /**
-   * Returns the normalizedUrl associated with raw uriPath. If the
-   * value can't be determined from internal _db, this return null.
-   * @param {string} uriPath
-   * @returns {string}
-   */
-  map(uriPath) {
-    /** @type import('@contrast/common').RouteInfo */
-    const record = this._query(uriPath);
-    return record ? record.normalizedUrl : null;
-  }
-}
-
-module.exports = NormalizedUrlMapper;