remotely_exceptional 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5db0afaa461aa92d936cae11184f651757c23e50
+  data.tar.gz: 6b8dfd4d4a3ff0c8602e435126de50e8ccc5dc70
+SHA512:
+  metadata.gz: 5697edf8df114e0a6c5c1953f76ae740e23dd69e6fc552dda3198e03e14a3a198f57d2e43f70be73fc5410afe2fc969333a20162d4190e333eb8160ac47fd084
+  data.tar.gz: 2a3ed81301611e4cff979f3a20b7ad7335d749b7751e7066a0cb95c70493334350f9d32b30b6f6245eb088a82ec7185229240d008071f72fe78a81b60622602b

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - 2.2.0

data/Gemfile

@@ -0,0 +1,16 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :doc do
+  gem "yard"
+end
+
+group :test do
+  gem "coveralls", :require => false
+  gem "guard"
+  gem "guard-minitest"
+  gem "minitest", ">= 3.0"
+  gem "mocha"
+  gem "simplecov", :require => false
+end

data/Guardfile

@@ -0,0 +1,7 @@
+gem_name = File.basename(Dir[File.expand_path("../*.gemspec", __FILE__)].first)[0..-9]
+
+guard(:minitest, :all_after_pass => false, :all_on_start => false) do
+  watch(%r{^lib/#{gem_name}/(.+)\.rb$}) { |m| "test/unit/#{m[1]}_test.rb" }
+  watch(%r{^test/.+_test\.rb$})
+  watch(%r{^(?:test/test_helper(.*)|lib/#{gem_name})\.rb$}) { "test" }
+end

data/LICENSE

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

data/README.md

@@ -0,0 +1,37 @@
+# RemotelyExceptional
+[![Gem Version](https://badge.fury.io/rb/remotely_exceptional.svg)](http://badge.fury.io/rb/remotely_exceptional)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/remotely_exceptional)
+[![Build Status](https://travis-ci.org/tdg5/remotely_exceptional.svg)](https://travis-ci.org/tdg5/remotely_exceptional)
+[![Coverage Status](https://coveralls.io/repos/tdg5/remotely_exceptional/badge.svg)](https://coveralls.io/r/tdg5/remotely_exceptional)
+[![Code Climate](https://codeclimate.com/github/tdg5/remotely_exceptional/badges/gpa.svg)](https://codeclimate.com/github/tdg5/remotely_exceptional)
+[![Dependency Status](https://gemnasium.com/tdg5/remotely_exceptional.svg)](https://gemnasium.com/tdg5/remotely_exceptional)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "remotely_exceptional"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install remotely_exceptional
+```
+
+## Usage
+
+## Contributing
+
+1. Fork it ( https://github.com/tdg5/remotely_exceptional/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end
+
+task :default => :test

data/lib/remotely_exceptional.rb

@@ -0,0 +1,11 @@
+require "remotely_exceptional/version"
+require "remotely_exceptional/exceptions"
+require "remotely_exceptional/handler"
+require "remotely_exceptional/remote_handling"
+
+# The namespace for the RemotelyExceptional gem.
+module RemotelyExceptional
+  # The namespace that specialized handlers live in.
+  module Handlers
+  end
+end

data/lib/remotely_exceptional/exceptions.rb

@@ -0,0 +1,12 @@
+module RemotelyExceptional
+  class Error < ::RuntimeError
+  end
+
+  class InvalidHandlerResponse < RemotelyExceptional::Error
+    attr_accessor :original_exception
+    def initialize(*)
+      super
+      @original_exception = $!
+    end
+  end
+end

data/lib/remotely_exceptional/handler.rb

@@ -0,0 +1,91 @@
+# Mixin providing basic functionality required for matching and handling
+# exceptions.
+module RemotelyExceptional::Handler
+  # Actions that will be taken on any object that includes this module.
+  #
+  # @param includer [Class,Module] The class or module that has included this
+  #   module.
+  def self.included(includer)
+    includer.extend(ClassMethods)
+  end
+
+  # Factory function for creating classes with Handler behaviors. Creates a new
+  # class with Handler behaviors from the given super class and block. By
+  # default the super class of the new class will be Object. The given block
+  # will be used as the matcher of the generated class.
+  #
+  # @param super_class [Class] An optional super class to use when creating a
+  #   new class with Handler behaviors.
+  # @yieldparam [Exception] exception_instance The exception instance that
+  #   should be evaluated for a match.
+  # @yieldreturn [Boolean] A boolean value indicating whether or not the
+  #   exception instance was matched.
+  # @return [Class] Returns a new class extended with Handler behaviors.
+  def self.new(super_class = Object, &block)
+    raise ArgumentError, "Block required" unless block_given?
+    handler_class = Class.new(super_class)
+    handler_class.send(:include, self)
+    handler_class.instance_variable_set(:@matcher, block)
+    handler_class
+  end
+
+  # Class-level handler behaviors that will be added to any object that includes
+  # this module.
+  module ClassMethods
+    # Used by Ruby's rescue keyword to evaluate if an exception instance can be
+    # caught by this Class or Module. Delegates to {#matcher}.
+    #
+    # @param exception [Exception] The exception instance that should be evaluated
+    #   for a match.
+    # @return [Boolean] Returns a Boolean value indicating whether or not the
+    #   exception instance matches this handler.
+    def ===(exception)
+      matcher.call(exception)
+    end
+
+    # Factory method that takes in an exception and an optional Hash of
+    # additional contextual information and creates a new Handler instance from
+    # that data. The generated Handler instance is then used to handle the the
+    # exception.
+    #
+    # @param exception [Exception] The exception to handle. Defaults to $!.
+    # @param context [Hash{Symbol=>Object}] An optional Hash of additional
+    #   contextual information about the exception.
+    # @return [Symbol] Returns a symbol indicating what action should be taken
+    #   to continue execution. Depending on the situation, valid values include:
+    #   [:continue, :raise, :retry]
+    def handle(exception = $!, context = {})
+      instance = new
+      context, exception = exception, $! if exception.is_a?(Hash)
+      instance.instance_variable_set(:@exception, exception)
+      instance.instance_variable_set(:@context, context)
+      instance.handle
+    end
+
+    private
+
+    # The block used by the class to evaluate matching exceptions.
+    def matcher
+      @matcher
+    end
+  end
+
+  attr_reader :context, :exception
+
+  # Placeholder method, must be implemented by including class. Should
+  # encapsulate the logic required to handle an exception matced by the class.
+  # Should take no arguments.
+  #
+  # @raise [NotImplementedError] Raised when the including class does not
+  #   provide it's own #handle instance method.
+  # @return [Symbol] Returns a symbol indicating what action should be taken
+  #   to continue execution. Depending on the situation, valid values include:
+  #   [:continue, :raise, :retry]
+  # @return [Array<(Symbol, Object)>] Returns a symbol indicating what action
+  #   should be taken to continue execution and an object that should be used as
+  #   the result of the rescue operation. Depending on the situation, valid
+  #   action values include: [:continue, :raise, :retry]
+  def handle
+    raise NotImplementedError, "#{__method__} must be implemented by including class!"
+  end
+end

data/lib/remotely_exceptional/handlers/prioritized_handler.rb

@@ -0,0 +1,178 @@
+module RemotelyExceptional::Handlers::PrioritizedHandler
+  # The default priority that should be used when registering handlers.
+  DEFAULT_PRIORITY = 1000.freeze
+
+  # Hash#default_proc for hashes that should return a new Set if a given key is
+  # not defined.
+  HASH_BUILDER = lambda { |hash, key| hash[key] = Set.new }.freeze
+
+  def self.included(includer)
+    includer.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    # Determines if any of the available handlers match the provided exception.
+    #
+    # @param exception [Exception] An exception.
+    # @return [Boolean] Returns true if a handler is available that matches the
+    #   given exception. Returns false if none of the available handlers match the
+    #   given exception.
+    def ===(exception)
+      !!handler_for_exception(exception)
+    end
+
+    # Returns the Hash of block handlers by priority.
+    #
+    # @return [Hash{Integer,Set}] The Hash of priorities and which block handlers
+    #   belong to those priorities.
+    def block_handlers
+      Thread.current["#{name}.block_handlers"] ||= Hash.new(&HASH_BUILDER)
+    end
+
+    # The default priority level that should be used for handlers when no priority
+    # is provided.
+    #
+    # @return [Integer] The default priority level.
+    def default_priority
+      const_get(:DEFAULT_PRIORITY)
+    end
+
+    # Finds the handler with the highest priority that matches the exception and
+    # uses this handler to handle the exception. If no handlers are available that
+    # match the given exception, the exception is re-raised.
+    #
+    # @param exception [Exception] The exception to handle.
+    # @param context [Hash{Symbol=>Object}] An optional Hash of additional
+    #   contextual information about the exception.
+    # @raise [exception] The given exception is reraised if no handler is found
+    #   that matches the given exception.
+    # @return [Symbol] Returns a symbol indicating what action should be taken
+    #   to continue execution. Depending on the situation, valid values include:
+    #   [:continue, :raise, :retry]
+    def handle(exception = $!, context = {})
+      context, exception = exception, $! if exception.is_a?(Hash)
+      priority_handler = handler_for_exception(exception)
+      raise exception if !priority_handler
+      priority_handler.handle(exception, context)
+    end
+
+    # Finds the handler with the highest priority that matches the given
+    # exception. Returns nil if no matching handler can be found.
+    #
+    # @param exception [Exception] The exception to find a matching handler for.
+    # @return [RemotelyExceptional::Handler] Returns the handler with the
+    #   highest priority that matches the given exception. If no handler is found,
+    #   returns nil.
+    # @return [nil] Returns nil if no matching handler could be found.
+    def handler_for_exception(exception)
+      prioritized_handlers.detect { |handler| handler === exception }
+    end
+
+    # Returns an enumerator that yields block handlers and registered handlers in
+    # priority ASC, name ASC order. The collection is lazily generated, so changes
+    # to the sets of handlers may appear during traversal. If consistent state is
+    # necessary, force the returned enumerator to eagerly generate the full
+    # collection using #to_a or similar.
+    #
+    # @return [Enumerator<RemotelyExceptional::Handler>] An enumerator of all
+    #   known block handlers and registered handlers in priority ASC, name ASC
+    #   order.
+    def prioritized_handlers
+      Enumerator.new do |yielder|
+        priorities = (registered_handlers.keys | block_handlers.keys).sort!
+        priorities.uniq!
+        priorities.each do |priority|
+          if registered_handlers.key?(priority)
+            collected_handlers = registered_handlers[priority].to_a
+          end
+          if block_handlers.key?(priority)
+            temp_handlers = block_handlers[priority].to_a
+            collected_handlers &&= collected_handlers.concat(temp_handlers)
+            collected_handlers ||= temp_handlers
+          end
+          collected_handlers.sort_by!(&:name)
+          collected_handlers.uniq!
+          collected_handlers.each { |handler| yielder << handler }
+        end
+      end
+    end
+
+    # Adds the given handler to the set of registered handlers. Optionally, a
+    # priority may be supplied. If no priority is supplied the {::default_priority
+    # default priority} is used.
+    #
+    # @param handler [RemotelyExceptional::Handler] The handler that should be
+    #   registered.
+    # @param options [Hash{Symbol=>Object}] A Hash of optional arguments.
+    # @option options [Integer] :priority ({::default_priority}) The priority of
+    #   the handler.
+    # @return [Boolean] Returns true if the handler was successfully registered
+    #   for the given priority. Returns false if the handler was already registered
+    #   for the given priority.
+    def register_handler(handler, options = {})
+      priority = options[:priority] || default_priority
+      !!registered_handlers[priority].add?(handler)
+    end
+
+    # Returns the Hash of registered handlers by priority.
+    #
+    # @return [Hash{Integer,Set<RemotelyExceptional::Handler>}] The Hash of
+    #   priorities and which handlers belong to those priorities.
+    def registered_handlers
+      Thread.current["#{name}.registered_handlers"] ||= Hash.new(&HASH_BUILDER)
+    end
+
+    # Removes the given handler. By default removes the handler from the
+    # {::default_priority default_priority}, but a :priority option may be
+    # supplied to remove the handler from a specified priority.
+    #
+    # @param handler [RemotelyExceptional::Handler] The handler that should be
+    #   removed.
+    # @param options [Hash{Symbol=>Object}] A Hash of optional arguments.
+    # @option options [Integer] :priority ({::default_priority}) The priority that
+    #   should be searched for the given handler.
+    # @return [Boolean] Returns true if the handler was successfully removed for
+    #   the given priority. Returns false if the handler was not registered for
+    #   the given priority.
+    def remove_handler(handler, options = {})
+      priority = options[:priority] || default_priority
+      registered_handlers.key?(priority) &&
+        !!registered_handlers[priority].delete(handler)
+    end
+
+    # Clears all {::block_handlers block handlers} and {::registered_handlers
+    # registered handlers}.
+    #
+    # @return [true]
+    def reset_handlers!
+      Thread.current["#{name}.registered_handlers"] = nil
+      Thread.current["#{name}.block_handlers"] = nil
+      true
+    end
+
+    # Registers a handler for the duration of the given block. By default
+    # registers the block at the {::default_priority default priority}, but a
+    # specific priority may be supplied as an option.
+    #
+    # @param handler [RemotelyExceptional::Handler] The handler that should be
+    #   registered.
+    # @param options [Hash{Symbol=>Object}] A Hash of optional arguments.
+    # @option options [Integer] :priority ({::default_priority}) The priority that
+    #   should be used to register the handler.
+    # @raise [ArgumentError] if a block is not provided.
+    # @return [Boolean] Returns true if the block handler was successfully
+    #   registered for the given priority. Returns false if a matching block
+    #   handler was already registered for the given priority.
+    def with_handler(handler, options = {})
+      raise ArgumentError, "Block required!" unless block_given?
+
+      priority = options[:priority] || default_priority
+      if block_handlers[priority].add?(handler)
+        added_handler = true
+      end
+      yield
+    ensure
+      block_handlers[priority].delete(handler) if added_handler
+    end
+  end
+end

data/lib/remotely_exceptional/remote_handling.rb

@@ -0,0 +1,42 @@
+module RemotelyExceptional::RemoteHandling
+  # Executes the given block of code in a context that allows for remote
+  # handling of exceptions using the specified handler class. Optionally,
+  # additional contextual information may be provided in case of an exception.
+  #
+  # @param handler [RemotelyExceptional::Handler] The handler that should be
+  #   used to match and handle any exceptions that occur.
+  # @param context [Hash{Symbol=>Object}] Optional contextual information that
+  #   will be made available to the handler if an exception occurs.
+  # @raise [ArgumentError] Raised if the provided handler is not a valid
+  #   RemotelyExceptional::Handler.
+  # @raise [RemotelyExceptional::InvalidHandlerResponse] Raised if an exception
+  #   is raised but the handler does not return a valid action symbol.
+  # @raise [Exception] Depending on the Handler used, could raise any error
+  #   returned by the handler's handle method.
+  # @return [Object] Returns the result of the given block if no exception
+  #   occurs.
+  # @return [Object, nil] If an exception occurs may return a result value
+  #   provided by the exception handler's handle method. If the handler's handle
+  #   method does not specify a result, nil will be returned instead.
+  def remotely_exceptional(handler, context = {})
+    raise ArgumentError, "Invalid Handler! Got #{handler.inspect}" unless handler &&
+      handler.respond_to?(:ancestors) &&
+      handler.ancestors.include?(RemotelyExceptional::Handler)
+
+    # Must explicitly use begin otherwise TypeError will occur if handler is not
+    # a Class or Module. We can raise a more specific error if begin is used.
+    begin
+      yield
+    rescue handler
+      response_code, result = handler.handle(context)
+      case response_code
+      when :raise then result ? raise(result) : raise
+      when :retry then retry
+      when :continue then result
+      else
+        msg = "Handler did not return an expected response code!"
+        raise RemotelyExceptional::InvalidHandlerResponse, msg
+      end
+    end
+  end
+end

data/lib/remotely_exceptional/version.rb

@@ -0,0 +1,4 @@
+module RemotelyExceptional
+  # The version of the RemotelyExceptional gem
+  VERSION = "0.0.1"
+end

data/remotely_exceptional.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "remotely_exceptional/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "remotely_exceptional"
+  spec.version       = RemotelyExceptional::VERSION
+  spec.authors       = ["Danny Guinther"]
+  spec.email         = ["dannyguinther@gmail.com"]
+  spec.summary       = %q{Remote control of exceptions raised in distant contexts.}
+  spec.description   = %q{Remote control of exceptions raised in distant contexts.}
+  spec.homepage      = "https://github.com/tdg5/remotely_exceptional"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake", "~> 0"
+end

data/test/test_helper.rb

@@ -0,0 +1,23 @@
+if ENV["CI"]
+  require "simplecov"
+  require "coveralls"
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+  SimpleCov.root(File.expand_path("../..", __FILE__))
+  SimpleCov.start do
+    add_filter "test"
+  end
+end
+
+require "minitest/autorun"
+require "mocha/setup"
+require "remotely_exceptional"
+
+# Use alternate shoulda-style DSL for tests
+class RemotelyExceptional::TestCase < Minitest::Spec
+  class << self
+    alias :setup :before
+    alias :teardown :after
+    alias :context :describe
+    alias :should :it
+  end
+end

data/test/unit/exceptions_test.rb

@@ -0,0 +1,22 @@
+require "test_helper"
+
+class RemotelyExceptional::ExceptionsTest < RemotelyExceptional::TestCase
+  exception = RemotelyExceptional::InvalidHandlerResponse
+  context exception.name do
+    subject { exception }
+    context "#original_exception" do
+      should "capture the original exception if one exists" do
+        assert_nil subject.new.original_exception
+        exception = ArgumentError
+        rescued = false
+        begin
+          raise exception
+        rescue exception
+          rescued = true
+          assert_kind_of exception, subject.new.original_exception
+        end
+        assert_equal true, rescued
+      end
+    end
+  end
+end

data/test/unit/handler_test.rb

@@ -0,0 +1,135 @@
+require "test_helper"
+
+class RemotelyExceptional::HandlerTest < RemotelyExceptional::TestCase
+  Subject = RemotelyExceptional::Handler
+  class TestMixer
+    include Subject
+  end
+
+  context Subject.name do
+    subject { Subject }
+
+    context "::new" do
+      should "raise ArgumentError if no block was given" do
+        assert_raises(ArgumentError) do
+          subject.new
+        end
+      end
+
+      should "return a new class that includes #{Subject.name}" do
+        test_class = subject.new {|other| true }
+        assert_equal true, test_class.ancestors.include?(subject)
+        assert_kind_of subject, test_class.new
+      end
+
+      should "set the matcher to the given block" do
+        block = proc {|other| true }
+        test_class = subject.new(&block)
+        assert_equal block, test_class.send(:matcher)
+      end
+
+      should "take an optional super_class argument" do
+        test_super_class = Class.new
+        test_class = subject.new(test_super_class) {|other| true }
+        assert_kind_of test_super_class, test_class.new
+      end
+    end
+  end
+
+  context TestMixer.name do
+    subject { TestMixer }
+
+    context "included behaviors" do
+      context "::new" do
+        should "not be overriden by the module" do
+          assert_kind_of subject, subject.new
+        end
+      end
+
+      context "::===" do
+        should "call the matcher with the given argument" do
+          expected_argument = ArgumentError
+          subject.expects(:matcher).returns(lambda { |other| other == expected_argument })
+          assert_equal true, subject === expected_argument
+        end
+      end
+
+      context "::handle" do
+        setup do
+          @exception = ArgumentError.new
+          @context = { :context => true }
+          @instance = subject.new
+          subject.expects(:new).at_least(1).returns(@instance)
+        end
+
+        should "create a new instance and invoke #handle" do
+          @instance.expects(:handle)
+          subject.handle(@exception, @context)
+        end
+
+        should "set the exception and context of the instance correctly" do
+          @instance.stubs(:handle)
+          subject.handle(@exception, @context)
+          assert_equal @exception, @instance.exception
+          assert_equal @context, @instance.context
+        end
+
+        should "should automatically detect exception if not provided in an exception context" do
+          @instance.stubs(:handle)
+          begin
+            raise @exception
+          rescue
+            subject.handle(@context)
+          end
+          # Should be the exception in an exception context
+          assert_equal @context, @instance.context
+          assert_equal @exception, @instance.exception
+        end
+
+        should "have a nil exception when not provided an exception outside of an exception context" do
+          @instance.stubs(:handle)
+          subject.handle(@context)
+          assert_equal @context, @instance.context
+          # Should be nil outside of an exception context
+          assert_nil @instance.exception
+        end
+      end
+
+      context "rescue" do
+        should "call the matcher with an exception class when used to rescue" do
+          expected_argument = ArgumentError
+          subject.expects(:matcher).returns(lambda { |other| !other.is_a?(expected_argument) })
+
+          rescued = false
+          assert_raises(ArgumentError) do
+            begin
+              raise ArgumentError
+            rescue subject
+              rescued = true
+            end
+          end
+          assert_equal false, rescued
+        end
+
+        should "invoke rescue code when the matcher matches the exception" do
+          expected_argument = ArgumentError
+          subject.expects(:matcher).returns(lambda { |other| other.is_a?(expected_argument) })
+
+          rescued = false
+          begin
+            raise ArgumentError
+          rescue subject
+            rescued = true
+          end
+          assert_equal true, rescued
+        end
+      end
+
+      context "#handle" do
+        should "raise NotImplementedError if not overriden" do
+          assert_raises(NotImplementedError) { subject.new.handle }
+        end
+      end
+    end
+  end
+end

data/test/unit/handlers/prioritized_handler_test.rb

@@ -0,0 +1,297 @@
+require "test_helper"
+require "remotely_exceptional/handlers/prioritized_handler"
+
+class RemotelyExceptional::Handlers::PrioritizedHandlerTest < RemotelyExceptional::TestCase
+  Subject = RemotelyExceptional::Handlers::PrioritizedHandler
+
+  AlphaHandler = RemotelyExceptional::Handler.new { |ex| ArgumentError === ex }
+  BetaHandler = RemotelyExceptional::Handler.new { |ex| RuntimeError === ex }
+  OmegaHandler = RemotelyExceptional::Handler.new { |ex| Exception === ex }
+
+  class TestSubject
+    include Subject
+  end
+
+  context "module that includes #{Subject.name}" do
+    subject { TestSubject }
+
+    setup { subject.reset_handlers! }
+
+    context "::===" do
+      should "return true if a handler is registered that matches the exception" do
+        subject.register_handler(AlphaHandler)
+        assert_equal true, subject === ArgumentError.new
+      end
+
+      should "return false if none of the handlers match the exception" do
+        subject.register_handler(AlphaHandler)
+        assert_equal false, subject === RuntimeError.new
+      end
+    end
+
+    context "::default_priority" do
+      should "return 1000" do
+        assert_equal 1000, subject.default_priority
+      end
+    end
+
+    context "::handle" do
+      should "delegate handling to the matching handler with the highest priority" do
+        subject.register_handler(AlphaHandler)
+        subject.register_handler(OmegaHandler, :priority => 10)
+        ex = ArgumentError.new
+        result = :continue
+        context = { :context => :foo }
+        OmegaHandler.expects(:handle).with(ex, context).returns(result)
+        assert_equal result, subject.handle(ex, context)
+      end
+
+      should "re-raise the exception if no matching handler is found" do
+        ex = ArgumentError.new
+        assert_raises(ex.class) { subject.handle(ex) }
+      end
+    end
+
+    context "::handler_for_exception" do
+      should "return the matching handler" do
+        subject.register_handler(AlphaHandler)
+        assert_equal AlphaHandler, subject.handler_for_exception(ArgumentError.new)
+      end
+
+      should "return the matching handler with the highest priority" do
+        subject.register_handler(AlphaHandler)
+        subject.register_handler(OmegaHandler, :priority => 10)
+        assert_equal OmegaHandler, subject.handler_for_exception(ArgumentError.new)
+      end
+
+      should "return nil if no matching handler is found" do
+        subject.register_handler(AlphaHandler)
+        subject.register_handler(BetaHandler)
+        assert_nil subject.handler_for_exception(SystemStackError.new)
+      end
+    end
+
+    context "::prioritized_handlers" do
+      should "yield handlers in priority ASC, name ASC order" do
+        setup_registered_handlers(subject)
+        found_handlers = nil
+        # Should be yielded first
+        subject.with_handler(BetaHandler, :priority => 5) do
+          # Should be yielded last
+          subject.with_handler(OmegaHandler, :priority => 2500) do
+            # Should only be yielded once for this priority
+            subject.with_handler(AlphaHandler) do
+              found_handlers = subject.prioritized_handlers.to_a
+            end
+          end
+        end
+        @expected_handlers.unshift(BetaHandler)
+        @expected_handlers.push(OmegaHandler)
+        assert_equal @expected_handlers, found_handlers
+      end
+
+      should "work when there are only registered handlers" do
+        setup_registered_handlers(subject)
+        subject.instance_variable_set(:@block_handlers, nil)
+        assert_equal @expected_handlers, subject.prioritized_handlers.to_a
+      end
+
+      should "work when there are only block handlers" do
+        found_handlers = nil
+        subject.with_handler(BetaHandler, :priority => 5) do
+          subject.with_handler(OmegaHandler, :priority => 2500) do
+            subject.with_handler(AlphaHandler) do
+              found_handlers = subject.prioritized_handlers.to_a
+            end
+          end
+        end
+        expected_handlers = [
+          BetaHandler,
+          AlphaHandler,
+          OmegaHandler,
+        ]
+        assert_equal expected_handlers, found_handlers
+      end
+
+      should "yield a handler only once per priority level" do
+        subject.register_handler(AlphaHandler)
+        found_handlers = nil
+        subject.with_handler(AlphaHandler) do
+          found_handlers = subject.prioritized_handlers.to_a
+        end
+        assert_equal 1, found_handlers.length
+        assert_equal AlphaHandler, found_handlers.first
+      end
+
+      context "set scan" do
+        should "not create empty sets when no keys exist" do
+          subject.prioritized_handlers.to_a
+          assert_empty subject.send(:registered_handlers)
+          assert_empty subject.send(:block_handlers)
+        end
+
+        should "not create empty sets when a key exists in one set" do
+          priority = 1000
+          subject.with_handler(AlphaHandler, :priority => priority) do
+            subject.prioritized_handlers.to_a
+          end
+          assert_equal false, subject.send(:registered_handlers).key?(priority)
+
+          priority = 10
+          subject.register_handler(AlphaHandler, :priority => priority)
+          assert_equal false, subject.send(:block_handlers).key?(priority)
+        end
+      end
+    end
+
+    context "::register_handler" do
+      should "return false if the handler was not registered" do
+        priority = 10
+        assert_equal true, subject.register_handler(AlphaHandler, :priority => priority)
+        assert_equal false, subject.register_handler(AlphaHandler, :priority => priority)
+      end
+
+      should "return true if the handler was registered" do
+        priority = 10
+        assert_equal true, subject.register_handler(AlphaHandler, :priority => priority)
+      end
+
+      should "register the handler with the provided priority" do
+        priority = 10
+        registered_handlers = subject.send(:registered_handlers)
+        registered_handlers.expects(:[]).with(priority).returns(Set.new)
+        assert_equal true, subject.register_handler(AlphaHandler, :priority => priority)
+      end
+
+      should "register the handler with the default priority if no priority given" do
+        priority = subject.default_priority
+        registered_handlers = subject.send(:registered_handlers)
+        registered_handlers.expects(:[]).with(priority).returns(Set.new)
+        assert_equal true, subject.register_handler(AlphaHandler)
+      end
+    end
+
+    context "::remove_handler" do
+      should "return false if the handler was not removed" do
+        assert_equal false, subject.remove_handler(AlphaHandler)
+      end
+
+      should "return true if the handler was removed" do
+        assert_equal true, subject.register_handler(AlphaHandler)
+        assert_equal true, subject.remove_handler(AlphaHandler)
+      end
+
+      should "remove a handler with a matching priority" do
+        priority = 10
+        assert_equal true, subject.register_handler(AlphaHandler, :priority => priority)
+        assert_equal true, subject.remove_handler(AlphaHandler, :priority => priority)
+      end
+
+      should "not remove a handler with a non-matching priority" do
+        priority = 10
+        assert_equal true, subject.register_handler(AlphaHandler, :priority => priority)
+        assert_equal false, subject.remove_handler(AlphaHandler)
+      end
+    end
+
+    context "::reset_handlers!" do
+      should "clear all handlers" do
+        subject.register_handler(AlphaHandler, :priority => 10)
+        initial_found_handlers = final_found_handlers = nil
+        subject.with_handler(AlphaHandler) do
+          initial_found_handlers = subject.prioritized_handlers.to_a
+          subject.reset_handlers!
+          final_found_handlers = subject.prioritized_handlers.to_a
+        end
+        assert_equal 2, initial_found_handlers.length
+        assert_equal 0, final_found_handlers.length
+      end
+    end
+
+    context "::with_handler" do
+      should "raise ArgumentError if no block is given" do
+        assert_raises(ArgumentError) do
+          subject.with_handler(AlphaHandler)
+        end
+      end
+
+      should "register the handler if it is not already registered" do
+        assert_equal true, subject.prioritized_handlers.none?
+        subject.with_handler(AlphaHandler) do
+          found_handlers = subject.prioritized_handlers.to_a
+          assert_equal 1, found_handlers.length
+          assert_equal AlphaHandler, subject.prioritized_handlers.first
+
+          # Should not add the handler again.
+          subject.with_handler(AlphaHandler) do
+            found_handlers = subject.prioritized_handlers.to_a
+            assert_equal 1, found_handlers.length
+            assert_equal AlphaHandler, subject.prioritized_handlers.first
+          end
+        end
+        assert_equal true, subject.prioritized_handlers.none?
+      end
+
+      should "register the handler with the given priority" do
+        priority = 10
+        assert_equal true, subject.prioritized_handlers.none?
+        subject.with_handler(AlphaHandler, :priority => priority) do
+          found_handler = subject.send(:block_handlers)[priority].first
+          assert_equal AlphaHandler, found_handler
+        end
+        assert_equal true, subject.prioritized_handlers.none?
+      end
+
+      should "register the handler with the default priority if no priority given" do
+        priority = subject.default_priority
+        assert_equal true, subject.prioritized_handlers.none?
+        subject.with_handler(AlphaHandler, :priority => priority) do
+          found_handler = subject.send(:block_handlers)[priority].first
+          assert_equal AlphaHandler, found_handler
+        end
+        assert_equal true, subject.prioritized_handlers.none?
+      end
+
+      should "remove the handler after yielding" do
+        assert_equal true, subject.prioritized_handlers.none?
+        subject.with_handler(AlphaHandler) do
+          assert_equal AlphaHandler, subject.prioritized_handlers.first
+        end
+        assert_equal true, subject.prioritized_handlers.none?
+      end
+
+      should "remove the handler even if an error occurs" do
+        assert_equal true, subject.prioritized_handlers.none?
+        assert_raises(Exception) do
+          subject.with_handler(AlphaHandler) do
+            assert_equal AlphaHandler, subject.prioritized_handlers.first
+            raise Exception
+          end
+        end
+        assert_equal true, subject.prioritized_handlers.none?
+      end
+    end
+
+  end
+
+  def setup_registered_handlers(handler)
+    # 5
+    assert_equal true, handler.register_handler(AlphaHandler)
+    # 2
+    assert_equal true, handler.register_handler(AlphaHandler, :priority => 500)
+    # 3
+    assert_equal true, handler.register_handler(BetaHandler, :priority => 500)
+    # 1
+    assert_equal true, handler.register_handler(OmegaHandler, :priority => 50)
+    # 4
+    assert_equal true, handler.register_handler(OmegaHandler, :priority => 500)
+
+    @expected_handlers =  [
+      OmegaHandler,
+      AlphaHandler,
+      BetaHandler,
+      OmegaHandler,
+      AlphaHandler,
+    ]
+  end
+end

data/test/unit/remote_handling_test.rb

@@ -0,0 +1,110 @@
+require "test_helper"
+
+class RemotelyExceptional::RemoteHandlingTest < RemotelyExceptional::TestCase
+  Subject = RemotelyExceptional::RemoteHandling
+
+  class TestMixer
+    include Subject
+  end
+
+  class TestHandler
+    include RemotelyExceptional::Handler
+    def self.matcher
+      lambda { |ex| ex.is_a?(exception_class) }
+    end
+
+    def self.exception_class
+      RuntimeError
+    end
+  end
+
+  context "class that includes #{Subject.name}" do
+
+    context "#remotely_exceptional" do
+      subject { TestMixer.new }
+
+      setup do
+        @handler = TestHandler
+        @instance = TestHandler.new
+        @handler.stubs(:new).returns(@instance)
+      end
+
+      should "raise ArgumentError unless a Handler is given" do
+        [nil, Class.new, Module.new, :not_a_handler].each do |handler|
+          assert_raises(ArgumentError) { subject.remotely_exceptional(handler) }
+        end
+      end
+
+      should "yield to the provided block" do
+        block_called = false
+        subject.remotely_exceptional(@handler) do
+          block_called = true
+        end
+        assert_equal true, block_called
+      end
+
+      context "response codes" do
+        should "raise InvalidHandlerResponse if unrecognized response code" do
+          @instance.expects(:handle).returns(:not_a_thing)
+          exception = assert_raises(RemotelyExceptional::InvalidHandlerResponse) do
+            subject.remotely_exceptional(@handler) do
+              raise @handler.exception_class
+            end
+          end
+          assert_kind_of @handler.exception_class, exception.original_exception
+        end
+
+        should "retry if retry code is given" do
+          @instance.expects(:handle).returns(:retry)
+          already_called = false
+          retried = false
+          subject.remotely_exceptional(@handler) do
+            if already_called
+              retried = true
+            else
+              already_called = true
+              raise @handler.exception_class
+            end
+          end
+          assert_equal true, retried
+        end
+
+        should "raise if raise code is given" do
+          @instance.expects(:handle).returns(:raise)
+          assert_raises(@handler.exception_class) do
+            subject.remotely_exceptional(@handler) do
+              raise @handler.exception_class
+            end
+          end
+        end
+
+        should "raise given exception if raise code is given with exception" do
+          exception_class = ArgumentError
+          @instance.expects(:handle).returns([:raise, exception_class])
+          assert_raises(exception_class) do
+            subject.remotely_exceptional(@handler) do
+              raise @handler.exception_class
+            end
+          end
+        end
+
+        should "continue if continue code is given" do
+          @instance.expects(:handle).returns(:continue)
+          result = subject.remotely_exceptional(@handler) do
+            raise @handler.exception_class
+          end
+          assert_nil result
+        end
+
+        should "continue and return given value if continue code is given with value" do
+          expected_result = 42
+          @instance.expects(:handle).returns([:continue, expected_result])
+          result = subject.remotely_exceptional(@handler) do
+            raise @handler.exception_class
+          end
+          assert_equal expected_result, result
+        end
+      end
+    end
+  end
+end

data/test/unit/remotely_exceptional_test.rb

@@ -0,0 +1,13 @@
+require "test_helper"
+
+class RemotelyExceptionalTest < RemotelyExceptional::TestCase
+  Subject = RemotelyExceptional
+
+  subject { Subject }
+
+  context Subject.name do
+    should "be defined" do
+      assert defined?(subject), "Expected #{subject.name} to be defined!"
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: remotely_exceptional
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Danny Guinther
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+description: Remote control of exceptions raised in distant contexts.
+email:
+- dannyguinther@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/remotely_exceptional.rb
+- lib/remotely_exceptional/exceptions.rb
+- lib/remotely_exceptional/handler.rb
+- lib/remotely_exceptional/handlers/prioritized_handler.rb
+- lib/remotely_exceptional/remote_handling.rb
+- lib/remotely_exceptional/version.rb
+- remotely_exceptional.gemspec
+- test/test_helper.rb
+- test/unit/exceptions_test.rb
+- test/unit/handler_test.rb
+- test/unit/handlers/prioritized_handler_test.rb
+- test/unit/remote_handling_test.rb
+- test/unit/remotely_exceptional_test.rb
+homepage: https://github.com/tdg5/remotely_exceptional
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Remote control of exceptions raised in distant contexts.
+test_files:
+- test/test_helper.rb
+- test/unit/exceptions_test.rb
+- test/unit/handler_test.rb
+- test/unit/handlers/prioritized_handler_test.rb
+- test/unit/remote_handling_test.rb
+- test/unit/remotely_exceptional_test.rb
+has_rdoc: