whodunit-chronicles 0.3.0 → 0.4.0

data/exe/whodunit-chronicles

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'whodunit/chronicles/cli'
+
+exit Whodunit::Chronicles::CLI.run(ARGV)

data/lib/whodunit/chronicles/chronicler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'cdc_core'
+
+require_relative 'ledger_entry'
+
+module Whodunit
+  module Chronicles
+    # Minimal CDC::Core processor that records change events into a ledger.
+    #
+    # Chronicler is intentionally small. It consumes a {CDC::Core::ChangeEvent},
+    # converts it into an immutable {LedgerEntry}, and appends that entry into
+    # the provided ledger. Scheduling, retries, backpressure, worker pools, and
+    # orchestration belong to CDC runtimes outside this gem.
+    class Chronicler < CDC::Core::Processor
+      # @return [Object] ledger receiving immutable entries
+      attr_reader :ledger
+
+      # Create a chronicler.
+      #
+      # @param ledger [#append] ledger-like object
+      # @param prepare [Boolean] whether to call ledger.prepare! during initialization
+      # @param ensure_indexes [Boolean] whether to call ledger.ensure_indexes! during initialization
+      # @param clock [#now] clock used when creating ledger entries
+      def initialize(ledger:, prepare: true, ensure_indexes: true, clock: Time)
+        @ledger = ledger
+        @clock = clock
+        @ledger.prepare! if prepare && @ledger.respond_to?(:prepare!)
+        @ledger.ensure_indexes! if ensure_indexes && @ledger.respond_to?(:ensure_indexes!)
+      end
+
+      # Process one CDC change event and append one ledger entry.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [CDC::Core::ProcessorResult] standardized processor result
+      def process(event)
+        entry = LedgerEntry.from_change_event(event, clock: @clock)
+        partition_for(entry).append(entry)
+        CDC::Core::ProcessorResult.success(event)
+      rescue StandardError => e
+        CDC::Core::ProcessorResult.failure(
+          e,
+          event: event,
+          processor: self.class.name,
+          retryable: true
+        )
+      end
+
+      private
+
+      # Resolve the ledger partition for an entry.
+      #
+      # @param entry [LedgerEntry] entry being appended
+      # @return [Object] ledger-like target
+      def partition_for(entry)
+        return @ledger.partition_for(entry) if @ledger.respond_to?(:partition_for)
+
+        @ledger
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/cli.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require_relative 'errors'
+require_relative 'ledger_factory'
+
+module Whodunit
+  module Chronicles
+    # Small operational command-line interface for ledger lifecycle tasks.
+    #
+    # The CLI owns book preparation, migration-like operations, index creation,
+    # verification, and status checks. The runtime chronicler only appends
+    # entries into a ledger it has been handed.
+    class CLI
+      # Run a command with argv-style arguments.
+      #
+      # @param argv [Array<String>] command-line arguments
+      # @param out [#puts] output stream
+      # @param err [#puts] error stream
+      # @return [Integer] process-style exit code
+      def self.run(argv, out: $stdout, err: $stderr)
+        new(argv: argv, out: out, err: err).run
+      end
+
+      # Create a CLI instance.
+      #
+      # @param argv [Array<String>] command-line arguments
+      # @param out [#puts] output stream
+      # @param err [#puts] error stream
+      def initialize(argv:, out:, err:)
+        @argv = argv.dup
+        @out = out
+        @err = err
+      end
+
+      # Execute the requested command.
+      #
+      # @return [Integer] process-style exit code
+      def run
+        return usage(0) if @argv.empty? || @argv.first == 'help'
+
+        namespace = @argv.shift
+        command = @argv.shift
+        config_path = @argv.shift
+        options = @argv.dup
+        return usage(1) unless namespace == 'ledger' && command && config_path
+
+        ledger = LedgerFactory.build(load_config(config_path))
+        execute_ledger_command(ledger, command, options)
+      rescue StandardError => e
+        @err.puts(e.message)
+        1
+      end
+
+      private
+
+      # Execute a ledger lifecycle command.
+      def execute_ledger_command(ledger, command, options)
+        case command
+        when 'prepare'
+          return usage(1) unless options.empty?
+
+          ensure_supported!(ledger, :prepare!)
+          ledger.prepare!
+          @out.puts('prepared')
+        when 'migrate'
+          return usage(1) unless options.empty?
+
+          ensure_supported!(ledger, :migrate!)
+          ledger.migrate!
+          @out.puts('migrated')
+        when 'ensure-indexes', 'indexes'
+          return usage(1) unless options.empty?
+
+          ensure_supported!(ledger, :ensure_indexes!)
+          ledger.ensure_indexes!
+          @out.puts('indexes ensured')
+        when 'verify'
+          return usage(1) unless options.empty?
+
+          ensure_supported!(ledger, :verify)
+          raise LedgerError, 'ledger verification failed' unless ledger.verify
+
+          @out.puts('verified')
+        when 'status'
+          return usage(1) unless options.empty? || options == ['--json']
+
+          ensure_supported!(ledger, :status)
+          @out.puts(format_status(ledger.status, options))
+        else
+          return usage(1)
+        end
+        0
+      end
+
+      # Load YAML configuration from disk.
+      def load_config(path)
+        YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: false) || {}
+      end
+
+      # Format status for humans.
+      def format_status(status, options)
+        return JSON.pretty_generate(status) if options == ['--json']
+
+        status.map { |key, value| "#{key}: #{value.inspect}" }.join("\n")
+      end
+
+      # Ensure a ledger supports an operational method.
+      def ensure_supported!(ledger, method_name)
+        return true if ledger.respond_to?(method_name)
+
+        raise LedgerError, "ledger does not support #{method_name}"
+      end
+
+      # Print usage information.
+      def usage(code)
+        @out.puts(<<~TEXT)
+          Usage:
+            whodunit-chronicles ledger prepare CONFIG
+            whodunit-chronicles ledger migrate CONFIG
+            whodunit-chronicles ledger ensure-indexes CONFIG
+            whodunit-chronicles ledger verify CONFIG
+            whodunit-chronicles ledger status CONFIG
+            whodunit-chronicles ledger status CONFIG --json
+        TEXT
+        code
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/errors.rb

@@ -2,42 +2,16 @@
 
 module Whodunit
   module Chronicles
-    # Base error class for all whodunit-chronicles errors.
-    #
-    # Rescuing this class catches every error raised by the gem:
-    #
-    #   begin
-    #     Whodunit::Chronicles.service.start
-    #   rescue Whodunit::Chronicles::Error => e
-    #     logger.error("Chronicles failure: #{e.message}")
-    #   end
+    # Base exception for whodunit-chronicles.
     class Error < StandardError; end
 
-    # Raised when the gem is configured with invalid or missing settings.
-    #
-    # @example
-    #   Whodunit::Chronicles.configure do |c|
-    #     c.adapter = :unknown_db   # => raises ConfigurationError
-    #   end
-    class ConfigurationError < Error; end
-
-    # Raised when a required database driver gem is not installed.
-    #
-    # @example message
-    #   "Could not load the 'pg' gem required for the postgresql adapter.
-    #    Add `gem 'pg', '~> 1.5'` to your Gemfile."
-    class AdapterLoadError < Error; end
-
-    # Raised when a streaming or replication connection fails.
-    class ConnectionError < Error; end
+    # Base exception for ledger-related failures.
+    class LedgerError < Error; end
 
-    # Raised when processing a change event fails.
-    class ProcessingError < Error; end
+    # Raised when an append operation fails before a result can be returned.
+    class AppendError < LedgerError; end
 
-    # Raised when writing an audit record to the audit database fails.
-    class PersistenceError < Error; end
-
-    # Raised when replication related error occurs
-    class ReplicationError < Error; end
+    # Raised when ledger configuration cannot be built.
+    class ConfigurationError < Error; end
   end
 end

data/lib/whodunit/chronicles/ledger.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Whodunit
+  module Chronicles
+    # Base class for append-only audit ledgers.
+    #
+    # Ledger is the minimal storage contract consumed by {Chronicler}. Concrete
+    # ledgers only need to implement {#append}; preparation, indexing, and
+    # partitioning are optional capabilities with safe defaults.
+    class Ledger
+      # Prepare backing storage if the ledger supports schema creation.
+      #
+      # @return [Ledger] this ledger
+      def prepare!
+        self
+      end
+
+      # Ensure useful indexes if the ledger supports index management.
+      #
+      # @return [Ledger] this ledger
+      def ensure_indexes!
+        self
+      end
+
+      # Apply storage evolution steps if the ledger supports migrations.
+      #
+      # @return [Ledger] this ledger
+      def migrate!
+        prepare!
+        ensure_indexes!
+        self
+      end
+
+      # Verify that the ledger is operational.
+      #
+      # @return [Boolean] true when the ledger appears usable
+      def verify
+        true
+      end
+
+      # Return lightweight operational status for this ledger.
+      #
+      # @return [Hash<Symbol, Object>] ledger status
+      def status
+        { adapter: self.class.name, ready: verify }
+      end
+
+      # Return the target ledger for an entry.
+      #
+      # Partition-aware ledgers override this method. Simple ledgers return
+      # themselves.
+      #
+      # @param entry [LedgerEntry] entry being appended
+      # @return [Ledger] ledger that should receive the entry
+      def partition_for(_entry)
+        self
+      end
+
+      # Append an immutable entry to the ledger.
+      #
+      # @param entry [LedgerEntry] entry to persist
+      # @raise [NotImplementedError] when not implemented by a concrete ledger
+      # @return [Object] implementation-defined result
+      def append(_entry)
+        raise NotImplementedError, "#{self.class} must implement #append"
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/ledger_entry.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'cdc_core'
+
+module Whodunit
+  module Chronicles
+    # Immutable audit-domain representation of one CDC::Core::ChangeEvent.
+    class LedgerEntry < Data.define(
+      :event_id,
+      :occurred_at,
+      :recorded_at,
+      :namespace,
+      :entity,
+      :identity,
+      :operation,
+      :actor,
+      :changes,
+      :metadata,
+      :payload
+    )
+      # Build a ledger entry from a normalized CDC change event.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @param clock [#now] clock used for recorded_at and fallback timestamps
+      # @return [LedgerEntry] immutable ledger entry
+      # @raise [TypeError] if event is not a CDC::Core::ChangeEvent
+      def self.from_change_event(event, clock: Time)
+        validate_change_event!(event)
+
+        new(
+          event_id: event_id_for(event),
+          occurred_at: event.occurred_at || clock.now,
+          recorded_at: clock.now,
+          namespace: namespace_for(event),
+          entity: entity_for(event),
+          identity: event.primary_key,
+          operation: event.operation,
+          actor: actor_for(event),
+          changes: changes_for(event),
+          metadata: metadata_for(event),
+          payload: event.to_h
+        )
+      end
+
+      class << self
+        alias_method :from_event, :from_change_event
+      end
+
+      # Convert this entry to a Hash keyed by attribute name.
+      #
+      # @return [Hash<Symbol, Object>] entry attributes
+      def to_h
+        members.to_h { |name| [name, public_send(name)] }
+      end
+
+      # Build a stable ordering identity for per-record ordering.
+      #
+      # @return [String] namespace/entity/identity tuple rendered as a string
+      def ordering_identity
+        [namespace, entity, identity].compact.join(':')
+      end
+
+      # Verify the event type.
+      #
+      # @param event [Object] candidate event
+      # @return [true]
+      def self.validate_change_event!(event)
+        return true if event.is_a?(CDC::Core::ChangeEvent)
+
+        raise TypeError, "expected CDC::Core::ChangeEvent, got #{event.class}"
+      end
+      private_class_method :validate_change_event!
+
+      # Derive a stable event id from CDC source coordinates.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [String] deterministic event id
+      def self.event_id_for(event)
+        require 'digest'
+        Digest::SHA256.hexdigest(Marshal.dump(event.to_h))
+      end
+      private_class_method :event_id_for
+
+      # Source-neutral namespace for the changed entity.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [String] namespace value
+      def self.namespace_for(event)
+        event.schema
+      end
+      private_class_method :namespace_for
+
+      # Source-neutral entity name for the changed record collection.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [String] entity value
+      def self.entity_for(event)
+        event.table
+      end
+      private_class_method :entity_for
+
+      # Extract actor details from event metadata.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [Object, nil] actor metadata
+      def self.actor_for(event)
+        event.metadata[:actor] || event.metadata[:whodunit]
+      end
+      private_class_method :actor_for
+
+      # Extract column changes in a persistence-friendly shape.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [Array<Hash>] changed column records
+      def self.changes_for(event)
+        event.changes.map(&:to_h)
+      end
+      private_class_method :changes_for
+
+      # Extract ledger metadata from CDC event metadata and source coordinates.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [Hash] metadata hash
+      def self.metadata_for(event)
+        event.metadata.to_h.merge(
+          'transaction_id' => event.transaction_id,
+          'source_position' => source_position_for(event),
+          'sequence_number' => event.sequence_number
+        ).compact
+      end
+      private_class_method :metadata_for
+
+      # Source-neutral position for checkpoint/replay correlation.
+      #
+      # @param event [CDC::Core::ChangeEvent] normalized CDC event
+      # @return [String, nil] source position
+      def self.source_position_for(event)
+        event.commit_lsn
+      end
+      private_class_method :source_position_for
+    end
+  end
+end

data/lib/whodunit/chronicles/ledger_factory.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'ledgers/memory_ledger'
+require_relative 'ledgers/file_ledger'
+require_relative 'ledgers/sqlite_ledger'
+
+module Whodunit
+  module Chronicles
+    # Builds ledger instances from simple configuration hashes.
+    class LedgerFactory
+      # Build a ledger from configuration.
+      #
+      # @param config [Hash] configuration hash
+      # @return [Ledger] configured ledger
+      def self.build(config)
+        new(config).build
+      end
+
+      # Create a factory.
+      #
+      # @param config [Hash] configuration hash
+      def initialize(config)
+        @config = stringify_keys(config)
+      end
+
+      # Build the configured ledger.
+      #
+      # @return [Ledger] configured ledger
+      def build
+        ledger = stringify_keys(@config.fetch('ledger', @config))
+        adapter = required_value(ledger, 'adapter')
+
+        case adapter
+        when 'memory'
+          Ledgers::MemoryLedger.new
+        when 'file'
+          Ledgers::FileLedger.new(path: required_value(ledger, 'path'))
+        when 'sqlite'
+          Ledgers::SQLiteLedger.new(path: required_value(ledger, 'path'), table_name: ledger.fetch('table_name', Ledgers::SQLiteLedger::DEFAULT_TABLE))
+        else
+          raise ConfigurationError, "unsupported ledger adapter: #{adapter.inspect}"
+        end
+      end
+
+      private
+
+      # Convert hash keys to strings recursively.
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.to_h { |key, nested| [key.to_s, stringify_keys(nested)] }
+        else
+          value
+        end
+      end
+
+      # Fetch a required config value with a user-facing error.
+      def required_value(config, key)
+        config.fetch(key)
+      rescue KeyError
+        raise ConfigurationError, "missing ledger #{key}"
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/ledgers/file_ledger.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require_relative '../ledger'
+
+module Whodunit
+  module Chronicles
+    module Ledgers
+      # Append-only newline-delimited JSON ledger for simple durable local storage.
+      class FileLedger < Ledger
+        # @return [String] path to the NDJSON ledger file
+        attr_reader :path
+
+        # Create a file-backed ledger.
+        #
+        # @param path [String] path to the NDJSON ledger file
+        def initialize(path:)
+          @path = path.to_s
+        end
+
+        # Ensure the parent directory and ledger file exist.
+        #
+        # @return [FileLedger] this ledger
+        def prepare!
+          directory = File.dirname(path)
+          FileUtils.mkdir_p(directory) unless directory == '.'
+          FileUtils.touch(path)
+          self
+        end
+
+        # Append one entry as one JSON line.
+        #
+        # @param entry [LedgerEntry] entry to append
+        # @return [LedgerEntry] appended entry
+        def append(entry)
+          File.open(path, 'ab') do |file|
+            file.flock(File::LOCK_EX)
+            file.write(JSON.generate(entry.to_h))
+            file.write("\n")
+          end
+          entry
+        end
+
+        # Read all entries from the file as hashes.
+        #
+        # @return [Array<Hash>] decoded ledger lines
+        def entries
+          return [] unless File.exist?(path)
+
+          File.readlines(path, chomp: true).reject(&:empty?).map { |line| JSON.parse(line) }
+        end
+      end
+    end
+  end
+end

data/lib/whodunit/chronicles/ledgers/memory_ledger.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../ledger'
+
+module Whodunit
+  module Chronicles
+    module Ledgers
+      # In-memory append-only ledger for tests, examples, and small scripts.
+      class MemoryLedger < Ledger
+        # @return [Array<LedgerEntry>] appended entries in insertion order
+        attr_reader :entries
+
+        # Create an empty in-memory ledger.
+        def initialize
+          @entries = []
+        end
+
+        # Append an entry to memory.
+        #
+        # @param entry [LedgerEntry] entry to append
+        # @return [LedgerEntry] appended entry
+        def append(entry)
+          @entries << entry
+          entry
+        end
+      end
+    end
+  end
+end