feat(cloudflare): Support Cloudflare types v5 & newer wrangler versions (#22180)

closes #22178
closes [JS-2999](https://linear.app/getsentry/issue/JS-2999)

I updated the types for our dev packages, but kept the tests on the
older version to cross-check compatibility as well for older versions.

In the past I wanted to keep the oldest version in here to not break
something by accident, but if we do that, we might miss on potential new
features/options, such as the new `step.do` option, which we wouldn't
have passed along. So IMO it is better to keep it latest here and test
against old and new versions instead


---

There are new types within the `ExecutionContext`, to support older
versions where only `waitUntil` and `passThroughOnException` were
required and the newer one which has more types in it,
`ExecutionContextCompat` was created, that picks the types which were
needed before and adds the newer `ExecutionContext` as well

Author: JPeer264

packages/cloudflare/package.json

@@ -65,15 +65,15 @@
     "@sentry/server-utils": "10.65.0"
   },
   "peerDependencies": {
-    "@cloudflare/workers-types": "^4.x"
+    "@cloudflare/workers-types": "^4.x || ^5.x"
   },
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "4.20250922.0",
+    "@cloudflare/workers-types": "5.20260710.1",
     "@types/node": "^18.19.1",
     "wrangler": "4.61.0"
   },

packages/cloudflare/src/client.ts

@@ -1,6 +1,7 @@
 import type { ClientOptions, Options, ServerRuntimeClientOptions } from '@sentry/core';
 import { applySdkMetadata, debug, ServerRuntimeClient, spanIsSampled } from '@sentry/core';
 import { DEBUG_BUILD } from './debug-build';
+import type { ExecutionContextCompat } from './executionContext';
 import type { makeFlushLock } from './flush';
 import type { CloudflareTransportOptions } from './transport';
 
@@ -230,7 +231,7 @@ interface BaseCloudflareOptions {
  * @see @sentry/core Options for more information.
  */
 export interface CloudflareOptions extends Options<CloudflareTransportOptions>, BaseCloudflareOptions {
-  ctx?: ExecutionContext;
+  ctx?: ExecutionContextCompat;
 }
 
 /**

packages/cloudflare/src/executionContext.ts

@@ -0,0 +1,13 @@
+import type { ExecutionContext } from '@cloudflare/workers-types';
+
+/**
+ * A structural subset of `ExecutionContext` that is compatible with both `@cloudflare/workers-types`
+ * v4 and v5.
+ *
+ * v5 added `exports` and `tracing` as required members. Referencing the full `ExecutionContext` in
+ * public input positions would force consumers on v4 (still allowed by our `peerDependencies` range)
+ * to provide members their types don't have. We only ever use `waitUntil` (plus a runtime
+ * `'storage' in ctx` check), so picking the members that exist in both majors keeps a context
+ * constructed against either version assignable here.
+ */
+export type ExecutionContextCompat = Pick<ExecutionContext, 'waitUntil' | 'passThroughOnException'> | ExecutionContext;

packages/cloudflare/src/flush.ts

@@ -2,6 +2,7 @@ import type { ExecutionContext } from '@cloudflare/workers-types';
 import type { Client } from '@sentry/core';
 import { debug, flush } from '@sentry/core';
 import { DEBUG_BUILD } from './debug-build';
+import type { ExecutionContextCompat } from './executionContext';
 
 type FlushLock = {
   readonly ready: Promise<void>;
@@ -34,7 +35,7 @@ const flushLockRegistries = new WeakMap<ExecutionContext['waitUntil'], FlushLock
  *
  * By using the original waitUntil for flush operations, we bypass this issue.
  */
-export function getOriginalWaitUntil(context: ExecutionContext): ExecutionContext['waitUntil'] | undefined {
+export function getOriginalWaitUntil(context: ExecutionContextCompat): ExecutionContext['waitUntil'] | undefined {
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const currentWaitUntil = context.waitUntil;
   const original = flushLockRegistries.get(currentWaitUntil)?.originalWaitUntil;
@@ -49,7 +50,7 @@ export function getOriginalWaitUntil(context: ExecutionContext): ExecutionContex
  * @param {ExecutionContext} context - The execution context to be enhanced. If no context is provided, the function returns undefined.
  * @return {FlushLock} Returns a flusher function if a valid context is provided, otherwise undefined.
  */
-export function makeFlushLock(context: ExecutionContext): FlushLock {
+export function makeFlushLock(context: ExecutionContextCompat): FlushLock {
   const registry = getOrCreateFlushLockRegistry(context);
   let resolveAllDone: () => void = () => undefined;
   const allDone = new Promise<void>(res => {
@@ -81,7 +82,7 @@ export function makeFlushLock(context: ExecutionContext): FlushLock {
   return Object.freeze(lock);
 }
 
-function getOrCreateFlushLockRegistry(context: ExecutionContext): FlushLockRegistry {
+function getOrCreateFlushLockRegistry(context: ExecutionContextCompat): FlushLockRegistry {
   // eslint-disable-next-line @typescript-eslint/unbound-method
   const waitUntil = context.waitUntil;
   const existingRegistry = flushLockRegistries.get(waitUntil);

packages/cloudflare/src/instrumentations/worker/instrumentQueueProducer.ts

@@ -69,7 +69,7 @@ export function instrumentQueueProducer<T extends Queue>(queue: T, bindingName:
       if (prop === 'send') {
         const original = Reflect.get(target, prop, receiver) as Queue['send'];
 
-        return function (this: unknown, message: unknown, options?: QueueSendOptions): Promise<void> {
+        return function (this: unknown, message: unknown, options?: QueueSendOptions): ReturnType<Queue['send']> {
           return startPublishSpan({ bindingName, bodySize: getBodySize(message) }, () =>
             Reflect.apply(original, target, [message, options]),
           );
@@ -82,7 +82,7 @@ export function instrumentQueueProducer<T extends Queue>(queue: T, bindingName:
           this: unknown,
           messages: Iterable<MessageSendRequest>,
           options?: QueueSendBatchOptions,
-        ): Promise<void> {
+        ): ReturnType<Queue['sendBatch']> {
           const messageArray = Array.from(messages);
           const totalBodySize = messageArray.reduce<number | undefined>((acc, m) => {
             const size = getBodySize(m.body);

packages/cloudflare/src/pages-plugin.ts

@@ -1,5 +1,6 @@
 import { setAsyncLocalStorageAsyncContextStrategy } from './async';
 import type { CloudflareOptions } from './client';
+import type { ExecutionContextCompat } from './executionContext';
 import { wrapRequestHandler } from './request';
 
 /**
@@ -53,8 +54,9 @@ export function sentryPagesPlugin<
     }
 
     const options = typeof handlerOrOptions === 'function' ? handlerOrOptions(context) : handlerOrOptions;
-    return wrapRequestHandler({ options, request: context.request, context: { ...context, props: {} } }, () =>
-      context.next(),
-    );
+    // A Pages `EventPluginContext` is not a Workers `ExecutionContext`, but `wrapRequestHandler` only
+    // uses `waitUntil` and a `'storage' in context` check, both of which this satisfies.
+    const executionContext = { ...context, props: {} } as unknown as ExecutionContextCompat;
+    return wrapRequestHandler({ options, request: context.request, context: executionContext }, () => context.next());
   };
 }

packages/cloudflare/src/request.ts

@@ -1,4 +1,4 @@
-import type { CfProperties, ExecutionContext, IncomingRequestCfProperties } from '@cloudflare/workers-types';
+import type { CfProperties, IncomingRequestCfProperties } from '@cloudflare/workers-types';
 import {
   captureException,
   continueTrace,
@@ -14,20 +14,21 @@ import {
 } from '@sentry/core';
 import { captureIncomingRequestBody } from './integrations/httpServer';
 import type { CloudflareOptions } from './client';
+import type { ExecutionContextCompat } from './executionContext';
 import { flushAndDispose, getOriginalWaitUntil } from './flush';
 import { addCloudResourceContext, addCultureContext, addRequest } from './scope-utils';
 import { init } from './sdk';
 import { classifyResponseStreaming } from './utils/streaming';
 
-function getRequestErrorMechanismType(context: ExecutionContext | undefined): string {
+function getRequestErrorMechanismType(context: ExecutionContextCompat | undefined): string {
   // Durable Object fetch handlers use DO state as context (see instrumentDurableObjectWithSentry)
   return context && 'storage' in context ? 'auto.faas.cloudflare.durable_object' : 'auto.http.cloudflare';
 }
 
 interface RequestHandlerWrapperOptions {
   options: CloudflareOptions;
   request: Request<unknown, IncomingRequestCfProperties<unknown> | CfProperties<unknown>>;
-  context: ExecutionContext | undefined;
+  context: ExecutionContextCompat | undefined;
   /**
    * If true, errors will be captured, rethrown and sent to Sentry.
    * Otherwise, errors are rethrown but not captured.

packages/cloudflare/src/workflows.ts

@@ -10,12 +10,15 @@ import {
   withScope,
 } from '@sentry/core';
 import type {
+  WorkflowDelayDuration,
   WorkflowEntrypoint,
   WorkflowEvent,
   WorkflowSleepDuration,
   WorkflowStep,
   WorkflowStepConfig,
+  WorkflowStepContext,
   WorkflowStepEvent,
+  WorkflowStepRollbackOptions,
   WorkflowTimeoutDuration,
 } from 'cloudflare:workers';
 import { setAsyncLocalStorageAsyncContextStrategy } from './async';
@@ -70,23 +73,34 @@ class WrappedWorkflowStep implements WorkflowStep {
 
   public async do<T extends Rpc.Serializable<T>>(
     name: string,
-    callback: (...args: unknown[]) => Promise<T>,
+    callback: (ctx: WorkflowStepContext) => Promise<T>,
+    rollbackOptions?: WorkflowStepRollbackOptions<T>,
   ): Promise<T>;
-  public async do<T extends Rpc.Serializable<T>>(
+  public async do<T extends Rpc.Serializable<T>, const C extends WorkflowStepConfig>(
     name: string,
-    config: WorkflowStepConfig,
-    callback: (...args: unknown[]) => Promise<T>,
+    config: C,
+    callback: (
+      ctx: WorkflowStepContext<C['retries'] extends { delay: infer D } ? D : WorkflowDelayDuration | number>,
+    ) => Promise<T>,
+    rollbackOptions?: WorkflowStepRollbackOptions<T>,
   ): Promise<T>;
   public async do<T extends Rpc.Serializable<T>>(
     name: string,
-    configOrCallback: WorkflowStepConfig | (() => Promise<T>),
-    maybeCallback?: (...args: unknown[]) => Promise<T>,
+    configOrCallback: WorkflowStepConfig | ((ctx: WorkflowStepContext) => Promise<T>),
+    callbackOrRollback?: ((ctx: WorkflowStepContext) => Promise<T>) | WorkflowStepRollbackOptions<T>,
+    maybeRollback?: WorkflowStepRollbackOptions<T>,
   ): Promise<T> {
     // Capture the current scope, so parent span (e.g., a startSpan surrounding step.do) is preserved
     const scopeForStep = getCurrentScope();
 
-    const userCallback = (maybeCallback || configOrCallback) as (...args: unknown[]) => Promise<T>;
-    const config = typeof configOrCallback === 'function' ? undefined : configOrCallback;
+    const hasConfig = typeof configOrCallback !== 'function';
+    const config = hasConfig ? configOrCallback : undefined;
+    const userCallback = (hasConfig ? callbackOrRollback : configOrCallback) as (
+      ctx: WorkflowStepContext,
+    ) => Promise<T>;
+    const rollbackOptions = (hasConfig ? maybeRollback : callbackOrRollback) as
+      | WorkflowStepRollbackOptions<T>
+      | undefined;
 
     const instrumentedCallback = async (...args: unknown[]): Promise<T> => {
       // Feature detection: Cloudflare Workflows (April 2026+) pass a step context
@@ -109,7 +123,9 @@ class WrappedWorkflowStep implements WorkflowStep {
           attributes: {
             'cloudflare.workflow.timeout': config?.timeout,
             'cloudflare.workflow.retries.backoff': config?.retries?.backoff,
-            'cloudflare.workflow.retries.delay': config?.retries?.delay,
+            // In workers-types v5, `delay` may be a `WorkflowDelayFunction`, which isn't a valid span attribute value.
+            'cloudflare.workflow.retries.delay':
+              typeof config?.retries?.delay === 'function' ? undefined : config?.retries?.delay,
             'cloudflare.workflow.retries.limit': config?.retries?.limit,
             'cloudflare.workflow.attempt': attempt,
             [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.faas.cloudflare.workflow',
@@ -118,7 +134,7 @@ class WrappedWorkflowStep implements WorkflowStep {
         },
         async span => {
           try {
-            const result = await userCallback(...args);
+            const result = await (userCallback as (...args: unknown[]) => Promise<T>)(...args);
             span.setStatus({ code: 1 });
             return result;
           } catch (error) {
@@ -133,7 +149,15 @@ class WrappedWorkflowStep implements WorkflowStep {
       );
     };
 
-    return config ? this._step.do(name, config, instrumentedCallback) : this._step.do(name, instrumentedCallback);
+    if (config) {
+      return rollbackOptions
+        ? this._step.do(name, config, instrumentedCallback, rollbackOptions)
+        : this._step.do(name, config, instrumentedCallback);
+    }
+
+    return rollbackOptions
+      ? this._step.do(name, instrumentedCallback, rollbackOptions)
+      : this._step.do(name, instrumentedCallback);
   }
 
   public async sleep(name: string, duration: WorkflowSleepDuration): Promise<void> {

yarn.lock

@@ -3137,6 +3137,11 @@
   resolved "https://registry.yarnpkg.com/@cloudflare/workers-types/-/workers-types-4.20250922.0.tgz#a159fbf3bb785fa85b473ecfaa8c501525827885"
   integrity sha512-BaqlKnVc0Xzqm9xt3TC4v0yB9EHy5vVqpiWz+DAsbEmdcpUbqdBschvI9502p6FgFbZElD7XcxTEeViXLsoO0A==
 
+"@cloudflare/workers-types@5.20260710.1":
+  version "5.20260710.1"
+  resolved "https://registry.yarnpkg.com/@cloudflare/workers-types/-/workers-types-5.20260710.1.tgz#215c0cf84c3917552b53a1f5129150abf0b6009f"
+  integrity sha512-4ooaY2Pb5XGwDn8Fzm6jnTAJkIX0R5LBvL9euQpp2T58sQItlAQd9yivAlkwGhpY5cM1u81/9HaXwKAjXwtyzA==
+
 "@cloudflare/workers-types@^4.20260426.0":
   version "4.20260519.1"
   resolved "https://registry.yarnpkg.com/@cloudflare/workers-types/-/workers-types-4.20260519.1.tgz#061b4594e874a0e506ddc6599221939e6718d2a7"