viaduct 0.0.3 → 0.1.0

data/.gitignore

@@ -1 +1,2 @@
 Gemfile.lock
+tmp/

data/Gemfile

@@ -1,3 +1,9 @@
 source 'https://rubygems.org'
 
 gemspec
+
+group :test, :development do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'rb-fsevent', '~> 0.9'
+end

data/Guardfile

@@ -1,4 +1,4 @@
-guard 'rspec', :version => 2 do
+guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec" }

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2010-2012Mitchell Hashimoto and John Bender
+Copyright (c) 2010-2012 Mitchell Hashimoto and John Bender
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+THE SOFTWARE.

data/README.md

@@ -1,10 +1,12 @@
 # Viaduct
 
-* Source: [https://github.com/slack/viaduct](https://github.com/slack/viaduct)
+Use middleware in your application. Catch exceptions and walk back up the stack!
+
+Mitchell also created the [middlware](https://github.com/mitchellh/middleware) gem, but it did not contain the warden code which is what interested me the most. Thus, viaduct.
 
-Use the middleware pattern in your application.
+* Source: [https://github.com/slack/viaduct](https://github.com/slack/viaduct)
 
-Extracted from the very excellent [Vagrant](http://vagrantup.com) Mitchell Hashimoto and John Bender
+Extracted from Mitchell Hashimoto and John Bender's very excellent [Vagrant](http://vagrantup.com).
 
 ## Installation
 
@@ -20,21 +22,99 @@ Or install it yourself as:
 
     $ gem install viaduct
 
+## Usage
+
+If you've spent any time using [rack](http://rack.github.io/) Viaduct will be very familiar.
+
+Simply:
+
+1. Define middlware classes that respond to `new` and `call`
+2. Create your middleware stack with `Viaduct::Builder`
+3. Run your stack with `Viaduct::Runner`
+
+For a few examples see the [integration example spec](spec/integration_spec.rb).
+
+Let's define two middlewares, one that appends text to the environment and one that removes an element.
+
+```ruby
+class Add
+  def initialize(app, env)
+    @app, @env = app, env
+  end
+
+  def call(env)
+    env[:data] << "adding"
+    @app.call(env)
+  end
+end
+
+class Remove
+  def initialize(app, env)
+    @app, @env = app, env
+  end
+
+  def call(env)
+    env[:data].shift
+    @app.call(env)
+  end
+end
+```
+
+Organize these into a sequence:
+
+```ruby
+stack = Viaduct::Builder.new do
+  use Add
+  use Remove
+  use Add
+end
+```
+
+Then execute that sequence by calling `Viaduct::Runner.run`:
+
+```ruby
+env = { data: [] }
+result = Viaduct::Runner.run(stack, env})
+#=> { data: ['adding'] }
+```
+
+### Handling exceptions
+
+`Viaduct::Runner` is responsible for the execution of your sequence. The first argument to `run` should be either a sequence from `Viaduct::Builder` or a ruby class that responds to `call`.
+
+Runner will hand the `env` hash to each of your middlwares, handling any excpetions. In the event that any down-stream middlware raises, Viaduct will walk back up the stack calling `recover` on each middleware see [handling exceptions example](spec/integration_spec.rb).
+
+### Debugging
+
+If you pass in an instance of `Logger` to `Viaduct::Runner` (or something that looks like a logger) Viaduct will add happily log execution information:
+
+```ruby
+sequence = Viaduct::Builder.new do
+  use Robust
+  use Flaky
+end
+
+Viaduct::Runner.run(sequence, logger: Logger.new($stderr))
+#I, [2013-04-19T22:28:29.931249 #847]  INFO -- : Calling action: #<Robust:0x007fb20255bf98>
+#I, [2013-04-19T22:28:29.931329 #847]  INFO -- : Calling action: #<Flaky:0x007fb20255bf48>
+#E, [2013-04-19T22:28:29.931404 #847] ERROR -- : Error occurred: I'm having trouble
+#I, [2013-04-19T22:28:29.931441 #847]  INFO -- : Calling recover: #<Robust:0x007fb20255bf98>
+#E, [2013-04-19T22:28:29.931488 #847] ERROR -- : Error occurred: I'm having trouble
+```
+
 ## Tests
 
-  $ bundle exec rake
+    $ bundle exec rake
 
 Or automatically run tests with guard
 
-  $ bundle exec guard
+    $ bundle exec guard
 
 ## Releasing
 
     $ gem install gem-release
     $ gem bump -trv patch
 
-## Usage
-
 ## Contributing
 
 1. Fork it

data/lib/viaduct/runner.rb

@@ -1,19 +1,16 @@
 module Viaduct
   class Runner
-    def initialize(globals=nil, &block)
-      @globals      = globals || {}
-      @lazy_globals = block
+    def self.run(app, options=nil)
+      new.run(app, options)
     end
 
     def run(callable_id, options=nil)
       callable = callable_id
       callable = Builder.new.use(callable_id) if callable_id.kind_of?(Class)
-      raise ArgumentError, "Argument to run must be a callable object or registered action." if !callable || !callable.respond_to?(:call)
+      raise ArgumentError, "Argument to run must be a callable object or known class." if !callable || !callable.respond_to?(:call)
 
       # Create the initial environment with the options given
       environment = Environment.new
-      environment.merge!(@globals)
-      environment.merge!(@lazy_globals.call) if @lazy_globals
       environment.merge!(options || {})
 
       callable.call(environment)

data/lib/viaduct/version.rb

@@ -1,3 +1,3 @@
 module Viaduct
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/lib/viaduct/warden.rb

@@ -17,7 +17,7 @@ module Viaduct
     def initialize(actions, env)
       @stack = []
       @actions = actions.map { |m| finalize_action(m, env) }
-      @logger  = env.has_key?(:logger) ? env[:logger] : Logger.new($stderr)
+      @logger  = env.has_key?(:logger) ? env[:logger] : Logger.new(nil)
     end
 
     def call(env)

data/spec/integration_spec.rb

@@ -0,0 +1,64 @@
+require 'spec_helper'
+
+describe "a simple set of middlwares" do
+  class Add
+    def initialize(app, env); @app, @env = app, env; end
+
+    def call(env)
+      env[:data] << "adding"
+      @app.call(env)
+    end
+  end
+
+  class Remove
+    def initialize(app, env); @app, @env = app, env; end
+
+    def call(env)
+      env[:data].shift
+      @app.call(env)
+    end
+  end
+
+  it "works" do
+    stack = Viaduct::Builder.new do
+      use Add
+      use Remove
+      use Add
+    end
+
+    env = Viaduct::Runner.run(stack, {data: []})
+    env[:data].should == ['adding']
+  end
+end
+
+describe "handling exceptions" do
+  class Robust
+    def initialize(app, env); @app, @env = app, env; end
+
+    def call(env)
+      @app.call(env)
+    end
+
+    def recover(env)
+      env[:logger].error "I got this!"
+    end
+  end
+
+  class Flaky
+    class OMG < StandardError; end
+
+    def initialize(app, env); @app, @env = app, env; end
+
+    def call(env)
+      raise OMG.new("I'm having trouble")
+    end
+  end
+
+  let(:sequence) { Viaduct::Builder.new { use Robust; use Flaky } }
+
+  it "has a chance to handle exceptions" do
+    expect {
+      Viaduct::Runner.run(sequence, { logger: Logger.new(nil) })
+    }.to raise_error Flaky::OMG
+  end
+end

data/spec/runner_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 describe Viaduct::Runner do
-  let(:instance) { described_class.new }
+  let(:instance) { Viaduct::Runner.new }
 
   it "should raise an error if an invalid callable is given" do
     expect { instance.run(7) }.to raise_error(ArgumentError, /must be a callable/)
@@ -34,26 +34,4 @@ describe Viaduct::Runner do
     instance.run(callable, "data" => "foo")
     result.should == "foo"
   end
-
-  it "should pass global options into the hash" do
-    result = nil
-    callable = lambda do |env|
-      result = env["data"]
-    end
-
-    instance = described_class.new("data" => "bar")
-    instance.run(callable)
-    result.should == "bar"
-  end
-
-  it "should yield the block passed to the init method to get lazy loaded globals" do
-    result = nil
-    callable = lambda do |env|
-      result = env["data"]
-    end
-
-    instance = described_class.new { { "data" => "bar" } }
-    instance.run(callable)
-    result.should == "bar"
-  end
 end

data/viaduct.gemspec

@@ -16,8 +16,4 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
-
-  gem.add_development_dependency "rake"
-  gem.add_development_dependency "guard"
-  gem.add_development_dependency "rspec", "~> 2.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: viaduct
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,56 +9,8 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-19 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: guard
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.10.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 2.10.0
+date: 2013-04-20 00:00:00.000000000 Z
+dependencies: []
 description: Build stuff with middlware.
 email:
 - jhansen@slack.io
@@ -83,6 +35,7 @@ files:
 - lib/viaduct/warden.rb
 - spec/builder_spec.rb
 - spec/environment_spec.rb
+- spec/integration_spec.rb
 - spec/runner_spec.rb
 - spec/spec_helper.rb
 - spec/warden_spec.rb
@@ -94,17 +47,17 @@ rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+  none: false
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -114,6 +67,8 @@ summary: Extracted from vagrant, viaduct makes it easy to build up middlware.
 test_files:
 - spec/builder_spec.rb
 - spec/environment_spec.rb
+- spec/integration_spec.rb
 - spec/runner_spec.rb
 - spec/spec_helper.rb
 - spec/warden_spec.rb
+has_rdoc: