omnes 0.1.0

data/lib/omnes/subscriber/adapter/method/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "omnes/errors"
+
+module Omnes
+  module Subscriber
+    module Adapter
+      class Method
+        # Raised when trying to subscribe to a missing method
+        class UnknownMethodSubscriptionAttemptError < Omnes::Error
+          attr_reader :method_name
+
+          # @api private
+          def initialize(method_name:)
+            @method_name = method_name
+            super(default_message)
+          end
+
+          private
+
+          def default_message
+            <<~MSG
+              You tried to subscribe an unexisting "#{method_name}" method. Event
+              handlers need to be public methods on the subscriber class.
+            MSG
+          end
+        end
+
+        # Raised when trying to subscribe to a private method
+        class PrivateMethodSubscriptionAttemptError < Omnes::Error
+          attr_reader :method_name
+
+          # @api private
+          def initialize(method_name:)
+            @method_name = method_name
+            super(default_message)
+          end
+
+          private
+
+          def default_message
+            <<~MSG
+              You tried to subscribe "#{method_name}" private method. Event handlers
+              need to be public methods on the subscriber class.
+            MSG
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "omnes/subscriber/adapter/method/errors"
+
+module Omnes
+  module Subscriber
+    module Adapter
+      # Builds a callback from a method of the instance
+      #
+      # You can use instance of this class as the adapter:
+      #
+      # ```ruby
+      # handle :foo, with: Adapter::Method.new(:foo)
+      # ```
+      #
+      # However, you can short-circuit with a {Symbol}.
+      #
+      # ```ruby
+      # handle :foo, with: :foo
+      # ```
+      class Method
+        attr_reader :name
+
+        def initialize(name)
+          @name = name
+        end
+
+        # @api private
+        def call(instance)
+          check_method(instance)
+
+          ->(event) { instance.method(name).(event) }
+        end
+
+        private
+
+        def check_method(instance)
+          raise PrivateMethodSubscriptionAttemptError.new(method_name: name) if instance.private_methods.include?(name)
+
+          raise UnknownMethodSubscriptionAttemptError.new(method_name: name) unless instance.methods.include?(name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+
+module Omnes
+  module Subscriber
+    module Adapter
+      # [Sidekiq](https://sidekiq.org/) adapter
+      #
+      # Builds subscription to be processed as Sidekiq's background jobs.
+      #
+      # Sidekiq requires that the argument passed to `#perform` is serializable.
+      # By default, the result of calling `#payload` in the event is taken.
+      #
+      # ```
+      # class MySubscriber
+      #   include Omnes::Subscriber
+      #   include Sidekiq::Job
+      #
+      #   handle :my_event, with: Adapter::Sidekiq
+      #
+      #   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::Sidekiq[serializer: :serialized_payload.to_proc]
+      # ```
+      #
+      # You can also globally configure the default serializer:
+      #
+      # ```
+      # Omnes.config.subscriber.adapter.sidekiq.serializer = :serialized_payload.to_proc
+      # ```
+      #
+      # You can delay the callback execution from the publication time with the
+      # {.in} method (analogous to {Sidekiq::Job.perform_in}).
+      #
+      # @example
+      #   handle :my_event, with: Adapter::Sidekiq.in(60)
+      module Sidekiq
+        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
+
+        # @param seconds [Integer]
+        def self.in(seconds)
+          self.[].in(seconds)
+        end
+
+        # @api private
+        class Instance
+          attr_reader :serializer
+
+          def initialize(serializer:)
+            @serializer = serializer
+          end
+
+          def call(instance, event)
+            instance.class.perform_async(serializer.(event))
+          end
+
+          def in(seconds)
+            lambda do |instance, event|
+              instance.class.perform_in(seconds, serializer.(event))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnes/subscriber/adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "omnes/subscriber/adapter/active_job"
+require "omnes/subscriber/adapter/method"
+require "omnes/subscriber/adapter/sidekiq"
+
+module Omnes
+  module Subscriber
+    # Adapters to build {Omnes::Subscription}'s callbacks
+    #
+    # Adapters need to implement a method `#call` taking the instance of
+    # {Omnes::Subscriber} and the event.
+    #
+    # Alternatively, they can be curried and only take the instance as an
+    # argument, returning a one-argument callable taking the event.
+    module Adapter
+      # @api private
+      # TODO: Simplify when when we can take callables and Proc in a polymorphic
+      # way: https://bugs.ruby-lang.org/issues/18644
+      #   > builder.to_proc.curry[instance]
+      def self.Type(value)
+        case value
+        when Symbol
+          Type(Method.new(value))
+        when Proc
+          value
+        else
+          value.method(:call)
+        end
+      end
+    end
+  end
+end

data/lib/omnes/subscriber/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "omnes/errors"
+
+module Omnes
+  module Subscriber
+    # Raised when subscribing the same subscriber instance to the same bus twice
+    class MultipleSubscriberSubscriptionAttemptError < Omnes::Error
+      # @api private
+      def initialize
+        super(default_message)
+      end
+
+      private
+
+      def default_message
+        <<~MSG
+          Omnes::Subscriber#subscribe_to method can only be called once for a
+          given instance on a given bus
+        MSG
+      end
+    end
+  end
+end

data/lib/omnes/subscriber/state.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "omnes/subscriber/adapter"
+require "omnes/subscriber/errors"
+require "omnes/subscription"
+
+module Omnes
+  module Subscriber
+    # @api private
+    class State
+      attr_reader :subscription_definitions, :calling_cache, :autodiscover_strategy
+
+      def initialize(autodiscover_strategy:, subscription_definitions: [], calling_cache: [])
+        @subscription_definitions = subscription_definitions
+        @calling_cache = calling_cache
+        @autodiscover_strategy = autodiscover_strategy
+      end
+
+      def call(bus, instance)
+        raise MultipleSubscriberSubscriptionAttemptError if already_called?(bus, instance)
+
+        autodiscover_subscription_definitions(bus, instance) unless autodiscover_strategy.nil?
+
+        definitions = subscription_definitions.map { |defn| defn.(bus) }
+
+        subscribe_definitions(definitions, bus, instance).tap do
+          mark_as_called(bus, instance)
+        end
+      end
+
+      def add_subscription_definition(&block)
+        @subscription_definitions << block
+      end
+
+      private
+
+      def already_called?(bus, instance)
+        calling_cache.include?([bus, instance])
+      end
+
+      def mark_as_called(bus, instance)
+        @calling_cache << [bus, instance]
+      end
+
+      def autodiscover_subscription_definitions(bus, instance)
+        bus.registry.event_names.each do |event_name|
+          method_name = autodiscover_strategy.(event_name)
+          next unless instance.respond_to?(method_name, true)
+
+          add_subscription_definition do |_bus|
+            [
+              Subscription::SINGLE_EVENT_MATCHER.curry[event_name],
+              Adapter.Type(Adapter::Method.new(method_name))
+            ]
+          end
+        end
+      end
+
+      def subscribe_definitions(definitions, bus, instance)
+        matcher_with_callbacks = definitions.map do |(matcher, adapter)|
+          [matcher, adapter.curry[instance]]
+        end
+
+        matcher_with_callbacks.map { |matcher, callback| bus.subscribe_with_matcher(matcher, callback) }
+      end
+    end
+  end
+end

data/lib/omnes/subscriber.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "omnes/subscriber/adapter"
+require "omnes/subscriber/state"
+require "omnes/subscription"
+
+module Omnes
+  # Supscriptions provider for a {Omnes::Bus}
+  #
+  # This module allows an including class to use its context to create event
+  # handlers.
+  #
+  # In its simplest form, you can match an event to a method in the class.
+  #
+  # ```
+  # class MySubscriber
+  #   include Omnes::Subscriber
+  #
+  #   handle :foo, with: :my_handler
+  #
+  #   def my_handler(event)
+  #     # do_something
+  #   end
+  # end
+  # ```
+  #
+  # Equivalent to the subscribe methods in {Omnes::Bus}, you can also subscribe
+  # to all events or use a custom matcher:
+  #
+  # ```
+  # class MySubscriber
+  #   include Omnes::Subscriber
+  #
+  #   handle_all                      with: :my_handler_one
+  #   handle_with_matcher my_matcher, with: :my_handler_two
+  #
+  #   def my_handler_one(event)
+  #     # do_something
+  #   end
+  #
+  #   def my_handler_two(event)
+  #     # do_something_else
+  #   end
+  # end
+  # ```
+  #
+  # Another option is to let the event handlers be automatically discovered. You
+  # need to enable the `autodiscover` feature and prefix the event name with
+  # `on_` for your handler name.
+  #
+  # ```
+  # class MySubscriber
+  #   include Omnes::Subscriber[
+  #     autodiscover: true
+  #   ]
+  #
+  #   def on_foo(event)
+  #     # do_something
+  #   end
+  # end
+  # ```
+  #
+  # If you prefer, you can make `autodiscover` on by default:
+  #
+  # ```
+  # Omnes.config.subscriber.autodiscover = true
+  # ```
+  #
+  # You can specify your own autodiscover strategy. It must be something
+  # callable, transforming the event name into the handler name.
+  #
+  # ```
+  # AUTODISCOVER_STRATEGY = ->(event_name) { event_name }
+  #
+  # class MySubscriber
+  #   include Omnes::Subscriber[
+  #     autodiscover: true,
+  #     autodiscover_strategy: AUTODISCOVER_STRATEGY
+  #   ]
+  #
+  #   def foo(event)
+  #     # do_something
+  #   end
+  # end
+  # ```
+  # You're not limited to using method names as event handlers. You can create
+  # your own adapters from the subscriber instance context.
+  #
+  # ```
+  # ADAPTER = lambda do |instance, event|
+  #   event.foo? ? instance.foo_true(event) : instance.foo_false(event)
+  # end
+  #
+  # class MySubscriber
+  #   include Omnes::Subscriber
+  #
+  #   handle :my_event, with: ADAPTER
+  #
+  #   def foo_true(event)
+  #     # do_something
+  #   end
+  #
+  #   def foo_false(event)
+  #     # do_something_else
+  #   end
+  # end
+  # ```
+  #
+  # Subscriber adapters can be leveraged to build integrations with background
+  # job libraries. See {Omnes::Subscriber::Adapter} for what comes shipped with
+  # the library.
+  #
+  # Once you've defined the event handlers, you can subscribe to a {Omnes::Bus}
+  # instance:
+  #
+  # ```
+  # MySubscriber.new.subscribe_to(bus)
+  # ```
+  #
+  # Notice that a subscriber instance can only be subscribed once to the same
+  # bus. However, you can subscribe distinct instances to the same bus or the
+  # same instance to different buses.
+  module Subscriber
+    extend Dry::Configurable
+
+    # @api private
+    ON_PREFIX_STRATEGY = ->(event_name) { :"on_#{event_name}" }
+
+    setting :autodiscover, default: false
+
+    setting :autodiscover_strategy, default: ON_PREFIX_STRATEGY
+
+    # Includes with options
+    #
+    # ```
+    # include Omnes::Subscriber[autodiscover: true]
+    # ```
+    #
+    # Use regular `include Omnes::Subscriber` in case you want to use the
+    # defaults (which can be changed through configuration).
+    #
+    # @param autodiscover [Boolean]
+    # @param autodiscover_strategy [#call]
+    def self.[](autodiscover: config.autodiscover, autodiscover_strategy: config.autodiscover_strategy)
+      Module.new(autodiscover_strategy: autodiscover ? autodiscover_strategy : nil)
+    end
+
+    # @api private
+    def self.included(klass)
+      klass.include(self.[])
+    end
+
+    # @api private
+    class Module < ::Module
+      attr_reader :autodiscover_strategy
+
+      def initialize(autodiscover_strategy:)
+        @autodiscover_strategy = autodiscover_strategy
+        super()
+      end
+
+      def included(klass)
+        klass.instance_variable_set(:@_mutex, Mutex.new)
+        klass.instance_variable_set(:@_state, State.new(autodiscover_strategy: autodiscover_strategy))
+        klass.extend(ClassMethods)
+        klass.include(InstanceMethods)
+      end
+    end
+
+    # Instance methods included in a {Omnes::Subscriber}
+    module InstanceMethods
+      # Subscribes event handlers to a bus
+      #
+      # @param bus [Omnes::Bus]
+      #
+      # @return [Omnes::Subscriber::Subscribers]
+      #
+      # @raise [Omnes::Subscriber::UnknownMethodSubscriptionAttemptError] when
+      #   subscribing a method that doesn't exist
+      # @raise [Omnes::Subscriber::PrivateMethodSubscriptionAttemptError] when
+      #   trying to subscribe a method that is private
+      # @raise [Omnes::Subscriber::DuplicateSubscriptionAttemptError] when
+      #   trying to subscribe to the same event with the same method more than once
+      def subscribe_to(bus)
+        self.class.instance_variable_get(:@_state).public_send(:call, bus, self)
+      end
+    end
+
+    # Included DSL methods for a {Omnes::Subscriber}
+    module ClassMethods
+      # Match a single event name
+      #
+      # @param event_name [Symbol]
+      # @param with [Symbol, #call] Public method in the class or an adapter
+      def handle(event_name, with:)
+        @_mutex.synchronize do
+          @_state.add_subscription_definition do |bus|
+            bus.registry.check_event_name(event_name)
+            [Subscription::SINGLE_EVENT_MATCHER.curry[event_name], Adapter.Type(with)]
+          end
+        end
+      end
+
+      # Handles all events
+      #
+      # @param with [Symbol, #call] Public method in the class or an adapter
+      def handle_all(with:)
+        @_mutex.synchronize do
+          @_state.add_subscription_definition do |_bus|
+            [Subscription::ALL_EVENTS_MATCHER, Adapter.Type(with)]
+          end
+        end
+      end
+
+      # Handles events with a custom matcher
+      #
+      # @param matcher [#call]
+      # @param with [Symbol, #call] Public method in the class or an adapter
+      def handle_with_matcher(matcher, with:)
+        @_mutex.synchronize do
+          @_state.add_subscription_definition do |_bus|
+            [matcher, Adapter.Type(with)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnes/subscription.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require "omnes/execution"
+
+module Omnes
+  # Subscription to an event
+  #
+  # An instance of it is returned on {Omnes::Bus} subscription methods.
+  #
+  # Usually, it isn't used directly beyond as a reference to unsubscribe.
+  #
+  # ```
+  # bus = Omnes::Bus.new
+  # bus.register(:foo)
+  # subscription = bus.subscribe(:foo) { |_event| do_something }
+  # bus.unsubscribe(subscription)
+  # ```
+  class Subscription
+    SINGLE_EVENT_MATCHER = lambda do |subscribed, candidate|
+      subscribed == candidate.omnes_event_name
+    end
+
+    ALL_EVENTS_MATCHER = ->(_candidate) { true }
+
+    # @api private
+    attr_reader :matcher, :callback
+
+    # @api private
+    def initialize(matcher:, callback:)
+      @matcher = matcher
+      @callback = callback
+    end
+
+    # @api private
+    def call(event)
+      result = nil
+      benchmark = Benchmark.measure do
+        result = @callback.(event)
+      end
+
+      Execution.new(subscription: self, result: result, benchmark: benchmark)
+    end
+
+    # @api private
+    def matches?(candidate)
+      matcher.(candidate)
+    end
+
+    # Returns self within a single-item array
+    #
+    # This method can be helpful to act polymorphic to an array of subscriptions
+    # from an {Omnes::Subscriber}, usually for testing purposes.
+    def subscriptions
+      [self]
+    end
+  end
+end

data/lib/omnes/unstructured_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Omnes
+  # Event with a payload defined at publication time
+  #
+  # An instance of it is automatically created on {Omnes::Bus#publish} when a
+  # name and payload are given.
+  #
+  # @example
+  #   bus = Omnes::Bus.new
+  #   bus.register(:foo)
+  #   bus.subscribe(:foo) do |event|
+  #     puts event[:bar]
+  #   end
+  #   bus.publish(:foo, bar: 'bar') # it'll generate an instance of this class
+  class UnstructuredEvent
+    # Name of the event
+    #
+    # @return [Symbol]
+    attr_reader :omnes_event_name
+
+    # Information made available to the matching subscriptions
+    #
+    # @return [Hash]
+    attr_reader :payload
+
+    # @api private
+    def initialize(payload:, omnes_event_name:)
+      @payload = payload
+      @omnes_event_name = omnes_event_name
+    end
+
+    # Delegates to {#payload}
+    #
+    # @param key [Any]
+    #
+    # @return Any
+    def [](key)
+      payload[key]
+    end
+  end
+end

data/lib/omnes/version.rb

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