autotel-cloudflare 2.12.0 → 2.13.0

package/src/bindings/browser-rendering.ts

@@ -0,0 +1,70 @@
+/**
+ * Browser Rendering binding instrumentation
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap, setAttr } from './common';
+
+interface BrowserRenderingLike {
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Instrument Browser Rendering binding (manual only — not auto-detected)
+ */
+export function instrumentBrowserRendering<T extends BrowserRenderingLike>(browser: T, bindingName?: string): T {
+  const name = bindingName || 'browser';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'fetch' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const [input] = args as [RequestInfo | URL, RequestInit | undefined];
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            return tracer.startActiveSpan(
+              `BrowserRendering ${name}: fetch`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes: {
+                  'browser.system': 'cloudflare-browser-rendering',
+                  'url.full': url,
+                },
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  setAttr(span, 'http.response.status_code', result?.status);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } catch (error) {
+                  span.recordException(error as Error);
+                  span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                  });
+                  throw error;
+                } finally {
+                  span.end();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      return value;
+    },
+  };
+
+  return wrap(browser, handler);
+}

package/src/bindings/common.ts

@@ -60,6 +60,15 @@ export function unwrap<T extends object>(item: T): T {
   }
 }
 
+/**
+ * Set attribute only if value is defined and non-null
+ */
+export function setAttr(span: { setAttribute: (key: string, value: any) => void }, key: string, value: unknown): void {
+  if (value !== undefined && value !== null) {
+    span.setAttribute(key, value);
+  }
+}
+
 export function wrap<T extends object>(
   item: T,
   handler: ProxyHandler<T>,

package/src/bindings/hyperdrive.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { instrumentHyperdrive } from './hyperdrive';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+
+describe('Hyperdrive Binding 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, fn) => {
+        return fn(mockSpan);
+      }),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  function createMockHyperdrive(overrides: Partial<Hyperdrive> = {}): Hyperdrive {
+    return {
+      connect: vi.fn(async () => ({} as Socket)),
+      connectionString: 'postgresql://user:secret-password@db.example.com:5432/mydb',
+      host: 'db.example.com',
+      port: 5432,
+      user: 'user',
+      password: 'secret-password',
+      database: 'mydb',
+      ...overrides,
+    } as unknown as Hyperdrive;
+  }
+
+  describe('connect()', () => {
+    it('should create span with correct attributes', async () => {
+      const mockHyperdrive = createMockHyperdrive();
+      const instrumented = instrumentHyperdrive(mockHyperdrive, 'my-db');
+
+      await instrumented.connect();
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Hyperdrive my-db: connect');
+      expect(options.kind).toBe(SpanKind.CLIENT);
+      expect(options.attributes['db.system']).toBe('cloudflare-hyperdrive');
+      expect(options.attributes['db.operation']).toBe('connect');
+      expect(options.attributes['server.address']).toBe('db.example.com');
+      expect(options.attributes['server.port']).toBe(5432);
+      expect(options.attributes['db.user']).toBe('user');
+    });
+
+    it('should handle errors correctly', async () => {
+      const connectError = new Error('Connection refused');
+      const mockHyperdrive = createMockHyperdrive({
+        connect: vi.fn(async () => {
+          throw connectError;
+        }) as any,
+      });
+      const instrumented = instrumentHyperdrive(mockHyperdrive, 'my-db');
+
+      await expect(instrumented.connect()).rejects.toThrow('Connection refused');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(connectError);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Connection refused',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should set OK status and end span on success', async () => {
+      const mockSocket = { readable: true } as unknown as Socket;
+      const mockHyperdrive = createMockHyperdrive({
+        connect: vi.fn(async () => mockSocket) as any,
+      });
+      const instrumented = instrumentHyperdrive(mockHyperdrive, 'my-db');
+
+      const result = await instrumented.connect();
+
+      expect(result).toBe(mockSocket);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should use default binding name when none provided', async () => {
+      const mockHyperdrive = createMockHyperdrive();
+      const instrumented = instrumentHyperdrive(mockHyperdrive);
+
+      await instrumented.connect();
+
+      const [spanName] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Hyperdrive hyperdrive: connect');
+    });
+  });
+
+  describe('non-instrumented properties', () => {
+    it('should pass through non-instrumented properties', () => {
+      const mockHyperdrive = createMockHyperdrive();
+      const instrumented = instrumentHyperdrive(mockHyperdrive, 'my-db');
+
+      expect(instrumented.connectionString).toBe('postgresql://user:secret-password@db.example.com:5432/mydb');
+      expect(instrumented.host).toBe('db.example.com');
+      expect(instrumented.port).toBe(5432);
+      expect(instrumented.user).toBe('user');
+      expect(instrumented.database).toBe('mydb');
+    });
+  });
+
+  describe('security', () => {
+    it('should never record password as an attribute', async () => {
+      const mockHyperdrive = createMockHyperdrive({
+        password: 'super-secret-password',
+      });
+      const instrumented = instrumentHyperdrive(mockHyperdrive, 'my-db');
+
+      await instrumented.connect();
+
+      const [, options] = mockTracer.startActiveSpan.mock.calls[0];
+
+      // Verify password is not in the attributes
+      const attributeKeys = Object.keys(options.attributes);
+      for (const key of attributeKeys) {
+        expect(options.attributes[key]).not.toBe('super-secret-password');
+      }
+      expect(options.attributes['db.password']).toBeUndefined();
+      expect(options.attributes['password']).toBeUndefined();
+
+      // Also verify setAttribute was not called with the password
+      for (const call of mockSpan.setAttribute.mock.calls) {
+        expect(call[1]).not.toBe('super-secret-password');
+      }
+    });
+  });
+});

package/src/bindings/hyperdrive.ts

@@ -0,0 +1,74 @@
+/**
+ * Hyperdrive binding instrumentation
+ */
+
+import {
+  trace,
+  SpanKind,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import type { WorkerTracer } from 'autotel-edge';
+import { wrap, setAttr } from './common';
+
+/**
+ * Instrument Hyperdrive binding
+ */
+export function instrumentHyperdrive<T extends Hyperdrive>(hyperdrive: T, bindingName?: string): T {
+  const name = bindingName || 'hyperdrive';
+
+  const handler: ProxyHandler<T> = {
+    get(target, prop) {
+      const value = Reflect.get(target, prop);
+
+      if (prop === 'connect' && typeof value === 'function') {
+        return new Proxy(value, {
+          apply: (fnTarget, thisArg, args) => {
+            const tracer = trace.getTracer('autotel-edge') as WorkerTracer;
+
+            const attributes: Record<string, string | number> = {
+              'db.system': 'cloudflare-hyperdrive',
+              'db.operation': 'connect',
+            };
+
+            // Extract connection info safely (never record password)
+            try {
+              setAttr({ setAttribute: (k: string, v: any) => { if (v !== undefined && v !== null) attributes[k] = v; } }, 'server.address', target.host);
+              setAttr({ setAttribute: (k: string, v: any) => { if (v !== undefined && v !== null) attributes[k] = v; } }, 'server.port', target.port);
+              setAttr({ setAttribute: (k: string, v: any) => { if (v !== undefined && v !== null) attributes[k] = v; } }, 'db.user', target.user);
+            } catch {
+              // Properties may not be accessible in all environments
+            }
+
+            return tracer.startActiveSpan(
+              `Hyperdrive ${name}: connect`,
+              {
+                kind: SpanKind.CLIENT,
+                attributes,
+              },
+              async (span) => {
+                try {
+                  const result = await Reflect.apply(fnTarget, thisArg, args);
+                  span.setStatus({ code: SpanStatusCode.OK });
+                  return result;
+                } catch (error) {
+                  span.recordException(error as Error);
+                  span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                  });
+                  throw error;
+                } finally {
+                  span.end();
+                }
+              },
+            );
+          },
+        });
+      }
+
+      return value;
+    },
+  };
+
+  return wrap(hyperdrive, handler);
+}

package/src/bindings/images.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+import { instrumentImages } from './images';
+
+describe('Images Binding 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, fn) => {
+        return fn(mockSpan);
+      }),
+    };
+
+    getTracerSpy = vi.spyOn(trace, 'getTracer').mockReturnValue(mockTracer as any);
+  });
+
+  afterEach(() => {
+    getTracerSpy.mockRestore();
+  });
+
+  function createMockImages() {
+    const mockTransformer: any = {
+      transform: vi.fn(function (this: any) {
+        return mockTransformer;
+      }),
+      draw: vi.fn(function (this: any) {
+        return mockTransformer;
+      }),
+      output: vi.fn(async () => ({
+        response: () => new Response('image-data'),
+        blob: async () => new Blob(['image-data']),
+        arrayBuffer: async () => new ArrayBuffer(8),
+      })),
+    };
+
+    return {
+      images: {
+        info: vi.fn(async () => ({ width: 800, height: 600, format: 'png' })),
+        input: vi.fn(() => mockTransformer),
+        someOtherMethod: vi.fn(() => 'passthrough'),
+        someProperty: 'test-value',
+      },
+      mockTransformer,
+    };
+  }
+
+  describe('info()', () => {
+    it('should create its own span with correct attributes', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      await instrumented.info(new ArrayBuffer(8));
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Images my-images: info');
+      expect(options.kind).toBe(SpanKind.CLIENT);
+      expect(options.attributes['images.system']).toBe('cloudflare-images');
+      expect(options.attributes['images.operation']).toBe('info');
+    });
+
+    it('should record width, height, format from result', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      await instrumented.info(new ArrayBuffer(8));
+
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('images.width', 800);
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('images.height', 600);
+      expect(mockSpan.setAttribute).toHaveBeenCalledWith('images.format', 'png');
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({ code: SpanStatusCode.OK });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+
+    it('should handle errors', async () => {
+      const { images } = createMockImages();
+      const testError = new Error('Image info failed');
+      images.info = vi.fn(async () => {
+        throw testError;
+      });
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      await expect(instrumented.info(new ArrayBuffer(8))).rejects.toThrow('Image info failed');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(testError);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Image info failed',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+  });
+
+  describe('pipeline: input() -> output()', () => {
+    it('should create a single span at output() with operation_count = 0', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const transformer = instrumented.input(new ArrayBuffer(8));
+      await transformer.output();
+
+      // Only one span created at output(), not at input()
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [spanName, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(spanName).toBe('Images my-images: output');
+      expect(options.attributes['images.system']).toBe('cloudflare-images');
+      expect(options.attributes['images.pipeline.operation_count']).toBe(0);
+    });
+  });
+
+  describe('pipeline: input() -> transform() -> output()', () => {
+    it('should create span with operation_count = 1', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const transformer = instrumented.input(new ArrayBuffer(8));
+      const transformed = transformer.transform({ width: 400 });
+      await transformed.output();
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(options.attributes['images.pipeline.operation_count']).toBe(1);
+    });
+  });
+
+  describe('pipeline: input() -> transform() -> draw() -> output()', () => {
+    it('should create span with operation_count = 2', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const transformer = instrumented.input(new ArrayBuffer(8));
+      const transformed = transformer.transform({ width: 400 });
+      const drawn = transformed.draw({});
+      await drawn.output();
+
+      expect(mockTracer.startActiveSpan).toHaveBeenCalledTimes(1);
+
+      const [, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(options.attributes['images.pipeline.operation_count']).toBe(2);
+    });
+  });
+
+  describe('output() format capture', () => {
+    it('should capture format from string arg', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const transformer = instrumented.input(new ArrayBuffer(8));
+      await transformer.output('webp');
+
+      const [, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(options.attributes['images.output.format']).toBe('webp');
+    });
+
+    it('should capture format from options object', async () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const transformer = instrumented.input(new ArrayBuffer(8));
+      await transformer.output({ format: 'avif' });
+
+      const [, options] = mockTracer.startActiveSpan.mock.calls[0];
+      expect(options.attributes['images.output.format']).toBe('avif');
+    });
+
+    it('should handle errors in output()', async () => {
+      const { images, mockTransformer } = createMockImages();
+      const testError = new Error('Output failed');
+      mockTransformer.output = vi.fn(async () => {
+        throw testError;
+      });
+
+      const instrumented = instrumentImages(images as any, 'my-images');
+      const transformer = instrumented.input(new ArrayBuffer(8));
+
+      await expect(transformer.output()).rejects.toThrow('Output failed');
+
+      expect(mockSpan.recordException).toHaveBeenCalledWith(testError);
+      expect(mockSpan.setStatus).toHaveBeenCalledWith({
+        code: SpanStatusCode.ERROR,
+        message: 'Output failed',
+      });
+      expect(mockSpan.end).toHaveBeenCalled();
+    });
+  });
+
+  describe('non-instrumented methods', () => {
+    it('should pass through non-instrumented methods unchanged', () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      const result = (instrumented as any).someOtherMethod();
+
+      expect(result).toBe('passthrough');
+      expect(images.someOtherMethod).toHaveBeenCalled();
+      expect(mockTracer.startActiveSpan).not.toHaveBeenCalled();
+    });
+
+    it('should pass through non-instrumented properties unchanged', () => {
+      const { images } = createMockImages();
+      const instrumented = instrumentImages(images as any, 'my-images');
+
+      expect((instrumented as any).someProperty).toBe('test-value');
+      expect(mockTracer.startActiveSpan).not.toHaveBeenCalled();
+    });
+  });
+});