announcer 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a2d800fef3f0cf19df0be391d3378a400c7922e6
+  data.tar.gz: 36868f33a3a5d88093a549c754cadbdc2885aa18
+SHA512:
+  metadata.gz: da50d2ac315e4a86fa8c56aae8468e0f2b47d3201cd0126dfee6c8ba6c3192ad59d225c5eff72e55241a3a02a7f5dd71c44a1db6293d2b72bfdfb9c61ed3b6a2
+  data.tar.gz: bab8224c83d5d0a1a3e847de999c5ef46c5309fbec6f3f7c23abd9cd2e7412b8244ae2181f9e84d9e6341ba96d1c4464fde314ca3acc0371c093b1960a4949fb

data/config/defaults.yml

@@ -0,0 +1,13 @@
+subscriptions:
+  default_priority: medium
+  max_priority: 5
+
+publishers:
+  resque:
+    publisher_queue: publisher
+    subscription_queue_formatter: null
+
+  remote_resque:
+    queue: publisher
+    redis_namespace: resque
+    subscription_queue_format: 'subscriptions_p%{priority}'

data/lib/ribbon/event_bus.rb

@@ -0,0 +1,37 @@
+module Ribbon
+  module EventBus
+    autoload(:Instance,     'ribbon/event_bus/instance')
+    autoload(:Config,       'ribbon/event_bus/config')
+    autoload(:Publishers,   'ribbon/event_bus/publishers')
+    autoload(:Plugins,      'ribbon/event_bus/plugins')
+    autoload(:Event,        'ribbon/event_bus/event')
+    autoload(:Subscription, 'ribbon/event_bus/subscription')
+    autoload(:Mixins,       'ribbon/event_bus/mixins')
+    autoload(:Errors,       'ribbon/event_bus/errors')
+
+    module_function
+
+    def method_missing(meth, *args, &block)
+      instance.send(meth, *args, &block)
+    end
+
+    def instance(name=:primary)
+      _registered_instances[name.to_sym] || Instance.new(name)
+    end
+
+    def _registered_instances
+      @__registered_instances ||= {}
+    end
+
+    def _register_instance(instance)
+      if _registered_instances.key?(instance.name)
+        raise Errors::DuplicateInstanceNameError, instance.name
+      else
+        _registered_instances[instance.name] = instance
+      end
+    end
+  end
+end
+
+# Create a shortcut
+EventBus = Ribbon::EventBus

data/lib/ribbon/event_bus/config.rb

@@ -0,0 +1,132 @@
+require 'yaml'
+
+module Ribbon::EventBus
+  class Config
+    # Putting this here instead of in Errors because I may move this into a
+    # separate gem.
+    class ConfigError < StandardError; end
+    class NotAddableError < ConfigError; end
+
+    class ProcArray < Array
+      def push(*procs)
+        raise ConfigError, "May only add blocks" unless procs.all? { |p| p.is_a?(Proc) }
+        super
+      end
+
+      def call(*args, &block)
+        map { |x| x.call(*args, &block) }
+      end
+    end
+
+    class UndefinedValue
+      def !
+        true
+      end
+    end
+
+    attr_reader :name
+
+    def initialize(name=nil, &block)
+      @name = name
+      define(&block) if block_given?
+    end
+
+    def define(&block)
+      case block.arity
+      when 0 then instance_eval(&block)
+      when 1 then block.call(self)
+      else   raise ConfigError, 'invalid config block arity'
+      end
+    end
+
+    # Deep dup all the values.
+    def dup
+      super.tap do |new_config|
+        new_config.instance_variable_set(
+          :@_nested,
+          Hash[
+            _nested.map { |key, object|
+              [
+                key,
+                object.is_a?(Config) ? object.dup : object
+              ]
+            }
+          ]
+        )
+      end
+    end
+
+    def method_missing(meth, *args, &block)
+      meth_str = meth.to_s
+
+      if /^(\w+)\=$/.match(meth_str)
+        _set($1, *args, &block)
+      elsif args.length > 0 || block_given?
+        _add(meth, *args, &block)
+      elsif /^(\w+)\?$/.match(meth_str)
+        !!_get($1)
+      else
+        _get_or_create_namespace(meth)
+      end
+    end
+
+    def merge_hash!(hash)
+      hash.each { |k, v|
+        if v.is_a?(Hash)
+          send(k).merge_hash!(v)
+        else
+          send("#{k}=", v)
+        end
+      }
+
+      self
+    end
+
+    def merge_config_file!(file)
+      merge_hash!(YAML.load_file(file))
+    end
+
+    private
+    def _get(key)
+      _nested[key.to_sym]
+    end
+
+    def _get_or_create_namespace(key)
+      object = _get(key)
+
+      if object.is_a?(UndefinedValue)
+        object = _set(key, Config.new((name ? "#{name}." : '') + key.to_s))
+      end
+
+      object
+    end
+
+    def _set(key, *args, &block)
+      object = _args_to_object(*args, &block)
+      _nested[key.to_sym] = object
+    end
+
+    def _add(key, *args, &block)
+      raise NotAddableError, self.inspect if @_value && !@_value.is_a?(Array)
+      object = _args_to_object(*args, &block)
+      _set(key, object.is_a?(Proc) ? ProcArray.new : []) if !_get(key)
+      _get(key).push(object)
+    end
+
+    def _args_to_object(*args, &block)
+      if args.length == 1
+        args.first
+      elsif args.length > 1
+        args
+      elsif block_given?
+        block
+      else
+        raise ConfigError, 'must pass value or block'
+      end
+    end
+
+    def _nested
+      @_nested ||= Hash.new { |hash, key| hash[key] = UndefinedValue.new }
+    end
+  end # Config
+end # Ribbon::EventBus

data/lib/ribbon/event_bus/errors.rb

@@ -0,0 +1,55 @@
+module Ribbon::EventBus
+  module Errors
+    class Error < StandardError; end
+    class DuplicateInstanceNameError < Error; end
+    class NoPublishersDefinedError < Error; end
+
+    ###
+    # Instance Errors
+    ###
+    class InstanceError < Error; end
+
+    ###
+    # Event Errors
+    ###
+    class EventError < Error; end
+    class UnsafeValueError < EventError
+      def initialize(key, value)
+        super("#{key.inspect} => #{value.inspect}")
+      end
+    end # UnsafeValueError
+
+    ###
+    # Subscription Errors
+    ###
+    class SubscriptionError < Error; end
+    class InvalidPriorityError < SubscriptionError; end
+    class UnexpectedEventError < SubscriptionError; end
+    class DuplicateIdentifierError < SubscriptionError; end
+
+    ###
+    # Publisher Errors
+    ###
+    class PublisherError < Error; end
+    class InvalidPublisherError < PublisherError; end
+    class InvalidPublisherNameError < PublisherError; end
+
+    # RemoteResquePublisher Errors
+    class RemoteResquePublisherError < PublisherError; end
+
+    # ProcPublisherErrors
+    class ProcPublisherError < PublisherError; end
+    class MissingProcError < ProcPublisherError; end
+    class InvalidArityError < ProcPublisherError; end
+
+    ###
+    # Plugin Errors
+    ###
+    class PluginError < Error; end
+
+    ###
+    # Serializable Errors
+    ###
+    class SerializableError < Error; end
+  end
+end

data/lib/ribbon/event_bus/event.rb

@@ -0,0 +1,93 @@
+module Ribbon::EventBus
+  class Event
+    include Mixins::HasInstance
+    include Mixins::HasConfig
+    include Mixins::Serializable
+
+    config_key :events
+    serialize_with :name, :instance, :params
+
+    attr_reader :name
+    attr_reader :params
+
+    def initialize(name, params={})
+      raise ArgumentError, 'missing event name' unless name.respond_to?(:to_sym)
+      @name = name.to_sym
+      _evaluate_params(params)
+    end
+
+    def self.load_from_serialized(name, instance, params)
+      new(name, params.merge(instance: instance))
+    end
+
+    def [](key)
+      params[key]
+    end
+
+    def publish
+      plugins.perform(:publish, self) { |event|
+        instance.publishers.each { |p| p.publish(event) }
+      }
+    end
+
+    def subscriptions
+      instance.subscriptions_to(self)
+    end
+
+    def to_s
+      "Event(#{name}" <<
+        (params && !params.empty? && ", #{params.inspect}" or '') <<
+        ")"
+    end
+
+    private
+
+    ############################################################################
+    # Parameter Evaluation Logic
+    #
+    # This evaluates the parameters passed to the initializer.
+    ############################################################################
+
+    ###
+    # Root evaluation method.
+    ###
+    def _evaluate_params(params)
+      unless params.is_a?(Hash)
+        raise ArgumentError, 'event parameters must be a hash'
+      end
+
+      params = params.dup
+      @instance = params.delete(:instance)
+      @params = _sanitize_params(params)
+    end
+
+    ###
+    # Sanitize the event params.
+    # Prevents passing values that could cause errors later in the EventBus.
+    ###
+    def _sanitize_params(params)
+      Hash[params.map { |key, value| [key.to_sym, _sanitize_value(key, value)] }].freeze
+    end
+
+    # Sanitize an array.
+    def _sanitize_array(key, array)
+      array.map { |value| _sanitize_value(key, value) }.freeze
+    end
+
+    # Sanitize an individual value.
+    def _sanitize_value(key, value)
+      case value
+      when String
+        value.dup.freeze
+      when Symbol, Integer, Float, NilClass, TrueClass, FalseClass
+        value
+      when Array
+        _sanitize_array(key, value)
+      when Hash
+        _sanitize_params(value)
+      else
+        raise Errors::UnsafeValueError.new(key, value)
+      end
+    end
+  end # Event
+end # Ribbon::EventBus

data/lib/ribbon/event_bus/instance.rb

@@ -0,0 +1,160 @@
+require 'ribbon/plugins'
+
+module Ribbon
+  module EventBus
+    DEFAULT_CONFIG_PATH = File.expand_path('../../../../config/defaults.yml', __FILE__).freeze
+
+    ##############################################################################
+    # Instance
+    #
+    # Represents an instance of the EventBus. Allows multiple Instances to be
+    # created with separate configuration, subscriptions, etc. Primarily intended
+    # to help testing, but there are practical use-cases as well.
+    ##############################################################################
+    class Instance
+      include Mixins::Serializable
+      include Ribbon::Plugins::ComponentMixin
+
+      serialize_with :name
+
+      plugin_loader do |plugin|
+        _translate_object_to_plugin(plugin)
+      end
+
+      attr_reader :name
+      attr_reader :publishers
+
+      def initialize(name=nil)
+        if name
+          @name = name.to_sym
+          EventBus._register_instance(self) if @name
+        end
+
+        _load_default_config
+      end
+
+      def self.load_from_serialized(name)
+        if name
+          EventBus.instance(name)
+        else
+          raise Errors::InstanceError, "Can't deserialize an unnamed Instance"
+        end
+      end
+
+      def config(&block)
+        (@__config ||= Config.new).tap { |config|
+          if block_given?
+            config.define(&block)
+            _process_config
+          end
+        }
+      end
+
+      def plugin(*args)
+        config { plugin(*args) }
+      end
+
+      def publish(*args)
+        raise Errors::NoPublishersDefinedError unless publishers && !publishers.empty?
+        _args_to_event(*args).publish
+      end
+
+      def subscribe_to(event_name, params={}, &block)
+        Subscription.new(event_name, params.merge(instance: self), &block)
+      end
+
+      def subscriptions_to(event_or_name)
+        event_name = event_or_name.is_a?(Event) ? event_or_name.name : event_or_name.to_sym
+        _registered_subscriptions_to(event_name).dup
+      end
+
+      def find_subscription(identifier)
+        _subscriptions_by_identifiers[identifier]
+      end
+
+      def find_publisher(publisher)
+        klass = Publishers.load(publisher)
+        publishers && publishers.find { |pub| pub.is_a?(klass) }
+      end
+
+      def has_publisher?(publisher)
+        !!find_publisher(publisher)
+      end
+
+      def _register_subscription(subscription)
+        if _subscriptions_by_identifiers[subscription.identifier]
+          # This is not expected to occur
+          raise Errors::SubscriptionError, "duplicate identifier: #{subscription.identifier.inspect}"
+        else
+          _subscriptions_by_identifiers[subscription.identifier] = subscription
+       end
+
+        _registered_subscriptions_to(subscription.event_name)
+          .push(subscription)
+          .sort! { |x, y| x.priority <=> y.priority }
+      end
+
+      private
+      def _translate_object_to_plugin(object)
+        case object
+        when String, Symbol
+          _translate_string_to_plugin(object.to_s)
+        end
+      end
+
+      def _translate_string_to_plugin(string)
+        begin
+          Plugins.const_get(
+            string.split('_').map(&:capitalize).join + 'Plugin'
+          )
+        rescue
+          nil # Let the Plugins gem handle this.
+        end
+      end
+
+      def _registered_subscriptions_to(event_name)
+        (@__registered_subscriptions ||= {})[event_name] ||= []
+      end
+
+      def _subscriptions_by_identifiers
+        @__registered_subscriptions_by_identifier ||= {}
+      end
+
+      def _load_default_config
+        config.merge_config_file!(DEFAULT_CONFIG_PATH)
+      end
+
+      # Attempt to convert *args to an event object.
+      def _args_to_event(name_or_event, params={})
+        raise ArgumentError, 'event parameters must be a hash' unless params.is_a?(Hash)
+
+        case name_or_event
+        when Event
+          name_or_event.tap { |e| e.instance_variable_set(:@instance, self) }
+        else
+          Event.new(name_or_event, params.merge(instance: self))
+        end
+      end # _args_to_event
+
+      def _process_config
+        @publishers = _load_publishers.dup.freeze
+        _update_plugins
+      end
+
+      def _load_publishers
+        Publishers.load_for_instance(self)
+      end
+
+      def _update_plugins
+        plugins.clear
+
+        if config.plugin?
+          config.plugin.each { |plugin|
+            plugin = [plugin] unless plugin.is_a?(Array)
+            plugins.add(*plugin)
+          }
+        end
+      end
+    end # Instance
+  end # EventBus
+end # Ribbon