right_aws 1.1.0

data/lib/sqs/right_sqs.rb

@@ -0,0 +1,369 @@
+#
+# Copyright (c) 2007 RightScale 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.
+#
+
+module RightAws
+
+    #
+    # SQS.
+    #
+    #  sqs    = RightAws::Sqs.new(aws_access_key_id, aws_secret_access_key)
+    #  queue1 = sqs.queue('my_awesome_queue')
+    #   ...
+    #  queue2 = RightAws::Sqs::Queue.create(sqs, 'my_cool_queue', true)
+    #  puts queue2.size
+    #   ...
+    #  message1 = queue2.receive
+    #  message1.visibility = 0
+    #  puts message1
+    #   ...
+    #  queue2.clear(true)
+    #  queue2.send_message('Ola-la!')
+    #  message2 = queue2.pop
+    #   ...
+    #  grantee1 = RightAws::Sqs::Grantee.create(queue2,'one_cool_guy@email.address')
+    #  grantee1.grant('FULLCONTROL')
+    #  grantee1.drop
+    #   ...
+    #  grantee2 = queue.grantees('another_cool_guy@email.address')
+    #  grantee2.revoke('SENDMESSAGE')
+    #
+  class Sqs
+    attr_reader :interface
+    
+    def initialize(aws_access_key_id, aws_secret_access_key, params={})
+      @interface = SqsInterface.new(aws_access_key_id, aws_secret_access_key, params)
+    end
+    
+      # Retrieves a list of queues. 
+      # Returns an +array+ of +Queue+ instances.
+      #
+      #  RightAws::Sqs.queues #=> array of queues
+      #
+    def queues(prefix=nil)
+      @interface.list_queues(prefix).map do |url|
+        Queue.new(self, url)
+      end
+    end
+    
+      # Returns Queue instance by queue name. 
+      # If the queue does not exist at Amazon SQS and +create+ then creates it.
+      #
+      #  RightAws::Sqs.queue('my_awesome_queue') #=> #<RightAws::Sqs::Queue:0xb7b626e4 ... >
+      #
+    def queue(queue_name, create=true, visibility=nil)
+      url = @interface.queue_url_by_name(queue_name)
+      url = (create ? @interface.create_queue(queue_name, visibility) : nil) unless url
+      url ? Queue.new(self, url) : nil
+    end
+  
+  
+    class Queue
+      attr_reader :name, :url, :sqs
+      
+        # Returns Queue instance by queue name. 
+        # If the queue does not exist at Amazon SQS and +create+ then creates it.
+        #
+        #  RightAws::Sqs::Queue.create(sqs, 'my_awesome_queue') #=> #<RightAws::Sqs::Queue:0xb7b626e4 ... >
+        #
+      def self.create(sqs, url_or_name, create=true, visibility=nil)
+        sqs.queue(url_or_name, create=true, visibility)
+      end
+      
+        # Creates new Queue instance. 
+        # Does not create queue at Amazon.
+        #
+        #  queue = RightAws::Sqs::Queue.new(sqs, 'my_awesome_queue')
+        #
+      def initialize(sqs, url_or_name)
+        @sqs  = sqs
+        @url  = @sqs.interface.queue_url_by_name(url_or_name)
+        @name = @sqs.interface.queue_name_by_url(@url)
+      end
+      
+        # Retrieves queue size.
+        #
+        #  queue.size #=> 1
+        #
+      def size
+        @sqs.interface.get_queue_length(@url)
+      end
+      
+        # Clears queue. 
+        # Deletes only the visible messages unless +force+ is +true+.
+        #
+        #  queue.clear(true) #=> true
+        #
+        # P.S. when <tt>force==true</tt> the queue deletes then creates again. This is 
+        # the quickest method to clear big queue oe the queue with 'locked' messages. All queue
+        # attributes restores. But there is no way to restore grantees permissions to 
+        # this queue. If you have no grantees except of 'root' then you have no problems.
+        # But if the grantees are there - better use <tt>queue.clear(false)</tt>.
+        #
+      def clear(force=false)
+        if force
+          @sqs.interface.force_clear_queue(@url)
+        else
+          @sqs.interface.clear_queue(@url)
+        end
+      end
+      
+        # Deletes queue. 
+        # Queue must be empty or +force+ must be set to +true+. 
+        # Returns +true+. 
+        #
+        #  queue.delete(true) #=> true
+        #
+      def delete(force=false)
+        @sqs.interface.delete_queue(@url, force)
+      end
+
+        # Sends new message to queue. 
+        # Returns new Message instance that has been sent to queue.
+      def send_message(message)
+        message = message.to_s
+        msg     = Message.new(self, @sqs.interface.send_message(@url, message), message)
+        msg.sent_at = Time.now
+        msg
+      end
+      alias_method :push, :send_message
+
+        # Retrieves a bunch of message from queue. 
+        # Returns an array of Message instances. 
+        #
+        #  queue.receive_messages(2,10) #=> array of messages
+        #
+      def receive_messages(number_of_messages=1, visibility=nil)
+        list = @sqs.interface.receive_messages(@url, number_of_messages, visibility)
+        list.map! do |entry|
+          msg             = Message.new(self, entry[:id], entry[:body], visibility)
+          msg.received_at = Time.now 
+          msg
+        end
+      end
+      
+        # Retrieves first accessible message from queue. 
+        # Returns Message instance or +nil+ it the queue is empty.
+        #
+        #  queue.receive #=> #<RightAws::Sqs::Message:0xb7bf0884 ... >
+        #
+      def receive(visibility=nil)
+        list = receive_messages(1, visibility)
+        list.empty? ? nil : list[0]
+      end
+
+        # Peeks message body.
+        #
+        #  queue.peek #=> #<RightAws::Sqs::Message:0xb7bf0884 ... >
+        #
+      def peek(message_id)
+        entry = @sqs.interface.peek_message(@url, message_id)
+        msg   = Message.new(self, entry[:id], entry[:body])
+        msg.received_at = Time.now 
+        msg
+      end
+
+        # Pops (and deletes) first accessible message from queue. 
+        # Returns Message instance or +nil+ it the queue is empty.
+        #
+        #  queue.pop #=> #<RightAws::Sqs::Message:0xb7bf0884 ... >
+        #
+      def pop
+        msg = receive
+        msg.delete if msg
+        msg
+      end
+
+        # Retrieves +VisibilityTimeout+ value for the queue. 
+        # Returns new timeout value.
+        #
+        #  queue.visibility #=> 30
+        #
+      def visibility
+        @sqs.interface.get_visibility_timeout(@url)
+      end
+        
+        # Sets new +VisibilityTimeout+ for the queue. 
+        # Returns new timeout value. 
+        #
+        #  queue.visibility #=> 30
+        #  queue.visibility = 33
+        #  queue.visibility #=> 33
+        #
+      def visibility=(visibility_timeout)
+        @sqs.interface.set_visibility_timeout(@url, visibility_timeout)
+        visibility_timeout
+      end
+        
+        # Sets new queue attribute value. 
+        # Not all attributes may be changed: +ApproximateNumberOfMessages+ (for example) is a read only attribute. 
+        # Returns a value to be assigned to attribute. 
+        #
+        # queue.set_attribute('VisibilityTimeout', '100')  #=> '100'
+        # queue.get_attribute('VisibilityTimeout')         #=> '100'
+        #
+      def set_attribute(attribute, value)
+        @sqs.interface.set_queue_attributes(@url, attribute, value)
+        value
+      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')  #=> '100'
+        #
+      def get_attribute(attribute='All')
+        attributes = @sqs.interface.get_queue_attributes(@url, attribute)
+        attribute=='All' ? attributes : attributes[attribute]
+      end
+        
+        # Retrieves a list grantees. 
+        # Returns an +array+ of Grantee instances if the +grantee_email_address+ is unset. 
+        # Else returns Grantee instance that points to +grantee_email_address+ or +nil+.
+        #
+        #  grantees = queue.grantees #=> [#<RightAws::Sqs::Grantee:0xb7bf0888 ... >, ...]
+        #   ...
+        #  grantee  = queue.grantees('cool_guy@email.address') #=> nil | #<RightAws::Sqs::Grantee:0xb7bf0888 ... >
+        #
+      def grantees(grantee_email_address=nil, permission = nil)
+        hash = @sqs.interface.list_grants(@url, grantee_email_address, permission)
+        grantees = []
+        hash.each do |key, value|
+          grantees << Grantee.new(self, grantee_email_address, key, value[:name], value[:perms])
+        end
+        if grantee_email_address
+          grantees.blank? ? nil : grantees.shift
+        else
+          grantees
+        end
+      end
+    end
+    
+    
+    class Message
+      attr_reader   :queue, :id, :body, :visibility
+      attr_accessor :sent_at, :received_at
+      
+      def initialize(queue, id=nil, body=nil, visibility=nil)
+        @queue       = queue
+        @id          = id
+        @body        = body
+        @visibility  = visibility
+        @sent_at     = nil
+        @received_at = nil
+      end
+      
+        # Returns +Message+ instance body.
+      def to_s
+        @body
+      end
+      
+        # Changes +VisibilityTimeout+ for current message. 
+        # Returns new +VisibilityTimeout+ value.
+      def visibility=(visibility_timeout)
+        @queue.sqs.interface.change_message_visibility(@queue.url, @id, visibility_timeout)
+        @visibility = visibility_timeout
+      end
+      
+        # Removes message from queue. 
+        # Returns +true+.
+      def delete
+        @queue.sqs.interface.delete_message(@queue.url, @id)
+      end
+    end
+
+
+    class Grantee
+      attr_accessor :queue, :id, :name, :perms, :email
+      
+        # Creates new Grantee instance. 
+        # To create new grantee for queue use:
+        #
+        #   grantee = Grantee.new(queue, grantee@email.address)
+        #   grantee.grant('FULLCONTROL')
+        #
+      def initialize(queue, email=nil, id=nil, name=nil, perms=[])
+        @queue = queue
+        @id    = id
+        @name  = name
+        @perms = perms
+        @email = email
+        retrieve unless id
+      end
+
+        # Retrieves security information for grantee identified by email. 
+        # Returns +nil+ if such user does not has any permissions for this queue or 
+        # +true+ if perms updated successfully. 
+      def retrieve # :nodoc:
+        @id    = nil
+        @name  = nil
+        @perms = []
+        
+        hash = @queue.sqs.interface.list_grants(@queue.url, @email)
+        return nil if hash.empty?
+        
+        grantee = hash.shift
+        @id     = grantee[0]
+        @name   = grantee[1][:name]
+        @perms  = grantee[1][:perms]
+        true
+      end
+        
+        # Adds permissions for grantee. 
+        # Permission: 'FULLCONTROL' | 'RECEIVEMESSAGE' | 'SENDMESSAGE'. 
+        # User must have @email set. 
+      def grant(permission=nil)
+        raise "You can't grant permission without defining a grantee email address!" unless @email
+        @queue.sqs.interface.add_grant(@queue.url, @email, permission)
+        retrieve
+      end
+      
+        # Revokes permissions for grantee. 
+        # Permission: 'FULLCONTROL' | 'RECEIVEMESSAGE' | 'SENDMESSAGE'. 
+        # Default value is 'FULLCONTROL'. 
+        # User must have +@email+ or +@id+ set. 
+        # Returns +true+.
+      def revoke(permission='FULLCONTROL')
+        @queue.sqs.interface.remove_grant(@queue.url, @email || @id, permission)
+        unless @email   # if email is unknown - just remove permission from local perms list...
+          @perms.delete(permission)
+        else            # ... else retrieve updated information from Amazon
+          retrieve
+        end
+        true
+      end
+      
+        # Revokes all permissions for this grantee.
+        # Returns +true+
+      def drop
+        @perms.each do |permission|
+          @queue.sqs.interface.remove_grant(@queue.url, @email || @id, permission)
+        end
+        retrieve
+        true
+      end
+      
+    end
+
+  end
+end

data/lib/sqs/right_sqs_interface.rb

@@ -0,0 +1,655 @@
+#
+# Copyright (c) 2007 RightScale 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.
+#
+
+module RightAws
+
+  class SqsInterface
+    
+    SIGNATURE_VERSION = "1"
+    API_VERSION       = "2007-05-01"
+    DEFAULT_HOST      = "queue.amazonaws.com"
+    DEFAULT_PORT      = 443
+    DEFAULT_PROTOCOL  = 'https'
+    REQUEST_TTL       = 30
+    DEFAULT_VISIBILITY_TIMEOUT = 30
+      # A list if Amazons problems we can handle by AWSErrorHandler.
+    @@amazon_problems = RightAws::AMAZON_PROBLEMS
+
+      # Current aws_access_key_id
+    attr_reader :aws_access_key_id
+      # Last HTTP request object
+    attr_reader :last_request
+      # Last HTTP response object
+    attr_reader :last_response
+      # Last AWS errors list (used by AWSErrorHandler)
+    attr_accessor :last_errors
+      # Last AWS request id (used by AWSErrorHandler)
+    attr_accessor :last_request_id
+      # Logger object
+    attr_accessor :logger
+      # Initial params hash
+    attr_accessor :params
+    
+    @@bench_sqs = Benchmark::Tms.new()
+    @@bench_xml = Benchmark::Tms.new()
+    
+      # Benchmark::Tms instance for SQS access benchmark.
+    def self.bench_sqs; @@bench_sqs;  end  
+      # Benchmark::Tms instance for XML parsing benchmark.
+    def self.bench_xml; @@bench_xml; end  # For benchmark puposes.
+
+      # Returns a list of Amazon service responses which are known as problems on Amazon side. 
+      # We have to re-request again if we've got any of them - probably the problem will disappear. By default returns the same value as AMAZON_PROBLEMS const.
+    def self.amazon_problems
+      @@amazon_problems
+    end
+    
+      # Sets a list of Amazon side problems.
+    def self.amazon_problems=(problems_list)
+      @@amazon_problems = problems_list
+    end
+
+      # Creates new RightSqs instance.
+      #
+      #  sqs = RightSqs.new('1E3GDYEOGFJPIT75KDT40','hgTHt68JY07JKUY08ftHYtERkjgtfERn57DFE379', {:multi_thread => true, :logger => Logger.new('/tmp/x.log')}) #=> <RightSqs:0xb7af6264>
+      #  
+      # Params is a hash:
+      #
+      #    {: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)
+      #     :logger       => Logger Object}        # Logger instance: logs to STDOUT if omitted }
+      #
+    def initialize(aws_access_key_id, aws_secret_access_key, params={})
+      @params = params
+      raise AwsError.new("AWS access keys are required to operate on SQS") \
+        if aws_access_key_id.blank? || aws_secret_access_key.blank?
+      @aws_access_key_id     = aws_access_key_id
+      @aws_secret_access_key = aws_secret_access_key
+        # params
+      @params[:server]       ||= DEFAULT_HOST
+      @params[:port]         ||= DEFAULT_PORT
+      @params[:protocol]     ||= DEFAULT_PROTOCOL
+      @params[:multi_thread] ||= defined?(AWS_DAEMON)
+        # set logger
+      @logger = @params[:logger]
+      @logger = RAILS_DEFAULT_LOGGER if !@logger && defined?(RAILS_DEFAULT_LOGGER)
+      @logger = Logger.new(STDOUT)   if !@logger
+      @logger.info "New #{self.class.name} using #{@params[:multi_thread] ? 'multi' : 'single'}-threaded mode"
+    end
+
+    def on_exception(options={:raise=>true, :log=>true}) # :nodoc:
+      AwsError::on_aws_exception(self, options)
+    end
+
+      # Return the +true+ if this RightS3 instance works in multi_thread state and +false+ otherwise.
+    def multi_thread
+      @params[:multi_thread]
+    end
+
+  #-----------------------------------------------------------------
+  #      Requests
+  #-----------------------------------------------------------------
+
+      # Generates request hash for QUERY API
+    def generate_request(action, param={})  # :nodoc:
+        # Sometimes we need to use queue uri (delete queue etc)
+        # In that case we will use Symbol key: 'param[:queue_url]'
+      queue_uri = param[:queue_url] ? URI(param[:queue_url]).path : '/'
+        # remove unset(=optional) and symbolyc keys
+      param.each{ |key, value| param.delete(key) if (value.nil? || key.is_a?(Symbol)) }
+        # prepare output hash
+      request_hash = { "Action"           => action,
+                       "Expires"          => Time.now.utc.since(REQUEST_TTL).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                       "AWSAccessKeyId"   => @aws_access_key_id,
+                       "Version"          => API_VERSION,
+                       "SignatureVersion" => SIGNATURE_VERSION }
+      request_hash.update(param)
+      request_data   = request_hash.sort{|a,b| (a[0].to_s.downcase)<=>(b[0].to_s.downcase)}.to_s
+      request_hash['Signature'] = Base64.encode64( OpenSSL::HMAC.digest( OpenSSL::Digest::Digest.new( "sha1" ), @aws_secret_access_key, request_data)).strip
+      request_params = request_hash.to_a.collect{|key,val| key.to_s + "=" + CGI::escape(val.to_s) }.join("&")
+      request        = Net::HTTP::Get.new("#{queue_uri}?#{request_params}")
+        # prepare output hash
+      { :request  => request, 
+        :server   => @params[:server],
+        :port     => @params[:port],
+        :protocol => @params[:protocol] }
+    end
+
+      # Generates request hash for REST API
+    def generate_rest_request(method, param) # :nodoc:
+      queue_uri = param[:queue_url] ? URI(param[:queue_url]).path : '/'
+      message   = param[:message]                # extract message body if nesessary
+        # remove unset(=optional) and symbolyc keys
+      param.each{ |key, value| param.delete(key) if (value.nil? || key.is_a?(Symbol)) }
+        # created request
+      param_to_str = param.to_a.collect{|key,val| key.to_s + "=" + CGI::escape(val.to_s) }.join("&")
+      param_to_str = "?#{param_to_str}" unless param_to_str.blank?
+      request = "Net::HTTP::#{method.titleize}".constantize.new("#{queue_uri}#{param_to_str}")
+      request.body = message if message
+        # set main headers
+      request['content-md5']  = ''
+      request['Content-Type'] = 'text/plain'
+      request['Date']         = Time.now.httpdate
+        # generate authorization string
+      auth_string = "#{method.upcase}\n#{request['content-md5']}\n#{request['Content-Type']}\n#{request['Date']}\n#{CGI::unescape(queue_uri)}"
+      signature   = Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new("sha1"), @aws_secret_access_key, auth_string)).strip
+        # set other headers
+      request['Authorization'] = "AWS #{@aws_access_key_id}:#{signature}"
+      request['AWS-Version']   = API_VERSION
+        # prepare output hash
+      { :request  => request, 
+        :server   => @params[:server],
+        :port     => @params[:port],
+        :protocol => @params[:protocol] }
+    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[:sqs_connection] ||= Rightscale::HttpConnection.new(:exception => AwsError)
+      @last_request  = request[:request]
+      @last_response = nil
+      response=nil
+      
+      @@bench_sqs.add!{ response = thread[:sqs_connection].request(request) }
+        # check response for errors...
+      @last_response = response
+      if response.is_a?(Net::HTTPSuccess)
+        @error_handler = nil
+        @@bench_xml.add! do
+          if parser.kind_of?(RightAWSParser)
+            REXML::Document.parse_stream(response.body, parser)
+          else
+            parser.parse(response)
+          end
+        end
+        return parser.result
+      else
+        @error_handler = AWSErrorHandler.new(self, parser, @@amazon_problems) unless @error_handler
+        check_result   = @error_handler.check(request)
+        if check_result
+          @error_handler = nil
+          return check_result 
+        end
+        raise AwsError.new(@last_errors, @last_response.code, @last_request_id)
+      end
+    rescue
+      @error_handler = nil
+      raise
+    end
+
+
+      # Creates new queue. Returns new queue link.
+      #
+      #  sqs.create_queue('my_awesome_queue') #=> 'http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
+      #
+    def create_queue(queue_name, default_visibility_timeout=nil)
+      req_hash = generate_request('CreateQueue', 
+                                  'QueueName'                => queue_name,
+                                  'DefaultVisibilityTimeout' => default_visibility_timeout || DEFAULT_VISIBILITY_TIMEOUT )
+      request_info(req_hash, SqsCreateQueueParser.new)
+    end
+
+     # Creates new queue. If +queue_name_prefix+ is omitted then retrieves a list of all queues.
+     #
+     #  sqs.create_queue('my_awesome_queue')
+     #  sqs.create_queue('my_awesome_queue_2')
+     #  sqs.list_queues('my_qwesome') #=> ['http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue','http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2']
+     #
+    def list_queues(queue_name_prefix=nil)
+      req_hash = generate_request('ListQueues', 'QueueNamePrefix' => queue_name_prefix)
+      request_info(req_hash, SqsListQueuesParser.new)
+    rescue
+      on_exception
+    end
+      
+      # Deletes queue (queue must be empty or +force_deletion+ must be set to true). Queue is identified by url. Returns +true+ or an exception.
+      #
+      #  sqs.delete_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue_2') #=> true
+      #
+    def delete_queue(queue_url, force_deletion = false)
+      req_hash = generate_request('DeleteQueue', 
+                                  'ForceDeletion' => force_deletion.to_s,
+                                  :queue_url      => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+
+      # 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', 
+                                  'Attribute' => attribute,
+                                  :queue_url  => queue_url)
+      request_info(req_hash, SqsGetQueueAttributesParser.new)
+    rescue
+      on_exception
+    end
+
+      # Sets queue attribute. Returns +true+ or an exception.
+      #
+      #  sqs.set_queue_attributes('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', "VisibilityTimeout", 10) #=> true
+      #
+      # P.S. Hmm... Amazon returns success even if such attribute does not exist. And they need some seconds to change attribute value.
+    def set_queue_attributes(queue_url, attribute, value)
+      req_hash = generate_request('SetQueueAttributes', 
+                                  'Attribute' => attribute,
+                                  'Value'     => value,
+                                  :queue_url  => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+
+     # Sets visibility timeout. Returns +true+ or an exception.
+     #
+     #  sqs.set_visibility_timeout('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 15) #=> true
+     #
+     # See also: +set_queue_attributes+
+     #
+    def set_visibility_timeout(queue_url, visibility_timeout=nil)
+      req_hash = generate_request('SetVisibilityTimeout', 
+                                  'VisibilityTimeout' => visibility_timeout || DEFAULT_VISIBILITY_TIMEOUT,
+                                  :queue_url => queue_url )
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+
+     # Retrieves visibility timeout.
+     #
+     #  sqs.get_visibility_timeout('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 15
+     #
+     # See also: +get_queue_attributes+
+     #
+    def get_visibility_timeout(queue_url)
+      req_hash = generate_request('GetVisibilityTimeout', :queue_url => queue_url )
+      request_info(req_hash, SqsGetVisibilityTimeoutParser.new)
+    rescue
+      on_exception
+    end
+
+     # Adds grants for user (identified by email he registered at Amazon). Returns +true+ or an exception. Permission = 'FULLCONTROL' | 'RECEIVEMESSAGE' | 'SENDMESSAGE'.
+     #
+     #  sqs.add_grant('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'my_awesome_friend@gmail.com', 'FULLCONTROL') #=> true
+     #
+    def add_grant(queue_url, grantee_email_address, permission = nil)
+      req_hash = generate_request('AddGrant', 
+                                  'Grantee.EmailAddress' => grantee_email_address,
+                                  'Permission'           => permission,
+                                  :queue_url             => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+    
+      # Retrieves hash of +grantee_id+ => +perms+ for this queue:
+      #
+      #  sqs.list_grants('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=>
+      #    {"000000000000000000000001111111111117476c7fea6efb2c3347ac3ab2792a"=>{:name=>"root", :perms=>["FULLCONTROL"]},
+      #     "00000000000000000000000111111111111e5828344600fc9e4a784a09e97041"=>{:name=>"myawesomefriend", :perms=>["FULLCONTROL"]}  
+      #
+    def list_grants(queue_url, grantee_email_address=nil, permission = nil)
+      req_hash = generate_request('ListGrants', 
+                                  'Grantee.EmailAddress' => grantee_email_address,
+                                  'Permission'           => permission,
+                                  :queue_url             => queue_url)
+      response = request_info(req_hash, SqsListGrantsParser.new)
+        # One user may have up to 3 permission records for every queue.
+        # We will join these records to one.
+      result = {}    
+      response.each do |perm|
+        id = perm[:id]
+          # create hash for new user if unexisit
+        result[id] = {:perms=>[]} unless result[id]
+          # fill current grantee params
+        result[id][:perms] << perm[:permission]
+        result[id][:name] = perm[:name]
+      end
+      result
+    end
+
+      # Revokes permission from user. Returns +true+ or an exception.
+      #
+      #  sqs.remove_grant('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'my_awesome_friend@gmail.com', 'FULLCONTROL') #=> true
+      #
+    def remove_grant(queue_url, grantee_email_address_or_id, permission = nil)
+      grantee_key = grantee_email_address_or_id.include?('@') ? 'Grantee.EmailAddress' : 'Grantee.ID'
+      req_hash = generate_request('RemoveGrant', 
+                                  grantee_key  => grantee_email_address_or_id,
+                                  'Permission' => permission,
+                                  :queue_url   => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    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>
+      #
+      #   sqs.receive_messages('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue',10, 5) #=>
+      #    [{:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}, ..., {}]
+      #
+      # P.S. Usually returns less messages than have been requested even if they are available.
+      #
+    def receive_messages(queue_url, number_of_messages=1, visibility_timeout=nil)
+      return [] if number_of_messages == 0
+      req_hash = generate_rest_request('GET',
+                                       'NumberOfMessages'  => number_of_messages,
+                                       'VisibilityTimeout' => visibility_timeout,
+                                       :queue_url          => "#{queue_url}/front" )
+      request_info(req_hash, SqsReceiveMessagesParser.new)
+    rescue
+      on_exception
+    end
+    
+      # Peeks message from queue by message id. Returns message in format of <tt>{:id=>'message_id', :body=>'message_body'}</tt> or +nil+.
+      #
+      #  sqs.peek_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', '1234567890...0987654321') #=>
+      #    {:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}
+      #
+    def peek_message(queue_url, message_id)
+      req_hash = generate_rest_request('GET', :queue_url => "#{queue_url}/#{CGI::escape message_id}" )
+      messages = request_info(req_hash, SqsReceiveMessagesParser.new)
+      messages.blank? ? nil : messages[0]
+    rescue
+      on_exception
+    end
+
+      # Sends new message to queue.Returns 'message_id' or raises an exception.
+      #
+      #  sqs.send_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 'message_1') #=> "1234567890...0987654321"
+      #
+    def send_message(queue_url, message)
+      req_hash = generate_rest_request('PUT',
+                                       :message   => message,
+                                       :queue_url => "#{queue_url}/back")
+      request_info(req_hash, SqsSendMessagesParser.new)
+    rescue
+      on_exception
+    end
+    
+      # Deletes message from queue. Returns +true+ or an exception.
+      #
+      #  sqs.delete_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', '12345678904...0987654321') #=> true
+      #
+    def delete_message(queue_url, message_id)
+      req_hash = generate_request('DeleteMessage', 
+                                  'MessageId' => message_id,
+                                  :queue_url  => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+    
+      # Changes message visibility timeout. Returns +true+ or an exception.
+      #
+      #  sqs.change_message_visibility('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', '1234567890...0987654321', 10) #=> true
+      #
+    def change_message_visibility(queue_url, message_id, visibility_timeout=0)
+      req_hash = generate_request('ChangeMessageVisibility', 
+                                  'MessageId'         => message_id,
+                                  'VisibilityTimeout' => visibility_timeout.to_s,
+                                  :queue_url          => queue_url)
+      request_info(req_hash, SqsStatusParser.new)
+    rescue
+      on_exception
+    end
+    
+      # Returns queue url by queue short name or +nil+ if queue is not found
+      #
+      #  sqs.queue_url_by_name('my_awesome_queue') #=> 'http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue'
+      #
+    def queue_url_by_name(queue_name)
+      return queue_name if queue_name.include?('/')
+      queue_urls = list_queues(queue_name)
+      queue_urls.each do |queue_url|
+        return queue_url if queue_name_by_url(queue_url) == queue_name
+      end
+      nil
+    rescue
+      on_exception
+    end
+
+      # Returns short queue name by url.
+      #
+      #  RightSqs.queue_name_by_url('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 'my_awesome_queue'
+      #
+    def self.queue_name_by_url(queue_url)
+      queue_url[/[^\/]*$/]
+    rescue
+      on_exception
+    end
+    
+      # Returns short queue name by url.
+      #
+      #  sqs.queue_name_by_url('http://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)
+    rescue
+      on_exception
+    end
+
+      # Returns approximate amount of messages in queue.
+      #
+      #  sqs.get_queue_length('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> 3
+      #
+    def get_queue_length(queue_url)
+      get_queue_attributes(queue_url)['ApproximateNumberOfMessages'].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
+      #
+    def clear_queue(queue_url)
+      while (m = pop_message(queue_url)) ; end   # delete all messages in queue
+      true
+    rescue
+      on_exception
+    end
+
+      # Deletes queue then re-creates it (restores attributes also). The fastest method to clear big queue or queue with invisible messages. Return +true+ or an exception.
+      #
+      #  sqs.force_clear_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> true
+      #
+    def force_clear_queue(queue_url)
+      queue_name       = queue_name_by_url(queue_url)
+      queue_attributes = get_queue_attributes(queue_url)
+      force_delete_queue(queue_url)
+      create_queue(queue_name)
+        # hmmm... The next like is a trick. Amazon do not want change attributes immediately after queue creation
+        # So we do 'empty' get_queue_attributes. Probably they need some time to allow attributes change.
+      get_queue_attributes(queue_url)  
+      queue_attributes.each{ |attribute, value| set_queue_attributes(queue_url, attribute, value) }
+      true
+    rescue
+      on_exception
+    end
+
+      # Deletes queue even if it has messages. Return +true+ or an exception.
+      #
+      #  force_delete_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue') #=> true
+      #
+      # P.S. same as <tt>delete_queue('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', true)</tt>
+    def force_delete_queue(queue_url)
+      delete_queue(queue_url, true)
+    rescue
+      on_exception
+    end
+
+      # Reads first accessible message from queue. Returns message as a hash: <tt>{:id=>'message_id', :body=>'message_body'}</tt> or +nil+.
+      #
+      #  sqs.receive_message('http://queue.amazonaws.com/ZZ7XXXYYYBINS/my_awesome_queue', 10) #=>
+      #    {:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}
+      #
+    def receive_message(queue_url, visibility_timeout=nil)
+      result = receive_messages(queue_url, 1, visibility_timeout)
+      result.blank? ? nil : result[0]
+    rescue
+      on_exception
+    end
+    
+      # Same as send_message
+    alias_method :push_message, :send_message
+    
+      # 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) #=>
+      #    [{:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}, ..., {}]
+      #
+    def pop_messages(queue_url, number_of_messages=1)
+      messages = receive_messages(queue_url, number_of_messages)
+      messages.each do |message|
+        delete_message(queue_url, message[:id])
+      end
+      messages
+    rescue
+      on_exception
+    end
+
+      # 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') #=>
+      #    {:id=>"12345678904GEZX9746N|0N9ED344VK5Z3SV1DTM0|1RVYH4X3TJ0987654321", :body=>"message_1"}
+      #
+    def pop_message(queue_url)
+      messages = pop_messages(queue_url)
+      messages.blank? ? nil : messages[0]
+    rescue
+      on_exception
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Status Response Parser
+    #-----------------------------------------------------------------
+
+    class SqsStatusParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        if name == 'StatusCode'
+          @result = @text=='Success' ? true : false
+        end
+      end
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Queue
+    #-----------------------------------------------------------------
+
+    class SqsCreateQueueParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        @result = @text if name == 'QueueUrl'
+      end
+    end
+
+    class SqsListQueuesParser < RightAWSParser # :nodoc:
+      def reset
+        @result = []
+      end
+      def tagend(name)
+        @result << @text if name == 'QueueUrl'
+      end
+    end
+
+    class SqsGetQueueAttributesParser < RightAWSParser # :nodoc:
+      def reset
+        @result = {}
+      end
+      def tagend(name)
+        case name 
+          when 'Attribute' ; @current_attribute          = @text
+          when 'Value'     ; @result[@current_attribute] = @text
+  #        when 'StatusCode'; @result['status_code']      = @text
+  #        when 'RequestId' ; @result['request_id']       = @text
+        end
+      end
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Timeouts
+    #-----------------------------------------------------------------
+
+    class SqsGetVisibilityTimeoutParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        @result = @text.to_i if name == 'VisibilityTimeout'
+      end
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Permissions
+    #-----------------------------------------------------------------
+
+    class SqsListGrantsParser < RightAWSParser # :nodoc:
+      def reset
+        @result = []
+      end
+      def tagstart(name, attributes)
+        @current_perms = {} if name == 'GrantList'
+      end
+      def tagend(name)
+        case name
+          when 'ID'         ; @current_perms[:id]         = @text
+          when 'DisplayName'; @current_perms[:name]       = @text
+          when 'Permission' ; @current_perms[:permission] = @text
+          when 'GrantList'  ; @result << @current_perms 
+        end
+      end
+    end
+
+    #-----------------------------------------------------------------
+    #      PARSERS: Messages
+    #-----------------------------------------------------------------
+
+    class SqsReceiveMessagesParser < RightAWSParser # :nodoc:
+      def reset
+        @result = []
+      end
+      def tagstart(name, attributes)
+        @current_message = {} if name == 'Message'
+      end
+      def tagend(name)
+        case name
+          when 'MessageId'  ; @current_message[:id]   = @text
+          when 'MessageBody'; @current_message[:body] = @text
+          when 'Message'    ; @result << @current_message
+        end
+      end
+    end
+
+    class SqsSendMessagesParser < RightAWSParser # :nodoc:
+      def tagend(name)
+        @result = @text if name == 'MessageId'
+      end
+    end
+    
+  end
+
+end