@originals/sdk 1.8.1 → 1.8.2

package/src/utils/Logger.ts

@@ -0,0 +1,324 @@
+/**
+ * Enhanced Logger for Originals SDK
+ * 
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Child loggers with hierarchical context
+ * - Performance timing with startTimer
+ * - Multiple output destinations
+ * - Data sanitization for sensitive information
+ * - Async-safe operations
+ */
+
+import type { OriginalsConfig } from '../types';
+
+/**
+ * Log level type
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  context: string;
+  message: string;
+  data?: unknown;
+  duration?: number; // For performance tracking
+  traceId?: string; // For request correlation
+}
+
+/**
+ * Log output interface for custom outputs
+ */
+export interface LogOutput {
+  write(entry: LogEntry): void | Promise<void>;
+}
+
+/**
+ * Console log output implementation
+ */
+export class ConsoleLogOutput implements LogOutput {
+  write(entry: LogEntry): void {
+    const timestamp = entry.timestamp;
+    const level = entry.level.toUpperCase().padEnd(5);
+    const context = entry.context;
+    const message = entry.message;
+    const durationStr = entry.duration !== undefined ? ` (${entry.duration.toFixed(2)}ms)` : '';
+    const dataStr = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+    
+    const logMessage = `[${timestamp}] ${level} [${context}] ${message}${durationStr}${dataStr}`;
+    
+    switch (entry.level) {
+      case 'debug':
+        console.debug(logMessage);
+        break;
+      case 'info':
+        console.info(logMessage);
+        break;
+      case 'warn':
+        console.warn(logMessage);
+        break;
+      case 'error':
+        console.error(logMessage);
+        break;
+    }
+  }
+}
+
+/**
+ * File log output implementation (async)
+ */
+export class FileLogOutput implements LogOutput {
+  private buffer: string[] = [];
+  private flushTimeout: ReturnType<typeof setTimeout> | null = null;
+  private readonly flushInterval = 1000; // Flush every 1 second
+
+  constructor(private filePath: string) {}
+
+  write(entry: LogEntry): void {
+    // Format as JSON line
+    const line = JSON.stringify(entry) + '\n';
+    this.buffer.push(line);
+
+    // Schedule flush
+    if (!this.flushTimeout) {
+      this.flushTimeout = setTimeout(() => {
+        void this.flush();
+      }, this.flushInterval);
+    }
+  }
+  
+  private async flush(): Promise<void> {
+    if (this.buffer.length === 0) {
+      return;
+    }
+    
+    const lines = this.buffer.join('');
+    this.buffer = [];
+    this.flushTimeout = null;
+    
+    try {
+      // Use Bun's file API for efficient file writing
+      const file = Bun.file(this.filePath);
+      const exists = await file.exists();
+      
+      if (exists) {
+        // Append to existing file
+        const content = await file.text();
+        await Bun.write(this.filePath, content + lines);
+      } else {
+        // Create new file
+        await Bun.write(this.filePath, lines);
+      }
+    } catch (err) {
+      // Fallback to console on file write error
+      console.error('Failed to write log file:', err);
+    }
+  }
+}
+
+/**
+ * Main Logger class
+ */
+export class Logger {
+  private outputs: LogOutput[] = [];
+  private minLevel: LogLevel;
+  private includeTimestamps: boolean;
+  private includeContext: boolean;
+  private sanitizeLogs: boolean;
+  
+  // Log level priorities
+  private static readonly LEVEL_PRIORITY: Record<LogLevel, number> = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+  };
+  
+  constructor(
+    private context: string,
+    config: OriginalsConfig
+  ) {
+    this.minLevel = config.logging?.level || 'info';
+    this.includeTimestamps = config.logging?.includeTimestamps !== false;
+    this.includeContext = config.logging?.includeContext !== false;
+    this.sanitizeLogs = config.logging?.sanitizeLogs !== false;
+    
+    // Set up default outputs
+    if (config.logging?.outputs && config.logging.outputs.length > 0) {
+      this.outputs = [...config.logging.outputs];
+    } else {
+      // Default to console output
+      this.outputs = [new ConsoleLogOutput()];
+    }
+  }
+  
+  /**
+   * Log a debug message
+   */
+  debug(message: string, data?: unknown): void {
+    this.log('debug', message, data);
+  }
+
+  /**
+   * Log an info message
+   */
+  info(message: string, data?: unknown): void {
+    this.log('info', message, data);
+  }
+
+  /**
+   * Log a warning message
+   */
+  warn(message: string, data?: unknown): void {
+    this.log('warn', message, data);
+  }
+
+  /**
+   * Log an error message
+   */
+  error(message: string, error?: Error, data?: unknown): void {
+    const errorData: unknown = error ? {
+      ...(data && typeof data === 'object' ? data : {}),
+      error: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      }
+    } : data;
+
+    this.log('error', message, errorData);
+  }
+  
+  /**
+   * Start a timer for performance tracking
+   * Returns a function that stops the timer and logs the duration
+   */
+  startTimer(operation: string): () => void {
+    const startTime = performance.now();
+    
+    return () => {
+      const duration = performance.now() - startTime;
+      this.log('debug', `${operation} completed`, undefined, duration);
+    };
+  }
+  
+  /**
+   * Create a child logger with nested context
+   */
+  child(childContext: string): Logger {
+    const newLogger = Object.create(Logger.prototype) as Logger;
+    newLogger.context = `${this.context}:${childContext}`;
+    newLogger.outputs = this.outputs;
+    newLogger.minLevel = this.minLevel;
+    newLogger.includeTimestamps = this.includeTimestamps;
+    newLogger.includeContext = this.includeContext;
+    newLogger.sanitizeLogs = this.sanitizeLogs;
+    return newLogger;
+  }
+  
+  /**
+   * Set a single output (replaces existing outputs)
+   */
+  setOutput(output: LogOutput): void {
+    this.outputs = [output];
+  }
+  
+  /**
+   * Add an output to the existing outputs
+   */
+  addOutput(output: LogOutput): void {
+    this.outputs.push(output);
+  }
+  
+  /**
+   * Internal log method
+   */
+  private log(level: LogLevel, message: string, data?: unknown, duration?: number): void {
+    // Check if we should log this level
+    if (Logger.LEVEL_PRIORITY[level] < Logger.LEVEL_PRIORITY[this.minLevel]) {
+      return;
+    }
+    
+    // Sanitize data if needed
+    const sanitizedData = this.sanitizeLogs ? this.sanitize(data) : data;
+    
+    // Create log entry
+    const entry: LogEntry = {
+      timestamp: this.includeTimestamps ? new Date().toISOString() : '',
+      level,
+      context: this.includeContext ? this.context : '',
+      message,
+      data: sanitizedData,
+      duration
+    };
+    
+    // Write to all outputs (fire and forget for async outputs)
+    for (const output of this.outputs) {
+      try {
+        const result = output.write(entry);
+        // If result is a promise, don't await it (non-blocking)
+        if (result instanceof Promise) {
+          result.catch(err => {
+            // Silently fail for async outputs to avoid blocking
+            if (typeof console !== 'undefined' && console.error) {
+              console.error('Log output error:', err);
+            }
+          });
+        }
+      } catch (err) {
+        // Continue even if one output fails
+        if (typeof console !== 'undefined' && console.error) {
+          console.error('Log output error:', err);
+        }
+      }
+    }
+  }
+  
+  /**
+   * Sanitize sensitive data from logs
+   */
+  private sanitize(data: unknown): unknown {
+    if (!data) {
+      return data;
+    }
+
+    // Handle arrays
+    if (Array.isArray(data)) {
+      return data.map(item => this.sanitize(item));
+    }
+
+    // Handle objects
+    if (typeof data === 'object') {
+      const sanitized: Record<string, unknown> = {};
+      
+      for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        
+        // Sanitize sensitive keys
+        if (
+          lowerKey.includes('private') ||
+          lowerKey.includes('key') ||
+          lowerKey.includes('secret') ||
+          lowerKey.includes('password') ||
+          lowerKey.includes('token') ||
+          lowerKey.includes('credential')
+        ) {
+          sanitized[key] = '[REDACTED]';
+        } else {
+          // Recursively sanitize nested objects
+          sanitized[key] = this.sanitize(value);
+        }
+      }
+      
+      return sanitized;
+    }
+    
+    // Return primitive values as-is
+    return data;
+  }
+}
+

package/src/utils/MetricsCollector.ts

@@ -0,0 +1,358 @@
+/**
+ * Metrics Collector for Originals SDK
+ * 
+ * Features:
+ * - Track operation counts and performance
+ * - Asset lifecycle metrics (created, migrated, transferred)
+ * - Error tracking by error code
+ * - Cache statistics (optional)
+ * - Export in JSON and Prometheus formats
+ * - Memory-efficient storage
+ */
+
+import type { LayerType } from '../types';
+
+/**
+ * Operation-specific metrics
+ */
+export interface OperationMetrics {
+  count: number;
+  totalTime: number;
+  avgTime: number;
+  minTime: number;
+  maxTime: number;
+  errorCount: number;
+}
+
+/**
+ * Complete metrics snapshot
+ */
+export interface Metrics {
+  // Asset operations
+  assetsCreated: number;
+  assetsMigrated: Record<string, number>; // by layer transition (e.g., "peer→webvh": 5)
+  assetsTransferred: number;
+  
+  // Operation performance
+  operationTimes: Record<string, OperationMetrics>;
+  
+  // Error tracking
+  errors: Record<string, number>; // by error code
+  
+  // Cache statistics (if caching is implemented)
+  cacheStats?: {
+    hits: number;
+    misses: number;
+    hitRate: number;
+  };
+  
+  // System metrics
+  startTime: string;
+  uptime: number; // milliseconds
+}
+
+/**
+ * MetricsCollector class
+ */
+export class MetricsCollector {
+  private assetsCreatedCount = 0;
+  private assetsMigratedMap: Map<string, number> = new Map();
+  private assetsTransferredCount = 0;
+  
+  private operationMetrics: Map<string, {
+    count: number;
+    totalTime: number;
+    minTime: number;
+    maxTime: number;
+    errorCount: number;
+  }> = new Map();
+  
+  private errorCounts: Map<string, number> = new Map();
+  
+  private cacheHits = 0;
+  private cacheMisses = 0;
+  
+  private readonly startTime: string;
+  
+  constructor() {
+    this.startTime = new Date().toISOString();
+  }
+  
+  /**
+   * Record an operation with timing and success status
+   */
+  recordOperation(operation: string, duration: number, success: boolean): void {
+    if (!this.operationMetrics.has(operation)) {
+      this.operationMetrics.set(operation, {
+        count: 0,
+        totalTime: 0,
+        minTime: Infinity,
+        maxTime: -Infinity,
+        errorCount: 0
+      });
+    }
+    
+    const metrics = this.operationMetrics.get(operation)!;
+    metrics.count++;
+    metrics.totalTime += duration;
+    metrics.minTime = Math.min(metrics.minTime, duration);
+    metrics.maxTime = Math.max(metrics.maxTime, duration);
+    
+    if (!success) {
+      metrics.errorCount++;
+    }
+  }
+  
+  /**
+   * Start tracking an operation, returns completion function
+   */
+  startOperation(operation: string): () => void {
+    const startTime = performance.now();
+    
+    return (success: boolean = true) => {
+      const duration = performance.now() - startTime;
+      this.recordOperation(operation, duration, success);
+    };
+  }
+  
+  /**
+   * Record an asset creation
+   */
+  recordAssetCreated(): void {
+    this.assetsCreatedCount++;
+  }
+  
+  /**
+   * Record an asset migration between layers
+   */
+  recordMigration(from: LayerType, to: LayerType): void {
+    // Create transition key
+    const fromShort = from.split(':')[1]; // "peer", "webvh", "btco"
+    const toShort = to.split(':')[1];
+    const transitionKey = `${fromShort}→${toShort}`;
+    
+    const current = this.assetsMigratedMap.get(transitionKey) || 0;
+    this.assetsMigratedMap.set(transitionKey, current + 1);
+  }
+  
+  /**
+   * Record an asset transfer
+   */
+  recordTransfer(): void {
+    this.assetsTransferredCount++;
+  }
+  
+  /**
+   * Record an error by error code
+   */
+  recordError(code: string, operation?: string): void {
+    // Track error by code
+    const current = this.errorCounts.get(code) || 0;
+    this.errorCounts.set(code, current + 1);
+    
+    // If operation is provided, increment its error count
+    if (operation && this.operationMetrics.has(operation)) {
+      this.operationMetrics.get(operation)!.errorCount++;
+    }
+  }
+  
+  /**
+   * Record a cache hit
+   */
+  recordCacheHit(): void {
+    this.cacheHits++;
+  }
+  
+  /**
+   * Record a cache miss
+   */
+  recordCacheMiss(): void {
+    this.cacheMisses++;
+  }
+  
+  /**
+   * Get a snapshot of all metrics
+   */
+  getMetrics(): Metrics {
+    const operationTimes: Record<string, OperationMetrics> = {};
+    
+    for (const [operation, metrics] of this.operationMetrics.entries()) {
+      operationTimes[operation] = {
+        count: metrics.count,
+        totalTime: metrics.totalTime,
+        avgTime: metrics.count > 0 ? metrics.totalTime / metrics.count : 0,
+        minTime: metrics.minTime === Infinity ? 0 : metrics.minTime,
+        maxTime: metrics.maxTime === -Infinity ? 0 : metrics.maxTime,
+        errorCount: metrics.errorCount
+      };
+    }
+    
+    const assetsMigrated: Record<string, number> = {};
+    for (const [key, count] of this.assetsMigratedMap.entries()) {
+      assetsMigrated[key] = count;
+    }
+    
+    const errors: Record<string, number> = {};
+    for (const [code, count] of this.errorCounts.entries()) {
+      errors[code] = count;
+    }
+    
+    const totalCacheRequests = this.cacheHits + this.cacheMisses;
+    const cacheStats = totalCacheRequests > 0 ? {
+      hits: this.cacheHits,
+      misses: this.cacheMisses,
+      hitRate: this.cacheHits / totalCacheRequests
+    } : undefined;
+    
+    return {
+      assetsCreated: this.assetsCreatedCount,
+      assetsMigrated,
+      assetsTransferred: this.assetsTransferredCount,
+      operationTimes,
+      errors,
+      cacheStats,
+      startTime: this.startTime,
+      uptime: Date.now() - new Date(this.startTime).getTime()
+    };
+  }
+  
+  /**
+   * Get metrics for a specific operation
+   */
+  getOperationMetrics(operation: string): OperationMetrics | null {
+    const metrics = this.operationMetrics.get(operation);
+    
+    if (!metrics) {
+      return null;
+    }
+    
+    return {
+      count: metrics.count,
+      totalTime: metrics.totalTime,
+      avgTime: metrics.count > 0 ? metrics.totalTime / metrics.count : 0,
+      minTime: metrics.minTime === Infinity ? 0 : metrics.minTime,
+      maxTime: metrics.maxTime === -Infinity ? 0 : metrics.maxTime,
+      errorCount: metrics.errorCount
+    };
+  }
+  
+  /**
+   * Reset all metrics
+   */
+  reset(): void {
+    this.assetsCreatedCount = 0;
+    this.assetsMigratedMap.clear();
+    this.assetsTransferredCount = 0;
+    this.operationMetrics.clear();
+    this.errorCounts.clear();
+    this.cacheHits = 0;
+    this.cacheMisses = 0;
+  }
+  
+  /**
+   * Export metrics in the specified format
+   */
+  export(format: 'json' | 'prometheus'): string {
+    if (format === 'json') {
+      return this.exportJSON();
+    } else if (format === 'prometheus') {
+      return this.exportPrometheus();
+    }
+    
+    throw new Error(`Unsupported export format: ${String(format)}`);
+  }
+  
+  /**
+   * Export metrics as JSON
+   */
+  private exportJSON(): string {
+    return JSON.stringify(this.getMetrics(), null, 2);
+  }
+  
+  /**
+   * Export metrics in Prometheus format
+   */
+  private exportPrometheus(): string {
+    const lines: string[] = [];
+    const metrics = this.getMetrics();
+    
+    // Asset metrics
+    lines.push('# HELP originals_assets_created_total Total number of assets created');
+    lines.push('# TYPE originals_assets_created_total counter');
+    lines.push(`originals_assets_created_total ${metrics.assetsCreated}`);
+    lines.push('');
+    
+    lines.push('# HELP originals_assets_transferred_total Total number of assets transferred');
+    lines.push('# TYPE originals_assets_transferred_total counter');
+    lines.push(`originals_assets_transferred_total ${metrics.assetsTransferred}`);
+    lines.push('');
+    
+    // Migration metrics
+    lines.push('# HELP originals_assets_migrated_total Total number of assets migrated by layer transition');
+    lines.push('# TYPE originals_assets_migrated_total counter');
+    for (const [transition, count] of Object.entries(metrics.assetsMigrated)) {
+      const [from, to] = transition.split('→');
+      lines.push(`originals_assets_migrated_total{from="${from}",to="${to}"} ${count}`);
+    }
+    lines.push('');
+    
+    // Operation metrics
+    for (const [operation, opMetrics] of Object.entries(metrics.operationTimes)) {
+      const safeOpName = operation.replace(/[^a-zA-Z0-9_]/g, '_');
+      
+      lines.push(`# HELP originals_operation_${safeOpName}_total Total number of ${operation} operations`);
+      lines.push(`# TYPE originals_operation_${safeOpName}_total counter`);
+      lines.push(`originals_operation_${safeOpName}_total ${opMetrics.count}`);
+      lines.push('');
+      
+      lines.push(`# HELP originals_operation_${safeOpName}_duration_milliseconds Duration of ${operation} operations`);
+      lines.push(`# TYPE originals_operation_${safeOpName}_duration_milliseconds summary`);
+      lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="0.0"} ${opMetrics.minTime}`);
+      lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="0.5"} ${opMetrics.avgTime}`);
+      lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="1.0"} ${opMetrics.maxTime}`);
+      lines.push(`originals_operation_${safeOpName}_duration_milliseconds_sum ${opMetrics.totalTime}`);
+      lines.push(`originals_operation_${safeOpName}_duration_milliseconds_count ${opMetrics.count}`);
+      lines.push('');
+      
+      lines.push(`# HELP originals_operation_${safeOpName}_errors_total Total number of errors in ${operation} operations`);
+      lines.push(`# TYPE originals_operation_${safeOpName}_errors_total counter`);
+      lines.push(`originals_operation_${safeOpName}_errors_total ${opMetrics.errorCount}`);
+      lines.push('');
+    }
+    
+    // Error metrics
+    lines.push('# HELP originals_errors_total Total number of errors by code');
+    lines.push('# TYPE originals_errors_total counter');
+    for (const [code, count] of Object.entries(metrics.errors)) {
+      lines.push(`originals_errors_total{code="${code}"} ${count}`);
+    }
+    lines.push('');
+    
+    // Cache metrics
+    if (metrics.cacheStats) {
+      lines.push('# HELP originals_cache_hits_total Total number of cache hits');
+      lines.push('# TYPE originals_cache_hits_total counter');
+      lines.push(`originals_cache_hits_total ${metrics.cacheStats.hits}`);
+      lines.push('');
+      
+      lines.push('# HELP originals_cache_misses_total Total number of cache misses');
+      lines.push('# TYPE originals_cache_misses_total counter');
+      lines.push(`originals_cache_misses_total ${metrics.cacheStats.misses}`);
+      lines.push('');
+      
+      lines.push('# HELP originals_cache_hit_rate Cache hit rate');
+      lines.push('# TYPE originals_cache_hit_rate gauge');
+      lines.push(`originals_cache_hit_rate ${metrics.cacheStats.hitRate}`);
+      lines.push('');
+    }
+    
+    // System metrics
+    lines.push('# HELP originals_uptime_milliseconds SDK uptime in milliseconds');
+    lines.push('# TYPE originals_uptime_milliseconds gauge');
+    lines.push(`originals_uptime_milliseconds ${metrics.uptime}`);
+    lines.push('');
+    
+    return lines.join('\n');
+  }
+}
+