yes-core 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4845d0466658aee907edb5bab0679603e25a9b5c088a8df067d0fbfcc060bff4
-  data.tar.gz: cca505e973fa99d5b8e4b07c44752b78b330fdc0035b45528c83139ee36a0e4b
+  metadata.gz: '06386ad1e1b30ddacbb4afaf392632875023650518041e3914178427039f91f5'
+  data.tar.gz: af40c3f3d98c611ce0653dfb0c0e2e2193376feb1ed0aeba69d43827fd6a09f9
 SHA512:
-  metadata.gz: '08121024f7bb36c1bb17281d772c907f4c1e9c119437caf6642c0461fcc9ce2d434c15fa6dc548ec8c6362b520b5144f8869d7054c8e9a110e33a984d757fd63'
-  data.tar.gz: b2b2bcbf061918d7876e27c6014d41adfe1ed5133163a078d09a31490219105a57f47699c5bd2d6c9d3400c12df527c13e2d0f76d64b32f1d4a2b1aaec1b4b8f
+  metadata.gz: e956ac8483b7a53f13009356536c221f92dc2dd6d88f6137ca4d1e6305a7c239a2870484197469243c14dca6552983d0004b263147ad6642d94c17611415cfd6
+  data.tar.gz: 5ac3c8ea889ddf9a01efc1ac645a35c9d394736f351e1f98d9ca1dc0f5550094ded103ba424f2a8df07f24d46a082948a69e719aab3aa330d18736d0815de17a

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## [2.3.0] - 2026-09-03
+- See root CHANGELOG.md for details.
+
 ## [2.2.0] - 2026-09-01
 
 - See root CHANGELOG.md for details.

data/lib/yes/core/command_handling/command_executor.rb

@@ -55,6 +55,8 @@ module Yes
       #   response = executor.call(command, guard_evaluator_class)
       #
       class CommandExecutor
+        include RevisionConflictWaiting
+
         MAX_RETRIES = 10
         INLINE_RECOVERY_RETRY_THRESHOLD = 5
 
@@ -96,13 +98,15 @@ module Yes
           rescue PgEventstore::WrongExpectedRevisionError => e
             retries += 1
             clear_pending_update_state if aggregate.class.read_model_enabled?
+            raise e if retries > MAX_RETRIES
 
-            retries <= MAX_RETRIES ? retry : raise(e)
+            wait_for_read_model(e, retries)
+            retry
           rescue ConcurrentUpdateError => e
             retries += 1
             # Don't clear pending state - another process owns it
             # Sleep with exponential backoff to give the other process time to finish
-            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+            sleep(RevisionConflictBackoff.schedule(retries)) if retries <= MAX_RETRIES
 
             # After several retries, check if pending state is stuck and attempt recovery
             # This prevents infinite retry loops when a process crashes leaving the flag set

data/lib/yes/core/command_handling/command_group_executor.rb

@@ -17,6 +17,8 @@ module Yes
       # Only the group's own guards run here — sub-command guards are
       # bypassed by design.
       class CommandGroupExecutor
+        include RevisionConflictWaiting
+
         MAX_RETRIES = 10
         INLINE_RECOVERY_RETRY_THRESHOLD = 5
 
@@ -47,10 +49,13 @@ module Yes
           rescue PgEventstore::WrongExpectedRevisionError => e
             retries += 1
             clear_pending_update_state if aggregate.class.read_model_enabled?
-            retries <= MAX_RETRIES ? retry : raise(e)
+            raise e if retries > MAX_RETRIES
+
+            wait_for_read_model(e, retries)
+            retry
           rescue ConcurrentUpdateError => e
             retries += 1
-            sleep([0.01 * (2**(retries - 1)), 1.0].min) if retries <= MAX_RETRIES
+            sleep(RevisionConflictBackoff.schedule(retries)) if retries <= MAX_RETRIES
 
             if aggregate.class.read_model_enabled? && retries >= INLINE_RECOVERY_RETRY_THRESHOLD
               ReadModelRecoveryService.attempt_inline_recovery(read_model, aggregate: aggregate)

data/lib/yes/core/command_handling/event_publisher.rb

@@ -106,17 +106,17 @@ module Yes
               name: aggregate_data[:name],
               id: aggregate_data[:id]
             )
-            expected_revision = command_utilities.stream_revision(stream)
+            stream_revision = command_utilities.stream_revision(stream)
             aggregate_revision = aggregate_data[:revision].call
-            normalized_revision = aggregate_revision == -1 ? :no_stream : aggregate_revision
+            expected_revision = aggregate_revision == -1 ? :no_stream : aggregate_revision
+            next if expected_revision == stream_revision
 
-            next if normalized_revision == expected_revision
-
-            # pg_eventstore 3.0 requires `verdict:`, which selects the error's
-            # message. This branch is only reached when the revision we hold
-            # differs from the store's, which is exactly :unmatched_stream_revision.
+            # Same argument convention as pg_eventstore itself: `revision` is what the
+            # store holds, `expected_revision` what we held. pg_eventstore 3.0 requires
+            # `verdict:`, which selects the error's message; this branch is only reached
+            # when the two differ, which is exactly :unmatched_stream_revision.
             raise PgEventstore::WrongExpectedRevisionError.new(
-              revision: aggregate_revision,
+              revision: stream_revision,
               expected_revision:,
               stream:,
               verdict: :unmatched_stream_revision

data/lib/yes/core/command_handling/revision_conflict_backoff.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Decides how long an executor waits before retrying a command after a
+      # PgEventstore::WrongExpectedRevisionError.
+      #
+      # The executors derive the expected revision from the read model's revision
+      # column. When the conflicting append came from this service, the read model
+      # was updated in the same process, so the very next attempt already sees the
+      # new revision and any wait only adds latency. When another service appended
+      # to the stream, the column only advances once this service's event listener
+      # has projected that event, typically a few hundred milliseconds later.
+      # Retrying immediately then burns every attempt inside the same half second
+      # and the command surfaces as a 500.
+      #
+      # The error carries the stream's actual revision, so for the aggregate's own
+      # stream the two cases can be told apart: retry at once while the reloaded
+      # read model has caught up, back off while it is still behind. A conflict on
+      # an external aggregate's stream (see EventPublisher#verify_external_revisions!)
+      # cannot be checked here and always backs off.
+      #
+      # Delays follow the same 10 ms doubling schedule as the ConcurrentUpdateError
+      # branch, capped per attempt and in total, with jitter so that requests which
+      # collided once do not retry in lockstep.
+      class RevisionConflictBackoff
+        # @return [Float] delay of the first waiting attempt, in seconds
+        BASE_DELAY_SECONDS = 0.01
+        # @return [Float] longest delay of a single attempt, in seconds
+        MAX_DELAY_SECONDS = 1.0
+        # @return [Float] total sleep budget across all retries of one command, in seconds
+        TOTAL_BUDGET_SECONDS = 2.0
+        # @return [Float] fraction by which a delay is randomised in both directions
+        JITTER_FRACTION = 0.25
+
+        class << self
+          # @param error [PgEventstore::WrongExpectedRevisionError] the conflict that was raised
+          # @param aggregate_id [String] id of the aggregate the executor works on; used to tell its own
+          #   stream from an external aggregate's stream
+          # @param read_model_revision [Integer, nil] the revision the read model reports after a
+          #   reload, or nil when the aggregate has no read model
+          # @param attempt [Integer] the 1-based retry attempt about to be made
+          # @return [Float] seconds to wait before retrying, 0.0 to retry immediately
+          def delay(error:, aggregate_id:, read_model_revision:, attempt:)
+            return 0.0 unless worth_waiting?(error, aggregate_id, read_model_revision)
+
+            remaining = TOTAL_BUDGET_SECONDS - waited_before(attempt)
+            return 0.0 unless remaining.positive?
+
+            jittered([schedule(attempt), remaining].min)
+          end
+
+          # The undisturbed exponential schedule, shared with the ConcurrentUpdateError retries.
+          #
+          # @param attempt [Integer] the 1-based retry attempt
+          # @return [Float] seconds
+          def schedule(attempt)
+            [BASE_DELAY_SECONDS * (2**(attempt - 1)), MAX_DELAY_SECONDS].min
+          end
+
+          private
+
+          # @return [Boolean] false only when the conflict is on the aggregate's own stream and the
+          #   read model already reports at least the stream revision the conflict was raised with
+          def worth_waiting?(error, aggregate_id, read_model_revision)
+            return true unless own_stream?(error.stream, aggregate_id)
+            return false unless read_model_revision.is_a?(Integer) && error.revision.is_a?(Integer)
+
+            read_model_revision < error.revision
+          end
+
+          # @return [Boolean] true when the stream belongs to the aggregate itself; a stream that
+          #   cannot be inspected is treated as the aggregate's own
+          def own_stream?(stream, aggregate_id)
+            return true unless stream.respond_to?(:stream_id)
+
+            stream.stream_id.to_s == aggregate_id.to_s
+          end
+
+          # @return [Float] seconds already spent sleeping before this attempt
+          def waited_before(attempt)
+            (1...attempt).sum { schedule(_1) }
+          end
+
+          # @return [Float] the delay randomised by ±JITTER_FRACTION
+          def jittered(delay)
+            delay * (1 + (JITTER_FRACTION * ((2 * rand) - 1)))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/command_handling/revision_conflict_waiting.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Yes
+  module Core
+    module CommandHandling
+      # Shared by {CommandExecutor} and {CommandGroupExecutor}: the wait between two
+      # attempts after a PgEventstore::WrongExpectedRevisionError. Expects the
+      # including class to expose a private +aggregate+ reader.
+      module RevisionConflictWaiting
+        private
+
+        # Sleeps only while the read model has not yet caught up with the stream
+        # revision reported by the conflict, see {RevisionConflictBackoff}.
+        #
+        # @param error [PgEventstore::WrongExpectedRevisionError]
+        # @param attempt [Integer] the 1-based retry attempt about to be made
+        # @return [void]
+        def wait_for_read_model(error, attempt)
+          delay = RevisionConflictBackoff.delay(
+            error:, aggregate_id: aggregate.id, read_model_revision: current_read_model_revision, attempt:
+          )
+          sleep(delay) if delay.positive?
+        end
+
+        # @return [Integer, nil] the freshly reloaded read model revision; nil without a read model or
+        #   when the row disappeared underneath the retry, both of which mean "retry immediately"
+        def current_read_model_revision
+          return nil unless aggregate.class.read_model_enabled?
+
+          aggregate.reload.revision
+        rescue ActiveRecord::RecordNotFound
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/yes/core/commands/stateless/handler.rb

@@ -191,12 +191,15 @@ module Yes
               expected = expected_revision(stream)
               next if revision == expected
 
-              revision_error!(revision || -1, expected || -1, stream)
+              revision_error!(expected || -1, revision || -1, stream)
             end
           end
 
-          # @param revision [Integer]
-          # @param expected_revision [Integer]
+          # Same argument convention as pg_eventstore itself: `revision` is what the store
+          # holds, `expected_revision` what this handler held.
+          #
+          # @param revision [Integer] the stream's current revision
+          # @param expected_revision [Integer] the revision the handler expected
           # @param stream [PgEventstore::Stream]
           def revision_error!(revision, expected_revision, stream)
             # pg_eventstore 3.0 requires `verdict:`, which selects the error's
@@ -209,7 +212,7 @@ module Yes
               self.class.current_span&.add_attributes(
                 {
                   current_revision: revision,
-                  expected_revision: expected_revision,
+                  expected_revision:,
                   stream: stream.to_json
                 }.stringify_keys
               )

data/lib/yes/core/error.rb

@@ -2,9 +2,28 @@
 
 module Yes
   module Core
+    # Base class for the gem's errors, carrying optional caller-supplied context.
+    #
+    # @example Raising with context
+    #   raise Yes::Core::Error.new('could not resolve the aggregate', extra: { id: })
+    #
+    # @example Consuming the context safely
+    #   # #extra is not guaranteed to be a Hash - type-check before merging it.
+    #   payload.merge!(error.extra) if error.extra.is_a?(Hash)
     class Error < StandardError
+      # Caller-supplied context, returned exactly as it was given.
+      #
+      # It defaults to +nil+ and is never coerced or validated, so it may be any object the
+      # caller passed. Code that treats it as a Hash must therefore type-check first: a bare
+      # +payload.merge!(error.extra)+ raises +TypeError+ both for the +nil+ default and for any
+      # other non-Hash value. That matters most inside error-reporting hooks, where such a
+      # +TypeError+ tends to be swallowed by the reporter and takes the report down with it.
+      #
+      # @return [Object, nil] whatever the caller supplied; +nil+ when nothing was
       attr_reader :extra
 
+      # @param message [String, nil] the error message
+      # @param extra [Object, nil] arbitrary context to attach; stored as given
       def initialize(message = nil, extra: nil)
         super(message)
         @extra = extra

data/lib/yes/core/version.rb

@@ -2,6 +2,6 @@
 
 module Yes
   module Core
-    VERSION = '2.2.0'
+    VERSION = '2.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yes-core
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Nico Ritsche
@@ -242,6 +242,8 @@ files:
 - lib/yes/core/command_handling/read_model_recovery_service.rb
 - lib/yes/core/command_handling/read_model_revision_guard.rb
 - lib/yes/core/command_handling/read_model_updater.rb
+- lib/yes/core/command_handling/revision_conflict_backoff.rb
+- lib/yes/core/command_handling/revision_conflict_waiting.rb
 - lib/yes/core/command_handling/state_updater.rb
 - lib/yes/core/commands/bus.rb
 - lib/yes/core/commands/command_group.rb