fog 1.10.0 → 1.10.1

data/lib/fog/rackspace/models/compute_v2/metadatum.rb

@@ -13,6 +13,10 @@ module Fog
 
         # Remove metadatum from server
         # @return [Boolean] return true if metadatum is deleting
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def destroy
           requires :identity
           connection.delete_metadata_item(collection_name, parent.id, key)
@@ -21,6 +25,10 @@ module Fog
 
         # Save metadatum on server
         # @return [Boolean] return true if metadatum is saving
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def save
           requires :identity, :value
           connection.set_metadata_item(collection_name, parent.id, key, value)

data/lib/fog/rackspace/models/compute_v2/server.rb

@@ -180,6 +180,10 @@ module Fog
         # * requires attributes: service:, :name, :image_id, and :flavor_id
         # * optional attributes :disk_config, :metadata, :personality
         # @return [Boolean] returns true if server is being created
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note You should use servers.create to create servers instead calling this method directly
         # @see Servers#create
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/CreateServers.html        
@@ -207,6 +211,10 @@ module Fog
         # This will update :name, :accessIPv4, and :accessIPv6 attributes.
         # @note If you edit the server name, the server host name does not change. Also, server names are not guaranteed to be unique.
         # @return true if update has started updating
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/ServerUpdate.html
         #
         # * State Transition
@@ -226,11 +234,15 @@ module Fog
 
         # Destroy the server
         # @return [Boolean] returns true if server has started deleting
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Delete_Server-d1e2883.html
         #
-        #   * Status Transition:	
-        #     * ACTIVE -> DELETED
-        #     * ERROR -> DELETED
+        # * Status Transition:
+        #   * ACTIVE -> DELETED
+        #   * ERROR -> DELETED
         def destroy
           requires :identity
           service.delete_server(identity)
@@ -239,6 +251,10 @@ module Fog
 
         # Server flavor
         # @return [Fog::Compute::RackspaceV2::Flavor] server flavor
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def flavor
           requires :flavor_id
           @flavor ||= service.flavors.get(flavor_id)
@@ -246,6 +262,10 @@ module Fog
 
         # Server image
         # @return [Fog::Compute::RackspaceV2::Image] server image
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def image
           requires :image_id
           @image ||= service.images.get(image_id)
@@ -256,11 +276,15 @@ module Fog
         # @param options [Hash]:
         # @option options [Hash<String, String>] metadata hash of containing metadata key value pairs.
         # @return [Fog::ComputeRackspaceV2::Image] image being created
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Create_Image-d1e4655.html
         #
-        #   * State Transition:
-        #     * SAVING -> ACTIVE
-        #     * SAVING  -> ERROR (on error)
+        # * State Transition:
+        #   * SAVING -> ACTIVE
+        #   * SAVING  -> ERROR (on error)
         def create_image(name, options = {})
           requires :identity
           response = service.create_image(identity, name, options)
@@ -274,6 +298,10 @@ module Fog
 
         # Attached Cloud Block Volumes
         # @return [Fog::Compute::RackspaceV2::Attachments] attached Cloud Block Volumes 
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/List_Volume_Attachments.html
         def attachments
           @attachments ||= begin
@@ -288,6 +316,10 @@ module Fog
         # @param [Fog::Rackspace::BlockStorage::Volume, String] volume object or the volume id of volume to mount
         # @param [String] device name of the device /dev/xvd[a-p]  (optional)
         # @return [Fog::Compute::RackspaceV2::Attachment] resulting attachment object
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Attach_Volume_to_Server.html
         def attach_volume(volume, device=nil)
           requires :identity
@@ -311,17 +343,22 @@ module Fog
         # @param [String] ready_state By default state is ACTIVE
         # @param [Array,String] error_states By default state is ERROR
         # @return [Boolean] returns true if server is in a ready state
-        # @raise [RuntimeException] if server state is an error state
+        # @raise [Fog::Compute::RackspaceV2::InvalidServerStateException] if server state is an error state
         def ready?(ready_state = ACTIVE, error_states=[ERROR])
           if error_states
             error_states = Array(error_states)
-            raise "Server should have transitioned to '#{ready_state}' not '#{state}'" if error_states.include?(state)
+            raise InvalidServerStateException.new(ready_state, state) if error_states.include?(state)
           end
           state == ready_state
         end
 
         # Reboot server
         # @param [String<SOFT, HARD>] type 'SOFT' will do a soft reboot. 'HARD' will do a hard reboot.
+        # @return [Boolean] returns true if server is being rebooted
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Reboot_Server-d1e3371.html
         #
         # * State transition:
@@ -338,6 +375,10 @@ module Fog
         # Rebuild removes all data on the server and replaces it with the specified image. The id and all IP addresses remain the same.
         # @param [String] image_id image to use for rebuild
         # @return [Boolean] returns true if rebuild is in process
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Rebuild_Server-d1e3538.html
         #
         # * Status Transition:
@@ -351,12 +392,16 @@ module Fog
         end
 
         # Resize existing server to a different flavor, in essence, scaling the server up or down. The original server is saved for a period of time to allow rollback if there is a problem. All resizes should be tested and explicitly confirmed, at which time the original server is removed. All resizes are automatically confirmed after 24 hours if they are not confirmed or reverted.     
-        # @param [String] flavor to resize 
+        # @param [String] flavor_id to resize
         # @return [Boolean] returns true if resize is in process
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Resize_Server-d1e3707.html
         # @see #confirm_resize
-        # @see #revert_resize        
+        # @see #revert_resize
         #
         # * Status Transition:
         #   * ACTIVE -> QUEUE_RESIZE -> PREP_RESIZE -> VERIFY_RESIZE
@@ -369,13 +414,18 @@ module Fog
         end
 
         # Confirms server resize operation
+        # @return [Boolean] returns true if resize has been confirmed
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.        
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Confirm_Resized_Server-d1e3868.html
         # @see #resize
         #
         # * Status Transition:
         #   * VERIFY_RESIZE -> ACTIVE
-        #   * VERIFY_RESIZE -> ERROR (on error)        
+            #   * VERIFY_RESIZE -> ERROR (on error)å
         def confirm_resize
           requires :identity
           service.confirm_resize_server(identity)
@@ -383,9 +433,14 @@ module Fog
         end
 
         # Reverts server resize operation
-        # @note All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.        
+        # @return [Boolean] returns true if resize is being reverted
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note All resizes are automatically confirmed after 24 hours if you do not explicitly confirm or revert the resize.
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Revert_Resized_Server-d1e4024.html
-        # @see #resize                
+        # @see #resize
         #
         # * Status Transition:
         #   * VERIFY_RESIZE -> ACTIVE
@@ -399,6 +454,10 @@ module Fog
         # Change admin password
         # @param [String] password The administrator password.
         # @return [Boolean] returns true if operation was scheduled
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note Though Rackspace does not enforce complexity requirements for the password, the operating system might. If the password is not complex enough, the server might enter an ERROR state.
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Change_Password-d1e3234.html
         #

data/lib/fog/rackspace/models/compute_v2/servers.rb

@@ -10,7 +10,11 @@ module Fog
         model Fog::Compute::RackspaceV2::Server
 
         # Returns list of servers 
-        # @return [Array<Fog::Compute::RackspaceV2::Server>] Retrieves a list servers.
+        # @return [Fog::Compute::RackspaceV2::Servers] Retrieves a list servers.
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note Fog's current implementation only returns 1000 servers
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/List_Servers-d1e2078.html
         def all
@@ -19,6 +23,11 @@ module Fog
         end
 
         # Creates a new server and populates ssh keys
+        # @return [Fog::Compute::RackspaceV2::Server]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @note This method is incompatible with Cloud Servers utlizing RackConnect. RackConnect users 
         #     should use server personalization to install keys.  Please see Server#personality for more information.
         # @example
@@ -27,7 +36,8 @@ module Fog
         #                             :image_id => service.images.find {|img| img.name =~ /Ubuntu/}.id,
         #                             :public_key_path => '~/.ssh/fog_rsa.pub',
         #                             :private_key_path => '~/.ssh/fog_rsa'
-        #        
+        #
+        # @raise [Fog::Compute::RackspaceV2::InvalidServerStateException] if server state is an error state
         def bootstrap(new_attributes = {})
           server = create(new_attributes)
           server.wait_for(1500) { ready? && !public_ip_address.empty? }
@@ -38,6 +48,10 @@ module Fog
         # Retrieves server
         # @param [String] server_id for server to be returned
         # @return [Fog::Compute::RackspaceV2:Server]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         # @see http://docs.rackspace.com/servers/api/v2/cs-devguide/content/Get_Server_Details-d1e2623.html
         def get(server_id)
           data = service.get_server(server_id).body['server']

data/lib/fog/rackspace/models/dns/zones.rb

@@ -8,21 +8,17 @@ module Fog
 
         model Fog::DNS::Rackspace::Zone
 
+        # List all domains. Return by default a maximum of 100 items
+        # @param [Hash] options Options to pass to the underlying API call 
+        # @option options [String] :name search for domains containing the given substring
+        # @option options [Integer] :limit number of records to return
+        # @option options [Integer] :offset starting offset of records to return
         def all(options={})
           clear
           data = service.list_domains(options).body['domains']
           load(data)
         end
         
-        # Returns all domains containing the given substring. Still limited 
-        # by the 100-domain pagination limit. Returns an empty array if
-        # no matches.
-        def find(substring)
-          clear
-          data = service.list_domains(:name => substring).body['domains']
-          load(data)
-        end
-        
         alias :each_zone_this_page :each
         def each
           if !block_given?

data/lib/fog/rackspace/models/identity/service_catalog.rb

@@ -0,0 +1,83 @@
+require 'fog/core/model'
+
+module Fog
+  module Rackspace
+    class Identity
+      class ServiceCatalog < Fog::Model
+        attr_reader :catalog
+        
+        def initialize(attributes)
+          @service = attributes.delete(:service)
+          @catalog = {}
+        end
+        
+        def services
+          catalog.keys
+        end
+        
+        def get_endpoints(service_type)
+          service_type = service_type.is_a?(String) ? service_type.to_sym : service_type
+          catalog[service_type]
+        end
+        
+        def display_service_regions(service_type)
+          endpoints = get_endpoints(service_type)
+          endpoints.collect { |k,v| ":#{k}" }.join(", ")          
+        end
+        
+        def get_endpoint(service_type, region=nil)
+          endpoint = get_endpoints(service_type)
+          raise "Unable to locate endpoint for service #{service_type}" unless endpoint
+
+          return endpoint if endpoint.is_a?(String) #There is only one endpoint for service
+
+          unless region
+            raise "There are multiple endpoints avaliable for #{service_type}. Please specify one of the following regions: #{display_service_regions(service_type)}."
+          end
+          region = region.is_a?(String) ? region.to_sym : region
+          endpoint = get_endpoints(service_type)[region]
+          raise "Unknown region :#{region} for service #{service_type}. Please use one of the following regions: #{display_service_regions(service_type)}" unless endpoint
+          endpoint
+        end
+        
+        def reload
+          @service.authenticate
+          @catalog = @service.service_catalog.catalog
+          self
+        end
+                
+        def self.from_response(service, hash)
+          service_catalog = ServiceCatalog.new :service => service
+          services = hash["access"]["serviceCatalog"]
+          services.each do |serv|
+            name = serv["name"].to_sym
+            service_catalog.send(:add_endpoints, name, serv)
+          end
+          service_catalog
+        end
+
+        private
+        
+        def add_endpoints(service_name, hash)
+          endpoints = hash["endpoints"]
+          if endpoints.size == 1
+            catalog[service_name] = endpoints[0]["publicURL"].freeze
+          else
+            catalog[service_name] = endpoints_from_array(endpoints)
+          end
+        end
+        
+        def endpoints_from_array(endpoints)
+          hash = {}
+          endpoints.each do |endpoint|
+            region = endpoint["region"].downcase.to_sym
+            url = endpoint["publicURL"].freeze
+            hash[region] = url
+          end
+          hash
+        end
+        
+      end
+    end
+  end
+end

data/lib/fog/rackspace/models/storage/account.rb

@@ -4,16 +4,42 @@ module Fog
   module Storage
     class Rackspace
       class Account < Fog::Model
+        # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/View_Account_Info-d1e11995.html
+
+        # @!attribute [rw] meta_temp_url_key
+        # @return [String] The temporary URL key used to generate temporary access to files
+        # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/Create_TempURL-d1a444.html
         attribute :meta_temp_url_key, :aliases => 'X-Account-Meta-Temp-Url-Key'
+
+        # @!attribute [r] container_count
+        # @return [Integer] The number of containers in account
         attribute :container_count, :aliases => 'X-Account-Container-Count', :type => :integer
+
+        # @!attribute [r] bytes_used
+        # @return [Integer] The total number of bytes used by the account
         attribute :bytes_used, :aliases => 'X-Account-Bytes-Used', :type => :integer
+
+        # @!attribute [r] object_count
+        # @return [Integer] The total number of objects in the account
         attribute :object_count, :aliases => 'X-Account-Object-Count', :type => :integer        
         
+        # Saves account settings (meta_temp_url_key)
+        # @return [Boolean] returns true if successfully updated
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def save
           service.post_set_meta_temp_url_key meta_temp_url_key
           true
         end
         
+        # Reload account with latest data from Cloud Files
+        # @return [Fog::Storage::Rackspace::Account] returns itself
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
         def reload
           response = service.head_containers
           merge_attributes response.headers

data/lib/fog/rackspace/models/storage/directories.rb

@@ -9,15 +9,35 @@ module Fog
 
         model Fog::Storage::Rackspace::Directory
 
+        # Returns list of directories
+        # @return [Fog::Storage::Rackspace::Directories] Retrieves a list directories.
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @note Fog's current implementation only returns 10,000 directories
+        # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/View_List_of_Containers-d1e1100.html
         def all
           data = service.get_containers.body
           load(data)
         end
 
-        # Supply the :cdn_cname option to use the Rackspace CDN CNAME functionality on the public_url.
+        # Retrieves directory
+        # @param [String] key  of directory
+        # @param options [Hash]:
+        # @option options [String] cdn_cname CDN CNAME used when calling Directory#public_url
+        # @return [Fog::Storage::Rackspace::Directory]
+        # @raise [Fog::Rackspace::Errors::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Errors::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Errors::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Errors::ServiceError]
+        # @example
+        #   directory = fog.directories.get('video', :cdn_cname => 'http://cdn.lunenburg.org')
+        #   files = directory.files
+        #   files.first.public_url
         #
-        # > fog.directories.get('video', :cdn_cname => 'http://cdn.lunenburg.org').files.first.public_url
-        # => 'http://cdn.lunenburg.org/hayley-dancing.mov'
+        # @see Directory#public_url
+        # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/View-Container_Info-d1e1285.html
         def get(key, options = {})
           data = service.get_container(key, options)
           directory = new(:key => key, :cdn_cname => options[:cdn_cname])