cloudfiles 1.4.0

data/lib/cloudfiles/container.rb

@@ -0,0 +1,275 @@
+module CloudFiles
+  class Container
+    # See COPYING for license information.
+    # Copyright (c) 2009, Rackspace US, Inc.
+
+    # Name of the container which corresponds to the instantiated container class
+    attr_reader :name
+
+    # Size of the container (in bytes)
+    attr_reader :bytes
+
+    # Number of objects in the container
+    attr_reader :count
+
+    # True if container is public, false if container is private
+    attr_reader :cdn_enabled
+
+    # CDN container TTL (if container is public)
+    attr_reader :cdn_ttl
+
+    # CDN container URL (if container if public)
+    attr_reader :cdn_url
+    
+    # The parent CloudFiles::Connection object for this container
+    attr_reader :connection
+
+    # Retrieves an existing CloudFiles::Container object tied to the current CloudFiles::Connection.  If the requested
+    # container does not exist, it will raise a NoSuchContainerException.  
+    # 
+    # Will likely not be called directly, instead use connection.container('container_name') to retrieve the object.
+    def initialize(connection,name)
+      @connection = connection
+      @name = name
+      @storagehost = self.connection.storagehost
+      @storagepath = self.connection.storagepath + "/" + URI.encode(@name).gsub(/&/,'%26')
+      @storageport = self.connection.storageport
+      @storagescheme = self.connection.storagescheme
+      @cdnmgmthost = self.connection.cdnmgmthost
+      @cdnmgmtpath = self.connection.cdnmgmtpath + "/" + URI.encode(@name).gsub(/&/,'%26')
+      @cdnmgmtport = self.connection.cdnmgmtport
+      @cdnmgmtscheme = self.connection.cdnmgmtscheme
+      populate
+    end
+
+    # Retrieves data about the container and populates class variables.  It is automatically called
+    # when the Container class is instantiated.  If you need to refresh the variables, such as 
+    # size, count, cdn_enabled, cdn_ttl, and cdn_url, this method can be called again.
+    #
+    #   container.count
+    #   => 2
+    #   [Upload new file to the container]
+    #   container.count
+    #   => 2
+    #   container.populate
+    #   container.count
+    #   => 3
+    def populate
+      # Get the size and object count
+      response = self.connection.cfreq("HEAD",@storagehost,@storagepath+"/",@storageport,@storagescheme)
+      raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "204")
+      @bytes = response["x-container-bytes-used"].to_i
+      @count = response["x-container-object-count"].to_i
+
+      # Get the CDN-related details
+      response = self.connection.cfreq("HEAD",@cdnmgmthost,@cdnmgmtpath,@cdnmgmtport,@cdnmgmtscheme)
+      @cdn_enabled = ((response["x-cdn-enabled"] || "").downcase == "true") ? true : false
+      @cdn_ttl = @cdn_enabled ? response["x-ttl"] : false
+      @cdn_url = @cdn_enabled ? response["x-cdn-uri"] : false
+      if @cdn_enabled
+        @cdn_log = response["x-log-retention"] == "False" ? false : true
+      else
+        @cdn_log = false
+      end
+
+      true
+    end
+    alias :refresh :populate
+    
+    # Returns true if log retention is enabled on this container, false otherwise
+    def log_retention?
+      @cdn_log
+    end
+    
+    # Change the log retention status for this container.  Values are true or false.
+    #
+    # These logs will be periodically (at unpredictable intervals) compressed and uploaded 
+    # to a “.CDN_ACCESS_LOGS” container in the form of “container_name.YYYYMMDDHH-XXXX.gz”.
+    def log_retention=(value)
+      response = self.connection.cfreq("POST",@cdnmgmthost,@cdnmgmtpath,@cdnmgmtport,@cdnmgmtscheme,{"x-log-retention" => value.to_s.capitalize})
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "201" or response.code == "202")
+      return true 
+    end
+      
+
+    # Returns the CloudFiles::StorageObject for the named object.  Refer to the CloudFiles::StorageObject class for available
+    # methods.  If the object exists, it will be returned.  If the object does not exist, a NoSuchObjectException will be thrown.
+    # 
+    #   object = container.object('test.txt')
+    #   object.data
+    #   => "This is test data"
+    #
+    #   object = container.object('newfile.txt')
+    #   => NoSuchObjectException: Object newfile.txt does not exist
+    def object(objectname)
+      o = CloudFiles::StorageObject.new(self,objectname,true)
+      return o
+    end
+    alias :get_object :object
+    
+
+    # Gathers a list of all available objects in the current container and returns an array of object names.  
+    #   container = cf.container("My Container")
+    #   container.objects                     #=> [ "dog", "cat", "donkey", "monkeydir/capuchin"]
+    # Pass a limit argument to limit the list to a number of objects:
+    #   container.objects(:limit => 1)                  #=> [ "dog" ]
+    # Pass an offset with or without a limit to start the list at a certain object:
+    #   container.objects(:limit => 1, :offset => 2)                #=> [ "donkey" ]
+    # Pass a prefix to search for objects that start with a certain string:
+    #   container.objects(:prefix => "do")       #=> [ "dog", "donkey" ]
+    # Only search within a certain pseudo-filesystem path:
+    #   container.objects(:path => 'monkeydir')     #=> ["monkeydir/capuchin"]
+    # All arguments to this method are optional.
+    # 
+    # Returns an empty array if no object exist in the container.  Throws an InvalidResponseException
+    # if the request fails.
+    def objects(params = {})
+      paramarr = []
+      paramarr << ["limit=#{URI.encode(params[:limit].to_i).gsub(/&/,'%26')}"] if params[:limit]
+      paramarr << ["offset=#{URI.encode(params[:offset].to_i).gsub(/&/,'%26')}"] if params[:offset]
+      paramarr << ["prefix=#{URI.encode(params[:prefix]).gsub(/&/,'%26')}"] if params[:prefix]
+      paramarr << ["path=#{URI.encode(params[:path]).gsub(/&/,'%26')}"] if params[:path]
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = self.connection.cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}",@storageport,@storagescheme)
+      return [] if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      return CloudFiles.lines(response.body)
+    end
+    alias :list_objects :objects
+
+    # Retrieves a list of all objects in the current container along with their size in bytes, hash, and content_type.
+    # If no objects exist, an empty hash is returned.  Throws an InvalidResponseException if the request fails.  Takes a
+    # parameter hash as an argument, in the same form as the objects method.
+    # 
+    # Returns a hash in the same format as the containers_detail from the CloudFiles class.
+    #
+    #   container.objects_detail
+    #   => {"test.txt"=>{:content_type=>"application/octet-stream", 
+    #                    :hash=>"e2a6fcb4771aa3509f6b27b6a97da55b", 
+    #                    :last_modified=>Mon Jan 19 10:43:36 -0600 2009, 
+    #                    :bytes=>"16"}, 
+    #       "new.txt"=>{:content_type=>"application/octet-stream", 
+    #                   :hash=>"0aa820d91aed05d2ef291d324e47bc96", 
+    #                   :last_modified=>Wed Jan 28 10:16:26 -0600 2009, 
+    #                   :bytes=>"22"}
+    #      }
+    def objects_detail(params = {})
+      paramarr = []
+      paramarr << ["format=xml"]
+      paramarr << ["limit=#{URI.encode(params[:limit].to_i).gsub(/&/,'%26')}"] if params[:limit]
+      paramarr << ["offset=#{URI.encode(params[:offset].to_i).gsub(/&/,'%26')}"] if params[:offset]
+      paramarr << ["prefix=#{URI.encode(params[:prefix]).gsub(/&/,'%26')}"] if params[:prefix]
+      paramarr << ["path=#{URI.encode(params[:path]).gsub(/&/,'%26')}"] if params[:path]
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = self.connection.cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}",@storageport,@storagescheme)
+      return {} if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      doc = REXML::Document.new(response.body)
+      detailhash = {}
+      doc.elements.each("container/object") { |o|
+        detailhash[o.elements["name"].text] = { :bytes => o.elements["bytes"].text, :hash => o.elements["hash"].text, :content_type => o.elements["content_type"].text, :last_modified => Time.parse(o.elements["last_modified"].text) }
+      }
+      doc = nil
+      return detailhash
+    end
+    alias :list_objects_info :objects_detail
+
+    # Returns true if the container is public and CDN-enabled.  Returns false otherwise.
+    #
+    #   public_container.public?
+    #   => true
+    #
+    #   private_container.public?
+    #   => false
+    def public?
+      return @cdn_enabled
+    end
+
+    # Returns true if a container is empty and returns false otherwise.
+    #
+    #   new_container.empty?
+    #   => true
+    #
+    #   full_container.empty?
+    #   => false
+    def empty?
+      return (@count.to_i == 0)? true : false
+    end
+
+    # Returns true if object exists and returns false otherwise.
+    #
+    #   container.object_exists?('goodfile.txt')
+    #   => true
+    #
+    #   container.object_exists?('badfile.txt')
+    #   => false
+    def object_exists?(objectname)
+      response = self.connection.cfreq("HEAD",@storagehost,"#{@storagepath}/#{URI.encode(objectname).gsub(/&/,'%26')}",@storageport,@storagescheme)
+      return (response.code == "204")? true : false
+    end
+
+    # Creates a new CloudFiles::StorageObject in the current container. 
+    #
+    # If an object with the specified name exists in the current container, that object will be returned.  Otherwise,
+    # an empty new object will be returned.
+    #
+    # Passing in the optional make_path argument as true will create zero-byte objects to simulate a filesystem path
+    # to the object, if an objectname with path separators ("/path/to/myfile.mp3") is supplied.  These path objects can 
+    # be used in the Container.objects method.
+    def create_object(objectname,make_path = false)
+      CloudFiles::StorageObject.new(self,objectname,false,make_path)
+    end
+    
+    # Removes an CloudFiles::StorageObject from a container.  True is returned if the removal is successful.  Throws 
+    # NoSuchObjectException if the object doesn't exist.  Throws InvalidResponseException if the request fails.
+    #
+    #   container.delete_object('new.txt')
+    #   => true
+    #
+    #   container.delete_object('nonexistent_file.txt')
+    #   => NoSuchObjectException: Object nonexistent_file.txt does not exist
+    def delete_object(objectname)
+      response = self.connection.cfreq("DELETE",@storagehost,"#{@storagepath}/#{URI.encode(objectname).gsub(/&/,'%26')}",@storageport,@storagescheme)
+      raise NoSuchObjectException, "Object #{objectname} does not exist" if (response.code == "404")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "204")
+      true
+    end
+
+    # Makes a container publicly available via the Cloud Files CDN and returns true upon success.  Throws NoSuchContainerException
+    # if the container doesn't exist or if the request fails.
+    # 
+    # Takes an optional argument, which is the CDN cache TTL in seconds (default 86400 seconds or 1 day, maximum 259200 or 3 days)
+    #
+    #   container.make_public(432000)
+    #   => true
+    def make_public(ttl = 86400)
+      response = self.connection.cfreq("PUT",@cdnmgmthost,@cdnmgmtpath,@cdnmgmtport,@cdnmgmtscheme)
+      raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")
+
+      headers = { "X-TTL" => ttl.to_s }
+      response = self.connection.cfreq("POST",@cdnmgmthost,@cdnmgmtpath,@cdnmgmtport,@cdnmgmtscheme,headers)
+      raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")
+      true
+    end
+
+    # Makes a container private and returns true upon success.  Throws NoSuchContainerException
+    # if the container doesn't exist or if the request fails.
+    #
+    # Note that if the container was previously public, it will continue to exist out on the CDN until it expires.
+    #
+    #   container.make_private
+    #   => true
+    def make_private
+      headers = { "X-CDN-Enabled" => "False" }
+      response = self.connection.cfreq("POST",@cdnmgmthost,@cdnmgmtpath,@cdnmgmtport,@cdnmgmtscheme,headers)
+      raise NoSuchContainerException, "Container #{@name} does not exist" unless (response.code == "201" || response.code == "202")
+      true
+    end
+    
+    def to_s # :nodoc:
+      @name
+    end
+
+  end
+
+end

data/lib/cloudfiles/storage_object.rb

@@ -0,0 +1,257 @@
+module CloudFiles
+  class StorageObject
+    # See COPYING for license information.
+    # Copyright (c) 2009, Rackspace US, Inc.
+    
+    # Name of the object corresponding to the instantiated object
+    attr_reader :name
+
+    # Size of the object (in bytes)
+    attr_reader :bytes
+    
+    # The parent CloudFiles::Container object
+    attr_reader :container
+
+    # Date of the object's last modification
+    attr_reader :last_modified
+
+    # ETag of the object data
+    attr_reader :etag
+
+    # Content type of the object data
+    attr_reader :content_type
+
+    # Builds a new CloudFiles::StorageObject in the current container.  If force_exist is set, the object must exist or a
+    # NoSuchObjectException will be raised.  If not, an "empty" CloudFiles::StorageObject will be returned, ready for data
+    # via CloudFiles::StorageObject.write
+    def initialize(container,objectname,force_exists=false,make_path=false) 
+      if objectname.match(/\?/)
+        raise SyntaxException, "Object #{objectname} contains an invalid character in the name (? not allowed)"
+      end
+      @container = container
+      @containername = container.name
+      @name = objectname
+      @make_path = make_path
+      @storagehost = self.container.connection.storagehost
+      @storagepath = self.container.connection.storagepath+"/#{URI.encode(@containername).gsub(/&/,'%26')}/#{URI.encode(@name).gsub(/&/,'%26')}"
+      @storageport = self.container.connection.storageport
+      @storagescheme = self.container.connection.storagescheme
+      if container.object_exists?(objectname)
+        populate
+      else
+        raise NoSuchObjectException, "Object #{@name} does not exist" if force_exists
+      end
+    end
+    
+    # Caches data about the CloudFiles::StorageObject for fast retrieval.  This method is automatically called when the 
+    # class is initialized, but it can be called again if the data needs to be updated.
+    def populate
+      response = self.container.connection.cfreq("HEAD",@storagehost,@storagepath,@storageport,@storagescheme)
+      raise NoSuchObjectException, "Object #{@name} does not exist" if (response.code != "204")
+      @bytes = response["content-length"]
+      @last_modified = Time.parse(response["last-modified"])
+      @etag = response["etag"]
+      @content_type = response["content-type"]
+      resphash = {}
+      response.to_hash.select { |k,v| k.match(/^x-object-meta/) }.each { |x| resphash[x[0]] = x[1].to_s }
+      @metadata = resphash
+      true
+    end
+    alias :refresh :populate
+
+    # Retrieves the data from an object and stores the data in memory.  The data is returned as a string.
+    # Throws a NoSuchObjectException if the object doesn't exist.
+    #
+    # If the optional size and range arguments are provided, the call will return the number of bytes provided by
+    # size, starting from the offset provided in offset.
+    # 
+    #   object.data
+    #   => "This is the text stored in the file"
+    def data(size=-1,offset=0,headers = {})
+      if size.to_i > 0
+        range = sprintf("bytes=%d-%d", offset.to_i, (offset.to_i + size.to_i) - 1)
+        headers['Range'] = range
+      end
+      response = self.container.connection.cfreq("GET",@storagehost,@storagepath,@storageport,@storagescheme,headers)
+      raise NoSuchObjectException, "Object #{@name} does not exist" unless (response.code =~ /^20/)
+      response.body.chomp
+    end
+
+    # Retrieves the data from an object and returns a stream that must be passed to a block.  Throws a 
+    # NoSuchObjectException if the object doesn't exist.
+    #
+    # If the optional size and range arguments are provided, the call will return the number of bytes provided by
+    # size, starting from the offset provided in offset.
+    #
+    #   data = ""
+    #   object.data_stream do |chunk|
+    #     data += chunk
+    #   end
+    #  
+    #   data
+    #   => "This is the text stored in the file"
+    def data_stream(size=-1,offset=0,headers = {},&block)
+      if size.to_i > 0
+        range = sprintf("bytes=%d-%d", offset.to_i, (offset.to_i + size.to_i) - 1)
+        headers['Range'] = range
+      end
+      self.container.connection.cfreq("GET",@storagehost,@storagepath,@storageport,@storagescheme,headers,nil) do |response|
+        raise NoSuchObjectException, "Object #{@name} does not exist" unless (response.code == "200")
+        response.read_body(&block)
+      end
+    end
+
+    # Returns the object's metadata as a nicely formatted hash, stripping off the X-Meta-Object- prefix that the system prepends to the
+    # key name.
+    #
+    #    object.metadata
+    #    => {"ruby"=>"cool", "foo"=>"bar"}
+    def metadata
+      metahash = {}
+      @metadata.each{|key, value| metahash[key.gsub(/x-object-meta-/,'').gsub(/\+\-/, ' ')] = URI.decode(value).gsub(/\+\-/, ' ')}
+      metahash
+    end
+    
+    # Sets the metadata for an object.  By passing a hash as an argument, you can set the metadata for an object.
+    # However, setting metadata will overwrite any existing metadata for the object.
+    # 
+    # Throws NoSuchObjectException if the object doesn't exist.  Throws InvalidResponseException if the request
+    # fails.
+    def set_metadata(metadatahash)
+      headers = {}
+      metadatahash.each{|key, value| headers['X-Object-Meta-' + key.to_s.capitalize] = value.to_s}
+      response = self.container.connection.cfreq("POST",@storagehost,@storagepath,@storageport,@storagescheme,headers)
+      raise NoSuchObjectException, "Object #{@name} does not exist" if (response.code == "404")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "202")
+      true
+    end
+    
+    # Takes supplied data and writes it to the object, saving it.  You can supply an optional hash of headers, including
+    # Content-Type and ETag, that will be applied to the object.
+    #
+    # If you would rather stream the data in chunks, instead of reading it all into memory at once, you can pass an 
+    # IO object for the data, such as: object.write(open('/path/to/file.mp3'))
+    #
+    # You can compute your own MD5 sum and send it in the "ETag" header.  If you provide yours, it will be compared to
+    # the MD5 sum on the server side.  If they do not match, the server will return a 422 status code and a MisMatchedChecksumException
+    # will be raised.  If you do not provide an MD5 sum as the ETag, one will be computed on the server side.
+    #
+    # Updates the container cache and returns true on success, raises exceptions if stuff breaks.
+    #
+    #   object = container.create_object("newfile.txt")
+    #
+    #   object.write("This is new data")
+    #   => true
+    #
+    #   object.data
+    #   => "This is new data"
+    #
+    # If you are passing your data in via STDIN, just do an
+    #
+    #   object.write
+    #
+    # with no data (or, if you need to pass headers)
+    #
+    #  object.write(nil,{'header' => 'value})
+    
+    def write(data=nil,headers={})
+      raise SyntaxException, "No data or header updates supplied" if ((data.nil? && $stdin.tty?) and headers.empty?)
+      if headers['Content-Type'].nil?
+        type = MIME::Types.type_for(self.name).first.to_s
+        if type.empty?
+          headers['Content-Type'] = "application/octet-stream"
+        else
+          headers['Content-Type'] = type
+        end
+      end
+      # If we're taking data from standard input, send that IO object to cfreq
+      data = $stdin if (data.nil? && $stdin.tty? == false)
+      response = self.container.connection.cfreq("PUT",@storagehost,"#{@storagepath}",@storageport,@storagescheme,headers,data)
+      code = response.code
+      raise InvalidResponseException, "Invalid content-length header sent" if (code == "412")
+      raise MisMatchedChecksumException, "Mismatched etag" if (code == "422")
+      raise InvalidResponseException, "Invalid response code #{code}" unless (code == "201")
+      make_path(File.dirname(self.name)) if @make_path == true
+      self.populate
+      true
+    end
+    
+    # A convenience method to stream data into an object from a local file (or anything that can be loaded by Ruby's open method)
+    #
+    # Throws an Errno::ENOENT if the file cannot be read.
+    #
+    #   object.data
+    #   => "This is my data"
+    #
+    #   object.load_from_filename("/tmp/file.txt")
+    #   => true
+    #
+    #   object.data
+    #   => "This data was in the file /tmp/file.txt"
+    #
+    #   object.load_from_filename("/tmp/nonexistent.txt")
+    #   => Errno::ENOENT: No such file or directory - /tmp/nonexistent.txt
+    def load_from_filename(filename)
+      f = open(filename)
+      self.write(f)
+      f.close
+      true
+    end
+
+    # A convenience method to stream data from an object into a local file
+    #
+    # Throws an Errno::ENOENT if the file cannot be opened for writing due to a path error, 
+    # and Errno::EACCES if the file cannot be opened for writing due to permissions.
+    #
+    #   object.data
+    #   => "This is my data"
+    #
+    #   object.save_to_filename("/tmp/file.txt")
+    #   => true
+    #
+    #   $ cat /tmp/file.txt
+    #   "This is my data"
+    #
+    #   object.save_to_filename("/tmp/owned_by_root.txt")
+    #   => Errno::EACCES: Permission denied - /tmp/owned_by_root.txt
+    def save_to_filename(filename)
+      File.open(filename, 'w+') do |f|
+        self.data_stream do |chunk|
+          f.write chunk
+        end
+      end
+      true
+    end
+    
+    # If the parent container is public (CDN-enabled), returns the CDN URL to this object.  Otherwise, return nil
+    #
+    #   public_object.public_url
+    #   => "http://c0001234.cdn.cloudfiles.rackspacecloud.com/myfile.jpg"
+    #
+    #   private_object.public_url
+    #   => nil
+    def public_url
+      self.container.public? ? self.container.cdn_url + "/#{URI.encode(@name).gsub(/&/,'%26')}" : nil
+    end
+    
+    def to_s # :nodoc:
+      @name
+    end
+    
+    private
+    
+    def make_path(path) # :nodoc:
+      if path == "." || path == "/"
+        return
+      else
+        unless self.container.object_exists?(path)
+          o = self.container.create_object(path)
+          o.write(nil,{'Content-Type' => 'application/directory'})
+        end
+        make_path(File.dirname(path))
+      end
+    end
+
+  end
+
+end