cloudkit-jruby 0.11.2

data/lib/cloudkit/rack/router.rb

@@ -0,0 +1,20 @@
+module Rack #:nodoc:
+
+  # A minimal router providing just what is needed for the OAuth and OpenID
+  # filters.
+  class Router
+
+    # Create an instance of Router to match on method, path and params.
+    def initialize(method, path, params=[])
+      @method = method.to_s.upcase; @path = path; @params = params
+    end
+
+    # By overriding the case comparison operator, we can match routes in a case
+    # statement.
+    #
+    # See also: CloudKit::Util#r, CloudKit::Request#match?
+    def ===(request)
+      request.match?(@method, @path, @params)
+    end
+  end
+end

data/lib/cloudkit/request.rb

@@ -0,0 +1,177 @@
+module CloudKit
+
+  # A subclass of Rack::Request providing CloudKit-specific features.
+  class Request < Rack::Request
+    include CloudKit::Util
+    alias_method :cloudkit_params, :params
+
+    def initialize(env)
+      super(env)
+    end
+
+    # Return a merged set of both standard params and OAuth header params.
+    def params
+      @cloudkit_params ||= cloudkit_params.merge(oauth_header_params)
+    end
+
+    # Return the JSON content from the request body
+    def json
+      self.body.rewind
+      raw = self.body.read
+      # extract the json from the body to avoid tunneled _method param from being parsed as json
+      (matches = raw.match(/(\{.*\})/)) ? matches[1] : raw
+    end
+
+    # Return a CloudKit::URI instance representing the rack request's path info.
+    def uri
+      @uri ||= CloudKit::URI.new(self.path_info)
+    end
+
+    # Return true if method, path, and required_params match.
+    def match?(method, path, required_params=[])
+      (request_method == method) &&
+        path_info.match(path.gsub(':id', '*')) && # just enough to work for now
+        param_match?(required_params)
+    end
+
+    # Return true of the array of required params match the request params. If
+    # a hash in passed in for a param, its value is also used in the match.
+    def param_match?(required_params)
+      required_params.all? do |required_param|
+        case required_param
+        when Hash
+          key = required_param.keys.first
+          return false unless params.has_key? key
+          return false unless params[key] == required_param[key]
+        when String
+          return false unless params.has_key? required_param
+        else
+          false
+        end
+        true
+      end
+    end
+
+    # Return OAuth header params in a hash.
+    def oauth_header_params
+      # This is a copy of the same method from the OAuth gem.
+      # TODO: Refactor the OAuth gem so that this method is available via a
+      # mixin, outside of the request proxy context.
+      %w( X-HTTP_AUTHORIZATION Authorization HTTP_AUTHORIZATION ).each do |header|
+        next unless @env.include?(header)
+        header = @env[header]
+        next unless header[0,6] == 'OAuth '
+        oauth_param_string = header[6,header.length].split(/[,=]/)
+        oauth_param_string.map!{|v| unescape(v.strip)}
+        oauth_param_string.map!{|v| v =~ /^\".*\"$/ ? v[1..-2] : v}
+        oauth_params = Hash[*oauth_param_string.flatten]
+        oauth_params.reject!{|k,v| k !~ /^oauth_/}
+        return oauth_params
+      end
+      return {}
+    end
+
+    # Unescape a value according to the OAuth spec.
+    def unescape(value)
+      ::URI.unescape(value.gsub('+', '%2B'))
+    end
+
+    # Return the last path element in the request URI.
+    def last_path_element
+      path_element(-1)
+    end
+
+    # Return a specific path element
+    def path_element(index)
+      path_info.split('/')[index] rescue nil
+    end
+
+    # Return an array containing one entry for each piece of upstream
+    # middleware. This is in the same spirit as Via headers in HTTP, but does
+    # not use the header because the transition from one piece of middleware to
+    # the next does not use HTTP.
+    def via
+      @env[CLOUDKIT_VIA].split(', ') rescue []
+    end
+
+    # Return parsed contents of an If-Match header.
+    #
+    # Note: Only a single ETag is useful in the context of CloudKit, so a list
+    # is treated as one ETag; the result of using the wrong ETag or a list of
+    # ETags is the same in the context of PUT and DELETE where If-Match
+    # headers are required.
+    def if_match
+      etag = @env['HTTP_IF_MATCH']
+      return nil unless etag
+      etag.strip!
+      etag = unquote(etag)
+      return nil if etag == '*'
+      etag
+    end
+
+    # Add a via entry to the Rack environment.
+    def inject_via(key)
+      items = via << key
+      @env[CLOUDKIT_VIA] = items.join(', ')
+    end
+
+    # Return the current user URI.
+    def current_user
+      return nil unless @env[CLOUDKIT_AUTH_KEY] && @env[CLOUDKIT_AUTH_KEY] != ''
+      @env[CLOUDKIT_AUTH_KEY]
+    end
+
+    # Set the current user URI.
+    def current_user=(user)
+      @env[CLOUDKIT_AUTH_KEY] = user
+    end
+
+    # Return true if authentication is being used.
+    def using_auth?
+      @env[CLOUDKIT_AUTH_PRESENCE] != nil
+    end
+
+    # Report to downstream middleware that authentication is in use.
+    def announce_auth(via)
+      inject_via(via)
+      @env[CLOUDKIT_AUTH_PRESENCE] = 1
+    end
+
+    # Return the session associated with this request.
+    def session
+      @env['rack.session']
+    end
+
+    # Return the login URL for this request. This is stashed in the Rack
+    # environment so the OpenID and OAuth middleware can cooperate during the
+    # token authorization step in the OAuth flow.
+    def login_url
+      @env[CLOUDKIT_LOGIN_URL] || '/login'
+    end
+
+    # Set the login url for this request.
+    def login_url=(url)
+      @env[CLOUDKIT_LOGIN_URL] = url
+    end
+
+    # Return the logout URL for this request.
+    def logout_url
+      @env[CLOUDKIT_LOGOUT_URL] || '/logout'
+    end
+
+    # Set the logout URL for this request.
+    def logout_url=(url)
+      @env[CLOUDKIT_LOGOUT_URL] = url
+    end
+
+    # Return the flash session for this request.
+    def flash
+      session[CLOUDKIT_FLASH] ||= CloudKit::FlashSession.new
+    end
+
+    # Return the host and scheme
+    def domain_root
+      "#{scheme}://#{@env['HTTP_HOST']}"
+    end
+  end
+end

data/lib/cloudkit/service.rb

@@ -0,0 +1,162 @@
+module CloudKit
+
+  # A CloudKit Service is Rack middleware providing a REST/HTTP 1.1 interface to
+  # a Store. Its primary purpose is to initialize and adapt a Store for use in a
+  # Rack middleware stack.
+  #
+  # ==Examples
+  #
+  # A rackup file exposing _items_ and _things_ as REST collections:
+  #   require 'cloudkit'
+  #   expose :items, :things
+  #
+  # The same as above, adding OpenID and OAuth/Discovery:
+  #   require 'cloudkit'
+  #   contain :items, :things
+  #
+  # An explicit setup, without using the Rack::Builder shortcuts:
+  #   require 'cloudkit'
+  #   use Rack::Session::Pool
+  #   use CloudKit::OAuthFilter
+  #   use CloudKit::OpenIDFilter
+  #   use CloudKit::Service, :collections => [:items, :things]
+  #   run lambda{|env| [200, {'Content-Type' => 'text/html'}, ['Hello']]}
+  #
+  # For more examples, including the use of different storage implementations,
+  # see the Table of Contents in the examples directory.
+  class Service
+    include ResponseHelpers
+
+    @@lock = Mutex.new
+
+    attr_reader :store
+
+    def initialize(app, options)
+      @app         = app
+      @collections = options[:collections]
+    end
+
+    def call(env)
+      @@lock.synchronize do
+        @store = Store.new(:collections => @collections)
+      end unless @store
+
+      request = Request.new(env)
+      unless bypass?(request)
+        return auth_config_error if (request.using_auth? && auth_missing?(request))
+        return not_implemented unless @store.implements?(request.request_method)
+        send(request.request_method.downcase, request) rescue internal_server_error.to_rack
+      else
+        @app.call(env)
+      end
+    end
+
+    protected
+
+    def get(request)
+      response = @store.get(
+        request.uri,
+        {}.filter_merge!(
+          :remote_user => request.current_user,
+          :offset      => request['offset'],
+          :limit       => request['limit']))
+      inject_link_headers(request, response)
+      response.to_rack
+    end
+
+    def post(request)
+      if tunnel_methods.include?(request['_method'].try(:upcase))
+        return send(request['_method'].downcase, request)
+      end
+      response = @store.post(
+        request.uri,
+        {:json => request.json}.filter_merge!(
+          :remote_user => request.current_user))
+      update_location_header(request, response)
+      response.to_rack
+    end
+
+    def put(request)
+      response = @store.put(
+        request.uri,
+        {:json => request.json}.filter_merge!(
+          :remote_user => request.current_user,
+          :etag        => request.if_match))
+      update_location_header(request, response)
+      response.to_rack
+    end
+
+    def delete(request)
+      @store.delete(
+        request.uri,
+        {}.filter_merge!(
+          :remote_user => request.current_user,
+          :etag        => request.if_match)).to_rack
+    end
+
+    def head(request)
+      response = @store.head(
+        request.uri,
+        {}.filter_merge!(
+          :remote_user => request.current_user,
+          :offset      => request['offset'],
+          :limit       => request['limit']))
+      inject_link_headers(request, response)
+      response.to_rack
+    end
+
+    def options(request)
+      @store.options(request.uri).to_rack
+    end
+
+    def inject_link_headers(request, response)
+      response['Link'] = versions_link_header(request) if request.uri.resource_uri?
+      response['Link'] = resolved_link_header(request) if request.uri.resource_collection_uri?
+      response['Link'] = index_link_header(request)    if request.uri.resolved_resource_collection_uri?
+      response['Link'] = resolved_link_header(request) if request.uri.version_collection_uri?
+      response['Link'] = index_link_header(request)    if request.uri.resolved_version_collection_uri?
+    end
+
+    def versions_link_header(request)
+      base_url = "#{request.domain_root}#{request.path_info}"
+      "<#{base_url}/versions>; rel=\"http://joncrosby.me/cloudkit/1.0/rel/versions\""
+    end
+
+    def resolved_link_header(request)
+      base_url = "#{request.domain_root}#{request.path_info}"
+      "<#{base_url}/_resolved>; rel=\"http://joncrosby.me/cloudkit/1.0/rel/resolved\""
+    end
+
+    def index_link_header(request)
+      index_path = request.path_info.sub(/\/_resolved(\/)*$/, '')
+      base_url = "#{request.domain_root}#{index_path}"
+      "<#{base_url}>; rel=\"index\""
+    end
+
+    def update_location_header(request, response)
+      return unless response['Location']
+      response['Location'] = "#{request.domain_root}#{response['Location']}"
+    end
+
+    def auth_missing?(request)
+      request.current_user == nil
+    end
+
+    def tunnel_methods
+      ['PUT', 'DELETE', 'OPTIONS', 'HEAD', 'TRACE']
+    end
+
+    def not_implemented
+      json_error_response(501, 'not implemented').to_rack
+    end
+
+    def auth_config_error
+      json_error_response(500, 'server auth misconfigured').to_rack
+    end
+
+    def bypass?(request)
+      collection = @collections.detect{|type| request.path_info.match("/#{type.to_s}")}
+      !collection && !request.uri.meta_uri?
+    end
+  end
+end

data/lib/cloudkit/store.rb

@@ -0,0 +1,349 @@
+module CloudKit
+
+  # A functional storage interface with HTTP semantics and pluggable adapters.
+  class Store
+    include ResponseHelpers
+    include CloudKit::Util
+
+    # Initialize a new Store. All resources in a Store are automatically
+    # versioned.
+    #
+    # ===Options
+    # - :collections - Array of resource collections to manage.
+    #
+    # ===Example
+    #   store = CloudKit::Store.new(:collections => [:foos, :bars])
+    #
+    # See also: Response
+    #
+    def initialize(options)
+      CloudKit.setup_storage_adapter unless CloudKit.storage_adapter
+      @collections = options[:collections]
+    end
+
+    # Retrieve a resource or collection of resources based on a URI.
+    #
+    # ===Parameters
+    # - uri - URI of the resource or collection to retrieve.
+    # - options - See below.
+    #
+    # ===Options
+    # - :remote_user - Optional. Scopes the dataset if provided.
+    # - :limit - Optional. Default is unlimited. Limit the number of records returned by a collection request.
+    # - :offset - Optional. Start the list of resources in a collection at offset (0-based).
+    # - :any - Optional. Not a literal ":any", but any key or keys that are top level JSON keys. This is a starting point for future JSONPath/JSONQuery support.
+    #
+    # ===URI Types
+    #   /cloudkit-meta
+    #   /{collection}
+    #   /{collection}/_resolved
+    #   /{collection}/{uuid}
+    #   /{collection}/{uuid}/versions
+    #   /{collection}/{uuid}/versions/_resolved
+    #   /{collection}/{uuid}/versions/{etag}
+    #
+    # ===Examples
+    #   get('/cloudkit-meta')
+    #   get('/foos')
+    #   get('/foos', :remote_user => 'coltrane')
+    #   get('/foos', :limit => 100, :offset => 200)
+    #   get('/foos/123')
+    #   get('/foos/123/versions')
+    #   get('/foos/123/versions/abc')
+    #
+    # See also: {REST API}[http://getcloudkit.com/rest-api.html]
+    #
+    def get(uri, options={})
+      return invalid_entity_type                        if !valid_collection_type?(uri.collection_type)
+      return meta                                       if uri.meta_uri?
+      return resource_collection(uri, options)          if uri.resource_collection_uri?
+      return resolved_resource_collection(uri, options) if uri.resolved_resource_collection_uri?
+      return resource(uri, options)                     if uri.resource_uri?
+      return version_collection(uri, options)           if uri.version_collection_uri?
+      return resolved_version_collection(uri, options)  if uri.resolved_version_collection_uri?
+      return resource_version(uri, options)             if uri.resource_version_uri?
+      status_404
+    end
+
+    # Retrieve the same items as the get method, minus the content/body. Using
+    # this method on a single resource URI performs a slight optimization due
+    # to the way CloudKit stores its ETags and Last-Modified information on
+    # write.
+    def head(uri, options={})
+      return invalid_entity_type unless @collections.include?(uri.collection_type)
+      if uri.resource_uri? || uri.resource_version_uri?
+        # ETag and Last-Modified are already stored for single items, so a slight
+        # optimization can be made for HEAD requests.
+        result = CloudKit::Resource.first(options.merge(:uri => uri.string))
+        return status_404.head unless result
+        return status_410.head if result.deleted?
+        return response(200, '', result.etag, result.last_modified)
+      else
+        get(uri, options).head
+      end
+    end
+
+    # Update or create a resource at the specified URI. If the resource already
+    # exists, an :etag option is required.
+    def put(uri, options={})
+      methods = methods_for_uri(uri)
+      return status_405(methods) unless methods.include?('PUT')
+      return invalid_entity_type unless @collections.include?(uri.collection_type)
+      return data_required       unless options[:json]
+      current_resource = resource(uri, options.excluding(:json, :etag, :remote_user))
+      return update_resource(uri, options) if current_resource.status == 200
+      return current_resource if current_resource.status == 410
+      create_resource(uri, options)
+    end
+
+    # Create a resource in a given collection.
+    def post(uri, options={})
+      methods = methods_for_uri(uri)
+      return status_405(methods) unless methods.include?('POST')
+      return invalid_entity_type unless @collections.include?(uri.collection_type)
+      return data_required       unless options[:json]
+      create_resource(uri, options)
+    end
+
+    # Delete the resource specified by the URI. Requires the :etag option.
+    def delete(uri, options={})
+      methods = methods_for_uri(uri)
+      return status_405(methods) unless methods.include?('DELETE')
+      return invalid_entity_type unless @collections.include?(uri.collection_type)
+      return etag_required       unless options[:etag]
+      resource = CloudKit::Resource.first(options.excluding(:etag).merge(:uri => uri.string))
+      return status_404 unless (resource && (resource.remote_user == options[:remote_user]))
+      return status_410 if resource.deleted?
+      return status_412 if resource.etag != options[:etag]
+
+      resource.delete
+      archived_resource = resource.previous_version
+      return json_meta_response(archived_resource.uri.string, archived_resource.etag, resource.last_modified)
+    end
+
+    # Build a response containing the allowed methods for a given URI.
+    def options(uri)
+      methods = methods_for_uri(uri)
+      allow(methods)
+    end
+
+    # Return a list of allowed methods for a given URI.
+    def methods_for_uri(uri)
+      return meta_methods                         if uri.meta_uri?
+      return resource_collection_methods          if uri.resource_collection_uri?
+      return resolved_resource_collection_methods if uri.resolved_resource_collection_uri?
+      return resource_methods                     if uri.resource_uri?
+      return version_collection_methods           if uri.version_collection_uri?
+      return resolved_version_collection_methods  if uri.resolved_version_collection_uri?
+      return resource_version_methods             if uri.resource_version_uri?
+    end
+
+    # Return the list of methods allowed for the cloudkit-meta URI.
+    def meta_methods
+      @meta_methods ||= http_methods.excluding('POST', 'PUT', 'DELETE')
+    end
+
+    # Return the list of methods allowed for a resource collection.
+    def resource_collection_methods
+      @resource_collection_methods ||= http_methods.excluding('PUT', 'DELETE')
+    end
+
+    # Return the list of methods allowed on a resolved resource collection.
+    def resolved_resource_collection_methods
+      @resolved_resource_collection_methods ||= http_methods.excluding('POST', 'PUT', 'DELETE')
+    end
+
+    # Return the list of methods allowed on an individual resource.
+    def resource_methods
+      @resource_methods ||= http_methods.excluding('POST')
+    end
+
+    # Return the list of methods allowed on a version history collection.
+    def version_collection_methods
+      @version_collection_methods ||= http_methods.excluding('POST', 'PUT', 'DELETE')
+    end
+
+    # Return the list of methods allowed on a resolved version history collection.
+    def resolved_version_collection_methods
+      @resolved_version_collection_methods ||= http_methods.excluding('POST', 'PUT', 'DELETE')
+    end
+
+    # Return the list of methods allowed on a resource version.
+    def resource_version_methods
+      @resource_version_methods ||= http_methods.excluding('POST', 'PUT', 'DELETE')
+    end
+
+    # Return true if this store implements a given HTTP method.
+    def implements?(http_method)
+      http_methods.include?(http_method.upcase)
+    end
+
+    # Return the list of HTTP methods supported by this Store.
+    def http_methods
+      ['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'OPTIONS']
+    end
+
+    # Return an array containing the response for each URI in a list.
+    def resolve_uris(uris) # TODO - remove if no longer needed
+      result = []
+      uris.each do |uri|
+        result << get(uri)
+      end
+      result
+    end
+    
+    def storage_adapter
+      CloudKit.storage_adapter
+    end
+
+    # Return the version number of this Store.
+    def version; 1; end
+
+    protected
+
+    # Return the list of collections managed by this Store.
+    def meta
+      json = JSON.generate(:uris => @collections.map{|t| "/#{t}"})
+      response(200, json, build_etag(json))
+    end
+
+    # Return a list of resource URIs for the given collection URI. Sorted by
+    # Last-Modified date in descending order.
+    def resource_collection(uri, options)
+      filter = options.excluding(:offset, :limit).merge(
+        :deleted              => false,
+        :collection_reference => uri.collection_uri_fragment,
+        :archived             => false)
+      result = CloudKit::Resource.current(filter)
+      bundle_collection_result(uri.string, options, result)
+    end
+
+    # Return all documents and their associated metadata for the given
+    # collection URI.
+    def resolved_resource_collection(uri, options)
+      result = CloudKit::Resource.current(
+        options.excluding(:offset, :limit).merge(
+          :collection_reference => uri.collection_uri_fragment))
+      bundle_resolved_collection_result(uri, options, result)
+    end
+
+    # Return the resource for the given URI. Return 404 if not found or if
+    # protected and unauthorized, 410 if authorized but deleted.
+    def resource(uri, options)
+      if resource = CloudKit::Resource.first(options.merge!(:uri => uri.string))
+        return status_410 if resource.deleted?
+        return response(200, resource.json, resource.etag, resource.last_modified)
+      end
+      status_404
+    end
+
+    # Return a collection of URIs for all versions of a resource including the
+    # current version. Sorted by Last-Modified date in descending order.
+    def version_collection(uri, options)
+      found = CloudKit::Resource.first(
+        options.excluding(:offset, :limit).merge(
+          :uri => uri.current_resource_uri))
+      return status_404 unless found
+      result = CloudKit::Resource.all( # TODO - just use found.versions
+        options.excluding(:offset, :limit).merge(
+          :resource_reference => uri.current_resource_uri,
+          :deleted            => false))
+      bundle_collection_result(uri.string, options, result)
+    end
+
+    # Return all document versions and their associated metadata for a given
+    # resource including the current version. Sorted by Last-Modified date in
+    # descending order.
+    def resolved_version_collection(uri, options)
+      found = CloudKit::Resource.first(
+        options.excluding(:offset, :limit).merge(
+          :uri => uri.current_resource_uri))
+      return status_404 unless found
+      result = CloudKit::Resource.all(
+        options.excluding(:offset, :limit).merge(
+          :resource_reference => uri.current_resource_uri,
+          :deleted            => false))
+      bundle_resolved_collection_result(uri, options, result)
+    end
+
+    # Return a specific version of a resource.
+    def resource_version(uri, options)
+      result = CloudKit::Resource.first(options.merge(:uri => uri.string))
+      return status_404 unless result
+      response(200, result.json, result.etag, result.last_modified)
+    end
+
+    # Create a resource at the specified URI.
+    def create_resource(uri, options)
+      JSON.parse(options[:json]) rescue (return status_422)
+      resource = CloudKit::Resource.create(uri, options[:json], options[:remote_user])
+      json_create_response(resource.uri.string, resource.etag, resource.last_modified)
+    end
+
+    # Update the resource at the specified URI. Requires the :etag option.
+    def update_resource(uri, options)
+      JSON.parse(options[:json]) rescue (return status_422)
+      resource = CloudKit::Resource.first(
+        options.excluding(:json, :etag).merge(:uri => uri.string))
+      return status_404    unless (resource && (resource.remote_user == options[:remote_user]))
+      return etag_required unless options[:etag]
+      return status_412    unless options[:etag] == resource.etag
+      resource.update(options[:json])
+      return json_meta_response(uri.string, resource.etag, resource.last_modified)
+    end
+
+    # Bundle a collection of results as a list of URIs for the response.
+    def bundle_collection_result(uri, options, result)
+      total  = result.size
+      offset = options[:offset].try(:to_i) || 0
+      max    = options[:limit] ? offset + options[:limit].to_i : total
+      list   = result.to_a[offset...max].map{|r| r.uri}
+      json   = uri_list(list, total, offset)
+      last_modified = result.first.try(:last_modified) if result.any?
+      response(200, json, build_etag(json), last_modified)
+    end
+
+    # Bundle a collection of results as a list of documents and the associated
+    # metadata (last_modified, uri, etag) that would have accompanied a response
+    # to their singular request.
+    def bundle_resolved_collection_result(uri, options, result)
+      total  = result.size
+      offset = options[:offset].try(:to_i) || 0
+      max    = options[:limit] ? offset + options[:limit].to_i : total
+      list   = result.to_a[offset...max]
+      json   = resource_list(list, total, offset)
+      last_modified = result.first.last_modified if result.any?
+      response(200, json, build_etag(json), last_modified)
+    end
+
+    # Generate a JSON URI list.
+    def uri_list(list, total, offset)
+      JSON.generate(:total => total, :offset => offset, :uris => list.map { |u| u.string })
+    end
+
+    # Generate a JSON document list.
+    def resource_list(list, total, offset)
+      results = []
+      list.each do |resource|
+        results << {
+          :uri           => resource.uri.string,
+          :etag          => resource.etag,
+          :last_modified => resource.last_modified,
+          :document      => resource.json}
+      end
+      JSON.generate(:total => total, :offset => offset, :documents => results)
+    end
+
+    # Build an ETag for a collection. ETags are generated on write as an
+    # optimization for GETs. This method is used for collections of resources
+    # where the optimization is not practical.
+    def build_etag(data)
+      Digest::MD5.hexdigest(data.to_s)
+    end
+
+    # Returns true if the collection type is valid for this Store.
+    def valid_collection_type?(collection_type)
+      @collections.include?(collection_type) || collection_type.to_s == 'cloudkit-meta'
+    end
+  end
+end