substation 0.0.10.beta2 → 0.0.10

data/.travis.yml

@@ -6,9 +6,13 @@ rvm:
   - 1.9.3
   - 2.0.0
   - ruby-head
-  - jruby-19mode
-  - jruby-head
-  - rbx-19mode
+  - rbx
 matrix:
+  include:
+    - rvm: jruby-19mode
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
+    - rvm: jruby-head
+      env: JRUBY_OPTS="$JRUBY_OPTS --debug"
   allow_failures:
     - rvm: ruby-head
+    - rvm: jruby-head

data/Changelog.md

@@ -1,40 +1,115 @@
-# v0.0.9 (not yet released)
+# v0.0.10 2014-08-11
 
-* [feature] Support definining failure chains
+* This release is full of breaking changes and new features. The README is still out of
+  date too, but I need to get this out of the door. For a complete list of changes, have
+  a look at the diffs linked at the end of this section.
 
-        env = Substation::Environment.build do
-          register :evaluate, Substation::Processor::Evaluator
-          register :wrap,     Substation::Processor::Wrapper
-        end
+* Add the possibility to nest chains inside others
+* Support decomposing/composing state before/after it is sent to handlers
+* Make all handlers observable
+* Support building on top of existing environments
+* Rename Chain#{failure_chain => exception_chain}
+* Store a chain's name in its definition
+* Expose Dispatcher#include?(name)
+* Make Chain::DSL accept an optional block
+
+  This allows for easy and syntactically nice
+  failure chain replacement when its desired
+  to replace/augment any of the failure chains
+  registered for processors within the chain to
+  merge.
+
+[Compare v0.0.9..v0.0.10](https://github.com/snusnu/substation/compare/v0.0.9...v0.0.10)
+
+# 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
 
-        class Error
-          attr_reader :data
-          def initialize(data)
-            @data = data
+            ValidationError  = Class.new(self)
+            ApplicationError = Class.new(self)
+            InternalError    = Class.new(self)
           end
 
-          class ValidationError < self
+          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
-        end
 
-        chain = env.chain do
-          evaluate Vanguard::Validator do
-            wrap Errors::ValidationError
+          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
-          call Some::Action
-          wrap Some::Presenter
         end
 
-        env             = Object.new
-        invalid_request = Substation::Requet.new(env, :invalid)
-        response        = chain.call(invalid_request)
+* [feature] Support (re)defining chain specific failure chains in case of uncaught exceptions.
+
+        module Demo
 
-        response.data.instance_of?(Errors::ValidationError)
-        # => true
+          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
 
-        response.data.data # => the actual vanguard violation set
+            # 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..master](https://github.com/snusnu/substation/compare/v0.0.8...master)
+[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

@@ -2,7 +2,14 @@ source 'http://rubygems.org'
 
 gemspec
 
+group :test do
+  gem 'multi_json', '~> 1.8.0'
+  gem 'ducktrap',   '~> 0.0.2', :git => 'https://github.com/mbj/ducktrap', :branch => 'master'
+  gem 'vanguard',   '~> 0.0.4', :git => 'https://github.com/mbj/vanguard', :branch => 'master'
+  gem 'anima',      '~> 0.2.0'
+end
+
 group :development do
-  gem 'devtools', :git => 'https://github.com/rom-rb/devtools.git'
+  gem 'devtools', :git => 'https://github.com/rom-rb/devtools.git', :branch => 'master'
   eval File.read('Gemfile.devtools')
 end

data/Gemfile.devtools

@@ -1,47 +1,63 @@
 # encoding: utf-8
 
 group :development do
-  gem 'rake',  '~> 10.1.0'
-  gem 'rspec', '~> 2.14.1'
-  gem 'yard',  '~> 0.8.7'
+  gem 'rake',       '~> 10.3.2'
+  gem 'rspec',      '~> 3.0.0'
+  gem 'rspec-its',  '~> 1.0.1'
+  gem 'yard',       '~> 0.8.7.4'
+
+  platform :rbx do
+    gem 'rubysl-singleton', '~> 2.0.0'
+  end
 end
 
 group :yard do
-  gem 'kramdown', '~> 1.2.0'
+  gem 'kramdown', '~> 1.3.3'
 end
 
 group :guard do
-  gem 'guard',         '~> 1.8.1'
-  gem 'guard-bundler', '~> 1.0.0'
-  gem 'guard-rspec',   '~> 3.0.2'
-  gem 'guard-rubocop', '~> 0.2.0'
-  gem 'guard-mutant',  '~> 0.0.1'
+  gem 'guard',         '~> 2.6.1'
+  gem 'guard-bundler', '~> 2.0.0'
+  gem 'guard-rspec',   '~> 4.2.9'
+  gem 'guard-rubocop', '~> 1.1.0'
 
   # file system change event handling
-  gem 'listen',     '~> 1.3.0'
+  gem 'listen',     '~> 2.7.7'
   gem 'rb-fchange', '~> 0.0.6', require: false
-  gem 'rb-fsevent', '~> 0.9.3', require: false
-  gem 'rb-inotify', '~> 0.9.0', require: false
+  gem 'rb-fsevent', '~> 0.9.4', require: false
+  gem 'rb-inotify', '~> 0.9.5', require: false
 
   # notification handling
-  gem 'libnotify',               '~> 0.8.0', require: false
+  gem 'libnotify',               '~> 0.8.3', require: false
   gem 'rb-notifu',               '~> 0.0.4', require: false
   gem 'terminal-notifier-guard', '~> 1.5.3', require: false
 end
 
 group :metrics do
-  gem 'coveralls', '~> 0.6.7'
-  gem 'flay',      '~> 2.4.0'
-  gem 'flog',      '~> 4.1.1'
-  gem 'reek',      '~> 1.3.2'
-  gem 'rubocop',   '~> 0.13.0'
+  gem 'coveralls', '~> 0.7.0'
+  gem 'flay',      '~> 2.5.0'
+  gem 'flog',      '~> 4.2.1'
+  gem 'reek',      '~> 1.3.7'
+  gem 'rubocop',   '~> 0.23.0'
   gem 'simplecov', '~> 0.7.1'
-  gem 'yardstick', '~> 0.9.7', git: 'https://github.com/dkubb/yardstick.git'
+  gem 'yardstick', '~> 0.9.9'
+
+  platforms :mri do
+    gem 'mutant',       '~> 0.5.23'
+    gem 'mutant-rspec', '~> 0.5.21'
+  end
 
   platforms :ruby_19, :ruby_20 do
-    gem 'mutant', git: 'https://github.com/mbj/mutant.git'
     gem 'yard-spellcheck', '~> 0.1.5'
   end
+
+  platform :rbx do
+    gem 'json',               '~> 1.8.1'
+    gem 'racc',               '~> 1.4.11'
+    gem 'rubysl-logger',      '~> 2.0.0'
+    gem 'rubysl-open-uri',    '~> 2.0.0'
+    gem 'rubysl-prettyprint', '~> 2.0.3'
+  end
 end
 
 group :benchmarks do
@@ -50,6 +66,6 @@ end
 
 platform :jruby do
   group :jruby do
-    gem 'jruby-openssl', '~> 0.8.5'
+    gem 'jruby-openssl', '~> 0.9.4'
   end
 end

data/Guardfile

@@ -4,7 +4,7 @@ guard :bundler do
   watch('Gemfile')
 end
 
-guard :rspec, :all_on_start => false, :all_after_pass => false do
+guard :rspec, :all_on_start => false, :all_after_pass => false, :cmd => 'bundle exec rspec --fail-fast --seed 1' do
   # run all specs if the spec_helper or supporting files files are modified
   watch('spec/spec_helper.rb')                      { 'spec/unit' }
   watch(%r{\Aspec/(?:lib|support|shared)/.+\.rb\z}) { 'spec/unit' }

data/README.md

@@ -4,6 +4,7 @@
 [![Build Status](https://secure.travis-ci.org/snusnu/substation.png?branch=master)][travis]
 [![Dependency Status](https://gemnasium.com/snusnu/substation.png)][gemnasium]
 [![Code Climate](https://codeclimate.com/github/snusnu/substation.png)][codeclimate]
+[![Inline docs](http://inch-ci.org/github/snusnu/substation.png)](http://inch-ci.org/github/snusnu/substation)
 [![Coverage Status](https://coveralls.io/repos/snusnu/substation/badge.png?branch=master)][coveralls]
 
 [gem]: https://rubygems.org/gems/substation
@@ -22,7 +23,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 +511,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 +543,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
@@ -679,6 +750,7 @@ Finally it's all hooked up behind a few
 
 * [snusnu](https://github.com/snusnu)
 * [mbj](https://github.com/mbj)
+* [indrekj](https://github.com/indrekj)
 
 ## Contributing