mammoth 0.1.0 → 0.2.0

data/lib/mammoth/webhook_sink.rb

@@ -2,7 +2,9 @@
 
 require "json"
 require "net/http"
+require "openssl"
 require "socket"
+require "time"
 require "uri"
 
 module Mammoth
@@ -11,27 +13,72 @@ module Mammoth
     # HTTP status range treated as successful webhook delivery.
     SUCCESS_RANGE = 200..299
 
-    attr_reader :name, :url, :timeout_seconds
+    SIGNING_ALGORITHM = "hmac_sha256"
+    SIGNATURE_PREFIX = "sha256="
+
+    attr_reader :name, :url, :timeout_seconds, :headers, :signing
 
     # @param name [String] destination name
     # @param url [String] webhook endpoint URL
     # @param timeout_seconds [Integer] HTTP open/read timeout in seconds
-    def initialize(name:, url:, timeout_seconds: 5)
+    # @param headers [Hash] static HTTP headers applied to every request
+    # @param signing [Hash, nil] HMAC signing configuration
+    def initialize(name:, url:, timeout_seconds: 5, headers: {}, signing: nil)
       @name = name
       @url = URI(url)
       @timeout_seconds = timeout_seconds
+      @headers = headers.transform_keys(&:to_s)
+      @signing = signing
     end
 
-    # Build a sink from Mammoth configuration.
-    #
-    # @param config [Mammoth::Configuration] loaded configuration
-    # @return [Mammoth::WebhookSink]
-    def self.from_config(config)
-      new(
-        name: config.dig("webhook", "name"),
-        url: config.dig("webhook", "url"),
-        timeout_seconds: config.dig("webhook", "timeout_seconds")
-      )
+    class << self
+      # Build a sink from Mammoth configuration.
+      #
+      # @param config [Mammoth::Configuration] loaded configuration
+      # @return [Mammoth::WebhookSink]
+      def from_config(config)
+        new(
+          name: config.dig("webhook", "name"),
+          url: config.dig("webhook", "url"),
+          timeout_seconds: config.dig("webhook", "timeout_seconds"),
+          headers: configured_headers(config),
+          signing: configured_signing(config)
+        )
+      end
+
+      private
+
+      def configured_headers(config)
+        static_headers = config.dig("webhook", "headers") || {}
+        env_headers = config.dig("webhook", "header_env") || {}
+
+        static_headers.merge(resolve_env_headers(env_headers))
+      end
+
+      def resolve_env_headers(env_headers)
+        env_headers.each_with_object(Hash.new) do |(header, env_name), resolved| # rubocop:disable Style/EmptyLiteral
+          resolved[header] = ENV.fetch(env_name) do
+            raise ConfigurationError, "webhook.header_env.#{header} references missing environment variable #{env_name}"
+          end
+        end
+      end
+
+      def configured_signing(config)
+        signing = config.dig("webhook", "signing")
+        return unless signing
+
+        algorithm = signing.fetch("algorithm", SIGNING_ALGORITHM)
+        raise ConfigurationError, "webhook.signing.algorithm must be #{SIGNING_ALGORITHM}" unless algorithm == SIGNING_ALGORITHM
+
+        secret_env = signing.fetch("secret_env")
+        {
+          secret: ENV.fetch(secret_env) do
+            raise ConfigurationError, "webhook.signing.secret_env references missing environment variable #{secret_env}"
+          end,
+          signature_header: signing.fetch("signature_header", "X-Mammoth-Signature"),
+          timestamp_header: signing.fetch("timestamp_header", "X-Mammoth-Timestamp")
+        }
+      end
     end
 
     # Deliver an event to the webhook endpoint.
@@ -40,7 +87,21 @@ module Mammoth
     # @return [Hash] delivery result
     # @raise [Mammoth::DeliveryError] when delivery fails
     def deliver(event)
-      payload = EventSerializer.call(event)
+      deliver_payload(EventSerializer.call(event))
+    end
+
+    # Deliver a transaction envelope to the webhook endpoint.
+    #
+    # @param envelope [#events, #transaction_id] CDC transaction envelope
+    # @return [Hash] delivery result
+    # @raise [Mammoth::DeliveryError] when delivery fails
+    def deliver_transaction(envelope)
+      deliver_payload(TransactionEnvelopeSerializer.call(envelope))
+    end
+
+    private
+
+    def deliver_payload(payload)
       response = perform_request(payload)
       return delivery_result(payload, response) if SUCCESS_RANGE.cover?(response.code.to_i)
 
@@ -49,8 +110,6 @@ module Mammoth
       raise DeliveryError, "webhook #{name} delivery failed: #{e.message}"
     end
 
-    private
-
     def perform_request(payload)
       Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == "https", open_timeout: timeout_seconds,
                                           read_timeout: timeout_seconds) do |http|
@@ -59,19 +118,36 @@ module Mammoth
     end
 
     def build_request(payload)
+      body = JSON.generate(payload)
       Net::HTTP::Post.new(url.request_uri).tap do |request|
         request["Content-Type"] = "application/json"
-        request.body = JSON.generate(payload)
+        headers.each { |header, value| request[header] = value }
+        apply_signature_headers(request, body)
+        request.body = body
       end
     end
 
     def delivery_result(payload, response)
       {
         event_id: payload.fetch("event_id"),
+        payload_type: payload["type"] || "event",
         destination: name,
         status: "delivered",
         http_status: response.code.to_i
       }
     end
+
+    def apply_signature_headers(request, body)
+      return unless signing
+
+      timestamp = Time.now.utc.iso8601
+      request[signing.fetch(:timestamp_header)] = timestamp
+      request[signing.fetch(:signature_header)] = signed_body(timestamp, body)
+    end
+
+    def signed_body(timestamp, body)
+      digest = OpenSSL::HMAC.hexdigest("SHA256", signing.fetch(:secret), "#{timestamp}.#{body}")
+      "#{SIGNATURE_PREFIX}#{digest}"
+    end
   end
 end

data/lib/mammoth.rb

@@ -7,9 +7,13 @@ require_relative "mammoth/status"
 require_relative "mammoth/sqlite_store"
 require_relative "mammoth/checkpoint_store"
 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/webhook_sink"
 require_relative "mammoth/delivery_worker"
+require_relative "mammoth/delivery_processor"
+require_relative "mammoth/concurrent_delivery_runtime"
 require_relative "mammoth/sources/postgres"
 require_relative "mammoth/cdc_source"
 require_relative "mammoth/replication_consumer"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: cdc-concurrent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: cdc-core
   requirement: !ruby/object:Gem::Requirement
@@ -134,8 +148,11 @@ files:
 - lib/mammoth/cdc_source.rb
 - lib/mammoth/checkpoint_store.rb
 - lib/mammoth/cli.rb
+- lib/mammoth/concurrent_delivery_runtime.rb
 - lib/mammoth/configuration.rb
 - lib/mammoth/dead_letter_store.rb
+- lib/mammoth/delivered_envelope_store.rb
+- lib/mammoth/delivery_processor.rb
 - lib/mammoth/delivery_worker.rb
 - lib/mammoth/errors.rb
 - lib/mammoth/event_serializer.rb
@@ -144,6 +161,7 @@ files:
 - lib/mammoth/sql/__bootstrap__.sql
 - lib/mammoth/sqlite_store.rb
 - lib/mammoth/status.rb
+- lib/mammoth/transaction_envelope_serializer.rb
 - lib/mammoth/version.rb
 - lib/mammoth/webhook_sink.rb
 homepage: https://kanutocd.github.io/mammoth/
@@ -153,7 +171,7 @@ metadata:
   homepage_uri: https://kanutocd.github.io/mammoth/
   source_code_uri: https://github.com/kanutocd/mammoth
   changelog_uri: https://github.com/kanutocd/mammoth/blob/main/CHANGELOG.md
-  documentation_uri: https://kanutocd.github.io/mammoth/api/
+  documentation_uri: https://kanutocd.github.io/mammoth/Mammoth.html
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -171,5 +189,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: Reliable delivery of PostgreSQL change events.
+summary: Reliable delivery of PostgreSQL logical replication events with retries,
+  dead letters, and operational state.
 test_files: []