yes-core 1.0.0

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Handles publishing events with revision checks
+      class EventPublisher
+        include Yes::Core::OpenTelemetry::Trackable
+
+        # Value object containing aggregate data needed for event publication
+        AggregateEventPublicationData = Struct.new(:id, :context, :name, :revision, keyword_init: true) do
+          def self.from_aggregate(aggregate)
+            new(
+              id: aggregate.id,
+              context: aggregate.class.context,
+              name: aggregate.class.name.split('::')[1],
+              revision: lambda {
+                if aggregate.class.read_model_enabled?
+                  aggregate.reload.revision
+                else
+                  # When read models are disabled, get revision directly from event stream
+                  begin
+                    latest = aggregate.latest_event
+                    latest ? latest.stream_revision : -1
+                  rescue PgEventstore::StreamNotFoundError
+                    # Stream doesn't exist yet - this is the first event
+                    -1
+                  end
+                end
+              }
+            )
+          end
+        end
+
+        # @param command [Object] The command instance
+        # @param aggregate_data [AggregateEventPublicationData] The aggregate publication data
+        # @param accessed_external_aggregates [Array<Hash>] List of accessed external aggregates with their revisions
+        # @param event_name [String, nil] Optional explicit event name to use
+        def initialize(command:, aggregate_data:, accessed_external_aggregates:, event_name: nil)
+          @command = command
+          @aggregate_data = aggregate_data
+          @accessed_external_aggregates = accessed_external_aggregates
+          @event_name = event_name
+          @command_utilities = Utils::CommandUtils.new(
+            context: aggregate_data.context,
+            aggregate: aggregate_data.name,
+            aggregate_id: aggregate_data.id
+          )
+        end
+
+        # Publishes the event after verifying revisions
+        #
+        # @return [PgEventstore::Event] The published event
+        # @raise [PgEventstore::WrongExpectedRevisionError] When revisions don't match
+        def call
+          verify_external_revisions!
+          publish_event
+        end
+
+        otl_trackable(
+          :call,
+          Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Publish Event', span_kind: :producer, track_sql: true)
+        )
+
+        private
+
+        # @return [Object] The command instance
+        attr_reader :command
+        # @return [AggregateEventPublicationData] The aggregate publication data
+        attr_reader :aggregate_data
+        # @return [Array<Hash>] List of accessed external aggregates with their revisions
+        attr_reader :accessed_external_aggregates
+        # @return [String, nil] The explicit event name to use
+        attr_reader :event_name
+        # @return [CommandUtils] The command utilities instance
+        attr_reader :command_utilities
+
+        delegate :payload, :origin, :batch_id, :metadata, to: :command
+
+        # Publishes the event to the event store
+        #
+        # @return [PgEventstore::Event] The published event
+        def publish_event
+          revision = aggregate_data.revision.call
+          expected_revision = revision == -1 ? :no_stream : revision
+
+          event = event_with_metadata
+          otl_record_event_data(event)
+
+          PgEventstore.client.append_to_stream(
+            command_utilities.build_stream(metadata:),
+            event,
+            options: { expected_revision: }
+          ).tap { otl_record_response(_1) }
+        end
+
+        # Verifies revisions of all accessed external aggregates
+        #
+        # @return [void]
+        # @raise [PgEventstore::WrongExpectedRevisionError] When revisions don't match
+        def verify_external_revisions!
+          accessed_external_aggregates.each do |aggregate_data|
+            stream = command_utilities.build_stream(
+              context: aggregate_data[:context],
+              name: aggregate_data[:name],
+              id: aggregate_data[:id]
+            )
+            expected_revision = command_utilities.stream_revision(stream)
+            aggregate_revision = aggregate_data[:revision].call
+            normalized_revision = aggregate_revision == -1 ? :no_stream : aggregate_revision
+
+            next if normalized_revision == expected_revision
+
+            raise PgEventstore::WrongExpectedRevisionError.new(
+              revision: aggregate_revision,
+              expected_revision:,
+              stream:
+            )
+          end
+        end
+
+        # Builds an event with metadata from the command
+        #
+        # @return [PgEventstore::Event] The event with metadata
+        def event_with_metadata
+          command_utilities.build_event(
+            command_name: command.class.name.split('::')[-2].underscore.to_sym,
+            payload:,
+            metadata: event_metadata
+          )
+        end
+
+        # Builds the event metadata
+        #
+        # @return [Hash] The event metadata
+        def event_metadata
+          meta = {}
+          meta['origin'] = origin if origin.present?
+          meta['batch_id'] = batch_id if batch_id.present?
+          meta['yes-dsl'] = true
+          meta.merge!(metadata) if metadata.present?
+
+          meta[:otl_contexts][:publisher] = self.class.propagate_context(service_name: true) if meta[:otl_contexts].present?
+
+          meta
+        end
+
+        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
+
+        def otl_record_response(result)
+          if ENV['STATSD_ADDR'].present?
+            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

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

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Base class for evaluating guards on command attributes
+      class GuardEvaluator
+        class TransitionError < Yes::Core::Error; end
+        class InvalidTransition < TransitionError; end
+        class NoChangeTransition < TransitionError; end
+
+        class << self
+          # @return [Hash<Symbol, Proc>] Hash of registered guards with names as keys and blocks as values
+          def guards
+            @guards ||= {}
+          end
+
+          # Defines a new guard with a name and evaluation block
+          #
+          # @param name [Symbol] Name of the guard
+          # @param error_extra [Hash, Proc] The extra information to be added to the error message payload
+          # @yield Block to evaluate the guard condition
+          # @yieldreturn [Boolean] True if the guard passes, false otherwise
+          # @return [void]
+          def guard(name, error_extra: {}, &block)
+            guards[name] = { block:, error_extra: }
+          end
+        end
+
+        # @param payload [Hash] The command payload
+        # @param metadata [Hash] The command metadata
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance
+        # @param command_name [Symbol] The command name
+        def initialize(payload:, metadata:, aggregate:, command_name:)
+          @raw_payload = payload
+          @raw_metadata = metadata
+          @aggregate = aggregate
+          @aggregate_tracker = AggregateTracker.new
+          @command_name = command_name
+          @payload = PayloadProxy.new(
+            raw_payload:,
+            raw_metadata:,
+            context: aggregate.class.context,
+            aggregate_tracker:,
+            parent_aggregates: aggregate.class.parent_aggregates
+          )
+        end
+
+        # Evaluates all registered guards
+        #
+        # @return [void]
+        # @raise [InvalidTransition] When a guard fails with an invalid transition
+        # @raise [NoChangeTransition] When a guard fails with a no change transition
+        def call
+          self.class.guards.each do |name, guard_data|
+            evaluate_guard(name, error_extra: guard_data[:error_extra], block: guard_data[:block])
+          end
+        end
+
+        # @return [Array<Hash>] List of accessed external aggregates with their revisions
+        delegate :accessed_external_aggregates, to: :aggregate_tracker
+
+        private
+
+        attr_reader :raw_payload, :raw_metadata, :payload, :aggregate, :aggregate_tracker, :command_name
+
+        # Evaluates a single guard and raises appropriate error if it fails
+        #
+        # @param name [Symbol] The name of the guard
+        # @param error_extra [Hash, Proc] The extra information to be added to the error message payload
+        # @param block [Proc] The guard block to evaluate
+        # @return [void]
+        # @raise [InvalidTransition] When the guard fails with an invalid transition
+        # @raise [NoChangeTransition] When the guard fails with a no change transition
+        def evaluate_guard(name, block:, error_extra: {})
+          result = evaluate_with_locale(&block)
+          return if result
+
+          extra = error_extra.respond_to?(:call) ? evaluate_with_locale(&error_extra) : error_extra
+
+          error_class = name == :no_change ? NoChangeTransition : InvalidTransition
+          raise error_class.new(error_message(name), extra:)
+        end
+
+        def value_changed?(val1, val2)
+          return val1 != val2 unless val1.is_a?(Hash) && val2.is_a?(Hash)
+
+          val1.with_indifferent_access != val2.with_indifferent_access
+        end
+
+        # Looks up the error message for a guard from I18n translations
+        #
+        # @param guard_name [Symbol] The name of the guard
+        # @return [String] The error message
+        def error_message(guard_name)
+          context_name = aggregate.class.context
+          aggregate_name = aggregate.class.aggregate
+
+          Yes::Core::ErrorMessages.guard_error(context_name, aggregate_name, command_name.to_s, guard_name)
+        end
+
+        # Handles method missing to delegate attribute calls to the current aggregate
+        #
+        # @param method_name [Symbol] The method name being called
+        # @yield Optional block passed to the method (unused)
+        # @yieldreturn [void]
+        # @return [Object] The result of calling the method on the current aggregate
+        def method_missing(method_name, *, &)
+          if aggregate.respond_to?(method_name)
+            result = aggregate.public_send(method_name, *, &)
+            track_external_aggregate(method_name, result) if aggregate_attribute?(method_name)
+            result
+          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
+
+        # Checks if the given method is an aggregate attribute
+        #
+        # @param method_name [Symbol] The method name to check
+        # @return [Boolean] True if the method is an aggregate attribute
+        def aggregate_attribute?(method_name)
+          aggregate.class.attributes[method_name] == :aggregate
+        end
+
+        # Tracks an external aggregate access
+        #
+        # @param attribute_name [Symbol] The attribute name
+        # @param instance [Object] The aggregate instance
+        # @return [void]
+        def track_external_aggregate(attribute_name, instance)
+          return unless instance
+
+          aggregate_tracker.track(
+            attribute_name: attribute_name.to_s.camelize,
+            id: instance.id,
+            revision: -> { instance.reload.revision },
+            context: aggregate.class.context
+          )
+        end
+
+        # Evaluates a block with the locale from payload if present
+        #
+        # @yield Block to be evaluated
+        # @return [Object] Result of block evaluation
+        def evaluate_with_locale(&block)
+          if raw_payload[:locale].present?
+            I18n.with_locale(raw_payload[:locale]) { instance_eval(&block) }
+          else
+            instance_eval(&block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Evaluates guards for commands and manages command-specific errors on aggregates
+      # Handles the decision of whether to skip guards and properly sets/clears error states
+      #
+      # @example
+      #   runner = GuardRunner.new(aggregate)
+      #   evaluator = runner.call(cmd, command_name, guard_evaluator_class, skip_guards: false)
+      #
+      class GuardRunner
+        include Yes::Core::OpenTelemetry::Trackable
+
+        # Initializes a new GuardRunner
+        #
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance for error management
+        def initialize(aggregate)
+          @aggregate = aggregate
+        end
+
+        # Evaluates guards for the command
+        #
+        # @param cmd [Yes::Core::Command] The command to be handled
+        # @param command_name [Symbol] The name of the command being executed
+        # @param guard_evaluator_class [Class] The guard evaluator class
+        # @param skip_guards [Boolean] Whether to skip guard evaluation
+        # @return [GuardEvaluator, nil] The guard evaluator instance or nil if guards skipped
+        # @raise [GuardEvaluator::InvalidTransition] When the transition is invalid
+        # @raise [GuardEvaluator::NoChangeTransition] When no change would occur
+        # @raise [Yes::Core::Command::Invalid] When the command is invalid
+        def call(cmd, command_name, guard_evaluator_class, skip_guards:)
+          if skip_guards
+            clear_command_error(command_name)
+            return nil
+          end
+
+          evaluator = guard_evaluator_class.new(
+            payload: cmd.payload,
+            metadata: cmd.metadata,
+            aggregate: aggregate,
+            command_name: command_name
+          )
+          evaluator.call
+
+          clear_command_error(command_name)
+
+          evaluator
+        rescue GuardEvaluator::InvalidTransition,
+               GuardEvaluator::NoChangeTransition,
+               Yes::Core::Command::Invalid => e
+          aggregate.send(:"#{command_name.to_s.underscore}_error=", e.message)
+          raise e
+        end
+
+        otl_trackable(
+          :call,
+          Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Evaluate guards')
+        )
+
+        private
+
+        attr_reader :aggregate
+
+        # Clears command-specific error on aggregate
+        #
+        # @param command_name [Symbol, String] The command name
+        # @return [void]
+        def clear_command_error(command_name)
+          aggregate.send(:"#{command_name.to_s.underscore}_error=", nil)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Provides proxy access to command payload with dynamic aggregate resolution
+      class PayloadProxy
+        # @param raw_payload [Hash] The raw command payload
+        # @param raw_metadata [Hash, nil] The raw command metadata (optional)
+        # @param context [String] The context name
+        # @param aggregate_tracker [AggregateTracker, nil] The tracker instance (optional)
+        def initialize(raw_payload:, context:, parent_aggregates:, raw_metadata: nil, aggregate_tracker: nil)
+          @raw_payload = raw_payload
+          @raw_metadata = raw_metadata
+          @context = context
+          @parent_aggregates = parent_aggregates
+          @aggregate_tracker = aggregate_tracker
+        end
+
+        # Access payload values by key
+        #
+        # @param key [Symbol, String] The key to access
+        # @return [Object] The value for the given key
+        delegate :[], to: :@raw_payload
+
+        # Access metadata through a proxy object
+        #
+        # @return [MetadataProxy] The metadata proxy object
+        def metadata
+          @metadata ||= MetadataProxy.new(@raw_metadata)
+        end
+
+        private
+
+        attr_reader :raw_payload, :raw_metadata, :context, :parent_aggregates, :aggregate_tracker
+
+        # Handles dynamic method calls to access payload values or resolve aggregates
+        #
+        # @param method_name [Symbol] The method being called
+        # @param args [Array] Method arguments (unused)
+        # @yield Optional block passed to the method (unused)
+        # @yieldreturn [void]
+        # @return [Object] The payload value or resolved aggregate
+        def method_missing(method_name, *args, &)
+          if raw_payload.key?(method_name)
+            raw_payload[method_name]
+          elsif raw_payload.key?(:"#{method_name}_id")
+            resolve_aggregate(method_name)
+          else
+            super
+          end
+        end
+
+        # Checks if method can be handled
+        #
+        # @param method_name [Symbol] The method to check
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if method can be handled
+        def respond_to_missing?(method_name, include_private = false)
+          raw_payload.key?(method_name) ||
+            raw_payload.key?(:"#{method_name}_id") ||
+            super
+        end
+
+        # Resolves an aggregate instance from its ID in the payload
+        #
+        # @param method_name [Symbol] The method name representing the aggregate
+        # @return [Object] The resolved aggregate instance
+        def resolve_aggregate(method_name)
+          id = raw_payload[:"#{method_name}_id"]
+          context = aggregate_context(method_name)
+          aggregate_class = "#{context}::#{method_name.to_s.camelize}::Aggregate".constantize
+          instance = aggregate_class.new(id)
+
+          aggregate_tracker&.track(
+            attribute_name: method_name,
+            id: instance.id,
+            revision: -> { instance.reload.revision },
+            context:
+          )
+
+          instance
+        end
+
+        def aggregate_context(aggregate_name)
+          parent_aggregates.with_indifferent_access.dig(aggregate_name, :context) || context
+        end
+      end
+
+      # Provides proxy access to command metadata
+      class MetadataProxy
+        # @param raw_metadata [Hash] The raw command metadata
+        def initialize(raw_metadata)
+          @raw_metadata = raw_metadata || {}
+        end
+
+        # Access metadata values by key (hash-style access)
+        #
+        # @param key [Symbol, String] The key to access
+        # @return [Object] The value for the given key
+        delegate :[], to: :raw_metadata
+
+        # Set metadata values by key (hash-style assignment)
+        #
+        # @param key [Symbol, String] The key to set
+        # @param value [Object] The value to set
+        # @return [Object] The value that was set
+        delegate :[]=, to: :raw_metadata
+
+        private
+
+        attr_reader :raw_metadata
+
+        # Handles dynamic method calls to access or set metadata values
+        #
+        # @param method_name [Symbol] The method being called
+        # @param args [Array] Method arguments
+        # @yield Optional block passed to the method (unused)
+        # @yieldreturn [void]
+        # @return [Object] The metadata value or the value being set
+        def method_missing(method_name, *args, &)
+          method_str = method_name.to_s
+
+          # Handle setter methods (e.g., xyz=)
+          if method_str.end_with?('=')
+            key = method_str.chomp('=').to_sym
+            raw_metadata[key] = args.first
+          # Handle getter methods
+          elsif args.empty?
+            if raw_metadata.key?(method_name)
+              raw_metadata[method_name]
+            elsif raw_metadata.key?(method_str)
+              raw_metadata[method_str]
+            end
+          else
+            super
+          end
+        end
+
+        # Checks if method can be handled
+        #
+        # @param method_name [Symbol] The method to check
+        # @param include_private [Boolean] Whether to include private methods
+        # @return [Boolean] True if method can be handled
+        def respond_to_missing?(method_name, include_private = false)
+          method_str = method_name.to_s
+
+          # Respond to setter methods
+          return true if method_str.end_with?('=')
+
+          # Respond to getter methods
+          raw_metadata.key?(method_name) ||
+            raw_metadata.key?(method_str) ||
+            super
+        end
+      end
+    end
+  end
+end