feat(cloudflare): Add support for durable objects

packages/cloudflare/src/durableobject.ts

@@ -0,0 +1,224 @@
+/* eslint-disable @typescript-eslint/unbound-method */
+import {
+  captureException,
+  flush,
+  getClient,
+  SEMANTIC_ATTRIBUTE_SENTRY_OP,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  startSpan,
+  withIsolationScope,
+  withScope,
+} from '@sentry/core';
+import type { DurableObject } from 'cloudflare:workers';
+import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import type { CloudflareOptions } from './client';
+import { isInstrumented, markAsInstrumented } from './instrument';
+import { wrapRequestHandler } from './request';
+import { init } from './sdk';
+
+type MethodWrapperOptions = {
+  spanName?: string;
+  spanOp?: string;
+  options: CloudflareOptions;
+  context: ExecutionContext | DurableObjectState;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function wrapMethodWithSentry<T extends (...args: any[]) => any>(
+  wrapperOptions: MethodWrapperOptions,
+  handler: T,
+  callback?: (...args: Parameters<T>) => void,
+): T {
+  if (isInstrumented(handler)) {
+    return handler;
+  }
+
+  markAsInstrumented(handler);
+
+  return new Proxy(handler, {
+    apply(target, thisArg, args: Parameters<T>) {
+      const currentClient = getClient();
+      // if a client is already set, use withScope, otherwise use withIsolationScope
+      const sentryWithScope = currentClient ? withScope : withIsolationScope;
+      return sentryWithScope(async scope => {
+        // In certain situations, the passed context can become undefined.
+        // For example, for Astro while prerendering pages at build time.
+        // see: https://github.com/getsentry/sentry-javascript/issues/13217
+        const context = wrapperOptions.context as ExecutionContext | undefined;
+
+        const currentClient = scope.getClient();
+        if (!currentClient) {
+          const client = init(wrapperOptions.options);
+          scope.setClient(client);
+        }
+
+        if (!wrapperOptions.spanName) {
+          try {
+            if (callback) {
+              callback(...args);
+            }
+            return await Reflect.apply(target, thisArg, args);
+          } catch (e) {
+            captureException(e, {
+              mechanism: {
+                type: 'cloudflare_durableobject',
+                handled: false,
+              },
+            });
+            throw e;
+          } finally {
+            context?.waitUntil(flush(2000));
+          }
+        }
+
+        const attributes = wrapperOptions.spanOp
+          ? {
+              [SEMANTIC_ATTRIBUTE_SENTRY_OP]: wrapperOptions.spanOp,
+              [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.faas.cloudflare_durableobjects',
+            }
+          : {};
+
+        // Only create these spans if they have a parent span.
+        return startSpan({ name: wrapperOptions.spanName, attributes, onlyIfParent: true }, async () => {
+          try {
+            return await Reflect.apply(target, thisArg, args);
+          } catch (e) {
+            captureException(e, {
+              mechanism: {
+                type: 'cloudflare_durableobject',
+                handled: false,
+              },
+            });
+            throw e;
+          } finally {
+            context?.waitUntil(flush(2000));
+          }
+        });
+      });
+    },
+  });
+}
+
+/**
+ * Instruments a Durable Object class to capture errors and performance data.
+ *
+ * Instruments the following methods:
+ * - fetch
+ * - alarm
+ * - webSocketMessage
+ * - webSocketClose
+ * - webSocketError
+ *
+ * as well as any other public RPC methods on the Durable Object instance.
+ *
+ * @param optionsCallback Function that returns the options for the SDK initialization.
+ * @param DurableObjectClass The Durable Object class to instrument.
+ * @returns The instrumented Durable Object class.
+ *
+ * @example
+ * ```ts
+ * class MyDurableObjectBase extends DurableObject {
+ *   constructor(ctx: DurableObjectState, env: Env) {
+ *     super(ctx, env);
+ *   }
+ * }
+ *
+ * export const MyDurableObject = instrumentDurableObjectWithSentry(
+ *   env => ({
+ *     dsn: env.SENTRY_DSN,
+ *     tracesSampleRate: 1.0,
+ *   }),
+ *   MyDurableObjectBase,
+ * );
+ * ```
+ */
+export function instrumentDurableObjectWithSentry<E, T extends DurableObject<E>>(
+  optionsCallback: (env: E) => CloudflareOptions,
+  DurableObjectClass: { new (state: DurableObjectState, env: E): T },
+): typeof DurableObjectClass {
+  return new Proxy(DurableObjectClass, {
+    construct(target, [context, env]) {
+      setAsyncLocalStorageAsyncContextStrategy();
+
+      const options = optionsCallback(env);
+
+      const obj = new target(context, env);
+
+      // These are the methods that are available on a Durable Object
+      // ref: https://developers.cloudflare.com/durable-objects/api/base/
+      // obj.alarm
+      // obj.fetch
+      // obj.webSocketError
+      // obj.webSocketClose
+      // obj.webSocketMessage
+
+      // Any other public methods on the Durable Object instance are RPC calls.
+
+      if (obj.fetch && typeof obj.fetch === 'function' && !isInstrumented(obj.fetch)) {
+        obj.fetch = new Proxy(obj.fetch, {
+          apply(target, thisArg, args) {
+            return wrapRequestHandler({ options, request: args[0], context }, () =>
+              Reflect.apply(target, thisArg, args),
+            );
+          },
+        });
+
+        markAsInstrumented(obj.fetch);
+      }
+
+      if (obj.alarm && typeof obj.alarm === 'function') {
+        obj.alarm = wrapMethodWithSentry({ options, context, spanName: 'alarm' }, obj.alarm);
+      }
+
+      if (obj.webSocketMessage && typeof obj.webSocketMessage === 'function') {
+        obj.webSocketMessage = wrapMethodWithSentry(
+          { options, context, spanName: 'webSocketMessage' },
+          obj.webSocketMessage,
+        );
+      }
+
+      if (obj.webSocketClose && typeof obj.webSocketClose === 'function') {
+        obj.webSocketClose = wrapMethodWithSentry({ options, context, spanName: 'webSocketClose' }, obj.webSocketClose);
+      }
+
+      if (obj.webSocketError && typeof obj.webSocketError === 'function') {
+        obj.webSocketError = wrapMethodWithSentry(
+          { options, context, spanName: 'webSocketError' },
+          obj.webSocketError,
+          (_, error) =>
+            captureException(error, {
+              mechanism: {
+                type: 'cloudflare_durableobject_websocket',
+                handled: false,
+              },
+            }),
+        );
+      }
+
+      for (const method of Object.getOwnPropertyNames(obj)) {
+        if (
+          method === 'fetch' ||
+          method === 'alarm' ||
+          method === 'webSocketError' ||
+          method === 'webSocketClose' ||
+          method === 'webSocketMessage'
+        ) {
+          continue;
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+        const value = (obj as any)[method] as unknown;
+        if (typeof value === 'function') {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+          (obj as any)[method] = wrapMethodWithSentry(
+            { options, context, spanName: method, spanOp: 'rpc' },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            value as (...args: any[]) => any,
+          );
+        }
+      }
+
+      return obj;
+    },
+  });
+}

packages/cloudflare/src/handler.ts

@@ -1,8 +1,3 @@
-import type {
-  ExportedHandler,
-  ExportedHandlerFetchHandler,
-  ExportedHandlerScheduledHandler,
-} from '@cloudflare/workers-types';
 import {
   captureException,
   flush,
@@ -13,15 +8,11 @@ import {
 } from '@sentry/core';
 import { setAsyncLocalStorageAsyncContextStrategy } from './async';
 import type { CloudflareOptions } from './client';
+import { isInstrumented, markAsInstrumented } from './instrument';
 import { wrapRequestHandler } from './request';
 import { addCloudResourceContext } from './scope-utils';
 import { init } from './sdk';
 
-/**
- * Extract environment generic from exported handler.
- */
-type ExtractEnv<P> = P extends ExportedHandler<infer Env> ? Env : never;
-
 /**
  * Wrapper for Cloudflare handlers.
  *
@@ -33,16 +24,15 @@ type ExtractEnv<P> = P extends ExportedHandler<infer Env> ? Env : never;
  * @param handler {ExportedHandler} The handler to wrap.
  * @returns The wrapped handler.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function withSentry<E extends ExportedHandler<any>>(
-  optionsCallback: (env: ExtractEnv<E>) => CloudflareOptions,
-  handler: E,
-): E {
+export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostMetadata = unknown>(
+  optionsCallback: (env: Env) => CloudflareOptions,
+  handler: ExportedHandler<Env, QueueHandlerMessage, CfHostMetadata>,
+): ExportedHandler<Env, QueueHandlerMessage, CfHostMetadata> {
   setAsyncLocalStorageAsyncContextStrategy();
 
   if ('fetch' in handler && typeof handler.fetch === 'function' && !isInstrumented(handler.fetch)) {
     handler.fetch = new Proxy(handler.fetch, {
-      apply(target, thisArg, args: Parameters<ExportedHandlerFetchHandler<ExtractEnv<E>>>) {
+      apply(target, thisArg, args: Parameters<ExportedHandlerFetchHandler<Env, CfHostMetadata>>) {
         const [request, env, context] = args;
         const options = optionsCallback(env);
         return wrapRequestHandler({ options, request, context }, () => target.apply(thisArg, args));
@@ -54,7 +44,7 @@ export function withSentry<E extends ExportedHandler<any>>(
 
   if ('scheduled' in handler && typeof handler.scheduled === 'function' && !isInstrumented(handler.scheduled)) {
     handler.scheduled = new Proxy(handler.scheduled, {
-      apply(target, thisArg, args: Parameters<ExportedHandlerScheduledHandler<ExtractEnv<E>>>) {
+      apply(target, thisArg, args: Parameters<ExportedHandlerScheduledHandler<Env>>) {
         const [event, env, context] = args;
         return withIsolationScope(isolationScope => {
           const options = optionsCallback(env);
@@ -95,23 +85,3 @@ export function withSentry<E extends ExportedHandler<any>>(
 
   return handler;
 }
-
-type SentryInstrumented<T> = T & {
-  __SENTRY_INSTRUMENTED__?: boolean;
-};
-
-function markAsInstrumented<T>(handler: T): void {
-  try {
-    (handler as SentryInstrumented<T>).__SENTRY_INSTRUMENTED__ = true;
-  } catch {
-    // ignore errors here
-  }
-}
-
-function isInstrumented<T>(handler: T): boolean | undefined {
-  try {
-    return (handler as SentryInstrumented<T>).__SENTRY_INSTRUMENTED__;
-  } catch {
-    return false;
-  }
-}

packages/cloudflare/src/index.ts

@@ -92,6 +92,7 @@ export {
 } from '@sentry/core';
 
 export { withSentry } from './handler';
+export { instrumentDurableObjectWithSentry } from './durableobject';
 export { sentryPagesPlugin } from './pages-plugin';
 
 export { wrapRequestHandler } from './request';

packages/cloudflare/src/instrument.ts

@@ -0,0 +1,25 @@
+type SentryInstrumented<T> = T & {
+  __SENTRY_INSTRUMENTED__?: boolean;
+};
+
+/**
+ * Mark an object as instrumented.
+ */
+export function markAsInstrumented<T>(obj: T): void {
+  try {
+    (obj as SentryInstrumented<T>).__SENTRY_INSTRUMENTED__ = true;
+  } catch {
+    // ignore errors here
+  }
+}
+
+/**
+ * Check if an object is instrumented.
+ */
+export function isInstrumented<T>(obj: T): boolean | undefined {
+  try {
+    return (obj as SentryInstrumented<T>).__SENTRY_INSTRUMENTED__;
+  } catch {
+    return false;
+  }
+}