rack-accept 0.2 → 0.3

data/.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'rack-accept'
-  s.version = '0.2'
+  s.version = '0.3'
   s.date = '2010-04-02'
 
   s.summary = 'HTTP Accept* for Ruby/Rack'
@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.test_files = s.files.select {|path| path =~ /^test\/.*_test.rb/ }
 
   s.add_dependency('rack', '>= 0.4')
-  s.add_development_dependency 'rake'
+  s.add_development_dependency('rake')
 
   s.has_rdoc = true
   s.rdoc_options = %w< --line-numbers --inline-source --title Rack::Accept --main Rack::Accept >

data/CHANGES

@@ -1,3 +1,8 @@
+## 0.3 / April 3, 2010
+
+  * Enhanced Rack middleware component to be able to automatically send a 406
+    response when the request is not acceptable
+
 ## 0.2 / April 2, 2010
 
   * Moved all common header methods into Rack::Accept::Header module

data/README

@@ -23,7 +23,7 @@ Using RubyGems:
 From a local copy:
 
     $ git clone git://github.com/mjijackson/rack-accept.git
-    $ sudo rake install
+    $ rake package && sudo rake install
 
 Usage
 -----
@@ -37,7 +37,7 @@ middleware pipeline and access the Rack::Accept::Request object in the
 
     use Rack::Accept
 
-    app = lambda {|env|
+    app = lambda do |env|
       accept = env['rack-accept.request']
       response = Rack::Response.new
 
@@ -50,22 +50,41 @@ middleware pipeline and access the Rack::Accept::Request object in the
       end
 
       response.finish
-    }
+    end
 
     run app
 
+Rack::Accept can also construct automatic 406 responses if you set up the types
+of media, character sets, encoding, or languages your server is able to serve
+ahead of time.
+
+    require 'rack/accept'
+
+    use(Rack::Accept) do |accept|
+      # We only ever serve content in English or Japanese from this site, so if
+      # the user doesn't accept either of these we will respond with a 406.
+      #
+      # Note: +accept+ is an instance of Rack::Accept::Context.
+      accept.languages = %w< en jp >
+    end
+
+    app = ...
+
+    run app
+
+Note: You should probably think about this very carefully before you use
+Rack::Accept in this way. Many user agents are careless about the types of
+Accept headers they send, and depend on apps not being too picky. Instead of
+automatically sending a 406, you should probably only send one when absolutely
+necessary.
+
 Additionally, Rack::Accept may be used outside of a Rack context to provide
 any Ruby app the ability to construct and interpret Accept headers.
 
     require 'rack/accept'
 
     mtype = Rack::Accept::MediaType.new
-    mtype.qvalues = {
-      'text/html' => 1,
-      'text/*'    => 0.8,
-      '*/*'       => 0.5
-    }
-
+    mtype.qvalues = { 'text/html' => 1, 'text/*' => 0.8, '*/*' => 0.5 }
     mtype.to_s # => "Accept: text/html, text/*;q=0.8, */*;q=0.5"
 
     cset = Rack::Accept::Charset.new('unicode-1-1, iso-8859-5;q=0.8')
@@ -74,7 +93,8 @@ any Ruby app the ability to construct and interpret Accept headers.
 
 The very last line in this example may look like a mistake to someone not
 familiar with the intricacies of the spec, but it's actually correct. It
-just puts emphasis on the convenience of using this library.
+just puts emphasis on the convenience of using this library so you don't
+have to worry about these kinds of details.
 
 Four-letter Words
 -----------------

data/doc/assets/layout.html.erb

@@ -13,16 +13,16 @@
         <div id="header">
             <h1>rack-accept</h1>
             <ul>
-                <li><a href="license.html">License</a></li>
                 <li><a href="api/index.html">API</a></li>
                 <li><a href="http://github.com/mjijackson/rack-accept/issues">Bugs</a></li>
                 <li><a href="http://github.com/mjijackson/rack-accept">Code</a></li>
+                <li><a href="usage.html">Usage</a></li>
                 <li><a href="index.html">Home</a></li>
             </ul>
         </div>
         <div id="content"><%= content %></div>
         <div id="footer">
-            <p class="rights">Copyright &copy; 2010 <a href="http://mjijackson.com/about" rel="me author">Michael J. I. Jackson</a></p>
+            <p><a href="license.html" rel="license">Copyright</a> &copy; 2010 <a href="http://mjijackson.com/about" rel="me author">Michael J. I. Jackson</a></p>
         </div>
     </div>
 </body>

data/doc/assets/style.css

@@ -38,7 +38,17 @@ code {
 }
 pre {
   background-color: #FDFDFD;
-  padding-left: 6px;
+  padding: 4px 0 4px 6px;
+  line-height: 1.2;
+}
+strong {
+  font-weight: bold;
+}
+::selection {
+  background: rgba(200,200,200,0.5);
+}
+::-moz-selection {
+  background: rgba(200,200,200,0.5);
 }
 #wrapper {
   position: relative;

data/doc/index.markdown

@@ -21,58 +21,7 @@ Using [RubyGems][rubygems]:
 From a local copy:
 
     $ git clone git://github.com/mjijackson/rack-accept.git
-    $ sudo rake install
-
-Usage
------
-
-Rack::Accept implements the Rack middleware interface and may be used with any
-Rack-based application. Simply insert the Rack::Accept module in your Rack
-middleware pipeline and access the [Rack::Accept::Request][req] object in the
-"rack-accept.request" environment key, as in the following example:
-
-    require 'rack/accept'
-
-    use Rack::Accept
-
-    app = lambda {|env|
-      accept = env['rack-accept.request']
-      response = Rack::Response.new
-
-      if accept.media_type?('text/html')
-        response['Content-Type'] = 'text/html'
-        response.write "<p>Hello. You accept text/html!</p>"
-      else
-        response['Content-Type'] = 'text/plain'
-        response.write "Apparently you don't accept text/html. Too bad."
-      end
-
-      response.finish
-    }
-
-    run app
-
-Additionally, Rack::Accept may be used outside of a Rack context to provide
-any Ruby app the ability to construct and interpret Accept headers.
-
-    require 'rack/accept'
-
-    mtype = Rack::Accept::MediaType.new
-    mtype.qvalues = {
-      'text/html' => 1,
-      'text/*'    => 0.8,
-      '*/*'       => 0.5
-    }
-
-    mtype.to_s # => "Accept: text/html, text/*;q=0.8, */*;q=0.5"
-
-    cset = Rack::Accept::Charset.new('unicode-1-1, iso-8859-5;q=0.8')
-    cset.best_of(%w< iso-8859-5 unicode-1-1 >)  # => "unicode-1-1"
-    cset.accept?('iso-8859-1')                  # => true
-
-The very last line in this example may look like a mistake to someone not
-familiar with the intricacies of [the spec][sec14-3], but it's actually
-correct. It just puts emphasis on the convenience of using this library.
+    $ rake package && sudo rake install
 
 [rfc]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
 [sec14]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
@@ -83,4 +32,3 @@ correct. It just puts emphasis on the convenience of using this library.
 [rack]: http://rack.rubyforge.org/
 [test]: http://github.com/mjijackson/rack-accept/tree/master/test/
 [rubygems]: http://rubygems.org/
-[req]: api/classes/Rack/Accept/Request.html

data/doc/license.markdown

@@ -1,3 +1,6 @@
+License
+-------
+
 Copyright 2010 Michael J. I. Jackson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

data/doc/usage.markdown

@@ -0,0 +1,74 @@
+Usage
+-----
+
+Rack::Accept implements the Rack middleware interface and may be used with any
+Rack-based application. Simply insert the Rack::Accept module in your Rack
+middleware pipeline and access the [Rack::Accept::Request][req] object in the
+"rack-accept.request" environment key, as in the following example:
+
+    require 'rack/accept'
+
+    use Rack::Accept
+
+    app = lambda do |env|
+      accept = env['rack-accept.request']
+      response = Rack::Response.new
+
+      if accept.media_type?('text/html')
+        response['Content-Type'] = 'text/html'
+        response.write "<p>Hello. You accept text/html!</p>"
+      else
+        response['Content-Type'] = 'text/plain'
+        response.write "Apparently you don't accept text/html. Too bad."
+      end
+
+      response.finish
+    end
+
+    run app
+
+Rack::Accept can also construct a [406][406] response automatically if you set
+up the types of media, character sets, encoding, or languages your server is
+able to serve ahead of time.
+
+    require 'rack/accept'
+
+    use(Rack::Accept) do |accept|
+      # We only ever serve content in English or Japanese from this site, so if
+      # the user doesn't accept either of these we will respond with a 406.
+      #
+      # Note: +accept+ is an instance of Rack::Accept::Context.
+      accept.languages = %w< en jp >
+    end
+
+    app = ...
+
+    run app
+
+__Note:__ You should probably think about this very carefully before you use
+Rack::Accept in this way. Many user agents are careless about the types of
+Accept headers they send, and depend on apps not being too picky. Instead of
+automatically sending a 406, you should probably only send one when absolutely
+necessary.
+
+Additionally, Rack::Accept may be used outside of a Rack context to provide
+any Ruby app the ability to construct and interpret Accept headers.
+
+    require 'rack/accept'
+
+    mtype = Rack::Accept::MediaType.new
+    mtype.qvalues = { 'text/html' => 1, 'text/*' => 0.8, '*/*' => 0.5 }
+    mtype.to_s # => "Accept: text/html, text/*;q=0.8, */*;q=0.5"
+
+    cset = Rack::Accept::Charset.new('unicode-1-1, iso-8859-5;q=0.8')
+    cset.best_of(%w< iso-8859-5 unicode-1-1 >)  # => "unicode-1-1"
+    cset.accept?('iso-8859-1')                  # => true
+
+The very last line in this example may look like a mistake to someone not
+familiar with the intricacies of [the spec][sec14-3], but it's actually
+correct. It just puts emphasis on the convenience of using this library so you
+don't have to worry about these kinds of details.
+
+[req]: api/classes/Rack/Accept/Request.html
+[406]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
+[sec14-3]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3

data/lib/rack/accept.rb

@@ -3,7 +3,7 @@ require 'rack'
 module Rack::Accept
 
   # The current version of rack-accept.
-  VERSION = [0, 2]
+  VERSION = [0, 3]
 
   # Returns the current version of rack-accept as a string.
   def self.version
@@ -22,5 +22,6 @@ module Rack::Accept
   autoload :Language,   'rack/accept/language'
   autoload :MediaType,  'rack/accept/media_type'
   autoload :Request,    'rack/accept/request'
+  autoload :Response,   'rack/accept/response'
 
 end

data/lib/rack/accept/charset.rb

@@ -15,8 +15,7 @@ module Rack::Accept
       'Accept-Charset'
     end
 
-    # Determines the quality factor (qvalue) of the given +charset+,
-    # according to the specifications of the original header.
+    # Determines the quality factor (qvalue) of the given +charset+.
     def qvalue(charset)
       m = matches(charset)
       if m.empty?
@@ -26,8 +25,8 @@ module Rack::Accept
       end
     end
 
-    # Returns an array of character sets from the original header that match
-    # the given +charset+, ordered by precedence.
+    # Returns an array of character sets from this header that match the given
+    # +charset+, ordered by precedence.
     def matches(charset)
       values.select {|v|
         v == charset || v == '*'

data/lib/rack/accept/context.rb

@@ -3,18 +3,67 @@ module Rack::Accept
   # Implements the Rack middleware interface.
   class Context
 
+    # This error is raised when the server is not able to provide an acceptable
+    # response.
+    class AcceptError < StandardError; end
+
     attr_reader :app
 
     def initialize(app)
       @app = app
+      @checks = {}
+      @check_headers = []
       yield self if block_given?
     end
 
     # Inserts a new Rack::Accept::Request object into the environment before
     # handing the request to the app immediately downstream.
     def call(env)
-      env['rack-accept.request'] ||= Request.new(env)
+      request = env['rack-accept.request'] ||= Request.new(env)
+      check!(request) unless @checks.empty?
       @app.call(env)
+    rescue AcceptError
+      response = Response.new
+      response.not_acceptable!
+      response.finish
+    end
+
+    # Defines the types of media this server is able to serve.
+    def media_types=(media_types)
+      add_check(:media_type, media_types)
+    end
+
+    # Defines the character sets this server is able to serve.
+    def charsets=(charsets)
+      add_check(:charset, charsets)
+    end
+
+    # Defines the types of encodings this server is able to serve.
+    def encodings=(encodings)
+      add_check(:encoding, encodings)
+    end
+
+    # Defines the languages this server is able to serve.
+    def languages=(languages)
+      add_check(:language, languages)
+    end
+
+  private
+
+    def add_check(header_name, values)
+      @checks[header_name] ||= []
+      @checks[header_name].concat(values)
+      @check_headers << header_name unless @check_headers.include?(header_name)
+    end
+
+    # Raises an AcceptError if this server is not able to serve an acceptable
+    # response.
+    def check!(request)
+      @check_headers.each do |header_name|
+        values = @checks[header_name]
+        header = request.send(header_name)
+        raise AcceptError unless values.any? {|v| header.accept?(v) }
+      end
     end
 
   end

data/lib/rack/accept/encoding.rb

@@ -15,8 +15,7 @@ module Rack::Accept
       'Accept-Encoding'
     end
 
-    # Determines the quality factor (qvalue) of the given +encoding+,
-    # according to the specifications of the original header.
+    # Determines the quality factor (qvalue) of the given +encoding+.
     def qvalue(encoding)
       m = matches(encoding)
       if m.empty?
@@ -26,8 +25,8 @@ module Rack::Accept
       end
     end
 
-    # Returns an array of encodings from the original header that match
-    # the given +encoding+, ordered by precedence.
+    # Returns an array of encodings from this header that match the given
+    # +encoding+, ordered by precedence.
     def matches(encoding)
       values.select {|v|
         v == encoding || v == '*'

data/lib/rack/accept/language.rb

@@ -15,8 +15,7 @@ module Rack::Accept
       'Accept-Language'
     end
 
-    # Determines the quality factor (qvalue) of the given +language+,
-    # according to the specifications of the original header.
+    # Determines the quality factor (qvalue) of the given +language+.
     def qvalue(language)
       return 1 if @qvalues.empty?
       m = matches(language)
@@ -24,8 +23,8 @@ module Rack::Accept
       @qvalues[m.first]
     end
 
-    # Returns an array of languages from the original header that match
-    # the given +language+, ordered by precedence.
+    # Returns an array of languages from this header that match the given
+    # +language+, ordered by precedence.
     def matches(language)
       values.select {|v|
         v == language || v == '*' || (language.match(/^(.+?)-/) && v == $1)

data/lib/rack/accept/media_type.rb

@@ -15,8 +15,7 @@ module Rack::Accept
       'Accept'
     end
 
-    # Determines the quality factor (qvalue) of the given +media_type+,
-    # according to the specifications of the original header.
+    # Determines the quality factor (qvalue) of the given +media_type+.
     def qvalue(media_type)
       return 1 if @qvalues.empty?
       m = matches(media_type)
@@ -24,8 +23,8 @@ module Rack::Accept
       @qvalues[m.first]
     end
 
-    # Returns an array of media types from the original header that match
-    # the given +media_type+, ordered by precedence.
+    # Returns an array of media types from this header that match the given
+    # +media_type+, ordered by precedence.
     def matches(media_type)
       type, subtype, params = parse_media_type(media_type)
       values.select {|v|

data/lib/rack/accept/request.rb

@@ -1,14 +1,11 @@
+require 'rack/request'
+
 module Rack::Accept
 
   # A container class for convenience methods when Rack::Accept is used on the
-  # request level (as Rack middleware, for example). This class manages a
+  # request level as Rack middleware. Instances of this class also manage a
   # lightweight cache of various header instances to speed up execution.
-  #
-  # Request currently does not extend Rack::Request because that class
-  # currently provides some limited functionality when it comes to determining
-  # the proper encoding to use with a request and I didn't want to confuse
-  # users.
-  class Request
+  class Request < Rack::Request
 
     attr_reader :env
 

data/lib/rack/accept/response.rb

@@ -0,0 +1,21 @@
+require 'rack/response'
+
+module Rack::Accept
+
+  # The base class for responses issued by Rack::Accept.
+  class Response < Rack::Response
+
+    # Marks this response as being unacceptable and clears the response body.
+    #
+    # Note: The HTTP spec advises servers to respond with an "entity" that
+    # describes acceptable parameters, but it fails to go into detail about its
+    # implementation. Thus, it is up to the user of this library to create such
+    # an entity if one is desired.
+    def not_acceptable!
+      self.status = 406
+      self.body = []
+      header['Content-Length'] = '0'
+    end
+
+  end
+end

data/test/charset_test.rb

@@ -22,6 +22,9 @@ class CharsetTest < Test::Unit::TestCase
     c = C.new('iso-8859-1;q=0, *;q=0.5')
     assert_equal(0.5, c.qvalue('iso-8859-5'))
     assert_equal(0, c.qvalue('iso-8859-1'))
+
+    c = C.new('*;q=0')
+    assert_equal(0, c.qvalue('iso-8859-1'))
   end
 
   def test_matches

data/test/context_test.rb

@@ -0,0 +1,59 @@
+require File.dirname(__FILE__) + '/helper'
+
+class ContextTest < Test::Unit::TestCase
+
+  def media_types; Proc.new {|c| c.media_types = %w< text/html > } end
+  def charsets;    Proc.new {|c| c.charsets = %w< iso-8859-5 > }   end
+  def encodings;   Proc.new {|c| c.encodings = %w< gzip > }        end
+  def languages;   Proc.new {|c| c.languages = %w< en > }          end
+
+  def test_empty
+    request
+    assert_equal(200, status)
+  end
+
+  def test_media_types
+    request('HTTP_ACCEPT' => 'text/html')
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT' => 'text/html', &media_types)
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT' => 'text/plain', &media_types)
+    assert_equal(406, status)
+  end
+
+  def test_charsets
+    request('HTTP_ACCEPT_CHARSET' => 'iso-8859-5')
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_CHARSET' => 'iso-8859-5', &charsets)
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_CHARSET' => 'unicode-1-1', &charsets)
+    assert_equal(406, status)
+  end
+
+  def test_encodings
+    request('HTTP_ACCEPT_ENCODING' => 'gzip')
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_ENCODING' => 'gzip', &encodings)
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_ENCODING' => 'compress', &encodings)
+    assert_equal(406, status)
+  end
+
+  def test_languages
+    request('HTTP_ACCEPT_LANGUAGE' => 'en')
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_LANGUAGE' => 'en', &languages)
+    assert_equal(200, status)
+
+    request('HTTP_ACCEPT_LANGUAGE' => 'jp', &languages)
+    assert_equal(406, status)
+  end
+
+end

data/test/helper.rb

@@ -15,3 +15,24 @@ $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
 require 'test/unit'
 require 'rack/accept'
+
+class Test::Unit::TestCase
+  attr_reader :context
+  attr_reader :response
+
+  def status
+    @response && @response.status
+  end
+
+  def request(env={}, method='GET', uri='/')
+    @context = Rack::Accept.new(fake_app)
+    yield @context if block_given?
+    mock_request = Rack::MockRequest.new(@context)
+    @response = mock_request.request(method.to_s.upcase, uri, env)
+    @response
+  end
+
+  def fake_app(status=200, headers={}, body=[])
+    lambda {|env| Rack::Response.new(body, status, headers).finish }
+  end
+end

metadata

@@ -4,8 +4,8 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
-  version: "0.2"
+  - 3
+  version: "0.3"
 platform: ruby
 authors: 
 - Michael J. I. Jackson
@@ -58,8 +58,10 @@ files:
 - lib/rack/accept/language.rb
 - lib/rack/accept/media_type.rb
 - lib/rack/accept/request.rb
+- lib/rack/accept/response.rb
 - lib/rack/accept.rb
 - test/charset_test.rb
+- test/context_test.rb
 - test/encoding_test.rb
 - test/header_test.rb
 - test/helper.rb
@@ -70,6 +72,7 @@ files:
 - doc/assets/style.css
 - doc/index.markdown
 - doc/license.markdown
+- doc/usage.markdown
 - CHANGES
 - .gemspec
 - Rakefile
@@ -111,6 +114,7 @@ specification_version: 3
 summary: HTTP Accept* for Ruby/Rack
 test_files: 
 - test/charset_test.rb
+- test/context_test.rb
 - test/encoding_test.rb
 - test/header_test.rb
 - test/language_test.rb