yes-core 1.0.0

data/lib/yes/core/process_managers/access_token_client.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ProcessManagers
+      # Client for obtaining access tokens using client credentials.
+      #
+      # @example
+      #   client = Yes::Core::ProcessManagers::AccessTokenClient.new
+      #   access_token = client.call(client_id: 'id', client_secret: 'secret')
+      class AccessTokenClient
+        # Custom error class for AccessTokenClient failures.
+        class Error < Yes::Core::ProcessManagers::Base::Error; end
+
+        # Holds structured response data from the token request.
+        Response = Data.define(:response, :request_body, :request_url, :body, :parsed_body, :status_code)
+
+        # @return [String] the authentication service URL
+        AUTH_URL = ENV.fetch('AUTH_URL', 'http://auth-cluster-ip-service:3000/v1')
+
+        # @return [String] the OAuth2 grant type
+        GRANT_TYPE = 'client_credentials'
+
+        # @return [Faraday::Connection] the HTTP connection
+        attr_reader :connection
+        private :connection
+
+        # Initializes the AccessTokenClient with a Faraday connection.
+        def initialize
+          @connection = Faraday.new(AUTH_URL) do |f|
+            f.request :json
+          end
+        end
+
+        # Requests an access token using client credentials.
+        #
+        # @param client_id [String] the client ID
+        # @param client_secret [String] the client secret
+        # @return [String] the access token
+        # @raise [Error] if the access token cannot be obtained
+        def call(client_id:, client_secret:)
+          payload = { client_id:, client_secret:, grant_type: GRANT_TYPE }
+
+          response = perform_request(payload)
+          access_token_error!(response) unless response.response.success?
+
+          return response.parsed_body['access_token'] if response.parsed_body&.dig('access_token')
+
+          access_token_error!(response)
+        end
+
+        private
+
+        # Performs the HTTP request to obtain the access token.
+        #
+        # @param payload [Hash] the request payload
+        # @return [Response] the response object
+        def perform_request(payload)
+          response = connection.post do |req|
+            req.url 'oauth/token'
+            req.body = payload
+          end
+          Response.new(
+            response:,
+            request_url: response.env.url.to_s,
+            request_body: payload,
+            body: response.body,
+            parsed_body: parse_response(response.body),
+            status_code: response.status
+          )
+        end
+
+        # Parses the JSON response body.
+        #
+        # @param body [String] the response body
+        # @return [Hash, nil] the parsed JSON or nil if parsing fails
+        def parse_response(body)
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Raises an error with details about the failed access token request.
+        #
+        # @param response [Response] the response object
+        # @raise [Error] with details about the failed request
+        def access_token_error!(response)
+          msg = 'Access Token Client: failed to get access token'
+
+          extra = {
+            request: {
+              url: response.request_url,
+              body: response.request_body.merge(client_secret: '[FILTERED]')
+            },
+            response: {
+              body: response.parsed_body || response.body,
+              status: response.status_code
+            }
+          }
+
+          Rails.logger.error("#{msg} extra: #{extra}")
+          raise Error.new(msg, extra:)
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/process_managers/base.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ProcessManagers
+      # Base class for process managers.
+      #
+      # @abstract Subclass and override {#call} to implement a process manager.
+      #
+      # @example
+      #   class MyProcessManager < Yes::Core::ProcessManagers::Base
+      #     def call(event)
+      #       # handle event
+      #     end
+      #   end
+      class Base
+        # Error class for process manager failures, with optional extra context.
+        class Error < StandardError
+          # @return [Hash] additional error context
+          attr_accessor :extra
+
+          # @param msg [String] the error message
+          # @param extra [Hash] additional error information
+          def initialize(msg, extra: {})
+            @extra = extra
+            super(msg)
+          end
+        end
+
+        # Handles an event. Must be implemented by subclasses.
+        #
+        # @param _event [Object] the event to handle
+        # @raise [NotImplementedError] if not overridden
+        def call(_event)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/process_managers/command_runner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ProcessManagers
+      # Publishes commands to a command API client with automatic access token retrieval.
+      #
+      # @abstract Subclass and override {#call} to implement command publishing logic.
+      #
+      # @example
+      #   class MyCommandRunner < Yes::Core::ProcessManagers::CommandRunner
+      #     def call(event)
+      #       publish(
+      #         client_id: ENV['CLIENT_ID'],
+      #         client_secret: ENV['CLIENT_SECRET'],
+      #         commands_data: [{ context: 'Foo', aggregate: 'Bar', command: 'create', params: {} }]
+      #       )
+      #     end
+      #   end
+      class CommandRunner < Base
+        # @return [AccessTokenClient] client for retrieving access tokens
+        attr_reader :access_token_client
+
+        # @return [ServiceClient] client for sending commands to the API
+        attr_reader :command_api_client
+
+        # @return [Logger] logger instance for error logging
+        attr_reader :logger
+
+        private :access_token_client, :command_api_client, :logger
+
+        # Initializes a new CommandRunner instance.
+        #
+        # @param command_api_client [ServiceClient, nil] the API client to use for sending commands
+        def initialize(command_api_client: nil)
+          super()
+
+          @command_api_client = command_api_client
+          @access_token_client = AccessTokenClient.new
+          @logger = Rails.logger
+        end
+
+        private
+
+        # Publishes commands to the API.
+        #
+        # @param client_id [String] the client ID for authentication
+        # @param client_secret [String] the client secret for authentication
+        # @param commands_data [Array<Hash>] the commands to be published
+        # @param custom_command_api_client [ServiceClient, nil] optional custom API client
+        # @return [Faraday::Response] the API response
+        # @raise [ArgumentError] if no API client is available
+        # @raise [Yes::Core::ProcessManagers::Base::Error] if the API request fails
+        def publish(client_id:, client_secret:, commands_data:, custom_command_api_client: nil)
+          access_token = access_token_client.call(client_id:, client_secret:)
+          api_client = custom_command_api_client || command_api_client
+
+          if api_client.nil?
+            raise ArgumentError, 'No API client available. Ensure custom_command_api_client is provided ' \
+                                 'or command_api_client is initialized.'
+          end
+
+          response = api_client.call(access_token:, commands_data:, channel:)
+          process_manager_error!(response) unless response.success?
+
+          response
+        end
+
+        # Generates the channel name based on the class name.
+        #
+        # @return [String] the channel name
+        # @example
+        #   "/process_managers/do_something_manager"
+        def channel
+          "/#{self.class.name.split('::').first(2).flatten.join('/').underscore}"
+        end
+
+        # Processes and logs errors from the API response.
+        #
+        # @param response [Faraday::Response] the API response
+        # @param error_msg [String, nil] additional error message
+        # @raise [Yes::Core::ProcessManagers::Base::Error] with detailed error information
+        def process_manager_error!(response, error_msg: nil)
+          msg = 'Process Manager: failed to send commands'
+
+          extra = {
+            error_msg:,
+            request: {
+              url: response.env.url.to_s,
+              body: JSON.parse(response.env.request_body),
+              token: response.env.request_headers['Authorization']
+            },
+            response: {
+              body: begin
+                JSON.parse(response.body)
+              rescue StandardError
+                response.body
+              end,
+              status: response.status
+            }
+          }
+
+          logger.error("#{msg} extra: #{extra}")
+          raise Yes::Core::ProcessManagers::Base::Error.new(msg, extra:)
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/process_managers/service_client.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ProcessManagers
+      # Handles communication with external command API services.
+      #
+      # @example
+      #   client = Yes::Core::ProcessManagers::ServiceClient.new('my_service')
+      #   client.call(access_token: token, commands_data: [...], channel: '/pm/channel')
+      class ServiceClient
+        # @return [String] the URL of the service to communicate with
+        attr_reader :service_url
+        private :service_url
+
+        # Initializes a new ServiceClient.
+        #
+        # @param service [String] the name of the service to connect to
+        def initialize(service)
+          @service_url = ENV.fetch(
+            "#{service.upcase}_SERVICE_URL",
+            "http://#{service.underscore.tr('_', '-')}-cluster-ip-service:3000"
+          )
+        end
+
+        # Sends commands to the service.
+        #
+        # @param access_token [String] JWT token for authentication
+        # @param commands_data [Array<Hash>] array of command data to be sent
+        # @param channel [String] the channel to send command notifications to
+        # @return [Faraday::Response] the response from the service
+        # @raise [ArgumentError] if access_token or channel is nil
+        def call(access_token: nil, commands_data: [], channel: nil)
+          raise ArgumentError, 'channel and access_token is required' if access_token.nil? || channel.nil?
+
+          connection(access_token).post do |req|
+            req.url '/v1/commands'
+            req.body = { channel:, commands: commands_data }
+          end
+        end
+
+        private
+
+        # Creates a Faraday connection to the service.
+        #
+        # @param access_token [String] JWT token for authentication
+        # @return [Faraday::Connection] the configured Faraday connection
+        def connection(access_token)
+          Faraday.new(service_url) do |f|
+            f.request :json
+            f.request :authorization, 'Bearer', access_token
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/process_managers/state.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module ProcessManagers
+      # Represents the state of a subject loaded in a process manager by replaying events.
+      #
+      # @abstract Subclass and override {#stream}, {#required_attributes}, and implement apply_* methods.
+      #
+      # @example
+      #   class UserState < Yes::Core::ProcessManagers::State
+      #     RELEVANT_EVENTS = %w[UserCreated UserUpdated].freeze
+      #
+      #     attr_reader :name, :email
+      #
+      #     private
+      #
+      #     def stream
+      #       PgEventstore::Stream.new(context: 'Users', stream_name: 'User', id: id)
+      #     end
+      #
+      #     def required_attributes
+      #       %i[name email]
+      #     end
+      #
+      #     def apply_user_created(event)
+      #       @name = event.data['name']
+      #       @email = event.data['email']
+      #     end
+      #   end
+      class State
+        # Loads the state for a given ID.
+        #
+        # @param id [String, Integer] the id of the subject to be loaded
+        # @return [State] a new instance with events applied
+        def self.load(id)
+          new(id).tap(&:load)
+        end
+
+        # @param id [String, Integer] the id of the subject to be loaded
+        def initialize(id)
+          @id = id
+        end
+
+        # Loads the state from relevant events.
+        #
+        # @return [void]
+        def load
+          events = relevant_events(stream)
+          return unless events
+
+          process_events(events)
+        end
+
+        # Checks if the state is valid (all required attributes are present).
+        #
+        # @return [Boolean] true if all required attributes are present
+        def valid?
+          required_attributes.all? { |attr| send(attr).present? }
+        end
+
+        private
+
+        # @return [String, Integer] the subject ID
+        attr_reader :id
+
+        # Defines the event stream this state is loaded from.
+        #
+        # @abstract Must be implemented by subclasses.
+        # @raise [NotImplementedError] if not implemented in subclass
+        # @return [PgEventstore::Stream] the event stream
+        def stream
+          raise NotImplementedError, "#{self.class} must implement #stream"
+        end
+
+        # Processes the relevant events and applies them to the state.
+        #
+        # @param events [Hash] a hash of event types and their corresponding events
+        # @raise [NotImplementedError] if an apply_* method is not implemented for an event type
+        # @return [void]
+        def process_events(events)
+          events.each do |event_type, event|
+            event_name = event_type.split('::').last
+            method_name = "apply_#{event_name.underscore}"
+
+            raise NotImplementedError, "#{self.class} must implement ##{method_name}" unless respond_to?(method_name, true)
+
+            send(method_name, event)
+          end
+        end
+
+        # Defines the required attributes for this state.
+        #
+        # @abstract Must be implemented by subclasses.
+        # @raise [NotImplementedError] if not implemented in subclass
+        # @return [Array<Symbol>] list of required attribute names
+        def required_attributes
+          raise NotImplementedError, "#{self.class} must implement #required_attributes"
+        end
+
+        # Retrieves relevant events for the given stream.
+        #
+        # @param stream [PgEventstore::Stream] the event stream to read from
+        # @return [Hash, nil] a hash of relevant events, or nil if no events are found
+        def relevant_events(stream)
+          options = { direction: 'Backwards', filter: { event_types: self.class::RELEVANT_EVENTS } }
+          PgEventstore.client.read_paginated(stream, options:).each_with_object({}) do |events, result|
+            events.each do |event|
+              result[event.type] ||= event
+
+              return result if (self.class::RELEVANT_EVENTS - result.keys).empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/railtie.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    class Railtie < Rails::Railtie
+      config.active_job.custom_serializers << Yes::Core::ActiveJobSerializers::DryStructSerializer
+      config.active_job.custom_serializers << Yes::Core::ActiveJobSerializers::CommandGroupSerializer
+
+      # Runs before any initializers are run
+      config.before_configuration do
+        PgEventstore.configure do |config|
+          config.subscription_pull_interval = 0.5
+          config.event_class_resolver = Yes::Core::EventClassResolver.new
+          # Order of middlewares is important, :with_indifferent_access must come first
+          config.middlewares = {
+            with_indifferent_access: Yes::Core::Middlewares::WithIndifferentAccess.new,
+            timestamp: Yes::Core::Middlewares::Timestamp.new
+          }
+        end
+      end
+
+      config.after_initialize do |app|
+        # Find all aggregates and register their public read models
+        Rails.root.glob('app/contexts/**/**/aggregate.rb').each do |file|
+          require file
+          context, aggregate = file.to_s.split('contexts/').last.split('/')
+          klass = "#{context.camelize}::#{aggregate.camelize}::Aggregate".constantize
+
+          if klass.read_model_public?
+            app.config.yes_read_api.read_models ||= []
+            app.config.yes_read_api.read_models << klass.read_model_name.pluralize
+          end
+
+          # Also register the template read model if the aggregate is draftable and the changes read model is public
+          if klass.draftable? && klass.changes_read_model_public?
+            app.config.yes_read_api.read_models ||= []
+            app.config.yes_read_api.read_models << klass.changes_read_model_name.pluralize
+          end
+        end
+      end
+
+      initializer 'yes-core.config' do |_app|
+        unless Rails.env.test?
+          Yes::Core.configure do |config|
+            config.logger ||= Rails.logger
+          end
+        end
+
+        PgEventstore.logger ||= Rails.logger if ENV['PG_ES_LOGGING'] == 'true'
+      end
+
+      # Load aggregate shortcuts when Rails console starts
+      console do
+        Yes::Core::Utils::AggregateShortcuts.load!
+      end
+    end
+  end
+end