rackful 0.1.4 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9219f743c670f4a149826fcf581a97e7c08251d6
+  data.tar.gz: 10ec5c1eb9c59f3d7adda6ed9be9518773311ba9
+SHA512:
+  metadata.gz: f3d112684686175bc973cd240cce7bf899684fe115184ea94b0cd4797d49aa45a1b939983f5af12f9cc3702a03eb541030023319205996bae5b951711e2fd783
+  data.tar.gz: a44bd266844173251e1c0a4ac35c9b7a3be32a77bfd4e369773cb6b49cecc47867e766e04cc8d0bf3eb0f2cbe28779dda4a7b52823b9104ce9e585ad0fec342b

data/CHANGES.md

@@ -1,3 +1,14 @@
+0.2.x
+=====
+The 0.2.x series is a major revision, not backward compatible with 0.1.x.
+
+0.2.0
+-----
+*   Removed Request::current, because it won’t work well with single-threaded
+    concurrency models (fibers, eventmachine and the like) and it’s not essential.
+*   Rackful::Server#call was made reentrant. This is necessary for response code
+    100 Continue.
+
 0.1.x
 =====
 The 0.1.x series is a major revision, not backward compatible with 0.0.x.
@@ -9,18 +20,17 @@ The 0.1.x series is a major revision, not backward compatible with 0.0.x.
 
 0.1.0
 -----
-*   Complete revision of the {Rackful::HTTPStatus} exception class. From now on,
-    there's
-    a separate class for each HTTP status code, e.g. {Rackful::HTTP404NotFound}.
-*   {Rackful::Path}, a subclass of `String`, is used for HTTP paths. This allows
-    serializers, especially for hypermedia, to distinguish paths from "ordinary"
+*   Complete revision of the `Rackful::HTTPStatus` exception class. From now on, there’s
+    a separate class for each HTTP status code, e.g. `Rackful::HTTP404NotFound`.
+*   `Rackful::Path`, a subclass of `String`, is used for HTTP paths. This allows
+    serializers, especially for hypermedia, to distinguish paths from “ordinary”
     strings, and render them accordingly.
-*   The concept of {Rackful::Serializer Serializers} was introduced. A serializer
+*   The concept of `Rackful::Serializer Serializers` was introduced. A serializer
     is an object that knows how to serialize an object to a certain media type.
 *   The mechanism for content negotiation has changed completely. See
-    {Rackful::Resource#serializer} and {Rackful::Resource::ClassMethods#best_content_type}.
+    `Rackful::Resource#serializer` and `Rackful::Resource::ClassMethods#best_content_type`.
 *   The mechanism for implementing HTTP method handlers has changed. See
-    {Rackful::Resource#do_METHOD} and {Rackful::Resource::ClassMethods#add_parser}.
+    `Rackful::Resource#do_METHOD` and `Rackful::Resource::ClassMethods#add_parser`.
 
 0.0.x
 =====

data/RACKFUL.md

@@ -1,25 +1,27 @@
-Rackful
-=======
+# @title Rackful
 
-Library for creating Rackful web services
+Library for creating ReSTful web services
 
-The latest documentation is always available
-[here, as GitHub pages](http://pieterb.github.com/Rackful/).
+The latest “stable” documentation can be found here:
 
-Rationale
----------
+* [User documentation](http://pieterb.github.com/Rackful/)
+* [Developer documentation](http://pieterb.github.com/Rackful/devel/) (includes
+  documentation for private methods and other internals)
 
-Confronted with the task of implementing a Rackful web service in Ruby, I
+Overview
+========
+
+Confronted with the task of implementing a ReSTful 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
+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
+    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.
+    ReSTful web service programming.
 
     This library is small. You could read _all_ the source code in less than an
     hour, and understand every detail.
@@ -28,20 +30,20 @@ find a library or framework with all of the following properties:
     subject of more than one flame-war over the years. Not much I can add to the
     debate...
 
-    _...but,_ with Ruby, you shouldn't _need_ code generation!
-    Unless, of course, you're an ex-Java programmer and/or don't understand
+    _...but,_ with Ruby, you shouldn’t _need_ code generation!
+    Unless, of course, you’re an ex-Java programmer and/or don’t understand
     meta-programming.
 
 *   **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,
+    libraries’ support is limited to `If-None-Match:` and `If-Modified-Since:`
+    headers, and only for `GET` and `HEAD` requests. For ReSTful 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
+*   **Resource centered** Some libraries claim ReSTfulness, 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.
@@ -52,7 +54,7 @@ find a library or framework with all of the following properties:
 Hello World!
 ------------
 
-Here's a working example of a simple Rackful server:
+Here’s a working example of a simple ReSTful server:
 
 {include:file:example/config.ru}
 
@@ -67,7 +69,7 @@ something like this:
 
 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
+In this example, we implement `GET` and `PUT` requests for the resource at “/”. but
 we get a few things for free:
 
 ### Free `OPTIONS` response:
@@ -79,36 +81,36 @@ Request:
 
 Response:
 
-    HTTP/1.1 204 No Content 
+    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
+`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:
+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 
+    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
+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
@@ -116,7 +118,7 @@ produce an `If-Match:` header, with the entity tag of our last version:
     Content-Type: text/plain
     Content-Length: 31
     If-Match: "86fb269d190d2c85f6e0468ceca42a20"
-    
+
     All your base are belong to us.
 
 Response:
@@ -131,7 +133,7 @@ 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>
@@ -143,17 +145,27 @@ response body, the server kindly points out exactly which precondition.
 Further reading
 ---------------
 *   {Rackful::Server#initialize} for more information about your Resource Factory.
-*   {Rackful::Resource#get\_etag} and {Rackful::Resource#get\_last\_modified} for more information on
-    conditional requests.
+*   {Rackful::Resource#get\_etag} and {Rackful::Resource#get\_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.
+
+Development
+===========
+Some conventions used throughout the code and documentation:
+
+*   In {Rack}, URLs are represented by Ruby Strings. In Rackful, URLs are
+    represented by objects of class {::URI::HTTP} wherever possible. This can
+    lead to confusion. As a convention, methods and variables that return/contain
+    a URL String have `url` in their names. while methods and variables that
+    return/contain a {::URI::HTTP} object have `uri` in their names. Yes, it’s
+    ugly, but it helps.
+*   URI’s are stored and passed around in their {::URI::Generic#normalize normalized}
+    form wherever possible.
 
 Licensing
----------
-Copyright ©2011-2012 Pieter van Beek <pieterb@sara.nl>
+=========
+Copyright ©2011-2014 Pieter van Beek <pieter@djinnit.com>
 
 Licensed under the {file:LICENSE.md Apache License 2.0}. You should have received a copy of the
 license as part of this distribution.

data/README.md

@@ -1,14 +1,20 @@
 Rackful
 =======
 
-Library for creating Rackful web services
+Library for creating ReSTful web services
 
-The latest documentation is always available
-[here, as GitHub pages](http://pieterb.github.com/Rackful/).
+The latest “stable” documentation can be found here:
+
+* [User documentation](http://pieterb.github.com/Rackful/)
+* [Developer documentation](http://pieterb.github.com/Rackful/devel/) (includes
+  documentation for private methods and other internals)
+
+Documentation for older versions:
+* [User documentation v0.1.5](http://pieterb.github.com/Rackful/0.1.5)
 
 Licensing
 ---------
-Copyright ©2011-2012 Pieter van Beek <pieterb@sara.nl>
+Copyright ©2011-2014 Pieter van Beek <pieter@djinnit.com>
 
-Licensed under the Apache License 2.0. You should have received a copy of the
+Licensed under the {file:LICENSE.md Apache License 2.0}. You should have received a copy of the
 license as part of this distribution.

data/example/config.ru

@@ -1,44 +1,38 @@
 # Load core functionality:
 require 'rackful'
 
-# Load extra middlewares: ({Rackful::MethodSpoofing}, {Rackful::HeaderSpoofing},
-# Rackful::RelativeLocation})
+# Load extra middlewares: ({Rackful::MethodOverride}, {Rackful::HeaderSpoofing})
 require 'rackful/middleware'
 
 require 'digest/md5'
 
 # The class of the object we're going to serve:
-class Root
-  include Rackful::Resource
+class Root < Rackful::Resource
   attr_reader :to_rackful
   def initialize
-    self.path = '/'
-    @to_rackful = 'Hello world!'
+    super( 'http://localhost:9292/hallo_wereld' )
+    @to_rackful = {
+      :a => 'Hello',
+      :b => Time.now,
+      :c => URI('http://www.example.com/some/path') }
   end
   def do_PUT request, response
-    @to_rackful = request.body.read.encode( Encoding::UTF_8 )
+    @to_rackful = self.parser(request).parse
   end
   def get_etag
-    '"' + Digest::MD5.new.update(to_rackful).to_s + '"'
+    '"' + Digest::MD5.new.update(to_rackful.inspect).to_s + '"'
   end
-  add_serializer Rackful::XHTML, 1.0
-  add_serializer Rackful::JSON, 1.0
-  add_media_type 'text/plain'
+  add_serializer Rackful::Serializer::XHTML, 1.0
+  add_serializer Rackful::Serializer::JSON, 0.5
+  add_parser Rackful::Parser::XHTML
+  add_parser Rackful::Parser::JSON
 end
-$root_resource = Root.new
+$root_resource = nil
 
-# Rackful::Server needs a resource factory which can map URIs to resource objects:
-class ResourceFactory
-  def [] uri
-    case uri
-    when '/';   $root_resource
-    else;       nil
-    end
-  end
-end
-
-use Rackful::MethodSpoofing
+use Rack::Reloader
+use Rackful::MethodOverride
 use Rackful::HeaderSpoofing
-use Rackful::RelativeLocation
 
-run Rackful::Server.new ResourceFactory.new
+run Rackful::Server.new { |uri|
+  $root_resource ||= Root.new
+}

data/lib/rackful.rb

@@ -1,6 +1,15 @@
-require 'rackful/path.rb'
+require 'uri'
+require 'nokogiri'
+require 'rack'
+require 'rack/utils'
+require 'base64'
+require 'time'
+require 'json'
+
+require 'rackful/uri.rb'
 require 'rackful/request.rb'
 require 'rackful/serializer.rb'
+require 'rackful/parser.rb'
 require 'rackful/resource.rb'
-require 'rackful/http_status.rb'
+require 'rackful/httpstatus.rb'
 require 'rackful/server.rb'

data/lib/rackful/httpstatus.rb

@@ -0,0 +1,250 @@
+# encoding: utf-8
+# Required for parsing:
+require 'rackful/resource.rb'
+require 'rackful/serializer.rb'
+
+
+module Rackful
+
+=begin markdown
+Exception which represents an HTTP Status response.
+@abstract
+=end
+class HTTPStatus < RuntimeError
+
+
+  class Resource < ::Rackful::Resource
+    class XHTML < Serializer::XHTML
+
+
+      def header
+        retval = super
+        retval += "<h1>HTTP/1.1 #{Rack::Utils.escape_html(resource.title)}</h1>\n"
+        unless resource.message.empty?
+          retval += "<div id=\"rackful-description\">#{resource.message}</div>\n"
+        end
+        retval
+      end
+
+
+      def headers; self.resource.headers; end
+
+
+    end # class Rackful::HTTPStatus::XHTML
+
+
+    add_serializer XHTML, 1.0
+
+    extend Forwardable
+    def_delegators :@http_status_object, :headers, :to_rackful, :title, :message
+
+
+    def initialize(uri, http_status_object)
+      super(uri)
+      @http_status_object = http_status_object
+    end
+
+
+  end # class Rackful::HTTPStatus::Resource
+
+
+  attr_reader :status, :headers, :to_rackful
+
+
+=begin markdown
+@param status [Symbol, Integer] e.g. `404` or `:not_found`
+@param message [String] XHTML
+@param info [ { Symbol => Object, String => String } ]
+    *   **Objects** indexed by **Symbols** are returned in the response body.
+    *   **Strings** indexed by **Strings** are returned as response headers.
+=end
+  def initialize status, message = nil, info = {}
+    @status = Rack::Utils.status_code status
+    raise "Wrong status: #{status}" if 0 === @status
+    message ||= ''
+    @headers = {}
+    @to_rackful = {}
+    info.each do
+      |k, v|
+      if k.kind_of? Symbol
+        @to_rackful[k] = v
+      else
+        @headers[k] = v.to_s
+      end
+    end
+    @to_rackful = nil if @to_rackful.empty?
+    if message
+      message = message.to_s
+      begin
+        Nokogiri.XML(
+          '<?xml version="1.0" encoding="UTF-8" ?>' +
+          "<div>#{message}</div>"
+        ) do |config| config.strict.nonet end
+      rescue
+        message = Rack::Utils.escape_html(message)
+      end
+    end
+    super message
+  end
+  
+  def serializer request
+    Resource.new( request.url, self ).serializer( request )
+  end
+
+  def title
+    "#{status} #{Rack::Utils::HTTP_STATUS_CODES[status]}"
+  end
+
+
+ 
+end # class Rackful::HTTPStatus
+
+
+=begin markdown
+@abstract Base class for HTTP status codes with only a simple text message, or
+  no message at all.
+=end
+class HTTPSimpleStatus < HTTPStatus
+
+  def initialize message = nil
+    /HTTP(\d\d\d)\w+\z/ === self.class.to_s
+    status = $1.to_i
+    super( status, message )
+  end
+
+end
+
+
+class HTTP201Created < HTTPStatus
+
+  def initialize locations
+    locations = [ locations ] unless locations.kind_of? Array
+    locations = locations.collect { |l| URI(l) }
+    if locations.size > 1
+      super( 201, 'New resources were created:', :locations => locations )
+    else
+      location = locations[0]
+      super(
+        201, 'A new resource was created:',
+        :"Location" => location, 'Location' => location
+      )
+    end
+  end
+
+end
+
+
+class HTTP202Accepted < HTTPStatus
+
+  def initialize location = nil
+    if location
+      location = URI(location)
+      super(
+        202, "The request body you sent has been accepted for processing.",
+        :"Job status location:" => location, 'Location' => location
+      )
+    else
+      super 202
+    end
+  end
+
+end
+
+
+class HTTP301MovedPermanently < HTTPStatus
+
+  def initialize location
+    location = URI(location)
+    super( 301, '', :'New location:' => location, 'Location' => location )
+  end
+
+end
+
+
+class HTTP303SeeOther < HTTPStatus
+
+  def initialize location
+    location = URI(location)
+    super( 303, '', :'See:' => location, 'Location' => location )
+  end
+
+end
+
+
+class HTTP304NotModified < HTTPStatus
+
+  def initialize
+    super( 304 )
+  end
+
+end
+
+
+class HTTP307TemporaryRedirect < HTTPStatus
+
+  def initialize location
+    location = URI(location)
+    super( 301, '', :'Current location:' => location, 'Location' => location )
+  end
+
+end
+
+
+class HTTP400BadRequest < HTTPSimpleStatus; end
+
+class HTTP403Forbidden < HTTPSimpleStatus; end
+
+class HTTP404NotFound < HTTPSimpleStatus; end
+
+
+class HTTP405MethodNotAllowed < HTTPStatus
+
+  def initialize methods
+    super( 405, '', 'Allow' => methods.join(', '), :'Allowed methods:' => methods )
+  end
+
+end
+
+
+class HTTP406NotAcceptable < HTTPStatus
+
+  def initialize content_types
+    super( 406, '', :'Available content-type(s):' => content_types )
+  end
+
+end
+
+
+class HTTP409Conflict < HTTPSimpleStatus; end
+
+class HTTP410Gone < HTTPSimpleStatus; end
+
+class HTTP411LengthRequired < HTTPSimpleStatus; end
+
+
+class HTTP412PreconditionFailed < HTTPStatus
+
+  def initialize header = nil
+    info = header ? { :'Failed precondition:' => header } : {}
+    super( 412, '', info )
+  end
+
+end
+
+
+class HTTP415UnsupportedMediaType < HTTPStatus
+
+  def initialize media_types
+    super( 415, '', :'Supported media-type(s):' => media_types )
+  end
+
+end
+
+
+class HTTP422UnprocessableEntity < HTTPSimpleStatus; end
+
+class HTTP501NotImplemented < HTTPSimpleStatus; end
+
+class HTTP503ServiceUnavailable < HTTPSimpleStatus; end
+
+end # module Rackful