bisques 1.0.0

data/README.rdoc

@@ -0,0 +1,70 @@
+Bisques is a client library for Amazon SQS (Simple Queue Service). It is
+implemented using httpclient (https://github.com/nahi/httpclient).
+
+* http://github.com/jemmyw/bisques
+
+== USAGE
+
+To interact with SQS initialize a Bisques::Client object.
+
+The following scripts will result in the producer printing 10 numbers from the
+fibonacci sequence, with the consumer script doing the actual calculation.
+
+=== Producer
+
+  require 'bisques'
+
+  Bisques::AwsCredentials.default(aws_key, aws_secret)
+  client = Bisques::Client.new('us-east-1')
+  number_queue = client.get_or_create_queue('numbers')
+  result_queue = client.get_or_create_queue('results')
+
+  1.upto(10).each{|n| number_queue.post_message({"number" => n}) }
+
+  10.times do
+    puts result_queue.retrieve_one.inspect
+  end
+
+=== Consumer
+
+  require 'bisques'
+
+  Bisques::AwsCredentials.default(aws_key, aws_secret)
+  client = Bisques::Client.new('us-east-1')
+  number_queue = client.get_or_create_queue('numbers')
+  result_queue = client.get_or_create_queue('results')
+
+  listener = Bisques::QueueListener.new(number_queue)
+  listener.listen do |message|
+    result = fib(message["number"])
+    result_queue.post_message({"result" => result})
+    message.delete
+  end
+
+  while true; sleep 1; end
+
+== LICENSE
+
+Copyright (c) 2012 Jeremy Wells
+
+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.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/bisques/aws_connection.rb

@@ -0,0 +1,100 @@
+require 'httpclient'
+require 'bisques/aws_request'
+require 'bisques/aws_credentials'
+
+module Bisques
+  class AwsActionError < Bisques::Error
+    attr_reader :type, :code, :message, :status
+
+    def initialize(type, code, message, status)
+      @type, @code, @message, @status = type, code, message, status
+      super(message)
+    end
+
+    def to_s
+      "HTTP #{status}: #{type} #{code} #{message}"
+    end
+  end
+
+  # This module is for making API classes more convenient. The including class
+  # must pass the correct params via super from it's #initialize call. Two
+  # useful methods are added to the including class, #request and #action.
+  module AwsConnection
+    def self.included(mod) # :nodoc:
+      mod.class_eval do
+        attr_accessor :credentials, :region, :service
+      end
+    end
+
+    # Give the region, service and optionally the AwsCredentials.
+    #
+    # === Example:
+    #
+    #   class Sqs
+    #     include AwsConnection
+    #
+    #     def initialize(region)
+    #       super(region, 'sqs')
+    #     end
+    #   end
+    #
+    def initialize(region, service, credentials = AwsCredentials.default)
+      @region, @service, @credentials = region, service, credentials
+    end
+
+    def connection # :nodoc:
+      @connection ||= HTTPClient.new.tap do |http|
+        http.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http.receive_timeout = 30
+      end
+    end
+
+    # Perform an HTTP query to the given path using the given method (GET,
+    # POST, PUT, DELETE). A hash of query params can be specified. A POST or
+    # PUT body cna be specified as either a string or a hash of form params. A
+    # hash of HTTP headers can be specified.
+    def request(method, path, query = {}, body = nil, headers = {})
+      AwsRequest.new(connection).tap do |aws_request|
+        aws_request.credentials = credentials
+        aws_request.path = path
+        aws_request.region = region
+        aws_request.service = service
+        aws_request.method = method
+        aws_request.query = query
+        aws_request.body = body
+        aws_request.headers = headers
+        aws_request.make_request
+      end
+    end
+
+    # Call an AWS API with the given name at the given path. An optional hash
+    # of options can be passed as arguments for the API call. Returns an
+    # AwsResponse. If the response is not successful then an AwsActionError is
+    # raised and the error information is extracted into the exception
+    # instance.
+    #
+    # The API call will be automatically retried if the returned status code is
+    # in the 500 range.
+    def action(action_name, path = "/", options = {})
+      retries = 0
+
+      begin
+        # If options given in place of path assume /
+        options, path = path, "/" if path.is_a?(Hash) && options.empty?
+        request(:post, path, {}, options.merge("Action" => action_name)).response.tap do |response|
+          unless response.success?
+            element = response.doc.xpath("//Error")
+            raise AwsActionError.new(element.xpath("Type").text, element.xpath("Code").text, element.xpath("Message").text, response.http_response.status)
+          end
+        end
+      rescue AwsActionError => e
+        if retries < 2 && (500..599).include?(e.status.to_i)
+          retries += 1
+          retry
+        else
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/bisques/aws_credentials.rb

@@ -0,0 +1,28 @@
+module Bisques
+  # Represents an AWS key/secret combination. Provides a convenient class
+  # method for setting defaults that can be used by all objects later on.
+  #
+  # Example:
+  #
+  #   AwsCredentials.default('aws_key', 'aws_secret')
+  #
+  class AwsCredentials
+    attr_reader :aws_key, :aws_secret
+
+    def initialize(aws_key, aws_secret)
+      @aws_key, @aws_secret = aws_key, aws_secret
+    end
+
+    class << self
+      def default(*args)
+        if args.size == 2
+          @default = AwsCredentials.new(*args)
+        elsif args.empty?
+          @default
+        else
+          raise ArgumentError, "default takes 0 or 2 arguments"
+        end
+      end
+    end
+  end
+end

data/lib/bisques/aws_request.rb

@@ -0,0 +1,114 @@
+require 'bisques/aws_request_authorization'
+require 'bisques/aws_response'
+
+module Bisques
+  # A request to an AWS API call. This class must be initiated with a client
+  # instance of HTTPClient. A number of mandatory attributes must be set before
+  # calling make_request to return the response. #make_request returns an
+  # AwsResponse object.
+  #
+  # === Example
+  #
+  #   request = AwsRequest.new(httpclient)
+  #   request.method = "GET" or "POST"
+  #   request.query = {"hash" => "of query params"}
+  #   request.body = {"hash" => "of form params"} or "text body"
+  #   request.headers = {"hash" => "of optional headers"}
+  #   request.path = "optional path"
+  #   request.region = "AWS region (ex. us-east-1)"
+  #   request.service = "AWS service (ex. sqs)"
+  #   request.credentials = AwsCredentials.new("aws_key", "aws_secret")
+  #   response = request.make_request => Returns AwsResponse
+  #
+  class AwsRequest
+    # The HTTP method to use. Should be GET or POST.
+    attr_accessor :method
+    # A hash describing the query params to send.
+    attr_accessor :query
+    # A hash or string describing the form params or HTTP body. Only used when
+    # the method is POST or PUT.
+    attr_accessor :body
+    # A hash of additional HTTP headers to send with the request.
+    attr_accessor :headers
+    # The path to the API call. This shouldn't be the full URL as the host part
+    # is built from the region and service.
+    attr_accessor :path
+    # The AWS region. Ex: us-east-1
+    attr_accessor :region
+    # The AWS service. Ex: sqs
+    attr_accessor :service
+    # The AWS credentials. Should respond to aws_key and aws_secret. Use
+    # AwsCredentials.
+    attr_accessor :credentials
+
+    # An AwsResponse object describing the response. Returns nil until
+    # #make_request has been called.
+    attr_reader :response
+    attr_reader :authorization # :nodoc:
+
+    # AWS has some particular rules about how it likes it's form params encoded.
+    def self.aws_encode(value)
+      value.to_s.gsub(/([^a-zA-Z0-9._~-]+)/n) do
+        '%' + $1.unpack('H2' * $1.size).join('%').upcase
+      end
+    end
+
+    # Create a new AwsRequest using the given HTTPClient object.
+    def initialize(httpclient)
+      @httpclient = httpclient
+    end
+
+    # The full URL to the API endpoint the request will call.
+    def url
+      File.join("https://#{service}.#{region}.amazonaws.com", path)
+    end
+
+    # Send the HTTP request and get a response. Returns an AwsResponse object.
+    # The instance is frozen once this method is called and cannot be used
+    # again.
+    def make_request
+      create_authorization
+
+      options = {}
+      options[:header] = authorization.headers.merge(
+        'Authorization' => authorization.authorization_header
+      )
+      options[:query] = query if query.any?
+      options[:body] = form_body if body
+
+      http_response = @httpclient.request(method, url, options)
+      @response = AwsResponse.new(self, http_response)
+
+      freeze
+
+      @response
+    end
+
+    private
+
+    # Encode the form params if the body is given as a Hash.
+    def form_body
+      if body.is_a?(Hash)
+        body.map do |k,v|
+          [AwsRequest.aws_encode(k), AwsRequest.aws_encode(v)].join("=")
+        end.join("&")
+      else
+        body
+      end
+    end
+
+    # Create the AwsRequestAuthorization object for the request.
+    def create_authorization
+      @authorization = AwsRequestAuthorization.new.tap do |authorization|
+        authorization.url = url
+        authorization.method = method
+        authorization.query = query
+        authorization.body = form_body
+        authorization.region = region
+        authorization.service = service
+        authorization.credentials = credentials
+        authorization.headers = headers
+      end
+    end
+  end
+end

data/lib/bisques/aws_request_authorization.rb

@@ -0,0 +1,174 @@
+require "openssl"
+
+module Bisques
+  # Instances of this class are used to create HTTP authorization headers for
+  # AWS using Signature Version 4, as per
+  # http://docs.amazonwebservices.com/general/latest/gr/signature-version-4.html
+  #
+  # === Usage
+  #
+  # This is just an example of extracting the relevant information.
+  # 
+  #   url = "https://sqs.us-east-1.amazon.com/"
+  #   original_headers = {"Content-Type": "text/plain"}
+  #   query = {"Action" => "ListQueues"}
+  #   body = "some body text"
+  #   credentials = AwsCredentials.default
+  #   
+  #   authorization = AwsRequestAuthorization.new
+  #   authorization.url = url
+  #   authorization.method = "POST"
+  #   authorization.query = query
+  #   authorization.body = body
+  #   authorization.region = "us-east-1"
+  #   authorization.service = "sqs"
+  #   authorization.headers = original_headers
+  #
+  #   new_headers = authorization.headers.merge(
+  #     "Authorization" => authorization.authorization_header
+  #   )
+  #
+  #   url_with_query = url + "?" + query.map{|p| p.join("=")}.join("&")
+  #
+  #   Net::HTTP.post(
+  #     url_with_query,
+  #     body,
+  #     new_headers
+  #   )
+  #
+  class AwsRequestAuthorization
+    # The full URL to the API call.
+    attr_accessor :url
+    # The HTTP method.
+    attr_accessor :method
+    # A hash of key/pairs for the query string.
+    attr_accessor :query
+    # A string of the body being sent (for POST and PUT HTTP methods).
+    attr_accessor :body
+    # The AWS region.
+    attr_accessor :region
+    # The AWS service.
+    attr_accessor :service
+    # An AwsCredentials object.
+    attr_accessor :credentials
+    # The headers to read back.
+    attr_reader   :headers
+
+    # The generated authorization header.
+    def authorization_header
+      [
+        "AWS4-HMAC-SHA256",
+        "Credential=#{credentials.aws_key}/#{request_datestamp}/#{region}/#{service}/aws4_request,",
+        "SignedHeaders=#{signed_headers.join(";")},",
+        "Signature=#{signature.to_s}"
+      ].join(" ")
+    end
+
+    # The HTTP headers being sent.
+    def headers=(headers={})
+      @headers = headers.merge(
+        "x-amz-date" => request_timestamp
+      )
+    end
+
+    private
+
+    # When first called set a time for the request and keep it.
+    def request_time
+      @request_time ||= Time.now.utc
+    end
+
+    # The AWS timestamp format.
+    def request_timestamp
+      request_time.strftime("%Y%m%dT%H%M%SZ")
+    end
+
+    # The AWS datestamp format.
+    def request_datestamp
+      request_time.strftime("%Y%m%d")
+    end
+
+    # The digest used is SHA2.
+    def digest
+      Digest::SHA2.new
+    end
+
+    # Task 3: Calculate the signature.
+    def signature
+      digest = "SHA256"
+      OpenSSL::HMAC.hexdigest(digest, signing_key, string_to_sign)
+    end
+
+    # Calculate the signing key for task 3.
+    def signing_key
+      digest = "SHA256"
+      kDate = OpenSSL::HMAC.digest(digest, "AWS4" + credentials.aws_secret, request_datestamp)
+      kRegion = OpenSSL::HMAC.digest(digest, kDate, region)
+      kService = OpenSSL::HMAC.digest(digest, kRegion, service)
+      OpenSSL::HMAC.digest(digest, kService, "aws4_request")
+    end
+
+    # Task 2: Create the string to sign.
+    def string_to_sign
+      [
+        "AWS4-HMAC-SHA256",
+        request_timestamp,
+        credential_scope,
+        digest.hexdigest(canonical)
+      ].join("\n")
+    end
+
+    # Task 1: Create a canonical request.
+    def canonical
+      canonical = ""
+      canonical << method.to_s.upcase << "\n"
+      canonical << uri.path << "\n"
+
+      canonical_query.each_with_index do |(param,value), index|
+      canonical << param << "=" << value
+      canonical << "&" unless index == query.size - 1
+      end
+
+      canonical << "\n"
+      canonical << canonical_headers.map{|h| h.join(":")}.join("\n")
+      canonical << "\n\n"
+      canonical << signed_headers.join(";")
+      canonical << "\n"
+
+      canonical << digest.hexdigest(body.to_s).downcase
+      canonical
+    end
+
+    # List of signed headers.
+    def signed_headers
+      canonical_headers.map{|name,value| name}
+    end
+
+    # Credential scope for task 2.
+    def credential_scope
+      [request_datestamp,
+        region,
+        service,
+        "aws4_request"].join("/")
+    end
+
+    # Canonical query for task 1. Uses the AwsRequest::aws_encode for AWS
+    # encoding rules.
+    def canonical_query
+      query.map{|param,value| [AwsRequest.aws_encode(param), AwsRequest.aws_encode(value)]}.sort
+    end
+
+    # The canonical headers, including the Host.
+    def canonical_headers
+      hash = headers.dup
+      hash["host"] ||= Addressable::URI.parse(url).host
+      hash = hash.map{|name,value| [name.downcase,value]}
+      hash.reject!{|name,value| name == "authorization"}
+      hash.sort
+    end
+
+    def uri
+      Addressable::URI.parse(url)
+    end
+  end
+end

data/lib/bisques/aws_response.rb

@@ -0,0 +1,36 @@
+require 'nokogiri'
+
+module Bisques
+  # Created by an AwsRequest to represent the returned details. The original
+  # request is stored in #request. The raw content is available in #content.
+  # AWS returns XML, and a Nokogiri::XML instance is available in #doc.
+  class AwsResponse
+    # The original AwsRequest that created this response.
+    attr_reader :request
+    # The raw response string from AWS
+    attr_reader :content
+    # The HTTP response. This can be used to get any headers or status codes.
+    attr_reader :http_response
+
+    def initialize(request, http_response) # :nodoc:
+      @request = request
+      @http_response = http_response
+      @content = @http_response.body
+    end
+
+    # A Nokogiri::XML document parsed from the #content.
+    def doc
+      @doc ||= Nokogiri::XML(content).tap{|x|x.remove_namespaces!}
+    end
+
+    # Returns true if the request was successful.
+    def success?
+      @http_response.ok?
+    end
+
+    # The request ID from AWS.
+    def request_id
+      @http_response.header['x-amzn-RequestId']
+    end
+  end
+end

data/lib/bisques/client.rb

@@ -0,0 +1,148 @@
+require 'bisques/aws_connection'
+require 'bisques/aws_credentials'
+require 'bisques/queue'
+require 'bisques/queue_listener'
+require 'digest/md5'
+
+module Bisques
+  # Bisques is a client for Amazon SQS. All of the API calls made to SQS are
+  # called via methods on this class.
+  #
+  # === Example
+  #
+  #   client = Bisques::Client.new('us-east-1', 'my_queues_', AwsCredentials.new(aws_key, aws_secret))
+  #   client.list_queues
+  #
+  class Client
+    # The queue prefix when interacting with SQS. The client will only be able
+    # to see queues whose name has this prefix.
+    attr_accessor :queue_prefix
+
+    include AwsConnection
+
+    # Initialize a client object. The AWS region must be specified. For
+    # example, 'us-east-1'. An optional queue prefix can be provided to
+    # restrict the queues this client can see and interact with. AWS
+    # credentials must be provided, or defaults set in AwsCredentials.
+    def initialize(region, queue_prefix = nil, credentials = AwsCredentials.default)
+      super(region, "sqs", credentials)
+      @queue_prefix = queue_prefix
+    end
+
+    # Returns a Queue object representing an SQS queue, creating it if it does
+    # not already exist.
+    def get_or_create_queue(name)
+      get_queue(name) || create_queue(name, {})
+    end
+
+    # Creates a new SQS queue and returns a Queue object.
+    def create_queue(name, attributes = {})
+      response = action("CreateQueue", {"QueueName" => Queue.sanitize_name("#{queue_prefix}#{name}")}.merge(attributes))
+
+      if response.success?
+        Queue.new(self, response.doc.xpath("//QueueUrl").text)
+      else
+        raise "Could not create queue #{name}"
+      end
+    end
+
+    # Deletes an SQS queue at a given path.
+    def delete_queue(queue_url)
+      response = action("DeleteQueue", queue_url)
+    end
+
+    # Get an SQS queue by name. Returns a Queue object if the queue is found, otherwise nil.
+    def get_queue(name, options = {})
+      response = action("GetQueueUrl", {"QueueName" => Queue.sanitize_name("#{queue_prefix}#{name}")}.merge(options))
+      
+      if response.success?
+        Queue.new(self, response.doc.xpath("//QueueUrl").text)
+      end
+
+    rescue Bisques::AwsActionError => e
+      raise unless e.code == "AWS.SimpleQueueService.NonExistentQueue"
+    end
+
+    # Return an array of Queue objects representing the queues found in SQS. An
+    # optional prefix can be supplied to restrict the queues found. This prefix
+    # is additional to the client prefix.
+    #
+    # Example:
+    #
+    #   # Delete all the queues
+    #   client.list_queues.each do |queue|
+    #     queue.delete
+    #   end
+    #
+    def list_queues(prefix = "")
+      response = action("ListQueues", "QueueNamePrefix" => "#{queue_prefix}#{prefix}")
+      response.doc.xpath("//ListQueuesResult/QueueUrl").map(&:text).map do |url|
+        Queue.new(self, url)
+      end
+    end
+
+    # Get the attributes for a queue. Takes an array of attribute names.
+    # Defaults to ["All"] which returns all the available attributes.
+    #
+    # This returns an AwsResponse object.
+    def get_queue_attributes(queue_url, attributes = ["All"])
+      attributes = attributes.map(&:to_s)
+
+      query = Hash[*attributes.each_with_index.map do |attribute, index|
+        ["AttributeName.#{index+1}", attribute]
+      end.flatten]
+
+      action("GetQueueAttributes", queue_url, query)
+    end
+
+    # Put a message on a queue. Takes the queue url and the message body, which
+    # should be a string. An optional delay seconds argument can be added if
+    # the message should not become visible immediately.
+    #
+    # Example:
+    #
+    #   client.send_message(queue.path, "test message")
+    #
+    def send_message(queue_url, message_body, delay_seconds=nil)
+      options = {"MessageBody" => message_body}
+      options["DelaySeconds"] = delay_seconds if delay_seconds
+
+      tries = 0
+      md5 = Digest::MD5.hexdigest(message_body)
+
+      begin
+        tries += 1
+        response = action("SendMessage", queue_url, options)
+        
+        returned_md5 = response.doc.xpath("//MD5OfMessageBody").text
+        raise MessageHasWrongMd5Error.new(message_body, md5, returned_md5) unless md5 == returned_md5
+      rescue MessageHasWrongMd5Error
+        if tries < 2
+          retry
+        else
+          raise
+        end
+      end
+    end
+
+    # Delete a message from a queue. The message is deleted by the handle given
+    # when the message is retrieved.
+    def delete_message(queue_url, receipt_handle)
+      response = action("DeleteMessage", queue_url, {"ReceiptHandle" => receipt_handle})
+    end
+
+    # Receive a message from a queue. Takes the queue url and an optional hash.
+    def receive_message(queue_url, options = {})
+      # validate_options(options, %w(AttributeName MaxNumberOfMessages VisibilityTimeout WaitTimeSeconds))
+      action("ReceiveMessage", queue_url, options)
+    end
+
+    # Change the visibility of a message on the queue. This is useful if you
+    # have retrieved a message and now want to keep it hidden for longer before
+    # deleting it, or if you have a job and decide you cannot action it and
+    # want to return it to the queue sooner.
+    def change_message_visibility(queue_url, receipt_handle, visibility_timeout)
+      action("ChangeMessageVisibility", queue_url, {"ReceiptHandle" => receipt_handle, "VisibilityTimeout" => visibility_timeout})
+    end
+  end
+end

data/lib/bisques/message.rb

@@ -0,0 +1,47 @@
+require 'json'
+
+module Bisques
+  # A message received from an SQS queue.
+  class Message
+    # The queue this message originated from.
+    attr_reader :queue
+    # The AWS Id of the message.
+    attr_reader :id
+    # A unique handle used to manipulate the message.
+    attr_reader :handle
+    # The raw text body of the message.
+    attr_reader :body
+    # Hash of SQS attributes.
+    attr_reader :attributes
+
+    def initialize(queue, id, handle, body, attributes = {}) #:nodoc:
+      @queue, @id, @handle, @body, @attributes = queue, id, handle, body, attributes
+    end
+
+    # The deserialized object in the message. This method is used to retrieve
+    # the contents that Queue#post_message placed there.
+    #
+    # Example:
+    #
+    #   queue.post_message([1,2,3])
+    #   queue.retrieve.object => [1,2,3]
+    #
+    def object
+      @object ||= JSON.parse(body)
+    end
+
+    # Delete the message from the queue. This should be called after the
+    # message has been received and processed. If not then after a timeout the
+    # message will get added back to the queue.
+    def delete
+      queue.delete_message(handle)
+    end
+
+    # Return the message to the queue immediately. If a client has taken a
+    # message and cannot process it for any reason it can put the message back
+    # faster than the default timeout by calling this method.
+    def return
+      queue.return_message(handle)
+    end
+  end
+end

data/lib/bisques/queue.rb

@@ -0,0 +1,148 @@
+require 'bisques/message'
+
+module Bisques
+  # An SQS queue
+  class Queue
+    class QueueError < Bisques::Error
+      def initialize(queue, message)
+        @queue = queue
+        super("queue: #{queue.name}; #{message}")
+      end
+    end
+    class QueueNotFound < QueueError; end
+
+
+    attr_reader :client # :nodoc:
+
+    def self.sanitize_name(name)
+      name = name.gsub(/[^_\w\d]/, "")
+
+      if name.length > 80
+        short_name = name[0,75]
+        short_name << Digest::MD5.hexdigest(name)
+        short_name = short_name[0,80]
+        name = short_name
+      end
+
+      name
+    end
+
+    # Queues are created by the Client passing the client itself and the url
+    # for the queue.
+    def initialize(client, url)
+      @client, @url = client, url
+    end
+
+    # The name of the queue derived from the URL.
+    def name
+      @url.split("/").last
+    end
+
+    # The path part of the queue URL
+    def path
+      Addressable::URI.parse(@url).path
+    end
+    alias_method :url, :path
+
+    def eql?(queue)
+      hash == queue.hash
+    end
+    def ==(queue)
+      hash == queue.hash
+    end
+    def hash # :nodoc:
+      @url.hash
+    end
+
+    # Return attributes for the queue. Pass in the names of the attributes to
+    # retrieve, or :All for all attributes. The available attributes can be
+    # found at
+    # http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QueryGetQueueAttributes.html
+    #
+    # If 1 attribute is requested then just that attributes value is returned.
+    # If more than one, or all, attributes are requested then a hash of
+    # attribute names and values is returned.
+    #
+    # ==== Example with one attribute:
+    #
+    #   queue.attributes(:ApproximateNumberOfMessages) => 10
+    #
+    # ==== Example with multiple attributes:
+    #
+    #   queue.attributes(:ApproximateNumberOfMessages, :ApproximateNumberOfMessagesDelayed) => {:ApproximateNumberOfMessages => 10, :ApproximateNumberOfMessagesDelayed => 5}
+    #
+    def attributes(*attributes)
+      return nil if attributes.blank?
+
+      values = {}
+      response = client.get_queue_attributes(url, attributes)
+
+      response.doc.xpath("//Attribute").each do |attribute_element|
+        name = attribute_element.xpath("Name").text
+        value = attribute_element.xpath("Value").text
+        value = value.to_i if value =~ /\A\d+\z/
+        values[name] = value
+      end
+
+      if values.size == 1 && attributes.size == 1
+        values.values.first
+      else
+        values
+      end
+    end
+
+    # Delete the queue
+    def delete
+      client.delete_queue(url)
+    end
+
+    # Post a message to the queue. The message must be serializable (i.e.
+    # strings, numbers, arrays, hashes).
+    def post_message(object)
+      client.send_message(url, JSON.dump(object))
+    end
+
+    # Retrieve a message from the queue. Returns nil if no message is waiting
+    # in the given poll time. Otherwise it returns a Message.
+    def retrieve(poll_time = 1)
+      response = client.receive_message(url, {"WaitTimeSeconds" => poll_time, "MaxNumberOfMessages" => 1})
+      raise QueueNotFound.new(self, "not found at #{url}") if response.http_response.status == 404
+
+      response.doc.xpath("//Message").map do |element|
+        attributes = Hash[*element.xpath("Attribute").map do |attr_element|
+          [attr_element.xpath("Name").text, attr_element.xpath("Value").text]
+        end.flatten]
+
+        Message.new(self, element.xpath("MessageId").text,
+                    element.xpath("ReceiptHandle").text,
+                    element.xpath("Body").text,
+                    attributes
+                   )
+      end.first
+    end
+
+    # Retrieve a single message from the queue. This will block until a message
+    # arrives. The message will be of the class Message.
+    def retrieve_one(poll_time = 5)
+      object = nil
+      while object.nil?
+        object = retrieve(poll_time)
+      end
+      object
+    end
+
+    # Delete a message from the queue. This should be called to confirm that
+    # the message has been processed. If it is not called then the message will
+    # get put back on the queue after a timeout.
+    def delete_message(handle)
+      response = client.delete_message(url, handle)
+      response.success?
+    end
+
+    # Return a message to the queue after receiving it. This would typically
+    # happen if the receiver decided it couldn't process.
+    def return_message(handle)
+      client.change_message_visibility(url, handle, 0)
+    end
+  end
+end

data/lib/bisques/queue_listener.rb

@@ -0,0 +1,89 @@
+require 'bisques/queue'
+require 'thread'
+
+module Bisques
+  # Listen for messages on a queue and execute a block when they arrive.
+  class QueueListener
+    def initialize(queue, poll_time = 5)
+      @queue, @poll_time = queue, poll_time
+    end
+
+    def listening?
+      @listening
+    end
+
+    # Listen for messages. This is asynchronous and returns immediately.
+    #
+    # Ex:
+    #
+    #   queue = bisques.find_or_create_queue("my queue")
+    #   listener = QueuedListener.new(queue)
+    #   listener.listen do |message|
+    #     puts "Received #{message.object}"
+    #     message.delete
+    #   end
+    #
+    #   while true; sleep 1; end # Process messages forever
+    #
+    # Note that the block you give to this method is executed in a new thread.
+    #
+    def listen(&block)
+      return if @listening
+      @listening = true
+
+      @thread = Thread.new do
+        while @listening
+          message = @queue.retrieve(@poll_time)
+          block.call(message) if message.present?
+        end
+      end
+    end
+
+    # Stop listening for messages
+    def stop
+      @listening = false
+      @thread.join if @thread
+    end
+  end
+
+  # Listen for messages on several queues at the same time. The interface for
+  # objects of this class is identical to that of QueueListener.
+  #
+  # Ex:
+  #
+  #   queue_1 = bisques.find_or_create_queue("queue one")
+  #   queue_2 = bisques.find_or_create_queue("queue two")
+  #   listener = MultiQueueListener.new(queue_1, queue_2)
+  #   listener.listen do |message|
+  #     puts "Queue #{message.queue.name}, message #{message.object}"
+  #     message.delete
+  #   end
+  #   while true; sleep 1; end # Process messages forever
+  #
+  class MultiQueueListener
+    def initialize(*queues)
+      @queues = queues
+      @listeners = []
+    end
+
+    def listening?
+      @listeners.any?
+    end
+
+    def listen(&block)
+      return if @listeners.any?
+      @listeners = @queues.map do |queue|
+        QueueListener.new(queue)
+      end
+
+      @listeners.each do |listener|
+        listener.listen(&block)
+      end
+    end
+
+    def stop
+      @listeners.each(&:stop)
+      @listeners = []
+    end
+  end
+end

data/lib/bisques.rb

@@ -0,0 +1,14 @@
+# See README.rdoc
+module Bisques
+  class Error < StandardError; end
+  class MessageHasWrongMd5Error < Error
+    attr_reader :msg, :expected, :got
+
+    def initialize(msg, expected, got)
+      @msg, @expected, @got = msg, expected, got
+      super(msg)
+    end
+  end
+end
+
+require 'bisques/client'

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: bisques
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeremy Wells
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httpclient
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: addressable
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: json
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+- !ruby/object:Gem::Dependency
+  name: rspec
+  prerelease: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+description: AWS SQS client
+email: jemmyw@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- README.rdoc
+- Rakefile
+- lib/bisques/aws_connection.rb
+- lib/bisques/aws_credentials.rb
+- lib/bisques/aws_request.rb
+- lib/bisques/aws_request_authorization.rb
+- lib/bisques/aws_response.rb
+- lib/bisques/client.rb
+- lib/bisques/message.rb
+- lib/bisques/queue.rb
+- lib/bisques/queue_listener.rb
+- lib/bisques.rb
+homepage: https://github.com/bigears/bisques
+licenses: []
+post_install_message: 
+rdoc_options:
+- --line-numbers
+- --inline-source
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: AWS SQS client
+test_files: []