yes-core 1.0.0

data/lib/yes/core/commands/bus.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      class Bus
+        include Yes::Core::OpenTelemetry::Trackable
+
+        attr_reader :command_processor, :perform_inline
+        private :command_processor, :perform_inline
+
+        def initialize(
+          command_processor: Processor,
+          perform_inline: Yes::Core.configuration.process_commands_inline
+        )
+          @command_processor = command_processor
+          @perform_inline = perform_inline
+        end
+
+        # Passees commands on to the command processor, in case origin is not provided,
+        # it will be derived from the caller. Also decides based on config whether to perform commands inline or not
+        # @param command_or_commands [Command, Array<Command>] Command(s) instance(s)
+        # @param origin [String] Origin of the command
+        # @param notifier_options [Hash] Options for command notifier
+        # @param batch_id [String] Batch ID
+        # @return [void]
+        def call(
+          command_or_commands,
+          origin: nil,
+          notifier_options: {},
+          batch_id: nil
+        )
+          origin ||= Utils::CallerUtils.origin_from_caller(caller_locations(1..1).first)
+
+          perform_method = perform_inline ? :perform_now : :perform_later
+          self.class.current_span&.add_attributes({ perform_method: perform_method.to_s, origin: }.stringify_keys)
+
+          command_processor.public_send(
+            perform_method, origin, command_or_commands, notifier_options, batch_id, perform_inline
+          )
+        end
+        otl_trackable :call, Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Command Bus Schedule')
+      end
+    end
+  end
+end

data/lib/yes/core/commands/group.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Represents a group of commands executed in a transaction.
+      # Provides DSL for defining which commands belong to the group
+      # and handles payload normalization across contexts and subjects.
+      class Group
+        RESERVED_KEYS = Yes::Core::Command::RESERVED_KEYS
+
+        # Meta attributes for the Group, compatible with the Command class.
+        class Attributes < Dry::Struct
+          class Invalid < Error; end
+
+          attribute? :transaction, Types.Instance(TransactionDetails).optional
+          attribute? :origin, Types::String.optional
+          attribute? :batch_id, Types::String.optional
+          attribute? :metadata, Types::Hash.optional
+          attribute(:command_id, Types::UUID.default { SecureRandom.uuid })
+
+          # @param attributes [Hash] constructor parameters
+          # @raise [Invalid] if the parameters are invalid
+          def self.new(attributes)
+            super
+          rescue Dry::Struct::Error => e
+            raise Invalid.new(extra: attributes), e
+          end
+        end
+
+        class << self
+          # @return [Array<Class>] List of command classes used in this group
+          attr_reader :commands
+
+          # @return [Array<Symbol>] List of unique command contexts
+          def command_contexts
+            commands.map { _1.to_s.split('::')[0].underscore.to_sym }.uniq
+          end
+
+          # @return [Array<Symbol>] List of subjects in the current context
+          def own_context_subjects
+            commands.
+              select { _1.to_s.split('::')[0].underscore.to_sym == own_context }.
+              map { _1.to_s.split('::')[1].underscore.to_sym }.uniq
+          end
+
+          # @return [Symbol] The context of the current command group
+          def own_context
+            to_s.split('::')[0].underscore.to_sym
+          end
+
+          # @return [Symbol] The subject of the current command group
+          def own_subject
+            to_s.split('::')[1].underscore.to_sym
+          end
+
+          # Defines a command for the command group.
+          #
+          # @param command_name [String] the command class name, e.g. 'NameChanged'
+          # @param context [String] the context of the command, defaults to the first module
+          # @param subject [String] the subject of the command, defaults to the second module
+          # @return [void]
+          def command(command_name, context: to_s.split('::')[0], subject: to_s.split('::')[1])
+            @commands ||= []
+            @commands <<
+              Object.const_get(
+                "#{context}::#{subject}::Commands::#{command_name}::Command"
+              )
+          end
+        end
+
+        # @return [Hash] The payload of the command group
+        attr_reader :payload
+
+        # @return [Attributes] The attributes of the command group
+        attr_reader :group_attributes
+
+        # @return [Array<Command>] Command instances of the group's commands
+        attr_reader :commands
+
+        delegate :transaction, :origin, :batch_id, :metadata, :command_id, to: :group_attributes
+
+        # Returns the aggregate ID from the first command in the group.
+        #
+        # @return [String, nil] the aggregate ID
+        def aggregate_id
+          commands.first&.aggregate_id
+        end
+
+        # Initialize a new Group.
+        #
+        # @param params [Hash] Parameters for the command group (meta attributes and command payload)
+        def initialize(params)
+          @group_attributes = Attributes.new(params.slice(*Yes::Core::Command::RESERVED_KEYS))
+          @payload = normalized_payloads(params)
+          @commands = self.class.commands.map do |command|
+            command.new(
+              payload.dig(command.to_s.split('::')[0].underscore.to_sym, command.to_s.split('::')[1].underscore.to_sym)
+            )
+          end
+        end
+
+        # Returns the command group as a hash for serialization.
+        #
+        # @return [Hash] payloads and meta attributes merged
+        def to_h
+          transaction = group_attributes.transaction
+          merged = payload.merge(group_attributes.to_h)
+          transaction ? merged.merge(transaction:) : merged
+        end
+
+        private
+
+        # Normalizes the payloads for the command group.
+        #
+        # @param params [Hash] the input parameters
+        # @return [Hash] the normalized payloads
+        def normalized_payloads(params)
+          params.without(RESERVED_KEYS).each_with_object({}) do |(key, value), norm_payloads|
+            if key.in?(self.class.command_contexts)
+              norm_payloads[key] = value
+            elsif key.in?(self.class.own_context_subjects)
+              norm_payloads[self.class.own_context] ||= {}
+              norm_payloads[self.class.own_context][key] = value
+            else
+              norm_payloads[self.class.own_context] ||= {}
+              norm_payloads[self.class.own_context][self.class.own_subject] ||= {}
+              norm_payloads[self.class.own_context][self.class.own_subject][key] = value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/commands/group_response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      class GroupResponse < Response
+        attribute :cmd, Yes::Core::Types.Instance(Yes::Core::Commands::Group)
+        attribute? :error,
+                   Yes::Core::Types.Instance(Yes::Core::Commands::Stateless::GroupHandler::CommandsError).optional
+      end
+    end
+  end
+end

data/lib/yes/core/commands/helper.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Provides naming resolution helpers for commands following the V2 folder structure
+      # (e.g. Context::Subject::Commands::DoSomething::Command).
+      #
+      # @example
+      #   helper = Yes::Core::Commands::Helper.new(command)
+      #   helper.command_name
+      class Helper
+        AGGREGATE_CLASSNAME = 'Aggregate'
+        VERSION_REGEXP = /::(?<version>V\d+)::/
+
+        attr_reader :inflector, :cmd
+        private :inflector, :cmd
+
+        delegate :splitted_command, to: :class
+
+        class << self
+          # Splits the command class name into module parts.
+          #
+          # @param cmd [Yes::Core::Command] the command instance
+          # @return [Array<String>] the split class name parts
+          def splitted_command(cmd)
+            cmd.class.to_s.split('::')
+          end
+        end
+
+        # @param cmd [Yes::Core::Command] the command instance
+        def initialize(cmd)
+          @inflector = Dry::Inflector.new
+          @cmd = cmd
+        end
+
+        # Returns the top-level context module of the command.
+        #
+        # @return [String] the command context
+        def command_context
+          splitted_command(cmd).first
+        end
+        alias context command_context
+
+        # Returns the locale for the command.
+        #
+        # @return [Symbol] the locale
+        def command_locale
+          cmd.respond_to?(:locale) ? cmd.locale : I18n.locale
+        end
+        alias locale command_locale
+
+        # Extracts the version from the command class name.
+        #
+        # @return [String, nil] the version string (e.g. "V1") or nil
+        def command_version
+          VERSION_REGEXP.match(cmd.class.to_s)&.[](:version)
+        end
+
+        # Returns the event payload with stringified keys.
+        #
+        # @return [Hash] the deep stringified event payload
+        def event_payload
+          cmd.payload.deep_stringify_keys
+        end
+
+        # Returns the underscored command name.
+        #
+        # @return [String] the command name
+        def command_name
+          inflector.underscore(splitted_command(cmd)[-2])
+        end
+
+        # Returns the aggregate class name.
+        #
+        # @return [String] the aggregate class name
+        def aggregate_classname
+          AGGREGATE_CLASSNAME
+        end
+
+        # Returns the aggregate module name.
+        #
+        # @return [String] the aggregate module name
+        def aggregate_module
+          splitted_command(cmd)[-4]
+        end
+        alias subject aggregate_module
+
+        # Returns the fully qualified authorizer class name.
+        #
+        # @return [String] the authorizer class name
+        def authorizer_classname
+          spl = splitted_command(cmd)
+          spl[0] == 'CommandGroups' ? "#{spl[0..1].join('::')}::Authorizer" : "#{spl[0..3].join('::')}::Authorizer"
+        end
+
+        # Returns the fully qualified validator class name.
+        #
+        # @return [String] the validator class name
+        def validator_classname
+          spl = splitted_command(cmd)
+          spl[0] == 'CommandGroups' ? "#{spl[0..1].join('::')}::Validator" : "#{spl[0..3].join('::')}::Validator"
+        end
+
+        # Returns the aggregate class constant.
+        #
+        # @return [Class] the aggregate class
+        def aggregate_class
+          inflector.constantize(
+            [
+              command_context,
+              command_version,
+              aggregate_module,
+              aggregate_classname
+            ].compact.join('::')
+          )
+        end
+
+        # Returns the aggregate ID from the command.
+        #
+        # @return [String] the aggregate ID
+        delegate :aggregate_id, to: :cmd
+      end
+    end
+  end
+end

data/lib/yes/core/commands/notifier.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# @abstract Command notifier base class. Subclass and override notification methods to implement
+# a custom notifier.
+module Yes
+  module Core
+    module Commands
+      class Notifier
+        attr_reader :channel
+        private :channel
+
+        # @param options [Hash] notifier options
+        # @option options [String] :channel the notification channel
+        def initialize(options = {})
+          @channel = options[:channel]
+        end
+
+        # Implement this method to notify that a batch has started processing
+        # @param batch_id [String] batch id of the batch that has started processing
+        # @param transaction [TransactionDetails] the transaction details of the current transaction
+        # @param commands [Array<Command>] the commands that are being processed
+        def notify_batch_started(batch_id, transaction = nil, commands = nil)
+          raise NotImplementedError
+        end
+
+        # Implement this method to notify that a batch has finished processing
+        # @param batch_id [String] batch id of the batch that has finished processing
+        # @param transaction [TransactionDetails] the transaction details of the current transaction
+        # @param responses [Array<Response>] the responses of the commands that were processed
+        def notify_batch_finished(batch_id, transaction = nil, responses = nil)
+          raise NotImplementedError
+        end
+
+        # Implement this method to notify that a command response has been received
+        # @param cmd_response [Yes::Core::Commands::Response] the command response to notify
+        def notify_command_response(cmd_response)
+          raise NotImplementedError
+        end
+
+        # Wraps the given block in a batch notification.
+        # @param batch_id [String] the batch id
+        # @param commands [Array<Command>] the commands being processed in the batch
+        # @param transaction [TransactionDetails] the transaction details of the current transaction
+        # @yield executes commands within the batch notification
+        # @yieldreturn [Array<Response>] responses from the executed commands
+        # @return [Array<Response>] responses from the executed commands
+        def with_batch_notification(batch_id, commands, transaction = nil)
+          notify_batch_started(batch_id, transaction, commands)
+          response = yield
+          notify_batch_finished(batch_id, transaction, response)
+
+          response
+        end
+
+        def self.with_batch_notification(notifiers, batch_id, commands, transaction = nil)
+          notifiers.each { _1.notify_batch_started(batch_id, transaction, commands) }
+          response = yield
+          notifiers.each { _1.notify_batch_finished(batch_id, transaction, response) }
+
+          response
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/commands/processor.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      # Processes commands asynchronously through ActiveJob
+      # @since 0.1.0
+      class Processor < ActiveJob::Base
+        include Yes::Core::OpenTelemetry::Trackable
+
+        queue_as :commands
+
+        # Error raised when a command is not registered with a handler
+        UnregisteredCommand = Class.new(Error)
+
+        # @return [Object] The notifier for command processing events
+        attr_reader :command_notifiers, :custom_batch_id
+        private :command_notifiers, :custom_batch_id
+
+        # Processes the given commands by running them through their respective handlers.
+        # @param origin [String] a string identifying the origin of the commands
+        # @param command_or_commands [Command, Array<Command>] the command or commands to process
+        # @param notifier_options [Hash] options to pass to the command notifier
+        # @param custom_batch_id [String] Custom batch ID
+        # @return [Array<Response>] the responses from the performed commands
+        # @raise [UnregisteredCommand] if any command lacks a handler
+        def perform(origin, command_or_commands, notifier_options, custom_batch_id = nil, inline = false)
+          setup(notifier_options, custom_batch_id, inline)
+          singleton_class.current_span&.add_event('Command Processor Setup Done')
+
+          commands = [*command_or_commands]
+          ensure_guard_evaluators_exist?(commands)
+          singleton_class.current_span&.add_event('Ensured Guard Evaluators Exist')
+
+          commands.map! { |cmd| cmd.class.new(cmd.to_h.merge(origin:, batch_id:)) }
+          singleton_class.current_span&.add_event('Commands Mapped')
+
+          if command_notifiers.any?
+            singleton_class.with_otl_span 'Run Commands With Notifiers' do
+              Notifier.with_batch_notification(command_notifiers, batch_id, commands) do
+                singleton_class.with_otl_span 'Run Commands' do
+                  run_commands(commands)
+                end
+              end
+            end
+          else
+            singleton_class.with_otl_span 'Run Commands' do
+              run_commands(commands)
+            end
+          end
+        end
+        otl_trackable :perform, Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Command Processor Perform')
+
+        private
+
+        # Instantiates the command notifier from the config, using the given options.
+        # @param notifier_options [Hash] the options to pass to the command notifier
+        # @param custom_batch_id [String] Custom batch ID
+        # @param inline [Boolean] whether to process the commands inline
+        # @return [void]
+        def setup(notifier_options, custom_batch_id, inline = false)
+          @command_notifiers = [] if inline
+
+          @command_notifiers ||= Yes::Core.configuration.command_notifier_classes&.map do |notifier_class|
+            notifier_class.new(notifier_options)
+          end || []
+          @custom_batch_id = custom_batch_id
+        end
+
+        # Runs the given commands through their respective aggregates.
+        # @param commands [Array<Command>] the commands to run
+        # @return [Array<Response>] responses from the performed commands
+        def run_commands(commands, _inline = false)
+          commands.map do |cmd|
+            cmd_response = run_command(cmd)
+            command_notifiers.each { _1.notify_command_response(cmd_response) }
+            cmd_response
+          end
+        end
+
+        # Executes a single command on its aggregate
+        # @param cmd [Command] the command to execute
+        # @return [Response] response from executing the command
+        def run_command(cmd)
+          command_helper = Yes::Core::Commands::Helper.new(cmd)
+          draft = draft?(cmd)
+          aggregate = aggregate_class(cmd).new(cmd.aggregate_id, draft:)
+          I18n.with_locale(command_helper.command_locale) do
+            # Pass payload as first argument, guards as option
+            aggregate.public_send(command_helper.command_name, cmd.to_h, guards: !draft)
+          end
+        end
+
+        def draft?(cmd)
+          cmd.metadata&.dig(:draft) || cmd.metadata&.dig(:edit_template_command)
+        end
+
+        # Determines the aggregate class for a given command
+        # @param cmd [Command] The command to find the aggregate class for
+        # @return [Class] The aggregate class that handles this command
+        def aggregate_class(cmd)
+          Yes::Core::Commands::Helper.new(cmd).aggregate_class
+        end
+
+        # Checks if a guard evaluator exists for the given command
+        # @param cmd [Command] The command to check
+        # @return [Boolean] true if a guard evaluator exists
+        # @raise [UnregisteredCommand] if no guard evaluator is found for the command
+        def guard_evaluator_exists?(cmd)
+          command_helper = Yes::Core::Commands::Helper.new(cmd)
+
+          klass = Yes::Core.configuration.guard_evaluator_class(command_helper.command_context,
+                                                                command_helper.subject,
+                                                                command_helper.command_name)
+
+          raise UnregisteredCommand, "Unregistered command: #{cmd.class}" unless klass
+
+          true
+        end
+
+        # Ensures handlers exist for all commands
+        # @param commands [Array<Command>] The commands to check
+        # @return [Boolean] true if handlers exist for all commands
+        # @raise [UnregisteredCommand] if any command lacks a handler
+        def ensure_guard_evaluators_exist?(commands)
+          commands.all? { guard_evaluator_exists?(_1) }
+        end
+
+        # Returns the batch id of the current batch.
+        # @return [String] the batch id
+        def batch_id
+          custom_batch_id || job_id
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/commands/response.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      class Response < Dry::Struct
+        attribute :cmd, Yes::Core::Types.Instance(Command)
+        attribute? :event, Yes::Core::Types.Instance(PgEventstore::Event).optional
+        attribute? :error,
+                   Yes::Core::Types.Instance(Yes::Core::CommandHandling::GuardEvaluator::TransitionError).
+                     optional
+
+        # @return [TransactionDetails, nil] command's transaction info if present
+        #
+        delegate :transaction, :batch_id, :payload, :metadata, to: :cmd
+
+        # @return [Boolean] true in case the command was processed successfully
+        #
+        def success?
+          error.blank?
+        end
+
+        # @return [Hash] error details in case an error occurred
+        #
+        def error_details
+          return {} unless error
+
+          {
+            message: error.message,
+            type: error.message&.underscore&.tr(' ', '_'),
+            extra: (error.extra if error.respond_to?(:extra) && error.extra.present?)
+          }.compact
+        end
+
+        # @return [String] type of the command response
+        #
+        def type
+          success? ? 'command_success' : 'command_error'
+        end
+
+        # @return [Hash] command response as a hash
+        #
+        def to_notification
+          error = success? ? {} : { error_details: }
+          {
+            type:,
+            batch_id:,
+            payload:,
+            metadata:,
+            command: cmd.class.name,
+            id: cmd.command_id,
+            transaction: transaction.to_h
+          }.merge(error)
+        end
+
+        # @return [Hash]
+        def as_json(*)
+          to_notification.as_json
+        end
+      end
+    end
+  end
+end