tfe-cloudfiles 1.4.7

data/.gitignore

@@ -0,0 +1,5 @@
+tmp/*
+coverage/*
+doc/*
+pkg/*
+*.gem

data/COPYING

@@ -0,0 +1,12 @@
+Unless otherwise noted, all files are released under the MIT license, exceptions contain licensing information in them.
+
+  Copyright (C) 2008 Rackspace US, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Except as contained in this notice, the name of Rackspace US, Inc. shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from Rackspace US, Inc.
+

data/Manifest

@@ -0,0 +1,16 @@
+tfe-cloudfiles.gemspec
+lib/cloudfiles/authentication.rb
+lib/cloudfiles/connection.rb
+lib/cloudfiles/container.rb
+lib/cloudfiles/storage_object.rb
+lib/cloudfiles.rb
+Manifest
+Rakefile
+README.rdoc
+test/cf-testunit.rb
+test/cloudfiles_authentication_test.rb
+test/cloudfiles_connection_test.rb
+test/cloudfiles_container_test.rb
+test/cloudfiles_storage_object_test.rb
+test/test_helper.rb
+TODO

data/README.rdoc

@@ -0,0 +1,71 @@
+= Rackspace Cloud Files
+
+== Description
+
+This is a Ruby interface into the Rackspace[http://rackspace.com/] {Cloud Files}[http://www.rackspacecloud.com/cloud_hosting_products/files] service. Cloud Files is reliable, scalable and affordable web-based storage hosting for backing up and archiving all your static content.  Cloud Files is the first and only cloud service that leverages a tier one CDN provider to create such an easy and complete storage-to-delivery solution for media content.
+
+== Upgrade Gotchas
+
+As of gem version 1.4.8, the connection method has changed from positional arguments to a hash of options.  This is the new style:
+
+   cf = CloudFiles::Connection.new(:username => "MY_USERNAME", :api_key => "MY_API_KEY")
+   
+This is the old style, which still works but is deprecated:
+
+   cf = CloudFiles::Connection.new("MY_USERNAME","MY_API_KEY")
+
+== Installation
+
+This source is available on Github[http://github.com/rackspace/ruby-cloudfiles/] and the gem is available on Gemcutter[http://gemcutter.org/].  To install it, do
+
+  gem sources -a http://gemcutter.org/
+  
+  sudo gem install cloudfiles
+  
+To use it in a Rails application, add the following information to your config/environment.rb
+
+  config.gem "cloudfiles"
+  
+
+== Examples
+
+See the class definitions for documentation on specific methods and operations.
+
+  require 'rubygems'
+  require 'cloudfiles'
+
+  # Log into the Cloud Files system
+  cf = CloudFiles::Connection.new(:username => "MY_USERNAME", :api_key => "MY_API_KEY")
+
+  # Get a listing of all containers under this account
+  cf.containers
+  => ["backup", "Books", "cftest", "test", "video", "webpics"]
+
+  # Access a specific container
+  container = cf.container('test')
+
+  # See how many objects are under this container
+  container.count
+  => 3
+
+  # List the objects
+  container.objects
+  => ["bigfile.txt", "new.txt", "test.txt"]
+
+  # Select an object
+  object = container.object('test.txt')
+
+  # Get that object's data
+  object.data
+  => "This is test data"
+
+== Authors
+
+Initial work by Major Hayden <major.hayden@rackspace.com>
+
+Subsequent work by H. Wade Minter <wade.minter@rackspace.com>
+
+== License
+
+See COPYING for license information.
+Copyright (c) 2009, Rackspace US, Inc.

data/Rakefile

@@ -0,0 +1,34 @@
+require './lib/cloudfiles.rb'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "tfe-cloudfiles"
+    gemspec.summary = "A Ruby API into Rackspace Cloud Files"
+    gemspec.description = "A Ruby version of the Rackspace Cloud Files API."
+    gemspec.email = ["wade.minter@rackspace.com", "todd@toddeichel.com"]
+    gemspec.homepage = "http://www.rackspacecloud.com/cloud_hosting_products/files"
+    gemspec.authors = ["H. Wade Minter", "Rackspace Hosting", "Todd Eichel"]
+    gemspec.add_dependency('mime-types', '>= 1.16')
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end 
+
+namespace :test do
+  desc 'Check test coverage'
+  task :coverage do
+    rm_f "coverage"
+    system("rcov -x '/Library/Ruby/Gems/1.8/gems/' --sort coverage #{File.join(File.dirname(__FILE__), 'test/*_test.rb')}")
+    system("open #{File.join(File.dirname(__FILE__), 'coverage/index.html')}") if PLATFORM['darwin']
+  end
+
+  desc 'Remove coverage products'
+  task :clobber_coverage do
+    rm_r 'coverage' rescue nil
+  end
+
+end
+
+

data/VERSION

@@ -0,0 +1 @@
+1.4.7

data/lib/cloudfiles.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# 
+# == Cloud Files API
+# ==== Connects Ruby Applications to Rackspace's {Cloud Files service}[http://www.rackspacecloud.com/cloud_hosting_products/files]
+# Initial work by Major Hayden <major.hayden@rackspace.com>
+# 
+# Subsequent work by H. Wade Minter <wade.minter@rackspace.com>
+#
+# See COPYING for license information.
+# Copyright (c) 2009, Rackspace US, Inc.
+# ----
+# 
+# === Documentation & Examples
+# To begin reviewing the available methods and examples, peruse the README file, or begin by looking at documentation for the 
+# CloudFiles::Connection class.
+#
+# The CloudFiles class is the base class.  Not much of note happens here.
+# To create a new CloudFiles connection, use the CloudFiles::Connection.new('user_name', 'api_key') method.
+module CloudFiles
+
+  VERSION = IO.read(File.dirname(__FILE__) + '/../VERSION')
+  require 'net/http'
+  require 'net/https'
+  require 'rexml/document'
+  require 'uri'
+  require 'digest/md5'
+  require 'time'
+  require 'rubygems'
+  require 'mime/types'
+
+  unless "".respond_to? :each_char
+    require "jcode"
+    $KCODE = 'u'
+  end
+
+  $:.unshift(File.dirname(__FILE__))
+  require 'cloudfiles/authentication'
+  require 'cloudfiles/connection'
+  require 'cloudfiles/container'
+  require 'cloudfiles/storage_object'
+
+  def self.lines(str)
+    (str.respond_to?(:lines) ? str.lines : str).to_a.map { |x| x.chomp }
+  end
+end
+
+
+
+class SyntaxException             < StandardError # :nodoc:
+end
+class ConnectionException         < StandardError # :nodoc:
+end
+class AuthenticationException     < StandardError # :nodoc:
+end
+class InvalidResponseException    < StandardError # :nodoc:
+end
+class NonEmptyContainerException  < StandardError # :nodoc:
+end
+class NoSuchObjectException       < StandardError # :nodoc:
+end
+class NoSuchContainerException    < StandardError # :nodoc:
+end
+class NoSuchAccountException      < StandardError # :nodoc:
+end
+class MisMatchedChecksumException < StandardError # :nodoc:
+end
+class IOException                 < StandardError # :nodoc:
+end
+class CDNNotEnabledException      < StandardError # :nodoc:
+end
+class ObjectExistsException       < StandardError # :nodoc:
+end
+class ExpiredAuthTokenException   < StandardError # :nodoc:
+end

data/lib/cloudfiles/authentication.rb

@@ -0,0 +1,52 @@
+module CloudFiles
+  class Authentication
+    # See COPYING for license information.
+    # Copyright (c) 2009, Rackspace US, Inc.
+    
+    # Performs an authentication to the Cloud Files servers.  Opens a new HTTP connection to the API server,
+    # sends the credentials, and looks for a successful authentication.  If it succeeds, it sets the cdmmgmthost,
+    # cdmmgmtpath, storagehost, storagepath, authtoken, and authok variables on the connection.  If it fails, it raises
+    # an AuthenticationException.
+    #
+    # Should probably never be called directly.
+    def initialize(connection)
+      path = '/v1.0'
+      hdrhash = { "X-Auth-User" => connection.authuser, "X-Auth-Key" => connection.authkey }
+      begin
+        server = Net::HTTP::Proxy(connection.proxy_host, connection.proxy_port).new('auth.api.rackspacecloud.com',443)
+        server.use_ssl = true
+        server.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        server.start
+      rescue
+        raise ConnectionException, "Unable to connect to #{server}"
+      end
+      response = server.get(path,hdrhash)
+      if (response.code == "204")
+        connection.cdnmgmthost = URI.parse(response["x-cdn-management-url"]).host
+        connection.cdnmgmtpath = URI.parse(response["x-cdn-management-url"]).path
+        connection.cdnmgmtport = URI.parse(response["x-cdn-management-url"]).port
+        connection.cdnmgmtscheme = URI.parse(response["x-cdn-management-url"]).scheme
+        connection.storagehost = set_snet(connection,URI.parse(response["x-storage-url"]).host)
+        connection.storagepath = URI.parse(response["x-storage-url"]).path
+        connection.storageport = URI.parse(response["x-storage-url"]).port
+        connection.storagescheme = URI.parse(response["x-storage-url"]).scheme
+        connection.authtoken = response["x-auth-token"]
+        connection.authok = true
+      else
+        connection.authtoken = false
+        raise AuthenticationException, "Authentication failed"
+      end
+      server.finish
+    end
+    
+    private
+    
+    def set_snet(connection,hostname)
+      if connection.snet?
+        "snet-#{hostname}"
+      else
+        hostname
+      end
+    end
+  end
+end

data/lib/cloudfiles/connection.rb

@@ -0,0 +1,317 @@
+module CloudFiles
+  class Connection
+    # See COPYING for license information.
+    # Copyright (c) 2009, Rackspace US, Inc.
+    
+    # Authentication key provided when the CloudFiles class was instantiated
+    attr_reader :authkey
+
+    # Token returned after a successful authentication
+    attr_accessor :authtoken
+
+    # Authentication username provided when the CloudFiles class was instantiated
+    attr_reader :authuser
+
+    # Hostname of the CDN management server
+    attr_accessor :cdnmgmthost
+
+    # Path for managing containers on the CDN management server
+    attr_accessor :cdnmgmtpath
+    
+    # Port number for the CDN server
+    attr_accessor :cdnmgmtport
+    
+    # URI scheme for the CDN server
+    attr_accessor :cdnmgmtscheme
+
+    # Hostname of the storage server
+    attr_accessor :storagehost
+
+    # Path for managing containers/objects on the storage server
+    attr_accessor :storagepath
+    
+    # Port for managing the storage server
+    attr_accessor :storageport
+    
+    # URI scheme for the storage server
+    attr_accessor :storagescheme
+    
+    # Instance variable that is set when authorization succeeds
+    attr_accessor :authok
+    
+    # The total size in bytes under this connection
+    attr_reader :bytes
+    
+    # The total number of containers under this connection
+    attr_reader :count
+    
+    # Optional proxy variables
+    attr_reader :proxy_host
+    attr_reader :proxy_port
+    
+    # Creates a new CloudFiles::Connection object.  Uses CloudFiles::Authentication to perform the login for the connection.
+    # The authuser is the Rackspace Cloud username, the authkey is the Rackspace Cloud API key.
+    #
+    # Setting the optional retry_auth variable to false will cause an exception to be thrown if your authorization token expires.
+    # Otherwise, it will attempt to reauthenticate.
+    #
+    # Setting the optional snet variable to true or setting an environment variable of RACKSPACE_SERVICENET to any value will cause 
+    # storage URLs to be returned with a prefix pointing them to the internal Rackspace service network, instead of a public URL.  
+    #
+    # This is useful if you are using the library on a Rackspace-hosted system, as it provides faster speeds, keeps traffic off of
+    # the public network, and the bandwidth is not billed.
+    #
+    # This will likely be the base class for most operations.
+    # 
+    # With gem 1.4.8, the connection style has changed.  It is now a hash of arguments.  Note that the proxy options are currently only
+    # supported in the new style.
+    #
+    #   cf = CloudFiles::Connection.new(:username => "MY_USERNAME", :api_key => "MY_API_KEY", :retry_auth => true, :snet => false, :proxy_host => "localhost", :proxy_port => "1234")
+    #
+    # The old style (positional arguments) is deprecated and will be removed at some point in the future.
+    # 
+    #   cf = CloudFiles::Connection.new(MY_USERNAME, MY_API_KEY, RETRY_AUTH, USE_SNET)
+    def initialize(*args)
+      if args[0].is_a?(Hash)
+        options = args[0]
+        @authuser = options[:username] ||( raise AuthenticationException, "Must supply a :username")
+        @authkey = options[:api_key] || (raise AuthenticationException, "Must supply an :api_key")
+        @retry_auth = options[:retry_auth] || true
+        @snet = ENV['RACKSPACE_SERVICENET'] || options[:snet]
+        @proxy_host = options[:proxy_host]
+        @proxy_port = options[:proxy_port]
+      elsif args[0].is_a?(String)
+        @authuser = args[0] ||( raise AuthenticationException, "Must supply the username as the first argument")
+        @authkey = args[1] || (raise AuthenticationException, "Must supply the API key as the second argument")
+        @retry_auth = args[2] || true
+        @snet = (ENV['RACKSPACE_SERVICENET'] || args[3]) ? true : false
+      end
+      @authok = false
+      @http = {}
+      CloudFiles::Authentication.new(self)
+    end
+
+    # Returns true if the authentication was successful and returns false otherwise.
+    #
+    #   cf.authok?
+    #   => true
+    def authok?
+      @authok
+    end
+    
+    # Returns true if the library is requesting the use of the Rackspace service network
+    def snet?
+      @snet
+    end
+
+    # Returns an CloudFiles::Container object that can be manipulated easily.  Throws a NoSuchContainerException if
+    # the container doesn't exist.
+    #
+    #    container = cf.container('test')
+    #    container.count
+    #    => 2
+    def container(name)
+      CloudFiles::Container.new(self,name)
+    end
+    alias :get_container :container
+
+    # Sets instance variables for the bytes of storage used for this account/connection, as well as the number of containers
+    # stored under the account.  Returns a hash with :bytes and :count keys, and also sets the instance variables.
+    #
+    #   cf.get_info
+    #   => {:count=>8, :bytes=>42438527}
+    #   cf.bytes
+    #   => 42438527    
+    def get_info
+      response = cfreq("HEAD",@storagehost,@storagepath,@storageport,@storagescheme)
+      raise InvalidResponseException, "Unable to obtain account size" unless (response.code == "204")
+      @bytes = response["x-account-bytes-used"].to_i
+      @count = response["x-account-container-count"].to_i
+      {:bytes => @bytes, :count => @count}
+    end
+    
+    # Gathers a list of the containers that exist for the account and returns the list of container names
+    # as an array.  If no containers exist, an empty array is returned.  Throws an InvalidResponseException
+    # if the request fails.
+    #
+    # If you supply the optional limit and marker parameters, the call will return the number of containers
+    # specified in limit, starting after the object named in marker.
+    #
+    #   cf.containers
+    #   => ["backup", "Books", "cftest", "test", "video", "webpics"] 
+    #
+    #   cf.containers(2,'cftest')
+    #   => ["test", "video"]
+    def containers(limit=0,marker="")
+      paramarr = []
+      paramarr << ["limit=#{URI.encode(limit.to_s).gsub(/&/,'%26')}"] if limit.to_i > 0
+      paramarr << ["offset=#{URI.encode(marker.to_s).gsub(/&/,'%26')}"] unless marker.to_s.empty?
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}",@storageport,@storagescheme)
+      return [] if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      CloudFiles.lines(response.body)
+    end
+    alias :list_containers :containers
+
+    # Retrieves a list of containers on the account along with their sizes (in bytes) and counts of the objects
+    # held within them.  If no containers exist, an empty hash is returned.  Throws an InvalidResponseException
+    # if the request fails.
+    #
+    # If you supply the optional limit and marker parameters, the call will return the number of containers
+    # specified in limit, starting after the object named in marker.
+    # 
+    #   cf.containers_detail              
+    #   => { "container1" => { :bytes => "36543", :count => "146" }, 
+    #        "container2" => { :bytes => "105943", :count => "25" } }
+    def containers_detail(limit=0,marker="")
+      paramarr = []
+      paramarr << ["limit=#{URI.encode(limit.to_s).gsub(/&/,'%26')}"] if limit.to_i > 0
+      paramarr << ["offset=#{URI.encode(marker.to_s).gsub(/&/,'%26')}"] unless marker.to_s.empty?
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = cfreq("GET",@storagehost,"#{@storagepath}?format=xml&#{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("account/container/") { |c|
+        detailhash[c.elements["name"].text] = { :bytes => c.elements["bytes"].text, :count => c.elements["count"].text  }
+      }
+      doc = nil
+      return detailhash
+    end
+    alias :list_containers_info :containers_detail
+
+    # Returns true if the requested container exists and returns false otherwise.
+    # 
+    #   cf.container_exists?('good_container')
+    #   => true
+    #  
+    #   cf.container_exists?('bad_container')
+    #   => false
+    def container_exists?(containername)
+      response = cfreq("HEAD",@storagehost,"#{@storagepath}/#{URI.encode(containername).gsub(/&/,'%26')}",@storageport,@storagescheme)
+      return (response.code == "204")? true : false ;
+    end
+
+    # Creates a new container and returns the CloudFiles::Container object.  Throws an InvalidResponseException if the 
+    # request fails.
+    #
+    # Slash (/) and question mark (?) are invalid characters, and will be stripped out.  The container name is limited to 
+    # 256 characters or less.
+    #
+    #   container = cf.create_container('new_container')
+    #   container.name
+    #   => "new_container"
+    #
+    #   container = cf.create_container('bad/name')
+    #   => SyntaxException: Container name cannot contain the characters '/' or '?'
+    def create_container(containername)
+      raise SyntaxException, "Container name cannot contain the characters '/' or '?'" if containername.match(/[\/\?]/)
+      raise SyntaxException, "Container name is limited to 256 characters" if containername.length > 256
+      response = cfreq("PUT",@storagehost,"#{@storagepath}/#{URI.encode(containername).gsub(/&/,'%26')}",@storageport,@storagescheme)
+      raise InvalidResponseException, "Unable to create container #{containername}" unless (response.code == "201" || response.code == "202")
+      CloudFiles::Container.new(self,containername)
+    end
+
+    # Deletes a container from the account.  Throws a NonEmptyContainerException if the container still contains
+    # objects.  Throws a NoSuchContainerException if the container doesn't exist.
+    # 
+    #   cf.delete_container('new_container')
+    #   => true
+    #
+    #   cf.delete_container('video')
+    #   => NonEmptyContainerException: Container video is not empty
+    #
+    #   cf.delete_container('nonexistent')
+    #   => NoSuchContainerException: Container nonexistent does not exist
+    def delete_container(containername)
+      response = cfreq("DELETE",@storagehost,"#{@storagepath}/#{URI.encode(containername).gsub(/&/,'%26')}",@storageport,@storagescheme)
+      raise NonEmptyContainerException, "Container #{containername} is not empty" if (response.code == "409")
+      raise NoSuchContainerException, "Container #{containername} does not exist" unless (response.code == "204")
+      true
+    end
+
+    # Gathers a list of public (CDN-enabled) containers that exist for an account and returns the list of container names
+    # as an array.  If no containers are public, an empty array is returned.  Throws a InvalidResponseException if
+    # the request fails.
+    #
+    # If you pass the optional argument as true, it will only show containers that are CURRENTLY being shared on the CDN, 
+    # as opposed to the default behavior which is to show all containers that have EVER been public.
+    #
+    #   cf.public_containers
+    #   => ["video", "webpics"]
+    def public_containers(enabled_only = false)
+      paramstr = enabled_only == true ? "enabled_only=true" : ""
+      response = cfreq("GET",@cdnmgmthost,"#{@cdnmgmtpath}?#{paramstr}",@cdnmgmtport,@cdnmgmtscheme)
+      return [] if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      CloudFiles.lines(response.body)
+    end
+
+    # This method actually makes the HTTP calls out to the server
+    def cfreq(method,server,path,port,scheme,headers = {},data = nil,attempts = 0,&block) # :nodoc:
+      start = Time.now
+      headers['Transfer-Encoding'] = "chunked" if data.is_a?(IO)
+      hdrhash = headerprep(headers)
+      start_http(server,path,port,scheme,hdrhash)
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(path,hdrhash)
+      if data
+        if data.respond_to?(:read)
+          request.body_stream = data
+        else
+          request.body = data
+        end
+        unless data.is_a?(IO)
+          request.content_length = data.respond_to?(:lstat) ? data.stat.size : data.size
+        end
+      else
+        request.content_length = 0
+      end
+      response = @http[server].request(request,&block)
+      raise ExpiredAuthTokenException if response.code == "401"
+      response
+    rescue Errno::EPIPE, Timeout::Error, Errno::EINVAL, EOFError
+      # Server closed the connection, retry
+      raise ConnectionException, "Unable to reconnect to #{server} after #{count} attempts" if attempts >= 5
+      attempts += 1
+      @http[server].finish
+      start_http(server,path,port,scheme,headers)
+      retry
+    rescue ExpiredAuthTokenException
+      raise ConnectionException, "Authentication token expired and you have requested not to retry" if @retry_auth == false
+      CloudFiles::Authentication.new(self)
+      retry
+    end
+    
+    private
+    
+    # Sets up standard HTTP headers
+    def headerprep(headers = {}) # :nodoc:
+      default_headers = {}
+      default_headers["X-Auth-Token"] = @authtoken if (authok? && @account.nil?)
+      default_headers["X-Storage-Token"] = @authtoken if (authok? && !@account.nil?)
+      default_headers["Connection"] = "Keep-Alive"
+      default_headers["User-Agent"] = "CloudFiles Ruby API #{VERSION}"
+      default_headers.merge(headers)
+    end
+    
+    # Starts (or restarts) the HTTP connection
+    def start_http(server,path,port,scheme,headers) # :nodoc:
+      if (@http[server].nil?)
+        begin
+          @http[server] = Net::HTTP::Proxy(self.proxy_host, self.proxy_port).new(server,port)
+          if scheme == "https"
+            @http[server].use_ssl = true
+            @http[server].verify_mode = OpenSSL::SSL::VERIFY_NONE
+          end
+          @http[server].start
+        rescue
+          raise ConnectionException, "Unable to connect to #{server}"
+        end
+      end
+    end
+
+  end
+
+end