rack-accept_headers 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4fe24376b339f7d18f11034851b747619af22f17
+  data.tar.gz: d3b43e1effbf379bec2ef4a2256721bb3bbe2590
+SHA512:
+  metadata.gz: adad5ec925d71f611c8ae25d88d18a98c2dbbbdc063c8134132c4e3b82c951a51ad79245d9e88d6e093ab65ee28aabd0d177f201ba84cd8259516e8b937a337c
+  data.tar.gz: 99110a7283ce5e03ad5d5902608cb7a4cea499a20a0dbcae4dea528896b513f71f60d482778bd193d5c50d3ac1c5909d06a97f284df6b5792d44e6d1fa35d779

data/.gitignore

@@ -0,0 +1,18 @@
+.DS_Store
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+/doc
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - jruby
+  - rbx
+  - ruby-head
+  - jruby-head
+
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - rvm: rbx

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+## 0.5.x
+
+  * Add accept-extension parameter support
+  * Add Guardfile
+  * Add Gemfile
+  * Switch from Test::Unit to Minitest
+  * Added travis-ci support
+
+## 0.4.3 / July 29, 2010
+
+  * Added support for Ruby 1.9.2
+
+## 0.4 / April 5, 2010
+
+  * Added support for media type queries with multiple range parameters
+  * Changed Rack::AcceptHeaders::Header#sort method to return only single values
+    and moved previous functionality to Rack::AcceptHeaders::Header#sort_with_qvalues
+
+## 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::AcceptHeaders::Header module
+  * Many improvements to the documentation
+
+## 0.1.1 / April 1, 2010
+
+  * Whoops, forgot to require Rack. :]
+
+## 0.1 / April 1, 2010
+
+  * Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rack-accept_headers.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb})
+  watch(%r{^lib/rack-accept_headers/(.*/)?([^/]+)\.rb})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb})      { 'test' }
+
+  # with Minitest::Spec
+  watch(%r{^spec/(.*)_spec\.rb})
+  watch(%r{^lib/rack-accept_headers/(.+)\.rb})         { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb}) { 'spec' }
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Michael Jackson
+
+MIT License
+
+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,198 @@
+[![Build Status](https://travis-ci.org/kamui/rack-accept_headers.png)](https://travis-ci.org/kamui/rack-accept_headers)
+
+**Rack::AcceptHeaders** is a suite of tools for Ruby/Rack applications that eases the
+complexity of building and interpreting the Accept* family of [HTTP request headers][rfc].
+
+Some features of the library are:
+
+  * Strict adherence to [RFC 2616][rfc], specifically [section 14][rfc-sec14]
+  * Full support for the [Accept][rfc-sec14-1], [Accept-Charset][rfc-sec14-2],
+    [Accept-Encoding][rfc-sec14-3], and [Accept-Language][rfc-sec14-4] HTTP
+    request headers
+  * May be used as [Rack][rack] middleware or standalone
+  * A comprehensive [test suite][test] that covers many edge cases
+
+[rfc]: http://www.w3.org/Protocols/rfc2616/rfc2616.html
+[rfc-sec14]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
+[rfc-sec14-1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1
+[rfc-sec14-2]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2
+[rfc-sec14-3]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+[rfc-sec14-4]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
+[rack]: http://rack.rubyforge.org/
+[test]: http://github.com/kamui/rack-accept_headers/tree/master/test/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'rack-accept_headers'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rack-accept_headers
+
+Or install it from a local copy:
+
+    $ git clone git://github.com/kamui/rack-accept_headers.git
+    $ cd rack-accept_headers
+    $ rake package
+    $ rake install
+
+## Usage
+
+**Rack::AcceptHeaders** implements the Rack middleware interface and may be used with any
+Rack-based application. Simply insert the `Rack::AcceptHeaders` module in your Rack
+middleware pipeline and access the `Rack::AcceptHeaders::Request` object in the
+`rack-accept_headers.request` environment key, as in the following example.
+
+```ruby
+require 'rack/accept_headers'
+
+use Rack::AcceptHeaders
+
+app = lambda do |env|
+  accept = env['rack-accept_headers.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::AcceptHeaders** can also construct automatic [406][406] responses if you set up
+the types of media, character sets, encoding, or languages your server is able
+to serve ahead of time. If you pass a configuration block to your `use`
+statement it will yield the `Rack::AcceptHeaders::Context` object that is used for that
+invocation.
+
+[406]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
+
+```ruby
+require 'rack/accept_headers'
+
+use(Rack::AcceptHeaders) do |context|
+  # 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.
+  context.languages = %w< en jp >
+end
+
+app = ...
+
+run app
+```
+
+**Note:** _You should think carefully before using Rack::AcceptHeaders 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._
+
+**Rack::AcceptHeaders** supports accept-extension parameter support. Here's an
+example:
+
+```ruby
+require 'rack/accept_headers'
+
+use Rack::AcceptHeaders
+
+app = lambda do |env|
+    SUPPORTED_MEDIA_TYPES = {
+      "text/html" => :html
+      "application/json" => :json,
+      "text/xml" => :xml
+    }
+
+  accept = env['rack-accept_headers.request']
+  response = Rack::Response.new
+
+  if accept
+    media_type = accept.media_type.best_of(SUPPORTED_MEDIA_TYPES.keys)
+
+    # Here, I would return a 415 Unsupported media type, if media_type is nil
+    # The unsupported_media_type call is left unimplemented here
+    # unsupported_media_type unless media_type
+
+    # To output the media_type symbol
+    # puts SUPPORTED_MEDIA_TYPES[media_type]
+
+    # To return a hash of accept-extension params for the given media type
+    # puts accept.media_type.params(media_type)
+
+    response['Content-Type'] = media_type
+    response.write %Q{{ "message" : "Hello. You accept #{media_type}" }}
+  else
+    media_type = "*/*"
+    response['Content-Type'] = SUPPORTED_MEDIA_TYPES.keys.first
+    response.write "Defaulting to #{response['Content-Type']}."
+  end
+
+  response.finish
+end
+
+run app
+```
+
+So, given this `Accept` header:
+
+```
+Accept: application/json;version=1.0;q=0.1
+```
+
+```ruby
+accept = env['rack-accept_headers.request']
+params = accept.media_type.params['application/json')
+```
+
+The `params` hash will end up with this value:
+
+```ruby
+{
+  "application/json" : {
+    "q" : 0.1,
+    "version" : "1.0"
+  }
+}
+```
+
+Additionally, **Rack::AcceptHeaders** may be used outside of a Rack context to provide
+any Ruby app the ability to construct and interpret Accept headers.
+
+```ruby
+require 'rack/accept_headers'
+
+mtype = Rack::AcceptHeaders::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::AcceptHeaders::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][rfc-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.
+
+## Four-letter Words
+
+  - Spec: [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html][rfc-sec14]
+  - Code: [http://github.com/kamui/rack-accept_headers][code]
+  - Bugs: [http://github.com/kamui/rack-accept_headers/issues][bugs]
+  - Docs: [http://rdoc.info/github/kamui/rack-accept_headers][docs]
+
+[code]: http://github.com/kamui/rack-accept_headers
+[bugs]: http://github.com/kamui/rack-accept_headers/issues
+[docs]: http://rdoc.info/github/kamui/rack-accept_headers

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList['spec/**/*_spec.rb']
+  t.verbose = true
+end
+
+task default: :test

data/lib/rack/accept_headers/charset.rb

@@ -0,0 +1,36 @@
+module Rack::AcceptHeaders
+  # Represents an HTTP Accept-Charset header according to the HTTP 1.1
+  # specification, and provides several convenience methods for determining
+  # acceptable character sets.
+  #
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.2
+  class Charset
+    include Header
+
+    # The name of this header.
+    def name
+      'Accept-Charset'
+    end
+
+    # Determines the quality factor (qvalue) of the given +charset+.
+    def qvalue(charset)
+      m = matches(charset)
+      if m.empty?
+        charset == 'iso-8859-1' ? 1 : 0
+      else
+        normalize_qvalue(@qvalues[m.first])
+      end
+    end
+
+    # 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 == '*'
+      }.sort {|a, b|
+        # "*" gets least precedence, any others should be equal.
+        a == '*' ? 1 : (b == '*' ? -1 : 0)
+      }
+    end
+  end
+end

data/lib/rack/accept_headers/context.rb

@@ -0,0 +1,67 @@
+module Rack::AcceptHeaders
+  # 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::AcceptHeaders::Request object into the environment before
+    # handing the request to the app immediately downstream.
+    def call(env)
+      request = env['rack-accept_headers.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
+end

data/lib/rack/accept_headers/encoding.rb

@@ -0,0 +1,36 @@
+module Rack::AcceptHeaders
+  # Represents an HTTP Accept-Encoding header according to the HTTP 1.1
+  # specification, and provides several convenience methods for determining
+  # acceptable content encodings.
+  #
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
+  class Encoding
+    include Header
+
+    # The name of this header.
+    def name
+      'Accept-Encoding'
+    end
+
+    # Determines the quality factor (qvalue) of the given +encoding+.
+    def qvalue(encoding)
+      m = matches(encoding)
+      if m.empty?
+        encoding == 'identity' ? 1 : 0
+      else
+        normalize_qvalue(@qvalues[m.first])
+      end
+    end
+
+    # 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 == '*'
+      }.sort {|a, b|
+        # "*" gets least precedence, any others should be equal.
+        a == '*' ? 1 : (b == '*' ? -1 : 0)
+      }
+    end
+  end
+end

data/lib/rack/accept_headers/header.rb

@@ -0,0 +1,149 @@
+module Rack::AcceptHeaders
+  # Contains methods that are useful for working with Accept-style HTTP
+  # headers. The MediaType, Charset, Encoding, and Language classes all mixin
+  # this module.
+  module Header
+    class InvalidHeader < StandardError; end
+
+    # Parses the value of an Accept-style request header into a hash of
+    # acceptable values and their respective quality factors (qvalues). The
+    # +join+ method may be used on the resulting hash to obtain a header
+    # string that is the semantic equivalent of the one provided.
+    def parse(header)
+      qvalues = {}
+
+      header.to_s.split(',').each do |part|
+        m = /^\s*([^\s,]+?)(?:\s*;\s*q\s*=\s*(\d+(?:\.\d+)?))?$/.match(part)
+
+        if m
+          qvalues[m[1].downcase] = normalize_qvalue((m[2] || 1).to_f)
+        else
+          raise InvalidHeader, "Invalid header value: #{part.inspect}"
+        end
+      end
+
+      qvalues
+    end
+    module_function :parse
+
+    # Returns a string suitable for use as the value of an Accept-style HTTP
+    # header from the map of acceptable values to their respective quality
+    # factors (qvalues). The +parse+ method may be used on the resulting string
+    # to obtain a hash that is the equivalent of the one provided.
+    def join(qvalues)
+      qvalues.map {|k, v| k + (v == 1 ? '' : ";q=#{v}") }.join(', ')
+    end
+    module_function :join
+
+    # Parses a media type string into its relevant pieces. The return value
+    # will be an array with three values: 1) the content type, 2) the content
+    # subtype, and 3) the media type parameters. An empty array is returned if
+    # no match can be made.
+    def parse_media_type(media_type)
+      m = media_type.to_s.match(/^\s*([a-zA-Z*]+)\s*\/\s*([a-zA-Z0-9*\-.+]+)\s*(?:;(.+))?$/)
+      m ? [m[1].downcase, m[2].downcase, m[3] || ''] : []
+    end
+    module_function :parse_media_type
+
+    # Parses a string of media type range parameters into a hash of parameters
+    # to their respective values.
+    def parse_range_params(params)
+      params.split(';').inject({'q' => '1'}) do |m, p|
+        k, v = p.split('=', 2)
+        m[k.strip] = v.strip if v
+        m
+      end
+    end
+    module_function :parse_range_params
+
+    # Converts 1.0 and 0.0 qvalues to 1 and 0 respectively. Used to maintain
+    # consistency across qvalue methods.
+    def normalize_qvalue(q)
+      (q == 1 || q == 0) && q.is_a?(Float) ? q.to_i : q
+    end
+    module_function :normalize_qvalue
+
+    module PublicInstanceMethods
+      # A table of all values of this header to their respective quality
+      # factors (qvalues).
+      attr_accessor :qvalues
+
+      def initialize(header='')
+        @qvalues = parse(header)
+      end
+
+      # The name of this header. Should be overridden in classes that mixin
+      # this module.
+      def name
+        ''
+      end
+
+      # Returns the quality factor (qvalue) of the given +value+. Should be
+      # overridden in classes that mixin this module.
+      def qvalue(value)
+        1
+      end
+
+      # Returns the value of this header as a string.
+      def value
+        join(@qvalues)
+      end
+
+      # Returns an array of all values of this header, in no particular order.
+      def values
+        @qvalues.keys
+      end
+
+      # Determines if the given +value+ is acceptable (does not have a qvalue
+      # of 0) according to this header.
+      def accept?(value)
+        qvalue(value) != 0
+      end
+
+      # Returns a copy of the given +values+ array, sorted by quality factor
+      # (qvalue). Each element of the returned array is itself an array
+      # containing two objects: 1) the value's qvalue and 2) the original
+      # value.
+      #
+      # It is important to note that this sort is a "stable sort". In other
+      # words, the order of the original values is preserved so long as the
+      # qvalue for each is the same. This expectation can be useful when
+      # trying to determine which of a variety of options has the highest
+      # qvalue. If the user prefers using one option over another (for any
+      # number of reasons), he should put it first in +values+. He may then
+      # use the first result with confidence that it is both most acceptable
+      # to the client and most convenient for him as well.
+      def sort_with_qvalues(values, keep_unacceptables=true)
+        qvalues = {}
+        values.each do |v|
+          q = qvalue(v)
+          if q != 0 || keep_unacceptables
+            qvalues[q] ||= []
+            qvalues[q] << v
+          end
+        end
+        order = qvalues.keys.sort.reverse
+        order.inject([]) {|m, q| m.concat(qvalues[q].map {|v| [q, v] }) }
+      end
+
+      # Sorts the given +values+ according to the qvalue of each while
+      # preserving the original order. See #sort_with_qvalues for more
+      # information on exactly how the sort is performed.
+      def sort(values, keep_unacceptables=false)
+        sort_with_qvalues(values, keep_unacceptables).map {|q, v| v }
+      end
+
+      # A shortcut for retrieving the first result of #sort.
+      def best_of(values, keep_unacceptables=false)
+        sort(values, keep_unacceptables).first
+      end
+
+      # Returns a string representation of this header.
+      def to_s
+        [name, value].join(': ')
+      end
+    end
+
+    include PublicInstanceMethods
+  end
+end

data/lib/rack/accept_headers/language.rb

@@ -0,0 +1,36 @@
+module Rack::AcceptHeaders
+  # Represents an HTTP Accept-Language header according to the HTTP 1.1
+  # specification, and provides several convenience methods for determining
+  # acceptable content languages.
+  #
+  # http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4
+  class Language
+    include Header
+    attr_writer :first_level_match
+
+    # The name of this header.
+    def name
+      'Accept-Language'
+    end
+
+    # Determines the quality factor (qvalue) of the given +language+.
+    def qvalue(language)
+      return 1 if @qvalues.empty?
+      m = matches(language)
+      return 0 if m.empty?
+      normalize_qvalue(@qvalues[m.first])
+    end
+
+    # Returns an array of languages from this header that match the given
+    # +language+, ordered by precedence.
+    def matches(language)
+      values.select {|v|
+        v = v.match(/^(.+?)-/) ? $1 : v if @first_level_match
+        v == language || v == '*' || (language.match(/^(.+?)-/) && v == $1)
+      }.sort {|a, b|
+        # "*" gets least precedence, any others are compared based on length.
+        a == '*' ? -1 : (b == '*' ? 1 : a.length <=> b.length)
+      }.reverse
+    end
+  end
+end