mammoth 0.8.0 → 1.0.0

data/lib/mammoth/commands/status_command.rb

@@ -5,14 +5,14 @@ module Mammoth
   module Commands
     # Reusable local command object for status inspection.
     class StatusCommand
-      attr_reader :config, :sqlite_store, :output
+      attr_reader :config, :state_adapter, :output
 
       # @param config [Mammoth::Configuration] loaded configuration
-      # @param sqlite_store [Mammoth::SQLiteStore, nil] optional operational store
+      # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
       # @param output [#puts] output stream
-      def initialize(config, sqlite_store: nil, output: $stdout)
+      def initialize(config, state_adapter: nil, output: $stdout)
         @config = config
-        @sqlite_store = sqlite_store
+        @state_adapter = state_adapter || OperationalState::Registry.build_configured(config)
         @output = output
       end
 
@@ -20,7 +20,7 @@ module Mammoth
       #
       # @return [Integer] process-style status code
       def call
-        Status.call(config, sqlite_store: sqlite_store, output: output)
+        Status.call(config, state_adapter: state_adapter, output: output)
         0
       end
     end

data/lib/mammoth/concurrent_delivery_runtime.rb

@@ -7,17 +7,19 @@ module Mammoth
   # I/O fan-out to cdc-concurrent. This class is intentionally small so the
   # runtime boundary remains easy to test and replace.
   class ConcurrentDeliveryRuntime
-    attr_reader :processor, :concurrency, :timeout, :preserve_order, :pool
+    attr_reader :processor, :concurrency, :timeout, :preserve_order, :pool, :observer
 
     # @param processor [#process] delivery processor
     # @param concurrency [Integer] number of concurrent delivery workers
     # @param timeout [Numeric, nil] optional per-item timeout
     # @param preserve_order [Boolean] preserve output order when supported
-    def initialize(processor:, concurrency:, timeout:, preserve_order:)
+    # @param observer [CDC::Core::Observer] dispatch lifecycle observer
+    def initialize(processor:, concurrency:, timeout:, preserve_order:, observer: CDC::Core::Observer.new)
       @processor = processor
       @concurrency = concurrency
       @timeout = timeout
       @preserve_order = preserve_order
+      @observer = observer
       @pool = build_pool
     end
 
@@ -28,7 +30,10 @@ module Mammoth
     def process_many(items)
       return [] if items.empty?
 
-      pool.process_many(items)
+      items.each { |item| observer.dispatch_started(item) }
+      pool.process_many(items).tap do |results|
+        results.each { |result| observe_result(result) }
+      end
     end
 
     # Shutdown the underlying runtime when supported.
@@ -41,6 +46,13 @@ module Mammoth
 
     private
 
+    def observe_result(result)
+      return observer.dispatch_succeeded(result) if result.success?
+      return observer.dispatch_failed(result) if result.failure?
+
+      observer.dispatch_skipped(result)
+    end
+
     def build_pool
       require "cdc/concurrent"
       CDC::Concurrent::ProcessorPool.new(processor:, concurrency:, timeout:, preserve_order:)

data/lib/mammoth/dead_letter_commands.rb

@@ -7,27 +7,19 @@ module Mammoth
   # Operator commands for inspecting and replaying dead letters.
   # rubocop:disable Metrics/ClassLength
   class DeadLetterCommands
-    # Internal replay envelope used for transaction dead-letter recovery.
-    DEAD_LETTER_TRANSACTION_ENVELOPE = Data.define(
-      :events,
-      :transaction_id,
-      :source_position,
-      :commit_lsn,
-      :committed_at,
-      :metadata
-    )
-
     attr_reader :argv, :lifecycle_hooks
 
     # @param argv [Array<String>] command line arguments
-    def self.call(argv, lifecycle_hooks: LifecycleHooks.new)
-      new(argv, lifecycle_hooks: lifecycle_hooks).call
+    def self.call(argv, state_adapter: nil, lifecycle_hooks: LifecycleHooks.new)
+      new(argv, state_adapter: state_adapter, lifecycle_hooks: lifecycle_hooks).call
     end
 
     # @param argv [Array<String>] command line arguments
+    # @param state_adapter [Mammoth::OperationalState::Adapter, nil] operational state dependency
     # @param lifecycle_hooks [Mammoth::LifecycleHooks, Hash] local lifecycle callbacks
-    def initialize(argv, lifecycle_hooks: LifecycleHooks.new)
+    def initialize(argv, state_adapter: nil, lifecycle_hooks: LifecycleHooks.new)
       @argv = argv
+      @state_adapter = state_adapter
       @lifecycle_hooks = lifecycle_hooks.is_a?(LifecycleHooks) ? lifecycle_hooks : LifecycleHooks.new(lifecycle_hooks)
     end
 
@@ -98,11 +90,15 @@ module Mammoth
     end
 
     def dead_letter_store
-      @dead_letter_store ||= DeadLetterStore.new(SQLiteStore.connect(load_config.dig("sqlite", "path")).bootstrap!)
+      @dead_letter_store ||= state_adapter.dead_letter_store
+    end
+
+    def state_adapter
+      @state_adapter ||= OperationalState::Registry.build_configured(load_config)
     end
 
     def worker
-      @worker ||= Application.new(load_config).delivery_worker
+      @worker ||= Application.new(load_config, state_adapter: state_adapter).delivery_worker
     end
 
     def dead_letter_id
@@ -250,9 +246,10 @@ module Mammoth
     end
 
     def replay_event(destination_name, payload)
-      return worker.deliver_to(destination_name, payload) if worker.respond_to?(:deliver_to)
+      event = PersistedPayloadDeserializer.event(payload)
+      return worker.deliver_to(destination_name, event) if worker.respond_to?(:deliver_to)
 
-      worker.deliver(payload)
+      worker.deliver(event)
     end
 
     def replay_transaction(destination_name, envelope)
@@ -270,14 +267,7 @@ module Mammoth
     end
 
     def transaction_envelope(payload)
-      DEAD_LETTER_TRANSACTION_ENVELOPE.new(
-        payload.fetch("events"),
-        payload.fetch("transaction_id"),
-        payload["source_position"],
-        payload["commit_lsn"],
-        payload["committed_at"],
-        payload["metadata"] || {}
-      )
+      PersistedPayloadDeserializer.transaction(payload)
     end
 
     def show_payload(row)
@@ -315,6 +305,7 @@ module Mammoth
     def replay_context(extra = {})
       {
         config: load_config,
+        state_adapter: state_adapter,
         dead_letter_store: dead_letter_store,
         delivery_worker: worker
       }.merge(extra)

data/lib/mammoth/dead_letter_store.rb

@@ -15,7 +15,7 @@ module Mammoth
 
     # Store a failed delivery.
     #
-    # @param event [Hash] normalized event payload
+    # @param event [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] normalized core work item
     # @param destination_name [String] destination name
     # @param error [Exception, nil] delivery failure
     # @param retry_count [Integer] number of delivery attempts

data/lib/mammoth/delivery_processor.rb

@@ -6,7 +6,7 @@ module Mammoth
   # The processor keeps cdc-concurrent integration narrow: cdc-concurrent owns
   # I/O-heavy fan-out mechanics, while DeliveryWorker owns Mammoth relay
   # semantics such as retries, dead letters, and checkpoint writes.
-  class DeliveryProcessor
+  class DeliveryProcessor < CDC::Core::Processor
     @concurrent_safe = false
 
     class << self
@@ -32,13 +32,16 @@ module Mammoth
 
     concurrent_safe!
 
-    attr_reader :delivery_worker, :delivery_unit
+    attr_reader :delivery_worker, :delivery_unit, :progress_coordinator
 
     # @param delivery_worker [Mammoth::DeliveryWorker] relay-aware delivery worker
     # @param delivery_unit [String, Symbol] event or transaction
-    def initialize(delivery_worker:, delivery_unit: :event)
+    # @param progress_coordinator [Mammoth::DeliveryProgressCoordinator, nil] contiguous progress coordinator
+    def initialize(delivery_worker:, delivery_unit: :event, progress_coordinator: nil)
+      super()
       @delivery_worker = delivery_worker
       @delivery_unit = delivery_unit.to_sym
+      @progress_coordinator = progress_coordinator
     end
 
     # @return [Boolean] true when this processor instance is safe for concurrent execution.
@@ -51,7 +54,7 @@ module Mammoth
     # Process one work item from CDC::Concurrent::ProcessorPool.
     #
     # @param work [Object] event or transaction envelope
-    # @return [Hash] delivery summary
+    # @return [CDC::Core::ProcessorResult] normalized processor result
     def call(work)
       process(work)
     end
@@ -59,14 +62,53 @@ module Mammoth
     # Process one work item using the configured delivery unit.
     #
     # @param work [Object] event or transaction envelope
-    # @return [Hash] delivery summary
+    # @return [CDC::Core::ProcessorResult] normalized processor result
     def process(work)
-      case delivery_unit
-      when :transaction
-        delivery_worker.deliver_transaction(work)
+      summary = deliver(work)
+      progress_coordinator&.complete(work)
+      build_result(work, summary)
+    rescue StandardError => e
+      failure_result(work, e, retryable: e.is_a?(DeliveryError))
+    end
+
+    private
+
+    def deliver(work)
+      return delivery_worker.deliver_transaction(work) if delivery_unit == :transaction
+
+      delivery_worker.deliver(work)
+    end
+
+    def build_result(work, summary)
+      case summary[:status].to_s
+      when "skipped"
+        CDC::Core::ProcessorResult.skipped(work, metadata: result_metadata(summary))
+      when "dead_lettered", "fanout_partial"
+        failure_result(work, DeliveryError.new(failure_reason(summary)), retryable: false, summary: summary)
       else
-        delivery_worker.deliver(work)
+        CDC::Core::ProcessorResult.success(work, value: summary, metadata: result_metadata(summary))
       end
     end
+
+    def failure_result(work, error, retryable:, summary: nil)
+      CDC::Core::ProcessorResult.failure(
+        error,
+        event: work,
+        reason: error.message,
+        retryable: retryable,
+        processor: self.class.name,
+        metadata: result_metadata(summary)
+      )
+    end
+
+    def failure_reason(summary)
+      "delivery completed with #{summary.fetch(:status)} status"
+    end
+
+    def result_metadata(summary)
+      metadata = { processor: self.class.name, delivery_unit: delivery_unit.to_s }
+      metadata[:delivery] = summary if summary
+      metadata
+    end
   end
 end

data/lib/mammoth/delivery_progress_coordinator.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Coordinates durable delivery progress across out-of-order workers.
+  #
+  # Work is registered in source order before dispatch. Completion may arrive
+  # in any order, but a checkpoint and upstream acknowledgement advance only
+  # when every item in the oldest closed source group has a durable outcome.
+  # A source group is normally one PostgreSQL transaction.
+  class DeliveryProgressCoordinator
+    # Mutable source transaction tracked by the coordinator.
+    class Group
+      attr_reader :items
+      attr_accessor :closed
+
+      # @param items [Array<DeliveryProgressCoordinator::Entry>] registered work
+      # @param closed [Boolean] whether the source group is complete
+      def initialize(items:, closed:)
+        @items = items
+        @closed = closed
+      end
+    end
+
+    # Mutable completion state for one registered work item.
+    class Entry
+      attr_reader :work, :source_position
+      attr_accessor :completed
+
+      # @param work [Object] registered work
+      # @param source_position [String, Integer, nil] upstream position
+      # @param completed [Boolean] whether a durable outcome was recorded
+      def initialize(work:, source_position:, completed:)
+        @work = work
+        @source_position = source_position
+        @completed = completed
+      end
+    end
+
+    attr_reader :checkpoint_store, :source_name, :slot_name, :publication_name
+
+    # @param checkpoint_store [Mammoth::CheckpointStore] durable checkpoint persistence
+    # @param source_name [String] logical source name
+    # @param slot_name [String] PostgreSQL replication slot name
+    # @param publication_name [String] publication name
+    # @param acknowledger [#call, nil] upstream durable-progress acknowledgement
+    # @param position_resolver [#call, nil] source-owned durable position resolver
+    def initialize(checkpoint_store:, source_name:, slot_name:, publication_name:, acknowledger: nil,
+                   position_resolver: nil)
+      @checkpoint_store = checkpoint_store
+      @source_name = source_name
+      @slot_name = slot_name
+      @publication_name = publication_name
+      @acknowledger = acknowledger
+      @position_resolver = position_resolver
+      # rubocop:disable Layout/LeadingCommentSpace -- Steep inline type syntax requires `#:`.
+      @groups = [] #: Array[Group]
+      @entries_by_work = {} #: Hash[untyped, Array[Entry]]
+      # rubocop:enable Layout/LeadingCommentSpace
+      @entries_by_work.compare_by_identity
+      @mutex = Mutex.new
+    end
+
+    # Register work before dispatch.
+    #
+    # @param work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] work item
+    # @param group_end [Boolean] whether this is the final item in its source group
+    # @return [void]
+    def register(work, group_end:)
+      @mutex.synchronize do
+        group = current_group
+        entry = Entry.new(work: work, source_position: source_position(work), completed: false)
+        group.items << entry
+        (@entries_by_work[work] ||= []) << entry # steep:ignore
+        group.closed = true if group_end
+      end
+      nil
+    end
+
+    # Mark a work item durably resolved and advance all newly contiguous groups.
+    #
+    # @param work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] work item
+    # @return [String, nil] latest source position advanced by this call
+    def complete(work)
+      @mutex.synchronize do
+        entry = pending_entry_for(work)
+        raise ReplicationError, "delivery progress completed before registration" unless entry
+
+        entry.completed = true
+        advance_contiguous_groups
+      end
+    end
+
+    # Close and advance a final source group after a clean end-of-stream.
+    #
+    # @return [String, nil] latest source position advanced by this call
+    def finalize
+      @mutex.synchronize do
+        @groups.last.closed = true if @groups.last
+        advance_contiguous_groups
+      end
+    end
+
+    private
+
+    def current_group
+      return @groups.last if @groups.last && !@groups.last.closed
+
+      Group.new(items: [], closed: false).tap { |group| @groups << group }
+    end
+
+    def pending_entry_for(work)
+      @entries_by_work.fetch(work, []).find { |entry| !entry.completed } # steep:ignore
+    end
+
+    def advance_contiguous_groups
+      advanced_position = nil
+
+      while (group = @groups.first) && group.closed && group.items.all?(&:completed)
+        position = group.items.reverse_each.lazy.map(&:source_position).find { |value| !value.nil? }
+        persist_and_acknowledge(position) if position
+        advanced_position = position || advanced_position
+        remove_group(group)
+      end
+
+      advanced_position
+    end
+
+    def persist_and_acknowledge(position)
+      checkpoint_store.write(
+        source_name: source_name,
+        slot_name: slot_name,
+        publication_name: publication_name,
+        last_lsn: position
+      )
+      @acknowledger&.call(position)
+    end
+
+    def remove_group(group)
+      @groups.shift
+      group.items.each do |entry|
+        entries = @entries_by_work[entry.work]
+        entries.delete(entry)
+        @entries_by_work.delete(entry.work) if entries.empty?
+      end
+    end
+
+    def source_position(work)
+      return @position_resolver.call(work) if @position_resolver
+
+      work.commit_lsn if work.respond_to?(:commit_lsn)
+    end
+  end
+end

data/lib/mammoth/delivery_worker.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Mammoth
-  # Delivers normalized events with retry, checkpoint, and dead-letter handling.
+  # Delivers normalized events with retry, ledger, and dead-letter handling.
   #
   # DeliveryWorker is Mammoth's first reliable delivery unit. It intentionally keeps
-  # the delivery contract small: attempt webhook delivery, advance the checkpoint
-  # after success, and persist the failed event to the dead letter queue after
-  # retry exhaustion.
+  # the delivery contract small: attempt webhook delivery, record idempotent
+  # success, and persist exhausted failures to the dead letter queue. Contiguous
+  # checkpointing is owned by DeliveryProgressCoordinator.
   class DeliveryWorker
     # Default source name used when an event does not provide one.
     DEFAULT_SOURCE = "postgresql"
@@ -15,9 +15,9 @@ module Mammoth
                 :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :enabled
 
     # @param sink [#deliver] destination sink
-    # @param checkpoint_store [Mammoth::CheckpointStore] checkpoint persistence
+    # @param checkpoint_store [Mammoth::CheckpointStore] retained dependency; shared progress owns writes
     # @param dead_letter_store [Mammoth::DeadLetterStore] dead letter persistence
-    # @param delivered_envelope_store [Mammoth::DeliveredEnvelopeStore, nil] downstream delivery ledger
+    # @param delivered_envelope_store [Mammoth::DeliveredEnvelopeStore] downstream delivery ledger
     # @param source_name [String] logical source name
     # @param slot_name [String] replication slot name
     # @param publication_name [String] publication name
@@ -26,13 +26,13 @@ module Mammoth
     # @param sleeper [#call] sleep strategy, injectable for tests
     # @param route_filter [Mammoth::RouteFilter, nil] optional destination route matcher
     # @param enabled [Boolean] whether this destination accepts new deliveries
-    def initialize(sink:, checkpoint_store:, dead_letter_store:, source_name:, slot_name:, publication_name:,
-                   max_attempts:, retry_schedule:, delivered_envelope_store: nil, sleeper: Kernel.method(:sleep),
+    def initialize(sink:, checkpoint_store:, dead_letter_store:, delivered_envelope_store:, source_name:, slot_name:,
+                   publication_name:, max_attempts:, retry_schedule:, sleeper: Kernel.method(:sleep),
                    route_filter: nil, enabled: true)
       @sink = sink
       @checkpoint_store = checkpoint_store
       @dead_letter_store = dead_letter_store
-      @delivered_envelope_store = delivered_envelope_store || DeliveredEnvelopeStore.new(checkpoint_store.sqlite_store)
+      @delivered_envelope_store = delivered_envelope_store
       @source_name = source_name
       @slot_name = slot_name
       @publication_name = publication_name
@@ -47,16 +47,18 @@ module Mammoth
     #
     # @param config [Mammoth::Configuration] loaded configuration
     # @param sink [#deliver] destination sink
-    # @param checkpoint_store [Mammoth::CheckpointStore] checkpoint persistence
+    # @param checkpoint_store [Mammoth::CheckpointStore] retained dependency; shared progress owns writes
     # @param dead_letter_store [Mammoth::DeadLetterStore] dead letter persistence
+    # @param delivered_envelope_store [Mammoth::DeliveredEnvelopeStore] downstream delivery ledger
     # @param sleeper [#call] sleep strategy
     # @return [Mammoth::DeliveryWorker]
-    def self.from_config(config, sink:, checkpoint_store:, dead_letter_store:, sleeper: Kernel.method(:sleep),
-                         delivery_policy: {})
+    def self.from_config(config, sink:, checkpoint_store:, dead_letter_store:, delivered_envelope_store:,
+                         sleeper: Kernel.method(:sleep), delivery_policy: {})
       new(
         sink: sink,
         checkpoint_store: checkpoint_store,
         dead_letter_store: dead_letter_store,
+        delivered_envelope_store: delivered_envelope_store,
         source_name: config.dig("mammoth", "name"),
         slot_name: config.dig("replication", "slot"),
         publication_name: Array(config.dig("replication", "publications")).join(","),
@@ -68,17 +70,17 @@ module Mammoth
       )
     end
 
-    # Deliver a transaction envelope with retry, checkpoint, and DLQ handling.
+    # Deliver a transaction envelope with retry, ledger, and DLQ handling.
     #
-    # @param envelope [#events, #transaction_id] CDC transaction envelope
+    # @param envelope [CDC::Core::TransactionEnvelope] CDC transaction envelope
     # @return [Hash] delivery summary
     def deliver_transaction(envelope)
       deliver_work(envelope, serializer: TransactionEnvelopeSerializer, delivery_method: :deliver_transaction)
     end
 
-    # Deliver an event with retry, checkpoint, and DLQ handling.
+    # Deliver an event with retry, ledger, and DLQ handling.
     #
-    # @param event [Hash, #to_h] normalized event
+    # @param event [CDC::Core::ChangeEvent] normalized event
     # @return [Hash] delivery summary
     def deliver(event)
       deliver_work(event, serializer: EventSerializer, delivery_method: :deliver)
@@ -97,7 +99,6 @@ module Mammoth
       return skip_result if skip_result
 
       if delivered_envelope_store.delivered?(idempotency_key)
-        checkpoint_payload(payload)
         return {
           status: "skipped",
           duplicate: true,
@@ -119,7 +120,6 @@ module Mammoth
           transaction_id: payload["transaction_id"],
           source_position: payload["source_position"]
         )
-        checkpoint_payload(payload)
         result.merge(attempts: attempts, idempotency_key: idempotency_key)
       rescue DeliveryError => e
         return dead_letter(work, e, attempts, serializer:) if attempts >= max_attempts
@@ -130,19 +130,6 @@ module Mammoth
     end
     # rubocop:enable Metrics/MethodLength
 
-    def checkpoint(work, serializer:)
-      checkpoint_payload(serializer.call(work))
-    end
-
-    def checkpoint_payload(payload)
-      checkpoint_store.write(
-        source_name: source_name,
-        slot_name: slot_name,
-        publication_name: publication_name,
-        last_lsn: payload["source_position"]
-      )
-    end
-
     def idempotency_key_for(payload:, delivery_unit:)
       [
         source_name,
@@ -168,8 +155,7 @@ module Mammoth
       skipped(payload, idempotency_key:, reason: "route_mismatch") unless route_filter.match_payload?(payload)
     end
 
-    def skipped(payload, idempotency_key:, reason:)
-      checkpoint_payload(payload)
+    def skipped(_payload, idempotency_key:, reason:)
       {
         status: "skipped",
         reason: reason,

data/lib/mammoth/dispatch_metrics.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Thread-safe in-process counters populated by Mammoth's CDC core observer.
+  #
+  # The registry deliberately stores CDC core metric names and tags. Rendering
+  # those counters for a specific backend remains an observability concern.
+  class DispatchMetrics
+    # Create an empty dispatch metric registry.
+    def initialize
+      @mutex = Mutex.new
+      @counters = Hash.new(0)
+    end
+
+    # Process-wide dispatch metrics used by the default observer and snapshot.
+    INSTANCE = new
+
+    # Increment a canonical CDC core metric.
+    #
+    # @param name [String] canonical CDC core metric name
+    # @param tags [Hash] canonical metric tags
+    # @return [Integer] updated counter value
+    def increment(name, tags = {})
+      key = [name.to_s.freeze, normalized_tags(tags)]
+      @mutex.synchronize { @counters[key] += 1 }
+    end
+
+    # Return an immutable point-in-time copy of all counters.
+    #
+    # @return [Array<Hash>] metric entries with name, tags, and value
+    def snapshot
+      @mutex.synchronize do
+        @counters.map do |(name, tags), value|
+          { name: name, tags: tags.to_h, value: value }
+        end
+      end
+    end
+
+    # Clear all counters.
+    #
+    # Intended for process lifecycle management and isolated tests.
+    #
+    # @return [self] cleared registry
+    def reset!
+      @mutex.synchronize { @counters.clear }
+      self
+    end
+
+    private
+
+    def normalized_tags(tags)
+      tags.to_h.transform_keys(&:to_s).sort_by(&:first).freeze
+    end
+  end
+end

data/lib/mammoth/event_serializer.rb

@@ -15,17 +15,19 @@ module Mammoth
     # Default source label used in serialized webhook payloads.
     DEFAULT_SOURCE = "postgresql"
 
-    # Serialize an event-like object into a webhook-ready Hash.
+    # Serialize a core change event into a webhook-ready Hash.
     #
-    # @param event [Hash, #to_h] normalized CDC event
+    # @param event [CDC::Core::ChangeEvent] normalized CDC event
     # @return [Hash] webhook payload
     def self.call(event)
       new(event).call
     end
 
-    # @param event [Hash, #to_h] normalized CDC event
+    # @param event [CDC::Core::ChangeEvent] normalized CDC event
     def initialize(event)
-      @event = event.respond_to?(:to_h) ? event.to_h : event
+      raise ArgumentError, "event must be a CDC::Core::ChangeEvent" unless event.is_a?(CDC::Core::ChangeEvent)
+
+      @event = event.to_h
     end
 
     # Return the webhook payload.
@@ -33,19 +35,20 @@ module Mammoth
     # @return [Hash] webhook payload
     def call
       event_hash = stringify_keys(@event)
+      metadata = stringify_keys(event_hash["metadata"] || {})
       {
-        "event_id" => event_hash["event_id"] || SecureRandom.uuid,
-        "source" => event_hash["source"] || DEFAULT_SOURCE,
+        "event_id" => event_id(metadata),
+        "source" => source(metadata),
         "operation" => normalize_operation(event_hash.fetch("operation")),
-        "namespace" => event_hash["namespace"] || event_hash["schema"],
-        "entity" => event_hash["entity"] || event_hash["table"],
-        "identity" => event_hash["identity"] || event_hash["primary_key"],
-        "source_position" => event_hash["source_position"] || event_hash["commit_lsn"],
+        "namespace" => event_hash["schema"],
+        "entity" => event_hash["table"],
+        "identity" => event_hash["primary_key"],
+        "source_position" => event_hash["commit_lsn"],
         "transaction_id" => event_hash["transaction_id"],
         "occurred_at" => occurred_at(event_hash),
         "data" => event_data(event_hash),
-        "changes" => event_hash["changes"] || [],
-        "metadata" => event_hash["metadata"] || {}
+        "changes" => metadata["changes"] || [],
+        "metadata" => metadata
       }
     end
 
@@ -66,6 +69,14 @@ module Mammoth
       operation.to_s
     end
 
+    def event_id(metadata)
+      metadata["event_id"] || SecureRandom.uuid
+    end
+
+    def source(metadata)
+      metadata["source"] || DEFAULT_SOURCE
+    end
+
     def occurred_at(event_hash)
       value = event_hash["occurred_at"]
       return value.iso8601 if value.respond_to?(:iso8601)