pg_eventstore 1.10.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ff0f3d0cf7c80ebe381ca1da32b921766c10055832f05b94d15e2f25b73d55
-  data.tar.gz: a00e2ef1bc9435b2e5b7732e0dd5ee85a3a3ed6e457c5d106f654f035ff7c3e3
+  metadata.gz: e0de14f58d080bcab32005e045530ca7888761e5415d013dbb262746a02806ba
+  data.tar.gz: fee7b7335212796361b5ded87497c7d744ed5ddfd011a47d54cc2b545991b227
 SHA512:
-  metadata.gz: 23c6bd66a79199cf49411e73635d4829c5bef802a97c3e37f3d46513a1c7b8163163fa665b99d47bd870829ba2059650c4d8b9798c95991c37834e478b352aa4
-  data.tar.gz: af188405be2d0a13c8694840dc6dcb5eef435ada27979a2f570be1ccacf33c465930d4bb9237ad6d7c78c7bde2edc5d0cfa61064dd7dc8c2c0c6a11856f39980
+  metadata.gz: 0dbdd04e5778b292177062e5a44ed9ee4c2fc03e98da945a73523036f62ed09cc27ac00d1a5853e99975b82fc798f2f83639bbb2cd4f1745150ff121ca5d7056
+  data.tar.gz: 060f8b1b51cda7be2c472f914dc611fee2db052a2cd773676013b2175e58cf12c3895e8b631a0d79443804f3a733ca25d7012fac6519551308c890df065457d5

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.12.0]
+
+- Introduce `#read_grouped` API method that allows to group events by type
+
+## [1.11.0]
+
+- Add a global position that caused an error to the subscription's error JSON info. This will help you understand what event caused your subscription to fail.
+- Improve long payloads in JSON preview in admin web UI in the way it does not moves content out of the visible area.
+- Admin UI: adjust events filtering and displaying of stream context, stream name, stream id and event type when values of them contain empty strings or non-displayable characters
+
 ## [1.10.0]
 - Admin UI: Adjust `SubscriptionSet` "Stop"/"Delete" buttons appearance. Now if `SubscriptionsSet` is not alive anymore(the related process is dead or does not exist anymore) - "Delete" button is shown. If `SubscriptionSet` is alive - "Stop" button is shown
 - Admin IU: fixed several potential XSS vulnerabilities

data/docs/reading_events.md

@@ -230,3 +230,101 @@ PgEventstore.client.read_paginated(projection_stream, options: { resolve_link_to
   end
 end
 ```
+
+## Grouping events by type
+
+`pg_eventstore` implements an ability to group events by type when reading from a stream. Example:
+
+```ruby
+stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Foo', stream_id: '1')
+event1 = PgEventstore::Event.new(type: 'Foo', data: { foo: 1 })
+event2 = PgEventstore::Event.new(type: 'Foo', data: { foo: 2 })
+event3 = PgEventstore::Event.new(type: 'Bar', data: { bar: 2 })
+
+PgEventstore.client.append_to_stream(stream, [event1, event2, event3])
+
+PgEventstore.client.read_grouped(stream) # => returns event1 and event3
+```
+
+API is very similar to the API of `#read`, but it ignores `:max_count` options as the result is always returns a set of event types in your stream.
+
+Reading most recent events:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :desc })
+```
+
+Filtering the result by stream attributes:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }] } }
+)
+```
+
+Filtering the result by event types:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { event_types: ['Foo', 'Bar'] } }
+)
+```
+
+Filtering by stream attributes and event types:
+
+```ruby
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }], event_types: ['Foo', 'Bar'] } }
+)
+```
+
+Reading most recent events until the certain stream revision:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :desc, from_revision: 1 })
+```
+
+Reading the oldest events from the certain stream revision:
+
+```ruby
+PgEventstore.client.read_grouped(stream, options: { direction: :asc, from_revision: 1 })
+```
+
+Reading most recent events until the certain global position:
+
+```ruby
+PgEventstore.client.read_grouped(PgEventstore::Stream.all_stream, options: { direction: :desc, from_position: 5 })
+```
+
+Reading the oldest events from the certain global position:
+
+```ruby
+PgEventstore.client.read_grouped(PgEventstore::Stream.all_stream, options: { direction: :asc, from_position: 5 })
+```
+
+### Event types list lookup
+
+If you do not provide event types filter - event types list will be determined based on the rest of arguments(a stream argument or a stream filters option).
+
+### Multiple events of same type in the result
+
+If same event type appear in different streams(different by `#context` and `#stream_name`) - those events will appear in the result. This is because even though `Event#type` value may be the same - its meaning may have different meaning in different `context`/`stream_name` couple. Example:
+
+```ruby
+stream1 = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Foo', stream_id: '1')
+stream2 = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'Bar', stream_id: '1')
+
+event1 = PgEventstore::Event.new(type: 'Foo', data: { foo: 1 })
+event2 = PgEventstore::Event.new(type: 'Foo', data: { foo: 2 })
+
+PgEventstore.client.append_to_stream(stream1, event1)
+PgEventstore.client.append_to_stream(stream2, event2)
+
+PgEventstore.client.read_grouped(
+  PgEventstore::Stream.all_stream,
+  options: { filter: { streams: [{ context: 'FooCtx' }] } }
+) # => returns both events even though they are of "Foo" type
+```

data/lib/pg_eventstore/client.rb

@@ -55,10 +55,11 @@ module PgEventstore
     # Read events from the specific stream or from "all" stream.
     # @param stream [PgEventstore::Stream]
     # @param options [Hash] request options
-    # @option options [String] :direction read direction - 'Forwards' or 'Backwards'
+    # @option options [String] :direction read direction. Allowed values are "Forwards", "Backwards", "asc", "desc",
+    #   :asc, :desc
     # @option options [Integer] :from_revision a starting revision number. **Use this option when stream name is a
     #   normal stream name**
-    # @option options [Integer, Symbol] :from_position a starting global position number. **Use this option when reading
+    # @option options [Integer] :from_position a starting global position number. **Use this option when reading
     #   from "all" stream**
     # @option options [Integer] :max_count max number of events to return in one response. Defaults to config.max_count
     # @option options [Boolean] :resolve_link_tos When using projections to create new events you
@@ -94,7 +95,7 @@ module PgEventstore
     #       }
     #     )
     #
-    #     # Filtering the a mix of context and event type
+    #     # Filtering a mix of context and event type
     #     PgEventstore.client.read(
     #       PgEventstore::Stream.all_stream,
     #       options: { filter: { streams: [{ context: 'User' }], event_types: ['MyAwesomeEvent'] } }
@@ -123,6 +124,23 @@ module PgEventstore
         call(stream, options: { max_count: config.max_count }.merge(options))
     end
 
+    # Takes a stream, determines a list of even types in it and returns most recent(or very first - depending on
+    # :direction option) events, one of each type. If :event_types filter is provided - uses it instead of automatic
+    # event types lookup logic. The result size is almost always less than or equal to event types list size, so passing
+    # :max_count option does not make any effect. In case if event of same type appears in different context/stream
+    # name - it will be counted as a different event, thus, may appear several times in the result.
+    # @see {#read} for the detailed docs
+    # @param stream [PgEventstore::Stream]
+    # @param options [Hash] request options
+    # @param middlewares [Array, nil]
+    # @return [Array<PgEventstore::Event>]
+    def read_grouped(stream, options: {}, middlewares: nil)
+      cmd_class = stream.all_stream? ? Commands::AllStreamReadGrouped : Commands::RegularStreamReadGrouped
+      cmd_class.
+        new(Queries.new(partitions: partition_queries, events: event_queries(middlewares(middlewares)))).
+        call(stream, options: 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]
@@ -149,7 +167,7 @@ module PgEventstore
     private
 
     # @param middlewares [Array, nil]
-    # @return [Array<Object<#serialize, #deserialize>>]
+    # @return [Array<PgEventstore::Middleware>]
     def middlewares(middlewares = nil)
       return config.middlewares.values unless middlewares
 

data/lib/pg_eventstore/commands/all_stream_read_grouped.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class AllStreamReadGrouped < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash] request options
+      # @option options [String] :direction read direction
+      # @option options [Integer, Symbol] :from_position. **Use this option when reading from "all" stream**
+      # @option options [Boolean] :resolve_link_tos
+      # @option options [Hash] :filter provide it to filter events
+      # @return [Array<PgEventstore::Event>]
+      # @raise [PgEventstore::StreamNotFoundError]
+      def call(stream, options: {})
+        event_types = QueryBuilders::PartitionsFiltering.extract_event_types_filter(options)
+        stream_filters = QueryBuilders::PartitionsFiltering.extract_streams_filter(options)
+        stream_ids_grouped = group_stream_ids(options)
+        options_by_event_type =
+          queries.partitions.partitions(stream_filters, event_types).flat_map do |partition|
+            stream_ids = stream_ids_grouped[[partition.context, partition.stream_name]]
+            next build_filter_options_for_streams(partition, stream_ids, options) if stream_ids
+
+            build_filter_options_for_partitions(partition, options)
+          end
+        queries.events.grouped_events(stream, options_by_event_type, **options.slice(:resolve_link_tos))
+      end
+
+      private
+
+      # @param options [Hash]
+      # @return [Hash]
+      def group_stream_ids(options)
+        event_stream_filters = QueryBuilders::EventsFiltering.extract_streams_filter(options)
+        event_stream_filters.each_with_object({}) do |attrs, res|
+          next unless attrs[:stream_id]
+
+          res[[attrs[:context], attrs[:stream_name]]] ||= []
+          res[[attrs[:context], attrs[:stream_name]]].push(attrs[:stream_id])
+        end
+      end
+
+      # @param partition [PgEventstore::Partition]
+      # @param stream_ids [Array<String>]
+      # @param options [Hash]
+      # @return [Array<Hash>]
+      def build_filter_options_for_streams(partition, stream_ids, options)
+        stream_ids.map do |stream_id|
+          filter = {
+            streams: [{ context: partition.context, stream_name: partition.stream_name, stream_id: stream_id }],
+            event_types: [partition.event_type]
+          }
+          options.merge(filter: filter, max_count: 1)
+        end
+      end
+
+      # @param partition [PgEventstore::Partition]
+      # @param options [Hash]
+      # @return [Hash]
+      def build_filter_options_for_partitions(partition, options)
+        filter = {
+          streams: [{ context: partition.context, stream_name: partition.stream_name }],
+          event_types: [partition.event_type]
+        }
+        options.merge(filter: filter, max_count: 1)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands/regular_stream_read_grouped.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module Commands
+    # @!visibility private
+    class RegularStreamReadGrouped < AbstractCommand
+      # @param stream [PgEventstore::Stream]
+      # @param options [Hash] request options
+      # @option options [String] :direction read direction
+      # @option options [Integer, Symbol] :from_revision. **Use this option when stream name is a normal stream name**
+      # @option options [Integer, Symbol] :from_position. **Use this option when reading from "all" stream**
+      # @option options [Boolean] :resolve_link_tos
+      # @option options [Hash] :filter provide it to filter events
+      # @return [Array<PgEventstore::Event>]
+      # @raise [PgEventstore::StreamNotFoundError]
+      def call(stream, options: {})
+        queries.events.stream_revision(stream) || raise(StreamNotFoundError, stream)
+
+        event_types = QueryBuilders::PartitionsFiltering.extract_event_types_filter(options)
+        stream_filters = QueryBuilders::PartitionsFiltering.extract_streams_filter(
+          filter: { streams: [{ context: stream.context, stream_name: stream.stream_name }] }
+        )
+        options_by_event_type = queries.partitions.partitions(stream_filters, event_types).map do |partition|
+          filter = { event_types: [partition.event_type] }
+          options.merge(filter: filter, max_count: 1)
+        end
+        queries.events.grouped_events(stream, options_by_event_type, **options.slice(:resolve_link_tos))
+      end
+    end
+  end
+end

data/lib/pg_eventstore/commands.rb

@@ -5,6 +5,8 @@ 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_grouped'
+require_relative 'commands/all_stream_read_grouped'
 require_relative 'commands/regular_stream_read_paginated'
 require_relative 'commands/system_stream_read_paginated'
 require_relative 'commands/multiple'

data/lib/pg_eventstore/errors.rb

@@ -243,4 +243,14 @@ module PgEventstore
       "Too many records of #{stream.to_hash.inspect} stream to lock: #{number_of_records}"
     end
   end
+
+  class WrappedException < Error
+    attr_reader :original_exception
+    attr_reader :extra
+
+    def initialize(original_exception, extra)
+      @original_exception = original_exception
+      @extra = extra
+    end
+  end
 end

data/lib/pg_eventstore/partition.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  class Partition
+    include Extensions::OptionsExtension
+
+    # @!attribute id
+    #   @return [Integer]
+    option(:id)
+    # @!attribute context
+    #   @return [String]
+    option(:context)
+    # @!attribute stream_name
+    #   @return [String, nil]
+    option(:stream_name)
+    # @!attribute event_type
+    #   @return [String, nil]
+    option(:event_type)
+    # @!attribute table_name
+    #   @return [String]
+    option(:table_name)
+  end
+end

data/lib/pg_eventstore/queries/event_queries.rb

@@ -98,6 +98,24 @@ module PgEventstore
       end
     end
 
+    # @param stream [PgEventstore::Stream]
+    # @param options_by_event_type [Array<Hash>] a set of options per an event type
+    # @param options [Hash]
+    # @option options [Boolean] :resolve_link_tos
+    # @return [Array<PgEventstore::Event>]
+    def grouped_events(stream, options_by_event_type, **options)
+      builders = options_by_event_type.map do |filter|
+        QueryBuilders::EventsFiltering.events_filtering(stream, filter)
+      end
+      final_builder = SQLBuilder.union_builders(builders.map(&:to_sql_builder))
+
+      raw_events = connection.with do |conn|
+        conn.exec_params(*final_builder.to_exec_params)
+      end.to_a
+      raw_events = links_resolver.resolve(raw_events) if options[:resolve_link_tos]
+      deserializer.deserialize_many(raw_events)
+    end
+
     private
 
     # @param stream [PgEventstore::Stream]

data/lib/pg_eventstore/queries/partition_queries.rb

@@ -176,6 +176,19 @@ module PgEventstore
       end.to_a
     end
 
+    # @param stream_filters [Array<Hash[Symbol, String]>]
+    # @param event_filters [Array<String>]
+    # @return [Array<PgEventstore::Partition>]
+    def partitions(stream_filters, event_filters)
+      partitions_filter = QueryBuilders::PartitionsFiltering.new
+      stream_filters.each { |attrs| partitions_filter.add_stream_attrs(**attrs) }
+      partitions_filter.add_event_types(event_filters)
+      partitions_filter.with_event_types
+      connection.with do |conn|
+        conn.exec_params(*partitions_filter.to_exec_params)
+      end.map(&method(:deserialize))
+    end
+
     # @param stream [PgEventstore::Stream]
     # @return [String]
     def context_partition_name(stream)
@@ -194,5 +207,13 @@ module PgEventstore
     def event_type_partition_name(stream, event_type)
       "event_types_#{Digest::MD5.hexdigest("#{stream.context}-#{stream.stream_name}-#{event_type}")[0..5]}"
     end
+
+    private
+
+    # @param attrs [Hash]
+    # @return [PgEventstore::Partition]
+    def deserialize(attrs)
+      Partition.new(**attrs.transform_keys(&:to_sym))
+    end
   end
 end

data/lib/pg_eventstore/queries.rb

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

data/lib/pg_eventstore/query_builders/basic_filtering.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  module QueryBuilders
+    # @!visibility private
+    class BasicFiltering
+      def initialize
+        @sql_builder = SQLBuilder.new.select("#{to_table_name}.*").from(to_table_name)
+      end
+
+      # @return [String]
+      def to_table_name
+        raise NotImplementedError
+      end
+
+      # @return [PgEventstore::SQLBuilder]
+      def to_sql_builder
+        @sql_builder
+      end
+
+      # @return [Array]
+      def to_exec_params
+        @sql_builder.to_exec_params
+      end
+    end
+  end
+end

data/lib/pg_eventstore/query_builders/events_filtering.rb

@@ -3,7 +3,11 @@
 module PgEventstore
   module QueryBuilders
     # @!visibility private
-    class EventsFiltering
+    class EventsFiltering < BasicFiltering
+      # @return [String]
+      TABLE_NAME = 'events'
+      private_constant :TABLE_NAME
+
       # @return [Integer]
       DEFAULT_LIMIT = 1_000
       # @return [Hash<String => String, Symbol => String>]
@@ -26,6 +30,7 @@ module PgEventstore
         # @return [PgEventstore::EventsFiltering]
         def events_filtering(stream, options)
           return all_stream_filtering(options) if stream.all_stream?
+
           if stream.system? && Stream::KNOWN_SYSTEM_STREAMS.include?(stream.context)
             return system_stream_filtering(stream, options)
           end
@@ -43,11 +48,9 @@ module PgEventstore
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
         def all_stream_filtering(options)
           event_filter = new
-          options in { filter: { event_types: Array => event_types } }
-          event_filter.add_event_types(event_types)
+          event_filter.add_event_types(extract_event_types_filter(options))
           event_filter.add_limit(options[:max_count])
-          options in { filter: { streams: Array => streams } }
-          streams&.each { |attrs| event_filter.add_stream_attrs(**attrs) }
+          extract_streams_filter(options).each { |attrs| event_filter.add_stream_attrs(**attrs) }
           event_filter.add_global_position(options[:from_position], options[:direction])
           event_filter.add_all_stream_direction(options[:direction])
           event_filter
@@ -58,8 +61,7 @@ module PgEventstore
         # @return [PgEventstore::QueryBuilders::EventsFiltering]
         def specific_stream_filtering(stream, options)
           event_filter = new
-          options in { filter: { event_types: Array => event_types } }
-          event_filter.add_event_types(event_types)
+          event_filter.add_event_types(extract_event_types_filter(options))
           event_filter.add_limit(options[:max_count])
           event_filter.add_stream_attrs(**stream.to_hash)
           event_filter.add_revision(options[:from_revision], options[:direction])
@@ -75,14 +77,39 @@ module PgEventstore
             event_filter.set_source(stream.context)
           end
         end
+
+        # @param options [Hash]
+        # @return [Array<String>]
+        def extract_event_types_filter(options)
+          options in { filter: { event_types: Array => event_types } }
+          event_types&.select! do
+            _1.is_a?(String)
+          end
+          event_types || []
+        end
+
+        # @param options [Hash]
+        # @return [Array<Hash[Symbol, String]>]
+        def extract_streams_filter(options)
+          options in { filter: { streams: Array => streams } }
+          streams = streams&.map do
+            _1 in { context: String | NilClass => context }
+            _1 in { stream_name: String | NilClass => stream_name }
+            _1 in { stream_id: String | NilClass => stream_id }
+            { context: context, stream_name: stream_name, stream_id: stream_id }
+          end
+          streams || []
+        end
       end
 
       def initialize
-        @sql_builder =
-          SQLBuilder.new.
-            select('events.*').
-            from('events').
-            limit(DEFAULT_LIMIT)
+        super
+        @sql_builder.limit(DEFAULT_LIMIT)
+      end
+
+      # @return [String]
+      def to_table_name
+        TABLE_NAME
       end
 
       # @param context [String, nil]
@@ -95,21 +122,20 @@ module PgEventstore
 
         stream_attrs.compact!
         sql = stream_attrs.map do |attr, _|
-          "events.#{attr} = ?"
+          "#{to_table_name}.#{attr} = ?"
         end.join(" AND ")
         @sql_builder.where_or(sql, *stream_attrs.values)
       end
 
-      # @param event_types [Array<String>, nil]
+      # @param event_types [Array<String>]
       # @return [void]
       def add_event_types(event_types)
-        return if event_types.nil?
         return if event_types.empty?
 
         sql = event_types.size.times.map do
           "?"
         end.join(", ")
-        @sql_builder.where("events.type IN (#{sql})", *event_types)
+        @sql_builder.where("#{to_table_name}.type IN (#{sql})", *event_types)
       end
 
       # @param revision [Integer, nil]
@@ -118,7 +144,7 @@ module PgEventstore
       def add_revision(revision, direction)
         return unless revision
 
-        @sql_builder.where("events.stream_revision #{direction_operator(direction)} ?", revision)
+        @sql_builder.where("#{to_table_name}.stream_revision #{direction_operator(direction)} ?", revision)
       end
 
       # @param position [Integer, nil]
@@ -127,19 +153,19 @@ module PgEventstore
       def add_global_position(position, direction)
         return unless position
 
-        @sql_builder.where("events.global_position #{direction_operator(direction)} ?", position)
+        @sql_builder.where("#{to_table_name}.global_position #{direction_operator(direction)} ?", position)
       end
 
       # @param direction [String, Symbol, nil]
       # @return [void]
       def add_stream_direction(direction)
-        @sql_builder.order("events.stream_revision #{SQL_DIRECTIONS[direction]}")
+        @sql_builder.order("#{to_table_name}.stream_revision #{SQL_DIRECTIONS[direction]}")
       end
 
       # @param direction [String, Symbol, nil]
       # @return [void]
       def add_all_stream_direction(direction)
-        @sql_builder.order("events.global_position #{SQL_DIRECTIONS[direction]}")
+        @sql_builder.order("#{to_table_name}.global_position #{SQL_DIRECTIONS[direction]}")
       end
 
       # @param limit [Integer, nil]
@@ -150,20 +176,10 @@ module PgEventstore
         @sql_builder.limit(limit)
       end
 
-      # @return [PgEventstore::SQLBuilder]
-      def to_sql_builder
-        @sql_builder
-      end
-
-      # @return [Array]
-      def to_exec_params
-        @sql_builder.to_exec_params
-      end
-
       # @param table_name [String] system stream view name
       # @return [void]
       def set_source(table_name)
-        @sql_builder.from(%{ "#{PG::Connection.escape(table_name)}" events })
+        @sql_builder.from(%{ "#{PG::Connection.escape(table_name)}" #{to_table_name} })
       end
 
       private