navis.js 1.0.0 → 3.0.0

package/src/messaging/sqs-adapter.js

@@ -0,0 +1,175 @@
+/**
+ * AWS SQS Messaging Adapter
+ * v3: SQS integration for async messaging
+ * 
+ * Note: Requires @aws-sdk/client-sqs to be installed
+ * npm install @aws-sdk/client-sqs
+ */
+
+const BaseMessaging = require('./base-messaging');
+
+class SQSMessaging extends BaseMessaging {
+  constructor(options = {}) {
+    super(options);
+    this.region = options.region || process.env.AWS_REGION || 'us-east-1';
+    this.queueUrl = options.queueUrl;
+    this.sqsClient = null;
+    
+    // Try to load AWS SDK (optional dependency)
+    try {
+      const { SQSClient, SendMessageCommand, ReceiveMessageCommand, DeleteMessageCommand } = require('@aws-sdk/client-sqs');
+      this.SQSClient = SQSClient;
+      this.SendMessageCommand = SendMessageCommand;
+      this.ReceiveMessageCommand = ReceiveMessageCommand;
+      this.DeleteMessageCommand = DeleteMessageCommand;
+    } catch (err) {
+      // AWS SDK not installed - will throw error on connect
+    }
+  }
+
+  /**
+   * Connect to SQS
+   */
+  async connect() {
+    if (!this.SQSClient) {
+      throw new Error('@aws-sdk/client-sqs is required. Install it with: npm install @aws-sdk/client-sqs');
+    }
+
+    this.sqsClient = new this.SQSClient({
+      region: this.region,
+      ...this.options.awsConfig,
+    });
+
+    this.isConnected = true;
+    return this;
+  }
+
+  /**
+   * Disconnect from SQS
+   */
+  async disconnect() {
+    this.isConnected = false;
+    if (this.sqsClient) {
+      // SQS client doesn't need explicit disconnect
+      this.sqsClient = null;
+    }
+  }
+
+  /**
+   * Publish message to SQS queue
+   * @param {string} queueUrl - SQS queue URL
+   * @param {Object} message - Message payload
+   * @param {Object} options - Publishing options
+   */
+  async publish(queueUrl, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const command = new this.SendMessageCommand({
+      QueueUrl: queueUrl || this.queueUrl,
+      MessageBody: JSON.stringify(message),
+      MessageAttributes: options.attributes || {},
+      DelaySeconds: options.delaySeconds || 0,
+    });
+
+    const response = await this.sqsClient.send(command);
+    return {
+      messageId: response.MessageId,
+      md5OfBody: response.MD5OfMessageBody,
+    };
+  }
+
+  /**
+   * Subscribe to SQS queue (long polling)
+   * @param {string} queueUrl - SQS queue URL
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Subscription options
+   */
+  async subscribe(queueUrl, handler, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const targetQueueUrl = queueUrl || this.queueUrl;
+    this._registerHandler(targetQueueUrl, handler);
+
+    // Start polling
+    const poll = async () => {
+      if (!this.isConnected) {
+        return;
+      }
+
+      try {
+        const command = new this.ReceiveMessageCommand({
+          QueueUrl: targetQueueUrl,
+          MaxNumberOfMessages: options.maxMessages || 1,
+          WaitTimeSeconds: options.waitTimeSeconds || 20, // Long polling
+          VisibilityTimeout: options.visibilityTimeout || 30,
+        });
+
+        const response = await this.sqsClient.send(command);
+
+        if (response.Messages && response.Messages.length > 0) {
+          for (const message of response.Messages) {
+            try {
+              const body = JSON.parse(message.Body);
+              const handlers = this._getHandlers(targetQueueUrl);
+
+              for (const h of handlers) {
+                await h(body, {
+                  messageId: message.MessageId,
+                  receiptHandle: message.ReceiptHandle,
+                  attributes: message.Attributes,
+                });
+              }
+
+              // Delete message after successful processing
+              if (options.autoDelete !== false) {
+                await this.sqsClient.send(new this.DeleteMessageCommand({
+                  QueueUrl: targetQueueUrl,
+                  ReceiptHandle: message.ReceiptHandle,
+                }));
+              }
+            } catch (error) {
+              console.error('Error processing SQS message:', error);
+              // Message will become visible again after visibility timeout
+            }
+          }
+        }
+      } catch (error) {
+        console.error('Error receiving SQS messages:', error);
+      }
+
+      // Continue polling
+      if (this.isConnected) {
+        setTimeout(poll, options.pollInterval || 0);
+      }
+    };
+
+    // Start polling
+    poll();
+
+    return { queueUrl: targetQueueUrl, handler };
+  }
+
+  /**
+   * Unsubscribe from queue
+   */
+  async unsubscribe(queueUrl, handler = null) {
+    const targetQueueUrl = queueUrl || this.queueUrl;
+    
+    if (handler) {
+      const handlers = this._getHandlers(targetQueueUrl);
+      const index = handlers.indexOf(handler);
+      if (index > -1) {
+        handlers.splice(index, 1);
+      }
+    } else {
+      this.subscribers.delete(targetQueueUrl);
+    }
+  }
+}
+
+module.exports = SQSMessaging;
+

package/src/observability/logger.js

@@ -0,0 +1,141 @@
+/**
+ * Structured Logger
+ * v3: Logging with levels and structured output
+ */
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  FATAL: 4,
+};
+
+class Logger {
+  constructor(options = {}) {
+    const level = options.level || process.env.LOG_LEVEL || 'INFO';
+    this.level = level;
+    this.levelValue = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
+    this.format = options.format || 'json'; // 'json' or 'text'
+    this.enableColors = options.enableColors !== false;
+    this.context = options.context || {};
+  }
+
+  /**
+   * Log a message
+   * @private
+   */
+  _log(level, message, data = {}) {
+    const levelValue = LOG_LEVELS[level];
+    if (levelValue < this.levelValue) {
+      return;
+    }
+
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...this.context,
+      ...data,
+    };
+
+    if (this.format === 'json') {
+      console.log(JSON.stringify(logEntry));
+    } else {
+      const color = this._getColor(level);
+      const reset = this.enableColors ? '\x1b[0m' : '';
+      const coloredLevel = this.enableColors ? `${color}${level}${reset}` : level;
+      console.log(`[${logEntry.timestamp}] ${coloredLevel}: ${message}`, data);
+    }
+  }
+
+  /**
+   * Get color for log level
+   * @private
+   */
+  _getColor(level) {
+    if (!this.enableColors) return '';
+    
+    const colors = {
+      DEBUG: '\x1b[36m', // Cyan
+      INFO: '\x1b[32m',  // Green
+      WARN: '\x1b[33m',  // Yellow
+      ERROR: '\x1b[31m', // Red
+      FATAL: '\x1b[35m', // Magenta
+    };
+    return colors[level] || '';
+  }
+
+  /**
+   * Debug log
+   */
+  debug(message, data = {}) {
+    this._log('DEBUG', message, data);
+  }
+
+  /**
+   * Info log
+   */
+  info(message, data = {}) {
+    this._log('INFO', message, data);
+  }
+
+  /**
+   * Warning log
+   */
+  warn(message, data = {}) {
+    this._log('WARN', message, data);
+  }
+
+  /**
+   * Error log
+   */
+  error(message, error = null, data = {}) {
+    const errorData = error ? {
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name,
+      },
+    } : {};
+    this._log('ERROR', message, { ...errorData, ...data });
+  }
+
+  /**
+   * Fatal log
+   */
+  fatal(message, error = null, data = {}) {
+    const errorData = error ? {
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name,
+      },
+    } : {};
+    this._log('FATAL', message, { ...errorData, ...data });
+  }
+
+  /**
+   * Create child logger with additional context
+   */
+  child(context) {
+    return new Logger({
+      level: this.level,
+      format: this.format,
+      enableColors: this.enableColors,
+      context: { ...this.context, ...context },
+    });
+  }
+
+  /**
+   * Set log level
+   */
+  setLevel(level) {
+    const upperLevel = level.toUpperCase();
+    this.level = upperLevel;
+    this.levelValue = LOG_LEVELS[upperLevel] !== undefined ? LOG_LEVELS[upperLevel] : LOG_LEVELS.INFO;
+  }
+}
+
+module.exports = Logger;
+

package/src/observability/metrics.js

@@ -0,0 +1,193 @@
+/**
+ * Metrics Collector
+ * v3: Collect and expose application metrics
+ */
+
+class Metrics {
+  constructor(options = {}) {
+    this.metrics = {
+      counters: new Map(),
+      gauges: new Map(),
+      histograms: new Map(),
+    };
+    this.enabled = options.enabled !== false;
+  }
+
+  /**
+   * Increment a counter
+   * @param {string} name - Metric name
+   * @param {number} value - Increment value (default: 1)
+   * @param {Object} labels - Metric labels
+   */
+  increment(name, value = 1, labels = {}) {
+    if (!this.enabled) return;
+
+    const key = this._getKey(name, labels);
+    const current = this.metrics.counters.get(key) || 0;
+    this.metrics.counters.set(key, current + value);
+  }
+
+  /**
+   * Decrement a counter
+   * @param {string} name - Metric name
+   * @param {number} value - Decrement value (default: 1)
+   * @param {Object} labels - Metric labels
+   */
+  decrement(name, value = 1, labels = {}) {
+    this.increment(name, -value, labels);
+  }
+
+  /**
+   * Set a gauge value
+   * @param {string} name - Metric name
+   * @param {number} value - Gauge value
+   * @param {Object} labels - Metric labels
+   */
+  gauge(name, value, labels = {}) {
+    if (!this.enabled) return;
+
+    const key = this._getKey(name, labels);
+    this.metrics.gauges.set(key, value);
+  }
+
+  /**
+   * Record a histogram value
+   * @param {string} name - Metric name
+   * @param {number} value - Value to record
+   * @param {Object} labels - Metric labels
+   */
+  histogram(name, value, labels = {}) {
+    if (!this.enabled) return;
+
+    const key = this._getKey(name, labels);
+    if (!this.metrics.histograms.has(key)) {
+      this.metrics.histograms.set(key, []);
+    }
+    this.metrics.histograms.get(key).push({
+      value,
+      timestamp: Date.now(),
+    });
+
+    // Keep only last 1000 values per histogram
+    const values = this.metrics.histograms.get(key);
+    if (values.length > 1000) {
+      values.shift();
+    }
+  }
+
+  /**
+   * Record request duration
+   * @param {string} method - HTTP method
+   * @param {string} path - Request path
+   * @param {number} duration - Duration in milliseconds
+   * @param {number} statusCode - HTTP status code
+   */
+  recordRequest(method, path, duration, statusCode) {
+    this.histogram('http_request_duration_ms', duration, {
+      method,
+      path,
+      status: statusCode,
+    });
+    this.increment('http_requests_total', 1, {
+      method,
+      path,
+      status: statusCode,
+    });
+  }
+
+  /**
+   * Get all metrics
+   * @returns {Object} - All collected metrics
+   */
+  getAll() {
+    return {
+      counters: Object.fromEntries(this.metrics.counters),
+      gauges: Object.fromEntries(this.metrics.gauges),
+      histograms: Object.fromEntries(
+        Array.from(this.metrics.histograms.entries()).map(([key, values]) => [
+          key,
+          {
+            count: values.length,
+            sum: values.reduce((sum, v) => sum + v.value, 0),
+            avg: values.length > 0 ? values.reduce((sum, v) => sum + v.value, 0) / values.length : 0,
+            min: values.length > 0 ? Math.min(...values.map(v => v.value)) : 0,
+            max: values.length > 0 ? Math.max(...values.map(v => v.value)) : 0,
+            values: values.slice(-100), // Last 100 values
+          },
+        ])
+      ),
+    };
+  }
+
+  /**
+   * Get metrics in Prometheus format
+   * @returns {string} - Prometheus metrics format
+   */
+  toPrometheus() {
+    const lines = [];
+
+    // Counters
+    for (const [key, value] of this.metrics.counters.entries()) {
+      const { name, labels } = this._parseKey(key);
+      const labelStr = Object.entries(labels)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+      lines.push(`${name}{${labelStr}} ${value}`);
+    }
+
+    // Gauges
+    for (const [key, value] of this.metrics.gauges.entries()) {
+      const { name, labels } = this._parseKey(key);
+      const labelStr = Object.entries(labels)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+      lines.push(`${name}{${labelStr}} ${value}`);
+    }
+
+    // Histograms
+    for (const [key, histogram] of this.metrics.histograms.entries()) {
+      const { name, labels } = this._parseKey(key);
+      const labelStr = Object.entries(labels)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(',');
+      lines.push(`${name}_count{${labelStr}} ${histogram.length}`);
+      lines.push(`${name}_sum{${labelStr}} ${histogram.reduce((sum, v) => sum + v.value, 0)}`);
+      lines.push(`${name}_avg{${labelStr}} ${histogram.length > 0 ? histogram.reduce((sum, v) => sum + v.value, 0) / histogram.length : 0}`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    this.metrics.counters.clear();
+    this.metrics.gauges.clear();
+    this.metrics.histograms.clear();
+  }
+
+  /**
+   * Get key for metric storage
+   * @private
+   */
+  _getKey(name, labels) {
+    const labelStr = JSON.stringify(labels);
+    return `${name}::${labelStr}`;
+  }
+
+  /**
+   * Parse key back to name and labels
+   * @private
+   */
+  _parseKey(key) {
+    const [name, labelStr] = key.split('::');
+    return {
+      name,
+      labels: JSON.parse(labelStr || '{}'),
+    };
+  }
+}
+
+module.exports = Metrics;
+

package/src/observability/tracer.js

@@ -0,0 +1,205 @@
+/**
+ * Distributed Tracer
+ * v3: Basic distributed tracing support
+ */
+
+class Tracer {
+  constructor(options = {}) {
+    this.serviceName = options.serviceName || 'navis-service';
+    this.enabled = options.enabled !== false;
+    this.spans = new Map();
+    this.traceId = null;
+  }
+
+  /**
+   * Start a new trace
+   * @param {string} operationName - Operation name
+   * @param {Object} context - Trace context
+   * @returns {string} - Trace ID
+   */
+  startTrace(operationName, context = {}) {
+    if (!this.enabled) return null;
+
+    const traceId = this._generateId();
+    const spanId = this._generateId();
+    
+    this.traceId = traceId;
+    
+    const span = {
+      traceId,
+      spanId,
+      operationName,
+      startTime: Date.now(),
+      tags: context.tags || {},
+      logs: [],
+      childSpans: [],
+    };
+
+    this.spans.set(spanId, span);
+    return traceId;
+  }
+
+  /**
+   * Start a new span
+   * @param {string} operationName - Operation name
+   * @param {Object} options - Span options
+   * @returns {string} - Span ID
+   */
+  startSpan(operationName, options = {}) {
+    if (!this.enabled) return null;
+
+    const spanId = this._generateId();
+    const parentSpanId = options.parentSpanId || this._getCurrentSpanId();
+    const traceId = options.traceId || this.traceId || this.startTrace(operationName);
+
+    const span = {
+      traceId,
+      spanId,
+      parentSpanId,
+      operationName,
+      startTime: Date.now(),
+      tags: options.tags || {},
+      logs: [],
+      childSpans: [],
+    };
+
+    this.spans.set(spanId, span);
+
+    // Add as child span if parent exists
+    if (parentSpanId) {
+      const parentSpan = this.spans.get(parentSpanId);
+      if (parentSpan) {
+        parentSpan.childSpans.push(spanId);
+      }
+    }
+
+    return spanId;
+  }
+
+  /**
+   * Finish a span
+   * @param {string} spanId - Span ID
+   * @param {Object} options - Finish options
+   */
+  finishSpan(spanId, options = {}) {
+    if (!this.enabled || !spanId) return;
+
+    const span = this.spans.get(spanId);
+    if (!span) return;
+
+    span.endTime = Date.now();
+    span.duration = span.endTime - span.startTime;
+    span.status = options.status || 'ok';
+    span.error = options.error || null;
+
+    if (options.tags) {
+      span.tags = { ...span.tags, ...options.tags };
+    }
+  }
+
+  /**
+   * Add tag to span
+   * @param {string} spanId - Span ID
+   * @param {string} key - Tag key
+   * @param {*} value - Tag value
+   */
+  addTag(spanId, key, value) {
+    if (!this.enabled || !spanId) return;
+
+    const span = this.spans.get(spanId);
+    if (span) {
+      span.tags[key] = value;
+    }
+  }
+
+  /**
+   * Add log to span
+   * @param {string} spanId - Span ID
+   * @param {string} message - Log message
+   * @param {Object} fields - Log fields
+   */
+  addLog(spanId, message, fields = {}) {
+    if (!this.enabled || !spanId) return;
+
+    const span = this.spans.get(spanId);
+    if (span) {
+      span.logs.push({
+        timestamp: Date.now(),
+        message,
+        fields,
+      });
+    }
+  }
+
+  /**
+   * Get trace data
+   * @param {string} traceId - Trace ID
+   * @returns {Object} - Trace data
+   */
+  getTrace(traceId) {
+    const traceSpans = Array.from(this.spans.values()).filter(
+      span => span.traceId === traceId
+    );
+    
+    return {
+      traceId,
+      spans: traceSpans,
+      duration: traceSpans.length > 0
+        ? Math.max(...traceSpans.map(s => s.endTime || Date.now())) -
+          Math.min(...traceSpans.map(s => s.startTime))
+        : 0,
+    };
+  }
+
+  /**
+   * Get all traces
+   * @returns {Array} - All traces
+   */
+  getAllTraces() {
+    const traceIds = new Set();
+    for (const span of this.spans.values()) {
+      traceIds.add(span.traceId);
+    }
+
+    return Array.from(traceIds).map(traceId => this.getTrace(traceId));
+  }
+
+  /**
+   * Clear old spans (keep last N)
+   * @param {number} keepCount - Number of spans to keep
+   */
+  clearOldSpans(keepCount = 1000) {
+    const spans = Array.from(this.spans.entries());
+    if (spans.length > keepCount) {
+      // Sort by start time and keep most recent
+      spans.sort((a, b) => b[1].startTime - a[1].startTime);
+      const toKeep = spans.slice(0, keepCount);
+      this.spans.clear();
+      for (const [id, span] of toKeep) {
+        this.spans.set(id, span);
+      }
+    }
+  }
+
+  /**
+   * Get current span ID
+   * @private
+   */
+  _getCurrentSpanId() {
+    // Return the most recently created span
+    const spans = Array.from(this.spans.values());
+    if (spans.length === 0) return null;
+    return spans[spans.length - 1].spanId;
+  }
+
+  /**
+   * Generate unique ID
+   * @private
+   */
+  _generateId() {
+    return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+
+module.exports = Tracer;
+