yes-core 1.0.0

data/lib/yes/core/utils/command_utils.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Handles command and handler class operations for aggregates
+      #
+      # @since 0.1.0
+      # @api private
+      class CommandUtils
+        class CommandNotFoundError < Yes::Core::Error; end
+
+        ASSIGN_COMMAND_PREFIX = 'assign_'
+
+        # @param context [String] The context namespace
+        # @param aggregate [String] The aggregate name
+        # @param aggregate_id [String] The ID of the aggregate
+        def initialize(context:, aggregate:, aggregate_id:)
+          @context = context
+          @aggregate = aggregate
+          @aggregate_id = aggregate_id
+        end
+
+        # Builds a change command instance for the given attribute and payload
+        #
+        # @param attribute [Symbol] The attribute name
+        # @param payload [Hash] The command payload
+        # @return [Yes::Core::Command] The instantiated command
+        # @raise [RuntimeError] If the command class cannot be found
+        def build_attribute_command(attribute, payload)
+          build_command(:"change_#{attribute}", payload)
+        end
+
+        # Builds a command instance for the given command name and payload
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The command payload
+        # @return [Yes::Core::Command] The instantiated command
+        # @raise [RuntimeError] If the command class cannot be found
+        def build_command(command_name, payload)
+          command_class = fetch_class(command_name, :command)
+          command_class.new("#{aggregate.underscore}_id": aggregate_id, **payload)
+        end
+
+        # Fetches the guard evaluator class for a given command name
+        #
+        # @param name [Symbol] The command name
+        # @return [Class] The guard evaluator class
+        # @raise [RuntimeError] If the guard evaluator class cannot be found
+        def fetch_guard_evaluator_class(name)
+          fetch_class(name, :guard_evaluator)
+        end
+
+        # Fetches the state updater class for a given command name
+        #
+        # @param name [Symbol] The command name
+        # @return [Class] The state updater class
+        def fetch_state_updater_class(name)
+          fetch_class(name, :state_updater)
+        end
+
+        # Builds a PgEventstore::Event instance
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The event payload
+        # @param metadata [Hash] Event metadata
+        # @return [PgEventstore::Event] The event instance
+        def build_event(command_name:, payload:, metadata: {})
+          event_class = Yes::Core.configuration.event_classes_for_command(context, aggregate, command_name).first
+          event_class.new(
+            type: "#{context}::#{aggregate_name_with_draft_suffix(aggregate, metadata)}#{event_class.name.demodulize}",
+            data: payload,
+            metadata:
+          )
+        end
+
+        # Builds a PgEventstore::Stream instance
+        #
+        # @param context [String] The context name
+        # @param name [String] The stream name
+        # @param id [String] The stream ID
+        # @return [PgEventstore::Stream] The stream instance
+        def build_stream(context: @context, name: @aggregate, id: @aggregate_id, metadata: {})
+          PgEventstore::Stream.new(
+            context:,
+            stream_name: aggregate_name_with_draft_suffix(name, metadata),
+            stream_id: id
+          )
+        end
+
+        # Gets the current revision of a stream
+        #
+        # @param stream [PgEventstore::Stream] The stream to check
+        # @return [Integer] The current revision
+        def stream_revision(stream)
+          PgEventstore.client.read(
+            stream,
+            options: { direction: 'Backwards', max_count: 1 },
+            middlewares: []
+          ).first&.stream_revision || 0
+        rescue PgEventstore::StreamNotFoundError
+          :no_stream
+        end
+
+        def prepare_assign_command_payload(command_name, payload)
+          return payload unless command_name.to_s.starts_with?(ASSIGN_COMMAND_PREFIX)
+
+          attribute_name = command_name.to_s.split(ASSIGN_COMMAND_PREFIX).last.to_sym
+          name_with_id = :"#{attribute_name}_id"
+          key = payload.key?(attribute_name) ? attribute_name : name_with_id
+
+          return payload unless payload[key].is_a?(Yes::Core::Aggregate)
+
+          payload[name_with_id] = payload.delete(key).id
+          payload
+        end
+
+        # @param event [PgEventstore::Event] The event
+        # @param aggregate_class [Class] The aggregate class
+        # @return [Symbol] The command name
+        # @raise [CommandNotFoundError] If the command is not found
+        def command_name_from_event(event, aggregate_class)
+          event_name = event.type.split('::').last.sub(event.stream.stream_name.sub(/(Draft|EditTemplate)/, ''), '').underscore
+          command = aggregate_class.commands.values.find { _1.event_name.to_s == event_name }
+          raise CommandNotFoundError, "Command not found for event #{event_name}" unless command
+
+          command.name
+        end
+
+        # Prepares the payload for a command
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The command payload
+        # @param aggregate_class [Class] The aggregate class
+        # @return [Hash] The prepared payload
+        def prepare_command_payload(command_name, payload, aggregate_class)
+          return append_locale_param(command_name, payload, aggregate_class) if payload.is_a?(Hash)
+
+          payload_attributes = aggregate_class.commands[command_name].payload_attributes.except(:locale)
+          raise 'Payload attributes must be a Hash with a single key (not including locale key)' if payload_attributes.length > 1
+
+          append_locale_param(command_name, { payload_attributes.keys.first => payload }, aggregate_class)
+        end
+
+        # Prefills default values in the payload if they are not provided
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The command payload
+        # @param aggregate_class [Class] The aggregate class
+        # @return [Hash] The prepared payload
+        def prepare_default_payload(command_name, payload, aggregate_class)
+          return payload unless payload.is_a?(Hash)
+
+          attributes_with_defaults = aggregate_class.commands[command_name].payload_attributes.select do |_key, value|
+            value.is_a?(Hash) && value.key?(:default)
+          end
+
+          return payload unless attributes_with_defaults.any?
+
+          additions = {}
+          attributes_with_defaults.each do |key, value|
+            next if payload.key?(key)
+
+            default = value[:default]
+            additions[key] = default.respond_to?(:call) ? default.call : default
+          end
+          payload.merge(additions)
+        end
+
+        private
+
+        attr_reader :context, :aggregate, :aggregate_id
+
+        # Fetches a class based on the command name and type
+        #
+        # @param command [Symbol] The command name
+        # @param type [Symbol] The type of class to fetch (:command or :guard_evaluator)
+        # @return [Class] The requested class
+        # @raise [RuntimeError] If the requested class cannot be found
+        def fetch_class(command, type)
+          klass = Yes::Core.configuration.aggregate_class(context, aggregate, command, type)
+          raise "#{type.to_s.tr('_', ' ').capitalize} class not found for #{command}" unless klass
+
+          klass
+        end
+
+        # Removes the '_id' suffix from an attribute name
+        #
+        # @param attribute [Symbol, String] The attribute name that might contain an '_id' suffix
+        # @return [String] The attribute name without the '_id' suffix
+        # @example
+        #   command_name(:user_id) # => "user"
+        #   command_name("company_id") # => "company"
+        #   command_name(:name) # => "name"
+        def command_name(attribute)
+          attribute.to_s.sub('_id', '')
+        end
+
+        # Adds locale param to payload if required and not present
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The command payload
+        # @param aggregate_class [Class] The aggregate class
+        # @return [Hash] The prepared payload
+        def append_locale_param(command_name, payload, aggregate_class)
+          return payload if payload.key?(:locale)
+          return payload unless aggregate_class.commands[command_name].payload_attributes.key?(:locale)
+
+          payload.merge(locale: I18n.locale.to_s)
+        end
+
+        # Builds the aggregate name with the draft suffix
+        #
+        # @param aggregate_name [String] The name of the aggregate
+        # @param metadata [Hash] The command metadata
+        # @return [String] The stream name
+        def aggregate_name_with_draft_suffix(aggregate_name, metadata = {})
+          return "#{aggregate_name}Draft" if metadata&.dig(:draft)
+          return "#{aggregate_name}EditTemplate" if metadata&.dig(:edit_template_command)
+
+          aggregate_name
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/error_notifier.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Notifies about errors via a pluggable error reporter.
+      #
+      # By default, errors are logged via Rails.logger. To integrate with an external
+      # error tracking service (e.g. Sentry), configure the error reporter:
+      #
+      #   Yes::Core.configure do |config|
+      #     config.error_reporter = ->(error, context:) { Sentry.capture_exception(error, extra: context) }
+      #   end
+      #
+      # The error_reporter must respond to #call(error, context:).
+      class ErrorNotifier
+        # @param event [PgEventstore::Event]
+        # @return [void]
+        def invalid_event_data(event)
+          msg = 'Event with invalid data found in stream'
+          data = { event: event.to_json }
+
+          logger&.info("#{msg} data: #{data}")
+          capture_message(msg, extra: data)
+        end
+
+        # @param error [Error]
+        # @return [void]
+        def payload_extraction_failed(error)
+          msg = 'Large payload extraction failed'
+
+          logger&.info("#{msg} data: #{error.extra}")
+          capture_message(msg, extra: error.extra)
+        end
+
+        # @param error [Error]
+        # @return [void]
+        def decryption_key_error(error)
+          data = {
+            encryptor_response: error.encryptor_response,
+            event: error.event
+          }
+
+          logger&.info("#{error.message} data: #{data}")
+          capture_message(error.message, extra: data)
+        end
+
+        # @param error [Error]
+        # @return [void]
+        def decryption_error(error)
+          logger&.info("#{error.message} data: #{error.extra}")
+          capture_message(error.message, extra: error.extra)
+        end
+
+        # @param message [String]
+        # @param event [PgEventstore::Event]
+        # @return [void]
+        def event_handler_not_defined(message, event)
+          data = { event: event.to_json }
+
+          logger&.info("#{message} data: #{data}")
+          capture_message(message, extra: data) if ENV['CAPTURE_EVENTSOURCING_ERRORS'] == 'true'
+        end
+
+        # @return [void]
+        def missing_payload_store_client_error
+          msg = 'Missing PayloadStore Client. Please configure it.'
+
+          logger&.info(msg)
+          capture_message(msg)
+        end
+
+        # @param error [Exception]
+        # @param extra [Hash, nil]
+        # @return [void]
+        def notify(error, extra: nil)
+          error_reporter&.call(error, context: extra || {})
+        end
+
+        private
+
+        attr_reader :error_reporter, :logger
+
+        def initialize(logger: Yes::Core.configuration.logger)
+          @error_reporter = Yes::Core.configuration.error_reporter
+          @logger = logger
+        end
+
+        # @param msg [String]
+        # @param options [Hash]
+        # @return [void]
+        def capture_message(msg, options = {})
+          return unless error_reporter
+
+          error = StandardError.new(msg)
+          error_reporter.call(error, context: options.fetch(:extra, {}))
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/event_name_resolver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Resolves event names from command names by converting command verbs to their past tense form
+      # @example
+      #   EventNameResolver.call('ChangeLocation') # => :location_changed
+      #   EventNameResolver.call('AddUser') # => :user_added
+      class EventNameResolver
+        # @return [Hash<String, String>] Mapping of command verbs to their corresponding event (past tense) forms
+        COMMAND_TO_EVENT_VERBS = {
+          'Activate' => 'Activated',
+          'Add' => 'Added',
+          'Approve' => 'Approved',
+          'Archive' => 'Archived',
+          'Assign' => 'Assigned',
+          'Cancel' => 'Cancelled',
+          'Change' => 'Changed',
+          'Close' => 'Closed',
+          'Complete' => 'Completed',
+          'Confirm' => 'Confirmed',
+          'Deactivate' => 'Deactivated',
+          'Delete' => 'Deleted',
+          'Disable' => 'Disabled',
+          'Enable' => 'Enabled',
+          'Fail' => 'Failed',
+          'Open' => 'Opened',
+          'Publish' => 'Published',
+          'Reactivate' => 'Reactivated',
+          'Reject' => 'Rejected',
+          'Remove' => 'Removed',
+          'Reopen' => 'Reopened',
+          'Resolve' => 'Resolved',
+          'Restore' => 'Restored',
+          'Start' => 'Started',
+          'Stop' => 'Stopped',
+          'Submit' => 'Submitted',
+          'Unassign' => 'Unassigned',
+          'Unpublish' => 'Unpublished',
+          'Update' => 'Updated'
+        }.freeze
+
+        # Converts a command name to its corresponding event name
+        # @param command_name [String, Symbol] The name of the command to convert
+        # @return [Symbol, nil] The converted event name as an underscored symbol, or nil if no conversion is possible
+        # @example
+        #   EventNameResolver.call('ChangeLocation') # => :location_changed
+        #   EventNameResolver.call(:add_user) # => :user_added
+        #   EventNameResolver.call('InvalidCommand') # => nil
+        def self.call(command_name)
+          normalized_command_name = command_name.to_s.camelize
+          COMMAND_TO_EVENT_VERBS.each do |command_verb, event_verb|
+            next unless normalized_command_name.start_with?(command_verb)
+
+            # Extract the subject (e.g. "Location" from "ChangeLocation")
+            subject = normalized_command_name.delete_prefix(command_verb)
+            # Return subject + verb (e.g. "LocationChanged")
+            return "#{subject}#{event_verb}".underscore.to_sym
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/exponential_retrier.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Generic exponential backoff retry utility
+      # Provides configurable retry logic with exponential backoff, jitter, and timeout
+      class ExponentialRetrier
+        # Default configuration constants
+        DEFAULT_MAX_RETRIES = 6
+        DEFAULT_BASE_SLEEP_TIME = 0.1
+        DEFAULT_MAX_SLEEP_TIME = 5.0
+        DEFAULT_JITTER_FACTOR = 0.1
+        DEFAULT_TIMEOUT = 30
+
+        # Error raised when retry fails after maximum attempts
+        class RetryFailedError < StandardError; end
+
+        # Error raised when timeout is exceeded
+        class TimeoutError < StandardError; end
+
+        # Configuration for the retrier
+        #
+        # @param max_retries [Integer] Maximum number of retry attempts
+        # @param base_sleep_time [Float] Base sleep time in seconds for exponential backoff
+        # @param max_sleep_time [Float] Maximum sleep time to prevent excessive waiting
+        # @param jitter_factor [Float] Jitter factor for randomizing sleep times
+        # @param timeout [Integer] Maximum time to wait before timing out
+        # @param logger [Object] Logger instance for retry information
+        def initialize(
+          max_retries: DEFAULT_MAX_RETRIES,
+          base_sleep_time: DEFAULT_BASE_SLEEP_TIME,
+          max_sleep_time: DEFAULT_MAX_SLEEP_TIME,
+          jitter_factor: DEFAULT_JITTER_FACTOR,
+          timeout: DEFAULT_TIMEOUT,
+          logger: nil
+        )
+          @max_retries = max_retries
+          @base_sleep_time = base_sleep_time
+          @max_sleep_time = max_sleep_time
+          @jitter_factor = jitter_factor
+          @timeout = timeout
+          @logger = logger || (defined?(Rails) ? Rails.logger : nil)
+          @start_time = Time.current
+        end
+
+        # Executes the retry logic with exponential backoff
+        #
+        # @param condition_check [Proc] Block that returns true when condition is met
+        # @param action [Proc] Block to execute when condition is met
+        # @param failure_message [String] Custom failure message for RetryFailedError
+        # @param timeout_message [String] Custom timeout message for TimeoutError
+        # @yield Alternative to action parameter - block to execute when condition is met
+        # @return [Object] Result of the action/block execution
+        # @raise [RetryFailedError] When condition is not met after maximum retries
+        # @raise [TimeoutError] When timeout is exceeded
+        def call(condition_check:, action: nil, failure_message: nil, timeout_message: nil, &block)
+          action_block = action || block
+          raise ArgumentError, 'Either action parameter or block must be provided' unless action_block
+
+          attempts = 0
+          total_wait_time = 0
+
+          loop do
+            check_timeout!(timeout_message)
+
+            if condition_check.call
+              log_success(attempts, total_wait_time) if attempts.positive?
+              return action_block.call
+            end
+
+            attempts += 1
+            if attempts >= max_retries
+              log_failure(attempts, total_wait_time)
+              raise RetryFailedError, failure_message || default_failure_message(attempts)
+            end
+
+            sleep_time = sleep_with_backoff(attempts)
+            total_wait_time += sleep_time
+          end
+        end
+
+        private
+
+        attr_reader :max_retries, :base_sleep_time, :max_sleep_time, :jitter_factor,
+                    :timeout, :logger, :start_time
+
+        # Checks if the timeout has been exceeded
+        #
+        # @param custom_message [String] Custom timeout message
+        # @raise [TimeoutError] When timeout is exceeded
+        def check_timeout!(custom_message = nil)
+          elapsed_time = Time.current - start_time
+
+          return unless elapsed_time > timeout
+
+          message = custom_message || "Timeout after #{elapsed_time.round(2)}s"
+          raise TimeoutError, message
+        end
+
+        # Sleeps with exponential backoff and jitter
+        #
+        # @param attempt_number [Integer] Current attempt number
+        # @return [Float] The actual sleep time used
+        def sleep_with_backoff(attempt_number)
+          sleep_time = calculate_sleep_time(attempt_number)
+          log_retry(attempt_number, sleep_time)
+          sleep(sleep_time)
+          sleep_time
+        end
+
+        # Calculates sleep time with exponential backoff, jitter, and maximum cap
+        #
+        # @param attempt_number [Integer] Current attempt number
+        # @return [Float] Sleep time in seconds
+        def calculate_sleep_time(attempt_number)
+          # Calculate base exponential backoff
+          base_sleep = base_sleep_time * (2**(attempt_number - 1))
+
+          # Add jitter to prevent thundering herd
+          jitter = base_sleep * jitter_factor * rand(-1.0..1.0)
+          sleep_with_jitter = base_sleep + jitter
+
+          # Cap at maximum sleep time
+          [sleep_with_jitter, max_sleep_time].min
+        end
+
+        # Default failure message when none is provided
+        #
+        # @param attempts [Integer] Number of attempts made
+        # @return [String] Default failure message
+        def default_failure_message(attempts)
+          "Retry failed after #{attempts} attempts"
+        end
+
+        # Logs successful retry after multiple attempts
+        #
+        # @param attempts [Integer] Number of attempts made
+        # @param total_wait_time [Float] Total time spent waiting
+        # @return [void]
+        def log_success(attempts, total_wait_time)
+          return unless logger
+
+          logger.info(
+            "ExponentialRetrier succeeded after #{attempts} attempts " \
+            "(waited #{total_wait_time.round(2)}s)"
+          )
+        end
+
+        # Logs failure after maximum retries
+        #
+        # @param attempts [Integer] Number of attempts made
+        # @param total_wait_time [Float] Total time spent waiting
+        # @return [void]
+        def log_failure(attempts, total_wait_time)
+          return unless logger
+
+          logger.error(
+            "ExponentialRetrier failed after #{attempts} attempts " \
+            "(waited #{total_wait_time.round(2)}s)"
+          )
+        end
+
+        # Logs retry attempt
+        #
+        # @param attempt_number [Integer] Current attempt number
+        # @param sleep_time [Float] Time to sleep before retry
+        # @return [void]
+        def log_retry(attempt_number, sleep_time)
+          return unless logger&.debug?
+
+          logger.debug(
+            "ExponentialRetrier retry #{attempt_number}/#{max_retries}. " \
+            "Sleeping #{sleep_time.round(3)}s"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/utils/hash_utils.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Utils
+      # Utility class for deep hash operations
+      class HashUtils
+        class << self
+          # Returns a deep duplicate of a hash, recursively duplicating nested hashes.
+          #
+          # @param hash [Hash] the hash to deep duplicate
+          # @return [Hash, Object] the deep duplicated hash, or the original object if not a Hash
+          #
+          # @example
+          #   HashUtils.deep_dup({ a: { b: 1 } })
+          #   # => { a: { b: 1 } } (a completely independent copy)
+          def deep_dup(hash)
+            return hash unless hash.instance_of?(Hash)
+
+            dupl = hash.dup
+            dupl.each { |k, v| dupl[k] = v.instance_of?(Hash) ? deep_dup(v) : v }
+            dupl
+          end
+
+          # Returns a hash with the keys flattened
+          #
+          # @param obj [Hash, Array] the object to flatten
+          # @param prefix [String] the key to use as a prefix for the keys in the hash
+          # @param memo [Hash] the hash to store the flattened keys and values
+          # @return [Hash] the flattened hash
+          #
+          # @example
+          #   HashUtils.deep_flatten_hash({ name: 'A', otl_contexts: { root: { attr: 10, available: true } } })
+          #    => {"name"=>"A", "otl_contexts.root.attr"=>10, "otl_contexts.root.available"=>true}
+          def deep_flatten_hash(obj, prefix = nil, memo = {})
+            case obj
+            when Hash
+              obj.each do |key, value|
+                case [key, value]
+                in Hash, Array
+                  memo[deep_flatten_hash(key)] = memo[deep_flatten_hash(value)]
+                in String | Symbol, Hash
+                  deep_flatten_hash(value, prefix ? "#{prefix}.#{key}" : key.to_s, memo)
+                in String | Symbol, Array
+                  memo[key.to_s] = deep_flatten_hash(value)
+                in Array, _
+                  memo[deep_flatten_hash(key)] = deep_flatten_hash(value)
+                else
+                  memo[prefix ? "#{prefix}.#{key}" : key.to_s] = value
+                end
+              end
+              memo
+            when Array
+              obj.map { deep_flatten_hash(_1) }
+            else
+              obj
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    VERSION = '1.0.0'
+  end
+end