fog 1.18.0 → 1.19.0

data/lib/fog/rackspace/models/queues/claim.rb

@@ -5,13 +5,42 @@ module Fog
     class Queues
       class Claim < Fog::Model
 
+        # @!attribute [r] identity
+        # @return [String] The claim's id
         identity :identity
 
+        # @!attribute [rw] grace
+        # @return [Integer] The grace attribute specifies the message grace period in seconds. The value of grace value must be between 60 and 43200 seconds (12 hours).
+        #   You must include a value for this attribute in your request. To deal with workers that have stopped responding (for up to 1209600 seconds or 14 days, including
+        #   claim lifetime), the server extends the lifetime of claimed messages to be at least as long as the lifetime of the claim itself, plus the specified grace period.
+        #   If a claimed message would normally live longer than the grace period, its expiration is not adjusted.
         attribute :grace
+
+        # @!attribute [rw] ttl
+        # @return [Integer] The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
         attribute :ttl
+
+        # @!attribute [rw] limit
+        # @return [Integer] Specifies the number of messages to return, up to 20 messages. If limit is not specified, limit defaults to 10.
         attribute :limit
+
+        # @!attribute [r] limit
+        # @return [Array<Fog::Rackspace::Queues::Messages>, Array<Strings>] Specifies the number of messages to return, up to 20 messages.
+        #   If limit is not specified, limit defaults to 10.
         attribute :messages
 
+        alias :id :identity
+
+        # Creates or updates a claim
+        #
+        # @return [Boolean] returns true if claim is being created
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_claimMessages__version__queues__queue_name__claims_claims-operations-dle001.html
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/PATCH_updateClaim__version__queues__queue_name__claims__claimId__claims-operations-dle001.html
         def save
           if identity.nil?
             create
@@ -20,6 +49,15 @@ module Fog
           end
         end
 
+        # Destroys Claim
+        #
+        # @return [Boolean] returns true if claim is deleted
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/DELETE_deleteClaim__version__queues__queue_name__claims__claimId__claims-operations-dle001.html
         def destroy
           requires :identity, :queue
           service.delete_claim(queue.name, identity)
@@ -42,12 +80,14 @@ module Fog
             })
           attributes[:messages] = messages.collect do |message|
             if message.instance_of? Fog::Rackspace::Queues::Message
+              message.claim_id = self.id
               message
             else
               Fog::Rackspace::Queues::Message.new(
                 message.merge({
                   :service => service,
-                  :collection => message_collection
+                  :collection => message_collection,
+                  :claim_id => self.id
                 }.merge(message))
               )
             end

data/lib/fog/rackspace/models/queues/claims.rb

@@ -8,12 +8,29 @@ module Fog
 
         model Fog::Rackspace::Queues::Claim
 
+        # @!attribute [rw] queue
+        # @return [String] The queue associated with the claim collection
         attr_accessor :queue
 
+        # Returns list of claims
+        # @note The Rackspace Cloud does not currently provide a way to retrieve claims as such this list is maintained by fog. Claims are added to the claim collection
+        # as they are created.
+        # @return [Fog::Rackspace::Queues::Claims] Retrieves a collection of claims.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
         def all
           self
         end
 
+        # This operation claims a set of messages (up to the value of the limit parameter) from oldest to newest and skips any messages that are already claimed.
+        # @return [Fog::Rackspace::Queues::Claim] Returns a claim
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_claimMessages__version__queues__queue_name__claims_claims-operations-dle001.html
         def create(attributes = {})
           object = new(attributes)
           if object.save
@@ -23,6 +40,14 @@ module Fog
           end
         end
 
+        # This operation queries the specified claim for the specified queue. Claims with malformed IDs or claims that are not found by ID are ignored.
+        #
+        # @param [Integer] claim_id Specifies the claim ID.
+        # @return [Fog::Rackspace::Queues::Claim] Returns a claim
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/GET_queryClaim__version__queues__queue_name__claims__claimId__claims-operations-dle001.html
         def get(claim_id)
           requires :queue
           data = service.get_claim(queue.identity, claim_id).body

data/lib/fog/rackspace/models/queues/message.rb

@@ -5,20 +5,49 @@ module Fog
     class Queues
       class Message < Fog::Model
 
+        # @!attribute [r] age
+        # @return [Integer] The number of seconds relative to the server's clock.
         attribute :age
+
+        # @!attribute [rw] ttl
+        # @return [Integer] specifies how long the server waits before marking the message as expired and removing it from the queue.
+        # @note The value of ttl must be between 60 and 1209600 seconds (14 days). Note that the server might not actually delete the message until its
+        # age has reached up to (ttl + 60) seconds, to allow for flexibility in storage implementations.
         attribute :ttl
+
+        # @!attribute [rw] body
+        # @return [String, Hash, Array] specifies an arbitrary document that constitutes the body of the message being sent. The size of this body is limited to 256 KB, excluding whitespace. The document must be valid JSON.
         attribute :body
+
+        # @!attribute [r] href
+        # @return [String] location of the message
         attribute :href
+
+        # @!attribute [r] claim_id
+        # @return [String] the id of the claim
         attribute :claim_id
 
+        # @!attribute [r] identity
+        # @return [String] The messages identity
         def identity
-          if href
-            href.split('/').last
-          else
-            nil
-          end
+          return nil unless href
+
+          match = href.match(/(\/(\w+))*\??/)
+          match ? match[-1] : nil
         end
+        alias :id :identity
 
+        # Creates messages
+        # Requires queue, client_id, body, and ttl attributes to be populated
+        # @note messages cannot be updated
+        #
+        # @return [Boolean] returns true if message has been succesfully saved
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_postMessage__version__queues__queue_name__messages_message-operations-dle001.html
         def save
           requires :queue, :client_id, :body, :ttl
           raise "Message has already been created and may not be updated." unless identity.nil?
@@ -27,6 +56,15 @@ module Fog
           true
         end
 
+        # Destroys Message
+        #
+        # @return [Boolean] returns true if message is deleted
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/DELETE_deleteMessage__version__queues__queue_name__messages__messageId__message-operations-dle001.html
         def destroy
           requires :identity, :queue
           options = {}

data/lib/fog/rackspace/models/queues/messages.rb

@@ -8,13 +8,43 @@ module Fog
 
         model Fog::Rackspace::Queues::Message
 
+        # @!attribute [r] client_id
+        # @return [String] UUID for the client instance.
         attr_accessor :client_id
+
+        # @!attribute [r] queue
+        # @return [String] The name of the queue associated with the message.
         attr_accessor :queue
+
+        # @!attribute [rw] echo
+        # @return [Boolean] Determines whether the API returns a client's own messages. The echo parameter is a Boolean value (true or false) that determines whether the API
+        #   returns a client's own messages, as determined by the uuid portion of the User-Agent header. If you do not specify a value, echo uses the default value of false.
+        #   If you are experimenting with the API, you might want to set echo=true in order to see the messages that you posted.
         attr_accessor :echo
+
+        # @!attribute [rw] limit
+        # @return [String]  When more messages are available than can be returned in a single request, the client can pick up the next batch of messages by simply using the URI
+        #   template parameters returned from the previous call in the "next" field. Specifies up to 10 messages (the default value) to return. If you do not specify a value
+        #   for the limit parameter, the default value of 10 is used.
         attr_accessor :limit
+
+        # @!attribute [rw] marker
+        # @return [String] Specifies an opaque string that the client can use to request the next batch of messages. The marker parameter communicates to the server which
+        #   messages the client has already received. If you do not specify a value, the API returns all messages at the head of the queue (up to the limit).
         attr_accessor :marker
+
+        # @!attribute [rw] include_claimed
+        # @return [String]  Determines whether the API returns claimed messages and unclaimed messages. The include_claimed parameter is a Boolean value (true or false)
+        #   that determines whether the API returns claimed messages and unclaimed messages. If you do not specify a value, include_claimed uses the default value of false
+        #   (only unclaimed messages are returned).
         attr_accessor :include_claimed
 
+        # Returns list of messages
+        #
+        # @return [Fog::Rackspace::Queues::Messages] Retrieves a collection of messages.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
         def all
           requires :client_id, :queue
           response = service.list_messages(client_id, queue.name, options)
@@ -26,6 +56,13 @@ module Fog
           load(data)
         end
 
+        # Returns the specified message from the queue.
+        #
+        # @param [Integer] message_id id of the message to be retrieved
+        # @return [Fog::Rackspace::Queues::Claim] Returns a claim
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
         def get(message_id)
           requires :client_id, :queue
           data = service.get_message(client_id, queue.name, message_id).body

data/lib/fog/rackspace/models/queues/queue.rb

@@ -5,8 +5,17 @@ module Fog
     class Queues
       class Queue < Fog::Model
 
+        # @!attribute [rw] name
+        # @return [String] name of queue
         identity :name
 
+        # Returns list of messages in the queue
+        #
+        # @return [Fog::Rackspace::Queues::Messages] Retrieves a collection of messages.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/GET_getMessages__version__queues__queue_name__messages_message-operations-dle001.html
         def messages
           @messages ||= begin
             Fog::Rackspace::Queues::Messages.new({
@@ -18,10 +27,25 @@ module Fog
           end
         end
 
+        # Returns queue statistics, including how many messages are in the queue, categorized by status.
+        #
+        # @return [Hash] Retrieves a collection of messages.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/GET_getQueueStats__version__queues__queue_name__stats_queue-operations-dle001.html
         def stats
           service.get_queue_stats(name).body['messages']
         end
 
+        # Returns list of claims
+        # @note The Rackspace Cloud does not currently provide a way to retrieve claims as such this list is maintained by fog. Claims are added to the claim collection
+        # as they are created.
+        # @return [Fog::Rackspace::Queues::Claims] Retrieves a collection of claims.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
         def claims
           @claims ||= begin
             Fog::Rackspace::Queues::Claims.new({
@@ -31,12 +55,32 @@ module Fog
           end
         end
 
-        #Helper method to enqueue a single message
+        # Helper method to enqueue a single message
+        #
+        # @param [String, Hash, Array] body The body attribute specifies an arbitrary document that constitutes the body of the message being sent. The size of this body is limited to 256 KB, excluding whitespace. The document must be valid JSON.
+        # @param [Integer] ttl The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+        # @param [Hash] options
+        # @return [Boolean] returns true if message has been succesfully enqueued
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_postMessage__version__queues__queue_name__messages_message-operations-dle001.html
         def enqueue(body, ttl, options = {})
-          messages.create(options.merge(options.merge({:body => body, :ttl => ttl})))
+          messages.create(options.merge({:body => body, :ttl => ttl}))
         end
 
-        #Helper method to claim (dequeue) a single message, including destroying it
+        # Helper method to claim (dequeue) a single message, yield the message, and then destroy it
+        #
+        # @param [Integer] ttl The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+        # @param [Integer] grace The grace attribute specifies the message grace period in seconds. The value of grace value must be between 60 and 43200 seconds (12 hours).
+        # @param [Hash] options
+        # @yieldparam message claimed [Fog::Rackspace::Queues::Message]
+        # @return [Boolean] Returns true if claim was successfully made
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
         def dequeue(ttl, grace, options = {}, &block)
           claim = claims.create(
             options.merge(
@@ -56,12 +100,31 @@ module Fog
           end
         end
 
+        # Creates queue
+        # Requires name attribute to be populated
+        #
+        # @return [Boolean] returns true if queue has been succesfully saved
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_postMessage__version__queues__queue_name__messages_message-operations-dle001.html
         def save
           requires :name
           data = service.create_queue(name)
           true
         end
 
+        # Destroys queue
+        #
+        # @return [Boolean] returns true if queue is deleted
+        #
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/DELETE_deleteQueue__version__queues__queue_name__queue-operations-dle001.html
         def destroy
           requires :name
           service.delete_queue(name)

data/lib/fog/rackspace/models/queues/queues.rb

@@ -8,6 +8,13 @@ module Fog
 
         model Fog::Rackspace::Queues::Queue
 
+        # Returns list of queues
+        #
+        # @return [Fog::Rackspace::Queues::Queues] Retrieves a collection of queues.
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/GET_listQueues__version__queues_.html
         def all
           response = service.list_queues
           if service.list_queues.status == 204
@@ -18,6 +25,14 @@ module Fog
           load(data)
         end
 
+        # This operation queries the specified queue.
+        #
+        # @param [String] queue_name Specifies the queue name
+        # @return [Fog::Rackspace::Queues::Queue] Returns a queue
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/GET_checkQueueExists__version__queues__queue_name__queue-operations-dle001.html
         def get(queue_name)
           #204 no content is returned on success.  That's why no data is passed 
           # from the GET to the constructor.

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

@@ -42,6 +42,11 @@ module Fog
         # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/CORS_Container_Header-d1e1300.html
         attribute :origin,          :aliases => ['Origin']
 
+        # @!attribute [rw] content_encoding
+        # @return [String] The content encoding of the file
+        # @see http://docs.rackspace.com/files/api/v1/cf-devguide/content/Enabling_File_Compression_with_the_Content-Encoding_Header-d1e2198.html
+        attribute :content_encoding, :aliases => 'Content-Encoding'
+
         # @!attribute [r] directory
         # @return [Fog::Storage::Rackspace::Directory] directory containing file
         attr_accessor :directory
@@ -87,6 +92,7 @@ module Fog
           options['Content-Type'] ||= content_type if content_type
           options['Access-Control-Allow-Origin'] ||= access_control_allow_origin if access_control_allow_origin
           options['Origin'] ||= origin if origin
+          options['Content-Encoding'] ||= content_encoding if content_encoding
           service.copy_object(directory.key, key, target_directory_key, target_file_key, options)
           target_directory = service.directories.new(:key => target_directory_key)
           target_directory.files.get(target_file_key)
@@ -133,7 +139,7 @@ module Fog
         end
 
         # Set last modified
-        # @param [String, Fog::Time] timestamp
+        # @param [String, Fog::Time] obj
         def last_modified=(obj)
           if obj.nil? || obj == "" || obj.is_a?(Time)
             attributes[:last_modified] = obj
@@ -247,6 +253,7 @@ module Fog
           options['Origin'] = origin if origin
           options['Content-Disposition'] = content_disposition if content_disposition
           options['Etag'] = etag if etag
+          options['Content-Encoding'] = content_encoding if content_encoding
           options.merge!(metadata.to_headers)
 
           data = service.put_object(directory.key, key, body, options)

data/lib/fog/rackspace/requests/compute_v2/delete_keypair.rb

@@ -4,7 +4,7 @@ module Fog
       class Real
 
         # Delete the key specified with key_name
-        # @param  [String] key_name: name of the key to delete
+        # @param  [String] key_name name of the key to delete
         # @return [Excon::Response] response
         # @raise  [Fog::Compute::RackspaceV2::NotFound]
         # @raise  [Fog::Compute::RackspaceV2::BadRequest]

data/lib/fog/rackspace/requests/compute_v2/get_keypair.rb

@@ -4,7 +4,7 @@ module Fog
       class Real
 
         # Retreive single keypair details
-        # @param [String] key_name: name of the key for which to request the details
+        # @param [String] key_name name of the key for which to request the details
         # @return  [Excon::Response] response :
         #   * body [Hash]: -
         #     * 'keypair' [Hash]: -

data/lib/fog/rackspace/requests/queues/create_claim.rb

@@ -2,6 +2,21 @@ module Fog
   module Rackspace
     class Queues
       class Real
+
+        # This operation claims a set of messages (up to the value of the limit parameter) from oldest to newest and skips any messages that are already claimed.
+        # If no unclaimed messages are available, the API returns a 204 No Content message.
+        #
+        # @param [String] queue_name Specifies the name of the queue.
+        # @param [Integer] ttl The ttl attribute specifies how long the server waits before releasing the claim. The ttl value must be between 60 and 43200 seconds (12 hours).
+        # @param [Integer] grace The grace attribute specifies the message grace period in seconds. The value of grace value must be between 60 and 43200 seconds (12 hours).
+        # @param [Hash] options
+        # @option options [Integer] :limit - Specifies the number of messages to return, up to 20 messages. If limit is not specified, limit defaults to 10.
+        # @return [Excon::Response] response
+        # @raise [Fog::Rackspace::Queues::NotFound] - HTTP 404
+        # @raise [Fog::Rackspace::Queues::BadRequest] - HTTP 400
+        # @raise [Fog::Rackspace::Queues::InternalServerError] - HTTP 500
+        # @raise [Fog::Rackspace::Queues::ServiceError]
+        # @see http://docs.rackspace.com/queues/api/v1.0/cq-devguide/content/POST_claimMessages__version__queues__queue_name__claims_claims-operations-dle001.html
         def create_claim(queue_name, ttl, grace, options = {})
           body = {
             :ttl => ttl,