cloudkit 0.9.0

data/CHANGES

@@ -0,0 +1,2 @@
+0.9.0
+- First public gem release

data/COPYING

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jon Crosby http://joncrosby.me
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,55 @@
+=CloudKit
+
+CloudKit is an Open Web JSON Appliance.
+
+More specifically, CloudKit provides RESTful JSON storage with optional OpenID and OAuth support, including OAuth Discovery. Stored entities are versioned. Services manage their own storage and do not require schema updates when models change.
+
+CloudKit is Rack middleware and as such can be used on its own or alongside other Rack-based applications or middleware components like Rails, Merb or Sinatra.
+
+===Examples
+
+In a rackup file called config.ru:
+
+  require 'cloudkit'
+  expose :notes, :todos
+
+The above creates a versioned HTTP service using JSON to represent two types of resource collections -- Notes and ToDos.
+
+In a different rackup file:
+
+  require 'cloudkit'
+  contain :notes, :todos
+
+The aboves provides the same API as example 1 with added authentication and authorization via OpenID and OAuth, respectively.
+
+An explicit version of example 2, minus the default developer landing page:
+
+  require 'cloudkit'
+  use Rack::Pool::Session
+  use CloudKit::OAuthFilter
+  use CloudKit::OpenIDFilter
+  use CloudKit::Service, :collections => [:notes, :todos]
+  run lambda {|env| [200, {}, ['HELLO']]}
+
+See the examples directory for more.
+
+Copyright (c) 2008 Jon Crosby http://joncrosby.me
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'rake/clean'
+
+CLEAN.include 'doc/api'
+
+task :default => :test
+
+desc 'Run specs'
+task :test => FileList['test/*_test.rb'] do |t|
+  suite = t.prerequisites.map{|f| "-r#{f.chomp('.rb')}"}.join(' ')
+  sh "ruby -Ilib:test #{suite} -e ''", :verbose => false
+end
+
+desc 'Generate rdoc'
+task :rdoc do
+  rm_rf 'doc/api'
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --inline-source
+    --line-numbers
+    --include=lib/cloudkit.rb
+    --include=lib/cloudkit/*.rb
+    --include=lib/cloudkit/*/*.rb
+    --exclude=Rakefile
+    --exclude=TODO
+    --exclude=cloudkit.gemspec
+    --exclude=templates/*
+    --exclude=examples/*
+    --exclude=test/*
+    --exclude=doc/index.html
+    --exclude=doc/curl.html
+    --exclude=doc/rest-api.html
+    --exclude=doc/main.css
+    --op=doc/api
+  SH
+end

data/TODO

@@ -0,0 +1,22 @@
+1.0
+- jquery.cloudkit
+    titanium/gears
+- openid sreg
+- titanium middleware
+    version/upgrade middleware
+    rake automation
+- oauth token management
+- oauth consumer registration
+- acls i.e. allowed methods per user per uri
+- complete user data export
+- method filtering on collections
+- js functions as observers (validation, mapping, etc.)
+- custom templates for openid / oauth
+
+Backlog
+- expect header/100-continue
+- deployable gem + admin app
+- cappuccino adapter
+- sproutcore adapter
+- tokyocabinet
+- ldap adapter for UserStore

data/cloudkit.gemspec

@@ -0,0 +1,82 @@
+Gem::Specification.new do |s|
+  s.specification_version = 2 if s.respond_to? :specification_version=
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.name              = "cloudkit"
+  s.version           = "0.9.0"
+  s.date              = "2008-12-22"
+  s.summary           = "An Open Web JSON Appliance."
+  s.description       = "An Open Web JSON Appliance."
+  s.authors           = ["Jon Crosby"]
+  s.email             = "jon@joncrosby.me"
+  s.homepage          = "http://getcloudkit.com"
+  s.files             = %w[
+    CHANGES
+    cloudkit.gemspec
+    COPYING
+    README
+    Rakefile
+    TODO
+    doc/curl.html
+    doc/images/example-code.gif
+    doc/images/json-title.gif
+    doc/images/oauth-discovery-logo.gif
+    doc/images/openid-logo.gif
+    doc/index.html
+    doc/main.css
+    doc/rest-api.html
+    examples/1.ru
+    examples/2.ru
+    examples/3.ru
+    examples/4.ru
+    examples/5.ru
+    examples/6.ru
+    examples/TOC
+    lib/cloudkit.rb
+    lib/cloudkit/flash_session.rb
+    lib/cloudkit/oauth_filter.rb
+    lib/cloudkit/oauth_store.rb
+    lib/cloudkit/openid_filter.rb
+    lib/cloudkit/openid_store.rb
+    lib/cloudkit/rack/builder.rb
+    lib/cloudkit/rack/router.rb
+    lib/cloudkit/request.rb
+    lib/cloudkit/service.rb
+    lib/cloudkit/store.rb
+    lib/cloudkit/store/adapter.rb
+    lib/cloudkit/store/extraction_view.rb
+    lib/cloudkit/store/response.rb
+    lib/cloudkit/store/response_helpers.rb
+    lib/cloudkit/store/sql_adapter.rb
+    lib/cloudkit/templates/authorize_request_token.erb
+    lib/cloudkit/templates/oauth_descriptor.erb
+    lib/cloudkit/templates/oauth_meta.erb
+    lib/cloudkit/templates/openid_login.erb
+    lib/cloudkit/templates/request_authorization.erb
+    lib/cloudkit/templates/request_token_denied.erb
+    lib/cloudkit/user_store.rb
+    lib/cloudkit/util.rb
+    test/ext_test.rb
+    test/flash_session_test.rb
+    test/helper.rb
+    test/oauth_filter_test.rb
+    test/oauth_store_test.rb
+    test/openid_filter_test.rb
+    test/openid_store_test.rb
+    test/rack_builder_test.rb
+    test/request_test.rb
+    test/service_test.rb
+    test/store_test.rb
+    test/user_store_test.rb
+    test/util_test.rb
+  ]
+  s.test_files        = s.files.select {|path| path =~ /^test\/.*_test.rb/}
+  s.rubyforge_project = "cloudkit"
+  s.rubygems_version  = "1.1.1"
+  s.add_dependency 'rack', '~> 0.4'
+  s.add_dependency 'rack-config', '>= 0.9'
+  s.add_dependency 'uuid', '= 2.0.1'
+  s.add_dependency 'sequel', '= 2.6.0'
+  s.add_dependency 'oauth', '>= 0.2.7'
+  s.add_dependency 'ruby-openid', '= 2.1.2'
+  s.add_dependency 'json', '= 1.1.3'
+end

data/doc/curl.html

@@ -0,0 +1,329 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+  <title>CloudKit via cURL</title>
+  <link rel="stylesheet" href="main.css" type="text/css" charset="utf-8"/>
+</head>
+<body>
+  <div class="wrapper">
+    <ul class="nav">
+      <li><a href="rest-api.html" title="REST API">REST API</a></li>
+      <li><a href="curl.html" title="cURL Tutorial">cURL</a></li>
+      <li><a href="api" title="RDoc">RDoc</a></li>
+      <li><a href="http://github.com/jcrosby/cloudkit" title="GitHub Source Repository">Code</a></li>
+      <li><a href="http://blog.joncrosby.me" title="Author's Blog">Blog</a></li>
+    </ul>
+  </div>
+  <div id="header">
+    <div class="wrapper">
+      <h1><a href="index.html">CloudKit</a></h1>
+      <div class="subpage-subtitle">via cURL</div>
+    </div>
+  </div>
+  <div class="meta">
+    <p class="wrapper">
+  This is a tour of the CloudKit <a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">REST</a>/HTTP 1.1 API
+  using <a href="http://curl.haxx.se/docs/manpage.html">curl</a>. For the complete
+  spec, see the <a href="rest-api.html">CloudKit REST API</a>.
+    </p>
+  </div>
+<div class="wrapper">
+<p>
+If you haven't already installed the gem:
+  <div class="code">
+    $ gem install cloudkit
+  </div>
+</p>
+
+<p>
+Create a rackup file named config.ru, containing these two lines of code:
+  <div class="code">
+    require 'cloudkit'<br/>
+    expose :notes
+  </div>
+</p>
+
+<p>
+Run the app using <a href="http://code.macournoyer.com/thin">Thin</a>:
+  <div class="code">
+    $ thin start -R config.ru
+  </div>
+</p>
+
+<p>
+CloudKit is discoverable from top to bottom. Let's see what resource collections
+we're hosting:
+  <div class="code">
+    $ curl -i http://localhost:3000/cloudkit-meta<br/>
+    HTTP/1.1 200 OK<br/>
+    ETag: "ef2f29b1834ef8c2bf0d8f1abb100177"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 20<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"uris":["\/notes"]}
+  </div>
+</p>
+
+<p>
+See what we can do with these note resources:
+  <div class="code">
+    $ curl -i -XOPTIONS http://localhost:3000/notes<br/>
+    HTTP/1.1 200 OK<br/>
+    Content-Length: 0<br/>
+    Allow: GET, HEAD, POST, OPTIONS<br/>
+    Connection: keep-alive<br/>
+  </div>
+</p>
+
+<p>
+List the currently available notes:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes<br/>
+    HTTP/1.1 200 OK<br/>
+    ETag: "df392c5664e6ecd64b83210fb925f6c8"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 32<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"uris":[],"total":0,"offset":0}
+  </div>
+</p>
+
+<p>
+The Link header will be explained momentarily.
+</p>
+
+<p>
+Create a note using <a href="http://tools.ietf.org/html/rfc2616#section-9.5">POST</a>:
+  <div class="code">
+    $ curl -i -XPOST -d'{"title":"projects"}' http://localhost:3000/notes<br/>
+    HTTP/1.1 201 Created<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 159<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uri":"\/notes\/0dda06f0-b134-012b-a2d8-0017f2c62348",<br/>
+      "ok":true,<br/>
+      "etag":"0dda0de0-b134-012b-a2d8-0017f2c62348",<br/>
+      "last_modified":"Sun, 21 Dec 2008 02:21:52 GMT"<br/>
+    }
+  </div>
+</p>
+
+<p>
+List the currently available notes again:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes<br/>
+    HTTP/1.1 200 OK<br/>
+    Last-Modified: Sun, 21 Dec 2008 02:21:52 GMT<br/>
+    ETag: "dd30142ff023386d2515b41fb88447a5"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 79<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uris":["\/notes\/0dda06f0-b134-012b-a2d8-0017f2c62348"],<br/>
+      "total":1,<br/>
+      "offset":0<br/>
+    }
+  </div>
+</p>
+
+<p>
+Create a note using <a href="http://tools.ietf.org/html/rfc2616#section-9.6">PUT</a>
+so that we can specify its location:
+  <div class="code">
+    $ curl -i -XPUT -d'{"title":"reminders"}' http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 201 Created<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 126<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uri":"\/notes\/abc",<br/>
+      "ok":true,<br/>
+      "etag":"89487620-b134-012b-a2d8-0017f2c62348",<br/>
+      "last_modified":"Sun, 21 Dec 2008 02:25:19 GMT"<br/>
+    }
+  </div>
+</p>
+
+<p>
+View the new note:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 200 OK<br/>
+    Last-Modified: Sun, 21 Dec 2008 02:25:19 GMT<br/>
+    ETag: "89487620-b134-012b-a2d8-0017f2c62348"<br/>
+    Link: &lt;http://localhost:3000/notes/abc/versions&gt;; rel="http://joncrosby.me/cloudkit/1.0/rel/versions"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 21<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"title":"reminders"}
+  </div>
+</p>
+
+<p>
+Along with the usual metadata, individual resources also provide discovery
+information via
+<a href="http://www.mnot.net/drafts/draft-nottingham-http-link-header-03.txt">Link Headers</a>
+as shown above. These links allow user agents to find related resources such as
+the complete history of a document and its
+<a href="http://tools.ietf.org/html/rfc2616#section-14.19">ETags</a>.
+The utility of these items will be demonstrated momentarily.
+</p>
+
+<p>
+Attempt a careless update and enjoy the failure:
+  <div class="code">
+    $ curl -i -XPUT -d'{"title":"foo"}' http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 400 Bad Request<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 25<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"error":"etag required"}
+  </div>
+</p>
+
+<p>
+Succeed in updating by being specific:
+  <div class="code">
+    $ curl -i -XPUT -H'If-Match:89487620-b134-012b-a2d8-0017f2c62348' -d'{"title":"foo"}' http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 200 OK<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 126<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uri":"\/notes\/abc",<br/>
+      "ok":true,<br/>
+      "etag":"522be9f0-b135-012b-a2d8-0017f2c62348",<br/>
+      "last_modified":"Sun, 21 Dec 2008 02:30:56 GMT"<br/>
+    }
+  </div>
+</p>
+
+<p>
+(Note: Your ETag will likely be different so substitute the one that curl
+provided when you created your own "abc" resource.)
+</p>
+
+<p>
+Watch a secondary, out-of-date client fail at updating by being specific but also being stale:
+  <div class="code">
+    $ curl -i -XPUT -H'If-Match:89487620-b134-012b-a2d8-0017f2c62348' -d'{"title":"foo"}' http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 412 Precondition Failed<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 31<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"error":"precondition failed"}
+  </div>
+</p>
+
+<p>
+A <a href="http://tools.ietf.org/html/rfc2616#section-10.4.13">412</a> code is
+returned indicating a precondition for this request failed. Specifically, the
+ETag was out of date. In this case, our second client can fall back on the
+resource's history to "catch up" and apply its changes to the most recent
+version of the resource.
+</p>
+
+<p>
+Get all versions of the document using the URI tagged with rel="versions" in the
+link header mentioned above, reverse sorted by Last-Modified, feed style:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes/abc/versions<br/>
+    HTTP/1.1 200 OK<br/>
+    Last-Modified: Sun, 21 Dec 2008 02:30:56 GMT<br/>
+    ETag: "bd9226d0c5f34fd761f6c64a0fe8bcc9"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 109<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uris":[<br/>
+        "\/notes\/abc",<br/>
+        "\/notes\/abc\/versions\/89487620-b134-012b-a2d8-0017f2c62348"<br/>
+      ],<br/>
+      "total":2,<br/>
+      "offset":0<br/>
+    }
+  </div>
+</p>
+
+<p>
+Delete the document:
+  <div class="code">
+    $ curl -i -XDELETE -H'If-Match:522be9f0-b135-012b-a2d8-0017f2c62348' http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 200 OK<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 174<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uri":"\/notes\/abc\/versions\/522be9f0-b135-012b-a2d8-0017f2c62348",<br/>
+      "ok":true,<br/>
+      "etag":"522be9f0-b135-012b-a2d8-0017f2c62348",<br/>
+      "last_modified":"Sun, 21 Dec 2008 02:30:56 GMT"<br/>
+    }
+  </div>
+</p>
+
+<p>
+Try to GET it again and notice the helpful <a href="http://tools.ietf.org/html/rfc2616#section-10.4.11">410</a>:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes/abc<br/>
+    HTTP/1.1 410 Gone<br/>
+    Link: &lt;http://localhost:3000/notes/abc/versions&gt;; rel="http://joncrosby.me/cloudkit/1.0/rel/versions"<br/>
+    Cache-Control: no-cache<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 37<br/>
+    Connection: keep-alive<br/><br/>
+
+    {"error":"entity previously deleted"}
+  </div>
+</p>
+
+<p>
+Notice the history is preserved:
+  <div class="code">
+    $ curl -i http://localhost:3000/notes/abc/versions<br/>
+    HTTP/1.1 200 OK<br/>
+    Last-Modified: Sun, 21 Dec 2008 02:30:56 GMT<br/>
+    ETag: "2308ee33e953c9be41221ff7612e5217"<br/>
+    Cache-Control: proxy-revalidate<br/>
+    Content-Type: application/json<br/>
+    Content-Length: 157<br/>
+    Connection: keep-alive<br/><br/>
+
+    {<br/>
+      "uris":[<br/>
+        "\/notes\/abc\/versions\/522be9f0-b135-012b-a2d8-0017f2c62348",<br/>
+        "\/notes\/abc\/versions\/89487620-b134-012b-a2d8-0017f2c62348"<br/>
+      ],<br/>
+      "total":2,<br/>
+      "offset":0<br/>
+    }
+  </div>
+</p>
+</div>
+</body>
+</html>