rackful 0.0.2 → 0.1.0

data/lib/rackful.rb

@@ -1,934 +1,6 @@
-# Copyright ©2011-2012 Pieter van Beek <pieterb@sara.nl>
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-
-require 'rexml/document' # Used by HTTPStatus
-require 'rack'
-
-=begin markdown
-Library for creating Rackful web services
-
-Rackful
-=======
-
-Rationale
----------
-
-Confronted with the task of implementing a Rackful web service in Ruby, I
-checked out a number of existing libraries and frameworks, including
-Ruby-on-Rails, and then decided to brew my own, the reason being that I couldn't
-find a library or framework with all of the following properties:
-
-*   **Small** Some of these frameworks are really big. I need to get a job done in
-    time. If understanding the framework takes more time than writing my own, I
-    must at least feel confident that the framework I'm learning is more powerful
-    that what I can come up with by myself. Ruby-on-Rails is probably the biggest
-    framework out there, and it still lacks many features that are essential to
-    Rackful web service programming.
-
-    This library is small. You could read _all_ the source code in less than an
-    hour, and understand every detail.
-
-*   **No extensive tooling or code generation** Code generation has been the
-    subject of more than one flame-war over the years. Not much I can add to the
-    debate. <em>But still,</em> with a language as dynamic as Ruby, you just
-    shouldn't need code generation. Ever.
-
-*   **Full support for conditional requests** using `If-*:` request headers. Most
-    libraries' support is limited to `If-None-Match:` and `If-Modified-Since:`
-    headers, and only for `GET` and `HEAD` requests. For Rackful web services,
-    the `If-Match:` and `If-Unmodified-Since:` headers are at least as important,
-    particularly for unsafe methods like `PUT`, `POST`, `PATCH`, and `DELETE`.
-
-    This library fully supports the `ETag:` and `Last-Modified:` headers, and all
-    `If-*:` headers.
-
-*   **Resource centered** Some libraries claim Rackfulness, but at the same
-    time have a servet-like interface, which requires you to implement method
-    handles such as `doPOST(url)`. In these method handlers you have to find out
-    what resource is posted to, depending on the URL.
-
-    This library requires that you implement a Resource Factory which maps URIs
-    to resource Objects. These objects will then receive HTTP requests.
-
-Hello World!
-------------
-
-Here's a working example of a simple Rackful server:
-
-{include:file:example/config.ru}
-
-This file is included in the distribution as `example/config.ru`.
-If you go to the `example` directory and run `rackup`, you should see
-something like this:
-
-    $> rackup
-    [2012-07-10 11:45:32] INFO  WEBrick 1.3.1
-    [2012-07-10 11:45:32] INFO  ruby 1.9.2 (2011-12-27) [java]
-    [2012-07-10 11:45:32] INFO  WEBrick::HTTPServer#start: pid=5994 port=9292
-
-Go with your browser to {http://localhost:9292/} and be greeted.
-
-In this example, we implement `GET` and `PUT` requests for the resource at '/'. but
-we get a few things for free:
-
-### Free `OPTIONS` response:
-
-Request:
-
-    OPTIONS / HTTP/1.1
-    Host: localhost:9292
-
-Response:
-
-    HTTP/1.1 204 No Content 
-    Allow: PUT, GET, HEAD, OPTIONS
-    Date: Tue, 10 Jul 2012 10:22:52 GMT
-
-As you can see, the server accurately reports all available methods for the
-resource. Notice the availability of the `HEAD` method; if you implement the
-`GET` method, you'll get `HEAD` for free. It's still a good idea to explicitly
-implement your own `HEAD` request handler, especially for expensive resources,
-when responding to a `HEAD` request should be much more efficient than generating
-a full `GET` response, and strip off the response body.
-
-### Free conditional request handling:
-
-Let's first get the current state of the resource, with this request:
-
-    GET / HTTP/1.1
-    Host: localhost:9292
-
-Response:
-
-    HTTP/1.1 200 OK 
-    Content-Type: text/plain
-    Content-Length: 12
-    ETag: "86fb269d190d2c85f6e0468ceca42a20"
-    Date: Tue, 10 Jul 2012 10:34:36 GMT
-    
-    Hello world!
-
-Now, we'd like to change the state of the resource, but only if it's still in
-the state we last saw, to avoid the "lost update problem". To do that, we
-produce an `If-Match:` header, with the entity tag of our last version:
-
-    PUT / HTTP/1.1
-    Host: localhost:9292
-    Content-Type: text/plain
-    Content-Length: 31
-    If-Match: "86fb269d190d2c85f6e0468ceca42a20"
-    
-    All your base are belong to us.
-
-Response:
-
-    HTTP/1.1 204 No Content
-    ETag: "920c1e9267f923c62b55a471c1d8a528"
-    Date: Tue, 10 Jul 2012 10:58:57 GMT
-
-The response contains an `ETag:` header, with the _new_ entity tag of this
-resource. When we replay this request, we get the following response:
-
-    HTTP/1.1 412 Precondition Failed
-    Content-Type: text/html; charset="UTF-8"
-    Date: Tue, 10 Jul 2012 11:06:54 GMT
-    
-    [...]
-    <h1>HTTP/1.1 412 Precondition Failed</h1>
-    <p>If-Match: "86fb269d190d2c85f6e0468ceca42a20"</p>
-    [...]
-
-The server returns with status <tt>412 Precondition Failed</tt>. In the HTML
-response body, the server kindly points out exactly which precondition.
-
-Further reading
----------------
-*   {Rackful::Server#initialize} for more information about your Resource Factory.
-*   {Rackful::Resource#etag} and {Rackful::Resource#last_modified} for more information on
-    conditional requests.
-*   {Rackful::Resource#do_METHOD} for more information about writing your own request
-    handlers.
-*   {Rackful::RelativeLocation} for more information about this piece of Rack middleware
-    which allows you to return relative and absolute paths in the `Location:`
-    response header, and why you'd want that.
-
-Licensing
----------
-Copyright ©2011-2012 Pieter van Beek <pieterb@sara.nl>
-
-Licensed under the Apache License 2.0. You should have received a copy of the
-license as part of this distribution.
-@author Pieter van Beek <rackful@djinnit.com>
-=end
-module Rackful
-
-
-=begin markdown
-Subclass of {Rack::Request}, augmented for Rackful requests.
-@since 0.0.1
-=end
-class Request < Rack::Request
-
-
-=begin markdown
-The resource factory for the current request.
-@return [#[]]
-@see Server#initialize
-@since 0.0.1
-=end
-  attr_reader :resource_factory
-
-
-  def initialize resource_factory, *args
-    super *args
-    @resource_factory = resource_factory
-  end
-
-
-=begin markdown
-The request currently being processed in the current thread.
-
-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]
-@since 0.0.1
-=end
-  def self.current
-    Thread.current[:djinn_request]
-  end
-
-
-=begin markdown
-Assert all <tt>If-*</tt> request headers.
-@return [void]
-@raise [HTTPStatus] with one of the following status codes:
-
-  -   `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`
-  -   `501 Not Implemented` in case of `If-Range:` header.
-@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.
-@since 0.0.1
-=end
-  def assert_if_headers resource
-    raise HTTPStatus, 'NOT_IMPLEMENTED If-Range: request header is not supported.' \
-      if @env.key? 'HTTP_IF_RANGE'
-    empty = resource.empty?
-    etag =          ( ! empty && resource.respond_to?(:etag)          ) ? resource.etag          : nil
-    last_modified = ( ! empty && resource.respond_to?(:last_modified) ) ? resource.last_modified : nil
-    cond = {
-      :match => self.if_match,
-      :none_match => self.if_none_match,
-      :modified_since => self.if_modified_since,
-      :unmodified_since => self.if_unmodified_since
-    }
-    allow_weak = ['GET', 'HEAD'].include? self.request_method
-    if empty
-      if cond[:match]
-        raise HTTPStatus, "PRECONDITION_FAILED If-Match: #{@env['HTTP_IF_MATCH']}"
-      elsif cond[:unmodified_since]
-        raise HTTPStatus, "PRECONDITION_FAILED If-Unmodified-Since: #{@env['HTTP_IF_UNMODIFIED_SINCE']}"
-      elsif cond[:modified_since]
-        raise HTTPStatus, 'NOT_FOUND'
-      end
-    else
-      if cond[:none_match] && self.validate_etag( etag, cond[:none_match] )
-        raise HTTPStatus, "PRECONDITION_FAILED If-None-Match: #{@env['HTTP_IF_NONE_MATCH']}"
-      elsif cond[:match] && ! self.validate_etag( etag, cond[:match] )
-        raise HTTPStatus, "PRECONDITION_FAILED If-Match: #{@env['HTTP_IF_MATCH']}"
-      elsif cond[:unmodified_since]
-        if ! last_modified || cond[:unmodified_since] < last_modified[0]
-          raise HTTPStatus, "PRECONDITION_FAILED If-Unmodified-Since: #{@env['HTTP_IF_UNMODIFIED_SINCE']}"
-        elsif last_modified && ! last_modified[1] && ! allow_weak &&
-              cond[:unmodified_since] == last_modified[0]
-          raise HTTPStatus,
-                "PRECONDITION_FAILED If-Unmodified-Since: #{@env['HTTP_IF_UNMODIFIED_SINCE']}<br/>" +
-                "Modification time is a weak validator for this resource."
-        end
-      elsif cond[:modified_since]
-        if ! last_modified || cond[:modified_since] >= last_modified[0]
-          raise HTTPStatus, 'NOT_MODIFIED'
-        elsif last_modified && ! last_modified[1] && !allow_weak &&
-              cond[:modified_since] == last_modified[0]
-          raise HTTPStatus,
-                "PRECONDITION_FAILED If-Modified-Since: #{@env['HTTP_IF_MODIFIED_SINCE']}<br/>" +
-                "Modification time is a weak validator for this resource."
-        end
-      end
-    end
-  end
-
-
-=begin markdown
-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}]
-@since 0.0.1
-=end
-  def accept
-    @env['djinn.accept'] ||= begin
-      Hash[
-        @env['HTTP_ACCEPT'].to_s.split(',').collect do
-          |entry|
-          type, *options = entry.delete(' ').split(';')
-          quality = 1
-          options.each { |e|
-            quality = e[2..-1].to_f if e.start_with? 'q='
-          }
-          [type, quality]
-        end
-      ]
-    rescue
-      {}
-    end
-  end # def accept
-
-
-=begin markdown
-The best media type for the response body...
-
-...given the client's `Accept:` header(s) and the available representations
-in the server.
-@param content_types [Hash{media_type => quality}]
-  indicating what media types can be provided by the server, with their
-  relative qualities.
-@param require_match [Boolean]
-  Should this method throw an {HTTPStatus} exception
-  `406 Not Acceptable` if there's no match.
-@return [String]
-@raise [HTTPStatus] `406 Not Acceptable`
-@todo This method and its documentation seem to mix **content type** and
-  **media type**. I think the implementation is good, only comparing
-  **media types**, so all references to **content types** should be
-  removed.
-@since 0.0.1
-=end
-  def best_content_type content_types, require_match = true
-    return content_types.sort_by(&:last).last[0] if self.accept.empty?
-    matches = []
-    self.accept.each {
-      |accept_type, accept_quality|
-      content_types.each {
-        |response_type, response_quality|
-        mime_type = response_type.split(';').first.strip
-        if File.fnmatch( accept_type, mime_type )
-          matches.push [ response_type, accept_quality * response_quality ]
-        end
-      }
-    }
-    if matches.empty?
-      raise HTTPStatus, 'NOT_ACCEPTABLE' if require_match
-      nil
-    else
-      matches.sort_by(&:last).last[0]
-    end
-  end
-
-
-=begin markdown
-@deprecated This method seems to be unused...
-@since 0.0.1
-=end
-  def truthy? parameter
-    value = self.GET[parameter] || ''
-    %r{\A(1|t(rue)?|y(es)?|on)\z}i === value
-  end
-
-
-=begin markdown
-@deprecated This method seems to be unused...
-@since 0.0.1
-=end
-  def falsy? parameter
-    value = self.GET[parameter] || ''
-    %r{\A(0|f(alse)?|n(o)?|off)\z}i === value
-  end
-
-
-=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
-@since 0.0.1
-=end
-  def if_match none = false
-    header = @env["HTTP_IF_#{ none ? 'NONE_' : '' }MATCH"]
-    return nil unless header
-    envkey = "djinn.if_#{ none ? 'none_' : '' }match"
-    if %r{\A\s*\*\s*\z} === header
-      return [ '*' ]
-    elsif %r{\A(\s*(W/)?"([^"\\]|\\.)*"\s*,)+\z}m === ( header + ',' )
-      return header.scan( %r{(?:W/)?"(?:[^"\\]|\\.)*"}m )
-    end
-    raise HTTPStatus, "BAD_REQUEST Couldn't parse If-#{ none ? 'None-' : '' }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
-@since 0.0.1
-=end
-  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
-@since 0.0.1
-=end
-  def if_modified_since unmodified = false
-    header = @env["HTTP_IF_#{ unmodified ? 'UN' : '' }MODIFIED_SINCE"]
-    return nil unless header
-    begin
-      header = Time.httpdate( header )
-    rescue ArgumentError
-      raise HTTPStatus, "BAD_REQUEST Couldn't parse If-#{ unmodified ? 'Unmodified' : 'Modified' }-Since: #{header}"
-    end
-    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
-@since 0.0.1
-=end
-  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.
-@since 0.0.1
-=end
-  def validate_etag etag, etags
-    etag = etag.to_s
-    match = etags.to_a.detect do
-      |tag|
-      tag = tag.to_s
-      tag == '*' or
-      tag == etag or
-      'W/' +  tag == etag or
-      'W/' + etag ==  tag
-    end
-    if  match and
-        '*' != match and
-        'W/' == etag[0,2] || 'W/' == match[0,2] and
-        ! [ 'HEAD', 'GET' ].include? self.request_method
-      raise HTTPStatus, "BAD_REQUEST Weak validators are only allowed for GET and HEAD requests."
-    end
-    !!match
-  end
-
-
-end # class Request
-
-
-=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
-`mime-type => quality` pairs. 
-@see Server, ResourceFactory
-@since 0.0.1
-=end
-module Resource
-
-
-  include Rack::Utils
-
-
-=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 `GET` requests
-  def do_GET request, response
-    response['Content-Type'] = 'text/plain'
-    response.body = [ 'Hello world!' ]
-  end
-@abstract
-@return [void]
-@raise [HTTPStatus, RuntimeError]
-@since 0.0.1
-=end
-
-
-=begin markdown
-The path of this resource.
-@return [String]
-@see #initialize
-@since 0.0.1
-=end
-  attr_reader :path
-
-
-=begin markdown
-@param path [#to_s] The path of this resource. This is a `path-absolute` as
-  defined in {http://tools.ietf.org/html/rfc3986#section-3.3 RFC3986, section 3.3}.
-@see #path
-@since 0.0.1
-=end
-  def initialize path
-    @path = path.to_s
-  end
-
-
-=begin markdown
-Does this resource _exists_?
-
-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`
-requests will still yield `404 Not Found`.
-
-@return [Boolean] The default implementation returns `false`.
-@since 0.0.1
-=end
-  def empty?
-    false
-  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>]
-@since 0.0.1
-=end
-  def http_methods
-    unless @djinn_resource_http_methods
-      @djinn_resource_http_methods = []
-      self.public_methods.each do
-        |public_method|
-        if ( match = /\Ado_([A-Z]+)\z/.match( public_method ) )
-          @djinn_resource_http_methods << match[1].to_sym
-        end
-      end
-      @djinn_resource_http_methods.delete :HEAD \
-        unless @djinn_resource_http_methods.include? :GET
-    end
-    @djinn_resource_http_methods
-  end
-
-
-=begin markdown
-Handles a HEAD request.
-
-As a courtesy, this module implements a default handler for HEAD requests,
-which calls {#do\_METHOD #do\_GET}, and then strips of the response body.
-
-If this resource implements method `content_types`, then `response['Content-Type']`
-will be set in the response object passed to {#do\_METHOD #do\_GET}.
-
-Feel free to override this method at will.
-@return [void]
-@raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement the `GET` method.
-@since 0.0.1
-=end
-  def do_HEAD request, response
-    raise Rackful::HTTPStatus, 'METHOD_NOT_ALLOWED ' +  self.http_methods.join( ' ' ) \
-      unless self.respond_to? :do_GET
-    self.do_GET request, response
-    response['Content-Length'] =
-      response.body.reduce(0) do
-        |memo, s| memo + bytesize(s)
-      end.to_s
-    response.body = []
-  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 [HTTPStatus] `404 Not Found` if this resource is empty.
-@since 0.0.1
-=end
-  def do_OPTIONS request, response
-    raise Rackful::HTTPStatus, 'NOT_FOUND' if self.empty?
-    response.status = status_code :no_content
-    response.header['Allow'] = self.http_methods.join ', '
-  end
-
-
-=begin markdown
-@!attribute [r] 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
-
-@abstract
-@return [String]
-@see http://tools.ietf.org/html/rfc2616#section-14.19 RFC2616 section 14.19
-@since 0.0.1
-=end
-
-
-=begin markdown
-@!attribute [r] 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
-@since 0.0.1
-=end
-
-
-=begin markdown
-Wrapper around {#do_HEAD}
-@private
-@return [void]
-@raise [HTTPStatus] `404 Not Found` if this resource is empty.
-@since 0.0.1
-=end
-  def http_HEAD request, response
-    raise Rackful::HTTPStatus, 'NOT_FOUND' if self.empty?
-    self.do_HEAD request, response
-  end
-
-
-=begin markdown
-Wrapper around {#do_METHOD #do_GET}
-@private
-@return [void]
-@raise [HTTPStatus]
-
-  -   `404 Not Found` if this resource is empty.
-  -   `405 Method Not Allowed` if the resource doesn't implement the `GET` method.
-@since 0.0.1
-=end
-  def http_GET request, response
-    raise Rackful::HTTPStatus, 'NOT_FOUND' if self.empty?
-    raise Rackful::HTTPStatus, 'METHOD_NOT_ALLOWED ' +  self.http_methods.join( ' ' ) \
-      unless self.respond_to? :do_GET
-    self.do_GET request, response
-  end
-
-
-=begin markdown
-Wrapper around {#do_METHOD #do_PUT}
-@private
-@return [void]
-@raise [HTTPStatus] `405 Method Not Allowed` if the resource doesn't implement the `PUT` method.
-@since 0.0.1
-=end
-  def http_PUT request, response
-    raise Rackful::HTTPStatus, 'METHOD_NOT_ALLOWED ' +  self.http_methods.join( ' ' ) \
-      unless self.respond_to? :do_PUT
-    self.do_PUT request, response
-  end
-
-
-end # module Resource
-
-
-=begin markdown
-@todo documentation
-@since 0.0.1
-=end
-class HTTPStatus < RuntimeError
-
-
-  include Rack::Utils
-
-
-  attr_reader :response
-
-
-=begin markdown
-@param message [String] `<status> [ <space> <message> ]`
-@since 0.0.1
-=end
-  def initialize( message )
-    @response = Rack::Response.new
-    matches = %r{\A(\S+)\s*(.*)\z}m.match(message.to_s)
-    status = status_code(matches[1].downcase.to_sym)
-    @response.status = status
-    message = matches[2]
-    case status
-    when 201, 301, 302, 303, 305, 307
-      message = message.split /\s+/
-      case message.length
-      when 0
-        message = ''
-      when 1
-        @response.header['Location'] = message[0]
-        message = "<p><a href=\"#{message[0]}\">#{escape_html(unescape message[0])}</a></p>"
-      else
-        message = '<ul>' + message.collect {
-          |url|
-          "\n<li><a href=\"#{url}\">#{escape_html(unescape url)}</a></li>"
-        }.join + '</ul>'
-      end
-    when 405 # Method not allowed
-      message = message.split /\s+/
-      @response.header['Allow'] = message.join ', '
-      message = '<h2>Allowed methods:</h2><ul><li>' +
-        message.join('</li><li>') + '</li></ul>'
-    when 406 # Unacceptable
-      message = message.split /\s+/
-      message = '<h2>Available representations:</h2><ul><li>' +
-        message.join('</li><li>') + '</li></ul>'
-    when 415 # Unsupported Media Type
-      message = message.split /\s+/
-      message = '<h2>Supported Media Types:</h2><ul><li>' +
-        message.join('</li><li>') + '</li></ul>'
-    end
-    super message
-    begin
-      REXML::Document.new \
-        '<?xml version="1.0" encoding="UTF-8" ?>' +
-        '<div>' + message + '</div>'
-    rescue
-      message = escape_html message
-    end
-    message = "<p>#{message}</p>" unless '<' == message[0, 1]
-    message = message.gsub( %r{\n}, "<br/>\n" )
-    @response.header['Content-Type'] = 'text/html; charset="UTF-8"'
-    @response.body = [ self.class.template.call( status, message ) ]
-  end
-
-
-  DEFAULT_TEMPLATE = lambda do
-    | status_code, xhtml_message |
-    status_code = status_code.to_i
-    xhtml_message = xhtml_message.to_s
-    <<EOS
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title>HTTP/1.1 #{status_code.to_s} #{HTTP_STATUS_CODES[status_code]}</title>
-  </head>
-  <body>
-    <h1>HTTP/1.1 #{status_code.to_s} #{HTTP_STATUS_CODES[status_code]}</h1>
-#{xhtml_message}
-  </body>
-</html>
-EOS
-  end
-
-
-=begin markdown
-Sets/gets the current template.
-
-The passed block must accept two arguments:
-
-1.  *int* a status code
-2.  *string* an xhtml fragment
-
-and return a string
-@since 0.0.1
-=end
-  def self.template(&block)
-    @template ||= ( block || DEFAULT_TEMPLATE )
-  end
-
-
-end
-
-
-=begin markdown
-Rack compliant server class for implementing RESTful web services.
-@since 0.0.1
-=end
-class Server
-
-
-=begin markdown
-An object responding thread safely to method `#[]`.
-
-A {Server} has no knowledge, and makes no presumptions, about your URI namespace.
-It requires a _Resource Factory_ which produces {Resource Resources} given
-a certain absolute path.
-
-The Resource Factory you provide need only implement one method, with signature
-`Resource #[]( String path )`.
-This method will be called with a URI-encoded path string, and must return a
-{Resource}, or `nil` if there's no resource at the given path.
-
-For example, if a Rackful client
-tries to access a resource with URI {http://example.com/your/resource http://example.com/some/resource},
-then your Resource Factory can expect to be called like this:
-
-    resource = resource_factory[ '/your/resource' ]
-
-If there's no resource at the given path, but you'd still like to respond to
-`POST` or `PUT` requests to this path, you must return an
-{Resource#empty? empty resource}.
-@return [#[]]
-@see #initialize
-@since 0.0.1
-=end
-  attr_reader :resource_factory
-
-
-=begin markdown
-{include:Server#resource_factory}
-@since 0.0.1
-=end
-  def initialize(resource_factory)
-    super()
-    @resource_factory = resource_factory
-  end
-
-
-=begin markdown
-As required by the Rack specification.
-
-For thread safety, this method clones `self`, which handles the request in
-{#call!}. A similar approach is taken by the Sinatra library.
-@return [Array<(status_code, response_headers, response_body)>]
-@since 0.0.1
-=end
-  def call(p_env)
-    start = Time.now
-    retval = dup.call! p_env
-    #$stderr.puts( 'Duration: ' + ( Time.now - start ).to_s )
-    retval
-  end
-
-
-=begin markdown
-@return [Array<(status_code, response_headers, response_body)>]
-@since 0.0.1
-=end
-  def call!(p_env)
-    request  = Rackful::Request.new( resource_factory, p_env )
-    # See also Request::current():
-    Thread.current[:djinn_request] = request
-    begin
-      response = Rack::Response.new
-      begin
-        raise HTTPStatus, 'NOT_FOUND' \
-          unless resource = self.resource_factory[request.path]
-        response.header['Content-Location'] = request.base_url + resource.path \
-          unless resource.path == request.path
-        request.assert_if_headers resource
-        if resource.respond_to? :"http_#{request.request_method}"
-          resource.__send__( :"http_#{request.request_method}", request, response )
-        elsif resource.respond_to? :"do_#{request.request_method}"
-          resource.__send__( :"do_#{request.request_method}", request, response )
-        else
-          raise HTTPStatus, 'METHOD_NOT_ALLOWED ' + resource.http_methods.join( ' ' )
-        end
-      rescue HTTPStatus
-        response = $!.response
-        raise if 500 == response.status
-        # The next line fixes a small peculiarity in RFC2616: the response body of
-        # a `HEAD` request _must_ be empty, even for responses outside 2xx.
-        if request.head?
-          response.body = []
-          response['Content-Length'] = '0'
-        end
-      end
-      if  201 == response.status &&
-          ( location = response['Location'] ) &&
-          ( new_resource = request.resource_factory[location] ) &&
-          ! new_resource.empty? \
-      or  ( (200...300) === response.status ||
-             304        ==  response.status ) &&
-          ! response['Location'] &&
-          ( new_resource = request.resource_factory[request.path] ) &&
-          ! new_resource.empty?
-        set_default_headers new_resource, response
-      end
-      response.finish
-    ensure
-      Thread.current[:djinn_request] = nil
-    end # begin
-  end
-
-
-private
-
-
-=begin markdown
-Adds `ETag:` and `Last-Modified:` response headers.
-@since 0.0.1
-=end
-  def set_default_headers resource, response
-    if ! response.include?( 'ETag' ) &&
-       resource.respond_to?( :etag )
-      response['ETag'] = resource.etag
-    end
-    if ! response.include?( 'Last-Modified' ) &&
-       resource.respond_to?( :last_modified )
-      response['Last-Modified'] = resource.last_modified[0].httpdate
-    end
-  end
-
-
-end # class Server
-
-
-end # module Rackful
+require 'rackful_path.rb'
+require 'rackful_request.rb'
+require 'rackful_serializer.rb'
+require 'rackful_resource.rb'
+require 'rackful_http_status.rb'
+require 'rackful_server.rb'