duracloud-client 0.0.3 → 0.1.0

data/lib/duracloud/manifest.rb

@@ -1,23 +1,46 @@
-require "csv"
-
 module Duracloud
   class Manifest
 
-    CSV_OPTS = {
-      col_sep: '\t',
-      headers: :first_row,
-      write_headers: true,
-      return_headers: true,
-    }
+    BAGIT = "BAGIT".freeze
+    TSV   = "TSV".freeze
+
+    attr_reader :space_id, :store_id
+
+    def initialize(space_id, store_id = nil)
+      @space_id = space_id
+      @store_id = store_id
+      @tsv_response = nil
+      @bagit_response = nil
+    end
+
+    def csv(opts = {})
+      CSVReader.call(tsv, opts)
+    end
+
+    def tsv
+      tsv_response.body
+    end
+
+    def bagit
+      bagit_response.body
+    end
+
+    private
+
+    def tsv_response
+      @tsv_response ||= get_response(TSV)
+    end
+
+    def bagit_response
+      @bagit_response ||= get_response(BAGIT)
+    end
 
-    def self.csv(space_id, csv_opts: {})
-      data = raw(space_id)
-      CSV.new(data, CSV_OPTS.merge(csv_opts))
+    def get_response(format)
+      Client.get_manifest(space_id, query(format))
     end
 
-    def self.raw(space_id)
-      response = Client.get_manifest(space_id)
-      response.body
+    def query(format)
+      { storeID: store_id, format: format }
     end
 
   end

data/lib/duracloud/persistence.rb

@@ -1,4 +1,4 @@
-require "active_model/callbacks"
+require "active_model"
 
 module Duracloud
   module Persistence

data/lib/duracloud/properties.rb

@@ -3,7 +3,11 @@ require 'time'
 require 'date'
 
 module Duracloud
+  #
+  # Encapsulates Duracloud "properties" which are transmitted via HTTP headers.
+  #
   # @abstract
+  #
   class Properties < Hashie::Mash
 
     PREFIX = "x-dura-meta-".freeze
@@ -23,38 +27,69 @@ module Duracloud
     # Properties set by the DuraCloud SyncTool
     SYNCTOOL = /\A#{PREFIX}(creator|(content-file-(created|modified|last-accessed-path)))\z/
 
+    # Is the property valid for this class of properties?
+    # @note Subclasses should override this method rather than the `#property?'
+    #   instance method.
+    # @param prop [String] the property name
+    # @return [Boolean]
     def self.property?(prop)
-      duraspace_property?(prop) && !internal_property?(prop)
+      duracloud_property?(prop) && !internal_property?(prop)
     end
 
+    # Filter the hash of properties, selecting only the properties valid
+    #   for this particular usage (subclass).
+    # @param hsh [Hash] the unfiltered properties
+    # @return [Hash] the filtered properties
     def self.filter(hsh)
       hsh.select { |k, v| property?(k) }
     end
 
-    def self.duraspace_property?(prop)
+    # Is the property a (theoretically) valid DuraCloud property?
+    # @param prop [String] the property name
+    # @return [Boolean]
+    def self.duracloud_property?(prop)
       prop.start_with?(PREFIX)
     end
 
+    # Is the property a reserved "internal" DuraCloud property?
+    # @param prop [String] the property name
+    # @return [Boolean]
     def self.internal_property?(prop)
       INTERNAL =~ prop
     end
 
+    # Is the property a space property?
+    # @param prop [String] the property name
+    # @return [Boolean]
     def self.space_property?(prop)
       SPACE =~ prop
     end
 
+    # Is the property a space ACL?
+    # @param prop [String] the property name
+    # @return [Boolean]
     def self.space_acl?(prop)
       SPACE_ACLS =~ prop
     end
 
+    # Is the property used for copying content?
+    # @param prop [String] the property name
+    # @return [Boolean]
     def self.copy_content_property?(prop)
       COPY_CONTENT =~ prop
     end
 
+    # Is the property valid for this class of properties?
+    # @note Subclasses should not override this method, but instead
+    #   override the `.property?' class method.
+    # @param prop [String] the property name
+    # @return [Boolean]
+    # @api private
     def property?(prop)
       self.class.property?(prop)
     end
 
+    # @api private
     def regular_writer(key, value)
       if property?(key)
         super
@@ -63,10 +98,12 @@ module Duracloud
       end
     end
 
+    # @api private
     def convert_key(key)
-      force_ascii(duraspace_property!(super))
+      force_ascii(duracloud_property!(super))
     end
 
+    # @api private
     def convert_value(value, _ = nil)
       case value
       when Array
@@ -82,12 +119,12 @@ module Duracloud
 
     private
 
-    # coerce to a Duraspace property
-    def duraspace_property!(prop)
+    # Coerce to a DuraCloud property
+    def duracloud_property!(prop)
       prop.dup.tap do |p|
         p.gsub!(/_/, '-')
         p.downcase!
-        p.prepend(PREFIX) unless self.class.duraspace_property?(p)
+        p.prepend(PREFIX) unless self.class.duracloud_property?(p)
       end
     end
 

data/lib/duracloud/request.rb

@@ -8,32 +8,44 @@ module Duracloud
     # @param body [String] the body of the request
     # @param headers [Hash] HTTP headers
     # @param query [Hash] Query string parameters
-    def initialize(client, http_method, url, body: nil, headers: nil, query: nil)
+    # def initialize(client, http_method, url, body: nil, headers: nil, query: nil)
+    def initialize(client, http_method, url, **options)
       @client      = client
       @http_method = http_method
       @url         = url
-      @body        = body
-      @headers     = headers
-      @query       = query
+      set_options(options.dup)
     end
 
     def execute
-      begin
-        original_response = connection.send(http_method,
-                                            url,
-                                            body: body,
-                                            query: query,
-                                            header: headers)
-        Response.new(original_response)
-      end
+      response_class.new(original_response)
     end
 
     private
 
+    def original_response
+      connection.send(http_method,
+                      url,
+                      body: body,
+                      query: query,
+                      header: headers)
+    end
+
+    def set_options(options)
+      @body    = options.delete(:body)
+      @headers = options.delete(:headers)
+      query   = options.delete(:query) || {}
+      # Treat other keywords args as query params and ignore empty params
+      @query = query.merge(options).reject { |k, v| v.to_s.empty? }
+    end
+
     def base_path
       '/'
     end
 
+    def response_class
+      Response
+    end
+
     def connection
       @connection ||= Connection.new(client, base_path)
     end

data/lib/duracloud/rest_methods.rb

@@ -2,79 +2,86 @@ module Duracloud
   module RestMethods
 
     def get_stores
-      durastore :get, "stores"
+      durastore(:get, "stores")
     end
 
-    def get_spaces
-      durastore :get, "spaces"
+    def get_spaces(**query)
+      durastore(:get, "spaces", **query)
     end
 
-    def get_space(space_id, query: nil)
-      durastore :get, space_id, query: query
+    def get_space(space_id, **query)
+      durastore(:get, space_id, **query)
     end
 
-    def get_space_properties(space_id)
-      durastore :head, space_id
+    def get_space_properties(space_id, **query)
+      durastore(:head, space_id, **query)
     end
 
-    def get_space_acls(space_id)
-      durastore :head, "acl/#{space_id}"
+    def get_space_acls(space_id, **query)
+      durastore(:head, "acl/#{space_id}", **query)
     end
 
-    def set_space_acls(space_id, acls)
-      durastore :post, space_id, properties: acls
+    def set_space_acls(space_id, **options)
+      durastore(:post, "acl/#{space_id}", **options)
     end
 
-    def create_space(space_id)
-      durastore :put, space_id
+    def create_space(space_id, **query)
+      durastore(:put, space_id, **query)
     end
 
-    def delete_space(space_id)
-      durastore :delete, space_id
+    def delete_space(space_id, **query)
+      durastore(:delete, space_id, **query)
     end
 
-    def get_content(url, **options)
-      durastore :get, url, **options
+    def get_content(space_id, content_id, **options)
+      durastore_content(:get, space_id, content_id, **options)
     end
 
-    def get_content_properties(url, **options)
-      durastore :head, url, **options
+    def get_content_properties(space_id, content_id, **options)
+      durastore_content(:head, space_id, content_id, **options)
     end
 
-    def set_content_properties(url, **options)
-      durastore :post, url, **options
+    def set_content_properties(space_id, content_id, **options)
+      durastore_content(:post, space_id, content_id, **options)
     end
 
-    def store_content(url, **options)
-      durastore :put, url, **options
+    def store_content(space_id, content_id, **options)
+      durastore_content(:put, space_id, content_id, **options)
     end
 
-    def delete_content(url, **options)
-      durastore :delete, url, **options
+    def copy_content(space_id, content_id, **options)
+      raise NotImplementedError,
+            "The API method 'Copy Content' has not yet been implemented."
     end
 
-    def get_audit_log
-      durastore :get, "audit/#{space_id}"
+    def delete_content(space_id, content_id, **options)
+      durastore_content(:delete, space_id, content_id, **options)
     end
 
-    def get_manifest(space_id)
-      durastore :get, "manifest/#{space_id}"
+    def get_audit_log(space_id, **query)
+      durastore(:get, "audit/#{space_id}", **query)
     end
 
-    def get_bit_integrity_report(space_id)
-      durastore :get, "bit-integrity/#{space_id}"
+    def get_manifest(space_id, **query)
+      durastore(:get, "manifest/#{space_id}", **query)
     end
 
-    def get_bit_integrity_report_properties(space_id)
-      durastore :head, "bit-integrity/#{space_id}"
+    def get_bit_integrity_report(space_id, **query)
+      durastore(:get, "bit-integrity/#{space_id}", **query)
     end
 
-    def get_tasks
-      raise NotImplementedError, "The API method 'Get Tasks' has not been implemented."
+    def get_bit_integrity_report_properties(space_id, **query)
+      durastore(:head, "bit-integrity/#{space_id}", **query)
     end
 
-    def perform_task
-      raise NotImplementedError, "The API method 'Perform Task' has not been implemented."
+    def get_tasks(**query)
+      raise NotImplementedError,
+            "The API method 'Get Tasks' has not been implemented."
+    end
+
+    def perform_task(task_name, **query)
+      raise NotImplementedError,
+            "The API method 'Perform Task' has not been implemented."
     end
 
     private
@@ -83,5 +90,10 @@ module Duracloud
       execute(DurastoreRequest, *args)
     end
 
+    def durastore_content(http_method, space_id, content_id, **options)
+      url = [ space_id, content_id ].join("/")
+      durastore(http_method, url, **options)
+    end
+
   end
 end

data/lib/duracloud/space.rb

@@ -1,63 +1,224 @@
 require "date"
 require "nokogiri"
-require "forwardable"
 
 module Duracloud
+  #
+  # A "space" within a DuraCloud account.
+  #
   class Space
-    extend Forwardable
     include Persistence
     include HasProperties
 
+    # Max size of content item list for one request.
+    #   This limit is imposed by Duracloud.
     MAX_RESULTS = 1000
 
-    def self.all
-      response = Client.get_spaces
-      doc = Nokogiri::XML(response.body)
-      doc.css('space').map { |s| new(s['id']) }
+    class << self
+      # List all spaces
+      # @param store_id [String] the store ID (optional)
+      # @return [Array<Duracloud::Space>] the list of spaces
+      # @raise [Duracloud::Error] the store was not found
+      def all(store_id = nil)
+        ids(store_id).map { |id| new(id, store_id) }
+      end
+
+      # List all space IDs
+      # @param store_id [String] the store ID (optional)
+      # @return [Array<String>] the list of space IDs
+      # @raise [Duracloud::Error] the store was not found
+      def ids(store_id = nil)
+        response = Client.get_spaces(storeID: store_id)
+        doc = Nokogiri::XML(response.body)
+        doc.css('space').map { |s| s['id'] }
+      end
+
+      # Enumerates the content IDs in the space.
+      # @param space_id [String] the space ID
+      # @param store_id [String] the store ID (optional)
+      # @param prefix [String] the content ID prefix for filtering (optional)
+      # @param start_after [String] the content ID to be used as a "marker".
+      #   Listing starts after this ID. (optional)
+      # @return [Enumerator] an enumerator.
+      # @raise [Duracloud::NotFoundError] the space or store does not exist.
+      def content_ids(space_id, store_id: nil, prefix: nil, start_after: nil)
+        space = find(space_id, store_id)
+        space.content_ids(prefix: prefix, start_after: start_after)
+      end
+
+      # Enumerates the content items in the space.
+      # @param space_id [String] the space ID
+      # @param store_id [String] the store ID (optional)
+      # @param prefix [String] the content ID prefix for filtering (optional)
+      # @param start_after [String] the content ID to be used as a "marker".
+      #   Listing starts after this ID. (optional)
+      # @return [Enumerator] an enumerator.
+      # @raise [Duracloud::NotFoundError] the space does not exist in Duracloud.
+      def items(space_id, store_id: nil, prefix: nil, start_after: nil)
+        space = find(space_id, store_id)
+        space.items(prefix: prefix, start_after: start_after)
+      end
+
+      # Create a new space
+      # @see .new for arguments
+      # @return [Duracloud::Space] the space
+      # @raise [Duracloud::BadRequestError] the space ID is invalid.
+      def create(*args)
+        new(*args) do |space|
+          yield space if block_given?
+          space.save
+        end
+      end
+
+      # Does the space exist?
+      # @see .new for arguments
+      # @return [Boolean] whether the space exists.
+      def exist?(*args)
+        find(*args) && true
+      rescue NotFoundError
+        false
+      end
+
+      # Find a space
+      # @see .new for arguments
+      # @return [Duracloud::Space] the space
+      # @raise [Duracloud::NotFoundError] the space or store was not found
+      def find(*args)
+        new(*args) do |space|
+          space.load_properties
+        end
+      end
+
+      # Return the number of items in the space
+      # @return [Fixnum] the number of items
+      # @raise [Duracloud::NotFoundError] the space or store was not found
+      def count(*args)
+        find(*args).count
+      end
+
+      # Return the audit log for the space
+      # @return [Duracloud::AuditLog] the audit log
+      # @raise [Duracloud::NotFoundError] the space or store was not found
+      def audit_log(*args)
+        find(*args).audit_log
+      end
+
+      # Return the bit integrity report for the space
+      # @return [Duracloud::BitIntegrityReport] the report
+      # @raise [Duracloud::NotFoundError] the space or store was not found
+      def bit_integrity_report(*args)
+        find(*args).bit_integrity_report
+      end
+
+      # Return the manifest for the space
+      # @return [Duracloud::Manifest] the manifest
+      # @raise [Duracloud::NotFoundError] the space or store was not found
+      def manifest(*args)
+        find(*args).manifest
+      end
     end
 
-    def self.create(id)
-      # TODO
+    attr_reader :space_id, :store_id
+    alias_method :id, :space_id
+
+    after_save :reset_acls
+    before_delete :reset_acls
+
+    # @param space_id [String] the space ID
+    # @param store_id [String] the store ID (optional)
+    def initialize(space_id, store_id = nil)
+      @space_id = space_id
+      @store_id = store_id
+      yield self if block_given?
     end
 
-    def self.find(id)
-      space = new(id)
-      space.load_properties
-      space
+    def inspect
+      "#<#{self.class} space_id=#{space_id.inspect}," \
+      " store_id=#{(store_id || '(default)').inspect}>"
     end
 
-    attr_reader :id
+    def to_s
+      space_id
+    end
 
-    delegate [:count, :created] => :properties
+    # Return the number of items in the space
+    # @return [Fixnum] the number of items
+    def count
+      properties.space_count.to_i
+    end
 
-    after_save :reset_acls
-    before_delete :reset_acls
+    # Return the creation date of the space, if persisted, or nil.
+    # @return [DateTime] the date
+    def created
+      if space_created = properties.space_created
+        DateTime.parse(space_created)
+      end
+    end
+
+    # Find a content item in the space
+    # @return [Duracloud::Content] the content item.
+    # @raise [Duracloud::NotFoundError] if the content item does not exist.
+    def find_content(content_id)
+      Content.find(space_id, content_id, store_id)
+    end
+
+    # Return the audit log for the space
+    # @return [Duracloud::AuditLog] the audit log
+    def audit_log
+      AuditLog.new(space_id, store_id)
+    end
 
-    def initialize(id)
-      @id = id
+    # Return the bit integrity report for the space
+    # @return [Duracloud::BitIntegrityReport] the report
+    def bit_integrity_report
+      BitIntergrityReport.new(space_id, store_id)
     end
 
+    # Return the manifest for the space
+    # @return [Duracloud::Manifest] the manifest
+    def manifest
+      Manifest.new(space_id, store_id)
+    end
+
+    # Return the ACLs for the space
+    # @return [Duracloud::SpaceAcls] the ACLs
     def acls
       @acls ||= SpaceAcls.new(self)
     end
 
-    def each(prefix: nil)
-      raise Error, "Space not yet persisted." unless persisted?
-      num = 0
-      while num < count
-        response = Client.get_space(id, query: {prefix: prefix, max_results: MAX_RESULTS})
-        xml = Nokogiri::XML(response.body)
-        content_ids = xml.css('item').map(&:text)
-        content_ids.each do |content_id|
-          yield content_id
+    # Enumerates the content IDs in the space.
+    # @param prefix [String] the content ID prefix for filtering (optional)
+    # @param start_after [String] the content ID to be used as a "marker".
+    #   Listing starts after this ID. (optional)
+    # @return [Enumerator] an enumerator.
+    # @raise [Duracloud::NotFoundError] the space does not exist in Duracloud.
+    def content_ids(prefix: nil, start_after: nil)
+      Enumerator.new do |yielder|
+        num = 0
+        marker = start_after
+        while num < count
+          q = query.merge(prefix: prefix, maxResults: MAX_RESULTS, marker: marker)
+          response = Client.get_space(space_id, **q)
+          xml = Nokogiri::XML(response.body)
+          ids = xml.css('item').map(&:text)
+          break if ids.empty?
+          ids.each do |content_id|
+            yielder << content_id
+          end
+          num += ids.length
+          marker = ids.last
         end
-        num += content_ids.length
       end
     end
 
-    def each_item(prefix: nil)
-      each(prefix: prefix) do |content_id|
-        yield Content.find(self, content_id)
+    # Enumerates the content items in the space.
+    # @see #content_ids
+    # @return [Enumerator] an enumerator.
+    # @raise [Duracloud::NotFoundError] the space does not exist in Duracloud.
+    def items(*args)
+      Enumerator.new do |yielder|
+        content_ids(*args).each do |content_id|
+          yielder << find_content(content_id)
+        end
       end
     end
 
@@ -68,11 +229,12 @@ module Duracloud
     end
 
     def create
-      Client.create_space(id)
+      Client.create_space(id, **query)
     end
 
     def update
-      Client.set_space_acls(id, acls)
+      options = { headers: acls.to_h, query: query }
+      Client.set_space_acls(id, **options)
     end
 
     def properties_class
@@ -80,11 +242,11 @@ module Duracloud
     end
 
     def get_properties_response
-      Client.get_space_properties(id)
+      Client.get_space_properties(id, **query)
     end
 
     def do_delete
-      Client.delete_space(id)
+      Client.delete_space(id, **query)
     end
 
     def do_save
@@ -95,5 +257,9 @@ module Duracloud
       end
     end
 
+    def query
+      { storeID: store_id }
+    end
+
   end
 end

data/lib/duracloud/space_acls.rb

@@ -11,10 +11,14 @@ module Duracloud
       super()
       @space = space
       if space.persisted?
-        response = Client.get_space_acls(space.id)
-        update SpaceAcls.filter(response.headers)
+        response = Client.get_space_acls(space.space_id, **query)
+        update filter(response.headers)
       end
     end
 
+    def query
+      { storeID: space.store_id }
+    end
+
   end
 end