pg_eventstore 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e22bb2356955ece89a16f5d43b803670d0304eaf27d2fedbf1daf12aa908812
-  data.tar.gz: 31d95e0380be2ad8dd7306a1b04a8a14e6f4f32f6bcdb8864e42205c0a1fe9bc
+  metadata.gz: 256d7be42cb993955eb3c387b27fa63bf9992852da2375c785f181b873fe7568
+  data.tar.gz: 4101d8f0706f402a8e97bce4864c2ab2c61a587845e1051826d7d26417c199bd
 SHA512:
-  metadata.gz: 8cda13e213beec47c83818301b415d1dbf5b80e0659e548c6d166a3e136172c38802b697353f13344bb0d6b15b99b54f59e950ab9fb2f07e7bf494adedb2c280
-  data.tar.gz: 5f0743afb46b2dcd00c9c164b51beb6f4ea6284b839a0036418d46e60e7d7b8a53d378a1eb265fc063364970ae6fb2b0091fabae51429775bec2f8c1c2e843fa
+  metadata.gz: 548512c6c8ec7161380848b1975313222173dd41db13d45c0216948bf769eb513d8593dc0e22263c4cc59c9210a7c90fab21f7a64b26a38217253422457582b4
+  data.tar.gz: 777aecbd9e7ad84882fbf0c20847fc79e8495addac77a5887db3dface85b7dec7aa3679e91849272109f6f6745cdbfd143628d8dc53d78b73559ba9fad31722f

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [0.4.0] - 2024-01-29
+
+- Implement asynchronous subscriptions. Refer to the documentation for more info
+
 ## [0.3.0] - 2024-01-24
 
 - Log SQL queries when `PgEvenstore.logger` is set and it is in `:debug` mode 

data/README.md

@@ -53,6 +53,7 @@ Documentation chapters:
 - [Events and streams definitions](docs/events_and_streams.md)
 - [Appending events](docs/appending_events.md)
 - [Reading events](docs/reading_events.md)
+- [Subscriptions](docs/subscriptions.md)
 - [Writing middlewares](docs/writing_middleware.md)
 - [How to make multiple commands atomic](docs/multiple_commands.md)
 

data/db/migrations/10_create_subscription_commands.sql

@@ -0,0 +1,15 @@
+CREATE TABLE public.subscription_commands
+(
+    id              bigserial                   NOT NULL,
+    name            character varying           NOT NULL,
+    subscription_id bigint                      NOT NULL,
+    created_at      timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscription_commands
+    ADD CONSTRAINT subscription_commands_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscription_commands_subscription_id_and_name ON public.subscription_commands USING btree (subscription_id, name);
+
+ALTER TABLE ONLY public.subscription_commands
+    ADD CONSTRAINT subscription_commands_subscription_fk FOREIGN KEY (subscription_id) REFERENCES public.subscriptions (id) ON DELETE CASCADE;

data/db/migrations/11_create_subscriptions_set_commands.sql

@@ -0,0 +1,15 @@
+CREATE TABLE public.subscriptions_set_commands
+(
+    id                   bigserial                   NOT NULL,
+    name                 character varying           NOT NULL,
+    subscriptions_set_id uuid                        NOT NULL,
+    created_at           timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions_set_commands
+    ADD CONSTRAINT subscriptions_set_commands_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscr_set_commands_subscriptions_set_id_and_name ON public.subscriptions_set_commands USING btree (subscriptions_set_id, name);
+
+ALTER TABLE ONLY public.subscriptions_set_commands
+    ADD CONSTRAINT subscriptions_set_commands_subscriptions_set_fk FOREIGN KEY (subscriptions_set_id) REFERENCES public.subscriptions_set (id) ON DELETE CASCADE;

data/db/migrations/12_improve_events_indexes.sql

@@ -0,0 +1 @@
+CREATE INDEX idx_events_event_type_id_and_global_position ON public.events USING btree (event_type_id, global_position);

data/db/migrations/9_create_subscriptions.sql

@@ -0,0 +1,46 @@
+CREATE TABLE public.subscriptions_set
+(
+    id                     uuid                                 DEFAULT public.gen_random_uuid() NOT NULL,
+    name                   character varying           NOT NULL,
+    state                  character varying           NOT NULL DEFAULT 'initial',
+    restart_count          integer                     NOT NULL DEFAULT 0,
+    max_restarts_number    int2                        NOT NULL DEFAULT 10,
+    time_between_restarts  int2                        NOT NULL DEFAULT 1,
+    last_restarted_at      timestamp without time zone,
+    last_error             jsonb,
+    last_error_occurred_at timestamp without time zone,
+    created_at             timestamp without time zone NOT NULL DEFAULT now(),
+    updated_at             timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions_set
+    ADD CONSTRAINT subscriptions_set_pkey PRIMARY KEY (id);
+
+CREATE TABLE public.subscriptions
+(
+    id                            bigserial                   NOT NULL,
+    set                           character varying           NOT NULL,
+    name                          character varying           NOT NULL,
+    options                       jsonb                       NOT NULL DEFAULT '{}'::jsonb,
+    total_processed_events        bigint                      NOT NULL DEFAULT 0,
+    current_position              bigint,
+    average_event_processing_time float4,
+    state                         character varying           NOT NULL DEFAULT 'initial',
+    restart_count                 integer                     NOT NULL DEFAULT 0,
+    max_restarts_number           int2                        NOT NULL DEFAULT 100,
+    time_between_restarts         int2                        NOT NULL DEFAULT 1,
+    last_restarted_at             timestamp without time zone,
+    last_error                    jsonb,
+    last_error_occurred_at        timestamp without time zone,
+    chunk_query_interval          int2                        NOT NULL DEFAULT 5,
+    last_chunk_fed_at             timestamp without time zone NOT NULL DEFAULT to_timestamp(0),
+    last_chunk_greatest_position  bigint,
+    locked_by                     uuid,
+    created_at                    timestamp without time zone NOT NULL DEFAULT now(),
+    updated_at                    timestamp without time zone NOT NULL DEFAULT now()
+);
+
+ALTER TABLE ONLY public.subscriptions
+    ADD CONSTRAINT subscriptions_pkey PRIMARY KEY (id);
+
+CREATE UNIQUE INDEX idx_subscriptions_set_and_name ON public.subscriptions USING btree (set, name);

data/docs/configuration.md

@@ -2,21 +2,23 @@
 
 Configuration options:
 
-| name                    | value    | default value                                                | description                                                                                                                                                                                                                                                            |
-|-------------------------|----------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| pg_uri                  | String   | `'postgresql://postgres:postgres@localhost:5432/eventstore'` | PostgreSQL connection string. See PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) for more information.                                                                                                            |
-| max_count               | Integer  | `1000`                                                       | Number of events to return in one response when reading from a stream.                                                                                                                                                                                                 |
-| middlewares             | Array    | `{}`                                                         | A hash where a key is a name of your middleware and value is an object that respond to `#serialize` and `#deserialize` methods. See [**Writing middleware**](writing_middleware.md) chapter.                                                                           |
-| event_class_resolver    | `#call`  | `PgEventstore::EventClassResolver.new`                       | A `#call`-able object that accepts a string and returns an event's class. See **Resolving events classes** chapter bellow for more info.                                                                                                                               |
-| logger                  | `Logger` | `nil`                                                        | A logger that logs messages from `pg_eventstore` gem.                                                                                                                                                                                                                  |
-| connection_pool_size    | Integer  | `5`                                                          | Max number of connections per ruby process. It must equal the number of threads of your application.                                                                                                                                                                   |
-| connection_pool_timeout | Integer  | `5`                                                          | Time in seconds to wait for the connection in pool to be released. If no connections are available during this time - `ConnectionPool::TimeoutError` will be raised. See `connection_pool` gem [docs](https://github.com/mperham/connection_pool#usage) for more info. |
+| name                               | value   | default value                                                | description                                                                                                                                                                                                                                                                                                            |
+|------------------------------------|---------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| pg_uri                             | String  | `'postgresql://postgres:postgres@localhost:5432/eventstore'` | PostgreSQL connection string. See PostgreSQL [docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS) for more information.                                                                                                                                                            |
+| max_count                          | Integer | `1000`                                                       | Number of events to return in one response when reading from a stream.                                                                                                                                                                                                                                                 |
+| middlewares                        | Array   | `{}`                                                         | A hash where a key is a name of your middleware and value is an object that respond to `#serialize` and `#deserialize` methods. See [**Writing middleware**](writing_middleware.md) chapter.                                                                                                                           |
+| event_class_resolver               | `#call` | `PgEventstore::EventClassResolver.new`                       | A `#call`-able object that accepts a string and returns an event's class. See **Resolving events classes** chapter bellow for more info.                                                                                                                                                                               |
+| connection_pool_size               | Integer | `5`                                                          | Max number of connections per ruby process. It must equal the number of threads of your application. When using subscriptions it is recommended to set it to the number of subscriptions divided by two or greater. See [**Picking max connections number**](#picking-max-connections-number) chapter of this section. |
+| connection_pool_timeout            | Integer | `5`                                                          | Time in seconds to wait for a connection in the pool to be released. If no connections are available during this time - `ConnectionPool::TimeoutError` will be raised. See `connection_pool` gem [docs](https://github.com/mperham/connection_pool#usage) for more info.                                               |
+| subscription_pull_interval         | Integer | `2`                                                          | How often to pull new subscription events in seconds.                                                                                                                                                                                                                                                                  |
+| subscription_max_retries           | Integer | `5`                                                          | Max number of retries of failed subscription.                                                                                                                                                                                                                                                                          |
+| subscription_retries_interval      | Integer | `1`                                                          | Interval in seconds between retries of failed subscriptions.                                                                                                                                                                                                                                                           |
+| subscriptions_set_max_retries      | Integer | `10`                                                         | Max number of retries for failed subscription sets.                                                                                                                                                                                                                                                                    |
+| subscriptions_set_retries_interval | Integer | `1`                                                          | interval in seconds between retries of failed subscription sets.                                                                                                                                                                                                                                                       |
 
 ## Multiple configurations
 
-`pg_eventstore` allows you to have as many configs as you want. This allows you, for example, to have different
-databases, or to have a different set of middlewares for specific cases only. To do so, you have to name your
-configuration, and later provide that name to `PgEventstore` client.
+`pg_eventstore` allows you to have as many configs as you want. This allows you, for example, to have different databases, or to have a different set of middlewares for specific cases only. To do so, you have to name your configuration, and later provide that name to `PgEventstore` client.
 
 Setup your configs:
 
@@ -42,8 +44,7 @@ PgEventstore.client(:pg_db_2).read(PgEventstore::Stream.all_stream)
 
 ### Default config
 
-If you have one config only - you don't have to bother naming it or passing a config name to the client when performing
-any operations. You can configure it as usual.
+If you have one config only - you don't have to bother naming it or passing a config name to the client when performing any operations. You can configure it as usual.
 
 Setup your default config:
 
@@ -64,19 +65,39 @@ EventStoreClient.client.read(PgEventstore::Stream.all_stream)
 
 ## Resolving event classes
 
-During the deserialization process `pg_eventstore` tries to pick the correct class for an event. By default it does it
-using the `PgEventstore::EventClassResolver` class. All it does is `Object.const_get(event_type)`. By default, if you
-don't provide the `type` attribute for an event explicitly, it will grab the event's class name, meaning by default:
+During the deserialization process `pg_eventstore` tries to pick the correct class for an event. By default it does it using the `PgEventstore::EventClassResolver` class. All it does is `Object.const_get(event_type)`. By default, if you don't provide the `type` attribute for an event explicitly, it will grab the event's class name, meaning by default:
 
 - event's type is event's class name
-- when instantiating an event - `pg_eventstore` tries to lookup an event class based on the value of event's `type`
-  attribute with a fallback to `PgEventstore::Event` class
+- when instantiating an event - `pg_eventstore` tries to lookup an event class based on the value of event's `type` attribute with a fallback to `PgEventstore::Event` class
 
-You can override the default event class resolver by providing any `#call`-able object. It should accept event's type
-and return event's class based on it. Example:
+You can override the default event class resolver by providing any `#call`-able object. It should accept event's type and return event's class based on it. Example:
 
 ```ruby
 PgEventstore.configure do |config|
   config.event_class_resolver = proc { |event_type| Object.const_get(event_type.gsub('Foo', 'Bar')) rescue PgEventstore::Event }
 end
 ```
+
+## Picking max connections number
+
+A connection is hold from the connection pool to perform the request and it is released back to the connection pool once the request is finished. If you run into the (theoretical) edge case, when all your application's threads (or subscriptions) are performing `pg_eventstore` queries at the same time and all those queries take more than `connection_pool_timeout` seconds to complete, you have to have `connection_pool_size` set to the exact amount of your application's threads (or to the number of subscriptions when using subscriptions) to prevent timeout errors. Practically this is not the case, as all `pg_eventstore` queries are pretty fast. So, a good value for the `connection_pool_size` option is **half the number ** of your application's threads(or half the number of Subscriptions).
+
+### Exception scenario
+
+If you are using the [`#multiple`](multiple_commands.md) method - you have to take into account the execution time of the whole block you pass in it. This is because the connection will be released only after the block's execution is finished. So, for example, if you perform several commands within the block, as well as some API request, the connection will be release only after all those steps:
+
+```ruby
+PgEventstore.client.multiple do
+  # Connection is hold from the connection pool
+  PgEventstore.client.read(some_stream)
+  Stripe::Payment.create(some_attrs)
+  PgEventstore.client.append_to_stream(some_stream, some_event)
+  # Connection is released
+end
+```
+
+Taking this into account you may want to increase `connection_pool_size` up to the number of your application's threads(or subscriptions).
+
+### Usage of external connection pooler
+
+`pg_eventstore` does not use any session-specific features of PostgreSQL. You can use any PostgreSQL connection pooler you like, such as [PgBouncer](https://www.pgbouncer.org/) for example. 

data/docs/subscriptions.md

@@ -0,0 +1,170 @@
+# Subscriptions
+
+In order to process new events in your microservices you have to have the ability to listen for them. `pg_eventstore` implements a subscription feature for this matter. It is implemented as a background thread that pulls new events according to your filters from time to time (see `subscription_pull_interval` setting option under [**Configuration**](configuration.md) chapter).
+
+## PgEventstore::Subscription
+
+`pg_eventstore` stores various subscription information in the database. The corresponding object that describes the database records is the `PgEventstore::Subscription` object. It is used in the `config.subscription_restart_terminator` setting for example. You can find its attributes summary [here](https://rubydoc.info/gems/pg_eventstore/PgEventstore/Subscription).  
+
+## PgEventstore::SubscriptionsSet
+
+`pg_eventstore` also stores information about which subscriptions are set. The corresponding object that describes the database records is `PgEventstore::SubscriptionsSet`. You can find its attributes summary [here](https://rubydoc.info/gems/pg_eventstore/PgEventstore/SubscriptionsSet).
+
+This record is created when you start your subscriptions. All subscriptions created using a single subscriptions manager instance are locked using a single `PgEventstore::SubscriptionsSet`. When subscriptions are locked, they can't be managed anywhere else. When you stop your subscriptions, the `PgEventstore::SubscriptionsSet` is deleted, unlocking the subscriptions. The `SubscriptionSet` also holds information about the state, number of restarts, the restart interval and last error of the background runner which is responsible for pulling the subscription's events. You can set the max number of restarts and the restarts interval of your subscriptions set via `config.subscriptions_set_max_retries` and `config.subscriptions_set_retries_interval` settings. See [**Configuration**](configuration.md) chapter for more info.
+
+## Creating a subscription
+
+First step you need to do is to create a `PgEventstore::SubscriptionsManager` object and provide the `subscription_set` keyword argument. Optionally you can provide a config name to use, override the `config.subscriptions_set_max_retries` and `config.subscriptions_set_retries_interval` settings:
+
+```ruby
+subscriptions_manager = PgEventstore.subscriptions_manager(subscription_set: 'SubscriptionsOfMyAwesomeMicroservice')
+another_subscriptions_manager = PgEventstore.subscriptions_manager(:my_custom_config, subscription_set: 'SubscriptionsOfMyAwesomeMicroservice', max_retries: 5, retries_interval: 2)
+```
+
+The required `subscription_set` option groups your subscriptions into a set. For example, you could refer to your service's name in the subscription set name.
+
+Now we can use the `#subscribe` method to create the subscription:
+
+```ruby
+subscriptions_manager.subscribe('MyAwesomeSubscription', handler: proc { |event| puts event })
+```
+
+First argument is the subscription's name. **It must be unique within the subscription set**. Second argument is your subscription's handler where you will be processing your events as they arrive. The example shows the minimum set of arguments required to create the subscription. 
+
+In the given state it will be listening to all events from all streams. You can define various filters by providing the `:filter` key of `options` argument:
+
+```ruby
+subscriptions_manager.subscribe(
+  'MyAwesomeSubscription', 
+  handler: proc { |event| puts event }, 
+  options: { filter: { streams: [{ context: 'MyAwesomeContext' }], event_types: ['Foo', 'Bar'] } }
+)
+```
+
+`:filter` supports the same options as the `#read` method supports when reading from the `"all"` stream. See [*"all" stream filtering*](reading_events.md#all-stream-filtering) section of **Reading events** chapter.
+
+After you added all necessary subscriptions, it is time to start them:
+
+```ruby
+subscriptions_manager.start
+```
+
+After calling `#start` all subscriptions are locked behind the given subscription set and can't be locked by any other subscription set. This measure is needed to prevent running the same subscription under the same subscription set using different processes/subscription managers. Such situation will lead to a malformed subscription state and will break its position, meaning the same event will be processed several times.
+
+To "unlock" the subscription you should gracefully stop the subscription manager:
+
+```ruby
+subscriptions_manager.stop
+```
+
+If you shut down the process which runs your subscriptions without calling the `#stop` method, subscriptions will remain locked, and the only way to unlock them will be to call the `#force_lock!` method before calling the `#start` method:
+
+```ruby
+subscriptions_manager.force_lock!
+subscriptions_manager.start
+```
+
+A complete example of the subscription setup process looks like this:
+
+```ruby
+require 'pg_eventstore'
+
+PgEventstore.configure do |config|
+  config.pg_uri = ENV.fetch('PG_EVENTSTORE_URI') { 'postgresql://postgres:postgres@localhost:5532/eventstore' }  
+end
+
+subscriptions_manager = PgEventstore.subscriptions_manager(subscription_set: 'MyAwesomeSubscriptions')
+subscriptions_manager.subscribe(
+  'Foo events Subscription', 
+  handler: proc { |event| p "Foo events Subscription: #{event.inspect}" }, 
+  options: { filter: { event_types: ['Foo'] } }
+)
+subscriptions_manager.subscribe(
+  '"BarCtx" context Subscription',
+  handler: proc { |event| p "'BarCtx' context Subscription: #{event.inspect}" }, 
+  options: { filter: { streams: [{ context: 'BarCtx' }] } 
+  }
+)
+subscriptions_manager.force_lock! if ENV['FORCE_LOCK'] == 'true'
+subscriptions_manager.start
+
+Kernel.trap('TERM') do
+  puts "Received TERM signal. Stopping Subscriptions Manager and exiting..."
+  # It is important to wrap subscriptions_manager.stop into another Thread, because it uses Thread::Mutex#synchronize
+  # internally, but its usage is not allowed inside Kernel.trap block
+  Thread.new { subscriptions_manager.stop }.join
+  exit
+end
+
+loop do
+  sleep 5
+  subscriptions_manager.subscriptions.each do |subscription|
+    puts <<~TEXT
+      Subscription <<#{subscription.name.inspect}>> is at position #{subscription.current_position}. \
+      Events processed: #{subscription.total_processed_events}
+    TEXT
+  end
+  puts "Current SubscriptionsSet: #{subscriptions_manager.subscriptions_set}"
+  puts ""
+end
+```
+
+You can save this script in `subscriptions.rb`, run it with `bundle exec ruby subscriptions.rb`, open another ruby console and test posting different events:
+
+```ruby
+require 'pg_eventstore'
+
+PgEventstore.configure do |config|
+  config.pg_uri = ENV.fetch('PG_EVENTSTORE_URI') { 'postgresql://postgres:postgres@localhost:5532/eventstore' }
+end
+
+foo_stream = PgEventstore::Stream.new(context: 'FooCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+bar_stream = PgEventstore::Stream.new(context: 'BarCtx', stream_name: 'MyAwesomeStream', stream_id: '1')
+PgEventstore.client.append_to_stream(foo_stream, PgEventstore::Event.new(type: 'Foo', data: { foo: :bar }))
+PgEventstore.client.append_to_stream(bar_stream, PgEventstore::Event.new(type: 'Foo', data: { foo: :bar }))
+```
+
+You will then see the output of your subscription handlers. To gracefully stop the subscriptions process, use `kill -TERM <pid>` command.
+
+## Overriding Subscription config values
+
+You can override `subscription_pull_interval`, `subscription_max_retries`, `subscription_retries_interval` and `subscription_restart_terminator` config values (see [**Configuration**](configuration.md) chapter for details) for the specific subscription by providing the corresponding arguments. Example:
+
+```ruby
+subscriptions_manager.subscribe(
+  'MyAwesomeSubscription', 
+  handler: proc { |event| puts event },
+  # overrides config.subscription_pull_interval
+  pull_interval: 1,
+  # overrides config.subscription_max_retries
+  max_retries: 10,
+  # overrides config.subscription_retries_interval
+  retries_interval: 2,
+  # overrides config.subscription_restart_terminator
+  restart_terminator: proc { |subscription| subscription.last_error['class'] == 'NoMethodError' }, 
+)
+```
+
+## Middlewares
+
+If you would like to skip some of your registered middlewares from processing events after they are being pulled by the subscription, you should use the `:middlewares` argument which allows you to override the list of middlewares you would like to use.
+
+Let's say you have these registered middlewares:
+
+```ruby
+PgEventstore.configure do |config|
+  config.middlewares = { foo: FooMiddleware.new, bar: BarMiddleware.new, baz: BazMiddleware.new }
+end
+```
+
+And you want to skip `FooMiddleware` and `BazMiddleware`. You simply have to provide an array of corresponding middleware keys you would like to use when creating the subscription:
+
+```ruby
+subscriptions_manager.subscribe('MyAwesomeSubscription', handler: proc { |event| puts event }, middlewares: %i[bar])
+```
+
+See the [Writing middleware](writing_middleware.md) chapter for info about what is middleware and how to implement it.
+
+## How many subscriptions I should put in one process?
+
+It depends on the nature of your subscription handlers. If they spend more time on ruby code execution than on IO operations, you should limit the number of subscriptions per single process. This can be especially noticed when you rebuild the read models of your microservice, processing all events from the start.

data/lib/pg_eventstore/callbacks.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module PgEventstore
+  # Allows you to define before, around and after callbacks withing the certain action. It is especially useful during
+  # asynchronous programming when you need to be able to react on asynchronous actions from the outside.
+  # Example:
+  #   class MyAwesomeClass
+  #     attr_reader :callbacks
+  #
+  #     def initialize
+  #       @callbacks = PgEventstore::Callbacks.new
+  #     end
+  #
+  #     def do_something
+  #       Thread.new do
+  #         @callbacks.run_callbacks(:something_happened) do
+  #           puts "I did something useful!"
+  #         end
+  #       end
+  #     end
+  #
+  #     def do_something_else
+  #       @callbacks.run_callbacks(:something_else_happened, :foo, bar: :baz) do
+  #         puts "Something else happened!"
+  #       end
+  #     end
+  #   end
+  #
+  #   obj = MyAwesomeClass.new
+  #   obj.callbacks.define_callback(:something_happened, :before, proc { puts "In before callback" })
+  #   obj.callbacks.define_callback(:something_happened, :after, proc { puts "In after callback" })
+  #   obj.callbacks.define_callback(
+  #     :something_happened, :around,
+  #     proc { |action| puts "In around before action"; action.call; puts "In around after action" }
+  #   )
+  #   obj.do_something
+  # Outputs:
+  #   In before callback
+  #   In around callback before action
+  #   I did something useful!
+  #   In around callback after action
+  #   In after callback
+  # Please note, that it is important to call *action.call* in around callback. Otherwise action simply won't be called.
+  #
+  # Optionally you can provide any set of arguments to {#run_callbacks} method. They will be passed to your callbacks
+  # functions then. Example:
+  #
+  #   obj = MyAwesomeClass.new
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :before,
+  #     proc { |*args, **kwargs| puts "In before callback. Args: #{args}, kwargs: #{kwargs}." }
+  #   )
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :after,
+  #     proc { |*args, **kwargs| puts "In after callback. Args: #{args}, kwargs: #{kwargs}." }
+  #   )
+  #   obj.callbacks.define_callback(
+  #     :something_else_happened, :around,
+  #     proc { |action, *args, **kwargs|
+  #       puts "In around before action. Args: #{args}, kwargs: #{kwargs}."
+  #       action.call
+  #       puts "In around after action. Args: #{args}, kwargs: #{kwargs}."
+  #     }
+  #   )
+  #   obj.do_something_else
+  # Outputs:
+  #   In before callback. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   In around before action. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   I did something useful!
+  #   In around after action. Args: [:foo], kwargs: {:bar=>:baz}.
+  #   In after callback. Args: [:foo], kwargs: {:bar=>:baz}.
+  class Callbacks
+    def initialize
+      @callbacks = {}
+    end
+
+    # @param action [Object] an object, that represents your action. In most cases you want to use a symbol there
+    # @param filter [Symbol] callback filter. Supported values are :before, :after and :around
+    # @param callback [#call]
+    # @return [void]
+    def define_callback(action, filter, callback)
+      @callbacks[action] ||= {}
+      @callbacks[action][filter] ||= []
+      @callbacks[action][filter].push(callback)
+    end
+
+    # @param action [Object] an action to run
+    # @return [Object] the result of passed block
+    def run_callbacks(action, *args, **kwargs, &blk)
+      return (yield if block_given?) unless @callbacks[action]
+
+      run_before_callbacks(action, *args, **kwargs)
+      result = run_around_callbacks(action, *args, **kwargs, &blk)
+      run_after_callbacks(action, *args, **kwargs)
+      result
+    end
+
+    private
+
+    def run_before_callbacks(action, *args, **kwargs)
+      @callbacks[action][:before]&.each do |callback|
+        callback.call(*args, **kwargs)
+      end
+    end
+
+    def run_around_callbacks(action, *args, **kwargs, &blk)
+      result = nil
+      stack = [proc { result = yield if block_given? }]
+      @callbacks[action][:around]&.reverse_each&.with_index do |callback, index|
+        stack.push(proc { callback.call(stack[index], *args, **kwargs); result })
+      end
+      stack.last.call(*args, **kwargs)
+      result
+    end
+
+    def run_after_callbacks(action, *args, **kwargs)
+      @callbacks[action][:after]&.each do |callback|
+        callback.call(*args, **kwargs)
+      end
+    end
+  end
+end

data/lib/pg_eventstore/client.rb

@@ -2,7 +2,7 @@
 
 require_relative 'commands'
 require_relative 'event_serializer'
-require_relative 'pg_result_deserializer'
+require_relative 'event_deserializer'
 require_relative 'queries'
 
 module PgEventstore
@@ -140,7 +140,7 @@ module PgEventstore
       EventQueries.new(
         connection,
         EventSerializer.new(middlewares),
-        PgResultDeserializer.new(middlewares, config.event_class_resolver)
+        EventDeserializer.new(middlewares, config.event_class_resolver)
       )
     end
   end

data/lib/pg_eventstore/config.rb

@@ -6,14 +6,46 @@ module PgEventstore
 
     attr_reader :name
 
-    # PostgreSQL connection URI docs https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
+    # @!attribute pg_uri
+    #   @return [String] PostgreSQL connection URI docs
+    #     https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS
     option(:pg_uri) { 'postgresql://postgres:postgres@localhost:5432/eventstore' }
+    # @!attribute max_count
+    #   @return [Integer] Number of events to return in one response when reading from a stream
     option(:max_count) { 1000 }
+    # @!attribute middlewares
+    #   @return [Hash{Symbol => <#serialize, #deserialize>}] A set of identified(by key) objects that respond to
+    #     #serialize and #deserialize
     option(:middlewares) { {} }
-    # Object that responds to #call. Should accept a string and return a class
+    # @!attribute event_class_resolver
+    #   @return [#call] A callable object that must accept a string and return a class. It is used when resolving
+    #     event's class during event's deserialization process
     option(:event_class_resolver) { EventClassResolver.new }
+    # @!attribute connection_pool_size
+    #   @return [Integer] Max number of connections per ruby process
     option(:connection_pool_size) { 5 }
-    option(:connection_pool_timeout) { 5 } # seconds
+    # @!attribute connection_pool_timeout
+    #   @return [Integer] Time in seconds to wait for the connection in pool to be released
+    option(:connection_pool_timeout) { 5 }
+    # @!attribute subscription_pull_interval
+    #   @return [Integer] How often Subscription should pull new events
+    option(:subscription_pull_interval) { 2 }
+    # @!attribute subscription_max_retries
+    #   @return [Integer] max number of retries of failed Subscription
+    option(:subscription_max_retries) { 100 }
+    # @!attribute subscription_retries_interval
+    #   @return [Integer] interval in seconds between retries of failed Subscription
+    option(:subscription_retries_interval) { 1 }
+    # @!attribute subscription_restart_terminator
+    #   @return [#call, nil] provide callable object that accepts Subscription object to decide whether to prevent
+    #     further Subscription restarts
+    option(:subscription_restart_terminator)
+    # @!attribute subscriptions_set_max_retries
+    #   @return [Integer] max number of retries of failed SubscriptionsSet
+    option(:subscriptions_set_max_retries) { 10 }
+    # @!attribute subscriptions_set_retries_interval
+    #   @return [Integer] interval in seconds between retries of failed SubscriptionsSet
+    option(:subscriptions_set_retries_interval) { 1 }
 
     # @param name [Symbol] config's name. Its value matches the appropriate key in PgEventstore.config hash
     def initialize(name:, **options)

data/lib/pg_eventstore/errors.rb

@@ -104,4 +104,67 @@ module PgEventstore
       TEXT
     end
   end
+
+  class RecordNotFound < Error
+    attr_reader :table_name, :id
+
+    # @param table_name [String]
+    # @param id [Integer, String]
+    def initialize(table_name, id)
+      @table_name = table_name
+      @id = id
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      "Could not find/update #{table_name.inspect} record with #{id.inspect} id."
+    end
+  end
+
+  class SubscriptionAlreadyLockedError < Error
+    attr_reader :set, :name, :lock_id
+
+    # @param set [String] subscriptions set name
+    # @param name [String] subscription's name
+    # @param lock_id [String] UUIDv4
+    def initialize(set, name, lock_id)
+      @set = set
+      @name = name
+      @lock_id = lock_id
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT
+        Could not lock Subscription from #{set.inspect} set with #{name.inspect} name. It is already locked by \
+        #{lock_id.inspect} set.
+      TEXT
+    end
+  end
+
+  class SubscriptionUnlockError < Error
+    attr_reader :set, :name, :expected_locked_by, :actual_locked_by
+
+    # @param set [String] subscription's set name
+    # @param name [String] subscription's name
+    # @param expected_locked_by [String] UUIDv4
+    # @param actual_locked_by [String, nil] UUIDv4
+    def initialize(set, name, expected_locked_by, actual_locked_by)
+      @set = set
+      @name = name
+      @expected_locked_by = expected_locked_by
+      @actual_locked_by = actual_locked_by
+      super(user_friendly_message)
+    end
+
+    # @return [String]
+    def user_friendly_message
+      <<~TEXT
+        Failed to unlock Subscription from #{set.inspect} set with #{name.inspect} name by \
+        #{expected_locked_by.inspect} lock id. It is currently locked by #{actual_locked_by.inspect} lock id.
+      TEXT
+    end
+  end
 end