mammoth 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1249f6166082904d6ecac8d74819442681eaac72ae1e23c80a2134c412e235a
-  data.tar.gz: 292272e0696a218c3a75d970476efa3acaa71d54164da139aefa007bbd256ae5
+  metadata.gz: d7437cc30ed1a50ca4b414c37bc75ba374569ef3cdfafc7b88f0631d5f462790
+  data.tar.gz: d75b6cf2476c892915aa24ceb5169f69889a794cb923e5d1748a7c5a726129e3
 SHA512:
-  metadata.gz: 4e401e3a8a1778ac6b63338636cc15d5c06ccbeea77e2179af1189ba8d60d1005a2281884e3cc3a09208ac4836f37d94132ab16c3f00b08edfb1c3347fe0e944
-  data.tar.gz: fe8efe54a12f5dae1960eb4cf34c91b1eacd1d91a8609c082349b2a4e900ebda7f5160052b8f7d3bf062b09d16bb84438712f0f7d514ff23b4b16606da8b279a
+  metadata.gz: b38367dbafad260559c1f80558d2aeb6f452688fc1404b5652dbd8310625fbe0058eb2ac45ab0dea9dc226b19e0447efca79ff8a70556f3b10f24ba1ebd2e8c9
+  data.tar.gz: f7950310f899a5291889853f95b096937b51332899c8adabe7209e6bef3b5c186863cc37bc0cb331e06a51c3ff5abc15b5049995a0822f07ff51c3076b5b79b5

data/CHANGELOG.md

@@ -1,6 +1,32 @@
 # Changelog
 
-## Unreleased
+## 0.7.1 Unreleased
+
+### Added
+
+- Added local lifecycle hooks for start, shutdown, and dead-letter replay extension points.
+- Added file and hash configuration providers for CLI, tests, and future control-plane integration.
+- Added reusable command objects for validate, bootstrap, start, sample delivery, and dead-letter commands.
+
+### Changed
+
+- Bumped Mammoth version to `0.7.1`.
+
+## 0.7.0
+
+### Added
+
+- Added explicit adapter registries for operational state, destinations, and delivery runtimes.
+- Added the built-in SQLite operational state adapter.
+- Added the built-in webhook destination adapter registration.
+- Added inline and concurrent runtime adapter registration.
+- Added optional node identity configuration for future control-plane integration.
+- Added local capability reporting for state, destination, runtime, and relay features.
+- Added a reusable status command object behind the CLI status command.
+
+### Changed
+
+- Bumped Mammoth version to `0.7.0`.
 
 ## 0.6.0
 

data/README.md

@@ -57,6 +57,9 @@ https://kanutocd.github.io/mammoth/Mammoth.html
 - public Helm chart support
 - unit and e2e test tasks
 - health and metrics endpoints
+- explicit extension registries for state, destination, and runtime adapters
+- node identity and local capability reporting
+- lifecycle hooks, configuration providers, and reusable local command objects
 
 ## Boundary
 
@@ -66,6 +69,19 @@ Mammoth does not own pgoutput protocol parsing, value decoding, source
 normalization, ordering policy, or runtime execution. Those belong to the
 upstream CDC Ecosystem components.
 
+## Extensions
+
+Mammoth OSS exposes small adapter registries for future extensions:
+
+- operational state adapters
+- destination adapters
+- runtime adapters
+- lifecycle hooks
+- configuration providers
+- local command objects
+
+See [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md).
+
 ## Configuration
 
 Mammoth configuration is YAML-backed and IDE-friendly.

data/config/mammoth.example.yml

@@ -34,6 +34,19 @@ mammoth:
   #   production_mammoth
   name: local_mammoth
 
+node:
+  # Optional local node identity for status output and future control-plane
+  # agents. Omit this section to default node_id to the host name and node_name
+  # to mammoth.name.
+  node_id: local-mammoth-1
+  node_name: local-mammoth-dev
+  fleet_id: local-dev
+  environment: development
+  labels:
+    region: local
+  metadata:
+    owner: platform
+
 postgres:
   # PostgreSQL host reachable from the Mammoth process or pod.
   #
@@ -331,6 +344,10 @@ sqlite:
   # records here. In Kubernetes, back this path with a PersistentVolumeClaim.
   path: data/mammoth.db
 
+operational_state:
+  # Mammoth OSS 0.7.x ships the sqlite operational state adapter.
+  adapter: sqlite
+
 observability:
   # Bind host for the optional health, readiness, and metrics server.
   host: 0.0.0.0

data/config/mammoth.schema.json

@@ -40,6 +40,47 @@
       },
       "description": "Mammoth instance identity and operator-facing metadata."
     },
+    "node": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "node_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable node identifier used by status output and future control-plane agents."
+        },
+        "node_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable node name."
+        },
+        "fleet_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional fleet identifier for grouping Mammoth nodes."
+        },
+        "environment": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional deployment environment such as development, staging, or production."
+        },
+        "labels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Operator-defined node labels."
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Operator-defined node metadata."
+        }
+      },
+      "description": "Optional local node identity. Mammoth OSS uses this for status and future extension surfaces only."
+    },
     "postgres": {
       "type": "object",
       "additionalProperties": false,
@@ -223,7 +264,7 @@
             "enum": [
               "webhook"
             ],
-            "description": "Destination adapter type. Mammoth OSS 0.6.0 supports webhook destinations."
+            "description": "Destination adapter type. Mammoth OSS 0.7.x supports webhook destinations."
           },
           "enabled": {
             "type": "boolean",
@@ -385,6 +426,20 @@
       },
       "description": "SQLite operational store settings for checkpoints, attempts, and dead-letter records."
     },
+    "operational_state": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "adapter": {
+          "type": "string",
+          "enum": [
+            "sqlite"
+          ],
+          "description": "Operational state adapter. Mammoth OSS 0.7.x ships the sqlite adapter."
+        }
+      },
+      "description": "Operational state adapter selection. SQLite remains the default OSS adapter."
+    },
     "logging": {
       "type": "object",
       "additionalProperties": false,

data/lib/mammoth/application.rb

@@ -10,25 +10,62 @@ module Mammoth
   # injected CDC work source rather than owning upstream CDC source-adapter
   # lifecycle decisions.
   class Application
-    attr_reader :config, :sqlite_store, :consumer, :delivery_worker, :checkpoint_store
+    attr_reader :config, :state_adapter, :consumer, :delivery_worker, :checkpoint_store, :lifecycle_hooks
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param source [#each, nil] injectable event source for tests and demos
     # @param sink [#deliver, nil] optional destination sink
     # @param sleeper [#call] retry sleep strategy
-    def initialize(config, source: nil, sink: nil, sleeper: Kernel.method(:sleep))
+    # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
+    def initialize(config, source: nil, sink: nil, sleeper: Kernel.method(:sleep), lifecycle_hooks: LifecycleHooks.new)
       @config = config
-      @sqlite_store = SQLiteStore.connect(config.dig("sqlite", "path")).bootstrap!
-      @checkpoint_store = CheckpointStore.new(sqlite_store)
+      @lifecycle_hooks = build_lifecycle_hooks(lifecycle_hooks)
+      @state_adapter = build_state_adapter
+      @checkpoint_store = state_adapter.checkpoint_store
       @consumer = ReplicationConsumer.new(source: source || build_source, delivery_unit: delivery_unit)
       @delivery_worker = sink ? build_delivery_worker(sink: sink, sleeper: sleeper) : build_configured_delivery_worker(sleeper:)
     end
 
+    # @return [Mammoth::SQLiteStore] underlying SQLite store for compatibility
+    def sqlite_store
+      state_adapter.respond_to?(:sqlite_store) ? state_adapter.sqlite_store : nil
+    end
+
     # Start the application runtime and deliver consumed CDC work.
     #
     # @return [Integer] number of processed work units
     def start
       runtime = build_runtime
+      processed = nil
+
+      lifecycle_hooks.call(:before_start, application_context(runtime: runtime))
+      processed = process_consumer(runtime)
+      lifecycle_hooks.call(:after_start, application_context(runtime: runtime, processed: processed))
+      processed
+    ensure
+      lifecycle_hooks.call(:before_shutdown, application_context(runtime: runtime, processed: processed))
+      runtime.shutdown if runtime.respond_to?(:shutdown)
+      lifecycle_hooks.call(:after_shutdown, application_context(runtime: runtime, processed: processed))
+    end
+
+    private
+
+    def build_lifecycle_hooks(hooks)
+      return hooks if hooks.is_a?(LifecycleHooks)
+
+      LifecycleHooks.new(hooks)
+    end
+
+    def application_context(extra = {})
+      {
+        config: config,
+        state_adapter: state_adapter,
+        checkpoint_store: checkpoint_store,
+        delivery_worker: delivery_worker
+      }.merge(extra)
+    end
+
+    def process_consumer(runtime)
       processed = 0
       batch = [nil].compact
 
@@ -45,22 +82,17 @@ module Mammoth
         end
       end
 
-      processed += process_batch(runtime, batch) if runtime_batching?(runtime) && batch.any?
-      processed
-    ensure
-      runtime.shutdown if runtime.respond_to?(:shutdown)
+      processed + flush_batch(runtime, batch)
     end
 
-    private
+    def flush_batch(runtime, batch)
+      return 0 unless runtime_batching?(runtime) && batch.any?
+
+      process_batch(runtime, batch)
+    end
 
     def process_work(runtime, work)
-      if runtime
-        runtime.process_many([work])
-      elsif transaction_delivery?
-        delivery_worker.deliver_transaction(work)
-      else
-        delivery_worker.deliver(work)
-      end
+      runtime.process_many([work])
     end
 
     def process_batch(runtime, batch)
@@ -73,9 +105,8 @@ module Mammoth
     end
 
     def build_runtime
-      return unless runtime_adapter == "concurrent"
-
-      ConcurrentDeliveryRuntime.new(
+      Runtimes::Registry.build(
+        runtime_adapter,
         processor: DeliveryProcessor.new(delivery_worker:, delivery_unit: delivery_unit),
         concurrency: runtime_concurrency,
         timeout: runtime_timeout,
@@ -92,7 +123,7 @@ module Mammoth
         config,
         sink: sink,
         checkpoint_store: checkpoint_store,
-        dead_letter_store: DeadLetterStore.new(sqlite_store),
+        dead_letter_store: state_adapter.dead_letter_store,
         sleeper: sleeper,
         delivery_policy: delivery_policy
       )
@@ -116,7 +147,7 @@ module Mammoth
 
       destinations.map.with_index(1) do |destination, index|
         {
-          sink: WebhookSink.from_destination_config(destination, label: "destinations[#{index - 1}]"),
+          sink: Destinations::Registry.build(destination, label: "destinations[#{index - 1}]"),
           delivery_policy: destination_delivery_policy(destination)
         }
       end
@@ -132,8 +163,12 @@ module Mammoth
       }
     end
 
-    def transaction_delivery?
-      delivery_unit == :transaction
+    def build_state_adapter
+      OperationalState::Registry.build(operational_state_adapter, config)
+    end
+
+    def operational_state_adapter
+      config.dig("operational_state", "adapter") || "sqlite"
     end
 
     def delivery_unit

data/lib/mammoth/capabilities.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Reports local Mammoth capabilities without inspecting private internals.
+  class Capabilities
+    # Built-in OSS data-plane feature capabilities.
+    FEATURES = %w[
+      checkpointing
+      delivery_ledger
+      dead_letters
+      replay
+      health
+      metrics
+      routing
+      fanout
+    ].freeze
+
+    attr_reader :config
+
+    # @param config [Mammoth::Configuration] loaded configuration
+    def initialize(config)
+      @config = config
+    end
+
+    # @param config [Mammoth::Configuration] loaded configuration
+    # @return [Hash] JSON-friendly capabilities
+    def self.call(config)
+      new(config).to_h
+    end
+
+    # @return [Hash] JSON-friendly capabilities
+    def to_h
+      {
+        operational_state: operational_state_adapter,
+        destinations: destination_types,
+        runtimes: Runtimes::Registry.names,
+        runtime: runtime_adapter,
+        features: FEATURES
+      }
+    end
+
+    private
+
+    def operational_state_adapter
+      config.dig("operational_state", "adapter") || "sqlite"
+    end
+
+    def runtime_adapter
+      config.dig("runtime", "adapter") || "inline"
+    end
+
+    def destination_types
+      destinations = config.data["destinations"]
+      return [config.dig("webhook", "type") || "webhook"] unless destinations
+
+      destinations.map { |destination| destination.fetch("type", "webhook") }.uniq.sort
+    end
+  end
+end

data/lib/mammoth/cdc_source.rb

@@ -3,7 +3,7 @@
 module Mammoth
   # Backwards-compatible internal alias for the PostgreSQL CDC source.
   #
-  # New code should use {Mammoth::Sources::Postgres}. Mammoth v0.1.0 keeps this
+  # New code should use {Mammoth::Sources::Postgres}. Mammoth keeps this
   # constant so older tests or examples that referenced the transitional
   # CdcSource name continue to work while the product-facing source name moves
   # to PostgreSQL.

data/lib/mammoth/cli.rb

@@ -85,53 +85,37 @@ module Mammoth
     end
 
     def validate
-      load_config
-      puts "Configuration OK: #{config_path}"
-      0
+      require_config_path!
+      Commands::ValidateCommand.new(config_provider).call
     end
 
     def bootstrap
-      config = load_config
-      store = SQLiteStore.connect(config.dig("sqlite", "path")).bootstrap!
-      puts "SQLite database initialized"
-      puts "Path: #{store.path}"
-      puts "Tables: #{store.tables.join(", ")}"
-      0
+      Commands::BootstrapCommand.new(load_config).call
     end
 
     def status
       config = load_config
       store = SQLiteStore.connect(config.dig("sqlite", "path"))
-      Status.call(config, sqlite_store: store)
-      0
+      Commands::StatusCommand.new(config, sqlite_store: store).call
     end
 
     def start
-      config = load_config
-      processed = Application.new(config).start
-      puts "Processed events: #{processed}"
-      0
+      Commands::StartCommand.new(load_config).call
     end
 
     def deliver_sample
       config = load_config
       event_path = argv.fetch(2, nil)
       raise ConfigurationError, "event JSON path required\n#{USAGE}" unless event_path
-      raise ConfigurationError, "event JSON file not found: #{event_path}" unless File.file?(event_path)
 
-      event = JSON.parse(File.read(event_path))
-      processed = Application.new(config, source: [event]).start
-      puts "Processed sample events: #{processed}"
-      0
-    rescue JSON::ParserError => e
-      raise ConfigurationError, "invalid event JSON in #{event_path}: #{e.message}"
+      Commands::DeliverSampleCommand.new(config, event_path: event_path).call
     end
 
     # Dispatch the nested dead-letter command group.
     #
     # @return [Integer] process status code
     def dead_letters
-      DeadLetterCommands.call(argv)
+      Commands::DeadLettersCommand.new(argv).call
     end
 
     def observability
@@ -143,9 +127,17 @@ module Mammoth
     end
 
     def load_config
+      require_config_path!
+
+      config_provider.load
+    end
+
+    def require_config_path!
       raise ConfigurationError, "configuration path required\n#{USAGE}" unless config_path
+    end
 
-      Configuration.load(config_path)
+    def config_provider
+      Configuration::Providers::FileProvider.new(config_path)
     end
   end
 end

data/lib/mammoth/commands/bootstrap_command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Commands
+    # Initializes the configured operational SQLite database.
+    class BootstrapCommand
+      attr_reader :config, :output
+
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @param output [#puts] output stream
+      def initialize(config, output: $stdout)
+        @config = config
+        @output = output
+      end
+
+      # @return [Integer] process-style status code
+      def call
+        store = SQLiteStore.connect(config.dig("sqlite", "path")).bootstrap!
+        output.puts "SQLite database initialized"
+        output.puts "Path: #{store.path}"
+        output.puts "Tables: #{store.tables.join(", ")}"
+        0
+      end
+    end
+  end
+end

data/lib/mammoth/commands/dead_letters_command.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Commands
+    # Reusable local command object for dead-letter inspection and replay.
+    class DeadLettersCommand
+      attr_reader :argv, :lifecycle_hooks
+
+      # @param argv [Array<String>] dead-letters CLI-style arguments
+      # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
+      def initialize(argv, lifecycle_hooks: LifecycleHooks.new)
+        @argv = argv
+        @lifecycle_hooks = lifecycle_hooks
+      end
+
+      # @return [Integer] process-style status code
+      def call
+        DeadLetterCommands.call(argv, lifecycle_hooks: lifecycle_hooks)
+      end
+    end
+  end
+end

data/lib/mammoth/commands/deliver_sample_command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mammoth
+  module Commands
+    # Delivers one JSON event file through the configured local application.
+    class DeliverSampleCommand
+      attr_reader :config, :event_path, :output, :lifecycle_hooks
+
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @param event_path [String] event JSON path
+      # @param output [#puts] output stream
+      # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
+      def initialize(config, event_path:, output: $stdout, lifecycle_hooks: LifecycleHooks.new)
+        @config = config
+        @event_path = event_path
+        @output = output
+        @lifecycle_hooks = lifecycle_hooks
+      end
+
+      # @return [Integer] process-style status code
+      def call
+        raise ConfigurationError, "event JSON file not found: #{event_path}" unless File.file?(event_path)
+
+        event = JSON.parse(File.read(event_path))
+        processed = Application.new(config, source: [event], lifecycle_hooks: lifecycle_hooks).start
+        output.puts "Processed sample events: #{processed}"
+        0
+      rescue JSON::ParserError => e
+        raise ConfigurationError, "invalid event JSON in #{event_path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mammoth/commands/start_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Commands
+    # Starts a Mammoth application and prints the processed work count.
+    class StartCommand
+      attr_reader :config, :source, :output, :lifecycle_hooks
+
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @param source [#each, nil] optional injected source
+      # @param output [#puts] output stream
+      # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
+      def initialize(config, source: nil, output: $stdout, lifecycle_hooks: LifecycleHooks.new)
+        @config = config
+        @source = source
+        @output = output
+        @lifecycle_hooks = lifecycle_hooks
+      end
+
+      # @return [Integer] process-style status code
+      def call
+        processed = Application.new(config, source: source, lifecycle_hooks: lifecycle_hooks).start
+        output.puts "Processed events: #{processed}"
+        0
+      end
+    end
+  end
+end

data/lib/mammoth/commands/status_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Local command objects shared by CLI and future control-plane agents.
+  module Commands
+    # Reusable local command object for status inspection.
+    class StatusCommand
+      attr_reader :config, :sqlite_store, :output
+
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @param sqlite_store [Mammoth::SQLiteStore, nil] optional operational store
+      # @param output [#puts] output stream
+      def initialize(config, sqlite_store: nil, output: $stdout)
+        @config = config
+        @sqlite_store = sqlite_store
+        @output = output
+      end
+
+      # Execute the status command.
+      #
+      # @return [Integer] process-style status code
+      def call
+        Status.call(config, sqlite_store: sqlite_store, output: output)
+        0
+      end
+    end
+  end
+end

data/lib/mammoth/commands/validate_command.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Commands
+    # Validates a Mammoth configuration through a provider.
+    class ValidateCommand
+      attr_reader :provider, :output
+
+      # @param provider [#load] configuration provider
+      # @param output [#puts] output stream
+      def initialize(provider, output: $stdout)
+        @provider = provider
+        @output = output
+      end
+
+      # @return [Integer] process-style status code
+      def call
+        config = provider.load
+        output.puts "Configuration OK: #{config.path}"
+        0
+      end
+    end
+  end
+end