jmstacey-ruby-cloudfiles 1.3.2

data/LICENSE

@@ -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/README.markdown

@@ -0,0 +1,78 @@
+Mosso Cloud Files
+=================
+
+This is a Ruby interface into the Rackspace[http://rackspace.com/] {Mosso Cloud Files}[http://www.mosso.com/cloudfiles.jsp] 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.
+
+Important Notice
+----------------
+
+This is NOT the official Ruby Cloud Files API. There are two branches in this project: offical and master. The official branch contains an unmodified official 1.3.0 Ruby API released by Rackspace. This branch (master) contains a slightly enhanced version as indicated in the Enhancements section below.
+
+* Releases from the official branch will be tagged with a prefix of "official-"
+* The Ruby Gem is the latest tagged version of the enhanced version.
+
+Requirements
+----------------
+
+* mime-types
+* archive-tar-minitar
+* nokogiri
+* hoe
+* rcov
+
+Installation
+---------------
+
+* gem sources -a http://gems.github.com
+* sudo gem install jmstacey-ruby-cloudfiles
+
+Examples
+----------------
+
+See the class definitions for documentation on specific methods and operations.
+
+  require 'cloudfiles'
+
+  # Log into the Cloud Files system
+  cf = CloudFiles::Connection.new(USERNAME, 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"
+
+Enhancements
+----------------
+
+* Pipe standard input ($stdin) straight to the container. [Jon Stacey in 1.3.1]
+	* Pass the string "STDIN" as the data for a write action. See the CFBackup project for a real-world example.
+
+Authors
+----------------
+
+Initial work by Major Hayden <major.hayden@rackspace.com>
+
+Subsequent work by H. Wade Minter <wade.minter@rackspace.com>
+
+Further enhancements by Jon Stacey
+
+Copyright
+----------------
+Copyright (c) 2009, Rackspace US, Inc. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+require './lib/cloudfiles.rb'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ruby-cloudfiles"
+    gem.summary = %Q{TODO}
+    gem.email = "jon@jonsview.com"
+    gem.homepage = "http://github.com/jmstacey/ruby-cloudfiles"
+    gem.authors = ["H. Wade Minter", "Rackspace Hosting", "Jon Stacey"]
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ruby-cloudfiles #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 3
+:patch: 2

data/lib/cloudfiles.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# 
+# == Cloud Files API
+# ==== Connects Ruby Applications to Rackspace's {Mosso Cloud Files service}[http://www.mosso.com/cloudfiles.jsp]
+# 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 = '1.3.0'
+  require 'net/http'
+  require 'net/https'
+  require 'rexml/document'
+  require 'uri'
+  require 'digest/md5'
+  require 'jcode' 
+  require 'time'
+  require 'rubygems'
+  require 'mime/types'
+
+  $KCODE = 'u'
+
+  $:.unshift(File.dirname(__FILE__))
+  require 'cloudfiles/authentication'
+  require 'cloudfiles/connection'
+  require 'cloudfiles/container'
+  require 'cloudfiles/storage_object'
+
+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,38 @@
+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 = '/auth'
+      hdrhash = { "X-Auth-User" => connection.authuser, "X-Auth-Key" => connection.authkey }
+      begin
+        server = Net::HTTP.new('api.mosso.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.storagehost = URI.parse(response["x-storage-url"]).host
+        connection.storagepath = URI.parse(response["x-storage-url"]).path
+        connection.authtoken = response["x-auth-token"]
+        connection.authok = true
+      else
+        connection.authtoken = false
+        raise AuthenticationException, "Authentication failed"
+      end
+      server.finish
+    end
+  end
+end

data/lib/cloudfiles/connection.rb

@@ -0,0 +1,286 @@
+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
+
+    # Array of requests that have been made so far
+    attr_reader :reqlog
+
+    # Hostname of the storage server
+    attr_accessor :storagehost
+
+    # Path for managing containers/objects on the storage server
+    attr_accessor :storagepath
+    
+    # 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
+
+    # Creates a new CloudFiles::Connection object.  Uses CloudFiles::Authentication to perform the login for the connection.
+    # The authuser is the Mosso username, the authkey is the Mosso 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.
+    #
+    # This will likely be the base class for most operations.
+    #
+    #   cf = CloudFiles::Connection.new(MY_USERNAME, MY_API_KEY)
+    def initialize(authuser,authkey,retry_auth = true) 
+      @authuser = authuser
+      @authkey = authkey
+      @retry_auth = retry_auth
+      @authok = false
+      @http = {}
+      @reqlog = []
+      CloudFiles::Authentication.new(self)
+    end
+
+    # Returns true if the authentication was successful and returns false otherwise.
+    #
+    #   cf.authok?
+    #   => true
+    def authok?
+      @authok
+    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)
+      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)}"] if limit.to_i > 0
+      paramarr << ["offset=#{URI.encode(marker.to_s)}"] unless marker.to_s.empty?
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = cfreq("GET",@storagehost,"#{@storagepath}?#{paramstr}")
+      return [] if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      response.body.to_a.map { |x| x.chomp }
+    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)}"] if limit.to_i > 0
+      paramarr << ["offset=#{URI.encode(marker.to_s)}"] unless marker.to_s.empty?
+      paramstr = (paramarr.size > 0)? paramarr.join("&") : "" ;
+      response = cfreq("GET",@storagehost,"#{@storagepath}?format=xml&#{paramstr}")
+      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}/#{containername}")
+      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}/#{containername}")
+      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}/#{containername}")
+      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}")
+      return [] if (response.code == "204")
+      raise InvalidResponseException, "Invalid response code #{response.code}" unless (response.code == "200")
+      response.body.to_a.map { |x| x.chomp }
+    end
+
+    # This method actually makes the HTTP calls out to the server
+    def cfreq(method,server,path,headers = {},data = nil,attempts = 0,&block) # :nodoc:
+      if data == "STDIN" # Hack (see next comment)
+        headers['Transfer-Encoding'] = "chunked"
+      end     
+
+      start = Time.now
+      hdrhash = headerprep(headers)
+      path = URI.escape(path)
+      start_http(server,path,hdrhash)
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(path,hdrhash)
+      
+      # Hacked by Jon Stacey to enable piped data to be streamed
+      if data
+        if data == "STDIN"
+          request.body_stream = $stdin
+        elsif data.respond_to?(:read)
+          request.body_stream = data
+        else
+          request.body = data
+        end
+        
+        unless data == "STDIN"              
+          request.content_length = data.respond_to?(:lstat) ? data.stat.size : data.size
+        end
+        
+      else
+        request.content_length = 0
+      end # if data
+      
+      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,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"] = "Ruby-CloudFiles/#{VERSION}"
+      default_headers.merge(headers)
+    end
+    
+    # Starts (or restarts) the HTTP connection
+    def start_http(server,path,headers) # :nodoc:
+      if (@http[server].nil?)
+        begin
+          @http[server] = Net::HTTP.new(server,443)
+          @http[server].use_ssl = true
+          @http[server].verify_mode = OpenSSL::SSL::VERIFY_NONE
+          # @http[server].set_debug_output $stderr # For debug purposes
+          @http[server].start
+        rescue
+          raise ConnectionException, "Unable to connect to #{server}"
+        end
+      end
+    end
+
+  end
+
+end