mammoth 0.6.0 → 0.7.1

data/lib/mammoth/configuration.rb

@@ -5,7 +5,7 @@ require "json-schema"
 require "yaml"
 
 module Mammoth
-  # Loads and validates Mammoth YAML configuration.
+  # Loads and validates Mammoth configuration.
   #
   # Configuration is intentionally schema-backed so the same contract can power
   # editor IntelliSense, preflight validation, and runtime startup checks.
@@ -22,15 +22,27 @@ module Mammoth
     # @return [Mammoth::Configuration] loaded configuration
     # @raise [Mammoth::ConfigurationError] when the file is missing or invalid
     def self.load(path, schema_path: DEFAULT_SCHEMA_PATH)
-      new(path, schema_path: schema_path).load
+      Providers::FileProvider.new(path).load(schema_path: schema_path)
+    end
+
+    # Build and validate a configuration from an in-memory Hash.
+    #
+    # @param data [Hash] configuration data
+    # @param path [String, nil] optional display path/source
+    # @param schema_path [String] JSON Schema path
+    # @return [Mammoth::Configuration] loaded configuration
+    # @raise [Mammoth::ConfigurationError] when the data is invalid
+    def self.from_hash(data, path: nil, schema_path: DEFAULT_SCHEMA_PATH)
+      Providers::HashProvider.new(data, path: path).load(schema_path: schema_path)
     end
 
     # @param path [String] YAML configuration path
     # @param schema_path [String] JSON Schema path
-    def initialize(path, schema_path: DEFAULT_SCHEMA_PATH)
+    # @param data [Hash, nil] already parsed configuration data
+    def initialize(path, schema_path: DEFAULT_SCHEMA_PATH, data: nil)
       @path = path
       @schema_path = schema_path
-      @data = nil
+      @data = data
     end
 
     # Load and validate the configuration file.
@@ -38,9 +50,7 @@ module Mammoth
     # @return [Mammoth::Configuration] self
     # @raise [Mammoth::ConfigurationError] when validation fails
     def load
-      raise ConfigurationError, "configuration file not found: #{path}" unless File.file?(path)
-
-      @data = YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+      @data ||= load_yaml_file
       raise ConfigurationError, "configuration must be a YAML mapping" unless data.is_a?(Hash)
 
       validate_schema!
@@ -60,6 +70,12 @@ module Mammoth
 
     private
 
+    def load_yaml_file
+      raise ConfigurationError, "configuration file not found: #{path}" unless path && File.file?(path)
+
+      YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+    end
+
     def validate_schema!
       raise ConfigurationError, "schema file not found: #{schema_path}" unless File.file?(schema_path)
 
@@ -85,5 +101,48 @@ module Mammoth
 
       raise ConfigurationError, "destination names must be unique: #{duplicates.join(", ")}"
     end
+
+    # Configuration provider contracts shared by CLI and future control agents.
+    module Providers
+      # Loads configuration from a YAML file.
+      class FileProvider
+        attr_reader :path
+
+        # @param path [String] YAML configuration path
+        def initialize(path)
+          @path = path
+        end
+
+        # @param schema_path [String] JSON Schema path
+        # @return [Mammoth::Configuration]
+        def load(schema_path: Configuration::DEFAULT_SCHEMA_PATH)
+          Configuration.new(path, schema_path: schema_path).load
+        end
+      end
+
+      # Loads configuration from an already parsed Hash.
+      class HashProvider
+        attr_reader :data, :path
+
+        # @param data [Hash] configuration data
+        # @param path [String, nil] optional source name for diagnostics/status
+        def initialize(data, path: nil)
+          @data = data
+          @path = path || "<hash>"
+        end
+
+        # @param schema_path [String] JSON Schema path
+        # @return [Mammoth::Configuration]
+        def load(schema_path: Configuration::DEFAULT_SCHEMA_PATH)
+          Configuration.new(path, schema_path: schema_path, data: deep_copy(data)).load
+        end
+
+        private
+
+        def deep_copy(value)
+          Marshal.load(Marshal.dump(value))
+        end
+      end
+    end
   end
 end

data/lib/mammoth/dead_letter_commands.rb

@@ -17,16 +17,18 @@ module Mammoth
       :metadata
     )
 
-    attr_reader :argv
+    attr_reader :argv, :lifecycle_hooks
 
     # @param argv [Array<String>] command line arguments
-    def self.call(argv)
-      new(argv).call
+    def self.call(argv, lifecycle_hooks: LifecycleHooks.new)
+      new(argv, lifecycle_hooks: lifecycle_hooks).call
     end
 
     # @param argv [Array<String>] command line arguments
-    def initialize(argv)
+    # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
+    def initialize(argv, lifecycle_hooks: LifecycleHooks.new)
       @argv = argv
+      @lifecycle_hooks = lifecycle_hooks.is_a?(LifecycleHooks) ? lifecycle_hooks : LifecycleHooks.new(lifecycle_hooks)
     end
 
     # Dispatch the nested dead-letter subcommand.
@@ -79,11 +81,13 @@ module Mammoth
       rows = replay_rows
       raise ConfigurationError, "no dead letters found to replay" if rows.empty?
 
+      lifecycle_hooks.call(:before_replay, replay_context(rows: rows))
       rows.each do |row|
         result = replay_row(row)
         dead_letter_store.resolve(row.fetch("id")) if replay_resolved?(result)
         puts replay_message(row, result)
       end
+      lifecycle_hooks.call(:after_replay, replay_context(rows: rows))
       0
     end
 
@@ -144,8 +148,6 @@ module Mammoth
 
         raise ConfigurationError, "unexpected argument #{args[index]}\n#{CLI::USAGE}"
       end
-    rescue ArgumentError
-      raise ConfigurationError, "invalid dead letter list option"
     rescue IndexError
       raise ConfigurationError, "missing value for dead letter option"
     end
@@ -188,13 +190,11 @@ module Mammoth
       end
 
       ids.map do |raw_id|
-        id = Integer(raw_id)
+        id = raw_id
         row = dead_letter_store.fetch(id)
         raise ConfigurationError, "dead letter not found: #{id}" unless row
 
         row
-      rescue ArgumentError
-        raise ConfigurationError, "dead letter id must be an integer"
       end
     end
 
@@ -311,6 +311,14 @@ module Mammoth
     def replay_message(row, result)
       "Dead letter #{row.fetch("id")}: #{result.fetch(:status)}"
     end
+
+    def replay_context(extra = {})
+      {
+        config: load_config,
+        dead_letter_store: dead_letter_store,
+        delivery_worker: worker
+      }.merge(extra)
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/mammoth/dead_letter_store.rb

@@ -100,6 +100,10 @@ module Mammoth
       database.get_first_value("SELECT COUNT(*) FROM dead_letters#{where}", values)
     end
 
+    # Count dead letters grouped by destination.
+    #
+    # @param status [String, nil] optional status filter
+    # @return [Array<Hash>] rows with destination_name and count
     def counts_by_destination(status: nil)
       where, values = row_filters(status:)
       database.execute(

data/lib/mammoth/delivered_envelope_store.rb

@@ -93,6 +93,9 @@ module Mammoth
       end
     end
 
+    # Count delivered envelopes grouped by destination.
+    #
+    # @return [Array<Hash>] rows with destination_name and count
     def counts_by_destination
       database.execute(
         "SELECT destination_name, COUNT(*) AS count FROM delivered_envelopes GROUP BY destination_name"

data/lib/mammoth/destinations/adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Destination adapter contracts and registry.
+  module Destinations
+    # Base contract for destination adapters.
+    class Adapter
+      # @return [Hash] JSON-friendly adapter capabilities
+      def self.capabilities
+        { type: adapter_type }
+      end
+
+      # @return [String] adapter type name
+      def self.adapter_type
+        type = name.split("::").last.to_s.delete_suffix("Adapter").downcase
+        type.empty? ? "adapter" : type
+      end
+    end
+  end
+end

data/lib/mammoth/destinations/registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Destinations
+    # Registry for destination adapters.
+    module Registry
+      class << self
+        # Register a destination adapter.
+        #
+        # @param name [String, Symbol] adapter name
+        # @param adapter [Object] adapter class
+        # @return [Object] registered adapter
+        def register(name, adapter)
+          registry.register(name, adapter)
+        end
+
+        # Fetch a destination adapter.
+        #
+        # @param name [String, Symbol] adapter name
+        # @return [Object] adapter class
+        def fetch(name)
+          registry.fetch(name)
+        end
+
+        # Build a destination sink from config.
+        #
+        # @param destination [Hash] destination config
+        # @param label [String] config label for errors
+        # @return [Object] delivery sink
+        def build(destination, label:)
+          fetch(destination.fetch("type", "webhook")).build(destination, label: label)
+        end
+
+        # @return [Array<String>] registered destination adapter names
+        def names
+          registry.names
+        end
+
+        # @return [Mammoth::Registry] underlying registry
+        def registry
+          @registry ||= Mammoth::Registry.new("destination")
+        end
+      end
+    end
+  end
+end

data/lib/mammoth/destinations/webhook_adapter.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Destinations
+    # Built-in webhook destination adapter.
+    class WebhookAdapter < Adapter
+      class << self
+        # @return [String] adapter type name
+        def adapter_type
+          "webhook"
+        end
+
+        # Build a webhook sink from destination configuration.
+        #
+        # @param destination [Hash] destination configuration
+        # @param label [String] config path label for errors
+        # @return [Mammoth::WebhookSink]
+        def build(destination, label:)
+          WebhookSink.from_destination_config(destination, label: label)
+        end
+
+        # @return [Hash] JSON-friendly capabilities
+        def capabilities
+          { type: adapter_type, delivery_units: %w[event transaction], signing: true, header_env: true }
+        end
+      end
+    end
+  end
+end

data/lib/mammoth/lifecycle_hooks.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Executes optional lifecycle callbacks around local Mammoth operations.
+  #
+  # Hooks are intentionally in-process and explicit. They give extensions and
+  # future control agents stable observation points without changing the data
+  # plane or introducing remote behavior into OSS.
+  class LifecycleHooks
+    EVENTS = %i[
+      before_start
+      after_start
+      before_shutdown
+      after_shutdown
+      before_replay
+      after_replay
+    ].freeze
+    EMPTY_CALLBACKS = [nil].compact.freeze
+
+    attr_reader :callbacks
+
+    # @param callbacks [Hash] lifecycle callbacks keyed by event name
+    def initialize(callbacks = {})
+      @callbacks = normalize(callbacks || {})
+    end
+
+    # @param event [Symbol, String] lifecycle event
+    # @param context [Hash] event context
+    # @return [void]
+    def call(event, context = {})
+      event = event.to_sym
+      raise ConfigurationError, "unknown lifecycle hook: #{event}" unless EVENTS.include?(event)
+
+      callback_list = callbacks.fetch(event, EMPTY_CALLBACKS)
+      # @type var callback_list: untyped
+      Array(callback_list).each do |callback|
+        # @type var callback: untyped
+        callback.call(context.merge(event: event))
+      end
+      nil
+    end
+
+    private
+
+    def normalize(callbacks)
+      normalized = {}
+      # @type var normalized: Hash[Symbol, untyped]
+      callbacks.each_with_object(normalized) do |(event, callback), memo|
+        key = event.to_sym
+        raise ConfigurationError, "unknown lifecycle hook: #{key}" unless EVENTS.include?(key)
+
+        memo[key] = Array(callback)
+      end
+    end
+  end
+end

data/lib/mammoth/node_identity.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Mammoth
+  # Local Mammoth node identity used by status and future control-plane agents.
+  class NodeIdentity
+    attr_reader :node_id, :node_name, :fleet_id, :environment, :labels, :metadata
+
+    # @param node_id [String] stable node identifier
+    # @param node_name [String] human-readable node name
+    # @param fleet_id [String, nil] optional fleet identifier
+    # @param environment [String, nil] optional environment name
+    # @param labels [Hash] operator-defined labels
+    # @param metadata [Hash] operator-defined metadata
+    def initialize(node_id:, node_name:, fleet_id: nil, environment: nil, labels: {}, metadata: {})
+      @node_id = node_id
+      @node_name = node_name
+      @fleet_id = fleet_id
+      @environment = environment
+      @labels = labels || {}
+      @metadata = metadata || {}
+    end
+
+    # Build identity from Mammoth configuration.
+    #
+    # @param config [Mammoth::Configuration] loaded configuration
+    # @return [Mammoth::NodeIdentity]
+    def self.from_config(config)
+      identity = config.data["node"] || {}
+      hostname = Socket.gethostname
+      new(
+        node_id: identity["node_id"] || hostname,
+        node_name: identity["node_name"] || config.dig("mammoth", "name") || hostname,
+        fleet_id: identity["fleet_id"],
+        environment: identity["environment"],
+        labels: identity["labels"] || {},
+        metadata: identity["metadata"] || {}
+      )
+    end
+
+    # @return [Hash] JSON-friendly node identity
+    def to_h
+      {
+        node_id: node_id,
+        node_name: node_name,
+        fleet_id: fleet_id,
+        environment: environment,
+        labels: labels,
+        metadata: metadata
+      }
+    end
+  end
+end

data/lib/mammoth/observability_server.rb

@@ -10,7 +10,9 @@ module Mammoth
   # may run it as a sidecar-like process or in a separate process that points at
   # the same SQLite operational database.
   class ObservabilityServer
+    # Default bind host for the observability server.
     DEFAULT_HOST = "0.0.0.0"
+    # Default TCP port for the observability server.
     DEFAULT_PORT = 9393
 
     attr_reader :config, :host, :port, :sqlite_store, :logger, :server

data/lib/mammoth/operational_state/adapter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Operational state adapter contracts and registry.
+  module OperationalState
+    # Base contract for operational state adapters.
+    class Adapter
+      # @return [void]
+      def initialize; end
+
+      # @return [Mammoth::CheckpointStore]
+      def checkpoint_store
+        raise NotImplementedError, "#{self.class} must implement #checkpoint_store"
+      end
+
+      # @return [Mammoth::DeadLetterStore]
+      def dead_letter_store
+        raise NotImplementedError, "#{self.class} must implement #dead_letter_store"
+      end
+
+      # @return [Mammoth::DeliveredEnvelopeStore]
+      def delivered_envelope_store
+        raise NotImplementedError, "#{self.class} must implement #delivered_envelope_store"
+      end
+
+      # @return [Hash] JSON-friendly state summary
+      def summary
+        {
+          adapter: "unknown",
+          checkpoints: checkpoint_store.count,
+          dead_letters: dead_letter_store.count,
+          delivered_envelopes: delivered_envelope_store.count
+        }
+      end
+    end
+  end
+end

data/lib/mammoth/operational_state/registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module OperationalState
+    # Registry for operational state adapters.
+    module Registry
+      class << self
+        # Register an operational state adapter.
+        #
+        # @param name [String, Symbol] adapter name
+        # @param adapter [Object] adapter class
+        # @return [Object] registered adapter
+        def register(name, adapter)
+          registry.register(name, adapter)
+        end
+
+        # Fetch an operational state adapter.
+        #
+        # @param name [String, Symbol] adapter name
+        # @return [Object] adapter class
+        def fetch(name)
+          registry.fetch(name)
+        end
+
+        # Build an operational state adapter from config.
+        #
+        # @param name [String, Symbol] adapter name
+        # @param config [Mammoth::Configuration] loaded configuration
+        # @return [Mammoth::OperationalState::Adapter] adapter instance
+        def build(name, config)
+          fetch(name).from_config(config)
+        end
+
+        # @return [Array<String>] registered operational state adapter names
+        def names
+          registry.names
+        end
+
+        # @return [Mammoth::Registry] underlying registry
+        def registry
+          @registry ||= Mammoth::Registry.new("operational_state")
+        end
+      end
+    end
+  end
+end

data/lib/mammoth/operational_state/sqlite_adapter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module OperationalState
+    # SQLite-backed operational state adapter used by Mammoth OSS.
+    class SQLiteAdapter < Adapter
+      attr_reader :sqlite_store
+
+      # @param sqlite_store [Mammoth::SQLiteStore] bootstrapped SQLite store
+      def initialize(sqlite_store)
+        super()
+        @sqlite_store = sqlite_store.bootstrap!
+      end
+
+      # Build a SQLite state adapter from Mammoth configuration.
+      #
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @return [Mammoth::OperationalState::SQLiteAdapter]
+      def self.from_config(config)
+        new(SQLiteStore.connect(config.dig("sqlite", "path")))
+      end
+
+      # @return [Mammoth::CheckpointStore]
+      def checkpoint_store
+        @checkpoint_store ||= CheckpointStore.new(sqlite_store)
+      end
+
+      # @return [Mammoth::DeadLetterStore]
+      def dead_letter_store
+        @dead_letter_store ||= DeadLetterStore.new(sqlite_store)
+      end
+
+      # @return [Mammoth::DeliveredEnvelopeStore]
+      def delivered_envelope_store
+        @delivered_envelope_store ||= DeliveredEnvelopeStore.new(sqlite_store)
+      end
+
+      # @return [Hash] JSON-friendly SQLite state summary
+      def summary
+        super.merge(adapter: "sqlite", path: sqlite_store.path, tables: sqlite_store.tables)
+      end
+    end
+  end
+end

data/lib/mammoth/registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Small explicit registry for built-in and extension-provided adapters.
+  class Registry
+    attr_reader :namespace, :entries
+
+    # @param namespace [String] human-readable registry name for errors
+    def initialize(namespace)
+      @namespace = namespace
+      @entries = {}
+    end
+
+    # Register an adapter under a stable name.
+    #
+    # @param name [String, Symbol] adapter name
+    # @param adapter [Object] adapter object or class
+    # @return [Object] registered adapter
+    def register(name, adapter)
+      key = normalize_name(name)
+      raise ConfigurationError, "#{namespace} adapter already registered: #{key}" if entries.key?(key)
+
+      entries[key] = adapter
+    end
+
+    # Fetch a registered adapter.
+    #
+    # @param name [String, Symbol] adapter name
+    # @return [Object] registered adapter
+    def fetch(name)
+      key = normalize_name(name)
+      entries.fetch(key) { raise ConfigurationError, "unknown #{namespace} adapter: #{key}" }
+    end
+
+    # @return [Array<String>] registered adapter names
+    def names
+      entries.keys.sort
+    end
+
+    private
+
+    def normalize_name(name)
+      name.to_s
+    end
+  end
+end

data/lib/mammoth/runtimes/adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Delivery runtime adapter contracts and registry.
+  module Runtimes
+    # Base contract for delivery runtime adapters.
+    class Adapter
+      # @return [void]
+      def initialize; end
+
+      # @return [Hash] JSON-friendly adapter capabilities
+      def self.capabilities
+        { type: adapter_type }
+      end
+
+      # @return [String] adapter type name
+      def self.adapter_type
+        type = name.split("::").last.to_s.delete_suffix("Adapter").downcase
+        type.empty? ? "adapter" : type
+      end
+    end
+  end
+end

data/lib/mammoth/runtimes/concurrent_adapter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Runtimes
+    # Runtime adapter backed by Mammoth's existing cdc-concurrent wrapper.
+    class ConcurrentAdapter < Adapter
+      class << self
+        # @return [String] adapter type name
+        def adapter_type
+          "concurrent"
+        end
+
+        # Build a concurrent runtime adapter.
+        #
+        # @param processor [#process] delivery processor
+        # @param concurrency [Integer] worker count
+        # @param timeout [Numeric, nil] optional timeout
+        # @param preserve_order [Boolean] preserve ordering when supported
+        # @return [Mammoth::ConcurrentDeliveryRuntime]
+        def build(processor:, concurrency:, timeout:, preserve_order:)
+          ConcurrentDeliveryRuntime.new(
+            processor: processor,
+            concurrency: concurrency,
+            timeout: timeout,
+            preserve_order: preserve_order
+          )
+        end
+      end
+    end
+  end
+end