feat(cloudflare): Add trace propagation for RPC method calls (#20343)

closes #19327
closes
[JS-1715](https://linear.app/getsentry/issue/JS-1715/sentrycloudflare-durable-object-rpc-spans-are-not-linked-to-worker)

closes #16898
closes
[JS-680](https://linear.app/getsentry/issue/JS-680/instrument-cloudflare-worker-rpc-methods)

closes #16760
closes
[JS-622](https://linear.app/getsentry/issue/JS-622/trace-propagation-in-cloudflare-workers-not-working-as-expected)

## Summary

> Most of the additions are tests, the main implementation is rather
small

Adds trace propagation for Cloudflare Workers RPC method calls to
Durable Objects.

This is admittedly a bit of a hack: [Cap'n
Proto](https://capnproto.org/) ([which powers Cloudflare
RPC](https://blog.cloudflare.com/capnweb-javascript-rpc-library/)) has
no native support for headers or metadata. To work around this, we
append our trace data (sentry-trace + baggage) as a trailing argument
object `{ __sentry: { trace, baggage } }` to every RPC call. On the
receiving DO side, we strip this argument before the user's method is
invoked, so it's completely transparent.

**Caveat:** If the Durable Object is not instrumented with Sentry, the
trailing `__sentry` argument will remain in the args array and be passed
to the user's method. I would count this as ok since:

- Users opting into RPC instrumentation are expected to instrument both
sides
- The extra argument is easy to ignore in most cases, unless users use
`...args` to retrieve all arguments

Otherwise, trace propagation should be seamless across Worker → DO and
Worker → Worker → DO call chains.

### How it works

As mentioned above a Sentry trace object is appended on each call

```ts
const id = env.MY_DURABLE_OBJECT.idFromName('test');
const stub = env.MY_DURABLE_OBJECT.get(id);

// User's RPC call
const result = await stub.sayHello('World');

// What is actually sent (transparent to user)
const result = await stub.sayHello('World', { __sentry: { trace, baggage } });
```

Author: JPeer264

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject/index.ts

@@ -6,22 +6,46 @@ interface Env {
   TEST_DURABLE_OBJECT: DurableObjectNamespace;
 }
 
+// Regression test for https://github.com/getsentry/sentry-javascript/issues/17127
+// This class mimics a real-world DO with private fields/methods and multiple public methods
 class TestDurableObjectBase extends DurableObject<Env> {
+  // Private field used by RPC methods - tests that private fields work with instrumentation
+  #greeting = 'Hello';
+
   public constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
   }
 
-  // eslint-disable-next-line @typescript-eslint/explicit-member-accessibility
+  // RPC method that uses a private field - this would throw TypeError if the Proxy
+  // doesn't correctly bind `this` to the original object
   async sayHello(name: string): Promise<string> {
-    return `Hello, ${name}`;
+    return `${this.#greeting}, ${name}`;
+  }
+
+  // RPC method that modifies a private field
+  async setGreeting(greeting: string): Promise<void> {
+    this.#greeting = greeting;
+  }
+
+  // Other public methods that are not called - should not interfere with RPC
+  async getStatus(): Promise<string> {
+    return 'OK';
+  }
+
+  async processData(data: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return { ...data, processed: true };
+  }
+
+  async multiply(a: number, b: number): Promise<number> {
+    return a * b;
   }
 }
 
 export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
   (env: Env) => ({
     dsn: env.SENTRY_DSN,
     tracesSampleRate: 1.0,
-    instrumentPrototypeMethods: true,
+    enableRpcTracePropagation: true,
   }),
   TestDurableObjectBase,
 );
@@ -36,6 +60,13 @@ export default {
       return new Response(greeting);
     }
 
+    // Test endpoint that modifies and reads a private field via RPC
+    if (request.url.includes('custom-greeting')) {
+      await stub.setGreeting('Howdy');
+      const greeting = await stub.sayHello('partner');
+      return new Response(greeting);
+    }
+
     return new Response('Usual response');
   },
 };

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject/test.ts

@@ -1,4 +1,5 @@
 import { expect, it } from 'vitest';
+import type { Event } from '@sentry/core';
 import { createRunner } from '../../../runner';
 
 it('traces a durable object method', async ({ signal }) => {
@@ -25,3 +26,74 @@ it('traces a durable object method', async ({ signal }) => {
   await runner.makeRequest('get', '/hello');
   await runner.completed();
 });
+
+// Regression test for https://github.com/getsentry/sentry-javascript/issues/17127
+// The RPC receiver does not implement the method error on consecutive calls
+it('handles consecutive RPC calls without throwing "RPC receiver does not implement method" error', async ({
+  signal,
+}) => {
+  const runner = createRunner(__dirname)
+    .expect(envelope => {
+      const transactionEvent = envelope[1]?.[0]?.[1];
+      expect(transactionEvent).toEqual(
+        expect.objectContaining({
+          transaction: 'sayHello',
+        }),
+      );
+    })
+    .expect(envelope => {
+      const transactionEvent = envelope[1]?.[0]?.[1];
+      expect(transactionEvent).toEqual(
+        expect.objectContaining({
+          transaction: 'sayHello',
+        }),
+      );
+    })
+    .unordered()
+    .start(signal);
+
+  // First request - this always worked
+  const response1 = await runner.makeRequest<string>('get', '/hello');
+  expect(response1).toBe('Hello, world');
+
+  // Second consecutive request - this used to fail with:
+  // "The RPC receiver does not implement the method 'sayHello'"
+  const response2 = await runner.makeRequest<string>('get', '/hello');
+  expect(response2).toBe('Hello, world');
+
+  await runner.completed();
+});
+
+// Regression test: RPC methods that access private fields should work correctly.
+// When enableRpcTracePropagation wraps the DO in a Proxy, calling methods through
+// the Proxy must ensure `this` refers to the original object (not the Proxy),
+// otherwise private field access throws: "Cannot read private member from an object
+// whose class did not declare it"
+it('allows RPC methods to access private class fields', async ({ signal }) => {
+  const runner = createRunner(__dirname)
+    .expect(envelope => {
+      const transactionEvent = envelope[1]?.[0]?.[1] as Event;
+      expect(transactionEvent).toEqual(
+        expect.objectContaining({
+          transaction: 'setGreeting',
+        }),
+      );
+    })
+    .expect(envelope => {
+      const transactionEvent = envelope[1]?.[0]?.[1] as Event;
+      expect(transactionEvent).toEqual(
+        expect.objectContaining({
+          transaction: 'sayHello',
+        }),
+      );
+    })
+    .unordered()
+    .start(signal);
+
+  // This calls setGreeting (writes private field) then sayHello (reads private field)
+  // Would throw TypeError if `this` is the Proxy instead of the original object
+  const response = await runner.makeRequest<string>('get', '/custom-greeting');
+  expect(response).toBe('Howdy, partner');
+
+  await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/propagation/worker-do-rpc-disabled/index.ts

@@ -0,0 +1,45 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+import type { RpcTarget } from 'cloudflare:workers';
+
+interface Env {
+  SENTRY_DSN: string;
+  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObjectBase>;
+}
+
+class MyDurableObjectBase extends DurableObject<Env> implements RpcTarget {
+  async sayHello(name: string): Promise<string> {
+    return `Hello, ${name}!`;
+  }
+}
+
+// enableRpcTracePropagation is NOT enabled, so RPC methods won't be instrumented
+export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    // enableRpcTracePropagation: false (default)
+  }),
+  MyDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+  }),
+  {
+    async fetch(request, env) {
+      const url = new URL(request.url);
+      const id = env.MY_DURABLE_OBJECT.idFromName('test');
+      const stub = env.MY_DURABLE_OBJECT.get(id);
+
+      if (url.pathname === '/rpc/hello') {
+        const result = await stub.sayHello('World');
+        return new Response(result);
+      }
+
+      return new Response('Not found', { status: 404 });
+    },
+  } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/propagation/worker-do-rpc-disabled/test.ts

@@ -0,0 +1,40 @@
+import { expect, it } from 'vitest';
+import type { Event } from '@sentry/core';
+import { createRunner } from '../../../../runner';
+
+it('does not create RPC transaction when enableRpcTracePropagation is disabled', async ({ signal }) => {
+  let receivedTransactions: string[] = [];
+
+  const runner = createRunner(__dirname)
+    .expect(envelope => {
+      const transactionEvent = envelope[1]?.[0]?.[1] as Event;
+
+      // Should only receive the worker HTTP transaction, not the DO RPC transaction
+      expect(transactionEvent).toEqual(
+        expect.objectContaining({
+          contexts: expect.objectContaining({
+            trace: expect.objectContaining({
+              op: 'http.server',
+              data: expect.objectContaining({
+                'sentry.origin': 'auto.http.cloudflare',
+              }),
+              origin: 'auto.http.cloudflare',
+            }),
+          }),
+          transaction: 'GET /rpc/hello',
+        }),
+      );
+      receivedTransactions.push(transactionEvent.transaction as string);
+    })
+    .start(signal);
+
+  // The RPC call should still work, just not be instrumented
+  const response = await runner.makeRequest<string>('get', '/rpc/hello');
+  expect(response).toBe('Hello, World!');
+
+  await runner.completed();
+
+  // Verify we only got the worker transaction, no RPC transaction
+  expect(receivedTransactions).toEqual(['GET /rpc/hello']);
+  expect(receivedTransactions).not.toContain('sayHello');
+});

dev-packages/cloudflare-integration-tests/suites/tracing/propagation/worker-do-rpc-disabled/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+  "name": "cloudflare-worker-do-rpc-disabled",
+  "main": "index.ts",
+  "compatibility_date": "2025-06-17",
+  "compatibility_flags": ["nodejs_als"],
+  "migrations": [
+    {
+      "new_sqlite_classes": ["MyDurableObject"],
+      "tag": "v1",
+    },
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "class_name": "MyDurableObject",
+        "name": "MY_DURABLE_OBJECT",
+      },
+    ],
+  },
+}

dev-packages/cloudflare-integration-tests/suites/tracing/propagation/worker-do-rpc/index.ts

@@ -0,0 +1,54 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+import type { RpcTarget } from 'cloudflare:workers';
+
+interface Env {
+  SENTRY_DSN: string;
+  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObjectBase>;
+}
+
+class MyDurableObjectBase extends DurableObject<Env> implements RpcTarget {
+  async sayHello(name: string): Promise<string> {
+    return `Hello, ${name}!`;
+  }
+
+  async multiply(a: number, b: number): Promise<number> {
+    return a * b;
+  }
+}
+
+export const MyDurableObject = Sentry.instrumentDurableObjectWithSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    enableRpcTracePropagation: true,
+  }),
+  MyDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+  (env: Env) => ({
+    dsn: env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+    enableRpcTracePropagation: true,
+  }),
+  {
+    async fetch(request, env) {
+      const url = new URL(request.url);
+      const id = env.MY_DURABLE_OBJECT.idFromName('test');
+      const stub = env.MY_DURABLE_OBJECT.get(id);
+
+      if (url.pathname === '/rpc/hello') {
+        const result = await stub.sayHello('World');
+        return new Response(result);
+      }
+
+      if (url.pathname === '/rpc/multiply') {
+        const result = await stub.multiply(6, 7);
+        return new Response(String(result));
+      }
+
+      return new Response('Not found', { status: 404 });
+    },
+  } satisfies ExportedHandler<Env>,
+);