event_store_client 1.4.9 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a08c9715141340d0ecea4be89e5843fdfeb743bf0e24388801efe240d7d1119b
-  data.tar.gz: ec61b28b753e74d652af34de20dd2047c739b33267490674498fbde4d277e444
+  metadata.gz: 171c9a5524c70a76dacc682fafd219139c4e845c997b59aa3dd26ea63851bd84
+  data.tar.gz: ff53343140523967227696e5cdca580ce7dd8d1a3ab750ac88438d7bb79808b7
 SHA512:
-  metadata.gz: e3a927092a217039a2423d1f3aa333d078216f29ab1c09040d142818edc2b3563ddd6cc83e5718370451eb0c9a0e260c0b272e248c98c413880a72968f9cf82e
-  data.tar.gz: 48f091d550b2d326665896e6ca4fa86e7a9af09dbb314adc6333c7b0265d323172159fb0f462f48d761f9e044bb683b8b472203b3720cbb8fe2e5af419925209
+  metadata.gz: 16d7f5ac50fe26de21c289ea236543f96636b5369551724b4284f4f8b3b88de9cf3ab2c5c15df49796ebec7b0129e9c361102d1b6a735c8cafd7c18ed9a4ef7a
+  data.tar.gz: fda744bf5c8c5bf0c03377e02e303fefe53bfea4ce0abb41923507bc515d9c6d45f0a7966386268a9ac70d58d430b98c5a7f90fb4729f4788f629f16f3719ea3

data/README.md

@@ -3,19 +3,20 @@
 
 # EventStoreClient
 
-An easy-to use API client for connecting ruby applications with [EventStoreDB](https://eventstore.com/)
+An easy-to use GRPC API client for connecting ruby applications with [EventStoreDB](https://eventstore.com/).
 
-## Supported adapters
+## Requirements
 
-- [GRPC](https://github.com/yousty/event_store_client/tree/master/lib/event_store_client/adapters/grpc/README.md) - default
-- [HTTP](https://github.com/yousty/event_store_client/tree/master/lib/event_store_client/adapters/http/README.md) - Deprecated
-- InMemory - for testing
+`event_store_client` gem requires:
+
+- ruby 2.7 or newer.
+- EventstoreDB version `>= "20.*"`.
 
 ## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'event_store_client', '~> 1.0'
+gem 'event_store_client'
 ```
 
 And then execute:
@@ -33,159 +34,43 @@ $ gem install event_store_client
 Before you start, make sure you are connecting to a running EventStoreDB instance. For a detailed guide see:
 [EventStoreServerSetup](https://github.com/yousty/event_store_client/blob/master/docs/eventstore_server_setup.md)
 
-### Create Dummy event and dummy Handler
-
-To test out the behavior, you'll need a sample event and event handler to work with:
-
-```ruby
-
-require 'securerandom'
-
-class SomethingHappened < EventStoreClient::DeserializedEvent
-  def schema
-    Dry::Schema.Params do
-      required(:user_id).value(:string)
-      required(:title).value(:string)
-    end
-  end
-end
-
-event = SomethingHappened.new(
-  data: { user_id: SecureRandom.uuid, title: "Something happened" },
-)
-```
-
-Now create a handler. It can be anything, which responds to a `call` method
-with an event being passed as an argument.
-
-```ruby
-class DummyHandler
-  def call(event)
-    puts "Handled #{event.class.name}"
-  end
-end
-```
-
-
-```ruby
-
-require 'event_store_client'
-require "event_store_client/adapters/grpc"
-
-EventStoreClient.configure do |config|
-  config.eventstore_url = ENV['EVENTSTORE_URL']
-  config.eventstore_user = ENV['EVENTSTORE_USER']
-  config.eventstore_password = ENV['EVENTSTORE_PASSWORD']
-  config.verify_ssl = false # remove this line if your server does have the host verified
-end
-
-event_store = EventStoreClient::Client.new
-
-event_store.subscribe(
-  DummyHandler.new,
-  to: [SomethingHappened]
-)
-
-event_store.listen
-```
-
-## Features
-
-## Basic Usage
-
-The main interface allows for actions listed below which is enough for basic useage.
-The actual adapter allows for more actions. Contributions as always welcome!
-
-```ruby
-# Publishing to a stream
-event_store.publish(stream: 'newstream', events: [event])
-
-# Reading from a stream
-events = event_store.read('newstream').value!
+See documentation chapters for the usage reference:
 
-# Reading all events from a stream
-events = event_store.read('newstream', options: { all: true }).value! #default 'false'
+- [Configuration](docs/configuration.md)
+- [Appending events](docs/appending_events.md)
+- [Reading events](docs/reading_events.md)
+- [Catch-up subscriptions](docs/catch_up_subscriptions.md)
+- [Linking events](docs/linking_events.md)
+- [Deleting streams](docs/deleting_streams.md)
+- [Encrypting events](docs/encrypting_events.md)
 
-# Linking existing events to a new stream
-event_store.link_to(stream_name, events)
-
-# Subscribing to events
-event_store.subscribe(DummyHandler.new, to: [SomethingHappened])
+## Contributing
 
-# Listening to new events for all registered subscriptions
-event_store.listen
+Do you want to contribute? Welcome!
 
-# In the new terminal session publish some events
-events = (1..10).map { event }
-event_store.publish(stream: 'newstream', events: events)
-# .... wait a little bit ... Your handler should be called for every single event you publish
-```
+1. Fork repository
+2. Create Issue
+3. Create PR ;)
 
-### Extended usage
+### Re-generating GRPC files from Proto
 
-You can get access to more features by calling the adapter directly, for example:
+If you need to re-generate GRPC files from [Proto](https://github.com/EventStore/EventStore/tree/master/src/Protos/Grpc) files - there is a tool to do it. Just run this command:
 
+```shell
+bin/rebuild_protos
 ```
-event_store.connection.delete_stream(stream)
-event_store.connection.tombstone_stream(stream)
-```
-
-See the adapters method list for the possible usage.
 
-- [HTTP](https://github.com/yousty/event_store_client/blob/master/lib/event_store_client/adapters/http/client.rb)
-- [GRPC](https://github.com/yousty/event_store_client/blob/master/lib/event_store_client/adapters/grpc/client.rb)
+### Running tests and development console
 
-### Configuration
+You will have to install Docker first. It is needed to run EventStore DB. You can run EventStore DB with this command:
 
-There are several configuration options you can pass to customize your client's instance.
-All the config options can be passed the same way:
-
-```ruby
-EventStoreClient.configure do |config|
-  config.adapter = :grpc
-end
+```shell
+docker-compose -f docker-compose-cluster.yml up
 ```
 
-| name        | value           | default   | description |
-|:-------------:|:-------------:|:-----:|:-------------:|
-| adapter      | `:grpc`, `:http` or `:in_memory` | `:grpc` | different ways to connect with an event_store_db. The in_memory is a mock server useful for testing |
-| verify_ssl   | Boolean      | true | Useful for self-signed certificates (Kubernetes, local development) |
-| error_handler | Any callable ruby object | EvenStoreClient::ErrorHandler | You can pass a custom error handler for reacting on event_handler errors.|
-| eventstore_url| String| 'http://localhost:2113'| An url for the server instance|
-| user| String| 'admin' | a user used to connect the application with the server|
-| password| String| 'changeit'| a password used to connect the application with the server|
-| per_page| Integer| 20 | a batch size for events subscriptions |
-| service_name| String| 'default' | a prefix (namespace) added to the subscriptions names|
-| mapper| `Mapper::Default` or `Mapper::Encrypted`| `Mapper::Default.new` | an engine used to parse events.
-
-## Event Mappers
-
-At the moment we offer two types of mappers:
-
-- default
-- encrypted
-
-### Default Mapper
-
-This is used out of the box. It just translates the EventClass defined in your application to
-Event parsable by event_store and the other way around.
-
-### Encrypted Mapper
-
-This is implemented to match GDPR requirements. It allows you to encrypt any event using your
-encryption_key repository. For the detailed guide see the: [Encrypting Events](https://github.com/yousty/event_store_client/blob/master/docs/encrypting_events.md).
-
-## Contributing
-
-Do you want to contribute? Welcome!
-
-1. Fork repository
-2. Create Issue
-3. Create PR ;)
-
-For running the client in the dev mode, see: [Development Guide](https://github.com/yousty/event_store_client/blob/master/docs/eventstore_server_setup.md)
+Now you can enter the dev console by running `bin/console` or run tests by running `rspec` command.
 
-### Publishing new version
+### Publishing a new version
 
 1. Push commit with updated `version.rb` file to the `release` branch. The new version will be automatically pushed to [rubygems](https://rubygems.org).
 2. Create release on github including change log.

data/docs/appending_events.md

@@ -0,0 +1,155 @@
+# Append your first event
+
+## Append your first event
+
+The simplest way to append an event to EventStoreDB is to create an `EventStoreClient::DeserializedEvent` object and call the `#append_to_stream` method.
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+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
+end
+```
+
+## Appending multiple events
+
+You can pass an array of events to the `#append_to_stream` method. This way events will be appended one-by-one. On each iteration `revision` will be incremented by 1. In case if any of requests fails - all further append requests will be canceled.
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+event1 = SomethingHappened.new(
+  id: SecureRandom.uuid, type: 'some-event', data: { user_id: SecureRandom.uuid, title: "Something happened 1" }
+)
+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
+end
+
+```
+
+## Working with EventStoreClient::DeserializedEvent
+
+When appending events to EventStoreDB they must first all be wrapped in an `EventStoreClient::DeserializedEvent` object. This allows you to specify the content of the event and the type of event.
+
+A sample of creating an event:
+
+```ruby
+EventStoreClient::DeserializedEvent.new(
+  # ID of event. Optional. If omitted, its value is generated using `SecureRandom.uuid`
+  id: SecureRandom.uuid,
+  # Event name. Optional. If omitted, its value will be generated using `self.class.to_s`
+  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: {}
+)
+```
+
+### Duplicated event id
+
+If two events with the same id are appended to the same stream in quick succession EventStoreDB will only append one copy of the event to the stream.
+
+```ruby
+class SomethingHappened < EventStoreClient::DeserializedEvent
+end
+
+event = SomethingHappened.new(
+  id: SecureRandom.uuid, type: 'some-event', data: {},
+)
+EventStoreClient.client.append_to_stream('some-stream', event)
+# Attempt to append the same event again. Will return the same result as for previous call
+EventStoreClient.client.append_to_stream('some-stream', event)
+```
+
+
+## Handling concurrency
+
+When appending 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 thrown.
+
+For example if we try to and append 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 = "some-stream$#{SecureRandom.uuid}"
+
+EventStoreClient.client.append_to_stream(stream_name, event1, options: { expected_revision: :no_stream })
+
+EventStoreClient.client.append_to_stream(stream_name, event2, options: { expected_revision: :no_stream })
+```
+
+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 = "some-stream$#{SecureRandom.uuid}"
+event1 = SomethingHappened.new(
+  type: 'some-event', data: {}
+)
+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
+# Expected revision matches => will succeed
+EventStoreClient.client.append_to_stream(stream_name, event2, options: { expected_revision: revision })
+# Will fail with revisions mismatch error
+EventStoreClient.client.append_to_stream(stream_name, 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" }
+)
+
+EventStoreClient.client.append_to_stream('some-stream', event, credentials: { username: 'admin', password: 'changeit' })
+```

data/docs/catch_up_subscriptions.md

@@ -0,0 +1,253 @@
+# Catch-up subscriptions
+
+Subscriptions allow you to subscribe to a stream and receive notifications about new events added to the stream.
+
+You provide an event handler and an optional starting point to the subscription. The handler is called for each event from the starting point onward.
+
+If events already exist, the handler will be called for each event one by one until it reaches the end of the stream. From there, the server will notify the handler whenever a new event appears.
+
+## Subscribing from the start
+
+When you need to process all the events in the store, including historical events, you need to subscribe from the beginning. You can either subscribe to receive events from a single stream, or subscribe to `$all` if you need to process all events in the database.
+
+### Subscribing to a stream
+
+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
+end
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: handler)
+```
+
+The provided handler will be called for every event in the stream. You may provide **any** object that responds to `#call`:
+
+```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
+  end
+end
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: SomeStreamHandler.new)
+```
+
+### Subscribing to $all
+
+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
+end
+EventStoreClient.client.subscribe_to_all(handler: handler)
+```
+
+## Subscribing from a specific position
+
+The previous examples will subscribe to the stream from the beginning. This will end up calling the handler for every event in the stream and then wait for new events after that.
+
+Both the stream and $all subscriptions accept a starting position if you want to read from a specific point onward. If events already exist at the position you subscribe to, they will be read on the server side and sent to the subscription.
+
+Once caught up, the sever will push any new events received on the streams to the client. There is no difference between catching up and live on the client side.
+
+### Subscribing to a stream
+
+To subscribe to a stream from a specific position, you need to provide a _stream position_. This can be `:start`, `:end` or an integer position.
+
+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 })
+```
+
+### Subscribing to $all
+
+Subscribing to the `$all` stream is much like subscribing to a regular stream. The only difference is how you need to specify the stream position. For the `$all` stream, you have to provide the `:from_position` hash, which consists of two integers, `:commit_position` and `:prepare_position`. The `:from_position` value can accept `:start` and `:end` values as well.
+
+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 } })
+```
+
+Please note that the given position needs to be a legitimate position in the `$all` stream.
+
+## Subscribing to a stream for live updates
+
+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 })
+```
+
+And the same works with `$all` :
+
+```ruby
+EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, 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.
+
+Keep in mind that when you subscribe to a stream from a certain position - you will also get live updates after your subscription catches up (processes all the historical events).
+
+## Resolving link-to's
+
+Link-to events point to events in other streams in EventStoreDB. These are generally created by projections such as the `$by_event_type` projection which links events of the same event type into the same stream. This makes it easier to look up all events of a certain type.
+
+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 })
+```
+
+## Handling subscription drops
+
+An application, which hosts the subscription, can go offline for a period of time for different reasons. It could be a crash, infrastructure failure, or a new version deployment. As you rarely would want to reprocess all the events again, you'd need to store the current position of the subscription somewhere, and then use it to restore the subscription from the point where it dropped off:
+
+```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
+end
+
+EventStoreClient.client.subscribe_to_stream('some-stream', handler: handler, options: { from_revision: checkpoint })
+```
+
+When subscribed to `$all` you want to keep the position of the event in the `$all` stream. As mentioned previously, the `$all` stream position consists of two integers (prepare and commit positions), not one:
+
+```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
+end
+
+EventStoreClient.client.subscribe_to_all(handler: handler, options: { from_position: checkpoint })
+```
+
+### 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:
+
+```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
+  else
+    # do something in case of error
+  end
+end
+
+EventStoreClient.client.subscribe_to_all(handler: handler, options: { from_position: checkpoint }, skip_deserialization: true)
+```
+
+## User credentials
+
+The user creating a subscription must have read access to the stream it's subscribing to, and only admin users may subscribe to `$all` or create filtered subscriptions.
+
+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' })
+```
+
+## Server-side filtering
+
+EventStoreDB allows you to filter the events whilst you subscribe to the `$all` stream so that you only receive the events that you care about.
+
+You can filter by event type or stream name using either a regular expression or a prefix. Server-side filtering is currently only available on the `$all` stream.
+
+A simple stream prefix filter looks like this:
+
+```ruby
+EventStoreClient.client.subscribe_to_all(handler: proc { |res| }, options: { filter: { stream_identifier: { prefix: ['test-', 'other-'] } } })
+```
+
+### Filtering out system events
+
+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 } } })
+```
+
+### Filtering by event type
+
+If you only want to subscribe to events of a given type there are two options. You can either use a regular expression or a prefix.
+
+#### Filtering by prefix
+
+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-'] } } })
+```
+
+#### Filtering by regular expression
+
+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' } } })
+```
+
+### Filtering by stream name
+
+If you only want to subscribe to a stream with a given name there are two options. You can either use a regular expression or a prefix.
+
+#### Filtering by prefix
+
+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-'] } } })
+```
+
+#### Filtering by regular expression
+
+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' } } })
+```