whodunit-chronicles 0.2.0 → 0.4.0

data/lib/whodunit/chronicles/change_event.rb

@@ -1,201 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Represents a database change event in a common format
-    #
-    # This class normalizes database changes from different sources
-    # (PostgreSQL WAL, MariaDB binlog, etc.) into a consistent format
-    # for processing by audit systems.
-    class ChangeEvent
-      # Supported database actions
-      ACTIONS = %w[INSERT UPDATE DELETE].freeze
-
-      attr_reader :table_name, :schema_name, :action, :primary_key, :old_data, :new_data,
-        :timestamp, :transaction_id, :sequence_number, :metadata
-
-      # Initialize a new change event
-      #
-      # @param table_name [String] The name of the table that changed
-      # @param action [String] The type of change (INSERT, UPDATE, DELETE)
-      # @param primary_key [Hash] The primary key values for the changed row
-      # @param old_data [Hash, nil] The row data before the change (nil for INSERT)
-      # @param new_data [Hash, nil] The row data after the change (nil for DELETE)
-      # @param timestamp [Time] When the change occurred
-      # @param schema_name [String] The schema name (optional, defaults to 'public')
-      # @param transaction_id [String, Integer] Database transaction identifier
-      # @param sequence_number [Integer] Sequence number within the transaction
-      # @param metadata [Hash] Additional adapter-specific metadata
-      def initialize(
-        table_name:,
-        action:,
-        primary_key:,
-        old_data: nil,
-        new_data: nil,
-        timestamp: Time.now,
-        schema_name: 'public',
-        transaction_id: nil,
-        sequence_number: nil,
-        metadata: {}
-      )
-        @table_name = table_name.to_s
-        @schema_name = schema_name.to_s
-        @action = validate_action(action.to_s.upcase)
-        @primary_key = primary_key || {}
-        @old_data = old_data
-        @new_data = new_data
-        @timestamp = timestamp
-        @transaction_id = transaction_id
-        @sequence_number = sequence_number
-        @metadata = metadata || {}
-
-        validate_data_consistency
-      end
-
-      # Get the qualified table name (schema.table)
-      #
-      # @return [String]
-      def qualified_table_name
-        "#{schema_name}.#{table_name}"
-      end
-
-      # Check if this is a create event
-      #
-      # @return [Boolean]
-      def create?
-        action == 'INSERT'
-      end
-
-      # Check if this is an update event
-      #
-      # @return [Boolean]
-      def update?
-        action == 'UPDATE'
-      end
-
-      # Check if this is a delete event
-      #
-      # @return [Boolean]
-      def delete?
-        action == 'DELETE'
-      end
-
-      # Get the changed columns for UPDATE events
-      #
-      # @return [Array<String>] Array of column names that changed
-      def changed_columns
-        return [] unless update? && old_data && new_data
-
-        old_data.keys.reject { |key| old_data[key] == new_data[key] }
-      end
-
-      # Get a hash of changes in [old_value, new_value] format
-      #
-      # @return [Hash] Hash of column_name => [old_value, new_value]
-      def changes
-        return {} unless update? && old_data && new_data
-
-        changed_columns.each_with_object({}) do |column, changes_hash|
-          changes_hash[column] = [old_data[column], new_data[column]]
-        end
-      end
-
-      # Get the current data for this event
-      #
-      # @return [Hash] The new_data for INSERT/UPDATE, old_data for DELETE
-      def current_data
-        case action
-        when 'INSERT', 'UPDATE'
-          new_data
-        when 'DELETE'
-          old_data
-        end
-      end
-
-      # Get all available data for this event
-      #
-      # @return [Hash] Combined old and new data
-      def all_data
-        (old_data || {}).merge(new_data || {})
-      end
-
-      # Convert to hash representation
-      #
-      # @return [Hash]
-      def to_h
-        {
-          table_name: table_name,
-          schema_name: schema_name,
-          qualified_table_name: qualified_table_name,
-          action: action,
-          primary_key: primary_key,
-          old_data: old_data,
-          new_data: new_data,
-          current_data: current_data,
-          changes: changes,
-          changed_columns: changed_columns,
-          timestamp: timestamp,
-          transaction_id: transaction_id,
-          sequence_number: sequence_number,
-          metadata: metadata,
-        }
-      end
-
-      # String representation
-      #
-      # @return [String]
-      def to_s
-        pk_str = primary_key.map { |k, v| "#{k}=#{v}" }.join(', ')
-        "#{action} #{qualified_table_name}(#{pk_str}) at #{timestamp}"
-      end
-
-      # Detailed string representation
-      #
-      # @return [String]
-      def inspect
-        "#<#{self.class.name} #{self}>"
-      end
-
-      # Compare events for equality
-      #
-      # @param other [ChangeEvent]
-      # @return [Boolean]
-      def ==(other)
-        return false unless other.is_a?(ChangeEvent)
-
-        table_name == other.table_name &&
-          schema_name == other.schema_name &&
-          action == other.action &&
-          primary_key == other.primary_key &&
-          old_data == other.old_data &&
-          new_data == other.new_data &&
-          timestamp == other.timestamp &&
-          transaction_id == other.transaction_id &&
-          sequence_number == other.sequence_number
-      end
-
-      private
-
-      def validate_action(action)
-        unless ACTIONS.include?(action)
-          raise ArgumentError, "Invalid action: #{action}. Must be one of: #{ACTIONS.join(', ')}"
-        end
-
-        action
-      end
-
-      def validate_data_consistency
-        case action
-        when 'INSERT'
-          raise ArgumentError, 'INSERT events must have new_data' if new_data.nil? || new_data.empty?
-          raise ArgumentError, 'INSERT events should not have old_data' unless old_data.nil?
-        when 'UPDATE'
-          raise ArgumentError, 'UPDATE events must have both old_data and new_data' if old_data.nil? || new_data.nil?
-        when 'DELETE'
-          raise ArgumentError, 'DELETE events must have old_data' if old_data.nil? || old_data.empty?
-          raise ArgumentError, 'DELETE events should not have new_data' unless new_data.nil?
-        end
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/configuration.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Configuration management for Chronicles
-    #
-    # Provides a centralized configuration system with sensible defaults
-    # and validation for all Chronicles settings.
-    class Configuration
-      attr_accessor :database_url, :audit_database_url, :adapter, :publication_name,
-        :replication_slot_name, :batch_size, :max_retry_attempts, :retry_delay,
-        :logger, :table_filter, :schema_filter
-
-      def initialize
-        @database_url = ENV.fetch('DATABASE_URL', nil)
-        @audit_database_url = ENV.fetch('AUDIT_DATABASE_URL', nil)
-        @adapter = :postgresql
-        @publication_name = 'whodunit_audit'
-        @replication_slot_name = 'whodunit_audit_slot'
-        @batch_size = 100
-        @max_retry_attempts = 3
-        @retry_delay = 5
-        @logger = Dry::Logger.new
-        @table_filter = nil
-        @schema_filter = nil
-      end
-
-      # Validate configuration settings
-      #
-      # @raise [ConfigurationError] if configuration is invalid
-      def validate!
-        raise ConfigurationError, 'database_url is required' if database_url.nil?
-        raise ConfigurationError, 'adapter must be :postgresql or :mysql' unless %i[postgresql mysql].include?(adapter)
-        raise ConfigurationError, 'batch_size must be positive' unless batch_size.positive?
-        raise ConfigurationError, 'max_retry_attempts must be positive' unless max_retry_attempts.positive?
-        raise ConfigurationError, 'retry_delay must be positive' unless retry_delay.positive?
-
-        validate_adapter_specific_settings!
-      end
-
-      # Check if a table should be chronicled based on filters
-      #
-      # @param table_name [String] The table name to check
-      # @param schema_name [String] The schema name to check
-      # @return [Boolean] true if the table should be chronicled
-      def chronicle_table?(table_name, schema_name = 'public')
-        return false if filtered_by_schema?(schema_name)
-        return false if filtered_by_table?(table_name)
-
-        true
-      end
-
-      private
-
-      def validate_adapter_specific_settings!
-        case adapter
-        when :postgresql
-          validate_postgresql_settings!
-        when :mysql
-          validate_mysql_settings!
-        end
-      end
-
-      def validate_postgresql_settings!
-        if publication_name && !/\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(publication_name)
-          raise ConfigurationError, 'publication_name must be a valid PostgreSQL identifier'
-        end
-
-        return unless replication_slot_name && !/\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(replication_slot_name)
-
-        raise ConfigurationError, 'replication_slot_name must be a valid PostgreSQL identifier'
-      end
-
-      def validate_mysql_settings!
-        # MySQL-specific validations can be added here in the future
-        # For now, MySQL settings are less restrictive
-      end
-
-      def filtered_by_schema?(schema_name)
-        return false unless schema_filter
-
-        case schema_filter
-        when Array
-          !schema_filter.include?(schema_name)
-        when String, Symbol
-          schema_name != schema_filter.to_s
-        when Proc
-          !schema_filter.call(schema_name)
-        else
-          false
-        end
-      end
-
-      def filtered_by_table?(table_name)
-        return false unless table_filter
-
-        case table_filter
-        when Array
-          !table_filter.include?(table_name)
-        when String, Symbol
-          table_name != table_filter.to_s
-        when Regexp
-          !table_filter.match?(table_name)
-        when Proc
-          !table_filter.call(table_name)
-        else
-          false
-        end
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/connection.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-
-module Whodunit
-  module Chronicles
-    # Handles database connections for chronicles processing
-    #
-    # Provides adapter-agnostic connection management for both PostgreSQL and MySQL
-    module Connection
-      private
-
-      def create_connection
-        audit_url = @audit_database_url || Chronicles.config.database_url
-
-        case detect_database_type(audit_url)
-        when :postgresql
-          require 'pg'
-          PG.connect(audit_url)
-        when :mysql
-          require 'trilogy'
-          parsed = parse_mysql_url(audit_url)
-          Trilogy.new(
-            host: parsed[:host],
-            port: parsed[:port] || 3306,
-            username: parsed[:username],
-            password: parsed[:password],
-            database: parsed[:database],
-            ssl: parsed[:ssl],
-          )
-        else
-          raise ConfigurationError, 'Unsupported database type for connection'
-        end
-      end
-
-      def detect_database_type(url)
-        return Chronicles.config.adapter unless url
-        return :postgresql if url.start_with?('postgres://', 'postgresql://')
-        return :mysql if url.start_with?('mysql://', 'mysql2://')
-
-        # Fallback to configured adapter
-        Chronicles.config.adapter
-      end
-
-      def parse_mysql_url(url)
-        return {} if url.nil? || url.empty?
-
-        uri = URI.parse(url)
-        {
-          host: uri.host,
-          port: uri.port,
-          username: uri.user,
-          password: uri.password,
-          database: uri.path&.sub('/', ''),
-          ssl: uri.query&.include?('ssl=true'),
-        }
-      end
-
-      def connection_active?
-        case detect_database_type(@audit_database_url || Chronicles.config.database_url)
-        when :postgresql
-          @connection && !@connection.finished?
-        when :mysql
-          @connection&.ping
-        else
-          false
-        end
-      end
-
-      def setup_connection_specifics
-        case detect_database_type(@audit_database_url || Chronicles.config.database_url)
-        when :postgresql
-          @connection.type_map_for_results = PG::BasicTypeMapForResults.new(@connection)
-        when :mysql
-          # MySQL/Trilogy doesn't need special setup
-        end
-      end
-
-      def ensure_connection
-        return if @connection && connection_active?
-
-        @connection = create_connection
-        setup_connection_specifics
-        ensure_table_exists
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/persistence.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Handles record persistence for different database adapters
-    #
-    # Provides adapter-specific SQL for inserting chronicle records
-    module Persistence
-      private
-
-      def persist_record(record)
-        db_type = detect_database_type(@audit_database_url || Chronicles.config.database_url)
-
-        case db_type
-        when :postgresql
-          persist_record_postgresql(record)
-        when :mysql
-          persist_record_mysql(record)
-        end
-      end
-
-      def persist_record_postgresql(record)
-        sql = <<~SQL
-          INSERT INTO whodunit_chronicles_audits (
-            table_name, schema_name, record_id, action, old_data, new_data, changes,
-            user_id, user_type, transaction_id, sequence_number, occurred_at, created_at, metadata
-          ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)
-          RETURNING id
-        SQL
-
-        params = build_record_params(record)
-        result = @connection.exec_params(sql, params)
-        record[:id] = result.first['id'].to_i
-        result.clear
-
-        record
-      end
-
-      def persist_record_mysql(record)
-        sql = <<~SQL
-          INSERT INTO whodunit_chronicles_audits (
-            table_name, schema_name, record_id, action, old_data, new_data, changes,
-            user_id, user_type, transaction_id, sequence_number, occurred_at, created_at, metadata
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        SQL
-
-        params = build_record_params(record)
-        @connection.execute(sql, *params)
-        record[:id] = @connection.last_insert_id
-
-        record
-      end
-
-      def persist_records_batch(records)
-        return records if records.empty?
-
-        db_type = detect_database_type(@audit_database_url || Chronicles.config.database_url)
-
-        case db_type
-        when :postgresql
-          persist_records_batch_postgresql(records)
-        when :mysql
-          persist_records_batch_mysql(records)
-        end
-      end
-
-      def persist_records_batch_postgresql(records)
-        # Use multi-row INSERT for better performance
-        values_clauses = []
-        all_params = []
-        param_index = 1
-
-        records.each do |record|
-          param_positions = (param_index..(param_index + 13)).map { |i| "$#{i}" }.join(', ')
-          values_clauses << "(#{param_positions})"
-          all_params.concat(build_record_params(record))
-          param_index += 14
-        end
-
-        sql = <<~SQL
-          INSERT INTO whodunit_chronicles_audits (
-            table_name, schema_name, record_id, action, old_data, new_data, changes,
-            user_id, user_type, transaction_id, sequence_number, occurred_at, created_at, metadata
-          ) VALUES #{values_clauses.join(', ')}
-          RETURNING id
-        SQL
-
-        result = @connection.exec_params(sql, all_params)
-
-        # Set IDs on the records
-        result.each_with_index do |row, index|
-          records[index][:id] = row['id'].to_i
-        end
-
-        result.clear
-        records
-      end
-
-      def persist_records_batch_mysql(records)
-        # For MySQL, we'll use individual inserts in a transaction for simplicity
-        # A more optimized version could use VALUES() with multiple rows
-        records.each do |record|
-          persist_record_mysql(record)
-        end
-
-        records
-      end
-
-      def build_record_params(record)
-        [
-          record[:table_name],
-          record[:schema_name],
-          record[:record_id].to_json,
-          record[:action],
-          record[:old_data]&.to_json,
-          record[:new_data]&.to_json,
-          record[:changes].to_json,
-          record[:user_id],
-          record[:user_type],
-          record[:transaction_id],
-          record[:sequence_number],
-          record[:occurred_at],
-          record[:created_at],
-          record[:metadata].to_json,
-        ]
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/processor.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Processes database change events and creates chronicle records
-    #
-    # Transforms ChangeEvent objects into structured chronicle records
-    # with complete object serialization and metadata.
-    class Processor
-      include Connection
-      include Table
-      include Persistence
-
-      attr_reader :logger, :connection
-
-      def initialize(
-        audit_database_url: Chronicles.config.audit_database_url,
-        logger: Chronicles.logger
-      )
-        @audit_database_url = audit_database_url
-        @logger = logger
-        @connection = nil
-      end
-
-      # Process a change event and create chronicle record
-      #
-      # @param change_event [ChangeEvent] The database change to chronicle
-      # @return [Hash] The created chronicle record
-      def process(change_event)
-        ensure_connection
-
-        record = build_record(change_event)
-        persist_record(record)
-
-        log(:debug, 'Processed change event',
-          table: change_event.qualified_table_name,
-          action: change_event.action,
-          id: record[:id])
-
-        record
-      rescue StandardError => e
-        log(:error, 'Failed to process change event',
-          error: e.message,
-          event: change_event.to_s)
-        raise
-      end
-
-      # Process multiple change events in a batch
-      #
-      # @param change_events [Array<ChangeEvent>] Array of change events
-      # @return [Array<Hash>] Array of created chronicle records
-      def process_batch(change_events)
-        return [] if change_events.empty?
-
-        ensure_connection
-
-        records = change_events.map { |event| build_record(event) }
-        persist_records_batch(records)
-
-        log(:info, 'Processed batch of change events', count: change_events.size)
-
-        records
-      rescue StandardError => e
-        log(:error, 'Failed to process batch',
-          error: e.message,
-          count: change_events.size)
-        raise
-      end
-
-      # Close database connection
-      def close
-        @connection&.close
-        @connection = nil
-      end
-
-      private
-
-      def build_record(change_event)
-        user_info = extract_user_info(change_event)
-
-        {
-          id: nil, # Will be set by database
-          table_name: change_event.table_name,
-          schema_name: change_event.schema_name,
-          record_id: change_event.primary_key,
-          action: change_event.action,
-          old_data: change_event.old_data,
-          new_data: change_event.new_data,
-          changes: change_event.changes,
-          user_id: user_info[:user_id],
-          user_type: user_info[:user_type],
-          transaction_id: change_event.transaction_id,
-          sequence_number: change_event.sequence_number,
-          occurred_at: change_event.timestamp,
-          created_at: Time.now,
-          metadata: build_metadata(change_event),
-        }
-      end
-
-      def extract_user_info(change_event)
-        data = change_event.current_data || {}
-
-        # Look for Whodunit user attribution fields
-        user_id = data['creator_id'] || data['updater_id'] || data['deleter_id']
-
-        {
-          user_id: user_id,
-          user_type: user_id ? 'User' : nil,
-        }
-      end
-
-      def build_metadata(change_event)
-        {
-          table_schema: change_event.schema_name,
-          qualified_table_name: change_event.qualified_table_name,
-          changed_columns: change_event.changed_columns,
-          adapter_metadata: change_event.metadata,
-          chronicles_version: Chronicles::VERSION,
-        }
-      end
-
-      def log(level, message, context = {})
-        logger.public_send(level, message, processor: 'Processor', **context)
-      end
-    end
-  end
-end