nats_pubsub 1.0.0

data/lib/nats_pubsub/active_record/publishable.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module NatsPubsub
+  module ActiveRecord
+    # Include this concern in your ActiveRecord models to automatically publish events
+    #
+    # @example Basic usage
+    #   class User < ApplicationRecord
+    #     include NatsPubsub::ActiveRecord::Publishable
+    #
+    #     publishes_events domain: 'users', resource: 'user'
+    #   end
+    #
+    # @example Advanced usage with conditional publishing
+    #   class Order < ApplicationRecord
+    #     include NatsPubsub::ActiveRecord::Publishable
+    #
+    #     publishes_events domain: 'orders',
+    #                      resource: 'order',
+    #                      on_create: true,
+    #                      on_update: -> { status_changed? },
+    #                      on_destroy: false,
+    #                      if: :should_publish?,
+    #                      except: [:internal_notes]
+    #
+    #     def should_publish?
+    #       !imported?
+    #     end
+    #   end
+    module Publishable
+      extend ActiveSupport::Concern
+
+      # Default sensitive attributes to exclude from events
+      DEFAULT_SENSITIVE_ATTRIBUTES = %i[
+        password password_digest encrypted_password
+        reset_password_token reset_password_sent_at
+        remember_created_at confirmation_token
+        unlock_token otp_secret_key otp_backup_codes
+        api_key api_secret access_token refresh_token
+        ssn credit_card_number bank_account
+      ].freeze
+
+      included do
+        class_attribute :publish_config, default: {}
+        class_attribute :sensitive_attributes, default: DEFAULT_SENSITIVE_ATTRIBUTES
+      end
+
+      class_methods do
+        # Configure event publishing for this model
+        #
+        # @param domain [String] Domain for pubsub subject (default: pluralized model name)
+        # @param resource [String] Resource type (default: underscored model name)
+        # @param options [Hash] Additional options
+        # @option options [Boolean, Proc] :on_create Publish created events (default: true)
+        # @option options [Boolean, Proc] :on_update Publish updated events (default: true)
+        # @option options [Boolean, Proc] :on_destroy Publish deleted events (default: true)
+        # @option options [Symbol, Proc] :if Conditional publishing
+        # @option options [Symbol, Proc] :unless Conditional publishing (inverted)
+        # @option options [Array<Symbol>] :only Whitelist attributes to publish
+        # @option options [Array<Symbol>] :except Blacklist attributes (in addition to sensitive)
+        # @option options [Symbol] :error_handler Custom error handler method name
+        def publishes_events(domain: nil, resource: nil, **options)
+          self.publish_config = {
+            domain: domain || name.underscore.pluralize,
+            resource: resource || name.underscore,
+            on_create: options.fetch(:on_create, true),
+            on_update: options.fetch(:on_update, true),
+            on_destroy: options.fetch(:on_destroy, true),
+            if: options[:if],
+            unless: options[:unless],
+            only: options[:only],
+            except: options[:except],
+            error_handler: options[:error_handler] || :handle_publish_error
+          }
+
+          setup_callbacks
+        end
+
+        # Add custom sensitive attributes
+        #
+        # @param attributes [Array<Symbol>] Attributes to exclude from publishing
+        def exclude_from_publishing(*attributes)
+          self.sensitive_attributes = sensitive_attributes + attributes.flatten
+        end
+
+        private
+
+        def setup_callbacks
+          setup_create_callback if publish_config[:on_create]
+          setup_update_callback if publish_config[:on_update]
+          setup_destroy_callback if publish_config[:on_destroy]
+        end
+
+        def setup_create_callback
+          condition = publish_config[:on_create]
+          after_commit :publish_created_event, on: :create,
+                       if: -> { should_publish_event?(:on_create, condition) }
+        end
+
+        def setup_update_callback
+          condition = publish_config[:on_update]
+          after_commit :publish_updated_event, on: :update,
+                       if: -> { saved_changes? && should_publish_event?(:on_update, condition) }
+        end
+
+        def setup_destroy_callback
+          condition = publish_config[:on_destroy]
+          after_commit :publish_deleted_event, on: :destroy,
+                       if: -> { should_publish_event?(:on_destroy, condition) }
+        end
+      end
+
+      private
+
+      def publish_created_event
+        publish_event('created')
+      end
+
+      def publish_updated_event
+        publish_event('updated', changes: previous_changes.keys)
+      end
+
+      def publish_deleted_event
+        publish_event('deleted')
+      end
+
+      def publish_event(action, extra = {})
+        config = self.class.publish_config
+        domain = config[:domain]
+        resource = config[:resource]
+
+        payload = publishable_attributes.merge(extra)
+
+        NatsPubsub.publish(domain, resource, action, **payload)
+      rescue StandardError => e
+        # Call custom error handler if defined
+        error_handler = config[:error_handler]
+        if error_handler && respond_to?(error_handler, true)
+          send(error_handler, e, action, payload)
+        else
+          handle_publish_error(e, action, payload)
+        end
+      end
+
+      def handle_publish_error(error, action, payload)
+        # Default error handler - log but don't fail
+        return unless defined?(Rails) && Rails.logger
+
+        Rails.logger.error(
+          "[NatsPubsub::Publishable] Failed to publish #{self.class.name}.#{action}: #{error.message}"
+        )
+      end
+
+      def should_publish_event?(event_type, condition)
+        # Check global if/unless conditions
+        config = self.class.publish_config
+        return false if config[:unless] && evaluate_condition(config[:unless])
+        return false if config[:if] && !evaluate_condition(config[:if])
+
+        # Check event-specific condition
+        return true if condition == true
+        return false if condition == false
+
+        evaluate_condition(condition) if condition
+      end
+
+      def evaluate_condition(condition)
+        case condition
+        when Symbol
+          send(condition)
+        when Proc
+          instance_eval(&condition)
+        else
+          !!condition
+        end
+      end
+
+      def publishable_attributes
+        attrs = attributes.symbolize_keys
+        config = self.class.publish_config
+
+        # Handle :only option (whitelist)
+        attrs = attrs.slice(*config[:only]) if config[:only]
+
+        # Exclude sensitive and custom blacklist
+        excluded = self.class.sensitive_attributes
+        excluded += config[:except] if config[:except]
+        attrs.except(*excluded)
+      end
+    end
+  end
+end

data/lib/nats_pubsub/cli.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'core/logging'
+require_relative 'subscribers/registry'
+
+module NatsPubsub
+  # CLI for running NatsPubsub subscribers
+  class CLI
+    def initialize(options = {})
+      @options = options
+      @pool = nil
+      @running = true
+    end
+
+    def run
+      setup_environment
+      setup_signal_handlers
+      discover_subscribers
+      start_pool
+      wait_for_shutdown
+    end
+
+    private
+
+    def setup_environment
+      ENV['RAILS_ENV'] = ENV['RACK_ENV'] = @options[:environment] if @options[:environment]
+
+      if @options[:require]
+        require File.expand_path(@options[:require])
+      elsif File.exist?('config/environment.rb')
+        require File.expand_path('config/environment.rb')
+      else
+        raise 'Cannot find application. Use -r to specify file to require.'
+      end
+
+      Logging.info(
+        "NatsPubsub starting in #{@options[:environment] || ENV['RAILS_ENV'] || 'development'} environment",
+        tag: 'NatsPubsub::CLI'
+      )
+    end
+
+    def discover_subscribers
+      Subscribers::Registry.instance.discover_subscribers!
+
+      subscribers = Subscribers::Registry.instance.all_subscribers
+      return unless subscribers.empty?
+
+      Logging.warn(
+        'No subscribers found in app/subscribers/',
+        tag: 'NatsPubsub::CLI'
+      )
+      exit(1)
+    end
+
+    def start_pool
+      # Load Pool (lazy load to avoid circular dependencies)
+      require_relative 'subscribers/pool'
+
+      concurrency = @options[:concurrency] || NatsPubsub.config.concurrency || 5
+      @pool = Subscribers::Pool.new(concurrency: concurrency)
+
+      Thread.new do
+        @pool.start!
+      end
+    end
+
+    def setup_signal_handlers
+      %w[INT TERM].each do |signal|
+        trap(signal) do
+          Logging.info(
+            "Received #{signal}, shutting down gracefully...",
+            tag: 'NatsPubsub::CLI'
+          )
+          @running = false
+          @pool&.stop!
+        end
+      end
+
+      trap('USR1') do
+        Logging.info('Thread dump:', tag: 'NatsPubsub::CLI')
+        Thread.list.each do |thread|
+          Logging.info(
+            "#{thread.name || thread.object_id}: #{thread.status}",
+            tag: 'NatsPubsub::CLI'
+          )
+        end
+      end
+    rescue ArgumentError => e
+      # Some systems don't support USR1
+      Logging.warn("Could not setup USR1 signal handler: #{e.message}", tag: 'NatsPubsub::CLI')
+    end
+
+    def wait_for_shutdown
+      sleep 0.5 while @running
+
+      Logging.info(
+        'Waiting for in-flight messages to complete...',
+        tag: 'NatsPubsub::CLI'
+      )
+      sleep 2
+
+      Logging.info('Shutdown complete', tag: 'NatsPubsub::CLI')
+    end
+  end
+end

data/lib/nats_pubsub/core/base_repository.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../models/model_utils'
+require_relative 'logging'
+
+module NatsPubsub
+  # Base repository class with common persistence patterns.
+  # Follows Template Method pattern for shared persistence flow.
+  # Extracted to DRY up InboxRepository and OutboxRepository.
+  class BaseRepository
+    attr_reader :model_class
+
+    def initialize(model_class)
+      @model_class = model_class
+    end
+
+    # Find or build a record by event_id
+    #
+    # @param event_id [String] Event identifier
+    # @return [ActiveRecord::Base] Record instance
+    def find_or_build(event_id)
+      ModelUtils.find_or_init_by_best(
+        model_class,
+        { event_id: event_id },
+        { dedup_key: event_id }
+      )
+    end
+
+    protected
+
+    # Assign attributes to record safely
+    #
+    # @param record [ActiveRecord::Base] Record instance
+    # @param attrs [Hash] Attributes to assign
+    def assign_attributes(record, attrs)
+      ModelUtils.assign_known_attrs(record, attrs)
+    end
+
+    # Save record with error handling
+    #
+    # @param record [ActiveRecord::Base] Record instance
+    # @raise [ActiveRecord::RecordInvalid] if save fails
+    def save_record!(record)
+      record.save!
+    rescue StandardError => e
+      Logging.error(
+        "Failed to save #{model_class.name}: #{e.class} #{e.message}",
+        tag: 'NatsPubsub::BaseRepository'
+      )
+      raise
+    end
+
+    # Update record with timestamp
+    #
+    # @param record [ActiveRecord::Base] Record instance
+    # @param attrs [Hash] Attributes to update
+    # @param timestamp [Time] Timestamp to use
+    def update_with_timestamp(record, attrs, timestamp = Time.now.utc)
+      attrs[:updated_at] = timestamp if record.respond_to?(:updated_at)
+      assign_attributes(record, attrs)
+      save_record!(record)
+    end
+
+    # Check if attribute exists on record
+    #
+    # @param record [ActiveRecord::Base] Record instance
+    # @param attribute [Symbol] Attribute name
+    # @return [Boolean]
+    def has_attribute?(record, attribute)
+      record.respond_to?(attribute)
+    end
+  end
+end

data/lib/nats_pubsub/core/config.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require_relative 'subject'
+require_relative 'constants'
+
+module NatsPubsub
+  class Config
+    attr_accessor :nats_urls, :env, :app_name, :destination_app,
+                  :max_deliver, :ack_wait, :backoff,
+                  :use_outbox, :use_inbox, :inbox_model, :outbox_model,
+                  :use_dlq, :dlq_max_attempts, :dlq_stream_suffix,
+                  :logger, :concurrency,
+                  :connection_pool_size, :connection_pool_timeout
+    attr_reader :preset
+
+    def initialize(preset: nil)
+      @preset = preset
+
+      # Default values (can be overridden by preset)
+      @nats_urls = ENV['NATS_URLS'] || ENV['NATS_URL'] || 'nats://localhost:4222'
+      @env       = ENV['NATS_ENV']  || 'development'
+      @app_name  = ENV['APP_NAME']  || 'app'
+      @destination_app = ENV.fetch('DESTINATION_APP', nil)
+
+      @max_deliver = Constants::Retry::MAX_ATTEMPTS
+      @ack_wait    = "#{Constants::Timeouts::ACK_WAIT_DEFAULT / 1000}s"
+      @backoff     = Constants::Retry::DEFAULT_BACKOFF.map { |ms| "#{ms}ms" }
+
+      @use_outbox   = false
+      @use_inbox    = false
+      @use_dlq      = true
+      @dlq_max_attempts = Constants::DLQ::MAX_ATTEMPTS
+      @dlq_stream_suffix = Constants::DLQ::STREAM_SUFFIX
+      @outbox_model = 'NatsPubsub::OutboxEvent'
+      @inbox_model  = 'NatsPubsub::InboxEvent'
+      @logger       = nil
+      @concurrency  = Constants::Consumer::DEFAULT_CONCURRENCY
+
+      # Connection pool settings
+      @connection_pool_size = ENV.fetch('NATS_POOL_SIZE', 5).to_i
+      @connection_pool_timeout = ENV.fetch('NATS_POOL_TIMEOUT', 5).to_i
+
+      # Middleware chain (lazy loaded to avoid circular dependency)
+      @server_middleware = nil
+
+      # Apply preset if provided
+      apply_preset!(preset) if preset
+    end
+
+    # Stream name per environment
+    def stream_name
+      "#{env}-events-stream"
+    end
+
+    # PubSub event subject format
+    # Delegates to Subject class for centralized subject building
+    # Format: {env}.{app_name}.{domain}.{resource}.{action}
+    def event_subject(domain, resource, action)
+      Subject.from_event(
+        env: env,
+        app_name: app_name,
+        domain: domain,
+        resource: resource,
+        action: action
+      ).to_s
+    end
+
+    # DLQ subject for failed messages
+    def dlq_subject
+      "#{env}.#{app_name}.dlq"
+    end
+
+    # DLQ stream name
+    def dlq_stream_name
+      "#{stream_name}#{dlq_stream_suffix}"
+    end
+
+    # Durable consumer name
+    def durable_name
+      "#{env}-#{app_name}-workers"
+    end
+
+    # Access/configure server middleware
+    def server_middleware
+      @server_middleware ||= begin
+        require_relative '../middleware/chain'
+        Middleware::Chain.new
+      end
+
+      yield @server_middleware if block_given?
+      @server_middleware
+    end
+
+    # Apply a configuration preset
+    #
+    # @param preset_name [Symbol] Preset name (:development, :production, :testing)
+    # @raise [ArgumentError] if preset is unknown
+    # @return [void]
+    def apply_preset!(preset_name)
+      require_relative 'config_presets'
+      ConfigPresets.apply!(self, preset_name)
+      @preset = preset_name
+    end
+
+    # Validate configuration values
+    # Raises ConfigurationError if invalid
+    #
+    # @raise [ConfigurationError] if configuration is invalid
+    # @return [void]
+    def validate!
+      validate_required_fields!
+      validate_numeric_ranges!
+      validate_urls!
+      validate_concurrency_bounds!
+    end
+
+    private
+
+    def validate_required_fields!
+      raise ConfigurationError, 'app_name cannot be blank' if app_name.nil? || app_name.to_s.strip.empty?
+      raise ConfigurationError, 'env cannot be blank' if env.nil? || env.to_s.strip.empty?
+      raise ConfigurationError, 'nats_urls cannot be empty' if nats_urls.nil? || nats_urls.empty?
+    end
+
+    def validate_numeric_ranges!
+      raise ConfigurationError, 'concurrency must be positive' if concurrency && concurrency <= 0
+      raise ConfigurationError, 'max_deliver must be positive' if max_deliver && max_deliver <= 0
+      raise ConfigurationError, 'dlq_max_attempts must be positive' if dlq_max_attempts && dlq_max_attempts <= 0
+    end
+
+    def validate_concurrency_bounds!
+      return unless concurrency
+
+      min = Constants::Consumer::MIN_CONCURRENCY
+      max = Constants::Consumer::MAX_CONCURRENCY
+
+      if concurrency < min
+        raise ConfigurationError, "concurrency must be at least #{min}, got #{concurrency}"
+      elsif concurrency > max
+        raise ConfigurationError, "concurrency cannot exceed #{max}, got #{concurrency}"
+      end
+    end
+
+    def validate_urls!
+      return unless nats_urls
+
+      Array(nats_urls).each do |url|
+        raise ConfigurationError, "Invalid NATS URL: #{url}" unless url =~ %r{\Anats://}i
+      end
+    end
+  end
+end

data/lib/nats_pubsub/core/config_presets.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+
+module NatsPubsub
+  # Configuration presets for common deployment scenarios
+  # Provides smart defaults for development, production, and testing environments
+  #
+  # @example Using a preset
+  #   NatsPubsub.setup_with_preset!(:production) do |config|
+  #     config.nats_urls = ENV['NATS_URLS']
+  #     config.app_name = 'my-app'
+  #   end
+  class ConfigPresets
+    class << self
+      # Apply a preset to a configuration object
+      #
+      # @param config [Config] Configuration object to modify
+      # @param preset [Symbol] Preset name (:development, :production, :testing)
+      # @raise [ArgumentError] if preset is unknown
+      def apply!(config, preset)
+        case preset
+        when :development
+          apply_development!(config)
+        when :production
+          apply_production!(config)
+        when :testing, :test
+          apply_testing!(config)
+        else
+          raise ArgumentError, "Unknown preset: #{preset}. Available: :development, :production, :testing"
+        end
+      end
+
+      # Get preset description
+      #
+      # @param preset [Symbol] Preset name
+      # @return [String] Description of the preset
+      def description(preset)
+        DESCRIPTIONS[preset] || "Unknown preset: #{preset}"
+      end
+
+      # List all available presets
+      #
+      # @return [Array<Symbol>] Available preset names
+      def available_presets
+        %i[development production testing]
+      end
+
+      private
+
+      # Development preset - optimized for local development
+      # - Verbose logging for debugging
+      # - Lower concurrency to avoid resource exhaustion
+      # - DLQ enabled for debugging failed messages
+      # - Shorter timeouts for faster feedback
+      # - Outbox/Inbox disabled by default (can enable for testing)
+      def apply_development!(config)
+        config.env = 'development' unless config.env
+        config.concurrency = Constants::Consumer::DEFAULT_CONCURRENCY
+        config.max_deliver = 3 # Fail faster in development
+        config.ack_wait = '10s' # Shorter timeout for faster feedback
+        config.backoff = %w[500ms 2s 5s] # Faster retries
+
+        # Features
+        config.use_dlq = true
+        config.use_outbox = false
+        config.use_inbox = false
+        config.dlq_max_attempts = 2 # Fail to DLQ faster for debugging
+
+        # Logging - verbose for development
+        config.logger ||= create_logger(:debug)
+      end
+
+      # Production preset - optimized for reliability and performance
+      # - Error-level logging to reduce noise
+      # - Higher concurrency for throughput
+      # - DLQ enabled for failure recovery
+      # - Longer timeouts for stability
+      # - Outbox/Inbox available (must explicitly enable)
+      def apply_production!(config)
+        config.env = 'production' unless config.env
+        config.concurrency = 20 # Higher throughput
+        config.max_deliver = Constants::Retry::MAX_ATTEMPTS
+        config.ack_wait = "#{Constants::Timeouts::ACK_WAIT_DEFAULT / 1000}s"
+        config.backoff = Constants::Retry::DEFAULT_BACKOFF.map { |ms| "#{ms}ms" }
+
+        # Features
+        config.use_dlq = true
+        config.use_outbox = false # Explicitly enable when needed
+        config.use_inbox = false # Explicitly enable when needed
+        config.dlq_max_attempts = Constants::DLQ::MAX_ATTEMPTS
+
+        # Logging - errors only in production
+        config.logger ||= create_logger(:error)
+      end
+
+      # Testing preset - optimized for test suite performance
+      # - Synchronous processing (no background workers)
+      # - Minimal logging to avoid test output noise
+      # - DLQ disabled (tests should verify behavior directly)
+      # - Fast timeouts
+      # - Fake mode enabled by default
+      def apply_testing!(config)
+        config.env = 'test' unless config.env
+        config.concurrency = 1 # Synchronous processing
+        config.max_deliver = 2 # Fail fast in tests
+        config.ack_wait = '1s' # Fast timeout
+        config.backoff = %w[100ms 500ms] # Minimal retries
+
+        # Features - disabled for speed
+        config.use_dlq = false
+        config.use_outbox = false
+        config.use_inbox = false
+        config.dlq_max_attempts = 1
+
+        # Logging - minimal for tests
+        config.logger ||= create_logger(:fatal) # Only fatal errors
+      end
+
+      # Create a logger with specified level
+      def create_logger(level)
+        require 'logger'
+        logger = Logger.new($stdout)
+        logger.level = Logger.const_get(level.to_s.upcase)
+        logger.formatter = proc do |severity, datetime, _progname, msg|
+          "[#{datetime.strftime('%Y-%m-%d %H:%M:%S')}] #{severity}: #{msg}\n"
+        end
+        logger
+      end
+
+      # Preset descriptions for documentation
+      DESCRIPTIONS = {
+        development: 'Optimized for local development with verbose logging and fast feedback',
+        production: 'Optimized for reliability and performance in production environments',
+        testing: 'Optimized for test suite performance with synchronous processing'
+      }.freeze
+    end
+  end
+end