pg_eventstore 1.1.5 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5fce9f1f61310bfc9c12afdb89b0a6589e9116133255eeb62ac406b24e351b72
-  data.tar.gz: 0a03a441f9e26a040f026fc7fac5d034c81b91d6f0e0bee98646b39a2f809147
+  metadata.gz: 7d3773773af377d169523f80ce08e439e019c33b94acd369f9927bf116d9bd4e
+  data.tar.gz: 3d131cf8aab4cc5f2996bc7f78c200d9b0c2455f2430863681056d569852d24e
 SHA512:
-  metadata.gz: 26a0a9b9cf70e32fd73d5f729d5d9654ec23cd90aa57a3bfdf4cae5603f58d56d62a1406df477200390497141e5c4bb89f157c749bd1df680c1b404898428094
-  data.tar.gz: 85aeeffcfc9ddfba2733e7362958a9d1528eb043ae5025c2d8bd055aa708e5c20eb2fef555be711174f3c058235c0f5b97c780b9f68b3a52e92592fe58d8f8c3
+  metadata.gz: 5b6af4853352632ce2b50306b200c5790e0f41e2063de53fe827985237665c48af5aa080072d8c1612888193f9a82050672888fc3bde0af31a77a35743a69e33
+  data.tar.gz: ee65c7f22d76c2b530783c1eeea8416962c5c969d50188f4a6c0a0d22746b1045ff5fc0b2d9a8ee3dcdeb6d8df6a4d46087ae09c7093fead0d3276bc11f45a98

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [1.2.0]
+- Implement `failed_subscription_notifier` subscription hook.
+
+Now you are able to define a function that is called when subscription fails and no longer can be automatically restarted because it hit max number of retries. You can define the hook globally in the config and per subscription. Examples:
+
+```ruby
+PgEventstore.configure do |config|
+  config.failed_subscription_notifier = proc { |sub, error| puts "Subscription: #{sub.inspect}, error: #{error.inspect}" }
+end
+
+subscriptions_manager = PgEventstore.subscriptions_manager(subscription_set: 'MyApp')
+# Overrides config.failed_subscription_notifier function
+subscriptions_manager.subscribe(
+  'My Subscription 1',
+  handler: Handler.new('My Subscription 1'),
+  options: { filter: { event_types: ['Foo'] } },
+  failed_subscription_notifier: proc { |_subscription, err| p err }
+)
+# Uses config.failed_subscription_notifier function
+subscriptions_manager.subscribe(
+  'My Subscription 2',
+  handler: Handler.new('My Subscription 2'),
+  options: { filter: { event_types: ['Bar'] } }
+)
+```
+
 ## [1.1.5]
 - Review the way to handle SubscriptionAlreadyLockedError error. This removes noise when attempting to lock an already locked subscription. 
 

data/docs/configuration.md

@@ -16,6 +16,7 @@ Configuration options:
 | subscriptions_set_max_retries      | Integer | `10`                                                         | Max number of retries for failed subscription sets.                                                                                                                                                                                                                                                                    |
 | subscriptions_set_retries_interval | Integer | `1`                                                          | Interval in seconds between retries of failed subscription sets.                                                                                                                                                                                                                                                       |
 | subscription_restart_terminator    | `#call` | `nil`                                                        | A callable object that accepts `PgEventstore::Subscription` object to determine whether restarts should be stopped(true - stops restarts, false - continues restarts).                                                                                                                                                 |
+| failed_subscription_notifier       | `#call` | `nil`                                                        | A callable object which is invoked with `PgEventstore::Subscription` instance and error instance after the related subscription died due to error and no longer can be automatically restarted due to max retries number reached. You can use this hook to send a notification about failed subscription.              |
 
 ## Multiple configurations
 

data/docs/subscriptions.md

@@ -151,7 +151,7 @@ You will then see the output of your subscription handlers. To gracefully stop t
 
 ## Overriding Subscription config values
 
-You can override `subscription_pull_interval`, `subscription_max_retries`, `subscription_retries_interval` and `subscription_restart_terminator` config values (see [**Configuration**](configuration.md) chapter for details) for the specific subscription by providing the corresponding arguments. Example:
+You can override `subscription_pull_interval`, `subscription_max_retries`, `subscription_retries_interval`, `subscription_restart_terminator` and `failed_subscription_notifier` config values (see [**Configuration**](configuration.md) chapter for details) for the specific subscription by providing the corresponding arguments. Example:
 
 ```ruby
 subscriptions_manager.subscribe(
@@ -164,7 +164,9 @@ subscriptions_manager.subscribe(
   # overrides config.subscription_retries_interval
   retries_interval: 2,
   # overrides config.subscription_restart_terminator
-  restart_terminator: proc { |subscription| subscription.last_error['class'] == 'NoMethodError' }, 
+  restart_terminator: proc { |subscription| subscription.last_error['class'] == 'NoMethodError' },
+  # overrides config.failed_subscription_notifier
+  failed_subscription_notifier: proc { |_subscription, err| p err }
 )
 ```
 

data/lib/pg_eventstore/config.rb

@@ -48,6 +48,10 @@ module PgEventstore
     # @!attribute subscriptions_set_retries_interval
     #   @return [Integer] interval in seconds between retries of failed SubscriptionsSet
     option(:subscriptions_set_retries_interval) { 1 }
+    # @!attribute failed_subscription_notifier
+    #   @return [#call, nil] provide callable object that accepts Subscription instance and error. It is useful when you
+    #     want to be get notified when your Subscription fails and no longer can be restarted
+    option(:failed_subscription_notifier)
 
     # @param name [Symbol] config's name. Its value matches the appropriate key in PgEventstore.config hash
     def initialize(name:, **options)

data/lib/pg_eventstore/subscriptions/subscription_runner.rb

@@ -29,11 +29,14 @@ module PgEventstore
     # @param events_processor [PgEventstore::EventsProcessor]
     # @param subscription [PgEventstore::Subscription]
     # @param restart_terminator [#call, nil]
-    def initialize(stats:, events_processor:, subscription:, restart_terminator: nil)
+    # @param failed_subscription_notifier [#call, nil]
+    def initialize(stats:, events_processor:, subscription:, restart_terminator: nil,
+                   failed_subscription_notifier: nil)
       @stats = stats
       @events_processor = events_processor
       @subscription = subscription
       @restart_terminator = restart_terminator
+      @failed_subscription_notifier = failed_subscription_notifier
 
       attach_callbacks
     end
@@ -119,11 +122,13 @@ module PgEventstore
       @subscription.update(last_chunk_fed_at: Time.now.utc, last_chunk_greatest_position: global_position)
     end
 
-    # @param _error [StandardError]
+    # @param error [StandardError]
     # @return [void]
-    def restart_subscription(_error)
+    def restart_subscription(error)
       return if @restart_terminator&.call(@subscription.dup)
-      return if @subscription.restart_count >= @subscription.max_restarts_number
+      if @subscription.restart_count >= @subscription.max_restarts_number
+        return @failed_subscription_notifier&.call(@subscription.dup, error)
+      end
 
       Thread.new do
         sleep @subscription.time_between_restarts

data/lib/pg_eventstore/subscriptions/subscriptions_manager.rb

@@ -61,14 +61,19 @@ module PgEventstore
     #   given subscription.
     # @param max_retries [Integer] max number of retries of failed Subscription
     # @param retries_interval [Integer, Float] a delay between retries of failed Subscription
-    # @param restart_terminator [#call, nil] a callable object which, when called - accepts PgEventstore::Subscription
-    #   object to determine whether restarts should be stopped(true - stops restarts, false - continues restarts)
+    # @param restart_terminator [#call, nil] a callable object which is invoked with PgEventstore::Subscription instance
+    #   to determine whether restarts should be stopped(true - stops restarts, false - continues restarts)
+    # @param failed_subscription_notifier [#call, nil] a callable object which is invoked with
+    #   PgEventstore::Subscription instance and error instance after the related subscription died due to error and no
+    #   longer can be automatically restarted due to max retries number reached. You can use this hook to send a
+    #   notification about failed subscription.
     # @return [void]
     def subscribe(subscription_name, handler:, options: {}, middlewares: nil,
                   pull_interval: config.subscription_pull_interval,
                   max_retries: config.subscription_max_retries,
                   retries_interval: config.subscription_retries_interval,
-                  restart_terminator: config.subscription_restart_terminator)
+                  restart_terminator: config.subscription_restart_terminator,
+                  failed_subscription_notifier: config.failed_subscription_notifier)
       subscription = Subscription.using_connection(config.name).new(
         set: @set_name, name: subscription_name, options: options, chunk_query_interval: pull_interval,
         max_restarts_number: max_retries, time_between_restarts: retries_interval
@@ -77,7 +82,8 @@ module PgEventstore
         stats: SubscriptionHandlerPerformance.new,
         events_processor: EventsProcessor.new(create_event_handler(middlewares, handler)),
         subscription: subscription,
-        restart_terminator: restart_terminator
+        restart_terminator: restart_terminator,
+        failed_subscription_notifier: failed_subscription_notifier
       )
 
       @subscription_feeder.add(runner)

data/lib/pg_eventstore/version.rb

@@ -2,5 +2,5 @@
 
 module PgEventstore
   # @return [String]
-  VERSION = "1.1.5"
+  VERSION = "1.2.0"
 end

data/sig/interfaces/failed_subscription_notifier.rbs

@@ -0,0 +1,3 @@
+interface _FailedSubscriptionNotifier
+  def call: (PgEventstore::Subscription subscription, StandardError error) -> void
+end

data/sig/pg_eventstore/config.rbs

@@ -44,6 +44,8 @@ module PgEventstore
 
     attr_accessor subscription_restart_terminator: _RestartTerminator?
 
+    attr_accessor failed_subscription_notifier: _FailedSubscriptionNotifier?
+
     attr_accessor subscriptions_set_max_retries: Integer
 
     attr_accessor subscriptions_set_retries_interval: Integer

data/sig/pg_eventstore/subscriptions/subscription_runner.rbs

@@ -12,11 +12,14 @@ module PgEventstore
     # _@param_ `subscription`
     #
     # _@param_ `restart_terminator`
+    #
+    # _@param_ `failed_subscription_notifier`
     def initialize: (
         stats: PgEventstore::SubscriptionHandlerPerformance,
         events_processor: PgEventstore::EventsProcessor,
         subscription: PgEventstore::Subscription,
-        ?restart_terminator: _RestartTerminator?
+        ?restart_terminator: _RestartTerminator?,
+        ?failed_subscription_notifier: _FailedSubscriptionNotifier?
       ) -> void
 
     def next_chunk_query_opts: () -> ::Hash[untyped, untyped]
@@ -47,7 +50,7 @@ module PgEventstore
     def update_subscription_chunk_stats: (Integer global_position) -> void
 
     # _@param_ `_error`
-    def restart_subscription: (StandardError _error) -> void
+    def restart_subscription: (StandardError error) -> void
 
     # Returns the value of attribute subscription.
     attr_accessor subscription: PgEventstore::Subscription

data/sig/pg_eventstore/subscriptions/subscriptions_manager.rbs

@@ -30,7 +30,9 @@ module PgEventstore
     #
     # _@param_ `retries_interval` — a delay between retries of failed Subscription
     #
-    # _@param_ `restart_terminator` — a callable object which, when called - accepts PgEventstore::Subscription object to determine whether restarts should be stopped(true - stops restarts, false - continues restarts)
+    # _@param_ `restart_terminator` — a callable object which is invoked with PgEventstore::Subscription instance to determine whether restarts should be stopped(true - stops restarts, false - continues restarts)
+    #
+    # _@param_ `failed_subscription_notifier` - a callable object which is invoked with PgEventstore::Subscription instance and error instance after the related subscription died due to error and no longer can be automatically restarted due to max retries number reached. You can use this hook to send a notification about failed subscription.
     def subscribe: (
         String subscription_name,
         handler: _SubscriptionHandler,
@@ -39,7 +41,8 @@ module PgEventstore
         ?pull_interval: Integer | Float,
         ?max_retries: Integer,
         ?retries_interval: Integer | Float,
-        ?restart_terminator: _RestartTerminator?
+        ?restart_terminator: _RestartTerminator?,
+        ?failed_subscription_notifier: _FailedSubscriptionNotifier?
       ) -> void
 
     def subscriptions: () -> ::Array[PgEventstore::Subscription]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pg_eventstore
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.2.0
 platform: ruby
 authors:
 - Ivan Dzyzenko
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-25 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pg
@@ -195,6 +195,7 @@ files:
 - sig/interfaces/callback.rbs
 - sig/interfaces/event_class_resolver.rbs
 - sig/interfaces/event_modifier.rbs
+- sig/interfaces/failed_subscription_notifier.rbs
 - sig/interfaces/restart_terminator.rbs
 - sig/interfaces/subscription_handler.rbs
 - sig/pg/basic_type_registry.rbs