feat: add request layer lifecycle TracingChannels

lib/layer.js

@@ -12,6 +12,7 @@
  * @private
  */
 
+const dc = require('node:diagnostics_channel')
 const isPromise = require('is-promise')
 const pathRegexp = require('path-to-regexp')
 const debug = require('debug')('router:layer')
@@ -25,6 +26,20 @@ const deprecate = require('depd')('router')
 const TRAILING_SLASH_REGEXP = /\/+$/
 const MATCHING_GROUP_REGEXP = /\((?:\?<(.*?)>)?(?!\?)/g
 
+/**
+ * TracingChannel setup.
+ * @private
+ */
+
+const requestChannel = dc.tracingChannel && dc.tracingChannel('express:request')
+
+/**
+ * Check if the channel has subscribers.
+ */
+function shouldTrace (ch) {
+  return ch && ch.hasSubscribers !== false
+}
+
 /**
  * Expose `Layer`.
  */
@@ -111,23 +126,12 @@ Layer.prototype.handleError = function handleError (error, req, res, next) {
     return next(error)
   }
 
-  try {
-    // invoke function
-    const ret = fn(error, req, res, next)
-
-    // wait for returned promise
-    if (isPromise(ret)) {
-      if (!(ret instanceof Promise)) {
-        deprecate('handlers that are Promise-like are deprecated, use a native Promise instead')
-      }
-
-      ret.then(null, function (error) {
-        next(error || new Error('Rejected promise'))
-      })
-    }
-  } catch (err) {
-    next(err)
-  }
+  const layer = this
+  invokeWithTrace(function () {
+    return fn(error, req, res, next)
+  }, function () {
+    return { req, res, layer }
+  }, next)
 }
 
 /**
@@ -147,16 +151,37 @@ Layer.prototype.handleRequest = function handleRequest (req, res, next) {
     return next()
   }
 
-  try {
-    // invoke function
-    const ret = fn(req, res, next)
+  // Skip tracing for route dispatch wrappers (this.route is only set on
+  // the internal layer that calls route.dispatch). The actual user handlers
+  // inside the route are traced individually.
+  if (this.route) {
+    return invokeWithTrace(function () {
+      return fn(req, res, next)
+    }, null, next)
+  }
 
-    // wait for returned promise
-    if (isPromise(ret)) {
-      if (!(ret instanceof Promise)) {
-        deprecate('handlers that are Promise-like are deprecated, use a native Promise instead')
-      }
+  const layer = this
+  invokeWithTrace(function () {
+    return fn(req, res, next)
+  }, function () {
+    return { req, res, layer }
+  }, next)
+}
 
+/**
+ * Invoke a handler function, optionally wrapping it in TracingChannel.
+ * The ctxFactory is only called when tracing is active, ensuring zero
+ * allocation overhead when no subscribers are registered.
+ * @private
+ */
+
+function invokeWithTrace (exec, ctxFactory, next) {
+  try {
+    const ret = (ctxFactory && shouldTrace(requestChannel))
+      ? requestChannel.tracePromise(function () { return handlePromise(exec()) }, ctxFactory())
+      : handlePromise(exec())
+
+    if (ret) {
       ret.then(null, function (error) {
         next(error || new Error('Rejected promise'))
       })
@@ -166,6 +191,20 @@ Layer.prototype.handleRequest = function handleRequest (req, res, next) {
   }
 }
 
+/**
+ * If the return value is a promise, validate it and return it.
+ * @private
+ */
+
+function handlePromise (ret) {
+  if (isPromise(ret)) {
+    if (!(ret instanceof Promise)) {
+      deprecate('handlers that are Promise-like are deprecated, use a native Promise instead')
+    }
+    return ret
+  }
+}
+
 /**
  * Check if this route matches `path`, if so
  * populate `.params`.