From b0bfb7ea74e3edd9db9e66139484100afd92d0f4 Mon Sep 17 00:00:00 2001
From: vmarchaud <contact@vmarchaud.fr>
Date: Sun, 26 Jan 2020 11:27:52 +0100
Subject: [PATCH] chore: add documentation about express layer store

---
 .../src/express.ts                            |  6 +++---
 .../opentelemetry-plugin-express/src/types.ts | 20 +++++++++++++++++--
 .../opentelemetry-plugin-express/src/utils.ts |  8 ++++----
 3 files changed, 25 insertions(+), 9 deletions(-)

diff --git a/packages/opentelemetry-plugin-express/src/express.ts b/packages/opentelemetry-plugin-express/src/express.ts
index 6a621b99c6c..1a0f48d4f56 100644
--- a/packages/opentelemetry-plugin-express/src/express.ts
+++ b/packages/opentelemetry-plugin-express/src/express.ts
@@ -26,7 +26,7 @@ import {
   PatchedRequest,
   Parameters,
   PathParams,
-  _MIDDLEWARES_STORE_PROPERTY,
+  _LAYERS_STORE_PROPERTY,
   ExpressPluginConfig,
   ExpressLayerType,
 } from './types';
@@ -174,7 +174,7 @@ export class ExpressPlugin extends BasePlugin<typeof express> {
         next: express.NextFunction
       ) {
         storeLayerPath(req, layerPath);
-        const route = (req[_MIDDLEWARES_STORE_PROPERTY] as string[]).join('');
+        const route = (req[_LAYERS_STORE_PROPERTY] as string[]).join('');
         const attributes: Attributes = {
           [AttributeNames.COMPONENT]: plugin._COMPONENT,
           [AttributeNames.HTTP_ROUTE]: route.length > 0 ? route : undefined,
@@ -200,7 +200,7 @@ export class ExpressPlugin extends BasePlugin<typeof express> {
           arguments[callbackIdx] = function() {
             callbackHasBeenCalled = true;
             if (!(req.route && arguments[0] instanceof Error)) {
-              (req[_MIDDLEWARES_STORE_PROPERTY] as string[]).pop();
+              (req[_LAYERS_STORE_PROPERTY] as string[]).pop();
             }
             return patchEnd(span, plugin._tracer.bind(next))();
           };
diff --git a/packages/opentelemetry-plugin-express/src/types.ts b/packages/opentelemetry-plugin-express/src/types.ts
index bcd329c3b6e..011afd37200 100644
--- a/packages/opentelemetry-plugin-express/src/types.ts
+++ b/packages/opentelemetry-plugin-express/src/types.ts
@@ -18,11 +18,27 @@ import { kLayerPatched } from './express';
 import { Request } from 'express';
 import { PluginConfig, Attributes } from '@opentelemetry/types';
 
-export const _MIDDLEWARES_STORE_PROPERTY = '__ot_middlewares';
+/**
+ * This const define where on the `request` object the plugin will mount the
+ * current stack of express layer.
+ *
+ * It is necessary because express doesnt store the different layers
+ * (ie: middleware, router etc) that it called to get to the current layer.
+ * Given that, the only way to know the route of a given layer is to
+ * store the path of where each previous layer has been mounted.
+ *
+ * ex: bodyParser > auth middleware > /users router > get /:id
+ *  in this case the stack would be: ["/users", "/:id"]
+ *
+ * ex2: bodyParser > /api router > /v1 router > /users router > get /:id
+ *  stack: ["/api", "/v1", "/users", ":id"]
+ *
+ */
+export const _LAYERS_STORE_PROPERTY = '__ot_middlewares';
 
 export type Parameters<T> = T extends (...args: infer T) => any ? T : unknown[];
 export type PatchedRequest = {
-  [_MIDDLEWARES_STORE_PROPERTY]?: string[];
+  [_LAYERS_STORE_PROPERTY]?: string[];
 } & Request;
 export type PathParams = string | RegExp | Array<string | RegExp>;
 
diff --git a/packages/opentelemetry-plugin-express/src/utils.ts b/packages/opentelemetry-plugin-express/src/utils.ts
index f688c8e409a..9da4974627e 100644
--- a/packages/opentelemetry-plugin-express/src/utils.ts
+++ b/packages/opentelemetry-plugin-express/src/utils.ts
@@ -19,7 +19,7 @@ import {
   ExpressLayer,
   AttributeNames,
   PatchedRequest,
-  _MIDDLEWARES_STORE_PROPERTY,
+  _LAYERS_STORE_PROPERTY,
   ExpressLayerType,
   IgnoreMatcher,
   ExpressPluginConfig,
@@ -31,14 +31,14 @@ import {
  * @param [value] the value to push into the array
  */
 export const storeLayerPath = (request: PatchedRequest, value?: string) => {
-  if (Array.isArray(request[_MIDDLEWARES_STORE_PROPERTY]) === false) {
-    Object.defineProperty(request, _MIDDLEWARES_STORE_PROPERTY, {
+  if (Array.isArray(request[_LAYERS_STORE_PROPERTY]) === false) {
+    Object.defineProperty(request, _LAYERS_STORE_PROPERTY, {
       enumerable: false,
       value: [],
     });
   }
   if (value === undefined) return;
-  (request[_MIDDLEWARES_STORE_PROPERTY] as string[]).push(value);
+  (request[_LAYERS_STORE_PROPERTY] as string[]).push(value);
 };
 
 /**