event_store_client 1.4.9 → 2.0.1

data/docs/configuration.md

@@ -0,0 +1,83 @@
+# 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                                                                                                                                                                                                                              |
+|----------------------|--------------------------------------------------------------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| event_store_url      | String                                                                               | `'esdb://localhost:2113'`               | Connection string. See description of possible values below.                                                                                                                                                                            |
+| per_page             | Integer                                                                              | `20`                                    | Number of events to return in one response.                                                                                                                                                                                              |
+| mapper               | `EventStoreClient::Mapper::Default.new` or `EventStoreClient::Mapper::Encrypted.new` | `EventStoreClient::Mapper::Default.new` | An object that is responsible for serialization / deserialization and encryption / decryption of events.                                                                                                                                     |
+| default_event_class  | `DeserializedEvent` or any class, inherited from it                                  | `DeserializedEvent`                     | This class will be used during the deserialization process when deserializer fails to resolve an event's class from response.                                                                                                             |
+| logger               | `Logger`                                                                             | `nil`                                   | A logger that would log messages from `event_store_client` and `grpc` gems.                                                                                                                                                               |
+| skip_deserialization | Boolean                                                                              | `false`                                 | Whether to skip event deserialization using the given `mapper` setting. If you set it to `true` decryption will be skipped as well. It is useful when you want to defer deserialization and handle it later by yourself. |
+| skip_decryption      | Boolean                                                                              | `false`                                 | Whether to skip decrypting encrypted event payloads.                                                                                                                                                                                                       |
+
+## Connection string
+
+Connection string allows you to provide connection options and a set of nodes of your cluster to connect to.
+
+Structure:
+
+```
+protocol://[username:password@]node1[,node2,node3,...,nodeN]/?connectionOptions
+```
+
+### Protocol
+
+There are two possible values:
+
+- `esdb`. Currently no effect.
+- `esdb+discover`. `+discover` tells the client that your cluster is setup as [DNS discovery](https://developers.eventstore.com/server/v20.10/cluster.html#cluster-with-dns). This means that the client will perform a lookup of cluster members of the first node you provided in the connection string.
+
+Examples:
+```
+esdb://localhost:2113
+esdb+discover://localhost:2113
+```
+
+### Credentials
+
+You may provide a username and password to be used to connect to the EventStore DB. Only secure connections will use those credentials. Only credentials defined with first node will be used.
+
+Examples:
+
+```
+esdb://some-admin:some-password@localhost:2113
+esdb://some-admin:some-password@localhost:2113,localhost:2114
+```
+
+### Nodes
+
+At least one node should be defined in the connection string in order for the client to work properly. You may define as much nodes as you want. However, the behavior of the client may change depending on how many nodes you provided and whether you set the `+discover` flag.
+
+Possible behaviours:
+
+- One node is provided. E.g. `esdb://localhost:2113`. The client assumes this setup is a standalone server - no cluster discovery will be done.
+- One node and `+discover` flag is provided. E.g. `esdb+discover://localhost:2113`. The client assumes this setup is a cluster with DNS discover setup - cluster discovery will be done.
+- Two or more nodes are provided. E.g. `esdb://localhost:2113,localhost:2114,localhost:2115`. The client assumes this setup is a nodes cluster setup - cluster discovery will be done. If discovery of a node fails, the next node in the list will be picked, and so forth, in round-robin manner, until max discovery attempts number is reached.
+
+If you provide more than one node and set `+discover` flag - only the first node will be considered.
+
+### Connection options
+
+Connection options allows you to adjust parameters such as timeout, security, etc.
+
+Possible options:
+
+| name                 | value                                           | default value | description                                                                                                                                                                                                                                            |
+|----------------------|-------------------------------------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| tls                  | Boolean                                         | `true`        | Whether to use a secure connection                                                                                                                                                                                                                       |
+| tlsVerifyCert        | Boolean                                         | `false`       | Whether to verify a certificate                                                                                                                                                                                                                        |
+| tlsCAFile            | String                                          | `nil`         | A path to a certificate file (e.g. `ca.crt`). If you set the `tls` option to `true`, but didn't provide this option, the client  will try to automatically retrieve an X.509 certificate from the nodes.                                                   |
+| gossipTimeout        | Integer                                         | `200`         | Milliseconds. Discovery request timeout. Only useful when there are several nodes or when `+discover` flag is set.                                                                                                                                      |
+| discoverInterval     | Integer                                         | `100`         | Milliseconds. Interval between discovery attempts. Only useful when there are several nodes or when `+discover` flag is set.                                                                                                                            |
+| maxDiscoverAttempts  | Integer                                         | `10`          | Max attempts before giving up to find a suitable cluster member. Only useful when there are several nodes or when the `+discover` flag is set.                                                                                                             |
+| caLookupInterval     | Integer                                         | `100`         | Milliseconds. Interval between X.509 certificate lookup attempts. This option is useful when you set the`tls` option to true, but you didn't provide the `tlsCAFile` option. In this case the certificate will be retrieved using the Net::HTTP#peer_cert method. |
+| caLookupAttempts     | Integer                                         | `3`           | Number of attempts for X.509 certificate lookup. This option is useful when you set the `tls` option to true, but you didn't provide the `tlsCAFile` option. In this case the certificate will be retrieved using Net::HTTP#peer_cert method.                |
+| nodePreference       | `"leader"`, `"follower"` or `"readOnlyReplica"` | `"leader"`    | Set which state of cluster members is preferred. Only useful if you provided the `+discover` flag or defined several nodes in the connection string.                                                                                                           |
+| timeout              | Integer, `nil`                                  | `nil`         | Milliseconds. Defines how long to wait for a response before throwing an error. This option doesn't apply to subscriptions. If set to `nil` - `event_store_client` will be waiting for a response forever (if there is a connection at all).                |
+| grpcRetryAttempts    | Integer                                         | `3`           | Number of times to retry GRPC requests. Does not apply to discovery requests. Final number of requests in cases of error will be initial request + grpcRetryAttempts.                                                                                  |
+| grpcRetryInterval    | Integer                                         | `100`         | Milliseconds. Delay between GRPC requests. retries.                                                                                                                                                                                                      |
+| throwOnAppendFailure | Boolean                                         | `true`        | Defines if append requests should immediately raise an error. If set to `false`, request will be retried in case of a server error.                                                                                                                       |

data/docs/deleting_streams.md

@@ -0,0 +1,25 @@
+# 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.
+
+```ruby
+EventStoreClient.client.delete_stream('some-stream')
+```
+
+## Hard deleting streams
+
+A hard delete of a stream is permanent. You cannot append to the stream or recreate it. As such, you should generally soft delete streams unless you have a specific need to permanently delete the stream.
+
+```ruby
+EventStoreClient.client.hard_delete_stream('some-stream')
+```
+
+## User credentials
+
+You can provide user credentials to be used to delete the stream as follows. This will override the default credentials set on the connection.
+
+```ruby
+EventStoreClient.client.delete_stream('some-stream', credentials: { username: 'admin', password: 'changeit' })
+```

data/docs/encrypting_events.md

@@ -0,0 +1,84 @@
+# 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
+end
+```
+
+The Encrypted mapper uses the encryption key repository to encrypt data in your events according to the event definition.
+
+Here is the minimal repository interface for this to work.
+
+```ruby
+class DummyRepository
+  class Key
+    attr_accessor :iv, :cipher, :id
+    def initialize(id:, **)
+      @id = id
+    end
+  end
+
+  def find(user_id)
+    Key.new(id: user_id)
+  end
+
+  def encrypt(*)
+    'darthvader'
+  end
+
+  def decrypt(*)
+    { first_name: 'Anakin', last_name: 'Skywalker'}
+  end
+end
+```
+
+Now, having that, you only need to define the event encryption schema:
+
+```ruby
+class EncryptedEvent < EventStoreClient::DeserializedEvent
+  def schema
+    Dry::Schema.Params do
+      required(:user_id).value(:string)
+      required(:first_name).value(:string)
+      required(:last_name).value(:string)
+      required(:profession).value(:string)
+    end
+  end
+
+  def self.encryption_schema
+    {
+      key: ->(data) { data['user_id'] },
+      attributes: %i[first_name last_name email]
+    }
+  end
+end
+
+event = EncryptedEvent.new(
+  user_id: SecureRandom.uuid,
+  first_name: 'Anakin',
+  last_name: 'Skywalker',
+  profession: 'Jedi'
+)
+```
+
+When you publish this event, the eventstore will store this payload:
+
+```ruby
+{
+  'data' => {
+    'user_id' => 'dab48d26-e4f8-41fc-a9a8-59657e590716',
+    'first_name' => 'encrypted',
+    'last_name' => 'encrypted',
+    'profession' => 'Jedi',
+    'encrypted' => '2345l423lj1#$!lkj24f1'
+  },
+  type: 'EncryptedEvent'
+  metadata: { ... }
+}
+```

data/docs/linking_events.md

@@ -0,0 +1,149 @@
+# Linking events
+
+## Linking single event
+
+To create a link on an existing event, you need to have a stream name where you want to link that event to and you need to have an event, fetched from the database:
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+event = SomethingHappened.new(
+  id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened" }
+)
+
+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
+# 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
+```
+
+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
+```
+
+If you don't provide the `:resolve_link_tos` option, the "linked" event will be returned instead of the original one.
+
+## Linking multiple events
+
+You can provide an array of events to link to the target stream:
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+events =
+  3.times.map do
+    SomethingHappened.new(
+      id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened" }
+    )
+  end
+
+stream_name_1 = 'some-stream-1'
+stream_name_2 = 'some-stream-2'
+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
+# 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
+```
+
+## Handling concurrency
+
+When linking events to a stream you can supply a stream state or stream revision. Your client can use this to tell EventStoreDB what state or version you expect the stream to be in when you append. If the stream isn't in that state then an exception will be raised.
+
+For example if we try and link two records expecting both times that the stream doesn't exist we will get an exception on the second:
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+event1 = SomethingHappened.new(
+  type: 'some-event', data: {},
+)
+
+event2 = SomethingHappened.new(
+  type: 'some-event', data: {},
+)
+
+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
+
+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
+```
+
+There are three available stream states:
+
+- `:any`
+- `:no_stream`
+- `:stream_exists`
+
+This check can be used to implement optimistic concurrency. When you retrieve a stream from EventStoreDB, you take note of the current version number, then when you save it back you can determine if somebody else has modified the record in the meantime.
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+stream_name_1 = "some-stream-1$#{SecureRandom.uuid}"
+stream_name_2 = "some-stream-2$#{SecureRandom.uuid}"
+event1 = SomethingHappened.new(
+  type: 'some-event', data: {}
+)
+event2 = SomethingHappened.new(
+  type: 'some-event', data: {}
+)
+
+# Pre-create some events
+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
+# Get the revision number of latest event
+revision = EventStoreClient.client.read(stream_name_2).success.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
+EventStoreClient.client.link_to(stream_name_2, event2, options: { expected_revision: revision })
+```
+
+## User credentials
+
+You can provide user credentials to be used to append the data as follows. This will override the default credentials set on the connection.
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+event = SomethingHappened.new(
+  id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened" }
+)
+
+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
+# Link event from first stream into second stream
+result = EventStoreClient.client.link_to(stream_name_2, event, credentials: { username: 'admin', password: 'changeit' })
+```

data/docs/reading_events.md

@@ -0,0 +1,200 @@
+# Reading events
+
+## Reading from a stream
+
+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
+```
+
+### Request options customization
+
+You can provide a block to the `#read` method. Request options will be yielded right before the request, allowing you to set advanced options:
+
+```ruby
+EventStoreClient.client.read('some-stream') do |opts|
+  opts.control_option = EventStore::Client::Streams::ReadReq::Options::ControlOption.new(
+    compatibility: 1
+  )
+end
+```
+
+### max_count
+
+You can provide the `:max_count` option. This option determines how much records to return in a response:
+
+```ruby
+EventStoreClient.client.read('some-stream', options: { max_count: 1000 })
+```
+
+### resolve_link_tos
+
+When using projections to create new events you can set whether the generated events are pointers to existing events. Setting this value to `true` tells EventStoreDB to return the event as well as the event linking to it.
+
+```ruby
+EventStoreClient.client.read('some-stream', options: { resolve_link_tos: true })
+```
+
+### from_revision
+
+You can define from which revision number you would like to start to read events:
+
+```ruby
+EventStoreClient.client.read('some-stream', options: { from_revision: 2 })
+```
+
+Acceptable values are: number, `:start` and `:end`
+
+### direction
+
+As well as being able to read a stream forwards you can also go backwards. This can be achieved by providing the `:direction` option:
+
+```ruby
+EventStoreClient.client.read('some-stream', options: { direction: 'Backwards', from_revision: :end })
+```
+
+## Checking if the stream exists
+
+In case a stream with given name does not exist, `Dry::Monads::Failure` will be returned with value `:stream_not_found`:
+
+```ruby
+result = EventStoreClient.client.read('non-existing-stream')
+# => Failure(:stream_not_found)
+result.failure?
+# => true
+result.failure
+# => :stream_not_found
+```
+
+## Reading from the $all stream
+
+Simply supply `"$all"` as the stream name in `#read`:
+
+```ruby
+EventStoreClient.client.read('$all')
+```
+
+The only difference in reading from `$all` vs reading from specific stream is that you should provide `:from_position` option instead `:from_revision` in order to define a position from which to read:
+
+```ruby
+EventStoreClient.client.read('$all', options: { from_position: :start })
+EventStoreClient.client.read('$all', options: { from_position: :end, direction: 'Backwards' })
+EventStoreClient.client.read('$all', options: { from_position: { commit_position: 9023, prepare_position: 9023 } })
+```
+
+## Result deserialization
+
+If you would like to skip deserialization of the `#read` result, you should use the `:skip_deserialization` argument. This way you will receive the result from EventStore DB as is, including system events, etc:
+
+```ruby
+EventStoreClient.client.read('some-stream', skip_deserialization: true)
+# => Success([<EventStore::Client::Streams::ReadResp ...>])
+```
+
+## Filtering
+
+The filtering feature is only available for the`$all` stream.
+
+Retrieve events from streams with name starting with `some-stream`:
+
+```ruby
+result =
+  EventStoreClient.client.read('$all', options: { filter: { stream_identifier: { prefix: ['some-stream'] } } })
+if result.success?
+  result.success.each do |e|
+    # iterate through events
+  end
+end
+```
+
+Retrieve events with name starting with `some-event`:
+
+```ruby
+result =
+  EventStoreClient.client.read('$all', options: { event_type: { prefix: ['some-event'] } })
+if result.success?
+  result.success.each do |e|
+    # iterate through events
+  end
+end
+```
+
+Retrieving events from stream `some-stream-1` and `some-stream-2`:
+
+```ruby
+result =
+  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
+end
+```
+
+## Pagination
+
+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
+  end
+end
+
+EventStoreClient.client.read_paginated('$all').each do |result|
+  if result.success?
+    result.success.each do |event|
+      # do something with event
+    end
+  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
+  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
+  end
+end
+```
+
+Note: for some reason when paginating the `$all` stream, EventStoreDB returns duplicate records from page to page (first event of `page N` = last event of `page N - 1`).
+## User credentials
+
+You can provide user credentials to be used to read the data as follows. This will override the default credentials set on the connection.
+
+```ruby
+EventStoreClient.client.read('some-stream', credentials: { username: 'admin', password: 'changeit' })
+```