substation 0.0.1

data/.gitignore

@@ -0,0 +1,37 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## Rubinius
+*.rbc
+.rbx
+
+## PROJECT::GENERAL
+*.gem
+coverage
+profiling
+turbulence
+rdoc
+pkg
+tmp
+doc
+log
+.yardoc
+measurements
+
+## BUNDLER
+.bundle
+Gemfile.lock
+
+## PROJECT::SPECIFIC

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--profile
+--order random
+--format progress

data/.rvmrc

@@ -0,0 +1 @@
+rvm use @$(basename `pwd`) --create

data/.travis.yml

@@ -0,0 +1,16 @@
+language: ruby
+before_install: gem install bundler
+bundler_args: --without yard guard benchmarks
+script: "bundle exec rake ci"
+rvm:
+  - 1.9.3
+  - 1.9.2
+  - 1.8.7
+  - ree
+  - ruby-head
+  - 2.0.0
+  - jruby-19mode
+  - jruby-18mode
+  - jruby-head
+  - rbx-19mode
+  - rbx-18mode

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'devtools', :git => 'https://github.com/datamapper/devtools.git'
+  eval File.read('Gemfile.devtools')
+end

data/Gemfile.devtools

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+group :development do
+  gem 'rake',  '~> 10.0.4'
+  gem 'rspec', '~> 2.13.0'
+  gem 'yard',  '~> 0.8.6.1'
+end
+
+group :yard do
+  gem 'kramdown', '~> 1.0.1'
+end
+
+group :guard do
+  gem 'guard',         '~> 1.8.0'
+  gem 'guard-bundler', '~> 1.0.0'
+  gem 'guard-rspec',   '~> 2.5.4'
+
+  # file system change event handling
+  gem 'listen',     '~> 1.0.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
+
+  # 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
+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 'yard-spellcheck', '~> 0.1.5'
+  end
+
+  platforms :mri_19, :rbx do
+    gem 'mutant', '~> 0.2.20'
+  end
+
+  platforms :rbx do
+    gem 'pelusa', '~> 0.2.2'
+  end
+end
+
+group :benchmarks do
+  gem 'rbench', '~> 0.2.3'
+end
+
+platform :jruby do
+  group :jruby do
+    gem 'jruby-openssl', '~> 0.8.5'
+  end
+end

data/Guardfile

@@ -0,0 +1,18 @@
+# encoding: utf-8
+
+guard :bundler do
+  watch('Gemfile')
+end
+
+guard :rspec, :all_on_start => false, :all_after_pass => false 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' }
+
+  # run unit specs if associated lib code is modified
+  watch(%r{\Alib/(.+)\.rb\z})                                         { |m| Dir["spec/unit/#{m[1]}"] }
+  watch("lib/#{File.basename(File.expand_path('../', __FILE__))}.rb") { 'spec/unit'                       }
+
+  # run a spec if it is modified
+  watch(%r{\Aspec/(?:unit|integration)/.+_spec\.rb\z})
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Martin Gamsjaeger (snusnu)
+
+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,322 @@
+# substation
+
+[![Gem Version](https://badge.fury.io/rb/substation.png)][gem]
+[![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]
+
+[gem]: https://rubygems.org/gems/substation
+[travis]: https://travis-ci.org/snusnu/substation
+[gemnasium]: https://gemnasium.com/snusnu/substation
+[codeclimate]: https://codeclimate.com/github/snusnu/substation
+
+`substation` can be thought of as a domain level request router. It assumes
+that every usecase in your application has a name and is implemented in a dedicated
+class that will be referred to as an *action* for the purposes of this
+document. The only protocol such actions must support is `#call(request)`.
+
+The contract for actions specifies that when invoked, actions can
+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 or a storage engine abstraction.
+
+The contract further specifies that every action must return an instance
+of either `Substation::Response::Success` or
+`Substation::Response::Failure`. Again, arbitrary data can be associated
+with any kind of response, and will be available in `response.data`. In
+addition to that, `response.success?` is available and will indicate
+wether invoking the action was successful or not.
+
+`Substation::Dispatcher` stores a mapping of action names to the actual
+objects implementing the action. Clients can use
+`Substation::Dispatcher#call(name, input, env)` to dispatch to any
+registered action. For example, a web application could map an http
+route to a specific action name and pass relevant http params on to the
+action.
+
+## Actions
+
+Here's an example of a valid action.
+
+```ruby
+module App
+  class SomeUseCase
+
+    # Perform the usecase
+    #
+    # @param [Substation::Request] request
+    #   the request passed to the registered action
+    #
+    # @return [Substation::Response]
+    #   the response returned when calling the action
+    #
+    # @api private
+    def self.call(request)
+      data = perform_work
+      if data
+        request.success(data)
+      else
+        request.error("Something went wrong")
+      end
+    end
+  end
+end
+```
+
+It is up to you how to implement the action. Another way of writing an
+action could involve providing an application specific baseclass for all
+your actions, which provides access to methods you frequently use within
+any specific action.
+
+```ruby
+module App
+
+  # Base class for all actions
+  #
+  # @abstract
+  class Action
+
+    # Perform the usecase
+    #
+    # @param [Substation::Request] request
+    #   the request passed to the registered action
+    #
+    # @return [Substation::Response]
+    #   the response returned when calling the action
+    #
+    # @api private
+    def self.call(request)
+      new(request).call
+    end
+
+    def initialize(request)
+      @request = request
+      @env     = @request.env
+    end
+
+    def call
+      raise NotImplementedError, "#{self.class}##{__method__} must be implemented"
+    end
+
+    private
+
+    def success(data)
+      @request.success(data)
+    end
+
+    def error(data)
+      @request.error(data)
+    end
+  end
+
+  class SomeUseCase < Action
+
+    def call
+      data = perform_work
+      if data
+        success(data)
+      else
+        error("Something went wrong")
+      end
+    end
+  end
+end
+```
+
+## Observers
+
+Sometimes, additional code needs to run wether your action was
+successful or not. Observers provide you with a place for that code.
+Again, the contract for observers is very simple: all they need to
+implement is `call(response)` and `substation` will make sure that the
+`response` param will be the response returned from invoking your
+action.
+
+It is therefore possible to dispatch to different observers based on
+wether the action was successful or not by utilizing
+`response.success?`. By accepting a `response` object, observers also
+have access to the original `input` and `env` the action was invoked
+with, as well as the `output` that the action produced. These objects
+are made available via `response.input`, `response.env` and
+`response.output`.
+
+Here's an example of a simple observer:
+
+```ruby
+module App
+  class SomeUseCaseObserver
+    def self.call(response)
+      # your code here
+    end
+  end
+end
+```
+
+A more involved observer could dispatch based on the success of the
+invoked action:
+
+```ruby
+module App
+  class SomeUseCaseObserver
+    def self.call(response)
+      klass = response.success? ? Success : Failure
+      klass.new(response).call
+    end
+
+    def initialize(response)
+      @response = response
+    end
+
+    class Success < self
+      def call
+        # your code here
+      end
+    end
+
+    class Failure < self
+      def call
+        # your code here
+      end
+    end
+  end
+end
+```
+
+## Configuration
+
+Since an application will most likely involve more than one usecase, we
+need a way to inform `substation` about all the usecases it should handle.
+For this purpose, we can instantiate a `Substation::Dispatcher` and hand
+it a configuration hash that describes the various actions by giving
+them a name, a class that's responsible for implementing the actual
+usecase, and a list of `0..n` observers that should be invoked depending
+on the action response.
+
+An example configuration for an action without any observers:
+
+```ruby
+dispatcher = Substation::Dispatcher.coerce({
+  'some_use_case' => { 'action' => 'App::SomeUseCase' }
+})
+```
+
+An example configuration for an action with one observer:
+
+```ruby
+dispatcher = Substation::Dispatcher.coerce({
+  'some_use_case' => {
+    'action'   => 'App::SomeUseCase',
+    'observer' => 'App::SomeUseCaseObserver'
+  }
+})
+```
+
+An example configuration for an action with multiple observers:
+
+```ruby
+dispatcher = Substation::Dispatcher.coerce({
+  'some_use_case' => {
+    'action'   => 'App::SomeUseCase',
+    'observer' => [
+      'App::SomeUseCaseObserver',
+      'App::AnotherObserver'
+    ]
+  }
+})
+```
+
+The above configuration examples are tailored towards being read from a
+(yaml) config file and therefore accept strings as keys and values. It's
+also possible to use symbols as keys and values. Values correspond to
+action or observer "handlers" and can also be given as either constants
+or procs. In any case, handlers must respond to `call(object)`.
+
+An example configuration using symbol keys and constants for handlers:
+
+```ruby
+dispatcher = Substation::Dispatcher.coerce({
+  :some_use_case => {
+    :action   => App::SomeUseCase,
+    :observer => App::SomeUseCaseObserver
+  }
+})
+```
+
+An example configuration using symbol keys and procs for handlers:
+
+```ruby
+dispatcher = Substation::Dispatcher.coerce({
+  :some_use_case => {
+    :action   => Proc.new { |request| request.success(:foo) },
+    :observer => Proc.new { |response| do_something }
+  }
+})
+```
+
+
+## Application environments
+
+In order to provide your actions with objects typically needed during
+the course of performing a usecase (like a logger or a storage engine
+abstraction), you can encapsulate these objects within an application
+specific environment object, and send that along to every action.
+
+Here's a simple example with an environment that encapsulates a logger,
+an artificial storage abstraction object and the dispatcher itself.
+
+The example builds on top of the application specific action baseclass
+shown above:
+
+```ruby
+module App
+  class Environment
+    attr_reader :storage
+    attr_reader :dispatcher
+    attr_reader :logger
+
+    def initialize(storage, dispatcher, logger)
+      @storage    = storage
+      @dispatcher = dispatcher
+      @logger     = logger
+    end
+  end
+
+  class Action
+    # ...
+    # code from above example
+    # ...
+
+    def db
+      @env.storage
+    end
+  end
+
+  class SomeUseCase < Action
+
+    def initialize(request)
+      super
+      @person = request.input
+    end
+
+    def call
+      if person = db.save_person(@person)
+        success(person)
+      else
+        error("Something went wrong")
+      end
+    end
+  end
+end
+
+dispatcher = Substation::Dispatcher.coerce({
+  'some_use_case' => { 'action' => 'App::SomeUseCase' }
+})
+
+storage = App::Storage.new # some storage abstraction
+env     = App::Environment.new(storage, dispatcher, Logger.new($stdout))
+
+# :some_input is no person, db.save_person will fail
+response = dispatcher.call(:some_use_case, :some_input, env)
+response.success? # => false
+```

data/Rakefile

@@ -0,0 +1,6 @@
+# encoding: utf-8
+
+require 'rake'
+require 'devtools'
+
+Devtools.init_rake_tasks

data/config/devtools.yml

@@ -0,0 +1,2 @@
+---
+unit_test_timeout: 0.3

data/config/flay.yml

@@ -0,0 +1,3 @@
+---
+threshold: 6
+total_score: 51

data/config/flog.yml

@@ -0,0 +1,2 @@
+---
+threshold: 10.9

data/config/mutant.yml

@@ -0,0 +1,3 @@
+---
+name: substation
+namespace: Substation

data/config/reek.yml

@@ -0,0 +1,103 @@
+---
+Attribute:
+  enabled: false
+  exclude: []
+BooleanParameter:
+  enabled: true
+  exclude: []
+ClassVariable:
+  enabled: true
+  exclude: []
+ControlParameter:
+  enabled: true
+  exclude: []
+DataClump:
+  enabled: true
+  exclude: []
+  max_copies: 2
+  min_clump_size: 2
+DuplicateMethodCall:
+  enabled: true
+  exclude: []
+  max_calls: 1
+  allow_calls: []
+FeatureEnvy:
+  enabled: true
+  exclude: []
+IrresponsibleModule:
+  enabled: true
+  exclude: []
+LongParameterList:
+  enabled: true
+  exclude:
+  - Substation::Dispatcher#call
+  max_params: 2
+LongYieldList:
+  enabled: true
+  exclude: []
+  max_params: 2
+NestedIterators:
+  enabled: true
+  exclude: []
+  max_allowed_nesting: 1
+  ignore_iterators: []
+NilCheck:
+  enabled: true
+  exclude: []
+RepeatedConditional:
+  enabled: true
+  exclude: []
+  max_ifs: 1
+TooManyInstanceVariables:
+  enabled: true
+  exclude:
+  - Substation::Response
+  max_instance_variables: 3
+TooManyMethods:
+  enabled: true
+  exclude: []
+  max_methods: 4
+TooManyStatements:
+  enabled: true
+  exclude:
+  - Substation::Utils#self.const_get
+  - Substation::Utils#self.symbolize_keys
+  max_statements: 3
+UncommunicativeMethodName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^[a-z]$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  accept: []
+UncommunicativeModuleName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  accept: []
+UncommunicativeParameterName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  accept: []
+UncommunicativeVariableName:
+  enabled: true
+  exclude: []
+  reject:
+  - !ruby/regexp /^.$/
+  - !ruby/regexp /[0-9]$/
+  - !ruby/regexp /[A-Z]/
+  accept: []
+UnusedParameters:
+  enabled: true
+  exclude: []
+UtilityFunction:
+  enabled: true
+  exclude: []
+  max_helper_calls: 0

data/config/yardstick.yml

@@ -0,0 +1,2 @@
+---
+threshold: 100.0