yes-core 1.0.0

data/lib/yes/core/commands/stateless/group_handler.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      module Stateless
+        # Handles a group of commands
+        class GroupHandler
+          include HandlerHelpers
+
+          class InvalidCommandGroupError < Error
+            def initialize(cmd_module_name, handler_module_name)
+              super("command #{cmd_module_name} does not match handler #{handler_module_name}")
+            end
+          end
+
+          class CustomHandlerMethodMissingError < Error; end
+          class CommandsError < Error; end
+
+          class << self
+            # @return [Array<Symbol, Class>] List of handlers for the command group
+            attr_reader :handlers
+
+            # @return [Boolean] Always returns true for stateless handlers
+            def stateless?
+              true
+            end
+
+            # Adds a handler to the command group
+            # @param command_or_handler_method_name [Symbol, String] the name of the command class (String) or custom handler method (Symbol)
+            # @param context [Symbol, String] the context of the handler's command, camel or snake case
+            # @param subject [Symbol, String] the subject of the handler's command, camel or snake case
+            # @return [void]
+            def handler(command_or_handler_method_name, context: to_s.split('::')[0],
+                        subject: to_s.split('::')[1])
+              @handlers ||= []
+              @handlers << build_handler(command_or_handler_method_name, context, subject)
+            end
+
+            private
+
+            # Builds a handler class or returns a symbol for the command, representing a custom handler method
+            # @param command_or_handler_name [Symbol, String] the name of the command class (String) or custom handler method (Symbol)
+            # @param context [String] the context of the handler's command
+            # @param subject [String] the subject of the handler's command
+            # @return [Class, Symbol] the handler class or a symbol representing the command
+            def build_handler(command_or_handler_name, context, subject)
+              return command_or_handler_name if command_or_handler_name.is_a?(Symbol)
+
+              Object.const_get(
+                "#{context}::#{subject}::Commands::#{command_or_handler_name}::Handler"
+              )
+            end
+          end
+
+          # @param cmd [Group] the command group to handle
+          # @param events_cache [Hash] already cached events
+          #  { stream => { event_name => event_data } }
+          # @raise [InvalidCommandGroupError] if the command is not valid
+          def initialize(cmd, events_cache: {})
+            raise InvalidCommandGroupError.new(cmd.class.name.deconstantize, self.class.name.deconstantize) unless valid_command?(cmd)
+
+            @cmd = cmd
+            @events_cache = events_cache
+          end
+
+          # Executes the command group
+          # @raise [CommandsError] if any handler errors occur during execution
+          # @return [void]
+          def call
+            errors = []
+
+            PgEventstore.client.multiple do
+              errors.push(*run_command_handlers)
+              errors.push(*run_custom_handlers)
+              raise CommandsError.new(extra: errors), 'Command group failed' if errors.any?
+
+              publish_events
+            end
+          end
+
+          private
+
+          attr_reader :cmd, :events_cache
+
+          # Runs the defined command handlers for each command in the group
+          # @return [Array] updated errors array
+          def run_command_handlers
+            cmd.commands.each_with_object([]) do |command, errors|
+              handler_class(command.class).new(command, publish_events: false).call
+            rescue Handler::InvalidTransition, Handler::NoChangeTransition => e
+              errors << { command: command.class.name, error: e.message, extra: e.extra }
+            end
+          end
+
+          # Runs any custom handlers defined for the command group
+          # @return [Array] updated errors array
+          def run_custom_handlers
+            custom_handlers.each_with_object([]) do |custom_handler, errors|
+              send(custom_handler)
+            rescue NoMethodError
+              raise CustomHandlerMethodMissingError, "Method #{custom_handler} not found"
+            rescue Handler::InvalidTransition, Handler::NoChangeTransition => e
+              errors << { custom_handler:, error: e.message, extra: e.extra }
+            end
+          end
+
+          # Publishes events for all commands in the group
+          # @return [void]
+          def publish_events
+            cmd.commands.each do |command|
+              handler = handler_class(command.class).new(command, revision_check: false)
+              # only run base class call method which publishes events
+              Handler.instance_method(:call).bind_call(handler)
+            end
+          end
+
+          # Checks if the given command is valid for this handler
+          # @param cmd [Group] the command group to validate
+          # @return [Boolean] true if the command is valid, false otherwise
+          def valid_command?(cmd)
+            cmd.is_a?(Group) && cmd.class.name.deconstantize == self.class.name.deconstantize
+          end
+
+          # Gets the handler class for a given command class
+          # @param command_class [Class] the command class
+          # @return [Class] the handler class for the command
+          def handler_class(command_class)
+            handler = handler_for(command_class)
+            default_handlers.find { _1 == handler } || Class.new(Handler) { self.event_name = handler.event_name }
+          end
+
+          # Gets the handler for a given command class
+          # @param command_class [Class] the command class
+          # @return [Class] the handler class for the command
+          def handler_for(command_class)
+            Object.const_get("#{command_class.name.deconstantize}::Handler")
+          end
+
+          # @return [Array<Class>] list of default handlers
+          def default_handlers
+            self.class.handlers.without(custom_handlers)
+          end
+
+          # @return [Array<Symbol>] list of custom handlers
+          def custom_handlers
+            self.class.handlers.select { _1.is_a?(Symbol) }
+          end
+
+          # Raises an InvalidTransition error
+          # @param message [String] the error message
+          # @param extra [Hash] additional error information
+          # @raise [Handler::InvalidTransition] always raised
+          def invalid_transition(message, extra: {})
+            raise Handler::InvalidTransition.new(extra:), message.to_s
+          end
+
+          # Raises a NoChangeTransition error
+          # @param message [String] the error message
+          # @param extra [Hash] additional error information
+          # @raise [Handler::NoChangeTransition] always raised
+          def no_change_transition(message, extra: {})
+            raise Handler::NoChangeTransition.new(extra:), message.to_s
+          end
+
+          # Returns a subject object composed based on the command group handler class
+          # @param context [String] the context of the subject
+          # @param subject [String] the subject of the command group
+          # @param aggregate_id [String] the id of the aggregate
+          # @param stream_prefix [String] the stream prefix of the subject
+          # @return [Yes::Core::Commands::Stateless::Subject] the subject object
+          def subject_data(
+            context: self.class.to_s.split('::')[0],
+            subject: self.class.to_s.split('::')[1],
+            aggregate_id: nil,
+            stream_prefix: nil
+          )
+            Yes::Core::Commands::Stateless::Subject.new(
+              context:, subject:, stream_prefix:, aggregate_id:
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/yes/core/commands/stateless/handler.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Commands
+      module Stateless
+        # Handles stateless commands by publishing events to the event store
+        # without maintaining aggregate state in memory.
+        #
+        # @example
+        #   class MyHandler < Yes::Core::Commands::Stateless::Handler
+        #     self.event_name = 'Created'
+        #   end
+        class Handler
+          include OpenTelemetry::Trackable
+          include HandlerHelpers
+
+          class TransitionError < Error; end
+          class InvalidTransition < TransitionError; end
+          class NoChangeTransition < TransitionError; end
+
+          MISSING_CMDS_MSG = 'Commands missing'
+
+          module RevisionsLoader
+            attr_reader(:revisions, :subject_stream_revision)
+
+            def call
+              transaction.otl_contexts.timestamps[:command_handling_started_at_ms] = (Time.now.utc.to_f * 1000).to_i if transaction&.otl_contexts
+
+              if revision_check
+                @subject_stream_revision = expected_revision(stream) || :no_stream
+                @revisions = load_stream_revisions
+              end
+
+              # Here the business logic is checked
+              super
+            end
+
+            private
+
+            # @return [Hash] { <#PgEventstore::Stream> => expected_revision, ... }
+            def load_stream_revisions
+              revisions = {}
+
+              self.class.streams&.each do |stream_attrs|
+                parts = stream_attrs[:prefix].split('::')
+                stream = PgEventstore::Stream.new(
+                  context: parts[0],
+                  stream_name: parts[1..].join('::'),
+                  stream_id: event_payload[stream_attrs[:subject_key]]
+                )
+                revisions[stream] = expected_revision(stream)
+              end
+
+              revisions
+            end
+          end
+
+          def self.inherited(base)
+            super
+
+            base.prepend(RevisionsLoader)
+          end
+
+          class << self
+            attr_accessor :event_name, :streams
+
+            # @return [Boolean]
+            def stateless?
+              true
+            end
+          end
+
+          attr_reader(:events_cache, :cmd_helper, :cmd, :revision_check, :publish_events)
+          private :events_cache, :cmd_helper, :cmd
+
+          delegate :origin, :batch_id, :transaction, to: :cmd
+          delegate :aggregate_id, :context, :subject, :locale, :event_payload, to: :cmd_helper
+          alias attributes event_payload
+
+          # @param cmd [Yes::Core::Command]
+          # @param events_cache [Hash] already cached events { stream => { event_name => event_data } }
+          # @param revision_check [Boolean] whether to check stream revisions before publishing
+          # @param publish_events [Boolean] whether to actually publish events
+          # @return [Stateless::Handler]
+          def initialize(cmd, events_cache: {}, revision_check: true, publish_events: true)
+            @cmd = cmd
+            @cmd_helper = Commands::Helper.new(cmd)
+            @revision_check = revision_check
+            @publish_events = publish_events
+            @events_cache = events_cache
+          end
+
+          # @return [void]
+          def call
+            return unless publish_events
+
+            publish_event(self.class.event_name)
+          end
+
+          # Publishes a single event to the event store
+          #
+          # @param event_name [String] the name of the event to publish
+          # @return [PgEventstore::Event] the published event
+          def publish_event(event_name)
+            transaction.otl_contexts.publisher = self.class.propagate_context(service_name: true) if transaction&.otl_contexts
+
+            type = event_type(event_name)
+            event_class = events_module.const_get(event_name)
+            event = event_class.new(
+              type:,
+              data: event_payload,
+              metadata: event_metadata
+            )
+            otl_record_event_data(event)
+            verify_revisions! if revision_check
+
+            PgEventstore.client.append_to_stream(
+              stream,
+              event,
+              options: { expected_revision: subject_stream_revision }
+            ).tap { otl_record_response(_1) }
+          end
+          otl_trackable :publish_event, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Publish Event', span_kind: :producer)
+
+          private
+
+          # @return [Module]
+          def events_module
+            "#{context}::#{subject}::Events".constantize
+          end
+
+          # @param event_name [String]
+          # @return [String]
+          def event_type(event_name)
+            "#{context}::#{stream_name(subject)}#{event_name}"
+          end
+
+          # @return [PgEventstore::Stream]
+          def stream
+            PgEventstore::Stream.new(context:, stream_name: stream_name(subject), stream_id: aggregate_id)
+          end
+
+          # @param subject [String]
+          # @return [String]
+          def stream_name(subject)
+            return subject unless cmd.metadata&.dig(:edit_template_command)
+
+            "#{subject}EditTemplate"
+          end
+
+          # @param stream [PgEventstore::Stream]
+          # @return [Integer, nil]
+          def expected_revision(stream = self.stream)
+            PgEventstore.client.read(
+              stream,
+              options: { direction: 'Backwards', max_count: 1 },
+              middlewares: []
+            ).first&.stream_revision || 0
+          rescue PgEventstore::StreamNotFoundError
+            nil
+          end
+
+          # @return [Hash]
+          def event_metadata
+            metadata = { origin:, batch_id: }
+            metadata.merge!(cmd.metadata || {})
+            metadata.merge!(transaction.for_eventstore_metadata) if transaction
+            metadata.deep_transform_keys(&:to_s)
+          end
+
+          # @param message [String]
+          # @param extra [Hash]
+          # @return [InvalidTransition]
+          def invalid_transition(message, extra: {})
+            raise InvalidTransition.new(extra:), message.to_s
+          end
+
+          # @param message [String]
+          # @param extra [Hash]
+          # @return [NoChangeTransition]
+          def no_change_transition(message, extra: {})
+            raise NoChangeTransition.new(extra:), message.to_s
+          end
+
+          # @return [void]
+          # @raise [PgEventstore::WrongExpectedRevisionError]
+          def verify_revisions!
+            revisions.each do |stream, revision|
+              expected = expected_revision(stream)
+              next if revision == expected
+
+              revision_error!(revision || -1, expected || -1, stream)
+            end
+          end
+
+          # @param revision [Integer]
+          # @param expected_revision [Integer]
+          # @param stream [PgEventstore::Stream]
+          def revision_error!(revision, expected_revision, stream)
+            PgEventstore::WrongExpectedRevisionError.new(revision:, expected_revision:, stream:).tap do |error|
+              self.class.current_span&.status = ::OpenTelemetry::Trace::Status.error('Wrong expected revision')
+              self.class.current_span&.add_attributes(
+                {
+                  current_revision: revision,
+                  expected_revision: expected_revision,
+                  stream: stream.to_json
+                }.stringify_keys
+              )
+
+              raise error
+            end
+          end
+
+          # @param context [String]
+          # @param subject [String]
+          # @param aggregate_id [String]
+          # @param stream_prefix [String, nil]
+          # @return [Yes::Core::Commands::Stateless::Subject]
+          def subject_data(
+            context: self.class.to_s.split('::')[0],
+            subject: self.class.to_s.split('::')[1],
+            aggregate_id: self.aggregate_id,
+            stream_prefix: nil
+          )
+            Yes::Core::Commands::Stateless::Subject.new(context:, subject:, stream_prefix:, aggregate_id:)
+          end
+
+          # @param command [String]
+          # @param context [String]
+          # @param subject [String]
+          # @return [Data]
+          def command_data(
+            command:,
+            context: self.class.to_s.split('::')[0],
+            subject: self.class.to_s.split('::')[1]
+          )
+            Data.define(:context, :subject, :command).new(context:, subject:, command:)
+          end
+
+          # @return [Yes::Core::Stateless::MissingCommandsAggregator]
+          def result_aggregator
+            @result_aggregator ||= Yes::Core::Stateless::MissingCommandsAggregator.new
+          end
+
+          # @param event [PgEventstore::Event]
+          # @return [void]
+          def otl_record_event_data(event)
+            self.class.current_span&.add_attributes(
+              {
+                'event.type' => event.type,
+                'event.data' => event.data.to_json,
+                'event.metadata' => event.metadata.to_json
+              }
+            )
+          end
+
+          # @param result [PgEventstore::Event]
+          # @return [void]
+          def otl_record_response(result)
+            if ENV['STATSD_ADDR'].present? && defined?(StatsD)
+              StatsD.increment(
+                'events_processing_total',
+                tags: {
+                  service: Rails.application.class.module_parent.name,
+                  source: "#{Rails.application.class.module_parent.name}-#{result.type}",
+                  target: "#{Rails.application.class.module_parent.name}-#{result.type}",
+                  type: 'producer',
+                  event: result.type
+                }
+              )
+            end
+
+            self.class.current_span&.status = ::OpenTelemetry::Trace::Status.ok
+            self.class.current_span&.add_event(
+              'Event Published to PgEventstore',
+              timestamp: result.created_at,
+              attributes: {
+                'event.type' => result.type,
+                'event.link_id' => result.link_id || '',
+                'global_position' => result.global_position,
+                'stream' => result.stream.to_json,
+                'stream.revision' => result.stream_revision,
+                'timestamp_ms' => (result.created_at.to_f * 1000).to_i
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end