duracloud-client 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 328f7556852dc8ca4dbdf2fed3314aa6ca2c160b
-  data.tar.gz: d10ae8810f1e964d495b8b88142246d42fc2c410
+  metadata.gz: 850dd8765ce4680a9a81f7453970ac9d8a33ec6d
+  data.tar.gz: 64f6a963ed6453f7f77af4ed9efbc93200417dfc
 SHA512:
-  metadata.gz: efa0688d30ec628915d6497422377c9edf95c06233af784947103ab110a4ea8925b7ff99854ccf829e024414eba6b370edd409dc525ff81b14c8707c1f6ccd93
-  data.tar.gz: 08bfcbd0b87934908c9b229b09400648699f90dd32e903b77d362033b8dcdbb1c737e3727e095b4a1343b32930dac68066895e5b5edc84f3d4e04c6e6a2db8e5
+  metadata.gz: a938f8b35fe0b32f4d6e73ac80c741adedd32c91513508f64e6cb63486299cff015cb38a394b22df2f1b56fe76024939ce06c1c3968a247406d0d069e08bd9bb
+  data.tar.gz: 303f6bbedfb8db0950ab9ffece57ba5989fa575dd0ed4b290004f4d13a91dfc88a252b83034bfc1503e1c81c6acfe5fe0b897da2b004ab9ab6234c86587c4128

data/README.md

@@ -1,4 +1,5 @@
 # duracloud-ruby-client
+
 Ruby client for communicating with DuraCloud
 
 ## Installation
@@ -84,7 +85,7 @@ D, [2016-04-29T12:12:32.641574 #28275] DEBUG -- : Duracloud::Client PUT https://
  => #<Duracloud::Space space_id="rest-api-testing2", store_id="(default)"> 
 ```
 
-A `Duracloud::BadRequestError` is raise if the space ID is invalid (illegal characters, too long, etc.).
+A `Duracloud::BadRequestError` exception is raised if the space ID is invalid (illegal characters, too long, etc.).
 
 #### Retrieve a space and view its properties
 
@@ -100,7 +101,7 @@ D, [2016-04-29T12:15:12.593075 #28275] DEBUG -- : Duracloud::Client HEAD https:/
  => #<DateTime: 2016-04-05T17:59:11+00:00 ((2457484j,64751s,0n),+0s,2299161j)> 
 ```
 
-A `Duracloud::NotFoundError` exception is raise if the space does not exist.
+A `Duracloud::NotFoundError` exception is raised if the space does not exist.
 
 #### Enumerate the content IDs of the space
 
@@ -153,6 +154,12 @@ If the space or content ID does not exist, a `Duracloud::NotFoundError` is raise
 If an MD5 digest is provided (:md5 attribute), a `Duracloud::MessageDigestError` is
 raised if the content ID exists and the stored digest does not match.
 
+*Added in v0.4.0*
+
+If a content item is not found at the content ID, `Duracloud::Content.find` will look for a "content manifest"
+by appending ".dura-manifest" to the content ID. If the manifest is found, the content item is marked as
+"chunked". **Caution: Working with chunked files should be considered EXPERIMENTAL.**
+
 #### Update the properties for a content item
 
 ```
@@ -177,6 +184,48 @@ D, [2016-04-29T18:32:06.465928 #32379] DEBUG -- : Duracloud::Client HEAD https:/
  => "bob@example.com"
 ```     
 
+#### Copy a content item
+
+*Added in v0.3.0; Changed in v0.4.0.*
+
+Accepts same keywords as `.find` and `.new` -- `:space_id`, `:content_id`, `:store_id` -- plus `:force`.
+
+The `:force` argument is a boolean (default `false`) indicating whether to replace existing content (if found) at the target location. If `:force` is false and content exists at the target location, the operation raises a `Duracloud::Content::CopyError` exception.
+
+Also, `:space_id` and `:content_id` arguments are not required, but default to the values of the current content object's attributes. An exception is raised if the source and destination locations are the same (regardless of the value of `:force`).
+
+```
+>> content = Duracloud::Content.find(space_id: 'rest-api-testing', content_id: 'contentItem.txt')
+D, [2017-01-27T17:16:45.846459 #93283] DEBUG -- : Duracloud::Client HEAD https://duke.duracloud.org/durastore/rest-api-testing/contentItem.txt 200 OK
+ => #<Duracloud::Content space_id="rest-api-testing", content_id="contentItem.txt", store_id=(default)> 
+
+>> content.copy(space_id: 'rest-api-testing2')
+D, [2017-01-27T17:17:59.848741 #93283] DEBUG -- : Duracloud::Client PUT https://duke.duracloud.org/durastore/rest-api-testing2/contentItem.txt 201 Created
+ => #<Duracloud::Content space_id="rest-api-testing2", content_id="contentItem.txt", store_id=(default)> 
+```
+
+#### Move a content item
+
+*Added in v0.3.0; Changed in v0.4.0.*
+
+See also *Copy a content item, above.
+
+```
+This is a convenience operation -- copy and delete -- not directly supported by the DuraCloud REST API.
+
+>> content = Duracloud::Content.find(space_id: 'rest-api-testing', content_id: 'contentItem.txt')
+D, [2017-01-27T17:19:41.926994 #93286] DEBUG -- : Duracloud::Client HEAD https://duke.duracloud.org/durastore/rest-api-testing/contentItem.txt 200 OK
+ => #<Duracloud::Content space_id="rest-api-testing", content_id="contentItem.txt", store_id=(default)> 
+
+>> content.move(space_id: 'rest-api-testing2')
+D, [2017-01-27T17:20:07.542468 #93286] DEBUG -- : Duracloud::Client PUT https://duke.duracloud.org/durastore/rest-api-testing2/contentItem.txt 201 Created
+D, [2017-01-27T17:20:08.442504 #93286] DEBUG -- : Duracloud::Client DELETE https://duke.duracloud.org/durastore/rest-api-testing/contentItem.txt 200 OK
+ => #<Duracloud::Content space_id="rest-api-testing2", content_id="contentItem.txt", store_id=(default)> 
+
+>> content.deleted?
+ => true 
+```
+
 #### Delete a content item
 
 ```
@@ -191,7 +240,7 @@ D, [2016-04-29T18:28:31.459962 #32379] DEBUG -- : Duracloud::Client DELETE https
 I, [2016-04-29T18:28:31.460069 #32379]  INFO -- : Content foo2 deleted successfully
  => #<Duracloud::Content space_id="rest-api-testing", content_id="foo2", store_id=(default)>
 
->> Duracloud::Content.exist?("rest-api-testing", "foo2")
+>> Duracloud::Content.exist?(space_id: "rest-api-testing", content_id: "foo2")
 D, [2016-04-29T18:29:03.935451 #32379] DEBUG -- : Duracloud::Client HEAD https://foo.duracloud.org/durastore/rest-api-testing/foo2 404 Not Found
  => false
 ```

data/lib/duracloud/abstract_entity.rb

@@ -0,0 +1,92 @@
+require "active_model"
+
+module Duracloud
+  class AbstractEntity
+    include ActiveModel::Model
+    extend ActiveModel::Callbacks
+
+    define_model_callbacks :save, :delete, :load_properties
+    after_save :persisted!
+    after_save :reset_properties
+    after_load_properties :persisted!
+    before_delete :reset_properties
+    after_delete :deleted!
+    after_delete :freeze
+
+    def save
+      raise Error, "Cannot save deleted #{self.class}." if deleted?
+      run_callbacks :save do
+        do_save
+      end
+    end
+
+    def delete
+      raise Error, "Cannot delete, already deleted." if deleted?
+      run_callbacks :delete do
+        do_delete
+      end
+    end
+
+    def persisted?
+      !!@persisted
+    end
+
+    def deleted?
+      !!@deleted
+    end
+
+    # Return the properties associated with this resource,
+    #   loading from Duracloud if necessary.
+    # @return [Duracloud::Properties] the properties
+    # @raise [Duracloud::NotFoundError] if the resource is marked persisted
+    #   but does not exist in Duracloud
+    def properties
+      load_properties if persisted? && @properties.nil?
+      @properties ||= properties_class.new
+    end
+
+
+    def load_properties
+      run_callbacks :load_properties do
+        do_load_properties
+      end
+    end
+
+    private
+
+    def do_load_properties
+      raise NotImplementedError, "Subclasses must implement `#do_load_properties` private method."
+    end
+
+    def persisted!
+      @persisted = true
+    end
+
+    def deleted!
+      @deleted = true
+      @persisted = false
+    end
+
+    def do_delete
+      raise NotImplementedError, "Subclasses must implement `do_delete`."
+    end
+
+    def do_save
+      raise NotImplementedError, "Subclasses must implement `do_save`."
+    end
+
+    def properties=(props)
+      filtered = props ? properties_class.filter(props) : props
+      @properties = properties_class.new(filtered)
+    end
+
+    def reset_properties
+      @properties = nil
+    end
+
+    def properties_class
+      Properties
+    end
+
+  end
+end

data/lib/duracloud/chunked_content.rb

@@ -0,0 +1,35 @@
+module Duracloud
+  class ChunkedContent < Content
+
+    def self.find(**kwargs)
+      new(**kwargs).tap do |content|
+        content.manifest
+      end
+    end
+
+    def manifest
+      if @manifest.nil?
+        @manifest = ContentManifest.find(space_id: space_id,
+                                         manifest_id: content_id + MANIFEST_EXT,
+                                         store_id: store_id)
+        load_properties
+      end
+      @manifest
+    end
+
+    private
+
+    def do_load_properties
+      if md5
+        if md5 != manifest.source.md5
+          raise MessageDigestError, "Expected MD5: {#{md5}}; DuraCloud MD5: {#{manifest.source.md5}}."
+        end
+      else
+        self.md5 = manifest.source.md5
+      end
+      self.properties = manifest.properties.dup
+      self.content_type = manifest.source.content_type
+    end
+
+  end
+end

data/lib/duracloud/client.rb

@@ -6,8 +6,8 @@ module Duracloud
     extend RestMethods
     include RestMethods
 
-    def self.execute(request_class, http_method, url, **options)
-      new.execute(request_class, http_method, url, **options)
+    def self.execute(request_class, http_method, url, **options, &block)
+      new.execute(request_class, http_method, url, **options, &block)
     end
 
     def self.configure
@@ -22,9 +22,9 @@ module Duracloud
       @config = Configuration.new(**options)
     end
 
-    def execute(request_class, http_method, url, **options)
+    def execute(request_class, http_method, url, **options, &block)
       request = request_class.new(self, http_method, url, **options)
-      response = request.execute
+      response = request.execute(&block)
       handle_response(response)
       response
     end

data/lib/duracloud/content.rb

@@ -4,48 +4,57 @@ module Duracloud
   #
   # A piece of content in DuraCloud
   #
-  class Content
-    include ActiveModel::Model
-    include ActiveModel::Dirty
-    include Persistence
-    include HasProperties
+  class Content < AbstractEntity
 
-    CHUNK_SIZE = 1024 * 16
+    class CopyError < Error; end
 
-    after_save :changes_applied
+    CHUNK_SIZE = 1024 * 16
+    COPY_SOURCE_HEADER = "x-dura-meta-copy-source"
+    COPY_SOURCE_STORE_HEADER = "x-dura-meta-copy-source-store"
+    MANIFEST_EXT = ".dura-manifest"
 
     # Does the content exist in DuraCloud?
-    # @return [Boolean] whether the content exists
-    # @raise [Duracloud::MessageDigestError] the provided digest in the :md5 attribute
-    #   does not match the stored value
-    def self.exist?(params={})
-      find(params) && true
+    # @return [Boolean] whether the content exists.
+    # @raise [Duracloud::MessageDigestError] the provided digest in the :md5 keyword option,
+    #   if given, does not match the stored value.
+    def self.exist?(**kwargs)
+      find(**kwargs) && true
     rescue NotFoundError
       false
     end
 
     # Find content in DuraCloud.
     # @return [Duraclound::Content] the content
-    # @raise [Duracloud::NotFoundError] the space, content, or store does not exist.
-    # @raise [Duracloud::MessageDigestError] the provided digest in the :md5 attribute
-    #   does not match the stored value
-    def self.find(params={})
-      new(params).tap do |content|
+    # @raise [Duracloud::NotFoundError] the space, content, or store (if given) does not exist.
+    # @raise [Duracloud::MessageDigestError] the provided digest in the :md5 keyword option,
+    #   if given, does not match the stored value.
+    def self.find(**kwargs)
+      new(**kwargs).tap do |content|
         content.load_properties
       end
+    rescue NotFoundError => e
+      ChunkedContent.find(**kwargs)
     end
 
-    attr_accessor :space_id, :content_id, :store_id
+    # Create new content in DuraCloud.
+    # @return [Duraclound::Content] the content
+    # @raise [Duracloud::NotFoundError] the space or store (if given) does not exist.
+    # @raise [Duracloud::MessageDigestError] the provided digest in the :md5 keyword option,
+    #   if given, does not match the stored value.
+    def self.create(**kwargs)
+      new(**kwargs).save
+    end
+
+    attr_accessor :space_id, :content_id, :store_id,
+                  :body, :md5, :content_type
     alias_method :id, :content_id
     validates_presence_of :space_id, :content_id
 
-    define_attribute_methods :content_type, :body, :md5
-
     # Return the space associated with this content.
     # @return [Duracloud::Space] the space.
     # @raise [Duracloud::NotFoundError] the space or store does not exist.
     def space
-      Space.find(space_id, store_id)
+      @space ||= Space.find(space_id, store_id)
     end
 
     def inspect
@@ -54,67 +63,33 @@ module Duracloud
       " store_id=#{store_id || '(default)'}>"
     end
 
-    # @api private
-    # @raise [Duracloud::NotFoundError] the content does not exist in DuraCloud.
-    def load_body
-      response = Client.get_content(*args, **query)
-      set_md5!(response)
-      @body = response.body # don't use setter b/c marks as dirty
-      persisted!
-    end
-
-    def load_properties
-      super do |response|
-        # don't mark content_type or md5 as changed
-        set_md5!(response)
-        @content_type = response.content_type
-      end
-    end
-
-    def body=(str_or_io)
-      @body = str_or_io
-      body_will_change!
-    end
-
-    # Return the content body, loading from DuraCloud if necessary.
-    # @return [String, StringIO] the content body
-    def body
-      load_body if persisted? && empty?
-      @body
-    end
-
     # Is the content empty?
     # @return [Boolean] whether the content is empty (nil or empty string)
     def empty?
-      @body.nil? || @body.size == 0
-    end
-
-    def content_type=(val)
-      content_type_will_change! unless val == @content_type
-      @content_type = val
+      body.nil? || ( body.respond_to?(:size) && body.size == 0 )
     end
 
-    def content_type
-      @content_type
-    end
-
-    def md5=(val)
-      md5_will_change! unless val == @md5
-      @md5 = val
-    end
-
-    def md5
-      @md5
+    # Downloads the remote content
+    # @yield [String] chunk of the remote content, if block given.
+    # @return [Duracloud::Response] the response to the content request.
+    # @raise [Duracloud::NotFoundError]
+    def download(&block)
+      Client.get_content(*args, **query, &block)
     end
 
     # @return [Duracloud::Content] the copied content
     #   The current instance still represents the original content.
-    def copy(target_space_id:, target_content_id:, target_store_id: nil)
-      copy_headers = {'x-dura-meta-copy-source'=>[space_id, content_id].join('/')}
-      copy_headers['x-dura-meta-copy-source-store'] = store_id if store_id
-      options = { storeID: target_store_id, headers: copy_headers }
-      Client.copy_content(target_space_id, target_content_id, **options)
-      Content.find(space_id: target_space_id, content_id: target_content_id, store_id: target_store_id, md5: md5)
+    def copy(**args)
+      dest = args.except(:force)
+      dest[:space_id]   ||= space_id
+      dest[:content_id] ||= content_id
+      raise CopyError, "Destination is the same as the source." if dest == copy_source
+      if !args[:force] && Content.exist?(**dest)
+        raise CopyError, "Destination exists and :false option is false."
+      end
+      options = { storeID: dest[:store_id], headers: copy_headers }
+      Client.copy_content(dest[:space_id], dest[:content_id], **options)
+      Content.new(dest.merge(md5: md5))
     end
 
     # @return [Duracloud::Content] the moved content
@@ -127,28 +102,6 @@ module Duracloud
 
     private
 
-    def set_md5!(response)
-      if md5
-        if md5 != response.md5
-          raise MessageDigestError,
-                "Expected MD5 digest (#{md5}) does not match response header: #{response.md5}"
-        end
-      else
-        @md5 = response.md5
-      end
-    end
-
-    def io_like?
-      body.respond_to?(:read) && body.respond_to?(:rewind)
-    end
-
-    def set_properties
-      headers = properties.to_h
-      headers["Content-Type"] = content_type if content_type_changed?
-      options = { headers: headers, query: query }
-      Client.set_content_properties(*args, **options)
-    end
-
     def store
       headers = {
         "Content-MD5"  => md5 || calculate_md5,
@@ -159,6 +112,24 @@ module Duracloud
       Client.store_content(*args, **options)
     end
 
+    def copy_headers
+      ch = { COPY_SOURCE_HEADER=>"#{space_id}/#{content_id}" }
+      ch[COPY_SOURCE_STORE_HEADER] = store_id if store_id
+      ch
+    end
+
+    def copy_source
+      { space_id: space_id, content_id: content_id, store_id: store_id }
+    end
+
+    def io_like?
+      body.respond_to?(:read) && body.respond_to?(:rewind)
+    end
+
+    def set_properties
+      Client.set_content_properties(*args, headers: properties, query: query)
+    end
+
     def calculate_md5
       digest = Digest::MD5.new
       if io_like?
@@ -177,8 +148,17 @@ module Duracloud
       ContentProperties
     end
 
-    def get_properties_response
-      Client.get_content_properties(*args, **query)
+    def do_load_properties
+      response = Client.get_content_properties(*args, **query)
+      if md5
+        if md5 != response.md5
+          raise MessageDigestError, "Expected MD5: {#{md5}}; DuraCloud MD5: {#{response.md5}}."
+        end
+      else
+        self.md5 = response.md5
+      end
+      self.properties = response.headers
+      self.content_type = response.content_type
     end
 
     def do_delete
@@ -186,7 +166,7 @@ module Duracloud
     end
 
     def do_save
-      if !empty? && body_changed?
+      if !empty?
         store
       elsif persisted?
         set_properties