mammoth 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f299dc783af6453331a635200b8fe3ddf03159b156a3a0cec6cc6377ede1c34
-  data.tar.gz: f56eabc963912066610c22a98af55af9a6db192f40869dfb1d5743c8f1eff98e
+  metadata.gz: b1249f6166082904d6ecac8d74819442681eaac72ae1e23c80a2134c412e235a
+  data.tar.gz: 292272e0696a218c3a75d970476efa3acaa71d54164da139aefa007bbd256ae5
 SHA512:
-  metadata.gz: c3167effc0333430719118b2ad3f8d8b53841c8c584b1e45949e256411e1a275eb56b71bd023d4d3778e31ec92f179c338d5814220f11c251f447aad7eee0233
-  data.tar.gz: d6db35472dfb2847e00f2158fd8677f26da5cb3c19d91e002566d598d9ecd8d67681e35dc2310ffd7fd41dcc0aec5535e822fd52f55f3865f9f65cc267633383
+  metadata.gz: 4e401e3a8a1778ac6b63338636cc15d5c06ccbeea77e2179af1189ba8d60d1005a2281884e3cc3a09208ac4836f37d94132ab16c3f00b08edfb1c3347fe0e944
+  data.tar.gz: fe8efe54a12f5dae1960eb4cf34c91b1eacd1d91a8609c082349b2a4e900ebda7f5160052b8f7d3bf062b09d16bb84438712f0f7d514ff23b4b16606da8b279a

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.6.0
+
+### Added
+
+- Added fanout route filters by schema, table, and operation for webhook destinations.
+- Added destination `enabled` controls for config-driven delivery cutovers.
+- Added per-destination retry policy overrides for `max_attempts` and `schedule_seconds`.
+- Added dead-letter replay filters by destination, status, and failed-at time window.
+- Added destination-labeled Prometheus metrics for dead-letter and delivered-envelope counts.
+
+### Changed
+
+- Bumped Mammoth version to `0.6.0`.
+
+## 0.5.1
+
+### Added
+
+- Added benchmark scripts for webhook delivery, webhook fanout, SQLite operational state, observability snapshots, and dead-letter replay.
+- Added shared benchmark helpers for synthetic CDC work items, local HTTP receivers, table output, JSON output, and environment-driven benchmark knobs.
+- Added a benchmark snapshot runner that writes Markdown, JSON, and per-trial logs for publishable benchmark results.
+
+### Changed
+
+- Aligned benchmark documentation across `README.md`, `docs/BENCHMARKS.md`, and `benchmark/README.md` around operator config tuning.
+
 ## 0.5.0
 
 ### Added

data/README.md

@@ -47,8 +47,10 @@ https://kanutocd.github.io/mammoth/Mammoth.html
 - dead letter persistence
 - webhook delivery sink
 - webhook fanout to multiple destinations
+- fanout route filters by schema, table, and operation
+- per-destination enable/disable and retry policy controls
 - delivery worker with retry, checkpoint, and DLQ handling
-- dead-letter inspection and replay commands
+- dead-letter inspection and filtered replay commands
 - CDC-core event serialization boundary
 - CDC Ecosystem source-adapter integration boundary
 - Docker image support
@@ -78,6 +80,24 @@ Validate configuration:
 bundle exec ./exe/mammoth validate config/mammoth.example.yml
 ```
 
+Fanout destinations can be routed and tuned independently:
+
+```yaml
+destinations:
+  - name: audit_webhook
+    type: webhook
+    enabled: true
+    url: https://audit.example.com/cdc
+    timeout_seconds: 5
+    route:
+      schemas: [public]
+      tables: [orders]
+      operations: [insert, update]
+    retry:
+      max_attempts: 3
+      schedule_seconds: [1, 10]
+```
+
 ## CLI
 
 ```bash
@@ -108,47 +128,27 @@ Mammoth stores operational memory in SQLite:
 
 ## Performance
 
-Mammoth scales downstream delivery throughput using the `cdc-concurrent` runtime while maintaining a single PostgreSQL logical replication stream.
-
-### Concurrent Delivery Benchmark
-
-Environment:
-
-* 10,000 transactions
-* 4 events per transaction
-* 40,000 total events
-
-#### Fast Downstream (10ms)
-
-| Concurrency | Transactions/sec |
-| ----------- | ---------------: |
-| 1           |            96.50 |
-| 25          |          2419.65 |
+Mammoth includes local benchmarks for the product surfaces operators tune in
+production:
 
-#### Realistic Webhook (50ms)
+- concurrent delivery runtime
+- real webhook delivery
+- multi-destination webhook fanout
+- SQLite operational state
+- observability snapshots
+- DLQ replay
 
-| Concurrency | Transactions/sec |
-| ----------- | ---------------: |
-| 1           |            19.85 |
-| 25          |           495.11 |
+The historical numbers in [Benchmarks](https://github.com/kanutocd/mammoth/tree/main/docs/BENCHMARKS.md) are retained as a
+snapshot, not a universal performance claim. Re-run the scripts in
+[`benchmark/`](https://github.com/kanutocd/mammoth/tree/main/benchmark) on your own hardware when choosing
+`runtime.concurrency`, `destinations`, SQLite storage, scrape frequency, and
+DLQ replay expectations.
 
-Observed throughput improved from:
+Create a publishable benchmark snapshot with:
 
-- 96.50 → 2419.65 transactions/sec (10ms sink latency)
-- 19.85 → 495.11 transactions/sec (50ms sink latency)
-
-when increasing delivery concurrency from 1 to 25.
-
-The benchmark demonstrates near-linear scaling of delivery throughput without increasing PostgreSQL replication connections.
-
-See:
-
-- docs/BENCHMARKS.md
-- examples/transaction_webhook
-
-For full benchmark methodology and results see:
-
-See [Benchmarks](docs/BENCHMARKS.md).
+```bash
+bundle exec ruby benchmark/snapshot.rb
+```
 
 ## E2E
 

data/config/mammoth.example.yml

@@ -275,6 +275,7 @@ webhook:
 # destinations:
 #   - name: primary_webhook
 #     type: webhook
+#     enabled: true
 #     url: https://example.com/webhooks/postgres
 #     timeout_seconds: 5
 #     header_env:
@@ -284,8 +285,28 @@ webhook:
 #       secret_env: MAMMOTH_PRIMARY_WEBHOOK_SIGNING_SECRET
 #   - name: audit_webhook
 #     type: webhook
+#     enabled: true
 #     url: https://audit.example.com/cdc
 #     timeout_seconds: 5
+#
+#     # Optional route filter. Omit route to receive every event/envelope.
+#     # For transaction delivery, a destination matches when any event in the
+#     # transaction matches; Mammoth still delivers the full transaction envelope.
+#     route:
+#       schemas:
+#         - public
+#       tables:
+#         - orders
+#       operations:
+#         - insert
+#         - update
+#
+#     # Optional per-destination retry override. Omit to use top-level retry.
+#     retry:
+#       max_attempts: 3
+#       schedule_seconds:
+#         - 1
+#         - 10
 
 retry:
   # Maximum delivery attempts before the event/envelope is moved to the dead

data/config/mammoth.schema.json

@@ -223,7 +223,11 @@
             "enum": [
               "webhook"
             ],
-            "description": "Destination adapter type. Mammoth OSS 0.5.0 supports webhook destinations."
+            "description": "Destination adapter type. Mammoth OSS 0.6.0 supports webhook destinations."
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "When false, Mammoth skips this destination, advances local progress for the work item, and does not attempt delivery."
           },
           "url": {
             "type": "string",
@@ -281,6 +285,61 @@
               }
             },
             "description": "Optional HMAC-SHA256 request signing for this webhook destination."
+          },
+          "route": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "schemas": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "PostgreSQL schemas this destination should receive. Omit to match every schema."
+              },
+              "tables": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "PostgreSQL tables this destination should receive. Omit to match every table."
+              },
+              "operations": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "description": "CDC operations this destination should receive, such as insert, update, or delete. Omit to match every operation."
+              }
+            },
+            "description": "Optional destination route filter. Event delivery matches one event; transaction delivery matches when any event in the transaction matches and delivers the full envelope."
+          },
+          "retry": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "max_attempts": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Destination-specific maximum delivery attempts before dead-lettering. Defaults to the top-level retry.max_attempts."
+              },
+              "schedule_seconds": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "description": "Destination-specific retry backoff schedule in seconds. Defaults to the top-level retry.schedule_seconds."
+              }
+            },
+            "description": "Optional retry policy override for this destination."
           }
         }
       },

data/lib/mammoth/application.rb

@@ -87,32 +87,51 @@ module Mammoth
       Sources::Postgres.new(config, checkpoint_store: checkpoint_store)
     end
 
-    def build_delivery_worker(sink:, sleeper:)
+    def build_delivery_worker(sink:, sleeper:, delivery_policy: {})
       DeliveryWorker.from_config(
         config,
         sink: sink,
         checkpoint_store: checkpoint_store,
         dead_letter_store: DeadLetterStore.new(sqlite_store),
-        sleeper: sleeper
+        sleeper: sleeper,
+        delivery_policy: delivery_policy
       )
     end
 
     def build_configured_delivery_worker(sleeper:)
-      workers = destination_sinks.map { |sink| build_delivery_worker(sink:, sleeper:) }
+      workers = destination_specs.map do |spec|
+        build_delivery_worker(sink: spec.fetch(:sink), sleeper:, delivery_policy: spec.fetch(:delivery_policy))
+      end
       return workers.fetch(0) if workers.one?
 
       FanoutDeliveryWorker.new(workers)
     end
 
-    def destination_sinks
+    def destination_specs
       destinations = config.data["destinations"]
-      return [WebhookSink.from_config(config)] unless destinations
+      unless destinations
+        delivery_policy = {} # : Hash[String, untyped]
+        return [{ sink: WebhookSink.from_config(config), delivery_policy: delivery_policy }]
+      end
 
       destinations.map.with_index(1) do |destination, index|
-        WebhookSink.from_destination_config(destination, label: "destinations[#{index - 1}]")
+        {
+          sink: WebhookSink.from_destination_config(destination, label: "destinations[#{index - 1}]"),
+          delivery_policy: destination_delivery_policy(destination)
+        }
       end
     end
 
+    def destination_delivery_policy(destination)
+      retry_config = destination["retry"] || {}
+      {
+        "enabled" => destination.fetch("enabled", true),
+        "max_attempts" => retry_config.fetch("max_attempts", config.dig("retry", "max_attempts")),
+        "schedule_seconds" => retry_config.fetch("schedule_seconds", config.dig("retry", "schedule_seconds")),
+        "route_filter" => RouteFilter.new(destination["route"])
+      }
+    end
+
     def transaction_delivery?
       delivery_unit == :transaction
     end

data/lib/mammoth/cli.rb

@@ -24,9 +24,11 @@ module Mammoth
       "  mammoth status CONFIG",
       "  mammoth start CONFIG",
       "  mammoth deliver-sample CONFIG EVENT_JSON",
-      "  mammoth dead-letters list CONFIG [--status STATUS] [--limit N]",
+      "  mammoth dead-letters list CONFIG [--status STATUS] [--destination NAME] " \
+      "[--failed-after ISO8601] [--failed-before ISO8601] [--limit N]",
       "  mammoth dead-letters show CONFIG ID",
-      "  mammoth dead-letters replay CONFIG [ID ...]",
+      "  mammoth dead-letters replay CONFIG [ID ...] [--destination NAME] [--status STATUS] " \
+      "[--failed-after ISO8601] [--failed-before ISO8601] [--limit N]",
       "  mammoth observability CONFIG"
     ].join("\n")
 

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,44 @@ 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 ArgumentError
+      raise ConfigurationError, "invalid dead letter list option"
+    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,8 +175,17 @@ 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)
@@ -154,6 +198,41 @@ module Mammoth
       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 +261,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,17 @@ 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
+
+    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 +136,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,18 @@ 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
+
+    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/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/route_filter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Mammoth
+  # Matches CDC events and transaction envelopes against destination route rules.
+  class RouteFilter
+    attr_reader :schemas, :tables, :operations
+
+    def initialize(config = nil)
+      route = config || {}
+      @schemas = normalized_set(route["schemas"])
+      @tables = normalized_set(route["tables"])
+      @operations = normalized_set(route["operations"])
+    end
+
+    def match?(work, serializer:)
+      match_payload?(serializer.call(work))
+    end
+
+    def match_payload?(payload)
+      if transaction_payload?(payload)
+        payload.fetch("events").any? { |event| event_match?(event) }
+      else
+        event_match?(payload)
+      end
+    end
+
+    private
+
+    def normalized_set(values)
+      return [] unless values
+
+      values.map { |value| value.to_s.downcase }.freeze
+    end
+
+    def transaction_payload?(payload)
+      payload.fetch("type", nil) == TransactionEnvelopeSerializer::PAYLOAD_TYPE
+    end
+
+    def event_match?(payload)
+      matches?(schemas, payload["namespace"]) &&
+        matches?(tables, payload["entity"]) &&
+        matches?(operations, payload["operation"])
+    end
+
+    def matches?(allowed_values, actual_value)
+      allowed_values.empty? || allowed_values.include?(actual_value.to_s.downcase)
+    end
+  end
+end

data/lib/mammoth/version.rb

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

data/lib/mammoth.rb

@@ -12,6 +12,7 @@ require_relative "mammoth/dead_letter_store"
 require_relative "mammoth/delivered_envelope_store"
 require_relative "mammoth/event_serializer"
 require_relative "mammoth/transaction_envelope_serializer"
+require_relative "mammoth/route_filter"
 require_relative "mammoth/webhook_sink"
 require_relative "mammoth/delivery_worker"
 require_relative "mammoth/fanout_delivery_worker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -161,6 +161,7 @@ files:
 - lib/mammoth/observability_server.rb
 - lib/mammoth/observability_snapshot.rb
 - lib/mammoth/replication_consumer.rb
+- lib/mammoth/route_filter.rb
 - lib/mammoth/sources/postgres.rb
 - lib/mammoth/sql/__bootstrap__.sql
 - lib/mammoth/sqlite_store.rb