pg_eventstore 1.1.3 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d389d47246c77539e8cd138d22082f8b3186b0e422e563510483e85189a5f68
-  data.tar.gz: 0cf5820ee9979d7ef0f3385848e105c7b378bfcac1f756ed5a1242ea572f2ea1
+  metadata.gz: 5fce9f1f61310bfc9c12afdb89b0a6589e9116133255eeb62ac406b24e351b72
+  data.tar.gz: 0a03a441f9e26a040f026fc7fac5d034c81b91d6f0e0bee98646b39a2f809147
 SHA512:
-  metadata.gz: e7e932435f9c6711af44a69e22fc8d4cbc2ce41f7f1cc1c1c43d269203d7d784076ace2af3d7296662ca8ab4b907df8a8692bf769d635c2d94a53a0b97df4b62
-  data.tar.gz: 745fd65a4c63290804765ceb96d2d3cacce3d2d5d0fecf4410fe962499fc948424734a1aa62a89d167af90afef6c3001808ae46102c04d4cfc6180ddd5bbcdd5
+  metadata.gz: 26a0a9b9cf70e32fd73d5f729d5d9654ec23cd90aa57a3bfdf4cae5603f58d56d62a1406df477200390497141e5c4bb89f157c749bd1df680c1b404898428094
+  data.tar.gz: 85aeeffcfc9ddfba2733e7362958a9d1528eb043ae5025c2d8bd055aa708e5c20eb2fef555be711174f3c058235c0f5b97c780b9f68b3a52e92592fe58d8f8c3

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.1.5]
+- Review the way to handle SubscriptionAlreadyLockedError error. This removes noise when attempting to lock an already locked subscription. 
+
+## [1.1.4]
+- Add rbs signatures
+
 ## [1.1.3]
 - Fix issue with assets caching between different gem's versions
 

data/README.md

@@ -53,10 +53,11 @@ Documentation chapters:
 
 After checking out the repo, run:
 - `bundle` to install dependencies
-- `docker-compose up` to start dev/test services
-- `bin/setup_db` to create/re-create development and test databases, tables and related objects 
+- `docker compose up` to start dev/test services
+- `bin/setup_db` to create/re-create development and test databases, tables and related objects
+- `bundle exec rbs collection install` to install external rbs definitions
 
-Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Then, run `bin/rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/docs/subscriptions.md

@@ -47,9 +47,23 @@ After you added all necessary subscriptions, it is time to start them:
 
 ```ruby
 subscriptions_manager.start
+# => PgEventstore::BasicRunner
 ```
 
-After calling `#start` all subscriptions are locked behind the given subscription set and can't be locked by any other subscription set. This measure is needed to prevent running the same subscription under the same subscription set using different processes/subscription managers. Such situation will lead to a malformed subscription state and will break its position, meaning the same event will be processed several times.
+After calling `#start` all subscriptions are locked behind the given subscriptions set and can't be locked by any other subscriptions set. This measure is needed to prevent running the same subscription under the same subscription set using different processes/subscription managers. Such situation will lead to a malformed subscription state and will break its position, meaning the same event will be processed several times. In real world the lock attempt may still happen. This can be common scenario when using kubernetes which rolls out new deployment before shutting down old one. In this case `#start` will return `nil`. You can use this behavior to properly handle such cases. Example:
+
+```ruby
+timeout = 20 # 20 seconds
+deadline = Time.now + timeout
+loop do
+  break if subscriptions_manager.start
+  if Time.now > deadline
+    puts "Failed to acquire subscriptions lock within #{timeout} seconds. Exiting now."
+    exit
+  end
+  sleep 2
+end
+```
 
 To "unlock" the subscription you should gracefully stop the subscription manager:
 
@@ -86,7 +100,16 @@ subscriptions_manager.subscribe(
   }
 )
 subscriptions_manager.force_lock! if ENV['FORCE_LOCK'] == 'true'
-subscriptions_manager.start
+timeout = 20 # 20 seconds
+deadline = Time.now + timeout
+loop do
+  break if subscriptions_manager.start
+  if Time.now > deadline
+    puts "Failed to acquire subscriptions lock within #{timeout} seconds. Exiting now."
+    exit
+  end
+  sleep 2
+end
 
 Kernel.trap('TERM') do
   puts "Received TERM signal. Stopping Subscriptions Manager and exiting..."

data/lib/pg_eventstore/abstract_command.rb

@@ -3,6 +3,8 @@
 module PgEventstore
   # @!visibility private
   class AbstractCommand
+    # @!attribute queries
+    #   @return [PgEventstore::Queries]
     attr_reader :queries
     private :queries
 

data/lib/pg_eventstore/callbacks.rb

@@ -97,12 +97,14 @@ module PgEventstore
 
     private
 
+    # @return [void]
     def run_before_callbacks(action, *args, **kwargs)
       @callbacks[action][:before]&.each do |callback|
         callback.call(*args, **kwargs)
       end
     end
 
+    # @return [Object] the result of the passed block
     def run_around_callbacks(action, *args, **kwargs, &blk)
       result = nil
       stack = [proc { result = yield if block_given? }]
@@ -113,6 +115,7 @@ module PgEventstore
       result
     end
 
+    # @return [void]
     def run_after_callbacks(action, *args, **kwargs)
       @callbacks[action][:after]&.each do |callback|
         callback.call(*args, **kwargs)

data/lib/pg_eventstore/client.rb

@@ -7,6 +7,8 @@ require_relative 'queries'
 
 module PgEventstore
   class Client
+    # @!attribute config
+    #   @return [PgEventstore::Config]
     attr_reader :config
     private :config
 
@@ -111,7 +113,10 @@ module PgEventstore
         call(stream, options: { max_count: config.max_count }.merge(options))
     end
 
-    # @see {#read} for available params
+    # @see {#read} for the detailed docs
+    # @param stream [PgEventstore::Stream]
+    # @param options [Hash] request options
+    # @param middlewares [Array, nil]
     # @return [Enumerator] enumerator will yield PgEventstore::Event
     def read_paginated(stream, options: {}, middlewares: nil)
       cmd_class = stream.system? ? Commands::SystemStreamReadPaginated : Commands::RegularStreamReadPaginated

data/lib/pg_eventstore/config.rb

@@ -30,7 +30,7 @@ module PgEventstore
     #   @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 [Float] How often Subscription should pull new events, seconds
+    #   @return [Float, Integer] How often Subscription should pull new events, seconds
     option(:subscription_pull_interval) { 1.0 }
     # @!attribute subscription_max_retries
     #   @return [Integer] max number of retries of failed Subscription

data/lib/pg_eventstore/connection.rb

@@ -38,7 +38,15 @@ module PgEventstore
       end
     end
 
-    attr_reader :uri, :pool_size, :pool_timeout
+    # @!attribute uri
+    #   @return [String]
+    attr_reader :uri
+    # @!attribute pool_size
+    #   @return [Integer]
+    attr_reader :pool_size
+    # @!attribute pool_timeout
+    #   @return [Integer]
+    attr_reader :pool_timeout
     private :uri, :pool_size, :pool_timeout
 
     # @param uri [String] PostgreSQL connection URI.

data/lib/pg_eventstore/errors.rb

@@ -22,6 +22,8 @@ module PgEventstore
   end
 
   class StreamNotFoundError < Error
+    # @!attribute stream
+    #   @return [PgEventstore::Stream]
     attr_reader :stream
 
     # @param stream [PgEventstore::Stream]
@@ -32,6 +34,8 @@ module PgEventstore
   end
 
   class SystemStreamError < Error
+    # @!attribute stream
+    #   @return [PgEventstore::Stream]
     attr_reader :stream
 
     # @param stream [PgEventstore::Stream]
@@ -42,7 +46,15 @@ module PgEventstore
   end
 
   class WrongExpectedRevisionError < Error
-    attr_reader :stream, :revision, :expected_revision
+    # @!attribute stream
+    #   @return [PgEventstore::Stream]
+    attr_reader :stream
+    # @!attribute revision
+    #   @return [Integer]
+    attr_reader :revision
+    # @!attribute expected_revision
+    #   @return [Integer, Symbol]
+    attr_reader :expected_revision
 
     # @param revision [Integer]
     # @param expected_revision [Integer, Symbol]
@@ -96,29 +108,13 @@ module PgEventstore
     end
   end
 
-  class StreamDeletionError < Error
-    attr_reader :stream_name, :details
-
-    # @param stream_name [String]
-    # @param details [String]
-    def initialize(stream_name, details:)
-      @stream_name = stream_name
-      @details = details
-      super(user_friendly_message)
-    end
-
-    # @return [String]
-    def user_friendly_message
-      <<~TEXT.strip
-        Could not delete #{stream_name.inspect} stream. It seems that a stream with that \
-        name does not exist, has already been deleted or its state does not match the \
-        provided :expected_revision option. Please check #details for more info.
-      TEXT
-    end
-  end
-
   class RecordNotFound < Error
-    attr_reader :table_name, :id
+    # @!attribute table_name
+    #   @return [String]
+    attr_reader :table_name
+    # @!attribute id
+    #   @return [Integer, String]
+    attr_reader :id
 
     # @param table_name [String]
     # @param id [Integer, String]
@@ -135,7 +131,15 @@ module PgEventstore
   end
 
   class SubscriptionAlreadyLockedError < Error
-    attr_reader :set, :name, :lock_id
+    # @!attribute set
+    #   @return [String]
+    attr_reader :set
+    # @!attribute name
+    #   @return [String]
+    attr_reader :name
+    # @!attribute lock_id
+    #   @return [Integer]
+    attr_reader :lock_id
 
     # @param set [String] subscriptions set name
     # @param name [String] subscription's name
@@ -157,7 +161,15 @@ module PgEventstore
   end
 
   class WrongLockIdError < Error
-    attr_reader :set, :name, :lock_id
+    # @!attribute set
+    #   @return [String]
+    attr_reader :set
+    # @!attribute name
+    #   @return [String]
+    attr_reader :name
+    # @!attribute lock_id
+    #   @return [Integer]
+    attr_reader :lock_id
 
     # @param set [String] subscriptions set name
     # @param name [String] subscription's name
@@ -179,6 +191,8 @@ module PgEventstore
   end
 
   class NotPersistedEventError < Error
+    # @!attribute event
+    #   @return [PgEventstore::Event]
     attr_reader :event
 
     # @param event [PgEventstore::Event]
@@ -194,7 +208,12 @@ module PgEventstore
   end
 
   class MissingPartitions < Error
-    attr_reader :stream, :event_types
+    # @!attribute stream
+    #   @return [PgEventstore::Stream]
+    attr_reader :stream
+    # @!attribute event_types
+    #   @return [Array<String>]
+    attr_reader :event_types
 
     # @param stream [PgEventstore::Stream]
     # @param event_types [Array<String>]

data/lib/pg_eventstore/event.rb

@@ -4,6 +4,7 @@ module PgEventstore
   class Event
     include Extensions::OptionsExtension
 
+    # @return [String] a type of link event
     LINK_TYPE = '$>'
 
     # @!attribute id
@@ -44,7 +45,7 @@ module PgEventstore
     attribute(:created_at)
 
     # Implements comparison of `PgEventstore::Event`-s. Two events matches if all of their attributes matches
-    # @param other [Object, EventStoreClient::DeserializedEvent]
+    # @param other [Object, PgEventstore::Event]
     # @return [Boolean]
     def ==(other)
       return false unless other.is_a?(PgEventstore::Event)

data/lib/pg_eventstore/event_class_resolver.rb

@@ -2,7 +2,7 @@
 
 module PgEventstore
   class EventClassResolver
-    # @param event_type [String]
+    # @param event_type [String, nil]
     # @return [Class]
     def call(event_type)
       Object.const_get(event_type)

data/lib/pg_eventstore/event_deserializer.rb

@@ -3,7 +3,12 @@
 module PgEventstore
   # @!visibility private
   class EventDeserializer
-    attr_reader :middlewares, :event_class_resolver
+    # @!attribute middlewares
+    #   @return [Array<#deserialize, #serialize>]
+    attr_reader :middlewares
+    # @!attribute event_class_resolver
+    #   @return [#call]
+    attr_reader :event_class_resolver
 
     # @param middlewares [Array<Object<#deserialize, #serialize>>]
     # @param event_class_resolver [#call]
@@ -13,6 +18,7 @@ module PgEventstore
     end
 
     # @param raw_events [Array<Hash>]
+    # @return [Array<PgEventstore::Event>]
     def deserialize_many(raw_events)
       raw_events.map(&method(:deserialize))
     end
@@ -20,7 +26,7 @@ module PgEventstore
     # @param attrs [Hash]
     # @return [PgEventstore::Event]
     def deserialize(attrs)
-      event = event_class_resolver.call(attrs['type']).new(**attrs.transform_keys(&:to_sym))
+      event = event_class_resolver.call(attrs['type']).new(**attrs.except('link').transform_keys(&:to_sym))
       middlewares.each do |middleware|
         middleware.deserialize(event)
       end

data/lib/pg_eventstore/event_serializer.rb

@@ -3,6 +3,8 @@
 module PgEventstore
   # @!visibility private
   class EventSerializer
+    # @!attribute middlewares
+    #   @return [Array<#deserialize, #serialize>]
     attr_reader :middlewares
 
     # @param middlewares [Array<#deserialize, #serialize>]

data/lib/pg_eventstore/extensions/callbacks_extension.rb

@@ -52,6 +52,7 @@ module PgEventstore
         end
       end
 
+      # @return [void]
       def define_callback(...)
         callbacks.define_callback(...)
       end

data/lib/pg_eventstore/extensions/options_extension.rb

@@ -81,7 +81,8 @@ module PgEventstore
         end
       end
 
-      ReadonlyAttributeError = Class.new(StandardError)
+      class ReadonlyAttributeError < StandardError
+      end
 
       def self.included(klass)
         klass.singleton_class.attr_accessor(:options)
@@ -122,6 +123,7 @@ module PgEventstore
       private
 
       # @param opt_name [Symbol]
+      # @return [void]
       # @raise [PgEventstore::Extensions::OptionsExtension::ReadOnlyError]
       def readonly_error(opt_name)
         raise(

data/lib/pg_eventstore/queries/event_queries.rb

@@ -3,7 +3,15 @@
 module PgEventstore
   # @!visibility private
   class EventQueries
-    attr_reader :connection, :serializer, :deserializer
+    # @!attribute connection
+    #   @return [PgEventstore::Connection]
+    attr_reader :connection
+    # @!attribute serializer
+    #   @return [PgEventstore::EventSerializer]
+    attr_reader :serializer
+    # @!attribute deserializer
+    #   @return [PgEventstore::EventDeserializer]
+    attr_reader :deserializer
     private :connection, :serializer, :deserializer
 
     # @param connection [PgEventstore::Connection]
@@ -32,7 +40,7 @@ module PgEventstore
     # Takes an array of potentially persisted events and loads their ids from db. Those ids can be later used to check
     # whether events are actually existing events.
     # @param events [Array<PgEventstore::Event>]
-    # @return [Array<Integer>]
+    # @return [Array<String>]
     def ids_from_db(events)
       sql_builder = SQLBuilder.new.from('events').select('id')
       partition_attrs = events.map { |event| [event.stream&.context, event.stream&.stream_name, event.type] }.uniq
@@ -72,7 +80,7 @@ module PgEventstore
 
     # @param stream [PgEventstore::Stream]
     # @param events [Array<PgEventstore::Event>]
-    # @return [PgEventstore::Event]
+    # @return [Array<PgEventstore::Event>]
     def insert(stream, events)
       sql_rows_for_insert, values = prepared_statements(stream, events)
       columns = %w[id data metadata stream_revision link_id link_partition_id type context stream_name stream_id]
@@ -122,7 +130,7 @@ module PgEventstore
 
     # @param stream [PgEventstore::Stream]
     # @param options [Hash]
-    # @return [PgEventstore::EventsFilteringQuery]
+    # @return [PgEventstore::EventsFiltering]
     def events_filtering(stream, options)
       return QueryBuilders::EventsFiltering.all_stream_filtering(options) if stream.all_stream?
 

data/lib/pg_eventstore/queries/links_resolver.rb

@@ -3,6 +3,8 @@
 module PgEventstore
   # @!visibility private
   class LinksResolver
+    # @!attribute connection
+    #   @return [PgEventstore::Connection]
     attr_reader :connection
     private :connection
 
@@ -46,6 +48,7 @@ module PgEventstore
       end.to_a
     end
 
+    # @return [PgEventstore::PartitionQueries]
     def partition_queries
       PartitionQueries.new(connection)
     end

data/lib/pg_eventstore/queries/partition_queries.rb

@@ -3,6 +3,8 @@
 module PgEventstore
   # @!visibility private
   class PartitionQueries
+    # @!attribute connection
+    #   @return [PgEventstore::Connection]
     attr_reader :connection
     private :connection
 
@@ -69,6 +71,7 @@ module PgEventstore
     end
 
     # @param stream [PgEventstore::Stream]
+    # @param event_type [String]
     # @param stream_name_partition_name [String]
     # @return [Hash] partition attributes
     def create_event_type_partition(stream, event_type, stream_name_partition_name)
@@ -185,6 +188,9 @@ module PgEventstore
       "stream_names_#{Digest::MD5.hexdigest("#{stream.context}-#{stream.stream_name}")[0..5]}"
     end
 
+    # @param stream [PgEventstore::Stream]
+    # @param event_type [String]
+    # @return [String]
     def event_type_partition_name(stream, event_type)
       "event_types_#{Digest::MD5.hexdigest("#{stream.context}-#{stream.stream_name}-#{event_type}")[0..5]}"
     end

data/lib/pg_eventstore/queries/transaction_queries.rb

@@ -3,6 +3,7 @@
 module PgEventstore
   # @!visibility private
   class TransactionQueries
+    # @return [Hash<Symbol => String>] symbol to transaction isolation level association
     ISOLATION_LEVELS = {
       read_committed: 'READ COMMITTED',
       repeatable_read: 'REPEATABLE READ',
@@ -11,6 +12,8 @@ module PgEventstore
       h.default = h[:serializable]
     end.freeze
 
+    # @!attribute connection
+    #   @return [PgEventstore::Connection]
     attr_reader :connection
     private :connection
 
@@ -57,6 +60,7 @@ module PgEventstore
       retry
     end
 
+    # @return [PgEventstore::PartitionQueries]
     def partition_queries
       PartitionQueries.new(connection)
     end

data/lib/pg_eventstore/queries.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'sql_builder'
-require_relative 'query_builders/events_filtering_query'
+require_relative 'query_builders/events_filtering'
 require_relative 'queries/transaction_queries'
 require_relative 'queries/event_queries'
 require_relative 'queries/partition_queries'

data/lib/pg_eventstore/query_builders/{events_filtering_query.rb → events_filtering.rb}

@@ -4,7 +4,9 @@ module PgEventstore
   module QueryBuilders
     # @!visibility private
     class EventsFiltering
+      # @return [Integer]
       DEFAULT_LIMIT = 1_000
+      # @return [Hash<String => String, Symbol => String>]
       SQL_DIRECTIONS = {
         'asc' => 'ASC',
         'desc' => 'DESC',
@@ -15,6 +17,7 @@ module PgEventstore
       }.tap do |directions|
         directions.default = 'ASC'
       end.freeze
+      # @return [Array<Symbol>]
       SUBSCRIPTIONS_OPTIONS = %i[from_position resolve_link_tos filter max_count].freeze
 
       class << self

data/lib/pg_eventstore/sql_builder.rb

@@ -19,13 +19,13 @@ module PgEventstore
     end
 
     # @param sql [String]
-    # @return self
+    # @return [self]
     def select(sql)
       @select_values.push(sql)
       self
     end
 
-    # @return self
+    # @return [self]
     def unselect
       @select_values.clear
       self
@@ -33,7 +33,7 @@ module PgEventstore
 
     # @param sql [String]
     # @param arguments [Array] positional values
-    # @return self
+    # @return [self]
     def where(sql, *arguments)
       @where_values['AND'].push([sql, arguments])
       self
@@ -41,14 +41,14 @@ module PgEventstore
 
     # @param sql [String]
     # @param arguments [Object] positional values
-    # @return self
+    # @return [self]
     def where_or(sql, *arguments)
       @where_values['OR'].push([sql, arguments])
       self
     end
 
     # @param table_name [String]
-    # @return self
+    # @return [self]
     def from(table_name)
       @from_value = table_name
       self
@@ -56,38 +56,40 @@ module PgEventstore
 
     # @param sql [String]
     # @param arguments [Object]
-    # @return self
+    # @return [self]
     def join(sql, *arguments)
       @join_values.push([sql, arguments])
       self
     end
 
     # @param sql [String]
-    # @return self
+    # @return [self]
     def order(sql)
       @order_values.push(sql)
       self
     end
 
+    # @return [self]
     def remove_order
       @order_values.clear
       self
     end
 
     # @param limit [Integer]
-    # @return self
+    # @return [self]
     def limit(limit)
       @limit_value = limit.to_i
       self
     end
 
+    # @return [self]
     def remove_limit
       @limit_value = nil
       self
     end
 
     # @param offset [Integer]
-    # @return self
+    # @return [self]
     def offset(offset)
       @offset_value = offset.to_i
       self
@@ -101,17 +103,19 @@ module PgEventstore
     end
 
     # @param sql [String]
-    # @return self
+    # @return [self]
     def group(sql)
       @group_values.push(sql)
       self
     end
 
+    # @return [self]
     def remove_group
       @group_values.clear
       self
     end
 
+    # @return [Array<String, Array<Object>>]
     def to_exec_params
       @positional_values.clear
       @positional_values_size = 0
@@ -125,10 +129,13 @@ module PgEventstore
       @positional_values
     end
 
+    # @param val [Integer]
+    # @return [Integer]
     def positional_values_size=(val)
       @positional_values_size = val
     end
 
+    # @return [Array<String, Array<Object>>]
     def _to_exec_params
       return [single_query_sql, @positional_values] if @union_values.empty?
 
@@ -188,6 +195,7 @@ module PgEventstore
     end
 
     # Replaces "?" signs in the given string with positional variables and memorize positional values they refer to.
+    # @param sql [String]
     # @return [String]
     def extract_positional_args(sql, *arguments)
       sql.gsub("?").each_with_index do |_, index|