rack-contrib 0.9.0

data/COPYING

@@ -0,0 +1,18 @@
+Copyright (c) 2008 The Committers
+
+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 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.rdoc

@@ -0,0 +1,60 @@
+= Contributed Rack Middleware and Utilities
+
+This package includes a variety of add-on components for Rack, a Ruby web server
+interface:
+
+* Rack::ETag - Automatically sets the ETag header on all String bodies.
+* Rack::JSONP - Adds JSON-P support by stripping out the callback param
+  and padding the response with the appropriate callback format.
+* Rack::LighttpdScriptNameFix - Fixes how lighttpd sets the SCRIPT_NAME
+  and PATH_INFO variables in certain configurations.
+* Rack::Locale - Detects the client locale using the Accept-Language request
+  header and sets a rack.locale variable in the environment.
+* Rack::MailExceptions - Rescues exceptions raised from the app and
+  sends a useful email with the exception, stacktrace, and contents of the
+  environment.
+* Rack::NestedParams - parses form params with subscripts (e.g., * "post[title]=Hello")
+  into a nested/recursive Hash structure (based on Rails' implementation).
+* Rack::PostBodyContentTypeParser - Adds support for JSON request bodies. The
+  Rack parameter hash is populated by deserializing the JSON data provided in
+  the request body when the Content-Type is application/json.
+* Rack::ProcTitle - Displays request information in process title ($0) for
+  monitoring/inspection with ps(1).
+* Rack::Profiler - Uses ruby-prof to measure request time.
+* Rack::Sendfile - Enables X-Sendfile support for bodies that can be served
+  from file.
+* Rack::TimeZone - Detects the clients timezone using JavaScript and sets
+  a variable in Rack's environment with the offset from UTC.
+* Rack::Evil - Lets the rack application return a response to the client from any place.
+* Rack::Callbacks - Implements DLS for pure before/after filter like Middlewares.
+
+=== Use
+
+Git is the quickest way to the rack-contrib sources:
+
+  git clone git://github.com/rack/rack-contrib.git
+
+Gems are currently available from GitHub clones:
+
+  gem install rack-rack-contrib --source=http://gems.github.com/
+
+Requiring 'rack/contrib' will add autoloads to the Rack modules for all of the
+components included. The following example shows what a simple rackup
+(+config.ru+) file might look like:
+
+  require 'rack'
+  require 'rack/contrib'
+
+  use Rack::Profiler if ENV['RACK_ENV'] == 'development'
+
+  use Rack::ETag
+  use Rack::MailExceptions
+
+  run theapp
+
+=== Links
+
+rack-contrib on GitHub:: <http://github.com/rack/rack-contrib>
+Rack:: <http://rack.rubyforge.org/>
+Rack On GitHub:: <http://github.org/rack/rack>
+rack-devel mailing list:: <http://groups.google.com/group/rack-devel>

data/Rakefile

@@ -0,0 +1,92 @@
+# Rakefile for Rack::Contrib.  -*-ruby-*-
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+desc "Run all the tests"
+task :default => [:test]
+
+desc "Generate RDox"
+task "RDOX" do
+  sh "specrb -Ilib:test -a --rdox >RDOX"
+end
+
+desc "Run all the fast tests"
+task :test do
+  sh "specrb -Ilib:test -w #{ENV['TEST'] || '-a'} #{ENV['TESTOPTS']}"
+end
+
+desc "Run all the tests"
+task :fulltest do
+  sh "specrb -Ilib:test -w #{ENV['TEST'] || '-a'} #{ENV['TESTOPTS']}"
+end
+
+desc "Generate RDoc documentation"
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.options << '--line-numbers' << '--inline-source' <<
+    '--main' << 'README' <<
+    '--title' << 'Rack Contrib Documentation' <<
+    '--charset' << 'utf-8'
+  rdoc.rdoc_dir = "doc"
+  rdoc.rdoc_files.include 'README.rdoc'
+  rdoc.rdoc_files.include 'RDOX'
+  rdoc.rdoc_files.include('lib/rack/*.rb')
+  rdoc.rdoc_files.include('lib/rack/*/*.rb')
+end
+task :rdoc => ["RDOX"]
+
+
+# PACKAGING =================================================================
+
+# load gemspec like github's gem builder to surface any SAFE issues.
+require 'rubygems/specification'
+$spec = eval(File.read('rack-contrib.gemspec'))
+
+def package(ext='')
+  "pkg/rack-contrib-#{$spec.version}" + ext
+end
+
+desc 'Build packages'
+task :package => %w[.gem .tar.gz].map {|e| package(e)}
+
+desc 'Build and install as local gem'
+task :install => package('.gem') do
+  sh "gem install #{package('.gem')}"
+end
+
+directory 'pkg/'
+
+file package('.gem') => %w[pkg/ rack-contrib.gemspec] + $spec.files do |f|
+  sh "gem build rack-contrib.gemspec"
+  mv File.basename(f.name), f.name
+end
+
+file package('.tar.gz') => %w[pkg/] + $spec.files do |f|
+  sh "git archive --format=tar HEAD | gzip > #{f.name}"
+end
+
+desc 'Publish gem and tarball to rubyforge'
+task 'publish:gem' => [package('.gem'), package('.tar.gz')] do |t|
+  sh <<-end
+    rubyforge add_release rack rack-contrib #{$spec.version} #{package('.gem')} &&
+    rubyforge add_file    rack rack-contrib #{$spec.version} #{package('.tar.gz')}
+  end
+end
+
+# GEMSPEC ===================================================================
+
+file 'rack-contrib.gemspec' => FileList['{lib,test}/**','Rakefile', 'README.rdoc'] do |f|
+  # read spec file and split out manifest section
+  spec = File.read(f.name)
+  parts = spec.split("  # = MANIFEST =\n")
+  fail 'bad spec' if parts.length != 3
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").sort.reject{ |file| file =~ /^\./ }.
+    map{ |file| "    #{file}" }.join("\n")
+  # piece file back together and write...
+  parts[1] = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = parts.join("  # = MANIFEST =\n")
+  spec.sub!(/s.date = '.*'/, "s.date = '#{Time.now.strftime("%Y-%m-%d")}'")
+  File.open(f.name, 'w') { |io| io.write(spec) }
+  puts "updated #{f.name}"
+end

data/lib/rack/contrib/bounce_favicon.rb

@@ -0,0 +1,16 @@
+module Rack
+  # Bounce those annoying favicon.ico requests
+  class BounceFavicon
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      if env["PATH_INFO"] == "/favicon.ico"
+        [404, {"Content-Type" => "text/html", "Content-Length" => "0"}, []]
+      else
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/rack/contrib/callbacks.rb

@@ -0,0 +1,37 @@
+module Rack
+  class Callbacks
+    def initialize(&block)
+      @before = []
+      @after  = []
+      instance_eval(&block) if block_given?
+    end
+
+    def before(middleware, *args, &block)
+      if block_given?
+        @before << middleware.new(*args, &block)
+      else
+        @before << middleware.new(*args)
+      end
+    end
+
+    def after(middleware, *args, &block)
+      if block_given?
+        @after << middleware.new(*args, &block)
+      else
+        @after << middleware.new(*args)
+      end
+    end
+
+    def run(app)
+      @app = app
+    end
+
+    def call(env)
+      @before.each {|c| c.call(env) }
+
+      response = @app.call(env)
+
+      @after.inject(response) {|r, c| c.call(r) }
+    end
+  end
+end

data/lib/rack/contrib/etag.rb

@@ -0,0 +1,20 @@
+require 'digest/md5'
+
+module Rack
+  # Automatically sets the ETag header on all String bodies
+  class ETag
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      status, headers, body = @app.call(env)
+
+      if !headers.has_key?('ETag') && body.is_a?(String)
+        headers['ETag'] = %("#{Digest::MD5.hexdigest(body)}")
+      end
+
+      [status, headers, body]
+    end
+  end
+end

data/lib/rack/contrib/evil.rb

@@ -0,0 +1,12 @@
+module Rack
+  class Evil
+    # Lets you return a response to the client immediately from anywhere ( M V or C ) in the code.
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      catch(:response) { @app.call(env) }
+    end
+  end
+end

data/lib/rack/contrib/garbagecollector.rb

@@ -0,0 +1,14 @@
+module Rack
+  # Forces garbage collection after each request.
+  class GarbageCollector
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    ensure
+      GC.start
+    end
+  end
+end

data/lib/rack/contrib/jsonp.rb

@@ -0,0 +1,38 @@
+module Rack
+  
+  # A Rack middleware for providing JSON-P support.
+  # 
+  # Full credit to Flinn Mueller (http://actsasflinn.com/) for this contribution.
+  # 
+  class JSONP
+    
+    def initialize(app)
+      @app = app
+    end
+    
+    # Proxies the request to the application, stripping out the JSON-P callback
+    # method and padding the response with the appropriate callback format.
+    # 
+    # Changes nothing if no <tt>callback</tt> param is specified.
+    # 
+    def call(env)
+      status, headers, response = @app.call(env)
+      request = Rack::Request.new(env)
+      response = pad(request.params.delete('callback'), response) if request.params.include?('callback')
+      [status, headers, response]
+    end
+    
+    # Pads the response with the appropriate callback format according to the
+    # JSON-P spec/requirements.
+    # 
+    # The Rack response spec indicates that it should be enumerable. The method
+    # of combining all of the data into a sinle string makes sense since JSON
+    # is returned as a full string.
+    # 
+    def pad(callback, response, body = "")
+      response.each{ |s| body << s }
+      "#{callback}(#{body})"
+    end
+    
+  end
+end

data/lib/rack/contrib/lighttpd_script_name_fix.rb

@@ -0,0 +1,16 @@
+module Rack
+  # Lighttpd sets the wrong SCRIPT_NAME and PATH_INFO if you mount your
+  # FastCGI app at "/". This middleware fixes this issue.
+
+  class LighttpdScriptNameFix
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      env["PATH_INFO"] = env["SCRIPT_NAME"].to_s + env["PATH_INFO"].to_s
+      env["SCRIPT_NAME"] = ""
+      @app.call(env)
+    end
+  end
+end

data/lib/rack/contrib/locale.rb

@@ -0,0 +1,31 @@
+require 'i18n'
+
+module Rack
+  class Locale
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      old_locale = I18n.locale
+      locale = nil
+
+      # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
+      if lang = env["HTTP_ACCEPT_LANGUAGE"]
+        lang = lang.split(",").map { |l|
+          l += ';q=1.0' unless l =~ /;q=\d+\.\d+$/
+          l.split(';q=')
+        }.first
+        locale = lang.first.split("-").first
+      else
+        locale = I18n.default_locale
+      end
+
+      locale = env['rack.locale'] = I18n.locale = locale.to_s
+      status, headers, body = @app.call(env)
+      headers['Content-Language'] = locale
+      I18n.locale = old_locale
+      [status, headers, body]
+    end
+  end
+end

data/lib/rack/contrib/mailexceptions.rb

@@ -0,0 +1,120 @@
+require 'net/smtp'
+require 'tmail'
+require 'erb'
+
+module Rack
+  # Catches all exceptions raised from the app it wraps and
+  # sends a useful email with the exception, stacktrace, and
+  # contents of the environment.
+
+  class MailExceptions
+    attr_reader :config
+
+    def initialize(app)
+      @app = app
+      @config = {
+        :to      => nil,
+        :from    => ENV['USER'] || 'rack',
+        :subject => '[exception] %s',
+        :smtp    => {
+          :server         => 'localhost',
+          :domain         => 'localhost',
+          :port           => 25,
+          :authentication => :login,
+          :user_name      => nil,
+          :password       => nil
+        }
+      }
+      @template = ERB.new(TEMPLATE)
+      yield self if block_given?
+    end
+
+    def call(env)
+      status, headers, body =
+        begin
+          @app.call(env)
+        rescue => boom
+          # TODO don't allow exceptions from send_notification to
+          # propogate
+          send_notification boom, env
+          raise
+        end
+      send_notification env['mail.exception'], env if env['mail.exception']
+      [status, headers, body]
+    end
+
+    %w[to from subject].each do |meth|
+      define_method(meth) { |value| @config[meth.to_sym] = value }
+    end
+
+    def smtp(settings={})
+      @config[:smtp].merge! settings
+    end
+
+  private
+    def generate_mail(exception, env)
+      mail = TMail::Mail.new
+      mail.to = Array(config[:to])
+      mail.from = config[:from]
+      mail.subject = config[:subject] % [exception.to_s]
+      mail.date = Time.now
+      mail.set_content_type 'text/plain'
+      mail.charset = 'UTF-8'
+      mail.body = @template.result(binding)
+      mail
+    end
+
+    def send_notification(exception, env)
+      mail = generate_mail(exception, env)
+      smtp = config[:smtp]
+      env['mail.sent'] = true
+      return if smtp[:server] == 'example.com'
+
+      Net::SMTP.start smtp[:address], smtp[:port], smtp[:domain], smtp[:user_name], smtp[:password], smtp[:authentication] do |server|
+        mail.to.each do |recipient|
+          server.send_message mail.to_s, mail.from, recipient
+        end
+      end
+    end
+
+    def extract_body(env)
+      if io = env['rack.input']
+        io.rewind if io.respond_to?(:rewind)
+        io.read
+      end
+    end
+
+    TEMPLATE = (<<-'EMAIL').gsub(/^ {4}/, '')
+    A <%= exception.class.to_s %> occured: <%= exception.to_s %>
+    <% if body = extract_body(env) %>
+
+    ===================================================================
+    Request Body:
+    ===================================================================
+
+    <%= body.gsub(/^/, '  ') %>
+    <% end %>
+
+    ===================================================================
+    Rack Environment:
+    ===================================================================
+
+      PID:                     <%= $$ %>
+      PWD:                     <%= Dir.getwd %>
+
+      <%= env.to_a.
+        sort{|a,b| a.first <=> b.first}.
+        map{ |k,v| "%-25s%p" % [k+':', v] }.
+        join("\n  ") %>
+
+    <% if exception.respond_to?(:backtrace) %>
+    ===================================================================
+    Backtrace:
+    ===================================================================
+
+      <%= exception.backtrace.join("\n  ") %>
+    <% end %>
+    EMAIL
+
+  end
+end

data/lib/rack/contrib/nested_params.rb

@@ -0,0 +1,143 @@
+require 'cgi'
+require 'strscan'
+
+module Rack
+  # Rack middleware for parsing POST/PUT body data into nested parameters
+  class NestedParams
+
+    CONTENT_TYPE = 'CONTENT_TYPE'.freeze
+    POST_BODY = 'rack.input'.freeze
+    FORM_INPUT = 'rack.request.form_input'.freeze
+    FORM_HASH = 'rack.request.form_hash'.freeze
+    FORM_VARS = 'rack.request.form_vars'.freeze
+
+    # supported content type
+    URL_ENCODED = 'application/x-www-form-urlencoded'.freeze
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      if form_vars = env[FORM_VARS]
+        env[FORM_HASH] = parse_query_parameters(form_vars)
+      elsif env[CONTENT_TYPE] == URL_ENCODED
+        post_body = env[POST_BODY]
+        env[FORM_INPUT] = post_body
+        env[FORM_HASH] = parse_query_parameters(post_body.read)
+        post_body.rewind if post_body.respond_to?(:rewind)
+      end
+      @app.call(env)
+    end
+
+    ## the rest is nabbed from Rails ##
+
+    def parse_query_parameters(query_string)
+      return {} if query_string.nil? or query_string.empty?
+
+      pairs = query_string.split('&').collect do |chunk|
+        next if chunk.empty?
+        key, value = chunk.split('=', 2)
+        next if key.empty?
+        value = value.nil? ? nil : CGI.unescape(value)
+        [ CGI.unescape(key), value ]
+      end.compact
+
+      UrlEncodedPairParser.new(pairs).result
+    end
+
+    class UrlEncodedPairParser < StringScanner
+      attr_reader :top, :parent, :result
+
+      def initialize(pairs = [])
+        super('')
+        @result = {}
+        pairs.each { |key, value| parse(key, value) }
+      end
+
+      KEY_REGEXP = %r{([^\[\]=&]+)}
+      BRACKETED_KEY_REGEXP = %r{\[([^\[\]=&]+)\]}
+
+      # Parse the query string
+      def parse(key, value)
+        self.string = key
+        @top, @parent = result, nil
+
+        # First scan the bare key
+        key = scan(KEY_REGEXP) or return
+        key = post_key_check(key)
+
+        # Then scan as many nestings as present
+        until eos?
+          r = scan(BRACKETED_KEY_REGEXP) or return
+          key = self[1]
+          key = post_key_check(key)
+        end
+
+        bind(key, value)
+      end
+
+      private
+        # After we see a key, we must look ahead to determine our next action. Cases:
+        #
+        #   [] follows the key. Then the value must be an array.
+        #   = follows the key. (A value comes next)
+        #   & or the end of string follows the key. Then the key is a flag.
+        #   otherwise, a hash follows the key.
+        def post_key_check(key)
+          if scan(/\[\]/) # a[b][] indicates that b is an array
+            container(key, Array)
+            nil
+          elsif check(/\[[^\]]/) # a[b] indicates that a is a hash
+            container(key, Hash)
+            nil
+          else # End of key? We do nothing.
+            key
+          end
+        end
+
+        # Add a container to the stack.
+        def container(key, klass)
+          type_conflict! klass, top[key] if top.is_a?(Hash) && top.key?(key) && ! top[key].is_a?(klass)
+          value = bind(key, klass.new)
+          type_conflict! klass, value unless value.is_a?(klass)
+          push(value)
+        end
+
+        # Push a value onto the 'stack', which is actually only the top 2 items.
+        def push(value)
+          @parent, @top = @top, value
+        end
+
+        # Bind a key (which may be nil for items in an array) to the provided value.
+        def bind(key, value)
+          if top.is_a? Array
+            if key
+              if top[-1].is_a?(Hash) && ! top[-1].key?(key)
+                top[-1][key] = value
+              else
+                top << {key => value}
+              end
+              push top.last
+              return top[key]
+            else
+              top << value
+              return value
+            end
+          elsif top.is_a? Hash
+            key = CGI.unescape(key)
+            parent << (@top = {}) if top.key?(key) && parent.is_a?(Array)
+            top[key] ||= value
+            return top[key]
+          else
+            raise ArgumentError, "Don't know what to do: top is #{top.inspect}"
+          end
+        end
+
+        def type_conflict!(klass, value)
+          raise TypeError, "Conflicting types for parameter containers. Expected an instance of #{klass} but found an instance of #{value.class}. This can be caused by colliding Array and Hash parameters like qs[]=value&qs[key]=value. (The parameters received were #{value.inspect}.)"
+        end
+    end
+
+  end
+end

data/lib/rack/contrib/post_body_content_type_parser.rb

@@ -0,0 +1,40 @@
+begin
+  require 'json'
+rescue LoadError => e
+  require 'json/pure'
+end
+
+module Rack
+  
+  # A Rack middleware for parsing POST/PUT body data when Content-Type is
+  # not one of the standard supported types, like <tt>application/json</tt>.
+  # 
+  # TODO: Find a better name.
+  # 
+  class PostBodyContentTypeParser
+    
+    # Constants
+    # 
+    CONTENT_TYPE = 'CONTENT_TYPE'.freeze
+    POST_BODY = 'rack.input'.freeze
+    FORM_INPUT = 'rack.request.form_input'.freeze
+    FORM_HASH = 'rack.request.form_hash'.freeze
+    
+    # Supported Content-Types
+    # 
+    APPLICATION_JSON = 'application/json'.freeze
+    
+    def initialize(app)
+      @app = app
+    end
+    
+    def call(env)
+      case env[CONTENT_TYPE]
+      when APPLICATION_JSON
+        env.update(FORM_HASH => JSON.parse(env[POST_BODY].read), FORM_INPUT => env[POST_BODY])
+      end
+      @app.call(env)
+    end
+    
+  end
+end