pg_eventstore 0.3.0 → 0.5.0

data/lib/pg_eventstore/callbacks.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # Allows you to define before, around and after callbacks withing the certain action. It is especially useful during
+  # asynchronous programming when you need to be able to react on asynchronous actions from the outside.
+  # Example:
+  #   class MyAwesomeClass
+  #     attr_reader :callbacks
+  #
+  #     def initialize
+  #       @callbacks = PgEventstore::Callbacks.new
+  #     end
+  #
+  #     def do_something
+  #       Thread.new do
+  #         @callbacks.run_callbacks(:something_happened) do
+  #           puts "I did something useful!"
+  #         end
+  #       end
+  #     end
+  #
+  #     def do_something_else
+  #       @callbacks.run_callbacks(:something_else_happened, :foo, bar: :baz) do
+  #         puts "Something else happened!"
+  #       end
+  #     end
+  #   end
+  #
+  #   obj = MyAwesomeClass.new
+  #   obj.callbacks.define_callback(:something_happened, :before, proc { puts "In before callback" })
+  #   obj.callbacks.define_callback(:something_happened, :after, proc { puts "In after callback" })
+  #   obj.callbacks.define_callback(
+  #     :something_happened, :around,
+  #     proc { |action| puts "In around before action"; action.call; puts "In around after action" }
+  #   )
+  #   obj.do_something
+  # Outputs:
+  #   In before callback
+  #   In around callback before action
+  #   I did something useful!
+  #   In around callback after action
+  #   In after callback
+  # Please note, that it is important to call *action.call* in around callback. Otherwise action simply won't be called.
+  #
+  # Optionally you can provide any set of arguments to {#run_callbacks} method. They will be passed to your callbacks
+  # functions then. Example:
+  #
+  #   obj = MyAwesomeClass.new
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :before,
+  #     proc { |*args, **kwargs| puts "In before callback. Args: #{args}, kwargs: #{kwargs}." }
+  #   )
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :after,
+  #     proc { |*args, **kwargs| puts "In after callback. Args: #{args}, kwargs: #{kwargs}." }
+  #   )
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :around,
+  #     proc { |action, *args, **kwargs|
+  #       puts "In around before action. Args: #{args}, kwargs: #{kwargs}."
+  #       action.call
+  #       puts "In around after action. Args: #{args}, kwargs: #{kwargs}."
+  #     }
+  #   )
+  #   obj.do_something_else
+  # Outputs:
+  #   In before callback. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   In around before action. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   I did something useful!
+  #   In around after action. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   In after callback. Args: [:foo], kwargs: {:bar=>:baz}.
+  class Callbacks
+    def initialize
+      @callbacks = {}
+    end
+
+    # @param action [Object] an object, that represents your action. In most cases you want to use a symbol there
+    # @param filter [Symbol] callback filter. Supported values are :before, :after and :around
+    # @param callback [#call]
+    # @return [void]
+    def define_callback(action, filter, callback)
+      @callbacks[action] ||= {}
+      @callbacks[action][filter] ||= []
+      @callbacks[action][filter].push(callback)
+    end
+
+    # @param action [Object] an action to run
+    # @return [Object] the result of passed block
+    def run_callbacks(action, *args, **kwargs, &blk)
+      return (yield if block_given?) unless @callbacks[action]
+
+      run_before_callbacks(action, *args, **kwargs)
+      result = run_around_callbacks(action, *args, **kwargs, &blk)
+      run_after_callbacks(action, *args, **kwargs)
+      result
+    end
+
+    private
+
+    def run_before_callbacks(action, *args, **kwargs)
+      @callbacks[action][:before]&.each do |callback|
+        callback.call(*args, **kwargs)
+      end
+    end
+
+    def run_around_callbacks(action, *args, **kwargs, &blk)
+      result = nil
+      stack = [proc { result = yield if block_given? }]
+      @callbacks[action][:around]&.reverse_each&.with_index do |callback, index|
+        stack.push(proc { callback.call(stack[index], *args, **kwargs); result })
+      end
+      stack.last.call(*args, **kwargs)
+      result
+    end
+
+    def run_after_callbacks(action, *args, **kwargs)
+      @callbacks[action][:after]&.each do |callback|
+        callback.call(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/client.rb

@@ -2,7 +2,7 @@
 
 require_relative 'commands'
 require_relative 'event_serializer'
-require_relative 'pg_result_deserializer'
+require_relative 'event_deserializer'
 require_relative 'queries'
 
 module PgEventstore
@@ -109,6 +109,36 @@ module PgEventstore
         call(stream, options: { max_count: config.max_count }.merge(options))
     end
 
+    # @see {#read} for available params
+    # @return [Enumerator] enumerator will yield PgEventstore::Event
+    def read_paginated(stream, options: {}, middlewares: nil)
+      cmd_class = stream.system? ? Commands::SystemStreamReadPaginated : Commands::RegularStreamReadPaginated
+      cmd_class.
+        new(Queries.new(streams: stream_queries, events: event_queries(middlewares(middlewares)))).
+        call(stream, options: { max_count: config.max_count }.merge(options))
+    end
+
+    # Links event from one stream into another stream. You can later access it by providing :resolve_link_tos option
+    # when reading from a stream. Only existing events can be linked.
+    # @param stream [PgEventstore::Stream]
+    # @param events_or_event [PgEventstore::Event, Array<PgEventstore::Event>]
+    # @param options [Hash]
+    # @option options [Integer] :expected_revision provide your own revision number
+    # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+    # @param middlewares [Array] provide a list of middleware names to use. Defaults to empty array, meaning no
+    #   middlewares will be applied to the "link" event
+    # @return [PgEventstore::Event, Array<PgEventstore::Event>] persisted event(s)
+    # @raise [PgEventstore::WrongExpectedRevisionError]
+    def link_to(stream, events_or_event, options: {}, middlewares: [])
+      result =
+        Commands::LinkTo.new(
+          Queries.new(
+            streams: stream_queries, events: event_queries(middlewares(middlewares)), transactions: transaction_queries
+          )
+        ).call(stream, *events_or_event, options: options)
+      events_or_event.is_a?(Array) ? result : result.first
+    end
+
     private
 
     # @param middlewares [Array, nil]
@@ -140,7 +170,7 @@ module PgEventstore
       EventQueries.new(
         connection,
         EventSerializer.new(middlewares),
-        PgResultDeserializer.new(middlewares, config.event_class_resolver)
+        EventDeserializer.new(middlewares, config.event_class_resolver)
       )
     end
   end

data/lib/pg_eventstore/commands/append.rb

@@ -9,9 +9,10 @@ module PgEventstore
       # @param options [Hash]
       # @option options [Integer] :expected_revision provide your own revision number
       # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+      # @param event_modifier [#call]
       # @return [Array<PgEventstore::Event>] persisted events
       # @raise [PgEventstore::WrongExpectedRevisionError]
-      def call(stream, *events, options: {})
+      def call(stream, *events, options: {}, event_modifier: EventModifiers::PrepareRegularEvent)
         raise SystemStreamError, stream if stream.system?
 
         queries.transactions.transaction do
@@ -19,7 +20,7 @@ module PgEventstore
           revision = stream.stream_revision
           assert_expected_revision!(revision, options[:expected_revision]) if options[:expected_revision]
           events.map.with_index(1) do |event, index|
-            queries.events.insert(stream, prepared_event(event, revision + index))
+            queries.events.insert(stream, event_modifier.call(event, revision + index))
           end.tap do
             queries.streams.update_stream_revision(stream, revision + events.size)
           end
@@ -28,15 +29,6 @@ module PgEventstore
 
       private
 
-      # @param event [PgEventstore::Event]
-      # @param revision [Integer]
-      # @return [PgEventstore::Event]
-      def prepared_event(event, revision)
-        event.class.new(
-          id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
-        )
-      end
-
       # @param revision [Integer]
       # @param expected_revision [Symbol, Integer]
       # @raise [PgEventstore::WrongExpectedRevisionError] in case if revision does not satisfy expected revision

data/lib/pg_eventstore/commands/event_modifiers/prepare_link_event.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    module EventModifiers
+      # Defines how to transform regular event into a link event
+      # @!visibility private
+      class PrepareLinkEvent
+        class << self
+          # @param event [PgEventstore::Event]
+          # @param revision [Integer]
+          # @return [PgEventstore::Event]
+          def call(event, revision)
+            Event.new(link_id: event.id, type: Event::LINK_TYPE, stream_revision: revision).tap do |e|
+              %i[link_id type stream_revision].each { |attr| e.readonly!(attr) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/event_modifiers/prepare_regular_event.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    module EventModifiers
+      # Defines how to transform regular event before appending it to the stream
+      # @!visibility private
+      class PrepareRegularEvent
+        class << self
+          # @param event [PgEventstore::Event]
+          # @param revision [Integer]
+          # @return [PgEventstore::Event]
+          def call(event, revision)
+            event.class.new(
+              id: event.id, data: event.data, metadata: event.metadata, type: event.type, stream_revision: revision
+            ).tap do |e|
+              %i[link_id stream_revision].each { |attr| e.readonly!(attr) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/link_to.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class LinkTo < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param events [Array<PgEventstore::Event>]
+      # @param options [Hash]
+      # @option options [Integer] :expected_revision provide your own revision number
+      # @option options [Symbol] :expected_revision provide one of next values: :any, :no_stream or :stream_exists
+      # @return [Array<PgEventstore::Event>] persisted events
+      # @raise [PgEventstore::WrongExpectedRevisionError]
+      # @raise [PgEventstore::NotPersistedEventError]
+      def call(stream, *events, options: {})
+        events.each(&method(:check_id_presence))
+        append_cmd = Append.new(queries)
+        append_cmd.call(stream, *events, options: options, event_modifier: EventModifiers::PrepareLinkEvent)
+      end
+
+      private
+
+      # Checks if Event#id is present. An event must have the #id value in order to be linked.
+      # @param event [PgEventstore::Event]
+      # @return [void]
+      def check_id_presence(event)
+        return unless event.id.nil?
+
+        raise NotPersistedEventError, event
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/regular_stream_read_paginated.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class RegularStreamReadPaginated < AbstractCommand
+      # @see PgEventstore::Commands::Read for docs
+      def call(stream, options: {})
+        revision = calc_initial_revision(stream, options)
+        Enumerator.new do |yielder|
+          loop do
+            events = read_cmd.call(stream, options: options.merge(from_revision: revision))
+            yielder << events if events.any?
+            raise StopIteration if end_reached?(events, options[:max_count])
+
+            revision = calc_next_revision(events, revision, options[:direction])
+            raise StopIteration if revision.negative?
+          end
+        end
+      end
+
+      private
+
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash]
+      # @return [Integer]
+      def calc_initial_revision(stream, options)
+        return options[:from_revision] if options[:from_revision]
+        return 0 if forwards?(options[:direction])
+
+        read_cmd.call(stream, options: options.merge(max_count: 1)).first.stream_revision
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param max_count [Integer]
+      # @return [Boolean]
+      def end_reached?(events, max_count)
+        events.size < max_count
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param revision [Integer]
+      # @param direction [String, Symbol, nil]
+      # @return [Integer]
+      def calc_next_revision(events, revision, direction)
+        return revision + events.size if forwards?(direction)
+
+        revision - events.size
+      end
+
+      # @param direction [String, Symbol, nil]
+      # @return [Boolean]
+      def forwards?(direction)
+        QueryBuilders::EventsFiltering::SQL_DIRECTIONS[direction] == QueryBuilders::EventsFiltering::SQL_DIRECTIONS[:asc]
+      end
+
+      # @return [PgEventstore::Commands::Read]
+      def read_cmd
+        @read_cmd ||= Read.new(queries)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/system_stream_read_paginated.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class SystemStreamReadPaginated < AbstractCommand
+      # @see PgEventstore::Commands::Read for docs
+      def call(stream, options: {})
+        position = calc_initial_position(stream, options)
+        Enumerator.new do |yielder|
+          loop do
+            events = read_cmd.call(stream, options: options.merge(from_position: position))
+            yielder << events if events.any?
+            raise StopIteration if end_reached?(events, options[:max_count])
+
+            position = calc_next_position(events, options[:direction])
+            raise StopIteration if position <= 0
+          end
+        end
+      end
+
+      private
+
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash]
+      # @return [Integer]
+      def calc_initial_position(stream, options)
+        return options[:from_position] if options[:from_position]
+        return 1 if forwards?(options[:direction])
+
+        read_cmd.call(stream, options: options.merge(max_count: 1)).first.global_position
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param max_count [Integer]
+      # @return [Boolean]
+      def end_reached?(events, max_count)
+        events.size < max_count
+      end
+
+      # @param events [Array<PgEventstore::Event>]
+      # @param direction [String, Symbol, nil]
+      # @return [Integer]
+      def calc_next_position(events, direction)
+        return events.last.global_position + 1 if forwards?(direction)
+
+        events.last.global_position - 1
+      end
+
+      # @param direction [String, Symbol, nil]
+      # @return [Boolean]
+      def forwards?(direction)
+        QueryBuilders::EventsFiltering::SQL_DIRECTIONS[direction] == QueryBuilders::EventsFiltering::SQL_DIRECTIONS[:asc]
+      end
+
+      # @return [PgEventstore::Commands::Read]
+      def read_cmd
+        @read_cmd ||= Read.new(queries)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative 'abstract_command'
+require_relative 'commands/event_modifiers/prepare_link_event'
+require_relative 'commands/event_modifiers/prepare_regular_event'
 require_relative 'commands/append'
 require_relative 'commands/read'
+require_relative 'commands/regular_stream_read_paginated'
+require_relative 'commands/system_stream_read_paginated'
 require_relative 'commands/multiple'
+require_relative 'commands/link_to'

data/lib/pg_eventstore/config.rb

@@ -6,14 +6,46 @@ module PgEventstore
 
     attr_reader :name
 
-    # PostgreSQL connection URI docs https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
+    # @!attribute pg_uri
+    #   @return [String] PostgreSQL connection URI docs
+    #     https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
     option(:pg_uri) { 'postgresql://postgres:postgres@localhost:5432/eventstore' }
+    # @!attribute max_count
+    #   @return [Integer] Number of events to return in one response when reading from a stream
     option(:max_count) { 1000 }
+    # @!attribute middlewares
+    #   @return [Hash{Symbol => <#serialize, #deserialize>}] A set of identified(by key) objects that respond to
+    #     #serialize and #deserialize
     option(:middlewares) { {} }
-    # Object that responds to #call. Should accept a string and return a class
+    # @!attribute event_class_resolver
+    #   @return [#call] A callable object that must accept a string and return a class. It is used when resolving
+    #     event's class during event's deserialization process
     option(:event_class_resolver) { EventClassResolver.new }
+    # @!attribute connection_pool_size
+    #   @return [Integer] Max number of connections per ruby process
     option(:connection_pool_size) { 5 }
-    option(:connection_pool_timeout) { 5 } # seconds
+    # @!attribute connection_pool_timeout
+    #   @return [Integer] Time in seconds to wait for the connection in pool to be released
+    option(:connection_pool_timeout) { 5 }
+    # @!attribute subscription_pull_interval
+    #   @return [Integer] How often Subscription should pull new events
+    option(:subscription_pull_interval) { 2 }
+    # @!attribute subscription_max_retries
+    #   @return [Integer] max number of retries of failed Subscription
+    option(:subscription_max_retries) { 100 }
+    # @!attribute subscription_retries_interval
+    #   @return [Integer] interval in seconds between retries of failed Subscription
+    option(:subscription_retries_interval) { 1 }
+    # @!attribute subscription_restart_terminator
+    #   @return [#call, nil] provide callable object that accepts Subscription object to decide whether to prevent
+    #     further Subscription restarts
+    option(:subscription_restart_terminator)
+    # @!attribute subscriptions_set_max_retries
+    #   @return [Integer] max number of retries of failed SubscriptionsSet
+    option(:subscriptions_set_max_retries) { 10 }
+    # @!attribute subscriptions_set_retries_interval
+    #   @return [Integer] interval in seconds between retries of failed SubscriptionsSet
+    option(:subscriptions_set_retries_interval) { 1 }
 
     # @param name [Symbol] config's name. Its value matches the appropriate key in PgEventstore.config hash
     def initialize(name:, **options)

data/lib/pg_eventstore/errors.rb

@@ -104,4 +104,84 @@ module PgEventstore
       TEXT
     end
   end
+
+  class RecordNotFound < Error
+    attr_reader :table_name, :id
+
+    # @param table_name [String]
+    # @param id [Integer, String]
+    def initialize(table_name, id)
+      @table_name = table_name
+      @id = id
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      "Could not find/update #{table_name.inspect} record with #{id.inspect} id."
+    end
+  end
+
+  class SubscriptionAlreadyLockedError < Error
+    attr_reader :set, :name, :lock_id
+
+    # @param set [String] subscriptions set name
+    # @param name [String] subscription's name
+    # @param lock_id [String] UUIDv4
+    def initialize(set, name, lock_id)
+      @set = set
+      @name = name
+      @lock_id = lock_id
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT.strip
+        Could not lock subscription from #{set.inspect} set with #{name.inspect} name. It is already locked by \
+        #{lock_id.inspect} set.
+      TEXT
+    end
+  end
+
+  class SubscriptionUnlockError < Error
+    attr_reader :set, :name, :expected_locked_by, :actual_locked_by
+
+    # @param set [String] subscription's set name
+    # @param name [String] subscription's name
+    # @param expected_locked_by [String] UUIDv4
+    # @param actual_locked_by [String, nil] UUIDv4
+    def initialize(set, name, expected_locked_by, actual_locked_by)
+      @set = set
+      @name = name
+      @expected_locked_by = expected_locked_by
+      @actual_locked_by = actual_locked_by
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT.strip
+        Failed to unlock subscription from #{set.inspect} set with #{name.inspect} name by \
+        #{expected_locked_by.inspect} lock id. It is currently locked by #{actual_locked_by.inspect} lock id.
+      TEXT
+    end
+  end
+
+  class NotPersistedEventError < Error
+    attr_reader :event
+
+    # @param event [PgEventstore::Event]
+    def initialize(event)
+      @event = event
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT.strip
+        Event#id must be present, got #{event.id.inspect} instead.
+      TEXT
+    end
+  end
 end

data/lib/pg_eventstore/{pg_result_deserializer.rb → event_deserializer.rb}

@@ -2,7 +2,7 @@
 
 module PgEventstore
   # @!visibility private
-  class PgResultDeserializer
+  class EventDeserializer
     attr_reader :middlewares, :event_class_resolver
 
     # @param middlewares [Array<Object<#deserialize, #serialize>>]
@@ -12,31 +12,14 @@ module PgEventstore
       @event_class_resolver = event_class_resolver
     end
 
-    # @param pg_result [PG::Result]
-    # @return [Array<PgEventstore::Event>]
-    def deserialize(pg_result)
-      pg_result.map(&method(:_deserialize))
+    # @param raw_events [Array<Hash>]
+    def deserialize_many(raw_events)
+      raw_events.map(&method(:deserialize))
     end
-    alias deserialize_many deserialize
-
-    # @param pg_result [PG::Result]
-    # @return [PgEventstore::Event, nil]
-    def deserialize_one(pg_result)
-      return if pg_result.ntuples.zero?
-
-      _deserialize(pg_result.first)
-    end
-
-    # @return [PgEventstore::PgResultDeserializer]
-    def without_middlewares
-      self.class.new([], event_class_resolver)
-    end
-
-    private
 
     # @param attrs [Hash]
     # @return [PgEventstore::Event]
-    def _deserialize(attrs)
+    def deserialize(attrs)
       event = event_class_resolver.call(attrs['type']).new(**attrs.transform_keys(&:to_sym))
       middlewares.each do |middleware|
         middleware.deserialize(event)
@@ -44,5 +27,10 @@ module PgEventstore
       event.stream = PgEventstore::Stream.new(**attrs['stream'].transform_keys(&:to_sym)) if attrs.key?('stream')
       event
     end
+
+    # @return [PgEventstore::EventDeserializer]
+    def without_middlewares
+      self.class.new([], event_class_resolver)
+    end
   end
 end