right_aws 1.10.0 → 2.0.0

data/lib/sdb/right_sdb_interface.rb

@@ -32,6 +32,7 @@ module RightAws
     DEFAULT_HOST      = 'sdb.amazonaws.com'
     DEFAULT_PORT      = 443
     DEFAULT_PROTOCOL  = 'https'
+    DEFAULT_PATH      = '/'
     API_VERSION       = '2007-11-07'
     DEFAULT_NIL_REPRESENTATION = 'nil'
 
@@ -47,7 +48,7 @@ module RightAws
     #    { :server       => 'sdb.amazonaws.com'  # Amazon service host: 'sdb.amazonaws.com'(default)
     #      :port         => 443                  # Amazon service port: 80 or 443(default)
     #      :protocol     => 'https'              # Amazon service protocol: 'http' or 'https'(default)
-    #      :signature_version => '0'             # The signature version : '0' or '1'(default)
+    #      :signature_version => '0'             # The signature version : '0','1 or '2'(default)
     #      :multi_thread => true|false           # Multi-threaded (connection per each thread): true or false(default)
     #      :logger       => Logger Object        # Logger instance: logs to STDOUT if omitted 
     #      :nil_representation => 'mynil'}       # interpret Ruby nil as this string value; i.e. use this string in SDB to represent Ruby nils (default is the string 'nil')
@@ -61,10 +62,12 @@ module RightAws
     def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
       @nil_rep = params[:nil_representation] ? params[:nil_representation] : DEFAULT_NIL_REPRESENTATION
       params.delete(:nil_representation)
-      init({ :name             => 'SDB', 
-             :default_host     => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).host   : DEFAULT_HOST, 
-             :default_port     => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).port   : DEFAULT_PORT, 
-             :default_protocol => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).scheme : DEFAULT_PROTOCOL }, 
+      init({ :name                => 'SDB',
+             :default_host        => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).host   : DEFAULT_HOST,
+             :default_port        => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).port   : DEFAULT_PORT,
+             :default_service     => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).path   : DEFAULT_PATH,
+             :default_protocol    => ENV['SDB_URL'] ? URI.parse(ENV['SDB_URL']).scheme : DEFAULT_PROTOCOL,
+             :default_api_version => ENV['SDB_API_VERSION'] || API_VERSION },
            aws_access_key_id     || ENV['AWS_ACCESS_KEY_ID'], 
            aws_secret_access_key || ENV['AWS_SECRET_ACCESS_KEY'], 
            params)
@@ -73,66 +76,55 @@ module RightAws
     #-----------------------------------------------------------------
     #      Requests
     #-----------------------------------------------------------------
+    
     def generate_request(action, params={}) #:nodoc:
-      # remove empty params from request
-      params.delete_if {|key,value| value.nil? }
-      #params_string  = params.to_a.collect{|key,val| key + "=#{CGI::escape(val.to_s)}" }.join("&")
-      # prepare service data
-      service = '/'
-      service_hash = {"Action"         => action,
-                      "AWSAccessKeyId" => @aws_access_key_id,
-                      "Version"        => API_VERSION }
-      service_hash.update(params)
-      service_params = signed_service_params(@aws_secret_access_key, service_hash, :get, @params[:server], service)
-      #
-      # use POST method if the length of the query string is too large
-      # see http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/MakingRESTRequests.html
-      if service_params.size > 2000
-        if signature_version == '2'
-          # resign the request because HTTP verb is included into signature
-          service_params = signed_service_params(@aws_secret_access_key, service_hash, :post, @params[:server], service)
-        end
-        request      = Net::HTTP::Post.new(service)
-        request.body = service_params
-        request['Content-Type'] = 'application/x-www-form-urlencoded'
-      else
-        request = Net::HTTP::Get.new("#{service}?#{service_params}")
-      end
-      # prepare output hash
-      { :request  => request, 
-        :server   => @params[:server],
-        :port     => @params[:port],
-        :protocol => @params[:protocol] }
+      generate_request_impl(:get, action, params )
     end
 
     # Sends request to Amazon and parses the response
     # Raises AwsError if any banana happened
     def request_info(request, parser)  #:nodoc:
-      thread = @params[:multi_thread] ? Thread.current : Thread.main
-      thread[:sdb_connection] ||= Rightscale::HttpConnection.new(:exception => AwsError, :logger => @logger)
-      request_info_impl(thread[:sdb_connection], @@bench, request, parser)
+      request_info_impl(:sdb_connection, @@bench, request, parser)
     end
 
     # Prepare attributes for putting.
     # (used by put_attributes)
-    def pack_attributes(attributes, replace = false) #:nodoc:
+    def pack_attributes(items_or_attributes, replace = false, batch = false) #:nodoc:
+      if batch
+        index = 0
+        items_or_attributes.inject({}){|result, (item_name, attributes)|
+          item_prefix = "Item.#{index}."
+          result["#{item_prefix}ItemName"] = item_name.to_s
+          result.merge!(
+            pack_single_item_attributes(attributes, replace, item_prefix))
+          index += 1
+          result
+        }
+      else
+        pack_single_item_attributes(items_or_attributes, replace)
+      end
+    end
+
+    def pack_single_item_attributes(attributes, replace, prefix = "")
       result = {}
       if attributes
         idx = 0
         skip_values = attributes.is_a?(Array)
         attributes.each do |attribute, values|
           # set replacement attribute
-          result["Attribute.#{idx}.Replace"] = 'true' if replace
+          result["#{prefix}Attribute.#{idx}.Replace"] = 'true' if replace
           # pack Name/Value
           unless values.nil?
-            Array(values).each do |value|
-              result["Attribute.#{idx}.Name"]  = attribute
-              result["Attribute.#{idx}.Value"] = ruby_to_sdb(value) unless skip_values
+            # Array(values) does not work here:
+            #  - Array('') => [] but we wanna get here ['']
+            [values].flatten.each do |value|
+              result["#{prefix}Attribute.#{idx}.Name"]  = attribute
+              result["#{prefix}Attribute.#{idx}.Value"] = ruby_to_sdb(value) unless skip_values
               idx += 1
             end
           else
-            result["Attribute.#{idx}.Name"] = attribute
-            result["Attribute.#{idx}.Value"] = ruby_to_sdb(nil) unless skip_values
+            result["#{prefix}Attribute.#{idx}.Name"] = attribute
+            result["#{prefix}Attribute.#{idx}.Value"] = ruby_to_sdb(nil) unless skip_values
             idx += 1
           end
         end
@@ -333,6 +325,37 @@ module RightAws
     rescue Exception
       on_exception
     end
+
+    # Add/Replace attributes for multiple items at a time.
+    #
+    # Params:
+    #   domain_name = DomainName
+    #   items       = {
+    #     'Item1' => {
+    #       'nameA'  => [valueA1, valueA2,..., valueAN],
+    #       ...
+    #       'nameB'  => [valueB1, valueB2,..., valueBN]
+    #     },
+    #     'Item2' => {
+    #       'nameC'  => [valueC1, valueC2,..., valueCN],
+    #       ...
+    #       'nameD'  => [valueD1, valueD2,..., valueDN]
+    #     }
+    #   }
+    #   replace = :replace | any other value to skip replacement
+    #
+    # Usage of batch_put_attributes is similar to put_attributes except that
+    # instead of supplying an item_name and a hash of attributes, you supply a
+    # hash of item names to attributes.
+    #
+    # See: http://docs.amazonwebservices.com/AmazonSimpleDB/latest/DeveloperGuide/index.html?SDB_API_BatchPutAttributes.html
+    def batch_put_attributes(domain_name, items, replace = false)
+      params = { 'DomainName' => domain_name }.merge(pack_attributes(items, replace, true))
+      link = generate_request("BatchPutAttributes", params)
+      request_info( link, QSdbSimpleParser.new)
+    rescue Exception
+      on_exception
+    end
     
     # Retrieve SDB item's attribute(s).
     # 
@@ -502,7 +525,7 @@ module RightAws
     # see: http://docs.amazonwebservices.com/AmazonSimpleDB/2007-11-07/DeveloperGuide/index.html?SDB_API_QueryWithAttributes.html
     #
     def query_with_attributes(domain_name, attributes=[], query_expression = nil, max_number_of_items = nil, next_token = nil)
-      attributes = attributes.to_a
+      attributes = Array(attributes)
       query_expression = query_expression_from_array(query_expression) if query_expression.is_a?(Array)
       @last_query_expression = query_expression
       #

data/lib/sqs/right_sqs_gen2.rb

@@ -136,7 +136,7 @@ module RightAws
         #  queue.clear() #=> true
         #
       def clear()
-          @sqs.interface.clear_queue(@url)
+        @sqs.interface.clear_queue(@url)
       end
       
         # Deletes queue.  Any messages in the queue will be permanently lost. 
@@ -167,11 +167,10 @@ module RightAws
         #
         #  queue.receive_messages(2,10) #=> array of messages
         #
-      def receive_messages(number_of_messages=1, visibility=nil)
-        list = @sqs.interface.receive_message(@url, number_of_messages, visibility)
+      def receive_messages(number_of_messages=1, visibility=nil, attributes=nil)
+        list = @sqs.interface.receive_message(@url, number_of_messages, visibility, attributes)
         list.map! do |entry|
-          msg = Message.new(self, entry['MessageId'], entry['ReceiptHandle'],
-                            entry['Body'], visibility)
+          msg = Message.new(self, entry['MessageId'], entry['ReceiptHandle'], entry['Body'], visibility, entry['Attributes'])
           msg.received_at = Time.now 
           msg.receive_checksum = entry['MD5OfBody']
           msg
@@ -183,8 +182,8 @@ module RightAws
         #
         #  queue.receive #=> #<RightAws::SqsGen2::Message:0xb7bf0884 ... >
         #
-      def receive(visibility=nil)
-        list = receive_messages(1, visibility)
+      def receive(visibility=nil, attributes=nil)
+        list = receive_messages(1, visibility, attributes)
         list.empty? ? nil : list[0]
       end
 
@@ -193,12 +192,15 @@ module RightAws
         #
         #  queue.pop #=> #<RightAws::SqsGen2::Message:0xb7bf0884 ... >
         #
-      def pop
-        list = @sqs.interface.pop_messages(@url, 1)
+        #  # pop a message with custom attributes
+        #  m = queue.pop(['SenderId', 'SentTimestamp']) #=> #<RightAws::SqsGen2::Message:0xb7bf1884 ... >
+        #  m.attributes #=> {"SentTimestamp"=>"1240991906937", "SenderId"=>"800000000005"}
+        #
+      def pop(attributes=nil)
+        list = @sqs.interface.pop_messages(@url, 1, attributes)
         return nil if list.empty?
         entry = list[0]
-        msg = Message.new(self, entry['MessageId'], entry['ReceiptHandle'],
-                            entry['Body'], visibility)
+        msg = Message.new(self, entry['MessageId'], entry['ReceiptHandle'], entry['Body'], visibility, entry['Attributes'])
         msg.received_at = Time.now 
         msg.receive_checksum = entry['MD5OfBody']
         msg
@@ -241,27 +243,77 @@ module RightAws
       end
         
         # Retrieves queue attributes. 
-        # At this moment Amazon supports +VisibilityTimeout+ and +ApproximateNumberOfMessages+ only. 
         # If the name of attribute is set, returns its value. Otherwise, returns a hash of attributes.
         #
         # queue.get_attribute('VisibilityTimeout')  #=> {"VisibilityTimeout"=>"45"} 
         #
+        # P.S. This guy is deprecated. Use +get_attributes+ instead.
       def get_attribute(attribute='All')
-        attributes = @sqs.interface.get_queue_attributes(@url, attribute)
+        attributes = get_attributes(attribute)
         attribute=='All' ? attributes : attributes[attribute]
       end
+
+      # Retrieves queue attributes.
+      #
+      #  queue.get_attributes #=>
+      #    {"ApproximateNumberOfMessages" => "0",
+      #     "LastModifiedTimestamp"       => "1240946032",
+      #     "CreatedTimestamp"            => "1240816887",
+      #     "VisibilityTimeout"           => "30",
+      #     "Policy"                      => "{"Version":"2008-10-17","Id":...}"}
+      #
+      #  queue.get_attributes("LastModifiedTimestamp", "VisibilityTimeout") #=>
+      #    {"LastModifiedTimestamp" => "1240946032",
+      #     "VisibilityTimeout"     => "30"}
+      #
+      def get_attributes(*attributes)
+        @sqs.interface.get_queue_attributes(@url, attributes)
+      end
+
+      # Add permission to the queue.
+      #
+      #  queue.add_permissions('testLabel',['125074342641', '125074342642'],
+      #                        ['SendMessage','SendMessage','ReceiveMessage']) #=> true
+      #
+      def add_permissions(label, grantees, actions)
+        @sqs.interface.add_permissions(@url, label, grantees, actions)
+      end
+
+      # Revoke any permissions in the queue policy that matches the +label+ parameter.
+      #
+      #  sqs.remove_permissions('testLabel') # => true
+      #
+      def remove_permissions(label)
+        @sqs.interface.remove_permissions(@url, label)
+      end
+
+      # Get current permissions set. The set is JSON packed.
+      # 
+      #  sqs.get_permissions #=>
+      #    '{"Version":"2008-10-17","Id":"/826693181925/kd-test-gen-2_5/SQSDefaultPolicy",
+      #      "Statement":[{"Sid":"kd-perm-04","Effect":"Allow","Principal":{"AWS":"100000000001",
+      #      "AWS":"100000000001","AWS":"100000000002"},"Action":["SQS:SendMessage","SQS:DeleteMessage",
+      #      "SQS:ReceiveMessage"],"Resource":"/826693181925/kd-test-gen-2_5"},{"Sid":"kd-perm-03",
+      #      "Effect":"Allow","Principal":{"AWS":"648772224137"},"Action":"SQS:SendMessage",
+      #      "Resource":"/826693181925/kd-test-gen-2_5"}]}'
+      #
+      def get_permissions
+        get_attributes('Policy')['Policy']
+      end
+      
     end
         
     class Message
-      attr_reader   :queue, :id, :body, :visibility, :receipt_handle
+      attr_reader   :queue, :id, :body, :visibility, :receipt_handle, :attributes
       attr_accessor :sent_at, :received_at, :send_checksum, :receive_checksum
       
-      def initialize(queue, id=nil, rh = nil, body=nil, visibility=nil)
+      def initialize(queue, id=nil, rh = nil, body=nil, visibility=nil, attributes=nil)
         @queue       = queue
         @id          = id
         @receipt_handle = rh 
         @body        = body
         @visibility  = visibility
+        @attributes  = attributes
         @sent_at     = nil
         @received_at = nil
         @send_checksum = nil
@@ -273,6 +325,12 @@ module RightAws
         @body
       end
 
+      # Set message visibility timeout.
+      def visibility=(visibility_timeout)
+        @queue.sqs.interface.change_message_visibility(@queue.url, @receipt_handle, visibility_timeout)
+        @visibility = visibility_timeout
+      end
+
         # Removes message from queue. 
         # Returns +true+.
       def delete
@@ -281,6 +339,5 @@ module RightAws
 
     end
 
-
   end
 end

data/lib/sqs/right_sqs_gen2_interface.rb

@@ -38,7 +38,7 @@ module RightAws
   class SqsGen2Interface < RightAwsBase
     include RightAwsBaseInterface
     
-    API_VERSION       = "2008-01-01"
+    API_VERSION       = "2009-02-01"
     DEFAULT_HOST      = "queue.amazonaws.com"
     DEFAULT_PORT      = 443
     DEFAULT_PROTOCOL  = 'https'
@@ -72,7 +72,7 @@ module RightAws
     #    {:server       => 'queue.amazonaws.com' # Amazon service host: 'queue.amazonaws.com' (default)
     #     :port         => 443                   # Amazon service port: 80 or 443 (default)
     #     :multi_thread => true|false            # Multi-threaded (connection per each thread): true or false (default)
-    #     :signature_version => '0'              # The signature version : '0' or '1'(default)
+    #     :signature_version => '0'              # The signature version : '0', '1' or '2'(default)
     #     :logger       => Logger Object}        # Logger instance: logs to STDOUT if omitted }
     #
     def initialize(aws_access_key_id=nil, aws_secret_access_key=nil, params={})
@@ -127,7 +127,7 @@ module RightAws
       #
       service_params = signed_service_params(@aws_secret_access_key, service_hash, :post, @params[:server], service)
       request        = Net::HTTP::Post.new(AwsUtils::URLencode(service))
-      request['Content-Type'] = 'application/x-www-form-urlencoded' 
+      request['Content-Type'] = 'application/x-www-form-urlencoded; charset=utf-8'
       request.body = service_params
         # prepare output hash
       { :request  => request, 
@@ -140,15 +140,12 @@ module RightAws
       # Sends request to Amazon and parses the response
       # Raises AwsError if any banana happened
     def request_info(request, parser) # :nodoc:
-      thread = @params[:multi_thread] ? Thread.current : Thread.main
-      thread[:sqs_connection] ||= Rightscale::HttpConnection.new(:exception => AwsError, :logger => @logger)
-      request_info_impl(thread[:sqs_connection], @@bench, request, parser)
+      request_info_impl(:sqs_connection, @@bench, request, parser)
     end
 
-
       # Creates a new queue, returning its URI.
       #
-      #  sqs.create_queue('my_awesome_queue') #=> 'http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
+      #  sqs.create_queue('my_awesome_queue') #=> 'https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
       #
     def create_queue(queue_name, default_visibility_timeout=nil)
       req_hash = generate_request('CreateQueue', 'QueueName' => queue_name,
@@ -164,7 +161,7 @@ module RightAws
      #
      #  sqs.create_queue('my_awesome_queue')
      #  sqs.create_queue('my_awesome_queue_2')
-     #  sqs.list_queues('my_awesome') #=> ['http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue','http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2']
+     #  sqs.list_queues('my_awesome') #=> ['https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue','https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2']
      #
     def list_queues(queue_name_prefix=nil)
       req_hash = generate_request('ListQueues', 'QueueNamePrefix' => queue_name_prefix)
@@ -179,11 +176,10 @@ module RightAws
       # may still show the deleted queue.  It is not unusual within the 60 s window to see the deleted queue absent from 
       # one list_queues call but present in the subsequent one.  Deletion is eventual.
       #
-      #  sqs.delete_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2') #=> true
-      # 
+      #  sqs.delete_queue('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2') #=> true
       # 
     def delete_queue(queue_url)
-      req_hash = generate_request('DeleteQueue', :queue_url      => queue_url)
+      req_hash = generate_request('DeleteQueue', :queue_url => queue_url)
       request_info(req_hash, SqsStatusParser.new(:logger => @logger))
     rescue
       on_exception
@@ -191,11 +187,24 @@ module RightAws
 
       # Retrieves the queue attribute(s). Returns a hash of attribute(s) or an exception.
       #
-      #  sqs.get_queue_attributes('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') 
-      #  #=> {"ApproximateNumberOfMessages"=>"0", "VisibilityTimeout"=>"30"}
-      #
-    def get_queue_attributes(queue_url, attribute='All')
-      req_hash = generate_request('GetQueueAttributes', 'AttributeName' => attribute, :queue_url  => queue_url)
+      #  sqs.get_queue_attributes('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=>
+      #    {"ApproximateNumberOfMessages" => "0",
+      #     "LastModifiedTimestamp"       => "1240946032",
+      #     "CreatedTimestamp"            => "1240816887",
+      #     "VisibilityTimeout"           => "30",
+      #     "Policy"                      => "{"Version":"2008-10-17","Id":...}"}
+      #     
+      #  queue.get_queue_attributes('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', "LastModifiedTimestamp", "VisibilityTimeout") #=>
+      #    {"LastModifiedTimestamp" => "1240946032",
+      #     "VisibilityTimeout"     => "30"}
+      #
+      # http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?Query_QueryGetQueueAttributes.html
+    def get_queue_attributes(queue_url, *attributes)
+      attributes.flatten!
+      attributes << 'All' if attributes.blank?
+      params = amazonize_list('AttributeName', attributes)
+      params.merge!(:queue_url  => queue_url)
+      req_hash = generate_request('GetQueueAttributes', params)
       request_info(req_hash, SqsGetQueueAttributesParser.new(:logger => @logger))
     rescue
       on_exception
@@ -203,48 +212,108 @@ module RightAws
 
       # Sets queue attribute. Returns +true+ or an exception.
       #
-      #  sqs.set_queue_attributes('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', "VisibilityTimeout", 10) #=> true
+      #  sqs.set_queue_attributes('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', "VisibilityTimeout", 10) #=> true
       #
       # From the SQS Dev Guide:
-      # "Currently, you can set only the 
-      # VisibilityTimeout attribute for a queue... 
-      # When you change a queue's attributes, the change can take up to 60 seconds to propagate 
+      # "When you change a queue's attributes, the change can take up to 60 seconds to propagate 
       # throughout the SQS system."
       #
       # NB: Attribute values may not be immediately available to other queries
       # for some time after an update. See the SQS documentation for
       # semantics, but in general propagation can take up to 60 s.
+      # 
+      #  see http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?Query_QuerySetQueueAttributes.html
     def set_queue_attributes(queue_url, attribute, value)
-      req_hash = generate_request('SetQueueAttributes', 'Attribute.Name'  => attribute, 'Attribute.Value' => value, :queue_url  => queue_url)
+      req_hash = generate_request('SetQueueAttributes', 
+                                  'Attribute.Name'  => attribute,
+                                  'Attribute.Value' => value,
+                                  :queue_url        => queue_url)
+      request_info(req_hash, SqsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+    # Add permissions to a queue.
+    #
+    #  sqs.add_permissions('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue',
+    #                     'testLabel', ['125074342641','125074342642'],
+    #                     ['SendMessage','SendMessage','ReceiveMessage']) #=> true
+    #
+    #  +permissions+ is a hash of: AccountId => ActionName
+    #  (valid ActionNames: * | SendMessage | ReceiveMessage | DeleteMessage | ChangeMessageVisibility | GetQueueAttributes )
+    #
+    #  see http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?Query_QueryAddPermission.html
+    #      http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?acp-overview.html
+    def add_permissions(queue_url, label, grantees, actions)
+      params      = amazonize_list('AWSAccountId', Array(grantees))
+      params.merge!(amazonize_list('ActionName', Array(actions)))
+      params.merge!('Label'    => label,
+                    :queue_url => queue_url )
+      req_hash = generate_request('AddPermission', params)
+      request_info(req_hash, SqsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
+
+    # Revoke any permissions in the queue policy that matches the +label+ parameter.
+    #
+    #  sqs.remove_permissions('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue',
+    #                        'testLabel') # => true
+    #
+    #  see http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?Query_QueryRemovePermission.html
+    def remove_permissions(queue_url, label)
+      req_hash = generate_request('RemovePermission',
+                                  'Label'    => label,
+                                  :queue_url => queue_url )
       request_info(req_hash, SqsStatusParser.new(:logger => @logger))
     rescue
       on_exception
     end
 
-      # Retrieves a list of messages from queue. Returns an array of hashes in format: <tt>{:id=>'message_id', body=>'message_body'}</tt>
+      # Retrieves a list of messages from queue. Returns an array of hashes in format: <tt>{:id=>'message_id', :body=>'message_body'}</tt>
       #
-      #   sqs.receive_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue',10, 5) #=>
+      #   sqs.receive_message('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue',10, 5) #=>
       #    [{"ReceiptHandle"=>"Euvo62...kw==", "MD5OfBody"=>"16af2171b5b83cfa35ce254966ba81e3", 
       #      "Body"=>"Goodbyte World!", "MessageId"=>"MUM4WlAyR...pYOTA="}, ..., {}]
       #
       # Normally this call returns fewer messages than the maximum specified,
       # even if they are available.
       #
-    def receive_message(queue_url, max_number_of_messages=1, visibility_timeout=nil)
+    def receive_message(queue_url, max_number_of_messages=1, visibility_timeout=nil, attributes=nil)
       return [] if max_number_of_messages == 0
-      req_hash = generate_post_request('ReceiveMessage', 'MaxNumberOfMessages'  => max_number_of_messages, 'VisibilityTimeout' => visibility_timeout,
-                                       :queue_url          => queue_url )
+      params = {}
+      params.merge!(amazonize_list('AttributeName', Array(attributes))) unless attributes.blank?
+      params.merge!('MaxNumberOfMessages' => max_number_of_messages,
+                    'VisibilityTimeout'   => visibility_timeout,
+                    :queue_url            => queue_url )
+      req_hash = generate_post_request('ReceiveMessage', params)
       request_info(req_hash, SqsReceiveMessageParser.new(:logger => @logger))
     rescue
       on_exception
     end
+
+    # Change the visibility timeout of a specified message in a queue.
+    #
+    #  sqs.change_message_visibility('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'Euvo62...kw==', 33) #=> true
+    #
+    #  see http://docs.amazonwebservices.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/index.html?Query_QueryChangeMessageVisibility.html
+    def change_message_visibility(queue_url, receipt_handle, visibility_timeout)
+      req_hash = generate_request('ChangeMessageVisibility',
+                                  'ReceiptHandle'     => receipt_handle,
+                                  'VisibilityTimeout' => visibility_timeout,
+                                  :queue_url          => queue_url )
+      request_info(req_hash, SqsStatusParser.new(:logger => @logger))
+    rescue
+      on_exception
+    end
     
       # Sends a new message to a queue.  Message size is limited to 8 KB.
       # If successful, this call returns a hash containing key/value pairs for
       # "MessageId" and "MD5OfMessageBody":
       #
-      #  sqs.send_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'message_1') #=> "1234567890...0987654321"
-      #  => {"MessageId"=>"MEs4M0JKNlRCRTBBSENaMjROTk58QVFRNzNEREhDVFlFOVJDQ1JKNjF8UTdBRllCUlJUMjhKMUI1WDJSWDE=", "MD5OfMessageBody"=>"16af2171b5b83cfa35ce254966ba81e3"}
+      #  sqs.send_message('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'message_1') #=> 
+      #    {"MessageId"=>"MEs4M0JKNlRCRTBBSENaMjROTk58QVFRNzNEREhDVFlFOVJDQ1JKNjF8UTdBRllCUlJUMjhKMUI1WDJSWDE=",
+      #     "MD5OfMessageBody"=>"16af2171b5b83cfa35ce254966ba81e3"}
       #
       # On failure, send_message raises an exception.
       #
@@ -271,7 +340,7 @@ module RightAws
       # you again on a subsequent receive request. You should create your system to be 
       # idempotent so that receiving a particular message more than once is not a problem. "
       #
-      #  sqs.delete_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'Euvo62/1nlIet...ao03hd9Sa0w==') #=> true
+      #  sqs.delete_message('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'Euvo62/1nlIet...ao03hd9Sa0w==') #=> true
       #
     def delete_message(queue_url, receipt_handle)
       req_hash = generate_request('DeleteMessage', 'ReceiptHandle' => receipt_handle, :queue_url  => queue_url)
@@ -281,7 +350,7 @@ module RightAws
     end
     
       # Given the queue's short name, this call returns the queue URL or +nil+ if queue is not found
-      #  sqs.queue_url_by_name('my_awesome_queue') #=> 'http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
+      #  sqs.queue_url_by_name('my_awesome_queue') #=> 'https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
       #
     def queue_url_by_name(queue_name)
       return queue_name if queue_name.include?('/')
@@ -296,7 +365,7 @@ module RightAws
 
       # Returns short queue name by url.
       #
-      #  RightSqs.queue_name_by_url('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 'my_awesome_queue'
+      #  RightSqs.queue_name_by_url('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 'my_awesome_queue'
       #
     def self.queue_name_by_url(queue_url)
       queue_url[/[^\/]*$/]
@@ -306,7 +375,7 @@ module RightAws
     
       # Returns short queue name by url.
       #
-      #  sqs.queue_name_by_url('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 'my_awesome_queue'
+      #  sqs.queue_name_by_url('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 'my_awesome_queue'
       #
     def queue_name_by_url(queue_url)
       self.class.queue_name_by_url(queue_url)
@@ -316,17 +385,19 @@ module RightAws
 
       # Returns approximate number of messages in queue.
       #
-      #  sqs.get_queue_length('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 3
+      #  sqs.get_queue_length('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 3
       #
     def get_queue_length(queue_url)
-      get_queue_attributes(queue_url)['ApproximateNumberOfMessages'].to_i
+      attrs = get_queue_attributes(queue_url)
+      attrs['ApproximateNumberOfMessages'].to_i +
+      attrs['ApproximateNumberOfMessagesNotVisible'].to_i
     rescue
       on_exception
     end
 
       # Removes all visible messages from queue. Return +true+ or an exception.
       #
-      #  sqs.clear_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> true
+      #  sqs.clear_queue('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> true
       #
     def clear_queue(queue_url)
       while (pop_messages(queue_url, 10).length > 0) ; end   # delete all messages in queue
@@ -337,12 +408,12 @@ module RightAws
 
       # Pops (retrieves and deletes) up to 'number_of_messages' from queue. Returns an array of retrieved messages in format: <tt>[{:id=>'message_id', :body=>'message_body'}]</tt>.
       #
-      #   sqs.pop_messages('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 3) #=>
+      #   sqs.pop_messages('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 3) #=>
       #   [{"ReceiptHandle"=>"Euvo62/...+Zw==", "MD5OfBody"=>"16af2...81e3", "Body"=>"Goodbyte World!", 
       #   "MessageId"=>"MEZI...JSWDE="}, {...}, ... , {...} ]
       #
-    def pop_messages(queue_url, number_of_messages=1)
-      messages = receive_message(queue_url, number_of_messages)
+    def pop_messages(queue_url, number_of_messages=1, attributes=nil)
+      messages = receive_message(queue_url, number_of_messages, nil, attributes)
       messages.each do |message|
         delete_message(queue_url, message['ReceiptHandle'])
       end
@@ -353,11 +424,11 @@ module RightAws
 
       # Pops (retrieves and  deletes) first accessible message from queue. Returns the message in format <tt>{:id=>'message_id', :body=>'message_body'}</tt> or +nil+.
       #
-      #  sqs.pop_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=>
+      #  sqs.pop_message('https://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=>
       #    {:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}
       #
-    def pop_message(queue_url)
-      messages = pop_messages(queue_url)
+    def pop_message(queue_url, attributes=nil)
+      messages = pop_messages(queue_url, 1, attributes)
       messages.blank? ? nil : messages[0]
     rescue
       on_exception
@@ -400,8 +471,8 @@ module RightAws
       end
       def tagend(name)
         case name 
-          when 'Name'      ; @current_attribute          = @text
-          when 'Value'     ; @result[@current_attribute] = @text
+          when 'Name'  then @current_attribute          = @text
+          when 'Value' then @result[@current_attribute] = @text
         end
       end
     end
@@ -415,14 +486,23 @@ module RightAws
         @result = []
       end
       def tagstart(name, attributes)
-        @current_message = {} if name == 'Message'
+        case name
+        when 'Message' then @current_message = { }
+        when 'Attribute' then
+          @current_message['Attributes'] ||= {}
+          @current_attribute_name  = ''
+          @current_attribute_value = ''
+        end
       end
       def tagend(name)
         case name
-          when 'MessageId'  ; @current_message['MessageId'] = @text
-          when 'ReceiptHandle' ; @current_message['ReceiptHandle'] = @text
-          when 'MD5OfBody' ; @current_message['MD5OfBody'] = @text
-          when 'Body'; @current_message['Body'] = @text; @result << @current_message
+        when 'MessageId'     then @current_message['MessageId']     = @text
+        when 'ReceiptHandle' then @current_message['ReceiptHandle'] = @text
+        when 'MD5OfBody'     then @current_message['MD5OfBody']     = @text
+        when 'Name'          then @current_attribute_name  = @text
+        when 'Value'         then @current_attribute_value = @text
+        when 'Attribute'     then @current_message['Attributes'][@current_attribute_name] = @current_attribute_value
+        when 'Body'          then @current_message['Body'] = @text; @result << @current_message
         end
       end
     end
@@ -433,8 +513,8 @@ module RightAws
       end
       def tagend(name)
         case name
-          when 'MessageId' ; @result['MessageId'] = @text
-          when 'MD5OfMessageBody' ; @result['MD5OfMessageBody'] = @text
+          when 'MessageId'        then @result['MessageId']        = @text
+          when 'MD5OfMessageBody' then @result['MD5OfMessageBody'] = @text
         end
       end
     end