Refactor and rename utilities for execution context handling

Renamed `cloneExecutionContext` to `copyExecutionContext` and updated its implementation for improved binding logic and symbol handling. Moved `makeFlushLock` to `utils/flushLock` and adjusted imports accordingly. Added tests to validate `copyExecutionContext` behaviors and ensure robustness.

Author: cod1k

packages/cloudflare/src/client.ts

@@ -1,7 +1,7 @@
 import type { ClientOptions, Options, ServerRuntimeClientOptions } from '@sentry/core';
 import { applySdkMetadata, ServerRuntimeClient } from '@sentry/core';
-import type { makeFlushLock } from './flush';
 import type { CloudflareTransportOptions } from './transport';
+import type { makeFlushLock } from './utils/flushLock';
 
 /**
  * The Sentry Cloudflare SDK Client.

packages/cloudflare/src/durableobject.ts

@@ -18,7 +18,7 @@ import { isInstrumented, markAsInstrumented } from './instrument';
 import { getFinalOptions } from './options';
 import { wrapRequestHandler } from './request';
 import { init } from './sdk';
-import { cloneExecutionContext } from './utils/cloneExecutionContext';
+import { copyExecutionContext } from './utils/copyExecutionContext';
 
 type MethodWrapperOptions = {
   spanName?: string;
@@ -196,7 +196,7 @@ export function instrumentDurableObjectWithSentry<
     construct(target, [ctx, env]) {
       setAsyncLocalStorageAsyncContextStrategy();
 
-      const context = cloneExecutionContext(ctx)
+      const context = copyExecutionContext(ctx)
 
       const options = getFinalOptions(optionsCallback(env), env);
 

packages/cloudflare/src/handler.ts

@@ -14,7 +14,7 @@ import { getFinalOptions } from './options';
 import { wrapRequestHandler } from './request';
 import { addCloudResourceContext } from './scope-utils';
 import { init } from './sdk';
-import { cloneExecutionContext } from './utils/cloneExecutionContext';
+import { copyExecutionContext } from './utils/copyExecutionContext';
 
 /**
  * Wrapper for Cloudflare handlers.
@@ -41,7 +41,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
           const [request, env, ctx] = args;
 
           const options = getFinalOptions(optionsCallback(env), env);
-          const context = cloneExecutionContext(ctx)
+          const context = copyExecutionContext(ctx)
           args[2] = context;
 
           return wrapRequestHandler({ options, request, context }, () => target.apply(thisArg, args));
@@ -75,7 +75,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
       handler.scheduled = new Proxy(handler.scheduled, {
         apply(target, thisArg, args: Parameters<ExportedHandlerScheduledHandler<Env>>) {
           const [event, env, ctx] = args;
-          const context = cloneExecutionContext(ctx)
+          const context = copyExecutionContext(ctx)
           args[2] = context;
           return withIsolationScope(isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
@@ -120,7 +120,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
       handler.email = new Proxy(handler.email, {
         apply(target, thisArg, args: Parameters<EmailExportedHandler<Env>>) {
           const [emailMessage, env, ctx] = args;
-          const context = cloneExecutionContext(ctx)
+          const context = copyExecutionContext(ctx)
           args[2] = context;
           return withIsolationScope(isolationScope => {
             const options = getFinalOptions(optionsCallback(env), env);
@@ -163,7 +163,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
       handler.queue = new Proxy(handler.queue, {
         apply(target, thisArg, args: Parameters<ExportedHandlerQueueHandler<Env, QueueHandlerMessage>>) {
           const [batch, env, ctx] = args;
-          const context = cloneExecutionContext(ctx)
+          const context = copyExecutionContext(ctx)
           args[2] = context;
 
           return withIsolationScope(isolationScope => {
@@ -215,7 +215,7 @@ export function withSentry<Env = unknown, QueueHandlerMessage = unknown, CfHostM
       handler.tail = new Proxy(handler.tail, {
         apply(target, thisArg, args: Parameters<ExportedHandlerTailHandler<Env>>) {
           const [, env, ctx] = args;
-          const context = cloneExecutionContext(ctx)
+          const context = copyExecutionContext(ctx)
           args[2] = context;
 
           return withIsolationScope(async isolationScope => {

packages/cloudflare/src/sdk.ts

@@ -12,10 +12,10 @@ import {
 } from '@sentry/core';
 import type { CloudflareClientOptions, CloudflareOptions } from './client';
 import { CloudflareClient } from './client';
-import { makeFlushLock } from './flush';
 import { fetchIntegration } from './integrations/fetch';
 import { setupOpenTelemetryTracer } from './opentelemetry/tracer';
 import { makeCloudflareTransport } from './transport';
+import { makeFlushLock } from './utils/flushLock';
 import { defaultStackParser } from './vendor/stacktrace';
 
 /** Get the default integrations for the Cloudflare SDK. */

packages/cloudflare/src/utils/cloneExecutionContext.ts

@@ -0,0 +1,26 @@
+import { type ExecutionContext } from '@cloudflare/workers-types';
+
+const kBound = Symbol.for('kBound');
+
+/**
+ * Clones the given execution context by creating a shallow copy while ensuring the binding of specific methods.
+ *
+ * @param {ExecutionContext|void} ctx - The execution context to clone. Can be void.
+ * @return {ExecutionContext|void} A cloned execution context with bound methods, or the original void value if no context was provided.
+ */
+export function copyExecutionContext<T extends ExecutionContext | void>(ctx: T): T {
+  if (!ctx) return ctx;
+  return Object.assign({}, ctx, {
+    ...('waitUntil' in ctx && { waitUntil: copyBound(ctx, 'waitUntil') }),
+    ...('passThroughOnException' in ctx && { passThroughOnException: copyBound(ctx, 'passThroughOnException') }),
+  });
+}
+
+function copyBound<T extends object, K extends keyof T>(obj: T, method: K): T[K] {
+  const method_impl = obj[method];
+  if (typeof method_impl !== 'function') return method_impl;
+  if ((method_impl as T[K] & { [kBound]?: boolean })[kBound]) return method_impl;
+
+  const bound = method_impl.bind(obj);
+  return Object.defineProperty(bound, kBound, { value: true, enumerable: false });
+}

packages/cloudflare/src/utils/copyExecutionContext.ts

@@ -1,25 +1,25 @@
 import type { ExecutionContext } from '@cloudflare/workers-types';
-import { createPromiseResolver } from './utils/makePromiseResolver';
+import { createPromiseResolver } from './makePromiseResolver';
 
 type FlushLock = {
   readonly ready: Promise<void>;
   readonly finalize: () => Promise<void>;
 };
-type Lockable<T> = T & { [kFlushLock]?: FlushLock };
+type MaybeLockable<T extends object> = T & { [kFlushLock]?: FlushLock };
 
 const kFlushLock = Symbol.for('kFlushLock');
 
-function getInstrumentedLock<T>(o: Lockable<T>): FlushLock | undefined {
+function getInstrumentedLock<T extends object>(o: MaybeLockable<T>): FlushLock | undefined {
   return o[kFlushLock];
 }
 
-function storeInstrumentedLock<T>(o: Lockable<T>, lock: FlushLock): void {
+function storeInstrumentedLock<T extends object>(o: MaybeLockable<T>, lock: FlushLock): void {
   o[kFlushLock] = lock;
 }
 
 /**
  * Enhances the given execution context by wrapping its `waitUntil` method with a proxy
- * to monitor pending tasks, and provides a flusher function to ensure all tasks
+ * to monitor pending tasks and provides a flusher function to ensure all tasks
  * have been completed before executing any subsequent logic.
  *
  * @param {ExecutionContext} context - The execution context to be enhanced. If no context is provided, the function returns undefined.

packages/cloudflare/src/flush.ts renamed to packages/cloudflare/src/utils/flushLock.ts

@@ -0,0 +1,42 @@
+import { type ExecutionContext } from '@cloudflare/workers-types';
+import { type Mocked, describe, expect, it, vi } from 'vitest';
+import { copyExecutionContext } from '../src/utils/copyExecutionContext';
+
+describe('Copy of the execution context', () => {
+  describe.for<keyof ExecutionContext>(['waitUntil', 'passThroughOnException'])('%s', method => {
+    it('Was not bound more than once', async () => {
+      const context = makeExecutionContextMock();
+      const copy = copyExecutionContext(context);
+      const copy_of_copy = copyExecutionContext(copy);
+
+      expect(copy[method]).toBe(copy_of_copy[method]);
+    });
+    it('Copied method is bound to the original', async () => {
+      const context = makeExecutionContextMock();
+      const copy = copyExecutionContext(context);
+
+      expect(copy[method]()).toBe(context);
+    });
+  });
+
+  it('No side effects', async () => {
+    const context = makeExecutionContextMock();
+    expect(() => copyExecutionContext(Object.freeze(context))).not.toThrow(
+      /Cannot define property \w+, object is not extensible/,
+    );
+  });
+  it('Respects symbols', async () => {
+    const s = Symbol('test');
+    const context = makeExecutionContextMock<ExecutionContext & { [s]: unknown }>();
+    context[s] = {};
+    const copy = copyExecutionContext(context);
+    expect(copy[s]).toBe(context[s]);
+  });
+});
+
+function makeExecutionContextMock<T extends ExecutionContext>() {
+  return {
+    waitUntil: vi.fn().mockReturnThis(),
+    passThroughOnException: vi.fn().mockReturnThis(),
+  } as unknown as Mocked<T>;
+}

packages/cloudflare/test/copy-execution-context.test.ts

@@ -1,6 +1,6 @@
 import { type ExecutionContext } from '@cloudflare/workers-types';
 import { describe, expect, it, vi } from 'vitest';
-import { makeFlushLock } from '../src/flush';
+import { makeFlushLock } from '../src/utils/flushLock';
 import { createPromiseResolver } from '../src/utils/makePromiseResolver';
 
 describe('Flush buffer test', () => {