pg_eventstore 0.3.0 → 0.4.0

data/lib/pg_eventstore/subscriptions/events_processor.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # This class actually processes events.
+  # @!visibility private
+  class EventsProcessor
+    include Extensions::CallbacksExtension
+    extend Forwardable
+
+    def_delegators :@basic_runner, :state, :start, :stop, :wait_for_finish, :stop_async, :restore, :running?
+
+    # @param handler [#call]
+    def initialize(handler)
+      @handler = handler
+      @raw_events = []
+      @basic_runner = BasicRunner.new(0, 5)
+      attach_runner_callbacks
+    end
+
+    # @param raw_events [Array<Hash>]
+    # @return [void]
+    def feed(raw_events)
+      callbacks.run_callbacks(:feed, raw_events.last&.dig('global_position'))
+      @raw_events.push(*raw_events)
+    end
+
+    # Number of unprocessed events which are currently in a queue
+    # @return [Integer]
+    def events_left_in_chunk
+      @raw_events.size
+    end
+
+    private
+
+    # @param raw_event [Hash]
+    # @return [void]
+    def process_event(raw_event)
+      callbacks.run_callbacks(:process, raw_event['global_position']) do
+        @handler.call(raw_event)
+      end
+    end
+
+    def attach_runner_callbacks
+      @basic_runner.define_callback(:process_async, :before, method(:process_async))
+      @basic_runner.define_callback(:after_runner_died, :before, method(:after_runner_died))
+      @basic_runner.define_callback(:before_runner_restored, :before, method(:before_runner_restored))
+      @basic_runner.define_callback(:change_state, :before, method(:change_state))
+    end
+
+    def process_async
+      raw_event = @raw_events.shift
+      return sleep 0.5 if raw_event.nil?
+
+      process_event(raw_event)
+    rescue
+      @raw_events.unshift(raw_event)
+      raise
+    end
+
+    def after_runner_died(...)
+      callbacks.run_callbacks(:error, ...)
+    end
+
+    def before_runner_restored
+      callbacks.run_callbacks(:restart)
+    end
+
+    def change_state(...)
+      callbacks.run_callbacks(:change_state, ...)
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/runner_state.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # Implements different states of a runner.
+  # @!visibility private
+  class RunnerState
+    include Extensions::CallbacksExtension
+
+    STATES = %i(initial running halting stopped dead).to_h { [_1, _1.to_s.freeze] }.freeze
+
+    def initialize
+      initial!
+    end
+
+    STATES.each do |state, value|
+      # Checks whether a runner is in appropriate state
+      # @return [Boolean]
+      define_method "#{state}?" do
+        @state == value
+      end
+
+      # Sets the state.
+      # @return [String]
+      define_method "#{state}!" do
+        set_state(value)
+      end
+    end
+
+    # @return [String] string representation of the state
+    def to_s
+      @state
+    end
+
+    private
+
+    # @param state [String]
+    # @return [String]
+    def set_state(state)
+      old_state = @state
+      @state = state
+      callbacks.run_callbacks(:change_state, @state) unless old_state == @state
+      @state
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/subscription.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # Defines ruby's representation of subscriptions record.
+  class Subscription
+    include Extensions::UsingConnectionExtension
+    include Extensions::OptionsExtension
+
+    # @!attribute id
+    #   @return [Integer]
+    attribute(:id)
+    # @!attribute set
+    #   @return [String] Subscription's set. Subscription should have unique pair of set and name.
+    attribute(:set)
+    # @!attribute name
+    #   @return [String] Subscription's name. Subscription should have unique pair of set and name.
+    attribute(:name)
+    # @!attribute total_processed_events
+    #   @return [Integer] total number of events, processed by this subscription
+    attribute(:total_processed_events)
+    # @!attribute options
+    #   @return [Hash] subscription's options to be used to query events. See {SubscriptionManager#subscribe} for the
+    #     list of available options
+    attribute(:options)
+    # @!attribute current_position
+    #   @return [Integer, nil] current Subscription's position. It is updated automatically each time an event is processed
+    attribute(:current_position)
+    # @!attribute state
+    #   @return [String, nil] current Subscription's state. It is updated automatically during Subscription's life cycle.
+    #     See {RunnerState::STATES} for possible values.
+    attribute(:state)
+    # @!attribute average_event_processing_time
+    #   @return [Float, nil] a speed of the subscription. Divide 1 by this value to determine how much events are
+    #     processed by the Subscription per second.
+    attribute(:average_event_processing_time)
+    # @!attribute restart_count
+    #   @return [Integer] the number of Subscription's restarts after its failure
+    attribute(:restart_count)
+    # @!attribute max_restarts_number
+    #   @return [Integer] maximum number of times the Subscription can be restarted
+    attribute(:max_restarts_number)
+    # @!attribute time_between_restarts
+    #   @return [Integer] interval in seconds between retries of failed Subscription
+    attribute(:time_between_restarts)
+    # @!attribute last_restarted_at
+    #   @return [Time, nil] last time the Subscription was restarted
+    attribute(:last_restarted_at)
+    # @!attribute last_error
+    #   @return [Hash{'class' => String, 'message' => String, 'backtrace' => Array<String>}, nil] the information about
+    #     last error caused when processing events by the Subscription.
+    attribute(:last_error)
+    # @!attribute last_error_occurred_at
+    #   @return [Time, nil] the time when the last error occurred
+    attribute(:last_error_occurred_at)
+    # @!attribute chunk_query_interval
+    #   @return [Integer] determines how often to pull events for the given Subscription in seconds
+    attribute(:chunk_query_interval)
+    # @!attribute chunk_query_interval
+    #   @return [Time] shows the time when last time events were fed to the event's processor
+    attribute(:last_chunk_fed_at)
+    # @!attribute last_chunk_greatest_position
+    #   @return [Integer, nil] shows the greatest global_position of the last event in the last chunk fed to the event's
+    #     processor
+    attribute(:last_chunk_greatest_position)
+    # @!attribute locked_by
+    #   @return [String, nil] UUIDv4. The id of subscription manager which obtained the lock of the Subscription. _nil_
+    #     value means that the Subscription isn't locked yet by any subscription manager.
+    attribute(:locked_by)
+    # @!attribute created_at
+    #   @return [Time]
+    attribute(:created_at)
+    # @!attribute updated_at
+    #   @return [Time]
+    attribute(:updated_at)
+
+    def options=(val)
+      @options = Utils.deep_transform_keys(val, &:to_sym)
+    end
+
+    # @param attrs [Hash]
+    # @return [Hash]
+    def update(attrs)
+      assign_attributes(subscription_queries.update(id, attrs))
+    end
+
+    # @param attrs [Hash]
+    # @return [Hash]
+    def assign_attributes(attrs)
+      attrs.each do |attr, value|
+        public_send("#{attr}=", value)
+      end
+    end
+
+    # Locks the Subscription by the given lock id
+    # @return [PgEventstore::Subscription]
+    def lock!(lock_id, force = false)
+      self.id = subscription_queries.find_or_create_by(set: set, name: name)[:id]
+      self.locked_by = subscription_queries.lock!(id, lock_id, force)
+      reset_runtime_attributes
+      self
+    end
+
+    # Unlocks the Subscription.
+    # @return [void]
+    def unlock!
+      subscription_queries.unlock!(id, locked_by)
+      self.locked_by = nil
+    end
+
+    # Dup the current object without assigned connection
+    # @return [PgEventstore::Subscription]
+    def dup
+      Subscription.new(**Utils.deep_dup(options_hash))
+    end
+
+    # @return [PgEventstore::Subscription]
+    def reload
+      assign_attributes(subscription_queries.find!(id))
+      self
+    end
+
+    private
+
+    def reset_runtime_attributes
+      update(
+        options: options,
+        restart_count: 0,
+        last_restarted_at: nil,
+        max_restarts_number: max_restarts_number,
+        chunk_query_interval: chunk_query_interval,
+        last_chunk_fed_at: Time.at(0).utc,
+        last_chunk_greatest_position: nil,
+        state: RunnerState::STATES[:initial]
+      )
+    end
+
+    def subscription_queries
+      SubscriptionQueries.new(self.class.connection)
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/subscription_feeder.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # This class is responsible for starting/stopping all SubscriptionRunners. The background runner of it is responsible
+  # for events pulling and feeding those SubscriptionRunners.
+  # @!visibility private
+  class SubscriptionFeeder
+    extend Forwardable
+
+    def_delegators :subscriptions_set, :id
+    def_delegators :@basic_runner, :start, :stop, :restore, :state, :wait_for_finish, :stop_async
+
+    # @param config_name [Symbol]
+    # @param set_name [String]
+    # @param max_retries [Integer] max number of retries of failed SubscriptionsSet
+    # @param retries_interval [Integer] a delay between retries of failed SubscriptionsSet
+    def initialize(config_name:, set_name:, max_retries:, retries_interval:)
+      @config_name = config_name
+      @runners = []
+      @set_name = set_name
+      @max_retries = max_retries
+      @retries_interval = retries_interval
+      @commands_handler = CommandsHandler.new(@config_name, self, @runners)
+      @basic_runner = BasicRunner.new(1, 0)
+      @force_lock = false
+      attach_runner_callbacks
+    end
+
+    # Adds SubscriptionRunner to the set
+    # @param runner [PgEventstore::SubscriptionRunner]
+    def add(runner)
+      assert_proper_state!
+      @runners.push(runner)
+      runner
+    end
+
+    # Starts all SubscriptionRunners. This is only available if SubscriptionFeeder's runner is alive.
+    # @return [void]
+    def start_all
+      return self unless @basic_runner.running?
+
+      @runners.each(&:start)
+      self
+    end
+
+    # Stops all SubscriptionRunners asynchronous. This is only available if SubscriptionFeeder's runner is alive.
+    # @return [void]
+    def stop_all
+      return self unless @basic_runner.running?
+
+      @runners.each(&:stop_async)
+      self
+    end
+
+    # Sets the force_lock flash to true. If set - all related Subscriptions will ignore their lock state and will be
+    # locked by the new SubscriptionsSet.
+    def force_lock!
+      @force_lock = true
+    end
+
+    # Produces a copy of currently running Subscriptions. This is needed, because original Subscriptions objects are
+    # dangerous to use - users may incidentally break their state.
+    # @return [Array<PgEventstore::Subscription>]
+    def read_only_subscriptions
+      @runners.map(&:subscription).map(&:dup)
+    end
+
+    # Produces a copy of current SubscriptionsSet. This is needed, because original SubscriptionsSet object is
+    # dangerous to use - users may incidentally break its state.
+    # @return [PgEventstore::SubscriptionsSet, nil]
+    def read_only_subscriptions_set
+      @subscriptions_set&.dup
+    end
+
+    private
+
+    # Locks all Subscriptions behind the current SubscriptionsSet
+    # @return [void]
+    def lock_all
+      @runners.each { |runner| runner.lock!(subscriptions_set.id, @force_lock) }
+    end
+
+    # @return [void]
+    def unlock_all
+      @runners.each(&:unlock!)
+    end
+
+    # @return [PgEventstore::SubscriptionsSet]
+    def subscriptions_set
+      @subscriptions_set ||= SubscriptionsSet.using_connection(@config_name).
+        create(name: @set_name, max_restarts_number: @max_retries, time_between_restarts: @retries_interval)
+    end
+
+    # @return [PgEventstore::SubscriptionRunnersFeeder]
+    def feeder
+      SubscriptionRunnersFeeder.new(@config_name)
+    end
+
+    # @return [void]
+    def attach_runner_callbacks
+      @basic_runner.define_callback(:change_state, :after, method(:update_subscriptions_set_state))
+      @basic_runner.define_callback(:before_runner_started, :before, method(:before_runner_started))
+      @basic_runner.define_callback(:after_runner_died, :before, method(:after_runner_died))
+      @basic_runner.define_callback(:after_runner_died, :after, method(:restart_runner))
+      @basic_runner.define_callback(:process_async, :before, method(:process_async))
+      @basic_runner.define_callback(:after_runner_stopped, :before, method(:after_runner_stopped))
+      @basic_runner.define_callback(:before_runner_restored, :after, method(:update_runner_restarts))
+    end
+
+    # @return [void]
+    def before_runner_started
+      lock_all
+      @runners.each(&:start)
+      @commands_handler.start
+    end
+
+    # @param error [StandardError]
+    # @return [void]
+    def after_runner_died(error)
+      subscriptions_set.update(last_error: Utils.error_info(error), last_error_occurred_at: Time.now.utc)
+    end
+
+    # @param _error [StandardError]
+    # @return [void]
+    def restart_runner(_error)
+      return if subscriptions_set.restart_count >= subscriptions_set.max_restarts_number
+
+      Thread.new do
+        sleep subscriptions_set.time_between_restarts
+        restore
+      end
+    end
+
+    # @return [void]
+    def update_runner_restarts
+      subscriptions_set.update(last_restarted_at: Time.now.utc, restart_count: subscriptions_set.restart_count + 1)
+    end
+
+    # @return [void]
+    def process_async
+      feeder.feed(@runners)
+    end
+
+    # @return [void]
+    def after_runner_stopped
+      @commands_handler.stop
+      @subscriptions_set&.delete
+      @subscriptions_set = nil
+      @runners.each(&:stop_async).each(&:wait_for_finish)
+      unlock_all
+    end
+
+    # @return [void]
+    def update_subscriptions_set_state(state)
+      subscriptions_set.update(state: state)
+    end
+
+    # This method helps to ensure that no Subscription is added after SubscriptionFeeder's runner is working
+    # @return [void]
+    # @raise [RuntimeError]
+    def assert_proper_state!
+      return if @basic_runner.initial? || @basic_runner.stopped?
+
+      error_message = <<~TEXT
+        Could not add subscription - #{subscriptions_set.name}##{subscriptions_set.id} must be either in the initial \
+        or in the stopped state, but it is in the #{@basic_runner.state} state now.
+      TEXT
+      raise error_message
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/subscription_handler_performance.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+
+module PgEventstore
+  # This class measures the performance of Subscription's handler and returns the average time required to process an
+  # event.
+  # @!visibility private
+  class SubscriptionHandlerPerformance
+    extend Forwardable
+
+    TIMINGS_TO_KEEP = 100
+
+    def_delegators :@lock, :synchronize
+
+    def initialize
+      @lock = Thread::Mutex.new
+      @timings = []
+    end
+
+    # Yields the given block to measure its execution time
+    # @return [Object] the result of yielded block
+    def track_exec_time
+      result = nil
+      time = Benchmark.realtime { result = yield }
+      synchronize do
+        @timings.shift if @timings.size == TIMINGS_TO_KEEP
+        @timings.push(time)
+      end
+      result
+    end
+
+    # The average time required to process an event.
+    # @return [Float]
+    def average_event_processing_time
+      synchronize { @timings.size.zero? ? 0 : @timings.sum / @timings.size }
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/subscription_runner.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module PgEventstore
+  # This class connects Subscription and EventsProcessor. Its public API is directed on locking/unlocking related
+  # Subscription, starting/stopping/restarting EventsProcessor and calculating options(starting position, number of
+  # events to fetch, etc) for the events pulling query.
+  # @!visibility private
+  class SubscriptionRunner
+    extend Forwardable
+
+    MAX_EVENTS_PER_CHUNK = 1_000
+    INITIAL_EVENTS_PER_CHUNK = 10
+
+    attr_reader :subscription
+
+    def_delegators :@events_processor, :start, :stop, :stop_async, :feed, :wait_for_finish, :restore, :state, :running?
+    def_delegators :@subscription, :lock!, :unlock!, :id
+
+    # @param stats [PgEventstore::SubscriptionHandlerPerformance]
+    # @param events_processor [PgEventstore::EventsProcessor]
+    # @param subscription [PgEventstore::Subscription]
+    # @param restart_terminator [#call, nil]
+    def initialize(stats:, events_processor:, subscription:, restart_terminator: nil)
+      @stats = stats
+      @events_processor = events_processor
+      @subscription = subscription
+      @restart_terminator = restart_terminator
+
+      attach_callbacks
+    end
+
+    # @return [Hash]
+    def next_chunk_query_opts
+      @subscription.options.merge(from_position: next_chunk_global_position, max_count: estimate_events_number)
+    end
+
+    # @return [Boolean]
+    def time_to_feed?
+      @subscription.last_chunk_fed_at + @subscription.chunk_query_interval <= Time.now.utc
+    end
+
+    private
+
+    # @return [Integer]
+    def next_chunk_global_position
+      (
+        @subscription.last_chunk_greatest_position || @subscription.current_position ||
+          @subscription.options[:from_position] || 0
+      ) + 1
+    end
+
+    # @return [Integer]
+    def estimate_events_number
+      return INITIAL_EVENTS_PER_CHUNK if @stats.average_event_processing_time.zero?
+
+      events_per_chunk = @subscription.chunk_query_interval / @stats.average_event_processing_time
+      [events_per_chunk, MAX_EVENTS_PER_CHUNK].min - @events_processor.events_left_in_chunk
+    end
+
+    # @return [void]
+    def attach_callbacks
+      @events_processor.define_callback(:process, :around, method(:track_exec_time))
+      @events_processor.define_callback(:process, :after, method(:update_subscription_stats))
+      @events_processor.define_callback(:error, :after, method(:update_subscription_error))
+      @events_processor.define_callback(:error, :after, method(:restart_subscription))
+      @events_processor.define_callback(:feed, :after, method(:update_subscription_chunk_stats))
+      @events_processor.define_callback(:restart, :after, method(:update_subscription_restarts))
+      @events_processor.define_callback(:change_state, :after, method(:update_subscription_state))
+    end
+
+    # @param action [Proc]
+    # @return [void]
+    def track_exec_time(action, *)
+      @stats.track_exec_time { action.call }
+    end
+
+    # @param current_position [Integer]
+    # @return [void]
+    def update_subscription_stats(current_position)
+      @subscription.update(
+        average_event_processing_time: @stats.average_event_processing_time,
+        current_position: current_position,
+        total_processed_events: @subscription.total_processed_events + 1
+      )
+    end
+
+    # @param state [String]
+    # @return [void]
+    def update_subscription_state(state)
+      @subscription.update(state: state)
+    end
+
+    # @return [void]
+    def update_subscription_restarts
+      @subscription.update(last_restarted_at: Time.now.utc, restart_count: @subscription.restart_count + 1)
+    end
+
+    # @param error [StandardError]
+    # @return [void]
+    def update_subscription_error(error)
+      @subscription.update(last_error: Utils.error_info(error), last_error_occurred_at: Time.now.utc)
+    end
+
+    # @param global_position [Integer, nil]
+    # @return [void]
+    def update_subscription_chunk_stats(global_position)
+      global_position ||= @subscription.last_chunk_greatest_position
+      @subscription.update(last_chunk_fed_at: Time.now.utc, last_chunk_greatest_position: global_position)
+    end
+
+    # @param _error [StandardError]
+    # @return [void]
+    def restart_subscription(_error)
+      return if @restart_terminator&.call(@subscription.dup)
+      return if @subscription.restart_count >= @subscription.max_restarts_number
+
+      Thread.new do
+        sleep @subscription.time_between_restarts
+        restore
+      end
+    end
+  end
+end

data/lib/pg_eventstore/subscriptions/subscription_runners_feeder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # This class pulls events from db and feeds given SubscriptionRunners
+  # @!visibility private
+  class SubscriptionRunnersFeeder
+    # @param config_name [Symbol]
+    def initialize(config_name)
+      @config_name = config_name
+    end
+
+    # @param runners [Array<PgEventstore::SubscriptionRunner>]
+    # @return [void]
+    def feed(runners)
+      runners = runners.select(&:running?).select(&:time_to_feed?)
+      return if runners.empty?
+
+      runners_query_options = runners.map { |runner| [runner.id, runner.next_chunk_query_opts] }
+      raw_events = subscription_queries.subscriptions_events(runners_query_options)
+      grouped_events = raw_events.group_by { |attrs| attrs['runner_id'] }
+      runners.each do |runner|
+        runner.feed(grouped_events[runner.id]) if grouped_events[runner.id]
+      end
+    end
+
+    private
+
+    # @return [PgEventstore::Connection]
+    def connection
+      PgEventstore.connection(@config_name)
+    end
+
+    # @return [PgEventstore::SubscriptionQueries]
+    def subscription_queries
+      SubscriptionQueries.new(connection)
+    end
+  end
+end