@gasket/plugin-elastic-apm 7.0.0-next.5 → 7.0.0-next.50

package/README.md

@@ -4,28 +4,22 @@ Adds Elastic APM instrumentation to your application
 
 ## Installation
 
-#### New apps
-
 ```
-gasket create <app-name> --plugins @gasket/plugin-elastic-apm
+npm i @gasket/plugin-elastic-apm
 ```
 
-#### Existing apps
+Update your `gasket` file plugin configuration:
 
-```
-npm install @gasket/plugin-elastic-apm elastic-apm-node
-```
+```diff
+// gasket.js
 
-Modify `plugins` section of your `gasket.config.js`:
++ import pluginElasticApm from '@gasket/plugin-elastic-apm';
 
-```diff
-module.exports = {
-  plugins: {
-    add: [
-+      '@gasket/plugin-elastic-apm'
-    ]
-  }
-}
+export default makeGasket({
+  plugins: [
++   pluginElasticApm
+  ]
+});
 ```
 
 Add a `--require` flag to a `package.json` start script:
@@ -77,14 +71,14 @@ configured under `elasticAPM` in the `gasket.config.js`.
 If your application’s users send session credentials or any other sensitive
 information in their cookies, you may wish to filter them out before they are
 stored in Elasticsearch. Specify a list of cookie names to redact in
-`gasket.config.js`:
+`gasket.js`:
 
 ```js
-module.exports = {
+export default makeGasket({
   elasticAPM: {
     sensitiveCookies: ['my_jwt', 'userFullName']
   }
-};
+});
 ```
 
 #### Custom Filtering Sensitive Fields
@@ -131,10 +125,15 @@ request details are as follows:
 | `res`    | The HTTP response or framework-specific wrapper around it |
 
 ```javascript
-// /lifecycles/apm-transaction.js
-
-module.exports = (gasket, transaction, { req, res }) => {
-  transaction.setLabel('language', req.headers['accept-language']);
+// example-plugin.js
+
+export default {
+  name: 'example-plugin',
+  hooks: {
+    apmTransaction(gasket, transaction, { req, res }) => {
+      transaction.setLabel('language', req.headers['accept-language']);
+    }
+  }
 }
 ```
 

package/lib/actions.js

@@ -0,0 +1,21 @@
+/** @type {import('@gasket/core').HookHandler<'actions'>} */
+module.exports = function actions(gasket) {
+  return {
+    async getApmTransaction(req) {
+      const apm = require('elastic-apm-node');
+
+      if (!apm?.isStarted()) {
+        return;
+      }
+
+      const transaction = apm.currentTransaction;
+      if (!transaction) {
+        return;
+      }
+
+      await gasket.exec('apmTransaction', transaction, { req });
+
+      return transaction;
+    }
+  };
+};

package/lib/configure.js

@@ -0,0 +1,34 @@
+/**
+ * Determines if the Elastic APM agent has sufficient config to be active
+ * @param {import('./index').ExtendedAgentConfigOptions} config Apm agent config
+ * @param {NodeJS.ProcessEnv} env Environment variables
+ * @returns {boolean} A combined config object
+ */
+const isActive = (config, env) => {
+  const { active, serverUrl, secretToken } = config;
+
+  if (active || env.ELASTIC_APM_ACTIVE) {
+    return true;
+  }
+
+  const combined = {
+    serverUrl: serverUrl || env.ELASTIC_APM_SERVER_URL,
+    secretToken: secretToken || env.ELASTIC_APM_SECRET_TOKEN
+  };
+
+  if (combined.serverUrl && combined.secretToken) {
+    return true;
+  }
+
+  return false;
+};
+
+/** @type {import('@gasket/core').HookHandler<'configure'>} */
+module.exports = function configure(gasket, config) {
+  config.elasticAPM = config.elasticAPM || {};
+
+  // eslint-disable-next-line no-process-env
+  config.elasticAPM.active = isActive(config.elasticAPM, process.env);
+
+  return { ...config };
+};

package/lib/cookies.js

@@ -1,8 +1,7 @@
 /**
  * Returns an array of cookie names which are considered sensitive because they
  * may contain session credential or PII
- *
- * @param {*} config the Gasket config object
+ * @param {import('@gasket/core').GasketConfig} config the Gasket config
  * @returns {string[]} an array of cookie names
  */
 const sensitiveCookies = (config) => {
@@ -18,40 +17,42 @@ const sensitiveCookies = (config) => {
 
 /**
  * Redacts the contents of user-specified sensitive cookies
- *
- * @param {object} config The Gasket config
- * @param {object} payload The APM payload
- * @returns {object} a modified version of the incoming APM payload
+ * @type {import('./index').filterSensitiveCookies}
  */
-const filterSensitiveCookies = (config) => (payload) => {
-  const cookiesToRedact = sensitiveCookies(config);
+const filterSensitiveCookies = function (config) {
+  return function (payload) {
+    const cookiesToRedact = sensitiveCookies(config);
 
-  if (
-    payload.context &&
+    if (
+      payload.context &&
     payload.context.request &&
     payload.context.request.headers &&
     payload.context.request.headers.cookie
-  ) {
-    let cookie = payload.context.request.headers.cookie;
-    cookiesToRedact.forEach((sc) => {
-      cookie = cookie.replace(new RegExp(sc + '=([^;]+)'), sc + '=[REDACTED]');
-    });
+    ) {
+      let cookie = payload.context.request.headers.cookie;
+      cookiesToRedact.forEach((sc) => {
+        cookie = cookie.replace(
+          new RegExp(sc + '=([^;]+)'),
+          sc + '=[REDACTED]'
+        );
+      });
 
-    payload.context.request.headers.cookie = cookie;
-  }
+      payload.context.request.headers.cookie = cookie;
+    }
 
-  if (payload.context &&
+    if (payload.context &&
     payload.context.request &&
     payload.context.request.cookies
-  ) {
-    cookiesToRedact.forEach((sc) => {
-      if (sc in payload.context.request.cookies) {
-        payload.context.request.cookies[sc] = '[REDACTED]';
-      }
-    });
-  }
+    ) {
+      cookiesToRedact.forEach((sc) => {
+        if (sc in payload.context.request.cookies) {
+          payload.context.request.cookies[sc] = '[REDACTED]';
+        }
+      });
+    }
 
-  return payload;
+    return payload;
+  };
 };
 
 module.exports = {

package/lib/create.js

@@ -0,0 +1,24 @@
+const { name, version, devDependencies } = require('../package.json');
+
+/** @type {import('@gasket/core').HookHandler<'create'>} */
+module.exports = function create(gasket, { pkg, files, gasketConfig }) {
+  const generatorDir = `${__dirname}/../generator`;
+
+  gasketConfig.addPlugin('pluginElasticApm', name);
+
+  pkg.add('dependencies', {
+    [name]: `^${version}`,
+    'dotenv': devDependencies.dotenv,
+    'elastic-apm-node': devDependencies['elastic-apm-node']
+  });
+
+  pkg.extend((current) => {
+    return {
+      scripts: {
+        start: `NODE_OPTIONS=--import=./setup.js ${current.scripts.start}`
+      }
+    };
+  });
+
+  files.add(`${generatorDir}/*`);
+};

package/lib/index.d.ts

@@ -1,25 +1,44 @@
 import type { IncomingMessage, ServerResponse } from 'http';
-import type { AgentConfigOptions, Transaction } from 'elastic-apm-node';
-import type { MaybeAsync } from '@gasket/engine';
+import type { AgentConfigOptions, Transaction, Payload } from 'elastic-apm-node';
+import type { MaybeAsync, GasketConfig } from '@gasket/core';
+import type { GasketData } from '@gasket/data';
+import type { GasketRequest } from '@gasket/core';
+import type { Request } from 'express';
 
-declare module '@gasket/engine' {
+export function filterSensitiveCookies(config: GasketConfig): function(Payload): Payload;
+
+export interface ExtendedAgentConfigOptions extends AgentConfigOptions {
+  sensitiveCookies?: Array<string>;
+}
+
+declare module '@gasket/core' {
   export interface GasketConfig {
-    elasticAPM?: AgentConfigOptions & {
-      sensitiveCookies?: Array<string>
-    },
+    elasticAPM?: ExtendedAgentConfigOptions;
   }
 
   export interface Gasket {
     apm?: Agent;
   }
 
+  export interface GasketActions {
+    async getApmTransaction(
+      req: IncomingMessage | Request
+    ): Promise<Transaction | void>
+  }
+
   export interface HookExecTypes {
     apmTransaction(
       transaction: Transaction,
-      details: {
-        req: IncomingMessage,
-        res: ServerResponse
+      context: {
+        req: IncomingMessage | Request;
       }
-    ): MaybeAsync<void>
+    ): MaybeAsync<void>;
   }
 }
+
+export default {
+  name: '@gasket/plugin-elastic-apm',
+  version: '',
+  description: '',
+  hooks: {}
+};

package/lib/index.js

@@ -1,77 +1,25 @@
-const { filterSensitiveCookies } = require('./cookies');
-const middleware = require('./middleware');
-const { devDependencies } = require('../package.json');
-
-/**
- * Determines if the Elastic APM agent has sufficient config to be active
- * @param {object} config gasket config
- * @param {object<string,any>} env environment variables
- * @returns {boolean} A combined config object
- */
-const isActive = (config, env) => {
-  const { active } = config;
+/// <reference types="create-gasket-app" />
+/// <reference types="@gasket/plugin-metadata" />
 
-  if (active || env.ELASTIC_APM_ACTIVE) {
-    return true;
-  }
-
-  if (env.ELASTIC_APM_SERVER_URL && env.ELASTIC_APM_SECRET_TOKEN) {
-    return true;
-  }
-
-  return false;
-};
-
-module.exports = {
+const actions = require('./actions');
+const create = require('./create');
+const middleware = require('./middleware');
+const configure = require('./configure');
+const {
+  name,
+  version,
+  description
+} = require('../package.json');
+
+/** @type {import('@gasket/core').Plugin} */
+const plugin = {
+  name,
+  version,
+  description,
   hooks: {
-    configure: {
-      handler: (gasket, config) => {
-        config.elasticAPM = config.elasticAPM || {};
-
-        // eslint-disable-next-line no-process-env
-        config.elasticAPM.active = isActive(config.elasticAPM, process.env);
-
-        return { ...config };
-      }
-    },
-    preboot: {
-      handler: async (gasket) => {
-        const { config, logger, command } = gasket;
-
-        if (command && command.id === 'local') return;
-
-        // prefer app-level dependency in case of duplicates
-        const apm = require(require.resolve('elastic-apm-node', {
-          paths: [config.root, __dirname]
-        }));
-
-        if (!apm.isStarted()) {
-          logger.warn(
-            'Elastic APM agent is not started. Use `--require ./setup.js`'
-          );
-        }
-
-        apm.addFilter(filterSensitiveCookies(config));
-      }
-    },
-    create: {
-      timing: {
-        after: ['@gasket/plugin-start']
-      },
-      handler(gasket, { pkg, files }) {
-        const generatorDir = `${__dirname}/../generator`;
-
-        pkg.add('dependencies', {
-          'elastic-apm-node': devDependencies['elastic-apm-node'],
-          'dotenv': devDependencies.dotenv
-        });
-        pkg.add('scripts', {
-          start: 'gasket start --require ./setup.js'
-        });
-
-        files.add(`${generatorDir}/*`);
-      }
-    },
+    actions,
+    configure,
+    create,
     middleware,
     metadata(gasket, meta) {
       return {
@@ -104,3 +52,5 @@ module.exports = {
     }
   }
 };
+
+module.exports = plugin;

package/lib/middleware.js

@@ -1,26 +1,12 @@
-/* eslint-disable spaced-comment */
-// @ts-check
-/// <reference types="./index" />
-/// <reference types="../../gasket-plugin-nextjs" />
-
-/**
- * @typedef {import('@gasket/engine').Gasket} Gasket
- * @typedef {import('http').IncomingMessage}  Request
- * @typedef {import('http').ServerResponse}   Response
- */
-
-const { callbackify } = require('util');
+/// <reference types="@gasket/plugin-express" />
 
 /**
  * Middleware for customizing transactions
- *
- * @param {Gasket}    gasket  The Gasket engine
- * @param {Request}   req     The HTTP request being handled
- * @param {Response}  res     The server response
+ * @param {import('@gasket/core').Gasket} gasket - The Gasket engine
+ * @param {import('http').IncomingMessage} req - The HTTP request being handled
  */
-async function customizeTransaction(gasket, req, res) {
-  const apm = gasket.apm;
-
+async function customizeTransaction(gasket, req) {
+  const apm = require('elastic-apm-node');
   if (!apm?.isStarted()) {
     return;
   }
@@ -30,12 +16,26 @@ async function customizeTransaction(gasket, req, res) {
     return;
   }
 
-  await gasket.exec('apmTransaction', transaction, { req, res });
+  await gasket.exec('apmTransaction', transaction, { req });
 }
 
-module.exports = (gasket) => {
+/**
+ * Add middleware to gather config details
+ * @type {import('@gasket/core').HookHandler<'middleware'>}
+ */
+module.exports = function middleware(gasket) {
+  const apm = require('elastic-apm-node');
+  // eslint-disable-next-line no-undefined
+  const isStarted = apm.isStarted() || undefined;
   return (
-    gasket.apm
-    && [callbackify(async (req, res) => customizeTransaction(gasket, req, res))]
+    isStarted &&
+    async function apmTransactionMiddleware(req, res, next) {
+      try {
+        customizeTransaction(gasket, req);
+      } catch (error) {
+        return next(error);
+      }
+      next();
+    }
   );
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@gasket/plugin-elastic-apm",
-  "version": "7.0.0-next.5",
+  "version": "7.0.0-next.50",
   "description": "Adds Elastic APM instrumentation to your application",
-  "main": "lib",
+  "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
     "lib"
@@ -14,8 +14,9 @@
     "test:runner": "jest test/*.test.js",
     "test:watch": "npm run test:runner -- --watch",
     "test:coverage": "npm run test:runner -- --coverage --coverageReporters text",
-    "posttest": "npm run lint",
-    "report": "npm run test:runner -- --coverage --coverageReporters lcov"
+    "posttest": "npm run lint && npm run typecheck",
+    "typecheck": "tsc",
+    "typecheck:watch": "tsc --watch"
   },
   "repository": {
     "type": "git",
@@ -40,24 +41,27 @@
   },
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-elastic-apm",
   "devDependencies": {
-    "@gasket/engine": "^7.0.0-next.5",
-    "dot-env": "^0.0.1",
+    "@gasket/core": "^7.0.0-next.50",
+    "dotenv": "^16.4.5",
     "elastic-apm-node": "^4.4.1",
     "eslint": "^8.56.0",
-    "eslint-config-godaddy": "^7.0.2",
-    "eslint-plugin-jest": "^27.6.3",
+    "eslint-config-godaddy": "^7.1.1",
+    "eslint-plugin-jest": "^28.6.0",
     "eslint-plugin-json": "^3.1.0",
-    "eslint-plugin-unicorn": "^44.0.0",
+    "eslint-plugin-unicorn": "^55.0.0",
     "jest": "^29.7.0",
-    "nyc": "^15.1.0"
+    "nyc": "^15.1.0",
+    "typescript": "^5.4.5"
   },
   "eslintConfig": {
     "extends": [
       "godaddy",
-      "plugin:jest/recommended"
+      "plugin:jest/recommended",
+      "plugin:jsdoc/recommended-typescript-flavor"
     ],
     "plugins": [
-      "unicorn"
+      "unicorn",
+      "jsdoc"
     ],
     "rules": {
       "unicorn/filename-case": "error"
@@ -66,5 +70,5 @@
   "jest": {
     "testEnvironment": "node"
   },
-  "gitHead": "b3b132ef284ac43616794283b969c23c45c0a90e"
+  "gitHead": "e7cfec6a118cf087c6532c23dc31170f4b15d182"
 }