substation 0.0.9 → 0.0.10.beta2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 674a347348ff4f36dbca255925b70c9ea794c95d
+  data.tar.gz: a28efb6f4038ee99e8f820f2dcaee74506e4182b
+SHA512:
+  metadata.gz: 5a9dcabb1d4a225cee6a4579587387c3829747fcaf77319ae2a0c2a2863eae6558c4d825e6c48f59ecc7d2a860831ae8dcadcda053d947f431b9b73bbaa0c593
+  data.tar.gz: bbd1fca2660e54697b3d1d8f5a69e4a527cf5a129a0995e589cf99966d7c54f9a10b30313e3f51b91a60b4ea38443dcb0a5f3e68253e028ffcda4804def5d107

data/.travis.yml

@@ -12,4 +12,3 @@ rvm:
 matrix:
   allow_failures:
     - rvm: ruby-head
-    - rvm: rbx-19mode

data/Changelog.md

@@ -1,98 +1,40 @@
-# v0.0.10 (not yet released)
+# v0.0.9 (not yet released)
 
-*
+* [feature] Support definining failure chains
 
-[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 }
+        env = Substation::Environment.build do
+          register :evaluate, Substation::Processor::Evaluator
+          register :wrap,     Substation::Processor::Wrapper
+        end
 
-            SOME_ACTION = Demo::ENV.chain do
-              validate Vanguard::Validator, VALIDATION_ERROR
-              call     Some::Action,        APPLICATION_ERROR
-            end
+        class Error
+          attr_reader :data
+          def initialize(data)
+            @data = data
           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
+          class ValidationError < self
           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 }
+        chain = env.chain do
+          evaluate Vanguard::Validator do
+            wrap Errors::ValidationError
           end
+          call Some::Action
+          wrap Some::Presenter
+        end
 
-          module Web
+        env             = Object.new
+        invalid_request = Substation::Requet.new(env, :invalid)
+        response        = chain.call(invalid_request)
 
-            INTERNAL_ERROR = Demo::ENV.chain(App::INTERNAL_ERROR) do
-              render Renderer::InternalError
-            end
+        response.data.instance_of?(Errors::ValidationError)
+        # => true
 
-            # 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
+        response.data.data # => the actual vanguard violation set
 
-[Compare v0.0.8..v0.0.9](https://github.com/snusnu/substation/compare/v0.0.8...v0.0.9)
+[Compare v0.0.8..master](https://github.com/snusnu/substation/compare/v0.0.8...master)
 
 # v0.0.8 2013-06-19
 

data/Gemfile.devtools

@@ -2,12 +2,12 @@
 
 group :development do
   gem 'rake',  '~> 10.1.0'
-  gem 'rspec', '~> 2.13.0'
-  gem 'yard',  '~> 0.8.6.2'
+  gem 'rspec', '~> 2.14.1'
+  gem 'yard',  '~> 0.8.7'
 end
 
 group :yard do
-  gem 'kramdown', '~> 1.1.0'
+  gem 'kramdown', '~> 1.2.0'
 end
 
 group :guard do
@@ -15,40 +15,33 @@ group :guard do
   gem 'guard-bundler', '~> 1.0.0'
   gem 'guard-rspec',   '~> 3.0.2'
   gem 'guard-rubocop', '~> 0.2.0'
+  gem 'guard-mutant',  '~> 0.0.1'
 
   # file system change event handling
-  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
+  gem 'listen',     '~> 1.3.0'
+  gem 'rb-fchange', '~> 0.0.6', require: false
+  gem 'rb-fsevent', '~> 0.9.3', require: false
+  gem 'rb-inotify', '~> 0.9.0', require: false
 
   # notification handling
-  gem 'libnotify',               '~> 0.8.0', :require => false
-  gem 'rb-notifu',               '~> 0.0.4', :require => false
-  gem 'terminal-notifier-guard', '~> 1.5.3', :require => false
+  gem 'libnotify',               '~> 0.8.0', 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.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 'flay',      '~> 2.4.0'
+  gem 'flog',      '~> 4.1.1'
+  gem 'reek',      '~> 1.3.2'
+  gem 'rubocop',   '~> 0.13.0'
   gem 'simplecov', '~> 0.7.1'
-  gem 'yardstick', '~> 0.9.6'
+  gem 'yardstick', '~> 0.9.7', git: 'https://github.com/dkubb/yardstick.git'
 
   platforms :ruby_19, :ruby_20 do
-    gem 'mutant',          '~> 0.3.0.beta13'
+    gem 'mutant', git: 'https://github.com/mbj/mutant.git'
     gem 'yard-spellcheck', '~> 0.1.5'
   end
-
-  platforms :ruby_19 do
-    gem 'json', '~> 1.8.0'
-  end
-
-  platforms :rbx do
-    gem 'pelusa', '~> 0.2.2'
-  end
 end
 
 group :benchmarks do

data/README.md

@@ -22,8 +22,7 @@ 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. Furthermore, `request.name` will contain the action
-name the `Substation::Dispatcher` used when dispatching to an action.
+abstraction object.
 
 The contract further specifies that every action must return an instance
 of either `Substation::Response::Success` or
@@ -510,9 +509,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
@@ -542,198 +541,129 @@ 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`. To construct a chain, you
-need to pass an enumerable of processors to `Substation::Chain#initialize`.
-Processors must support three methods:
+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:
 
 1. `#call(<Substation::Request, Substation::Response>) => Substation::Response`
 2. `#result(Substation::Response) => <Substation::Request, Substation::Response>`
-3. `#success?(Substation::Response) => Boolean`
 
-### Incoming processors
+### Incoming handlers
 
 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 `Processor#success?`
+would halt and return that response in case calling its `#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 processors therefore is:
+The contract for incoming handlers therefore is:
 
 1. `#call(Substation::Request) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Request`
-3. `#success?(Substation::Response) => Boolean`
 
-By including the `Substation::Processor::Incoming` module into your
-processor class, you'll get the following for free:
+By including the `Substation::Chain::Incoming` 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.to_request
-end
-
-def success?(response)
-  response.success?
-end
-
-def with_failure_chain(chain)
-  self.class.new(name, handler, chain)
+  Request.new(response.env, response.output)
 end
 ```
 
-This shows that an incoming processor can alter the incoming request in any
+This shows that an incoming handler 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`.
 
-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
+### The pivot handler
 
 Pivot is just another fancy name for the action in the context of a
-chain. It's also the point where all subsequent processors have to further
+chain. It's also the point where all subsequent handlers 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 processor therefore is:
+The contract for the pivot handler therefore is:
 
 1. `#call(Substation::Request) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Response`
-3. `#success?(Substation::Response) => Boolean`
 
-By including the `Substation::Processor::Pivot` module into your handler
+By including the `Substation::Chain::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 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`.
+This reflects the fact that a pivot handler (since it's the one actually
+producing the "raw" response, returns it unaltered.
 
-### Outgoing processors
+### Outgoing handlers
 
 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 processors might further
+`Substation::Response`. Since subsequent outgoing handlers 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
-processor.
+`Substation::Response` object that can be passed on to the next handler.
 
-The contract for outgoing processors therefore is:
+The contract for outgoing handlers therefore is:
 
 1. `#call(Substation::Response) => Substation::Response`
 2. `#result(Substation::Response) => Substation::Response`
-3. `#success?(Substation::Response) => true`
 
-By including the `Substation::Processor::Outgoing` module into your
-processor class, you'll get the following for free:
+By including the `Substation::Chain::Outgoing` module into your handler
+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 processor's `#call` can do anything with
+This shows that an outgoing handler'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 uses a few of the above mentioned *incoming processors*
+The demo implements a few of the above mentioned *incoming handlers*
 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 processors* for
+and some simple *outgoing handlers* 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