navis.js 2.0.0 → 3.0.1

package/src/messaging/nats-adapter.js

@@ -0,0 +1,141 @@
+/**
+ * NATS Messaging Adapter
+ * v3: NATS integration for async messaging
+ * 
+ * Note: Requires nats to be installed
+ * npm install nats
+ */
+
+const BaseMessaging = require('./base-messaging');
+
+class NATSMessaging extends BaseMessaging {
+  constructor(options = {}) {
+    super(options);
+    this.servers = options.servers || ['nats://localhost:4222'];
+    this.nc = null;
+  }
+
+  /**
+   * Connect to NATS
+   */
+  async connect() {
+    try {
+      const { connect } = require('nats');
+      this.connectNATS = connect;
+    } catch (err) {
+      throw new Error('nats is required. Install it with: npm install nats');
+    }
+
+    this.nc = await this.connectNATS({
+      servers: this.servers,
+      ...this.options.natsConfig,
+    });
+
+    this.isConnected = true;
+    return this;
+  }
+
+  /**
+   * Disconnect from NATS
+   */
+  async disconnect() {
+    this.isConnected = false;
+    if (this.nc) {
+      await this.nc.close();
+      this.nc = null;
+    }
+  }
+
+  /**
+   * Publish message to NATS subject
+   * @param {string} subject - NATS subject
+   * @param {Object} message - Message payload
+   * @param {Object} options - Publishing options
+   */
+  async publish(subject, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const data = Buffer.from(JSON.stringify(message));
+    this.nc.publish(subject, data);
+    
+    return { subject, published: true };
+  }
+
+  /**
+   * Subscribe to NATS subject
+   * @param {string} subject - NATS subject
+   * @param {Function} handler - Message handler function
+   * @param {Object} options - Subscription options
+   */
+  async subscribe(subject, handler, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    this._registerHandler(subject, handler);
+
+    const subscription = this.nc.subscribe(subject, {
+      queue: options.queue || undefined,
+    });
+
+    (async () => {
+      for await (const msg of subscription) {
+        try {
+          const body = JSON.parse(msg.data.toString());
+          const handlers = this._getHandlers(subject);
+
+          for (const h of handlers) {
+            await h(body, {
+              subject: msg.subject,
+              reply: msg.reply,
+              sid: msg.sid,
+            });
+          }
+        } catch (error) {
+          console.error('Error processing NATS message:', error);
+        }
+      }
+    })().catch(console.error);
+
+    return { subject, handler, subscription };
+  }
+
+  /**
+   * Unsubscribe from subject
+   */
+  async unsubscribe(subject, handler = null) {
+    if (handler) {
+      const handlers = this._getHandlers(subject);
+      const index = handlers.indexOf(handler);
+      if (index > -1) {
+        handlers.splice(index, 1);
+      }
+    } else {
+      this.subscribers.delete(subject);
+    }
+  }
+
+  /**
+   * Request-reply pattern
+   * @param {string} subject - NATS subject
+   * @param {Object} message - Request message
+   * @param {Object} options - Request options
+   */
+  async request(subject, message, options = {}) {
+    if (!this.isConnected) {
+      await this.connect();
+    }
+
+    const data = Buffer.from(JSON.stringify(message));
+    const response = await this.nc.request(subject, data, {
+      timeout: options.timeout || 5000,
+    });
+
+    return JSON.parse(response.data.toString());
+  }
+}
+
+module.exports = NATSMessaging;
+

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;
+