rackful 0.1.0 → 0.1.1

data/CHANGES.md

@@ -0,0 +1,30 @@
+0.1.x
+=====
+The 0.1.x series is a major revision, not backward compatible with 0.0.x.
+
+0.1.1
+-----
+*   Fixed the gemspec file. Not everything new was properly included (including
+    this changelog!).
+
+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"
+    strings, and render them accordingly.
+*   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}.
+*   The mechanism for implementing HTTP method handlers has changed. See
+    {Rackful::Resource#do_METHOD} and {Rackful::Resource::ClassMethods#add_parser}.
+
+0.0.x
+=====
+
+0.0.2
+-----
+*   Improved documentation

data/RACKFUL.md

@@ -0,0 +1,159 @@
+Rackful
+=======
+
+Library for creating Rackful web services
+
+The latest documentation is always available
+[here, as GitHub pages](http://pieterb.github.com/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...
+
+    _...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,
+    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#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.
+
+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.

data/rackful.gemspec

@@ -2,7 +2,7 @@ Gem::Specification.new do |s|
 
   # Required properties:
   s.name        = 'rackful'
-  s.version     = '0.1.0'
+  s.version     = '0.1.1'
   s.summary     = "Library for building ReSTful web services with Rack"
   s.description = <<EOS
 Rackful provides a minimal interface for developing ReSTful web services with
@@ -11,8 +11,8 @@ resource objects, which expose their state at URLs.
 
 This version is NOT backward compatible with versions 0.0.x.
 EOS
-  s.files       = Dir[ '{example/*,lib/**/*}' ] +
-                  %w( rackful.gemspec README.md LICENSE.md mkdoc.sh )
+  s.files       = Dir[ '{*.md,example/*,lib/**/*}' ] +
+                  %w( rackful.gemspec mkdoc.sh )
 
   # Optional properties:
   s.author      = 'Pieter van Beek'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rackful
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-04 00:00:00.000000000Z
+date: 2012-08-05 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70130076580680 !ruby/object:Gem::Requirement
+  requirement: &70177120280540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *70130076580680
+  version_requirements: *70177120280540
 description: ! 'Rackful provides a minimal interface for developing ReSTful web services
   with
 
@@ -38,6 +38,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGES.md
+- LICENSE.md
+- RACKFUL.md
+- README.md
 - example/config.ru
 - example/config2.ru
 - lib/rackful/header_spoofing.rb
@@ -51,8 +55,6 @@ files:
 - lib/rackful_serializer.rb
 - lib/rackful_server.rb
 - rackful.gemspec
-- README.md
-- LICENSE.md
 - mkdoc.sh
 homepage: http://pieterb.github.com/Rackful/
 licenses: