mammoth 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc13868a4aa6d845e63c655af36b9bbb69604be8bfb5b7ab6beda7d1a765c145
-  data.tar.gz: 9a3c9514953f68db2d5287903e29980ffb147460691817f5de1a19a8123f1727
+  metadata.gz: 9169e3ff1f9fad3a07df87cee57891aea0ca6815f356f7ef998e94572a432ea4
+  data.tar.gz: 6ee2140075cb22b1fc0aea3977a33adfd1aa49918d184a823ee3cbcab9b87bac
 SHA512:
-  metadata.gz: 552aa45078fa0ed209890bbfe8eb2dc0672234d4e008c8cc0edd954a284e0b40bffafe16a2a8c2df8dd0219aee3eed742ba2a38531cd3d2acd7b13b35bb48b11
-  data.tar.gz: 69f509480ecdd46aa50a7879c3dbc1589becce9a651b1697e1f164ea0d6be781edb9f54238940a32553b59956c8cba05cd2b0caaffca57812823cb32e6fa481b
+  metadata.gz: 37191be4257dbab756e5e2ba81bae60905df5a921792001daf12b5ece1bcacbf60c353967b6da5c0de4e71311a8b95311ed37e7f8f2587bcb49e7dfbae6a57bd
+  data.tar.gz: 603479a5b0e7e067743eb6dcb8802ea2077954df50e23a3b29b97bdefb161cb1c47f493dfac919aa27d6a0552f018fcc1a7116e876acca50f71bc716f0d8c539

data/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 1.2.0 - 2026-07-19
+
+### Added
+
+- Added an opt-in monitoring profile to `webhooks-quickstart` with provisioned
+  Prometheus and Grafana services, meaningful seeded traffic, a Mammoth
+  operations dashboard, curated Prometheus queries, recording rules, and
+  example Prometheus and Grafana alerting rules.
+
+## 1.1.0 - 2026-07-19
+
+### Added
+
+- Added a serializer benchmark comparing explicit and deterministic fallback
+  event IDs for event and transaction payload projection.
+- Added `webhooks-quickstart`, a one-command PostgreSQL-to-Mammoth demo with an
+  order application; inspectable signed webhook deliveries and retries;
+  `INSERT`, `UPDATE`, and `DELETE` events; multi-event payment and reversal
+  transactions; adaptation guidance; WAL-retention safeguards; and end-to-end
+  verification.
+
+### Fixed
+
+- Generate deterministic fallback event and transaction-envelope IDs so retries
+  and post-crash redelivery preserve destination idempotency when upstream
+  metadata does not provide an event ID.
+- Serialize `CDC::Core::ChangeEvent` column differences when complete old and
+  new rows are available, while avoiding false differences from key-only old
+  rows.
+- Require pgoutput-source-adapter 0.3.1 and use its stable transaction-local
+  event sequence to prevent deterministic ID collisions between otherwise
+  identical changes while preserving replay stability.
+
 ## 1.0.0 - 2026-07-17
 
 ### Added

data/README.md

@@ -38,10 +38,28 @@ API documentation:
 
 https://kanutocd.github.io/mammoth/Mammoth.html
 
+## Start Here
 
-## v1.0 Release Scope
+The recommended first-run experience is the
+[`webhooks-quickstart`](webhooks-quickstart) stack. One Compose command starts a
+demo application, logical-replication-enabled PostgreSQL, Mammoth, a signed
+webhook receiver with visible retries, and Mammoth health endpoints:
 
-Mammoth 1.0 includes:
+```bash
+cd webhooks-quickstart
+docker compose up --build --wait
+```
+
+Once the flow is visible, follow its
+[`ADAPTING.md`](webhooks-quickstart/ADAPTING.md) guide to connect Mammoth to an
+existing PostgreSQL application. Its optional `monitoring` profile adds seeded
+traffic, a provisioned Grafana dashboard and alert rules, and a curated
+Prometheus query library; see the
+[observability guide](docs/OBSERVABILITY.md#runnable-monitoring-showcase).
+
+## v1 Release Scope
+
+Mammoth 1.x includes:
 
 - operator CLI for validation, bootstrap, status, delivery, observability, and
   dead-letter workflows
@@ -107,7 +125,9 @@ Human-readable CLI formatting and PostgreSQL-derived row columns are not frozen:
 scripts should rely on documented exit behavior, while receivers must tolerate
 additive fields and coordinate source schema changes. See
 [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) for the complete promise and
-major-version boundaries.
+major-version boundaries. See
+[`docs/WEBHOOK-PAYLOADS.md`](docs/WEBHOOK-PAYLOADS.md) for the canonical event
+and transaction JSON contracts, column-change semantics, and event-ID behavior.
 
 ## Boundary
 
@@ -222,6 +242,7 @@ rather than opening SQLite directly.
 Mammoth includes local benchmarks for the product surfaces operators tune in
 production:
 
+- event and transaction serialization, including deterministic fallback IDs
 - concurrent delivery runtime
 - real webhook delivery
 - multi-destination webhook fanout

data/lib/mammoth/event_serializer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
-require "securerandom"
+require "digest"
 require "time"
 
 module Mammoth
@@ -27,17 +27,17 @@ module Mammoth
     def initialize(event)
       raise ArgumentError, "event must be a CDC::Core::ChangeEvent" unless event.is_a?(CDC::Core::ChangeEvent)
 
-      @event = event.to_h
+      @event = event
     end
 
     # Return the webhook payload.
     #
     # @return [Hash] webhook payload
     def call
-      event_hash = stringify_keys(@event)
+      event_hash = stringify_keys(@event.to_h)
       metadata = stringify_keys(event_hash["metadata"] || {})
       {
-        "event_id" => event_id(metadata),
+        "event_id" => event_id(event_hash, metadata),
         "source" => source(metadata),
         "operation" => normalize_operation(event_hash.fetch("operation")),
         "namespace" => event_hash["schema"],
@@ -47,7 +47,7 @@ module Mammoth
         "transaction_id" => event_hash["transaction_id"],
         "occurred_at" => occurred_at(event_hash),
         "data" => event_data(event_hash),
-        "changes" => metadata["changes"] || [],
+        "changes" => serialized_changes(event_hash, metadata),
         "metadata" => metadata
       }
     end
@@ -69,8 +69,25 @@ module Mammoth
       operation.to_s
     end
 
-    def event_id(metadata)
-      metadata["event_id"] || SecureRandom.uuid
+    def event_id(event_hash, metadata)
+      metadata["event_id"] || deterministic_event_id(event_hash, metadata)
+    end
+
+    def deterministic_event_id(event_hash, metadata)
+      identity = {
+        source: source(metadata),
+        transaction_id: event_hash["transaction_id"],
+        source_position: event_hash["commit_lsn"],
+        sequence_number: event_hash["sequence_number"],
+        occurred_at: event_hash["occurred_at"],
+        namespace: event_hash["schema"],
+        entity: event_hash["table"],
+        operation: normalize_operation(event_hash.fetch("operation")),
+        primary_key: event_hash["primary_key"],
+        old_values: event_hash["old_values"],
+        new_values: event_hash["new_values"]
+      }
+      "evt_#{Digest::SHA256.hexdigest(JSON.generate(identity))}"
     end
 
     def source(metadata)
@@ -87,5 +104,20 @@ module Mammoth
     def event_data(event_hash)
       event_hash["data"] || event_hash["new_values"] || event_hash["old_values"] || {}
     end
+
+    def serialized_changes(event_hash, metadata)
+      return metadata["changes"] || [] if metadata.key?("changes")
+      return [] unless changes_available?(event_hash)
+
+      @event.changes.map(&:to_h)
+    end
+
+    def changes_available?(event_hash)
+      return true unless normalize_operation(event_hash.fetch("operation")) == "update"
+
+      old_values = event_hash["old_values"]
+      new_values = event_hash["new_values"]
+      old_values.is_a?(Hash) && new_values.is_a?(Hash) && old_values.keys.sort == new_values.keys.sort
+    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 = "1.0.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mammoth
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -122,7 +122,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -132,7 +132,7 @@ dependencies:
         version: '0.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement