autotel-edge 3.0.0

package/src/api/logger.ts

@@ -0,0 +1,197 @@
+/**
+ * Zero-dependency structured logger for edge environments
+ *
+ * This logger is ~100 LOC and provides:
+ * - Structured JSON logging
+ * - Auto trace context injection (traceId, spanId)
+ * - Dynamic log level control (per-request via context)
+ * - Level support (info, error, warn, debug)
+ * - Zero dependencies (console-based)
+ *
+ * Unlike Pino/Winston (~500KB), this is <1KB minified!
+ */
+
+import { trace, context as api_context, createContextKey } from '@opentelemetry/api';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+
+/**
+ * Context key for storing active log level (enables per-request log levels)
+ */
+const LOG_LEVEL_KEY = createContextKey('autotel-edge-log-level');
+
+export interface EdgeLogger {
+  info(msg: string, attrs?: Record<string, any>): void;
+  error(msg: string, error?: Error | unknown, attrs?: Record<string, any>): void;
+  warn(msg: string, attrs?: Record<string, any>): void;
+  debug(msg: string, attrs?: Record<string, any>): void;
+}
+
+/**
+ * Get the active log level from context (if set)
+ * Falls back to undefined if no log level is set in context
+ */
+export function getActiveLogLevel(): LogLevel | undefined {
+  return api_context.active().getValue(LOG_LEVEL_KEY) as LogLevel | undefined;
+}
+
+/**
+ * Run a function with a specific log level
+ * The log level is stored in OpenTelemetry context and applies to all logger calls within the callback
+ *
+ * This works in edge runtimes (uses OTel context, not Node.js AsyncLocalStorage)
+ *
+ * @example
+ * ```typescript
+ * // Enable debug logging for a specific request
+ * runWithLogLevel('debug', () => {
+ *   log.debug('This will be logged')
+ *   processRequest()
+ * })
+ *
+ * // Disable logging temporarily
+ * runWithLogLevel('none', () => {
+ *   log.info('This will NOT be logged')
+ * })
+ * ```
+ */
+export function runWithLogLevel<T>(level: LogLevel, callback: () => T): T {
+  const ctx = api_context.active().setValue(LOG_LEVEL_KEY, level);
+  return api_context.with(ctx, callback);
+}
+
+/**
+ * Get current trace context from active span
+ */
+function getTraceContext():
+  | { traceId: string; spanId: string; correlationId: string }
+  | null {
+  const span = trace.getActiveSpan();
+  if (!span) return null;
+
+  const ctx = span.spanContext();
+  return {
+    traceId: ctx.traceId,
+    spanId: ctx.spanId,
+    correlationId: ctx.traceId.slice(0, 16), // First 16 chars for grouping
+  };
+}
+
+/**
+ * Create a lightweight structured logger
+ *
+ * @param service - Service name for logging
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```typescript
+ * const log = createEdgeLogger('user-service')
+ *
+ * log.info('Creating user', { email: 'test@example.com' })
+ * // Output: {"level":"info","service":"user-service","msg":"Creating user",
+ * //          "email":"test@example.com","traceId":"...","spanId":"..."}
+ *
+ * // Dynamic log level control per-request
+ * runWithLogLevel('debug', () => {
+ *   log.debug('This will be logged even if logger was created with level: "info"')
+ * })
+ * ```
+ */
+export function createEdgeLogger(
+  service: string,
+  options?: {
+    level?: LogLevel;
+    pretty?: boolean; // For development
+  },
+): EdgeLogger {
+  const defaultLevel = options?.level || 'info';
+  const pretty = options?.pretty || false;
+
+  const levelPriority: Record<LogLevel, number> = {
+    none: -1,
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+  };
+
+  const shouldLog = (level: LogLevel): boolean => {
+    // Priority: context level > options level > 'info' default
+    const activeLevel = getActiveLogLevel() ?? defaultLevel;
+
+    // 'none' means suppress all logging
+    if (activeLevel === 'none') return false;
+
+    return levelPriority[level] >= levelPriority[activeLevel];
+  };
+
+  const log = (
+    level: 'info' | 'error' | 'warn' | 'debug',
+    msg: string,
+    attrs?: Record<string, any>,
+  ) => {
+    if (!shouldLog(level)) return;
+
+    const ctx = getTraceContext();
+    const logEntry: Record<string, any> = {
+      level,
+      service,
+      msg,
+      ...attrs,
+      ...ctx, // Auto-inject traceId, spanId, correlationId
+      timestamp: new Date().toISOString(),
+    };
+
+    if (pretty) {
+      // Pretty print for development
+      const traceInfo = ctx
+        ? ` [${ctx.traceId.slice(0, 8)}.../${ctx.spanId.slice(0, 8)}...]`
+        : '';
+      console.log(
+        `[${level.toUpperCase()}]${traceInfo} ${service}: ${msg}`,
+        attrs || '',
+      );
+    } else {
+      // Structured JSON for production
+      console.log(JSON.stringify(logEntry));
+    }
+  };
+
+  return {
+    info: (msg: string, attrs?: Record<string, any>) => log('info', msg, attrs),
+
+    error: (msg: string, error?: Error | unknown, attrs?: Record<string, any>) => {
+      const errorAttrs = error instanceof Error
+        ? {
+            error: error.message,
+            stack: error.stack,
+            name: error.name,
+            ...attrs,
+          }
+        : { error: String(error), ...attrs };
+
+      log('error', msg, errorAttrs);
+    },
+
+    warn: (msg: string, attrs?: Record<string, any>) => log('warn', msg, attrs),
+
+    debug: (msg: string, attrs?: Record<string, any>) => log('debug', msg, attrs),
+  };
+}
+
+/**
+ * Helper to get trace context (useful for BYOL - Bring Your Own Logger)
+ *
+ * @example
+ * ```typescript
+ * import bunyan from 'bunyan'
+ * import { getEdgeTraceContext } from 'autotel-edge/api/logger'
+ *
+ * const bunyanLogger = bunyan.createLogger({ name: 'myapp' })
+ * const ctx = getEdgeTraceContext()
+ * bunyanLogger.info({ ...ctx, email: 'test@example.com' }, 'Creating user')
+ * ```
+ */
+export function getEdgeTraceContext() {
+  return getTraceContext();
+}

package/src/compose.ts

@@ -0,0 +1,243 @@
+/**
+ * Composition utilities for autotel-edge
+ *
+ * Helper functions for composing instrumentation and middleware.
+ *
+ * @example
+ * ```typescript
+ * import { compose } from 'autotel-edge/api/compose'
+ * import { instrumentGlobalFetch, instrumentGlobalCache } from 'autotel-edge/instrumentation'
+ *
+ * const setupInstrumentation = compose(
+ *   instrumentGlobalFetch,
+ *   instrumentGlobalCache
+ * )
+ *
+ * setupInstrumentation({ enabled: true })
+ * ```
+ */
+
+/**
+ * Compose multiple setup functions into one
+ *
+ * Takes multiple instrumentation functions and returns a single function
+ * that calls them all in order with the same config.
+ *
+ * @example
+ * ```typescript
+ * const setup = compose(
+ *   instrumentGlobalFetch,
+ *   instrumentGlobalCache
+ * )
+ *
+ * setup({ enabled: true })
+ * ```
+ */
+export function compose<TConfig = unknown>(
+  ...fns: Array<(config?: TConfig) => void>
+): (config?: TConfig) => void {
+  return (config?: TConfig) => {
+    for (const fn of fns) {
+      fn(config);
+    }
+  };
+}
+
+/**
+ * Compose multiple async setup functions into one
+ *
+ * Like `compose` but for async functions.
+ *
+ * @example
+ * ```typescript
+ * const setup = composeAsync(
+ *   async (config) => { await initTracing(config) },
+ *   async (config) => { await initMetrics(config) }
+ * )
+ *
+ * await setup({ endpoint: 'https://...' })
+ * ```
+ */
+export function composeAsync<TConfig = unknown>(
+  ...fns: Array<(config?: TConfig) => Promise<void>>
+): (config?: TConfig) => Promise<void> {
+  return async (config?: TConfig) => {
+    for (const fn of fns) {
+      await fn(config);
+    }
+  };
+}
+
+/**
+ * Pipe - compose functions from left to right
+ *
+ * Unlike `compose` which is right-to-left, pipe is left-to-right
+ * which matches the execution order visually.
+ *
+ * @example
+ * ```typescript
+ * const setup = pipe(
+ *   (config) => ({ ...config, tracing: true }),
+ *   (config) => ({ ...config, metrics: true }),
+ *   (config) => initObservability(config)
+ * )
+ *
+ * setup({ service: 'my-worker' })
+ * ```
+ */
+export function pipe<TInput, TOutput>(
+  ...fns: Array<(input: any) => any>
+): (input: TInput) => TOutput {
+  return (input: TInput) => {
+    return fns.reduce((acc, fn) => fn(acc), input as any) as TOutput;
+  };
+}
+
+/**
+ * Create a conditional instrumentation function
+ *
+ * Only runs the instrumentation if the predicate returns true.
+ *
+ * @example
+ * ```typescript
+ * const setupFetch = when(
+ *   (env) => env.ENABLE_FETCH_TRACING === 'true',
+ *   instrumentGlobalFetch
+ * )
+ *
+ * setupFetch(env)
+ * ```
+ */
+export function when<TConfig = unknown>(
+  predicate: (config?: TConfig) => boolean,
+  fn: (config?: TConfig) => void
+): (config?: TConfig) => void {
+  return (config?: TConfig) => {
+    if (predicate(config)) {
+      fn(config);
+    }
+  };
+}
+
+/**
+ * Create a conditional async instrumentation function
+ *
+ * @example
+ * ```typescript
+ * const setupCache = whenAsync(
+ *   async (env) => await featureEnabled('cache-tracing'),
+ *   instrumentGlobalCache
+ * )
+ *
+ * await setupCache(env)
+ * ```
+ */
+export function whenAsync<TConfig = unknown>(
+  predicate: (config?: TConfig) => Promise<boolean> | boolean,
+  fn: (config?: TConfig) => Promise<void>
+): (config?: TConfig) => Promise<void> {
+  return async (config?: TConfig) => {
+    if (await predicate(config)) {
+      await fn(config);
+    }
+  };
+}
+
+/**
+ * Tap - run a side effect and return the original value
+ *
+ * Useful for logging or debugging in a pipe.
+ *
+ * @example
+ * ```typescript
+ * const setup = pipe(
+ *   tap((config) => console.log('Initial config:', config)),
+ *   (config) => ({ ...config, tracing: true }),
+ *   tap((config) => console.log('After tracing:', config)),
+ *   (config) => initObservability(config)
+ * )
+ * ```
+ */
+export function tap<T>(fn: (value: T) => void): (value: T) => T {
+  return (value: T) => {
+    fn(value);
+    return value;
+  };
+}
+
+/**
+ * Memoize - cache the result of a function
+ *
+ * Useful for expensive initialization functions that should only run once.
+ *
+ * @example
+ * ```typescript
+ * const setup = memoize(() => {
+ *   console.log('Setting up (expensive)...')
+ *   instrumentGlobalFetch()
+ *   instrumentGlobalCache()
+ * })
+ *
+ * setup() // Logs "Setting up (expensive)..."
+ * setup() // Does nothing (cached)
+ * setup() // Does nothing (cached)
+ * ```
+ */
+export function memoize<TArgs extends any[], TReturn>(
+  fn: (...args: TArgs) => TReturn
+): (...args: TArgs) => TReturn {
+  const cached: { hasValue: boolean; value: TReturn } = { hasValue: false, value: undefined as any };
+
+  return (...args: TArgs) => {
+    if (!cached.hasValue) {
+      cached.value = fn(...args);
+      cached.hasValue = true;
+    }
+    return cached.value;
+  };
+}
+
+/**
+ * Retry - retry a function on failure
+ *
+ * @example
+ * ```typescript
+ * const setupWithRetry = retry(
+ *   async () => {
+ *     await fetch('https://api.example.com/init')
+ *   },
+ *   { maxAttempts: 3, delayMs: 1000 }
+ * )
+ *
+ * await setupWithRetry()
+ * ```
+ */
+export function retry<TArgs extends any[], TReturn>(
+  fn: (...args: TArgs) => Promise<TReturn>,
+  options: {
+    maxAttempts?: number;
+    delayMs?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+  } = {}
+): (...args: TArgs) => Promise<TReturn> {
+  const { maxAttempts = 3, delayMs = 1000, onRetry } = options;
+
+  return async (...args: TArgs) => {
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        if (attempt < maxAttempts) {
+          onRetry?.(attempt, lastError);
+          await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+      }
+    }
+
+    throw lastError;
+  };
+}

package/src/core/buffer.ts

@@ -0,0 +1,16 @@
+/**
+ * Buffer polyfill for edge environments
+ *
+ * Cloudflare Workers and other edge runtimes need the Buffer global
+ * for OpenTelemetry OTLP serialization.
+ */
+
+//@ts-ignore - node:buffer available in CF Workers with nodejs_compat
+import { Buffer } from 'node:buffer';
+
+//@ts-ignore
+globalThis.Buffer = Buffer;
+
+
+
+export {Buffer} from 'node:buffer';