yes-core 1.0.0

data/lib/yes/core/aggregate.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # The Aggregate class represents a core entity in the eventsourcing system.
+    # It provides functionality for managing event sourcing patterns including:
+    # - Attribute management with automatic command and event generation
+    # - Parent-child aggregate relationships
+    # - Read model associations
+    # - Context management
+    #
+    # @example Define an aggregate with attributes
+    #   class UserAggregate < Yes::Core::Aggregate
+    #     primary_context 'Users'
+    #     attribute :email, :email
+    #     attribute :name, :string
+    #   end
+    #
+    # @example Define an aggregate with a parent
+    #   class ProfileAggregate < Yes::Core::Aggregate
+    #     parent :user do
+    #       guard(:user_exists) { payload.user.present? }
+    #       guard(:not_removed) { trashed_at.blank? }
+    #     end
+    #     attribute :bio, :string
+    #   end
+    #
+    # @example Define an aggregate with a command
+    #   class CompanyAggregate < Yes::Core::Aggregate
+    #     primary_context 'Companies'
+    #
+    #     command :assign_user do
+    #       payload user_id: :uuid
+    #
+    #       guard :user_already_assigned do
+    #         user_id.present?
+    #       end
+    #     end
+    #   end
+    #
+    # @since 0.1.0
+    # @author Nico Ritsche
+    class Aggregate
+      attr_reader :id, :command_utilities, :draft
+
+      private :command_utilities, :draft
+
+      include HasReadModel
+      include Draftable
+      include HasAuthorizer
+
+      class << self
+        # @return [String, nil] The primary context name for this aggregate
+        attr_reader :_primary_context
+
+        # Hook that runs when a class inherits from Aggregate
+        # @param subclass [Class] The class inheriting from Aggregate
+        # @return [void]
+        def inherited(subclass)
+          super
+
+          # Add an "end of definition" hook using at_exit
+          # Setting up read model classes is done here, because it needs to be done after
+          # the class definition is complete.
+          TracePoint.new(:end) do |tp|
+            if tp.self == subclass
+              subclass.setup_read_model_classes if subclass.read_model_enabled?
+              subclass.setup_authorizer_classes
+              tp.disable
+            end
+          end.enable
+        end
+
+        # Defines a parent aggregate and automatically registers a corresponding Assign command
+        # together with a corresponding attribute.
+        #
+        # @param name [Symbol] The name of the parent.
+        # @param options [Hash] Options for configuring the parent.
+        # @yield Block for defining guards and other attribute configurations.
+        # @return [void]
+        def parent(name, **options, &)
+          parent_aggregates[name] = options
+
+          attribute name, :aggregate
+
+          return unless options.fetch(:command, true)
+
+          command :"assign_#{name}" do
+            payload "#{name}_id": :uuid
+
+            guard(:no_change) { public_send(:"#{name}_id") != payload.public_send(:"#{name}_id") }
+
+            instance_eval(&) if block_given?
+          end
+        end
+
+        # Retrieves or initializes the parent_aggregates hash.
+        #
+        # @return [Hash<Symbol, Hash>] A hash containing parent aggregates and their configuration options
+        def parent_aggregates
+          @parent_aggregates ||= {}
+        end
+
+        # Defines a default removal behavior for the aggregate.
+        #
+        # @param attr_name [Symbol] the attribute name to use for marking removal
+        # @yield Block for defining additional guards and other removal configurations
+        # @return [void]
+        #
+        # @example Define a default removal behavior
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable
+        #   end
+        #
+        # @example Define a removal behavior with additional custom guards
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable do
+        #       guard(:exists) { read_model.name.present? }
+        #     end
+        #   end
+        #
+        # @example Define a removal behavior with a custom attribute name
+        #   class UserAggregate < Yes::Core::Aggregate
+        #     removable(attr_name: :deleted_at)
+        #   end
+        #
+        def removable(attr_name: :removed_at, &)
+          attribute attr_name, :datetime unless attributes.key?(attr_name)
+
+          command :remove do
+            guard(:no_change) { !public_send(attr_name) }
+            update_state { method(attr_name).call { Time.current } }
+            instance_eval(&) if block_given?
+          end
+        end
+
+        # Sets the primary context for the aggregate.
+        #
+        # @param context [String] The primary context to set.
+        # @return [void]
+        def primary_context(context)
+          @_primary_context = context
+        end
+
+        # Defines an attribute on the aggregate which creates corresponding command, event and handler
+        #
+        # @param name [Symbol] name of the attribute
+        # @param type [Symbol] type of the attribute (e.g., :string, :email, :uuid)
+        # @param options [Hash] additional options for the attribute
+        # @yield Block for defining guards and other attribute configurations
+        # @yieldreturn [void]
+        #
+        # @example Define a string attribute (without command)
+        #   attribute :name, :string
+        #
+        # @example Define an aggregate attribute (without command)
+        #   attribute :location, :aggregate
+        #
+        # @example Define an email attribute with command
+        #   attribute :email, :email, command: true
+        #
+        # @example Define an attribute with command and guards
+        #   attribute :first_name, :string, command: true do
+        #     guard :something do
+        #       first_name == 'John'
+        #     end
+        #   end
+        #
+        # @example Define a localized attribute
+        #   attribute :description, :string, command: true, localized: true
+        def attribute(name, type, **options, &)
+          raise 'Aggregate attribute definition with command: true is not allowed' if type == :aggregate && options[:command]
+
+          @attributes ||= {}
+          @attributes[name] = type
+
+          @attribute_options ||= {}
+          @attribute_options[name] = options.slice(:localized)
+
+          options = options.merge(context:, aggregate:)
+          Dsl::AttributeDefiner.new(
+            Dsl::AttributeData.new(name, type, self, options)
+          ).call
+
+          command(:change, name, type, &) if options[:command]
+        end
+
+        # Defines a command on the aggregate which creates corresponding command and event classes
+        #
+        # @overload command(name, &)
+        #   @param name [Symbol] name of the command
+        #   @yield Block for defining payload, guards, and other command configurations
+        #   @yieldreturn [void]
+        #
+        # @overload command(publish)
+        #   @param publish [Symbol] passing :publish as a name will generate published attribute and publish command
+        #   @return [void]
+        #
+        # @overload command(change, attribute, **options)
+        #   @param change [Symbol] passing :change as a name will generate a change command and an attribute
+        #   @param attribute [Symbol] attribute name
+        #   @param options [Hash] additional options for the attribute
+        #   @return [void]
+        #
+        # @overload command(enable, attribute, **options)
+        #   @param enable [Symbol] passing :enable or :activate as a name will generate a flag set to true command and an attribute
+        #   @param attribute [Symbol] attribute name
+        #   @param options [Hash] additional options for the attribute
+        #   @return [void]
+        #
+        # @overload command(toggle_names, attribute)
+        #  @param toggle_names [Array<Symbol>] toggle command names to be generated
+        #  @param attribute [Symbol] attribute name
+        #  @return [void]
+        #
+        # @example Define a basic command
+        #   command :assign_user
+        #
+        # @example Define a command with custom payload and guards
+        #   command :assign_user do
+        #     payload user_id: :uuid
+        #
+        #     guard :user_already_assigned do
+        #       user_id.present?
+        #     end
+        #
+        #     event :user_assigned
+        #   end
+        #
+        # @example Define change command and an attribute
+        #   command :change, :age, :integer, localized: true
+        #
+        # @example Define set flag to true command an an attribute
+        #   command :activate, :dropout, attribute: :dropout_enabled
+        #
+        # @example Define set of toggle commands an an attribute
+        #   command [:enable, :disable], :dropout
+        #
+        # @example Define publish command an published attribute
+        #   command :publish
+        #
+        def command(*args, **, &)
+          return handle_command_shortcut(*args, **, &) unless Dsl::CommandShortcutExpander.base_case?(*args, **, &)
+
+          name = args.first
+          @commands ||= {}
+          command_data = Dsl::CommandData.new(name, self, { context:, aggregate: })
+          @commands[name] = command_data
+
+          Dsl::CommandDefiner.new(command_data).call(&)
+        end
+
+        # Returns the context namespace for the aggregate
+        #
+        # @return [String] The context namespace
+        # @example
+        #   Users::User::Aggregate.context #=> "Users"
+        def context
+          name.to_s.split('::').first
+        end
+
+        # Returns the aggregate name without namespace and "Aggregate" suffix
+        #
+        # @return [String] The aggregate name
+        # @example
+        #   Users::User::Aggregate.aggregate #=> "User"
+        def aggregate
+          name.to_s.split('::')[-2]
+        end
+
+        # @return [Hash] The attributes defined on this aggregate
+        def attributes
+          @attributes ||= {}
+        end
+
+        # @return [Hash] The attribute options (localized, encrypted, etc.)
+        def attribute_options
+          @attribute_options ||= {}
+        end
+
+        # @return [Hash] The commands defined on this aggregate
+        def commands
+          @commands ||= {}
+        end
+
+        private
+
+        #
+        # Takes all parameters passed to command invocation, forwards them to the command shortcut expander
+        # and then defines commands and attributes
+        #
+        # @param [Array<Object>] *args
+        # @param [Hash<Object, Object>] **kwargs
+        # @param [Proc] &block
+        #
+        # @return [void]
+        #
+        def handle_command_shortcut(...)
+          expanded = Dsl::CommandShortcutExpander.new(...).call
+
+          expanded.attributes.each do |specification|
+            next if attributes.key?(specification.name)
+
+            attribute(specification.name, specification.type, **specification.options)
+          end
+
+          expanded.commands.each do |specification|
+            command(specification.name, &specification.block)
+          end
+        end
+      end
+
+      # Initializes a new aggregate instance
+      # @param id [String] The aggregate ID (optional, defaults to SecureRandom.uuid)
+      # @param draft [Boolean] Whether this instance is being edited as a draft (default: false)
+      # @return [Yes::Core::Aggregate] A new aggregate instance
+      #
+      # @example Backwards compatibility - single ID parameter
+      #   Aggregate.new(some_id)
+      #
+      # @example With draft as keyword argument
+      #   Aggregate.new(draft: true)
+      #
+      # @example With positional id and draft keyword
+      #   Aggregate.new(some_id, draft: true)
+      #
+      def initialize(id = SecureRandom.uuid, draft: false)
+        validate_draft_initialization(draft)
+
+        @id = id
+        @draft = draft
+
+        @command_utilities = Utils::CommandUtils.new(
+          context: self.class.context,
+          aggregate: self.class.aggregate,
+          aggregate_id: @id
+        )
+      end
+
+      # Reloads the aggregate and its read model
+      # @return [Yes::Core::Aggregate] The reloaded aggregate
+      def reload
+        read_model&.reload
+
+        self
+      end
+
+      # Returns the events for the aggregate
+      # @return [Enumerator<PgEventstore::Event>] The events for the aggregate
+      def events
+        PgEventstore.client.read_paginated(
+          command_utilities.build_stream(metadata: { draft: draft? }), options: { direction: 'Forwards' }
+        )
+      end
+
+      # Retrieves the most recent event from the aggregate's event stream
+      # @return [PgEventstore::Event, nil] The latest event or nil if no events exist
+      def latest_event
+        PgEventstore.client.read(
+          command_utilities.build_stream(metadata: { draft: draft? }), options: { max_count: 1, direction: :desc }
+        ).first
+      end
+
+      # Returns the stream revision number of the latest event
+      # @return [Integer] The revision number of the latest event in the stream
+      # @raise [NoMethodError] If no events exist for this aggregate
+      def event_revision
+        latest_event.stream_revision
+      end
+
+      # Returns a list of commands that can be executed on this aggregate with their associated events
+      # @return [Hash<Symbol, Array<Symbol>>] A hash of command names to their event names, sorted alphabetically
+      # @example
+      #   user_aggregate.commands
+      #   # => {
+      #   #   approve_documents: [:documents_approved],
+      #   #   change_age: [:age_changed],
+      #   #   change_email: [:email_changed],
+      #   #   change_name: [:name_changed]
+      #   # }
+      def commands
+        mappings = Yes::Core.configuration.command_event_mappings(
+          self.class.context,
+          self.class.aggregate
+        )
+
+        mappings.sort.to_h
+      end
+
+      private
+
+      # Validates that draft initialization is only allowed for draftable aggregates
+      #
+      # @param draft [Boolean] Whether the aggregate is being initialized as a draft
+      # @raise [ArgumentError] If draft is true but aggregate is not draftable
+      # @return [void]
+      def validate_draft_initialization(draft)
+        return unless draft && !self.class.draftable?
+
+        raise ArgumentError, "#{self.class.name} is not draftable. Add 'draftable' to the class definition."
+      end
+    end
+  end
+end

data/lib/yes/core/authentication_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # Raised when authentication fails in API controllers
+    class AuthenticationError < Error; end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # Provides a shared Cerbos client instance for authorizer classes.
+      #
+      # @example Including in a class with class-level methods
+      #   class MyAuthorizer
+      #     class << self
+      #       include Yes::Core::Authorization::CerbosClientProvider
+      #     end
+      #   end
+      module CerbosClientProvider
+        private
+
+        # @return [Cerbos::Client] Cerbos client configured from Yes::Core configuration
+        def cerbos_client
+          Cerbos::Client.new(
+            Yes::Core.configuration.cerbos_url,
+            tls: Yes::Core.configuration.cerbos_tls
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # @abstract command authorizer base class. Subclass and override call method to implement
+      # a custom authorizer.
+      class CommandAuthorizer
+        include OpenTelemetry::Trackable
+
+        CommandNotAuthorized = Class.new(Yes::Core::Error)
+
+        class << self
+          include OpenTelemetry::Trackable
+
+          # Implement this method to authorize a command. Needs to return true if command is authorized,
+          # otherwise raise CommandNotAuthorized.
+          # @param command [Yes::Core::Command] command to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if command is authorized
+          def call(_command, auth_data)
+            return true if super_admin?(auth_data)
+
+            current_span&.status = ::OpenTelemetry::Trace::Status.error('Command not authorized')
+            raise CommandNotAuthorized
+          end
+          otl_trackable :call, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Authorize Command')
+
+          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/command_cerbos_authorizer.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # Cerbos-based command authorizer base class.
+      #
+      # Subclasses must define a RESOURCE constant:
+      #   RESOURCE = { name: 'apprenticeship', read_model: Apprenticeship, draft_read_model: ApprenticeshipDraft }
+      #
+      # @abstract
+      class CommandCerbosAuthorizer < Yes::Core::Authorization::CommandAuthorizer
+        NEW_RESOURCE_ID = 'new'
+
+        class << self
+          include OpenTelemetry::Trackable
+          include CerbosClientProvider
+
+          # @param command [Yes::Core::Command] command to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if command is authorized
+          # @raise [CommandNotAuthorized] if command is not authorized
+          def call(command, auth_data)
+            singleton_class.current_span&.add_attributes({ 'command' => command.to_json })
+
+            check_principal_id_present(auth_data)
+            singleton_class.current_span&.add_event('Principal Id Checked')
+
+            resource = load_resource(command)
+            singleton_class.current_span&.add_event('Resource Loaded')
+
+            decision = authorize(command, resource, auth_data)
+            singleton_class.current_span&.add_event('Cerbos Decision', attributes: { 'decision' => decision.to_json })
+
+            return true if decision.allow_all?
+
+            raise_command_unauthorized_error!(decision)
+          end
+          otl_trackable :call, OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Cerbos Authorize Command')
+
+          private
+
+          # @param decision [Cerbos::Output::CheckResources::Result]
+          # @raise [CommandNotAuthorized]
+          def raise_command_unauthorized_error!(decision)
+            msg = 'You are not allowed to execute this command'
+            singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error(msg)
+
+            raise self::CommandNotAuthorized.new(msg, extra: { decision: decision.outputs.map(&:value) })
+          end
+
+          # @param auth_data [Hash] authorization data
+          # @return [Boolean] true if identity_id is present in auth_data
+          # @raise [CommandNotAuthorized] if identity_id is not present in auth_data
+          def check_principal_id_present(auth_data)
+            return true if principal_id(auth_data)
+
+            msg = 'Missing identity id in JWT token auth_data'
+            singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error(msg)
+            raise self::CommandNotAuthorized, msg
+          end
+
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [ActiveRecord::Base] resource to authorize
+          # @raise [StandardError] if RESOURCE[:name] or RESOURCE[:read_model] is not defined
+          def load_resource(command)
+            unless defined?(self::RESOURCE) && self::RESOURCE[:name] && self::RESOURCE[:read_model]
+              message =
+                'Your CommandCerbosAuthorizer subclass needs to define RESOURCE[:name] and RESOURCE[:read_model] constant'
+              raise StandardError, message
+            end
+
+            read_model(command).find_by(id: command.send("#{self::RESOURCE[:name]}_id"))
+          end
+
+          # Returns the appropriate read model class for the command.
+          # Uses the draft read model when the command is an edit template command
+          # and a draft_read_model is configured in RESOURCE.
+          #
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [Class] the read model class
+          def read_model(command)
+            return self::RESOURCE[:draft_read_model] if command.metadata&.dig(:edit_template_command) && self::RESOURCE[:draft_read_model]
+
+            self::RESOURCE[:read_model]
+          end
+
+          # @param command [Yes::Core::Command]
+          # @param resource [ActiveRecord::Base]
+          # @param auth_data [Hash]
+          # @return [Cerbos::Output::CheckResources::Result]
+          def authorize(...)
+            singleton_class.current_span&.add_event('Authorization Started')
+            payload = cerbos_payload(...)
+            singleton_class.current_span&.add_event('Cerbos Payload Built')
+
+            singleton_class.with_otl_span('Authorize request to Cerbos') do
+              cerbos_client.check_resource(**payload)
+            end
+          end
+
+          # @param command [Yes::Core::Command] command to authorize
+          # @param resource [ActiveRecord::Base] resource to authorize
+          # @param auth_data [Hash] authorization data
+          # @return [Hash] payload for Cerbos check_resource
+          def cerbos_payload(command, resource, auth_data)
+            {
+              principal: principal_data(auth_data).deep_merge(attributes: { command_payload: command.payload }),
+              resource: resource_data(resource, command),
+              actions: actions(command),
+              include_metadata: Yes::Core.configuration.cerbos_commands_authorizer_include_metadata
+            }.deep_symbolize_keys.tap { singleton_class.current_span&.set_attribute('cerbos_payload', _1.to_json) }
+          end
+
+          # @param resource [ActiveRecord::Base] resource to authorize
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [Hash] resource data for Cerbos check_resource
+          def resource_data(resource, command)
+            attribs = resource_attributes(resource, command)
+            {
+              kind: resource_kind(resource, attribs),
+              scope: scope(command),
+              id: resource_id(resource),
+              attributes: attribs
+            }
+          end
+
+          # @param resource [ActiveRecord::Base] resource to authorize
+          # @param attribs [Hash] resource attributes
+          # @return [String] resource kind for Cerbos check_resource
+          def resource_kind(resource, attribs)
+            (attribs.values.any? { !_1.nil? } || attribs.empty?) && resource&.id ? self::RESOURCE[:name] : new_resource_id
+          end
+
+          # @param resource [ActiveRecord::Base] resource to authorize
+          # @return [String] resource id for Cerbos check_resource
+          def resource_id(resource)
+            resource&.id || new_resource_id
+          end
+
+          # @param resource [ActiveRecord::Base] resource to authorize
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [Hash] resource attributes for Cerbos check_resource
+          def resource_attributes(resource, _command)
+            resource&.try(:auth_attributes)&.as_json || {}
+          end
+
+          # @param auth_data [Hash] authorization data
+          # @return [Hash] principal data for Cerbos check_resource
+          def principal_data(auth_data)
+            Yes::Core.configuration.cerbos_principal_data_builder.call(
+              auth_data.with_indifferent_access
+            )
+          end
+
+          # @param auth_data [Hash]
+          # @return [String]
+          def principal_id(auth_data)
+            auth_data.with_indifferent_access[:identity_id]
+          end
+
+          # @return [String] new resource id
+          def new_resource_id
+            "#{self::RESOURCE[:name]}:#{NEW_RESOURCE_ID}"
+          end
+
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [Array<String>] actions for Cerbos check_resource
+          def actions(command)
+            [command.class.to_s.gsub(/::Commands?/, '').split('::').last.underscore]
+          end
+
+          # @param command [Yes::Core::Command] command to authorize
+          # @return [String] scope for Cerbos check_resource
+          def scope(command)
+            command.class.to_s.split('::').first.underscore
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module Authorization
+      # @abstract Read model authorizer base class. Subclass and override call method to implement
+      # a custom authorizer.
+      class ReadModelAuthorizer
+        NotAuthorized = Class.new(Yes::Core::Error)
+
+        # Implement this method to authorize a read model.
+        # Needs to return true if read model is authorized, otherwise raise NotAuthorized.
+        # @param record [ApplicationRecord] record to authorize
+        # @param auth_data [Hash] authorization data
+        # @return [Boolean] true if read model is authorized
+        def self.call(_record, _auth_data)
+          raise NotAuthorized
+        end
+      end
+    end
+  end
+end