substation 0.0.8 → 0.0.9

data/config/rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  Includes:
+    - '../**/*.rake'
+  Excludes:
+    - '../spec/spec_helper.rb'
+
+# Avoid parameter lists longer than five parameters.
+ParameterLists:
+  Max: 3
+  CountKeywordArgs: true
+
+# Avoid more than `Max` levels of nesting.
+BlockNesting:
+  Max: 3
+
+HashSyntax:
+  Enabled: false
+
+Blocks:
+  Enabled: false
+
+SpaceInsideBrackets:
+  Enabled: false
+
+Documentation:
+  Enabled: false # reek already checks this and rubocop requires duplicate docs
+
+SingleLineMethods:
+  Enabled: false
+
+LineLength:
+  Max: 106 # the offending lines are in specs, sadly this means global disabling for now 
+
+MethodLength:
+  Max: 12 # reek performs these checks anyway

data/lib/substation.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 require 'set'
 require 'forwardable'
 
@@ -31,6 +33,13 @@ require 'concord'
 # action.
 
 module Substation
+
+  # An empty frozen array useful for (default) parameters
+  EMPTY_ARRAY = [].freeze
+
+  # Error raised when trying to access an unknown processor
+  UnknownProcessor = Class.new(StandardError)
+
 end
 
 require 'substation/utils'
@@ -41,8 +50,8 @@ require 'substation/chain'
 require 'substation/chain/dsl'
 require 'substation/processor'
 require 'substation/processor/evaluator'
-require 'substation/processor/pivot'
 require 'substation/processor/wrapper'
+require 'substation/processor/transformer'
 require 'substation/environment'
 require 'substation/environment/dsl'
 require 'substation/dispatcher'

data/lib/substation/chain.rb

@@ -1,20 +1,19 @@
+# encoding: utf-8
+
 module Substation
 
   # Implements a chain of responsibility for an action
   #
   # An instance of this class will typically contain (in that order)
-  # a few handlers that process the incoming {Request} object, one
-  # handler that calls an action ({Chain::Pivot}), and some handlers
+  # a few processors that process the incoming {Request} object, one
+  # processor that calls an action ({Processor::Pivot}), and some processors
   # that process the outgoing {Response} object.
   #
-  # Both {Chain::Incoming} and {Chain::Outgoing} handlers must
-  # respond to `#call(response)` and `#result(response)`.
-  #
-  # @example chain handlers (used in instance method examples)
+  # @example chain processors (used in instance method examples)
   #
   #   module App
   #
-  #     class Handler
+  #     class Processor
   #
   #       def initialize(handler = nil)
   #         @handler = handler
@@ -25,11 +24,11 @@ module Substation
   #       attr_reader :handler
   #
   #       class Incoming < self
-  #         include Substation::Chain::Incoming
+  #         include Substation::Processor::Incoming
   #       end
   #
   #       class Outgoing < self
-  #         include Substation::Chain::Outgoing
+  #         include Substation::Processor::Outgoing
   #
   #         private
   #
@@ -39,13 +38,13 @@ module Substation
   #       end
   #     end
   #
-  #     class Validator < Handler::Incoming
+  #     class Validator < Processor::Incoming
   #       def call(request)
   #         result = handler.call(request.input)
-  #         if result.valid?
+  #         if result.success?
   #           request.success(request.input)
   #         else
-  #           request.error(result.violations)
+  #           request.error(result.output)
   #         end
   #       end
   #     end
@@ -58,7 +57,7 @@ module Substation
   #       end
   #     end
   #
-  #     class Presenter < Handler::Outgoing
+  #     class Presenter < Processor::Outgoing
   #       def call(response)
   #         respond_with(response, handler.new(response.output))
   #       end
@@ -67,74 +66,97 @@ module Substation
   #
   class Chain
 
-    # Supports chaining handlers processed before the {Pivot}
-    module Incoming
+    include Enumerable
+    include Concord.new(:processors, :failure_chain)
+    include Adamantium::Flat
 
-      # The request passed on to the next handler in a {Chain}
-      #
-      # @param [Response] response
-      #   the response returned from the previous handler in a {Chain}
+    # Empty chain
+    EMPTY = Class.new(self).new(EMPTY_ARRAY, EMPTY_ARRAY)
+
+    # Wraps response data and an exception not caught from a handler
+    class FailureData
+      include Equalizer.new(:data)
+
+      # Return the data available when +exception+ was raised
       #
-      # @return [Request]
-      #   the request passed on to the next handler in a {Chain}
+      # @return [Object]
       #
       # @api private
-      def result(response)
-        Request.new(response.env, response.output)
-      end
-    end
+      attr_reader :data
 
-    # Supports chaining the {Pivot} or handlers processed after the {Pivot}
-    module Outgoing
+      # Return the exception instance
+      #
+      # @return [Class<StandardError>]
+      #
+      # @api private
+      attr_reader :exception
 
-      # The response passed on to the next handler in a {Chain}
+      # Initialize a new instance
+      #
+      # @param [Object] data
+      #   the data available when +exception+ was raised
       #
-      # @param [Response] response
-      #   the response returned from the previous handler in a {Chain}
+      # @param [Class<StandardError>] exception
+      #   the exception instance raised from a handler
       #
-      # @return [Response]
-      #   the response passed on to the next handler in a {Chain}
+      # @return [undefined]
       #
       # @api private
-      def result(response)
-        response
+      def initialize(data, exception)
+        @data, @exception = data, exception
+      end
+
+      # Return the hash value
+      #
+      # @return [Fixnum]
+      #
+      # @api private
+      def hash
+        super ^ exception.class.hash
       end
 
       private
 
-      # Build a new {Response} based on +response+ and +output+
+      # Tests wether +other+ is comparable using +comparator+
       #
-      # @param [Response] response
-      #   the original response
+      # @param [Symbol] comparator
+      #   the operation used for comparison
       #
-      # @param [Object] output
-      #   the data to be wrapped within the new {Response}
+      # @param [Object] other
+      #   the object to test
       #
-      # @return [Response]
+      # @return [Boolean]
       #
       # @api private
-      def respond_with(response, output)
-        response.class.new(response.request, output)
+      def cmp?(comparator, other)
+        super && exception.class.send(comparator, other.exception.class)
       end
     end
 
-    # Supports chaining the {Pivot} handler
-    Pivot = Outgoing
-
-    include Enumerable
-    include Concord.new(:handlers)
-    include Adamantium::Flat
-    include Pivot # allow nesting of chains
-
-    # Empty chain
-    EMPTY = Class.new(self).new([])
+    # Return a failure response
+    #
+    # @param [Request] request
+    #   the initial request passed into the chain
+    #
+    # @param [Object] data
+    #   the processed data available when the exception was raised
+    #
+    # @param [Class<StandardError>] exception
+    #   the exception instance that was raised
+    #
+    # @return [Response::Failure]
+    #
+    # @api private
+    def self.failure_response(request, data, exception)
+      Response::Failure.new(request, FailureData.new(data, exception))
+    end
 
     # Call the chain
     #
-    # Invokes all handlers and returns either the first
+    # Invokes all processors and returns either the first
     # {Response::Failure} that it encounters, or if all
     # goes well, the {Response::Success} returned from
-    # the last handler.
+    # the last processor.
     #
     # @example
     #
@@ -162,20 +184,21 @@ module Substation
     #   the request to handle
     #
     # @return [Response::Success]
-    #   the response returned from the last handler
+    #   the response returned from the last processor
     #
     # @return [Response::Failure]
-    #   the response returned from the failing handler
-    #
-    # @raise [Exception]
-    #   any exception that isn't explicitly rescued in client code
+    #   the response returned from the failing processor's failure chain
     #
     # @api public
     def call(request)
-      handlers.inject(request) { |result, handler|
-        response = handler.call(result)
-        return response unless response.success?
-        handler.result(response)
+      processors.reduce(request) { |result, processor|
+        begin
+          response = processor.call(result)
+          return response unless processor.success?(response)
+          processor.result(response)
+        rescue => exception
+          return on_failure(request, result, exception)
+        end
       }
     end
 
@@ -194,8 +217,29 @@ module Substation
     # @api private
     def each(&block)
       return to_enum unless block
-      handlers.each(&block)
+      processors.each(&block)
       self
     end
+
+    private
+
+    # Call the failure chain in case of an uncaught exception
+    #
+    # @param [Request] request
+    #   the initial request passed into the chain
+    #
+    # @param [Object] data
+    #   the processed data available when the exception was raised
+    #
+    # @param [Class<StandardError>] exception
+    #   the exception instance that was raised
+    #
+    # @return [Response::Failure]
+    #
+    # @api private
+    def on_failure(request, data, exception)
+      failure_chain.call(self.class.failure_response(request, data, exception))
+    end
+
   end # class Chain
 end # module Substation

data/lib/substation/chain/dsl.rb

@@ -1,25 +1,8 @@
-module Substation
+# encoding: utf-8
 
+module Substation
   class Chain
 
-    # Build a new chain instance
-    #
-    # @param [DSL] dsl
-    #   the dsl klass to use for defining the chain
-    #
-    # @param [Chain] other
-    #   another chain to build on top of
-    #
-    # @param [Proc] block
-    #   a block to instance_eval in the context of +dsl+
-    #
-    # @return [Chain]
-    #
-    # @api private
-    def self.build(dsl, other, &block)
-      new(dsl.processors(other, &block))
-    end
-
     # The DSL class used to define chains in an {Environment}
     class DSL
 
@@ -72,7 +55,6 @@ module Substation
           }
         end
 
-
         # Define a new instance method on the +dsl+ class
         #
         # @param [Symbol] name
@@ -89,38 +71,36 @@ module Substation
         # @api private
         def define_dsl_method(name, processor, dsl)
           dsl.class_eval do
-            define_method(name) { |*args| use(processor.new(*args)) }
+            define_method(name) { |*args| use(processor.new(name, *args)) }
           end
         end
 
       end # class Builder
 
-      # The processors to be used within a {Chain}
+      # Build a new {Chain} based on +other+, a +failure_chain+ and a block
       #
-      # @return [Array<#call>]
-      #
-      # @api private
-      attr_reader :processors
-
-      # The processors to be used within a {Chain}
+      # @param [#each<#call>] other
+      #   the processors to build on top of
       #
-      # @param [Chain] chain
-      #   the chain to build on top of
+      # @param [Chain] failure_chain
+      #   the failure chain to invoke in case of an uncaught exception
       #
       # @param [Proc] block
       #   a block to be instance_eval'ed
       #
-      # @return [Array<#call>]
+      # @return [Chain]
       #
       # @api private
-      def self.processors(chain, &block)
-        new(chain, &block).processors
+      def self.build(other, failure_chain, &block)
+        Chain.new(new(other, &block).processors, failure_chain)
       end
 
+      include Equalizer.new(:processors)
+
       # Initialize a new instance
       #
       # @param [#each<#call>] processors
-      #   an enumerable of processors to build on top of
+      #   the processors to build on top of
       #
       # @param [Proc] block
       #   a block to be instance_eval'ed
@@ -129,11 +109,20 @@ module Substation
       #
       # @api private
       def initialize(processors, &block)
-        @processors = []
+        @processors = {}
         chain(processors)
         instance_eval(&block) if block
       end
 
+      # The processors to be used within a {Chain}
+      #
+      # @return [Array<#call>]
+      #
+      # @api private
+      def processors
+        @processors.values
+      end
+
       # Use the given +processor+ within a chain
       #
       # @param [#call] processor
@@ -143,7 +132,7 @@ module Substation
       #
       # @api private
       def use(processor)
-        @processors << processor
+        @processors[processor.name] = processor
         self
       end
 
@@ -156,10 +145,46 @@ module Substation
       #
       # @api private
       def chain(other)
-        other.each { |handler| use(handler) }
+        other.each { |processor| use(processor) }
+        self
+      end
+
+      # Use +chain+ as the failure chain for the processor identified by +name+
+      #
+      # @param [Symbol] name
+      #   the processor's name
+      #
+      # @param [#call] chain
+      #   the failure chain to use for the processor identified by +name+
+      #
+      # @return [self]
+      #
+      # @api private
+      def failure_chain(name, chain)
+        @processors[name] = processor(name).with_failure_chain(chain)
         self
       end
 
+      private
+
+      # Return the processor identified by +name+
+      #
+      # @param [Symbol] name
+      #   the processor's name
+      #
+      # @return [#call]
+      #   the processor identified by +name+
+      #
+      # @raise [UnknownProcessor]
+      #   if no processor identified by +name+ is registered
+      #
+      # @api private
+      def processor(name)
+        @processors.fetch(name) {
+          raise UnknownProcessor, "No processor named #{name.inspect} is registered"
+        }
+      end
+
     end # class DSL
   end # class Chain
 end # module Substation