whodunit-chronicles 0.3.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.to_h do |column|
-          [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/composite_processor.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Fans out a single change event to multiple processors in sequence.
-    #
-    # Use this to build pipelines — e.g. simultaneously storing audit records,
-    # streaming to Grafana, and triggering alerts — without coupling any single
-    # processor to the others.
-    #
-    # Each processor runs independently. If one raises, the error is logged and
-    # the remaining processors still execute (fail-open by default). Set
-    # `fail_fast: true` to instead halt the chain on the first error.
-    #
-    # @example Basic pipeline
-    #   service = Whodunit::Chronicles::Service.new(
-    #     adapter: adapter,
-    #     processor: Whodunit::Chronicles::CompositeProcessor.new([
-    #       AuditStoreProcessor.new,
-    #       AlertingProcessor.new,
-    #       GrafanaProcessor.new
-    #     ])
-    #   )
-    #
-    # @example Halt on first error
-    #   CompositeProcessor.new(processors, fail_fast: true)
-    #
-    class CompositeProcessor
-      # @param processors [Array<#process>] ordered list of processors to invoke
-      # @param fail_fast [Boolean] when true, halt the chain on the first error
-      # @param logger [Logger, nil] optional logger; defaults to Chronicles logger
-      def initialize(processors, fail_fast: false, logger: nil)
-        raise ArgumentError, 'processors must be an Array' unless processors.is_a?(Array)
-        raise ArgumentError, 'processors cannot be empty' if processors.empty?
-
-        @processors = processors
-        @fail_fast  = fail_fast
-        @logger     = logger || Whodunit::Chronicles.logger
-      end
-
-      # Process a change event through every processor in the chain.
-      #
-      # @param change_event [ChangeEvent] the event to process
-      # @return [void]
-      # @raise [ProcessingError] only when fail_fast is true and a child raises
-      def process(change_event)
-        errors = []
-
-        @processors.each do |processor|
-          processor.process(change_event)
-        rescue StandardError => e
-          raise ProcessingError, "#{processor.class} failed: #{e.message}" if @fail_fast
-
-          @logger.error { "CompositeProcessor: #{processor.class} raised #{e.class}: #{e.message}" }
-          errors << e
-        end
-
-        return if errors.empty?
-
-        @logger.warn do
-          "CompositeProcessor: #{errors.size} processor(s) failed for #{change_event.table_name}##{change_event.action}"
-        end
-      end
-
-      # @return [Integer] the number of processors in the chain
-      def size
-        @processors.size
-      end
-
-      # @return [Array<Class>] the processor classes in chain order
-      def processor_classes
-        @processors.map(&:class)
-      end
-
-      # Append a processor to the end of the chain.
-      #
-      # @param processor [#process] the processor to add
-      # @return [self]
-      def add(processor)
-        @processors << processor
-        self
-      end
-      alias << add
-    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