pg_eventstore 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf4e7b2fb569adcc91434eecc16b269504108e980924f45543996b37f2fca67
-  data.tar.gz: 451796b0e92415aadf14c7ef6e2627378d99181f4a37104f8ce50ea990b12c75
+  metadata.gz: 12384e5023ddd60d3ff1f70006dcc8cc44d7901e4ddc7c24fcf3ab3772a00daf
+  data.tar.gz: d663c5aaaa96cee4f641710e7206938d9c8b06428c286b292edfaaecaaf0f4b1
 SHA512:
-  metadata.gz: 78af9eb3c02e3f002765dfb888263a221e3f77cd005593ecff4c5a8443f781e992ecd30d0f81120f4afcd268b573afab5c8616f683aed0255104db7d1c6e3fa1
-  data.tar.gz: d8c27f5efd39737c453b490e176bba7cb6d24456faee0b86fb317899ec7bb19d411ed5fdc3f7ed7742a23deb36e87b70d2ce44a4727bf78e23709f77958bd1b9
+  metadata.gz: e316a1a3d5a9619e4b9637aa411d9ff1cf438d4e210b02d7efd0b25e6bb1b865ff96f0cf8df2729715b5ec0b017b6254fbd51c6db9ad808b9c1a28717f7f65fc
+  data.tar.gz: cfecd6d0c57422130233c1fce18dd94b978c577427684ccff0610c54c8951cfbea0d91904dabfdfc73dbc6b9568fbb1d04b955344cbb53eabc08edefee0b2d16

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.1.4]
+- Add rbs signatures
+
+## [1.1.3]
+- Fix issue with assets caching between different gem's versions
+
 ## [1.1.2]
 - Improve web app compatibility with rails
 

data/README.md

@@ -47,44 +47,22 @@ Documentation chapters:
 - [Subscriptions](docs/subscriptions.md)
 - [Writing middlewares](docs/writing_middleware.md)
 - [How to make multiple commands atomic](docs/multiple_commands.md)
-
-## Admin web UI
-
-`pg_eventstore` implements admin UI where you can browse various database objects. It is implemented as rack application. It doesn't have any authentication/authorization mechanism - it is your responsibility to take care of it.
-
-### Rails integration
-
-In your `config/routes.rb`:
-
-```ruby
-require 'pg_eventstore/web'
-
-mount PgEventstore::Web::Application, at: '/eventstore'
-```
-
-### Standalone application
-
-Create `config.ru` file and place next content in there:
-
-```ruby
-require 'pg_eventstore/web'
-
-run PgEventstore::Web::Application
-```
-
-Now you can use any web server to run it.
+- [Admin UI](docs/admin_ui.md)
 
 ## Development
 
 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`.
 
+To run admin UI web server - run `puma` in your terminal. By default it will start web server on `http://0.0.0.0:9292`.
+
 ### Benchmarks
 
 There is a script to help you to tests the `pg_eventstore` implementation performance. You can run it using next command:

data/docs/admin_ui.md

@@ -0,0 +1,35 @@
+# Admin UI
+
+`pg_eventstore` implements admin UI where you can browse various database objects. Key features:
+
+- events lookup using filtering by stream context, stream name, stream id and event type
+- subscriptions management and monitoring
+
+![Events lookup](images/events_lookup.jpg)
+![Subscriptions](images/subscriptions.jpg)
+
+## Authorization
+
+Admin UI is implemented as a rack application. It doesn't have any built-in authentication/authorization mechanism - it is your responsibility to take care of it.
+
+### Rails integration
+
+In your `config/routes.rb`:
+
+```ruby
+require 'pg_eventstore/web'
+
+mount PgEventstore::Web::Application, at: '/eventstore'
+```
+
+### Standalone application
+
+Create `config.ru` file and place next content in there:
+
+```ruby
+require 'pg_eventstore/web'
+
+run PgEventstore::Web::Application
+```
+
+Now you can use any web server to run it.

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