@contrast/route-coverage 1.29.0 → 1.30.0

package/lib/index.js

@@ -17,6 +17,7 @@
 
 const { callChildComponentMethodsSync, Event } = require('@contrast/common');
 const { routeIdentifier } = require('./utils/route-info');
+const NormalizedUrlMapper = require('./normalized-url-mapper');
 
 /**
  * @param {import('.').Core & {
@@ -33,19 +34,24 @@ module.exports = function init(core) {
   /** @type {Map<string, import('@contrast/common').RouteInfo>} */
   const routeInfo = new Map();
   const recentlyObserved = new Set();
-
   const routeQueue = new Map();
+
   const routeCoverage = core.routeCoverage = {
+    _normalizedUrlMapper: new NormalizedUrlMapper(),
+
+    uriPathToNormalizedUrl(uriPath) {
+      return this._normalizedUrlMapper.map(uriPath);
+    },
+
     discover(info) {
       logger.trace({ info }, 'Discovered new route:');
-
       routeInfo.set(routeIdentifier(info), info);
+      this._normalizedUrlMapper.handleDiscover(info);
     },
 
     discoveryFinished() {
       const routes = Array.from(routeInfo.values());
       messages.emit(Event.ROUTE_COVERAGE_DISCOVERY_FINISHED, routes);
-
       this.discover = this.queue;
       this.discoveryFinished = this.queuingFinished;
     },

package/lib/normalized-url-mapper.js

@@ -0,0 +1,174 @@
+/*
+ * Copyright: 2024 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;

package/lib/normalized-url-mapper.test.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { expect } = require('chai');
+const frameworkRoutingData = require('@contrast/test/data/framework-routing-data');
+const NormalizedUrlMapper = require('./normalized-url-mapper');
+
+describe('route-coverage NormalizedUrlMapper', function() {
+  const testData = Object.values(frameworkRoutingData()).flatMap((a) => a);
+
+  describe('.map', function() {
+    it('returns null if no discovery events were handled', function() {
+      const mapper = new NormalizedUrlMapper();
+      [
+        '/user/1',
+        '/user/2',
+        '/user/3',
+        '/user/4',
+        '/user/1/cart',
+        '/user/2/cart',
+        '/user/3/cart',
+        '/user/4/cart',
+        '/products/all',
+        '/products/all',
+        '/products/1',
+        '/products/2',
+        '/products/3',
+        '/products/4',
+      ].forEach((uriPath) => {
+        expect(mapper.map(uriPath)).to.be.null;
+      });
+    });
+
+    it('returns normalizedUrl mapped from generic uriPath', function() {
+      const mapper = new NormalizedUrlMapper();
+      testData.forEach((d) => mapper.handleDiscover(d.routeInfo));
+      testData.forEach((td) => {
+        const { routeInfo, paths, hasMapping } = td;
+
+        for (const uriPath of paths) {
+          // todo - dynamic and regex paths
+          if (hasMapping === false) {
+            expect(mapper.map(uriPath)).to.be.null;
+          } else {
+            expect(mapper.map(uriPath)).to.equal(routeInfo.normalizedUrl);
+          }
+        }
+      });
+    });
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrast/route-coverage",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Handles route discovery and observation",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Contrast Security <nodejs@contrastsecurity.com> (https://www.contrastsecurity.com)",
@@ -18,12 +18,12 @@
   },
   "dependencies": {
     "@contrast/common": "1.26.0",
-    "@contrast/config": "1.35.0",
-    "@contrast/dep-hooks": "1.8.0",
+    "@contrast/config": "1.36.0",
+    "@contrast/dep-hooks": "1.9.0",
     "@contrast/fn-inspect": "^4.3.0",
-    "@contrast/logger": "1.13.0",
-    "@contrast/patcher": "1.12.0",
-    "@contrast/scopes": "1.9.0",
+    "@contrast/logger": "1.14.0",
+    "@contrast/patcher": "1.13.0",
+    "@contrast/scopes": "1.10.0",
     "semver": "^7.6.0"
   }
 }