event_store_client 2.3.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb40cc642961ff384a83e16559b383ad86a97e5fe06874eb38a040a7976d2fc2
-  data.tar.gz: 521ed3605f2378177aa9c5d573eaec83d48243f66936b2384ba3c751f46c505a
+  metadata.gz: 82b73db66b7feef1d17e010f9e410476ab900bd6b137af03ee57106f2aefea6b
+  data.tar.gz: 926d40bfa51a581de7f9e7942d7092e4e0f0d7c23d1c932cb689946ef3a690f5
 SHA512:
-  metadata.gz: 0b9d4283f8f67c20f67b49a9c408d0d9ffb0efe2ecc26f3f0c3781c285612ea8abbc4acfc15e50762cb8f085df5944734bcefab1374e9c0ee1d025f9eb3c200e
-  data.tar.gz: 9751686541fcfb576b8d582d07d3c9de5cd83f5f44129bb9302751ac116a59a305133efa7bd98d81beb8e96600649700b5d9666c05a63a617bc85bb8f6c16710
+  metadata.gz: 59dc478314bb1a15895dfe851248d6c1b62a381c26d03c8f7d1d18465a1407a28f007a959f2c655222b54dd310929df5430528125c3c97221393e3ce3b937256
+  data.tar.gz: bb92b9f60639f5d0552c69b493e0e6dbb8e6985e89d7f4f78de6df45c12e6098554e7de13f8880e45fd84a8ddc8528eec778a78715ebd591fcc5c331709bea4a

data/README.md

@@ -9,7 +9,7 @@ An easy-to use GRPC API client for connecting ruby applications with [EventStore
 
 `event_store_client` gem requires:
 
-- ruby 2.7 or newer.
+- ruby 3.0 or newer.
 - EventstoreDB version `>= "20.*"`.
 
 ## Installation

data/docs/appending_events.md

@@ -1,6 +1,4 @@
-# @title Appending events
-
-# Append your first event
+# Appending Events
 
 ## Append your first event
 
@@ -14,11 +12,11 @@ event = SomethingHappened.new(
   id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened" }
 )
 
-result = EventStoreClient.client.append_to_stream('some-stream', event)
-# if event was appended successfully
-if result.success?
-  # result.success => <EventStore::Client::Streams::AppendResp>
-else # event was not appended, result.failure? => true
+begin
+  EventStoreClient.client.append_to_stream('some-stream', event)
+  # => EventStore::Client::Streams::AppendResp
+rescue EventStoreClient::WrongExpectedVersionError => e
+  puts e.message
 end
 ```
 
@@ -37,15 +35,13 @@ event2 = SomethingHappened.new(
   id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened 2" }
 )
 
-results = EventStoreClient.client.append_to_stream('some-stream', [event1, event2])
-results.each do |result|
-  # Event was appended successfully
-  if result.success?
-    # result.success => <EventStore::Client::Streams::AppendResp>
-  else # event was not appended, result.failure? => true
-  end
+begin
+  EventStoreClient.client.append_to_stream('some-stream', [event1, event2])
+  # => Array<EventStore::Client::Streams::AppendResp>
+rescue EventStoreClient::WrongExpectedVersionError => e
+  puts e.message
+  puts e.caused_by # event which caused the error
 end
-
 ```
 
 ## Working with EventStoreClient::DeserializedEvent
@@ -62,8 +58,8 @@ EventStoreClient::DeserializedEvent.new(
   type: 'some-event-name',
   # Event data. Optional. Will default to `{}` (empty hash) if omitted
   data: { foo: :bar },
-  # Optional. Defaults to `{ 'type' => event_name_you_provided, 'content-type' => 'application/json' }`
-  metadata: {}
+  # Optional. You can put here any value which is not supposed to be present in data.
+  custom_metadata: {}
 )
 ```
 
@@ -128,13 +124,11 @@ event1 = SomethingHappened.new(
 event2 = SomethingHappened.new(
   type: 'some-event', data: {}
 )
-event3 = SomethingHappened.new(
-  type: 'some-event', data: {}
-)
+
 # Pre-populate stream with some event
 EventStoreClient.client.append_to_stream(stream_name, event1)
 # Get the revision number of latest event
-revision = EventStoreClient.client.read(stream_name).success.last.stream_revision
+revision = EventStoreClient.client.read(stream_name).last.stream_revision
 # Expected revision matches => will succeed
 EventStoreClient.client.append_to_stream(stream_name, event2, options: { expected_revision: revision })
 # Will fail with revisions mismatch error

data/docs/catch_up_subscriptions.md

@@ -1,6 +1,4 @@
-# @title Catch-up subscriptions
-
-# Catch-up subscriptions
+# Catch-up Subscriptions
 
 Subscriptions allow you to subscribe to a stream and receive notifications about new events added to the stream.
 
@@ -17,13 +15,8 @@ When you need to process all the events in the store, including historical event
 The most simple stream subscription looks like the following:
 
 ```ruby
-handler = proc do |result|
-  if result.success?
-    event = result.success # retrieve a result
-    # ... do something with event
-  else # result.failure?
-    puts result.failure # prints error
-  end
+handler = proc do |event|
+  p event
 end
 EventStoreClient.client.subscribe_to_stream('some-stream', handler: handler)
 ```
@@ -32,13 +25,8 @@ The provided handler will be called for every event in the stream. You may provi
 
 ```ruby
 class SomeStreamHandler
-  def call(result)
-    if result.success?
-      event = result.success # retrieve a result
-      # ... do something with event
-    else # result.failure?
-      puts result.failure # prints error
-    end
+  def call(event)
+    p event
   end
 end
 EventStoreClient.client.subscribe_to_stream('some-stream', handler: SomeStreamHandler.new)
@@ -49,13 +37,8 @@ EventStoreClient.client.subscribe_to_stream('some-stream', handler: SomeStreamHa
 Subscribing to `$all` is much the same as subscribing to a single stream. The handler will be called for every event appended after the starting position.
 
 ```ruby
-handler = proc do |result|
-  if result.success?
-    event = result.success # retrieve a result
-    # ... do something with event
-  else # result.failure?
-    puts result.failure # prints error
-  end
+handler = proc do |event|
+  p event
 end
 EventStoreClient.client.subscribe_to_all(handler: handler)
 ```
@@ -75,7 +58,7 @@ To subscribe to a stream from a specific position, you need to provide a _stream
 The following subscribes to the stream `some-stream` at position `20`, this means that events `21` and onward will be handled:
 
 ```ruby
-EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |res| }, options: { from_revision: 20 })
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |event| }, options: { from_revision: 20 })
 ```
 
 ### Subscribing to $all
@@ -85,7 +68,7 @@ Subscribing to the `$all` stream is much like subscribing to a regular stream. T
 The following `$all` subscription will subscribe from the event after the one at commit position `1056` and prepare position `1056`:
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { from_position: { commit_position: 1056, prepare_position: 1056 } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { from_position: { commit_position: 1056, prepare_position: 1056 } })
 ```
 
 Please note that the given position needs to be a legitimate position in the `$all` stream.
@@ -95,13 +78,13 @@ Please note that the given position needs to be a legitimate position in the `$a
 You can subscribe to a stream to get live updates by subscribing to the end of the stream:
 
 ```ruby
-EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |res| }, options: { from_revision: :end })
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |event| }, options: { from_revision: :end })
 ```
 
 And the same works with `$all` :
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { from_position: :end })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { from_position: :end })
 ```
 
 This won't read through the history of the stream, but will rather notify the handler when a new event appears in the respective stream.
@@ -115,7 +98,7 @@ Link-to events point to events in other streams in EventStoreDB. These are gener
 When reading a stream you can specify whether to resolve link-to's or not. By default, link-to events are not resolved. You can change this behaviour by setting the `resolve_link_tos` option to `true`:
 
 ```ruby
-EventStoreClient.client.subscribe_to_stream('$et-myEventType', handler: proc { |res| }, options: { resolve_link_tos: true })
+EventStoreClient.client.subscribe_to_stream('$et-myEventType', handler: proc { |event| }, options: { resolve_link_tos: true })
 ```
 
 ## Handling subscription drops
@@ -124,14 +107,9 @@ An application, which hosts the subscription, can go offline for a period of tim
 
 ```ruby
 checkpoint = :start
-handler = proc do |result|
-  if result.success?
-    event = result.success
-    handle_event(event)
-    checkpoint = event.stream_revision
-  else
-    # do something in case of error
-  end
+handler = proc do |event|
+  handle_event(event)
+  checkpoint = event.stream_revision
 end
 
 EventStoreClient.client.subscribe_to_stream('some-stream', handler: handler, options: { from_revision: checkpoint })
@@ -141,14 +119,9 @@ When subscribed to `$all` you want to keep the position of the event in the `$al
 
 ```ruby
 checkpoint = :start
-handler = proc do |result|
-  if result.success?
-    event = result.success
-    handle_event(event)
-    checkpoint = { prepare_position: event.prepare_position, commit_position: event.commit_position }
-  else
-    # do something in case of error
-  end
+handler = proc do |event|
+  handle_event(event)
+  checkpoint = { prepare_position: event.prepare_position, commit_position: event.commit_position }
 end
 
 EventStoreClient.client.subscribe_to_all(handler: handler, options: { from_position: checkpoint })
@@ -156,28 +129,20 @@ EventStoreClient.client.subscribe_to_all(handler: handler, options: { from_posit
 
 ### Checkpoints and other responses
 
-By default `event_store_client` will skip such EventStore DB responses as checkpoints, confirmations, etc. If you would like to handle them in the subscription handler, you can provide the`skip_deserialization` keyword argument, and then handle deserialization by yourself:
+By default `event_store_client` will skip such EventStore DB responses as checkpoints, confirmations, etc. If you would like to handle them in the subscription handler, you can provide the `skip_deserialization` keyword argument, and then handle deserialization by yourself:
 
 ```ruby
 checkpoint = :start
-handler = proc do |result|
-  if result.success?
-    response = result.success
-    if response.checkpoint
-      handle_checkpoint(response.checkpoint)
-    else
-      result = EventStoreClient::GRPC::Shared::Streams::ProcessResponse.new.call(
-        response,
-        false,
-        false
-      )
-      if result&.success?
-        event = result.success
-        handle_event(event)
-      end
-    end
+handler = proc do |raw_response|
+  if raw_response.checkpoint
+    handle_checkpoint(raw_response.checkpoint)
   else
-    # do something in case of error
+    event = EventStoreClient::GRPC::Shared::Streams::ProcessResponse.new(config: EventStoreClient.config).call(
+      raw_response,
+      false,
+      false
+    )
+    handle_event(event) if event
   end
 end
 
@@ -191,7 +156,7 @@ The user creating a subscription must have read access to the stream it's subscr
 The code below shows how you can provide user credentials for a subscription. When you specify subscription credentials explicitly, it will override the default credentials set for the client. If you don't specify any credentials, the client will use the credentials specified for the client, if you specified those.
 
 ```ruby
-EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |res| }, credentials: { username: 'admin', password: 'changeit' })
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: proc { |event| }, credentials: { username: 'admin', password: 'changeit' })
 ```
 
 ## Server-side filtering
@@ -203,7 +168,7 @@ You can filter by event type or stream name using either a regular expression or
 A simple stream prefix filter looks like this:
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { stream_identifier: { prefix: ['test-', 'other-'] } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { stream_identifier: { prefix: ['test-', 'other-'] } } })
 ```
 
 ### Filtering out system events
@@ -211,7 +176,7 @@ EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { fil
 There are a number of events in EventStoreDB called system events. These are prefixed with a `$` and under most circumstances you won't care about these. They can be filtered out by event type.
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { event_type: { regex: /^[^\$].*/.to_s } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { event_type: { regex: /^[^\$].*/.to_s } } })
 ```
 
 ### Filtering by event type
@@ -223,7 +188,7 @@ If you only want to subscribe to events of a given type there are two options. Y
 This will only subscribe to events with a type that begin with `customer-`:
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { event_type: { prefix: ['customer-'] } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { event_type: { prefix: ['customer-'] } } })
 ```
 
 #### Filtering by regular expression
@@ -231,7 +196,7 @@ EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { fil
 If you want to subscribe to multiple event types then it might be better to provide a regular expression. This will subscribe to any event that begins with `user` or `company`:
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { event_type: { regex: '^user|^company' } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { event_type: { regex: '^user|^company' } } })
 ```
 
 ### Filtering by stream name
@@ -243,7 +208,7 @@ If you only want to subscribe to a stream with a given name there are two option
 This will only subscribe to all streams with a name that begins with `user-`:
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { stream_identifier: { prefix: ['user-'] } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { stream_identifier: { prefix: ['user-'] } } })
 ```
 
 #### Filtering by regular expression
@@ -251,5 +216,5 @@ EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { fil
 If you want to subscribe to multiple streams then it might be better to provide a regular expression.
 
 ```ruby
-EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { stream_identifier: { regex: '^account|^savings' } } })
+EventStoreClient.client.subscribe_to_all(handler: proc { |event| }, options: { filter: { stream_identifier: { regex: '^account|^savings' } } })
 ```

data/docs/configuration.md

@@ -1,9 +1,5 @@
-# @title Configuration
-
 # Configuration
 
-Currently only one setup is supported. For example, you can't configure a connection to multiple clusters.
-
 Configuration options:
 
 | name                 | value                                                                                | default value                                                                                                                     | description                                                                                                                                                                                                                                           |
@@ -30,9 +26,9 @@ end
 the resulting `channel_args` value will be
 
 ```ruby
-{ 
-  "grpc.min_reconnect_backoff_ms" => 200, 
-  "grpc.max_reconnect_backoff_ms" => 100, 
+{
+  "grpc.min_reconnect_backoff_ms" => 200,
+  "grpc.max_reconnect_backoff_ms" => 100,
   "grpc.initial_reconnect_backoff_ms" => 100
 }
 ```
@@ -41,7 +37,7 @@ This behaviour is intentional. So, if you want to override them all - you should
 
 ```ruby
 EventStoreClient.configure do |config|
-  config.channel_args = { 
+  config.channel_args = {
     'grpc.min_reconnect_backoff_ms' => 500,
     'grpc.max_reconnect_backoff_ms' => 500,
     'grpc.initial_reconnect_backoff_ms' => 500
@@ -141,7 +137,7 @@ EventStoreClient.configure(name: :es_db_1) do |config|
 end
 EventStoreClient.configure(name: :es_db_2) do |config|
   # adjust your second config here
-  config.eventstore_url = 'esdb://localhost:2114' 
+  config.eventstore_url = 'esdb://localhost:2114'
 end
 ```
 
@@ -164,7 +160,7 @@ Setup your default config:
 ```ruby
 EventStoreClient.configure do |config|
   # config goes here
-  config.eventstore_url = 'esdb://localhost:2113' 
+  config.eventstore_url = 'esdb://localhost:2113'
 end
 ```
 

data/docs/deleting_streams.md

@@ -1,10 +1,8 @@
-# @title Deleting streams
-
-# Deleting streams
+# Deleting Streams
 
 ## Soft deleting streams
 
-When you read a soft deleted stream, the read returns `:stream_not_found` or 404 result. After deleting the stream, you are able to append to it again, continuing from where it left off.
+When you read a soft deleted stream, the read raises `EventStoreClient::StreamNotFoundError` error. After deleting the stream, you are able to append to it again, continuing from where it left off.
 
 ```ruby
 EventStoreClient.client.delete_stream('some-stream')
@@ -25,3 +23,15 @@ You can provide user credentials to be used to delete the stream as follows. Thi
 ```ruby
 EventStoreClient.client.delete_stream('some-stream', credentials: { username: 'admin', password: 'changeit' })
 ```
+
+## Possible errors during stream deletion
+
+If you try to delete non-existing stream, or if you provided `:expected_revision` option with a value which doesn't match current stream's state - `EventStoreClient::StreamDeletionError` error will be raised:
+
+```ruby
+begin
+  EventStoreClient.client.delete_stream('non-existing-stream')
+rescue => e
+  puts e.message
+end
+```

data/docs/encrypting_events.md

@@ -1,15 +1,11 @@
-# @title Encrypting events
-
-# Encrypting events
+# Encrypting Events
 
 To encrypt/decrypt events payload, you can use an encrypted mapper.
 
 
 ```ruby
-mapper = EventStoreClient::Mapper::Encrypted.new(key_repository)
-
 EventStoreClient.configure do |config|
-  config.mapper = mapper
+  config.mapper = EventStoreClient::Mapper::Encrypted.new(key_repository, config: config)
 end
 ```
 

data/docs/linking_events.md

@@ -1,6 +1,4 @@
-# @title Linking events
-
-# Linking events
+# Linking Events
 
 ## Linking single event
 
@@ -18,18 +16,16 @@ stream_name_1 = 'some-stream-1'
 stream_name_2 = 'some-stream-2'
 EventStoreClient.client.append_to_stream(stream_name_1, event)
 # Get persisted event
-event = EventStoreClient.client.read(stream_name_1).success.first
+event = EventStoreClient.client.read(stream_name_1).first
 # Link event from first stream into second stream
-result = EventStoreClient.client.link_to(stream_name_2, event)
-if result.success? # Event was successfully linked
-else # event was not linked, result.failure? => true
-end
+EventStoreClient.client.link_to(stream_name_2, event)
+# => EventStore::Client::Streams::AppendResp
 ```
 
 The linked event can later be fetched by providing the `:resolve_link_tos` option when reading from the stream:
 
 ```ruby
-EventStoreClient.client.read('some-stream-2', options: { resolve_link_tos: true }).success
+EventStoreClient.client.read('some-stream-2', options: { resolve_link_tos: true })
 ```
 
 If you don't provide the `:resolve_link_tos` option, the "linked" event will be returned instead of the original one.
@@ -55,14 +51,10 @@ events.each do |event|
   EventStoreClient.client.append_to_stream(stream_name_1, event)
 end
 # Get persisted events
-events = EventStoreClient.client.read(stream_name_1).success
+events = EventStoreClient.client.read(stream_name_1)
 # Link events from first stream into second stream one by one
-results = EventStoreClient.client.link_to(stream_name_2, events)
-results.each do |result|
-  if result.success? # Event was successfully linked
-  else # event was not linked, result.failure? => true
-  end
-end
+EventStoreClient.client.link_to(stream_name_2, events)
+# => Array<EventStore::Client::Streams::AppendResp>
 ```
 
 ## Handling concurrency
@@ -87,11 +79,13 @@ stream_name_1 = "some-stream-1$#{SecureRandom.uuid}"
 stream_name_2 = "some-stream-2$#{SecureRandom.uuid}"
 
 EventStoreClient.client.append_to_stream(stream_name_1, [event1, event2])
-events = EventStoreClient.client.read(stream_name_1).success
+events = EventStoreClient.client.read(stream_name_1)
 
-results = EventStoreClient.client.link_to(stream_name_2, events, options: { expected_revision: :no_stream })
-results[0].success? # => true
-results[1].success? # => false because second request tries to link the event with `:no_stream` expected revision
+begin
+  EventStoreClient.client.link_to(stream_name_2, events, options: { expected_revision: :no_stream })
+rescue EventStoreClient::WrongExpectedVersionError => e
+  puts e.message
+end
 ```
 
 There are three available stream states:
@@ -119,13 +113,13 @@ event2 = SomethingHappened.new(
 EventStoreClient.client.append_to_stream(stream_name_1, event1)
 EventStoreClient.client.append_to_stream(stream_name_2, event2)
 # Load events from DB
-event1 = EventStoreClient.client.read(stream_name_1).success.first
-event2 = EventStoreClient.client.read(stream_name_2).success.first
+event1 = EventStoreClient.client.read(stream_name_1).first
+event2 = EventStoreClient.client.read(stream_name_2).first
 # Get the revision number of latest event
-revision = EventStoreClient.client.read(stream_name_2).success.last.stream_revision
+revision = EventStoreClient.client.read(stream_name_2).last.stream_revision
 # Expected revision matches => will succeed
 EventStoreClient.client.link_to(stream_name_2, event1, options: { expected_revision: revision })
-# Will fail with revisions mismatch error
+# Will fail with EventStoreClient::WrongExpectedVersionError error due to revisions mismatch
 EventStoreClient.client.link_to(stream_name_2, event2, options: { expected_revision: revision })
 ```
 
@@ -145,7 +139,7 @@ stream_name_1 = 'some-stream-1'
 stream_name_2 = 'some-stream-2'
 EventStoreClient.client.append_to_stream(stream_name_1, event)
 # Get persisted event
-event = EventStoreClient.client.read(stream_name_1).success.first
+event = EventStoreClient.client.read(stream_name_1).first
 # Link event from first stream into second stream
-result = EventStoreClient.client.link_to(stream_name_2, event, credentials: { username: 'admin', password: 'changeit' })
+EventStoreClient.client.link_to(stream_name_2, event, credentials: { username: 'admin', password: 'changeit' })
 ```