event_store_subscriptions 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f261c1fb47c48ba5354b9d02c1b1a066e64813e397933657bbb75c396ec06f85
+  data.tar.gz: ce40a5265ba3d2bc34f4392cae838df08a471c13c85bbecc292dd53628cf464f
+SHA512:
+  metadata.gz: 97ce25b1bbcd50a345b2be4ed7f1b98048f540732a91eafff55d36c31d6d513ad759614938dba6a07139a448d0e2c3b35bdfc1bb1e96b77ee2de51643b07b84d
+  data.tar.gz: 995f4264d8a301b8dae0156ab0d08fbe3ca41744194b4357e6fddba9d29b73deec207d98d6c9859fad8f5cbc41e3204580c163d76b61e8f8ea4e92c814ab8ded

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Yousty AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,284 @@
+![Run tests](https://github.com/yousty/event_store_subscriptions/workflows/Run%20tests/badge.svg?branch=main&event=push)
+[![Gem Version](https://badge.fury.io/rb/event_store_subscriptions.svg)](https://badge.fury.io/rb/event_store_subscriptions)
+
+# EventStoreSubscriptions
+
+Extends the functionality of the [EventStoreDB ruby client](https://github.com/yousty/event_store_client) with a catch-up subscriptions manager. 
+
+By default `event_store_client` implements thread-blocking methods to subscribe to a stream. Those are `#subscribe_to_stream` and `#subscribe_to_all`. In order to subscribe to many streams/events, you need to implement asynchronous subscriptions on your own. This gem solves this task by putting each subscription into its own thread.
+
+The thread-based implementation has a downside: any IO operation in your subscription's handlers will block all other threads. So it is important to consider how many subscriptions you put into a single process. There is a plan to integrate Ractors instead/alongside threads to provide the option to eliminate the IO-blocking issue.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'event_store_subscriptions'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install event_store_subscriptions
+
+## Usage
+
+Use the `#create` and `#create_for_all` methods to subscribe to a stream. For the full list of available arguments see the documentation of the `EventStoreClient::GRPC::Client#subscribe_to_stream` method in the [event_store_client gem docs](https://rubydoc.info/gems/event_store_client). You may also want to check the [Catch-up subscriptions](https://github.com/yousty/event_store_client/blob/master/docs/catch_up_subscriptions.md) section as well.
+
+### Subscribing to a specific stream
+
+Use the `#create` method in order to subscribe to specific stream:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+handler = proc do |resp|
+  if resp.success?
+    do_something_with_resp(resp.success) # retrieve an event
+  else # resp.failure? => true
+    handle_failure(resp.failure)
+  end
+end
+subscriptions.create('some-stream', handler: handler)
+subscriptions.listen_all
+```
+
+You may provide any object which responds to `#call` as a handler:
+
+```ruby
+class SomeStreamHandler
+  def call(resp)
+    if resp.success?
+      do_something_with_resp(resp.success) # retrieve an event
+    else # resp.failure? => true
+      handle_failure(resp.failure)
+    end
+  end
+end
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create('some-stream', handler: SomeStreamHandler.new)
+subscriptions.listen_all
+```
+
+### Subscribing to the $all stream
+
+Use the `#create_for_all` method to subscribe to the all stream:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+handler = proc do |resp|
+  if resp.success?
+    do_something_with_resp(resp.success) # retrieve an event
+  else # resp.failure? => true
+    handle_failure(resp.failure)
+  end
+end
+subscriptions.create_for_all(handler: handler)
+subscriptions.listen_all
+```
+
+You may also explicitly pass `"$all"` stream name to the `#create` method:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+handler = proc do |resp|
+  if resp.success?
+    do_something_with_resp(resp.success) # retrieve an event
+  else # resp.failure? => true
+    handle_failure(resp.failure)
+  end
+end
+subscriptions.create('$all', handler: handler)
+subscriptions.listen_all
+```
+
+### Handling Subscription position updates
+
+You may want to add a handler that will be executed each time a subscription gets position updates. Such updates happen when new events are added to the stream or when EventStore DB produces a checkpoint response.
+
+#### Listening for position updates of a specific stream
+
+A handler registered to receive position updates of a specific stream is called with the `EventStoreSubscriptions::SubscriptionRevision` class instance. It holds the current revision of the stream.
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscription = subscriptions.create('some-stream', handler: proc { |r| p r })
+subscription.position.register_update_hook do |position|
+  puts "Current revision is #{position.revision}"
+end
+subscription.listen
+```
+
+#### Listening for position updates of the $all stream
+
+A handler registered to receive position updates of the `$all` stream is called with the `EventStoreSubscriptions::SubscriptionPosition` class instance. It holds the current `commit_position` and `prepare_position` of the `$all` stream.
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscription = subscriptions.create_for_all(handler: proc { |r| p r })
+subscription.position.register_update_hook do |position|
+  puts "Current commit/prepare positions are #{position.commit_position}/#{position.prepare_position}"
+end
+subscription.listen
+```
+
+### Automatic restart of failed Subscriptions
+
+This gem provides a possibility to watch over your subscription collections and restart a subscription in case it failed. Subscriptions may fail because an exception was raised in the handler or in the position update hook. A new subscription will be started, listening from the position the failed subscription has stopped. 
+
+Start watching over your subscriptions' collection:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create_for_all(handler: proc { |r| p r })
+EventStoreSubscriptions::WatchDog.watch(subscriptions)
+subscriptions.listen_all
+```
+
+### Async nature of this gem
+
+`EventStoreSubscriptions::Subscriptions#listen_all`, `EventStoreSubscriptions::Subscriptions#stop_all`, `EventStoreSubscriptions::Subscription#listen`, `EventStoreSubscriptions::Subscription#stop_listening`, `EventStoreSubscriptions::WatchDog#watch`, `EventStoreSubscriptions::WatchDog#unwatch` methods are asynchronous. This means that they spawn thread that performs proper task in the background.
+
+`EventStoreSubscriptions::Subscriptions#stop_all`, `EventStoreSubscriptions::Subscription#stop_listening` and `EventStoreSubscriptions::WatchDog#unwatch` methods has ending run time, meaning that they runners won't run forever.
+
+`EventStoreSubscriptions::Subscriptions#listen_all`, `EventStoreSubscriptions::Subscription#listen` and `EventStoreSubscriptions::WatchDog#watch` methods will run forever.
+
+In order to stop running `Subscription` or `WatchDog` you should initiate stop process and wait for finish.
+
+#### Stopping Subscription
+
+For single subscription:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscription = subscriptions.create_for_all(handler: proc { |r| p r })
+subscription.listen
+
+# Initiate Subscription shutdown
+subscription.stop_listening
+# Wait for Subscription to finish. This will block current Thread.
+subscription.wait_for_finish
+```
+
+For the entire collection:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create_for_all(handler: proc { |r| p r })
+subscriptions.listen_all
+
+# Initiate shutdown for each Subscription in the collection
+subscriptions.stop_all
+# Wait for all Subscriptions to finish. This will block current Thread.
+subscriptions.subscriptions.each(&:wait_for_finish)
+```
+
+#### Stopping WatchDog
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+watcher = EventStoreSubscriptions::WatchDog.watch(subscriptions)
+
+# Initiate WatchDog shutdown
+watcher.unwatch
+# Wait for WatchDog to finish. This will block current Thread.
+watcher.wait_for_finish
+```
+
+### Graceful shutdown
+
+You may want to gracefully shut down the process that handles the subscriptions. In order to do so, you should define a `Kernel.trap` handler to handle your kill signal:
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create_for_all(handler: proc { |r| p r })
+watcher = EventStoreSubscriptions::WatchDog.watch(subscriptions)
+subscriptions.listen_all
+
+Kernel.trap('TERM') do
+  # Because the implementation uses Mutex - wrap it into Thread to bypass the limitations of
+  # Kernel#trap
+  Thread.new do
+    # Initiate graceful shutdown. Need to shutdown watcher first, and then - subscriptions
+    watcher.unwatch.wait_for_finish
+    subscriptions.stop_all.each(&:wait_for_finish)
+  end.join
+  exit
+end
+
+# Wait while Subscriptions are working
+subscriptions.each(&:wait_for_finish)
+```
+
+Now just send the `TERM` signal if you want to gracefully shut down your process:
+
+```bash
+kill -TERM <pid of your process>
+```
+
+### Monitoring Subscriptions
+
+After you started listening your Subscriptions, you may want to monitor status of them. There is various built-in statistics which you can get.
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create_for_all(handler: proc { |r| p r })
+watcher = EventStoreSubscriptions::WatchDog.watch(subscriptions)
+subscriptions.listen_all
+
+loop do
+  sleep 1
+  subscriptions.subscriptions.each do |subscription|
+    puts "Current state is: #{subscription.state}"
+    puts "Current position: #{subscription.position.to_h}"
+    puts "Last error: #{subscription.statistic.last_error.inspect}"
+    puts "Last restart was at: #{subscription.statistic.last_restart_at || 'Never'}"
+    puts "Total errors/restarts: #{subscription.statistic.errors_count}"
+    puts "Events processed: #{subscription.statistic.events_processed}"
+    puts "Current watcher state is: #{watcher.state}"
+  end
+end
+```
+
+### WatchDog and control of restart condition of Subscriptions
+
+You may want to decide yourself whether `WhatchDog` should restart a `Subscription`. You can do so by providing a proc which, if thruthy result is returned, skips the restart of `Subscription`.
+
+```ruby
+subscriptions = EventStoreSubscriptions::Subscriptions.new(EventStoreClient.client)
+subscriptions.create_for_all(handler: proc { |r| p r })
+# Do not restart Subscription if its id is even
+restart_terminator = proc { |sub| sub.__id__ % 2 == 0 }
+EventStoreSubscriptions::WatchDog.watch(subscriptions, restart_terminator: restart_terminator)
+subscriptions.listen_all
+```
+
+## Development
+
+You will have to install Docker first. It is needed to run EventStore DB. You can run EventStore DB with this command:
+
+```shell
+docker-compose -f docker-compose-cluster.yml up
+```
+
+Now you can enter a dev console by running `bin/console` or run tests by running the `rspec` command.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/event_store_subscriptions. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yousty/event_store_subscriptions/blob/master/CODE_OF_CONDUCT.md).
+
+### Publishing new version
+
+1. Push commit with updated `version.rb` file to the `release` branch. The new version will be automatically pushed to [rubygems](https://rubygems.org).
+2. Create release on GitHub including change log.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the EventStoreSubscriptions project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yousty/event_store_subscriptions/blob/master/CODE_OF_CONDUCT.md).

data/lib/event_store_subscriptions/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  class Error < StandardError
+  end
+
+  class ThreadNotDeadError < Error
+  end
+end

data/lib/event_store_subscriptions/object_state.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # Defines various states. It is used to set and get current object's state.
+  class ObjectState
+    attr_accessor :state
+    attr_reader :semaphore
+    private :state, :state=, :semaphore
+
+    STATES = %i(initial running halting stopped dead).freeze
+
+    def initialize
+      @semaphore = Thread::Mutex.new
+      initial!
+    end
+
+    STATES.each do |state|
+      # Checks whether the object is in appropriate state
+      # @return [Boolean]
+      define_method "#{state}?" do
+        semaphore.synchronize { self.state == state }
+      end
+
+      # Sets the state.
+      # @return [Symbol]
+      define_method "#{state}!" do
+        semaphore.synchronize { self.state = state }
+      end
+    end
+
+    # @return [String] string representation of the #state
+    def to_s
+      state.to_s
+    end
+  end
+end

data/lib/event_store_subscriptions/subscription.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  class Subscription
+    include WaitForFinish
+
+    FORCED_SHUTDOWN_DELAY = 60 # seconds
+
+    attr_accessor :runner
+    attr_reader :client, :setup, :state, :position, :statistic
+    private :runner, :runner=
+
+    # @param position [EventStoreSubscriptions::SubscriptionPosition, EventStoreSubscriptions::SubscriptionRevision]
+    # @param client [EventStoreClient::GRPC::Client]
+    # @param setup [EventStoreSubscriptions::SubscriptionSetup]
+    # @param statistic [EventStoreSubscriptions::SubscriptionStatistic]
+    def initialize(position:, client:, setup:, statistic: SubscriptionStatistic.new)
+      @position = position
+      @client = client
+      @setup = setup
+      @state = ObjectState.new
+      @statistic = statistic
+      @runner = nil
+    end
+
+    # Start listening for the events
+    # @return [EventStoreSubscriptions::Subscription] returns self
+    def listen
+      self.runner ||=
+        begin
+          state.running!
+          Thread.new do
+            Thread.current.abort_on_exception = false
+            Thread.current.report_on_exception = false
+            client.subscribe_to_stream(
+              *setup.args,
+              **adjusted_kwargs,
+              &setup.blk
+            )
+          rescue StandardError => e
+            statistic.last_error = e
+            statistic.errors_count += 1
+            state.dead!
+            raise
+          end
+        end
+      self
+    end
+
+    # Stops listening for events. This command is async - the result is not immediate. Use the #wait_for_finish 
+    # method to wait until the runner has fully stopped.
+    # @return [EventStoreSubscriptions::Subscription] returns self
+    def stop_listening
+      return self unless runner&.alive?
+
+      state.halting!
+      Thread.new do
+        stopping_at = Time.now.utc
+        loop do
+          # Give Subscription up to FORCED_SHUTDOWN_DELAY seconds for graceful shutdown
+          runner&.exit if Time.now.utc - stopping_at > FORCED_SHUTDOWN_DELAY
+
+          unless runner&.alive?
+            state.stopped!
+            self.runner = nil
+            break
+          end
+          sleep 0.1
+        end
+      end
+      self
+    end
+
+    # Removes all properties of object and freezes it. You can't delete currently running
+    #   Subscription though. You must stop it first.
+    # @return [EventStoreSubscriptions::Subscription] frozen object
+    # @raise [EventStoreSubscriptions::ThreadNotDeadError] raises this error in case runner Thread
+    #   is still alive for some reason. Normally this should never happen.
+    def delete
+      if runner&.alive?
+        raise ThreadNotDeadError, "Can not delete alive Subscription #{self.inspect}"
+      end
+
+      instance_variables.each { |var| instance_variable_set(var, nil) }
+      freeze
+    end
+
+    private
+
+    # Wraps original handler into our own handler to provide extended functionality.
+    # @param original_handler [#call]
+    # @return [Proc]
+    def handler(original_handler)
+      proc do |result|
+        Thread.current.exit unless state.running?
+        original_result = result.success
+        result = EventStoreClient::GRPC::Shared::Streams::ProcessResponse.new.call(
+          original_result,
+          *process_response_args
+        )
+        original_handler.call(result) if result
+        statistic.events_processed += 1
+        position.update(original_result)
+      end
+    end
+
+    # Calculates "skip_deserialization" and "skip_decryption" arguments for the ProcessResponse
+    # class. Since we have overridden the original handler, we need to calculate the correct argument values
+    # to process the response on our own. This method implements the same behavior as
+    # the event_store_client gem implements (EventStoreClient::GRPC::Client#subscribe_to_stream
+    # method).
+    # @return [Array<Boolean>]
+    def process_response_args
+      skip_deserialization =
+        if setup.kwargs.key?(:skip_deserialization)
+          setup.kwargs[:skip_deserialization]
+        else
+          client.config.skip_deserialization
+        end
+      skip_decryption =
+        if setup.kwargs.key?(:skip_decryption)
+          setup.kwargs[:skip_decryption]
+        else
+          client.config.skip_decryption
+        end
+      [skip_deserialization, skip_decryption]
+    end
+
+    # Override keyword arguments, provided by dev in EventStoreSubscriptions::Subscriptions#create
+    # or EventStoreSubscriptions::Subscriptions#create_for_all methods. This is needed to provide
+    # our own handler and to override the starting position of the given stream.
+    # @return [Hash]
+    def adjusted_kwargs
+      kwargs = setup.dup.kwargs
+      kwargs.merge!(handler: handler(kwargs[:handler]), skip_deserialization: true)
+      return kwargs unless position.present?
+
+      kwargs[:options] ||= {}
+      kwargs[:options].merge!(position.to_option)
+      kwargs
+    end
+  end
+end

data/lib/event_store_subscriptions/subscription_position.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # This class is used to persist and update commit_position and prepare_position when subscribing
+  # to the "$all" stream.
+  class SubscriptionPosition < Struct.new(:commit_position, :prepare_position)
+    attr_reader :update_hooks
+
+    def initialize(*)
+      super
+      @update_hooks = []
+    end
+
+    # Updates the position from the GRPC response.
+    # @param response [EventStore::Client::Streams::ReadResp] GRPC EventStore object. See its
+    #   structure in the lib/event_store_client/adapters/grpc/generated/streams_pb.rb file in
+    #   `event_store_client` gem.
+    # @return [Boolean] whether the position was updated
+    def update(response)
+      source = response.checkpoint || response.event&.event
+      return false unless source
+
+      # Updating position values in memory first to prevent the situation when the update hook fails,
+      # and the position is not up to date.
+      self.commit_position, self.prepare_position =
+        source.commit_position, source.prepare_position
+
+      update_hooks.each do |handler|
+        handler.call(self)
+      end
+      true
+    end
+
+    # Adds a handler that will be executed when the position gets updates. You may add as many
+    # handlers as you want.
+    # Example:
+    #   ```ruby
+    #   subscription_position.register_update_hook do |position|
+    #     # do something with the position. E.g. persist it somewhere
+    #   end
+    #   subscription_position.register_update_hook do |position|
+    #     # do something else with the position
+    #   end
+    #   ```
+    # @return [void]
+    def register_update_hook(&blk)
+      update_hooks << blk
+    end
+
+    # Checks if position's properties are absent
+    # @return [Boolean]
+    def empty?
+      commit_position.nil? || prepare_position.nil?
+    end
+
+    # Checks if position's properties are present
+    # @return [Boolean]
+    def present?
+      !empty?
+    end
+
+    # Constructs a hash compatible for usage with EventStoreClient::GRPC::Client#subscribe_to_stream
+    # method. You can pass it into :options keyword argument of that method to set the starting
+    # position of the stream.
+    # @return [Hash]
+    def to_option
+      { from_position: { commit_position: commit_position, prepare_position: prepare_position } }
+    end
+  end
+end

data/lib/event_store_subscriptions/subscription_revision.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # This class is used to persist and update the revision when subscribing to the specific stream.
+  # Specific streams are streams which names differ from "$all".
+  class SubscriptionRevision < Struct.new(:revision)
+    attr_reader :update_hooks
+
+    def initialize(*)
+      super
+      @update_hooks = []
+    end
+
+    # Updates the revision from GRPC response.
+    # @param response [EventStore::Client::Streams::ReadResp] GRPC EventStore object. See its
+    #   structure in the lib/event_store_client/adapters/grpc/generated/streams_pb.rb file in the
+    #   `event_store_client` gem.
+    # @return [Boolean] whether the revision was updated
+    def update(response)
+      return false unless response.event&.event
+
+      # Updating revision value in memory first to prevent the situation when update hook fails and,
+      # thus keeping the revision not up to date
+      self.revision = response.event.event.stream_revision
+      update_hooks.each do |handler|
+        handler.call(self)
+      end
+      true
+    end
+
+    # Adds a handler that will be executed when the revision gets updates. You may add as many
+    # handlers as you want.
+    # Example:
+    #   ```ruby
+    #   subscription_revision.register_update_hook do |position|
+    #     # do something with the position. E.g. persist it somewhere
+    #   end
+    #   subscription_revision.register_update_hook do |position|
+    #     # do something else with the position
+    #   end
+    #   ```
+    # @return [void]
+    def register_update_hook(&blk)
+      update_hooks << blk
+    end
+
+    # Checks if revision property is absent
+    # @return [Boolean]
+    def empty?
+      revision.nil?
+    end
+
+    # Checks if revision property is set
+    # @return [Boolean]
+    def present?
+      !empty?
+    end
+
+    # Constructs a hash compatible for usage with EventStoreClient::GRPC::Client#subscribe_to_stream
+    # method. You can pass it into :options keyword argument of that method to set the starting
+    # revision of the stream.
+    # @return [Hash]
+    def to_option
+      { from_revision: revision }
+    end
+  end
+end

data/lib/event_store_subscriptions/subscription_setup.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # Handles arguments that were used to create a subscription. We need to persist them for
+  # later adjustment and delegation.
+  class SubscriptionSetup < Struct.new(:args, :kwargs, :blk)
+    # @return [EventStoreSubscriptions::SubscriptionSetup]
+    def dup
+      self.class.new(args.dup, deep_dup(kwargs), blk)
+    end
+
+    private
+
+    # @param hash [Hash]
+    # @return [Hash]
+    def deep_dup(hash)
+      result = {}
+      hash.each_pair do |k, v|
+        result[k] =
+          case v
+          when Hash
+            deep_dup(v)
+          when Array
+            v.dup
+          else
+            v
+          end
+      end
+      result
+    end
+  end
+end

data/lib/event_store_subscriptions/subscription_statistic.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # Holds Subscription statistic
+  class SubscriptionStatistic
+    attr_accessor :last_error, :errors_count, :events_processed, :last_restart_at
+
+    def initialize
+      @last_error = nil
+      @last_restart_at = nil
+      @errors_count = 0
+      @events_processed = 0
+    end
+  end
+end

data/lib/event_store_subscriptions/subscriptions.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # Implements Subscription-s collection
+  class Subscriptions
+    ALL_STREAM = '$all'
+
+    attr_reader :client
+    attr_reader :semaphore
+    private :semaphore
+
+    # @param client [EventStoreClient::GRPC::Client]
+    def initialize(client)
+      @client = client
+      @subscriptions = []
+      @semaphore = Mutex.new
+    end
+
+    # @see EventStoreClient::GRPC::Client#subscribe_to_stream documentation for available params
+    # @return [EventStoreSubscriptions::Subscription]
+    def create(*args, **kwargs, &blk)
+      setup = SubscriptionSetup.new(args, kwargs, blk)
+      subscription = Subscription.new(
+        position: position_class(args[0]).new, client: client, setup: setup
+      )
+      add(subscription)
+      subscription
+    end
+
+    # Shortcut to create a Subscription to subscribe to the '$all' stream
+    # @see EventStoreClient::GRPC::Client#subscribe_to_all documentation for available params
+    # @return [EventStoreSubscriptions::Subscription]
+    def create_for_all(**kwargs, &blk)
+      create(ALL_STREAM, **kwargs, &blk)
+    end
+
+    # Adds Subscription to the collection
+    # @param subscription [EventStoreSubscriptions::Subscription]
+    # @return [Array<EventStoreSubscriptions::Subscription>] current subscription's collection
+    def add(subscription)
+      semaphore.synchronize { @subscriptions << subscription }
+    end
+
+    # Removes subscription from the collection
+    # @param subscription [EventStoreSubscriptions::Subscription]
+    # @return [EventStoreSubscriptions::Subscription, nil] returns deleted subscription or nil if it
+    #   wasn't present in the collection
+    def remove(subscription)
+      semaphore.synchronize { @subscriptions.delete(subscription) }
+    end
+
+    # Starts listening to all subscriptions in the collection
+    # @return [Array<EventStoreSubscriptions::Subscription>]
+    def listen_all
+      semaphore.synchronize { @subscriptions.each(&:listen) }
+    end
+
+    # Stops listening to all subscriptions in the collection
+    # @return [Array<EventStoreSubscriptions::Subscription>]
+    def stop_all
+      semaphore.synchronize { @subscriptions.each(&:stop_listening) }
+    end
+
+    # @return [Array<EventStoreSubscriptions::Subscription>]
+    def subscriptions
+      # Duping original collection to prevent potential mutable operations over it from user's side
+      semaphore.synchronize { @subscriptions.dup }
+    end
+
+    private
+
+    # @param stream_name [String]
+    # @return [Class<EventStoreSubscriptions::SubscriptionPosition>, Class<EventStoreSubscriptions::SubscriptionRevision>]
+    def position_class(stream_name)
+      stream_name == ALL_STREAM ? SubscriptionPosition : SubscriptionRevision
+    end
+  end
+end

data/lib/event_store_subscriptions/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  VERSION = "1.0.0"
+end

data/lib/event_store_subscriptions/wait_for_finish.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  module WaitForFinish
+    # Waits until state switches from :running to any other state.
+    # @return [void]
+    def wait_for_finish
+      loop do
+        break if state.stopped? || state.dead?
+
+        sleep 0.1
+      end
+    end
+  end
+end

data/lib/event_store_subscriptions/watch_dog.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module EventStoreSubscriptions
+  # Watches over the given subscriptions collection and restarts dead subscriptions. It is useful
+  # in cases when your subscription's handler raises error. Its usage is optional.
+  class WatchDog
+    include WaitForFinish
+
+    CHECK_INTERVAL = 5 # seconds. How often to scan subscriptions
+
+    class << self
+      # @param collection [EventStoreSubscriptions::Subscriptions]
+      # @param restart_terminator [Proc, nil]
+      # @return [EventStoreSubscriptions::WatchDog]
+      def watch(collection, restart_terminator: nil)
+        new(collection).watch
+      end
+    end
+
+    attr_accessor :runner
+    attr_reader :collection, :state, :restart_terminator
+    private :runner, :runner=, :restart_terminator
+
+    # @param collection [EventStoreSubscriptions::Subscriptions]
+    # @param restart_terminator [Proc, nil] define a terminator that would halt Subscription restart
+    #   process if the result of it execution is truthy. Subscription instance will be passed as a
+    #   first argument into it, and, based on it, you should decide whether to process the restart
+    #   or not.
+    def initialize(collection, restart_terminator: nil)
+      @collection = collection
+      @state = ObjectState.new
+      @runner = nil
+      @restart_terminator = restart_terminator
+    end
+
+    # Start watching over the given Subscriptions collection
+    # @return [EventStoreSubscriptions::WatchDog] returns self
+    def watch
+      self.runner ||=
+        begin
+          state.running!
+          Thread.new do
+            loop do
+              sleep CHECK_INTERVAL
+              break unless state.running?
+
+              collection.subscriptions.each do |sub|
+                break unless state.running?
+
+                restart_subscription(sub) if sub.state.dead?
+              end
+            end
+          rescue StandardError => e
+            state.dead!
+            raise
+          end
+        end
+      self
+    end
+
+    # Stop watching over the given subscriptions collection. This command is async - the result is
+    # not immediate. Use the #wait_for_finish method in order to wait until the runner has fully stopped .
+    # Example:
+    #   ```ruby
+    #   watch_dog.unwatch.wait_for_finish
+    #   ```
+    # @return [EventStoreSubscriptions::WatchDog] returns self
+    def unwatch
+      return self unless runner&.alive?
+
+      state.halting!
+      Thread.new do
+        loop do
+          # If runner sleeps between runs we can safely shut it down. Even if the edge case happens,
+          # when a runner's status changes between its check and `runner.exit`, it is still ok, it
+          # would be shut down anyway because of the guard condition `break unless state.running?`
+          runner.exit if runner&.status == 'sleep'
+          unless runner&.alive?
+            state.stopped!
+            self.runner = nil
+            break
+          end
+          sleep 0.1
+        end
+      end
+      self
+    end
+
+    private
+
+    # @param failed_sub [EventStoreSubscriptions::Subscription]
+    # @return [EventStoreSubscriptions::Subscription] newly created Subscription
+    def restart_subscription(failed_sub)
+      return if restart_terminator&.call(failed_sub)
+      # Check if no one else did this job
+      return unless collection.remove(failed_sub)
+
+      new_sub = Subscription.new(
+        position: failed_sub.position,
+        client: failed_sub.client,
+        setup: failed_sub.setup,
+        statistic: failed_sub.statistic
+      )
+      new_sub.statistic.last_restart_at = Time.now.utc
+      collection.add(new_sub)
+      failed_sub.delete
+      new_sub.listen
+    end
+  end
+end

data/lib/event_store_subscriptions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'event_store_client'
+require_relative 'event_store_subscriptions/version'
+require_relative 'event_store_subscriptions/error'
+require_relative 'event_store_subscriptions/wait_for_finish'
+require_relative 'event_store_subscriptions/object_state'
+require_relative 'event_store_subscriptions/subscription_statistic'
+require_relative 'event_store_subscriptions/subscription'
+require_relative 'event_store_subscriptions/subscription_position'
+require_relative 'event_store_subscriptions/subscription_revision'
+require_relative 'event_store_subscriptions/subscription_setup'
+require_relative 'event_store_subscriptions/subscriptions'
+require_relative 'event_store_subscriptions/watch_dog'
+
+module EventStoreSubscriptions
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: event_store_subscriptions
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ivan Dzyzenko
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: event_store_client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Implementation of subscription manager for `event_store_client` gem.
+email:
+- ivan.dzyzenko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/event_store_subscriptions.rb
+- lib/event_store_subscriptions/error.rb
+- lib/event_store_subscriptions/object_state.rb
+- lib/event_store_subscriptions/subscription.rb
+- lib/event_store_subscriptions/subscription_position.rb
+- lib/event_store_subscriptions/subscription_revision.rb
+- lib/event_store_subscriptions/subscription_setup.rb
+- lib/event_store_subscriptions/subscription_statistic.rb
+- lib/event_store_subscriptions/subscriptions.rb
+- lib/event_store_subscriptions/version.rb
+- lib/event_store_subscriptions/wait_for_finish.rb
+- lib/event_store_subscriptions/watch_dog.rb
+homepage: https://github.com/yousty/event_store_subscriptions
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/yousty/event_store_subscriptions
+  source_code_uri: https://github.com/yousty/event_store_subscriptions
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key: 
+specification_version: 4
+summary: Implementation of subscription manager for `event_store_client` gem.
+test_files: []