emittance 1.1.0 → 2.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: bdfbafff04e9e3f13600cd866e8feceea7f0d5e3
-  data.tar.gz: 58a17c61fc1861ad40799d774c0423b11a1d1f8f
+SHA256:
+  metadata.gz: 9ef6d6a01910b713c52f871249fffbddcd3534818b7b92640de2de23b9b1d838
+  data.tar.gz: 55a9f2bd1d5734a4171d42db6098bb0dba27a26cae0071a43712dff4d34011b1
 SHA512:
-  metadata.gz: 54f8e3827b60740b23a26d6edff782bd46bcb8d2f1144fd29548f7c17aec0402323311b2644d28e2f7520c437a6d3a40667be73edbbdbd2660f2d3ee5103e140
-  data.tar.gz: 8acf082bf58a7fe57d23e239ebfe283fe33a4888e9653783509079f2b2a7acfcedbcc551f5b657d9f498227285d22e10cfc9817ae82c30737fc55d35c90ad9c2
+  metadata.gz: e8475538f43bdfe7d0a524270a7f69c31ecd7f90a19e7146899a0f286606d8bf68f087c6ac40d321b02c5fc38b279217fb648b4352c693168814c0715f420ed8
+  data.tar.gz: f3b5f39f6ba0a5f311378e21d6e09158048c57c8f0b4c22f11a16c15146a82e85c17acac4f4c181acd4c78d6dc18a9215d1081933e1855a5f45478c0f17185e3

data/.ruby-version

@@ -1 +1 @@
-2.4.2
+2.5.3

data/.travis.yml

@@ -3,7 +3,10 @@ env:
     - secure: "uBY5L4Qs7b9dEVG2XAJ2x9O+PgJTIA9Ezkiu7KrfxjNhMViSUOGmkKvVxBWKwFzChfsFT2wQK/TYcNNtpZoFCLxqyBTCFV1DLHiPQ3mAW4yHPiRbwkEX5HSjypn+4ONd+nk26hMgfrnnAoHM5m4tkAQRo1dY8ARv46iH2wctErVYzj5ACf/OUmrIoF/+QXkE98oOWLMYhtyAhmlBusdcM+czreMD2BUzFilkhVLLY41KA1f7EE0W4v8aY87SOsBR6Q6bFKXm9bW3xxR6nKHukFXgXtfkkylcGOZur8VrvTxx/NAKTOyx/mCo4h1SqwZrIJQoPh3uBwv6n41YGkIzFQoebPiUnnsVYCnlz0V2AnnCdcZ/LrpIVra+bN7bh3oMtEKmlrU8cHeRQy0HlaD9u4o1KYwlg0X8lApGpsSsc+GKAC9MzGk4P3aOWFFSxqs/oo98bhlxuCvYjEh+x/aXeOqG6a/3Vlg6p/gJPxqDlaHmF6JfYGWrCysnJQtbBAstH/HhT2XHm/96uH3OURI7o+tx/I63/Qz/YG68O0nV9leFUrcmARK8XMavn1N5BM0Uoh/XhC0JUnu3GJJ7g7kABPkck81U1qWskDMeUm8hhfJgWVSixnAxKBehX+rKrizbcj3/UyqYKy7SnNHJ6fQo34rBxDLe0O8ULbWifj5/Xg4="
 language: ruby
 rvm:
-  - 2.4.2
+  - 2.2.10
+  - 2.4.5
+  - 2.5.4
+  - 2.6.2
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter

data/.yardopts

@@ -2,3 +2,5 @@
 --no-private
 'lib/**/*.rb'
 --readme README.md
+-
+docs/RoutingStrategies.md

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# emittance changelog
+
+## Unreleased
+- Drop support for ruby versions < 2.2
+- Add support for multiple brokers
+- Add the "topical" routing strategy, which mimicks RabbitMQ's topic queue routing

data/Gemfile.lock

@@ -6,20 +6,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.4.0)
     coderay (1.1.2)
     diff-lcs (1.3)
     docile (1.1.5)
+    jaro_winkler (1.5.2)
     json (2.1.0)
     method_source (0.9.0)
+    parallel (1.14.0)
+    parser (2.6.0.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    rainbow (3.0.0)
     rake (10.5.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
       rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.0)
+    rspec-core (3.7.1)
       rspec-support (~> 3.7.0)
     rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -28,11 +35,21 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.0)
+    rubocop (0.62.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
     simplecov (0.15.1)
       docile (~> 1.1.0)
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
+    unicode-display_width (1.4.1)
     yard (0.9.12)
 
 PLATFORMS
@@ -44,8 +61,9 @@ DEPENDENCIES
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
+  rubocop
   simplecov
   yard
 
 BUNDLED WITH
-   1.16.0
+   1.17.2

data/docs/RoutingStrategies.md

@@ -0,0 +1,39 @@
+# @title Routing Strategies
+
+# Routing Strategies
+
+Emittance can be configured to use one of several "routing strategies." A routing strategy is a way in which an event is identified so that watchers can decide which events they wish to subscribe to. All routing strategies encapsulate the same following basic ideas:
+
+1. Events have one or more "identifiers." These identifiers are meant to express the "type" of event that was emitted, such as `order_completed`, or `user_logged_in`.
+2. Watchers can choose the identifier(s) they wish to subscribe to. Some routing strategies can even allow a watcher to watch for multiple kinds of events with a single identifier. For instance, if we are using the `:topical` routing strategy, we can watch for the identifier `posts.*`, and be able to receive events with the identifier `posts.create` and `posts.destroy`.
+
+## Routing Strategy Architecture
+
+All routing strategies encompass two procedures: the creation of an event, and the registration/retrieval of watcher subscriptions. If you wish to create your own routing strategy, then you must implement both.
+
+### Event Lookup & Creation
+
+Event lookup is a residual feature of the "classical" routing strategy, which created a separate class for a given event identifier. This might eventually be removed in later versions, but for now a routing strategy must provide an object or class that implements three methods: `.identifiers_for_klass`, `.find_event_klass`, and `.register_identifier`.
+
+`.identifiers_for_klass` takes an event class and (optionally) an event object, returning a list of identifiers for that given class. In the future this workflow will be simplified, but for now it is how an event's identifier is determined.
+
+`.find_event_klass` takes an identifier or set of identifiers, returning the relevant event class for those identifiers. With future lookup strategies, this will be unnecessary being that all events will have the same class.
+
+`.register_identifier` adds an identifier to a given event class. This is essentially a no-op with future lookup strategies, but the idea is that a given event type can have multiple identifiers.
+
+### Subscription Registration & Identifier Routing
+
+The primary purpose of a routing strategy is to facilitate the registration and retrieval of subscriptions given a specific event identifier. A routing strategy provides a class the instances of which serve to store subscriptions and route queries. Such a class must implement four instance methods: `#register`, `#[]`, `#clear_registrations_for`, and `#clear`.
+
+`#register` takes an identifier and a subscription object (subscriptions can be anything) and stores the pair for later retrieval.
+
+`#[]` takes an identifier and returns an enumerable collection of subscriptions relevant to that particular identifier. The rules for which subscriptions are returned are up to the author. This method should also return an object which can also be used to add a subscription to the parent registry using the `#<<` method.
+
+```ruby
+subscriptions = my_regisration_map['some_identifier']
+subscriptions << another_subscription
+```
+
+`#clear_registrations_for` takes an identifier and clears all subscriptions relevant to that identifier.
+
+`#clear` clears all subscriptions.

data/emittance.gemspec

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
-# coding: utf-8
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'emittance/version'
 
@@ -27,6 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'yard'
 end

data/lib/emittance/brokerage.rb

@@ -5,31 +5,105 @@ module Emittance
   # The clearinghouse for brokers. Registers brokers, and decides which broker to use when sent an event. First point of
   # contact for event propagation.
   #
-  class Brokerage
+  # == Multiple brokers
+  #
+  # Emittance can support multiple brokers. This is implemented in a whitelist fashion. To enable a broker, just call
+  # {Emittance::Brokerage.use_broker}:
+  #
+  #   Emittance.use_broker :asynchronous
+  #
+  # Watchers subscribe to events on a per-broker basis. By default, a watcher will subscribe on the default broker
+  # Emittance initializes with +synchronous+ as the default broker). You can override that default by specifying it in
+  # a parameter on the {Emittance::Watcher.watch} method:
+  #
+  #    MyWatcher.watch :something_cool_happened, broker: :asynchronous { |event| puts event.payload.inspect }
+  #
+  # To change the default broker, use {Emittance::Brokerage.default_broker=}:
+  #
+  #   Emittance.default_broker = :asynchronous
+  #
+  module Brokerage
+    class BrokerNotInUseError < StandardError; end
+
     @enabled = true
-    @current_broker = nil
 
     class << self
+      attr_reader :default_broker
+
+      # Sends an event to all brokers that are in-use.
+      #
       # @param event [Emittance::Event] the event object
-      def send_event(event)
-        broker.process_event(event) if enabled?
+      def send_event(event, middleware: Emittance::Middleware)
+        return nil unless enabled?
+
+        event = middleware.up(event)
+        brokers_in_use.each { |broker| broker.process_event(event) }
       end
 
-      # @return [Class] the currently selected broker
-      def broker
-        @current_broker
+      # @return [Set<Emittance::Broker>]
+      def brokers_in_use
+        @brokers_in_use ||= Set.new
       end
 
-      # @param identifier [Symbol] the symbol you have registered the broker to
-      def use_broker(identifier)
-        @current_broker = registry.fetch identifier
+      # Normalizes broker input in order to provide an interface that allows either a {Emittance::Broker} subclass _or_
+      # its identifier to be passed in to a method.
+      #
+      # @param broker [Class, Symbol, nil] either a broker or its identifier
+      def find_broker(broker)
+        if brokers_in_use.include?(broker) || (broker.is_a?(Class) && broker <= Emittance::Broker)
+          broker
+        elsif broker.nil?
+          default_broker
+        else
+          registry.fetch(broker)
+        end
       end
 
-      # @param broker [Emittance::Broker] the broker you would like to register
-      def register_broker(broker, symbol)
-        registry.register broker, symbol
+      # Checks if a broker is in use in this brokerage.
+      #
+      # @return [Boolean] true if broker is in use, false otherwise
+      def broker_in_use?(broker)
+        broker = find_broker(broker)
+
+        brokers_in_use.include?(broker)
       end
 
+      # Adds a broker to the list of {Emittance::Broker} subclasses available. The first broker to be added becomes the
+      # default broker.
+      #
+      # @param broker [Class, Symbol] the symbol you have registered the broker to
+      def use_broker(broker)
+        broker = find_broker(broker)
+
+        brokers_in_use << broker
+        self.default_broker = broker unless default_broker
+      end
+
+      # Sets the default broker. If the watcher does not specify the broker, this will be the broker that gets
+      def default_broker=(broker)
+        broker = find_broker(broker)
+        raise BrokerNotInUseError, 'Default broker must be in use' unless broker_in_use?(broker)
+
+        @default_broker = broker
+      end
+
+      # A semi-private API. If you have created your own broker, this method adds it to the available pool of brokers.
+      #
+      # Emittance::Brokerage.register_broker MyBroker, :mine
+      #
+      # @param broker [Class] the broker you would like to register
+      # @param identifier [Symbol] the symbol you would like use to point to your registered broker
+      def register_broker(broker, identifier)
+        registry.register broker, identifier
+      end
+
+      def dispatcher_for(broker = nil)
+        broker = find_broker(broker)
+        broker.dispatcher
+      end
+
+      alias dispatcher dispatcher_for
+
       # @return [Module] the registry containing all broker registrations
       def registry
         Emittance::Brokerage::Registry

data/lib/emittance/dispatcher/registration_map.rb

@@ -8,7 +8,7 @@ module Emittance
     # A proxy for a hash. Identifies special identifiers.
     #
     class RegistrationMap
-      SPECIAL_IDENTIFIER_REGEX = /^\@/
+      SPECIAL_IDENTIFIER_REGEX = /^\@/.freeze
 
       class << self
         # @param identifier the identifier we want to know information about
@@ -38,6 +38,10 @@ module Emittance
         self
       end
 
+      def clear
+        @reg_map = {}
+      end
+
       private
 
       attr_reader :reg_map

data/lib/emittance/dispatcher/topic_registration_map.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Emittance
+  class Dispatcher
+    ##
+    # Tracks registrations for a set of topics.
+    #
+    # == Structure & Registration
+    #
+    # A +TopicRegistrationMap+ is structured like a hash, where the keys are topic parts, and the values are something
+    # called a +Mapping+. A +Mapping+ is a struct containing a set of subscriptions for its immediate topic level, as
+    # well as another +TopicRegistrationMap+. This forms a tree-like structure. For example, if we have a set of
+    # subscriptions on the following topics (their index is denoted above each element for clarity:
+    #
+    #               #   0    1    2    3    4      5      6    7      8      9      10       11       12
+    #   routing_key = ['*', '*', '*', '*', '*.b', '*.b', 'a', 'a.*', 'a.*', 'a.*', 'a.*.c', 'a.*.c', 'a.a']
+    #
+    # We could register them each using the {#register} method:
+    #
+    #   registrations = TopicRegistrationMap.new
+    #
+    #   routing_key.each_with_index do |routing_key, idx|
+    #     registrations.register(routing_key, idx)
+    #   end
+    #
+    # The resulting map would look like this:
+    #
+    #   root map:
+    #     *:
+    #       subscriptions: [0, 1, 2, 3]
+    #       map:
+    #         b:
+    #           subscriptions: [4, 5]
+    #     a:
+    #       subscriptions: [6]
+    #       map:
+    #         *:
+    #           subscriptions: [7, 8, 9]
+    #           map:
+    #             c:
+    #               subscriptions: [10, 11]
+    #         a:
+    #           subscriptions: [12]
+    #
+    # == Lookup
+    #
+    # Suppose we publish to the topic +a.a+. We can use the {#[]} method to fetch all the subscriptions relevant to
+    # that topic:
+    #
+    #   registrations['a.a'] # => [7, 8, 9, 12]
+    #
+    class TopicRegistrationMap
+      Subscription = Struct.new(:routing_key, :registration)
+
+      # @param root [TopicRegistrationMap] (private API)
+      def initialize(root = nil)
+        @root = root
+      end
+
+      # @private
+      def root
+        @root || self
+      end
+
+      # @private
+      def mappings
+        @mappings ||= new_mappings
+      end
+
+      # Looks up subscriptions whose registrations match the given topic.
+      #
+      # @param topic_or_event [#to_s, Emittance::Event] the topic or event for which you wish to look up subscriptions
+      # @return [Enumerable] the set of subscriptions
+      def [](topic_or_event)
+        topic, head, tail, parts = process_routing_key(topic_or_event)
+
+        items = parts.length == 1 ? my_subscriptions(head, original_lookup: topic) : child_subscriptions(head, tail)
+
+        Result.new(root, topic, items)
+      end
+
+      # @private
+      def subscriptions_for_exactly(topic_part, original_lookup:)
+        Result.new(root, original_lookup, mappings[topic_part].subscriptions)
+      end
+
+      # @private
+      def all_child_subscriptions_for_exactly(topic_part, original_lookup:)
+        mappings.values.reduce(Result.new(root, original_lookup, Set.new)) do |result, mapping|
+          result + mapping.map.subscriptions_for_exactly(topic_part, original_lookup: original_lookup)
+        end
+      end
+
+      # Registers a subscription to the given routing key.
+      #
+      # @param routing_key [#to_s] the routing key that you wish to subscribe to
+      # @param registration [Object] the registration you wish to store under that routing key
+      # @param original_routing_key [#to_s] (private API)
+      def register(routing_key, registration, original_routing_key: nil)
+        routing_key, head, tail, parts = process_routing_key(routing_key)
+        original_routing_key ||= routing_key
+
+        mapping = mappings[head]
+
+        if parts.length == 1
+          mapping << Subscription.new(original_routing_key, registration)
+        else
+          mapping.map.register(tail, registration, original_routing_key: original_routing_key)
+        end
+      end
+
+      # Clears registrations associated with a given routing key.
+      #
+      # @param routing_key [#to_s] the routing key the registrations for which you with to clear from this map
+      def clear_registrations_for(routing_key)
+        _routing_key, head, tail, parts = process_routing_key(routing_key)
+
+        mapping = mappings[head]
+
+        if parts.length == 1
+          mapping.subscriptions.clear
+        else
+          mapping.map.clear_registrations_for(tail)
+        end
+      end
+
+      def clear
+        @mappings = new_mappings
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize
+      def my_subscriptions(head, original_lookup:)
+        mappings['#'].subscriptions +
+          mappings['*'].subscriptions +
+          mappings[head].subscriptions +
+          mappings[head].map.subscriptions_for_exactly('#', original_lookup: original_lookup) +
+          mappings['*'].map.subscriptions_for_exactly('#', original_lookup: original_lookup) +
+          mappings['#'].map.subscriptions_for_exactly(head, original_lookup: original_lookup) +
+          mappings['#'].map.subscriptions_for_exactly('*', original_lookup: original_lookup)
+      end
+
+      def child_subscriptions(head, tail)
+        Result.new(root, tail, mappings['#'].subscriptions) +
+          child_subscriptions_for_hash_on_tail(tail) +
+          mappings['*'].map[tail] +
+          mappings[head].map[tail]
+      end
+
+      def child_subscriptions_for_hash_on_tail(routing_key)
+        original_routing_key = routing_key
+        result = Result.new(root, original_routing_key)
+
+        until parts_for_routing_key(routing_key).empty?
+          routing_key, _, tail, = process_routing_key(routing_key)
+          result += Result.new(root, original_routing_key, mappings['#'].map[routing_key].items)
+
+          routing_key = tail
+        end
+
+        result
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def process_routing_key(routing_key)
+        routing_key = normalize_routing_key(routing_key)
+        parts = parts_for_routing_key(routing_key)
+        tail = routing_key_for_parts(parts[1..-1])
+
+        [routing_key, parts.first, tail, parts]
+      end
+
+      def normalize_routing_key(routing_key)
+        if routing_key.is_a?(Emittance::Event)
+          routing_key.topic
+        elsif routing_key.to_s == '@all' # support for legacy special identifier
+          '#'
+        else
+          routing_key
+        end
+      end
+
+      def parts_for_routing_key(routing_key)
+        routing_key.to_s.split('.')
+      end
+
+      def routing_key_for_parts(parts)
+        parts.join('.')
+      end
+
+      def new_mappings
+        Hash.new { |h, k| h[k] = Mapping.new(root) }
+      end
+
+      # @private
+      class Mapping
+        attr_reader :root_map
+
+        def initialize(root_map)
+          @root_map = root_map
+        end
+
+        def push(new_subscription)
+          subscriptions << new_subscription
+        end
+
+        alias << push
+
+        def subscriptions
+          @subscriptions ||= Set.new
+        end
+
+        def map
+          @map ||= TopicRegistrationMap.new(root_map)
+        end
+      end
+
+      # @private
+      class Result
+        include Enumerable
+
+        attr_reader :root_map, :lookup_key, :items
+
+        def initialize(root_map, lookup_key, items = Set.new)
+          @root_map = root_map
+          @lookup_key = lookup_key
+          @items = items
+        end
+
+        def each
+          return enum_for(:each) unless block_given?
+
+          items.each { |item| item.respond_to?(:registration) ? yield(item.registration) : yield(item) }
+        end
+
+        # Adds a subscription to the root mapping. This is set up all wonky in this manner with a (sort of) circular
+        # reference because the original API was set up this way. This allows us to add subscriptions to the
+        # collection itself.
+        def push(new_subscription)
+          root_map.register(lookup_key, new_subscription)
+        end
+
+        alias << push
+
+        def +(other)
+          unless root_map == other.root_map && lookup_key == other.lookup_key
+            raise ArgumentError, 'Cannot add two Results with different root_maps or lookup_keys'
+          end
+
+          self.class.new(root_map, lookup_key, items + other.items)
+        end
+
+        def empty?
+          items.empty?
+        end
+
+        def length
+          items.length
+        end
+
+        alias size length
+        alias count length
+
+        def first
+          items.first
+        end
+
+        def last
+          items.last
+        end
+
+        def clear
+          root_map.clear_registrations_for(lookup_key)
+        end
+      end
+    end
+  end
+end

data/lib/emittance/dispatcher.rb

@@ -3,10 +3,11 @@
 require 'set'
 
 require 'emittance/dispatcher/registration_map'
+require 'emittance/dispatcher/topic_registration_map'
 
 module Emittance
   ##
-  # Abstract class for dispatchers. Subclasses must implement the following methods:
+  # Abstract class for dispatchers. Subclasses must implement the following class methods:
   #
   # - +._process_event+
   # - +._register+
@@ -17,11 +18,65 @@ module Emittance
   # you want, but typically represent the callback you would like to run whenever an event of a certain type is
   # emitted.
   #
+  # == Example
+  #
+  # Suppose we have a simple dispatcher. We're not going to worry about method calls, so we're just going to focus on
+  # implementing +._register+ and +._process_event+.
+  #
+  #   class SimpleDispatcher < Emittance::Dispatcher
+  #     class << self
+  #       private
+  #
+  #       # +._register+ takes the original identifier/topic, an optional params hash, and a block. To register the
+  #       # callback, push it on to the collection returned by the +.registrations_for+ method. You can format the
+  #       # callback in any way you like.
+  #       def _register(identifier, _params = {}, &callback)
+  #         registrations_for(event) << format_callback(callback)
+  #         callback
+  #       end
+  #
+  #       # +._process_event+ is simple -- we just need to fetch the registrations related to the event, and process
+  #       # them. The registrations are returned in the exact same format as they were stored in +._register+. So, in
+  #       # this case, we will get a set of +CallbackWrapper+ objects, each of which responds to +#call+.
+  #       #
+  #       # IMPORTANT: You also need to make sure that the +down+ middleware stack is called in the process.
+  #       def _process_event(event)
+  #         event = Emittance::Middleware.down(event)
+  #         registrations_for(event).each { |registration| registration.call(event) }
+  #       end
+  #
+  #       def format_callback(callback)
+  #         CallbackWrapper.new(callback)
+  #       end
+  #     end
+  #   end
+  #
   class Dispatcher
+    ROUTING_STRATEGIES = {
+      classical: RegistrationMap,
+      topical: TopicRegistrationMap
+    }.freeze
+
+    @routing_strategy = RegistrationMap
+
     class << self
-      # @private
-      def inherited(subklass)
-        subklass.instance_variable_set '@registrations', RegistrationMap.new
+      def routing_strategy
+        @routing_strategy || ::Emittance::Dispatcher.instance_variable_get('@routing_strategy')
+      end
+
+      alias registration_router_klass routing_strategy
+
+      def routing_strategy=(new_strategy_name)
+        new_strategy =
+          if new_strategy_name.is_a?(Module)
+            new_strategy_name
+          else
+            ROUTING_STRATEGIES[new_strategy_name.to_sym]
+          end
+
+        raise ArgumentError, 'Could not find a routing strategy with that name' unless new_strategy
+
+        @routing_strategy = new_strategy
       end
 
       # Calls the subclass's +_process_event+ method.
@@ -47,7 +102,7 @@ module Emittance
 
       # @return [RegistrationMap] the registrations
       def clear_registrations!
-        registrations.each_key { |key| clear_registrations_for! key }
+        registrations.clear
         registrations
       end
 
@@ -59,7 +114,9 @@ module Emittance
 
       private
 
-      attr_reader :registrations
+      def registrations
+        @registrations ||= registration_router_klass.new
+      end
 
       def _process_event(_event)
         raise NotImplementedError

data/lib/emittance/dispatchers/synchronous.rb

@@ -11,6 +11,7 @@ module Emittance
 
         def _process_event(event)
           registrations_for(event).each do |registration|
+            event = Emittance::Middleware.down(event)
             registration.call event
           end
         end

data/lib/emittance/emitter.rb

@@ -58,14 +58,12 @@ module Emittance
       # @param payload [*] any additional information that might be helpful for an event's handler to have. Can be
       #   standardized on a per-event basis by pre-defining the class associated with the identifier and validating
       #   the payload. See {Emittance::Event} for more details.
-      # @param broker [Symbol] the identifier for the broker you wish to handle the event. Requires additional gems
-      #   if not using the default.
       #
       # @return the payload
       def emit(identifier, payload: nil)
         now = Time.now
         event_klass = _event_klass_for identifier
-        event = event_klass.new(self, now, payload)
+        event = event_klass.new(self, now, payload).tap { |the_event| the_event.topic = identifier }
         _send_to_broker event
 
         payload
@@ -76,11 +74,10 @@ module Emittance
       #
       # @param identifiers [*] anything that can be used to generate an +Event+ class.
       # @param payload (@see #emit)
-      # @param broker (@see #emit)
       def emit_with_dynamic_identifier(*identifiers, payload:)
         now = Time.now
         event_klass = _event_klass_for(*identifiers)
-        event = event_klass.new(self, now, payload)
+        event = event_klass.new(self, now, payload).tap { |the_event| the_event.topic = identifiers.join('.') }
         _send_to_broker event
 
         payload

data/lib/emittance/event.rb

@@ -2,6 +2,21 @@
 
 module Emittance
   ##
+  # = Topical Event Lookup
+  #
+  # This section describes the new ('topical') style of event lookup. This will be maintained in the future in favor
+  # of the old ('classical') style. However, it is not enabled by default. To enable this strategy, you must configure
+  # Emittance to use it:
+  #
+  #   Emittance.event_routing_strategy = :topical
+  #
+  # This strategy mimicks the topic name format used by RabbitMQ.
+  #
+  # = Classical Event Lookup (Legacy)
+  #
+  # This section describes the old ('classical') style of event lookup. While it's unlikely to be removed, it will
+  # remain unsupported in favor of the new ('topical') style of event lookup, described above.
+  #
   # Basic usage of Emittance doesn't require that you fiddle with objects of type +Emittance::Event+. However, this
   # class is open for you to inherit from in the cases where you would like to customize some aspects of the event.
   #
@@ -104,10 +119,37 @@ module Emittance
   # We can manually add an identifier post-hoc, but this would nevertheless become confusing.
   #
   class Event
+    LOOKUP_STRATEGIES = {
+      classical: EventLookup,
+      topical: TopicLookup
+    }.freeze
+
+    @lookup_strategy = EventLookup
+
     class << self
+      attr_reader :lookup_strategy
+
+      # @param new_strategy_name [#to_sym] the name of the new lookup strategy
+      def lookup_strategy=(new_strategy_name)
+        new_strategy =
+          if new_strategy_name.is_a?(Module)
+            new_strategy_name
+          else
+            LOOKUP_STRATEGIES[new_strategy_name.to_sym]
+          end
+
+        raise ArgumentError, 'Could not find a lookup strategy with that name' unless new_strategy
+
+        @lookup_strategy = new_strategy
+      end
+
+      def inherited(subklass)
+        subklass.instance_variable_set('@lookup_strategy', lookup_strategy)
+      end
+
       # @return [Array<Symbol>] the identifier that can be used by the {Emittance::Broker broker} to find event handlers
-      def identifiers
-        EventLookup.identifiers_for_klass(self).to_a
+      def identifiers(event = nil)
+        lookup_strategy.identifiers_for_klass(self, event).to_a
       end
 
       # Gives the Event object a custom identifier.
@@ -115,17 +157,19 @@ module Emittance
       # @param sym [Symbol] the identifier you wish to identify this event by when emitting and watching for it
       def add_identifier(sym)
         raise Emittance::InvalidIdentifierError, 'Identifiers must respond to #to_sym' unless sym.respond_to?(:to_sym)
-        EventLookup.register_identifier self, sym.to_sym
+
+        lookup_strategy.register_identifier self, sym.to_sym
       end
 
       # @param identifiers [*] anything that can be derived into an identifier (or the event class itself) for the
       #   purposes of looking up an event class.
       def event_klass_for(*identifiers)
-        EventLookup.find_event_klass(*identifiers)
+        lookup_strategy.find_event_klass(*identifiers)
       end
     end
 
     attr_reader :emitter, :timestamp, :payload
+    attr_accessor :topic
 
     # @param emitter the object that emitted the event
     # @param timestamp [Time] the time at which the event occurred
@@ -138,7 +182,7 @@ module Emittance
 
     # @return [Array<Symbol>] all identifiers that can be used to identify the event
     def identifiers
-      self.class.identifiers
+      self.class.identifiers(self)
     end
   end
 end

data/lib/emittance/event_lookup.rb

@@ -8,9 +8,9 @@ module Emittance
   # event class.
   #
   module EventLookup
-    class << self
-      include Emittance::Helpers::StringHelpers
+    extend Emittance::Helpers::StringHelpers
 
+    class << self
       # Look up an {Emittance::Event} class by an identifier. Generates an Event class if no such class exists for
       # that identifier.
       #
@@ -55,7 +55,7 @@ module Emittance
 
       # @param klass [Class] a subclass of {Emittance::Event} you wish to find the identifiers for
       # @return [Set<Symbol>] a collection of identifiers that can be used to identify that event class
-      def identifiers_for_klass(klass)
+      def identifiers_for_klass(klass, _event = nil)
         Emittance::EventLookup::Registry.identifiers_for_klass(klass)
       end
 
@@ -219,7 +219,7 @@ module Emittance
         #
         # @param event_klass [Class] the class you want the identifiers for
         # @return [Set<Symbol>] all identifiers that can be used to identify the given event class
-        def identifiers_for_klass(event_klass)
+        def identifiers_for_klass(event_klass, _event = nil)
           lookup_klass_to_identifier_mapping(event_klass) ||
             (create_mapping_for_klass(event_klass) && lookup_klass_to_identifier_mapping(event_klass))
         end

data/lib/emittance/middleware/logging.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Emittance
+  class Middleware
+    ##
+    # Middleware for logging events
+    #
+    class Logging < Emittance::Middleware
+      @current_logger = Logger.new(STDOUT)
+
+      class << self
+        attr_accessor :current_logger
+      end
+
+      def up
+        current_logger.info event_log_str
+
+        event
+      end
+
+      private
+
+      def current_logger
+        self.class.current_logger
+      end
+
+      def event_log_str
+        "Emittance: #{event.identifiers.last.inspect} event emitted."
+      end
+    end
+  end
+end

data/lib/emittance/middleware.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Emittance
+  ##
+  # Module for managing middlewares.
+  #
+  class Middleware
+    @registered_middlewares = []
+
+    class << self
+      attr_reader :registered_middlewares
+
+      # @param middleware [Class, Array<#up, #down>] the middleware or array of middlewares you wish to register.
+      # @return [Array] the updated list of registered middlewares.
+      def register(middleware)
+        middlewares = Array(middleware)
+
+        middlewares.each { |mw| registered_middlewares << mw }
+      end
+
+      def clear_registrations!
+        registered_middlewares.clear
+      end
+
+      def up(input_event)
+        registered_middlewares.reduce(input_event) { |event, klass| klass.new(event).up }
+      end
+
+      def down(input_event)
+        registered_middlewares.reduce(input_event) { |event, klass| klass.new(event).down }
+      end
+    end
+
+    attr_reader :event
+
+    def initialize(event)
+      @event = event
+    end
+
+    def up
+      event
+    end
+
+    def down
+      event
+    end
+  end
+end

data/lib/emittance/topic_lookup.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Emittance
+  ##
+  # Since events don't need to be dynamically generated when using topics, we essentially want to stub out all of the
+  # class creation and registration logic.
+  #
+  module TopicLookup
+    class << self
+      def identifiers_for_klass(_klass, event = nil)
+        raise ArgumentError, 'Cannot generate identifiers without an event' unless event
+
+        [event.topic]
+      end
+
+      def register_identifier(klass, identifier)
+        # no op
+      end
+
+      def find_event_klass(*_identifiers)
+        Emittance::Event
+      end
+    end
+  end
+end

data/lib/emittance/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Emittance
-  VERSION = '1.1.0'
+  VERSION = '2.0.0.pre.1'
 end

data/lib/emittance/watcher.rb

@@ -11,21 +11,22 @@ module Emittance
     # @param identifier [Symbol] the event's identifier
     # @param callback_method [Symbol] one option for adding a callback--the method on the object to call when the
     #   event fires
+    # @param params [Hash] any parameters related to the registration of a watcher
     # @param callback [Block] the other option for adding a callback--the block you wish to be executed when the event
     #   fires
     # @return [Proc] the block that will run when the event fires
-    def watch(identifier, callback_method = nil, params = {}, &callback)
-      if callback_method
-        _dispatcher.register_method_call identifier, self, callback_method, params
+    def watch(identifier, callback_method = nil, **params, &callback)
+      if callback
+        _dispatcher(params).register identifier, params, &callback
       else
-        _dispatcher.register identifier, params, &callback
+        _dispatcher(params).register_method_call identifier, self, callback_method, params
       end
     end
 
     private
 
-    def _dispatcher
-      Emittance.dispatcher
+    def _dispatcher(params)
+      Emittance.dispatcher_for(params[:broker])
     end
   end
 end

data/lib/emittance.rb

@@ -6,12 +6,14 @@ require 'emittance/errors'
 require 'emittance/helpers/string_helpers'
 require 'emittance/helpers/constant_helpers'
 require 'emittance/event_lookup'
+require 'emittance/topic_lookup'
 require 'emittance/dispatcher'
 require 'emittance/brokerage'
 require 'emittance/broker'
 require 'emittance/event'
 require 'emittance/emitter'
 require 'emittance/watcher'
+require 'emittance/middleware'
 require 'emittance/notifier'
 require 'emittance/action'
 
@@ -20,6 +22,8 @@ require 'emittance/action'
 #
 module Emittance
   class << self
+    attr_reader :event_routing_strategy
+
     # Enable eventing process-wide
     def enable!
       Emittance::Brokerage.enable!
@@ -36,20 +40,45 @@ module Emittance
     end
 
     # @return [Class] the currently enabled broker class
-    def broker
-      Emittance::Brokerage.broker
+    def default_broker
+      Emittance::Brokerage.default_broker
+    end
+
+    alias broker default_broker
+
+    def dispatcher_for(*args)
+      Emittance::Brokerage.dispatcher_for(*args)
     end
 
+    alias dispatcher dispatcher_for
+
     # @return [Class] the dispatcher attached to the currently enabled broker
-    def dispatcher
-      broker.dispatcher
+    def default_dispatcher
+      default_broker.dispatcher
     end
 
-    # @param [identifier] the identifier that can be used to identify the broker you wish to use
+    # @param identifier [#to_sym] the identifier that can be used to identify the broker you wish to use
     def use_broker(identifier)
       Emittance::Brokerage.use_broker identifier
     end
 
+    def default_broker=(identifier)
+      Emittance::Brokerage.default_broker = identifier
+    end
+
+    #   Emittance.use_middleware MyMiddleware
+    #   Emittance.use_middleware MyOtherMiddleware, MyCoolMiddleware
+    #
+    # @param middlewares [Array<Class>] each middleware you wish to run.
+    def use_middleware(*middlewares)
+      Emittance::Middleware.register middlewares
+    end
+
+    # Removes all middlewares from the app.
+    def clear_middleware!
+      Emittance::Middleware.clear_registrations!
+    end
+
     # Not yet implemented! Remove nocov and private flags when finished.
     # :nocov:
     # @private
@@ -58,6 +87,12 @@ module Emittance
       # Emittance::Dispatcher.suppress(&blk)
     end
     # :nocov:
+
+    def event_routing_strategy=(new_strategy)
+      @event_routing_strategy = new_strategy
+      Emittance::Event.lookup_strategy = new_strategy
+      Emittance::Dispatcher.routing_strategy = new_strategy
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: emittance
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0.pre.1
 platform: ruby
 authors:
 - Tyler Guillen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-17 00:00:00.000000000 Z
+date: 2019-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +120,7 @@ files:
 - ".ruby-version"
 - ".travis.yml"
 - ".yardopts"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -114,6 +129,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/RoutingStrategies.md
 - emittance.gemspec
 - lib/emittance.rb
 - lib/emittance/action.rb
@@ -123,6 +139,7 @@ files:
 - lib/emittance/dispatcher.rb
 - lib/emittance/dispatcher/registration_collection_proxy.rb
 - lib/emittance/dispatcher/registration_map.rb
+- lib/emittance/dispatcher/topic_registration_map.rb
 - lib/emittance/dispatchers/synchronous.rb
 - lib/emittance/emitter.rb
 - lib/emittance/errors.rb
@@ -130,7 +147,10 @@ files:
 - lib/emittance/event_lookup.rb
 - lib/emittance/helpers/constant_helpers.rb
 - lib/emittance/helpers/string_helpers.rb
+- lib/emittance/middleware.rb
+- lib/emittance/middleware/logging.rb
 - lib/emittance/notifier.rb
+- lib/emittance/topic_lookup.rb
 - lib/emittance/version.rb
 - lib/emittance/watcher.rb
 homepage: https://github.com/aastronautss/emittance
@@ -148,12 +168,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: A robust and flexible eventing library for Ruby.