rackables 0.1.0 → 0.2.0

data/README.rdoc

@@ -0,0 +1,50 @@
+= Rackables
+
+== Middleware
+
+Rackables bundles the following Rack middlewares:
+
+* Rackables::Branch - Conditionally re-routes the Rack stack at runtime to an alternate endpoint
+* Rackables::CacheControl - Sets response Cache-Control header
+* Rackables::DefaultCharset - Sets charset directive in Content-Type header
+* Rackables::Get - Allows creation of simple endpoints and path routing with a syntax similar to Sinatra's get method
+* Rackables::HideExceptions - Rescues exceptions with a static exception page
+* Rackables::TrailingSlashRedirect - 301 Redirects requests paths with a trailing slash
+
+== More 
+
+Rackables also bundles a Rack environment inquirer similar to Rails.env:
+	
+  Rack.env                # => "development"
+  Rack.env.development?   # => true
+
+== Use
+
+Requiring 'rackables' will add autoloads for all Rackables middlewares. To use the Rack.env inquirer, 
+you must explicitly require "rackables/more/env_inquirer".
+
+Example config.ru:
+
+  require 'rackables'
+  require 'rackables/more/env_inquirer'
+  require 'my_endpont_app'
+
+  if Rack.env.development?
+    use Rack::ShowExceptions
+  else
+    use Rackables::HideExceptions, 'public/500.html'
+  end
+
+  use Rackables::TrailingSlashRedirect
+  use Rackables::CacheControl, :public, :max_age => 60
+  use Rackables::DefaultCharset, 'utf-8'
+
+  use Rackables::Get, '/ping_monitor' do
+    "pong"
+  end
+
+  use Rackables::Branch do |env|
+    Rack::Lobster if env["PATH_INFO"] =~ /^\/lobster$/
+  end
+
+  run MyEndpointApp

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/rackables.rb

@@ -1,6 +1,8 @@
 module Rackables
-  autoload :CacheControl, 'rackables/cache_control'
-  autoload :DefaultCharset, 'rackables/default_charset'
-  autoload :PublicExceptionPage, 'rackables/public_exception_page'
-  autoload :TrailingSlashRedirect, 'rackables/trailing_slash_redirect'
+  autoload :Branch,                 'rackables/branch'
+  autoload :CacheControl,           'rackables/cache_control'
+  autoload :DefaultCharset,         'rackables/default_charset'
+  autoload :Get,                    'rackables/get'
+  autoload :HideExceptions,         'rackables/hide_exceptions'
+  autoload :TrailingSlashRedirect,  'rackables/trailing_slash_redirect'
 end

data/lib/rackables/branch.rb

@@ -0,0 +1,39 @@
+module Rackables
+  # Rackables::Branch lets you conditionally re-route the Rack stack at runtime to
+  # an alternate endpoint.
+  #
+  # You initialize this middleware with a block, which should either 1. return a
+  # valid rack endpoint, when want to branch away from the current Rack pipeline,
+  # or 2. nil/false, when you want to continue on. The block is passed the current
+  # Rack env hash.
+  #
+  # config.ru usage example:
+  #
+  #   use Rackables::Branch do |env|
+  #     ApiApp if env["PATH_INFO"] =~ /\.xml$/
+  #   end
+  #
+  #   run MyEndpointApp
+  #
+  # A slightly more complex example with multiple endpoints:
+  #
+  #   use Rackables::Branch do |env|
+  #     if env['PATH_INFO'] =~ %r{^\/foo\/(bar|baz)(.*)$/}
+  #       env['PATH_INFO'] = $2
+  #       {'bar' => BarApp, 'baz' => BazApp}[$1]
+  #     end
+  #   end
+  #
+  #   run MyEndpointApp
+  class Branch
+    def initialize(app, &block)
+      @app = app
+      @block = block
+    end
+
+    def call(env)
+      app = @block.call(env) || @app
+      app.call(env)
+    end
+  end
+end

data/lib/rackables/cache_control.rb

@@ -1,21 +1,65 @@
 module Rackables
   class CacheControl
-    # Works well with Varnish
-    # TODO: accomodate more options than just public, max-age=
-    def initialize(app, value, opts)
+    # Lets you set the Cache-Control response header from middleware. Does not overwrite
+    # existing Cache-Control response header, if it already has been set.
+    #
+    # Examples:
+    #
+    #   use Rackables::CacheControl, :public, :max_age => 5
+    #     # => Cache-Control: public, max-age=5
+    #
+    #   use Rackables::CacheControl, :private, :must_revalidate, :community => "UCI"
+    #     # => Cache-Control: private, must-revalidate, community="UCI"
+    #
+    # Values specified as a Proc will be called at runtime for each request:
+    #
+    #   use Rackables::CacheControl, :public, :max_age => Proc.new { rand(6) + 3 }
+    def initialize(app, *directives)
       @app = app
-      @value = value
-      @opts = opts
+      @hash = extract_hash!(directives)
+      @directives = directives
+      extract_non_callable_values_from_hash!
+      stringify_hash_keys!
+      stringify_directives!
     end
 
     def call(env)
-      status, headers, body = @app.call(env)
-      if headers['Cache-Control'].nil?
-        max_age = @opts[:max_age]
-        max_age = max_age.call if max_age.respond_to?(:call)
-        headers['Cache-Control'] = "#{@value}, max-age=#{max_age}"
+      response = @app.call(env)
+      headers = response[1]
+      unless headers.has_key?('Cache-Control')
+        value = @hash.empty? ? @directives : "#{@directives}, #{stringify_hash}"
+        headers['Cache-Control'] = value
       end
-      [status, headers, body]
+      response
     end
+    
+    private
+      def extract_hash!(array)
+        array.last.kind_of?(Hash) ? array.pop : {}
+      end
+      
+      def extract_non_callable_values_from_hash!
+        @hash.reject! { |k,v| v == false }
+        @hash.reject! { |k,v| @directives << k if v == true }
+        @hash.reject! { |k,v| @directives << "#{k}=#{v.inspect}" if !v.respond_to?(:call) }
+      end
+      
+      def stringify_hash_keys!
+        @hash.each do |key, value|
+          @hash[stringify_directive(key)] = @hash.delete(key)
+        end
+      end
+      
+      def stringify_directives!
+        @directives = @directives.map {|d| stringify_directive(d)}.join(', ')
+      end
+      
+      def stringify_hash
+        @hash.inject([]) {|arr, (k, v)| arr << "#{k}=#{v.call.inspect}"}.join(', ')
+      end
+      
+      def stringify_directive(directive)
+        directive.to_s.tr('_','-')
+      end
   end
 end

data/lib/rackables/default_charset.rb

@@ -1,4 +1,8 @@
 module Rackables
+  # Adds the specified charset to the Content-Type header, if one isn't
+  # already there.
+  #
+  # Ideal for use with Sinatra, which by default doesn't set charset
   class DefaultCharset
     HAS_CHARSET = /charset=/
 
@@ -8,12 +12,13 @@ module Rackables
     end
 
     def call(env)
-      status, headers, body = @app.call(env)
+      response = @app.call(env)
+      headers = response[1]
       content_type = headers['Content-Type']
       if content_type && content_type !~ HAS_CHARSET
         headers['Content-Type'] = "#{content_type}; charset=#{@value}"
       end
-      [status, headers, body]
+      response
     end
   end
 end

data/lib/rackables/get.rb

@@ -0,0 +1,45 @@
+module Rackables
+  # Simplest example:
+  #
+  #   use Rackables::Get, '/ping_monitor' do
+  #     'pong'
+  #   end
+  #
+  # Rack::Response object is yielded as second argument to block:
+  #
+  #   use Rackables::Get, '/json' do |env, response|
+  #     response['Content-Type'] = 'application/json'
+  #     %({"foo": "bar"})
+  #   end
+  #
+  # Example with regular expression -- match data object is yielded as third argument to block
+  #
+  #   use Rackables::Get, %r{^/(john|paul|george|ringo)} do |env, response, match|
+  #     "Hello, #{match[1]}"
+  #   end
+  #
+  # A false/nil return from block will not return a response; control will continue down the
+  # Rack stack:
+  #
+  #   use Rackables::Get, '/api_key' do |env, response|
+  #     '12345' if env['myapp.user'].authorized?
+  #   end
+  class Get
+    def initialize(app, path, &block)
+      @app = app
+      @path = path
+      @block = block
+    end
+
+    def call(env)
+      path, method = env['PATH_INFO'].to_s, env['REQUEST_METHOD']
+      if method == 'GET' && ((@path.is_a?(Regexp) && match = @path.match(path)) || @path == path)
+        response = ::Rack::Response.new
+        response.body = @block.call(env, response, match)
+        response.body ? response.finish : @app.call(env)
+      else
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/rackables/{public_exception_page.rb → hide_exceptions.rb}

@@ -6,14 +6,14 @@ module Rackables
   #   if ENV['RACK_ENV'] == 'development'
   #     use Rack::ShowExceptions
   #   else
-  #     use Rackables::PublicExceptionPage
+  #     use Rackables::HideExceptions
   #   end
   #
   # The default HTML included here is a copy of the 500 page included with Rails
   # You can optionally specify your own file, ex:
   #
-  #   use Rackables::PublicExceptionPage, "public/500.html"
-  class PublicExceptionPage
+  #   use Rackables::HideExceptions, "public/500.html"
+  class HideExceptions
 
     def initialize(app, file_path = nil)
       @app = app

data/lib/rackables/more/env_inquirer.rb

@@ -0,0 +1,28 @@
+# This file not required by default -- to add this feature, you need to explicitly require, ex:
+#
+#   require 'rackables/more/env_inquirer'
+module Rack
+  # Adds pretty reader and query methods for ENV['RACK_ENV'] value.
+  # A copy of Rails' Rails.env for Rack apps.
+  #
+  # Examples:
+  #
+  #   Rack.env                # => "development"
+  #   Rack.env.development?   # => true
+  def self.env
+    @env ||= Utils::StringInquirer.new(ENV["RACK_ENV"] || "development")
+  end
+
+  module Utils
+    # TAKEN FROM ACTIVE SUPPORT
+    class StringInquirer < String
+      def method_missing(method_name, *arguments)
+        if method_name.to_s[-1,1] == "?"
+          self == method_name.to_s[0..-2]
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rackables/trailing_slash_redirect.rb

@@ -1,4 +1,7 @@
 module Rackables
+  # Request paths with a trailing slash are 301 redirected to the version without, e.g.:
+  #
+  #   GET /foo/   # => 301 redirects to /foo
   class TrailingSlashRedirect
     HAS_TRAILING_SLASH = %r{^/(.*)/$}
 

data/test/test_branch.rb

@@ -0,0 +1,26 @@
+require 'test/unit'
+require 'rackables'
+
+class TestBranch < Test::Unit::TestCase
+
+  def test_calls_app_returned_from_block
+    app = Proc.new { [200, {}, ["Downstream app"]] }
+    blog = Proc.new { [200, {}, ["Blog"]] }
+    middleware = Rackables::Branch.new(app) do |env|
+      blog if env['PATH_INFO'] =~ /^\/blog/
+    end
+    status, headers, body = middleware.call('PATH_INFO' => '/blog')
+    assert_equal 'Blog', body[0]
+  end
+
+  def test_calls_app_passed_in_to_initialize_when_block_returns_false
+    app = Proc.new { [200, {}, ["Downstream app"]] }
+    blog = Proc.new { [200, {}, ["Blog"]] }
+    middleware = Rackables::Branch.new(app) do |env|
+      blog if env['PATH_INFO'] =~ /^\/blog/
+    end
+    status, headers, body = middleware.call('PATH_INFO' => '/foo')
+    assert_equal 'Downstream app', body[0]
+  end
+
+end

data/test/test_cache_control.rb

@@ -3,21 +3,51 @@ require 'rackables'
 
 class TestCacheControl < Test::Unit::TestCase
 
-  def test_sets_cache_control
+  def test_sets_cache_control_with_value_set_as_integer
     app = Proc.new { [200, {}, []]}
     middleware = Rackables::CacheControl.new(app, :public, :max_age => 5)
     status, headers, body = middleware.call({})
     assert_equal 'public, max-age=5', headers['Cache-Control']
   end
+  
+  def test_sets_cache_control_with_value_set_as_string
+    app = Proc.new { [200, {}, []]}
+    middleware = Rackables::CacheControl.new(app, :public, :community => "UCI")
+    status, headers, body = middleware.call({})
+    assert_equal %(public, community="UCI"), headers['Cache-Control']
+  end
 
-  def test_sets_cache_control_with_value_specified_as_proc
+  def test_sets_cache_control_with_value_specified_as_proc_which_is_called_at_runtime
     app = Proc.new { [200, {}, []]}
-    middleware = Rackables::CacheControl.new(app, :public, :max_age => Proc.new {5})
+    value = 7 #compile-time value
+    middleware = Rackables::CacheControl.new(app, :public, :max_age => Proc.new {value})
+    value = 5 #runtime value
     status, headers, body = middleware.call({})
     assert_equal 'public, max-age=5', headers['Cache-Control']
   end
+  
+  def test_sets_cache_control_with_multiple_values
+    app = Proc.new { [200, {}, []]}
+    middleware = Rackables::CacheControl.new(app, :private, :no_cache, :must_revalidate)
+    status, headers, body = middleware.call({})
+    assert_equal %(private, no-cache, must-revalidate), headers['Cache-Control']
+  end
+  
+  def test_sets_true_value
+    app = Proc.new { [200, {}, []]}
+    middleware = Rackables::CacheControl.new(app, :private, :must_revalidate => true)
+    status, headers, body = middleware.call({})
+    assert_equal 'private, must-revalidate', headers['Cache-Control']
+  end
+  
+  def test_does_not_set_false_value
+    app = Proc.new { [200, {}, []]}
+    middleware = Rackables::CacheControl.new(app, :private, :must_revalidate => false)
+    status, headers, body = middleware.call({})
+    assert_equal 'private', headers['Cache-Control']
+  end
 
-  def test_respects_existing_cache_control_value
+  def test_respects_existing_cache_control_header
     app = Proc.new { [200, {'Cache-Control' => 'private'}, []]}
     middleware = Rackables::CacheControl.new(app, :public, :max_age => 5)
     status, headers, body = middleware.call({})

data/test/test_get.rb

@@ -0,0 +1,80 @@
+require 'test/unit'
+require 'rackables'
+require 'rubygems'
+require 'rack'
+
+class TestGet < Test::Unit::TestCase
+
+  def setup
+    @app = Proc.new { [200, {}, ["Downstream app"]] }
+  end
+
+  def test_calls_downstream_app_when_no_match
+    middleware = Rackables::Get.new(@app, '/foo') { 'bar' }
+    status, headers, body = middleware.call('PATH_INFO' => '/bar', 'REQUEST_METHOD' => 'GET')
+    assert_equal 200, status
+    assert_equal 'Downstream app', body[0]
+  end
+
+  def test_calls_downstream_app_when_path_matches_but_request_method_is_not_get
+    middleware = Rackables::Get.new(@app, '/foo') { 'bar' }
+    status, headers, body = middleware.call('PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'POST')
+    assert_equal 200, status
+    assert_equal 'Downstream app', body[0]
+  end
+
+  def test_calls_downstream_app_when_path_matches_but_block_returns_nil
+    middleware = Rackables::Get.new(@app, '/foo') {  }
+    status, headers, body = middleware.call('PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'GET')
+    assert_equal 200, status
+    assert_equal 'Downstream app', body[0]
+  end
+
+  def test_get_returns_response_when_string_path_arg_matches_path_info
+    middleware = Rackables::Get.new(@app, '/foo') { 'bar' }
+    status, headers, body = middleware.call('PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'GET')
+    assert_equal 200, status
+    assert_equal 'bar', body.body
+  end
+
+  def test_get_returns_response_when_string_path_arg_matches_regex
+    middleware = Rackables::Get.new(@app, /foo/) { 'bar' }
+    status, headers, body = middleware.call('PATH_INFO' => '/bar/foo', 'REQUEST_METHOD' => 'GET')
+    assert_equal 200, status
+    assert_equal 'bar', body.body
+  end
+
+  def test_block_yields_env
+    env = {'PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'GET'}
+    middleware = Rackables::Get.new(@app, '/foo') do |e, resp|
+      assert_equal env, e
+    end
+    status, headers, body = middleware.call(env)
+  end
+
+  def test_block_yields_response_obj
+    env = {'PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'GET'}
+    middleware = Rackables::Get.new(@app, '/foo') do |e, resp|
+      assert_instance_of ::Rack::Response, resp
+    end
+    status, headers, body = middleware.call(env)
+  end
+
+  def test_block_yields_match_data
+    env = {'PATH_INFO' => '/foobar', 'REQUEST_METHOD' => 'GET'}
+    middleware = Rackables::Get.new(@app, /foo(.+)/) do |e, resp, match|
+      assert_instance_of MatchData, match
+      assert_equal 'bar', match[1]
+    end
+    status, headers, body = middleware.call(env)
+  end
+
+  def test_response_honors_headers_set_in_block
+    middleware = Rackables::Get.new(@app, '/foo') {|e, r| r['X-Foo'] = 'bar'; 'baz' }
+    status, headers, body = middleware.call('PATH_INFO' => '/foo', 'REQUEST_METHOD' => 'GET')
+    assert_equal 200, status
+    assert_equal 'bar', headers['X-Foo']
+    assert_equal 'baz', body.body
+  end
+
+end

data/test/{test_public_exception_page.rb → test_hide_exceptions.rb}

@@ -1,11 +1,11 @@
 require 'test/unit'
 require 'rackables'
 
-class TestPublicExceptionPage < Test::Unit::TestCase
+class TestHideExceptions < Test::Unit::TestCase
 
   def test_returns_downstream_app_response_when_no_exception_raised
     app = Proc.new { [200, {'Content-Type' => 'text/html'}, ['Downstream app']]}
-    middleware = Rackables::PublicExceptionPage.new(app)
+    middleware = Rackables::HideExceptions.new(app)
     status, headers, body = middleware.call({})
     assert_equal 200, status
     assert_equal ['Downstream app'], body
@@ -13,7 +13,7 @@ class TestPublicExceptionPage < Test::Unit::TestCase
 
   def test_returns_500_with_default_exception_page_when_exception_raised_by_downstream_app
     app = Proc.new { raise }
-    middleware = Rackables::PublicExceptionPage.new(app)
+    middleware = Rackables::HideExceptions.new(app)
     status, headers, body = middleware.call({})
     assert_equal 500, status
     assert_match /We\'re sorry, but something went wrong/, body[0]
@@ -21,7 +21,7 @@ class TestPublicExceptionPage < Test::Unit::TestCase
 
   def test_returns_500_with_custom_exception_page_when_file_path_specified
     app = Proc.new { raise }
-    middleware = Rackables::PublicExceptionPage.new(app, 'test/fixtures/custom_500.html')
+    middleware = Rackables::HideExceptions.new(app, 'test/fixtures/custom_500.html')
     status, headers, body = middleware.call({})
     assert_equal 500, status
     assert_match /Custom 500 page/, body[0]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rackables
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Geoff Buesing
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-12 00:00:00 -06:00
+date: 2010-01-15 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
@@ -20,20 +20,25 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
-- README
+- README.rdoc
 - Rakefile
 - VERSION
 - lib/rackables.rb
+- lib/rackables/branch.rb
 - lib/rackables/cache_control.rb
 - lib/rackables/default_charset.rb
-- lib/rackables/public_exception_page.rb
+- lib/rackables/get.rb
+- lib/rackables/hide_exceptions.rb
+- lib/rackables/more/env_inquirer.rb
 - lib/rackables/trailing_slash_redirect.rb
 - test/fixtures/custom_500.html
+- test/test_branch.rb
 - test/test_cache_control.rb
 - test/test_default_charset.rb
-- test/test_public_exception_page.rb
+- test/test_get.rb
+- test/test_hide_exceptions.rb
 - test/test_trailing_slash_redirect.rb
 has_rdoc: true
 homepage: http://github.com/gbuesing/rackables
@@ -64,7 +69,9 @@ signing_key:
 specification_version: 3
 summary: Bundle of useful Rack middleware
 test_files: 
+- test/test_branch.rb
 - test/test_cache_control.rb
 - test/test_default_charset.rb
-- test/test_public_exception_page.rb
+- test/test_get.rb
+- test/test_hide_exceptions.rb
 - test/test_trailing_slash_redirect.rb

data/README

@@ -1,6 +0,0 @@
-Bundles the following Rack middlewares:
-
-Rackables::CacheControl
-Rackables::DefaultCharset
-Rackables::PublicExceptionPage
-Rackables::TrailingSlashRedirect