whodunit-chronicles 0.1.0.pre → 0.2.0

data/lib/whodunit/chronicles/adapters/mysql.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'trilogy'
+require 'uri'
+
+module Whodunit
+  module Chronicles
+    module Adapters
+      # MySQL/MariaDB binary log streaming adapter
+      #
+      # Uses MySQL's binary log replication to stream database changes
+      # without impacting application performance.
+      class MySQL < StreamAdapter
+        DEFAULT_SERVER_ID = 1001
+
+        attr_reader :connection, :database_url, :server_id, :binlog_file, :binlog_position
+
+        def initialize(
+          database_url: Chronicles.config.database_url,
+          server_id: DEFAULT_SERVER_ID,
+          logger: Chronicles.logger
+        )
+          super(logger: logger)
+          @database_url = database_url
+          @server_id = server_id
+          @connection = nil
+          @binlog_file = nil
+          @binlog_position = nil
+          @binlog_checksum = true
+        end
+
+        # Start streaming binary log changes
+        def start_streaming(&)
+          raise ArgumentError, 'Block required for processing events' unless block_given?
+
+          log(:info, 'Starting MySQL binary log streaming')
+
+          establish_connection
+          ensure_setup
+
+          self.running = true
+          fetch_current_position
+
+          log(:info, 'Starting replication from position',
+            file: @binlog_file, position: @binlog_position)
+
+          begin
+            stream_binlog_events(&)
+          rescue StandardError => e
+            log(:error, 'Streaming error', error: e.message, backtrace: e.backtrace.first(5))
+            raise ReplicationError, "Failed to stream changes: #{e.message}"
+          ensure
+            self.running = false
+          end
+        end
+
+        # Stop streaming
+        def stop_streaming
+          log(:info, 'Stopping MySQL binary log streaming')
+          self.running = false
+          close_connection
+        end
+
+        # Get current replication position
+        def current_position
+          return "#{@binlog_file}:#{@binlog_position}" if @binlog_file && @binlog_position
+
+          fetch_current_position
+          "#{@binlog_file}:#{@binlog_position}"
+        end
+
+        # Set up binary log replication
+        def setup
+          log(:info, 'Setting up MySQL binary log replication')
+
+          establish_connection
+          validate_binlog_format
+          validate_server_id
+          enable_binlog_checksum
+
+          log(:info, 'MySQL setup completed successfully')
+        end
+
+        # Remove binary log replication setup (minimal cleanup needed)
+        def teardown
+          log(:info, 'Tearing down MySQL binary log replication')
+          close_connection
+          log(:info, 'MySQL teardown completed')
+        end
+
+        # Test database connection
+        def test_connection
+          establish_connection
+          result = @connection.query('SELECT @@hostname, @@version, @@server_id')
+          info = result.first
+
+          log(:info, 'Connection test successful',
+            hostname: info['@@hostname'],
+            version: info['@@version'],
+            server_id: info['@@server_id'])
+
+          true
+        rescue StandardError => e
+          log(:error, 'Connection test failed', error: e.message)
+          false
+        end
+
+        private
+
+        def establish_connection
+          return if @connection&.ping
+
+          parsed_url = parse_database_url(@database_url)
+
+          @connection = Trilogy.new(
+            host: parsed_url[:host],
+            port: parsed_url[:port] || 3306,
+            username: parsed_url[:username],
+            password: parsed_url[:password],
+            database: parsed_url[:database],
+            ssl: parsed_url[:ssl],
+          )
+
+          log(:debug, 'Established MySQL connection',
+            host: parsed_url[:host],
+            database: parsed_url[:database])
+        rescue StandardError => e
+          log(:error, 'Failed to establish connection', error: e.message)
+          raise AdapterError, "Connection failed: #{e.message}"
+        end
+
+        def close_connection
+          @connection&.close
+          @connection = nil
+        end
+
+        def parse_database_url(url)
+          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 ensure_setup
+          validate_binlog_format
+          validate_server_id
+        end
+
+        def validate_binlog_format
+          result = @connection.query('SELECT @@binlog_format')
+          format = result.first['@@binlog_format']
+
+          unless %w[ROW MIXED].include?(format)
+            raise ReplicationError,
+              "Binary log format must be ROW or MIXED, currently: #{format}"
+          end
+
+          log(:debug, 'Binary log format validated', format: format)
+        end
+
+        def validate_server_id
+          result = @connection.query('SELECT @@server_id')
+          current_server_id = result.first['@@server_id'].to_i
+
+          if current_server_id == @server_id
+            raise ReplicationError,
+              "Server ID conflict: #{@server_id} is already in use"
+          end
+
+          log(:debug, 'Server ID validated',
+            current: current_server_id,
+            replication: @server_id)
+        end
+
+        def enable_binlog_checksum
+          @connection.query('SET @master_binlog_checksum = @@global.binlog_checksum')
+          log(:debug, 'Binary log checksum enabled')
+        end
+
+        def fetch_current_position
+          result = @connection.query('SHOW MASTER STATUS')
+          status = result.first
+
+          raise ReplicationError, 'Unable to fetch master status - binary logging may be disabled' unless status
+
+          @binlog_file = status['File']
+          @binlog_position = status['Position']
+          log(:debug, 'Fetched master position',
+            file: @binlog_file,
+            position: @binlog_position)
+        end
+
+        def stream_binlog_events(&)
+          # Register as replica server
+          register_replica_server
+
+          # Request binary log dump
+          request_binlog_dump
+
+          # Process binary log events
+          process_binlog_stream(&)
+        rescue StandardError => e
+          log(:error, 'Binary log streaming error', error: e.message)
+          raise
+        end
+
+        def register_replica_server
+          # This would typically use COM_REGISTER_SLAVE MySQL protocol command
+          # For now, we'll use a simplified approach
+          log(:debug, 'Registering as replica server', server_id: @server_id)
+
+          # NOTE: Full implementation would require low-level MySQL protocol handling
+          # This is a placeholder for the binary log streaming setup
+        end
+
+        def request_binlog_dump
+          log(:debug, 'Requesting binary log dump',
+            file: @binlog_file,
+            position: @binlog_position)
+
+          # This would use COM_BINLOG_DUMP MySQL protocol command
+          # Full implementation requires binary protocol handling
+        end
+
+        def process_binlog_stream(&)
+          # This would process the binary log event stream
+          # Each event would be parsed and converted to a ChangeEvent
+
+          log(:info, 'Processing binary log stream (placeholder implementation)')
+
+          # Placeholder: In a real implementation, this would:
+          # 1. Read binary log events from the stream
+          # 2. Parse event headers and data
+          # 3. Convert to ChangeEvent objects
+          # 4. Yield each event to the block
+
+          # For now, we'll simulate with a warning
+          log(:warn, 'MySQL binary log streaming requires full protocol implementation')
+
+          # Yield a placeholder change event to demonstrate the interface
+          change_event = ChangeEvent.new(
+            table_name: 'example_table',
+            action: 'INSERT',
+            primary_key: { id: 1 },
+            new_data: { id: 1, name: 'test' },
+            old_data: nil,
+            timestamp: Time.now,
+            metadata: { position: current_position },
+          )
+
+          yield(change_event) if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/configuration.rb

@@ -30,21 +30,20 @@ module Whodunit
       # @raise [ConfigurationError] if configuration is invalid
       def validate!
         raise ConfigurationError, 'database_url is required' if database_url.nil?
-        raise ConfigurationError, 'adapter must be :postgresql' unless adapter == :postgresql
+        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_publication_name!
-        validate_slot_name!
+        validate_adapter_specific_settings!
       end
 
-      # Check if a table should be audited based on filters
+      # 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 audited
-      def audit_table?(table_name, schema_name = 'public')
+      # @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)
 
@@ -53,18 +52,30 @@ module Whodunit
 
       private
 
-      def validate_publication_name!
-        return if /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(publication_name)
-
-        raise ConfigurationError, 'publication_name must be a valid PostgreSQL identifier'
+      def validate_adapter_specific_settings!
+        case adapter
+        when :postgresql
+          validate_postgresql_settings!
+        when :mysql
+          validate_mysql_settings!
+        end
       end
 
-      def validate_slot_name!
-        return if /\A[a-zA-Z_][a-zA-Z0-9_]*\z/.match?(replication_slot_name)
+      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
 

data/lib/whodunit/chronicles/connection.rb

@@ -0,0 +1,88 @@
+# 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

@@ -0,0 +1,129 @@
+# 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

@@ -0,0 +1,127 @@
+# 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