nats_wave 1.1.0

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/nats_wave.yml

@@ -0,0 +1,65 @@
+default: &default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+    connection_pool_size: 10
+    timeout: 5
+    reconnect_attempts: 3
+
+  publishing:
+    enabled: true
+    default_subject_prefix: <%= ENV['SERVICE_NAME'] %>
+    batch_size: 100
+    async: true
+
+  subscription:
+    enabled: true
+    subjects: [ ]
+    queue_group: <%= ENV['SERVICE_NAME'] %>_consumers
+
+  database:
+    adapter: "active_record"
+    connection_pool_size: 5
+
+  #  middleware:
+  #    authentication:
+  #      enabled: false
+  #      secret_key: <%= ENV['NATS_AUTH_SECRET'] %>
+  #    validation:
+  #      enabled: true
+  #      schema_registry: <%= ENV['SCHEMA_REGISTRY_URL'] %>
+  #    logging:
+  #      enabled: true
+  #      level: "info"
+
+  error_handling:
+    max_retries: 3
+    retry_delay: 5
+    dead_letter_queue: "failed_messages"
+
+development:
+  <<: *default
+  middleware:
+    authentication:
+      enabled: false
+    logging:
+      level: "debug"
+
+test:
+  <<: *default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+  publishing:
+    enabled: false
+  subscription:
+    enabled: false
+
+production:
+  <<: *default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+  middleware:
+    authentication:
+      enabled: true
+      secret_key: <%= ENV['NATS_AUTH_SECRET'] %>
+    logging:
+      level: "info"

data/examples/catalog_model.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Catalog < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    nats_publishable(
+            actions: %i[create update], # Don't publish deletes
+            skip_attributes: %i[view_count search_vector internal_notes],
+            include_associations: %i[category variants]
+    )
+    
+    # Custom serializer support
+    def self.nats_wave_attribute_transformations
+        {
+                hammer_estimate: ->(value, _action) { value.to_f.round(2) },
+                name: :sanitize_name,
+                description: lambda { |value, _action|
+                    ActionView::Base.full_sanitizer.sanitize(value)
+                }
+        }
+    end
+    
+    private
+    
+    def sanitize_name(name, _action)
+        name&.strip&.titleize
+    end
+    
+    def nats_wave_metadata
+        {
+                organization: organization&.name,
+                make:,
+                catalog_tracked: track_catalog?
+        }
+    end
+end

data/examples/configuration_examples.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Basic configuration
+NatsWave.configure do |config|
+    config.nats_url = 'nats://localhost:4222'
+    config.service_name = 'ecommerce_api'
+    config.default_subject_prefix = 'ecommerce.events'
+end
+
+# Advanced configuration with model mappings
+NatsWave.configure do |config|
+    config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
+    config.service_name = 'catalog_service'
+    config.environment = Rails.env
+    
+    # Subscribe to other team's events
+    config.add_subscription('warehouse.assets.*')
+    config.add_subscription('external.catalogs.*')
+    config.add_subscription('payments.transactions.*')
+    
+    # Map external models to local models
+    config.add_model_mapping('WarehouseAsset', 'Catalog', {
+            'asset_name' => 'name',
+            'asset_description' => 'description',
+            'asset_value' => 'hammer_estimate',
+            'asset_id' => 'external_icn',
+            'model' => 'category'
+    })
+    
+    config.add_model_mapping('ExternalCatalog', 'Catalog', {
+            'package_name' => 'name',
+            'package_cost' => 'hammer_estimate',
+            'external_vin' => 'vin'
+    })
+    
+    # Custom transformation rules
+    config.transformation_rules = {
+            'hammer_estimate' => ->(value) { value.to_f.round(2) },
+            'name' => ->(value) { value&.titleize },
+            'email' => ->(value) { value&.downcase }
+    }
+    
+    # Custom subscription with handler
+    config.add_subscription('payments.failed.*') do |message|
+        PaymentFailureHandler.process(message)
+    end
+    
+    # Middleware configuration
+    config.middleware_authentication_enabled = Rails.env.production?
+    config.auth_secret_key = ENV['NATS_AUTH_SECRET']
+    config.middleware_validation_enabled = true
+    config.middleware_logging_enabled = true
+    config.log_level = Rails.env.production? ? 'info' : 'debug'
+end
+
+# Catalogion configuration
+if Rails.env.production?
+    NatsWave.configure do |config|
+        config.nats_url = ENV.fetch('NATS_CLUSTER_URL')
+        config.connection_pool_size = 20
+        config.async_publishing = true
+        config.middleware_authentication_enabled = true
+        config.auth_secret_key = ENV.fetch('NATS_AUTH_SECRET')
+        config.schema_registry_url = ENV['SCHEMA_REGISTRY_URL']
+        config.max_retries = 5
+        config.retry_delay = 10
+    end
+end

data/examples/user_model.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class User < ApplicationRecord
+    include NatsWave::NatsPublishable
+    
+    # Configure NATS publishing
+    nats_publishable(
+            actions: %i[create update destroy],
+            skip_attributes: %i[password_digest remember_token password_reset_token],
+            include_associations: %i[profile organization],
+            subject_prefix: 'users',
+            metadata: { tenant_id: 'main' },
+            if: -> { active? },
+            unless: -> { system_user? }
+    )
+    
+    # Define unique attributes for syncing
+    def self.nats_wave_unique_attributes
+        %i[email external_icn username]
+    end
+    
+    # Define attributes that shouldn't be synced from other instances
+    def self.nats_wave_skip_sync_attributes
+        %i[last_login_at login_count password_digest]
+    end
+    
+    # Custom attribute transformations
+    def self.nats_wave_attribute_transformations
+        {
+                email: ->(value, _action) { value&.downcase&.strip },
+                phone: :format_phone_number
+        }
+    end
+    
+    private
+    
+    # Custom metadata for NATS messages
+    def nats_wave_metadata
+        {
+                tenant_id: organization&.tenant_id,
+                user_type: account_type,
+                subscription_level: subscription&.level
+        }
+    end
+    
+    def format_phone_number(phone, _action)
+        # Custom transformation logic
+        phone&.gsub(/\D/, '')
+    end
+    
+    def active?
+        status == 'active'
+    end
+    
+    def system_user?
+        email&.ends_with?('@system.internal')
+    end
+end

data/lib/generators/nats_wave/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module NatsWave
+    module Generators
+        class InstallGenerator < Rails::Generators::Base
+            include Rails::Generators::Migration
+            
+            source_root File.expand_path('templates', __dir__)
+            
+            def self.next_migration_number(path)
+                next_migration_number = current_migration_number(path) + 1
+                ActiveRecord::Migration.next_migration_number(next_migration_number)
+            end
+            
+            desc 'Creates a NatsWave initializer and configuration file'
+            
+            def copy_initializer
+                template 'initializer.rb', 'config/initializers/nats_wave.rb'
+            end
+            
+            def copy_configuration
+                template 'nats_wave.yml', 'config/nats_wave.yml'
+            end
+            
+            def create_migrations
+                migration_template 'create_nats_wave_failed_messages.rb',
+                                   'db/migrate/create_nats_wave_failed_messages.rb'
+                migration_template 'create_nats_wave_failed_subscriptions.rb',
+                                   'db/migrate/create_nats_wave_failed_subscriptions.rb'
+            end
+            
+            def show_instructions
+                readme 'README' if behavior == :invoke
+            end
+        end
+    end
+end

data/lib/generators/nats_wave/templates/README

@@ -0,0 +1,31 @@
+===============================================================================
+
+NatsWave has been installed successfully!
+
+Next steps:
+
+1. Run the migrations:
+   rails db:migrate
+
+2. Configure your models:
+
+   class User < ApplicationRecord
+     nats_publishable(
+       actions: [:create, :update, :destroy],
+       skip_attributes: [:password_digest, :remember_token],
+       include_associations: [:profile]
+     )
+   end
+
+3. Start the subscriber:
+   rails nats_wave:start
+
+4. Test the health:
+   rails nats_wave:health
+
+5. Configure your NATS server URL:
+   export NATS_URL=nats://your-nats-server:4222
+
+For more information, visit: https://github.com/PurpleWave/nats_wave
+
+===============================================================================

data/lib/generators/nats_wave/templates/create_nats_wave_failed_messages.rb

@@ -0,0 +1,20 @@
+class CreateNatsWaveFailedMessages < ActiveRecord::Migration[6.1]
+    def change
+        create_table :nats_wave_failed_messages do |t|
+            t.string :subject, null: false
+            t.text :payload, null: false
+            t.text :error_message, null: false
+            t.text :error_backtrace
+            t.string :error_class
+            t.integer :retry_count, default: 0, null: false
+            t.datetime :next_retry_at
+            t.datetime :last_retry_at
+            t.timestamps
+        end
+        
+        add_index :nats_wave_failed_messages, :subject
+        add_index :nats_wave_failed_messages, [:retry_count, :next_retry_at], name: 'idx_nats_wave_failed_retry'
+        add_index :nats_wave_failed_messages, :created_at
+        add_index :nats_wave_failed_messages, :error_class
+    end
+end

data/lib/generators/nats_wave/templates/create_nats_wave_failed_subscriptions.rb

@@ -0,0 +1,20 @@
+class CreateNatsWaveFailedSubscriptions < ActiveRecord::Migration[6.1]
+    def change
+        create_table :nats_wave_failed_subscriptions do |t|
+            t.string :subject, null: false
+            t.text :message, null: false
+            t.text :error_message, null: false
+            t.text :error_backtrace
+            t.string :error_class
+            t.integer :retry_count, default: 0, null: false
+            t.datetime :next_retry_at
+            t.datetime :last_retry_at
+            t.timestamps
+        end
+        
+        add_index :nats_wave_failed_subscriptions, :subject
+        add_index :nats_wave_failed_subscriptions, [:retry_count, :next_retry_at], name: 'idx_nats_wave_subs_retry'
+        add_index :nats_wave_failed_subscriptions, :created_at
+        add_index :nats_wave_failed_subscriptions, :error_class
+    end
+end

data/lib/generators/nats_wave/templates/initializer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+#
+NatsWave.configure do |config|
+    # Basic configuration
+    config.nats_url = ENV.fetch('NATS_URL', 'nats://localhost:4222')
+    config.service_name = ENV.fetch('SERVICE_NAME',
+                                    Rails.application.class.name.deconstantize.underscore)
+    config.environment = Rails.env
+    
+    # Publishing configuration
+    config.default_subject_prefix = "#{config.service_name}.events"
+    config.publishing_enabled = true
+    config.async_publishing = true
+    
+    # Subscription configuration
+    config.subscription_enabled = true
+    config.queue_group = "#{config.service_name}_consumers"
+    
+    # Model mappings (example)
+    # config.add_model_mapping('ExternalAsset', 'Catalog', {
+    #   'name' => 'title',
+    #   'description' => 'body',
+    #   'hammer_estimate' => 'cost'
+    # })
+    
+    # Subscriptions (example)
+    # config.add_subscription('external.assets.*')
+    # config.add_subscription('catalog.items.*')
+    
+    # Custom subscription with handler
+    # config.add_subscription('webhooks.external.*') do |message|
+    #   WebhookProcessor.process(message)
+    # end
+    
+    # Middleware
+    config.middleware_logging_enabled = true
+    config.log_level = Rails.env.production? ? 'info' : 'debug'
+    
+    # Authentication (optional)
+    # config.middleware_authentication_enabled = true
+    # config.auth_secret_key = ENV['NATS_AUTH_SECRET']
+    
+    # Validation (optional)
+    # config.middleware_validation_enabled = true
+    # config.schema_registry_url = ENV['SCHEMA_REGISTRY_URL']
+end
+
+# Configure metrics backend if available
+NatsWave::Metrics.metrics_backend = StatsD if defined?(StatsD)
+
+# Auto-start subscriber in development
+if Rails.env.development?
+    Rails.application.config.after_initialize do
+        Thread.new do
+            sleep 2 # Give Rails time to boot
+            begin
+                NatsWave.start_subscriber
+                Rails.logger.info 'NatsWave subscriber started automatically'
+            rescue StandardError => e
+                Rails.logger.error "Failed to start NatsWave subscriber: #{e.message}"
+            end
+        end
+    end
+end

data/lib/generators/nats_wave/templates/nats_wave.yml

@@ -0,0 +1,65 @@
+default: &default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+    connection_pool_size: 10
+    timeout: 5
+    reconnect_attempts: 3
+
+  publishing:
+    enabled: true
+    default_subject_prefix: <%= ENV['SERVICE_NAME'] %>
+    batch_size: 100
+    async: true
+
+  subscription:
+    enabled: true
+    subjects: [ ]
+    queue_group: <%= ENV['SERVICE_NAME'] %>_consumers
+
+  database:
+    adapter: "active_record"
+    connection_pool_size: 5
+
+  #  middleware:
+  #    authentication:
+  #      enabled: false
+  #      secret_key: <%= ENV['NATS_AUTH_SECRET'] %>
+  #    validation:
+  #      enabled: true
+  #      schema_registry: <%= ENV['SCHEMA_REGISTRY_URL'] %>
+  #    logging:
+  #      enabled: true
+  #      level: "info"
+
+  error_handling:
+    max_retries: 3
+    retry_delay: 5
+    dead_letter_queue: "failed_messages"
+
+development:
+  <<: *default
+  middleware:
+    authentication:
+      enabled: false
+    logging:
+      level: "debug"
+
+test:
+  <<: *default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+  publishing:
+    enabled: false
+  subscription:
+    enabled: false
+
+production:
+  <<: *default
+  nats:
+    url: <%= ENV['NATS_URL'] %>
+  middleware:
+    authentication:
+      enabled: true
+      secret_key: <%= ENV['NATS_AUTH_SECRET'] %>
+    logging:
+      level: "info"

data/lib/nats_wave/adapters/active_record.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module NatsWave
+    module Adapters
+        class ActiveRecord
+            def initialize(config)
+                @config = config
+            end
+            
+            def create_from_external(external_model, data, metadata = {})
+                mapping = ModelRegistry.local_models_for(external_model)
+                
+                mapping.each do |local_model_name, config|
+                    create_or_update_local_record(local_model_name, external_model, data, config, 'create')
+                end
+            end
+            
+            def update_from_external(external_model, data, metadata = {})
+                mapping = ModelRegistry.local_models_for(external_model)
+                
+                mapping.each do |local_model_name, config|
+                    create_or_update_local_record(local_model_name, external_model, data, config, 'update')
+                end
+            end
+            
+            def destroy_from_external(external_model, data, metadata = {})
+                mapping = ModelRegistry.local_models_for(external_model)
+                
+                mapping.each do |local_model_name, config|
+                    destroy_local_record(local_model_name, external_model, data, config)
+                end
+            end
+            
+            # Legacy methods for backward compatibility
+            def create(model_name, data, metadata = {})
+                model_class = get_model_class(model_name)
+                clean_data = data.except('created_at', 'updated_at', :created_at, :updated_at)
+                
+                with_nats_publishing_disabled do
+                    record = model_class.create!(clean_data)
+                    NatsWave.logger.debug("Created #{model_name} with ID: #{record.id}")
+                    record
+                end
+            rescue => e
+                raise DatabaseError, "Failed to create #{model_name}: #{e.message}"
+            end
+            
+            def connected?
+                return false unless defined?(::ActiveRecord)
+                ::ActiveRecord::Base.connected?
+            rescue
+                false
+            end
+            
+            private
+            
+            def create_or_update_local_record(local_model_name, external_model, external_data, config, action)
+                model_class = get_model_class(local_model_name)
+                
+                # Transform the data using field mappings and transformations
+                transformed_data = transform_external_data(external_data, config)
+                
+                # Find existing record based on unique fields
+                existing_record = find_existing_record(model_class, transformed_data, config[:unique_fields])
+                
+                with_nats_publishing_disabled do
+                    case config[:sync_strategy]
+                        when :create_only
+                            create_record_if_not_exists(model_class, existing_record, transformed_data)
+                        when :update_only
+                            update_record_if_exists(existing_record, transformed_data) if existing_record
+                        when :upsert, nil
+                            upsert_record(model_class, existing_record, transformed_data, config)
+                    end
+                end
+                
+                # Track the sync operation
+                NatsWave::Metrics.track_sync_operation(
+                        local_model_name,
+                        action,
+                        0, # duration - you could track this
+                        success: true
+                )
+            
+            rescue => e
+                NatsWave.logger.error("Failed to sync #{external_model} to #{local_model_name}: #{e.message}")
+                
+                NatsWave::Metrics.track_sync_operation(
+                        local_model_name,
+                        action,
+                        0,
+                        success: false
+                )
+                
+                raise DatabaseError, "Sync failed for #{local_model_name}: #{e.message}"
+            end
+            
+            def transform_external_data(external_data, config)
+                field_mappings = config[:field_mappings] || {}
+                transformations = config[:transformations] || {}
+                skip_fields = config[:skip_fields] || []
+                
+                transformed = {}
+                
+                external_data.each do |key, value|
+                    next if skip_fields.include?(key.to_s) || skip_fields.include?(key.to_sym)
+                    
+                    # Map field name
+                    local_field = field_mappings[key] || field_mappings[key.to_sym] || key
+                    
+                    # Apply transformation
+                    if transformations[local_field]
+                        transformation = transformations[local_field]
+                        value = case transformation
+                                    when Proc
+                                        transformation.arity == 1 ? transformation.call(value) : transformation.call(value, external_data)
+                                    when Symbol
+                                        # Would need to be called on the model instance
+                                        value
+                                    else
+                                        value
+                                end
+                    end
+                    
+                    transformed[local_field] = value
+                end
+                
+                # Remove Rails timestamp fields that might conflict
+                transformed.except('created_at', 'updated_at', :created_at, :updated_at)
+            end
+            
+            def find_existing_record(model_class, data, unique_fields)
+                unique_fields ||= [:id]
+                
+                unique_fields.each do |field|
+                    value = data[field] || data[field.to_sym]
+                    next unless value
+                    
+                    record = model_class.find_by(field => value)
+                    return record if record
+                end
+                
+                nil
+            end
+            
+            def create_record_if_not_exists(model_class, existing_record, data)
+                return existing_record if existing_record
+                
+                record = model_class.create!(data)
+                NatsWave.logger.info("Created #{model_class.name} with ID: #{record.id}")
+                record
+            end
+            
+            def update_record_if_exists(existing_record, data)
+                return unless existing_record
+                
+                existing_record.update!(data)
+                NatsWave.logger.info("Updated #{existing_record.class.name} ID: #{existing_record.id}")
+                existing_record
+            end
+            
+            def upsert_record(model_class, existing_record, data, config)
+                if existing_record
+                    existing_record.update!(data)
+                    NatsWave.logger.info("Updated #{model_class.name} ID: #{existing_record.id}")
+                    existing_record
+                else
+                    record = model_class.create!(data)
+                    NatsWave.logger.info("Created #{model_class.name} with ID: #{record.id}")
+                    record
+                end
+            end
+            
+            def destroy_local_record(local_model_name, external_model, external_data, config)
+                model_class = get_model_class(local_model_name)
+                transformed_data = transform_external_data(external_data, config)
+                
+                existing_record = find_existing_record(model_class, transformed_data, config[:unique_fields])
+                return unless existing_record
+                
+                with_nats_publishing_disabled do
+                    if existing_record.respond_to?(:soft_delete)
+                        existing_record.soft_delete
+                    else
+                        existing_record.destroy!
+                    end
+                    
+                    NatsWave.logger.info("Destroyed #{local_model_name} ID: #{existing_record.id}")
+                end
+            end
+            
+            def get_model_class(model_name)
+                model_name.constantize
+            rescue NameError
+                raise DatabaseError, "Model class '#{model_name}' not found"
+            end
+            
+            def with_nats_publishing_disabled(&block)
+                Thread.current[:skip_nats_wave_publishing] = true
+                yield
+            ensure
+                Thread.current[:skip_nats_wave_publishing] = false
+            end
+        end
+    end
+end