substation 0.0.8 → 0.0.9

data/.travis.yml

@@ -9,3 +9,7 @@ rvm:
   - jruby-19mode
   - jruby-head
   - rbx-19mode
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: rbx-19mode

data/Changelog.md

@@ -1,8 +1,98 @@
-# v0.0.9 (not yet released)
+# v0.0.10 (not yet released)
 
 *
 
-[Compare v0.0.8..master](https://github.com/snusnu/substation/compare/v0.0.8...master)
+[Compare v0.0.9..master](https://github.com/snusnu/substation/compare/v0.0.9...master)
+
+# v0.0.9 2013-07-10
+
+* [BREAKING CHANGE] Refactor `Substation::Processor` classes.
+
+  * Renamed `Substation::Processor::Evaluator` to `Substation::Processor::Evaluator::Data`.
+  * Renamed `Substation::Processor::Pivot` to `Substation::Processor::Evaluator::Pivot`.
+  * Added `Substation::Processor::Evaluator::Request` which passes the complete `Request` instance on to the handler.
+  * Added `Substation::Processor::Transformer` to transform `Response#output` into any other object.
+
+* [feature] Make the dispatched name available in `Request#name`.
+
+* [feature] Support (re)definining failure chains for `Substation::Processor::Fallible` processors.
+
+        module Demo
+          ENV = Substation::Environment.build do
+            register :validate, Substation::Processor::Evaluator::Data
+            register :call,     Substation::Processor::Evaluator::Pivot
+            register :wrap,     Substation::Processor::Wrapper
+            register :render,   Substation::Processor::Transformer
+          end
+
+          class Error
+            attr_reader :data
+            def initialize(data)
+              @data = data
+            end
+
+            ValidationError  = Class.new(self)
+            ApplicationError = Class.new(self)
+            InternalError    = Class.new(self)
+          end
+
+          module App
+            VALIDATION_ERROR  = Demo::ENV.chain { wrap Error::ValidationError }
+            APPLICATION_ERROR = Demo::ENV.chain { wrap Error::ApplicationError }
+
+            SOME_ACTION = Demo::ENV.chain do
+              validate Vanguard::Validator, VALIDATION_ERROR
+              call     Some::Action,        APPLICATION_ERROR
+            end
+          end
+
+          module Web
+            VALIDATION_ERROR = Demo::ENV.chain(App::VALIDATION_ERROR) do
+              render Renderer::ValidationError
+            end
+
+            APPLICATION_ERROR = Demo::ENV.chain(App::APPLICATION_ERROR) do
+              render Renderer::ApplicationError
+            end
+
+            # in case of success, returns an instance of Views::Person
+            # in case of validation failure, renders using Renderer::ValidationError
+            # in case of internal error, renders using Renderer::InternalError
+            SOME_ACTION = Demo::ENV.chain(App::SOME_ACTION) do
+              failure_chain :validate, VALIDATION_ERROR
+              failure_chain :call,     INTERNAL_ERROR
+              wrap Presenters::Person
+              wrap Views::ShowPerson
+            end
+          end
+        end
+
+* [feature] Support (re)defining chain specific failure chains in case of uncaught exceptions.
+
+        module Demo
+
+          module App
+            INTERNAL_ERROR = Demo::ENV.chain { wrap Error::InternalError }
+          end
+
+          module Web
+
+            INTERNAL_ERROR = Demo::ENV.chain(App::INTERNAL_ERROR) do
+              render Renderer::InternalError
+            end
+
+            # The INTERNAL_ERROR chain will be called if an exception
+            # isn't rescued by the responsible handler
+            SOME_ACTION = Demo::ENV.chain(App::SOME_ACTION, INTERNAL_ERROR) do
+              failure_chain :validate, VALIDATION_ERROR
+              failure_chain :call,     INTERNAL_ERROR
+              wrap Presenters::Person
+              wrap Views::ShowPerson
+            end
+          end
+        end
+
+[Compare v0.0.8..v0.0.9](https://github.com/snusnu/substation/compare/v0.0.8...v0.0.9)
 
 # v0.0.8 2013-06-19
 

data/Gemfile.devtools

@@ -1,22 +1,23 @@
 # encoding: utf-8
 
 group :development do
-  gem 'rake',  '~> 10.0.4'
+  gem 'rake',  '~> 10.1.0'
   gem 'rspec', '~> 2.13.0'
-  gem 'yard',  '~> 0.8.6.1'
+  gem 'yard',  '~> 0.8.6.2'
 end
 
 group :yard do
-  gem 'kramdown', '~> 1.0.1'
+  gem 'kramdown', '~> 1.1.0'
 end
 
 group :guard do
-  gem 'guard',         '~> 1.8.0'
+  gem 'guard',         '~> 1.8.1'
   gem 'guard-bundler', '~> 1.0.0'
-  gem 'guard-rspec',   '~> 2.5.4'
+  gem 'guard-rspec',   '~> 3.0.2'
+  gem 'guard-rubocop', '~> 0.2.0'
 
   # file system change event handling
-  gem 'listen',     '~> 1.0.2'
+  gem 'listen',     '~> 1.2.2'
   gem 'rb-fchange', '~> 0.0.6', :require => false
   gem 'rb-fsevent', '~> 0.9.3', :require => false
   gem 'rb-inotify', '~> 0.9.0', :require => false
@@ -28,20 +29,21 @@ group :guard do
 end
 
 group :metrics do
-  gem 'backports',       '~> 3.3', '>= 3.3.0'
-  gem 'coveralls',       '~> 0.6.6'
-  gem 'flay',            '~> 2.2.0'
-  gem 'flog',            '~> 4.0.0'
-  gem 'reek',            '~> 1.3.1', :git => 'https://github.com/troessner/reek.git'
-  gem 'simplecov',       '~> 0.7.1'
-  gem 'yardstick',       '~> 0.9.6'
-
-  platforms :ruby_19 do
+  gem 'coveralls', '~> 0.6.7'
+  gem 'flay',      '~> 2.3.0'
+  gem 'flog',      '~> 4.1.0'
+  gem 'reek',      '~> 1.3.1', :git => 'https://github.com/troessner/reek.git'
+  gem 'rubocop',   '~> 0.9.1'
+  gem 'simplecov', '~> 0.7.1'
+  gem 'yardstick', '~> 0.9.6'
+
+  platforms :ruby_19, :ruby_20 do
+    gem 'mutant',          '~> 0.3.0.beta13'
     gem 'yard-spellcheck', '~> 0.1.5'
   end
 
-  platforms :mri_19, :rbx do
-    gem 'mutant', '~> 0.2.20'
+  platforms :ruby_19 do
+    gem 'json', '~> 1.8.0'
   end
 
   platforms :rbx do

data/README.md

@@ -22,7 +22,8 @@ receive arbitrary input data which will be available in `request.input`.
 Additionally, `request.env` contains an arbitrary object that
 represents your application environment and will typically provide access
 to useful things like a logger and probably some sort of storage engine
-abstraction object.
+abstraction object. Furthermore, `request.name` will contain the action
+name the `Substation::Dispatcher` used when dispatching to an action.
 
 The contract further specifies that every action must return an instance
 of either `Substation::Response::Success` or
@@ -509,9 +510,9 @@ In a typical application scenario, a few things need to happen before an
 actual use case (an action) can be invoked. These things will often
 include the following steps (probably in that order).
 
+* Input data sanitization
 * Authentication
 * Authorization
-* Input data sanitization
 * Input data validation
 
 We only want to invoke our action if all those steps succeed. If any of
@@ -541,129 +542,198 @@ b) If you need to return JSON, you might just
 * Pass the response data to some serializer object and dump it to JSON
 
 To allow chaining all those steps in a declarative way, substation
-provides an object called `Substation::Chain`. Its contract is dead
-simple:
-
-1. `#call(Substation::Request) => Substation::Response`
-2. `#result(Substation::Response) => Substation::Response`
-
-You typically won't be calling `Substation::Chain#result` yourself, but
-having it around, allows us to use chains in *incoming handlers*,
-essentially nesting chains. This makes it possible to construct one
-chain up until the pivot handler, and then reuse that same chain in one
-usecase that takes the response and renders HTML, and in another that
-renders JSON.
-
-To construct a chain, you need to pass an enumerable of so called
-handler objects to `Substation::Chain.new`. Handlers must support two
-methods:
+provides an object called `Substation::Chain`. To construct a chain, you
+need to pass an enumerable of processors to `Substation::Chain#initialize`.
+Processors must support three methods:
 
 1. `#call(<Substation::Request, Substation::Response>) => Substation::Response`
 2. `#result(Substation::Response) => <Substation::Request, Substation::Response>`
+3. `#success?(Substation::Response) => Boolean`
 
-### Incoming handlers
+### Incoming processors
 
 All steps required *before* processing the action will potentially
 produce a new, altered, `Substation::Request`. Therefore, the object
 passed to `#call` must be an instance of `Substation::Request`.
 
 Since `#call` must return a `Substation::Response` (because the chain
-would halt and return that response in case calling its `#success?`
+would halt and return that response in case calling `Processor#success?`
 method would return `false`), we also need to implement `#result`
 and have it return a `Substation::Request` instance that can be passed
 on to the next handler.
 
-The contract for incoming handlers therefore is:
+The contract for incoming processors therefore is:
 
 1. `#call(Substation::Request) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Request`
+3. `#success?(Substation::Response) => Boolean`
 
-By including the `Substation::Chain::Incoming` module into your handler
-class, you'll get the following for free:
+By including the `Substation::Processor::Incoming` module into your
+processor class, you'll get the following for free:
 
 ```ruby
+def initialize(name, handler, failure_chain)
+  @name, @handler, @failure_chain = name, handler, failure_chain
+end
+
 def result(response)
-  Request.new(response.env, response.output)
+  response.to_request
+end
+
+def success?(response)
+  response.success?
+end
+
+def with_failure_chain(chain)
+  self.class.new(name, handler, chain)
 end
 ```
 
-This shows that an incoming handler can alter the incoming request in any
+This shows that an incoming processor can alter the incoming request in any
 way that it wants to, as long as it returns the new request input data in
 `Substation::Response#output` returned from `#call`.
 
-### The pivot handler
+Currently, `substation` provides the following incoming processors out
+of the box:
+
+* `Substation::Processor::Evaluator::Request` passes `request` to the handler
+* `Substation::Processor::Evaluator::Data` passes `request.input` to the handler
+
+### The pivot processor
 
 Pivot is just another fancy name for the action in the context of a
-chain. It's also the point where all subsequent handlers have to further
+chain. It's also the point where all subsequent processors have to further
 process the `Substation::Response` returned from invoking the action.
+Therefore, the pivot processor is the last processor that expects a
+`Substation::Request` as parameter to its `#call` method.
 
-The contract for the pivot handler therefore is:
+The contract for the pivot processor therefore is:
 
 1. `#call(Substation::Request) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Response`
+3. `#success?(Substation::Response) => Boolean`
 
-By including the `Substation::Chain::Pivot` module into your handler
+By including the `Substation::Processor::Pivot` module into your handler
 class, you'll get the following for free:
 
 ```ruby
+def initialize(name, handler, failure_chain)
+  @name, @handler, @failure_chain = name, handler, failure_chain
+end
+
 def result(response)
   response
 end
+
+def success?(response)
+  response.success?
+end
+
+def with_failure_chain(chain)
+  self.class.new(name, handler, chain)
+end
 ```
 
-This reflects the fact that a pivot handler (since it's the one actually
-producing the "raw" response, returns it unaltered.
+This reflects the fact that a pivot processor (since it's the one actually
+producing the "raw" response, returns it unaltered).
+
+The pivot processor is shipped with `substation` and is implemented by
+`Substation::Processor::Evaluator::Pivot`.
 
-### Outgoing handlers
+### Outgoing processors
 
 All steps required *after* processing the action will potentially
 produce a new, altered, `Substation::Response` instance to be returned.
 Therefore the object passed to `#call` must be an instance of
-`Substation::Response`. Since subsequent outgoing handlers might further
+`Substation::Response`. Since subsequent outgoing processors might further
 process the response, `#result` must be implemented so that it returns a
-`Substation::Response` object that can be passed on to the next handler.
+`Substation::Response` object that can be passed on to the next
+processor.
 
-The contract for outgoing handlers therefore is:
+The contract for outgoing processors therefore is:
 
 1. `#call(Substation::Response) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Response`
+3. `#success?(Substation::Response) => true`
 
-By including the `Substation::Chain::Outgoing` module into your handler
-class, you'll get the following for free:
+By including the `Substation::Processor::Outgoing` module into your
+processor class, you'll get the following for free:
 
 ```ruby
+def initialize(name, handler)
+  @name, @handler = name, handler
+end
+
 def result(response)
   response
 end
+
+def success?(response)
+  true
+end
+
+private
+
+def respond_with(response, output)
+  response.class.new(response.request, output)
+end
 ```
 
-This shows that an outgoing handler's `#call` can do anything with
+This shows that an outgoing processor's `#call` can do anything with
 the `Substation::Response#output` it received, as long as it makes
 sure to return a new response with the new output properly set.
 
+Currently, `substation` provides the following outgoing processors out
+of the box:
+
+* `Substation::Processor::Wrapper` wraps `response.output` in a new handler instance
+* `Substation::Processor::Transformer` transforms `response.output` using a new handler instance
+
+### Handlers
+
+You might have noticed the `handler` param passed to any processor's
+`#initialize` method. Handlers are the actual objects performing your
+application logic. Processors use these handlers to produce the data
+they're supposed to "pipe through the chain".
+
+The interface your handlers must implement should be familiar by now.
+
+All handlers to be used with incoming processors must accept an instance
+of `Substation::Request` as parameter to `#call`. Handlers to be used
+with `Substation::Processor::Evaluator` subclasses must furthermore
+return an object that responds to `#success?` and `#output`.
+
+Note how the interface required for evaluator handler return values
+matches the interface a `Substation::Response` exposes. This means that
+the pivot processor can be (and is) implemented using the builtin
+`Substation::Processor::Evaluator::Request` processor. The handler you
+pass to the pivot processor is the object that actually implements your
+application usecase, the action, and it's response gets evaluated.
+
+All handlers to be used with outgoing processors must accept an instance
+of `Substation::Response` as parameter to `#call`. They can do whatever
+they want with the passed in response, but they must make sure to return
+another instance of `Substation::Response`. To help with this, outgoing
+processors provide the `#respond_with(response, data)` method that
+you'll typically call to return the response value for `#call`.
+
 ### Example
 
 [substation-demo](https://github.com/snusnu/substation-demo) implements a
 simple web application using `Substation::Chain`.
 
-The demo implements a few of the above mentioned *incoming handlers*
+The demo uses a few of the above mentioned *incoming processors*
 for
 
 * [Sanitization](https://github.com/snusnu/substation-demo/blob/master/demo/web/sanitizers.rb) using [ducktrap](https://github.com/mbj/ducktrap)
 * [Validation](https://github.com/snusnu/substation-demo/blob/master/demo/validators.rb) using [vanguard](https://github.com/mbj/vanguard)
 
-and some simple *outgoing handlers* for
+and some simple *outgoing processors* for
 
 * Wrapping response output in a
 [presenter](https://github.com/snusnu/substation-demo/blob/master/demo/web/presenters.rb)
 * [Serializing](https://github.com/snusnu/substation-demo/blob/master/demo/web/serializers.rb) response output to JSON
 
-The
-[handlers](https://github.com/snusnu/substation-demo/blob/master/demo/web/processors.rb)
-are called *processors* in that app, and encapsulate the actual handler
-performing the job. That's a common pattern, because you typically will
-have to adapt to the interface your actual handlers provide.
-
 Have a look at the base
 [actions](https://github.com/snusnu/substation-demo/blob/master/demo/web/actions.rb)
 that are then used to either produce

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
-threshold: 6
-total_score: 82
+threshold: 9
+total_score: 134

data/config/mutant.yml

@@ -1,3 +1,4 @@
 ---
 name: substation
 namespace: Substation
+strategy: --rspec-dm2

data/config/reek.yml

@@ -25,9 +25,10 @@ FeatureEnvy:
   enabled: true
   exclude:
   - Substation::Chain#call # loops over instance state
-  - Substation::Chain::Incoming#result # defined in a module
-  - Substation::Chain::Outgoing#respond_with #defined in a module
+  - Substation::Processor::Outgoing#respond_with #defined in a module
   - Substation::Processor::Evaluator#call # method object
+  - Substation::Processor::Evaluator#on_success # method object
+  - Substation::Processor#success? # in a module to be included in a method object
 IrresponsibleModule:
   enabled: true
   exclude: []
@@ -36,6 +37,8 @@ LongParameterList:
   exclude:
   - Substation::Dispatcher#call
   - Substation::Chain::DSL::Builder#define_dsl_method
+  - Substation::Chain#self.failure_response
+  - Substation::Chain#on_failure
   max_params: 2
 LongYieldList:
   enabled: true
@@ -58,10 +61,12 @@ TooManyInstanceVariables:
   enabled: true
   exclude:
   - Substation::Response
+  - Substation::Processor::Evaluator
   max_instance_variables: 3
 TooManyMethods:
   enabled: true
-  exclude: []
+  exclude:
+  - Substation::Chain::DSL
   max_methods: 4
 TooManyStatements:
   enabled: true
@@ -110,6 +115,7 @@ UnusedParameters:
 UtilityFunction:
   enabled: true
   exclude:
-  - Substation::Chain::Incoming#result # defined in a module
-  - Substation::Chain::Outgoing#respond_with # defined in a module
+  - Substation::Processor::Outgoing#respond_with # defined in a module
+  - Substation::Processor::Evaluator#on_success # inside a method object
+  - Substation::Processor#success? # in a module to be included in a method object
   max_helper_calls: 0