yes-core 1.0.0

data/lib/yes/core/event.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # Base event class for all events in the system.
+    # Inherits from PgEventstore::Event for PostgreSQL-based event storage.
+    class Event < PgEventstore::Event
+      DEFAULT_VERSION = 1
+      PAYLOAD_STORE_VALUE_PREFIX = 'payload-store:'
+
+      InvalidDataError = Class.new(StandardError)
+
+      # Stores the event version blocks
+      @versions = {}
+
+      # Module included in versioned event subclasses to provide correct naming
+      module VersionedEvent
+        # Class methods for versioned events
+        module ClassMethods
+          # Overwrite name so that it reports the correct class name which is set from parent class
+          # @return [String]
+          def name
+            @_class_name
+          end
+        end
+
+        # Add class methods
+        # @param base [Class]
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Overwrite inspect so that it reports the correct class name
+        # @return [String]
+        def inspect
+          variables = attributes_hash.keys.map { |v| "#{v}=#{public_send(v).inspect}" }
+          "#<#{self.class.name} #{variables.join(' ')}>"
+        end
+      end
+
+      class << self
+        # Instantiates a new event. If no version is given, the default version is used.
+        # @param args [Hash]
+        # @return [Yes::Core::Event]
+        def new(**args)
+          # Prevent creating infinite subclasses of versioned events
+          return super if include?(VersionedEvent)
+
+          options = args.dup
+          version = options[:version] || options.dig(:metadata, 'version')
+
+          # Add version to custom metadata if provided
+          if options[:version]
+            options[:metadata] = options[:metadata]&.dup || {}
+            options[:metadata]['version'] ||= version
+          end
+
+          versioned_event_class(version).new(**options)
+        end
+
+        # Returns a dynamic event class as a subclass of the current event class.
+        # This is done so that we can have different versions of the same event with different
+        # schemas.
+        # @param version [Integer]
+        # @return [Class<Yes::Core::Event>] versioned event class
+        def versioned_event_class(version)
+          Class.new(self, &@versions[version || DEFAULT_VERSION]).tap do |versioned_event_class|
+            versioned_event_class.instance_variable_set(:@_class_name, name)
+            versioned_event_class.include(VersionedEvent)
+          end
+        end
+
+        # Defines the fields that are stored in the payload store
+        # @param fields [Array<Symbol>]
+        def payload_store_fields(fields)
+          @ps_store_fields = [*fields].map(&:to_s)
+        end
+
+        # @return [Array<String>] the fields that are stored in the payload store
+        def ps_store_fields
+          @ps_store_fields&.map(&:to_s) || []
+        end
+
+        # Defines a new version of the event. The block is evaluated in the context of the new
+        # event class.
+        # @param number [Integer] The version number
+        # @param blk [Proc] The block containing schema and transformations
+        def version(number, &blk)
+          raise ArgumentError, 'Version number must be an integer' unless number.is_a?(Integer)
+
+          undefined_versions = (1...number).reject { |n| @versions.key?(n) }
+          raise ArgumentError, "Previous versions not defined: #{undefined_versions.join(', ')}" if undefined_versions.any?
+
+          @versions[number] = blk
+        end
+
+        # Initializes class variables for subclasses.
+        # @param subclass [Class]
+        def inherited(subclass)
+          subclass.instance_variable_set(:@versions, {})
+          subclass.instance_variable_set(:@ps_store_fields, @ps_store_fields)
+
+          super
+        end
+      end
+
+      def initialize(**attrs)
+        validate(attrs[:data]) unless attrs[:skip_validation]
+        super
+      end
+
+      alias to_h options_hash
+
+      # @return [Hash]
+      def as_json(*)
+        to_h.transform_keys(&:to_s)
+      end
+
+      # @return [String]
+      def to_json(*)
+        as_json.to_json(*)
+      end
+
+      # @return [Hash] payload store fields with their values
+      def ps_fields_with_values
+        data.select do |_, value|
+          next unless value.is_a?(String)
+
+          value.start_with?(PAYLOAD_STORE_VALUE_PREFIX) && value.split(':').last =~ Types::UUID_REGEXP
+        end
+      end
+
+      # Checks whether the event contains encrypted data
+      # @return [Boolean]
+      def encrypted?
+        metadata&.key?('encryption') && !metadata['encryption'].empty?
+      end
+
+      # @return [Integer] the event version
+      def version
+        metadata['version'] || DEFAULT_VERSION
+      end
+
+      # @param version [Integer] the event version
+      def version=(version)
+        metadata['version'] = version
+      end
+
+      # @return [Hash] the otl context
+      # @param type [Symbol, nil] :publisher or :root
+      def otl_context(type:)
+        return metadata['otl_contexts'] unless type
+
+        metadata.dig('otl_contexts', type.to_s) || {}
+      end
+
+      # @param context [Hash] the otl context
+      #  @option context [String] :traceparent the standard open https://www.w3.org/TR/trace-context/#header-name
+      # @param type [Symbol, nil] :publisher or :root
+      def otl_context=(context, type:)
+        return metadata['otl_contexts'] = context unless type
+
+        metadata['otl_contexts'] ||= {}
+        metadata['otl_contexts'][type.to_s] = context
+      end
+
+      # Transforms the event to a new version
+      # @param direction [Symbol] :up or :down
+      # @return [Event] the transformed event
+      def transform(direction)
+        return self unless self.class.include?(VersionedEvent)
+        raise ArgumentError, 'Direction is not valid' unless %i[up down].include?(direction)
+
+        transformed_event = DataTransformation.new(send(direction), data).call
+        v = direction == :up ? version + 1 : version - 1
+        Yes::Core::Event.new(data: transformed_event, version: v)
+      end
+
+      # event schema
+      def schema; end
+
+      private
+
+      # @param data [Hash]
+      # @return [void]
+      def validate(data)
+        validation_schema = schema
+        return unless validation_schema
+
+        validation = validation_schema.call(data || {})
+        errors = validation.errors.to_h.dup
+        validate_ps_values(data, errors)
+        return if errors.empty?
+
+        raise(InvalidDataError.new(message: "#{validation_schema.class.name} #{errors}"))
+      end
+
+      # Check if a field trapped to errors list because it now has payload store value. If so - remove it from errors
+      # list. Otherwise - add another error that it must be a valid payload store value.
+      # @param data [Hash]
+      # @param errors [Hash<Symbol => Array<String>>]
+      # @return [void]
+      def validate_ps_values(data, errors)
+        errors.each do |field, messages|
+          next unless self.class.ps_store_fields.include?(field.to_s)
+          next errors.delete(field) if valid_ps_value?(data[field] || data[field.to_s])
+
+          messages.push('or must be a correct payload store value')
+        end
+      end
+
+      # @param value [Object]
+      # @return [Boolean]
+      def valid_ps_value?(value)
+        Types::PAYLOAD_STORE_TYPE.call(value)
+        true
+      rescue Dry::Types::ConstraintError
+        false
+      end
+    end
+  end
+end

data/lib/yes/core/event_class_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    # Resolves PgEventstore event types back into their proper class.
+    # When configured as the event_class_resolver in PgEventstore, events
+    # deserialized from the store will be instances of their registered class
+    # (e.g., `Test::UserCreated < Yes::Core::Event`) instead of raw `PgEventstore::Event`.
+    class EventClassResolver
+      # Proxy that skips schema validation when deserializing events from the store,
+      # since stored events are already validated.
+      class SkipValidationProxy < BasicObject
+        # @param klass [Class] the event class to proxy
+        def initialize(klass)
+          @klass = klass
+        end
+
+        # @param attrs [Hash] event attributes from the store
+        # @return [Yes::Core::Event] the event instance with validation skipped
+        def new(**attrs)
+          @klass.new(**attrs, skip_validation: true)
+        end
+      end
+
+      # Resolves an event type string to its class.
+      #
+      # @param event_type [String] the event type (e.g., "Test::UserCreated")
+      # @return [#new] the event class or a proxy that skips validation
+      def call(event_type)
+        SkipValidationProxy.new(Object.const_get(event_type))
+      rescue NameError, TypeError
+        PgEventstore.logger&.debug(<<~TEXT.strip)
+          Unable to resolve class by `#{event_type}' event type. \
+          Picking #{Event} event class to instantiate the event.
+        TEXT
+        Event
+      end
+    end
+  end
+end

data/lib/yes/core/generators/read_models/add_pending_update_tracking_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Yes
+  module Core
+    module Generators
+      module ReadModels
+        # Generator to add pending_update_since tracking to read models
+        # Usage: rails generate yes:core:read_models:add_pending_update_tracking
+        class AddPendingUpdateTrackingGenerator < Rails::Generators::Base
+          include Rails::Generators::Migration
+
+          source_root File.expand_path('templates', __dir__)
+
+          # Generator description for help text
+          desc 'Adds pending_update_since column and constraints to read models for consistency tracking'
+
+          # Main generator method
+          def create_migration
+            migration_number = self.class.next_migration_number(File.join(destination_root, 'db/migrate'))
+            path = File.join(destination_root, "db/migrate/#{migration_number}_add_pending_update_tracking_to_read_models.rb")
+            template('add_pending_update_tracking.rb.erb', path)
+          end
+
+          # Required by Rails::Generators::Migration
+          def self.next_migration_number(dirname)
+            next_migration_number = current_migration_number(dirname) + 1
+            ActiveRecord::Migration.next_migration_number(next_migration_number)
+          end
+
+          private
+
+          # Returns the Rails migration version
+          # @return [String] The migration version string
+          def migration_version
+            "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/generators/read_models/templates/add_pending_update_tracking.rb.erb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+class AddPendingUpdateTrackingToReadModels < ActiveRecord::Migration<%= migration_version %>
+  def up
+    # Get all read model tables from the configuration
+    read_model_tables = Yes::Core.configuration.all_read_model_table_names
+
+    read_model_tables.each do |table_name|
+      # Skip if table doesn't exist (might not have been migrated yet)
+      next unless ActiveRecord::Base.connection.table_exists?(table_name)
+      
+      add_pending_tracking_to_table(table_name)
+    end
+  end
+
+  def down
+    # Get all read model tables from the configuration
+    read_model_tables = Yes::Core.configuration.all_read_model_table_names
+
+    read_model_tables.each do |table_name|
+      # Skip if table doesn't exist
+      next unless ActiveRecord::Base.connection.table_exists?(table_name)
+      
+      remove_pending_tracking_from_table(table_name)
+    end
+  end
+
+  private
+
+  # Truncates an index name to fit within PostgreSQL's 63 character limit
+  # @param name [String] The index name to potentially truncate
+  # @return [String] The truncated index name
+  def truncate_index_name(name)
+    return name if name.length <= 62
+    
+    # Create a short hash for uniqueness
+    require 'digest'
+    hash = Digest::SHA256.hexdigest(name)[0..7]
+    
+    # Take first part of name and append hash
+    "#{name[0..52]}_#{hash}"
+  end
+
+  # Adds pending_update_since tracking to a table
+  # @param table_name [String] The table to modify
+  def add_pending_tracking_to_table(table_name)
+    # Add pending_update_since column if it doesn't exist
+    unless column_exists?(table_name, :pending_update_since)
+      add_column table_name, :pending_update_since, :datetime
+      say "Added pending_update_since column to #{table_name}", :green
+    end
+
+    # Create trigger function if it doesn't exist
+    create_pending_update_trigger_function
+
+    # Create trigger on the table
+    trigger_name = "trg_#{table_name}_prevent_concurrent_pending"
+    # Truncate trigger name if too long
+    trigger_name = trigger_name[0..62] if trigger_name.length > 63
+    
+    execute <<-SQL
+      DROP TRIGGER IF EXISTS #{trigger_name} ON #{table_name};
+      CREATE TRIGGER #{trigger_name}
+        BEFORE UPDATE ON #{table_name}
+        FOR EACH ROW
+        EXECUTE FUNCTION prevent_concurrent_pending_update();
+    SQL
+    say "Added concurrent update prevention trigger on #{table_name}", :green
+
+    # Create regular index for efficient recovery queries
+    recovery_index_name = truncate_index_name("idx_#{table_name}_pending_recovery")
+    unless index_exists?(table_name, :pending_update_since, name: recovery_index_name)
+      add_index table_name,
+                :pending_update_since,
+                where: 'pending_update_since IS NOT NULL',
+                name: recovery_index_name
+      say "Added recovery index on #{table_name}.pending_update_since", :green
+    end
+  end
+
+  # Creates the PostgreSQL function to prevent concurrent pending updates
+  def create_pending_update_trigger_function
+    execute <<-SQL
+      CREATE OR REPLACE FUNCTION prevent_concurrent_pending_update()
+      RETURNS TRIGGER AS $$
+      BEGIN
+        -- If trying to set pending_update_since when it's already set
+        IF NEW.pending_update_since IS NOT NULL AND 
+           OLD.pending_update_since IS NOT NULL AND
+           NEW.pending_update_since != OLD.pending_update_since THEN
+          RAISE EXCEPTION 'Concurrent pending update not allowed for record %', NEW.id
+            USING ERRCODE = 'unique_violation';
+        END IF;
+        
+        -- Allow clearing pending_update_since (setting to NULL)
+        -- Allow initial setting when OLD value is NULL
+        RETURN NEW;
+      END;
+      $$ LANGUAGE plpgsql;
+    SQL
+  end
+
+  # Removes pending tracking from a table
+  # @param table_name [String] The table to modify
+  def remove_pending_tracking_from_table(table_name)
+    # Remove trigger
+    trigger_name = "trg_#{table_name}_prevent_concurrent_pending"
+    trigger_name = trigger_name[0..62] if trigger_name.length > 63
+    execute "DROP TRIGGER IF EXISTS #{trigger_name} ON #{table_name};"
+    
+    # Remove recovery index
+    recovery_index_name = truncate_index_name("idx_#{table_name}_pending_recovery")
+    remove_index table_name, name: recovery_index_name if index_exists?(table_name, nil, name: recovery_index_name)
+    
+    # Remove column
+    remove_column table_name, :pending_update_since if column_exists?(table_name, :pending_update_since)
+    
+    # Note: We don't remove the trigger function as it might be used by other tables
+    
+    say "Removed pending tracking from #{table_name}", :yellow
+  end
+end

data/lib/yes/core/generators/read_models/templates/migration.rb.erb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class UpdateReadModels < ActiveRecord::Migration[7.1]
+  def change
+    <% @aggregates.each do |aggregate| %>
+    <%= table_operations(aggregate) %>
+    <% end %>
+  end
+end

data/lib/yes/core/generators/read_models/update_generator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Yes
+  module Core
+    module Generators
+      module ReadModels
+        class UpdateGenerator < Rails::Generators::Base
+          include Rails::Generators::Migration
+
+          source_root File.expand_path('templates', __dir__)
+
+          desc 'Creates or updates read models for aggregates'
+
+          def create_migration
+            @aggregates = find_aggregates
+            return if @aggregates.empty?
+
+            migration_number = self.class.next_migration_number(File.join(destination_root, 'db/migrate'))
+
+            path = File.join(destination_root, "db/migrate/#{migration_number}_update_read_models.rb")
+            template('migration.rb.erb', path)
+          end
+
+          # Required by Rails::Generators::Migration
+          def self.next_migration_number(dirname)
+            next_migration_number = current_migration_number(dirname) + 1
+            ActiveRecord::Migration.next_migration_number(next_migration_number)
+          end
+
+          private
+
+          def find_aggregates
+            root_path = Rails.root || Pathname.new(destination_root)
+
+            Dir.glob(root_path.join('app/contexts/**/**/aggregate.rb')).map do |file|
+              require file
+              context, aggregate = file.split('contexts/').last.split('/')
+              klass = "#{context.camelize}::#{aggregate.camelize}::Aggregate".constantize
+              {
+                context:,
+                aggregate:,
+                klass:,
+                attributes: klass.attributes,
+                read_model_name: klass.read_model_name
+              }
+            end
+          end
+
+          def table_operations(aggregate)
+            table_name = aggregate[:read_model_name].to_s.pluralize
+
+            if table_exists?(table_name)
+              alter_table_block(aggregate, table_name)
+            else
+              create_table_block(aggregate)
+            end
+          end
+
+          def create_table_block(aggregate)
+            table_name = aggregate[:read_model_name].to_s.pluralize
+            <<~RUBY
+              create_table :#{table_name} do |t|
+                #{column_definitions(aggregate[:attributes])}
+                t.integer :revision, null: false, default: -1
+                t.timestamps
+              end
+            RUBY
+          end
+
+          def alter_table_block(aggregate, table_name)
+            existing_columns = fetch_existing_columns(table_name)
+            defined_columns = build_defined_columns(aggregate)
+
+            build_alter_statements(table_name, existing_columns, defined_columns, aggregate[:attributes])
+          end
+
+          def fetch_existing_columns(table_name)
+            ActiveRecord::Base.connection.columns(table_name).map(&:name) - %w[id created_at updated_at]
+          end
+
+          def build_defined_columns(aggregate)
+            aggregate[:attributes].keys.map do |key|
+              type = aggregate[:attributes][key]
+              type == :aggregate ? "#{key}_id" : key.to_s
+            end
+          end
+
+          def build_alter_statements(table_name, existing_columns, defined_columns, attributes)
+            statements = []
+            statements << add_revision_statement(table_name) unless existing_columns.include?('revision')
+            statements.concat(build_add_column_statements(table_name, existing_columns, defined_columns, attributes))
+            statements.concat(build_remove_column_statements(table_name, existing_columns, defined_columns))
+            statements.join("\n    ")
+          end
+
+          def add_revision_statement(table_name)
+            "add_column :#{table_name}, :revision, :integer, null: false, default: -1"
+          end
+
+          def build_add_column_statements(table_name, existing_columns, defined_columns, attributes)
+            (defined_columns - existing_columns).map do |column|
+              attribute_name = column.end_with?('_id') ? column.chomp('_id').to_sym : column.to_sym
+              type = attributes[attribute_name]
+              "add_column :#{table_name}, :#{column}, :#{database_type(type)}"
+            end
+          end
+
+          def build_remove_column_statements(table_name, existing_columns, defined_columns)
+            (existing_columns - defined_columns - ['revision']).map do |column|
+              "remove_column :#{table_name}, :#{column}"
+            end
+          end
+
+          def column_definitions(attributes)
+            attributes.map do |name, type|
+              if type == :aggregate
+                "t.uuid :#{name}_id"
+              else
+                "t.#{database_type(type)} :#{name}"
+              end
+            end.join("\n      ")
+          end
+
+          def table_exists?(table_name)
+            ActiveRecord::Base.connection.table_exists?(table_name)
+          end
+
+          def database_type(type)
+            case type
+            when :string, :email, :url then :string
+            when :integer then :integer
+            when :uuid then :uuid
+            when :boolean then :boolean
+            when :float then :float
+            when :datetime then :datetime
+            when :hash then :jsonb
+            when :aggregate then :uuid
+            else :string # default to string for unknown types
+            end
+          end
+        end
+      end
+    end
+  end
+end