whodunit-chronicles 0.1.0 → 0.3.0

data/lib/whodunit/chronicles.rb

@@ -8,11 +8,15 @@ require_relative 'chronicles/version'
 require_relative 'chronicles/configuration'
 require_relative 'chronicles/change_event'
 require_relative 'chronicles/stream_adapter'
-require_relative 'chronicles/audit_processor'
+require_relative 'chronicles/connection'
+require_relative 'chronicles/table'
+require_relative 'chronicles/persistence'
+require_relative 'chronicles/processor'
 require_relative 'chronicles/service'
 
-# Adapters
-require_relative 'chronicles/adapters/postgresql'
+require_relative 'chronicles/errors'
+require_relative 'chronicles/adapter_loader'
+require_relative 'chronicles/composite_processor'
 
 module Whodunit
   # Chronicles - The complete historical record of `whodunit did what?` data
@@ -28,17 +32,15 @@ module Whodunit
     setting :database_url, default: ENV.fetch('DATABASE_URL', nil)
     setting :audit_database_url, default: ENV.fetch('AUDIT_DATABASE_URL', nil)
     setting :adapter, default: :postgresql
+    # PostgreSQL-specific settings
     setting :publication_name, default: 'whodunit_audit'
     setting :replication_slot_name, default: 'whodunit_audit_slot'
+    # MySQL-specific settings
+    setting :mysql_server_id, default: 1001
     setting :batch_size, default: 100
     setting :max_retry_attempts, default: 3
     setting :retry_delay, default: 5
 
-    class Error < StandardError; end
-    class ConfigurationError < Error; end
-    class AdapterError < Error; end
-    class ReplicationError < Error; end
-
     # Configure Chronicles
     #
     # @example
@@ -46,6 +48,9 @@ module Whodunit
     #     config.database_url = "postgresql://localhost/myapp"
     #     config.audit_database_url = "postgresql://localhost/myapp_audit"
     #     config.adapter = :postgresql
+    #     # OR for MySQL:
+    #     config.adapter = :mysql
+    #     config.mysql_server_id = 1001
     #   end
     def self.configure
       yield(config) if block_given?

data/whodunit-chronicles.gemspec

@@ -12,9 +12,9 @@ Gem::Specification.new do |spec|
   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/whodunit-gem/whodunit-chronicles'
+  spec.homepage = 'https://github.com/kanutocd/whodunit-chronicles'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.2.0'
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   spec.metadata['homepage_uri'] = spec.homepage
@@ -33,29 +33,47 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  # Core dependencies
+  # ── 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 dependencies
-  spec.add_dependency 'pg', '~> 1.5'
-  # Driver for MySQL-compatible database
-  # spec.add_dependency 'trilogy', '~> 2.9'
+  # ── 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'
 
-  # Development dependencies
+  # 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', '~> 6.0'
+  # ── Security scanning dependencies ──────────────────────────────
+  spec.add_development_dependency 'brakeman', '~> 7.1'
   spec.add_development_dependency 'bundler-audit', '~> 0.9'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: whodunit-chronicles
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -59,13 +59,41 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: trilogy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
@@ -136,6 +164,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +220,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rubocop-thread_safety
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -192,6 +262,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -212,14 +296,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -243,35 +327,47 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
 - ".rubocop.yml"
 - ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - LICENSE
 - README.md
 - Rakefile
+- docker-compose.yml
+- docker/mysql/init.sql
+- docker/postgres/init.sql
 - examples/images/campaign-performance-analytics.png
 - examples/images/candidate-journey-analytics.png
 - examples/images/recruitment-funnel-analytics.png
 - lib/.gitkeep
 - lib/whodunit-chronicles.rb
 - lib/whodunit/chronicles.rb
+- lib/whodunit/chronicles/adapter_loader.rb
+- lib/whodunit/chronicles/adapters/mysql.rb
 - lib/whodunit/chronicles/adapters/postgresql.rb
-- lib/whodunit/chronicles/audit_processor.rb
 - lib/whodunit/chronicles/change_event.rb
+- lib/whodunit/chronicles/composite_processor.rb
 - lib/whodunit/chronicles/configuration.rb
+- lib/whodunit/chronicles/connection.rb
+- lib/whodunit/chronicles/errors.rb
+- lib/whodunit/chronicles/persistence.rb
+- lib/whodunit/chronicles/processor.rb
 - lib/whodunit/chronicles/service.rb
 - lib/whodunit/chronicles/stream_adapter.rb
+- lib/whodunit/chronicles/table.rb
 - lib/whodunit/chronicles/version.rb
 - whodunit-chronicles.gemspec
-homepage: https://github.com/whodunit-gem/whodunit-chronicles
+homepage: https://github.com/kanutocd/whodunit-chronicles
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/whodunit-gem/whodunit-chronicles
-  source_code_uri: https://github.com/whodunit-gem/whodunit-chronicles
-  changelog_uri: https://github.com/whodunit-gem/whodunit-chronicles/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/kanutocd/whodunit-chronicles
+  source_code_uri: https://github.com/kanutocd/whodunit-chronicles
+  changelog_uri: https://github.com/kanutocd/whodunit-chronicles/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -280,7 +376,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/whodunit/chronicles/audit_processor.rb

@@ -1,270 +0,0 @@
-# frozen_string_literal: true
-
-module Whodunit
-  module Chronicles
-    # Processes database change events and creates audit records
-    #
-    # Transforms ChangeEvent objects into structured audit records
-    # with complete object serialization and metadata.
-    class AuditProcessor
-      attr_reader :logger, :audit_connection
-
-      def initialize(
-        audit_database_url: Chronicles.config.audit_database_url,
-        logger: Chronicles.logger
-      )
-        @audit_database_url = audit_database_url
-        @logger = logger
-        @audit_connection = nil
-      end
-
-      # Process a change event and create audit record
-      #
-      # @param change_event [ChangeEvent] The database change to audit
-      # @return [Hash] The created audit record
-      def process(change_event)
-        ensure_audit_connection
-
-        audit_record = build_audit_record(change_event)
-        persist_audit_record(audit_record)
-
-        log(:debug, 'Processed change event',
-          table: change_event.qualified_table_name,
-          action: change_event.action,
-          audit_id: audit_record[:id])
-
-        audit_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 audit records
-      def process_batch(change_events)
-        return [] if change_events.empty?
-
-        ensure_audit_connection
-
-        audit_records = change_events.map { |event| build_audit_record(event) }
-        persist_audit_records_batch(audit_records)
-
-        log(:info, 'Processed batch of change events', count: change_events.size)
-
-        audit_records
-      rescue StandardError => e
-        log(:error, 'Failed to process batch',
-          error: e.message,
-          count: change_events.size)
-        raise
-      end
-
-      # Close audit database connection
-      def close
-        @audit_connection&.close
-        @audit_connection = nil
-      end
-
-      private
-
-      def ensure_audit_connection
-        return if @audit_connection && !@audit_connection.finished?
-
-        @audit_connection = PG.connect(@audit_database_url || Chronicles.config.database_url)
-        @audit_connection.type_map_for_results = PG::BasicTypeMapForResults.new(@audit_connection)
-
-        ensure_audit_table_exists
-      end
-
-      def ensure_audit_table_exists
-        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
-
-        @audit_connection.exec(create_sql)
-      rescue PG::Error => e
-        # Ignore "already exists" errors from CONCURRENTLY
-        raise unless e.message.include?('already exists')
-      end
-
-      def build_audit_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 persist_audit_record(audit_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 = [
-          audit_record[:table_name],
-          audit_record[:schema_name],
-          audit_record[:record_id].to_json,
-          audit_record[:action],
-          audit_record[:old_data]&.to_json,
-          audit_record[:new_data]&.to_json,
-          audit_record[:changes].to_json,
-          audit_record[:user_id],
-          audit_record[:user_type],
-          audit_record[:transaction_id],
-          audit_record[:sequence_number],
-          audit_record[:occurred_at],
-          audit_record[:created_at],
-          audit_record[:metadata].to_json,
-        ]
-
-        result = @audit_connection.exec_params(sql, params)
-        audit_record[:id] = result.first['id'].to_i
-        result.clear
-
-        audit_record
-      end
-
-      def persist_audit_records_batch(audit_records)
-        return audit_records if audit_records.empty?
-
-        # Use multi-row INSERT for better performance
-        values_clauses = []
-        all_params = []
-        param_index = 1
-
-        audit_records.each do |record|
-          param_positions = (param_index..(param_index + 13)).map { |i| "$#{i}" }.join(', ')
-          values_clauses << "(#{param_positions})"
-
-          all_params.push(
-            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,
-          )
-
-          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 = @audit_connection.exec_params(sql, all_params)
-
-        # Set IDs on the audit records
-        result.each_with_index do |row, index|
-          audit_records[index][:id] = row['id'].to_i
-        end
-
-        result.clear
-        audit_records
-      end
-
-      def log(level, message, context = {})
-        logger.public_send(level, message, processor: 'AuditProcessor', **context)
-      end
-    end
-  end
-end