nats_wave 1.1.0

data/lib/nats_wave/concerns/publishable.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module NatsWave
+    module ActiveRecordExtension
+        extend ActiveSupport::Concern
+        
+        module ClassMethods
+            def nats_publishable(options = {})
+                include NatsWave::NatsPublishable
+                class_attribute :nats_publishing_options
+                self.nats_publishing_options = {
+                        enabled: true,
+                        actions: %i[create update
+    			                           destroy],
+                        skip_attributes: [],
+                        include_associations: [],
+                        async: true
+                }.merge(options)
+                
+                # Register this model for publishing
+                NatsWave.configuration&.add_publication(name,
+                                                        nats_publishing_options[:actions])
+            end
+        end
+    end
+    
+    module NatsPublishable
+        extend ActiveSupport::Concern
+        
+        included do
+            after_commit :publish_to_nats_on_create, on: :create, if: :should_publish_create?
+            after_commit :publish_to_nats_on_update, on: :update,
+                         if: :should_publish_update?
+            after_commit :publish_to_nats_on_destroy, on: :destroy,
+                         if: :should_publish_destroy?
+        end
+        
+        class_methods do
+            def nats_wave_enabled?
+                nats_publishing_options[:enabled]
+            end
+            
+            def nats_wave_actions
+                nats_publishing_options[:actions]
+            end
+            
+            def nats_wave_skip_attributes
+                nats_publishing_options[:skip_attributes]
+            end
+            
+            def nats_wave_unique_attributes
+                # Override this method in your models to define unique attributes for syncing
+                %i[email slug code external_icn].select do |attr|
+                    column_names.include?(attr.to_s)
+                end
+            end
+            
+            def nats_wave_skip_sync_attributes
+                # Override this method to define attributes that shouldn't be synced from other instances
+                %w[created_at updated_at]
+            end
+            
+            def nats_wave_attribute_transformations
+                # Override this method to define custom transformations
+                {}
+            end
+        end
+        
+        private
+        
+        def should_publish_create?
+            should_publish_action?(:create)
+        end
+        
+        def should_publish_update?
+            should_publish_action?(:update) && has_significant_changes?
+        end
+        
+        def should_publish_destroy?
+            should_publish_action?(:destroy)
+        end
+        
+        def should_publish_action?(action)
+            return false unless self.class.nats_wave_enabled?
+            return false unless self.class.nats_wave_actions.include?(action)
+            return false if Thread.current[:skip_nats_wave_publishing]
+            return false if @skip_nats_wave_publishing
+            
+            # Check conditional options
+            return false if nats_publishing_options[:if] && !instance_eval(&nats_publishing_options[:if])
+            
+            return false if nats_publishing_options[:unless] && instance_eval(&nats_publishing_options[:unless])
+            
+            true
+        end
+        
+        def has_significant_changes?
+            skip_attrs = self.class.nats_wave_skip_attributes.map(&:to_s)
+            significant_changes = previous_changes.except(*skip_attrs, 'updated_at')
+            significant_changes.any?
+        end
+        
+        def publish_to_nats_on_create
+            publish_to_nats('create', attributes, build_metadata)
+        end
+        
+        def publish_to_nats_on_update
+            publish_to_nats('update', previous_changes, build_metadata)
+        end
+        
+        def publish_to_nats_on_destroy
+            publish_to_nats('destroy', attributes, build_metadata)
+        end
+        
+        def publish_to_nats(action, _data, metadata)
+            subject = build_nats_subject(action)
+            
+            NatsWave.client.publish(
+                    subject: subject,
+                    model: self.class.name,
+                    action: action,
+                    data: publishable_attributes,
+                    metadata: metadata
+            )
+        rescue StandardError => e
+            NatsWave.logger.error("Failed to publish NATS event: #{e.message}")
+            # Don't raise to avoid breaking the main transaction
+        end
+        
+        def build_nats_subject(action)
+            prefix = nats_publishing_options&.dig(:subject_prefix)
+            model_name = self.class.name.underscore
+            
+            if prefix
+                "#{prefix}.#{model_name}.#{action}"
+            else
+                "#{model_name}.#{action}"
+            end
+        end
+        
+        def publishable_attributes
+            attrs = if nats_publishing_options&.dig(:only)
+                        attributes.slice(*nats_publishing_options[:only].map(&:to_s))
+                    elsif nats_publishing_options&.dig(:except)
+                        attributes.except(*nats_publishing_options[:except].map(&:to_s))
+                    else
+                        attributes
+                    end
+            
+            # Add associations if configured
+            attrs.merge!(serialize_associations) if nats_publishing_options[:include_associations].present?
+            
+            attrs
+        end
+        
+        def serialize_associations
+            associations = {}
+            
+            self.class.reflect_on_all_associations.each do |association|
+                unless nats_publishing_options[:include_associations].include?(association.name)
+                    next
+                end
+                
+                case association.macro
+                    when :belongs_to
+                        if (related = send(association.name))
+                            associations["#{association.name}_id"] =
+                                    related.id
+                            if association.polymorphic?
+                                associations["#{association.name}_type"] =
+                                        related.class.name
+                            end
+                        end
+                    when :has_many, :has_and_belongs_to_many
+                        if respond_to?("#{association.name}_ids")
+                            associations["#{association.name.to_s.singularize}_ids"] =
+                                    send("#{association.name}_ids")
+                        end
+                    when :has_one
+                        if (related = send(association.name))
+                            associations["#{association.name}_id"] =
+                                    related.id
+                        end
+                end
+            end
+            
+            associations
+        end
+        
+        def build_metadata
+            metadata = {
+                    model_id: id,
+                    model_type: self.class.name,
+                    table_name: self.class.table_name,
+                    primary_key: self.class.primary_key
+            }
+            
+            # Add custom metadata if method exists
+            metadata.merge!(nats_wave_metadata) if respond_to?(:nats_wave_metadata,
+                                                               true)
+            
+            # Add configured metadata
+            metadata.merge!(nats_publishing_options[:metadata]) if nats_publishing_options[:metadata]
+            
+            metadata
+        end
+        
+        def skip_nats_wave_publishing!
+            @skip_nats_wave_publishing = true
+        end
+        
+        def enable_nats_wave_publishing!
+            @skip_nats_wave_publishing = false
+        end
+    end
+end

data/lib/nats_wave/configuration.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module NatsWave
+    class Configuration
+        # Core settings
+        attr_accessor :nats_url, :service_name, :version, :instance_id,
+                      :database_url, :connection_pool_size, :timeout, :reconnect_attempts,
+                      :publishing_enabled, :subscription_enabled, :default_subject_prefix,
+                      :batch_size, :async_publishing, :queue_group,
+                      :middleware_authentication_enabled, :middleware_validation_enabled,
+                      :middleware_logging_enabled, :auth_secret_key, :schema_registry_url,
+                      :max_retries, :retry_delay, :dead_letter_queue, :log_level,
+                      :model_mappings, :field_mappings, :transformation_rules,
+                      :subscriptions, :publications
+        
+        def initialize(options = {})
+            @nats_url = ENV['NATS_URL']
+            @service_name = ENV['NATS_SERVICE_NAME']
+            @version = ENV['NATS_SERVICE_VERSION'] || "1.1.0"
+            @instance_id = ENV['NATS_INSTANCE_ID'] || Socket.gethostname
+            @database_url = ENV['NATS_DATABASE_URL'] || nil
+            @connection_pool_size = (ENV['NATS_CONNECTION_POOL_SIZE'] || 10).to_i
+            @timeout = (ENV['NATS_TIMEOUT'] || 5).to_i
+            @reconnect_attempts = (ENV['NATS_RECONNECT_ATTEMPTS'] || 3).to_i
+            @publishing_enabled = ENV['NATS_PUBLISHING_ENABLED'] != 'false'
+            @subscription_enabled = ENV['NATS_SUBSCRIPTION_ENABLED'] != 'false'
+            @default_subject_prefix = ENV['NATS_SUBJECT_PREFIX'] || nil
+            @batch_size = (ENV['NATS_BATCH_SIZE'] || 100).to_i
+            @async_publishing = ENV['NATS_ASYNC_PUBLISHING'] != 'false'
+            @queue_group = ENV['NATS_QUEUE_GROUP'] || nil
+            @middleware_authentication_enabled = ENV['NATS_AUTH_ENABLED'] == 'true'
+            @middleware_validation_enabled = ENV['NATS_VALIDATION_ENABLED'] != 'false'
+            @middleware_logging_enabled = ENV['NATS_LOGGING_ENABLED'] != 'false'
+            @auth_secret_key = ENV['NATS_AUTH_SECRET_KEY'] || nil
+            @schema_registry_url = ENV['NATS_SCHEMA_REGISTRY_URL'] || nil
+            @max_retries = (ENV['NATS_MAX_RETRIES'] || 3).to_i
+            @retry_delay = (ENV['NATS_RETRY_DELAY'] || 5).to_i
+            @dead_letter_queue = ENV['NATS_DEAD_LETTER_QUEUE'] || "failed_messages"
+            @log_level = ENV['NATS_LOG_LEVEL'] || "info"
+            
+            # Initialize collections
+            @model_mappings = {}
+            @field_mappings = {}
+            @transformation_rules = {}
+            @subscriptions = []
+            @publications = []
+            
+            # Override with provided options (highest priority)
+            options.each do |key, value|
+                send("#{key}=", value) if respond_to?("#{key}=")
+            end
+            
+            # Set computed defaults
+            @default_subject_prefix ||= service_name
+            @queue_group ||= "#{service_name}_consumers"
+        end
+        
+        def add_model_mapping(external_model, local_model, field_mappings = {})
+            @model_mappings[external_model] = {
+                    target_model: local_model,
+                    field_mappings: field_mappings
+            }
+        end
+        
+        def add_subscription(subject_pattern, handler = nil, &block)
+            @subscriptions << {
+                    subject: subject_pattern,
+                    handler: handler || block
+            }
+        end
+        
+        def add_publication(model_class, actions = [:create, :update, :destroy])
+            @publications << {
+                    model: model_class,
+                    actions: Array(actions)
+            }
+        end
+        
+        def nats_server_url
+            # This is the URL other teams can use to subscribe to your events
+            uri = URI.parse(@nats_url)
+            "#{uri.scheme}://#{uri.host}:#{uri.port}"
+        end
+        
+        def subject_patterns
+            # Returns all subject patterns this service publishes
+            patterns = []
+            @publications.each do |pub|
+                model_name = pub[:model].to_s.underscore
+                pub[:actions].each do |action|
+                    patterns << "#{@default_subject_prefix}.#{model_name}.#{action}"
+                end
+            end
+            patterns
+        end
+        
+        def to_h
+            instance_variables.each_with_object({}) do |var, hash|
+                hash[var.to_s.delete('@').to_sym] = instance_variable_get(var)
+            end
+        end
+    end
+end

data/lib/nats_wave/database_connector.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module NatsWave
+    class DatabaseConnector
+        def initialize(config)
+            @config = config
+            @adapter = determine_adapter
+        end
+        
+        def apply_change(model:, action:, data:, metadata:)
+            case action.to_s.downcase
+                when 'create'
+                    create_record(model, data, metadata)
+                when 'update'
+                    update_record(model, data, metadata)
+                when 'delete', 'destroy'
+                    delete_record(model, data, metadata)
+                else
+                    NatsWave.logger.warn("Unknown action: #{action}")
+            end
+        rescue StandardError => e
+            NatsWave.logger.error("Database operation failed: #{e.message}")
+            raise DatabaseError, "Database operation failed: #{e.message}"
+        end
+        
+        def connected?
+            @adapter.connected?
+        end
+        
+        private
+        
+        def determine_adapter
+            raise ConfigurationError, 'No supported database adapter found' unless defined?(ActiveRecord)
+            
+            Adapters::ActiveRecord.new(@config)
+        end
+        
+        def create_record(model, data, metadata)
+            @adapter.create(model, data, metadata)
+        end
+        
+        def update_record(model, data, metadata)
+            @adapter.update(model, data, metadata)
+        end
+        
+        def delete_record(model, data, metadata)
+            @adapter.delete(model, data, metadata)
+        end
+    end
+end

data/lib/nats_wave/dead_letter_queue.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module NatsWave
+    class DeadLetterQueue
+        def initialize(config)
+            @config = config
+            @storage = setup_storage
+            @max_retries = config.max_retries
+            @retry_delay = config.retry_delay
+        end
+        
+        def store_failed_message(message, error, retry_count)
+            failed_message = {
+                    id: SecureRandom.uuid,
+                    message: message.to_json,
+                    error: error.message,
+                    error_class: error.class.name,
+                    error_backtrace: error.backtrace&.join("\n"),
+                    retry_count: retry_count,
+                    timestamp: Time.current.iso8601,
+                    next_retry: calculate_next_retry(retry_count)
+            }
+            
+            @storage.store(failed_message)
+            NatsWave.logger.error("Stored failed message in DLQ: #{failed_message[:id]}")
+        end
+        
+        def retry_failed_messages
+            @storage.pending_retries.each do |failed_message|
+                next if failed_message[:next_retry] > Time.current
+                
+                begin
+                    retry_message(failed_message)
+                    @storage.remove(failed_message[:id])
+                    NatsWave.logger.info("Successfully retried message: #{failed_message[:id]}")
+                rescue StandardError => e
+                    increment_retry_count(failed_message, e)
+                end
+            end
+        end
+        
+        def pending_retries_count
+            @storage.pending_retries.count
+        end
+        
+        def permanent_failures_count
+            @storage.permanent_failures.count
+        end
+        
+        def get_failed_messages(limit = 100)
+            @storage.all.first(limit)
+        end
+        
+        def remove_failed_message(id)
+            @storage.remove(id)
+        end
+        
+        private
+        
+        def setup_storage
+            # For production, you'd want to use Redis, database, or file storage
+            # For now, use in-memory storage
+            InMemoryStorage.new
+        end
+        
+        def calculate_next_retry(retry_count)
+            # Exponential backoff: 1min, 5min, 25min
+            delay = @retry_delay * (5 ** retry_count)
+            Time.current + delay
+        end
+        
+        def retry_message(failed_message)
+            # This would need to be implemented based on your retry strategy
+            # For now, just log that we would retry
+            NatsWave.logger.info("Retrying message: #{failed_message[:id]}")
+            
+            # In a real implementation, you would:
+            # 1. Re-parse the message
+            # 2. Re-apply middleware
+            # 3. Re-process the message
+            # 4. Handle the result
+        end
+        
+        def increment_retry_count(failed_message, error)
+            failed_message[:retry_count] += 1
+            failed_message[:error] = error.message
+            failed_message[:error_class] = error.class.name
+            failed_message[:next_retry] = calculate_next_retry(failed_message[:retry_count])
+            
+            if failed_message[:retry_count] >= @max_retries
+                NatsWave.logger.error("Message exceeded max retries: #{failed_message[:id]}")
+                @storage.mark_permanent_failure(failed_message)
+            else
+                @storage.update(failed_message)
+            end
+        end
+        
+        class InMemoryStorage
+            def initialize
+                @messages = {}
+                @mutex = Mutex.new
+            end
+            
+            def store(message)
+                @mutex.synchronize do
+                    @messages[message[:id]] = message
+                end
+            end
+            
+            def remove(id)
+                @mutex.synchronize do
+                    @messages.delete(id)
+                end
+            end
+            
+            def update(message)
+                @mutex.synchronize do
+                    @messages[message[:id]] = message
+                end
+            end
+            
+            def pending_retries
+                @mutex.synchronize do
+                    @messages.values.select { |msg| msg[:retry_count] < 3 }
+                end
+            end
+            
+            def permanent_failures
+                @mutex.synchronize do
+                    @messages.values.select { |msg| msg[:retry_count] >= 3 }
+                end
+            end
+            
+            def all
+                @mutex.synchronize do
+                    @messages.values
+                end
+            end
+            
+            def mark_permanent_failure(message)
+                # In a real implementation, you might move this to a different storage
+                update(message)
+            end
+        end
+    end
+end

data/lib/nats_wave/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NatsWave
+    class Error < StandardError; end
+    
+    class ConnectionError < Error; end
+    
+    class PublishError < Error; end
+    
+    class SubscriptionError < Error; end
+    
+    class ValidationError < Error; end
+    
+    class UnauthorizedError < Error; end
+    
+    class ConfigurationError < Error; end
+    
+    class TransformationError < Error; end
+    
+    class DatabaseError < Error; end
+    
+    class TimeoutError < Error; end
+    
+    class MappingError < Error; end
+    
+    class AuthenticationError < Error; end
+end

data/lib/nats_wave/message_transformer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'json'
+
+module NatsWave
+    class MessageTransformer
+        SCHEMA_VERSION = '1.0'
+        
+        def initialize(config)
+            @config = config
+        end
+        
+        def build_standard_message(subject:, model:, action:, data:, metadata:, source:)
+            {
+                    event_id: SecureRandom.uuid,
+                    timestamp: Time.current.iso8601,
+                    source: source,
+                    subject: subject,
+                    model: model,
+                    action: action,
+                    data: sanitize_data(data),
+                    metadata: sanitize_metadata(metadata),
+                    schema_version: SCHEMA_VERSION
+            }
+        end
+        
+        def parse_message(raw_message)
+            case raw_message
+                when String
+                    JSON.parse(raw_message)
+                when Hash
+                    raw_message
+                else
+                    raise TransformationError, 'Invalid message format'
+            end
+        rescue JSON::ParserError => e
+            raise TransformationError, "Failed to parse message: #{e.message}"
+        end
+        
+        private
+        
+        def sanitize_data(data)
+            case data
+                when Hash
+                    data.transform_values { |v| sanitize_value(v) }
+                when Array
+                    data.map { |v| sanitize_value(v) }
+                else
+                    sanitize_value(data)
+            end
+        end
+        
+        def sanitize_metadata(metadata)
+            default_metadata = {
+                    correlation_id: SecureRandom.uuid,
+                    timestamp: Time.current.iso8601
+            }
+            
+            # Add Rails-specific context if available
+            if defined?(Rails)
+                default_metadata[:rails_env] = Rails.env
+                default_metadata[:rails_version] = Rails.version
+            end
+            
+            # Add current user context if available (Current is a Rails 5.2+ feature)
+            if defined?(Current)
+                default_metadata[:user_id] = Current.user&.id if Current.respond_to?(:user)
+                default_metadata[:request_id] = Current.request_id if Current.respond_to?(:request_id)
+            end
+            
+            default_metadata[:hostname] = Socket.gethostname
+            default_metadata[:process_id] = Process.pid
+            
+            default_metadata.merge(sanitize_data(metadata))
+        end
+        
+        def sanitize_value(value)
+            case value
+                when String, Integer, Float, TrueClass, FalseClass, NilClass
+                    value
+                when Time, DateTime
+                    value.iso8601
+                when Date
+                    value.to_s
+                when Hash
+                    value.transform_values { |v| sanitize_value(v) }
+                when Array
+                    value.map { |v| sanitize_value(v) }
+                else
+                    value.to_s
+            end
+        end
+    end
+end