orfeas_lyra 0.6.0

data/lib/lyra/projections/event_store_reader.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Projections
+    # Reads model state from event store when projections are disabled.
+    #
+    # Uses CachedProjection (backed by Solid Cache or Rails.cache) for
+    # fast reads while keeping events as the source of truth.
+    #
+    # Usage:
+    #   EventStoreReader.find(User, 123)
+    #   EventStoreReader.find_by(User, email: "test@example.com")
+    #   EventStoreReader.where(User, status: "active")
+    #
+    class EventStoreReader
+      class << self
+        # Find a record by ID (cached)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param id [Integer, String] The record ID
+        # @return [ActiveRecord::Base, nil] The reconstructed record or nil
+        def find(model_class, id)
+          attributes = CachedProjection.find(model_class, id)
+          return nil unless attributes
+
+          build_instance(model_class, attributes)
+        end
+
+        # Find a record by attributes (cached)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param attributes [Hash] The attributes to match
+        # @return [ActiveRecord::Base, nil] The first matching record or nil
+        def find_by(model_class, attributes)
+          result = CachedProjection.find_by(model_class, attributes)
+          return nil unless result
+
+          build_instance(model_class, result)
+        end
+
+        # Check if a record exists (cached)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param id [Integer, String] The record ID
+        # @return [Boolean] True if record exists and is not destroyed
+        def exists?(model_class, id)
+          CachedProjection.exists?(model_class, id)
+        end
+
+        # Get a CachedRelation for the model (supports method chaining)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @return [CachedRelation] A relation-like object for chaining
+        def relation(model_class)
+          results = CachedProjection.all(model_class)
+          records = results.map { |attrs| build_instance(model_class, attrs) }.compact
+          CachedRelation.new(model_class, records)
+        end
+
+        # Load all records of a given type (cached)
+        # Warning: Can be expensive for large datasets
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @return [CachedRelation] A relation containing all reconstructed records
+        def all(model_class)
+          relation(model_class)
+        end
+
+        # Query records with conditions (cached)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param conditions [Hash] Query conditions
+        # @return [CachedRelation] A relation containing matching records
+        def where(model_class, conditions)
+          relation(model_class).where(conditions)
+        end
+
+        # Count records (cached)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param conditions [Hash] Optional conditions
+        # @return [Integer] Count of matching records
+        def count(model_class, conditions = {})
+          CachedProjection.count(model_class, conditions)
+        end
+
+        # Invalidate cache for a record (call after event stored)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param id [Integer, String] The record ID
+        def invalidate(model_class, id)
+          CachedProjection.invalidate(model_class, id)
+        end
+
+        # Warm cache for a record (call after event stored)
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param id [Integer, String] The record ID
+        def warm(model_class, id)
+          CachedProjection.warm(model_class, id)
+        end
+
+        private
+
+        def build_instance(model_class, attributes)
+          # Ensure attributes are stringified
+          attrs = attributes.transform_keys(&:to_s)
+
+          # Filter to only known columns
+          column_names = model_class.column_names
+          filtered_attrs = attrs.slice(*column_names)
+
+          # Use AR's instantiate method - proper way to build from DB-style attributes
+          record = model_class.instantiate(filtered_attrs)
+
+          # Note: We don't mark as readonly because the app may need to modify
+          # and re-save (which will go through event sourcing)
+
+          record
+        rescue => e
+          Rails.logger.warn("Lyra::EventStoreReader: Failed to build instance - #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/lyra/projections/model_projection.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Projections
+    # Synchronous projection handler for updating model tables from events.
+    #
+    # In event_sourcing mode, this class is responsible for keeping the model
+    # (read model) tables in sync with the event store. It uses raw SQL operations
+    # (insert, update_all, delete_all) to avoid triggering ActiveRecord callbacks
+    # or PaperTrail versioning.
+    #
+    # Usage:
+    #   ModelProjection.project(Registration, :create, result)
+    #   ModelProjection.project(Registration, :update, result)
+    #   ModelProjection.project(Registration, :destroy, result)
+    #
+    class ModelProjection
+      class << self
+        # Project a command result to the model table
+        #
+        # @param model_class [Class] The ActiveRecord model class
+        # @param operation [Symbol] :create, :update, or :destroy
+        # @param result [CommandResult] The result from CommandHandler
+        def project(model_class, operation, result)
+          case operation
+          when :create
+            project_create(model_class, result)
+          when :update
+            project_update(model_class, result)
+          when :destroy
+            project_destroy(model_class, result)
+          else
+            raise ArgumentError, "Unknown operation: #{operation}"
+          end
+        end
+
+        # Insert a new record into the model table
+        #
+        # Uses insert() to bypass all callbacks and validations.
+        # This is intentional - the event is the source of truth.
+        def project_create(model_class, result)
+          attributes = result.attributes.dup
+
+          # Ensure we have an ID
+          raise "Cannot project create without ID" unless attributes[:id] || attributes["id"]
+
+          # Add timestamps if not present
+          now = Time.current
+          attributes[:created_at] ||= now
+          attributes[:updated_at] ||= now
+
+          # Convert to database-safe format
+          insert_attrs = sanitize_attributes(model_class, attributes)
+
+          # Use insert to bypass callbacks
+          # Bypass strict data access - projections are legitimate bulk operations
+          previous = Thread.current[:lyra_bypass_strict_access]
+          Thread.current[:lyra_bypass_strict_access] = true
+          begin
+            model_class.insert(insert_attrs)
+          ensure
+            Thread.current[:lyra_bypass_strict_access] = previous
+          end
+        end
+
+        # Update an existing record in the model table
+        #
+        # Uses update_all() to bypass all callbacks.
+        def project_update(model_class, result)
+          event = result.events&.first
+          return unless event
+
+          model_id = event.data[:model_id] || event.data["model_id"]
+          changes = event.data[:changes] || event.data["changes"] || {}
+
+          return if changes.empty?
+
+          # Extract new values from changes (changes are [old_value, new_value] tuples)
+          # Use symbol keys consistently to avoid duplicate column errors
+          updates = {}
+          changes.each do |field, change|
+            new_value = change.is_a?(Array) ? change.last : change
+            updates[field.to_sym] = new_value
+          end
+
+          # Ensure updated_at timestamp (may already be in changes)
+          updates[:updated_at] ||= Time.current
+
+          # Use update_all to bypass callbacks
+          # Bypass strict data access - projections are legitimate bulk operations
+          previous = Thread.current[:lyra_bypass_strict_access]
+          Thread.current[:lyra_bypass_strict_access] = true
+          begin
+            model_class.where(id: model_id).update_all(updates)
+          ensure
+            Thread.current[:lyra_bypass_strict_access] = previous
+          end
+        end
+
+        # Delete a record from the model table
+        #
+        # Uses delete_all() to bypass callbacks and dependent destroy.
+        def project_destroy(model_class, result)
+          event = result.events&.first
+          return unless event
+
+          model_id = event.data[:model_id] || event.data["model_id"]
+
+          # Use delete_all to bypass callbacks
+          # Bypass strict data access - projections are legitimate bulk operations
+          previous = Thread.current[:lyra_bypass_strict_access]
+          Thread.current[:lyra_bypass_strict_access] = true
+          begin
+            model_class.where(id: model_id).delete_all
+          ensure
+            Thread.current[:lyra_bypass_strict_access] = previous
+          end
+        end
+
+        private
+
+        # Sanitize attributes for database insertion
+        #
+        # Removes attributes that don't correspond to database columns
+        # and ensures proper type conversion.
+        def sanitize_attributes(model_class, attributes)
+          column_names = model_class.column_names.map(&:to_s)
+
+          attributes.stringify_keys.slice(*column_names).tap do |attrs|
+            # Convert any special types
+            attrs.each do |key, value|
+              # Handle BigDecimal/Float precision
+              column = model_class.columns_hash[key]
+              if column&.type == :decimal && value.is_a?(Float)
+                attrs[key] = BigDecimal(value.to_s)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyra/schema/diff.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Schema
+    # Compares schemas and produces human-readable difference reports
+    class Diff
+      # Severity levels for different types of changes
+      SEVERITIES = {
+        model_added: :info,
+        model_removed: :breaking,
+        column_added: :info,
+        column_removed: :breaking,
+        column_type_changed: :breaking,
+        column_nullable_changed: :warning,
+        column_limit_changed: :warning,
+        pii_field_added: :warning,
+        pii_field_removed: :info,
+        event_name_changed: :breaking,
+        event_prefix_changed: :warning,
+        config_changed: :info
+      }.freeze
+
+      class << self
+        def compare(old_schema, new_schema)
+          new.compare(old_schema, new_schema)
+        end
+
+        def format_report(differences)
+          new.format_report(differences)
+        end
+      end
+
+      def compare(old_schema, new_schema)
+        differences = []
+
+        # Compare models (normalize keys to strings for comparison)
+        old_models = normalize_keys(old_schema[:models] || {})
+        new_models = normalize_keys(new_schema[:models] || {})
+
+        # Check for removed models
+        (old_models.keys - new_models.keys).each do |model_name|
+          differences << {
+            type: :model_removed,
+            severity: SEVERITIES[:model_removed],
+            model: model_name,
+            message: "Model '#{model_name}' was removed from monitoring"
+          }
+        end
+
+        # Check for added models
+        (new_models.keys - old_models.keys).each do |model_name|
+          differences << {
+            type: :model_added,
+            severity: SEVERITIES[:model_added],
+            model: model_name,
+            message: "Model '#{model_name}' was added to monitoring"
+          }
+        end
+
+        # Compare existing models
+        (old_models.keys & new_models.keys).each do |model_name|
+          differences += compare_model(
+            model_name,
+            old_models[model_name],
+            new_models[model_name]
+          )
+        end
+
+        # Compare configuration changes
+        differences += compare_configuration(
+          old_schema[:configuration] || {},
+          new_schema[:configuration] || {}
+        )
+
+        differences
+      end
+
+      def compare_model(model_name, old_model, new_model)
+        differences = []
+
+        # Access with string keys (models are already normalized)
+        old_prefix = old_model["event_prefix"]
+        new_prefix = new_model["event_prefix"]
+
+        # Compare event prefix
+        if old_prefix != new_prefix
+          differences << {
+            type: :event_prefix_changed,
+            severity: SEVERITIES[:event_prefix_changed],
+            model: model_name,
+            old_value: old_prefix,
+            new_value: new_prefix,
+            message: "#{model_name} event_prefix changed: '#{old_prefix}' -> '#{new_prefix}'"
+          }
+        end
+
+        # Compare columns
+        differences += compare_columns(model_name, old_model["columns"] || {}, new_model["columns"] || {})
+
+        # Compare events
+        differences += compare_events(model_name, old_model["events"] || {}, new_model["events"] || {})
+
+        differences
+      end
+
+      def compare_columns(model_name, old_columns, new_columns)
+        differences = []
+
+        # Removed columns
+        (old_columns.keys - new_columns.keys).each do |col_name|
+          differences << {
+            type: :column_removed,
+            severity: SEVERITIES[:column_removed],
+            model: model_name,
+            column: col_name,
+            message: "Column '#{col_name}' removed from #{model_name}"
+          }
+        end
+
+        # Added columns
+        (new_columns.keys - old_columns.keys).each do |col_name|
+          col_info = new_columns[col_name]
+          msg = "Column '#{col_name}' added to #{model_name}"
+          msg += " (PII: #{col_info["pii_type"]})" if col_info["pii"]
+
+          differences << {
+            type: :column_added,
+            severity: SEVERITIES[:column_added],
+            model: model_name,
+            column: col_name,
+            pii: col_info["pii"],
+            message: msg
+          }
+        end
+
+        # Changed columns
+        (old_columns.keys & new_columns.keys).each do |col_name|
+          differences += compare_column(model_name, col_name, old_columns[col_name], new_columns[col_name])
+        end
+
+        differences
+      end
+
+      def compare_column(model_name, col_name, old_col, new_col)
+        differences = []
+
+        # Use string keys (columns are already normalized)
+        old_type = old_col["type"]
+        new_type = new_col["type"]
+        old_nullable = old_col["nullable"]
+        new_nullable = new_col["nullable"]
+        old_limit = old_col["limit"]
+        new_limit = new_col["limit"]
+        old_pii = old_col["pii"]
+        new_pii = new_col["pii"]
+
+        # Type change
+        if old_type != new_type
+          differences << {
+            type: :column_type_changed,
+            severity: SEVERITIES[:column_type_changed],
+            model: model_name,
+            column: col_name,
+            old_value: old_type,
+            new_value: new_type,
+            message: "#{model_name}.#{col_name} type changed: #{old_type} -> #{new_type}"
+          }
+        end
+
+        # Nullable change
+        if old_nullable != new_nullable
+          differences << {
+            type: :column_nullable_changed,
+            severity: SEVERITIES[:column_nullable_changed],
+            model: model_name,
+            column: col_name,
+            old_value: old_nullable,
+            new_value: new_nullable,
+            message: "#{model_name}.#{col_name} nullable changed: #{old_nullable} -> #{new_nullable}"
+          }
+        end
+
+        # Limit change
+        if old_limit != new_limit
+          differences << {
+            type: :column_limit_changed,
+            severity: SEVERITIES[:column_limit_changed],
+            model: model_name,
+            column: col_name,
+            old_value: old_limit,
+            new_value: new_limit,
+            message: "#{model_name}.#{col_name} limit changed: #{old_limit} -> #{new_limit}"
+          }
+        end
+
+        # PII detection change
+        if old_pii != new_pii
+          type = new_pii ? :pii_field_added : :pii_field_removed
+          differences << {
+            type: type,
+            severity: SEVERITIES[type],
+            model: model_name,
+            column: col_name,
+            message: "#{model_name}.#{col_name} PII status changed: #{old_pii} -> #{new_pii}"
+          }
+        end
+
+        differences
+      end
+
+      def compare_events(model_name, old_events, new_events)
+        differences = []
+
+        # Check for event name changes (removed + added = renamed)
+        removed_events = old_events.keys - new_events.keys
+        added_events = new_events.keys - old_events.keys
+
+        # Detect renames by matching operations
+        removed_events.each do |old_name|
+          old_op = old_events[old_name]["operation"]
+
+          matching_new = added_events.find do |new_name|
+            new_events[new_name]["operation"] == old_op
+          end
+
+          if matching_new
+            differences << {
+              type: :event_name_changed,
+              severity: SEVERITIES[:event_name_changed],
+              model: model_name,
+              old_value: old_name,
+              new_value: matching_new,
+              operation: old_op,
+              message: "#{model_name} event renamed: #{old_name} -> #{matching_new}"
+            }
+            added_events.delete(matching_new)
+          end
+        end
+
+        differences
+      end
+
+      def compare_configuration(old_config, new_config)
+        differences = []
+
+        # Normalize to string keys for comparison
+        old_cfg = normalize_keys(old_config)
+        new_cfg = normalize_keys(new_config)
+
+        %w[mode strict_schema projection_mode].each do |key|
+          old_val = old_cfg[key]
+          new_val = new_cfg[key]
+
+          # Normalize values to strings for comparison
+          old_val_str = old_val.to_s if old_val
+          new_val_str = new_val.to_s if new_val
+
+          if old_val_str != new_val_str
+            differences << {
+              type: :config_changed,
+              severity: SEVERITIES[:config_changed],
+              key: key,
+              old_value: old_val,
+              new_value: new_val,
+              message: "Configuration '#{key}' changed: #{old_val} -> #{new_val}"
+            }
+          end
+        end
+
+        differences
+      end
+
+      def format_report(differences)
+        return "No schema changes detected." if differences.empty?
+
+        lines = ["Schema Changes Detected:"]
+        lines << "=" * 60
+
+        grouped = differences.group_by { |d| d[:severity] }
+
+        [:breaking, :warning, :info].each do |severity|
+          next unless grouped[severity]&.any?
+
+          lines << ""
+          icon = severity_icon(severity)
+          lines << "#{icon} #{severity.to_s.upcase} (#{grouped[severity].size}):"
+          lines << "-" * 40
+
+          grouped[severity].each do |diff|
+            lines << "  - #{diff[:message]}"
+          end
+        end
+
+        lines << ""
+        lines << "=" * 60
+
+        # Add action suggestions
+        if grouped[:breaking]&.any?
+          lines << ""
+          lines << "ACTION REQUIRED: Breaking changes detected."
+          lines << "Run 'rake lyra:schema:update' to create a new schema version."
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def severity_icon(severity)
+        case severity
+        when :breaking then "[!]"
+        when :warning then "[?]"
+        when :info then "[i]"
+        else "[ ]"
+        end
+      end
+
+      # Normalize hash keys to strings recursively for consistent comparison
+      def normalize_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_s).transform_values do |value|
+          case value
+          when Hash then normalize_keys(value)
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyra/schema/event_class_registrar.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Schema
+    # Registers event classes at Rails startup to ensure RailsEventStore
+    # can properly deserialize events. Without this, dynamically created
+    # event classes would not exist after app restart, causing
+    # Object.const_get() to fail during event deserialization.
+    class EventClassRegistrar
+      class << self
+        # Register all event classes from configuration and stored schema
+        def register_all
+          register_from_configuration
+          register_from_schema
+        end
+
+        # Get list of all registered event class names
+        def registered_events
+          Lyra::Events.constants(false).map(&:to_s)
+        end
+
+        private
+
+        # Register events for currently monitored models
+        def register_from_configuration
+          Lyra.config.monitored_models.each do |model_class|
+            config = Lyra.config.model_config(model_class)
+
+            [:created, :updated, :destroyed].each do |operation|
+              event_name = config.event_name_for(operation)
+              ensure_event_class_exists(event_name)
+            end
+          end
+        end
+
+        # Register events from stored schema (handles legacy/removed models)
+        def register_from_schema
+          return unless Store.exists?
+
+          schema = Store.load_current
+          return unless schema && schema[:models]
+
+          schema[:models].each_value do |model_schema|
+            events = model_schema[:events] || model_schema["events"] || {}
+            events.each_key do |event_name|
+              ensure_event_class_exists(event_name.to_s)
+            end
+          end
+        end
+
+        def ensure_event_class_exists(event_name)
+          # Sanitize namespaced event names (e.g., "Spree::OrderCreated" -> "SpreeOrderCreated")
+          # Ruby const_set doesn't accept "::" in constant names
+          sanitized_name = event_name.to_s.gsub("::", "")
+
+          return if Lyra::Events.const_defined?(sanitized_name, false)
+
+          Lyra::Events.const_set(sanitized_name, Class.new(Lyra::Event))
+        end
+      end
+    end
+  end
+end