mammoth 0.9.0 → 1.1.0

data/lib/mammoth/sources/postgres.rb

@@ -27,6 +27,8 @@ module Mammoth
       attr_reader :adapter
       # @return [Mammoth::CheckpointStore, nil] checkpoint store used for restart resume
       attr_reader :checkpoint_store
+      # @return [#inspect, nil] injected PostgreSQL publication inspector
+      attr_reader :publication_inspector
 
       # Build a PostgreSQL CDC source.
       #
@@ -36,13 +38,16 @@ module Mammoth
       # @param decoder [Object, nil] injected pgoutput decoder
       # @param adapter [Object, nil] injected source adapter
       # @param checkpoint_store [Mammoth::CheckpointStore, nil] persisted checkpoints for restart resume
-      def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil, checkpoint_store: nil)
+      # @param publication_inspector [#inspect, nil] injected publication metadata inspector
+      def initialize(config, runner: nil, parser: nil, decoder: nil, adapter: nil, checkpoint_store: nil,
+                     publication_inspector: nil)
         @config = config
         @runner = runner
         @parser = parser
         @decoder = decoder
         @adapter = adapter
         @checkpoint_store = checkpoint_store
+        @publication_inspector = publication_inspector
       end
 
       # Stream CDC::Core work from PostgreSQL logical replication.
@@ -59,13 +64,15 @@ module Mammoth
       def each(&block)
         return enum_for(:each) unless block_given?
 
+        preflight_slot!
+        preflight_replica_identity!
         normalizer = effective_adapter
         unless normalizer.respond_to?(:each_normalized)
           raise ReplicationError, "pgoutput source adapter must respond to #each_normalized"
         end
 
         normalizer.each_normalized(decoded_stream) do |work|
-          block.call(validate_core_work!(work))
+          yield_with_progress_position(validate_core_work!(work), &block)
         end
         nil
       rescue StandardError => e
@@ -74,11 +81,65 @@ module Mammoth
         raise ReplicationError, "PostgreSQL CDC source failed: #{e.message}"
       end
 
+      # Acknowledge a durably handled PostgreSQL WAL position.
+      #
+      # @param lsn [String, Integer] pgoutput-client compatible WAL position
+      # @return [Integer] normalized acknowledged WAL position
+      def acknowledge(lsn)
+        effective_runner.ack(lsn)
+      rescue StandardError => e
+        raise ReplicationError, "PostgreSQL WAL acknowledgement failed: #{e.message}"
+      end
+
+      # Resolve the acknowledgement-compatible transport position for work
+      # currently being yielded by this source.
+      #
+      # @param work [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope] yielded work
+      # @return [String, Integer, nil] pgoutput-client compatible WAL position
+      def progress_position_for(work)
+        return nil unless yielded_work_includes?(work)
+
+        @yielded_progress_position
+      end
+
+      # Inspect the configured slot for readiness and operator metrics.
+      #
+      # pgoutput-client owns catalog access. This method converts its snapshot
+      # into Mammoth's PostgreSQL-specific health policy without leaking
+      # transport-library types into the observability layer.
+      #
+      # @return [PostgresSlotHealth]
+      def slot_health
+        status = inspected_slot_status
+        return PostgresSlotHealth.missing(required_config("replication", "slot")) unless status
+
+        PostgresSlotHealth.new(
+          slot_name: value_from(status, :slot_name),
+          present: true,
+          active: value_from(status, :active) == true,
+          retained_wal_bytes: value_from(status, :retained_wal_bytes),
+          wal_status: value_from(status, :wal_status),
+          safe_wal_size: value_from(status, :safe_wal_size),
+          inactive_since: value_from(status, :inactive_since),
+          invalidation_reason: value_from(status, :invalidation_reason),
+          restart_lsn: value_from(status, :restart_lsn),
+          restart_lsn_bytes: metric_lsn(value_from(status, :restart_lsn)),
+          confirmed_flush_lsn: value_from(status, :confirmed_flush_lsn),
+          confirmed_flush_lsn_bytes: metric_lsn(value_from(status, :confirmed_flush_lsn)),
+          conflicting: value_from(status, :conflicting) == true
+        )
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL slot health inspection failed: #{e.message}"
+      end
+
       private
 
       def decoded_stream
         Enumerator.new do |stream|
           effective_runner.start do |payload, metadata = nil|
+            @latest_progress_position = acknowledgement_position(metadata)
             process_payload(payload, metadata) { |decoded| stream << stream_event(decoded, metadata) }
           end
         end
@@ -108,6 +169,15 @@ module Mammoth
         normalizer.stream_event(decoded, source_position: source_position(metadata))
       end
 
+      def yield_with_progress_position(work)
+        @yielded_work = work
+        @yielded_progress_position = @latest_progress_position
+        yield work
+      ensure
+        @yielded_work = nil
+        @yielded_progress_position = nil
+      end
+
       def validate_core_work!(work)
         return work if work.is_a?(CDC::Core::ChangeEvent)
         return work if work.is_a?(CDC::Core::TransactionEnvelope)
@@ -156,6 +226,22 @@ module Mammoth
         value_from(metadata, :source_position, :commit_lsn, :lsn, :wal_end_lsn, :end_lsn, :final_lsn)
       end
 
+      def acknowledgement_position(metadata)
+        value = value_from(metadata, :wal_end_lsn, :wal_end, :lsn)
+        return nil if value.nil?
+        return value if value.is_a?(Integer) && value >= 0
+        return value if value.is_a?(String) && value.match?(%r{\A[0-9A-F]+/[0-9A-F]+\z}i)
+
+        raise ReplicationError, "invalid PostgreSQL transport LSN for acknowledgement: #{value.inspect}"
+      end
+
+      def yielded_work_includes?(work)
+        return true if @yielded_work.equal?(work)
+        return false unless @yielded_work.is_a?(CDC::Core::TransactionEnvelope)
+
+        @yielded_work.events.any? { |event| event.equal?(work) }
+      end
+
       def effective_runner
         runner || @effective_runner || begin
           @effective_runner = build_runner
@@ -180,6 +266,12 @@ module Mammoth
         end
       end
 
+      def effective_publication_inspector
+        publication_inspector || @effective_publication_inspector || begin
+          @effective_publication_inspector = build_publication_inspector
+        end
+      end
+
       def build_runner
         require_optional!("pgoutput/client", "pgoutput-client")
 
@@ -201,7 +293,12 @@ module Mammoth
       def build_adapter
         require_optional!("pgoutput/source_adapter", "pgoutput-source-adapter")
 
-        Pgoutput::SourceAdapter::Cdc.new
+        resolver = Pgoutput::SourceAdapter::ReplicaIdentityResolver.new(replica_identity_relations)
+        Pgoutput::SourceAdapter::Cdc.new(primary_key_resolver: resolver)
+      end
+
+      def build_publication_inspector
+        PostgresPublicationInspector.new(database_url:)
       end
 
       def runner_options
@@ -210,7 +307,7 @@ module Mammoth
           slot_name: required_config("replication", "slot"),
           publication_names: required_publications,
           start_lsn: replication_start_lsn,
-          auto_create_slot: config.dig("replication", "auto_create_slot") == true,
+          auto_create_slot: safe_auto_create_slot?,
           temporary_slot: config.dig("replication", "temporary_slot") == true
         }.tap do |options|
           feedback_interval = config.dig("replication", "feedback_interval")
@@ -225,6 +322,157 @@ module Mammoth
         checkpoint_lsn
       end
 
+      def preflight_slot!
+        resume_lsn = replication_start_lsn
+        validate_temporary_slot_resume!(resume_lsn)
+        status = inspected_slot_status
+
+        if status.nil?
+          return if safe_auto_create_slot?
+
+          raise ReplicationError, missing_slot_message(resume_lsn)
+        end
+
+        validate_slot_identity!(status)
+        validate_slot_health!(status)
+        validate_slot_reachability!(status, resume_lsn) unless blank?(resume_lsn)
+        nil
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL slot preflight failed: #{e.message}"
+      end
+
+      def preflight_replica_identity!
+        invalid_tables = publication_tables.reject(&:identity_usable?)
+        return if invalid_tables.empty?
+
+        details = invalid_tables.map do |table|
+          "#{table.qualified_name} (actions=#{table.identity_actions.join("/")}, " \
+            "replica_identity=#{replica_identity_name(table.replica_identity)})"
+        end
+        raise ReplicationError,
+              "PostgreSQL replica identity preflight failed for #{details.join(", ")}. " \
+              "Add a primary key, select an eligible unique index with REPLICA IDENTITY USING INDEX, " \
+              "use REPLICA IDENTITY FULL, or remove UPDATE/DELETE from the publication."
+      rescue StandardError => e
+        raise e if e.is_a?(ReplicationError)
+
+        raise ReplicationError, "PostgreSQL replica identity preflight failed: #{e.message}"
+      end
+
+      def publication_tables
+        @publication_tables ||= effective_publication_inspector.inspect(required_publications).freeze
+      end
+
+      def replica_identity_relations
+        relations = {} # : Hash[Integer | [String, String], Array[String]]
+        publication_tables.each do |table|
+          next if table.replica_identity_columns.empty?
+
+          columns = table.replica_identity_columns
+          relations[table.relation_id] = columns
+          relations[[table.schema_name, table.table_name]] = columns
+        end
+        relations
+      end
+
+      def inspected_slot_status
+        client = effective_runner
+        unless client.respond_to?(:slot_status)
+          raise ReplicationError, "pgoutput-client 0.4+ with #slot_status is required for PostgreSQL slot inspection"
+        end
+
+        client.slot_status
+      end
+
+      def validate_temporary_slot_resume!(resume_lsn)
+        return if blank?(resume_lsn)
+        return unless config.dig("replication", "temporary_slot") == true
+
+        raise ReplicationError, "cannot resume durable PostgreSQL checkpoint #{resume_lsn} with a temporary slot"
+      end
+
+      def validate_slot_identity!(status)
+        slot_name = required_config("replication", "slot")
+        unless value_from(status, :slot_name) == slot_name
+          raise ReplicationError, "PostgreSQL slot preflight returned the wrong slot for #{slot_name}"
+        end
+        unless value_from(status, :slot_type) == "logical" && value_from(status, :plugin) == "pgoutput"
+          raise ReplicationError, "PostgreSQL slot #{slot_name} must be a logical pgoutput slot"
+        end
+
+        database = required_config("postgres", "database")
+        return if value_from(status, :database) == database
+
+        raise ReplicationError, "PostgreSQL slot #{slot_name} belongs to a different database"
+      end
+
+      def validate_slot_health!(status)
+        slot_name = required_config("replication", "slot")
+        raise ReplicationError, "PostgreSQL slot #{slot_name} is already active" if value_from(status, :active) == true
+
+        wal_status = value_from(status, :wal_status)
+        if %w[lost unreserved].include?(wal_status)
+          raise ReplicationError, "PostgreSQL slot #{slot_name} cannot retain required WAL (wal_status=#{wal_status})"
+        end
+
+        invalidation_reason = value_from(status, :invalidation_reason)
+        if value_from(status, :conflicting) == true || !blank?(invalidation_reason)
+          raise ReplicationError,
+                "PostgreSQL slot #{slot_name} is invalidated#{": #{invalidation_reason}" unless blank?(invalidation_reason)}"
+        end
+
+        return unless blank?(value_from(status, :restart_lsn))
+
+        raise ReplicationError, "PostgreSQL slot #{slot_name} has no reachable restart LSN"
+      end
+
+      def validate_slot_reachability!(status, resume_lsn)
+        requested = parse_transport_lsn(resume_lsn, "resume checkpoint")
+        %i[restart_lsn confirmed_flush_lsn].each do |field|
+          boundary = value_from(status, field)
+          next if blank?(boundary)
+          next unless requested < parse_transport_lsn(boundary, field.to_s)
+
+          raise ReplicationError,
+                "PostgreSQL slot cannot serve checkpoint #{resume_lsn}; #{field}=#{boundary} has already advanced past it"
+        end
+      end
+
+      def parse_transport_lsn(value, label)
+        require_optional!("pgoutput/client", "pgoutput-client")
+        Pgoutput::Client::LSN.parse(value)
+      rescue StandardError => e
+        raise ReplicationError, "invalid PostgreSQL #{label} LSN #{value.inspect}: #{e.message}"
+      end
+
+      def metric_lsn(value)
+        return nil if blank?(value)
+
+        parse_transport_lsn(value, "slot metric")
+      end
+
+      def replica_identity_name(value)
+        {
+          "d" => "default",
+          "n" => "nothing",
+          "f" => "full",
+          "i" => "index"
+        }.fetch(value, value)
+      end
+
+      def safe_auto_create_slot?
+        config.dig("replication", "auto_create_slot") == true && blank?(replication_start_lsn)
+      end
+
+      def missing_slot_message(resume_lsn)
+        slot_name = required_config("replication", "slot")
+        return "PostgreSQL slot #{slot_name} is missing and auto_create_slot is disabled" if blank?(resume_lsn)
+
+        "PostgreSQL slot #{slot_name} is missing; refusing to recreate it while checkpoint #{resume_lsn} requires continuity"
+      end
+
       def checkpoint_lsn
         return nil unless checkpoint_store
 

data/lib/mammoth/sources/postgres_publication_inspector.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mammoth
+  module Sources
+    # Immutable replica-identity facts for one table in configured publications.
+    class PostgresPublicationTable
+      attr_reader :relation_id, :schema_name, :table_name, :publishes_updates, :publishes_deletes, :replica_identity,
+                  :replica_identity_columns, :primary_key_usable, :replica_identity_index_usable
+
+      # @return [void]
+      def initialize(relation_id:, schema_name:, table_name:, publishes_updates:, publishes_deletes:,
+                     replica_identity:, replica_identity_columns:, primary_key_usable:,
+                     replica_identity_index_usable:)
+        @relation_id = relation_id
+        @schema_name = schema_name
+        @table_name = table_name
+        @publishes_updates = publishes_updates
+        @publishes_deletes = publishes_deletes
+        @replica_identity = replica_identity
+        @replica_identity_columns = replica_identity_columns.freeze
+        @primary_key_usable = primary_key_usable
+        @replica_identity_index_usable = replica_identity_index_usable
+        freeze
+      end
+
+      # Schema-qualified table name for diagnostics.
+      #
+      # @return [String]
+      def qualified_name
+        "#{schema_name}.#{table_name}"
+      end
+
+      # Publication actions that require old-row identity.
+      #
+      # @return [Array<String>]
+      def identity_actions
+        actions = [] # : Array[String]
+        actions.tap do
+          actions << "UPDATE" if publishes_updates
+          actions << "DELETE" if publishes_deletes
+        end
+      end
+
+      # Whether any configured publication requires replica identity.
+      #
+      # @return [Boolean]
+      def identity_required?
+        publishes_updates || publishes_deletes
+      end
+
+      # Whether PostgreSQL can identify old rows for the published actions.
+      #
+      # `d` uses a primary key, `i` uses a selected replica-identity index,
+      # and `f` logs the full old row. `n` provides no old-row identity.
+      #
+      # @return [Boolean]
+      def identity_usable?
+        return true unless identity_required?
+
+        case replica_identity
+        when "d" then primary_key_usable
+        when "i" then replica_identity_index_usable
+        when "f" then true
+        else false
+        end
+      end
+    end
+
+    # Read-only PostgreSQL publication and replica-identity catalog inspector.
+    class PostgresPublicationInspector
+      QUERY = <<~SQL
+        SELECT
+          relation.oid AS relation_id,
+          namespace.nspname AS schema_name,
+          relation.relname AS table_name,
+          bool_or(publication.pubupdate) AS publishes_updates,
+          bool_or(publication.pubdelete) AS publishes_deletes,
+          relation.relreplident AS replica_identity,
+          CASE relation.relreplident
+            WHEN 'd' THEN (
+              SELECT COALESCE(jsonb_agg(attribute.attname ORDER BY key.ordinality), '[]'::jsonb)
+              FROM pg_index AS identity_columns_index
+              JOIN LATERAL unnest(identity_columns_index.indkey)
+                WITH ORDINALITY AS key(attribute_number, ordinality) ON true
+              JOIN pg_attribute AS attribute
+                ON attribute.attrelid = relation.oid
+               AND attribute.attnum = key.attribute_number
+              WHERE identity_columns_index.indrelid = relation.oid
+                AND identity_columns_index.indisprimary
+                AND identity_columns_index.indisvalid
+                AND identity_columns_index.indisready
+                AND identity_columns_index.indislive
+            )
+            WHEN 'i' THEN (
+              SELECT COALESCE(jsonb_agg(attribute.attname ORDER BY key.ordinality), '[]'::jsonb)
+              FROM pg_index AS identity_columns_index
+              JOIN LATERAL unnest(identity_columns_index.indkey)
+                WITH ORDINALITY AS key(attribute_number, ordinality) ON true
+              JOIN pg_attribute AS attribute
+                ON attribute.attrelid = relation.oid
+               AND attribute.attnum = key.attribute_number
+              WHERE identity_columns_index.indrelid = relation.oid
+                AND identity_columns_index.indisreplident
+                AND identity_columns_index.indisvalid
+                AND identity_columns_index.indisready
+                AND identity_columns_index.indislive
+            )
+            WHEN 'f' THEN (
+              SELECT COALESCE(jsonb_agg(attribute.attname ORDER BY attribute.attnum), '[]'::jsonb)
+              FROM pg_attribute AS attribute
+              WHERE attribute.attrelid = relation.oid
+                AND attribute.attnum > 0
+                AND NOT attribute.attisdropped
+            )
+            ELSE '[]'::jsonb
+          END AS replica_identity_columns,
+          EXISTS (
+            SELECT 1
+            FROM pg_index AS primary_index
+            WHERE primary_index.indrelid = relation.oid
+              AND primary_index.indisprimary
+              AND primary_index.indisvalid
+              AND primary_index.indisready
+              AND primary_index.indislive
+          ) AS primary_key_usable,
+          EXISTS (
+            SELECT 1
+            FROM pg_index AS identity_index
+            WHERE identity_index.indrelid = relation.oid
+              AND identity_index.indisreplident
+              AND identity_index.indisvalid
+              AND identity_index.indisready
+              AND identity_index.indislive
+          ) AS replica_identity_index_usable
+        FROM pg_publication_tables AS publication_table
+        JOIN pg_publication AS publication
+          ON publication.pubname = publication_table.pubname
+        JOIN pg_namespace AS namespace
+          ON namespace.nspname = publication_table.schemaname
+        JOIN pg_class AS relation
+          ON relation.relnamespace = namespace.oid
+         AND relation.relname = publication_table.tablename
+        WHERE publication.pubname IN (
+          SELECT jsonb_array_elements_text($1::jsonb)
+        )
+        GROUP BY namespace.nspname, relation.relname, relation.oid, relation.relreplident
+        ORDER BY namespace.nspname, relation.relname
+      SQL
+
+      attr_reader :database_url
+
+      # @param database_url [String] PostgreSQL connection URL
+      # @param connection_factory [#call, nil] optional connection factory for tests
+      def initialize(database_url:, connection_factory: nil)
+        @database_url = database_url
+        @connection_factory = connection_factory
+      end
+
+      # Inspect tables included by the configured publications.
+      #
+      # @param publication_names [Array<String>] configured publication names
+      # @return [Array<PostgresPublicationTable>]
+      def inspect(publication_names)
+        connection = open_connection
+        rows = connection.exec_params(QUERY, [JSON.generate(publication_names)])
+        rows.map { |row| build_table(row) }
+      rescue pg_error_class => e
+        raise ReplicationError, "PostgreSQL publication inspection failed: #{e.message}"
+      ensure
+        connection&.close unless connection&.finished?
+      end
+
+      private
+
+      def open_connection
+        return @connection_factory.call(database_url) if @connection_factory
+
+        require "pg"
+        PG.connect(database_url)
+      end
+
+      def build_table(row)
+        PostgresPublicationTable.new(
+          relation_id: Integer(row.fetch("relation_id")),
+          schema_name: row.fetch("schema_name"),
+          table_name: row.fetch("table_name"),
+          publishes_updates: postgres_boolean(row.fetch("publishes_updates")),
+          publishes_deletes: postgres_boolean(row.fetch("publishes_deletes")),
+          replica_identity: row.fetch("replica_identity"),
+          replica_identity_columns: parse_columns(row.fetch("replica_identity_columns")),
+          primary_key_usable: postgres_boolean(row.fetch("primary_key_usable")),
+          replica_identity_index_usable: postgres_boolean(row.fetch("replica_identity_index_usable"))
+        )
+      end
+
+      def parse_columns(value)
+        columns = value.is_a?(String) ? JSON.parse(value) : value
+        column_list = Array(columns) # : Array[untyped]
+        column_list.map(&:to_s)
+      end
+
+      def postgres_boolean(value)
+        [true, "t"].include?(value)
+      end
+
+      def pg_error_class
+        require "pg"
+        PG::Error
+      end
+    end
+  end
+end

data/lib/mammoth/sources/postgres_slot_health.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Mammoth
+  module Sources
+    # Immutable operator-facing health snapshot for one PostgreSQL replication slot.
+    #
+    # This is a Mammoth-owned policy view. The transport layer supplies catalog
+    # facts; Mammoth decides whether they make the configured source ready for
+    # continuous delivery.
+    # Typed PostgreSQL slot health and readiness policy.
+    class PostgresSlotHealth
+      attr_reader :slot_name, :present, :active, :retained_wal_bytes, :wal_status, :safe_wal_size, :inactive_since,
+                  :invalidation_reason, :restart_lsn, :restart_lsn_bytes, :confirmed_flush_lsn,
+                  :confirmed_flush_lsn_bytes, :conflicting
+
+      # Build a PostgreSQL slot health snapshot from normalized catalog facts.
+      #
+      # @return [void]
+      def initialize(slot_name:, present:, active:, retained_wal_bytes:, wal_status:, safe_wal_size:, inactive_since:,
+                     invalidation_reason:, restart_lsn:, restart_lsn_bytes:, confirmed_flush_lsn:,
+                     confirmed_flush_lsn_bytes:, conflicting:)
+        @slot_name = slot_name
+        @present = present
+        @active = active
+        @retained_wal_bytes = retained_wal_bytes
+        @wal_status = wal_status
+        @safe_wal_size = safe_wal_size
+        @inactive_since = inactive_since
+        @invalidation_reason = invalidation_reason
+        @restart_lsn = restart_lsn
+        @restart_lsn_bytes = restart_lsn_bytes
+        @confirmed_flush_lsn = confirmed_flush_lsn
+        @confirmed_flush_lsn_bytes = confirmed_flush_lsn_bytes
+        @conflicting = conflicting
+        freeze
+      end
+
+      # Build a snapshot for a missing configured slot.
+      #
+      # @param slot_name [String] configured replication slot
+      # @return [PostgresSlotHealth]
+      def self.missing(slot_name)
+        new(
+          slot_name:, present: false, active: false, retained_wal_bytes: nil,
+          wal_status: nil, safe_wal_size: nil, inactive_since: nil,
+          invalidation_reason: nil, restart_lsn: nil, restart_lsn_bytes: nil,
+          confirmed_flush_lsn: nil, confirmed_flush_lsn_bytes: nil, conflicting: false
+        )
+      end
+
+      # Whether the slot is present, active, and retaining usable WAL.
+      #
+      # @return [Boolean]
+      def ready?
+        reason.nil?
+      end
+
+      # Operator-facing reason the slot is not ready.
+      #
+      # @return [String, nil]
+      def reason
+        return "slot is missing" unless present
+        return "slot is inactive" unless active
+        return "wal_status=#{wal_status}" if %w[lost unreserved].include?(wal_status)
+        return "slot is invalidated: #{invalidation_reason}" unless blank?(invalidation_reason)
+        return "slot is conflicting" if conflicting
+        return "slot has no restart LSN" if blank?(restart_lsn)
+
+        nil
+      end
+
+      # Stable readiness payload without transport-library types.
+      #
+      # @return [Hash]
+      def summary
+        {
+          slot_name:, present:, active:, retained_wal_bytes:, wal_status:, safe_wal_size:, inactive_since:,
+          invalidation_reason:, restart_lsn:, restart_lsn_bytes:, confirmed_flush_lsn:,
+          confirmed_flush_lsn_bytes:, conflicting:, ready: ready?, reason:
+        }
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value == ""
+      end
+    end
+  end
+end

data/lib/mammoth/transaction_envelope_serializer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require "securerandom"
+require "digest"
 require "time"
 
 module Mammoth
@@ -38,7 +38,7 @@ module Mammoth
     def call
       event_payloads = envelope.events.map { |event| EventSerializer.call(event) }
       {
-        "event_id" => envelope_metadata["event_id"] || SecureRandom.uuid,
+        "event_id" => envelope_metadata["event_id"] || deterministic_event_id(event_payloads),
         "type" => PAYLOAD_TYPE,
         "source" => first_event_value(event_payloads, "source") || EventSerializer::DEFAULT_SOURCE,
         "transaction_id" => envelope.transaction_id,
@@ -70,6 +70,16 @@ module Mammoth
       @envelope_metadata ||= stringify_keys(envelope.metadata)
     end
 
+    def deterministic_event_id(event_payloads)
+      identity = {
+        source: first_event_value(event_payloads, "source") || EventSerializer::DEFAULT_SOURCE,
+        transaction_id: envelope.transaction_id,
+        source_position: source_position(event_payloads),
+        event_ids: event_payloads.map { |payload| payload.fetch("event_id") }
+      }
+      "txn_#{Digest::SHA256.hexdigest(JSON.generate(identity))}"
+    end
+
     def source_position(event_payloads)
       envelope.commit_lsn ||
         first_event_value(event_payloads.reverse, "source_position")

data/lib/mammoth/version.rb

@@ -2,5 +2,5 @@
 
 module Mammoth
   # Current Mammoth gem version.
-  VERSION = "0.9.0"
+  VERSION = "1.1.0"
 end