autotel 4.1.0 → 4.2.0

package/src/http.ts

@@ -1,424 +0,0 @@
-/**
- * HTTP Instrumentation Helpers
- *
- * Optional import: Not included in main bundle
- * Import from: 'autotel/http'
- *
- * Provides decorators and utilities for HTTP client instrumentation.
- * Works with fetch, axios, and other HTTP clients.
- *
- * @example
- * ```typescript
- * import { HttpInstrumented } from 'autotel/http'
- *
- * @HttpInstrumented()
- * class ApiClient {
- *   async getUser(id: string) {
- *     return fetch(`/api/users/${id}`)
- *   }
- * }
- * ```
- */
-
-import { SpanStatusCode, context, propagation } from '@opentelemetry/api';
-import { getConfig } from './config';
-import { getActiveContextWithBaggage } from './trace-context';
-
-export interface HttpInstrumentedOptions {
-  /** Service name for HTTP calls (default: 'http-client') */
-  serviceName?: string;
-  /** Extract URL from method arguments (default: first arg) */
-  urlExtractor?: (args: unknown[]) => string | undefined;
-  /** Extract HTTP method from method name or args */
-  methodExtractor?: (methodName: string, args: unknown[]) => string;
-  /** Add custom attributes to spans */
-  attributesFromArgs?: (args: unknown[]) => Record<string, string | number>;
-  /** Slow request threshold in milliseconds (adds warning attribute) - default: 3000ms */
-  slowRequestThresholdMs?: number;
-}
-
-/**
- * Decorator for auto-instrumenting HTTP client methods
- *
- * @example Basic usage
- * ```typescript
- * @HttpInstrumented()
- * class ApiClient {
- *   async fetchUser(userId: string) {
- *     const res = await fetch(`https://api.example.com/users/${userId}`)
- *     return res.json()
- *   }
- *
- *   async createOrder(order: Order) {
- *     const res = await fetch('https://api.example.com/orders', {
- *       method: 'POST',
- *       body: JSON.stringify(order)
- *     })
- *     return res.json()
- *   }
- * }
- * ```
- *
- * @example Advanced usage with custom extractors
- * ```typescript
- * @HttpInstrumented({
- *   serviceName: 'payment-gateway',
- *   urlExtractor: (args) => {
- *     const config = args[0] as RequestConfig
- *     return config.url
- *   },
- *   attributesFromArgs: (args) => ({
- *     'http.request_id': args[0]?.requestId,
- *     'http.retry_count': args[0]?.retryCount || 0
- *   })
- * })
- * class PaymentClient {
- *   async charge(config: RequestConfig) {
- *     return axios(config)
- *   }
- * }
- * ```
- */
-export function HttpInstrumented(options: HttpInstrumentedOptions = {}) {
-  const serviceName = options.serviceName || 'http-client';
-  const slowRequestThresholdMs = options.slowRequestThresholdMs ?? 3000;
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-empty-object-type
-  return function <T extends { new (...args: any[]): {} }>(
-    target: T,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _context: ClassDecoratorContext,
-  ) {
-    return class extends target {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      constructor(...args: any[]) {
-        super(...args);
-
-        const proto = target.prototype;
-        const methodNames = Object.getOwnPropertyNames(proto).filter(
-          (name) =>
-            name !== 'constructor' &&
-            typeof proto[name] === 'function' &&
-            !name.startsWith('_'),
-        );
-
-        for (const methodName of methodNames) {
-          const originalMethod = proto[methodName];
-
-          if (
-            originalMethod.constructor.name === 'AsyncFunction' ||
-            originalMethod.toString().startsWith('async ')
-          ) {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const wrappedMethod = async (...args: any[]) => {
-              const config = getConfig();
-              const tracer = config.tracer;
-
-              const url = options.urlExtractor
-                ? options.urlExtractor(args)
-                : (args[0] as string | undefined);
-
-              const method = options.methodExtractor
-                ? options.methodExtractor(methodName, args)
-                : inferHttpMethod(methodName);
-
-              const spanName = url
-                ? `HTTP ${method} ${extractPath(url)}`
-                : `HTTP ${method}`;
-
-              return tracer.startActiveSpan(spanName, async (span) => {
-                const startTime = performance.now();
-
-                try {
-                  span.setAttributes({
-                    'http.method': method,
-                    'http.url': url || 'unknown',
-                    'service.name': serviceName,
-                    'operation.name': `${serviceName}.${methodName}`,
-                  });
-
-                  if (url) {
-                    const urlObj = parseUrl(url);
-                    span.setAttributes({
-                      'http.scheme': urlObj.protocol,
-                      'http.host': urlObj.host,
-                      'http.target': urlObj.path,
-                    });
-                  }
-
-                  if (options.attributesFromArgs) {
-                    span.setAttributes(options.attributesFromArgs(args));
-                  }
-
-                  const result = await originalMethod.apply(this, args);
-
-                  const duration = performance.now() - startTime;
-
-                  // Extract status code from response
-                  const statusCode = extractStatusCode(result);
-                  if (statusCode) {
-                    span.setAttribute('http.status_code', statusCode);
-
-                    if (statusCode >= 400) {
-                      span.setStatus({
-                        code: SpanStatusCode.ERROR,
-                        message: `HTTP ${statusCode}`,
-                      });
-                    } else {
-                      span.setStatus({ code: SpanStatusCode.OK });
-                    }
-                  } else {
-                    span.setStatus({ code: SpanStatusCode.OK });
-                  }
-
-                  span.setAttributes({
-                    'http.duration_ms': duration,
-                  });
-
-                  // Mark slow requests for investigation
-                  if (duration > slowRequestThresholdMs) {
-                    span.setAttribute('http.slow_request', true);
-                    span.setAttribute(
-                      'http.slow_request_threshold_ms',
-                      slowRequestThresholdMs,
-                    );
-                  }
-
-                  return result;
-                } catch (error) {
-                  const duration = performance.now() - startTime;
-
-                  span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message:
-                      error instanceof Error ? error.message : 'Unknown error',
-                  });
-
-                  span.setAttributes({
-                    'http.duration_ms': duration,
-                    'error.type':
-                      error instanceof Error
-                        ? error.constructor.name
-                        : 'Unknown',
-                    'error.message':
-                      error instanceof Error ? error.message : 'Unknown error',
-                  });
-
-                  throw error;
-                } finally {
-                  span.end();
-                }
-              });
-            };
-
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (this as any)[methodName] = wrappedMethod;
-          }
-        }
-      }
-    };
-  };
-}
-
-/**
- * Helper: Trace a single HTTP request
- *
- * @example
- * ```typescript
- * import { traceHttpRequest } from 'autotel/http'
- *
- * const data = await traceHttpRequest(
- *   'GET /api/users',
- *   () => fetch('https://api.example.com/users')
- * )
- * ```
- */
-export async function traceHttpRequest<T>(
-  spanName: string,
-  fn: () => Promise<T>,
-  attributes?: Record<string, string | number>,
-): Promise<T> {
-  const config = getConfig();
-  const tracer = config.tracer;
-
-  return tracer.startActiveSpan(spanName, async (span) => {
-    try {
-      if (attributes) {
-        span.setAttributes(attributes);
-      }
-
-      const result = await fn();
-      span.setStatus({ code: SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: error instanceof Error ? error.message : 'Unknown error',
-      });
-      throw error;
-    } finally {
-      span.end();
-    }
-  });
-}
-
-// Helper functions
-
-function inferHttpMethod(methodName: string): string {
-  const lower = methodName.toLowerCase();
-  if (
-    lower.includes('get') ||
-    lower.includes('fetch') ||
-    lower.includes('list')
-  )
-    return 'GET';
-  if (lower.includes('post') || lower.includes('create')) return 'POST';
-  if (lower.includes('put') || lower.includes('update')) return 'PUT';
-  if (lower.includes('delete') || lower.includes('remove')) return 'DELETE';
-  if (lower.includes('patch')) return 'PATCH';
-  return 'GET'; // Default
-}
-
-function extractPath(url: string): string {
-  try {
-    const urlObj = new URL(url);
-    return urlObj.pathname;
-  } catch {
-    // Relative URL or invalid
-    return url.split('?')[0] || url;
-  }
-}
-
-function parseUrl(url: string): {
-  protocol: string;
-  host: string;
-  path: string;
-} {
-  try {
-    const urlObj = new URL(url);
-    return {
-      protocol: urlObj.protocol.replace(':', ''),
-      host: urlObj.host,
-      path: urlObj.pathname + urlObj.search,
-    };
-  } catch {
-    return {
-      protocol: 'http',
-      host: 'unknown',
-      path: url,
-    };
-  }
-}
-
-function extractStatusCode(result: unknown): number | undefined {
-  if (result && typeof result === 'object') {
-    // Check for Response.status (fetch API)
-    if ('status' in result && typeof result.status === 'number') {
-      return result.status;
-    }
-    // Check for statusCode (axios, node http)
-    if ('statusCode' in result && typeof result.statusCode === 'number') {
-      return result.statusCode;
-    }
-  }
-  return undefined;
-}
-
-/**
- * Inject trace context into HTTP headers (for distributed tracing)
- *
- * This includes W3C Trace Context (traceparent, tracestate) and W3C Baggage headers.
- * Uses OpenTelemetry's propagation system for full compatibility.
- *
- * @example
- * ```typescript
- * import { injectTraceContext } from 'autotel/http'
- *
- * const headers = injectTraceContext({
- *   'Content-Type': 'application/json'
- * })
- *
- * fetch('/api/users', { headers })
- * ```
- *
- * @example With baggage
- * ```typescript
- * import { trace, withBaggage, injectTraceContext } from 'autotel'
- *
- * export const createOrder = trace((ctx) => async (order: Order) => {
- *   return await withBaggage({
- *     baggage: { 'tenant.id': order.tenantId },
- *     fn: async () => {
- *       const headers = injectTraceContext();
- *       // Headers now include 'baggage' header with tenant.id
- *       await fetch('/api/charge', { headers });
- *     },
- *   });
- * });
- * ```
- */
-export function injectTraceContext(
-  headers: Record<string, string> = {},
-): Record<string, string> {
-  // Use getActiveContextWithBaggage to check stored context (from baggage setters)
-  // This ensures ctx.setBaggage() changes are included in injected headers
-  const currentContext = getActiveContextWithBaggage();
-
-  // Use OpenTelemetry's propagation.inject for full W3C support
-  // This includes traceparent, tracestate, and baggage headers
-  propagation.inject(currentContext, headers);
-
-  return headers;
-}
-
-/**
- * Extract trace context from HTTP headers (for distributed tracing)
- *
- * This extracts W3C Trace Context (traceparent, tracestate) and W3C Baggage headers.
- * Uses OpenTelemetry's propagation system for full compatibility.
- *
- * Returns a context that can be used with context.with() to run code
- * with the extracted trace context and baggage.
- *
- * @example
- * ```typescript
- * import { extractTraceContext, trace } from 'autotel'
- * import { context } from 'autotel'
- *
- * // In Express middleware
- * app.use((req, res, next) => {
- *   const extractedContext = extractTraceContext(req.headers);
- *   context.with(extractedContext, () => {
- *     next();
- *   });
- * });
- * ```
- *
- * @example In a traced function
- * ```typescript
- * export const handleWebhook = trace((ctx) => async (req: Request) => {
- *   const extractedContext = extractTraceContext(req.headers);
- *   return await context.with(extractedContext, async () => {
- *     // Now ctx.getBaggage() will return baggage from the incoming request
- *     const tenantId = ctx.getBaggage('tenant.id');
- *     await processWebhook(req.body);
- *   });
- * });
- * ```
- */
-export function extractTraceContext(
-  headers: Record<string, string | string[] | undefined>,
-): ReturnType<typeof context.active> {
-  const carrier: Record<string, string> = {};
-
-  // Convert headers to flat string format expected by propagation
-  for (const [key, value] of Object.entries(headers)) {
-    if (value !== undefined) {
-      carrier[key] = Array.isArray(value) ? (value[0] ?? '') : value;
-    }
-  }
-
-  // Extract context using OpenTelemetry's propagation system
-  // Returns a Context that can be used with context.with()
-  return propagation.extract(context.active(), carrier);
-}