yes-core 1.0.0

data/lib/yes/core/command_handling/read_model_recovery_service.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Service for recovering read models that are stuck in pending state
+      # This handles cases where the process was interrupted after publishing an event
+      # but before updating the read model
+      class ReadModelRecoveryService
+        # Default timeout after which a read model is considered stuck
+        DEFAULT_STUCK_TIMEOUT = 1.minute
+
+        # Recovery attempt result
+        RecoveryResult = Struct.new(:success, :read_model, :error_message, keyword_init: true)
+
+        class << self
+          include Yes::Core::OpenTelemetry::Trackable
+
+          # Finds and recovers all stuck read models
+          # @param stuck_timeout [ActiveSupport::Duration] Time after which a model is considered stuck
+          # @param batch_size [Integer] Number of read models to process at once
+          # @return [Array<RecoveryResult>] Results of recovery attempts
+          def recover_all_stuck_read_models(stuck_timeout: DEFAULT_STUCK_TIMEOUT, batch_size: 100)
+            results = []
+
+            find_stuck_read_models_with_aggregates(stuck_timeout:, batch_size:).each do |entry|
+              result = recover_read_model(
+                entry[:read_model],
+                aggregate_class: entry[:aggregate_class],
+                is_draft: entry[:is_draft]
+              )
+              results << result
+
+              log_recovery_result(result)
+            end
+
+            results
+          end
+
+          # Recovers a single read model
+          # @param read_model [ActiveRecord::Base] The read model to recover
+          # @param aggregate_class [Class] The aggregate class to use for recovery
+          # @param is_draft [Boolean] Flag indicating if this is a draft aggregate
+          # @return [RecoveryResult] Result of the recovery attempt
+          def recover_read_model(read_model, aggregate_class:, is_draft: false)
+            # Use advisory lock to prevent concurrent recovery attempts
+            lock_key = "read_model_recovery_#{read_model.class.name}_#{read_model.id}"
+
+            with_advisory_lock(lock_key) do
+              # Re-check if still stuck after acquiring lock
+              read_model.reload
+
+              return RecoveryResult.new(success: true, read_model:, error_message: 'Already recovered') unless read_model.pending_update_since?
+
+              # Instantiate aggregate with proper parameters
+              aggregate_id = determine_aggregate_id(read_model)
+
+              aggregate = if is_draft
+                            aggregate_class.new(aggregate_id, draft: true)
+                          else
+                            aggregate_class.new(aggregate_id)
+                          end
+
+              latest_event = aggregate.latest_event
+
+              # Reapply the update using ReadModelUpdater
+              updater = ReadModelUpdater.new(aggregate)
+              updater.call(latest_event, latest_event.data)
+
+              RecoveryResult.new(success: true, read_model:)
+            end
+          rescue ActiveRecord::ActiveRecordError => e
+            # Database errors during recovery
+            RecoveryResult.new(
+              success: false,
+              read_model:,
+              error_message: "Database error during recovery: #{e.message}"
+            )
+          rescue PgEventstore::Error => e
+            # Event store errors during recovery
+            RecoveryResult.new(
+              success: false,
+              read_model:,
+              error_message: "Event store error during recovery: #{e.message}"
+            )
+          rescue StandardError => e
+            # Unexpected errors - log them for debugging
+            Rails.logger.error("Unexpected error recovering read model #{read_model.class.name}##{read_model.id}: #{e.class.name}")
+            RecoveryResult.new(
+              success: false,
+              read_model:,
+              error_message: "Unexpected error: #{e.class.name} - #{e.message}"
+            )
+          end
+
+          # Checks if a read model needs recovery and attempts it with retries
+          # @param read_model [ActiveRecord::Base] The read model to check
+          # @param aggregate [Yes::Core::Aggregate] Aggregate instance to use for recovery
+          # @param threshold [ActiveSupport::Duration] Time threshold for recovery (default: 2 seconds)
+          # @param max_retries [Integer] Maximum number of retry attempts (default: 10)
+          # @return [void]
+          # @raise [Yes::Core::Utils::ExponentialRetrier::RetryFailedError] If recovery fails after max retries
+          # @raise [Yes::Core::Utils::ExponentialRetrier::TimeoutError] If recovery times out
+          def check_and_recover_with_retries(read_model, aggregate:, threshold: 2.seconds, max_retries: 10)
+            return unless read_model.respond_to?(:pending_update_since)
+
+            retrier = Yes::Core::Utils::ExponentialRetrier.new(
+              max_retries: max_retries,
+              base_sleep_time: 0.1,
+              max_sleep_time: 1.0,
+              timeout: 30,
+              logger: Rails.logger
+            )
+
+            retrier.call(
+              condition_check: -> { attempt_recovery_if_pending(read_model, threshold, aggregate:) },
+              failure_message: "Could not recover pending read model #{read_model.class.name}##{read_model.id}",
+              timeout_message: "Timeout waiting for read model recovery #{read_model.class.name}##{read_model.id}"
+            ) do
+              # Success - either not pending or recovered
+              true
+            end
+          end
+
+          otl_trackable(
+            :check_and_recover_with_retries,
+            Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Check and Recover Readmodel with Retries')
+          )
+
+          # Attempts inline recovery during command execution retry loops
+          # This method is designed to be called from CommandExecutor when stuck in retry loops
+          # @param read_model [ActiveRecord::Base] The read model to check and recover
+          # @param aggregate [Yes::Core::Aggregate] Aggregate instance to use for recovery
+          # @param threshold [ActiveSupport::Duration] Time threshold for considering state stuck (default: 2 seconds)
+          # @return [Boolean] True if recovery succeeded or not needed, false if recovery failed
+          def attempt_inline_recovery(read_model, aggregate:, threshold: 2.seconds)
+            return true unless read_model.respond_to?(:pending_update_since)
+
+            attempt_recovery_if_pending(read_model, threshold, aggregate: aggregate)
+          end
+
+          private
+
+          # Checks state and attempts recovery in one go
+          # @param read_model [ActiveRecord::Base] The read model to check
+          # @param threshold [ActiveSupport::Duration] Time threshold for recovery
+          # @param aggregate [Yes::Core::Aggregate] Aggregate instance to use for recovery
+          # @return [Boolean] True if no recovery needed or recovery succeeded, false if recovery needed but failed
+          def attempt_recovery_if_pending(read_model, threshold, aggregate:)
+            read_model.reload
+
+            # Not pending - we're good
+            return true if read_model.pending_update_since.blank?
+
+            # Pending but too recent - another process is working on it, proceed
+            return true unless read_model.pending_update_since < threshold.ago
+
+            # Pending and old enough - attempt recovery now
+            Rails.logger.info("Read model #{read_model.class.name}##{read_model.id} is in pending state, attempting recovery")
+
+            begin
+              updater = ReadModelUpdater.new(aggregate)
+              updater.call(
+                aggregate.latest_event,
+                aggregate.latest_event.data
+              )
+              Rails.logger.info("Successfully recovered read model #{read_model.class.name}##{read_model.id}")
+              true
+            rescue Yes::Core::CommandHandling::ReadModelRevisionGuard::RevisionAlreadyAppliedError
+              # Another thread already recovered - this is a successful outcome
+              Rails.logger.info("Recovery already completed by another thread for #{read_model.class.name}##{read_model.id}")
+
+              # Ensure pending flag is cleared if still set
+              read_model.reload
+              if read_model.pending_update_since.present?
+                read_model.update_column(:pending_update_since, nil)
+                Rails.logger.debug { "Cleared lingering pending_update_since flag for #{read_model.class.name}##{read_model.id}" }
+              end
+
+              true
+            rescue ActiveRecord::ActiveRecordError, PgEventstore::Error => e
+              # Expected errors during recovery
+              Rails.logger.debug { "Recovery attempt failed for #{read_model.class.name}##{read_model.id}: #{e.message}" }
+              false
+            rescue StandardError => e
+              # Unexpected errors
+              Rails.logger.error("Unexpected error during recovery attempt for #{read_model.class.name}##{read_model.id}: #{e.class.name} - #{e.message}")
+              false
+            end
+          end
+
+          # Finds all read models stuck in pending state with their aggregate classes
+          # @param stuck_timeout [ActiveSupport::Duration] Time after which a model is considered stuck
+          # @param batch_size [Integer] Number of records to fetch
+          # @return [Array<Hash>] Stuck read models with their aggregate classes and draft flags
+          def find_stuck_read_models_with_aggregates(stuck_timeout:, batch_size:)
+            stuck_models = []
+
+            Yes::Core.configuration.all_read_models_with_aggregate_classes.each do |mapping|
+              read_model_class = mapping[:read_model_class]
+              aggregate_class = mapping[:aggregate_class]
+              is_draft = mapping[:is_draft]
+
+              next unless read_model_class.column_names.include?('pending_update_since')
+
+              read_model_class.
+                where.not(pending_update_since: nil).
+                where(pending_update_since: ...stuck_timeout.ago).
+                limit(batch_size).
+                each do |read_model|
+                  stuck_models << { read_model:, aggregate_class:, is_draft: }
+                end
+            end
+
+            stuck_models
+          end
+
+          # Determines the aggregate ID from a read model
+          # @param read_model [ActiveRecord::Base] The read model
+          # @return [String] The aggregate ID
+          def determine_aggregate_id(read_model)
+            read_model.respond_to?(:aggregate_id) ? read_model.aggregate_id : read_model.id
+          end
+
+          # Acquires an advisory lock for the given key
+          # @param lock_key [String] The lock key
+          # @yield Block to execute with the lock
+          def with_advisory_lock(lock_key)
+            # Use PostgreSQL advisory lock
+            lock_id = Zlib.crc32(lock_key)
+
+            connection = ActiveRecord::Base.connection
+            obtained = connection.execute("SELECT pg_try_advisory_lock(#{lock_id})").first['pg_try_advisory_lock']
+
+            return yield if obtained
+
+            raise "Could not obtain advisory lock for #{lock_key}"
+          ensure
+            connection.execute("SELECT pg_advisory_unlock(#{lock_id})") if obtained
+          end
+
+          # Logs the result of a recovery attempt
+          # @param result [RecoveryResult] The recovery result
+          def log_recovery_result(result)
+            if result.success
+              Rails.logger.info(
+                "Successfully recovered read model: #{result.read_model.class.name}##{result.read_model.id}"
+              )
+            else
+              Rails.logger.error(
+                "Failed to recover read model: #{result.read_model.class.name}##{result.read_model.id} - #{result.error_message}"
+              )
+            end
+          end
+
+          # Access to command utilities
+          def command_utilities
+            Yes::Core::CommandUtilities
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/read_model_revision_guard.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative '../utils/exponential_retrier'
+
+module Yes
+  module Core
+    module CommandHandling
+      # Ensures that read model revisions match expected event revisions
+      # Uses ExponentialRetrier for retry logic with exponential backoff
+      # This handles eventual consistency between the event store and read model databases
+      class ReadModelRevisionGuard
+        # Error raised when revision guard fails after maximum retries
+        class RevisionMismatchError < Yes::Core::Error; end
+
+        # Error raised when timeout is exceeded
+        class TimeoutError < Yes::Core::Utils::ExponentialRetrier::TimeoutError; end
+
+        # Error raised when revision has already been applied
+        class RevisionAlreadyAppliedError < Yes::Core::Error; end
+
+        # Logger wrapper that adds revision context to log messages
+        class ContextualLogger
+          def initialize(base_logger, context)
+            @base_logger = base_logger
+            @context = context
+          end
+
+          def info(message)
+            return unless base_logger
+
+            base_logger.info("#{message} for revision #{context.expected_revision}")
+          end
+
+          def error(message)
+            return unless base_logger
+
+            base_logger.error(
+              "#{message} for revision #{context.expected_revision}. " \
+              "Current revision: #{context.current_revision}"
+            )
+          end
+
+          def debug(message)
+            return unless base_logger&.debug?
+
+            base_logger.debug(
+              "#{message} for revision #{context.expected_revision} (current: #{context.current_revision})"
+            )
+          end
+
+          def debug?
+            base_logger&.debug?
+          end
+
+          private
+
+          attr_reader :base_logger, :context
+        end
+
+        class << self
+          # Calls the guard with a read model and expected revision
+          #
+          # @param read_model [Object] The read model to guard
+          # @param expected_revision [Integer] The expected revision (should be read_model.revision + 1)
+          # @param revision_column [Symbol] The revision column to use (defaults to :revision)
+          # @yield Block to execute when revisions match
+          # @return [Object] Result of the block execution
+          # @raise [RevisionMismatchError] When revisions don't match after maximum retries
+          # @raise [TimeoutError] When timeout is exceeded
+          # @raise [RevisionAlreadyAppliedError] When revision has already been applied
+          def call(read_model, expected_revision, revision_column: :revision, &)
+            new(read_model, expected_revision, revision_column:).call(&)
+          end
+        end
+
+        # @param read_model [Object] The read model to guard
+        # @param expected_revision [Integer] The expected revision
+        # @param revision_column [Symbol] The revision column to use (defaults to :revision)
+        def initialize(read_model, expected_revision, revision_column: :revision)
+          @read_model = read_model
+          @expected_revision = expected_revision
+          @revision_column = revision_column
+        end
+
+        # Gets the expected revision for this guard
+        #
+        # @return [Integer] The expected revision value
+        attr_reader :expected_revision
+
+        # Gets the current revision from the read model using the specified column
+        #
+        # @return [Integer] The current revision value
+        def current_revision
+          read_model.public_send(revision_column)
+        end
+
+        # Executes the guard logic with retry mechanism
+        #
+        # @yield Block to execute when revisions match
+        # @return [Object] Result of the block execution
+        # @raise [RevisionMismatchError] When revisions don't match after maximum retries
+        # @raise [TimeoutError] When timeout is exceeded
+        # @raise [RevisionAlreadyAppliedError] When revision has already been applied
+        def call(&)
+          retrier = create_retrier
+
+          begin
+            retrier.call(
+              condition_check: -> { check_revision_and_return_match_status },
+              failure_message: revision_mismatch_message,
+              timeout_message: timeout_message,
+              &
+            )
+          rescue Yes::Core::Utils::ExponentialRetrier::RetryFailedError => e
+            raise RevisionMismatchError, e.message
+          rescue Yes::Core::Utils::ExponentialRetrier::TimeoutError => e
+            raise TimeoutError, e.message
+          end
+        end
+
+        private
+
+        attr_reader :read_model, :revision_column
+
+        # Creates the retrier with custom logging context
+        #
+        # @return [Yes::Core::Utils::ExponentialRetrier] Configured retrier instance
+        def create_retrier
+          Yes::Core::Utils::ExponentialRetrier.new(
+            max_retries: 10,
+            base_sleep_time: 0.1,
+            max_sleep_time: 5.0,
+            jitter_factor: 0.1,
+            timeout: 30,
+            logger: create_contextual_logger
+          )
+        end
+
+        # Creates a logger wrapper that adds revision context to log messages
+        #
+        # @return [ContextualLogger] Logger with revision context
+        def create_contextual_logger
+          base_logger = defined?(Rails.logger) ? Rails.logger : nil
+          ContextualLogger.new(base_logger, self)
+        end
+
+        # Checks revision status and returns whether revision matches
+        # Also handles the revision already applied error
+        #
+        # @return [Boolean] True if revision matches, false if record not found (retry)
+        # @raise [RevisionAlreadyAppliedError] When revision has already been applied
+        def check_revision_and_return_match_status
+          read_model.reload
+          check_revision_status!
+          revision_matches?
+        rescue ActiveRecord::RecordNotFound
+          # Record was just created but not yet visible due to transaction timing,
+          # read replica lag, or isolation levels. Return false to trigger retry.
+          false
+        end
+
+        # Checks if the current read model revision + 1 equals the expected revision
+        #
+        # @return [Boolean] True if revisions match
+        def revision_matches?
+          read_model.public_send(revision_column) + 1 == expected_revision
+        end
+
+        # Checks if we've somehow skipped past the expected revision
+        #
+        # @raise [RevisionAlreadyAppliedError] When revision has already been applied
+        def check_revision_status!
+          return unless current_revision >= expected_revision
+
+          raise RevisionAlreadyAppliedError,
+                "Expected revision #{expected_revision} but read model already at revision #{current_revision}. " \
+                'This revision may have already been applied.'
+        end
+
+        # Generates error message for revision mismatch
+        #
+        # @return [String] Error message
+        def revision_mismatch_message
+          'Revision mismatch. ' \
+            "Expected revision #{expected_revision}, but read model has revision #{current_revision}. " \
+            "Expected: read_model.#{revision_column} (#{current_revision}) + 1 = #{expected_revision}"
+        end
+
+        # Generates error message for timeout
+        #
+        # @return [String] Timeout message
+        def timeout_message
+          "Timeout waiting for revision #{expected_revision}. Current revision: #{current_revision}"
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/read_model_updater.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Updates read models with revision guard to ensure consistency
+      # Handles state updater instantiation and execution within a revision-protected context
+      #
+      # @example
+      #   updater = ReadModelUpdater.new(aggregate)
+      #   updater.call(event, command_payload, :approve_documents)
+      #
+      class ReadModelUpdater
+        include Yes::Core::OpenTelemetry::Trackable
+
+        # Initializes a new ReadModelUpdater
+        #
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance to update read model for
+        def initialize(aggregate)
+          @aggregate = aggregate
+          @read_model = aggregate.read_model if aggregate.class.read_model_enabled?
+          @command_utilities = aggregate.send(:command_utilities)
+          @revision_column = aggregate.send(:revision_column) if aggregate.class.read_model_enabled?
+        end
+
+        # Updates the read model with revision guard protection
+        #
+        # @param event [Yes::Core::Event] The event that was published
+        # @param command_payload [Hash] The command payload
+        # @param command_name [Symbol, String] The command name (optional, will be derived from event if not provided)
+        # @return [void]
+        def call(event, command_payload = nil, command_name = nil, resolve_payload: false)
+          return unless aggregate.class.read_model_enabled?
+
+          begin
+            command_name ||= command_utilities.command_name_from_event(event, aggregate.class)
+          rescue Yes::Core::Utils::CommandUtils::CommandNotFoundError => e
+            Rails.logger.warn("Command not found for event #{event.type}: #{e.message}")
+
+            # update revision only in case event is unknown to aggregate
+            return update_revision(event.stream_revision)
+          end
+
+          payload = command_payload || payload_from_event(event, resolve_payload)
+
+          locale = payload[:locale]
+
+          state_updater_class = command_utilities.fetch_state_updater_class(command_name)
+
+          ReadModelRevisionGuard.call(
+            read_model,
+            event.stream_revision,
+            revision_column:
+          ) do
+            state_changes = state_updater_class.new(
+              payload: payload.except(*Yes::Core::Command::RESERVED_KEYS),
+              aggregate:,
+              event:
+            ).call
+            aggregate.update_read_model(
+              state_changes.merge(
+                revision_column => event.stream_revision,
+                locale:,
+                pending_update_since: nil
+              )
+            )
+          end
+        rescue ReadModelRevisionGuard::RevisionAlreadyAppliedError => e
+          Rails.logger.warn("Read model revision already applied: #{e.message}")
+        end
+
+        otl_trackable(
+          :call,
+          Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Update read model',
+                                                         span_kind: :producer, track_sql: true)
+        )
+
+        private
+
+        attr_reader :aggregate, :read_model, :command_utilities, :revision_column
+
+        def update_revision(revision)
+          aggregate.update_read_model(revision_column => revision)
+        end
+
+        def payload_from_event(event, resolve_payload)
+          return event.data unless resolve_payload
+          return event.data unless event.data.values.any? do |value|
+            next false unless value.is_a?(String)
+
+            value.start_with?(Yes::Core::Event::PAYLOAD_STORE_VALUE_PREFIX)
+          end
+
+          Yes::Core::PayloadStore::Lookup.new.call(event).each do |key, value|
+            event.data[key.to_s] = value
+          end
+
+          event.data
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/state_updater.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Base class for handling custom state updates on command attributes
+      class StateUpdater
+        class << self
+          # @return [Hash] The update state block
+          attr_reader :update_state_block
+          attr_reader :updated_attributes
+
+          # Defines the update state block and analyzes it for attribute updates
+          #
+          # @param custom [Boolean] Skip attribute analysis when true
+          # @yield Block to evaluate for state updates
+          # @yieldreturn [void]
+          # @return [void]
+          def update_state(custom: false, &block)
+            @update_state_block = block
+            @updated_attributes = []
+
+            # Only analyze the block if not in custom mode
+            return if custom
+
+            analyzer = BlockAnalyzer.new
+            analyzer.instance_eval(&block)
+            @updated_attributes = analyzer.updated_attributes
+          end
+        end
+
+        # Helper class to analyze the update_state block at definition time
+        class BlockAnalyzer
+          attr_reader :updated_attributes
+
+          def initialize
+            @updated_attributes = []
+          end
+
+          # @param method_name [Symbol] The method being called
+          # @param args [Array] Method arguments (unused)
+          # @yield Optional block to evaluate for attribute value
+          # @yieldreturn [void]
+          # @return [void]
+          def method_missing(method_name, *_args, &block)
+            @updated_attributes << method_name if block
+          end
+
+          def respond_to_missing?(*, **)
+            true
+          end
+        end
+
+        # @param payload [Hash] The command payload
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance
+        # @param event [Event, nil] The event instance (optional)
+        def initialize(payload:, aggregate:, event: nil)
+          @raw_payload = payload
+          @aggregate = aggregate
+          @event = event
+          @payload = PayloadProxy.new(
+            raw_payload:,
+            context: aggregate.class.context,
+            parent_aggregates: aggregate.class.parent_aggregates
+          )
+        end
+
+        # Evaluates the update state block and returns the updated attributes
+        # If no block is defined, returns the payload attributes except aggregate_id
+        #
+        # @return [Hash] The updated attributes
+        def call
+          if self.class.update_state_block
+            @updates = {}
+            instance_eval(&self.class.update_state_block)
+            @updates
+          else
+            raw_payload.except(:"#{aggregate.class.aggregate.underscore}_id")
+          end
+        end
+
+        private
+
+        attr_reader :raw_payload, :payload, :aggregate, :event
+
+        # Handles method missing to delegate attribute calls to the current aggregate
+        #
+        # @param method_name [Symbol] The method name being called
+        # @yield Optional block to evaluate for the attribute value
+        # @yieldreturn [Object] The value to set for the attribute
+        # @return [Object] The result of calling the method on the current aggregate
+        def method_missing(method_name, *, &block)
+          if block
+            @updates[method_name] = instance_eval(&block)
+          elsif aggregate.respond_to?(method_name)
+            aggregate.public_send(method_name, *, &block)
+          else
+            super
+          end
+        end
+
+        # Checks if method is defined on the current aggregate
+        #
+        # @param method_name [Symbol] The method name to check
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if method exists
+        def respond_to_missing?(method_name, include_private = false)
+          aggregate.respond_to?(method_name, include_private) || super
+        end
+      end
+    end
+  end
+end