mediate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06e45660926271c9435a4c2dd1634974b3873091f12160b907833cab8c9b7abf
+  data.tar.gz: 8b1fe7523830f57f8e2499bf8c3575ffc0eef7716478a554f683947a8958dd95
+SHA512:
+  metadata.gz: 6f29b77858c6361cbdc54ccc79656d470dd2feb274fe341746fa66d9fc33e34a7c1906bc8df859dfbb0dbf68fa73fc5f1b7819a2bb889565c91388abfbd8d090
+  data.tar.gz: 20c32a19443169eb74e41524b8ae9a342a023a2f54a306d182c3419988dbc5479a739c5866012d29a83e1cb1aeace714f6677efaab7c6368d90082fa0655c879

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,140 @@
+AllCops:
+  TargetRubyVersion: 2.6
+Gemspec/DeprecatedAttributeAssignment: # new in 1.30
+  Enabled: true
+Gemspec/RequireMFA: # new in 1.23
+  Enabled: true
+Layout/LineContinuationLeadingSpace: # new in 1.31
+  Enabled: true
+Layout/LineContinuationSpacing: # new in 1.31
+  Enabled: true
+Layout/LineEndStringConcatenationIndentation: # new in 1.18
+  Enabled: true
+Layout/LineLength:
+  Max: 120
+Layout/SpaceBeforeBrackets: # new in 1.7
+  Enabled: true
+Lint/AmbiguousAssignment: # new in 1.7
+  Enabled: true
+Lint/AmbiguousOperatorPrecedence: # new in 1.21
+  Enabled: true
+Lint/AmbiguousRange: # new in 1.19
+  Enabled: true
+Lint/ConstantOverwrittenInRescue: # new in 1.31
+  Enabled: true
+Lint/DeprecatedConstants: # new in 1.8
+  Enabled: true
+Lint/DuplicateBranch: # new in 1.3
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # new in 1.1
+  Enabled: true
+Lint/EmptyBlock: # new in 1.1
+  Enabled: true
+Lint/EmptyClass: # new in 1.3
+  Enabled: false
+Lint/EmptyInPattern: # new in 1.16
+  Enabled: true
+Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock: # new in 1.8
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # new in 1.2
+  Enabled: true
+Lint/NonAtomicFileOperation: # new in 1.31
+  Enabled: true
+Lint/NumberedParameterAssignment: # new in 1.9
+  Enabled: true
+Lint/OrAssignmentToConstant: # new in 1.9
+  Enabled: true
+Lint/RedundantDirGlobSort: # new in 1.8
+  Enabled: true
+Lint/RefinementImportMethods: # new in 1.27
+  Enabled: true
+Lint/RequireRelativeSelfPath: # new in 1.22
+  Enabled: true
+Lint/SymbolConversion: # new in 1.9
+  Enabled: true
+Lint/ToEnumArguments: # new in 1.1
+  Enabled: true
+Lint/TripleQuotes: # new in 1.9
+  Enabled: true
+Lint/UnexpectedBlockArity: # new in 1.5
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # new in 1.1
+  Enabled: true
+Lint/UselessRuby2Keywords: # new in 1.23
+  Enabled: true
+Metrics/BlockLength:
+  IgnoredMethods: ['describe', 'context']
+Metrics/ClassLength:
+  Max: 150
+Naming/BlockForwarding: # new in 1.24
+  Enabled: true
+Security/CompoundHash: # new in 1.28
+  Enabled: true
+Security/IoMethods: # new in 1.22
+  Enabled: true
+Style/ArgumentsForwarding: # new in 1.1
+  Enabled: true
+Style/CollectionCompact: # new in 1.2
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # new in 1.1
+  Enabled: true
+Style/EndlessMethod: # new in 1.8
+  Enabled: true
+Style/EnvHome: # new in 1.29
+  Enabled: true
+Style/FetchEnvVar: # new in 1.28
+  Enabled: true
+Style/FileRead: # new in 1.24
+  Enabled: true
+Style/FileWrite: # new in 1.24
+  Enabled: true
+Style/HashConversion: # new in 1.10
+  Enabled: true
+Style/HashExcept: # new in 1.7
+  Enabled: true
+Style/IfWithBooleanLiteralBranches: # new in 1.9
+  Enabled: true
+Style/InPatternThen: # new in 1.16
+  Enabled: true
+Style/MapCompactWithConditionalBlock: # new in 1.30
+  Enabled: true
+Style/MapToHash: # new in 1.24
+  Enabled: true
+Style/MultilineInPatternThen: # new in 1.16
+  Enabled: true
+Style/NegatedIfElseCondition: # new in 1.2
+  Enabled: true
+Style/NestedFileDirname: # new in 1.26
+  Enabled: true
+Style/NilLambda: # new in 1.3
+  Enabled: true
+Style/NumberedParameters: # new in 1.22
+  Enabled: true
+Style/NumberedParametersLimit: # new in 1.22
+  Enabled: true
+Style/ObjectThen: # new in 1.28
+  Enabled: true
+Style/OpenStructUse: # new in 1.23
+  Enabled: true
+Style/QuotedSymbols: # new in 1.16
+  Enabled: true
+Style/RedundantArgument: # new in 1.4
+  Enabled: true
+Style/RedundantInitialize: # new in 1.27
+  Enabled: true
+Style/RedundantSelfAssignmentBranch: # new in 1.19
+  Enabled: true
+Style/SelectByRegexp: # new in 1.22
+  Enabled: true
+Style/StringChars: # new in 1.12
+  Enabled: true
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+Style/SwapValues: # new in 1.1
+  Enabled: true

data/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+    "recommendations": []
+}

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in mediate.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "yard", "~> 0.9.28"
+
+gem "concurrent-ruby", "~> 1.1", require: "concurrent"

data/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: .
+  specs:
+    mediate (0.1.0)
+      concurrent-ruby (~> 1.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    concurrent-ruby (1.1.10)
+    diff-lcs (1.5.0)
+    json (2.6.2)
+    parallel (1.22.1)
+    parser (3.1.2.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.5.0)
+    rexml (3.2.5)
+    rspec (3.11.0)
+      rspec-core (~> 3.11.0)
+      rspec-expectations (~> 3.11.0)
+      rspec-mocks (~> 3.11.0)
+    rspec-core (3.11.0)
+      rspec-support (~> 3.11.0)
+    rspec-expectations (3.11.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-mocks (3.11.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.11.0)
+    rspec-support (3.11.0)
+    rubocop (1.31.2)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.18.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.19.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    unicode-display_width (2.2.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
+
+PLATFORMS
+  arm64-darwin-21
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  concurrent-ruby (~> 1.1)
+  mediate!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  yard (~> 0.9.28)
+
+BUNDLED WITH
+   2.3.17

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,293 @@
+# Mediate
+
+A simple mediator implementation for Ruby inspired by [Mediatr](https://github.com/jbogard/MediatR).
+
+Decouple application components by sending a request through the mediator and receiving a response from a handler, instead of directly calling methods on imported classes.
+
+Supports request/response, notifications (i.e., events), pre- and post-request handler decorators, and error handling.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Requests](#requests)
+    - [Implicit handler declaration](#implicit-handler-declaration)
+    - [Request polymorphism](#request-polymorphism)
+    - [Pre- and post-request behaviors](#pre--and-post-request-behaviors)
+  - [Notifications](#notifications)
+  - [Error handlers](#error-handlers)
+  - [Testing](#testing)
+    - [Testing implicit request handlers](#testing-implicit-request-handlers)
+  - [Using with Rails](#using-with-rails)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Add this to your Gemfile:
+
+```ruby
+gem "mediate"
+```
+
+And run:
+
+```sh
+bundle
+```
+
+## Usage
+
+There are two types of messages that can be sent through the mediator:
+
+- Requests (`Mediate::Request`) have exactly one handler (`Mediate::RequestHandler`), which returns a response.
+- Notifications (`Mediate::Notification`) are `publish`ed to zero or more handlers (`Mediate::NotificationHandler`).  Nothing is returned to the caller.
+
+### Requests
+
+To define a request, declare a class that inherits from `Mediate::Request`.
+
+```ruby
+class Ping < Mediate::Request
+    attr_reader :message
+
+    def initialize(message)
+        @message = message
+        super()
+    end
+end
+```
+
+To register a handler for it, declare a class that inherits from `Mediate::RequestHandler`, call the class method `handles` passing the class of requests that it handles, and implement the `handle` method.
+
+```ruby
+class PingHandler < Mediate::RequestHandler
+    handles Ping
+
+    def handle(request)
+        "Received: #{request.message}"
+    end
+end
+```
+
+To send a request, pass it to `Mediate.dispatch`.  The mediator will resolve the registered handler according to the request type and return the result of its `handle` method.
+
+```ruby
+response = Mediate.dispatch(Ping.new('hello'))
+puts response # 'Received: hello'
+```
+
+The only requirement for `RequestHandler`s, besides implementing the `handle` method, is that __they should have a constructor that can be called without arguments__.  This applies to all `*Handler` and `*Behavior` classes.  For example, the following would work because all constructor parameters have default values.
+
+```ruby
+class PingHandler < Mediate::RequestHandler
+    handles Ping
+
+    def initialize(service = SomeService.new)
+        @service = service
+    end
+
+    def handle(request)
+        @service.call("Received: #{request.message}")
+    end
+end
+```
+
+Note that only one handler can be registered for a particular request class; attempting to register another handler for `Ping` would raise a `RequestHandlerAlreadyExistsError`.
+
+#### Implicit handler declaration
+
+For simple handlers, you can skip the explicit `RequestHandler` declaration above and instead pass a block to `Request.handle_with`.
+
+```ruby
+class Ping < Mediate::Request
+    attr_reader :message
+
+    def initialize(message)
+        @message = message
+        super()
+    end
+    # This will have the same behavior as the PingHandler declaration above.
+    handle_with { |request| "Received: #{request.message}" }
+end
+
+response = Mediate.dispatch(Ping.new('hello'))
+puts response # 'Received: hello'
+```
+
+Behind the scenes, this defines a `Ping::Handler` class that calls the given block in its `handle` method.  For testing purposes, you can get an instance of this handler class by calling `Mediate::Request.create_implicit_handler` (see [Testing implicit request handlers](#testing-implicit-request-handlers)).
+
+#### Request polymorphism
+
+The mediator resolves handlers by moving up the request's inheritance chain until it finds a registered handler for that class.  For example, subclasses of `Ping` would be handled by `PingHandler`.
+
+```ruby
+class SubPing < Ping; end
+puts Mediate.dispatch(SubPing.new('howdy')) # 'Received: howdy'
+```
+
+Unless we registered a handler for `SubPing` explicitly.
+
+```ruby
+class SubPing < Ping
+    handle_with { |request| "Received from SubPing: #{request.message}" }
+end
+puts Mediate.dispatch(SubPing.new('howdy')) # 'Received from SubPing: howdy'
+```
+
+#### Pre- and post-request behaviors
+
+For certain cases, you will want code to run before or after a request is handled, e.g., logging, authorization, validation, backwards compatibility, etc.  Effectively, these act as decorators for your request handler(s).  You can register `Mediate::PrerequestBehavior`s and `Mediate::PostrequestBehavior`s for this purpose.
+
+Behaviors will run for any request that is or inherits from the request class registered.  For example, if you wanted a behavior to run for every request, you could register it with `handles Mediate::Request`.  Unlike request handlers, multiple behaviors can be registered for the same request class.
+
+```ruby
+class PreLoggingBehavior < Mediate::PrerequestBehavior
+    handles Mediate::Request # This will be called before all request handlers
+
+    def initialize(logger = Logger)
+        @logger = logger
+    end
+
+    def handle(request)
+        @logger.info("Received request: #{request}")
+    end
+end
+
+class PingValidator < Mediate::PrerequestBehavior
+    handles Ping # Will be called before Ping requests or any subclasses of Ping
+
+    def handle(request)
+        raise "Ping is missing message" if request.message.nil?
+    end
+end
+
+class PostLoggingBehavior < Mediate::PostrequestBehavior
+    handles Mediate::Request # Will be called after all request handlers
+
+    def initialize(logger = Logger)
+        @logger = logger
+    end
+
+    def handle(request, result)
+        @logger.info("Request: #{request} resulted in #{result}")
+    end
+end
+```
+
+### Notifications
+
+Notifications are messages that can be passed to multiple handlers.  To publish a notification, call `Mediate.publish(notification)`.  No response is returned from `publish`.
+
+Define a notification by inheriting from `Mediate::Notification`.
+
+```ruby
+class PostCreated < Mediate::Notification
+    attr_reader :post
+
+    def initialize(post)
+        @post = post
+    end
+end
+```
+
+Declare and register a handler by inheriting from `Mediate::NotificationHandler`, calling `handles` with the notification class to handle, and implementing the `handle` method.
+
+```ruby
+class PostCreatedHandler < Mediate::NotificationHandler
+    handles PostCreated
+    
+    def handle(notification)
+        # do something with PostCreated notification...
+    end
+end
+```
+
+Like [request behaviors](#pre--and-post-request-behaviors), all notification handlers that are registered for a notification class or any of its superclasses will be called when a given notification is published.  For example, a handler that `handles Mediate::Notification` will be called when any notification is published.  Handlers will be called in order of inheritance of their registered notifications from subclass to superclass (and in order of registration if the registered notification class is the same).
+
+### Error handlers
+
+When a request or notification handler raises a `StandardError`, the mediator will find all `ErrorHandler`s that have been registered for that request/notification class (or superclasses) and the exception class (or superclasses).
+
+```ruby
+# This will be called on any StandardError from any request or notification handler
+class GlobalErrorHandler < Mediate::ErrorHandler
+    handles StandardError, Mediate::Request
+    handles StandardError, Mediate::Notification
+
+    # dispatched is the Request or Notification
+    def handle(dispatched, exception, state)
+        # do something...
+    end
+end
+
+# This would get called when ActiveRecord::RecordNotFound is raised while handling a QueryRequest
+class NotFoundHandler < Mediate::ErrorHandler
+    handles ActiveRecord::RecordNotFound, QueryRequest
+
+    def handle(dispatched, exception, state)
+        # ...
+    end
+end
+```
+
+Note that the exception class passed to handles must be `StandardError` or a subclass of it.
+
+The `state` parameter of `handle` is a `Mediate::ErrorHandlerState` instance that represents whether the exception has been "handled" or not.  By calling `set_as_handled` and optionally passing in a result, all subsequent error handlers will be skipped and the given result will be returned to the caller of `dispatch` (obviously, if the error was raised from a notification handler, nothing will be returned).
+
+```ruby
+class ValidationErrorHandler < Mediate::ErrorHandler
+    handles ActiveRecord::RecordInvalid, Mediate::Request
+
+    def handle(dispatched, exception, state)
+        state.set_as_handled(exception.record.errors)
+    end
+end
+```
+
+### Testing
+
+All of the handler and behavior classes described above are just normal Ruby classes.  You can instantiate them and call their `handle` methods to test as you normally would.
+
+Special consideration is only required when testing paths that invoke methods on the mediator itself (e.g., `Mediate.dispatch` or `Mediate.publish`), since it is designed to be a singleton.  The mediator's registration methods are idempotent (and thread-safe), so re-registering handlers should not cause issues.  However, if you want to ensure that you are not sharing state between tests, you can call the `Mediate.mediator.reset` method in your test setup or clean-up to remove all handler and behavior registrations.
+
+#### Testing implicit request handlers
+
+How can you test a request handler defined using `handle_with` and a block like the following?
+
+```ruby
+class ExampleRequest < Mediate::Request
+    handle_with do |request|
+        # ....
+    end
+end
+```
+
+The `handle_with` method defines a handler class and registers it with the mediator to handle the containing request class.  `Mediate::Request` provides a convenience method, `create_implicit_handler`, that creates an instance of this handler class.  You can then call `handle` on that method like normal to test it.
+
+```ruby
+RSpec.describe "ExampleRequestHandler" do
+    let(:handler) { ExampleRequest.create_implicit_handler }
+
+    it "returns something" do
+        expect(handler.handle(ExampleRequest.new)).to be_truthy
+    end
+end
+```
+
+### Using with Rails
+
+TODO
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome in this repo.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "yard"
+
+YARD::Rake::YardocTask.new
+
+task default: %i[spec rubocop]

data/lib/mediate/error_handler.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # @abstract override {#handle} to implement.
+  #
+  # An abstract base class that handles exceptions raised by request handlers, behaviors, or notification handlers.
+  #
+  class ErrorHandler
+    #
+    # Registers this to handle exceptions of type exception_class when raised while handling requests or notifications
+    #   of type dispatched_class.
+    #
+    # @param [StandardError] exception_class the type of exceptions that this should handle
+    # @param [Class] dispatched_class the request or notification type
+    #  (should inherit from Mediate::Request or Mediate::Notification)
+    # @param [Mediate::Mediator] mediator the Mediator instance to register on
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if exception_class is not a StandardError
+    #   or dispatched_class is not a Request or Notification
+    def self.handles(exception_class = StandardError, dispatched_class = Mediate::Request, mediator = Mediate.mediator)
+      mediator.register_error_handler(self, exception_class, dispatched_class)
+    end
+
+    #
+    # The method to implement to handle exceptions.
+    #
+    # @abstract
+    #
+    # @param [Mediate::Request, Mediate::Notification] _dispatched the request or notification that was been handled
+    # @param [StandardError] _exception the exception that was raised
+    # @param [Mediate::ErrorHandlerState] _state the result of handling the current exception--
+    #   call state.set_as_handled(result) to skip subsequent error handlers and return result
+    #   (if the exception was thrown while handling a request; notification handlers will not return anything)
+    #
+    # @return [void]
+    #
+    def handle(_dispatched, _exception, _state)
+      raise NoMethodError, "handle must be implemented"
+    end
+  end
+end

data/lib/mediate/error_handler_state.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # Represents the result of handling an exception
+  #
+  class ErrorHandlerState
+    attr_reader :result
+
+    #
+    # Sets the state as handled with the given result. Subsequent error handlers will be skipped and, if
+    #   the exception was thrown while handling a Mediate::Request, this result will be returned.
+    #
+    # @param result if the exception was thrown as part of handling a Mediate::Request, this will be returned
+    #
+    # @return [Boolean] true
+    #
+    def set_as_handled(result = nil)
+      @result = result
+      @handled = true
+    end
+
+    #
+    # Indicates whether the current exception has been handled and the result should be returned (if applicable).
+    #
+    # @return [Boolean] whether the current exception has been handled
+    #
+    def handled?
+      !!@handled
+    end
+  end
+end

data/lib/mediate/errors/no_handler_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # Namespace that contains custom Mediate errors.
+  #
+  module Errors
+    #
+    # Indicates that a Mediate::Request was sent to the Mediator, but no Mediate::RequestHandler
+    #   was registered to handle it.
+    #
+    class NoHandlerError < StandardError
+      def initialize(request_class)
+        super("No handler for #{request_class}. Call handles(#{request_class}) on a RequestHandler to register.")
+      end
+    end
+  end
+end

data/lib/mediate/errors/request_handler_already_exists_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # Namespace that contains custom Mediate errors.
+  #
+  module Errors
+    #
+    # Indicates that a Mediate::RequestHandler was already registered for the given request_class.
+    #
+    class RequestHandlerAlreadyExistsError < StandardError
+      def initialize(request_class, registered_handler_class, attempted_handler_class)
+        super("Attempted to register #{attempted_handler_class} to handle #{request_class},\
+          but #{registered_handler_class} is already registered to handle #{request_class}.\
+          This is probably a mistake, as only one handler should be registered per request type.")
+      end
+    end
+  end
+end

data/lib/mediate/mediator.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "singleton"
+
+require_relative "errors/no_handler_error"
+require_relative "errors/request_handler_already_exists_error"
+require_relative "error_handler"
+require_relative "error_handler_state"
+require_relative "notification"
+require_relative "notification_handler"
+require_relative "postrequest_behavior"
+require_relative "prerequest_behavior"
+require_relative "request"
+require_relative "request_handler"
+
+module Mediate
+  #
+  # Implements the mediator pattern.  Call {#dispatch} to send requests and
+  #   {#publish} to publish notifications.
+  #
+  class Mediator
+    include Singleton
+    REQUEST_BASE = Mediate::Request
+    NOTIF_BASE = Mediate::Notification
+    private_constant :REQUEST_BASE, :NOTIF_BASE
+
+    def initialize
+      reset
+    end
+
+    #
+    # Sends a request to the registered handler, passing to any applicable pipeline behaviors.
+    #
+    # @param [Mediate::Request] request
+    #
+    # @return the response returned from the Mediate::RequestHandler
+    #
+    # @raise [ArgumentError] if request is nil
+    # @raise [Mediate::Errors::NoHandlerError] if no handlers have been registered for the given request's type
+    #
+    def dispatch(request)
+      raise ArgumentError, "request cannot be nil" if request.nil?
+
+      request_handler = resolve_handler(@request_handlers, request.class, REQUEST_BASE)
+      raise Errors::NoHandlerError, request.class if request_handler == NullHandler
+
+      prerequest_handlers = collect_by_inheritance(@prerequest_behaviors, request.class, REQUEST_BASE)
+      postrequest_handlers = collect_by_inheritance(@postrequest_behaviors, request.class, REQUEST_BASE)
+      run_request_pipeline(request, prerequest_handlers, request_handler, postrequest_handlers)
+    end
+
+    #
+    # Sends a notification to all register handlers for the given notification's type.
+    #
+    # @param [Mediate::Notification] notification
+    #
+    # @return [void]
+    #
+    def publish(notification)
+      raise ArgumentError, "notification cannot be nil" if notification.nil?
+
+      handler_classes = collect_by_inheritance(@notification_handlers, notification.class, NOTIF_BASE)
+      handler_classes.each do |handler_class|
+        handler_class.new.handle(notification)
+      rescue StandardError => e
+        handle_exception(notification, e, NOTIF_BASE)
+        # Don't break from loop, since we don't want a single notification handler to prevent others from
+        # receiving notification.
+      end
+    end
+
+    def register_request_handler(handler_class, request_class)
+      validate_base_class(handler_class, Mediate::RequestHandler)
+      validate_base_class(request_class, REQUEST_BASE)
+      raise_if_request_handler_exists(request_class, handler_class)
+      @request_handlers[request_class] = handler_class
+    end
+
+    def register_notification_handler(handler_class, notif_class)
+      validate_base_class(handler_class, Mediate::NotificationHandler)
+      validate_base_class(notif_class, NOTIF_BASE, allow_base: true)
+      append_to_hash_value(@notification_handlers, notif_class, handler_class)
+    end
+
+    def register_prerequest_behavior(behavior_class, request_class)
+      validate_base_class(behavior_class, Mediate::PrerequestBehavior)
+      validate_base_class(request_class, REQUEST_BASE, allow_base: true)
+      append_to_hash_value(@prerequest_behaviors, request_class, behavior_class)
+    end
+
+    def register_postrequest_behavior(behavior_class, request_class)
+      validate_base_class(behavior_class, Mediate::PostrequestBehavior)
+      validate_base_class(request_class, REQUEST_BASE, allow_base: true)
+      append_to_hash_value(@postrequest_behaviors, request_class, behavior_class)
+    end
+
+    def register_error_handler(handler_class, exception_class, dispatch_class)
+      if dispatch_class <= NOTIF_BASE
+        register_error_handler_for_dispatch(handler_class, exception_class, dispatch_class, NOTIF_BASE)
+      else
+        register_error_handler_for_dispatch(handler_class, exception_class, dispatch_class, REQUEST_BASE)
+      end
+    end
+
+    #
+    # Clears all registered handlers and behaviors for this Mediator instance. This is useful
+    #   for cleaning up after integration tests.
+    #
+    # @return [void]
+    #
+    def reset
+      @request_handlers = Concurrent::Map.new
+      @notification_handlers = Concurrent::Map.new
+      @prerequest_behaviors = Concurrent::Map.new
+      @postrequest_behaviors = Concurrent::Map.new
+      @exception_handlers = Concurrent::Map.new
+    end
+
+    private
+
+    def raise_if_request_handler_exists(request_class, new_handler)
+      registered = @request_handlers.fetch(request_class, nil)
+      return if registered.nil? || registered == new_handler
+
+      raise Errors::RequestHandlerAlreadyExistsError.new(request_class, registered, new_handler)
+    end
+
+    def register_error_handler_for_dispatch(handler_class, exception_class, dispatch_class, dispatch_base_class)
+      validate_base_class(handler_class, Mediate::ErrorHandler)
+      validate_base_class(exception_class, StandardError, allow_base: true)
+      validate_base_class(dispatch_class, dispatch_base_class, allow_base: true)
+      map = @exception_handlers.fetch_or_store(exception_class, Concurrent::Map.new)
+      append_to_hash_value(map, dispatch_class, handler_class)
+    end
+
+    def run_request_pipeline(request, pre_handlers, request_handler, post_handlers)
+      result = nil
+      pre_handlers.each { |handler_class| handler_class.new.handle(request) }
+      result = request_handler.new.handle(request)
+      post_handlers.each { |handler_class| handler_class.new.handle(request, result) }
+      result
+    rescue StandardError => e
+      handle_exception(request, e, REQUEST_BASE)
+    end
+
+    def append_to_hash_value(hash, key, value)
+      hash[key] = hash.fetch(key, Concurrent::Set.new) << value
+    end
+
+    def validate_base_class(given, expected_base, allow_base: false)
+      raise ArgumentError, "class cannot be nil" if given.nil? || expected_base.nil?
+
+      return if allow_base && given == expected_base
+
+      raise ArgumentError, "#{given} does not inherit from #{expected_base}" unless given < expected_base
+    end
+
+    def handle_exception(dispatched, exception, dispatch_base_class)
+      exception_to_dispatched_maps = collect_by_inheritance(@exception_handlers, exception.class, StandardError)
+      handler_classes = exception_to_dispatched_maps.reduce(Concurrent::Set.new) do |memo, curr|
+        collect_by_inheritance(curr, dispatched.class, dispatch_base_class, memo)
+      end
+      state = ErrorHandlerState.new
+      handler_classes.each do |handler_class|
+        handler_class.new.handle(dispatched, exception, state)
+        break if state.handled?
+      end
+      state.result
+    end
+
+    def resolve_handler(handlers_hash, request_class, base_class)
+      value = handlers_hash[request_class]
+      return value unless value.nil?
+      return NullHandler if request_class >= base_class
+
+      resolve_handler(handlers_hash, request_class.superclass, base_class)
+    end
+
+    def collect_by_inheritance(hash, key_class, base_class, collected = Concurrent::Set.new)
+      values = hash.fetch(key_class, Concurrent::Set.new)
+      # Wrap values in Set and flatten to account for case when values is not a Set itself.
+      # This may break if values is nested Sets, although we don't have that case yet.
+      new_collected = (collected || Concurrent::Set.new) | Concurrent::Set[values].flatten
+      return new_collected if key_class > base_class
+
+      collect_by_inheritance(hash, key_class.superclass, base_class, new_collected)
+    end
+
+    #
+    # A null object for a Mediate::RequestHandler
+    #
+    class NullHandler; end
+  end
+end

data/lib/mediate/notification.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # The base class of a notification that can be published to multiple handlers.
+  #
+  class Notification
+  end
+end

data/lib/mediate/notification_handler.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # @abstract override {#handle} to implement.
+  #
+  # Abstract base class of a handler of notifications.
+  #
+  class NotificationHandler
+    #
+    # Registers this handler for the given notification Class.
+    #   The notification Class must have Mediate::Notification as a superclass.
+    #
+    # @param [Class] notif_class the Class of the notifications that get passed to this handler
+    # @param [Mediate::Mediator] mediator the mediator instance to register the handler with
+    #
+    # @raise [ArgumentError] if notif_class does not inherit from Mediate::Notification
+    #
+    # @return [void]
+    #
+    def self.handles(notif_class = Mediate::Notification, mediator = Mediate.mediator)
+      mediator.register_notification_handler(self, notif_class)
+    end
+
+    #
+    # The method to implement that handles the notifications registered for this handler.
+    #
+    # @abstract
+    #
+    # @param [Mediate::Notification] _notification
+    #
+    # @return [void]
+    #
+    def handle(_notification)
+      raise NoMethodError, "handle must be implemented"
+    end
+  end
+end

data/lib/mediate/postrequest_behavior.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # @abstract override {#handle} to implement
+  #
+  # Abstract base class of a pipeline behavior that processes a request after the RequestHandler finishes.
+  #
+  class PostrequestBehavior
+    #
+    # Registers this behavior to handle requests of the given type.
+    #
+    # @param [Class] request_class the type of requests to handle (should inherit from Mediate::Request)
+    # @param [Mediate::Mediator] mediator the Mediator instance to register to
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if request_class does not inherit from Mediate::Request
+    #
+    def self.handles(request_class = Mediate::Request, mediator = Mediate.mediator)
+      mediator.register_postrequest_behavior(self, request_class)
+    end
+
+    #
+    # @abstract
+    #
+    # The method that handles the request and the result that the handler returned.
+    #
+    # @param [Mediate::Request] _request
+    # @param _result what was returned by the RequestHandler
+    #
+    # @return [void]
+    #
+    def handle(_request, _result)
+      raise NoMethodError, "handle must be implemented"
+    end
+  end
+end

data/lib/mediate/prerequest_behavior.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # @abstract override {#handle} to implement
+  #
+  # Abstract base class of a pipeline behavior that processes a request before it's given to the handler.
+  #
+  class PrerequestBehavior
+    #
+    # Registers this behavior to handle requests of the given type.
+    #
+    # @param [Class] request_class the type of requests to handle (should inherit from Mediate::Request)
+    # @param [Mediate::Mediator] mediator the Mediator instance to register to
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] if request_class does not inherit from Mediate::Request
+    #
+    def self.handles(request_class = Mediate::Request, mediator = Mediate.mediator)
+      mediator.register_prerequest_behavior(self, request_class)
+    end
+
+    #
+    # @abstract
+    #
+    # The method that handles the request.
+    #
+    # @param [Mediate::Request] _request
+    #
+    # @return [void]
+    #
+    def handle(_request)
+      raise NoMethodError, "handle must be implemented"
+    end
+  end
+end

data/lib/mediate/request.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # The base class of a request that can be dispatched to the mediator, which
+  # returns a response from its handler.
+  #
+  class Request
+    IMPLICIT_HANDLER_CLASS_NAME = "Handler"
+
+    #
+    # Registers a handler for this Request type using the given block as the handle method.
+    #
+    # @param [Mediate::Mediator] mediator the instance to register the handler on
+    # @param [Proc] &proc the block that will handle the request
+    #
+    # @raises [ArgumentError] if no block is given
+    #
+    # @example When a request of this type is dispatched, the handle_with block will run
+    #   class MyRequest < Mediate::Request
+    #     handle_with do |request|
+    #       ## do something with request...
+    #     end
+    #   end
+    def self.handle_with(mediator = Mediate.mediator, &proc)
+      raise ArgumentError, "expected block to be passed to #handle_with." unless proc
+
+      if implicit_handler_defined?
+        raise "#{name}::#{IMPLICIT_HANDLER_CLASS_NAME} is already defined. Cannot create implicit handler."
+      end
+
+      handler_class = define_handler(proc)
+      const_set(IMPLICIT_HANDLER_CLASS_NAME, handler_class)
+      mediator.register_request_handler(handler_class, self)
+    end
+
+    #
+    # If an implicit handler is defined for this Request using the #handle_with method,
+    # this will return an instance of it. Use this for testing the handler.
+    #
+    # @return [Mediate::RequestHandler] the implicit handler class for this Request
+    #
+    # @raise [RuntimeError] if no implicit handler is defined
+    #
+    # @example Create an instance and call #handle on it to test it
+    #   handler = MyRequest.create_implicit_handler
+    #   result = handler.handle(MyRequest.new)
+    def self.create_implicit_handler
+      raise "Implicit handler is not defined." unless implicit_handler_defined?
+
+      const_get(IMPLICIT_HANDLER_CLASS_NAME).new
+    end
+
+    def self.undefine_implicit_handler
+      return unless implicit_handler_defined?
+
+      remove_const(IMPLICIT_HANDLER_CLASS_NAME)
+    end
+
+    def self.define_handler(proc)
+      Class.new(RequestHandler) do
+        @@handle_proc = proc # rubocop:disable Style/ClassVars
+        def handle(request)
+          @@handle_proc.call(request)
+        end
+      end
+    end
+
+    def self.implicit_handler_defined?
+      const_defined?(IMPLICIT_HANDLER_CLASS_NAME)
+    end
+
+    private_constant :IMPLICIT_HANDLER_CLASS_NAME
+    private_class_method :define_handler, :implicit_handler_defined?
+  end
+end

data/lib/mediate/request_handler.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Mediate
+  #
+  # @abstract override {#handle} to implement.
+  #
+  # Abstract base class of a handler of requests.  Each request type should have only one
+  # handler.
+  #
+  class RequestHandler
+    #
+    # Registers this handler for the given request Class.
+    #   The request Class must have Mediate::Request as a superclass.
+    #
+    # @param [Class] request_class the Class of the requests that get passed to this handler
+    # @param [Mediate::Mediator] mediator the mediator instance to register the handler with
+    #
+    # @raise [ArgumentError] if request_class does not inherit from Mediate::Request
+    #
+    # @return [void]
+    #
+    def self.handles(request_class, mediator = Mediate.mediator)
+      mediator.register_request_handler(self, request_class)
+    end
+
+    #
+    # The method to implement that handles the request of the type registered
+    # for this handler. Whatever this method returns will be returned to the sender of the request.
+    #
+    # @abstract
+    #
+    # @param [Mediate::Request] _request
+    #
+    # @return the result of handling the request
+    #
+    def handle(_request)
+      raise NoMethodError, "handle must be implemented"
+    end
+  end
+end

data/lib/mediate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Mediate
+  VERSION = "0.1.0"
+end

data/lib/mediate.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "mediate/version"
+require_relative "mediate/mediator"
+require "singleton"
+
+#
+# Namespace containing a simple implementation of the mediator pattern.
+#
+module Mediate
+  #
+  # Get the current mediator instance.  This will be a singleton
+  # throughout the lifetime of the program.
+  #
+  # @return [Mediate::Mediator] the current mediator instance
+  #
+  def self.mediator
+    Mediator.instance
+  end
+
+  #
+  # Sends a request to the registered handler, passing to any applicable pipeline behaviors.
+  #
+  # @param [Mediate::Request] request
+  #
+  # @return the response returned from the Mediate::RequestHandler
+  #
+  # @raise [ArgumentError] if request is nil
+  # @raise [Mediate::Errors::NoHandlerError] if no handlers have been registered for the given request's type
+  #
+  def self.dispatch(request)
+    mediator.dispatch(request)
+  end
+
+  #
+  # Sends a notification to all register handlers for the given notification's type.
+  #
+  # @param [Mediate::Notification] notification
+  #
+  # @return [void]
+  #
+  def self.publish(notification)
+    mediator.publish(notification)
+  end
+end

data/mediate.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/mediate/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mediate"
+  spec.version = Mediate::VERSION
+  spec.authors = ["Ryan Ferguson"]
+
+  spec.summary = "Simple mediator implementation"
+  spec.homepage = "https://github.com/rferg/mediate"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/rferg/mediate"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "concurrent-ruby", "~> 1.1"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/sig/mediate.rbs

@@ -0,0 +1,4 @@
+module Mediate
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: mediate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ryan Ferguson
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-08-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".vscode/extensions.json"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/mediate.rb
+- lib/mediate/error_handler.rb
+- lib/mediate/error_handler_state.rb
+- lib/mediate/errors/no_handler_error.rb
+- lib/mediate/errors/request_handler_already_exists_error.rb
+- lib/mediate/mediator.rb
+- lib/mediate/notification.rb
+- lib/mediate/notification_handler.rb
+- lib/mediate/postrequest_behavior.rb
+- lib/mediate/prerequest_behavior.rb
+- lib/mediate/request.rb
+- lib/mediate/request_handler.rb
+- lib/mediate/version.rb
+- mediate.gemspec
+- sig/mediate.rbs
+homepage: https://github.com/rferg/mediate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rferg/mediate
+  source_code_uri: https://github.com/rferg/mediate
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Simple mediator implementation
+test_files: []