@contrast/route-coverage 1.20.7 → 1.22.0

package/lib/install/fastify.js

@@ -12,99 +12,116 @@
  * engineered, modified, repackaged, sold, redistributed or otherwise used in a
  * way not consistent with the End User License Agreement.
  */
-// @ts-check
 'use strict';
 
-const { createSignature } = require('./../utils/route-info');
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { StringPrototypeToLowerCase, isString } = require('@contrast/common');
+const { getFastifyMethods } = require('./../utils/methods');
+const { patchType } = require('./../utils/route-info');
 
-/** @typedef {Parameters<import('fastify-3.0.0').onRouteHookHandler>[0]} RouteOptions */
-
-/**
- * @param {import('..').Core & {
- *  routeCoverage: import('..').RouteCoverage & {
- *    fastify?: import('@contrast/common').Installable
- *  }
- * }} core
- */
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Fastify
 module.exports = function init(core) {
+  /*
+   Fastify has two ways of defining routes:
+   1. fastify.route({ method: '<method>', url: '<url>', handler: <fn> })
+   2. fastify.<method>('<url>', <fn>)
+   (See NODE-3483 for more detail)
+  We need a way to keep track of which routes were fully declared using .route
+  So, we instrument the route method below and add identifying info to this array
+ */
+  const fullyDeclaredRoutes = [];
   const { patcher, depHooks, routeCoverage } = core;
 
-  /** @param {RouteOptions} routeOptions */
-  function registerRouteHandler(routeOptions) {
-    if (!routeOptions || !routeOptions.method || !routeOptions.url) return;
-
-    const { url, method } = routeOptions;
-    if (Array.isArray(method)) {
-      method.forEach((method) => {
-        emitRouteCoverage(url, method);
-      });
-    } else {
-      emitRouteCoverage(url, method);
+  const isFullyDeclared = (method, url) => isString(method) && fullyDeclaredRoutes.includes(method + url);
+  function fullyDeclare(method, url) {
+    if (isString(method)) {
+      fullyDeclaredRoutes.push(method + url);
+      if (method === 'GET') fullyDeclaredRoutes.push(`HEAD${url}`);
     }
-
-    // TODO
-    observationListener(routeOptions, url);
-  }
-
-  /**
-   * @param {RouteOptions} routeOptions
-   * @param {string} url
-   */
-  function observationListener(routeOptions, url) {
-    patcher.patch(routeOptions, 'handler', {
-      name: 'fastify.routeOptions.handler',
-      patchType: 'route-coverage',
-      pre(data) {
-        const [request] = data.args;
-        const { method } = request.raw;
-        const [parsedUrl] = request.url.split(/\?/);
-        emitObservation(parsedUrl, url, method);
-      },
-    });
   }
 
-  /**
-   * @param {string} url
-   * @param {string} method
-   */
-  function emitRouteCoverage(url, method) {
+  function createRouteInfo(method, url, routePath) {
+    const fullyDeclared = isFullyDeclared(method, routePath);
     method = StringPrototypeToLowerCase.call(method);
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'fastify' };
-    routeCoverage.discover(event);
-  }
 
-  /**
-   * @param {string} url
-   * @param {string} normalizedUrl
-   * @param {string=} method
-   */
-  function emitObservation(url, normalizedUrl, method) {
-    method = method && StringPrototypeToLowerCase.call(method);
-    routeCoverage.observe({ method, url, normalizedUrl });
+    const signature = fullyDeclared
+      ? `fastify.route({ method: '${method}', url: '${url}', handler: [Function] })`
+      : `fastify.${method}('${url}', [Function])`;
+
+    const routeInfo = {
+      signature,
+      url,
+      method,
+      normalizedUrl: url,
+      framework: 'fastify'
+    };
+    return routeInfo;
   }
 
   return core.routeCoverage.fastify = {
     install() {
-      depHooks.resolve(
-        { name: 'fastify', version: '>=3.0.0' },
-        /** @param {import("fastify-3.0.0").fastify} fastify */
-        (fastify) =>
-          patcher.patch(fastify, {
-            name: 'fastify.build',
-            patchType: 'route-coverage',
-            post({ result: server }) {
-              server.addHook('onRoute', (routeOptions) => {
-                registerRouteHandler(routeOptions);
-              });
+      // The routePath property used below was introduced in 3.2.0
+      return depHooks.resolve({ name: 'fastify', version: '>=3.2.0' }, (fastify) => patcher.patch(fastify, {
+        name: 'fastify',
+        patchType,
+        post({ result: server }) {
+          patcher.patch(server, 'route', {
+            name: 'server.route',
+            patchType,
+            pre({ args }) {
+              const [{ method, url }] = args;
+              if (!isString(url)) return;
+
+              if (Array.isArray(method)) {
+                method.forEach((verb) => {
+                  fullyDeclare(verb, url);
+                });
+              } else {
+                fullyDeclare(method, url);
+              }
+            }
+          });
+          server.addHook('onRoute', (routeOptions) => {
+            if (!routeOptions) return;
+
+            const { method, url, routePath } = routeOptions;
+            if (!method || !url || !routePath || !isString(routePath)) return;
+
+            let routeInfo;
+            const FASTIFY_METHODS = getFastifyMethods(server.version);
+            if (Array.isArray(method)) {
+              // If a route was defined using .all this method property will be an
+              // array of all methods supported by Fastify
+              if (FASTIFY_METHODS.every(m => method.includes(m))) {
+                routeInfo = createRouteInfo('all', url, routePath);
+                routeCoverage.discover(routeInfo);
+              } else {
+                method.forEach((verb) => {
+                  routeInfo = createRouteInfo(verb, url, routePath);
+                  routeCoverage.discover(routeInfo);
+                });
+              }
+            } else {
+              routeInfo = createRouteInfo(method, url, routePath);
+              routeCoverage.discover(routeInfo);
+            }
 
-              server.addHook('onReady', (done) => {
-                routeCoverage.discoveryFinished();
-                return done();
-              });
-            },
-          }),
-      );
+            patcher.patch(routeOptions, 'handler', {
+              name: 'fastify.routeOptions.handler',
+              patchType,
+              pre({ args }) {
+                const [req] = args;
+                const method = StringPrototypeToLowerCase.call(req.raw?.method);
+                const [url] = req.url.split(/\?/);
+                routeCoverage.observe({ ...routeInfo, url, method });
+              },
+            });
+          });
+          server.addHook('onReady', (done) => {
+            routeCoverage.discoveryFinished();
+            return done();
+          });
+        }
+      }));
     }
   };
 };

package/lib/install/fastify.test.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const scopes = require('@contrast/scopes');
+const patcher = require('@contrast/patcher');
+const mocks = require('@contrast/test/mocks');
+const { getFastifyMethods } = require('../utils/methods');
+
+describe('route-coverage fastify', function () {
+  let core, serverMock, framework;
+
+  beforeEach(function () {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.routeCoverage = mocks.routeCoverage();
+    core.scopes = scopes(core);
+    core.depHooks = mocks.depHooks();
+    core.patcher = patcher(core);
+
+    serverMock = {
+      addHook: sinon.stub(),
+      route: sinon.stub(),
+      version: '4.4.0'
+    };
+
+    let fastify;
+    framework = 'fastify';
+    core.depHooks.resolve.callsFake((desc, cb) => {
+      fastify = cb(() => serverMock);
+    });
+
+    require('./fastify')(core).install();
+
+    fastify();
+  });
+
+  it('skips instrumenting if route options does not exist', function () {
+    serverMock.addHook.withArgs('onRoute').yield();
+    expect(core.routeCoverage.discover).not.to.have.been.called;
+  });
+
+  it('skips instrumenting if there is no method provided', function () {
+    serverMock.addHook.withArgs('onRoute').yield({});
+    expect(core.routeCoverage.discover).not.to.have.been.called;
+  });
+
+  it('skips instrumenting if there is no url provided', function () {
+    serverMock.addHook.withArgs('onRoute').yield({ method: 'GET' });
+    expect(core.routeCoverage.discover).not.to.have.been.called;
+  });
+
+  it('discovers a route with a single method', function () {
+    serverMock.addHook
+      .withArgs('onRoute')
+      .yield({ method: 'GET', url: '/test/route', routePath: '/test/route' });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.get('/test/route', [Function])",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'get',
+      framework
+    });
+    expect(core.routeCoverage.discover).to.have.been.called;
+    expect(core.routeCoverage.discover).to.have.callCount(1);
+  });
+
+  it('discovers a fully declared (.route) route with a single method', function () {
+    serverMock.route({ method: 'GET', url: '/test/route' });
+    serverMock.addHook
+      .withArgs('onRoute')
+      .yield({ method: 'GET', url: '/test/route', routePath: '/test/route' });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.route({ method: 'get', url: '/test/route', handler: [Function] })",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'get',
+      framework
+    });
+    expect(core.routeCoverage.discover).to.have.been.called;
+    expect(core.routeCoverage.discover).to.have.callCount(1);
+  });
+
+  it('discovers a route with multiple methods', function () {
+    serverMock.addHook.withArgs('onRoute').yield({
+      method: ['GET', 'POST'],
+      url: '/test/route',
+      routePath: '/test/route'
+    });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.get('/test/route', [Function])",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'get',
+      framework
+    });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.post('/test/route', [Function])",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'post',
+      framework
+    });
+
+    expect(core.routeCoverage.discover).to.have.callCount(2);
+  });
+
+  it('discovers a route with all methods', function () {
+    const FASTIFY_METHODS = getFastifyMethods('4.4.0');
+    serverMock.addHook.withArgs('onRoute').yield({
+      method: FASTIFY_METHODS,
+      url: '/test/route',
+      routePath: '/test/route'
+    });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.all('/test/route', [Function])",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'all',
+      framework
+    });
+  });
+
+  it('discovers a fully declared route (.route) with multiple methods', function () {
+    serverMock.route({ method: ['GET', 'POST'], url: '/test/route' });
+
+    serverMock.addHook.withArgs('onRoute').yield({
+      method: ['GET', 'POST'],
+      url: '/test/route',
+      routePath: '/test/route'
+    });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.route({ method: 'get', url: '/test/route', handler: [Function] })",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'get',
+      framework
+    });
+
+    expect(core.routeCoverage.discover).to.have.been.calledWith({
+      signature: "fastify.route({ method: 'post', url: '/test/route', handler: [Function] })",
+      url: '/test/route',
+      normalizedUrl: '/test/route',
+      method: 'post',
+      framework
+    });
+
+    expect(core.routeCoverage.discover).to.have.callCount(2);
+  });
+
+  it('signals that discovery is finished when the onReady hook is triggered', function () {
+    serverMock.addHook.withArgs('onReady').yield(sinon.stub());
+
+    expect(core.routeCoverage.discoveryFinished).to.have.been.calledOnce;
+  });
+
+  it('observes a route when the route handler is called', function () {
+    const routeOptions = {
+      method: 'GET',
+      url: '/test/route',
+      routePath: '/test/route',
+      handler: sinon.stub(),
+    };
+
+    serverMock.addHook.withArgs('onRoute').yield(routeOptions);
+    routeOptions.handler({ raw: { method: 'GET' }, url: '/test/route' });
+
+    expect(core.routeCoverage.observe).to.have.been.calledWith({
+      signature: "fastify.get('/test/route', [Function])",
+      url: '/test/route',
+      method: 'get',
+      normalizedUrl: '/test/route',
+      framework: 'fastify'
+    });
+  });
+
+  it('removes query string from url before reporting observation', function () {
+    const routeOptions = {
+      method: 'GET',
+      url: '/test/route',
+      routePath: '/test/route',
+      handler: sinon.stub(),
+    };
+
+    serverMock.addHook.withArgs('onRoute').yield(routeOptions);
+    routeOptions.handler({ raw: { method: 'GET' }, url: '/test/route?input=foo' });
+
+    expect(core.routeCoverage.observe).to.have.been.calledWith({
+      signature: "fastify.get('/test/route', [Function])",
+      url: '/test/route',
+      method: 'get',
+      normalizedUrl: '/test/route',
+      framework: 'fastify'
+    });
+  });
+
+});

package/lib/install/hapi.js

@@ -15,14 +15,21 @@
 'use strict';
 
 const { StringPrototypeToLowerCase } = require('@contrast/common');
-const { createSignature, patchType } = require('./../utils/route-info');
+const { patchType } = require('./../utils/route-info');
 
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Hapi
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
 
   function emitRouteCoverage(url, method) {
     method = StringPrototypeToLowerCase.call(method);
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'hapi' };
+    const event = {
+      signature: `server.route({ method: '${method}', path: '${url}', handler: [Function] })`,
+      url,
+      method,
+      normalizedUrl: url,
+      framework: 'hapi'
+    };
     routeCoverage.discover(event);
   }
 

package/lib/install/hapi.test.js

@@ -0,0 +1,125 @@
+'use strict';
+
+const { expect } = require('chai');
+const sinon = require('sinon');
+const scopes = require('@contrast/scopes');
+const patcher = require('@contrast/patcher');
+const mocks = require('@contrast/test/mocks');
+
+describe('route-coverage hapi', function () {
+  let core, route, _core, hapi, framework;
+
+  beforeEach(function () {
+    core = mocks.core();
+    core.logger = mocks.logger();
+    core.routeCoverage = mocks.routeCoverage();
+    core.scopes = scopes(core);
+    core.depHooks = mocks.depHooks();
+    core.patcher = patcher(core);
+
+    route = {
+      settings: {
+        handler: sinon.stub()
+      }
+    };
+
+    _core = {
+      router: {
+        add() {
+          return { route };
+        }
+      }
+    };
+
+    hapi = {
+      server() {
+        return { _core };
+      },
+      Server() {
+        return { _core };
+      }
+    };
+    framework = 'hapi';
+
+    core.depHooks.resolve.withArgs({ name: '@hapi/hapi', version: '>=18 <22' }).yields(hapi);
+    require('./hapi')(core).install();
+  });
+
+
+  ['server', 'Server'].forEach((server) => {
+
+    it('does not report a non-existent route', function () {
+      const hapiServer = hapi[server]();
+      hapiServer._core.router.add();
+      expect(core.routeCoverage.discover).not.to.have.been.called;
+    });
+
+    it('does not report a route missing a method', function () {
+      const hapiServer = hapi[server]();
+      hapiServer._core.router.add({ path: '/foo' });
+      expect(core.routeCoverage.discover).not.to.have.been.called;
+    });
+
+    it('does not report a route missing a path', function () {
+      const hapiServer = hapi[server]();
+      hapiServer._core.router.add({ method: 'GET' });
+      expect(core.routeCoverage.discover).not.to.have.been.called;
+    });
+
+    it('discovers a route with a single method', function () {
+      const hapiServer = hapi[server]();
+      hapiServer._core.router.add({ method: 'GET', path: '/foo' });
+
+      expect(core.routeCoverage.discover).to.have.been.calledWith({
+        signature: "server.route({ method: 'get', path: '/foo', handler: [Function] })",
+        url: '/foo',
+        normalizedUrl: '/foo',
+        method: 'get',
+        framework
+      });
+    });
+
+    it('discovers a route with multiple methods', function () {
+      const hapiServer = hapi[server]();
+      hapiServer._core.router.add({ method: ['GET', 'PUT'], path: '/foo' });
+
+      expect(core.routeCoverage.discover).to.have.been.calledWith({
+        signature: "server.route({ method: 'get', path: '/foo', handler: [Function] })",
+        url: '/foo',
+        normalizedUrl: '/foo',
+        method: 'get',
+        framework
+      });
+
+      expect(core.routeCoverage.discover).to.have.been.calledWith({
+        signature: "server.route({ method: 'put', path: '/foo', handler: [Function] })",
+        url: '/foo',
+        normalizedUrl: '/foo',
+        method: 'put',
+        framework
+      });
+    });
+
+    it('observes a route when a route handler is exercised', async function () {
+      const hapiServer = hapi[server]();
+      const { route } = hapiServer._core.router.add({ method: 'get', path: '/foo' });
+      route.settings.handler({ method: 'get', path: '/foo', route: { path: '/foo' } });
+      expect(core.routeCoverage.observe).to.have.been.calledWith({
+        url: '/foo',
+        normalizedUrl: '/foo',
+        method: 'get'
+      });
+    });
+
+    it('observes a route when a route contains parameters', async function () {
+      const hapiServer = hapi[server]();
+      const { route } = hapiServer._core.router.add({ method: 'get', path: '/foo/{id}' });
+      route.settings.handler({ method: 'get', path: '/foo/1', route: { path: '/foo/{id}' } });
+      expect(core.routeCoverage.observe).to.have.been.calledWith({
+        url: '/foo/1',
+        normalizedUrl: '/foo/{id}',
+        method: 'get'
+      });
+    });
+  });
+});

package/lib/install/koa.js

@@ -14,56 +14,76 @@
  */
 'use strict';
 
-const { StringPrototypeToLowerCase } = require('@contrast/common');
+const { METHODS } = require('./../utils/methods');
+const { StringPrototypeToLowerCase, isString } = require('@contrast/common');
 const { createSignature, patchType } = require('./../utils/route-info');
 
+// Spec: https://contrast.atlassian.net/wiki/spaces/NOD/pages/3454861621/Node.js+Agent+Route+Signatures#Koa
 module.exports = function init(core) {
   const { patcher, depHooks, routeCoverage } = core;
 
-  function emitRouteCoverage(url, method) {
-    const event = { signature: createSignature(url, method), url, method, normalizedUrl: url, framework: 'koa' };
-    routeCoverage.discover(event);
-  }
-
-  const routeObservationPathClosure = ({ path }) =>
-    async function routeObservationMiddleware(ctx, next) {
-      const req = ctx.request;
-
-      if (req) {
-        const { url: reqUrl, method } = req;
-        const [url] = reqUrl.split(/\?/);
-        routeCoverage.observe({ url, method: StringPrototypeToLowerCase.call(method || ''), normalizedUrl: path });
-      }
-
-      await next();
+  function createRouteInfo(method, url) {
+    method = StringPrototypeToLowerCase.call(method);
+    const routeInfo = {
+      signature: createSignature(url, method),
+      url,
+      method,
+      normalizedUrl: url,
+      framework: 'koa'
     };
+    return routeInfo;
+  }
 
   return core.routeCoverage.koa = {
     install() {
-      ['@koa/router', 'koa-router'].forEach((name) => {
-        depHooks.resolve({ name }, (_export) => {
-          if (!_export?.prototype?.register) return;
+      depHooks.resolve({ name: 'koa', version: '>=2.3.0' }, (Koa) => {
+        // Koa uses its own routing library @koa/router to define routes before
+        // mounting them on the app with .use so instrumenting use and traversing
+        // the constructed routes is the more technically correct approach than
+        // instrumenting the routing library
+        patcher.patch(Koa.prototype, 'use', {
+          name: 'Koa.prototype.use',
+          patchType,
+          pre: ({ args }) => {
+            if (args?.length === 0) return;
+            const [router] = args;
 
-          patcher.patch(_export.prototype, 'register', {
-            name: 'koaRouter.prototype',
-            patchType,
-            post: ({ args, result: layer }) => {
-              const [path, methods] = args;
-              if (!path || !methods || Array.isArray(path)) {
-                return;
-              }
+            if (!router?.router) return;
 
+            router.router.stack.forEach((Layer) => {
+              const { methods, path } = Layer;
+              if (!path || !isString(path)) return;
+
+              let routeInfo;
               if (methods.length === 0) {
-                emitRouteCoverage(path, 'use');
+                routeInfo = createRouteInfo('use', path);
+                routeCoverage.discover(routeInfo);
+              } else if (METHODS.every(m => methods.includes(m))) {
+                // If a route was defined using .all this methods property will be an
+                // array of all methods supported by Koa
+                routeInfo = createRouteInfo('all', path);
+                routeCoverage.discover(routeInfo);
               } else {
                 methods.forEach((method) => {
-                  emitRouteCoverage(path, StringPrototypeToLowerCase.call(method || ''));
+                  routeInfo = createRouteInfo(method, path);
+                  routeCoverage.discover(routeInfo);
                 });
               }
 
-              layer.stack.unshift(routeObservationPathClosure({ path }).bind(this));
-            }
-          });
+              if (!Layer.stack || Layer.stack.length === 0) return;
+              async function observationMiddleware(ctx, next) {
+                if (!ctx.request) return;
+                const { url: reqUrl, method } = ctx.request;
+                const [url] = reqUrl.split(/\?/);
+                routeCoverage.observe({ ...routeInfo, url, method: StringPrototypeToLowerCase.call(method) });
+                await next();
+              }
+              // If two routes share middleware, the same stack is used
+              // To add our observation middleware without adding them to all routes
+              // we need to create a shallow copy
+              Layer.stack = [observationMiddleware, ...Layer.stack];
+            });
+          }
         });
       });
     }