omnes 0.1.0

data/lib/omnes/bus.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require "omnes/publication"
+require "omnes/registry"
+require "omnes/subscription"
+require "omnes/unstructured_event"
+
+module Omnes
+  # An event bus for the publish/subscribe pattern
+  #
+  # An instance of this class acts as an event bus middleware for publishers of
+  # events and their subscriptions.
+  #
+  # ```
+  # bus = Omnes::Bus.new
+  # ```
+  #
+  # Before being able to work with a given event, its name (a {Symbol}) needs to
+  # be registered:
+  #
+  # ```
+  # bus.register(:foo)
+  # ```
+  #
+  # An event can be anything responding to a method `:name` which, needless to
+  # say, must match with a registered name.
+  #
+  # Typically, there're two main ways to generate events.
+  #
+  # An event can be generated at publication time, where you provide its name
+  # and a payload to be consumed by its subscribers.
+  #
+  # ```
+  # bus.publish(:foo, bar: :baz)
+  # ```
+  #
+  # In that case, an instance of {Omnes::UnstructuredEvent} is generated
+  # under the hood.
+  #
+  # Unstructured events are straightforward to create and use, but they're
+  # harder to debug as they're defined at publication time. On top of that,
+  # other features, such as event persistence, can't be reliably built on top of
+  # them.
+  #
+  # You can also publish an instance of a class including {Omnes::Event}. The
+  # only fancy thing it provides is an OOTB event name generated based on the
+  # class name. See {Omnes::Event} for details.
+  #
+  # ```
+  # class Foo
+  #   include Omnes::Event
+  #
+  #   attr_reader :bar
+  #
+  #   def initialize
+  #     @bar = :baz
+  #   end
+  # end
+  #
+  # bus.publish(Foo.new)
+  # ```
+  #
+  # Instance-backed events provide a well-defined structure, and other features,
+  # like event persistence, can be added on top of them.
+  #
+  # Regardless of the type of published event, it's yielded to its subscriptions
+  # so that they can do their job:
+  #
+  # ```
+  # bus.subscribe(:foo) do |event|
+  #   # event.payload[:bar] or event[:bar] for unstructured events
+  #   # event.bar for the event instance example
+  # end
+  # ```
+  #
+  # The subscription code can be given as a block (previous example) or as
+  # anything responding to a method `#call`.
+  #
+  # ```
+  # class MySubscription
+  #   def call(event)
+  #     # ...
+  #   end
+  # end
+  #
+  # bus.subscribe(:foo, MySubscription.new)
+  # ```
+  #
+  # See also {Omnes::Subscriber} for a more powerful way to define standalone
+  # event handlers.
+  #
+  # You can also create a subscription that will run for all events:
+  #
+  # ```
+  # bus.subscribe_to_all(MySubscription.new)
+  # ```
+  #
+  # Custom matchers can be defined. A matcher is something responding to `#call`
+  # and taking the event as an argument. It needs to return `true` or `false` to
+  # decide whether the subscription needs to be run for that event.
+  #
+  # ```
+  # matcher ->(event) { event.name.start_with?(:foo) }
+  #
+  # bus.subscribe_with_matcher(matcher, MySubscription.new)
+  # ```
+  class Bus
+    # @api private
+    def self.EventType(value, **payload)
+      case value
+      when Symbol
+        UnstructuredEvent.new(omnes_event_name: value, payload: payload)
+      else
+        value
+      end
+    end
+
+    # @api private
+    attr_reader :cal_loc_start,
+                :subscriptions
+
+    # @!attribute [r] registry
+    #   @return [Omnes::Bus::Registry]
+    attr_reader :registry
+
+    def initialize(cal_loc_start: 1, registry: Registry.new, subscriptions: [])
+      @cal_loc_start = cal_loc_start
+      @registry = registry
+      @subscriptions = subscriptions
+    end
+
+    # Registers an event name
+    #
+    # @param event_name [Symbol]
+    # @param caller_location [Thread::Backtrace::Location] Caller location
+    #   associated to the registration. Useful for debugging (shown in error
+    #   messages). It defaults to this method's caller.
+    #
+    # @raise [Omnes::AlreadyRegisteredEventError] when the event is already
+    #   registered
+    # @raise [Omnes::InvalidEventNameError] when the event is not a {Symbol}
+    #
+    # @return [Omnes::Registry::Registration]
+    def register(event_name, caller_location: caller_locations(cal_loc_start)[0])
+      registry.register(event_name, caller_location: caller_location)
+    end
+
+    # Publishes an event, running all matching subscriptions
+    #
+    # @overload publish(event_name, caller_location:, **payload)
+    #   @param event_name [Symbol] Name for the generated
+    #     {Omnes::UnstructuredEvent} event.
+    #   @param **payload [Hash] Payload for the generated
+    #     {Omnes::UnstrUnstructuredEvent}
+    #
+    # @overload publish(event, caller_location:)
+    #   @param event [#name] An event instance
+    #
+    # @param caller_location [Thread::Backtrace::Location] Caller location
+    #   associated to the publication. Useful for debugging (shown in error
+    #   messages). It defaults to this method's caller.
+    #
+    # @return [Omnes::Publication] A publication object encapsulating metadata
+    #   for the event and the originated subscription executions
+    #
+    # @raise [Omnes::UnknownEventError] When event name has not been registered
+    def publish(event, caller_location: caller_locations(cal_loc_start)[0], **payload)
+      publication_time = Time.now.utc
+      event = self.class.EventType(event, **payload)
+      registry.check_event_name(event.omnes_event_name)
+      executions = execute_subscriptions_for_event(event)
+
+      Publication.new(
+        event: event,
+        executions: executions,
+        caller_location: caller_location,
+        time: publication_time
+      )
+    end
+
+    # Adds a subscription for a single event
+    #
+    # @param event_name [Symbol] Name of the event
+    # @param callable [#call] Subscription callback taking the event
+    # @yield [event] Subscription callback if callable is not given
+    #
+    # @return [Omnes::Subscription]
+    #
+    # @raise [Omnes::UnknownEventError] When event name has not been registered
+    def subscribe(event_name, callable = nil, &block)
+      registry.check_event_name(event_name)
+
+      subscribe_with_matcher(Subscription::SINGLE_EVENT_MATCHER.curry[event_name], callable, &block)
+    end
+
+    # Adds a subscription for all events
+    #
+    # @param callable [#call] Subscription callback taking the event
+    # @yield [event] Subscription callback if callable is not given
+    #
+    # @return [Omnes::Subscription]
+    def subscribe_to_all(callable = nil, &block)
+      subscribe_with_matcher(Subscription::ALL_EVENTS_MATCHER, callable, &block)
+    end
+
+    # Adds a subscription with given matcher
+    #
+    # @param matcher [#call] Callable taking the event and returning a boolean
+    # @param callable [#call] Subscription callback taking the event
+    # @yield [event] Subscription callback if callable is not given
+    #
+    # @return [Omnes::Subscription]
+    def subscribe_with_matcher(matcher, callable = nil, &block)
+      callback = callable || block
+      Subscription.new(matcher: matcher, callback: callback).tap do |subscription|
+        @subscriptions << subscription
+      end
+    end
+
+    # Removes a subscription
+    #
+    # @param subscription [Omnes::Subscription]
+    def unsubscribe(subscription)
+      @subscriptions.delete(subscription)
+    end
+
+    # Runs given block performing only a selection of subscriptions
+    #
+    # That's something useful for testing purposes, as it allows to silence
+    # subscriptions that are not part of the system under test.
+    #
+    # After the block is over, original subscriptions are restored.
+    #
+    # @param selection [Array<Omnes::Subscription>]
+    # @yield Block to run
+    #
+    # @raise [Omnes::UnknownSubscriptionError] when the subscription is not
+    #   known by the bus
+    def performing_only(*selection)
+      selection.each do |subscription|
+        unless subscriptions.include?(subscription)
+          raise UnknownSubscriptionError.new(subscription: subscription,
+                                             bus: self)
+        end
+      end
+      all_subscriptions = subscriptions
+      @subscriptions = selection
+      yield
+    ensure
+      @subscriptions = all_subscriptions
+    end
+
+    # Specialized version of {#performing_only} with no subscriptions
+    #
+    # @see #performing_only
+    def performing_nothing(&block)
+      performing_only(&block)
+    end
+
+    private
+
+    def execute_subscriptions_for_event(event)
+      subscriptions_for_event(event).map do |subscription|
+        subscription.(event)
+      end
+    end
+
+    def subscriptions_for_event(event_name)
+      @subscriptions.select do |subscription|
+        subscription.matches?(event_name)
+      end
+    end
+  end
+end

data/lib/omnes/errors.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Omnes
+  class Error < StandardError; end
+
+  # Raised when an event name is not known
+  class UnknownEventError < Error
+    attr_reader :event_name, :known_events
+
+    def initialize(event_name:, known_events:)
+      @event_name = event_name
+      @known_events = known_events
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        '#{event_name}' event is not registered.
+        #{suggestions_message}
+
+        All known events are:
+
+          '#{known_events.join("', '")}'
+      MSG
+    end
+
+    def suggestions_message
+      DidYouMean::PlainFormatter.new.message_for(suggestions)
+    end
+
+    def suggestions
+      dictionary = DidYouMean::SpellChecker.new(dictionary: known_events)
+
+      dictionary.correct(event_name)
+    end
+  end
+
+  # Raised when trying to register an invalid event name
+  class InvalidEventNameError < Error
+    attr_reader :event_name
+
+    def initialize(event_name:)
+      @event_name = event_name
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        #{event_name.inspect} is not a valid event name. Only symbols can be
+        registered.
+      MSG
+    end
+  end
+
+  # Raised when trying to register the same event name a second time
+  class AlreadyRegisteredEventError < Error
+    attr_reader :event_name, :registration
+
+    def initialize(event_name:, registration:)
+      @event_name = event_name
+      @registration = registration
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        Can't register #{event_name} event as it's already registered.
+
+        The registration happened at:
+
+        #{registration.caller_location}
+      MSG
+    end
+  end
+
+  # Raised when a subscription is not known by a bus
+  class UnknownSubscriptionError < Error
+    attr_reader :subscription, :bus
+
+    def initialize(subscription:, bus:)
+      @subscription = subscription
+      @bus = bus
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        #{subscription.inspect} is not a subscription known by bus
+        #{bus.inspect}
+      MSG
+    end
+  end
+end

data/lib/omnes/event.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+
+module Omnes
+  # Event mixin for custom classes
+  #
+  # Any instance of a class including this one can be used as a published event
+  # (see {Omnes::Bus#publish}).
+  #
+  # ```
+  # class MyEvent
+  #   include Omnes::Event
+  #
+  #   attr_reader :event
+  #
+  #   def initialize(id:)
+  #     @id = id
+  #   end
+  # end
+  #
+  # bus = Omnes::Bus.new
+  # bus.register(:my_event)
+  # bus.subscribe(:my_event) do |event|
+  #   puts event.id
+  # end
+  # bus.publish(MyEvent.new(1))
+  # ```
+  module Event
+    extend Dry::Configurable
+
+    # Generates the event name for an event instance
+    #
+    # It returns the underscored class name, with an `Event` suffix removed if
+    # present. E.g:
+    #
+    # - Foo -> `:foo`
+    # - FooEvent -> `:foo`
+    # - FooBar -> `:foo_bar`
+    # - FBar -> `:f_bar`
+    # - Foo::Bar -> `:foo_bar`
+    #
+    # You can also use your custom name builder. It needs to be something
+    # callable taking the instance as argument and returning a {Symbol}:
+    #
+    # ```
+    # my_name_builder = ->(instance) { instance.class.name.to_sym }
+    # Omnes.config.event.name_builder = my_name_builder
+    # ```
+    #
+    # @return [Symbol]
+    DEFAULT_NAME_BUILDER = lambda do |instance|
+      instance.class.name
+              .chomp("Event")
+              .gsub(/([[:alpha:]])([[:upper:]])/, '\1_\2')
+              .gsub("::", "_")
+              .downcase
+              .to_sym
+    end
+
+    setting :name_builder, default: DEFAULT_NAME_BUILDER
+
+    # Event name
+    #
+    # @return [Symbol]
+    #
+    # @see DEFAULT_NAME_BUILDER
+    def omnes_event_name
+      Omnes::Event.config.name_builder.(self)
+    end
+  end
+end

data/lib/omnes/execution.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Omnes
+  # Execution of an {Omnes::Subscription}
+  #
+  # When an event is published, it executes all matching subscriptions. Every
+  # single execution is represented as an instance of this class. It contains
+  # the result value of the subscriptions along with helpful metadata as the
+  # time of the execution or a benchmark for it.
+  #
+  # You'll most likely interact with this class for debugging or logging
+  # purposes through a {Omnes::Publication} returned on {Omnes::Bus#publish}.
+  class Execution
+    # The subscription to which the execution belongs
+    #
+    # @return [Omnes::Subscription]
+    attr_reader :subscription
+
+    # The value returned by the {#subscription}'s callback
+    #
+    # @return [Any]
+    attr_reader :result
+
+    # Benchmark for the {#subscription}'s callback
+    #
+    # @return [Benchmark::Tms]
+    attr_reader :benchmark
+
+    # Time of execution
+    #
+    # @return [Time]
+    attr_reader :time
+
+    # @private
+    def initialize(subscription:, result:, benchmark:, time: Time.now.utc)
+      @subscription = subscription
+      @result = result
+      @benchmark = benchmark
+      @time = time
+    end
+  end
+end

data/lib/omnes/publication.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Omnes
+  # The result of publishing an event
+  #
+  # It encapsulates a published {Omnes::Event} as well as the
+  # {Omnes::Execution}s it originated.
+  #
+  # This class is useful mainly for debugging and logging purposes. An
+  # instance of it is returned on {Omnes::Bus#publish}.
+  class Publication
+    # Published event
+    #
+    # @return [#name]
+    attr_reader :event
+
+    # Subscription executions that the publication originated
+    #
+    # @return [Array<Omnes::Execution>]
+    attr_reader :executions
+
+    # Location for the event caller
+    #
+    # It's usually set by {Omnes::Bus#publish}, and it points to the caller of
+    # that method.
+    #
+    # @return [Thread::Backtrace::Location]
+    attr_reader :caller_location
+
+    # Time of the event publication
+    #
+    # @return [Time]
+    attr_reader :time
+
+    # @api private
+    def initialize(event:, executions:, caller_location:, time:)
+      @event = event
+      @executions = executions
+      @caller_location = caller_location
+      @time = time
+    end
+  end
+end

data/lib/omnes/registry.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "omnes/errors"
+
+module Omnes
+  # Registry of known event names
+  #
+  # Before publishing or subscribing to an event, its name must be registered to
+  # the instance associated with the bus (see {Omnes::Bus#register}).
+  class Registry
+    # Wraps the registration of an event
+    class Registration
+      # @!attribute [r] event_name
+      #   @return [Symbol]
+      attr_reader :event_name
+
+      # @!attribute [r] caller_location
+      #   @return [Thread::Backtrace::Location]
+      attr_reader :caller_location
+
+      def initialize(event_name:, caller_location:)
+        @event_name = event_name
+        @caller_location = caller_location
+      end
+    end
+
+    # @!attribute [r] registrations
+    #   @return [Array<Omnes::Registry::Registration>]
+    attr_reader :registrations
+
+    def initialize(registrations: [])
+      @registrations = registrations
+    end
+
+    # @api private
+    def register(event_name, caller_location: caller_locations(1)[0])
+      raise InvalidEventNameError.new(event_name: event_name) unless valid_event_name?(event_name)
+
+      registration = registration(event_name)
+      raise AlreadyRegisteredEventError.new(event_name: event_name, registration: registration) if registration
+
+      Registration.new(event_name: event_name, caller_location: caller_location).tap do |reg|
+        @registrations << reg
+      end
+    end
+
+    # Removes an event name from the registry
+    #
+    # @param event_name [Symbol]
+    def unregister(event_name)
+      check_event_name(event_name)
+
+      @registrations.delete_if { |regs| regs.event_name == event_name }
+    end
+
+    # Returns an array with all registered event names
+    #
+    # @return [Array<Symbol>]
+    def event_names
+      registrations.map(&:event_name)
+    end
+
+    # Returns the registration, if present, for the event name
+    #
+    # @param event_name [Symbol]
+    #
+    # @return [Omnes::Registry::Registration, nil]
+    def registration(event_name)
+      registrations.find { |reg| reg.event_name == event_name }
+    end
+
+    # Returns whether a given event name is registered
+    #
+    # Use {#check_event_name} for a raising version of it.
+    #
+    # @param event_name [Symbol]
+    #
+    # @return [Boolean]
+    def registered?(event_name)
+      !registration(event_name).nil?
+    end
+
+    # Checks whether given event name is present in the registry
+    #
+    # Use {#registered?} for a predicate version of it.
+    #
+    # @param event_name [Symbol]
+    #
+    # @raise [UnknownEventError] if the event is not registered
+    def check_event_name(event_name)
+      return if registered?(event_name)
+
+      raise UnknownEventError.new(event_name: event_name, known_events: event_names)
+    end
+
+    private
+
+    def valid_event_name?(event_name)
+      event_name.is_a?(Symbol)
+    end
+  end
+end

data/lib/omnes/subscriber/adapter/active_job.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+
+module Omnes
+  module Subscriber
+    module Adapter
+      # [ActiveJob](https://edgeguides.rubyonrails.org/active_job_basics.html) adapter
+      #
+      # Builds subscription to be processed as ActiveJob background jobs.
+      #
+      # ActiveJob requires that the argument passed to `#perform` is
+      # serializable. By default, the result of calling `#payload` in the event
+      # is taken.
+      #
+      # ```
+      # class MyJob < ActiveJob
+      #   include Omnes::Subscriber
+      #
+      #   handle :my_event, with: Adapter::ActiveJob
+      #
+      #   def perform(payload)
+      #     # do_something
+      #   end
+      # end
+      #
+      # bus = Omnes::Bus.new
+      # bus.register(:my_event)
+      # bus.publish(:my_event, "foo" => "bar")
+      # ```
+      # However, you can configure how the event is serialized thanks to the
+      # `serializer:` option. It needs to be something callable taking the
+      # event as argument:
+      #
+      # ```
+      # handle :my_event, with: Adapter::ActiveJob[serializer: :serialized_payload.to_proc]
+      # ```
+      #
+      # You can also globally configure the default serializer:
+      #
+      # ```
+      # Omnes.config.subscriber.adapter.active_job.serializer = :serialized_payload.to_proc
+      # ```
+      module ActiveJob
+        extend Dry::Configurable
+
+        setting :serializer, default: :payload.to_proc
+
+        # @param serializer [#call]
+        def self.[](serializer: config.serializer)
+          Instance.new(serializer: serializer)
+        end
+
+        # @api private
+        def self.call(instance, event)
+          self.[].(instance, event)
+        end
+
+        # @api private
+        class Instance
+          attr_reader :serializer
+
+          def initialize(serializer:)
+            @serializer = serializer
+          end
+
+          def call(instance, event)
+            instance.class.perform_later(serializer.(event))
+          end
+        end
+      end
+    end
+  end
+end