mammoth 0.5.1 → 0.7.0

data/lib/mammoth/dead_letter_commands.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 
 module Mammoth
   # Operator commands for inspecting and replaying dead letters.
@@ -55,7 +56,14 @@ module Mammoth
     end
 
     def list
-      rows = dead_letter_store.rows(status: list_options.fetch(:status), limit: list_options.fetch(:limit))
+      options = list_options
+      rows = dead_letter_store.rows(
+        status: options.fetch(:status),
+        destination: options.fetch(:destination),
+        failed_after: options.fetch(:failed_after),
+        failed_before: options.fetch(:failed_before),
+        limit: options.fetch(:limit)
+      )
       puts list_header
       rows.each { |row| puts list_row(row) }
       0
@@ -73,7 +81,7 @@ module Mammoth
 
       rows.each do |row|
         result = replay_row(row)
-        dead_letter_store.resolve(row.fetch("id")) unless result.fetch(:status) == "dead_lettered"
+        dead_letter_store.resolve(row.fetch("id")) if replay_resolved?(result)
         puts replay_message(row, result)
       end
       0
@@ -106,7 +114,7 @@ module Mammoth
     #
     # @return [Hash] list options
     def list_options
-      options = { status: "pending", limit: 100 }
+      options = { status: "pending", destination: nil, failed_after: nil, failed_before: nil, limit: 100 }
       index = 0
       args = argv.drop(3)
 
@@ -122,17 +130,42 @@ module Mammoth
     def parse_list_option(args, index, options)
       case args.fetch(index)
       when "--status"
-        options[:status] = args.fetch(index + 1)
-        index + 2
+        assign_option(args, index, options, :status)
+      when "--destination"
+        assign_option(args, index, options, :destination)
+      when "--failed-after"
+        assign_time_option(args, index, options, :failed_after)
+      when "--failed-before"
+        assign_time_option(args, index, options, :failed_before)
       when "--limit"
-        options[:limit] = Integer(args.fetch(index + 1))
-        index + 2
+        assign_limit_option(args, index, options)
       else
         raise ConfigurationError, "unknown option #{args[index]}\n#{CLI::USAGE}" if args[index].start_with?("--")
 
         raise ConfigurationError, "unexpected argument #{args[index]}\n#{CLI::USAGE}"
       end
-    rescue ArgumentError, IndexError
+    rescue IndexError
+      raise ConfigurationError, "missing value for dead letter option"
+    end
+
+    def assign_option(args, index, options, key)
+      options[key] = args.fetch(index + 1)
+      index + 2
+    end
+
+    def assign_time_option(args, index, options, key)
+      options[key] = parse_time_option(args.fetch(index + 1), args.fetch(index))
+      index + 2
+    end
+
+    def assign_limit_option(args, index, options)
+      options[:limit] = parse_limit_option(args.fetch(index + 1))
+      index + 2
+    end
+
+    def parse_limit_option(value)
+      Integer(value)
+    rescue ArgumentError
       raise ConfigurationError, "dead letter limit must be an integer"
     end
 
@@ -140,20 +173,62 @@ module Mammoth
     #
     # @return [Array<Hash>] replay rows
     def replay_rows
-      ids = argv.drop(3)
-      return dead_letter_store.pending if ids.empty?
+      options = replay_options
+      ids = options.fetch(:ids)
+      if ids.empty?
+        return dead_letter_store.rows(
+          status: options.fetch(:status),
+          destination: options.fetch(:destination),
+          failed_after: options.fetch(:failed_after),
+          failed_before: options.fetch(:failed_before),
+          limit: options.fetch(:limit)
+        )
+      end
 
       ids.map do |raw_id|
-        id = Integer(raw_id)
+        id = raw_id
         row = dead_letter_store.fetch(id)
         raise ConfigurationError, "dead letter not found: #{id}" unless row
 
         row
-      rescue ArgumentError
-        raise ConfigurationError, "dead letter id must be an integer"
       end
     end
 
+    def parse_time_option(value, option_name)
+      Time.iso8601(value).utc.iso8601
+    rescue ArgumentError
+      raise ConfigurationError, "#{option_name} must be an ISO-8601 timestamp"
+    end
+
+    def replay_options
+      ids = [] # : Array[Integer]
+      options = { ids: ids, status: "pending", destination: nil, failed_after: nil, failed_before: nil, limit: 100 }
+      index = 0
+      args = argv.drop(3)
+
+      # rubocop:disable Style/WhileUntilModifier
+      while index < args.length
+        index = parse_replay_option(args, index, options)
+      end
+      # rubocop:enable Style/WhileUntilModifier
+
+      options
+    end
+
+    def parse_replay_option(args, index, options)
+      case args.fetch(index)
+      when "--status", "--destination", "--failed-after", "--failed-before", "--limit"
+        parse_list_option(args, index, options)
+      else
+        raise ConfigurationError, "unexpected argument #{args[index]}\n#{CLI::USAGE}" if args[index].start_with?("--")
+
+        options[:ids] << Integer(args.fetch(index))
+        index + 1
+      end
+    rescue ArgumentError
+      raise ConfigurationError, "dead letter id must be an integer"
+    end
+
     def fetch_dead_letter!(id)
       row = dead_letter_store.fetch(id)
       raise ConfigurationError, "dead letter not found: #{id}" unless row
@@ -182,6 +257,10 @@ module Mammoth
       worker.deliver_transaction(envelope)
     end
 
+    def replay_resolved?(result)
+      result.fetch(:status) == "delivered" || result.fetch(:duplicate, false)
+    end
+
     def transaction_payload?(payload)
       payload.fetch("type", nil) == TransactionEnvelopeSerializer::PAYLOAD_TYPE
     end

data/lib/mammoth/dead_letter_store.rb

@@ -65,8 +65,9 @@ module Mammoth
     #
     # @param limit [Integer] maximum number of rows
     # @return [Array<Hash>] pending dead letter rows
-    def pending(limit: 100)
-      rows(status: "pending", limit: limit)
+    def pending(limit: 100, destination: nil, failed_after: nil, failed_before: nil)
+      rows(status: "pending", limit: limit, destination: destination, failed_after: failed_after,
+           failed_before: failed_before)
     end
 
     # Fetch dead letters, optionally filtered by status.
@@ -74,15 +75,12 @@ module Mammoth
     # @param status [String, nil] optional dead-letter status filter
     # @param limit [Integer] maximum number of rows
     # @return [Array<Hash>] dead letter rows
-    def rows(status: nil, limit: 100)
-      if status && status != "all"
-        return database.execute(
-          "SELECT * FROM dead_letters WHERE status = ? ORDER BY failed_at ASC LIMIT ?",
-          [status, limit]
-        )
-      end
-
-      database.execute("SELECT * FROM dead_letters ORDER BY failed_at ASC LIMIT ?", [limit])
+    def rows(status: nil, limit: 100, destination: nil, failed_after: nil, failed_before: nil)
+      where, values = row_filters(status:, destination:, failed_after:, failed_before:)
+      database.execute(
+        "SELECT * FROM dead_letters#{where} ORDER BY failed_at ASC LIMIT ?",
+        values + [limit]
+      )
     end
 
     # Fetch one dead letter by id.
@@ -97,12 +95,21 @@ module Mammoth
     #
     # @param status [String, nil] optional status
     # @return [Integer] dead letter count
-    def count(status: nil)
-      if status
-        database.get_first_value("SELECT COUNT(*) FROM dead_letters WHERE status = ?", [status])
-      else
-        database.get_first_value("SELECT COUNT(*) FROM dead_letters")
-      end
+    def count(status: nil, destination: nil)
+      where, values = row_filters(status:, destination:)
+      database.get_first_value("SELECT COUNT(*) FROM dead_letters#{where}", values)
+    end
+
+    # Count dead letters grouped by destination.
+    #
+    # @param status [String, nil] optional status filter
+    # @return [Array<Hash>] rows with destination_name and count
+    def counts_by_destination(status: nil)
+      where, values = row_filters(status:)
+      database.execute(
+        "SELECT destination_name, COUNT(*) AS count FROM dead_letters#{where} GROUP BY destination_name",
+        values
+      )
     end
 
     # Mark a dead letter as resolved.
@@ -133,5 +140,29 @@ module Mammoth
         [status, Time.now.utc.iso8601, id]
       )
     end
+
+    def row_filters(status: nil, destination: nil, failed_after: nil, failed_before: nil)
+      predicates = [] # : Array[String]
+      values = [] # : Array[untyped]
+
+      unless status.nil? || status == "all"
+        predicates << "status = ?"
+        values << status
+      end
+      if destination
+        predicates << "destination_name = ?"
+        values << destination
+      end
+      if failed_after
+        predicates << "failed_at >= ?"
+        values << failed_after
+      end
+      if failed_before
+        predicates << "failed_at <= ?"
+        values << failed_before
+      end
+
+      [predicates.empty? ? "" : " WHERE #{predicates.join(" AND ")}", values]
+    end
   end
 end

data/lib/mammoth/delivered_envelope_store.rb

@@ -85,8 +85,21 @@ module Mammoth
     # Count delivered envelopes.
     #
     # @return [Integer] delivered envelope count
-    def count
-      database.get_first_value("SELECT COUNT(*) FROM delivered_envelopes")
+    def count(destination: nil)
+      if destination
+        database.get_first_value("SELECT COUNT(*) FROM delivered_envelopes WHERE destination_name = ?", [destination])
+      else
+        database.get_first_value("SELECT COUNT(*) FROM delivered_envelopes")
+      end
+    end
+
+    # Count delivered envelopes grouped by destination.
+    #
+    # @return [Array<Hash>] rows with destination_name and count
+    def counts_by_destination
+      database.execute(
+        "SELECT destination_name, COUNT(*) AS count FROM delivered_envelopes GROUP BY destination_name"
+      )
     end
 
     private

data/lib/mammoth/delivery_worker.rb

@@ -12,7 +12,7 @@ module Mammoth
     DEFAULT_SOURCE = "postgresql"
 
     attr_reader :sink, :checkpoint_store, :dead_letter_store, :delivered_envelope_store, :retry_schedule, :max_attempts,
-                :sleeper, :source_name, :slot_name, :publication_name
+                :sleeper, :source_name, :slot_name, :publication_name, :route_filter, :enabled
 
     # @param sink [#deliver] destination sink
     # @param checkpoint_store [Mammoth::CheckpointStore] checkpoint persistence
@@ -24,8 +24,11 @@ module Mammoth
     # @param max_attempts [Integer] maximum delivery attempts
     # @param retry_schedule [Array<Integer>] retry wait schedule in seconds
     # @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))
+                   max_attempts:, retry_schedule:, delivered_envelope_store: nil, sleeper: Kernel.method(:sleep),
+                   route_filter: nil, enabled: true)
       @sink = sink
       @checkpoint_store = checkpoint_store
       @dead_letter_store = dead_letter_store
@@ -36,6 +39,8 @@ module Mammoth
       @max_attempts = max_attempts
       @retry_schedule = retry_schedule
       @sleeper = sleeper
+      @route_filter = route_filter || RouteFilter.new
+      @enabled = enabled
     end
 
     # Build a delivery worker from Mammoth configuration and stores.
@@ -46,7 +51,8 @@ module Mammoth
     # @param dead_letter_store [Mammoth::DeadLetterStore] dead letter persistence
     # @param sleeper [#call] sleep strategy
     # @return [Mammoth::DeliveryWorker]
-    def self.from_config(config, sink:, checkpoint_store:, dead_letter_store:, sleeper: Kernel.method(:sleep))
+    def self.from_config(config, sink:, checkpoint_store:, dead_letter_store:, sleeper: Kernel.method(:sleep),
+                         delivery_policy: {})
       new(
         sink: sink,
         checkpoint_store: checkpoint_store,
@@ -54,9 +60,11 @@ module Mammoth
         source_name: config.dig("mammoth", "name"),
         slot_name: config.dig("replication", "slot"),
         publication_name: Array(config.dig("replication", "publications")).join(","),
-        max_attempts: config.dig("retry", "max_attempts"),
-        retry_schedule: config.dig("retry", "schedule_seconds"),
-        sleeper: sleeper
+        max_attempts: delivery_policy.fetch("max_attempts", config.dig("retry", "max_attempts")),
+        retry_schedule: delivery_policy.fetch("schedule_seconds", config.dig("retry", "schedule_seconds")),
+        sleeper: sleeper,
+        route_filter: delivery_policy.fetch("route_filter", RouteFilter.new),
+        enabled: delivery_policy.fetch("enabled", true)
       )
     end
 
@@ -85,6 +93,9 @@ module Mammoth
       delivery_unit = delivery_unit_for(delivery_method)
       idempotency_key = idempotency_key_for(payload:, delivery_unit:)
 
+      skip_result = skip_result_for(payload, idempotency_key:)
+      return skip_result if skip_result
+
       if delivered_envelope_store.delivered?(idempotency_key)
         checkpoint_payload(payload)
         return {
@@ -151,6 +162,24 @@ module Mammoth
       sink.respond_to?(:name) ? sink.name : sink.class.name
     end
 
+    def skip_result_for(payload, idempotency_key:)
+      return skipped(payload, idempotency_key:, reason: "disabled") unless enabled
+
+      skipped(payload, idempotency_key:, reason: "route_mismatch") unless route_filter.match_payload?(payload)
+    end
+
+    def skipped(payload, idempotency_key:, reason:)
+      checkpoint_payload(payload)
+      {
+        status: "skipped",
+        reason: reason,
+        duplicate: false,
+        idempotency_key: idempotency_key,
+        attempts: 0,
+        destination: destination_name
+      }
+    end
+
     def dead_letter(event, error, attempts, serializer:)
       id = dead_letter_store.write(
         event: event,

data/lib/mammoth/destinations/adapter.rb

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

data/lib/mammoth/destinations/registry.rb

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

data/lib/mammoth/destinations/webhook_adapter.rb

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

data/lib/mammoth/node_identity.rb

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

data/lib/mammoth/observability_server.rb

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

data/lib/mammoth/observability_snapshot.rb

@@ -71,7 +71,20 @@ module Mammoth
       dead_letter_store = DeadLetterStore.new(store)
       delivered_store = DeliveredEnvelopeStore.new(store)
 
-      lines = metric_headers + [
+      lines = metric_headers + aggregate_metric_lines(
+        checkpoint_store: checkpoint_store,
+        dead_letter_store: dead_letter_store,
+        delivered_store: delivered_store
+      ) + destination_metric_lines(dead_letter_store:, delivered_store:)
+      "#{lines.join("\n")}\n"
+    rescue Mammoth::Error, SQLite3::Exception
+      "#{(metric_headers + [metric_line("mammoth_up", 0)]).join("\n")}\n"
+    end
+
+    private
+
+    def aggregate_metric_lines(checkpoint_store:, dead_letter_store:, delivered_store:)
+      [
         metric_line("mammoth_up", 1),
         metric_line("mammoth_checkpoints_total", checkpoint_store.count),
         metric_line("mammoth_dead_letters_total", dead_letter_store.count),
@@ -80,12 +93,24 @@ module Mammoth
         metric_line("mammoth_dead_letters_ignored_total", dead_letter_store.count(status: "ignored")),
         metric_line("mammoth_delivered_envelopes_total", delivered_store.count)
       ]
-      "#{lines.join("\n")}\n"
-    rescue Mammoth::Error, SQLite3::Exception
-      "#{(metric_headers + [metric_line("mammoth_up", 0)]).join("\n")}\n"
     end
 
-    private
+    def destination_metric_lines(dead_letter_store:, delivered_store:)
+      destination_names.flat_map do |destination|
+        [
+          metric_line("mammoth_dead_letters_total", dead_letter_store.count(destination: destination),
+                      destination: destination),
+          metric_line("mammoth_dead_letters_pending_total",
+                      dead_letter_store.count(status: "pending", destination: destination), destination: destination),
+          metric_line("mammoth_dead_letters_resolved_total",
+                      dead_letter_store.count(status: "resolved", destination: destination), destination: destination),
+          metric_line("mammoth_dead_letters_ignored_total",
+                      dead_letter_store.count(status: "ignored", destination: destination), destination: destination),
+          metric_line("mammoth_delivered_envelopes_total", delivered_store.count(destination: destination),
+                      destination: destination)
+        ]
+      end
+    end
 
     def operational_store
       sqlite_store || SQLiteStore.connect(config.dig("sqlite", "path"))
@@ -95,6 +120,13 @@ module Mammoth
       config.dig("mammoth", "name")
     end
 
+    def destination_names
+      destinations = config.data["destinations"]
+      return destinations.map { |destination| destination.fetch("name") } if destinations
+
+      [config.dig("webhook", "name")]
+    end
+
     def checked_at
       clock.call.utc.iso8601
     end
@@ -118,8 +150,10 @@ module Mammoth
       ]
     end
 
-    def metric_line(name, value)
-      %(#{name}{mammoth_name="#{escape_label(mammoth_name)}"} #{Integer(value)})
+    def metric_line(name, value, destination: nil)
+      labels = { "mammoth_name" => mammoth_name }
+      labels["destination"] = destination if destination
+      %(#{name}{#{labels.map { |label, label_value| %(#{label}="#{escape_label(label_value)}") }.join(",")}} #{Integer(value)})
     end
 
     def escape_label(value)

data/lib/mammoth/operational_state/adapter.rb

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