feat(core, node): portable Express integration

This extracts the functionality from the OTel Express intstrumentation,
replacing it with a portable standalone integration in `@sentry/core`,
which can be extended and applied to patch any Express module import in
whatever way makes sense for the platform in question.

Currently in node, that is still an OpenTelemetry intstrumentation, but
just handling the automatic module load instrumentation, not the entire
tracing integration.

This is somewhat a proof of concept, to see what it takes to port a
fairly invovled OTel integration into a state where it can support all
of the platforms that we care about, but it does impose a bit less of a
translation layer between OTel and Sentry semantics (for example, no
need to use the no-op `span.recordException()`).

The only user-visible change (beyond the additional export in
`@sentry/core`, of course) is that spans have an origin of
`auto.http.express` rather than `auto.http.otel.express`, since it's no
longer technically an otel integration.

Obviously this is not a full clean-room reimplementation, and relies on
the fact that the opentelemetry-js-contrib project is Apache 2.0
licensed. I included the link to the upstream license in the index file
for the Express integration, but there may be a more appropriate way to
ensure that the license is respected properly. It was arguably a
derivative work already, but simple redistribution is somewhat different
than re-implementation with subtly different context.

Author: isaacs

dev-packages/node-integration-tests/suites/express/tracing/test.ts

@@ -32,7 +32,7 @@ describe('express tracing', () => {
                 }),
                 description: 'corsMiddleware',
                 op: 'middleware.express',
-                origin: 'auto.http.otel.express',
+                origin: 'auto.http.express',
               }),
               expect.objectContaining({
                 data: expect.objectContaining({
@@ -41,7 +41,7 @@ describe('express tracing', () => {
                 }),
                 description: '/test/express',
                 op: 'request_handler.express',
-                origin: 'auto.http.otel.express',
+                origin: 'auto.http.express',
               }),
             ]),
           },

packages/core/src/index.ts

@@ -116,6 +116,13 @@ export { linkedErrorsIntegration } from './integrations/linkederrors';
 export { moduleMetadataIntegration } from './integrations/moduleMetadata';
 export { requestDataIntegration } from './integrations/requestdata';
 export { captureConsoleIntegration } from './integrations/captureconsole';
+export {
+  unpatchExpressModule,
+  patchExpressModule,
+  setupExpressErrorHandler,
+  expressErrorHandler,
+} from './integrations/express/index';
+export type { ExpressIntegrationOptions } from './integrations/express/types';
 export { dedupeIntegration } from './integrations/dedupe';
 export { extraErrorDataIntegration } from './integrations/extraerrordata';
 export { rewriteFramesIntegration } from './integrations/rewriteframes';

packages/core/src/integrations/express/index.ts

@@ -0,0 +1,262 @@
+/**
+ * Platform-portable Express tracing integration, OTel-free, for use
+ * on Cloudflare, Deno, Bun, etc.
+ *
+ * @module
+ *
+ * This Sentry integration is a derivative work based on the OpenTelemetry
+ * Express instrumentation.
+ *
+ * <https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-express>
+ *
+ * Extended under the terms of the Apache 2.0 license linked below:
+ *
+ * ----
+ *
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { debug } from '../../utils/debug-logger';
+import { captureException } from '../../exports';
+import { getIsolationScope } from '../../currentScopes';
+import { httpRequestToRequestData } from '../../utils/request';
+import { DEBUG_BUILD } from '../../debug-build';
+import type {
+  ExpressApplication,
+  ExpressErrorMiddleware,
+  ExpressExport,
+  ExpressHandlerOptions,
+  ExpressIntegrationOptions,
+  ExpressLayer,
+  ExpressMiddleware,
+  ExpressModuleExport,
+  ExpressRouter,
+  ExpressRouterv4,
+  ExpressRouterv5,
+  MiddlewareError,
+} from './types';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+  defaultShouldHandleError,
+  getLayerPath,
+  hasDefaultProp,
+  isExpressWithoutRouterPrototype,
+  isExpressWithRouterPrototype,
+} from './utils';
+import { unwrapMethod, wrapMethod } from '../../utils/object';
+import { patchLayer } from './patch-layer';
+
+const getExpressExport = (express: ExpressModuleExport): ExpressExport =>
+  hasDefaultProp(express) ? express.default : (express as ExpressExport);
+
+/**
+ * This is a portable instrumentatiton function that works in any environment
+ * where Express can be loaded, without depending on OpenTelemetry.
+ *
+ * @example
+ * ```javascript
+ * import express from 'express';
+ * import * as Sentry from '@sentry/deno'; // or any SDK that extends core
+ *
+ * Sentry.patchExpressModule({ express })
+ */
+export const patchExpressModule = (options: ExpressIntegrationOptions) => {
+  // pass in the require() or import() result of express
+  const express = getExpressExport(options.express);
+  const routerProto: ExpressRouterv4 | ExpressRouterv5 | undefined = isExpressWithRouterPrototype(express)
+    ? express.Router.prototype // Express v5
+    : isExpressWithoutRouterPrototype(express)
+      ? express.Router // Express v4
+      : undefined;
+
+  if (!routerProto) {
+    throw new TypeError('no valid Express route function to instrument');
+  }
+
+  // oxlint-disable-next-line @typescript-eslint/unbound-method
+  const originalRouteMethod = routerProto.route;
+  try {
+    wrapMethod(
+      routerProto,
+      'route',
+      function routeTrace(this: ExpressRouter, ...args: Parameters<typeof originalRouteMethod>[]) {
+        const route = originalRouteMethod.apply(this, args);
+        const layer = this.stack[this.stack.length - 1] as ExpressLayer;
+        patchLayer(options, layer, getLayerPath(args));
+        return route;
+      },
+    );
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to patch express route method:', e);
+  }
+
+  // oxlint-disable-next-line @typescript-eslint/unbound-method
+  const originalRouterUse = routerProto.use;
+  try {
+    wrapMethod(
+      routerProto,
+      'use',
+      function useTrace(this: ExpressApplication, ...args: Parameters<typeof originalRouterUse>) {
+        const route = originalRouterUse.apply(this, args);
+        const layer = this.stack[this.stack.length - 1];
+        if (!layer) return route;
+        patchLayer(options, layer, getLayerPath(args));
+        return route;
+      },
+    );
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to patch express use method:', e);
+  }
+
+  const { application } = express;
+  const originalApplicationUse = application.use;
+  try {
+    wrapMethod(
+      application,
+      'use',
+      function appUseTrace(
+        this: ExpressApplication & {
+          _router?: ExpressRouter;
+          router?: ExpressRouter;
+        },
+        ...args: Parameters<ExpressApplication['use']>
+      ) {
+        // If we access app.router in express 4.x we trigger an assertion error.
+        // This property existed in v3, was removed in v4 and then re-added in v5.
+        const router = isExpressWithRouterPrototype(express) ? this.router : this._router;
+        const route = originalApplicationUse.apply(this, args);
+        if (router) {
+          const layer = router.stack[router.stack.length - 1];
+          if (layer) {
+            patchLayer(options, layer, getLayerPath(args));
+          }
+        }
+        return route;
+      },
+    );
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to patch express application.use method:', e);
+  }
+
+  return express;
+};
+
+export const unpatchExpressModule = (options: ExpressIntegrationOptions) => {
+  const express = getExpressExport(options.express);
+  const routerProto: ExpressRouterv5 | ExpressRouterv4 | undefined = isExpressWithRouterPrototype(express)
+    ? express.Router.prototype // Express v5
+    : isExpressWithoutRouterPrototype(express)
+      ? express.Router // Express v4
+      : undefined;
+
+  if (!routerProto) {
+    throw new TypeError('no valid Express route function to deinstrument');
+  }
+
+  try {
+    unwrapMethod(routerProto, 'route');
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to unpatch express route method:', e);
+  }
+
+  try {
+    unwrapMethod(routerProto, 'use');
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to unpatch express use method:', e);
+  }
+
+  const { application } = express;
+  try {
+    unwrapMethod(application, 'use');
+  } catch (e) {
+    DEBUG_BUILD && debug.error('Failed to unpatch express application.use method:', e);
+  }
+
+  return express;
+};
+
+/**
+ * An Express-compatible error handler, used by setupExpressErrorHandler
+ */
+export function expressErrorHandler(options?: ExpressHandlerOptions): ExpressErrorMiddleware {
+  return function sentryErrorMiddleware(
+    error: MiddlewareError,
+    request: IncomingMessage,
+    res: ServerResponse,
+    next: (error: MiddlewareError) => void,
+  ): void {
+    const normalizedRequest = httpRequestToRequestData(request);
+    // Ensure we use the express-enhanced request here, instead of the plain HTTP one
+    // When an error happens, the `expressRequestHandler` middleware does not run, so we set it here too
+    getIsolationScope().setSDKProcessingMetadata({ normalizedRequest });
+
+    const shouldHandleError = options?.shouldHandleError || defaultShouldHandleError;
+
+    if (shouldHandleError(error)) {
+      const eventId = captureException(error, {
+        mechanism: { type: 'auto.middleware.express', handled: false },
+      });
+      (res as { sentry?: string }).sentry = eventId;
+    }
+
+    next(error);
+  };
+}
+
+/**
+ * Add an Express error handler to capture errors to Sentry.
+ *
+ * The error handler must be before any other middleware and after all controllers.
+ *
+ * @param app The Express instances
+ * @param options {ExpressHandlerOptions} Configuration options for the handler
+ *
+ * @example
+ * ```javascript
+ * import * as Sentry from 'sentry/deno'; // or any other @sentry/<platform>
+ * import * as express from 'express';
+ *
+ * Sentry.instrumentExpress(express);
+ *
+ * const app = express();
+ *
+ * // Add your routes, etc.
+ *
+ * // Add this after all routes,
+ * // but before any and other error-handling middlewares are defined
+ * Sentry.setupExpressErrorHandler(app);
+ *
+ * app.listen(3000);
+ * ```
+ */
+export function setupExpressErrorHandler(
+  app: {
+    use: (middleware: ExpressMiddleware | ExpressErrorMiddleware) => unknown;
+  },
+  options?: ExpressHandlerOptions,
+): void {
+  app.use(expressRequestHandler());
+  app.use(expressErrorHandler(options));
+}
+
+function expressRequestHandler(): ExpressMiddleware {
+  return function sentryRequestMiddleware(request: IncomingMessage, _res: ServerResponse, next: () => void): void {
+    const normalizedRequest = httpRequestToRequestData(request);
+    // Ensure we use the express-enhanced request here, instead of the plain HTTP one
+    getIsolationScope().setSDKProcessingMetadata({ normalizedRequest });
+
+    next();
+  };
+}