whodunit-chronicles 0.3.0 → 0.4.0

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

data/lib/whodunit/chronicles/service.rb

@@ -1,207 +0,0 @@
-# frozen_string_literal: true
-
-require 'concurrent-ruby'
-
-module Whodunit
-  module Chronicles
-    # Main service orchestrator for chronicle streaming
-    #
-    # Coordinates the stream adapter and processor to provide
-    # a complete chronicle streaming solution with error handling and monitoring.
-    class Service
-      attr_reader :adapter, :processor, :logger, :executor
-
-      def initialize(
-        adapter: nil,
-        processor: nil,
-        logger: Chronicles.logger
-      )
-        @adapter = adapter || build_adapter
-        @processor = processor || Processor.new(logger: logger)
-        @logger = logger
-        @executor = Concurrent::ThreadPoolExecutor.new(
-          min_threads: 1,
-          max_threads: 4,
-          max_queue: 100,
-          fallback_policy: :caller_runs,
-        )
-        @running = false
-        @retry_count = 0
-      end
-
-      # Start the chronicle streaming service
-      #
-      # @return [self]
-      def start
-        return self if running?
-
-        log(:info, 'Starting Chronicles streaming service')
-
-        validate_setup!
-        test_connections!
-
-        @running = true
-        @retry_count = 0
-
-        start_streaming_with_retry
-
-        log(:info, 'Chronicles streaming service started successfully')
-        self
-      rescue StandardError => e
-        log(:error, 'Failed to start service', error: e.message)
-        @running = false
-        raise
-      end
-
-      # Stop the chronicle streaming service
-      #
-      # @return [void]
-      def stop
-        return unless running?
-
-        log(:info, 'Stopping Chronicles streaming service')
-        @running = false
-
-        adapter.stop_streaming if adapter.streaming?
-        @executor.shutdown
-        @executor.wait_for_termination(timeout: 30)
-
-        processor.close
-        log(:info, 'Chronicles streaming service stopped')
-      end
-
-      # Check if service is running
-      #
-      # @return [Boolean]
-      def running?
-        @running
-      end
-
-      # Get service status information
-      #
-      # @return [Hash]
-      def status
-        {
-          running: running?,
-          adapter_streaming: adapter.streaming?,
-          adapter_position: adapter.current_position,
-          retry_count: @retry_count,
-          executor_status: {
-            active_count: @executor.active_count,
-            completed_task_count: @executor.completed_task_count,
-            queue_length: @executor.queue_length,
-          },
-        }
-      end
-
-      # Set up the chronicle streaming infrastructure
-      #
-      # @return [void]
-      def setup!
-        log(:info, 'Setting up chronicle streaming infrastructure')
-        adapter.setup
-        log(:info, 'Chronicle streaming infrastructure setup completed')
-      end
-
-      # Tear down the chronicle streaming infrastructure
-      #
-      # @return [void]
-      def teardown!
-        log(:info, 'Tearing down chronicle streaming infrastructure')
-        stop if running?
-        adapter.teardown
-        log(:info, 'Chronicle streaming infrastructure teardown completed')
-      end
-
-      private
-
-      def build_adapter
-        case Chronicles.config.adapter
-        when :postgresql
-          Whodunit::Chronicles::AdapterLoader.load(:postgresql, logger:)
-        when :mysql
-          Whodunit::Chronicles::AdapterLoader.load(:mysql, logger:)
-        else
-          raise ConfigurationError, "Unsupported adapter: #{Chronicles.config.adapter}"
-        end
-      end
-
-      def validate_setup!
-        Chronicles.config.validate!
-
-        return if adapter.test_connection
-
-        raise AdapterLoadError, 'Failed to connect to source database'
-      end
-
-      def test_connections!
-        adapter.test_connection
-        # Test processor connection by creating a dummy connection
-        processor.send(:ensure_connection)
-      rescue StandardError => e
-        raise AdapterLoadError, "Connection test failed: #{e.message}"
-      end
-
-      def start_streaming_with_retry
-        @executor.post do
-          loop do
-            break unless running?
-
-            begin
-              adapter.start_streaming do |change_event|
-                process_change_event(change_event)
-              end
-            rescue StandardError => e
-              handle_streaming_error(e)
-              break unless should_retry?
-            end
-          end
-        end
-      end
-
-      def process_change_event(change_event)
-        return unless change_event
-        return unless should_chronicle_table?(change_event)
-
-        log(:debug, 'Processing change event',
-          table: change_event.qualified_table_name,
-          action: change_event.action
-        )
-
-        processor.process(change_event)
-      rescue StandardError => e
-        log(:error, 'Failed to process change event',
-          error: e.message,
-          event: change_event.to_s
-        )
-      end
-
-      def should_chronicle_table?(change_event)
-        Chronicles.config.chronicle_table?(
-          change_event.table_name,
-          change_event.schema_name,
-        )
-      end
-
-      def handle_streaming_error(error)
-        @retry_count += 1
-        log(:error, 'Streaming error occurred',
-          error: error.message,
-          retry_count: @retry_count,
-          max_retries: Chronicles.config.max_retry_attempts
-        )
-
-        # Wait before retry
-        sleep(Chronicles.config.retry_delay) if should_retry?
-      end
-
-      def should_retry?
-        running? && @retry_count < Chronicles.config.max_retry_attempts
-      end
-
-      def log(level, message, context = {})
-        logger.public_send(level, message, service: 'Chronicles::Service', **context)
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/stream_adapter.rb

@@ -1,91 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Abstract base class for database streaming adapters
-    #
-    # Defines the interface that all database-specific adapters must implement
-    # for streaming database changes into audit events.
-    class StreamAdapter
-      attr_reader :logger
-
-      def initialize(logger: Chronicles.logger)
-        @logger = logger
-        @running = false
-        @position = nil
-      end
-
-      # Start streaming database changes
-      #
-      # @param block [Proc] Block to call for each change event
-      # @return [void]
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def start_streaming(&)
-        raise NotImplementedError, "#{self.class} must implement #start_streaming"
-      end
-
-      # Stop streaming database changes
-      #
-      # @return [void]
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def stop_streaming
-        raise NotImplementedError, "#{self.class} must implement #stop_streaming"
-      end
-
-      # Get current replication position
-      #
-      # @return [String, nil] Current position or nil if not available
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def current_position
-        raise NotImplementedError, "#{self.class} must implement #current_position"
-      end
-
-      # Check if adapter is currently streaming
-      #
-      # @return [Boolean]
-      def streaming?
-        @running
-      end
-
-      # Set up the database for streaming (create publications, slots, etc.)
-      #
-      # @return [void]
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def setup
-        raise NotImplementedError, "#{self.class} must implement #setup"
-      end
-
-      # Tear down streaming setup (remove publications, slots, etc.)
-      #
-      # @return [void]
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def teardown
-        raise NotImplementedError, "#{self.class} must implement #teardown"
-      end
-
-      # Test connection to the database
-      #
-      # @return [Boolean] true if connection is successful
-      # @raise [NotImplementedError] Must be implemented by subclasses
-      def test_connection
-        raise NotImplementedError, "#{self.class} must implement #test_connection"
-      end
-
-      protected
-
-      attr_writer :running, :position
-
-      # Log a message with context
-      #
-      # @param level [Symbol] Log level (:info, :warn, :error, etc.)
-      # @param message [String] Log message
-      # @param context [Hash] Additional context
-      def log(level, message, context = {})
-        logger.public_send(level, message,
-          adapter: self.class.name.split('::').last,
-          position: current_position,
-          **context)
-      end
-    end
-  end
-end

data/lib/whodunit/chronicles/table.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Handles table creation for different database adapters
-    #
-    # Provides adapter-specific SQL for creating chronicles tables
-    module Table
-      private
-
-      def ensure_table_exists
-        db_type = detect_database_type(@audit_database_url || Chronicles.config.database_url)
-
-        case db_type
-        when :postgresql
-          create_postgresql_table
-        when :mysql
-          create_mysql_table
-        end
-      end
-
-      def create_postgresql_table
-        create_sql = <<~SQL
-          CREATE TABLE IF NOT EXISTS whodunit_chronicles_audits (
-            id BIGSERIAL PRIMARY KEY,
-            table_name TEXT NOT NULL,
-            schema_name TEXT NOT NULL DEFAULT 'public',
-            record_id JSONB,
-            action TEXT NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
-            old_data JSONB,
-            new_data JSONB,
-            changes JSONB,
-            user_id BIGINT,
-            user_type TEXT,
-            transaction_id TEXT,
-            sequence_number INTEGER,
-            occurred_at TIMESTAMP WITH TIME ZONE NOT NULL,
-            created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-            metadata JSONB DEFAULT '{}'::jsonb,
-          #{'  '}
-            -- Indexes for performance
-            CONSTRAINT valid_data_for_action CHECK (
-              (action = 'INSERT' AND old_data IS NULL AND new_data IS NOT NULL) OR
-              (action = 'UPDATE' AND old_data IS NOT NULL AND new_data IS NOT NULL) OR#{'  '}
-              (action = 'DELETE' AND old_data IS NOT NULL AND new_data IS NULL)
-            )
-          );
-
-          -- Performance indexes
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_table_record#{' '}
-            ON whodunit_chronicles_audits (table_name, (record_id->>'id'));
-
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_occurred_at#{' '}
-            ON whodunit_chronicles_audits (occurred_at DESC);
-
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_user#{' '}
-            ON whodunit_chronicles_audits (user_id, user_type);
-
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_action#{' '}
-            ON whodunit_chronicles_audits (action);
-
-          -- GIN index for JSONB columns
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_record_id_gin#{' '}
-            ON whodunit_chronicles_audits USING GIN (record_id);
-
-          CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_chronicles_audits_changes_gin#{' '}
-            ON whodunit_chronicles_audits USING GIN (changes);
-        SQL
-
-        @connection.exec(create_sql)
-      rescue PG::Error => e
-        # Ignore "already exists" errors from CONCURRENTLY
-        raise unless e.message.include?('already exists')
-      end
-
-      def create_mysql_table
-        create_sql = <<~SQL
-          CREATE TABLE IF NOT EXISTS whodunit_chronicles_audits (
-            id BIGINT AUTO_INCREMENT PRIMARY KEY,
-            table_name TEXT NOT NULL,
-            schema_name TEXT NOT NULL DEFAULT 'public',
-            record_id JSON,
-            action TEXT NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
-            old_data JSON,
-            new_data JSON,
-            changes JSON,
-            user_id BIGINT,
-            user_type TEXT,
-            transaction_id TEXT,
-            sequence_number INTEGER,
-            occurred_at TIMESTAMP NOT NULL,
-            created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
-            metadata JSON DEFAULT (JSON_OBJECT()),
-          #{'  '}
-            -- Constraint for data integrity
-            CONSTRAINT valid_data_for_action CHECK (
-              (action = 'INSERT' AND old_data IS NULL AND new_data IS NOT NULL) OR
-              (action = 'UPDATE' AND old_data IS NOT NULL AND new_data IS NOT NULL) OR
-              (action = 'DELETE' AND old_data IS NOT NULL AND new_data IS NULL)
-            ),
-          #{'  '}
-            -- Performance indexes
-            INDEX idx_chronicles_audits_table_record (table_name(255), (JSON_UNQUOTE(JSON_EXTRACT(record_id, '$.id')))),
-            INDEX idx_chronicles_audits_occurred_at (occurred_at DESC),
-            INDEX idx_chronicles_audits_user (user_id, user_type(255)),
-            INDEX idx_chronicles_audits_action (action(50))
-          );
-        SQL
-
-        @connection.query(create_sql)
-      rescue StandardError => e
-        # Ignore "already exists" errors
-        unless e.message.include?('already exists') ||
-               (e.message.include?('Table') && e.message.include?('already exists'))
-          raise
-        end
-      end
-    end
-  end
-end

data/whodunit-chronicles.gemspec

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/whodunit/chronicles/version'
-
-Gem::Specification.new do |spec|
-  spec.name = 'whodunit-chronicles'
-  spec.version = Whodunit::Chronicles::VERSION
-  spec.authors = ['Ken C. Demanawa', 'Spherical Cow']
-  spec.email = ['kenneth.c.demanawa@gmail.com']
-
-  spec.summary = 'The complete historical record of your data'
-  spec.description = 'While Whodunit tracks who made changes, Chronicles captures ' \
-                     'what changed by streaming database events into comprehensive ' \
-                     'audit trails with zero Rails application overhead.'
-  spec.homepage = 'https://github.com/kanutocd/whodunit-chronicles'
-  spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.2.0'
-
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata['rubygems_mfa_required'] = 'true'
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = 'exe'
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  # ── Core runtime dependencies ───────────────────────────────
-  spec.add_dependency 'concurrent-ruby', '~> 1.2'
-  spec.add_dependency 'dry-configurable', '~> 1.0'
-  spec.add_dependency 'dry-logger', '~> 1.0'
-
-  # ── Database adapters — OPTIONAL at runtime ───────────────────────────────
-  #
-  # Chronicles lazy-loads the driver that matches your configured adapter.
-  # You only need to install the gem for the database(s) you actually use:
-  #
-  #   PostgreSQL  →  gem 'pg', '~> 1.5'
-  #   MySQL/MariaDB → gem 'trilogy', '~> 2.9'
-  #
-  # Both are listed here so `bundle install` in development installs them,
-  # but they are NOT required at gem load time — only when the adapter loads.
-  spec.add_development_dependency 'pg',       '~> 1.5'
-  spec.add_development_dependency 'trilogy',  '~> 2.9'
-
-  # bigdecimal: required by trilogy on Ruby 3.4+ (removed from stdlib).
-  # Declared here so CI on Ruby 3.4+ doesn't break. Trilogy should own this
-  # dependency — track https://github.com/trilogy-libraries/trilogy/issues
-  # Required for Ruby 3.4+ compatibility (trilogy dependency)
-  spec.add_development_dependency 'bigdecimal', '~> 3.1'
-
-  # ── Development tooling ───────────────────────────────
-  spec.add_development_dependency 'kramdown', '~> 2.5'
-  spec.add_development_dependency 'minitest', '~> 5.20'
-  spec.add_development_dependency 'mocha', '~> 2.1'
-  spec.add_development_dependency 'pry', '~> 0.14'
-  spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.6.0'
-  spec.add_development_dependency 'rubocop', '~> 1.60'
-  spec.add_development_dependency 'rubocop-minitest', '~> 0.34'
-  spec.add_development_dependency 'rubocop-performance', '~> 1.19'
-  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
-  spec.add_development_dependency 'rubocop-thread_safety', '~> 0.5'
-  spec.add_development_dependency 'simplecov', '~> 0.22'
-  spec.add_development_dependency 'simplecov-cobertura', '~> 3.0'
-  spec.add_development_dependency 'yard', '~> 0.9'
-
-  # ── Security scanning dependencies ──────────────────────────────
-  spec.add_development_dependency 'brakeman', '~> 7.1'
-  spec.add_development_dependency 'bundler-audit', '~> 0.9'
-end