autotel-cloudflare 2.12.0 → 2.14.0

package/src/handlers/workflows.test.ts

@@ -0,0 +1,325 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrumentWorkflow } from './workflows';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('Workflow Instrumentation', () => {
+  let mockTracer: any;
+  let mockSpan: any;
+  let getTracerSpy: any;
+
+  beforeEach(() => {
+    mockSpan = {
+      spanContext: () => ({
+        traceId: 'test-trace-id',
+        spanId: 'test-span-id',
+        traceFlags: 1,
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      end: vi.fn(),
+      isRecording: () => true,
+      updateName: vi.fn(),
+      addEvent: vi.fn(),
+    };
+
+    mockTracer = {
+      startActiveSpan: vi.fn((name, options, context, fn) => {
+        if (typeof options === 'function') return options(mockSpan);
+        if (typeof context === 'function') return context(mockSpan);
+        if (typeof fn === 'function') return fn(mockSpan);
+        return Promise.resolve();
+      }),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  describe('instrumentWorkflow()', () => {
+    it('should wrap workflow class constructor', () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run() {}
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'test-workflow', {
+        service: { name: 'test' },
+      });
+
+      expect(Instrumented).toBeDefined();
+      expect(typeof Instrumented).toBe('function');
+    });
+
+    it('should create workflow instance with instrumented run()', () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run() { return 'done'; }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'test-workflow', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+
+      expect(instance).toBeDefined();
+      expect(typeof instance.run).toBe('function');
+    });
+
+    it('should accept static config', () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run() {}
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'test-workflow', {
+        service: { name: 'test', version: '1.0.0' },
+        exporter: { url: 'http://localhost:4318/v1/traces' },
+      });
+
+      expect(Instrumented).toBeDefined();
+    });
+
+    it('should accept config function', () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run() {}
+      }
+
+      interface Env {
+        OTLP_ENDPOINT: string;
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'test-workflow', (env: Env) => ({
+        service: { name: 'test' },
+        exporter: { url: env.OTLP_ENDPOINT },
+      }));
+
+      expect(Instrumented).toBeDefined();
+    });
+  });
+
+  describe('run() instrumentation', () => {
+    it('should preserve run() return value', async () => {
+      const output = { status: 'ok', orderId: 'ord-123' };
+
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {
+          return output;
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'return-test', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-return' };
+      const step = { do: vi.fn(), sleep: vi.fn(), sleepUntil: vi.fn() };
+
+      await expect(instance.run(event, step)).resolves.toEqual(output);
+    });
+
+    it('should create span for run() with workflow attributes', async () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {}
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'test-workflow', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: { foo: 'bar' }, timestamp: new Date(), instanceId: 'wf-123' };
+      const step = { do: vi.fn(), sleep: vi.fn(), sleepUntil: vi.fn() };
+
+      await instance.run(event, step);
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalled();
+
+      const spanName = mockTracer.startActiveSpan.mock.calls[0][0];
+      expect(spanName).toBe('Workflow test-workflow: run');
+
+      const options = mockTracer.startActiveSpan.mock.calls[0][1];
+      expect(options.kind).toBe(SpanKind.INTERNAL);
+      expect(options.attributes['workflow.name']).toBe('test-workflow');
+      expect(options.attributes['workflow.instance_id']).toBe('wf-123');
+      expect(options.attributes['faas.trigger']).toBe('workflow');
+    });
+
+    it('should track cold starts', async () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {}
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'cold-test', {
+        service: { name: 'test' },
+      });
+
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-1' };
+      const step = { do: vi.fn(), sleep: vi.fn(), sleepUntil: vi.fn() };
+
+      const instance1 = new Instrumented({}, {});
+      await instance1.run(event, step);
+      const firstOptions = mockTracer.startActiveSpan.mock.calls[0][1];
+      expect(firstOptions.attributes['faas.coldstart']).toBe(true);
+
+      const instance2 = new Instrumented({}, {});
+      await instance2.run(event, step);
+      const secondOptions = mockTracer.startActiveSpan.mock.calls[1][1];
+      expect(secondOptions.attributes['faas.coldstart']).toBe(false);
+    });
+
+    it('should handle run() errors', async () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run() {
+          throw new Error('Workflow failed');
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'error-test', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-err' };
+      const step = { do: vi.fn(), sleep: vi.fn(), sleepUntil: vi.fn() };
+
+      await expect(instance.run(event, step)).rejects.toThrow('Workflow failed');
+
+      expect(mockSpan.recordException).toHaveBeenCalled();
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Workflow failed',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+  });
+
+  describe('step.do() instrumentation', () => {
+    it('should create span for step.do() calls', async () => {
+      const stepDoResult = { paymentId: 'pay_123' };
+      const mockStepDo = vi.fn().mockResolvedValue(stepDoResult);
+
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {
+          return await step.do('process payment', async () => stepDoResult);
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'step-test', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-step' };
+      const step = {
+        do: vi.fn(async (_name: string, cb: () => Promise<any>) => cb()),
+        sleep: vi.fn(),
+        sleepUntil: vi.fn(),
+      };
+
+      await instance.run(event, step);
+
+      // Should have spans for both run() and step.do()
+      expect(mockTracer.startActiveSpan.mock.calls.length).toBeGreaterThanOrEqual(2);
+
+      const stepSpanCall = mockTracer.startActiveSpan.mock.calls[1];
+      expect(stepSpanCall[0]).toBe('Workflow step-test: process payment');
+      expect(stepSpanCall[1].attributes['workflow.step.name']).toBe('process payment');
+      expect(stepSpanCall[1].attributes['workflow.name']).toBe('step-test');
+    });
+
+    it('should handle step.do() errors', async () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {
+          await step.do('failing step', async () => {
+            throw new Error('Step failed');
+          });
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'step-err', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-step-err' };
+      const step = {
+        do: vi.fn(async (_name: string, cb: () => Promise<any>) => cb()),
+        sleep: vi.fn(),
+        sleepUntil: vi.fn(),
+      };
+
+      await expect(instance.run(event, step)).rejects.toThrow('Step failed');
+
+      expect(mockSpan.recordException).toHaveBeenCalled();
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+  });
+
+  describe('step.sleep() instrumentation', () => {
+    it('should create span for step.sleep() calls', async () => {
+      class TestWorkflow {
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {
+          await step.sleep('wait for settlement', '2 hours');
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'sleep-test', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-sleep' };
+      const step = {
+        do: vi.fn(),
+        sleep: vi.fn().mockResolvedValue(undefined),
+        sleepUntil: vi.fn(),
+      };
+
+      await instance.run(event, step);
+
+      const sleepSpanCall = mockTracer.startActiveSpan.mock.calls[1];
+      expect(sleepSpanCall[0]).toBe('Workflow sleep-test: sleep wait for settlement');
+      expect(sleepSpanCall[1].attributes['workflow.sleep.name']).toBe('wait for settlement');
+      expect(sleepSpanCall[1].attributes['workflow.sleep.duration']).toBe('2 hours');
+      expect(sleepSpanCall[1].attributes['workflow.name']).toBe('sleep-test');
+    });
+  });
+
+  describe('this binding', () => {
+    it('should preserve this context in run()', async () => {
+      class TestWorkflow {
+        private value = 42;
+        constructor(public ctx: any, public env: any) {}
+        async run(event: any, step: any) {
+          return this.value;
+        }
+      }
+
+      const Instrumented = instrumentWorkflow(TestWorkflow, 'this-test', {
+        service: { name: 'test' },
+      });
+
+      const instance = new Instrumented({}, {});
+      const event = { payload: {}, timestamp: new Date(), instanceId: 'wf-this' };
+      const step = { do: vi.fn(), sleep: vi.fn(), sleepUntil: vi.fn() };
+
+      // Should not throw — this.value should be accessible
+      await expect(instance.run(event, step)).resolves.not.toThrow();
+    });
+  });
+});

package/src/handlers/workflows.ts

@@ -14,25 +14,48 @@ import {
   SpanStatusCode,
   SpanKind,
 } from '@opentelemetry/api';
-import type { ConfigurationOption } from 'autotel-edge';
+import type { ConfigurationOption, WorkflowTrigger } from 'autotel-edge';
 import { createInitialiser, setConfig, WorkerTracer } from 'autotel-edge';
 import { wrap } from '../bindings/common';
 
-// Workflow types (these would come from @cloudflare/workers-types when available)
-type WorkflowEvent = any;
-type WorkflowStep = any;
+/**
+ * Workflow types matching the Cloudflare Workers Workflows API.
+ * @see https://developers.cloudflare.com/workflows/
+ */
+
+interface WorkflowEvent<T = unknown> {
+  payload: Readonly<T>;
+  timestamp: Date;
+  instanceId: string;
+}
+
+interface WorkflowStepConfig {
+  retries?: {
+    limit: number;
+    delay?: string | number;
+    backoff?: 'constant' | 'linear' | 'exponential';
+  };
+  timeout?: string | number;
+}
+
+interface WorkflowStep {
+  do<T>(name: string, callback: () => Promise<T>): Promise<T>;
+  do<T>(name: string, config: WorkflowStepConfig, callback: () => Promise<T>): Promise<T>;
+  sleep(name: string, duration: string | number): Promise<void>;
+  sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+}
 
 type WorkflowRunFn = (
-  event: WorkflowEvent,
+  event: Readonly<WorkflowEvent>,
   step: WorkflowStep,
-) => Promise<void> | void;
+) => Promise<unknown> | void;
 
 /**
  * Track cold starts per Workflow class
  */
-const coldStarts = new WeakMap<any, boolean>();
+const coldStarts = new WeakMap<object, boolean>();
 
-function isColdStart(workflowClass: any): boolean {
+function isColdStart(workflowClass: object): boolean {
   if (!coldStarts.has(workflowClass)) {
     coldStarts.set(workflowClass, true);
     return true;
@@ -41,7 +64,7 @@ function isColdStart(workflowClass: any): boolean {
 }
 
 /**
- * Proxy the step object to instrument step.do() calls
+ * Proxy the step object to instrument step.do() and step.sleep() calls
  */
 function instrumentWorkflowStep(
   step: WorkflowStep,
@@ -55,7 +78,7 @@ function instrumentWorkflowStep(
       if (prop === 'do' && typeof value === 'function') {
         return new Proxy(value, {
           apply: (fnTarget, thisArg, args) => {
-            const [stepName] = args as [string, () => Promise<any>];
+            const [stepName] = args as [string, ...unknown[]];
 
             const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
 
@@ -148,13 +171,13 @@ function instrumentWorkflowStep(
 function instrumentWorkflowRun(
   runFn: WorkflowRunFn,
   workflowName: string,
-  workflowClass: any,
+  workflowClass: object,
 ): WorkflowRunFn {
   return async function instrumentedRun(
-    this: any,
-    event: WorkflowEvent,
+    this: unknown,
+    event: Readonly<WorkflowEvent>,
     step: WorkflowStep,
-  ): Promise<void> {
+  ): Promise<unknown> {
     const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
 
     // Instrument the step object to track individual operations
@@ -168,17 +191,16 @@ function instrumentWorkflowRun(
         kind: SpanKind.INTERNAL,
         attributes: {
           'workflow.name': workflowName,
+          'workflow.instance_id': event.instanceId,
           'faas.trigger': 'workflow',
           'faas.coldstart': isColdStart(workflowClass),
-          // Add workflow event attributes if available
-          ...(event?.workflowId && { 'workflow.id': event.workflowId }),
-          ...(event?.runId && { 'workflow.run_id': event.runId }),
         },
       },
       async (span) => {
         try {
-          await runFn.call(this, event, instrumentedStep);
+          const result = await runFn.call(this, event, instrumentedStep);
           span.setStatus({ code: SpanStatusCode.OK });
+          return result;
         } catch (error) {
           span.recordException(error as Error);
           span.setStatus({
@@ -198,17 +220,17 @@ function instrumentWorkflowRun(
  * Instrument a Workflow instance
  */
 function instrumentWorkflowInstance(
-  workflowInstance: any,
+  workflowInstance: Record<string, unknown>,
   workflowName: string,
-  workflowClass: any,
-): any {
-  const instanceHandler: ProxyHandler<any> = {
+  workflowClass: object,
+): Record<string, unknown> {
+  const instanceHandler: ProxyHandler<Record<string, unknown>> = {
     get(target, prop) {
       const value = Reflect.get(target, prop);
 
       if (prop === 'run' && typeof value === 'function') {
         return instrumentWorkflowRun(
-          value.bind(target),
+          value.bind(target) as WorkflowRunFn,
           workflowName,
           workflowClass,
         );
@@ -235,12 +257,12 @@ function instrumentWorkflowInstance(
  * **Usage:**
  * ```typescript
  * import { WorkflowEntrypoint } from 'cloudflare:workers'
- * import { instrumentWorkflow } from 'autotel-edge'
+ * import { instrumentWorkflow } from 'autotel-cloudflare/handlers'
  *
- * export class CheckoutWorkflow extends WorkflowEntrypoint {
+ * class MyWorkflow extends WorkflowEntrypoint {
  *   async run(event, step) {
  *     await step.do('submit payment', async () => {
- *       return await submitToPaymentProcessor(event.params.payment)
+ *       return await submitToPaymentProcessor(event.payload.payment)
  *     })
  *
  *     await step.sleep('wait for feedback', '2 days')
@@ -249,9 +271,8 @@ function instrumentWorkflowInstance(
  *   }
  * }
  *
- * // Wrap the class before exporting
- * export const CheckoutWorkflowInstrumented = instrumentWorkflow(
- *   CheckoutWorkflow,
+ * export const CheckoutWorkflow = instrumentWorkflow(
+ *   MyWorkflow,
  *   'checkout-workflow',
  *   (env: Env) => ({
  *     exporter: {
@@ -266,14 +287,6 @@ function instrumentWorkflowInstance(
  * )
  * ```
  *
- * **What you get:**
- * - 🎯 Automatic spans for workflow.run() execution
- * - 📋 Automatic spans for each step.do() operation
- * - ⏸️ Automatic spans for step.sleep() operations
- * - 🔄 Automatic retry tracking (via step.do retries)
- * - 🥶 Cold start tracking
- * - ⚡ Automatic span lifecycle management
- *
  * @param workflowClass - The WorkflowEntrypoint class to instrument
  * @param workflowName - The name of the workflow (used in span names)
  * @param config - Configuration or configuration function
@@ -293,9 +306,7 @@ export function instrumentWorkflow<
       // Extract env from constructor args (typically last arg)
       const env = args[args.length - 1] || {};
 
-      // Initialize config for this workflow instance
-      // Use Request as trigger type since workflows don't have a standard Trigger type yet
-      const trigger = new Request('https://workflow.local/run');
+      const trigger: WorkflowTrigger = { type: 'workflow', name: workflowName };
       const workflowConfig = initialiser(env, trigger);
       const context = setConfig(workflowConfig);
 
@@ -315,4 +326,3 @@ export function instrumentWorkflow<
 
   return wrap(workflowClass, classHandler);
 }
-

package/src/index.ts

@@ -51,6 +51,14 @@ export {
   instrumentD1,
   instrumentServiceBinding,
   instrumentBindings,
+  instrumentAI,
+  instrumentVectorize,
+  instrumentHyperdrive,
+  instrumentQueueProducer,
+  instrumentAnalyticsEngine,
+  instrumentImages,
+  instrumentRateLimiter,
+  instrumentBrowserRendering,
 } from './bindings';
 
 // Global instrumentations