event_sourcery 0.21.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bab180e1a9e9380aad56c19810e3effb6911350010a4e1538711885fe177cd49
-  data.tar.gz: 0c5ca78c052c3b8a61f7c9a4141038e25e77c9d1802aea80a6bc9b6045b5e255
+  metadata.gz: f837642276b30c8fae75c9314c2adc4854e5b46105b520870f4960cf2b13b461
+  data.tar.gz: 3622196388903fcf3b4f9b98fb0f5317cbffd71c6cd8b8ccc3cf571d63a773d2
 SHA512:
-  metadata.gz: 4db8e9b04415d9dc57871f2ebd25a9e2cb70752e109ee4fec6b396fd11528ccdc660edf57a29e04373e62946eca596ebc56495da2ae17a0946decfeb0ef88ba1
-  data.tar.gz: 232ee9d65f9e61545f5f914f5a8de5893495fa22ce515d818bd1dca07bf7da9992711233843e1bbbe01f894b8e8ddbcf148929f0ab69f84a47a78270cff356d9
+  metadata.gz: 110dde9b74656dffc1838f5855c203bbd3e74b593a81f5d8a876c2629f99a032b8c577bcd3e59c35f96945032504051d9a7dd1103daa3e44a282b91660f01ac7
+  data.tar.gz: cf26df2449e5db4a83ae3ce336e382b13c81bd3e6a7381dccab52bcc37d0928c2fa1e44f30d0d351475b520ab739e36b7f9438d2afca6f606d0e091a56725b30

data/CHANGELOG.md

@@ -5,6 +5,107 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+## [0.24.0] - 2021-11-18
+
+### Added
+
+- Test against Ruby 3.0 in the CI build ([#229]).
+
+### Changed
+
+- Use GitHub Actions for the CI build instead of Travis CI ([#228]).
+- This project now uses `main` as its default branch ([#230]).
+  - Documentation updated to refer to `main` and links updated accordingly.
+
+### Removed
+- Remove Ruby 2.3, 2.4 and 2.5 from the CI test matrix ([#232]).
+
+[#228]: https://github.com/envato/event_sourcery/pull/228
+[#229]: https://github.com/envato/event_sourcery/pull/229
+[#230]: https://github.com/envato/event_sourcery/pull/230
+[#232]: https://github.com/envato/event_sourcery/pull/232
+
+## [0.23.1] - 2020-10-02
+### Fixed
+- Upgrade development dependency Rake to version 13. This resolves
+  [CVE-2020-8130](https://github.com/advisories/GHSA-jppv-gw3r-w3q8).
+
+- Patch `ESPRunner` to gracefully handle terminating subprocesses it did
+  not start ([#223]).
+
+- Resolve warnings raised by Ruby 2.7 ([#225]).
+
+[#223]: https://github.com/envato/event_sourcery/pull/223
+[#225]: https://github.com/envato/event_sourcery/pull/225
+
+## [0.23.0] - 2019-07-11
+### Added
+- Add Ruby 2.6 to the CI test matrix.
+- `ESPRunner` supports an `after_subprocess_termination` hook. This optional
+  initializer argument will will be executed when each child process
+  terminates. This allows for monitoring and alerts to be configured.
+  For example, Rollbar:
+
+  ```ruby
+  EventSourcery::EventProcessing::ESPRunner.new(
+    event_processors: processors,
+    event_source: source,
+    after_subprocess_termination: proc do |processor:, runner:, exit_status:|
+      if exit_status != 0
+        Rollbar.error("Processor #{processor.processor_name} "\
+                      "terminated with exit status #{exit_status}")
+      end
+    end
+  ).start!
+  ```
+
+- `ESPRunner` exposes three new public methods `start_processor`, `shutdown`,
+  and `shutdown_requested?`. These provide options for handling subprocess
+  failure/termination. For example, shutting down the `ESPRunner`:
+
+  ```ruby
+  EventSourcery::EventProcessing::ESPRunner.new(
+    event_processors: processors,
+    event_source: source,
+    after_subprocess_termination: proc do |processor:, runner:, exit_status:|
+      runner.shutdown
+    end
+  ).start!
+  ```
+
+  Or restarting the event processor:
+
+  ```ruby
+  EventSourcery::EventProcessing::ESPRunner.new(
+    event_processors: processors,
+    event_source: source,
+    after_subprocess_termination: proc do |processor:, runner:, exit_status:|
+      runner.start_processor(processor) unless runner.shutdown_requested?
+    end
+  ).start!
+  ```
+
+- `ESPRunner` checks for dead child processes every second. This means we
+  shouldn't see `[ruby] <defunct>` in the process list (ps) when a processor
+  fails.
+- `ESPRunner` logs when child processes die.
+- `ESPRunner` logs when sending signals to child processes.
+
+### Removed
+- Remove Ruby 2.2 from the CI test matrix.
+
+## [0.22.0] - 2018-10-04
+### Added
+- Log critical exceptions to the application provided block via the new
+  configuration option ([#209](https://github.com/envato/event_sourcery/pull/209)):
+
+  ```ruby
+  config.on_event_processor_critical_error = proc do |exception, processor_name|
+    # report the death of this processor to an error reporting service like Rollbar.
+  end
+  ```
+
 ## [0.21.0] - 2018-07-02
 ### Added
 - Graceful shutdown interrupts poll-wait sleep for quicker quitting
@@ -18,7 +119,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [0.20.0] - 2018-06-21
 ### Changed
-- Changed signature of `ESPProcess#initialize` to include a default value for `after_fork`. This prevents the 
+- Changed signature of `ESPProcess#initialize` to include a default value for `after_fork`. This prevents the
 `after_fork` change from 0.19.0 from being a breaking change to external creators of ESPProcess.
 - Added more logging when a fatal exception occurs in ESPProcess
 
@@ -152,7 +253,11 @@ moving all Postgres related code into a separate gem.
 - EventSourcery no longer depends on Virtus.
 - `Command` and `CommandHandler` have been removed.
 
-[Unreleased]: https://github.com/envato/event_sourcery/compare/v0.21.0...HEAD
+[Unreleased]: https://github.com/envato/event_sourcery/compare/v0.24.0...HEAD
+[0.24.0]: https://github.com/envato/event_sourcery/compare/v0.23.1...v0.24.0
+[0.23.1]: https://github.com/envato/event_sourcery/compare/v0.23.0...v0.23.1
+[0.23.0]: https://github.com/envato/event_sourcery/compare/v0.22.0...v0.23.0
+[0.22.0]: https://github.com/envato/event_sourcery/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/envato/event_sourcery/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/envato/event_sourcery/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/envato/event_sourcery/compare/v0.18.0...v0.19.0

data/README.md

@@ -1,6 +1,6 @@
 # EventSourcery
 
-[![Build Status](https://travis-ci.org/envato/event_sourcery.svg?branch=master)](https://travis-ci.org/envato/event_sourcery)
+[![Build Status](https://github.com/envato/event_sourcery/workflows/tests/badge.svg?branch=main)](https://github.com/envato/event_sourcery/actions?query=workflow%3Atests+branch%3Amain)
 
 A framework for building event sourced, CQRS applications.
 
@@ -67,6 +67,7 @@ EventSourcery.configure do |config|
   # Add custom reporting of errors occurring during event processing.
   # One might set up an error reporting service like Rollbar here.
   config.on_event_processor_error = proc { |exception, processor_name| … }
+  config.on_event_processor_critical_error = proc { |exception, processor_name| … }
 
   # Enable EventSourcery logging.
   config.logger = Logger.new('logs/my_event_sourcery_app.log')
@@ -104,7 +105,7 @@ To release a new version:
 
 1. Update the version number in `lib/event_sourcery/version.rb`
 2. Add the new version with release notes to CHANGELOG.md
-3. Get these changes onto master via the normal PR process
+3. Get these changes onto main via the normal PR process
 4. Run `bundle exec rake release`, this will create a git tag for the
    version, push tags up to GitHub, and package the code in a `.gem` file.
 
@@ -217,7 +218,7 @@ The event store is a persistent store of events.
 
 EventSourcery currently supports a Postgres-based event store via the [event_sourcery-postgres gem](https://github.com/envato/event_sourcery-postgres).
 
-For more information about the `EventStore` API refer to [the postgres event store](https://github.com/envato/event_sourcery-postgres/blob/master/lib/event_sourcery/postgres/event_store.rb) or the [in memory event store in this repo](lib/event_sourcery/event_store/memory.rb)
+For more information about the `EventStore` API refer to [the postgres event store](https://github.com/envato/event_sourcery-postgres/blob/HEAD/lib/event_sourcery/postgres/event_store.rb) or the [in memory event store in this repo](lib/event_sourcery/memory/event_store.rb)
 
 #### Storing Events
 
@@ -293,7 +294,7 @@ Reactors can be used to build [process managers or sagas](https://msdn.microsoft
 
 #### Running Multiple ESPs
 
-An EventSourcery application will typically have multiple ESPs running. EventSourcery provides a class called [ESPRunner](lib/event_sourcery/event_processing/esp_runner.rb) which can be used to run ESPs. It runs each ESP in a forked child process so each ESP can process the event store independently. You can find an example in [event_sourcery_todo_app](https://github.com/envato/event_sourcery_todo_app/blob/master/Rakefile).
+An EventSourcery application will typically have multiple ESPs running. EventSourcery provides a class called [ESPRunner](lib/event_sourcery/event_processing/esp_runner.rb) which can be used to run ESPs. It runs each ESP in a forked child process so each ESP can process the event store independently. You can find an example in [event_sourcery_todo_app](https://github.com/envato/event_sourcery_todo_app/blob/HEAD/Rakefile).
 
 Note that you may instead choose to run each ESP in their own process directly. The coordination of this is not currently provided by EventSourcery.
 

data/event_sourcery.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/envato/event_sourcery'
   spec.metadata      = {
                          'bug_tracker_uri' => 'https://github.com/envato/event_sourcery/issues',
-                         'changelog_uri'   => 'https://github.com/envato/event_sourcery/blob/master/CHANGELOG.md',
+                         'changelog_uri'   => 'https://github.com/envato/event_sourcery/blob/HEAD/CHANGELOG.md',
                          'source_code_uri' => 'https://github.com/envato/event_sourcery',
                        }
 
@@ -25,8 +25,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.2.0'
 
-  spec.add_development_dependency 'bundler', '~> 1.10'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake', '~> 13'
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'benchmark-ips'

data/lib/event_sourcery/aggregate_root.rb

@@ -3,7 +3,7 @@ module EventSourcery
   # EventSourcery::AggregateRoot provides a foundation for writing your own aggregate root classes.
   # You can use it by including it in your classes, as show in the example code.
   #
-  # Excerpt from {https://github.com/envato/event_sourcery/blob/master/docs/core-concepts.md EventSourcery Core Concepts} on Aggregates follows:
+  # Excerpt from {https://github.com/envato/event_sourcery/blob/HEAD/docs/core-concepts.md EventSourcery Core Concepts} on Aggregates follows:
   # === Aggregates and Command Handling
   #
   #   An aggregate is a cluster of domain objects that can be treated as a single unit.
@@ -18,7 +18,7 @@ module EventSourcery
   # A typical EventSourcery application will have one or more aggregate roots with multiple commands.
   #
   # The following partial example is taken from the EventSourceryTodoApp.
-  # Refer a more complete example {https://github.com/envato/event_sourcery_todo_app/blob/master/app/aggregates/todo.rb here}.
+  # Refer a more complete example {https://github.com/envato/event_sourcery_todo_app/blob/HEAD/app/aggregates/todo.rb here}.
   #
   # @example
   #   module EventSourceryTodoApp

data/lib/event_sourcery/config.rb

@@ -19,6 +19,14 @@ module EventSourcery
     # @return Proc
     attr_accessor :on_event_processor_error
 
+    # A Proc to be executed on an event processor critical error.
+    # App defined behaviour can be provided. This will be called
+    # if an exception causes an a event processor to die.
+    # i.e. report to an error reporting service like Rollbar.
+    #
+    # @return Proc
+    attr_accessor :on_event_processor_critical_error
+
     # @return EventStore::EventTypeSerializers::Underscored
     attr_accessor :event_type_serializer
 
@@ -40,6 +48,9 @@ module EventSourcery
       @on_event_processor_error = proc { |exception, processor_name|
         # app specific custom logic ie. report to an error reporting service like Rollbar.
       }
+      @on_event_processor_critical_error = proc { |exception, processor_name|
+        # app specific custom logic ie. report to an error reporting service like Rollbar.
+      }
       @event_builder = nil
       @event_type_serializer = EventStore::EventTypeSerializers::Underscored.new
       @error_handler_class = EventProcessing::ErrorHandlers::ConstantRetry
@@ -47,10 +58,10 @@ module EventSourcery
     end
 
     # Logger instance used by EventSourcery.
-    # By default EventSourcery will log to STDOUT with a log level of Logger::DEBUG
+    # By default EventSourcery will log to STDOUT with a log level of Logger::INFO
     def logger
       @logger ||= ::Logger.new(STDOUT).tap do |logger|
-        logger.level = Logger::DEBUG
+        logger.level = Logger::INFO
       end
     end
 

data/lib/event_sourcery/event_processing/esp_process.rb

@@ -26,6 +26,7 @@ module EventSourcery
       rescue Exception => e
         EventSourcery.logger.fatal("An unhandled exception occurred in #{processor_name}")
         EventSourcery.logger.fatal(e)
+        EventSourcery.config.on_event_processor_critical_error.call(e, processor_name)
         raise e
       end
 

data/lib/event_sourcery/event_processing/esp_runner.rb

@@ -7,14 +7,18 @@ module EventSourcery
                      event_source:,
                      max_seconds_for_processes_to_terminate: 30,
                      shutdown_requested: false,
-                     after_fork: nil)
+                     after_fork: nil,
+                     after_subprocess_termination: nil,
+                     logger: EventSourcery.logger)
         @event_processors = event_processors
         @event_source = event_source
-        @pids = []
+        @pids = {}
         @max_seconds_for_processes_to_terminate = max_seconds_for_processes_to_terminate
         @shutdown_requested = shutdown_requested
         @exit_status = true
         @after_fork = after_fork
+        @after_subprocess_termination = after_subprocess_termination
+        @logger = logger
       end
 
       # Start each Event Stream Processor in a new child process.
@@ -22,8 +26,9 @@ module EventSourcery
         with_logging do
           start_processes
           listen_for_shutdown_signals
-          wait_till_shutdown_requested
-          record_terminated_processes
+          while_waiting_for_shutdown do
+            record_terminated_processes
+          end
           terminate_remaining_processes
           until all_processes_terminated? || waited_long_enough?
             record_terminated_processes
@@ -34,25 +39,36 @@ module EventSourcery
         exit_indicating_status_of_processes
       end
 
+      def start_processor(event_processor)
+        process = ESPProcess.new(
+          event_processor: event_processor,
+          event_source: @event_source,
+          after_fork: @after_fork,
+        )
+        pid = Process.fork { process.start }
+        @pids[pid] = event_processor
+      end
+
+      def shutdown
+        @shutdown_requested = true
+      end
+
+      def shutdown_requested?
+        @shutdown_requested
+      end
+
       private
 
+      attr_reader :logger
+
       def with_logging
-        EventSourcery.logger.info { 'Forking ESP processes' }
+        logger.info('ESPRunner: Forking processes')
         yield
-        EventSourcery.logger.info { 'ESP processes shutdown' }
+        logger.info('ESPRunner: Processes shutdown')
       end
 
       def start_processes
-        @event_processors.each(&method(:start_process))
-      end
-
-      def start_process(event_processor)
-        process = ESPProcess.new(
-          event_processor: event_processor,
-          event_source: @event_source,
-          after_fork: @after_fork,
-        )
-        @pids << Process.fork { process.start }
+        @event_processors.each(&method(:start_processor))
       end
 
       def listen_for_shutdown_signals
@@ -61,12 +77,12 @@ module EventSourcery
         end
       end
 
-      def shutdown
-        @shutdown_requested = true
-      end
-
-      def wait_till_shutdown_requested
-        sleep(1) until @shutdown_requested
+      def while_waiting_for_shutdown
+        loop do
+          yield
+          break if shutdown_requested?
+          sleep(1)
+        end
       end
 
       def terminate_remaining_processes
@@ -77,19 +93,24 @@ module EventSourcery
         send_signal_to_remaining_processes(:KILL)
       end
 
-
       def send_signal_to_remaining_processes(signal)
-        Process.kill(signal, *@pids) unless all_processes_terminated?
+        return if all_processes_terminated?
+
+        logger.info("ESPRunner: Sending #{signal} to [#{@pids.values.map(&:processor_name).join(', ')}]")
+        Process.kill(signal, *@pids.keys)
       rescue Errno::ESRCH
         record_terminated_processes
         retry
       end
 
       def record_terminated_processes
-        until all_processes_terminated? ||
-              ((pid, status) = Process.wait2(-1, Process::WNOHANG)).nil?
-          @pids.delete(pid)
+        until all_processes_terminated? || (pid, status = Process.wait2(-1, Process::WNOHANG)).nil?
+          event_processor = @pids.delete(pid)
+          logger.info("ESPRunner: Process #{event_processor&.processor_name || pid} " \
+                      "terminated with exit status: #{status.exitstatus.inspect}")
+          next unless event_processor
           @exit_status &&= !!status.success?
+          @after_subprocess_termination&.call(processor: event_processor, runner: self, exit_status: status.exitstatus)
         end
       end
 

data/lib/event_sourcery/event_store/event_builder.rb

@@ -5,10 +5,10 @@ module EventSourcery
         @event_type_serializer = event_type_serializer
       end
 
-      def build(event_data)
+      def build(**event_data)
         type = event_data.fetch(:type)
         klass = event_type_serializer.deserialize(type)
-        upcast(klass.new(event_data))
+        upcast(klass.new(**event_data))
       end
 
       private

data/lib/event_sourcery/rspec/event_store_shared_examples.rb

@@ -212,9 +212,9 @@ RSpec.shared_examples 'an event store' do
       end
     end
 
-    def events_by_range(*args)
+    def events_by_range(from_event_id, to_event_id, **args)
       [].tap do |events|
-        event_store.each_by_range(*args) do |event|
+        event_store.each_by_range(from_event_id, to_event_id, **args) do |event|
           events << event
         end
       end

data/lib/event_sourcery/version.rb

@@ -1,4 +1,4 @@
 module EventSourcery
   # Defines the version
-  VERSION = '0.21.0'.freeze
+  VERSION = '0.24.0'.freeze
 end

metadata

@@ -1,43 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: event_sourcery
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Envato
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-01 00:00:00.000000000 Z
+date: 2021-11-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.10'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -127,7 +127,7 @@ homepage: https://github.com/envato/event_sourcery
 licenses: []
 metadata:
   bug_tracker_uri: https://github.com/envato/event_sourcery/issues
-  changelog_uri: https://github.com/envato/event_sourcery/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/envato/event_sourcery/blob/HEAD/CHANGELOG.md
   source_code_uri: https://github.com/envato/event_sourcery
 post_install_message: 
 rdoc_options: []
@@ -144,8 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Event Sourcing Library