mammoth 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8226f7d0510693efd8d3c88623f346bcd24e88f80935c54581994d23b5a64767
-  data.tar.gz: 69a7da12ff8b589851ea0a51d3a68e7c25a2521c49eaaf222afef0a020a5d524
+  metadata.gz: 137dbf7bc96183b45b2756dcb736884a66a45e920a884d35829f74518f14cef6
+  data.tar.gz: 0dd31f792456297c5ac2e6f16ef6842211a87de63824e2e6707c7bac00a68e59
 SHA512:
-  metadata.gz: 4ecaf03600872e85d979e4c546e2e5f102dea80331ba216d18dd4d8df3c1c09d4c17148634f09b17f755cff86051e2205e290ffe1e4be1a760d9e5851237b179
-  data.tar.gz: 4b8ade4da78b6a4db908fb909c7a11b6dad9572a0d8d4bf3fdb55a55d6b491adb61785b89888deea4c8c9e140cb9c48d78847a5190f4601a03228de4bd6ba577
+  metadata.gz: ff73c21bfee44d9b5c9d2f02535a0fdd2dadc9b86b868b8219305889b54c3ef50c8818092d6d60c65f96b8fa39097104e64cc7cc694af646bdd1208be128d134
+  data.tar.gz: 991cb45e7f3cbeb18afde25f41d0a1f1c4c3479f920c0551ca33ab2b93b266ad48a9bf258e46c79c68164c1deb7c493c5b252f616563d67f98b9df4c49057a08

data/CHANGELOG.md

@@ -1,14 +1,70 @@
 # Changelog
 
-## 0.1.0 - Unreleased
-
-- Rename product and gem from Echo to Mammoth.
-- Position Mammoth OSS as the reliable PostgreSQL change-event delivery appliance.
-- Add pgoutput-client / parser / decoder / source-adapter integration boundary.
-- Serialize CDC-core `ChangeEvent` shaped work into webhook payloads.
-- Flatten CDC-core `TransactionEnvelope` shaped work before sink delivery.
-- Add `mammoth start CONFIG` CLI command for live operation.
-- Add public Helm chart under `charts/mammoth`.
-- Add slim multi-stage Dockerfile for OSS image builds.
-- Add e2e test task and script using real HTTP, SQLite, and filesystem paths.
-- Switch OSS license metadata to MIT.
+## Unreleased
+
+
+## [0.1.0] - 2026-06-17
+
+Initial public release of Mammoth.
+
+### Added
+
+- PostgreSQL logical replication source integration via pgoutput.
+- CDC event normalization through the CDC ecosystem.
+- Webhook delivery destination.
+- SQLite-backed operational state storage.
+- Checkpoint persistence infrastructure.
+- Dead-letter persistence infrastructure.
+- Retry handling for failed webhook deliveries.
+- Configuration validation command.
+- Operational state bootstrap command.
+- Operational status command.
+- Sample event delivery command.
+- Helm chart for Kubernetes deployments.
+- Persistent volume support for SQLite operational state.
+- Example configurations and runnable demonstrations.
+
+### Examples
+
+- `examples/postgres_webhook`
+
+  - Demonstrates webhook delivery using sample CDC-shaped events.
+
+- `examples/live_postgres_webhook`
+
+  - Demonstrates end-to-end PostgreSQL logical replication.
+  - Demonstrates replication slot management.
+  - Demonstrates webhook delivery from live database changes.
+
+- `examples/operational_state`
+
+  - Demonstrates operational state bootstrap.
+  - Demonstrates checkpoint and dead-letter schema initialization.
+
+- `examples/failing_webhook_retry`
+
+  - Demonstrates retry exhaustion behavior.
+  - Demonstrates durable dead-letter persistence.
+
+- `examples/kubernetes_helm`
+
+  - Demonstrates Helm-based deployment.
+  - Demonstrates PVC-backed operational memory.
+
+### Validation
+
+The 0.1.0 release was manually validated through:
+
+- PostgreSQL logical replication slot creation and consumption.
+- Idle replication connections exceeding one hour.
+- Post-idle event delivery.
+- Webhook delivery success path.
+- Webhook failure and dead-letter path.
+- SQLite checkpoint and dead-letter persistence.
+- Helm chart rendering and installation.
+- Kubernetes deployment on Kind.
+- PVC-backed operational state storage.
+
+### Notes
+
+Mammoth currently operates as a single active consumer per PostgreSQL logical replication slot. The default Helm deployment uses a single replica to align with PostgreSQL logical replication semantics.

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/mammoth.svg)](https://badge.fury.io/rb/mammoth)
 [![CI](https://github.com/kanutocd/mammoth/workflows/CI/badge.svg)](https://github.com/kanutocd/mammoth/actions)
-[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.4-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%204.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Mammoth is a self-hosted PostgreSQL event relay focused on reliable delivery
@@ -11,9 +11,7 @@ of database change events.
 ```text
 PostgreSQL
       ↓
-pgoutput-client / parser / decoder
-      ↓
-Pgoutput::SourceAdapter::Cdc
+CDC Ecosystem source adapter
       ↓
 CDC::Core::ChangeEvent
       ↓
@@ -39,7 +37,7 @@ Mammoth OSS includes:
 - webhook delivery sink
 - delivery worker with retry, checkpoint, and DLQ handling
 - CDC-core event serialization boundary
-- pgoutput-client / parser / decoder / source-adapter integration boundary
+- CDC Ecosystem source-adapter integration boundary
 - Docker image support
 - public Helm chart support
 - unit and e2e test tasks

data/config/mammoth.example.yml

@@ -0,0 +1,39 @@
+# yaml-language-server: $schema=./mammoth.schema.json
+
+mammoth:
+  name: local_mammoth
+
+postgres:
+  host: localhost
+  port: 5432
+  database: app_development
+  username: mammoth
+  password_env: MAMMOTH_POSTGRES_PASSWORD
+
+replication:
+  slot: mammoth_prod
+  publications:
+    - mammoth_publication
+  auto_create_slot: false
+  temporary_slot: false
+  feedback_interval: 10.0
+
+webhook:
+  name: primary_webhook
+  url: https://example.com/webhooks/postgres
+  timeout_seconds: 5
+
+retry:
+  max_attempts: 5
+  schedule_seconds:
+    - 1
+    - 5
+    - 30
+    - 60
+    - 300
+
+sqlite:
+  path: data/mammoth.db
+
+logging:
+  level: info

data/config/mammoth.schema.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "id": "https://kanutocd.github.io/mammoth/schema/mammoth.schema.json",
+ "title": "Mammoth Configuration",
+  "type": "object",
+  "additionalProperties": false,
+
+  "required": [
+    "mammoth",
+    "postgres",
+    "replication",
+    "webhook",
+    "retry",
+    "sqlite",
+    "logging"
+  ],
+
+  "properties": {
+    "mammoth": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+
+    "postgres": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host",
+        "port",
+        "database",
+        "username",
+        "password_env"
+      ],
+      "properties": {
+        "host": {
+          "type": "string",
+          "minLength": 1
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "database": {
+          "type": "string",
+          "minLength": 1
+        },
+        "username": {
+          "type": "string",
+          "minLength": 1
+        },
+        "password_env": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+
+    "replication": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "slot",
+        "publications"
+      ],
+      "properties": {
+        "slot": {
+          "type": "string",
+          "minLength": 1
+        },
+        "publications": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "start_lsn": {
+          "type": ["string", "null"]
+        },
+        "auto_create_slot": {
+          "type": "boolean"
+        },
+        "temporary_slot": {
+          "type": "boolean"
+        },
+        "feedback_interval": {
+          "type": "number",
+          "minimum": 0,
+          "exclusiveMinimum": true
+        }
+      }
+    },
+
+    "webhook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "url",
+        "timeout_seconds"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "timeout_seconds": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+
+    "retry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "max_attempts",
+        "schedule_seconds"
+      ],
+      "properties": {
+        "max_attempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "schedule_seconds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "integer",
+            "minimum": 1
+          }
+        }
+      }
+    },
+
+    "sqlite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+
+    "logging": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["level"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": [
+            "debug",
+            "info",
+            "warn",
+            "error"
+          ]
+        }
+      }
+    }
+  }
+}

data/exe/mammoth

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "mammoth"
+
+exit Mammoth::CLI.call(ARGV)

data/lib/mammoth/application.rb

@@ -1,23 +1,25 @@
 # frozen_string_literal: true
 
 module Mammoth
-  # Top-level Mammoth application composition root.
+  # Top-level Mammoth application runtime.
   #
-  # Application wires Mammoth's current v0.1.0 runtime pieces: configuration,
-  # SQLite operational memory, replication boundary, delivery worker, checkpoint
-  # store, dead letter store, and webhook sink.
+  # Application wires Mammoth's delivery-side runtime pieces: configuration,
+  # SQLite operational memory, replication consumer, delivery worker, checkpoint
+  # store, dead letter store, and webhook sink. Upstream PostgreSQL transport
+  # composition stays outside this class so the application runtime consumes an
+  # injected CDC work source rather than owning upstream CDC source-adapter
+  # lifecycle decisions.
   class Application
     attr_reader :config, :sqlite_store, :consumer, :delivery_worker
 
     # @param config [Mammoth::Configuration] loaded configuration
     # @param source [#each, nil] injectable event source for tests and demos
-    # @param adapter [#call, nil] optional source adapter
     # @param sink [#deliver, nil] optional destination sink
     # @param sleeper [#call] retry sleep strategy
-    def initialize(config, source: nil, adapter: nil, sink: nil, sleeper: Kernel.method(:sleep))
+    def initialize(config, source: nil, sink: nil, sleeper: Kernel.method(:sleep))
       @config = config
       @sqlite_store = SQLiteStore.connect(config.dig("sqlite", "path")).bootstrap!
-      @consumer = ReplicationConsumer.new(config, source: source, adapter: adapter)
+      @consumer = ReplicationConsumer.new(source: source)
       @delivery_worker = build_delivery_worker(sink: sink || WebhookSink.from_config(config), sleeper: sleeper)
     end
 

data/lib/mammoth/cdc_source.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Backwards-compatible internal alias for the PostgreSQL CDC source.
+  #
+  # New code should use {Mammoth::Sources::Postgres}. Mammoth v0.1.0 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.
+  CdcSource = Sources::Postgres
+end

data/lib/mammoth/cli.rb

@@ -5,6 +5,7 @@ require "json"
 module Mammoth
   # Small command dispatcher for Mammoth's operator-facing CLI.
   class CLI
+    # Human-readable command usage printed for invalid or incomplete invocations.
     USAGE = [
       "Usage:",
       "  mammoth version",
@@ -88,8 +89,9 @@ module Mammoth
     end
 
     def start
-      processed = Application.new(load_config).start
-      puts "Delivered events: #{processed}"
+      config = load_config
+      processed = Application.new(config, source: Sources::Postgres.new(config)).start
+      puts "Processed events: #{processed}"
       0
     end
 
@@ -101,7 +103,7 @@ module Mammoth
 
       event = JSON.parse(File.read(event_path))
       processed = Application.new(config, source: [event]).start
-      puts "Delivered sample events: #{processed}"
+      puts "Processed sample events: #{processed}"
       0
     rescue JSON::ParserError => e
       raise ConfigurationError, "invalid event JSON in #{event_path}: #{e.message}"

data/lib/mammoth/configuration.rb

@@ -10,7 +10,8 @@ module Mammoth
   # Configuration is intentionally schema-backed so the same contract can power
   # editor IntelliSense, preflight validation, and runtime startup checks.
   class Configuration
-    DEFAULT_SCHEMA_PATH = File.expand_path("../../config/mammoth.schema.json", __dir__)
+    # Default JSON Schema used to validate Mammoth YAML configuration files.
+    DEFAULT_SCHEMA_PATH = File.expand_path("../../config/mammoth.schema.json", __dir__.to_s)
 
     attr_reader :path, :data, :schema_path
 

data/lib/mammoth/delivery_worker.rb

@@ -8,6 +8,7 @@ module Mammoth
   # after success, and persist the failed event to the dead letter queue after
   # retry exhaustion.
   class DeliveryWorker
+    # Default source name used when an event does not provide one.
     DEFAULT_SOURCE = "postgresql"
 
     attr_reader :sink, :checkpoint_store, :dead_letter_store, :retry_schedule, :max_attempts, :sleeper, :source_name,
@@ -50,7 +51,7 @@ module Mammoth
         dead_letter_store: dead_letter_store,
         source_name: config.dig("mammoth", "name"),
         slot_name: config.dig("replication", "slot"),
-        publication_name: config.dig("replication", "publication"),
+        publication_name: Array(config.dig("replication", "publications")).join(","),
         max_attempts: config.dig("retry", "max_attempts"),
         retry_schedule: config.dig("retry", "schedule_seconds"),
         sleeper: sleeper

data/lib/mammoth/event_serializer.rb

@@ -12,6 +12,7 @@ module Mammoth
   # from PostgreSQL-specific message shapes while preserving source metadata such
   # as commit LSN and transaction identity when available.
   class EventSerializer
+    # Default source label used in serialized webhook payloads.
     DEFAULT_SOURCE = "postgresql"
 
     # Serialize an event-like object into a webhook-ready Hash.

data/lib/mammoth/replication_consumer.rb

@@ -1,35 +1,18 @@
 # frozen_string_literal: true
 
 module Mammoth
-  # Consumes CDC-core work items from Mammoth's configured replication source.
+  # Consumes normalized CDC work from an injected source.
   #
-  # ReplicationConsumer is the boundary between upstream CDC ingestion and
-  # sink delivery. Live PostgreSQL ingestion is delegated to {PgoutputSource};
-  # injected sources remain available for unit tests, demos, and e2e fixtures.
+  # ReplicationConsumer is intentionally upstream-agnostic. It does not know
+  # which upstream system produced the work. Its
+  # only job is to consume CDC Ecosystem work, flatten CDC transaction
+  # envelopes, and yield individual change events to the delivery pipeline.
   class ReplicationConsumer
-    attr_reader :config, :source, :adapter
+    attr_reader :source
 
-    # @param config [Mammoth::Configuration] loaded configuration
     # @param source [#each, nil] injectable CDC work stream
-    # @param adapter [#call, nil] optional adapter for injected raw events
-    def initialize(config, source: nil, adapter: nil)
-      @config = config
+    def initialize(source: nil)
       @source = source
-      @adapter = adapter
-    end
-
-    # Return the configured replication slot.
-    #
-    # @return [String]
-    def slot
-      config.dig("replication", "slot")
-    end
-
-    # Return the configured publication.
-    #
-    # @return [String]
-    def publication
-      config.dig("replication", "publication")
     end
 
     # Consume normalized CDC work from the configured source.
@@ -40,36 +23,52 @@ module Mammoth
       return enum_for(:start) unless block_given?
 
       count = 0
+
       each_event do |event|
         yield event
         count += 1
       end
+
       count
     end
 
     private
 
-    def each_event
-      effective_source.each do |raw_work|
-        normalize(raw_work).each { |event| yield event }
+    def each_event(&block)
+      effective_source.each do |work|
+        flatten_cdc_work(work).each(&block)
       end
     end
 
     def effective_source
-      source || PgoutputSource.new(config)
+      source || raise(ReplicationError, "replication source is not configured")
+    end
+
+    def flatten_cdc_work(work)
+      return [] if work.nil?
+      return validate_events(work.events) if transaction_envelope?(work)
+      return work.flat_map { |item| flatten_cdc_work(item) } if work.is_a?(Array)
+
+      validate_events([work])
     end
 
-    def normalize(raw_work)
-      adapted = adapter ? adapter.call(raw_work) : raw_work
-      flatten_cdc_work(adapted)
+    def validate_events(events)
+      events.each { |event| validate_cdc_event!(event) }
     end
 
-    def flatten_cdc_work(work)
-      if transaction_envelope?(work)
-        work.events
-      else
-        Array(work).flat_map { |item| transaction_envelope?(item) ? item.events : item }
-      end
+    def validate_cdc_event!(event)
+      return event if event.respond_to?(:to_h) && cdc_event_hash?(event.to_h)
+
+      raise ReplicationError, "CDC source yielded non-CDC work: #{event.class}"
+    end
+
+    def cdc_event_hash?(event_hash)
+      return false unless event_hash.respond_to?(:key?)
+
+      has_operation = event_hash.key?("operation") || event_hash.key?(:operation)
+      has_position = event_hash.key?("source_position") || event_hash.key?(:source_position) ||
+                     event_hash.key?("commit_lsn") || event_hash.key?(:commit_lsn)
+      has_operation && has_position
     end
 
     def transaction_envelope?(work)

data/lib/mammoth/sources/postgres.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Sources
+    # Concrete PostgreSQL CDC source for Mammoth.
+    #
+    # Postgres realizes the CDC Ecosystem libraries for Mammoth's product
+    # boundary. It composes pgoutput-client, pgoutput-parser,
+    # pgoutput-decoder, and pgoutput-source-adapter into a single source that
+    # yields CDC::Core-shaped work to the delivery runtime.
+    #
+    # This class may mention pgoutput implementation details because it is the
+    # concrete PostgreSQL source adapter used by Mammoth. The rest of Mammoth
+    # should remain source-agnostic and consume only the work yielded here.
+    class Postgres
+      # @return [Mammoth::Configuration] loaded Mammoth configuration
+      attr_reader :config
+      # @return [#start, nil] injected pgoutput-client runner
+      attr_reader :runner
+      # @return [Object, nil] injected pgoutput protocol parser
+      attr_reader :parser
+      # @return [Object, nil] injected pgoutput decoder
+      attr_reader :decoder
+      # @return [Object, nil] injected CDC source adapter
+      attr_reader :adapter
+
+      # Build a PostgreSQL CDC source.
+      #
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @param runner [#start, nil] injected pgoutput-client runner
+      # @param parser [Object, nil] injected pgoutput parser or relation tracker
+      # @param decoder [Object, nil] injected pgoutput decoder
+      # @param adapter [Object, nil] injected source adapter
+      def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil)
+        @config = config
+        @runner = runner
+        @parser = parser
+        @decoder = decoder
+        @adapter = adapter
+      end
+
+      # Stream CDC::Core-shaped work from PostgreSQL logical replication.
+      #
+      # Calling this method starts the injected or configured pgoutput-client
+      # runner. The runner owns the PostgreSQL replication connection and slot
+      # lifecycle; this class only composes the parser, decoder, and adapter
+      # libraries around the stream.
+      #
+      # @yieldparam work [Object] CDC::Core::ChangeEvent or TransactionEnvelope
+      # @return [Enumerator, nil]
+      # @raise [Mammoth::ReplicationError] when the source cannot stream CDC work
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        effective_runner.start do |payload, metadata = nil|
+          process_payload(payload, metadata, &block)
+        end
+        nil
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL CDC source failed: #{e.message}"
+      end
+
+      private
+
+      def process_payload(payload, metadata, &block)
+        parsed = parse_payload(payload)
+        decoded = decode_message(parsed, metadata)
+        normalize_decoded(decoded).each { |work| block.call(work) if work }
+      end
+
+      def parse_payload(payload)
+        parser = effective_parser
+        return parser.process(payload) if parser.respond_to?(:process)
+        return parser.parse(payload) if parser.respond_to?(:parse)
+        return parser.call(payload) if parser.respond_to?(:call)
+
+        raise ReplicationError, "pgoutput parser must respond to #process, #parse, or #call"
+      end
+
+      def decode_message(message, metadata)
+        decoder = effective_decoder
+        if decoder.respond_to?(:decode)
+          return callable_accepts_metadata?(decoder, :decode) ? decoder.decode(message, metadata) : decoder.decode(message)
+        end
+        if decoder.respond_to?(:call)
+          return callable_accepts_metadata?(decoder, :call) ? decoder.call(message, metadata) : decoder.call(message)
+        end
+
+        raise ReplicationError, "pgoutput decoder must respond to #decode or #call"
+      end
+
+      def normalize_decoded(decoded)
+        return [] if decoded.nil?
+        return decoded.flat_map { |item| normalize_decoded(item) } if decoded.is_a?(Array)
+
+        adapter = effective_adapter
+        result = if adapter.respond_to?(:normalize)
+                   adapter.normalize(decoded)
+                 elsif adapter.respond_to?(:call)
+                   adapter.call(decoded)
+                 else
+                   raise ReplicationError, "pgoutput source adapter must respond to #normalize or #call"
+                 end
+
+        result.is_a?(Array) ? result.compact : [result].compact
+      end
+
+      def effective_runner
+        runner || (@effective_runner ||= build_runner)
+      end
+
+      def effective_parser
+        parser || (@effective_parser ||= build_parser)
+      end
+
+      def effective_decoder
+        decoder || (@effective_decoder ||= build_decoder)
+      end
+
+      def effective_adapter
+        adapter || (@effective_adapter ||= build_adapter)
+      end
+
+      def build_runner
+        require_optional!("pgoutput/client", "pgoutput-client")
+
+        Pgoutput::Client::Runner.new(**runner_options)
+      end
+
+      def build_parser
+        require_optional!("pgoutput", "pgoutput-parser")
+
+        Pgoutput::RelationTracker.new
+      end
+
+      def build_decoder
+        require_optional!("pgoutput/decoder", "pgoutput-decoder")
+
+        Pgoutput::Decoder.new
+      end
+
+      def build_adapter
+        require_optional!("pgoutput/source_adapter", "pgoutput-source-adapter")
+
+        Pgoutput::SourceAdapter::Cdc.new
+      end
+
+      def runner_options
+        {
+          database_url: database_url,
+          slot_name: required_config("replication", "slot"),
+          publication_names: required_publications,
+          start_lsn: config.dig("replication", "start_lsn"),
+          auto_create_slot: !config.dig("replication", "auto_create_slot").nil?,
+          temporary_slot: !config.dig("replication", "temporary_slot").nil?
+        }.tap do |options|
+          feedback_interval = config.dig("replication", "feedback_interval")
+          options[:feedback_interval] = feedback_interval unless feedback_interval.nil?
+        end
+      end
+
+      def required_publications
+        publications = required_config("replication", "publications")
+        unless publications.is_a?(Array) && publications.any? &&
+               publications.all? { |publication| publication.is_a?(String) && !publication.empty? }
+          raise ReplicationError, "missing PostgreSQL source config: replication.publications"
+        end
+
+        publications
+      end
+
+      def callable_accepts_metadata?(object, method_name)
+        arity = object.respond_to?(:arity) && method_name == :call ? object.arity : object.method(method_name).arity
+        arity != 1
+      end
+
+      def database_url
+        password = ENV.fetch(required_config("postgres", "password_env"), nil)
+        credentials = required_config("postgres", "username").dup
+        credentials << ":#{password}" if password
+
+        "postgres://#{credentials}@#{required_config("postgres", "host")}:#{required_config("postgres", "port")}/" \
+          "#{required_config("postgres", "database")}"
+      end
+
+      def required_config(*keys)
+        value = config.dig(*keys)
+        raise ReplicationError, "missing PostgreSQL source config: #{keys.join(".")}" if value.nil? || value == ""
+
+        value
+      end
+
+      def require_optional!(feature, gem_name)
+        require feature
+        true
+      rescue LoadError => e
+        raise ReplicationError, "#{gem_name} is required for PostgreSQL CDC source integration: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mammoth/sqlite_store.rb

@@ -11,10 +11,15 @@ module Mammoth
   # inspectable state required for reliability: schema versions, checkpoints,
   # and dead letters.
   class SQLiteStore
-    DEFAULT_DB_PATH = File.expand_path("../../.sqlite3/mammoth.db", __dir__)
-    MIGRATION_DIR = File.expand_path("sql", __dir__)
+    # Default SQLite database path used by local Mammoth runs.
+    DEFAULT_DB_PATH = File.expand_path("../../.sqlite3/mammoth.db", __dir__.to_s)
+    # Directory containing bundled SQLite schema migration files.
+    MIGRATION_DIR = File.expand_path("sql", __dir__.to_s)
+    # Initial schema migration file applied to new SQLite stores.
     BOOTSTRAP_FILE = "__bootstrap__.sql"
+    # Synthetic schema version recorded after the bootstrap migration succeeds.
     BOOTSTRAP_VERSION = "__bootstrap__"
+    # Table that records applied SQLite schema migrations.
     MIGRATIONS_TABLE = "schema_migrations"
 
     attr_reader :path

data/lib/mammoth/status.rb

@@ -26,6 +26,8 @@ module Mammoth
     # @return [void]
     def call
       puts "Mammoth: #{config.dig("mammoth", "name")}"
+      puts "Replication slot: #{config.dig("replication", "slot")}"
+      puts "Replication publications: #{Array(config.dig("replication", "publications")).join(", ")}"
       puts "Runtime: not started"
       puts "SQLite: #{sqlite_path}"
       puts "Webhook: #{config.dig("webhook", "name")}"

data/lib/mammoth/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Mammoth
-  VERSION = "0.0.0"
+  # Current Mammoth gem version.
+  VERSION = "0.1.0"
 end

data/lib/mammoth/webhook_sink.rb

@@ -2,11 +2,13 @@
 
 require "json"
 require "net/http"
+require "socket"
 require "uri"
 
 module Mammoth
   # Delivers normalized Mammoth events to a webhook endpoint.
   class WebhookSink
+    # HTTP status range treated as successful webhook delivery.
     SUCCESS_RANGE = 200..299
 
     attr_reader :name, :url, :timeout_seconds

data/lib/mammoth.rb

@@ -10,7 +10,8 @@ require_relative "mammoth/dead_letter_store"
 require_relative "mammoth/event_serializer"
 require_relative "mammoth/webhook_sink"
 require_relative "mammoth/delivery_worker"
-require_relative "mammoth/pgoutput_source"
+require_relative "mammoth/sources/postgres"
+require_relative "mammoth/cdc_source"
 require_relative "mammoth/replication_consumer"
 require_relative "mammoth/application"
 require_relative "mammoth/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -10,63 +10,63 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: json-schema
+  name: cdc-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.2'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.2'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: json-schema
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
+        version: '6.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
+        version: '6.2'
 - !ruby/object:Gem::Dependency
-  name: cdc-core
+  name: pgoutput-client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
-  name: pgoutput-client
+  name: pgoutput-decoder
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: pgoutput-decoder
+  name: pgoutput-parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -80,7 +80,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: pgoutput-parser
+  name: pgoutput-source-adapter
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -94,39 +94,44 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.1'
 - !ruby/object:Gem::Dependency
-  name: pgoutput-source-adapter
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '2.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '2.9'
 description: |
   Mammoth is an OSS PostgreSQL change-event delivery appliance for Ruby.
 
-  It consumes CDC-shaped events produced from the pgoutput family of gems and
-  cdc-core, then delivers those changes to webhook endpoints with durable
+  It realizes the CDC Ecosystem pgoutput and cdc-core libraries for PostgreSQL,
+  then delivers normalized changes to webhook endpoints with durable
   checkpointing, retry state, dead letters, and operational visibility.
 
   Mammoth is application-first: it can be installed as a Ruby gem, packaged
   into a container image, or deployed into Kubernetes with Helm.
 email:
 - kenneth.c.demanawa@gmail.com
-executables: []
+executables:
+- mammoth
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- config/mammoth.example.yml
+- config/mammoth.schema.json
+- exe/mammoth
 - lib/mammoth.rb
 - lib/mammoth/application.rb
+- lib/mammoth/cdc_source.rb
 - lib/mammoth/checkpoint_store.rb
 - lib/mammoth/cli.rb
 - lib/mammoth/configuration.rb
@@ -134,8 +139,8 @@ files:
 - lib/mammoth/delivery_worker.rb
 - lib/mammoth/errors.rb
 - lib/mammoth/event_serializer.rb
-- lib/mammoth/pgoutput_source.rb
 - lib/mammoth/replication_consumer.rb
+- lib/mammoth/sources/postgres.rb
 - lib/mammoth/sql/__bootstrap__.sql
 - lib/mammoth/sqlite_store.rb
 - lib/mammoth/status.rb

data/lib/mammoth/pgoutput_source.rb

@@ -1,166 +0,0 @@
-# frozen_string_literal: true
-
-module Mammoth
-  # Streams PostgreSQL logical replication through the CDC Ecosystem boundary.
-  #
-  # PgoutputSource is Mammoth's upstream integration point. It composes the
-  # standalone pgoutput transport, parser, decoder, and source-adapter gems so
-  # the rest of Mammoth only receives CDC-core domain objects. Transport
-  # resiliency remains owned by pgoutput-client; Mammoth owns delivery.
-  class PgoutputSource
-    # @return [Mammoth::Configuration] loaded Mammoth configuration
-    attr_reader :config
-    # @return [Object, nil] pgoutput-client compatible runner
-    attr_reader :runner
-    # @return [Object, nil] pgoutput-parser compatible parser
-    attr_reader :parser
-    # @return [Object, nil] pgoutput-decoder compatible decoder
-    attr_reader :decoder
-    # @return [Object, nil] CDC source adapter
-    attr_reader :source_adapter
-
-    # Build the pgoutput integration source.
-    #
-    # @param config [Mammoth::Configuration] loaded configuration
-    # @param runner [Object, nil] injectable pgoutput-client runner
-    # @param parser [Object, nil] injectable pgoutput parser
-    # @param decoder [Object, nil] injectable pgoutput decoder
-    # @param source_adapter [Object, nil] injectable CDC source adapter
-    def initialize(config, runner: nil, parser: nil, decoder: nil, source_adapter: nil)
-      @config = config
-      @runner = runner
-      @parser = parser
-      @decoder = decoder
-      @source_adapter = source_adapter
-    end
-
-    # Stream CDC-core objects from PostgreSQL.
-    #
-    # @yieldparam work [Object] CDC::Core::ChangeEvent or TransactionEnvelope
-    # @return [void]
-    # @raise [Mammoth::ReplicationError] when required CDC components are unavailable
-    def each
-      return enum_for(:each) unless block_given?
-
-      effective_runner.start do |payload, metadata|
-        normalized_items(payload, metadata).each { |item| yield item }
-      end
-    end
-
-    private
-
-    def normalized_items(payload, metadata)
-      decoded = effective_decoder ? invoke_component(effective_decoder, parsed_payload(payload), metadata) : parsed_payload(payload)
-      normalized = invoke_source_adapter(decoded, metadata)
-      Array(normalized).flatten
-    end
-
-    def parsed_payload(payload)
-      return payload unless effective_parser
-
-      invoke_component(effective_parser, payload)
-    end
-
-    def invoke_source_adapter(decoded, metadata)
-      adapter = effective_source_adapter
-      if adapter.respond_to?(:normalize)
-        adapter.normalize(decoded)
-      elsif adapter.respond_to?(:call)
-        adapter.call(decoded, metadata)
-      else
-        raise ReplicationError, "pgoutput source adapter must respond to #normalize or #call"
-      end
-    end
-
-    def invoke_component(component, *args)
-      if component.respond_to?(:call)
-        component.call(*args)
-      elsif component.respond_to?(:parse)
-        component.parse(*args)
-      elsif component.respond_to?(:decode)
-        component.decode(*args)
-      else
-        raise ReplicationError, "#{component.class} must respond to #call, #parse, or #decode"
-      end
-    end
-
-    def effective_runner
-      @runner ||= build_runner
-    end
-
-    def effective_parser
-      @parser ||= build_parser
-    end
-
-    def effective_decoder
-      @decoder ||= build_decoder
-    end
-
-    def effective_source_adapter
-      @source_adapter ||= build_source_adapter
-    end
-
-    def build_runner
-      require_optional!("pgoutput_client", "pgoutput-client")
-      Pgoutput::Client::Runner.new(
-        database_url: database_url,
-        slot_name: config.dig("replication", "slot"),
-        publication_names: [config.dig("replication", "publication")],
-        start_lsn: config.dig("replication", "start_lsn"),
-        auto_create_slot: config.dig("replication", "auto_create_slot") || false
-      )
-    end
-
-    def build_parser
-      require_any!(["pgoutput_parser", "pgoutput/parser"], "pgoutput-parser")
-      constant_or_nil("Pgoutput::Parser") || constant_or_nil("Pgoutput::Parser::Parser")
-    end
-
-    def build_decoder
-      require_any!(["pgoutput_decoder", "pgoutput/decoder"], "pgoutput-decoder")
-      constant_or_nil("Pgoutput::Decoder") || constant_or_nil("Pgoutput::Decoder::ValueDecoder")
-    end
-
-    def build_source_adapter
-      require_optional!("cdc_core", "cdc-core")
-      require_any!(["pgoutput_source_adapter", "pgoutput/source_adapter/cdc"], "pgoutput-source-adapter")
-
-      adapter_class = constant_or_nil("Pgoutput::SourceAdapter::Cdc")
-      raise ReplicationError, "Pgoutput::SourceAdapter::Cdc is unavailable" unless adapter_class
-
-      adapter_class.new
-    end
-
-    def database_url
-      password = ENV.fetch(config.dig("postgres", "password_env"), "")
-      user = config.dig("postgres", "username")
-      host = config.dig("postgres", "host")
-      port = config.dig("postgres", "port")
-      database = config.dig("postgres", "database")
-      "postgres://#{user}:#{password}@#{host}:#{port}/#{database}"
-    end
-
-    def require_optional!(feature, gem_name)
-      require feature
-    rescue LoadError => e
-      raise ReplicationError, "#{gem_name} is required for live pgoutput replication: #{e.message}"
-    end
-
-    def require_any!(features, gem_name)
-      errors = []
-      features.each do |feature|
-        require feature
-        return true
-      rescue LoadError => e
-        errors << e.message
-      end
-      raise ReplicationError, "#{gem_name} is required for live pgoutput replication: #{errors.join("; ")}"
-    end
-
-    def constant_or_nil(name)
-      name.split("::").reduce(Object) { |scope, const_name| scope.const_get(const_name, false) }
-    rescue NameError
-      nil
-    end
-  end
-end