cloudkit 0.10.1 → 0.11.0

data/lib/cloudkit/store/memory_table.rb

@@ -0,0 +1,105 @@
+module CloudKit
+
+  # A MemoryTable implements the essential pieces of the Rufus Tokyo Table API
+  # required for CloudKit's operation. It is basically a hash of hashes with
+  # querying capabilities. None of the data is persisted to disk nor is it
+  # designed with production use in mind. The primary purpose is to enable
+  # testing and development with CloudKit without depending on binary Tokyo
+  # Cabinet dependencies.
+  #
+  # Implementing a new adapter for CloudKit means writing an adapter that
+  # passes the specs for this one.
+  class MemoryTable
+
+    # Create a new MemoryTable instance.
+    def initialize
+      @serial_id = 0
+      clear
+    end
+
+    # Create a hash record for the given key. Returns the record if valid or nil
+    # otherwise. Records are valid if they are hashses with both string keys and
+    # string values.
+    def []=(key, record)
+      if valid?(record)
+        @keys << key unless @hash[key]
+        return @hash[key] = record
+      end
+      nil
+    end
+
+    # Retrieve the hash record for a given key.
+    def [](key)
+      @hash[key]
+    end
+
+    # Clear the contents of the store.
+    def clear
+      @hash = {}
+      @keys = []
+    end
+
+    # Return an ordered set of all keys in the store.
+    def keys
+      @keys
+    end
+
+    # Generate a unique ID within the scope of this store.
+    def generate_unique_id
+      @serial_id += 1
+    end
+
+    # Run a query configured by the provided block. If no block is provided, all
+    # records are returned. Each record contains the original hash key/value
+    # pairs, plus the primary key (indexed by :pk => value).
+    def query(&block)
+      return @keys.map { |key| @hash[key].merge(:pk => key) } unless block
+      q = MemoryQuery.new
+      block.call(q)
+      q.run(self)
+    end
+
+    # Simulate a transaction. This development-mode transaction merely yields
+    # to its block.
+    def transaction
+      yield
+    end
+
+    protected 
+
+    def valid?(record)
+      return false unless record.is_a?(Hash)
+      record.keys.all? { |k| k.is_a?(String) && record[k].is_a?(String) }
+    end
+
+  end
+
+  # MemoryQuery is used internally by MemoryTable to configure a query and run
+  # it against the store.
+  class MemoryQuery
+
+    # Initialize a new MemoryQuery.
+    def initialize
+      @conditions = []
+    end
+
+    # Run a query against the provided table using the conditions stored in this
+    # MemoryQuery instance. Returns all records that match all conditions.
+    # Conditions are added using #add_condition.
+    def run(table)
+      table.keys.inject([]) do |result, key|
+        if @conditions.all? { |condition| table[key][condition[0]] == condition[2] }
+          result << table[key].merge(:pk => key)
+        else
+          result
+        end
+      end
+    end
+
+    # Add a condition to this query. The operator parameter is ignored at this
+    # time, assuming only equality.
+    def add_condition(key, operator, value)
+      @conditions << [key, operator, value]
+    end
+  end
+end

data/lib/cloudkit/store/resource.rb

@@ -0,0 +1,256 @@
+module CloudKit
+
+  # A CloudKit::Resource represents a "resource" in the REST/HTTP sense of the
+  # word. It encapsulates a JSON document and its metadata such as it URI, ETag,
+  # Last-Modified date, remote user, and its historical versions.
+  class Resource
+
+    attr_reader :uri, :etag, :last_modified, :json, :remote_user
+
+    # Initialize a new instance of a resource.
+    #
+    # === Parameters
+    # - uri - A CloudKit::URI for the resource or its parent collection.
+    # - json - A string representing a valid JSON object.
+    # - remote_user - Optional. The URI for the user creating the resource.
+    # - options - Optional. A hash of other internal properties to set, mostly for internal use.
+    def initialize(uri, json, remote_user=nil, options={})
+      load_from_options(options.merge(
+        :uri         => uri,
+        :json        => json,
+        :remote_user => remote_user))
+    end
+
+    # Save the resource. If this is a new resource with only a resource
+    # collection URI, its full URI will be generated. ETags and Last-Modified
+    # dates are also generated upon saving. No manual reloads are required.
+    def save
+      @id ||= '%064d' % CloudKit.storage_adapter.generate_unique_id
+      @etag = UUID.generate unless @deleted
+      @last_modified = Time.now.httpdate
+
+      CloudKit.storage_adapter[@id] = {
+        'uri'                  => @uri.cannonical_uri_string,
+        'etag'                 => escape(@etag),
+        'last_modified'        => @last_modified,
+        'json'                 => @json,
+        'deleted'              => escape(@deleted),
+        'archived'             => escape(@archived),
+        'remote_user'          => escape(@remote_user),
+        'collection_reference' => @collection_reference ||= @uri.collection_uri_fragment,
+        'resource_reference'   => @resource_reference ||= @uri.cannonical_uri_string
+      }.merge(escape_values(parsed_json))
+      reload
+    end
+
+    # Update the json and optionally the remote_user for the current resource.
+    # Automatically archives the previous version, generating new ETag and
+    # Last-Modified dates. Raises HistoricalIntegrityViolation for attempts to
+    # modify resources that are not current.
+    def update(json, remote_user=nil)
+      raise HistoricalIntegrityViolation unless current?
+      CloudKit.storage_adapter.transaction do
+        record = CloudKit.storage_adapter[@id]
+        record['uri'] = "#{@uri.string}/versions/#{@etag}"
+        record['archived'] = escape(true)
+        CloudKit.storage_adapter[@id] = record
+        self.class.create(@uri, json, remote_user || @remote_user)
+      end
+      reload
+    end
+
+    # Delete the given resource. This is a soft delete, archiving the previous
+    # resource and inserted a deleted resource placeholder at the old URI.
+    # Raises HistoricalIntegrityViolation for attempts to delete resources that
+    # are not current.
+    def delete
+      raise HistoricalIntegrityViolation unless current?
+      CloudKit.storage_adapter.transaction do
+        original_uri = @uri
+        record = CloudKit.storage_adapter[@id]
+        record['uri'] = "#{@uri.string}/versions/#{@etag}"
+        record['archived'] = escape(true)
+        @uri = wrap_uri(record['uri'])
+        @archived = unescape(record['archived'])
+        CloudKit.storage_adapter[@id] = record
+        self.class.new(original_uri, @json, @remote_user, {:deleted => true}).save
+      end
+      reload
+    end
+
+    # Returns all versions of the given resource, reverse ordered by
+    # Last-Modified date, including the current version of the resource.
+    def versions
+      # TODO make this a collection proxy, only loading the first, then the
+      # rest as needed during iteration (possibly in chunks)
+      return nil if @archived
+      @versions ||= [self].concat(CloudKit.storage_adapter.query { |q|
+        q.add_condition('resource_reference', :eql, @resource_reference)
+        q.add_condition('archived', :eql, 'true')
+      }.reverse.map { |hash| self.class.build_from_hash(hash) })
+    end
+
+    # Returns all previous versions of a resource, reverse ordered by
+    # Last-Modified date.
+    def previous_versions
+      @previous_versions ||= versions[1..-1] rescue []
+    end
+
+    # Returns the most recent previous version of the given resource.
+    def previous_version
+      @previous_version ||= previous_versions[0]
+    end
+
+    # Returns true if the resource has been deleted.
+    def deleted?
+      @deleted
+    end
+
+    # Returns true if the resource is archived i.e. not the current version.
+    def archived?
+      @archived
+    end
+
+    # Returns true if the resource is not archived and not deleted.
+    def current?
+      !@deleted && !@archived
+    end
+
+    # Returns and caches the parsed JSON representation for this resource.
+    def parsed_json
+      @parsed_json ||= JSON.parse(@json)
+    end
+
+    # Create a new resource. Intializes and saves in one step.
+    #
+    # === Parameters
+    # - uri - A CloudKit::URI for the resource or its parent collection.
+    # - json - A string representing a valid JSON object.
+    # - remote_user - Optional. The URI for the user creating the resource.
+    def self.create(uri, json, remote_user=nil)
+      resource = new(uri, json, remote_user)
+      resource.save
+      resource
+    end
+
+    # Find all current resources with the given properties. Expectes a hash
+    # specifying the search parameters. Returns an array of Resources.
+    def self.current(spec={})
+      all({:deleted => false, :archived => false}.merge(spec))
+    end
+
+    # Find all resources with the given properties. Expects a hash specifying
+    # the search parameters. Returns an array of Resources.
+    def self.all(spec={})
+      CloudKit.storage_adapter.query { |q|
+        spec.keys.each { |k|
+          q.add_condition(k.to_s, :eql, escape(spec[k]))
+        }
+      }.reverse.map { |hash| build_from_hash(hash) }
+    end
+
+    # Find the first matching resource or nil. Expects a hash specifying the
+    # search parameters.
+    def self.first(spec)
+      all(spec)[0]
+    end
+
+    protected
+
+    def load_from_options(opts)
+      options = symbolize_keys(opts)
+
+      @uri                  = wrap_uri(options[:uri])
+      @json                 = options[:json]
+      @last_modified        = options[:last_modified]
+      @resource_reference   = options[:resource_reference]
+      @collection_reference = options[:collection_reference]
+      @id                   = options[:id] || options[:pk] || nil
+      @etag                 = unescape(options[:etag])
+      @remote_user          = unescape(options[:remote_user])
+      @archived             = unescape(options[:archived]) || false
+      @deleted              = unescape(options[:deleted]) || false
+    end
+
+    def reload
+      result = CloudKit.storage_adapter.query { |q|
+        q.add_condition('uri', :eql, @resource_reference)
+      }
+      load_from_options(result[0])
+    end
+
+    def self.build_from_hash(data)
+      new(
+        data['uri'],
+        data['json'],
+        data['remote_user'],
+        {}.filter_merge!(
+          :etag                 => data['etag'],
+          :last_modified        => data['last_modified'],
+          :resource_reference   => data['resource_reference'],
+          :collection_reference => data['collection_reference'],
+          :id                   => data[:pk],
+          :deleted              => data['deleted'],
+          :archived             => data['archived']))
+    end
+
+    def wrap_uri(uri)
+      self.class.wrap_uri(uri)
+    end
+
+    def self.wrap_uri(uri)
+      case uri
+        when CloudKit::URI; uri
+        else CloudKit::URI.new(uri)
+      end
+    end
+
+    def scope(key)
+      "#{@id}:#{key}"
+    end
+
+    def escape(value)
+      self.class.escape(value)
+    end
+
+    def self.escape(value)
+      case value
+      when TrueClass
+        "true"
+      when FalseClass
+        "false"
+      when NilClass
+        "null"
+      when Fixnum, Bignum, Float
+        value.to_s
+      else
+        value
+      end
+    end
+
+    def unescape(value)
+      self.class.unescape(value)
+    end
+
+    def self.unescape(value)
+      case value
+      when "true"
+        true
+      when "false"
+        false
+      when "null"
+        nil
+      else
+        value
+      end
+    end
+
+    def symbolize_keys(hash)
+      hash.inject({}) { |memo, pair| memo.merge({pair[0].to_sym => pair[1]}) }
+    end
+
+    def escape_values(hash)
+      hash.inject({}) { |memo, pair| memo.merge({pair[0] => escape(pair[1])}) }
+    end
+  end
+end

data/lib/cloudkit/store/response_helpers.rb

@@ -68,7 +68,6 @@ module CloudKit::ResponseHelpers
   end
 
   def json_error_response(status, message)
-    "trying to throw a json error message for #{status} #{message}"
     response(status, json_error(message), nil, nil, :cache => false)
   end
 end

data/lib/cloudkit/uri.rb

@@ -0,0 +1,88 @@
+module CloudKit
+
+  # A CloudKit::URI wraps a URI string, added methods useful for routing
+  # in CloudKit as well as caching URI components for future comparisons.
+  class URI
+
+    # The string form of a URI.
+    attr_reader :string
+
+    # Create a new URI with the given string.
+    def initialize(string)
+      @string = string
+    end
+
+    # Return the resource collection URI fragment.
+    #   Example: URI.new('/foos/123').collection_uri_fragment => '/foos
+    def collection_uri_fragment
+      "/#{components[0]}" rescue nil
+    end
+
+    # Splits a URI into its components
+    def components
+      @components ||= @string.split('/').reject{|x| x == '' || x == nil} rescue []
+    end
+
+    # Return the resource collection referenced by a URI.
+    #   Example: URI.new('/foos/123').collection_type => :foos
+    def collection_type
+      components[0].to_sym rescue nil
+    end
+
+    # Return the URI for the current version of a resource.
+    #   Example: URI.new('/foos/123/versions/abc').current_resource_uri => '/foos/123'
+    def current_resource_uri
+      "/#{components[0..1].join('/')}" rescue nil
+    end
+
+    # Returns true if URI matches /cloudkit-meta
+    def meta_uri?
+      return components.size == 1 && components[0] == 'cloudkit-meta'
+    end
+
+    # Returns true if URI matches /{collection}
+    def resource_collection_uri?
+      return components.size == 1
+    end
+
+    # Returns true if URI matches /{collection}/_resolved
+    def resolved_resource_collection_uri?
+      return components.size == 2 && components[1] == '_resolved'
+    end
+
+    # Returns true if URI matches /{collection}/{uuid}
+    def resource_uri?
+      return components.size == 2 && components[1] != '_resolved'
+    end
+
+    # Returns true if URI matches /{collection}/{uuid}/versions
+    def version_collection_uri?
+      return components.size == 3 && components[2] == 'versions'
+    end
+
+    # Returns true if URI matches /{collection}/{uuid}/versions/_resolved
+    def resolved_version_collection_uri?
+      return components.size == 4 && components[2] == 'versions' && components[3] == '_resolved'
+    end
+
+    # Returns true if URI matches /{collection}/{uuid}/versions/{etag}
+    def resource_version_uri?
+      return components.size == 4 && components[2] == 'versions' && components[3] != '_resolved'
+    end
+
+    # Returns a cannonical URI for a given URI/URI fragment, generating it if
+    # required.
+    #   Example: URI.new('/items/123').cannoncal_uri_string => /items/123
+    #
+    #   Example: URI.new('/items').cannonical_uri_string => /items/some-new-uuid
+    def cannonical_uri_string
+      @cannonical_uri_string ||= if resource_collection_uri?
+        "#{@string}/#{UUID.generate}"
+      elsif resource_uri?
+        @string
+      else
+        raise CloudKit::InvalidURIFormat
+      end
+    end
+  end
+end