SQS 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Zachary Holt
+
+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/README

@@ -0,0 +1,3 @@
+Please see the MIT-LICENSE file for copyright and distribution information.
+
+SQS is a Ruby interface to Amazon's Simple Queue Service.

data/lib/sqs.rb

@@ -0,0 +1,294 @@
+#!/usr/local/bin/ruby
+
+dir = File::dirname( __FILE__ )
+
+#require "#{dir}/aws"
+require 'base64'
+require 'erb'
+require 'net/http'
+require 'openssl'
+require 'rexml/document'
+#include Digest
+include ERB::Util
+include OpenSSL
+include REXML
+
+
+class SQS
+
+  dir = File.dirname( __FILE__ )
+  require "#{dir}/sqs/queue"
+  require "#{dir}/sqs/message"
+  require "#{dir}/sqs/grant"
+  
+  
+  def self.new
+    # rather than a singleton class, never allow instantiation
+    return SQS
+  end
+  
+  def self.prepare_parameters_for_signing( hsh={} )
+    # Param-name1Param-value1Param-name2Param-value2...Param-nameNParam-valueN
+    # see http://docs.amazonwebservices.com/AWSSimpleQueueService/2006-04-01/Query/QueryAuth.html
+    hsh.keys.sort{ |a,b| a.to_s.casecmp( b.to_s ) }.map{ |a| "#{a.to_s}#{hsh[a].to_s}"}.join( '' )
+  end
+
+  def self.prepare_parameters_for_query( hsh={} )
+    # Param-name1Param-value1Param-name2Param-value2...Param-nameNParam-valueN
+    # see http://docs.amazonwebservices.com/AWSSimpleQueueService/2006-04-01/Query/QueryAuth.html
+    hsh.keys.map{ |a| "#{url_encode( a.to_s )}=#{url_encode( hsh[a].to_s )}"}.join( '&' )
+  end
+
+  def self.access_key_id=( i )
+    @@access_key_id = i
+  end
+  def self.access_key_id
+    @@access_key_id
+  end
+  def self.secret_access_key=( k )
+    @@secret_access_key = k
+  end
+  def self.secret_access_key
+    @@secret_access_key
+  end
+  def self.url_for_auery=( u )
+    @@url_for_query = u
+  end
+  def self.url_for_query
+    @@url_for_query
+  end
+
+  def self.create_signature( params )
+    prepared_parameters = self.prepare_parameters_for_signing( params )
+    digest = OpenSSL::HMAC::digest( OpenSSL::Digest::Digest.new("SHA1"), self.secret_access_key, prepared_parameters )
+    b64_hmac = Base64.encode64( digest ).strip
+    b64_hmac
+  end
+
+  def self.permissions( perm=nil )
+    perms = { :full => 'FULLCONTROL', :send => 'SENDMESSAGE', :receive => 'RECEIVEMESSAGE' }
+    if perm.nil?
+      perms
+    else
+      perms.has_value?( perm.to_s.upcase ) ? perm.to_s.upcase : perms[perm.to_sym]
+    end
+  end
+
+  def self.create_queue( params={} )
+    params = params.is_a?( Hash ) ? params : { :name => params }
+    params[:Action] = 'CreateQueue'
+    return false if params[:name].to_s.empty?
+    params[:QueueName] = params[:name]
+    params.delete( :name )
+
+    doc = self.call_web_service( params )
+    queue_url = doc.queue_url
+    SQS::Queue.new( :url => queue_url )
+
+  rescue Exception => e
+    raise e
+  end
+
+
+
+  def self.get_queue( params={} )
+    params = params.is_a?( Hash ) ? params : { :name => params }
+    self.list_queues( :prefix => params[:name] ).each do |queue|
+      return queue if queue.name == params[:name]
+    end
+
+    raise "Could not find the queue named '#{params[:name]}'"
+  rescue Exception => e
+    raise e
+  end
+
+
+  def self.list_queues( params={} )
+    # use :prefix => 'Boo' to get queues whose names begin with 'Boo'
+    params = params.is_a?( Hash ) ? params : { }
+    params[:Action] = 'ListQueues'
+    if ( params.has_key?( :prefix ) )
+      params[:QueueNamePrefix] = params[:prefix]
+      params.delete( :prefix )
+    end
+
+    doc = self.call_web_service( params )
+    queues = Array.new()
+
+    begin
+      XPath.each( doc, '/ListQueuesResponse/QueueUrl' ) do |element|
+        queues << SQS::Queue.new( :url => element.text )
+      end
+    rescue RuntimeError => e
+      queues = Array.new()
+    end
+    queues
+  rescue Exception => e
+    raise e
+  end
+
+  def self.each_queue( params={}, &block )
+    self.list_queues( params ).each do |q|
+      block.call( q )
+    end
+  rescue Exception => e
+    raise e
+  end
+
+
+
+  def self.api_version
+    '2006-04-01'
+  end
+
+  def self.signature_version
+    1
+  end
+
+  def self.request_ttl
+    30
+  end
+
+  def self.retry_attempts
+    10
+  end
+
+  def self.params_for_query( t=nil )
+    expires = t.is_a?( Time ) ? t : Time.now.request_expires
+    
+    {
+      :DefaultVisibilityTimeout => SQS::Queue.default_visibility_timeout,
+      :Version => self.api_version,
+      :AWSAccessKeyId => self.access_key_id,
+      :SignatureVersion => self.signature_version,
+      :Expires => expires.to_iso8601
+    }
+  end
+  
+  def self.counter
+    @@counter
+  end
+  def self.reset_counter
+    @@counter = 0
+  end
+  def self.increment_counter
+    @@counter += 1
+  end
+  protected
+  @@counter = 0;
+  @@secret_access_key = 'Replace this with your secret access key'
+  @@access_key_id = 'Replace this with your access key id'
+  @@url_for_query = 'http://queue.amazonaws.com/'
+  
+
+  def self.reasons_not_to_retry
+    [ 'Success', 'InvalidParameterValue' ]
+  end
+
+  def self.call_web_service( params )
+    params = self.params_for_query.merge( params )
+
+    begin
+      retries = params[:retries] + 0
+      params.delete( :retries )
+      retries = 1 if retries < 1
+    rescue
+      retries = self.retry_attempts
+    end
+
+    if !params[:queue].nil? && params[:queue].respond_to?( :url )
+      url = params[:queue].url
+      params.delete( :queue )
+    else
+      url = "#{self.url_for_query}"
+    end
+    url += "?#{self.prepare_parameters_for_query( params )}&Signature="
+
+    url_encoded_signature = url_encode( self.create_signature( params ) )
+    response = Net::HTTP.get( URI.parse( url + url_encoded_signature ) )
+    self.increment_counter
+    doc = Document.new( response )
+    status = doc.status
+
+    unless status == 'Success'
+      error_code = doc.error_code
+      error_message = doc.error_message
+      case error_code
+      when 'AuthFailure', 'InvalidParameterValue', 'AWS.SimpleQueueService.NonEmptyQueue'
+        raise( "#{error_code}: #{error_message} (#{url}#{url_encoded_signature})" )
+      else
+        raise( "Unknown Error: #{doc} (#{url}#{url_encoded_signature})" )
+      end
+    end
+
+    doc
+  rescue Exception => e
+    raise e.is_a?( SocketError ) ? "Do you have internet access? (#{e.message})" : e
+  end
+end
+
+class Time
+  def to_iso8601
+    self.utc.strftime( "%Y-%m-%dT%H:%M:%SZ" ) 
+  end
+
+  def request_expires
+    self + SQS.request_ttl
+  end
+end
+
+module REXML
+  class Document
+  
+    def error_code ; self.node_text( '/Response/Errors/Error/Code' ) ; end
+    def error_message ; self.node_text( '/Response/Errors/Error/Message' ) ; end
+    def request_id ; self.node_text( '*/ResponseStatus/RequestId' ) ; end
+
+    def queue_url ; self.node_text( '/CreateQueueResponse/QueueUrl' ) ; end
+    def status ; self.node_text( '*/ResponseStatus/StatusCode' ) ; end
+
+    def message_id( type=:send ) ; self.node_text( "/#{type.to_s.capitalize}MessageResponse/#{ type == :send ? '' : 'Message/'}MessageId" ) ; end
+    def message_body( type=:peek ) ; self.node_text( "/#{type.to_s.capitalize}MessageResponse/Message/MessageBody" ) ; end
+
+    def messages( type=:receive ) ; self.nodes( "/#{type.to_s.capitalize}MessageResponse#{ type == :send ? '' : '/Message'}" ) ; end
+
+    def visibility_timeout( type=:get ) ; self.node_text( "/#{type.to_s.capitalize}VisibilityTimeoutResponse/VisibilityTimeout" ).to_i ; end
+
+    def grant_lists( type=:list ) ; self.nodes("/#{type.to_s.capitalize}GrantsResponse#{ type == :send ? '' : '/GrantList'}" ) ; end
+
+    protected
+    def node_text( xpath )
+      code = XPath.first( self, xpath )
+      code.to_s.empty? ? '' : code.text
+    end
+    
+    def nodes( xpath )
+      XPath.match( self, xpath )
+    end
+  end
+
+
+  class Element
+    def message_id ; self.node_text( "MessageId" ) ; end
+    def message_body ; self.node_text( "MessageBody" ) ; end
+
+    def id( type=:message ) ; self.node_text( type == :grantee ? "ID" : "Id" ) ; end
+    def display_name ; self.node_text( "DisplayName" ) ; end
+    def permission ; self.node_text( "Permission" ) ; end
+
+    def grantees( type=:list ) ; self.nodes("Grantee" ) ; end
+
+    protected
+    def node_text( xpath )
+      code = XPath.first( self, xpath )
+      code.to_s.empty? ? '' : code.text
+    end
+    
+    def nodes( xpath )
+      XPath.match( self, xpath )
+    end
+  end
+  
+end
+
+Dir[File.join( File.join( File.dirname( __FILE__ ), 'sqs' ), "*.rb" )].each { |f| require f }

data/lib/sqs/grant.rb

@@ -0,0 +1,34 @@
+
+class SQS::Grant
+  def self.atts
+    [:email, :display_name, :id, :_permission]
+  end
+
+  self.atts.each do |att|
+    attr_accessor att
+  end
+  
+  def initialize( options={} )
+    if options.is_a?( Hash )
+      SQS::Grant.atts.each do |thing|
+        self.send "#{thing}=", options[thing.to_s =~ /^_(.*)$/ ? $1.to_sym : thing]
+      end
+    else
+      self.email = options
+    end
+  end
+
+  def permission
+    self._permission
+  end
+
+  def permission=( p )
+    if SQS.permissions.has_key?( p.to_s.to_sym )
+      self._permission = SQS.permissions[p.to_s.to_sym]
+    else
+      self._permission = p.to_s.upcase
+    end
+  end
+end
+
+

data/lib/sqs/message.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/local/ruby
+
+class SQS::Message
+  attr_accessor :queue, :_body, :id
+
+  def initialize( options={} )
+    self.body = options.is_a?( Hash ) ? options[:body] : nil
+    self.queue = options.is_a?( Hash ) ? options[:queue] : nil
+    self.id = options.is_a?( Hash ) ? options[:id] : options.to_s
+  end
+
+
+  def delete
+    raise "This #{self.class.to_s} cannot be deleted, because there is no associated SQS::Queue" unless self.queue.is_a?( SQS::Queue )
+    raise "Cannot delete a message with no id." if self.id.to_s.empty?
+
+    doc = SQS.call_web_service( :Action => 'DeleteMessage', :queue => self.queue, :MessageId => self.id )
+    true
+  rescue Exception => e
+    raise e
+  end
+
+
+  def peek
+    raise "This #{self.class.to_s} cannot be peeked, because there is no associated SQS::Queue" unless self.queue.is_a?( SQS::Queue )
+    raise "Cannot peek a message with no id." if self.id.to_s.empty?
+
+    doc = SQS.call_web_service( :Action => 'PeekMessage', :queue => self.queue, :MessageId => self.id )
+    self.body = doc.message_body
+    true
+  rescue Exception => e
+    raise e
+  end
+
+  def body 
+    self.peek if self._body.to_s.empty?
+    self._body
+  end
+  def body=( b )
+    self._body = b
+  end
+
+end

data/lib/sqs/queue.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/local/ruby
+
+require 'uri'
+require 'rexml/document'
+include REXML
+
+class SQS::Queue
+  private
+  @attributes = {}
+  @@acceptable_schemes = ['https', 'http']
+
+  public
+  attr_accessor :url
+  def initialize( options={} )
+    self.url = options.is_a?( Hash ) ? options[:url] : options
+    bad_url = false
+
+    begin
+      u = URI.parse( self.url )
+      bad_url = !@@acceptable_schemes.include?( u.scheme ) || u.host.to_s.empty? || u.path.to_s.empty?
+    rescue URI::InvalidURIError, NoMethodError
+      bad_url = true
+    end
+    raise "'#{self.url}' does not seem to be a parseable URL. (Please provide all parts of the URL.)" if bad_url
+  end
+
+  def ==( other_queue )
+    self.url == other_queue.url
+  rescue
+    false
+  end
+  
+  def to_s
+    "#{self.class.to_s} '#{self.name}' (#{self.url})"
+  end
+
+  def delete
+    doc = SQS.call_web_service( :Action => 'DeleteQueue', :queue => self )
+    true
+  rescue Exception => e
+    raise e
+  end
+
+  def force_delete
+    begin
+      self.delete
+    rescue
+      while m = self.receive_message
+        m.delete if m.respond_to?( :delete )
+      end
+      populated = 2
+      while populated > 0
+        begin
+          self.delete
+          populated = 0
+        rescue
+          populated -= 1
+        end
+      end
+    end
+    true
+  rescue Exception => e
+    raise e
+  end
+
+
+  def send_message( m )
+    doc = SQS.call_web_service( :Action => 'SendMessage', :queue => self, :MessageBody => m.to_s )
+    m = SQS::Message.new( :id => doc.message_id, :queue => self )
+  rescue Exception => e
+    raise e
+  end
+
+  def receive_message
+    # returns the first element of what receive_messages returns
+    m = self.receive_messages( :count => 1 ).first
+    yield( m ) if block_given?
+    m
+  end
+  def receive_messages( options={} )
+    # returns an array of SQS::Message instances (could be empty)
+    count = options.has_key?( :count ) ? options[:count].to_i : 1
+    params = { :Action => 'ReceiveMessage', :queue => self, :NumberOfMessages => count }
+    params[:VisibilityTimeout] = options[:message_ttl] if options.has_key?( :message_ttl )
+    doc = SQS.call_web_service( params )
+
+    messages = Array.new
+    doc.messages.each do |m|
+      messages << SQS::Message.new( :id => m.message_id, :queue => self, :body => m.message_body)
+    end
+    messages
+  rescue Exception => e
+    raise e
+  end
+
+  def visibility_timeout=( timeout )
+    doc = SQS.call_web_service( :Action => 'SetVisibilityTimeout', :queue => self, :VisibilityTimeout => timeout.to_i )
+    true
+  rescue Exception => e
+    raise e
+  end
+  def visibility_timeout
+    doc = SQS.call_web_service( :Action => 'GetVisibilityTimeout', :queue => self )
+    doc.visibility_timeout.to_i
+  rescue Exception => e
+    raise e
+  end
+
+
+
+  def add_grant( options={} )
+    doc = SQS.call_web_service(
+      :Action => 'AddGrant',
+      :queue => self,
+      :Permission => SQS.permissions[options[:permission]],
+      'Grantee.EmailAddress'.to_sym => options[:email].respond_to?( :email ) ? options[:email].email : options[:email]
+    )
+    true
+  rescue Exception => e
+    raise e
+  end
+
+  def remove_grant( options={} )
+    params = {
+      :Action => 'RemoveGrant',
+      :queue => self,
+      :Permission => SQS.permissions( options[:permission] ),
+    }
+
+    if !options[:id].nil?
+      params['Grantee.ID'.to_sym] = options[:id].respond_to?( :id ) && !options[:id].is_a?( String ) ? options[:id].id : options[:id]
+    elsif !options[:email].nil?
+      params['Grantee.EmailAddress'.to_sym] = options[:email].respond_to?( :email ) ? options[:email].email : options[:email]
+    else
+      raise "You must specify either a grant id (:id) or a grantee email address (:email) when calling remove_grant."
+    end
+
+    doc = SQS.call_web_service( params )
+    true
+  rescue Exception => e
+    raise e
+  end
+
+  def list_grants
+    doc = SQS.call_web_service( :Action => 'ListGrants', :queue => self )
+    grants = Array.new
+    doc.grant_lists.each do |list|
+      list.grantees.each do |g|
+        grants << SQS::Grant.new( :id => g.id( :grantee ), :display_name => g.display_name, :permission => list.permission )
+      end
+    end
+    grants
+  rescue Exception => e
+    raise e
+  end
+
+  def each_grant( &block )
+    self.list_grants.each do |g|
+      block.call( g )
+    end
+  end
+
+  def name
+    # return everything after the last slash
+    self.url =~ /([^\/]*)$/ ? $1 : ''
+  end
+
+  def self.default_visibility_timeout
+    30
+  end
+
+  def exist?
+    SQS.get_queue( self.name )
+    true
+  rescue
+    false
+  end
+  alias_method :exists?, :exist?
+end