orfeas_lyra 0.6.0

data/lib/lyra/aggregate.rb

@@ -0,0 +1,131 @@
+module Lyra
+  # Base aggregate class for event sourcing
+  class Aggregate
+    attr_reader :id, :version, :changes
+
+    def initialize(id = nil)
+      @id = id
+      @version = 0
+      @changes = []
+      @state = {}
+    end
+
+    # Load aggregate from event stream
+    def self.load(id, event_store = nil)
+      event_store ||= Lyra.config.event_store
+      aggregate = new(id)
+
+      stream_name = aggregate.stream_name
+      events = event_store.read.stream(stream_name).to_a
+
+      events.each { |event| aggregate.apply(event, persisted: true) }
+      aggregate
+    rescue RailsEventStore::EventNotFound
+      new(id)
+    end
+
+    # Apply an event to the aggregate
+    def apply(event, persisted: false)
+      method_name = "apply_#{event.class.name.demodulize.underscore}"
+
+      if respond_to?(method_name, true)
+        send(method_name, event)
+        @version += 1 if persisted
+        @changes << event unless persisted
+      end
+    end
+
+    # Store pending changes to event store
+    def store(event_store = nil)
+      return if @changes.empty?
+
+      event_store ||= Lyra.config.event_store
+
+      @changes.each do |event|
+        event_store.publish(event, stream_name: stream_name)
+      end
+
+      @changes.clear
+    end
+
+    def stream_name
+      "#{self.class.name.demodulize}$#{id}"
+    end
+
+    protected
+
+    attr_reader :state
+
+    def set_state(key, value)
+      @state[key] = value
+    end
+
+    def get_state(key)
+      @state[key]
+    end
+  end
+
+  # Generic aggregate for monitored models
+  class GenericAggregate < Aggregate
+    def initialize(id = nil, model_class = nil)
+      super(id)
+      @model_class = model_class
+    end
+
+    def stream_name
+      "#{@model_class.name}$#{id}"
+    end
+
+    # Override apply to handle dynamic event class names (e.g., RegistrationCreated -> apply_created)
+    def apply(event, persisted: false)
+      event_name = event.class.name.demodulize.underscore
+
+      # Extract operation from event name (e.g., "registration_created" -> "created")
+      operation = extract_operation(event_name)
+      method_name = "apply_#{operation}"
+
+      if respond_to?(method_name, true)
+        send(method_name, event)
+        @version += 1 if persisted
+        @changes << event unless persisted
+      end
+    end
+
+    private
+
+    def extract_operation(event_name)
+      # Match common operation suffixes
+      case event_name
+      when /_created$/
+        "created"
+      when /_updated$/
+        "updated"
+      when /_destroyed$/, /_deleted$/
+        "destroyed"
+      else
+        event_name
+      end
+    end
+
+    def apply_created(event)
+      @id = event.data[:model_id] rescue event.model_id
+      attrs = event.data[:attributes] rescue event.attributes
+      attrs&.each { |k, v| set_state(k, v) }
+    end
+
+    def apply_updated(event)
+      changes = event.data[:changes] rescue event.changes
+      changes&.each do |key, value|
+        # Handle both [old, new] arrays and direct values
+        new_val = value.is_a?(Array) ? value.last : value
+        set_state(key, new_val)
+      end
+    end
+
+    def apply_destroyed(event)
+      set_state(:deleted, true)
+      timestamp = event.data[:timestamp] rescue event.timestamp rescue Time.current
+      set_state(:deleted_at, timestamp)
+    end
+  end
+end

data/lib/lyra/associations/event_aware.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Associations
+    # Event-aware association module for handling eventual consistency.
+    #
+    # In event_sourcing mode, associated records may not exist in the database
+    # yet if projections are async. This module provides event-aware versions
+    # of Rails associations that fall back to event reconstruction when needed.
+    #
+    # Usage in models:
+    #   class Registration < ApplicationRecord
+    #     include Lyra::Associations::EventAware
+    #
+    #     event_aware_belongs_to :program
+    #     event_aware_has_many :payment_transactions
+    #   end
+    #
+    module EventAware
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Event-aware belongs_to association
+        #
+        # Tries database first, falls back to event reconstruction if not found.
+        #
+        # @param name [Symbol] Association name
+        # @param options [Hash] Standard belongs_to options plus:
+        #   - class_name: Override the class name
+        #   - foreign_key: Override the foreign key
+        def event_aware_belongs_to(name, **options)
+          foreign_key = options[:foreign_key] || "#{name}_id"
+          class_name = (options[:class_name] || name.to_s.camelize).to_s
+
+          define_method(name) do
+            fk_value = send(foreign_key)
+            return nil if fk_value.nil?
+
+            # Try database first (fast path)
+            associated = class_name.constantize.find_by(id: fk_value)
+            return associated if associated
+
+            # Fall back to event store reconstruction (slow path)
+            return nil unless Lyra.event_sourcing_mode?
+
+            EventReconstructor.reconstruct(class_name.constantize, fk_value)
+          end
+
+          define_method("#{name}=") do |value|
+            send("#{foreign_key}=", value&.id)
+          end
+        end
+
+        # Event-aware has_many association
+        #
+        # Queries database and optionally includes pending records from events.
+        #
+        # @param name [Symbol] Association name (plural)
+        # @param options [Hash] Options including:
+        #   - class_name: Override the class name
+        #   - foreign_key: Override the foreign key
+        def event_aware_has_many(name, **options)
+          foreign_key = options[:foreign_key] || "#{model_name.singular}_id"
+          class_name = (options[:class_name] || name.to_s.singularize.camelize).to_s
+
+          define_method(name) do
+            model_id = id
+            return [] unless model_id
+
+            # Query database
+            db_records = class_name.constantize.where(foreign_key => model_id)
+
+            # In event_sourcing mode with async projections, include pending records
+            if Lyra.event_sourcing_mode? && Lyra.config.projection_mode == :async
+              pending = PendingRecords.for(class_name.constantize, foreign_key, model_id)
+              (db_records.to_a + pending).uniq(&:id)
+            else
+              db_records
+            end
+          end
+        end
+      end
+    end
+
+    # Reconstructs a record from its event stream
+    class EventReconstructor
+      class << self
+        # Reconstruct a record's current state from events
+        #
+        # @param model_class [Class] The model class
+        # @param id [Integer, String] The record ID
+        # @return [VirtualRecord, nil] A virtual record or nil if not found/deleted
+        def reconstruct(model_class, id)
+          stream_name = "#{model_class.name}$#{id}"
+
+          begin
+            events = Lyra.config.event_store.read.stream(stream_name).to_a
+          rescue StandardError
+            return nil
+          end
+
+          return nil if events.empty?
+
+          # Replay events to build current state
+          state = replay_events(events)
+
+          return nil if state[:deleted]
+
+          VirtualRecord.new(model_class, id, state)
+        end
+
+        private
+
+        def replay_events(events)
+          state = { deleted: false }
+
+          events.each do |event|
+            data = event.data.is_a?(Hash) ? event.data : {}
+            operation = data[:operation] || data["operation"]
+
+            case operation&.to_sym
+            when :created
+              state.merge!(data[:attributes] || data["attributes"] || {})
+            when :updated
+              changes = data[:changes] || data["changes"] || {}
+              changes.each do |field, change|
+                new_value = change.is_a?(Array) ? change.last : change
+                state[field.to_sym] = new_value
+              end
+            when :destroyed
+              state[:deleted] = true
+            end
+          end
+
+          state
+        end
+      end
+    end
+
+    # Finds records that exist in events but not yet in the database
+    class PendingRecords
+      class << self
+        # Find pending records for a has_many association
+        #
+        # @param model_class [Class] The associated model class
+        # @param foreign_key [String] The foreign key field
+        # @param parent_id [Integer, String] The parent record ID
+        # @return [Array<VirtualRecord>] Array of virtual records
+        def for(model_class, foreign_key, parent_id)
+          # This is a simplified implementation
+          # A production version would need to track pending events more efficiently
+          []
+        end
+      end
+    end
+
+    # Virtual record representing a record from events (not in DB)
+    #
+    # Provides a read-only interface that looks like an ActiveRecord model
+    # but is backed by event data instead of a database row.
+    class VirtualRecord
+      attr_reader :id
+
+      def initialize(model_class, id, state)
+        @model_class = model_class
+        @id = id
+        @state = state.transform_keys(&:to_sym)
+      end
+
+      def persisted?
+        false
+      end
+
+      def new_record?
+        true
+      end
+
+      # Indicates this is a virtual record from events
+      def pending_projection?
+        true
+      end
+
+      def readonly?
+        true
+      end
+
+      # Access attributes
+      def [](key)
+        @state[key.to_sym]
+      end
+
+      def attributes
+        @state.except(:deleted)
+      end
+
+      def to_param
+        id&.to_s
+      end
+
+      def method_missing(method, *args)
+        method_name = method.to_s
+
+        # Getter
+        if @state.key?(method)
+          @state[method]
+        # Boolean query
+        elsif method_name.end_with?("?")
+          field = method_name.chomp("?").to_sym
+          !!@state[field]
+        # Setter (rejected - read only)
+        elsif method_name.end_with?("=")
+          raise ReadOnlyRecord, "Cannot modify a virtual record"
+        else
+          nil
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @state.key?(method) || method.to_s.end_with?("?") || super
+      end
+
+      class ReadOnlyRecord < StandardError; end
+    end
+  end
+end

data/lib/lyra/command.rb

@@ -0,0 +1,81 @@
+module Lyra
+  # Base command class
+  class Command
+    attr_reader :model_class, :data
+
+    def initialize(model_class, data = {})
+      @model_class = model_class
+      @data = data
+    end
+
+    def aggregate_id
+      data[:id] || data['id']
+    end
+  end
+
+  module Commands
+    class CreateCommand < Command
+      def initialize(model_class, attributes)
+        super(model_class, attributes)
+      end
+
+      def attributes
+        data
+      end
+    end
+
+    class UpdateCommand < Command
+      def initialize(model_class, id, changes)
+        super(model_class, id: id, changes: changes)
+      end
+
+      def id
+        data[:id]
+      end
+
+      def changes
+        data[:changes]
+      end
+    end
+
+    class DestroyCommand < Command
+      def initialize(model_class, id)
+        super(model_class, id: id)
+      end
+
+      def id
+        data[:id]
+      end
+    end
+  end
+
+  # Command result
+  class CommandResult
+    attr_reader :success, :attributes, :error, :events
+
+    def initialize(success:, attributes: {}, error: nil, events: [])
+      @success = success
+      @attributes = attributes
+      @error = error
+      @events = events
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !success?
+    end
+
+    class << self
+      def success(attributes: {}, events: [])
+        new(success: true, attributes: attributes, events: events)
+      end
+
+      def failure(error:)
+        new(success: false, error: error)
+      end
+    end
+  end
+end

data/lib/lyra/command_handler.rb

@@ -0,0 +1,155 @@
+module Lyra
+  # Command handler for processing commands in hijack mode
+  class CommandHandler
+    class << self
+      def handle(command)
+        handler = new(command)
+        handler.call
+      end
+    end
+
+    attr_reader :command
+
+    def initialize(command)
+      @command = command
+    end
+
+    def call
+      case command
+      when Commands::CreateCommand
+        handle_create
+      when Commands::UpdateCommand
+        handle_update
+      when Commands::DestroyCommand
+        handle_destroy
+      else
+        CommandResult.failure(error: "Unknown command type")
+      end
+    rescue => e
+      CommandResult.failure(error: e.message)
+    end
+
+    private
+
+    def handle_create
+      model_class = command.model_class
+
+      # Generate ID for new aggregate
+      # In event_sourcing mode, we MUST pre-generate IDs since we abort the DB save
+      # In hijack mode, only UUID keys need pre-generation (integers come from DB)
+      id = if Lyra.event_sourcing_mode?
+        # Always pre-generate in event_sourcing mode
+        IdGenerator.next_id(model_class)
+      elsif model_class.columns_hash[model_class.primary_key]&.type == :uuid
+        SecureRandom.uuid
+      else
+        # For integer primary keys in hijack mode, use a temporary placeholder
+        # The actual ID will be assigned by the database after save
+        "pending-#{SecureRandom.hex(8)}"
+      end
+
+      # Create aggregate
+      aggregate_class = find_aggregate_class
+      aggregate = aggregate_class.new(id, command.model_class)
+
+      # Create event with pre-generated ID
+      # Use symbolize_keys for consistent key types in event data
+      event_attrs = command.attributes.symbolize_keys.merge(id: id)
+      event = create_event(:created, id, event_attrs)
+
+      # Apply event to aggregate
+      aggregate.apply(event)
+
+      # Store events
+      # In event_sourcing mode, defer storage until after throw(:abort) completes
+      # (storing inside the callback would be rolled back with the transaction)
+      unless Lyra.event_sourcing_mode?
+        aggregate.store(Lyra.config.event_store)
+      end
+
+      # Return result with ID
+      # In event_sourcing mode, always include ID (it's pre-generated)
+      # In hijack mode, only include for UUID (integers come from DB)
+      attributes = command.attributes.dup
+      # Remove string "id" key to prevent conflict with symbol :id
+      # (AR attributes have string keys, but we add symbol keys)
+      attributes.delete("id")
+      if Lyra.event_sourcing_mode? || model_class.columns_hash[model_class.primary_key]&.type == :uuid
+        attributes[:id] = id
+      end
+      CommandResult.success(attributes: attributes, events: [event])
+    end
+
+    def handle_update
+      # Load aggregate (or create new one for records without event history)
+      aggregate_class = find_aggregate_class
+      aggregate = aggregate_class.load(command.id, Lyra.config.event_store) rescue aggregate_class.new(command.id, command.model_class)
+
+      # Create event
+      event = create_event(:updated, command.id, { changes: command.changes })
+
+      # Apply event to aggregate
+      aggregate.apply(event)
+
+      # Store events (defer in event_sourcing mode)
+      unless Lyra.event_sourcing_mode?
+        aggregate.store(Lyra.config.event_store)
+      end
+
+      CommandResult.success(events: [event])
+    end
+
+    def handle_destroy
+      # Load aggregate (or create new one for records without event history)
+      aggregate_class = find_aggregate_class
+      aggregate = aggregate_class.load(command.id, Lyra.config.event_store) rescue aggregate_class.new(command.id, command.model_class)
+
+      # Create event
+      event = create_event(:destroyed, command.id, {})
+
+      # Apply event to aggregate
+      aggregate.apply(event)
+
+      # Store events (defer in event_sourcing mode)
+      unless Lyra.event_sourcing_mode?
+        aggregate.store(Lyra.config.event_store)
+      end
+
+      CommandResult.success(events: [event])
+    end
+
+    def create_event(operation, id, data)
+      event_data = {
+        model_class: command.model_class.name,
+        model_id: id,
+        operation: operation,
+        attributes: data[:attributes] || data,
+        changes: data[:changes] || {},
+        timestamp: Time.current
+      }
+
+      event_metadata = {
+        source: 'lyra_command_handler',
+        correlation_id: Lyra::Correlation.current_id,
+        causation_id: Lyra::Causation.current_id
+      }
+
+      config = Lyra.config.model_config(command.model_class)
+      event_name = config.event_name_for(operation)
+
+      # Find or create the event class in Lyra::Events namespace
+      event_class = if Lyra::Events.const_defined?(event_name, false)
+        Lyra::Events.const_get(event_name, false)
+      else
+        Lyra::Events.const_set(event_name, Class.new(Lyra::Event))
+      end
+
+      event_class.new(data: event_data, metadata: event_metadata)
+    end
+
+    def find_aggregate_class
+      config = Lyra.config.model_config(command.model_class)
+      config.aggregate_class || Lyra::GenericAggregate
+    end
+  end
+end

data/lib/lyra/configuration.rb

@@ -0,0 +1,124 @@
+module Lyra
+  class Configuration
+    # Valid modes for Lyra operation
+    MODES = [:disabled, :monitor, :hijack, :event_sourcing].freeze
+
+    attr_accessor :mode, :event_store, :event_backend, :hijack_enabled, :retention_policy
+    attr_accessor :projection_mode, :strict_projections, :projection_error_handler, :async_projections_inline
+    attr_accessor :strict_schema, :schema_path
+    attr_accessor :strict_data_access  # Raise on callback-bypassing operations
+    attr_accessor :metadata_proc  # Custom metadata proc for events
+    attr_reader :monitored_models
+
+    def initialize
+      @mode = :monitor
+      @event_backend = :rails_event_store
+      @hijack_enabled = false
+      @monitored_models = []
+      @model_configs = {}
+      @retention_policy = nil
+      # Event sourcing specific options
+      @projection_mode = :sync  # :sync, :async, or :disabled
+      @strict_projections = false  # Raise on projection errors if true
+      @projection_error_handler = nil  # Custom error handler proc
+      @async_projections_inline = false  # Run async projections synchronously (useful for testing)
+      # Schema validation options
+      @strict_schema = false  # Fail on startup if schema changes detected
+      @schema_path = nil  # Custom path for schema files (defaults to db/lyra_schemas/)
+      # Strict data access - raise on operations that bypass callbacks
+      @strict_data_access = false
+      # User tracking - custom metadata proc called for every event
+      # Signature: ->(record, operation) { { user_id: ..., ... } }
+      @metadata_proc = nil
+    end
+
+    # Register a model for monitoring/hijacking
+    def monitor_model(model_class, options = {})
+      # Check by name to handle Rails development reloading (class objects change on reload)
+      model_name = begin
+        model_class.name
+      rescue StandardError
+        model_class.object_id.to_s
+      end
+
+      unless @monitored_models.any? { |m| (m.name rescue m.object_id.to_s) == model_name }
+        @monitored_models << model_class
+      else
+        # Update the reference to the new class object (after reload)
+        @monitored_models.map! { |m| (m.name rescue m.object_id.to_s) == model_name ? model_class : m }
+      end
+      @model_configs[model_class] = ModelConfiguration.new(model_class, options)
+    end
+
+    def model_config(model_class)
+      @model_configs[model_class] || ModelConfiguration.new(model_class)
+    end
+
+    def monitor_mode?
+      @mode == :monitor
+    end
+
+    def hijack_mode?
+      @mode == :hijack || @hijack_enabled
+    end
+
+    def event_sourcing_mode?
+      @mode == :event_sourcing
+    end
+
+    def disabled_mode?
+      @mode == :disabled
+    end
+
+    # Enable hijack mode (can override CRUD operations)
+    def enable_hijack!
+      @hijack_enabled = true
+      @mode = :hijack
+    end
+
+    # Enable monitor mode (only log events, don't override)
+    def enable_monitor!
+      @hijack_enabled = false
+      @mode = :monitor
+    end
+
+    # Enable event sourcing mode (events as source of truth, no direct DB writes)
+    def enable_event_sourcing!
+      @mode = :event_sourcing
+      @hijack_enabled = false
+    end
+
+    # Disable Lyra completely
+    def disable!
+      @mode = :disabled
+      @hijack_enabled = false
+    end
+  end
+
+  class ModelConfiguration
+    attr_accessor :event_prefix, :aggregate_class, :command_handler, :privacy_policy
+    attr_reader :model_class
+
+    def initialize(model_class, options = {})
+      @model_class = model_class
+      @event_prefix = options[:event_prefix] || model_class.name
+      @aggregate_class = options[:aggregate_class]
+      @command_handler = options[:command_handler]
+      @custom_event_mapping = options[:event_mapping] || {}
+      @privacy_policy = options[:privacy_policy]
+    end
+
+    def event_name_for(operation)
+      @custom_event_mapping[operation] || "#{event_prefix}#{operation.to_s.camelize}"
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Reset configuration (useful for testing)
+  def self.reset_config!
+    @config = Configuration.new
+  end
+end