nats_wave 1.1.0

data/lib/nats_wave/metrics.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module NatsWave
+    class Metrics
+        @metrics_backend = nil
+        
+        class << self
+            attr_accessor :metrics_backend
+            
+            # Auto-configure Datadog if available
+            def configure_datadog(config = {})
+                return unless defined?(Datadog::Statsd)
+                
+                @metrics_backend = Adapters::DatadogMetrics.new({
+                                                                        service_name: NatsWave.configuration&.service_name || 'nats_wave',
+                                                                        namespace: 'nats_wave',
+                                                                        tags: {
+                                                                                service: NatsWave.configuration&.service_name || 'unknown',
+                                                                                environment: ENV['RAILS_ENV'] || 'unknown'
+                                                                        }
+                                                                }.merge(config))
+                
+                Rails.logger.info "🐕 NatsWave configured with Datadog metrics" if defined?(Rails)
+            end
+            
+            def increment_published_messages(subject, model: nil, action: nil)
+                return unless metrics_backend
+                
+                tags = build_tags(subject: subject, model: model, action: action, direction: 'outbound')
+                metrics_backend.increment('nats_wave.messages.published', tags: tags)
+                
+                # Also track by model and action separately
+                if model && action
+                    metrics_backend.increment('nats_wave.model.published', tags: ["model:#{model}", "action:#{action}"])
+                end
+                
+                log_metric('published', subject, model, action)
+            end
+            
+            def increment_received_messages(subject, model: nil, action: nil, source: nil)
+                return unless metrics_backend
+                
+                tags = build_tags(subject: subject, model: model, action: action, direction: 'inbound', source: source)
+                metrics_backend.increment('nats_wave.messages.received', tags: tags)
+                
+                log_metric('received', subject, model, action)
+            end
+            
+            def track_processing_time(subject, model: nil, action: nil, &block)
+                return yield unless metrics_backend
+                
+                start_time = Time.current
+                result = nil
+                success = false
+                
+                begin
+                    result = yield
+                    success = true
+                    result
+                rescue => e
+                    success = false
+                    increment_errors(e.class.name, subject: subject, model: model)
+                    raise
+                ensure
+                    duration = Time.current - start_time
+                    
+                    tags = build_tags(
+                            subject: subject,
+                            model: model,
+                            action: action,
+                            status: success ? 'success' : 'error'
+                    )
+                    
+                    metrics_backend.histogram('nats_wave.processing_time', duration, tags: tags)
+                    
+                    log_processing_time(subject, duration, success)
+                end
+            end
+            
+            def increment_errors(error_type, subject: nil, model: nil, action: nil)
+                return unless metrics_backend
+                
+                tags = build_tags(
+                        error_type: error_type,
+                        subject: subject,
+                        model: model,
+                        action: action
+                )
+                
+                metrics_backend.increment('nats_wave.errors', tags: tags)
+                
+                # Track specific error types
+                metrics_backend.increment('nats_wave.error_types', tags: ["error_type:#{error_type}"])
+            end
+            
+            def increment_failed_messages(error_type, subject: nil, retry_count: 0)
+                return unless metrics_backend
+                
+                tags = build_tags(error_type: error_type, subject: subject, retry_count: retry_count)
+                metrics_backend.increment('nats_wave.messages.failed', tags: tags)
+            end
+            
+            def increment_retries(subject: nil, retry_count: 0, max_retries: 3)
+                return unless metrics_backend
+                
+                tags = build_tags(
+                        subject: subject,
+                        retry_count: retry_count,
+                        retry_stage: retry_count >= max_retries ? 'final' : 'intermediate'
+                )
+                
+                metrics_backend.increment('nats_wave.retries', tags: tags)
+            end
+            
+            def gauge_connection_status(connected, nats_url: nil)
+                return unless metrics_backend
+                
+                tags = ["status:#{connected ? 'connected' : 'disconnected'}"]
+                tags << "server:#{extract_host(nats_url)}" if nats_url
+                
+                metrics_backend.gauge('nats_wave.connection_status', connected ? 1 : 0, tags: tags)
+            end
+            
+            def gauge_failed_messages_count(count, queue_type: 'default')
+                return unless metrics_backend
+                
+                metrics_backend.gauge('nats_wave.failed_messages_count', count, tags: ["queue:#{queue_type}"])
+            end
+            
+            def gauge_subscriber_count(count)
+                return unless metrics_backend
+                
+                metrics_backend.gauge('nats_wave.subscriber_count', count)
+            end
+            
+            def track_message_size(size_bytes, subject: nil, direction: 'outbound')
+                return unless metrics_backend
+                
+                tags = build_tags(subject: subject, direction: direction)
+                metrics_backend.histogram('nats_wave.message_size', size_bytes, tags: tags)
+            end
+            
+            def track_batch_size(count, operation: 'publish')
+                return unless metrics_backend
+                
+                metrics_backend.histogram('nats_wave.batch_size', count, tags: ["operation:#{operation}"])
+            end
+            
+            # Custom business metrics
+            def track_sync_operation(model, operation, duration, success: true, record_count: 1)
+                return unless metrics_backend
+                
+                status = success ? 'success' : 'error'
+                tags = ["model:#{model}", "operation:#{operation}", "status:#{status}"]
+                
+                metrics_backend.histogram('nats_wave.sync.duration', duration, tags: tags)
+                metrics_backend.histogram('nats_wave.sync.record_count', record_count, tags: tags)
+                metrics_backend.increment('nats_wave.sync.operations', tags: tags)
+            end
+            
+            private
+            
+            def build_tags(**params)
+                tags = []
+                
+                params.each do |key, value|
+                    next if value.nil? || value.to_s.empty?
+                    
+                    # Clean up subject names for better grouping
+                    if key == :subject && value.is_a?(String)
+                        # Convert "app.events.user.create" to "user.create"
+                        cleaned_subject = value.split('.').last(2).join('.')
+                        tags << "subject:#{cleaned_subject}"
+                        
+                        # Also add subject category
+                        category = value.split('.').first
+                        tags << "subject_category:#{category}" if category
+                    else
+                        tags << "#{key}:#{value}"
+                    end
+                end
+                
+                tags
+            end
+            
+            def extract_host(nats_url)
+                return 'unknown' unless nats_url
+                
+                URI.parse(nats_url).host || 'unknown'
+            rescue
+                'unknown'
+            end
+            
+            def log_metric(type, subject, model = nil, action = nil)
+                return unless defined?(Rails)
+                
+                Rails.logger.debug({
+                                           metric: "nats_wave.message.#{type}",
+                                           subject: subject,
+                                           model: model,
+                                           action: action,
+                                           timestamp: Time.current.iso8601
+                                   }.compact.to_json)
+            end
+            
+            def log_processing_time(subject, duration, success)
+                return unless defined?(Rails)
+                
+                level = success ? :debug : :warn
+                Rails.logger.send(level, {
+                        metric: 'nats_wave.processing_time',
+                        subject: subject,
+                        duration_seconds: duration.round(3),
+                        success: success,
+                        timestamp: Time.current.iso8601
+                }.to_json)
+            end
+        end
+    end
+end

data/lib/nats_wave/middleware/authentication.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module NatsWave
+    module Middleware
+        class Authentication < Base
+            def initialize(config)
+                super
+                @secret_key = config.auth_secret_key
+            end
+            
+            def call(message)
+                return message unless @config.middleware_authentication_enabled
+                
+                # For outgoing messages, add authentication token
+                if outgoing_message?(message)
+                    add_auth_token(message)
+                else
+                    # For incoming messages, validate token
+                    validate_auth_token(message)
+                end
+                
+                message
+            end
+            
+            private
+            
+            def outgoing_message?(message)
+                message.key?(:subject) && message.key?(:data)
+            end
+            
+            def add_auth_token(message)
+                return message unless @secret_key
+                
+                payload = {
+                        service: @config.service_name,
+                        instance_id: @config.instance_id,
+                        timestamp: Time.current.to_i,
+                        exp: Time.current.to_i + 3600 # 1 hour expiry
+                }
+                
+                token = JWT.encode(payload, @secret_key, 'HS256')
+                message[:metadata] ||= {}
+                message[:metadata][:auth_token] = token
+                
+                message
+            end
+            
+            def validate_auth_token(message)
+                token = message.dig('metadata', 'auth_token')
+                
+                raise UnauthorizedError, 'Missing authentication token' unless token
+                
+                begin
+                    JWT.decode(token, @secret_key, true, { algorithm: 'HS256' })
+                rescue JWT::DecodeError => e
+                    raise UnauthorizedError, "Invalid authentication token: #{e.message}"
+                end
+                
+                message
+            end
+        end
+    end
+end

data/lib/nats_wave/middleware/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module NatsWave
+    module Middleware
+        class Base
+            def initialize(config)
+                @config = config
+            end
+            
+            def call(message)
+                raise NotImplementedError, 'Subclasses must implement #call'
+            end
+            
+            protected
+            
+            attr_reader :config
+        end
+    end
+end

data/lib/nats_wave/middleware/logging.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module NatsWave
+    module Middleware
+        class Logging < Base
+            def call(message)
+                return message unless logging_enabled?
+                
+                if outgoing_message?(message)
+                    log_outgoing_message(message)
+                else
+                    log_incoming_message(message)
+                end
+                
+                message
+            end
+            
+            private
+            
+            def logging_enabled?
+                @config.middleware_logging_enabled
+            end
+            
+            def outgoing_message?(message)
+                message.key?(:subject) && message.key?(:data)
+            end
+            
+            def log_outgoing_message(message)
+                NatsWave.logger.send(log_level, {
+                        type: 'nats_wave_publish',
+                        event_id: message[:event_id],
+                        subject: message[:subject],
+                        model: message[:model],
+                        action: message[:action],
+                        service: @config.service_name,
+                        timestamp: message[:timestamp]
+                }.to_json)
+            end
+            
+            def log_incoming_message(message)
+                NatsWave.logger.send(log_level, {
+                        type: 'nats_wave_receive',
+                        event_id: message['event_id'],
+                        subject: message['subject'],
+                        model: message['model'],
+                        action: message['action'],
+                        source_service: message.dig('source', 'service'),
+                        timestamp: message['timestamp']
+                }.to_json)
+            end
+            
+            def log_level
+                level = @config.log_level || 'info'
+                level.to_sym
+            end
+        end
+    end
+end

data/lib/nats_wave/middleware/validation.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module NatsWave
+    module Middleware
+        class Validation < Base
+            MESSAGE_SCHEMA = {
+                    type: 'object',
+                    required: %w[event_id timestamp source subject model action data],
+                    properties: {
+                            event_id: {
+                                    type: 'string',
+                                    pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+                            },
+                            timestamp: { type: 'string', format: 'date-time' },
+                            source: {
+                                    type: 'object',
+                                    required: %w[service version instance_id],
+                                    properties: {
+                                            service: { type: 'string' },
+                                            version: { type: 'string' },
+                                            instance_id: { type: 'string' }
+                                    }
+                            },
+                            subject: { type: 'string', minLength: 1 },
+                            model: { type: 'string', minLength: 1 },
+                            action: { type: 'string', enum: %w[create update delete destroy] },
+                            data: { type: 'object' },
+                            metadata: { type: 'object' },
+                            schema_version: { type: 'string' }
+                    }
+            }.freeze
+            
+            def initialize(config)
+                super
+                @schema_registry = SchemaRegistry.new(config.schema_registry_url) if validation_enabled?
+            end
+            
+            def call(message)
+                return message unless validation_enabled?
+                
+                validate_message_structure(message)
+                validate_against_schema(message) if @schema_registry
+                
+                message
+            end
+            
+            private
+            
+            def validation_enabled?
+                @config.middleware_validation_enabled
+            end
+            
+            def validate_message_structure(message)
+                errors = JSON::Validator.fully_validate(MESSAGE_SCHEMA, message)
+                
+                return if errors.empty?
+                
+                error_message = "Message validation failed: #{errors.join(', ')}"
+                NatsWave.logger.error(error_message)
+                raise ValidationError, error_message
+            end
+            
+            def validate_against_schema(message)
+                schema_version = message['schema_version'] || '1.0'
+                
+                return if @schema_registry.validate_message(message, schema_version)
+                
+                raise ValidationError, "Message does not conform to schema version #{schema_version}"
+            end
+        end
+    end
+end

data/lib/nats_wave/model_mapper.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module NatsWave
+    class ModelMapper
+        def initialize(config = nil)
+            @config = config
+        end
+        
+        def map_external_to_local(external_model, external_data)
+            # First check the registry
+            local_model = ModelRegistry.best_local_model_for(external_model, external_data)
+            return nil unless local_model
+            
+            local_mappings = ModelRegistry.local_models_for(external_model)
+            mapping_config = local_mappings[local_model]
+            
+            # Transform the data
+            transformed_data = transform_data(
+                    external_data,
+                    mapping_config[:field_mappings] || {},
+                    mapping_config[:transformations] || {}
+            )
+            
+            {
+                    model: local_model,
+                    data: transformed_data,
+                    config: mapping_config,
+                    unique_fields: mapping_config[:unique_fields] || [:id],
+                    sync_strategy: mapping_config[:sync_strategy] || :upsert
+            }
+        end
+        
+        def map_local_to_external(local_model_instance, target_external_model)
+            return nil unless local_model_instance.class.respond_to?(:nats_wave_can_sync_from?)
+            return nil unless local_model_instance.class.nats_wave_can_sync_from?(target_external_model)
+            
+            local_model_instance.nats_wave_mapped_attributes_for(target_external_model)
+        end
+        
+        def transform_data(data, field_mappings, transformations)
+            result = {}
+            
+            # Apply field mappings
+            data.each do |key, value|
+                mapped_key = field_mappings[key] || field_mappings[key.to_sym] || key
+                result[mapped_key] = value
+            end
+            
+            # Apply transformations
+            transformations.each do |field, transformer|
+                if result.key?(field) && transformer.respond_to?(:call)
+                    begin
+                        result[field] = transformer.call(result[field])
+                    rescue => e
+                        NatsWave.logger.error("Transformation failed for field #{field}: #{e.message}")
+                        raise TransformationError, "Failed to transform field #{field}: #{e.message}"
+                    end
+                end
+            end
+            
+            result
+        end
+        
+        # Legacy compatibility with old configuration-based mappings
+        def map_model(external_model, external_data)
+            # Try registry first
+            registry_mapping = map_external_to_local(external_model, external_data)
+            return registry_mapping if registry_mapping
+            
+            # Fall back to configuration-based mapping
+            return nil unless @config
+            
+            mapping_config = @config.model_mappings[external_model]
+            return nil unless mapping_config
+            
+            local_model = mapping_config[:target_model]
+            field_mappings = mapping_config[:field_mappings] || {}
+            
+            mapped_attributes = map_attributes(external_data, field_mappings)
+            
+            {
+                    model: local_model,
+                    id: extract_id(external_data, field_mappings),
+                    attributes: mapped_attributes
+            }
+        end
+        
+        private
+        
+        def map_attributes(external_data, field_mappings)
+            mapped = {}
+            
+            external_data.each do |external_field, value|
+                local_field = field_mappings[external_field] || external_field
+                
+                # Apply transformations if configured
+                if @config&.transformation_rules && @config.transformation_rules[local_field]
+                    value = apply_transformation(local_field, value)
+                end
+                
+                mapped[local_field] = value
+            end
+            
+            mapped
+        end
+        
+        def extract_id(external_data, field_mappings)
+            id_field = field_mappings['id'] || 'id'
+            external_data[id_field]
+        end
+        
+        def apply_transformation(field, value)
+            transformation = @config.transformation_rules[field]
+            
+            case transformation
+                when Proc
+                    transformation.call(value)
+                when Symbol
+                    send(transformation, value) if respond_to?(transformation, true)
+                else
+                    value
+            end
+        end
+    end
+end