yes-core 1.0.0

data/lib/yes/core/authorization/read_models_authorizer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # Authorizes a collection of read model records by delegating to per-record authorizers.
+      class ReadModelsAuthorizer
+        NotAuthorized = Class.new(Yes::Core::Error)
+
+        class << self
+          # @param read_model_name [String] name of the read model
+          # @param records [Array<ApplicationRecord>] records to authorize
+          # @param auth_data [Hash] authorization data
+          # @raise [NotAuthorized] if any records are not authorized
+          def call(read_model_name, records, auth_data)
+            authorizer = authorizer_for(read_model_name)
+
+            return unless authorizer
+
+            unauthorized = []
+            records.each do |record|
+              authorizer.call(record, auth_data)
+            rescue ReadModelAuthorizer::NotAuthorized => e
+              unauthorized << {
+                message: e.message,
+                model_type: record.class.to_s,
+                model_id: record.id
+              }
+            end
+
+            raise NotAuthorized.new(extra: unauthorized) if unauthorized.any?
+          end
+
+          private
+
+          # @param read_model_name [String] name of the read model
+          # @return [Yes::Core::Authorization::ReadModelAuthorizer, nil] authorizer for read model if existing
+          def authorizer_for(read_model_name)
+            class_name = "ReadModels::#{read_model_name.classify}::Authorizer"
+
+            Kernel.const_get(class_name)
+          rescue NameError
+            nil # defining a per record authorizer is optional
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/authorization/read_request_authorizer.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # @abstract Read request authorizer base class. Subclass and override call method to implement
+      # a custom authorizer.
+      class ReadRequestAuthorizer
+        NotAuthorized = Class.new(Yes::Core::Error)
+
+        class << self
+          # Implement this method to authorize a read request.
+          # Needs to return true if read request is authorized, otherwise raise NotAuthorized.
+          # @param params [Hash] request params to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if read request is authorized raises NotAuthorized otherwise
+          def call(_params, _auth_data)
+            raise NotAuthorized
+          end
+
+          private
+
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if user is a super admin
+          def super_admin?(auth_data)
+            Yes::Core.configuration.super_admin_check.call(auth_data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/authorization/read_request_cerbos_authorizer.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # @abstract Read request Cerbos authorizer base class. Subclass and override call method to implement
+      # a custom authorizer.
+      class ReadRequestCerbosAuthorizer < Yes::Core::Authorization::ReadRequestAuthorizer
+        class << self
+          include OpenTelemetry::Trackable
+          include CerbosClientProvider
+
+          # Implement this method to authorize a read request.
+          # Needs to return true if read request is authorized, otherwise raise NotAuthorized.
+          # @param params [Hash] request params to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if read request is authorized raises NotAuthorized otherwise
+          # @raise [NotAuthorized] if read request is not authorized
+          def call(params, auth_data)
+            singleton_class.current_span&.add_attributes(
+              { params: params.to_json, auth_data: auth_data.to_json }.stringify_keys
+            )
+            auth_data = auth_data.with_indifferent_access
+
+            check_authorization_data(params) unless super_admin?(auth_data)
+
+            decision = authorize(params, auth_data)
+            singleton_class.current_span&.add_event('Cerbos Decision', attributes: { 'decision' => decision.to_json })
+            return true if decision.allow_all?
+
+            raise_unauthorized_error!(params, decision)
+          end
+          otl_trackable :call, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Cerbos Authorize Read Request')
+
+          private
+
+          # @param params [Hash]
+          # @param decision [Cerbos::Decision] decision from Cerbos
+          # raise [NotAuthorized]
+          def raise_unauthorized_error!(params, decision)
+            msg = "You don't have access to these #{params[:model]}"
+            singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error(msg)
+
+            raise self::NotAuthorized.new(msg, extra: { decision: decision.outputs.map(&:value) })
+          end
+
+          # @param params [Hash] request params to authorize
+          # @return [Boolean] true if user is a super admin
+          # @raise [NotAuthorized]
+          def check_authorization_data(_params)
+            raise NotImplementedError, 'You need to implement check_authorization_data'
+          end
+
+          def authorize(...)
+            cerbos_client.check_resource(**cerbos_payload(...))
+          end
+
+          # @param params [Hash] request params to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Hash] payload for Cerbos check_resource
+          def cerbos_payload(params, auth_data)
+            {
+              principal: principal_data(auth_data),
+              resource: resource_data(params),
+              actions: actions(params),
+              include_metadata: Yes::Core.configuration.cerbos_read_authorizer_include_metadata
+            }.deep_symbolize_keys.tap { singleton_class.current_span&.set_attribute('cerbos_payload', _1.to_json) }
+          end
+
+          # @param params [Hash] request params to authorize
+          # @return [Hash] resource data for Cerbos check_resource
+          def resource_data(params)
+            {
+              scope:,
+              kind: params[:model],
+              id: resource_id(params),
+              attributes: resource_attributes(params)
+            }
+          end
+
+          # @param params [Hash]
+          # @return [Hash]
+          def resource_attributes(_params)
+            {}
+          end
+
+          # @param auth_data [Hash] authorization data
+          # @return [Hash] principal data for Cerbos check_resource
+          def principal_data(auth_data)
+            Yes::Core.configuration.cerbos_read_principal_data_builder.call(auth_data)
+          end
+
+          # @return [String] scope for Cerbos check_resource
+          def scope
+            Rails.application.class.module_parent_name.underscore
+          end
+
+          # @param params [Hash] request params to authorize
+          def actions(_params)
+            Yes::Core.configuration.cerbos_read_authorizer_actions
+          end
+
+          # @param params [Hash] request params to authorize
+          # @return [String] resource id for Cerbos check_resource
+          def resource_id(params)
+            "#{Yes::Core.configuration.cerbos_read_authorizer_resource_id_prefix}#{params[:model]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # Base command class for all commands in the system.
+    # Inherits from Dry::Struct for type-safe attribute definitions.
+    class Command < Dry::Struct
+      # Raised when a command fails validation
+      class Invalid < Error; end
+
+      RESERVED_KEYS = %i[transaction origin batch_id command_id metadata es_encrypted].freeze
+
+      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
+
+      # Returns the command payload excluding reserved keys.
+      #
+      # @return [Hash] command payload as a hash
+      def payload
+        to_h.except(*RESERVED_KEYS)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Tracks external aggregate access during command handling
+      class AggregateTracker
+        # @return [Array<Hash>] List of accessed external aggregates with their revisions
+        attr_reader :accessed_external_aggregates
+
+        def initialize
+          @accessed_external_aggregates = []
+        end
+
+        # Tracks an external aggregate access
+        #
+        # @param attribute_name [Symbol] The attribute name
+        # @param id [String] The aggregate ID
+        # @param revision [Integer] The aggregate revision
+        # @param context [String] The context name
+        # @return [void]
+        def track(attribute_name:, id:, revision:, context:)
+          accessed_external_aggregates << {
+            id:,
+            context:,
+            name: attribute_name.to_s.camelize,
+            revision:
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Raised when multiple processes attempt to update the same aggregate concurrently
+      # This error is thrown when the pending_update_since mechanism detects a conflict
+      class ConcurrentUpdateError < Yes::Core::Error
+        # Initializes a new ConcurrentUpdateError
+        #
+        # @param aggregate_class [Class] The aggregate class
+        # @param aggregate_id [String] The ID of the aggregate being updated
+        # @param original_error [Exception] The underlying database error
+        def initialize(aggregate_class:, aggregate_id:, original_error: nil)
+          message = build_error_message(aggregate_class, aggregate_id, original_error)
+
+          super(message, extra: {
+            aggregate_class: aggregate_class.name,
+            aggregate_id: aggregate_id,
+            context: aggregate_class.context,
+            stream_name: aggregate_class.aggregate,
+            original_error: original_error&.message
+          })
+        end
+
+        private
+
+        # Builds the error message
+        #
+        # @param aggregate_class [Class] The aggregate class
+        # @param aggregate_id [String] The aggregate ID
+        # @param original_error [Exception, nil] The underlying error if any
+        # @return [String] The formatted error message
+        def build_error_message(aggregate_class, aggregate_id, original_error)
+          context = aggregate_class.context
+          stream_name = aggregate_class.aggregate
+
+          base_message = "Concurrent update detected for #{context}::#{stream_name} with ID #{aggregate_id}. " \
+                         'Another process is currently updating this aggregate.'
+
+          if original_error
+            "#{base_message} Original error: #{original_error.message}"
+          else
+            base_message
+          end
+        end
+      end
+
+      # Executes commands with retry logic and pending state management
+      # Handles the core command execution including guard evaluation, event publishing,
+      # and error handling with optimistic concurrency control
+      #
+      # @example
+      #   executor = CommandExecutor.new(aggregate)
+      #   response = executor.call(command, guard_evaluator_class)
+      #
+      class CommandExecutor
+        MAX_RETRIES = 10
+        INLINE_RECOVERY_RETRY_THRESHOLD = 5
+
+        # Initializes a new CommandExecutor
+        #
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance to execute commands for
+        def initialize(aggregate)
+          @aggregate = aggregate
+          @read_model = aggregate.read_model if aggregate.class.read_model_enabled?
+        end
+
+        # Executes a command with retry logic and error handling
+        #
+        # @param cmd [Yes::Core::Command] The command to execute
+        # @param command_name [Symbol] The name of the command being executed
+        # @param guard_evaluator_class [Class] The guard evaluator class to process the command
+        # @param skip_guards [Boolean] Whether to skip guard evaluation (default: false)
+        # @return [Yes::Core::Commands::Response] The command response
+        def call(cmd, command_name, guard_evaluator_class, skip_guards: false)
+          retries = 0
+
+          begin
+            evaluator = GuardRunner.new(aggregate).call(cmd, command_name, guard_evaluator_class, skip_guards:)
+
+            set_pending_update_state if aggregate.class.read_model_enabled?
+
+            begin
+              event = EventPublisher.new(
+                command: cmd,
+                aggregate_data: EventPublisher::AggregateEventPublicationData.from_aggregate(aggregate),
+                accessed_external_aggregates: evaluator&.accessed_external_aggregates || []
+              ).call
+            rescue StandardError => e
+              clear_pending_update_state if aggregate.class.read_model_enabled?
+              raise e
+            end
+
+            command_response_class(cmd).new(cmd:, event:)
+          rescue PgEventstore::WrongExpectedRevisionError => e
+            retries += 1
+            clear_pending_update_state if aggregate.class.read_model_enabled?
+
+            retries <= MAX_RETRIES ? retry : raise(e)
+          rescue ConcurrentUpdateError => e
+            retries += 1
+            # Don't clear pending state - another process owns it
+            # Sleep with exponential backoff to give the other process time to finish
+            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+
+            # After several retries, check if pending state is stuck and attempt recovery
+            # This prevents infinite retry loops when a process crashes leaving the flag set
+            if aggregate.class.read_model_enabled? && retries >= INLINE_RECOVERY_RETRY_THRESHOLD
+              ReadModelRecoveryService.attempt_inline_recovery(read_model, aggregate: aggregate)
+              read_model.reload
+            end
+
+            retries <= MAX_RETRIES ? retry : raise(e)
+          rescue GuardEvaluator::InvalidTransition,
+                 GuardEvaluator::NoChangeTransition,
+                 Yes::Core::Command::Invalid => e
+            command_response_class(cmd).new(cmd: cmd, error: e, batch_id: cmd.batch_id)
+          end
+        end
+
+        private
+
+        attr_reader :aggregate, :read_model
+
+        # Sets pending update state on read model
+        #
+        # @return [void]
+        # @raise [ConcurrentUpdateError] If another process is already updating
+        def set_pending_update_state
+          return unless read_model
+
+          begin
+            ActiveRecord::Base.transaction(requires_new: true) do
+              read_model.update_column(:pending_update_since, Time.current)
+            end
+          rescue ActiveRecord::StatementInvalid => e
+            raise e unless e.message.include?('Concurrent pending update not allowed')
+
+            raise ConcurrentUpdateError.new(
+              aggregate_class: aggregate.class,
+              aggregate_id: read_model.id,
+              original_error: e
+            )
+          end
+        end
+
+        # Clears pending update state on read model
+        #
+        # @return [void]
+        def clear_pending_update_state
+          return unless read_model
+
+          read_model.update_column(:pending_update_since, nil)
+        end
+
+        # Determines the appropriate response class for the command
+        #
+        # @param cmd [Yes::Core::Command] The command
+        # @return [Class] GroupResponse or Response class
+        def command_response_class(cmd)
+          if cmd.is_a?(Yes::Core::Commands::Group)
+            Yes::Core::Commands::Stateless::GroupResponse
+          else
+            Yes::Core::Commands::Response
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Handles the complete command execution flow for aggregates
+      # This class orchestrates command preparation, execution, and read model updates
+      #
+      # @example
+      #   handler = CommandHandler.new(aggregate)
+      #   response = handler.call(:approve_documents, { document_ids: '123', another: 'value' })
+      #
+      class CommandHandler
+        include Yes::Core::OpenTelemetry::Trackable
+
+        # Initializes a new CommandHandler
+        #
+        # @param aggregate [Yes::Core::Aggregate] The aggregate instance to handle commands for
+        def initialize(aggregate)
+          @aggregate = aggregate
+          @command_utilities = aggregate.send(:command_utilities)
+          @read_model = aggregate.read_model if aggregate.class.read_model_enabled?
+        end
+
+        # Executes a command and updates the aggregate state
+        #
+        # @param command_name [Symbol] The name of the command to execute
+        # @param payload [Hash] The command payload
+        # @param guards [Boolean] Whether to evaluate guards (default: true)
+        # @param metadata [Hash] Optional custom metadata to add to the event
+        # @return [Yes::Core::Commands::Response] The command response
+        def call(command_name, payload, guards: true, metadata: nil)
+          prepared_payload = prepare_payload(command_name, payload, metadata)
+          cmd = command_utilities.build_command(command_name, prepared_payload)
+
+          guard_evaluator_class = command_utilities.fetch_guard_evaluator_class(command_name)
+
+          ReadModelRecoveryService.check_and_recover_with_retries(read_model, aggregate:) if aggregate.class.read_model_enabled?
+
+          response = CommandExecutor.new(aggregate).
+                     call(cmd, command_name, guard_evaluator_class, skip_guards: !guards)
+
+          ReadModelUpdater.new(aggregate).call(response.event, prepared_payload, command_name) if aggregate.class.read_model_enabled? && response.success?
+
+          response
+        end
+        otl_trackable :call,
+                      Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Execute command')
+
+        private
+
+        attr_reader :aggregate, :command_utilities, :read_model
+
+        # Prepares the command payload
+        #
+        # @param command_name [Symbol] The command name
+        # @param payload [Hash] The raw payload
+        # @param metadata [Hash, nil] Optional custom metadata
+        # @return [Hash] The prepared payload
+        def prepare_payload(command_name, payload, metadata = nil)
+          prepared = command_utilities.prepare_default_payload(
+            command_name,
+            payload,
+            aggregate.class
+          )
+          prepared = command_utilities.prepare_command_payload(
+            command_name,
+            prepared,
+            aggregate.class
+          )
+          prepared = command_utilities.prepare_assign_command_payload(
+            command_name,
+            prepared
+          )
+
+          add_console_origin(prepared)
+          add_draft_metadata(prepared) if aggregate.draft?
+          add_otl_metadata(prepared)
+          add_custom_metadata(prepared, metadata)
+
+          prepared
+        end
+
+        # Adds console origin to payload when not already present and running in Rails console
+        #
+        # @param payload [Hash] The payload to modify
+        # @return [void]
+        def add_console_origin(payload)
+          return if payload[:origin].present?
+
+          console_origin = Utils::CallerUtils.console_origin
+          payload[:origin] = console_origin if console_origin
+        end
+
+        # Adds draft metadata to payload if aggregate is draft
+        #
+        # @param payload [Hash] The payload to modify
+        # @return [void]
+        def add_draft_metadata(payload)
+          payload[:metadata] ||= {}
+          payload[:metadata][:draft] = true
+        end
+
+        def add_otl_metadata(payload)
+          return if payload.dig(:metadata, :otl_contexts).blank?
+
+          payload[:metadata][:otl_contexts][:timestamps][:command_handling_started_at_ms] = (Time.now.utc.to_f * 1000).to_i
+        end
+
+        # Adds custom metadata to payload
+        #
+        # @param payload [Hash] The payload to modify
+        # @param metadata [Hash, nil] The custom metadata to add
+        # @return [void]
+        def add_custom_metadata(payload, metadata)
+          return if metadata.blank?
+
+          payload[:metadata] ||= {}
+          payload[:metadata].merge!(metadata)
+        end
+      end
+    end
+  end
+end