orfeas_lyra 0.6.0

data/lib/lyra/consistency/read_your_writes.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Lyra
+  module Consistency
+    # Read-Your-Writes consistency helper for event_sourcing mode.
+    #
+    # When using async projections, there's a window where a record might
+    # exist in the event store but not yet in the database. This helper
+    # ensures that within a block, any writes are immediately projected
+    # before reads happen.
+    #
+    # Usage:
+    #   Lyra::Consistency::ReadYourWrites.with_guaranteed_read do
+    #     @registration = Registration.create!(params)
+    #     redirect_to @registration  # Guaranteed to find it
+    #   end
+    #
+    module ReadYourWrites
+      class << self
+        # Execute block with read-your-writes guarantee
+        #
+        # Tracks any writes within the block and ensures they are
+        # projected before the block returns.
+        def with_guaranteed_read
+          return yield unless Lyra.event_sourcing_mode?
+
+          # Store pending writes in thread-local storage
+          Thread.current[:lyra_pending_writes] = []
+
+          begin
+            result = yield
+            ensure_projected
+            result
+          ensure
+            Thread.current[:lyra_pending_writes] = nil
+          end
+        end
+
+        # Record a write that needs projection (called by interceptor)
+        def record_write(model_class, operation, result)
+          pending = Thread.current[:lyra_pending_writes]
+          return unless pending
+
+          pending << { model_class: model_class, operation: operation, result: result }
+        end
+
+        # Check if we're in a guaranteed read block
+        def in_guaranteed_block?
+          !Thread.current[:lyra_pending_writes].nil?
+        end
+
+        private
+
+        # Ensure all pending writes are projected
+        def ensure_projected
+          pending = Thread.current[:lyra_pending_writes] || []
+
+          pending.each do |write|
+            Lyra::Projections::ModelProjection.project(
+              write[:model_class],
+              write[:operation],
+              write[:result]
+            )
+          rescue => e
+            Rails.logger.error("Lyra: Failed to ensure projection - #{e.message}")
+            raise if Lyra.config.strict_projections
+          end
+        end
+      end
+    end
+
+    # Controller concern for automatic read-your-writes handling
+    module ControllerConcern
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :with_lyra_consistency, if: :lyra_consistency_enabled?
+      end
+
+      private
+
+      def with_lyra_consistency
+        ReadYourWrites.with_guaranteed_read { yield }
+      end
+
+      def lyra_consistency_enabled?
+        Lyra.event_sourcing_mode? && Lyra.config.projection_mode == :async
+      end
+    end
+  end
+end

data/lib/lyra/correlation.rb

@@ -0,0 +1,144 @@
+module Lyra
+  # Correlation system for grouping related operations and events
+  # correlation_id: Groups all events from the same user action (e.g., all events from one HTTP request)
+  class Correlation
+    class << self
+      # Generate a unique correlation ID for a group of operations
+      def generate_id
+        "corr_#{Time.now.to_i}_#{SecureRandom.hex(8)}"
+      end
+
+      # Current correlation ID (thread-safe)
+      def current_id
+        Thread.current[:lyra_correlation_id]
+      end
+
+      # Set correlation ID for current context
+      def with_id(correlation_id = nil)
+        correlation_id ||= generate_id
+        previous_id = Thread.current[:lyra_correlation_id]
+        Thread.current[:lyra_correlation_id] = correlation_id
+
+        yield correlation_id if block_given?
+      ensure
+        Thread.current[:lyra_correlation_id] = previous_id
+      end
+    end
+  end
+
+  # Causation system for tracking event chains
+  # causation_id: Points to the specific event that directly caused this event (parent-child relationship)
+  #
+  # Example:
+  #   OrderPlaced (causation_id: nil)           <- root event
+  #     └── PaymentProcessed (causation_id: OrderPlaced.id)
+  #           └── InventoryReserved (causation_id: PaymentProcessed.id)
+  #
+  class Causation
+    class << self
+      # Current causation ID (the event that caused the current operation)
+      def current_id
+        Thread.current[:lyra_causation_id]
+      end
+
+      # Set causation ID for current context (when processing/handling an event)
+      def with_id(causation_id)
+        previous_id = Thread.current[:lyra_causation_id]
+        Thread.current[:lyra_causation_id] = causation_id
+
+        yield causation_id if block_given?
+      ensure
+        Thread.current[:lyra_causation_id] = previous_id
+      end
+
+      # Clear causation (for root events)
+      def clear
+        Thread.current[:lyra_causation_id] = nil
+      end
+
+      # Track causation relationship (for building causation chains)
+      def track(cause_event_id, effect_event_id)
+        causation_store[effect_event_id] = cause_event_id
+      end
+
+      # Get the full causation chain for an event (root -> ... -> event)
+      def chain_for(event_id)
+        chain = [event_id]
+        current = event_id
+
+        while (parent = causation_store[current])
+          chain.unshift(parent)
+          current = parent
+          break if chain.size > 100 # Prevent infinite loops
+        end
+
+        chain
+      end
+
+      # Get direct cause of an event
+      def cause_of(event_id)
+        causation_store[event_id]
+      end
+
+      private
+
+      def causation_store
+        @causation_store ||= {}
+      end
+    end
+  end
+
+  # User action context for tracking what user action triggered events
+  class UserActionContext
+    attr_reader :action_id, :user_id, :action_type, :controller, :action_name, :params
+
+    def initialize(action_type:, user_id: nil, controller: nil, action_name: nil, params: {})
+      @action_id = "action_#{Time.now.to_i}_#{SecureRandom.hex(6)}"
+      @action_type = action_type  # :web_request, :api_call, :background_job, :console
+      @user_id = user_id
+      @controller = controller
+      @action_name = action_name
+      @params = sanitize_params(params)
+      @started_at = Time.current
+    end
+
+    def to_h
+      {
+        action_id: action_id,
+        action_type: action_type,
+        user_id: user_id,
+        controller: controller,
+        action_name: action_name,
+        params: params,
+        started_at: @started_at
+      }
+    end
+
+    class << self
+      def current
+        Thread.current[:lyra_user_action_context]
+      end
+
+      def with_context(action_type:, user_id: nil, **options)
+        context = new(action_type: action_type, user_id: user_id, **options)
+        previous = Thread.current[:lyra_user_action_context]
+        Thread.current[:lyra_user_action_context] = context
+
+        # Also set correlation ID
+        Lyra::Correlation.with_id(context.action_id) do
+          yield context if block_given?
+        end
+      ensure
+        Thread.current[:lyra_user_action_context] = previous
+      end
+    end
+
+    private
+
+    def sanitize_params(params)
+      # Remove sensitive parameters
+      sensitive_keys = [:password, :password_confirmation, :token, :secret, :api_key]
+      params.except(*sensitive_keys)
+    end
+  end
+end

data/lib/lyra/dual_view.rb

@@ -0,0 +1,231 @@
+module Lyra
+  # Provides dual view comparison between CRUD state and Event-sourced state
+  class DualView
+    attr_reader :model_class, :model_id
+
+    def initialize(model_class, model_id)
+      @model_class = model_class
+      @model_id = model_id
+    end
+
+    # Get both CRUD and Event-sourced views
+    def compare
+      {
+        crud_view: crud_state,
+        event_sourced_view: event_sourced_state,
+        differences: calculate_differences,
+        metadata: {
+          model_class: model_class.name,
+          model_id: model_id,
+          timestamp: Time.current,
+          mode: Lyra.config.mode
+        }
+      }
+    end
+
+    # CRUD view - current database state
+    def crud_state
+      record = model_class.find_by(id: model_id)
+
+      return { exists: false } unless record
+
+      {
+        exists: true,
+        attributes: record.attributes,
+        timestamps: {
+          created_at: record.created_at,
+          updated_at: record.updated_at
+        }
+      }
+    end
+
+    # Event-sourced view - state rebuilt from events
+    def event_sourced_state
+      stream_name = "#{model_class.name}$#{model_id}"
+
+      begin
+        events = Lyra.config.event_store.read.stream(stream_name).to_a
+      rescue => e
+        return {
+          exists: false,
+          error: e.message,
+          events_count: 0
+        }
+      end
+
+      return { exists: false, events_count: 0 } if events.empty?
+
+      state = StateProjection.new.rebuild_from_events(events)
+
+      {
+        exists: true,
+        state: state,
+        events_count: events.count,
+        first_event_at: event_timestamp(events.first),
+        last_event_at: event_timestamp(events.last),
+        events_summary: events.map { |e| { type: e.class.name, operation: event_operation(e), timestamp: event_timestamp(e) } }
+      }
+    end
+
+    # Helper methods to extract data from events (works with both Lyra::Event and RubyEventStore::Event)
+    def event_timestamp(event)
+      return event.timestamp if event.respond_to?(:timestamp) && event.timestamp
+      event.data[:timestamp] || event.data["timestamp"] || event.metadata[:timestamp]
+    end
+
+    def event_operation(event)
+      return event.operation if event.respond_to?(:operation)
+      op = event.data[:operation] || event.data["operation"]
+      op.is_a?(String) ? op.to_sym : op
+    end
+
+    # Calculate differences between CRUD and Event-sourced states
+    def calculate_differences
+      crud = crud_state
+      es = event_sourced_state
+
+      return { exists_mismatch: true } if crud[:exists] != es[:exists]
+      return { no_differences: true } if !crud[:exists] && !es[:exists]
+
+      crud_attrs = crud[:attributes] || {}
+      es_attrs = es[:state] || {}
+
+      differences = {}
+
+      # Build lookup tables with both string and symbol keys
+      crud_lookup = build_key_lookup(crud_attrs)
+      es_lookup = build_key_lookup(es_attrs)
+
+      # Compare union of all keys from both sources, excluding DB-managed timestamps
+      ignored_keys = %i[created_at updated_at]
+      all_keys = (crud_lookup.keys + es_lookup.keys).uniq - ignored_keys
+
+      all_keys.each do |key|
+        crud_val = crud_lookup[key]
+        es_val = es_lookup[key]
+
+        unless values_equal?(crud_val, es_val)
+          differences[key] = {
+            crud: crud_val,
+            event_sourced: es_val
+          }
+        end
+      end
+
+      differences.empty? ? { no_differences: true } : differences
+    end
+
+    # Get audit trail from events
+    def audit_trail
+      AuditProjection.audit_trail(model_class, model_id)
+    end
+
+    private
+
+    # Build a normalized lookup table from attributes hash
+    # Converts all keys to symbols for consistent access
+    def build_key_lookup(attrs)
+      result = {}
+      attrs.each do |key, val|
+        result[key.to_sym] = val
+      end
+      result
+    end
+
+    # Compare values with type coercion for common mismatches
+    def values_equal?(crud_val, es_val)
+      return true if crud_val == es_val
+      return true if crud_val.nil? && es_val.nil?
+      return false if crud_val.nil? || es_val.nil?
+
+      # Normalize for comparison
+      normalized_crud = normalize_value(crud_val)
+      normalized_es = normalize_value(es_val)
+
+      normalized_crud == normalized_es
+    end
+
+    def normalize_value(val)
+      case val
+      when Time, DateTime, ActiveSupport::TimeWithZone
+        val.utc.iso8601
+      when Date
+        val.iso8601
+      when BigDecimal
+        val.to_f.round(6)
+      when Float
+        val.round(6)
+      when Integer
+        val.to_f
+      when String
+        # Try to parse as time if it looks like a timestamp
+        if val =~ /^\d{4}-\d{2}-\d{2}(T|\s)/
+          begin
+            Time.parse(val).utc.iso8601
+          rescue
+            val
+          end
+        # Try to parse as number if it looks numeric
+        elsif val =~ /^-?\d+\.?\d*$/
+          val.to_f.round(6)
+        else
+          val
+        end
+      when TrueClass, FalseClass
+        val
+      when NilClass
+        nil
+      else
+        val.to_s
+      end
+    end
+
+    # Class methods for batch comparison
+    class << self
+      def compare_all(model_class)
+        model_class.find_each.map do |record|
+          new(model_class, record.id).compare
+        end
+      end
+
+      def find_discrepancies(model_class)
+        compare_all(model_class).select do |comparison|
+          comparison[:differences] != { no_differences: true }
+        end
+      end
+    end
+  end
+
+  # Analysis tools
+  class StateAnalyzer
+    def self.analyze(model_class, model_id)
+      view = DualView.new(model_class, model_id)
+
+      {
+        comparison: view.compare,
+        audit_trail: view.audit_trail,
+        recommendations: generate_recommendations(view)
+      }
+    end
+
+    def self.generate_recommendations(view)
+      comparison = view.compare
+      recommendations = []
+
+      if comparison[:differences][:exists_mismatch]
+        recommendations << "State existence mismatch - investigate data consistency"
+      end
+
+      if comparison[:differences] != { no_differences: true } && !comparison[:differences][:exists_mismatch]
+        recommendations << "Attribute differences detected - consider which source is authoritative"
+        recommendations << "Differences: #{comparison[:differences].keys.join(', ')}"
+      end
+
+      if comparison[:event_sourced_view][:events_count] == 0 && comparison[:crud_view][:exists]
+        recommendations << "CRUD record exists but no events found - may have been created before Lyra was enabled"
+      end
+
+      recommendations
+    end
+  end
+end

data/lib/lyra/engine.rb

@@ -0,0 +1,67 @@
+module Lyra
+  # Only define Engine when Rails is available
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+      isolate_namespace Lyra
+
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      initializer "lyra.configure_rails_initialization" do
+        # Initialize Event Store
+        Lyra.event_store ||= RailsEventStore::Client.new
+      end
+
+      initializer "lyra.inject_interceptors", after: :load_config_initializers do
+        ActiveSupport.on_load(:active_record) do
+          require "lyra/interceptors/crud_interceptor"
+          include Lyra::Interceptors::CrudInterceptor
+        end
+      end
+
+      # Install association interceptor for disabled projections mode
+      # Must run after active_record is loaded
+      initializer "lyra.install_association_interceptor", after: "lyra.inject_interceptors" do
+        ActiveSupport.on_load(:active_record) do
+          require "lyra/interceptors/association_interceptor"
+          Lyra::Interceptors::AssociationInterceptor.install!
+        end
+      end
+
+      # Install strict data access relation extension for update_all/delete_all
+      # This intercepts bulk operations on relations (Model.where(...).update_all)
+      initializer "lyra.install_strict_data_access", after: "lyra.inject_interceptors" do
+        ActiveSupport.on_load(:active_record) do
+          ActiveRecord::Relation.prepend(Lyra::StrictDataAccessRelation)
+        end
+      end
+
+      # Register event classes at startup for RailsEventStore deserialization
+      # This ensures Object.const_get() works when reading events from the store
+      initializer "lyra.register_event_classes", after: :load_config_initializers do
+        config.after_initialize do
+          next unless Lyra.config.monitored_models.any?
+
+          Lyra::Schema::EventClassRegistrar.register_all
+        end
+      end
+
+      # Schema validation on startup (after event classes are registered)
+      initializer "lyra.verify_schema", after: "lyra.register_event_classes" do
+        config.after_initialize do
+          next unless Lyra.config.monitored_models.any?
+          next unless Lyra.config.strict_schema
+
+          validator = Lyra::Schema::Validator.new
+          validator.enforce! if validator.schema_exists?
+        end
+      end
+
+      # Load rake tasks
+      rake_tasks do
+        load "tasks/lyra_schema.rake"
+      end
+    end
+  end
+end

data/lib/lyra/event.rb

@@ -0,0 +1,71 @@
+module Lyra
+  # Base event class for all Lyra events
+  class Event < RailsEventStore::Event
+    def self.inherited(subclass)
+      super
+      # Auto-register event types
+      Lyra::EventRegistry.register(subclass)
+    end
+
+    # Accessor methods that handle both symbol and string keys
+    # (JSON serializer converts symbols to strings)
+    def model_class
+      data[:model_class] || data["model_class"]
+    end
+
+    def model_id
+      data[:model_id] || data["model_id"]
+    end
+
+    def operation
+      op = data[:operation] || data["operation"]
+      op.is_a?(String) ? op.to_sym : op
+    end
+
+    def attributes
+      data[:attributes] || data["attributes"] || {}
+    end
+
+    def changes
+      data[:changes] || data["changes"] || {}
+    end
+
+    def timestamp
+      data[:timestamp] || data["timestamp"] || metadata[:timestamp]
+    end
+
+    def user_id
+      # user_id is stored in data[:metadata] (nested), not top-level metadata
+      nested = data[:metadata] || data["metadata"] || {}
+      nested[:user_id] || nested["user_id"] || metadata[:user_id]
+    end
+
+    def request_id
+      # request_id is stored in data[:metadata] (nested), not top-level metadata
+      nested = data[:metadata] || data["metadata"] || {}
+      nested[:request_id] || nested["request_id"] || metadata[:request_id]
+    end
+  end
+
+  module Events
+    # Dynamically created events will be placed here
+  end
+
+  class EventRegistry
+    @events = []
+
+    class << self
+      def register(event_class)
+        @events << event_class unless @events.include?(event_class)
+      end
+
+      def all
+        @events
+      end
+
+      def find_by_name(name)
+        @events.find { |e| e.name == name }
+      end
+    end
+  end
+end