rackful 0.1.4 → 0.2.0

data/lib/rackful/request.rb

@@ -1,63 +1,53 @@
-# Required for parsing:
-require 'rack'
-
-# Required for running:
+# encoding: utf-8
 
 
 module Rackful
 
-=begin markdown
-Subclass of {Rack::Request}, augmented for Rackful requests.
-=end
+# Subclass of {Rack::Request}, augmented for Rackful requests.
 class Request < Rack::Request
 
 
-=begin markdown
-The resource factory for the current request.
-@return [#[]]
-@see Server#initialize
-=end
-  def resource_factory; self.env['rackful.resource_factory']; end
-  def base_path
-    self.env['rackful.base_path'] ||= begin
-      r = self.content_path.dup
-      r[%r{[^/]*\z}] = ''
-      r
-    end
+  def initialize *args
+    super( *args )
   end
+
+
 =begin markdown
-Similar to the HTTP/1.1 `Content-Location:` header. Contains the canonical path
-to the requested resource, which may differ from {#path}
-@return [Path]
-=end
-  def content_path; self.env['rackful.content_path'] ||= self.path; end
-=begin markdown
-Set by {Rackful::Server#call!}
-@return [Path]
-=end
-  def content_path= bp; self.env['rackful.content_path'] = bp.to_path; end
-=begin markdown
-@return [Path]
+Shortcut to {Server#resource_at}.
+
+(see Server#resource_at)
+@return (see Server#resource_at)
+@raise (see Server#resource_at)
 =end
-  def path; super.to_path; end
+  def resource_at *args
+    env['rackful.server'].resource_at( *args )
+  end
 
 
-  def initialize resource_factory, *args
-    super( *args )
-    self.env['rackful.resource_factory'] = resource_factory
+=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
   end
 
 
 =begin markdown
-The request currently being processed in the current thread.
+The canonical url of the requested resource. This may differ from {#url}.
 
-In a multi-threaded server, multiple requests can be handled at one time.
-This method returns the request object, created (and registered) by
-{Server#call!}
-@return [Request]
+@todo Change URI::Generic into URI::HTTP
+@param uri [URI::Generic, String]
+@return [URI::Generic, String] `uri`
 =end
-  def self.current
-    Thread.current[:rackful_request]
+  def canonical_uri=( uri )
+    env['rackful.canonical_uri'] =
+      uri.kind_of?( URI::Generic ) ? URI(uri) : URI( uri ).normalize
+    uri
   end
 
 
@@ -79,7 +69,7 @@ Assert all <tt>If-*</tt> request headers.
 =end
   def assert_if_headers resource
     #raise HTTP501NotImplemented, 'If-Range: request header is not supported.' \
-    #  if @env.key? 'HTTP_IF_RANGE'
+    #  if env.key? 'HTTP_IF_RANGE'
     empty = resource.empty?
     etag =
       if ! empty && resource.respond_to?(:get_etag)
@@ -106,7 +96,7 @@ Assert all <tt>If-*</tt> request headers.
       elsif cond[:unmodified_since]
         raise HTTP412PreconditionFailed, 'If-Unmodified-Since'
       elsif cond[:modified_since]
-        raise HTTP404NotFound, resource.path
+        raise HTTP404NotFound
       end
     else
       if cond[:none_match] && self.validate_etag( etag, cond[:none_match] )
@@ -136,17 +126,77 @@ Assert all <tt>If-*</tt> request headers.
   end
 
 
-=begin markdown
-Hash of acceptable media types and their qualities.
+  # Shortcut to {Rack::Utils.q_values}. Well, actually, we reimplemented it
+  # because the implementation in {Rack::Utils} seems incomplete.
+  # @return [Array<Array(type, quality)>]
+  # @see Rack::Utils.q_values
+  def q_values
+    # This would be the “shortcut” implementation:
+    #env['rackful.q_values'] ||= Rack::Utils.q_values(env['HTTP_ACCEPT'])
+    # But here’s a full (and better) implementation:
+    env['rackful.q_values'] ||= env['HTTP_ACCEPT'].to_s.split(/\s*,\s*/).map do
+      |part|
+      value, *parameters = part.split(/\s*;\s*/)
+      quality = 1.0
+      parameters.each do |p|
+        quality = p[2..-1].to_f if p.start_with? 'q='
+      end
+      [value, quality]
+    end
+  end
+
 
-This method parses the HTTP/1.1 `Accept:` header. If no acceptable media
-types are provided, an empty Hash is returned.
-@return [Hash{media_type => quality}]
+=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
+  # types are provided, an empty Hash is returned.
+  # @return [Hash{media_type => quality}]
+  # @deprecated Use {#q_values} instead
   def accept
-    @env['rackful.accept'] ||= begin
+    env['rackful.accept'] ||= begin
       Hash[
-        @env['HTTP_ACCEPT'].to_s.split(',').collect do
+        env['HTTP_ACCEPT'].to_s.split(',').collect do
           |entry|
           type, *options = entry.delete(' ').split(';')
           quality = 1
@@ -170,7 +220,7 @@ Parses the HTTP/1.1 `If-Match:` header.
 @see #if_none_match
 =end
   def if_match none = false
-    header = @env["HTTP_IF_#{ none ? 'NONE_' : '' }MATCH"]
+    header = env["HTTP_IF_#{ none ? 'NONE_' : '' }MATCH"]
     return nil unless header
     envkey = "rackful.if_#{ none ? 'none_' : '' }match"
     if %r{\A\s*\*\s*\z} === header
@@ -200,7 +250,7 @@ Parses the HTTP/1.1 `If-None-Match:` header.
 @see #if_unmodified_since
 =end
   def if_modified_since unmodified = false
-    header = @env["HTTP_IF_#{ unmodified ? 'UN' : '' }MODIFIED_SINCE"]
+    header = env["HTTP_IF_#{ unmodified ? 'UN' : '' }MODIFIED_SINCE"]
     return nil unless header
     begin
       header = Time.httpdate( header )

data/lib/rackful/resource.rb

@@ -1,177 +1,169 @@
-# Required for parsing:
-require 'rack'
-
-# Required for running:
+# encoding: utf-8
 
+require 'forwardable'
 
 module Rackful
 
-=begin markdown
-Mixin for resources served by {Server}.
-
-{Server} helps you implement Rackful resource objects quickly in a couple
-of ways.  
-Classes that include this module may implement a method `content_types`
-for content negotiation. This method must return a Hash of
-`media-type => quality` pairs. 
-@see Server, ResourceFactory
-=end
-module Resource
+# Abstract superclass for resources served by {Server}.
+# @see Server
+# @todo better documentation
+# @abstract Realizations must implement…
+class Resource
+
+  class << self
+
+
+  # Meta-programmer method.
+  # @example Have your resource rendered in XML and JSON
+  #   class MyResource
+  #     add_serializer MyResource2XML
+  #     add_serializer MyResource2JSON, 0.5
+  #   end
+  # @param serializer [Serializer]
+  # @param quality [Float]
+  # @return [self]
+  def add_serializer serializer, quality = 1.0
+    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
+    }
+    self
+  end
 
 
-  include Rack::Utils
+  # Meta-programmer method.
+  # @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 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!
+    self
+  end
 
 
-=begin
-Normally, when a module is included, all the instance methods of the included
-module become available as instance methods to the including module/class. But
-class methods of the included module don't become available as class methods to
-the including class.
+  # 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
 
 
-=end
-  def self.included(base)
-    base.extend ClassMethods
+  # 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
 
 
-  module ClassMethods
-
-=begin
-Meta-programmer method.
-@example Have your resource rendered in XML and JSON
-  class MyResource
-    add_serializer MyResource2XML
-    add_serializer MyResource2JSON, 0.5
+  # 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
+          |key, oldval, newval|
+          ( oldval + newval ).uniq
+        end
+      else
+        self.parsers
+      end
   end
-@param serializer [Serializer]
-@param quality [Float]
-@return [self]
-=end
-    def add_serializer serializer, quality = 1.0
-      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
-      }
-      self
-    end
 
 
-    def serializers
-      # The single '@' on the following line is on purpose!
-      @rackful_resource_serializers ||= {}
-    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]
+  # @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
+          |key, oldval, newval|
+          newval[1] >= oldval[1] ? newval : oldval
+        end
+      else
+        self.serializers
+      end
+  end
 
 
-    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
-            |key, oldval, newval|
-            newval[1] >= oldval[1] ? newval : oldval
-          end
-        else
-          self.serializers
-        end
-    end
+  end # module ClassMethods
 
 
-=begin
-Meta-programmer method.
-@example Have your resource accept XML and JSON in `PUT` requests
-  class MyResource
-    add_media_type 'text/xml', :PUT
-    add_media_type 'application/json', :PUT
-  end
-@param [#to_s] media_type
-@param [#to_sym] method
-@return [self]
-=end
-    def add_media_type media_type, method = :PUT
-      method = method.to_sym
-      self.media_types[method] ||= []
-      self.media_types[method] << media_type.to_s
-      self
-    end
+  extend Forwardable
+  def_delegators 'self.class', :parsers, :serializers, :all_parsers, :all_serializers
 
 
-=begin
-@return [Hash(method => Array(media_types))]
-=end
-    def media_types
-      @rackful_resource_media_types ||= {}
-    end
+  def initialize( uri )
+    @uri = uri.kind_of?( URI::Generic ) ? uri.dup : URI(uri.to_s).normalize
+    #self.uri = uri
+  end
 
 
-=begin
-@todo Documentation
+=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 all_media_types
-      @rackful_resource_all_media_types ||=
-        if self.superclass.respond_to?(:all_media_types)
-          self.superclass.all_media_types.merge( self.media_types ) do
-            |key, oldval, newval|
-            oldval + newval
-          end
-        else
-          self.media_types
-        end
-    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 )
+  end
 
 
 =begin markdown
 The best media type for the response body, given the current HTTP request.
-@param accept [Hash]
-@param require_match [Boolean]
-@return [String] content-type
-@raise [HTTP406NotAcceptable] if `require_match` is `true` and no match was found.
+@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 best_content_type accept, require_match = true
-      if accept.empty?
-        return self.all_serializers.values.sort_by(&:last).last[0]::CONTENT_TYPES[0]
-      end
-      matches = []
-      accept.each_pair {
-        |accept_media_type, accept_quality|
-        self.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, self.all_serializers.keys() )
-        else
-          return self.all_serializers.values.sort_by(&:last).last[0]::CONTENT_TYPES[0]
+  def parser request
+    unless request.content_length ||
+           'chunked' == request.env['HTTP_TRANSFER_ENCODING']
+      raise HTTP411LengthRequired
+    end
+    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
       end
-      matches.sort_by(&:last).last[0]
     end
-
-
-  end # module ClassMethods
-
-
-=begin markdown
-@return [Serializer]
-=end
-  def serializer content_type
-    @rackful_resource_serializers ||= {}
-    @rackful_resource_serializers[content_type] ||=
-      self.class.all_serializers[content_type][0].new( self, content_type )
+    raise( HTTP415UnsupportedMediaType, supported_media_types.uniq )
   end
 
 
-=begin
+=begin markdown
 @!method do_METHOD( Request, Rack::Response )
   HTTP/1.1 method handler.
 
@@ -189,36 +181,23 @@ The best media type for the response body, given the current HTTP request.
 
 
 =begin markdown
-The path of this resource.
-@return [Rackful::Path]
-@see #initialize
+The canonical path of this resource.
+@return [URI]
 =end
-  def path; @rackful_resource_path; end
-
-
-  def path= path
-    @rackful_resource_path = Path.new(path)
-  end
+  attr_reader :uri
 
 
   def title
-    ( '/' == self.path ) ?
-      Request.current.host :
-      File.basename(self.path).to_path.unescape
-  end
-
-
-  def requested?
-    self.path.slashify == Request.current.path.slashify
+    self.uri.segments.last || self.class.to_s
   end
 
 
 =begin markdown
-Does this resource _exists_?
+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#resource_factory resource factory} can
-produce an empty resource to to handle the `PUT` request. `HEAD` and `GET`
+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`.
@@ -227,10 +206,7 @@ requests will still yield `404 Not Found`.
     false
   end
 
-
-=begin markdown
-
-=end
+  # @todo documentation
   def to_rackful
     self
   end
@@ -286,7 +262,7 @@ 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>]
-@private
+@api private
 =end
   def http_methods
     r = []
@@ -321,8 +297,7 @@ Feel free to override this method at will.
 @raise [HTTP404NotFound] `404 Not Found` if this resource is empty.
 =end
   def http_OPTIONS request, response
-    raise HTTP404NotFound, path if self.empty?
-    response.status = status_code :no_content
+    response.status = Rack::Utils.status_code :no_content
     response.header['Allow'] = self.http_methods.join ', '
   end
 
@@ -349,21 +324,20 @@ Feel free to override this method at will.
 
 
 =begin markdown
-@private
-@param [Rackful::Request] request
-@param [Rack::Response] response
+@api private
+@param request [Rackful::Request]
+@param response [Rack::Response]
 @return [void]
 @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
 =end
   def http_GET request, response
-    raise HTTP404NotFound, path if self.empty?
+    raise HTTP404NotFound if self.empty?
     # May throw HTTP406NotAcceptable:
-    content_type = self.class.best_content_type( request.accept )
+    content_type = request.best_content_type( self )
     response['Content-Type'] = content_type
-    response.status = status_code( :ok )
+    response.status = Rack::Utils.status_code( :ok )
     response.headers.merge! self.default_headers
-    # May throw HTTP405MethodNotAllowed:
-    serializer = self.serializer( content_type )
+    serializer = self.serializer( request, content_type )
     if serializer.respond_to? :headers
       response.headers.merge!( serializer.headers )
     end
@@ -373,14 +347,15 @@ Feel free to override this method at will.
 
 =begin markdown
 Wrapper around {#do_METHOD #do_GET}
-@private
+@api private
 @return [void]
 @raise [HTTP404NotFound, HTTP405MethodNotAllowed]
 =end
   def http_DELETE request, response
-    raise HTTP404NotFound, path if self.empty?
-    raise HTTP405MethodNotAllowed, self.http_methods unless self.respond_to?( :destroy )
-    response.status = status_code( :no_content )
+    raise HTTP404NotFound if self.empty?
+    raise HTTP405MethodNotAllowed, self.http_methods unless
+      self.respond_to?( :destroy )
+    response.status = Rack::Utils.status_code( :no_content )
     if headers = self.destroy( request, response )
       response.headers.merge! headers
     end
@@ -388,39 +363,30 @@ Wrapper around {#do_METHOD #do_GET}
 
 
 =begin markdown
-@private
+@api private
 @return [void]
 @raise [HTTP415UnsupportedMediaType, HTTP405MethodNotAllowed] if the resource doesn't implement the `PUT` method.
 =end
   def http_PUT request, response
     raise HTTP405MethodNotAllowed, self.http_methods unless self.respond_to? :do_PUT
-    unless self.class.media_types[:PUT] &&
-           self.class.media_types[:PUT].include?( request.media_type )
-      raise HTTP415UnsupportedMediaType, self.class.media_types[:PUT]
-    end
-    response.status = status_code( self.empty? ? :created : :no_content )
+    response.status = Rack::Utils.status_code( self.empty? ? :created : :no_content )
     self.do_PUT( request, response )
     response.headers.merge! self.default_headers
   end
 
 
 =begin markdown
-Wrapper around {#do_METHOD #do_PUT}
-@private
+Wrapper around {#do_METHOD}
+@api private
 @return [void]
-@raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement the `PUT` method.
+@raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement
+  the request method.
 =end
   def http_method request, response
     method = request.request_method.to_sym
     if ! self.respond_to?( :"do_#{method}" )
       raise HTTP405MethodNotAllowed, self.http_methods
     end
-    if  ( request.content_length ||
-          'chunked' == request.env['HTTP_TRANSFER_ENCODING'] ) and
-        ! self.class.media_types[method] ||
-        ! self.class.media_types[method].include?( request.media_type )
-      raise HTTP415UnsupportedMediaType, self.class.media_types[method]
-    end
     self.send( :"do_#{method}", request, response )
   end
 
@@ -441,33 +407,4 @@ Adds `ETag:` and `Last-Modified:` response headers.
 end # module Resource
 
 
-=begin unused
-module Collection
-
-
-  include Enumerable
-
-
-  def self.included( modul )
-    unless modul.kind_of? Resource
-      raise "module #{self} included in #{modul}, which isn't a Rackful::Resource"
-    end
-  end
-  
-  
-  def recurse?; false; end
-  
-  
-  def each_pair
-    self.each do
-      |path|
-      yield [ path, Request.current.resource_factory( path ) ]
-    end
-  end
-
-
-end # module Collection
-=end
-
-
 end # module Rackful