rackful 0.2.0 → 0.2.1

data/lib/rackful/request.rb

@@ -1,76 +1,99 @@
 # encoding: utf-8
 
+# Required for parsing:
+require 'rackful/global.rb'
+
+# Required for running:
 
 module Rackful
 
 # Subclass of {Rack::Request}, augmented for Rackful requests.
+#
+# This class mixes in module `StatusCodes` for convenience, as explained in the
+# {StatusCodes StatusCodes documentation}.
 class Request < Rack::Request
 
+  include StatusCodes
 
   def initialize *args
     super( *args )
   end
 
 
-=begin markdown
-Shortcut to {Server#resource_at}.
-
-(see Server#resource_at)
-@return (see Server#resource_at)
-@raise (see Server#resource_at)
-=end
-  def resource_at *args
-    env['rackful.server'].resource_at( *args )
+  # Calls the code block passed to the {#initialize constructor}.
+  # @param uri [URI::HTTP, String]
+  # @return [Resource]
+  # @raise [HTTP404NotFound]
+  def resource_at( uri )
+    uri = uri.kind_of?( URI::Generic ) ? uri.dup : URI(uri).normalize
+    uri.query = nil
+    retval = env['rackful.resource_registry'].call( uri )
+    raise HTTP404NotFound unless retval
+    retval
   end
 
-
-=begin markdown
-Similar to the HTTP/1.1 `Content-Location:` header. Contains the canonical url
-of the requested resource, which may differ from {#url}.
-
-If parameter +full_path+ is provided, than this is used instead of the current
-request’s full path (which is the path plus optional query string).
-@return [URI::Generic]
-=end
-  def canonical_uri
-    env['rackful.canonical_uri'] ||= URI( self.url ).normalize
+  # The current request’s main resource.
+  #
+  # As a side effect, {#canonical_uri} can be changed.
+  # @return [Resource]
+  # @raise [HTTP404NotFound] from {#resource_at}
+  def resource
+    @rackful_request_resource ||= begin
+      c = URI(url).normalize
+      retval = resource_at(c)
+      c += retval.uri
+      c.query = query_string unless query_string.empty?
+      env['rackful.canonical_uri'] = c
+      retval
+    end
   end
 
 
-=begin markdown
-The canonical url of the requested resource. This may differ from {#url}.
-
-@todo Change URI::Generic into URI::HTTP
-@param uri [URI::Generic, String]
-@return [URI::Generic, String] `uri`
-=end
-  def canonical_uri=( uri )
-    env['rackful.canonical_uri'] =
-      uri.kind_of?( URI::Generic ) ? URI(uri) : URI( uri ).normalize
-    uri
+  # Similar to the HTTP/1.1 `Content-Location:` header. Contains the canonical url
+  # of the requested resource, which may differ from {#url}.
+  # 
+  # If parameter +full_path+ is provided, than this is used instead of the current
+  # request’s full path (which is the path plus optional query string).
+  # @return [URI::Generic]
+  def canonical_uri
+    env['rackful.canonical_uri'] || URI( self.url ).normalize
   end
 
 
-=begin markdown
-Assert all <tt>If-*</tt> request headers.
-@return [void]
-@raise [HTTP304NotModified, HTTP400BadRequest, HTTP404NotFound, HTTP412PreconditionFailed]
-  with the following meanings:
-
-  -   `304 Not Modified`
-  -   `400 Bad Request` Couldn't parse one or more <tt>If-*</tt> headers, or a
-      weak validator comparison was requested for methods other than `GET` or
-      `HEAD`.
-  -   `404 Not Found`
-  -   `412 Precondition Failed`
-@see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616, section 13.3.3
-  for details about weak and strong validator comparison.
-@todo Implement support for the `If-Range:` header.
-=end
-  def assert_if_headers resource
+  # The canonical url of the requested resource. This may differ from {#url}.
+  # 
+  # @todo Change URI::Generic into URI::HTTP
+  # @param uri [URI::Generic, String]
+  # @return [URI::Generic, String] `uri`
+  #   def canonical_uri=( uri )
+  #     env['rackful.canonical_uri'] =
+  #       uri.kind_of?( URI::Generic ) ? uri.dup : URI( uri ).normalize
+  #     uri
+  #   end
+
+
+  # Assert all <tt>If-*</tt> request headers.
+  # @return [void]
+  # @raise [HTTP304NotModified, HTTP400BadRequest, HTTP404NotFound, HTTP412PreconditionFailed]
+  #   with the following meanings:
+  # 
+  #   -   `304 Not Modified`
+  #   -   `400 Bad Request` Couldn't parse one or more <tt>If-*</tt> headers, or a
+  #       weak validator comparison was requested for methods other than `GET` or
+  #       `HEAD`.
+  #   -   `404 Not Found`
+  #   -   `412 Precondition Failed`
+  # @see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616, section 13.3.3
+  #   for details about weak and strong validator comparison.
+  # @todo Implement support for the `If-Range:` header.
+  def assert_if_headers
     #raise HTTP501NotImplemented, 'If-Range: request header is not supported.' \
     #  if env.key? 'HTTP_IF_RANGE'
-    empty = resource.empty?
+    begin
+      empty = resource.empty?
+    rescue HTTP404NotFound => e
+      empty = true
+    end
     etag =
       if ! empty && resource.respond_to?(:get_etag)
         resource.get_etag
@@ -146,47 +169,6 @@ Assert all <tt>If-*</tt> request headers.
   end
 
 
-=begin markdown
-The best media type to represent a resource, given the current HTTP request.
-@param resource [Resource] the resource to represent
-@param require_match [Boolean] this flag determines what must happen if the
-  client sent an `Accept:` header, and we cannot serve any of the acceptable
-  media types. **`TRUE`** means that an {HTTP406NotAcceptable} exception is
-  raised. **`FALSE`** means that the content-type with the highest quality is
-  returned.
-@return [String] content-type
-@raise [HTTP406NotAcceptable]
-@api private
-=end
-  def best_content_type( resource, require_match = true )
-    q_values = self.q_values
-    if q_values.empty?
-      return resource.all_serializers.values.sort_by(&:last).last[0]::CONTENT_TYPES[0]
-    end
-    matches = []
-    q_values.each {
-      |accept_media_type, accept_quality|
-      resource.all_serializers.each_pair {
-        |content_type, v|
-        quality = v[1]
-        media_type = content_type.split(';').first.strip
-        if File.fnmatch( accept_media_type, media_type )
-          matches << [ content_type, accept_quality * quality ]
-        end
-      }
-    }
-    if matches.empty?
-      if require_match
-        raise( HTTP406NotAcceptable, resource.all_serializers.keys() )
-      else
-        return resource.all_serializers.values.sort_by(&:last).
-          last.first::CONTENT_TYPES.first
-      end
-    end
-    matches.sort_by(&:last).last.first
-  end
-
-
   # Hash of acceptable media types and their qualities.
   #
   # This method parses the HTTP/1.1 `Accept:` header. If no acceptable media
@@ -212,13 +194,11 @@ The best media type to represent a resource, given the current HTTP request.
   end # def accept
 
 
-=begin markdown
-@!method if_match()
-Parses the HTTP/1.1 `If-Match:` header.
-@return [nil, Array<String>]
-@see http://tools.ietf.org/html/rfc2616#section-14.24 RFC2616, section 14.24
-@see #if_none_match
-=end
+  # @!method if_match()
+  # Parses the HTTP/1.1 `If-Match:` header.
+  # @return [nil, Array<String>]
+  # @see http://tools.ietf.org/html/rfc2616#section-14.24 RFC2616, section 14.24
+  # @see #if_none_match
   def if_match none = false
     header = env["HTTP_IF_#{ none ? 'NONE_' : '' }MATCH"]
     return nil unless header
@@ -232,23 +212,19 @@ Parses the HTTP/1.1 `If-Match:` header.
   end
 
 
-=begin markdown
-Parses the HTTP/1.1 `If-None-Match:` header.
-@return [nil, Array<String>]
-@see http://tools.ietf.org/html/rfc2616#section-14.26 RFC2616, section 14.26
-@see #if_match
-=end
+  # Parses the HTTP/1.1 `If-None-Match:` header.
+  # @return [nil, Array<String>]
+  # @see http://tools.ietf.org/html/rfc2616#section-14.26 RFC2616, section 14.26
+  # @see #if_match
   def if_none_match
     self.if_match true
   end
 
 
-=begin markdown
-@!method if_modified_since()
-@return [nil, Time]
-@see http://tools.ietf.org/html/rfc2616#section-14.25 RFC2616, section 14.25
-@see #if_unmodified_since
-=end
+  # @!method if_modified_since()
+  # @return [nil, Time]
+  # @see http://tools.ietf.org/html/rfc2616#section-14.25 RFC2616, section 14.25
+  # @see #if_unmodified_since
   def if_modified_since unmodified = false
     header = env["HTTP_IF_#{ unmodified ? 'UN' : '' }MODIFIED_SINCE"]
     return nil unless header
@@ -261,29 +237,25 @@ Parses the HTTP/1.1 `If-None-Match:` header.
   end
 
 
-=begin markdown
-@return [nil, Time]
-@see http://tools.ietf.org/html/rfc2616#section-14.28 RFC2616, section 14.28
-@see #if_modified_since
-=end
+  # @return [nil, Time]
+  # @see http://tools.ietf.org/html/rfc2616#section-14.28 RFC2616, section 14.28
+  # @see #if_modified_since
   def if_unmodified_since
     self.if_modified_since true
   end
 
 
-=begin markdown
-Does any of the tags in `etags` match `etag`?
-@param etag [#to_s]
-@param etags [#to_a]
-@example
-  etag = '"foo"'
-  etags = [ 'W/"foo"', '"bar"' ]
-  validate_etag etag, etags
-  #> true
-@return [Boolean]
-@see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616 section 13.3.3
-  for details about weak and strong validator comparison.
-=end
+  # Does any of the tags in `etags` match `etag`?
+  # @param etag [#to_s]
+  # @param etags [#to_a]
+  # @example
+  #   etag = '"foo"'
+  #   etags = [ 'W/"foo"', '"bar"' ]
+  #   validate_etag etag, etags
+  #   #> true
+  # @return [Boolean]
+  # @see http://tools.ietf.org/html/rfc2616#section-13.3.3 RFC2616 section 13.3.3
+  #   for details about weak and strong validator comparison.
   def validate_etag etag, etags
     etag = etag.to_s
     match = etags.to_a.detect do
@@ -304,6 +276,5 @@ Does any of the tags in `etags` match `etag`?
   end
 
 
-end # class Request
-
+end # class Rackful::Request
 end # module Rackful

data/lib/rackful/resource.rb

@@ -1,21 +1,80 @@
 # encoding: utf-8
 
-require 'forwardable'
+# Required for parsing:
+require 'rackful/global.rb'
+
+# Required for running:
 
 module Rackful
 
 # Abstract superclass for resources served by {Server}.
+#
+# This class mixes in module `StatusCodes` for convenience, as explained in the
+# {StatusCodes StatusCodes documentation}.
 # @see Server
 # @todo better documentation
 # @abstract Realizations must implement…
-class Resource
-
-  class << self
+#
+# @!method do_METHOD( Request, Rack::Response )
+#   HTTP/1.1 method handler.
+# 
+#   To handle certain HTTP/1.1 request methods, resources must implement methods
+#   called `do_<HTTP_METHOD>`.
+#   @example Handling `PATCH` requests
+#     def do_PATCH request, response
+#       response['Content-Type'] = 'text/plain'
+#       response.body = [ 'Hello world!' ]
+#     end
+#   @abstract
+#   @return [void]
+#   @raise [HTTPStatus, RuntimeError]
+#
+# @!attribute [r] get_etag
+#   The ETag of this resource.
+# 
+#   If your classes implement this method, then an `ETag:` response
+#   header is generated automatically when appropriate. This allows clients to
+#   perform conditional requests, by sending an `If-Match:` or
+#   `If-None-Match:` request header. These conditions are then asserted
+#   for you automatically.
+# 
+#   Make sure your entity tag is a properly formatted string. In ABNF:
+# 
+#       entity-tag    = [ "W/" ] quoted-string
+#       quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
+#       qdtext        = <any TEXT except <">>
+#       quoted-pair   = "\" CHAR
+# 
+#   @abstract
+#   @return [String]
+#   @see http://tools.ietf.org/html/rfc2616#section-14.19 RFC2616 section 14.19
+# 
+# @!attribute [r] get_last_modified
+#   Last modification of this resource.
+# 
+#   If your classes implement this method, then a `Last-Modified:` response
+#   header is generated automatically when appropriate. This allows clients to
+#   perform conditional requests, by sending an `If-Modified-Since:` or
+#   `If-Unmodified-Since:` request header. These conditions are then asserted
+#   for you automatically.
+#   @abstract
+#   @return [Array<(Time, Boolean)>] The timestamp, and a flag indicating if the
+#     timestamp is a strong validator.
+#   @see http://tools.ietf.org/html/rfc2616#section-14.29 RFC2616 section 14.29
+# 
+# @!method destroy()
+#   @return [Hash, nil] an optional header hash.
+module Resource
+  
+  include StatusCodes
+
+  module ClassMethods
 
 
   # Meta-programmer method.
   # @example Have your resource rendered in XML and JSON
   #   class MyResource
+  #     include Rackful::Resource
   #     add_serializer MyResource2XML
   #     add_serializer MyResource2JSON, 0.5
   #   end
@@ -26,124 +85,124 @@ class Resource
     quality = quality.to_f
     quality = 1.0 if quality > 1.0
     quality = 0.0 if quality < 0.0
-    s = [serializer, quality]
-    serializer::CONTENT_TYPES.each {
-    |content_type|
-      self.serializers[content_type.to_s] = s
-    }
+    sq = [serializer, quality]
+    serializer.content_types.each do
+      |content_type|
+      unless  ( old = serializers[content_type] ) and # @formatter:off
+              old[1] > quality # @formatter:on
+        serializers[content_type] = sq
+      end
+    end
     self
   end
 
 
   # Meta-programmer method.
+  #
+  # A parser is an object or a class that implements to the following two methods:
+  #
+  # 1.  (Array<String>) media_types()
+  # 2.  (void) parse(Request, Resource)
+  #
+  # The first call returns a list of media types this parser can parse, for example:
+  # `[ 'text/html', 'application/xhtml+xml' ]`. The second call parses a request
+  # in the context of a certain resource.
   # @example Have your resource accept XHTML in `PUT` requests
   #   class MyResource
   #     include Rackful::Resource
   #     add_parser Rackful::Parser::XHTML, :PUT
   #   end
-  # @param parser [Class] an implementation (ie. subclass) of {Parser}
+  # @param parser [#parse, #media_types] an implementation (ie. subclass) of {Parser}
   # @param method [#to_sym] For example: `:PUT` or `:POST`
   # @return [self]
   def add_parser parser, method = :PUT
     method = method.to_sym
-    self.parsers[method] ||= []
-    self.parsers[method] << parser
-    self.parsers[method].uniq!
+    parsers[method] ||= []
+    parser.media_types.each do
+      |mt|
+      parsers[method] << [mt, parser]
+    end
+    parsers[method].uniq!
     self
   end
 
 
-  # All parsers added to _this_ class.  Ie. not including parsers added
-  # to parent classes.
-  # @return [Hash{Symbol => Array<Class>}] A hash of lists of {Parser} classes,
-  #   indexed by HTTP method.
-  # @api private
-  def parsers
-    # The single '@' on the following line is on purpose!
-    @rackful_resource_parsers ||= {}
-  end
-
-
-  # All serializers added to _this_ class.  Ie. not including serializers added
-  # to parent classes.
-  # @return [Hash{Serializer => Float}]
-  # @api private
-  def serializers
-    # The single '@' on the following line is on purpose!
-    @rackful_resource_serializers ||= {}
-  end
-
-
   # All parsers for this class, including parsers added to parent classes.
   # The result of this method is cached, which will interfere with code reloading.
-  # @param method [#to_sym] For example: `:PUT` or `:POST`
   # @return [Hash{Symbol => Array<Class>}]
   # @api private
   def all_parsers
     # The single '@' on the following line is on purpose!
     @rackful_resource_all_parsers ||=
       if self.superclass.respond_to?(:all_parsers)
-        self.parsers.merge( self.superclass.all_parsers ) do
+        self.superclass.all_parsers.merge( parsers ) do
           |key, oldval, newval|
           ( oldval + newval ).uniq
         end
       else
-        self.parsers
+        parsers
       end
   end
 
 
   # All serializers for this class, including those added to parent classes.
   # The result of this method is cached, which will interfere with code reloading.
-  # @return [Hash{Serializer => Float}] The float indicates the quality of each
-  #   serializer in the interval [0,1]
+  # @return [Hash{ String( content_type ) => Array( Serializer, Float(quality) ) }]
   # @api private
   def all_serializers
     # The single '@' on the following line is on purpose!
     @rackful_resource_all_serializers ||=
       if self.superclass.respond_to?(:all_serializers)
-        self.superclass.all_serializers.merge( self.serializers ) do
+        self.superclass.all_serializers.merge( serializers ) do
           |key, oldval, newval|
           newval[1] >= oldval[1] ? newval : oldval
         end
       else
-        self.serializers
+        serializers
       end
   end
 
+  private
 
-  end # module ClassMethods
+  # All parsers added to _this_ class.  Ie. not including parsers added
+  # to parent classes.
+  # @return [Hash{Symbol => Array<Class>}] A hash of lists of {Parser} classes,
+  #   indexed by HTTP method.
+  # @api private
+  def parsers
+    # The single '@' on the following line is on purpose!
+    @rackful_resource_parsers ||= {}
+  end
 
 
-  extend Forwardable
-  def_delegators 'self.class', :parsers, :serializers, :all_parsers, :all_serializers
+  # All serializers added to _this_ class.  Ie. not including serializers added
+  # to parent classes.
+  # @return [Hash{ String( content_type ) => Array( Serializer, Float(quality) ) }]
+  # @api private
+  def serializers
+    # The single '@' on the following line is on purpose!
+    @rackful_resource_serializers ||= {}
+  end
 
 
-  def initialize( uri )
-    @uri = uri.kind_of?( URI::Generic ) ? uri.dup : URI(uri.to_s).normalize
-    #self.uri = uri
-  end
+  end # module ClassMethods
 
 
-=begin markdown
-@param request [Request]
-@param content_type [String, nil] If omitted, you get the best serializer
-  available, which may not be acceptable by the client.
-@return [Serializer]
-=end
-  def serializer request, content_type = nil
-    content_type ||= request.best_content_type( self, false )
-    self.class.all_serializers[content_type][0].new( request, self, content_type )
+  # This callback includes all methods of {ClassMethods} into all classes that
+  # include {Resource}, to make them available as a tiny DSL.
+  # @api private
+  def self.included(base)
+    base.extend ClassMethods
   end
 
 
-=begin markdown
-The best media type for the response body, given the current HTTP request.
-@param request [Rackful::Request]
-@return [Parser, nil] a {Parser}, or nil if the request entity is empty
-@raise [HTTP415UnsupportedMediaType] if no parser can be found for the request entity
-=end
-  def parser request
+  # Parse and “execute” the request body.
+  # @param request [Rackful::Request]
+  # @param response [Rack::Response]
+  # @return [Parser, nil] a {Parser}, or nil if the request entity is empty
+  # @raise [HTTP415UnsupportedMediaType] if no parser can be found for the request entity
+  # @api private
+  def parse request, response
     unless request.content_length ||
            'chunked' == request.env['HTTP_TRANSFER_ENCODING']
       raise HTTP411LengthRequired
@@ -151,40 +210,25 @@ The best media type for the response body, given the current HTTP request.
     request_media_type = request.media_type.to_s
     supported_media_types = []
     all_parsers = self.class.all_parsers[ request.request_method.to_sym ] || []
-    all_parsers.each do |p|
-      p::MEDIA_TYPES.each do |parser_media_type|
-        if File.fnmatch( parser_media_type, request_media_type )
-          return p.new( request, self )
-        end
-        supported_media_types << parser_media_type
+    all_parsers.each do |mt, p|
+      if File.fnmatch( mt, request_media_type, File::FNM_PATHNAME )
+        return p.parse( request, response, self )
       end
+      supported_media_types << mt
     end
+    raise( HTTP405MethodNotAllowed, self.http_methods ) if supported_media_types.empty?
     raise( HTTP415UnsupportedMediaType, supported_media_types.uniq )
   end
 
 
-=begin markdown
-@!method do_METHOD( Request, Rack::Response )
-  HTTP/1.1 method handler.
-
-  To handle certain HTTP/1.1 request methods, resources must implement methods
-  called `do_<HTTP_METHOD>`.
-  @example Handling `PATCH` requests
-    def do_PATCH request, response
-      response['Content-Type'] = 'text/plain'
-      response.body = [ 'Hello world!' ]
-    end
-  @abstract
-  @return [void]
-  @raise [HTTPStatus, RuntimeError]
-=end
+  # The canonical path of this resource.
+  # @return [URI]
+  attr_reader :uri
 
 
-=begin markdown
-The canonical path of this resource.
-@return [URI]
-=end
-  attr_reader :uri
+  def uri=( uri )
+    @uri = uri.kind_of?(URI::Generic) ? uri.dup : URI(uri).normalize
+  end
 
 
   def title
@@ -192,16 +236,14 @@ The canonical path of this resource.
   end
 
 
-=begin markdown
-Does this resource _exist_?
-
-For example, a client can `PUT` to a URL that doesn't refer to a resource
-yet. In that case, your {Server#initialize resource registry} can
-produce an empty resource to handle the `PUT` request. `HEAD` and `GET`
-requests will still yield `404 Not Found`.
-
-@return [Boolean] The default implementation returns `false`.
-=end
+  # Does this resource _exist_?
+  # 
+  # For example, a client can `PUT` to a URL that doesn't refer to a resource
+  # yet. In that case, your {Server#initialize resource registry} can
+  # produce an empty resource to handle the `PUT` request. `HEAD` and `GET`
+  # requests will still yield `404 Not Found`.
+  # 
+  # @return [Boolean] The default implementation returns `false`.
   def empty?
     false
   end
@@ -212,58 +254,13 @@ requests will still yield `404 Not Found`.
   end
 
 
-=begin markdown
-@!attribute [r] get_etag
-  The ETag of this resource.
-
-  If your classes implement this method, then an `ETag:` response
-  header is generated automatically when appropriate. This allows clients to
-  perform conditional requests, by sending an `If-Match:` or
-  `If-None-Match:` request header. These conditions are then asserted
-  for you automatically.
-
-  Make sure your entity tag is a properly formatted string. In ABNF:
-
-      entity-tag    = [ "W/" ] quoted-string
-      quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
-      qdtext        = <any TEXT except <">>
-      quoted-pair   = "\" CHAR
-
-  @abstract
-  @return [String]
-  @see http://tools.ietf.org/html/rfc2616#section-14.19 RFC2616 section 14.19
-=end
-
-
-=begin markdown
-@!attribute [r] get_last_modified
-  Last modification of this resource.
 
-  If your classes implement this method, then a `Last-Modified:` response
-  header is generated automatically when appropriate. This allows clients to
-  perform conditional requests, by sending an `If-Modified-Since:` or
-  `If-Unmodified-Since:` request header. These conditions are then asserted
-  for you automatically.
-  @abstract
-  @return [Array<(Time, Boolean)>] The timestamp, and a flag indicating if the
-    timestamp is a strong validator.
-  @see http://tools.ietf.org/html/rfc2616#section-14.29 RFC2616 section 14.29
-=end
 
-
-=begin markdown
-@!method destroy()
-  @return [Hash, nil] an optional header hash.
-=end
-
-
-=begin markdown
-List of all HTTP/1.1 methods implemented by this resource.
-
-This works by inspecting all the {#do_METHOD} methods this object implements.
-@return [Array<Symbol>]
-@api private
-=end
+  # List of all HTTP/1.1 methods implemented by this resource.
+  # 
+  # This works by inspecting all the {#do_METHOD} methods this object implements.
+  # @return [Array<Symbol>]
+  # @api private
   def http_methods
     r = []
     if self.empty?
@@ -284,33 +281,29 @@ This works by inspecting all the {#do_METHOD} methods this object implements.
   end
 
 
-=begin markdown
-Handles an OPTIONS request.
-
-As a courtesy, this module implements a default handler for OPTIONS
-requests. It creates an `Allow:` header, listing all implemented HTTP/1.1
-methods for this resource. By default, an `HTTP/1.1 204 No Content` is
-returned (without an entity body).
-
-Feel free to override this method at will.
-@return [void]
-@raise [HTTP404NotFound] `404 Not Found` if this resource is empty.
-=end
+  # Handles an OPTIONS request.
+  # 
+  # As a courtesy, this module implements a default handler for OPTIONS
+  # requests. It creates an `Allow:` header, listing all implemented HTTP/1.1
+  # methods for this resource. By default, an `HTTP/1.1 204 No Content` is
+  # returned (without an entity body).
+  # 
+  # Feel free to override this method at will.
+  # @return [void]
+  # @raise [HTTP404NotFound] `404 Not Found` if this resource is empty.
   def http_OPTIONS request, response
     response.status = Rack::Utils.status_code :no_content
     response.header['Allow'] = self.http_methods.join ', '
   end
 
 
-=begin markdown
-Handles a HEAD request.
-
-This default handler for HEAD requests calls {#http\_GET}, and
-then strips off the response body.
-
-Feel free to override this method at will.
-@return [self]
-=end
+  # Handles a HEAD request.
+  # 
+  # This default handler for HEAD requests calls {#http\_GET}, and
+  # then strips off the response body.
+  # 
+  # Feel free to override this method at will.
+  # @return [self]
   def http_HEAD request, response
     self.http_GET request, response
     response['Content-Length'] =
@@ -323,21 +316,18 @@ Feel free to override this method at will.
   end
 
 
-=begin markdown
-@api private
-@param request [Rackful::Request]
-@param response [Rack::Response]
-@return [void]
-@raise [HTTP404NotFound, HTTP405MethodNotAllowed]
-=end
+  # @api private
+  # @param request [Rackful::Request]
+  # @param response [Rack::Response]
+  # @return [void]
+  # @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
   def http_GET request, response
     raise HTTP404NotFound if self.empty?
     # May throw HTTP406NotAcceptable:
-    content_type = request.best_content_type( self )
-    response['Content-Type'] = content_type
+    serializer = self.serializer( request )
+    response['Content-Type'] = serializer.content_type
     response.status = Rack::Utils.status_code( :ok )
     response.headers.merge! self.default_headers
-    serializer = self.serializer( request, content_type )
     if serializer.respond_to? :headers
       response.headers.merge!( serializer.headers )
     end
@@ -345,12 +335,47 @@ Feel free to override this method at will.
   end
 
 
-=begin markdown
-Wrapper around {#do_METHOD #do_GET}
-@api private
-@return [void]
-@raise [HTTP404NotFound, HTTP405MethodNotAllowed]
-=end
+  # The best serializer to represent this resource, given the current HTTP request.
+  # @param request [Request] the current request
+  # @param require_match [Boolean] this flag determines what must happen if the
+  #   client sent an `Accept:` header, and we cannot serve any of the acceptable
+  #   media types. **`TRUE`** means that an {HTTP406NotAcceptable} exception is
+  #   raised. **`FALSE`** means that the content-type with the highest quality is
+  #   returned.
+  # @return [Serializer]
+  # @raise [HTTP406NotAcceptable]
+  def serializer( request, require_match = true )
+    q_values = request.q_values # Array<Array(type, quality)>
+    default_serializer = # @formatter:off
+      # Hash{ String( content_type ) => Array( Serializer, Float(quality) ) }
+      self.class.all_serializers.
+      # Array< Array( Serializer, Float(quality) ) >
+      values.sort_by(&:last).
+      # Serializer
+      last.first # @formatter:on
+    best_match = [ default_serializer, 0.0, default_serializer.content_types.first ]
+    q_values.each do
+      |accept_media_type, accept_quality|
+      self.class.all_serializers.each_pair do
+        |content_type, sq|
+        media_type = content_type.split(/\s*;\s*/).first
+        if File.fnmatch( accept_media_type, media_type, File::FNM_PATHNAME ) and
+           best_match.nil? || best_match[1] < ( accept_quality * sq[1] )
+          best_match = [ sq[0], sq[1], content_type ]
+        end
+      end
+    end
+    if require_match and best_match[1] <= 0.0
+      raise( HTTP406NotAcceptable, self.class.all_serializers.keys() )
+    end
+    best_match[0].new(request, self, best_match[2])
+  end
+
+
+  # Wrapper around {#do_METHOD #do_GET}
+  # @api private
+  # @return [void]
+  # @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
   def http_DELETE request, response
     raise HTTP404NotFound if self.empty?
     raise HTTP405MethodNotAllowed, self.http_methods unless
@@ -362,26 +387,61 @@ Wrapper around {#do_METHOD #do_GET}
   end
 
 
-=begin markdown
-@api private
-@return [void]
-@raise [HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the resource doesn't implement the `PUT` method.
-=end
+  # @api private
+  # @return [void]
+  # @raise [HTTP404NotFound, HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the
+  #   resource doesn’t implement the `PATCH` method or can’t handle the provided
+  #   request body media type.
+  def http_PATCH request, response
+    raise HTTP404NotFound if self.empty?
+    response.status = :no_content
+    begin
+      parse(request, response)
+    rescue HTTP405MethodNotAllowed => e
+      raise e unless self.respond_to? :do_PATCH
+      self.do_PATCH( request, response )
+    end
+    response.headers.merge! self.default_headers
+  end
+
+
+  # @api private
+  # @return [void]
+  # @raise [HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the
+  #   resource doesn’t implement the `POST` method or can’t handle the provided
+  #   request body media type.
+  def http_POST request, response
+    begin
+      parse(request, response)
+    rescue HTTP405MethodNotAllowed => e
+      raise e unless self.respond_to? :do_POST
+      self.do_POST( request, response )
+    end
+  end
+
+
+  # @api private
+  # @return [void]
+  # @raise [HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the
+  #   resource doesn’t implement the `PUT` method or can’t handle the provided
+  #   request body media type.
   def http_PUT request, response
-    raise HTTP405MethodNotAllowed, self.http_methods unless self.respond_to? :do_PUT
     response.status = Rack::Utils.status_code( self.empty? ? :created : :no_content )
-    self.do_PUT( request, response )
+    begin
+      parse(request, response)
+    rescue HTTP405MethodNotAllowed => e
+      raise e unless self.respond_to? :do_PUT
+      self.do_PUT( request, response )
+    end
     response.headers.merge! self.default_headers
   end
 
 
-=begin markdown
-Wrapper around {#do_METHOD}
-@api private
-@return [void]
-@raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement
-  the request method.
-=end
+  # Wrapper around {#do_METHOD}
+  # @api private
+  # @return [void]
+  # @raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement
+  #   the request method.
   def http_method request, response
     method = request.request_method.to_sym
     if ! self.respond_to?( :"do_#{method}" )
@@ -391,9 +451,7 @@ Wrapper around {#do_METHOD}
   end
 
 
-=begin markdown
-Adds `ETag:` and `Last-Modified:` response headers.
-=end
+  # Adds `ETag:` and `Last-Modified:` response headers.
   def default_headers
     r = {}
     r['ETag'] = self.get_etag \
@@ -404,7 +462,5 @@ Adds `ETag:` and `Last-Modified:` response headers.
   end
 
 
-end # module Resource
-
-
+end # module Rackful::Resource
 end # module Rackful