event_store_client 2.3.0 → 3.1.0

data/docs/reading_events.md

@@ -1,6 +1,4 @@
-# @title Reading events
-
-# Reading events
+# Reading Events
 
 ## Reading from a stream
 
@@ -8,18 +6,7 @@ The simplest way to read a stream forwards is to supply a stream name.
 
 ```ruby
 EventStoreClient.client.read('some-stream')
-# => Success([#<EventStoreClient::DeserializedEvent 0x1>, #<EventStoreClient::DeserializedEvent 0x1>])
-```
-
-This will return either `Dry::Monads::Success` with the list of events attached or `Dry::Monads::Failure` with an error. You can handle the result like this:
-
-```ruby
-result = EventStoreClient.client.read('some-stream')
-if result.success?
-  result.success.each do |event|
-    # do something with an event
-  end
-end
+# => [#<EventStoreClient::DeserializedEvent 0x1>, #<EventStoreClient::DeserializedEvent 0x1>]
 ```
 
 ### Request options customization
@@ -68,17 +55,17 @@ As well as being able to read a stream forwards you can also go backwards. This
 EventStoreClient.client.read('some-stream', options: { direction: 'Backwards', from_revision: :end })
 ```
 
-## Checking if the stream exists
+## Checking if stream exists
 
-In case a stream with given name does not exist, `Dry::Monads::Failure` will be returned with value `:stream_not_found`:
+In case a stream with given name does not exist - `EventStoreClient::StreamNotFoundError` error will be raised:
 
 ```ruby
-result = EventStoreClient.client.read('non-existing-stream')
-# => Failure(:stream_not_found)
-result.failure?
-# => true
-result.failure
-# => :stream_not_found
+begin
+  EventStoreClient.client.read('non-existing-stream')
+rescue EventStoreClient::StreamNotFoundError => e
+  puts e.message # => Stream "non-existing-stream" does not exist.
+  puts e.stream_name # => "non-existing-stream"
+end
 ```
 
 ## Reading from the $all stream
@@ -103,46 +90,40 @@ If you would like to skip deserialization of the `#read` result, you should use
 
 ```ruby
 EventStoreClient.client.read('some-stream', skip_deserialization: true)
-# => Success([<EventStore::Client::Streams::ReadResp ...>])
+# => [<EventStore::Client::Streams::ReadResp ...>]
 ```
 
 ## Filtering
 
-The filtering feature is only available for the`$all` stream.
+The filtering feature is only available for the `$all` stream.
 
 Retrieve events from streams with name starting with `some-stream`:
 
 ```ruby
-result =
+events =
   EventStoreClient.client.read('$all', options: { filter: { stream_identifier: { prefix: ['some-stream'] } } })
-if result.success?
-  result.success.each do |e|
-    # iterate through events
-  end
+events.each do |event|
+# iterate through events
 end
 ```
 
 Retrieve events with name starting with `some-event`:
 
 ```ruby
-result =
+events =
   EventStoreClient.client.read('$all', options: { event_type: { prefix: ['some-event'] } })
-if result.success?
-  result.success.each do |e|
-    # iterate through events
-  end
+events.each do |event|
+  # iterate through events
 end
 ```
 
 Retrieving events from stream `some-stream-1` and `some-stream-2`:
 
 ```ruby
-result =
+events =
   EventStoreClient.client.read('$all', options: { filter: { stream_identifier: { prefix: ['some-stream-1', 'some-stream-2'] } } })
-if result.success?
-  result.success.each do |e|
-    # iterate through events
-  end
+events.each do |event|
+  # iterate through events
 end
 ```
 
@@ -151,43 +132,33 @@ end
 You can use `#read_paginated`, the ready-to-go implementation of pagination which returns an array of result pages:
 
 ```ruby
-EventStoreClient.client.read_paginated('some-stream').each do |result|
-  if result.success?
-    result.success.each do |event|
-      # do something with event
-    end
+EventStoreClient.client.read_paginated('some-stream').each do |events|
+  events.each do |event|
+    # iterate through events
   end
 end
 
-EventStoreClient.client.read_paginated('$all').each do |result|
-  if result.success?
-    result.success.each do |event|
-      # do something with event
-    end
+EventStoreClient.client.read_paginated('$all').each do |events|
+  events.each do |event|
+    # iterate through events
   end
 end
 ```
 
-
-
 ### Paginating backward reads
 
 Just supply a call with `:direction` option and with `:from_position`/`:from_revision` option(depending on what stream you read from):
 
 ```ruby
-EventStoreClient.client.read_paginated('some-stream', options: { direction: 'Backwards', from_revision: :end }).each do |result|
-  if result.success?
-    result.each do |event|
-      # do something with event
-    end
+EventStoreClient.client.read_paginated('some-stream', options: { direction: 'Backwards', from_revision: :end }).each do |events|
+  events.each do |event|
+    # iterate through events
   end
 end
 
-EventStoreClient.client.read_paginated('$all', options: { direction: 'Backwards', from_position: :end }).each do |result|
-  if result.success?
-    result.each do |event|
-      # do something with event
-    end
+EventStoreClient.client.read_paginated('$all', options: { direction: 'Backwards', from_position: :end }).each do |events|
+  events.each do |event|
+    # iterate through events
   end
 end
 ```

data/lib/event_store_client/adapters/grpc/client.rb

@@ -31,8 +31,8 @@ module EventStoreClient
       #       puts proposed_msg_opts.proposed_message
       #     end
       #   ```
-      # @return [Dry::Monads::Result::Success, Dry::Monads::Result::Failure, Array<Dry::Monads::Result::Success, Dry::Monads::Result::Failure>]
-      #   Returns monads' Success/Failure in case whether request was performed.
+      # @return [EventStore::Client::Streams::AppendResp, Array<EventStore::Client::Streams::AppendResp>]
+      # @raise [EventStoreClient::WrongExpectedVersionError]
       def append_to_stream(stream_name, events_or_event, options: {}, credentials: {}, &blk)
         if events_or_event.is_a?(Array)
           Commands::Streams::AppendMultiple.new(config: config, **credentials).call(
@@ -93,7 +93,8 @@ module EventStoreClient
       #       )
       #     end
       #   ```
-      # @return [Dry::Monads::Success, Dry::Monads::Failure]
+      # @return [Array<EventStoreClient::DeserializedEvent>, Array<EventStore::Client::Streams::ReadResp>]
+      # @raise [EventStoreClient::StreamNotFoundError]
       def read(stream_name, options: {}, skip_deserialization: config.skip_deserialization,
                skip_decryption: config.skip_decryption, credentials: {}, &blk)
         Commands::Streams::Read.new(config: config, **credentials).call(
@@ -106,8 +107,9 @@ module EventStoreClient
       end
 
       # @see {#read} for available params
-      # @return [Enumerator] enumerator will yield Dry::Monads::Success or Dry::Monads::Failure on
-      #   each iteration
+      # @return [Enumerator] enumerator will yield EventStoreClient::DeserializedEvent or
+      # EventStore::Client::Streams::ReadResp on each iteration depending on `:skip_deserialization`
+      # argument value
       def read_paginated(stream_name, options: {}, credentials: {},
                          skip_deserialization: config.skip_deserialization,
                          skip_decryption: config.skip_decryption, &blk)
@@ -136,7 +138,8 @@ module EventStoreClient
       #       opts.stream_identifier.stream_name = 'overridden-stream-name'
       #     end
       #     ```
-      # @return [Dry::Monads::Success, Dry::Monads::Failure]
+      # @return [EventStore::Client::Streams::DeleteResp]
+      # @raise [EventStoreClient::StreamDeletionError]
       def hard_delete_stream(stream_name, options: {}, credentials: {}, &blk)
         Commands::Streams::HardDelete.
           new(config: config, **credentials).
@@ -159,7 +162,8 @@ module EventStoreClient
       #       opts.stream_identifier.stream_name = 'overridden-stream-name'
       #     end
       #     ```
-      # @return [Dry::Monads::Success, Dry::Monads::Failure]
+      # @return [EventStore::Client::Streams::DeleteResp]
+      # @raise [EventStoreClient::StreamDeletionError]
       def delete_stream(stream_name, options: {}, credentials: {}, &blk)
         Commands::Streams::Delete.
           new(config: config, **credentials).
@@ -218,7 +222,7 @@ module EventStoreClient
       #       )
       #     end
       #     ```
-      # @return [Dry::Monads::Success, Dry::Monads::Failure]
+      # @return [void] will block current Thread until killed
       def subscribe_to_stream(stream_name, handler:, options: {}, credentials: {},
                               skip_deserialization: config.skip_deserialization,
                               skip_decryption: config.skip_decryption, &blk)
@@ -274,7 +278,7 @@ module EventStoreClient
       # @param credentials [Hash]
       # @option credentials [String] :username
       # @option credentials [String] :password
-      # @return [Dry::Monads::Success, Dry::Monads::Failure]
+      # @return [EventStore::Client::Gossip::ClusterInfo]
       def cluster_info(credentials: {})
         Commands::Gossip::ClusterInfo.new(config: config, **credentials).call
       end

data/lib/event_store_client/adapters/grpc/commands/command.rb

@@ -14,8 +14,6 @@ module EventStoreClient
           end
         end
 
-        include Dry::Monads[:try, :result]
-
         attr_reader :connection, :config
         private :connection, :config
 

data/lib/event_store_client/adapters/grpc/commands/gossip/cluster_info.rb

@@ -11,7 +11,7 @@ module EventStoreClient
           # @api private
           # @see {EventStoreClient::GRPC::Client#cluster_info}
           def call
-            Success(retry_request { service.read(request.new, metadata: metadata) })
+            retry_request { service.read(request.new, metadata: metadata) }
           end
         end
       end

data/lib/event_store_client/adapters/grpc/commands/streams/append.rb

@@ -20,7 +20,7 @@ module EventStoreClient
             response = retry_request(skip_retry: config.eventstore_url.throw_on_append_failure) do
               service.append(payload, metadata: metadata)
             end
-            validate_response(response)
+            validate_response(response, caused_by: event)
           end
 
           private
@@ -41,11 +41,17 @@ module EventStoreClient
           end
 
           # @param resp [EventStore::Client::Streams::AppendResp]
-          # @return [Dry::Monads::Success, Dry::Monads::Failure]
-          def validate_response(resp)
-            return Success(resp) if resp.success
+          # @param caused_by [EventStoreClient::DeserializedEvent]
+          # @return [EventStore::Client::Streams::AppendResp]
+          # @raise [EventStoreClient::WrongExpectedVersionError]
+          def validate_response(resp, caused_by:)
+            return resp if resp.success
 
-            Failure(resp.wrong_expected_version)
+            error = WrongExpectedVersionError.new(
+              resp.wrong_expected_version,
+              caused_by: caused_by
+            )
+            raise error
           end
         end
       end

data/lib/event_store_client/adapters/grpc/commands/streams/append_multiple.rb

@@ -10,9 +10,8 @@ module EventStoreClient
           # @api private
           # @see {EventStoreClient::GRPC::Client#append_to_stream}
           def call(stream_name, events, options:, &blk)
-            result = []
-            events.each.with_index do |event, index|
-              response = Commands::Streams::Append.new(
+            events.map.with_index do |event, index|
+              Commands::Streams::Append.new(
                 config: config, **connection_options
               ).call(
                 stream_name, event, options: options
@@ -21,10 +20,7 @@ module EventStoreClient
 
                 yield(req_opts, proposed_msg_opts) if blk
               end
-              result.push(response)
-              break if response.failure?
             end
-            result
           end
 
           private

data/lib/event_store_client/adapters/grpc/commands/streams/delete.rb

@@ -13,11 +13,13 @@ module EventStoreClient
           def call(stream_name, options:, &blk)
             options = normalize_options(stream_name, options)
             yield options if blk
-            Success(
-              retry_request { service.delete(request.new(options: options), metadata: metadata) }
-            )
-          rescue ::GRPC::FailedPrecondition
-            Failure(:stream_not_found)
+            retry_request { service.delete(request.new(options: options), metadata: metadata) }
+          rescue ::GRPC::FailedPrecondition => e
+            # GRPC::FailedPrecondition may happen for several reasons. For example, stream may not
+            # be existing, or :expected_revision option value does not match the current state of
+            # the stream. So, re-raise our own error, and pass there the original message - just in
+            # case.
+            raise StreamDeletionError.new(stream_name, details: e.message)
           end
 
           private

data/lib/event_store_client/adapters/grpc/commands/streams/hard_delete.rb

@@ -13,11 +13,13 @@ module EventStoreClient
           def call(stream_name, options:, &blk)
             options = normalize_options(stream_name, options)
             yield options if blk
-            Success(
-              retry_request { service.delete(request.new(options: options), metadata: metadata) }
-            )
-          rescue ::GRPC::FailedPrecondition
-            Failure(:stream_not_found)
+            retry_request { service.delete(request.new(options: options), metadata: metadata) }
+          rescue ::GRPC::FailedPrecondition => e
+            # GRPC::FailedPrecondition may happen for several reasons. For example, stream may not
+            # be existing, or :expected_revision option value does not match the current state of
+            # the stream. So, re-raise our own error, and pass there the original message - just in
+            # case.
+            raise StreamDeletionError.new(stream_name, details: e.message)
           end
 
           private

data/lib/event_store_client/adapters/grpc/commands/streams/link_to_multiple.rb

@@ -10,18 +10,13 @@ module EventStoreClient
           # @api private
           # @see {EventStoreClient::GRPC::Client#link_to}
           def call(stream_name, events, options:, &blk)
-            result = []
             link_cmd = Commands::Streams::LinkTo.new(config: config, **connection_options)
-            events.each.with_index do |event, index|
-              response =
-                link_cmd.call(stream_name, event, options: options) do |req_opts, proposed_msg_opts|
-                  req_opts.options.revision += index if has_revision_option?(req_opts.options)
-                  yield(req_opts, proposed_msg_opts) if blk
-                end
-              result.push(response)
-              break if response.failure?
+            events.map.with_index do |event, index|
+              link_cmd.call(stream_name, event, options: options) do |req_opts, proposed_msg_opts|
+                req_opts.options.revision += index if has_revision_option?(req_opts.options)
+                yield(req_opts, proposed_msg_opts) if blk
+              end
             end
-            result
           end
 
           private

data/lib/event_store_client/adapters/grpc/commands/streams/read_paginated.rb

@@ -40,22 +40,19 @@ module EventStoreClient
 
                     paginate_options(opts, position)
                   end
-                unless response.success?
-                  yielder << response
-                  raise StopIteration
-                end
                 processed_response =
                   EventStoreClient::GRPC::Shared::Streams::ProcessResponses.
                     new(config: config).
                     call(
-                      response.success,
+                      response,
                       skip_deserialization,
                       skip_decryption
                     )
-                yielder << processed_response if processed_response.success.any?
-                raise StopIteration if end_reached?(response.success, max_count)
 
-                position = calc_next_position(response.success, direction, stream_name)
+                yielder << processed_response if processed_response.any?
+                raise StopIteration if end_reached?(response, max_count)
+
+                position = calc_next_position(response, direction, stream_name)
                 raise StopIteration if position.negative?
               end
             end

data/lib/event_store_client/adapters/grpc/commands/streams/subscribe.rb

@@ -28,11 +28,9 @@ module EventStoreClient
 
               handler.call(result) if result
             end
-            Success(
-              retry_request do
-                service.read(request.new(options: options), metadata: metadata, &callback)
-              end
-            )
+            retry_request do
+              service.read(request.new(options: options), metadata: metadata, &callback)
+            end
           end
 
           private

data/lib/event_store_client/adapters/grpc/shared/streams/process_response.rb

@@ -5,8 +5,6 @@ module EventStoreClient
     module Shared
       module Streams
         class ProcessResponse
-          include Dry::Monads[:result]
-
           attr_reader :config
           private :config
 
@@ -19,15 +17,15 @@ module EventStoreClient
           # @param response [EventStore::Client::Streams::ReadResp]
           # @param skip_deserialization [Boolean]
           # @param skip_decryption [Boolean]
-          # @return [Dry::Monads::Success, Dry::Monads::Failure, nil]
+          # @return [EventStoreClient::DeserializedEvent, EventStore::Client::Streams::ReadResp, nil]
+          # @raise [EventStoreClient::StreamNotFoundError]
           def call(response, skip_deserialization, skip_decryption)
-            return Failure(:stream_not_found) if response.stream_not_found
-            return Success(response) if skip_deserialization
+            non_existing_stream = response.stream_not_found&.stream_identifier&.stream_name
+            raise StreamNotFoundError, non_existing_stream if non_existing_stream
+            return response if skip_deserialization
             return unless response.event&.event
 
-            Success(
-              config.mapper.deserialize(response.event.event, skip_decryption: skip_decryption)
-            )
+            config.mapper.deserialize(response.event.event, skip_decryption: skip_decryption)
           end
         end
       end

data/lib/event_store_client/adapters/grpc/shared/streams/process_responses.rb

@@ -5,8 +5,6 @@ module EventStoreClient
     module Shared
       module Streams
         class ProcessResponses
-          include Dry::Monads[:result]
-
           attr_reader :config
           private :config
 
@@ -19,20 +17,20 @@ module EventStoreClient
           # @param responses [Array<EventStore::Client::Streams::ReadResp>]
           # @param skip_deserialization [Boolean]
           # @param skip_decryption [Boolean]
-          # @return [Dry::Monads::Success, Dry::Monads::Failure]
+          # @return [Array<EventStoreClient::DeserializedEvent>, Array<EventStore::Client::Streams::ReadResp>]
+          # @raise [EventStoreClient::StreamNotFoundError]
           def call(responses, skip_deserialization, skip_decryption)
-            return Failure(:stream_not_found) if responses.first&.stream_not_found
-            return Success(responses) if skip_deserialization
+            non_existing_stream = responses.first&.stream_not_found&.stream_identifier&.stream_name
+            raise StreamNotFoundError, non_existing_stream if non_existing_stream
+            return responses if skip_deserialization
 
-            events =
-              responses.map do |response|
-                # It could be <EventStore::Client::Streams::ReadResp: last_stream_position: 39> for
-                # example. Such responses should be skipped. See generated files for more info.
-                next unless response.event&.event
+            responses.map do |response|
+              # It could be <EventStore::Client::Streams::ReadResp: last_stream_position: 39> for
+              # example. Such responses should be skipped. See generated files for more info.
+              next unless response.event&.event
 
-                config.mapper.deserialize(response.event.event, skip_decryption: skip_decryption)
-              end
-            Success(events.compact)
+              config.mapper.deserialize(response.event.event, skip_decryption: skip_decryption)
+            end.compact
           end
         end
       end

data/lib/event_store_client/adapters/grpc.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require 'grpc'
-require 'dry-monads'
 
 # Load all generated by google-protobuf files
 Dir[File.expand_path('grpc/generated/*.rb', __dir__)].each { |f| require f }

data/lib/event_store_client/deserialized_event.rb

@@ -7,8 +7,8 @@ module EventStoreClient
     InvalidDataError = Class.new(StandardError)
     private_constant :InvalidDataError
 
-    attr_reader :id, :type, :title, :data, :metadata, :stream_name, :stream_revision,
-                :prepare_position, :commit_position
+    attr_reader :id, :type, :title, :data, :metadata, :custom_metadata, :stream_name,
+                :stream_revision, :prepare_position, :commit_position
 
     # @args [Hash] opts
     # @option opts [Boolean] :skip_validation
@@ -34,6 +34,7 @@ module EventStoreClient
           'type' => @type,
           'content-type' => payload_content_type
         )
+      @custom_metadata = args[:custom_metadata] || {}
       @stream_name = args[:stream_name]
       @stream_revision = args[:stream_revision]
       @prepare_position = args[:prepare_position]
@@ -57,7 +58,7 @@ module EventStoreClient
     def ==(other)
       return false unless other.is_a?(EventStoreClient::DeserializedEvent)
 
-      to_h == other.to_h
+      meaningful_attrs(to_h) == meaningful_attrs(other.to_h)
     end
 
     # @return [Hash]
@@ -75,8 +76,25 @@ module EventStoreClient
       type == LINK_TYPE
     end
 
+    # Detect whether an event is a system event
+    # @return [Boolean]
+    def system?
+      return false unless type
+
+      type.start_with?('$')
+    end
+
     private
 
+    # When comparing two events - we drop commit_position and prepare_position from attributes list
+    # to compare. This is because their value are different when retrieving the same event from
+    # '$all' stream and from specific stream.
+    # @param hash [Hash]
+    # @return [Hash]
+    def meaningful_attrs(hash)
+      hash.delete_if { |key, _val| %i(commit_position prepare_position).include?(key) }
+    end
+
     def validate(data)
       return unless schema
 

data/lib/event_store_client/errors.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module EventStoreClient
+  class Error < StandardError
+    # @return [Hash]
+    def as_json(*)
+      to_h.transform_keys(&:to_s)
+    end
+
+    # @return [Hash]
+    def to_h
+      hash =
+        instance_variables.each_with_object({}) do |var, result|
+          key = var.to_s
+          key[0] = '' # remove @ sign
+          result[key.to_sym] = instance_variable_get(var)
+        end
+      hash[:message] = message
+      hash[:backtrace] = backtrace
+      hash
+    end
+  end
+
+  class StreamNotFoundError < Error
+    attr_reader :stream_name
+
+    # @param stream_name [String]
+    def initialize(stream_name)
+      @stream_name = stream_name
+      super("Stream #{stream_name.inspect} does not exist.")
+    end
+  end
+
+  class WrongExpectedVersionError < Error
+    attr_reader :wrong_expected_version, :caused_by
+
+    # @param wrong_expected_version [EventStore::Client::Streams::AppendResp::WrongExpectedVersion]
+    # @param caused_by [EventStoreClient::DeserializedEvent] an event on which
+    #   WrongExpectedVersionError error happened. It can be useful when appending array of events -
+    #   based on it you will know which events were appended and which weren't.
+    def initialize(wrong_expected_version, caused_by:)
+      @wrong_expected_version = wrong_expected_version
+      @caused_by = caused_by
+      super(user_friendly_message)
+    end
+
+    private
+
+    # @return [String]
+    def user_friendly_message
+      return expected_stream_exists if wrong_expected_version.expected_stream_exists
+      return expected_no_stream if wrong_expected_version.expected_no_stream
+      return current_no_stream if wrong_expected_version.current_no_stream
+      unless wrong_expected_version.expected_revision == wrong_expected_version.current_revision
+        return unmatched_stream_revision
+      end
+
+      # Unhandled case. Could happen if something else would be added to proto and I don't add it
+      # here.
+      self.class.to_s
+    end
+
+    # @return [String]
+    def expected_stream_exists
+      "Expected stream to exist, but it doesn't."
+    end
+
+    # @return [String]
+    def expected_no_stream
+      "Expected stream to be absent, but it actually exists."
+    end
+
+    # @return [String]
+    def current_no_stream
+      <<~TEXT.strip
+        Stream revision #{wrong_expected_version.expected_revision.inspect} is expected, but \
+        stream does not exist.
+      TEXT
+    end
+
+    # @return [String]
+    def unmatched_stream_revision
+      <<~TEXT.strip
+        Stream revision #{wrong_expected_version.expected_revision.inspect} is expected, but \
+        actual stream revision is #{wrong_expected_version.current_revision.inspect}.
+      TEXT
+    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
+end